refactor: make cli-auth part of the providers class

- previously the nproject name to the backend was passed like 'C--USERS-...' and it used the legacy project-config.json file in .claude to get the original workspace paths,
However, now we are directly passing the workspace and no parsing is necessary for the routes.
So I modified the extractProjectDirectory to just return the project name.

.github/workflows/cross-platform-server.yml

@@ -0,0 +1,47 @@
+name: Cross Platform Server Verification
+
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+
+jobs:
+  verify:
+    name: Verify on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+        node:
+          - 22
+
+    steps:
+      # This step checks out the repository so the matrix job can build and test it.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # This step installs the Node.js version the README already declares as the project baseline.
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      # This step installs dependencies exactly as locked so native and shell behavior stays reproducible.
+      - name: Install dependencies
+        run: npm ci
+
+      # This step verifies the TypeScript server code before runtime checks.
+      - name: Typecheck server
+        run: npm run typecheck:server
+
+      # This step runs the built-in Node tests that exercise the OS adapter layer directly.
+      - name: Test server adapters
+        run: npm run test:server
+
+      # This step ensures the in-progress TypeScript backend still compiles in each OS environment.
+      - name: Build server
+        run: npm run server:build

.gitignore

@@ -8,6 +8,7 @@ lerna-debug.log*
 
 # Build outputs
 dist/
+server/dist/
 dist-ssr/
 build/
 out/
@@ -138,4 +139,4 @@ tasks/
 !src/i18n/locales/de/tasks.json
 
 # Git worktrees
-.worktrees/
+.worktrees/

docs/backend/endpoint-inventory.csv

@@ -0,0 +1,144 @@
+transport,method,path,tag,authMode,sourceFile,sourceLine,purpose,consumerFiles,pathParams,queryParams,bodyHints,successShape,errorShape,sideEffects,priority
+"http","GET","/health","System","public","server/index.js","345","Expose server health, timestamp, and install mode for diagnostics.","src/hooks/useVersionCheck.ts","","","","Structured JSON object response.","Handler-specific error behavior.","Read-only backend query.","low"
+"http","POST","/api/system/update","System","bearer_token","server/index.js","425","Run the application update workflow on the host machine.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.","low"
+"http","GET","/api/projects","Projects","bearer_token","server/index.js","491","List detected projects and workspaces.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON payload returned directly from service logic.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","GET","/api/projects/:projectName/sessions","Sessions","bearer_token","server/index.js","500","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","offset; try {
+        const { limit","","JSON payload returned directly from service logic.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","GET","/api/projects/:projectName/sessions/:sessionId/messages","Sessions","bearer_token","server/index.js","512","Return paginated messages for a stored session.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; sessionId","limit; offset","","Structured JSON object response.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","PUT","/api/projects/:projectName/rename","Projects","bearer_token","server/index.js","537","PUT /api/projects/:projectName/rename for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","try {
+        const { displayName","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","DELETE","/api/projects/:projectName/sessions/:sessionId","Sessions","bearer_token","server/index.js","548","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; sessionId","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","PUT","/api/sessions/:sessionId/rename","Sessions","bearer_token","server/index.js","563","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","","provider; summary","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.","low"
+"http","DELETE","/api/projects/:projectName","Projects","bearer_token","server/index.js","589","DELETE /api/projects/:projectName for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","force","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","POST","/api/projects/create","Projects","bearer_token","server/index.js","601","Manually add a project path to the workspace list.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","try {
+        const { path","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"sse","GET","/api/search/conversations","Sessions","bearer_token","server/index.js","618","Search conversation history across stored projects and stream results.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","limit; q","","Server-sent events stream with progress/result/error events.","Streamed error event or JSON error fallback.","Read-only backend query.","high"
+"http","GET","/api/browse-filesystem","Realtime","bearer_token","server/index.js","674","Browse local directories so the UI can suggest workspace locations.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","try {
+        const { path","","Structured JSON object response.","JSON object with error message and optional details.","Read-only backend query.","low"
+"http","POST","/api/create-folder","Projects","bearer_token","server/index.js","754","Create a new directory on the local filesystem.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","try {
+        const { path","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.","low"
+"http","GET","/api/projects/:projectName/file","Files","bearer_token","server/index.js","795","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","filePath","","Structured JSON object response.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","GET","/api/projects/:projectName/files/content","Files","bearer_token","server/index.js","835","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","path","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","PUT","/api/projects/:projectName/file","Files","bearer_token","server/index.js","888","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","content; filePath","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","GET","/api/projects/:projectName/files","Files","bearer_token","server/index.js","937","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","JSON payload returned directly from service logic.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","POST","/api/projects/:projectName/files/create","Files","bearer_token","server/index.js","1016","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","name; path; type","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","PUT","/api/projects/:projectName/files/rename","Files","bearer_token","server/index.js","1093","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","newName; oldPath","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","DELETE","/api/projects/:projectName/files","Files","bearer_token","server/index.js","1170","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","path; relativePaths; targetPath; type","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","POST","/api/projects/:projectName/files/upload","Files","bearer_token","server/index.js","1396","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Mixed response shape; inspect handler during refactor.","Handler-specific error behavior.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","POST","/api/transcribe","Realtime","bearer_token","server/index.js","1964","Transcribe uploaded audio and optionally enhance the result for prompts or tasks.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","mode","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Processes uploaded files and external model responses.","low"
+"http","POST","/api/projects/:projectName/upload-images","Files","bearer_token","server/index.js","2113","Upload images for chat use and return browser-safe data URLs.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"http","GET","/api/projects/:projectName/sessions/:sessionId/token-usage","Sessions","bearer_token","server/index.js","2198","Report token usage for a stored provider session.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; sessionId","provider","","Structured JSON object response.","JSON object with error message and optional details.","Touches local workspace files or directories.","high"
+"http","GET","*","System","public","server/index.js","2386","Serve the React application fallback for non-API routes.","","","","","Static file or HTML response.","JSON error response with HTTP status code.","Read-only backend query.","low"
+"http","GET","/api/auth/status","Auth","public","server/routes/auth.js","9","Report whether authentication is configured.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/auth/register","Auth","public","server/routes/auth.js","23","Create the first local user account.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","password; try {
+    const { username","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/auth/login","Auth","public","server/routes/auth.js","82","Authenticate a local user and issue a token.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","password; try {
+    const { username","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","GET","/api/auth/user","Auth","bearer_token","server/routes/auth.js","122","Return the currently authenticated user.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","Handler-specific error behavior.","Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/auth/logout","Auth","bearer_token","server/routes/auth.js","129","Invalidate the current authenticated session.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON object with an explicit success flag and payload.","Handler-specific error behavior.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/projects/create-workspace","Projects","bearer_token","server/routes/projects.js","175","Create or register a workspace and optionally clone a GitHub repository into it.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","githubTokenId; githubUrl; newGithubToken; path; try {
+    const { workspaceType","Structured JSON object response.","JSON validation error response.","Mutates backend or external state.; Touches local workspace files or directories.","high"
+"sse","GET","/api/projects/clone-progress","Projects","bearer_token","server/routes/projects.js","335","Stream workspace cloning progress events to the frontend.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { path; githubTokenId; githubUrl; newGithubToken","","Server-sent events stream with progress/result/error events.","Streamed error event or JSON error fallback.","Touches local workspace files or directories.","high"
+"http","GET","/api/git/status","Git","bearer_token","server/routes/git.js","291","Read git status information for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","GET","/api/git/diff","Git","bearer_token","server/routes/git.js","354","Return git diff output for a project or file.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project; file","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","GET","/api/git/file-with-diff","Git","bearer_token","server/routes/git.js","437","Read, write, create, rename, delete, or upload project files.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project; file","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.; Touches local workspace files or directories.","high"
+"http","POST","/api/git/initial-commit","Git","bearer_token","server/routes/git.js","517","POST /api/git/initial-commit for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/commit","Git","bearer_token","server/routes/git.js","561","POST /api/git/commit for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project; files; message","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/revert-local-commit","Git","bearer_token","server/routes/git.js","592","POST /api/git/revert-local-commit for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","GET","/api/git/branches","Git","bearer_token","server/routes/git.js","639","List git branches for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","POST","/api/git/checkout","Git","bearer_token","server/routes/git.js","681","POST /api/git/checkout for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","branch; const { project","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/create-branch","Git","bearer_token","server/routes/git.js","703","POST /api/git/create-branch for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","branch; const { project","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","GET","/api/git/commits","Git","bearer_token","server/routes/git.js","725","List recent commits for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project; limit","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","GET","/api/git/commit-diff","Git","bearer_token","server/routes/git.js","782","Return diff details for a specific commit.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","commit; const { project","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","POST","/api/git/generate-commit-message","Git","bearer_token","server/routes/git.js","814","Generate an AI-assisted commit message from the current diff.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project; files; provider","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","GET","/api/git/remote-status","Git","bearer_token","server/routes/git.js","1019","Report remote sync status for a project repository.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","const { project","","Structured JSON object response.","JSON validation error response.","Touches git repositories or local git config.","high"
+"http","POST","/api/git/fetch","Git","bearer_token","server/routes/git.js","1097","POST /api/git/fetch for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project","JSON object with an explicit success flag and payload.","JSON validation error response.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/pull","Git","bearer_token","server/routes/git.js","1138","POST /api/git/pull for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project","Structured JSON object response.","JSON validation error response.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/push","Git","bearer_token","server/routes/git.js","1206","POST /api/git/push for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project","Structured JSON object response.","JSON validation error response.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/publish","Git","bearer_token","server/routes/git.js","1277","POST /api/git/publish for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","branch; const { project","Structured JSON object response.","JSON validation error response.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/discard","Git","bearer_token","server/routes/git.js","1356","POST /api/git/discard for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project; file","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","POST","/api/git/delete-untracked","Git","bearer_token","server/routes/git.js","1410","POST /api/git/delete-untracked for backend runtime support.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","const { project; file","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","high"
+"http","GET","/api/mcp/cli/list","MCP","bearer_token","server/routes/mcp.js","16","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/mcp/cli/add","MCP","bearer_token","server/routes/mcp.js","59","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/mcp/cli/add-json","MCP","bearer_token","server/routes/mcp.js","142","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","jsonConfig; projectPath; scope; try {
+    const { name","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","DELETE","/api/mcp/cli/remove/:name","MCP","bearer_token","server/routes/mcp.js","235","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","scope","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/mcp/cli/get/:name","MCP","bearer_token","server/routes/mcp.js","305","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/mcp/config/read","MCP","bearer_token","server/routes/mcp.js","348","Manage Claude MCP CLI and configuration state.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/cursor/config","Providers","bearer_token","server/routes/cursor.js","15","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","POST","/api/cursor/config","Providers","bearer_token","server/routes/cursor.js","59","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","model; try {
+    const { permissions","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","GET","/api/cursor/mcp","Providers","bearer_token","server/routes/cursor.js","122","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/cursor/mcp/add","Providers","bearer_token","server/routes/cursor.js","183","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","DELETE","/api/cursor/mcp/:name","Providers","bearer_token","server/routes/cursor.js","245","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/cursor/mcp/add-json","Providers","bearer_token","server/routes/cursor.js","292","Manage Cursor configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","jsonConfig; try {
+    const { name","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/cursor/sessions","Providers","bearer_token","server/routes/cursor.js","348","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","try {
+    const { projectPath","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","GET","/api/cursor/sessions/:sessionId","Providers","bearer_token","server/routes/cursor.js","583","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","projectPath","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","GET","/api/taskmaster/installation-status","TaskMaster","bearer_token","server/routes/taskmaster.js","243","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/detect/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","278","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","JSON payload returned directly from service logic.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/detect-all","TaskMaster","bearer_token","server/routes/taskmaster.js","350","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/initialize/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","434","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","rules","Mixed response shape; inspect handler during refactor.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/next/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","460","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/tasks/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","570","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/prd/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","685","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/prd/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","761","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","content; fileName","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/prd/:projectName/:fileName","TaskMaster","bearer_token","server/routes/taskmaster.js","846","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; fileName","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","DELETE","/api/taskmaster/prd/:projectName/:fileName","TaskMaster","bearer_token","server/routes/taskmaster.js","911","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; fileName","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/init/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","971","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/add-task/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","1060","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","dependencies; description; priority; prompt; title","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","PUT","/api/taskmaster/update-task/:projectName/:taskId","TaskMaster","bearer_token","server/routes/taskmaster.js","1164","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName; taskId","","description; details; priority; status; title","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/parse-prd/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","1291","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","append; fileName; numTasks","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/taskmaster/prd-templates","TaskMaster","bearer_token","server/routes/taskmaster.js","1392","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.","high"
+"http","POST","/api/taskmaster/apply-template/:projectName","TaskMaster","bearer_token","server/routes/taskmaster.js","1838","Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","projectName","","","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.; Reads or writes TaskMaster project assets.","high"
+"http","GET","/api/mcp-utils/taskmaster-server","MCP","bearer_token","server/routes/mcp-utils.js","18","Return MCP helper information used by setup flows.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON payload returned directly from service logic.","JSON error response with HTTP status code.","Reads or writes TaskMaster project assets.; Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/mcp-utils/all-servers","MCP","bearer_token","server/routes/mcp-utils.js","35","Return MCP helper information used by setup flows.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON payload returned directly from service logic.","JSON error response with HTTP status code.","Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/commands/list","Commands","bearer_token","server/routes/commands.js","406","List, load, or execute slash commands available to the chat experience.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","try {
+    const { projectPath","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","POST","/api/commands/load","Commands","bearer_token","server/routes/commands.js","456","List, load, or execute slash commands available to the chat experience.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","commandPath; try {
+    const { commandPath","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","POST","/api/commands/execute","Commands","bearer_token","server/routes/commands.js","507","List, load, or execute slash commands available to the chat experience.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","commandPath","Structured JSON object response.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","GET","/api/settings/api-keys","Settings","bearer_token","server/routes/settings.js","11","Manage local API keys used to access the backend.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/settings/api-keys","Settings","bearer_token","server/routes/settings.js","27","Manage local API keys used to access the backend.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","try {
+    const { keyName","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","DELETE","/api/settings/api-keys/:keyId","Settings","bearer_token","server/routes/settings.js","47","Manage local API keys used to access the backend.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","keyId","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","PATCH","/api/settings/api-keys/:keyId/toggle","Settings","bearer_token","server/routes/settings.js","64","Manage local API keys used to access the backend.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","keyId","","isActive","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","GET","/api/settings/credentials","Settings","bearer_token","server/routes/settings.js","91","Manage stored provider and GitHub credentials.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","try {
+    const { type","","Structured JSON object response.","JSON object with error message and optional details.","Reads or writes local authentication or credential state.","medium"
+"http","POST","/api/settings/credentials","Settings","bearer_token","server/routes/settings.js","104","Manage stored provider and GitHub credentials.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","credentialType; credentialValue; description; try {
+    const { credentialName","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","DELETE","/api/settings/credentials/:credentialId","Settings","bearer_token","server/routes/settings.js","139","Manage stored provider and GitHub credentials.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","credentialId","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","PATCH","/api/settings/credentials/:credentialId/toggle","Settings","bearer_token","server/routes/settings.js","156","Manage stored provider and GitHub credentials.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","credentialId","","isActive","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes local authentication or credential state.","medium"
+"http","GET","/api/cli/claude/status","CLI Auth","bearer_token","server/routes/cli-auth.js","9","Report local authentication status for provider CLIs.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","low"
+"http","GET","/api/cli/cursor/status","CLI Auth","bearer_token","server/routes/cli-auth.js","39","Report local authentication status for provider CLIs.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","low"
+"http","GET","/api/cli/codex/status","CLI Auth","bearer_token","server/routes/cli-auth.js","59","Report local authentication status for provider CLIs.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","low"
+"http","GET","/api/cli/gemini/status","CLI Auth","bearer_token","server/routes/cli-auth.js","79","Report local authentication status for provider CLIs.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","low"
+"http","GET","/api/user/git-config","User","bearer_token","server/routes/user.js","28","Read or update stored git identity settings.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Touches git repositories or local git config.","medium"
+"http","POST","/api/user/git-config","User","bearer_token","server/routes/user.js","57","Read or update stored git identity settings.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","gitEmail; try {
+    const userId = req.user.id;
+    const { gitName","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.; Touches git repositories or local git config.","medium"
+"http","POST","/api/user/complete-onboarding","User","bearer_token","server/routes/user.js","93","Mark onboarding as completed for the current user.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Mutates backend or external state.","medium"
+"http","GET","/api/user/onboarding-status","User","bearer_token","server/routes/user.js","108","Return onboarding completion status for the current user.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Read-only backend query.","medium"
+"http","GET","/api/codex/config","Providers","bearer_token","server/routes/codex.js","23","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","GET","/api/codex/sessions","Providers","bearer_token","server/routes/codex.js","54","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","try {
+    const { projectPath","","JSON object with an explicit success flag and payload.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","GET","/api/codex/sessions/:sessionId/messages","Providers","bearer_token","server/routes/codex.js","71","Return paginated messages for a stored session.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","limit; offset","","JSON object with an explicit success flag and payload.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","DELETE","/api/codex/sessions/:sessionId","Providers","bearer_token","server/routes/codex.js","89","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","","","JSON object with an explicit success flag and payload.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","GET","/api/codex/mcp/cli/list","Providers","bearer_token","server/routes/codex.js","103","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Reads or writes MCP CLI configuration.","medium"
+"http","POST","/api/codex/mcp/cli/add","Providers","bearer_token","server/routes/codex.js","135","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","DELETE","/api/codex/mcp/cli/remove/:name","Providers","bearer_token","server/routes/codex.js","186","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Mutates backend or external state.; Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/codex/mcp/cli/get/:name","Providers","bearer_token","server/routes/codex.js","220","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/codex/mcp/config/read","Providers","bearer_token","server/routes/codex.js","254","Manage Codex configuration, MCP settings, and stored sessions.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Reads or writes MCP CLI configuration.","medium"
+"http","GET","/api/gemini/sessions/:sessionId/messages","Providers","bearer_token","server/routes/gemini.js","8","Return paginated messages for a stored session.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","","","Structured JSON object response.","JSON error response with HTTP status code.","Read-only backend query.","medium"
+"http","DELETE","/api/gemini/sessions/:sessionId","Providers","bearer_token","server/routes/gemini.js","37","List or manage sessions associated with a project or provider.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","sessionId","","","JSON object with an explicit success flag and payload.","JSON error response with HTTP status code.","Mutates backend or external state.","medium"
+"http","GET","/api/plugins","Plugins","bearer_token","server/routes/plugins.js","27","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","","Structured JSON object response.","JSON object with error message and optional details.","Installs, updates, or serves plugin assets/processes.","medium"
+"http","GET","/api/plugins/:name/manifest","Plugins","bearer_token","server/routes/plugins.js","40","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","JSON payload returned directly from service logic.","JSON object with error message and optional details.","Installs, updates, or serves plugin assets/processes.","medium"
+"http","GET","/api/plugins/:name/assets/*","Plugins","bearer_token","server/routes/plugins.js","57","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","Mixed response shape; inspect handler during refactor.","JSON object with error message and optional details.","Installs, updates, or serves plugin assets/processes.","medium"
+"http","PUT","/api/plugins/:name/enable","Plugins","bearer_token","server/routes/plugins.js","96","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","try {
+    const { enabled","JSON object with an explicit success flag and payload.","JSON object with error message and optional details.","Mutates backend or external state.; Installs, updates, or serves plugin assets/processes.","medium"
+"http","POST","/api/plugins/install","Plugins","bearer_token","server/routes/plugins.js","136","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","try {
+    const { url","JSON object with an explicit success flag and payload.","JSON validation error response.","Mutates backend or external state.; Installs, updates, or serves plugin assets/processes.","medium"
+"http","POST","/api/plugins/:name/update","Plugins","bearer_token","server/routes/plugins.js","169","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","JSON object with an explicit success flag and payload.","JSON validation error response.","Mutates backend or external state.; Installs, updates, or serves plugin assets/processes.","medium"
+"http","DELETE","/api/plugins/:name","Plugins","bearer_token","server/routes/plugins.js","282","List, install, update, serve, enable, or remove plugins.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","name","","","JSON object with an explicit success flag and payload.","JSON validation error response.","Mutates backend or external state.; Installs, updates, or serves plugin assets/processes.","medium"
+"sse","POST","/api/agent","Agent","api_key_or_platform","server/routes/agent.js","839","Accept external agent jobs that run a provider against a local or cloned project.","src/components/chat/hooks/useChatComposerState.ts; src/components/chat/hooks/useChatProviderState.ts; src/components/chat/hooks/useChatSessionState.ts; src/components/chat/hooks/useSlashCommands.ts; src/components/file-tree/view/ImageViewer.tsx; src/components/git-panel/hooks/useGitPanelController.ts; src/components/git-panel/hooks/useRevertLocalCommit.ts; src/components/onboarding/view/Onboarding.tsx; src/components/plugins/view/PluginIcon.tsx; src/components/plugins/view/PluginTabContent.tsx; src/components/prd-editor/hooks/usePrdSave.ts; src/components/project-creation-wizard/data/workspaceApi.ts; src/components/settings/constants/constants.ts; src/components/settings/hooks/useCredentialsSettings.ts; src/components/settings/hooks/useGitSettings.ts; src/components/settings/hooks/useSettingsController.ts; src/components/version-upgrade/view/VersionUpgradeModal.tsx; src/contexts/PluginsContext.tsx; src/utils/api.js","","","branchName; cleanup; const { githubUrl; createBranch; createPR; githubToken; message; model; projectPath; provider; stream","Server-sent events stream with progress/result/error events.","Streamed error event or JSON error fallback.","Mutates backend or external state.; Invokes external AI providers and may modify project files.","high"

docs/backend/endpoint-inventory.md

@@ -0,0 +1,217 @@
+# Backend Inventory
+
+Generated on 2026-03-11T17:31:18.119Z.
+
+## Summary
+
+- HTTP routes: 118
+- SSE routes: 3
+- Modular routes: 96
+- Inline routes: 25
+- Route files scanned: 16
+
+## Realtime Contracts
+
+- Incoming websocket message types (14): abort-session, check-session-status, claude-command, claude-permission-response, codex-command, cursor-abort, cursor-command, cursor-resume, gemini-command, get-active-sessions, get-pending-permissions, init, input, resize
+- Outgoing websocket message types (7): active-sessions, auth_url, error, output, pending-permissions-response, session-aborted, session-status
+
+## Agent
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/agent` | api_key_or_platform | Accept external agent jobs that run a provider against a local or cloned project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/agent.js:839 |
+
+## Auth
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/auth/login` | public | Authenticate a local user and issue a token. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/auth.js:82 |
+| POST | `/api/auth/logout` | bearer_token | Invalidate the current authenticated session. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/auth.js:129 |
+| POST | `/api/auth/register` | public | Create the first local user account. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/auth.js:23 |
+| GET | `/api/auth/status` | public | Report whether authentication is configured. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/auth.js:9 |
+| GET | `/api/auth/user` | bearer_token | Return the currently authenticated user. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/auth.js:122 |
+
+## CLI Auth
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/cli/claude/status` | bearer_token | Report local authentication status for provider CLIs. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cli-auth.js:9 |
+| GET | `/api/cli/codex/status` | bearer_token | Report local authentication status for provider CLIs. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cli-auth.js:59 |
+| GET | `/api/cli/cursor/status` | bearer_token | Report local authentication status for provider CLIs. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cli-auth.js:39 |
+| GET | `/api/cli/gemini/status` | bearer_token | Report local authentication status for provider CLIs. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cli-auth.js:79 |
+
+## Commands
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/commands/execute` | bearer_token | List, load, or execute slash commands available to the chat experience. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/commands.js:507 |
+| POST | `/api/commands/list` | bearer_token | List, load, or execute slash commands available to the chat experience. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/commands.js:406 |
+| POST | `/api/commands/load` | bearer_token | List, load, or execute slash commands available to the chat experience. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/commands.js:456 |
+
+## Files
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/projects/:projectName/file` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:795 |
+| PUT | `/api/projects/:projectName/file` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:888 |
+| GET | `/api/projects/:projectName/files` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:937 |
+| DELETE | `/api/projects/:projectName/files` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:1170 |
+| GET | `/api/projects/:projectName/files/content` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:835 |
+| POST | `/api/projects/:projectName/files/create` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:1016 |
+| PUT | `/api/projects/:projectName/files/rename` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:1093 |
+| POST | `/api/projects/:projectName/files/upload` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:1396 |
+| POST | `/api/projects/:projectName/upload-images` | bearer_token | Upload images for chat use and return browser-safe data URLs. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:2113 |
+
+## Git
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/git/branches` | bearer_token | List git branches for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:639 |
+| POST | `/api/git/checkout` | bearer_token | POST /api/git/checkout for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:681 |
+| POST | `/api/git/commit` | bearer_token | POST /api/git/commit for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:561 |
+| GET | `/api/git/commit-diff` | bearer_token | Return diff details for a specific commit. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:782 |
+| GET | `/api/git/commits` | bearer_token | List recent commits for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:725 |
+| POST | `/api/git/create-branch` | bearer_token | POST /api/git/create-branch for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:703 |
+| POST | `/api/git/delete-untracked` | bearer_token | POST /api/git/delete-untracked for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1410 |
+| GET | `/api/git/diff` | bearer_token | Return git diff output for a project or file. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:354 |
+| POST | `/api/git/discard` | bearer_token | POST /api/git/discard for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1356 |
+| POST | `/api/git/fetch` | bearer_token | POST /api/git/fetch for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1097 |
+| GET | `/api/git/file-with-diff` | bearer_token | Read, write, create, rename, delete, or upload project files. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:437 |
+| POST | `/api/git/generate-commit-message` | bearer_token | Generate an AI-assisted commit message from the current diff. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:814 |
+| POST | `/api/git/initial-commit` | bearer_token | POST /api/git/initial-commit for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:517 |
+| POST | `/api/git/publish` | bearer_token | POST /api/git/publish for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1277 |
+| POST | `/api/git/pull` | bearer_token | POST /api/git/pull for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1138 |
+| POST | `/api/git/push` | bearer_token | POST /api/git/push for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1206 |
+| GET | `/api/git/remote-status` | bearer_token | Report remote sync status for a project repository. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:1019 |
+| POST | `/api/git/revert-local-commit` | bearer_token | POST /api/git/revert-local-commit for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:592 |
+| GET | `/api/git/status` | bearer_token | Read git status information for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/git.js:291 |
+
+## MCP
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/mcp-utils/all-servers` | bearer_token | Return MCP helper information used by setup flows. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp-utils.js:35 |
+| GET | `/api/mcp-utils/taskmaster-server` | bearer_token | Return MCP helper information used by setup flows. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp-utils.js:18 |
+| POST | `/api/mcp/cli/add` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:59 |
+| POST | `/api/mcp/cli/add-json` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:142 |
+| GET | `/api/mcp/cli/get/:name` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:305 |
+| GET | `/api/mcp/cli/list` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:16 |
+| DELETE | `/api/mcp/cli/remove/:name` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:235 |
+| GET | `/api/mcp/config/read` | bearer_token | Manage Claude MCP CLI and configuration state. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/mcp.js:348 |
+
+## Plugins
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/plugins` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:27 |
+| DELETE | `/api/plugins/:name` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:282 |
+| GET | `/api/plugins/:name/assets/*` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:57 |
+| PUT | `/api/plugins/:name/enable` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:96 |
+| GET | `/api/plugins/:name/manifest` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:40 |
+| POST | `/api/plugins/:name/update` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:169 |
+| POST | `/api/plugins/install` | bearer_token | List, install, update, serve, enable, or remove plugins. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/plugins.js:136 |
+
+## Projects
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/create-folder` | bearer_token | Create a new directory on the local filesystem. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:754 |
+| GET | `/api/projects` | bearer_token | List detected projects and workspaces. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:491 |
+| DELETE | `/api/projects/:projectName` | bearer_token | DELETE /api/projects/:projectName for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:589 |
+| PUT | `/api/projects/:projectName/rename` | bearer_token | PUT /api/projects/:projectName/rename for backend runtime support. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:537 |
+| GET | `/api/projects/clone-progress` | bearer_token | Stream workspace cloning progress events to the frontend. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/projects.js:335 |
+| POST | `/api/projects/create` | bearer_token | Manually add a project path to the workspace list. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:601 |
+| POST | `/api/projects/create-workspace` | bearer_token | Create or register a workspace and optionally clone a GitHub repository into it. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/projects.js:175 |
+
+## Providers
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/codex/config` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:23 |
+| POST | `/api/codex/mcp/cli/add` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:135 |
+| GET | `/api/codex/mcp/cli/get/:name` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:220 |
+| GET | `/api/codex/mcp/cli/list` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:103 |
+| DELETE | `/api/codex/mcp/cli/remove/:name` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:186 |
+| GET | `/api/codex/mcp/config/read` | bearer_token | Manage Codex configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:254 |
+| GET | `/api/codex/sessions` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:54 |
+| DELETE | `/api/codex/sessions/:sessionId` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:89 |
+| GET | `/api/codex/sessions/:sessionId/messages` | bearer_token | Return paginated messages for a stored session. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/codex.js:71 |
+| GET | `/api/cursor/config` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:15 |
+| POST | `/api/cursor/config` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:59 |
+| GET | `/api/cursor/mcp` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:122 |
+| DELETE | `/api/cursor/mcp/:name` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:245 |
+| POST | `/api/cursor/mcp/add` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:183 |
+| POST | `/api/cursor/mcp/add-json` | bearer_token | Manage Cursor configuration, MCP settings, and stored sessions. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:292 |
+| GET | `/api/cursor/sessions` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:348 |
+| GET | `/api/cursor/sessions/:sessionId` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/cursor.js:583 |
+| DELETE | `/api/gemini/sessions/:sessionId` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/gemini.js:37 |
+| GET | `/api/gemini/sessions/:sessionId/messages` | bearer_token | Return paginated messages for a stored session. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/gemini.js:8 |
+
+## Realtime
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/browse-filesystem` | bearer_token | Browse local directories so the UI can suggest workspace locations. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:674 |
+| POST | `/api/transcribe` | bearer_token | Transcribe uploaded audio and optionally enhance the result for prompts or tasks. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:1964 |
+
+## Sessions
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/projects/:projectName/sessions` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:500 |
+| DELETE | `/api/projects/:projectName/sessions/:sessionId` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:548 |
+| GET | `/api/projects/:projectName/sessions/:sessionId/messages` | bearer_token | Return paginated messages for a stored session. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:512 |
+| GET | `/api/projects/:projectName/sessions/:sessionId/token-usage` | bearer_token | Report token usage for a stored provider session. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:2198 |
+| GET | `/api/search/conversations` | bearer_token | Search conversation history across stored projects and stream results. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:618 |
+| PUT | `/api/sessions/:sessionId/rename` | bearer_token | List or manage sessions associated with a project or provider. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:563 |
+
+## Settings
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `/api/settings/api-keys` | bearer_token | Manage local API keys used to access the backend. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:11 |
+| POST | `/api/settings/api-keys` | bearer_token | Manage local API keys used to access the backend. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:27 |
+| DELETE | `/api/settings/api-keys/:keyId` | bearer_token | Manage local API keys used to access the backend. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:47 |
+| PATCH | `/api/settings/api-keys/:keyId/toggle` | bearer_token | Manage local API keys used to access the backend. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:64 |
+| GET | `/api/settings/credentials` | bearer_token | Manage stored provider and GitHub credentials. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:91 |
+| POST | `/api/settings/credentials` | bearer_token | Manage stored provider and GitHub credentials. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:104 |
+| DELETE | `/api/settings/credentials/:credentialId` | bearer_token | Manage stored provider and GitHub credentials. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:139 |
+| PATCH | `/api/settings/credentials/:credentialId/toggle` | bearer_token | Manage stored provider and GitHub credentials. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/settings.js:156 |
+
+## System
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| GET | `*` | public | Serve the React application fallback for non-API routes. | - | server/index.js:2386 |
+| POST | `/api/system/update` | bearer_token | Run the application update workflow on the host machine. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/index.js:425 |
+| GET | `/health` | public | Expose server health, timestamp, and install mode for diagnostics. | src/hooks/useVersionCheck.ts | server/index.js:345 |
+
+## TaskMaster
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/taskmaster/add-task/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:1060 |
+| POST | `/api/taskmaster/apply-template/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:1838 |
+| GET | `/api/taskmaster/detect-all` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:350 |
+| GET | `/api/taskmaster/detect/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:278 |
+| POST | `/api/taskmaster/init/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:971 |
+| POST | `/api/taskmaster/initialize/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:434 |
+| GET | `/api/taskmaster/installation-status` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:243 |
+| GET | `/api/taskmaster/next/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:460 |
+| POST | `/api/taskmaster/parse-prd/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:1291 |
+| GET | `/api/taskmaster/prd-templates` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:1392 |
+| GET | `/api/taskmaster/prd/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:685 |
+| POST | `/api/taskmaster/prd/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:761 |
+| GET | `/api/taskmaster/prd/:projectName/:fileName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:846 |
+| DELETE | `/api/taskmaster/prd/:projectName/:fileName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:911 |
+| GET | `/api/taskmaster/tasks/:projectName` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:570 |
+| PUT | `/api/taskmaster/update-task/:projectName/:taskId` | bearer_token | Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/taskmaster.js:1164 |
+
+## User
+
+| Method | Path | Auth | Purpose | Consumers | Source |
+| --- | --- | --- | --- | --- | --- |
+| POST | `/api/user/complete-onboarding` | bearer_token | Mark onboarding as completed for the current user. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/user.js:93 |
+| GET | `/api/user/git-config` | bearer_token | Read or update stored git identity settings. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/user.js:28 |
+| POST | `/api/user/git-config` | bearer_token | Read or update stored git identity settings. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/user.js:57 |
+| GET | `/api/user/onboarding-status` | bearer_token | Return onboarding completion status for the current user. | src/components/chat/hooks/useChatComposerState.ts<br>src/components/chat/hooks/useChatProviderState.ts<br>src/components/chat/hooks/useChatSessionState.ts<br>src/components/chat/hooks/useSlashCommands.ts<br>src/components/file-tree/view/ImageViewer.tsx<br>src/components/git-panel/hooks/useGitPanelController.ts<br>src/components/git-panel/hooks/useRevertLocalCommit.ts<br>src/components/onboarding/view/Onboarding.tsx<br>src/components/plugins/view/PluginIcon.tsx<br>src/components/plugins/view/PluginTabContent.tsx<br>src/components/prd-editor/hooks/usePrdSave.ts<br>src/components/project-creation-wizard/data/workspaceApi.ts<br>src/components/settings/constants/constants.ts<br>src/components/settings/hooks/useCredentialsSettings.ts<br>src/components/settings/hooks/useGitSettings.ts<br>src/components/settings/hooks/useSettingsController.ts<br>src/components/version-upgrade/view/VersionUpgradeModal.tsx<br>src/contexts/PluginsContext.tsx<br>src/utils/api.js | server/routes/user.js:108 |

docs/backend/input-parsing-cross-platform.md

@@ -0,0 +1,314 @@
+# Cross-Platform Input Parsing Notes
+## Why This Matters In This Repo
+CloudCLI is not only an HTTP API plus React UI. From the README and current backend layout, it also launches CLIs, keeps interactive terminal sessions alive, reads and writes local files, parses process output, and forwards terminal input from the browser into local shells. That puts the backend on the boundary between browser input, terminal behavior, child process behavior, and filesystem behavior. Linux and Windows differ at each of those boundaries.
+
+For the TypeScript migration, the OS adapter layer now lives in:
+- [server/src/shared/platform/index.ts](/c:/Users/OMEN6/Desktop/Projects/Paid/ClaudeCodeUI%20-%20Siteboon/claudecodeui/server/src/shared/platform/index.ts)
+
+Use those helpers in new `server/src` code so feature modules do not branch on the operating system.
+
+## Assumptions
+- The legacy runtime in `server/index.js` stays untouched for now.
+- New backend code will be added under `server/src`.
+- Node.js 22 is the baseline because the README already requires Node 22+.
+- The main instability is text handling around shells, streams, and files, not business logic.
+
+## Where Parsing Happens In This Repo
+- `server/index.js`: PTY shell input/output and session reuse
+- `server/cursor-cli.js`: streaming line-delimited JSON from `cursor-agent`
+- `server/gemini-response-handler.js`: incremental parsing of Gemini JSON lines
+- `server/routes/mcp.js` and `server/routes/codex.js`: parsing human-readable CLI output
+- `server/cli.js` and `server/load-env.js`: parsing command-line args and `.env` text
+- `server/routes/git.js` and related routes: parsing Git stdout line by line
+
+Those are not all the same problem. In this repo, "input parsing" means terminal input parsing, stream parsing, file parsing, shell command construction, and path normalization.
+
+## Core Terms
+### Process
+A process is a running program such as `node server/start.js`, `git`, `codex`, or `cursor-agent`. When your backend launches one of these, the backend is the parent process and the launched program is the child process.
+
+### Child Process
+A child process is a process started by another process. Examples:
+- CloudCLI launches `git status`
+- CloudCLI launches `codex mcp list`
+- CloudCLI launches `cursor-agent --output-format stream-json`
+
+Important point: a child process usually does not hand you one final string. It emits output over time.
+
+### stdin, stdout, stderr
+These are the three standard streams:
+- `stdin`: data going into the process
+- `stdout`: normal output coming out
+- `stderr`: diagnostics, warnings, and errors
+
+Node example:
+```ts
+const child = spawn('git', ['status']);
+child.stdout.on('data', (chunk) => {
+  // normal output from git
+});
+child.stderr.on('data', (chunk) => {
+  // warnings or errors
+});
+child.stdin.write('yes\n');
+child.stdin.end();
+```
+
+Repo examples:
+- terminal keystrokes go to `stdin`
+- `cursor-agent` JSON events arrive on `stdout`
+- many CLI failures appear on `stderr`
+
+### TTY and PTY
+- `TTY`: a terminal device
+- `PTY`: a pseudo-terminal, meaning software that behaves like a terminal
+
+Why it matters:
+- `spawn()` is best for non-interactive commands like `git status`
+- `node-pty` is best for interactive shells like PowerShell or bash sessions
+
+Repo example: `server/index.js` uses `node-pty` for the integrated shell because agents and shells expect terminal behavior, not just plain pipes.
+
+### argv
+`argv` means argument vector: the list of command-line arguments passed to a program.
+
+Example:
+```ts
+spawn('git', ['log', '--oneline', '-5']);
+```
+
+Here the executable is `git` and the argv is `['log', '--oneline', '-5']`. This is safer than building one big shell string because Node passes arguments directly instead of asking a shell to reinterpret them.
+
+### cwd
+`cwd` means current working directory. Examples:
+- run `git status` in the project root
+- run `claude mcp add --scope local` inside the current project
+- run a terminal session inside a selected workspace
+
+If `cwd` is wrong, parsing may look broken even when the parser is correct, because the command itself is operating in the wrong place.
+
+### Buffer, String, and Decoding
+A `Buffer` is raw bytes. A string is decoded text. Processes emit bytes first, then you decode them, and only after that should you parse lines, JSON, or tokens.
+
+Example:
+```ts
+child.stdout.on('data', (chunk: Buffer) => {
+  const text = chunk.toString('utf8');
+});
+```
+
+### Line Ending
+A line ending marks the end of a text line:
+- Linux/macOS usually use LF: `\n`
+- Windows often uses CRLF: `\r\n`
+- older tools sometimes emit CR alone: `\r`
+
+Classic bug:
+```ts
+'a\r\nb\r\n'.split('\n');
+// ['a\r', 'b\r', '']
+```
+
+That hidden trailing `\r` is one of the most common Windows parsing bugs.
+
+### BOM
+BOM means byte order mark. In UTF-8 text it appears as `\uFEFF` at the start. Typical failures:
+- first key becomes `\uFEFFNAME` instead of `NAME`
+- JSON parsing fails because the first character is not what the parser expected
+- `.env` parsing silently produces the wrong first variable name
+
+The adapter layer strips BOM explicitly for that reason.
+
+### Chunk
+A chunk is one partial piece of stream data. Chunks are transport boundaries, not logical message boundaries. Important rules:
+- one line can arrive in multiple chunks
+- one chunk can contain many lines
+- one JSON object can be split across chunk boundaries
+
+Example:
+```txt
+Chunk 1: {"type":"message","text":"hel
+Chunk 2: lo"}\r\n{"type":"message","text":"next"}\r\n
+```
+
+If you parse each chunk independently, you corrupt the first JSON object.
+
+## The Backend Parsing Lifecycle
+Most backend parsing problems in this repo can be viewed as a four-step pipeline:
+1. Receive raw bytes or raw text.
+2. Normalize transport details.
+3. Parse business structure.
+4. Return normalized data to the rest of the app.
+
+Examples:
+- file bytes -> UTF-8 string -> normalize line endings -> split lines -> parse fields
+- stdout chunks -> accumulate partial lines -> parse JSON per line -> emit events
+- browser terminal input -> normalize Enter/newlines -> write to PTY
+
+The operating system mainly affects step 2. That is why the new adapter layer exists.
+
+## Linux vs Windows Differences That Usually Matter
+### 1. Newlines In Files And Process Output
+Linux usually gives LF. Windows often gives CRLF. Some tools mix them.
+
+Bad pattern:
+```ts
+const lines = output.split('\n');
+```
+
+Safer pattern:
+```ts
+import { splitLines } from '@/shared/platform/index.js';
+
+const lines = splitLines(output, {
+  preserveEmptyLines: false,
+  trimTrailingEmptyLine: true,
+});
+```
+
+Use `splitLines()` when you already have the whole string in memory.
+
+### 2. Chunked Streams
+A process stream is not line-oriented by default.
+
+Bad pattern:
+```ts
+child.stdout.on('data', (chunk) => {
+  const event = JSON.parse(chunk.toString());
+});
+```
+
+This fails when one JSON object is split across chunks.
+
+Safer pattern:
+```ts
+import { createStreamLineAccumulator } from '@/shared/platform/index.js';
+
+const lines = createStreamLineAccumulator({ preserveEmptyLines: false });
+child.stdout.on('data', (chunk) => {
+  for (const line of lines.push(chunk)) {
+    const event = JSON.parse(line);
+  }
+});
+child.on('close', () => {
+  for (const line of lines.flush()) {
+    const event = JSON.parse(line);
+  }
+});
+```
+
+Use this for Cursor, Gemini, JSONL, NDJSON, or any line-based CLI protocol.
+
+### 3. Shell Syntax And Fallback Logic
+POSIX shells and PowerShell do not use the same syntax.
+- POSIX fallback: `cmd1 || cmd2`
+- PowerShell fallback: `cmd1; if ($LASTEXITCODE -ne 0) { cmd2 }`
+
+Use:
+```ts
+import { buildFallbackCommand, createShellSpawnPlan } from '@/shared/platform/index.js';
+
+const shellCommand = buildFallbackCommand('codex resume 123', 'codex', 'windows');
+const spawnPlan = createShellSpawnPlan(shellCommand, 'windows');
+```
+
+This keeps feature code from hardcoding bash rules into Windows paths or PowerShell rules into Linux code.
+
+### 4. Quoting Rules
+Even when two shells both support quotes, they do not escape them the same way.
+- POSIX single quote escape is awkward: `'it'"'"'s'`
+- PowerShell single quote escape doubles the quote: `'it''s'`
+
+Use:
+```ts
+import { quoteShellArgument } from '@/shared/platform/index.js';
+
+const safe = quoteShellArgument("it's", 'windows');
+```
+
+### 5. Path Separators And Case
+- Linux paths use `/`
+- Windows paths typically use `\`
+- Linux is usually case-sensitive
+- Windows is usually case-insensitive
+
+Examples:
+- `/repo/File.ts` and `/repo/file.ts` are different on Linux
+- `C:\Repo\File.ts` and `c:\repo\file.ts` usually refer to the same file on Windows
+
+Use:
+```ts
+import { arePathsEquivalent, normalizePathForPlatform, toPortablePath } from '@/shared/platform/index.js';
+```
+
+Guideline:
+- use platform-specific paths when calling the OS
+- use portable slash paths for logs, keys, and serialized payloads
+
+### 6. Terminal Input
+Terminal input is not the same as a normal HTML form submission.
+- pressing Enter may arrive as `\r`
+- pasted text may contain `\n` or `\r\n`
+- terminal apps often expect carriage return behavior
+
+Use:
+```ts
+import { normalizeTerminalInput } from '@/shared/platform/index.js';
+```
+
+This matters for PTY writes because terminal software often treats `\r` as the real Enter key behavior.
+
+## The New Adapter Functions
+- `normalizeTextForParsing()`: use when your goal is parsing text consistently, not preserving original file style; good for `.env`, JSONL, human-readable CLI output, and buffered command output.
+- `splitLines()`: use when the full text is already in memory and you want clean logical lines; good for config files, buffered Git output, and fully collected CLI output.
+- `createStreamLineAccumulator()`: use when text arrives incrementally over time; good for `stdout`, `stderr`, line-based streaming JSON, and long-lived child processes.
+- `createShellSpawnPlan()`: use when the command must go through a shell because shell syntax is required; good for fallback commands, resume-or-start command chains, and interactive shell launch plans.
+- `quoteShellArgument()`: use before interpolating dynamic values into shell command strings; good for session IDs, file paths, branch names, and user-provided subcommands.
+- `buildFallbackCommand()`: use when the same logic must work in bash and PowerShell; a repo-shaped example is "resume Codex session if it exists, otherwise start a fresh one."
+- `preserveExistingLineEndings()`: use when writing text files back to disk and you want to avoid noisy diffs; good for markdown files, config files, and user-managed text artifacts.
+
+## Practical Backend Rules For This Repo
+1. If you already have the full text, normalize once and then parse.
+2. If the source is a stream, use an accumulator and never parse per chunk.
+3. Prefer `spawn(executable, argv, { shell: false })` whenever possible.
+4. Only use a shell when shell syntax is actually needed.
+5. When you must use a shell, push all shell-specific behavior into the adapter layer.
+6. Preserve existing line endings on user files unless you intentionally want normalization.
+7. Separate transport normalization from business parsing.
+
+## Common Mistakes To Avoid
+- Parsing stdout chunk-by-chunk. Symptom: random JSON parse failures or truncated events. Fix: accumulate complete lines first.
+- Using `split('\n')` on Windows text. Symptom: values end with `\r` and equality checks fail. Fix: normalize line endings or use `splitLines()`.
+- Building one huge shell string for everything. Symptom: quoting bugs, OS-specific failures, and injection risk. Fix: prefer `spawn()` with argv; if shell is required, use `quoteShellArgument()` and `createShellSpawnPlan()`.
+- Rewriting files with a different line-ending style. Symptom: huge git diffs and noisy file changes. Fix: use `preserveExistingLineEndings()`.
+
+## Testing Strategy Implemented Here
+This strategy intentionally does not add Jest, Vitest, or another test framework.
+
+It uses:
+- Node's built-in `node:test`
+- `tsx` only to execute TypeScript tests
+- a GitHub Actions matrix on Ubuntu and Windows
+
+Local verification:
+```bash
+npm run test:server
+npm run verify:server
+```
+
+CI verification:
+- `npm run typecheck:server`
+- `npm run test:server`
+- `npm run server:build`
+
+This gives you two kinds of confidence:
+- contract confidence: the adapter functions behave as designed
+- environment confidence: the same checks pass on real Linux and Windows runners
+
+## Final Mental Model
+Think in three layers:
+1. Raw transport layer. Examples: chunks, bytes, terminal keystrokes, raw file text.
+2. Normalization layer. Examples: strip BOM, normalize line endings, normalize terminal input, normalize shell behavior.
+3. Business parsing layer. Examples: parse JSON, parse CLI output, parse `.env`, parse Git status, parse session files.
+
+If you keep layer 2 in shared adapters, layer 3 stops caring about Linux vs Windows.

docs/backend/llm-module-structure.md

@@ -0,0 +1,190 @@
+# LLM Module Structure (Refactor Runtime)
+
+This document describes the current backend structure under `server/src/modules/llm`, how execution/session state works, and how the provider abstraction is designed.
+
+## High-Level Layout
+
+```text
+server/src/modules/llm/
+  llm.routes.ts
+  llm.registry.ts
+  providers/
+    provider.interface.ts
+    abstract.provider.ts
+    base-sdk.provider.ts
+    base-cli.provider.ts
+    claude.provider.ts
+    codex.provider.ts
+    cursor.provider.ts
+    gemini.provider.ts
+  services/
+    llm.service.ts
+    sessions.service.ts
+    sessions-watcher.service.ts
+    messages-unifier.service.ts
+    assets.service.ts
+    mcp.service.ts
+    skills.service.ts
+  session-indexers/
+    session-indexer.interface.ts
+    session-indexer.utils.ts
+    claude.session-indexer.ts
+    codex.session-indexer.ts
+    cursor.session-indexer.ts
+    gemini.session-indexer.ts
+    index.ts
+  tests/
+    llm-unifier.providers.test.ts
+    llm-unifier.sessions.test.ts
+    llm-unifier.images.test.ts
+    llm-unifier.mcp.test.ts
+    llm-unifier.skills.test.ts
+    llm-unifier.messages.test.ts
+```
+
+## Responsibilities By File Group
+
+- `llm.routes.ts`
+  - HTTP API for provider runtime sessions (start/resume/stop/model/thinking), normalized session/history messages, assets upload, MCP config/probe, skills listing, indexed session CRUD/sync.
+- `llm.registry.ts`
+  - Singleton provider registry. Instantiates one provider class per provider id.
+- `providers/*`
+  - Runtime execution and live event collection.
+  - SDK family (`BaseSdkProvider`) for Claude/Codex.
+  - CLI family (`BaseCliProvider`) for Cursor/Gemini.
+- `services/llm.service.ts`
+  - Input validation + capability gating + facade over provider registry.
+- `services/sessions.service.ts`
+  - DB-backed indexed sessions and history file parsing.
+  - Returns normalized message history via `messages-unifier.service.ts`.
+- `services/sessions-watcher.service.ts`
+  - `chokidar` watchers for provider artifact folders.
+  - On filesystem update, triggers `synchronizeProviderFile(provider, filePath)`.
+- `services/messages-unifier.service.ts`
+  - Provider-specific raw event/history -> unified message contract for frontend.
+- `services/assets.service.ts`
+  - Stores uploaded images in `.cloudcli/assets`.
+- `services/mcp.service.ts`
+  - Unified MCP CRUD/probe across provider-native config formats/scopes/transports.
+- `services/skills.service.ts`
+  - Provider-specific skill directory discovery and metadata extraction.
+- `session-indexers/*`
+  - Scans provider artifacts from disk and upserts indexed sessions into `sessions` DB table.
+
+## Runtime Flow (Provider Sessions)
+
+1. `POST /api/llm/providers/:provider/sessions/start` hits `llm.routes.ts`.
+2. Route calls `llmService.startSession(...)`.
+3. `llm.service.ts` validates payload and capability constraints.
+4. `llm.registry.ts` resolves provider instance.
+5. Provider (`BaseSdkProvider` or `BaseCliProvider`) creates an in-memory session record and starts execution.
+6. Stream/process output is appended as in-memory `ProviderSessionEvent[]`.
+7. Route can either:
+   - return `202` immediately with snapshot, or
+   - await completion via `waitForSession`.
+8. Snapshots are enriched with unified `messages` via `llmMessagesUnifier.normalizeSessionEvents(...)`.
+
+## Indexed History Flow (Disk/DB)
+
+1. Watcher or manual sync scans provider folders.
+2. Provider-specific indexer extracts minimal metadata and upserts `sessionsDb`.
+3. History endpoints (`/sessions/:sessionId/history`, `/sessions/:sessionId/messages`) read transcript path from DB.
+4. JSON/JSONL is parsed and transformed via `llmMessagesUnifier.normalizeHistoryEntries(...)`.
+
+## Interface + Abstract + Base-Class Design
+
+### `IProvider` (interface)
+`providers/provider.interface.ts`
+
+- Consumer contract used by registry/service layer.
+- Exposes:
+  - `launchSession`, `resumeSession`, `stopSession`, `waitForSession`
+  - `setSessionModel`, `setSessionThinkingMode`
+  - `getSession`, `listSessions`
+  - `listModels`
+- Exposes `capabilities` so callers can gate unsupported features before calling provider-specific logic.
+
+### `AbstractProvider` (abstract class)
+`providers/abstract.provider.ts`
+
+- Shared lifecycle state and rules:
+  - `sessions: Map<string, MutableProviderSession>`
+  - `sessionPreferences: Map<string, { model?, thinkingMode? }>`
+- Implements:
+  - in-memory session reads (`getSession`, `listSessions`, `waitForSession`)
+  - stop handling + session status events
+  - model/thinking updates with capability checks
+  - event ring-buffer logic (`MAX_EVENT_BUFFER_SIZE`)
+- Leaves provider execution specifics abstract (`listModels`, `launchSession`, `resumeSession`).
+
+### `BaseSdkProvider` and `BaseCliProvider`
+
+- `BaseSdkProvider`
+  - shared async iterable stream consumption.
+  - handles completion/error transitions and completion system event emission.
+- `BaseCliProvider`
+  - shared child-process spawn + stdout/stderr line accumulation + JSON line parsing.
+  - graceful stop (`SIGTERM` then `SIGKILL`) and completion/error transitions.
+
+### Concrete provider classes
+
+- `ClaudeProvider` (SDK)
+  - uses `@anthropic-ai/claude-agent-sdk`.
+  - supports runtime permission requests and emits permission events.
+  - image payload support via base64 content blocks.
+- `CodexProvider` (SDK)
+  - dynamic import of `@openai/codex-sdk`.
+  - supports text + `local_image` prompt items.
+- `CursorProvider` (CLI)
+  - `cursor-agent` invocation builder + model list parsing.
+- `GeminiProvider` (CLI)
+  - `gemini` invocation builder + curated model catalog.
+
+## In-Memory Session Setup: How It Works
+
+The in-memory part is inside `AbstractProvider` + base classes:
+
+- Session record is created at launch/resume in memory (`Map`).
+- Events are appended in real-time while stream/process runs.
+- Snapshot endpoints read this map directly (`/providers/:provider/sessions...`).
+- Stop/wait/model/thinking controls operate on this same in-memory handle.
+- Completed sessions currently remain in map (bounded event history per session, but no map eviction).
+
+Key characteristics:
+
+- Process-local only (not shared across instances).
+- Lost on server restart.
+- Good for immediate live control and progress.
+- Not the source of truth for historical transcripts (disk/DB is).
+
+## Is In-Memory Session State Necessary, Or Useless?
+
+Short answer: **not useless**, but **not sufficient as a durable architecture**.
+
+### Why it is necessary in the current design
+
+- You need live handles for:
+  - `stopSession` (abort process/stream now),
+  - `waitForSession`,
+  - real-time event buffering for immediate API responses.
+- These are runtime concerns and cannot be satisfied by session-index DB rows alone.
+
+### Where it is weak
+
+- No eviction/pruning for completed session map entries.
+- No persistence across restart.
+- No cross-instance coordination (if horizontally scaled, only the owning instance can control that session).
+
+### Practical conclusion
+
+- Keep in-memory runtime state for **active execution control**.
+- Treat DB/indexed history as the durable read model.
+- If you need reliability across restarts/instances, move execution ownership to a durable worker/orchestrator and store live session metadata in a shared store.
+
+## Suggested Hardening (Incremental)
+
+1. Add session map eviction policy (TTL/LRU for completed/failed/stopped sessions).
+2. Add ownership metadata (`instanceId`) if multiple backend instances will run.
+3. Add explicit `activeSessions` metric endpoint.
+4. Optionally persist minimal runtime state (status transitions + timestamps) to DB for auditability.
+

docs/backend/llm-unifier-helper-2.md

@@ -0,0 +1,456 @@
+# How each provider supports image uploading
+
+Universally: First, we should upload the images in `.cloudcli/assets` folder. Then,  it should just reference that path later on.
+
+## Claude
+- When clicking send, attach the images in the content list with the type of 'image'.
+- https://platform.claude.com/docs/en/api/messages#message_param
+```js
+  const imageBytes = await fs.readFile(imagePath);
+  const sdkPrompt = (async function*: AsyncIterable<SDKUserMessage> () {
+    yield {
+      type: 'user',
+      message: {
+        role: 'user',
+        content: [
+          { type: 'text', text: prompt },
+          {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: 'image/jpeg',
+              data: imageBytes.toString('base64'),
+            },
+          },
+        ],
+      },
+      parent_tool_use_id: null,
+      timestamp: new Date().toISOString(),
+    };
+  })(); // automatically executed because of the `()` in the end.
+```
+
+### Some useful types
+```ts
+export interface MessageParam {
+  content: string | Array<ContentBlockParam>;
+
+  role: 'user' | 'assistant'; // when we send the message for prompting, the role will be 'user'
+}
+
+/**
+ * Regular text content.
+ */
+export type ContentBlockParam =
+  | TextBlockParam
+  | ImageBlockParam
+  | DocumentBlockParam
+  | SearchResultBlockParam
+  | ThinkingBlockParam
+  | RedactedThinkingBlockParam
+  | ToolUseBlockParam
+  | ToolResultBlockParam
+  | ServerToolUseBlockParam
+  | WebSearchToolResultBlockParam;
+  
+  
+export interface TextBlockParam {
+  text: string;
+  type: 'text';
+}
+
+export interface ImageBlockParam {
+  source: Base64ImageSource | URLImageSource; // I'll be using only base 64 for now.
+  type: 'image';
+}
+
+export interface Base64ImageSource {
+  data: string;
+  media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+  type: 'base64';
+}
+```
+
+### Explanations about async generators and yield
+To understand why `async function*` is used, it helps to stop thinking of functions as "machines that run and finish" and start thinking of them as **"factories that stay open."** 
+```ts
+async function* getTaskStatus(): AsyncIterable<string> {
+  yield "Checking permissions..."; 
+  await new Promise(r => setTimeout(r, 500)); // Simulate work
+
+  yield "Searching database...";
+  await new Promise(r => setTimeout(r, 500));
+
+  yield "Formatting prompt...";
+}
+
+// CONSUMPTION
+async function run() {
+  const statusGenerator = getTaskStatus();
+
+  for await (const status of statusGenerator) {
+    console.log(`Current Status: ${status}`);
+  }
+  
+  console.log("Done!");
+}
+```
+
+## Codex
+```ts
+const streamed = await thread.runStreamed([ {type: "text", text: "Describe this image:"}, {type: "local_image", path: "scripts/pic.jpg"}
+```
+- Don't add the above query lines for codex. We can directly use the `sdk`.
+
+## Gemini and Cursor
+- Just add the path to the end of the prompt when clicking send for paths including images. For e.g. 
+```
+<some-user-prompt>
+
+<images_input>
+---- IGNORE THE <images_input> QUERY LINES. Just use the attached list of an array of paths for images below and use it with the above prompt.
+
+["scripts\pic.jpg", "<path-for-second-image>", ...]
+```
+
+
+
+# MCP servers (how to add/remove one and run it)
+
+**What is the Model Context Protocol (MCP)?**
+Think of MCP as the USB-C cable for AI.
+- Historically, if you wanted an AI model to read your GitHub repository, query your database, or search your company's Notion workspace, developers had to write custom, one-off integrations for every single AI tool.
+- Created by Anthropic as an open-source standard, the Model Context Protocol fixes this. It is a universal language that allows AI applications (the "clients") to securely connect to external data sources and tools (the "servers") using a single, unified protocol.
+
+**What is an MCP Server?**
+- If MCP is the USB-C cable, an **MCP Server** is the hard drive or webcam you are plugging in.
+- It is a lightweight program that acts as a secure bridge between your specific data and the AI. When the AI needs context—like checking the current state of a file or executing a search—it asks the MCP server. The server translates the AI's request, securely fetches the data or performs the action, and hands the result back to the AI.
+
+ **Different  transport mechanisms for MCP servers**
+1. `stdio` - This is the default and most common transport for local development. When using `stdio`, the AI client directly launches the MCP server as a background "child process" on your machine. The client and server then talk to each other locally by writing to and reading from standard input (`stdin`) and standard output (`stdout`).
+	- **Clear Example:** A local **File System Server**. You want the AI to read your local `package.json` file. The AI client spawns the file system server via `stdio`. Because the server is running locally on your hardware, it inherently has access to your files without needing complex authentication. It reads the file and prints the contents back to the AI.
+2. `https` (Streamable HTTP) - Streamable HTTP replaces older remote methods. It uses a single HTTP or HTTPS endpoint for bidirectional communication. The client sends standard `POST` requests, and the server can respond instantly or keep the connection open to stream data back. It behaves exactly like a modern web API. Because it runs over HTTP, it supports standard web security features like OAuth, Bearer tokens, and CORS.
+	- **Clear Example:** A **Cloud Database Server**. If you work on a team and want everyone's AI to be able to query a shared staging database, you would deploy an MCP server to the cloud. Your AI connects to `https://api.yourcompany.com/mcp` using Streamable HTTP and passes an API key in the headers to securely run queries.
+3. `sse` (Server sent events) - SSE is the legacy transport mechanism for remote servers. While still widely supported, it is actively being phased out in favor of Streamable HTTP because it is slightly more cumbersome to build and maintain.
+	- **How it works:** Unlike Streamable HTTP which uses a single unified endpoint, SSE requires _two_ distinct network connections. The client connects to an SSE endpoint (via an HTTP `GET` request) strictly to listen for incoming messages from the server, and uses a separate HTTP `POST` endpoint to send messages to the server.
+    
+- **Clear Example:** An older **Slack Integration Server**. The AI client connects to the server's SSE stream to listen for real-time incoming messages from a Slack channel. When the AI wants to reply, it sends a payload to a separate `/message` POST endpoint.
+
+**Frontend coordination**
+- When listing the MCP servers for a provider, go to the appropriate files where the configuration is stored to fetch all of them. When listing, the User/Local/Project MCPs should be grouped separately. 
+- To add/remove an MCP server, go to the appropriate file and add/remove it there keeping in mind whether it is configured as User/Local/Project. 
+- To update the server, go to the appropriate file and update it from there.
+- There should also be one big mcp adder that supports `http` and `stdio` only. When it's added from there, the server will automatically be added to every provider.
+
+## Claude
+Supports all 3 transports.
+### `stdio`
+- We can have arguments and env variables input when executing the command.
+- `args` and `env` are optional.
+```json
+{
+  "mcpServers": {
+    "local-weather": {
+      "type": "stdio",
+      "command": "/path/to/weather-cli",
+      "args": ["--api-key", "abc123"],
+      "env": {
+        "CACHE_DIR": "/tmp"
+      }
+    }
+  }
+}
+```
+
+### `http`
+- We don't pass `env` inputs for now. It's supported but we will add it only later.
+- `headers` is optional.
+```json
+{
+  "mcpServers": {
+    "weather-api": {
+      "type": "http",
+      "url": "https://api.weather.com/mcp",
+      "headers": {
+        "Authorization": "Bearer token"
+      }
+    }
+  }
+}
+```
+
+### `sse`
+- similar with `http` format.
+```json
+{
+  "mcpServers": {
+	"private-api": {
+	  "type": "sse",
+	  "url": "https://api.company.com/sse",
+	  "headers": {
+		"X-API-Key": "your-key-here"
+		}
+	}
+  }
+}
+```
+
+### Support for different modes (Local, user, project)
+
+#### Local
+- stored in `~/.claude.json` under the project’s path.
+#### User
+- stored in `~/.claude.json` under the main object with the key `"mcpServers"
+#### Project specific
+- add it in the `.mcp.json` file in the project root directory.
+
+## Codex
+
+### Configuration (Only `stdio` and `http` are supported.)
+
+#### `stdio`
+- `command` (required): The command that starts the server.
+- `args` (optional): Arguments to pass to the server.
+- `env` (optional): Environment variables to set for the server.
+- `env_vars` (optional): Environment variables to allow and forward.
+- `cwd` (optional): Working directory to start the server from.
+
+```toml
+[mcp_servers.my_stdio]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+
+[mcp_servers.my_stdio.env]
+API_KEY = "your-key"
+```
+
+With forwarded host env vars.
+```toml
+[mcp_servers.my_stdio]
+command = "python"
+args = ["server.py"]
+env_vars = ["API_KEY", "DEBUG"]
+cwd = "/path/to/project"
+```
+#### `http`
+- `url` (required): The server address.
+- `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.
+- `http_headers` (optional): Map of header names to static values.
+- `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).
+```toml
+[mcp_servers.my_http]
+url = "https://example.com/mcp"
+bearer_token_env_var = "MY_API_TOKEN"
+http_headers = { "X-Custom-Header" = "custom-value" }
+env_http_headers = { "X-Api-Key" = "MY_API_KEY_ENV" }
+```
+
+### Support for different modes (user, project)
+#### User
+- add it to the global `~/.codex/config.toml` file.
+
+#### Project specific
+- add it in `.codex/config.toml` file in the project's root directory.
+
+## Gemini
+Supports all 3 transports.
+### `stdio`
+- We can have arguments and env variables as inputs when executing the command.
+- `args` and `env` are optional.
+- No `type` attribute like Claude for `stdio`. If there is no type, we can infer that it must be `stdio` since the rest have it.
+```json
+
+{
+  "mcpServers": {
+    "serverName": {
+      "command": "path/to/server",
+      "args": ["--arg1", "value1"],
+      "env": {
+        "API_KEY": "$MY_API_TOKEN"
+      },
+      "cwd": "./server-directory"
+    }
+  }
+}
+```
+
+### `http`
+- We don't pass `env` inputs. Notice the type is set here like Claude. 
+- `headers` is optional. 
+- EXACTLY same as Claude `http`.
+```json
+{
+  "mcpServers": {
+    "weather-api": {
+      "type": "http",
+      "url": "https://api.weather.com/mcp",
+      "headers": {
+        "Authorization": "Bearer token"
+      }
+    }
+  }
+}
+```
+
+### `sse`
+- similar with `http` format. 
+- EXACT with Claude `sse` format.
+```json
+{
+  "mcpServers": {
+	"private-api": {
+	  "type": "sse",
+	  "url": "https://api.company.com/sse",
+	  "headers": {
+		"X-API-Key": "your-key-here"
+		}
+	}
+  }
+}
+```
+
+### Support for different modes (user, project)
+
+#### User
+- stored in `~/.gemini/settings.json`.
+
+#### Project specific
+- add it in the `.gemini/settings.json` file in the project root directory.
+
+
+
+## Cursor
+
+Supports all 3 transports. There is no `type` attribute for all 3. Here are the structures:
+
+#### `stdio`
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "mcp-server"],
+      "env": {
+        "API_KEY": "value"
+      }
+    }
+  }
+}
+```
+
+#### `http` / `sse` 
+```json
+// MCP server using HTTP or SSE - runs on a server
+{
+  "mcpServers": {
+    "server-name": {
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "API_KEY": "value"
+      }
+    }
+  }
+}
+```
+
+
+### Support for different modes (user, project)
+
+#### User
+- stored in `~/.cursor/mcp.json`.
+
+#### Project specific
+- add it in the `.cursor/mcp.json` file in the project root directory.
+
+
+
+
+# Skills management (ONLY Fetching support needed for now)
+## Claude
+- To get user skills, fetch all `~/.claude/skills/<skill-name>/SKILL.md`.
+- To get project skills, fetch from `.claude/skills/<skill-name>/SKILL.md`. 
+- To get plugin skills:
+	- Find all the enabled plugins in `~/.claude/settings.json`. 
+	```json
+	{
+	  "apiKeyHelper": "...",
+	  "enabledPlugins": {
+		"example-skills@anthropic-agent-skills": true
+	  },
+	  ...
+	}
+	```
+	- Then go to `~/.claude/plugins/installed_plugins.json` file to find where the plugin is installed. 
+	```json
+	{
+	  "version": 2,
+	  "plugins": {
+	    "example-skills@anthropic-agent-skills": [
+	      {
+	        "scope": "user",
+	        "installPath": "C:\\Users\\OMEN6\\.claude\\plugins\\cache\\anthropic-agent-skills\\example-skills\\3d5951151859",
+	        "version": "3d5951151859",
+	        "installedAt": "2026-03-03T12:52:08.024Z",
+	        "lastUpdated": "2026-03-03T12:52:08.024Z",
+	        "gitCommitSha": "3d59511518591fa82e6cfcf0438d68dd5dad3e76"
+	      }
+	    ]
+	  }
+	}
+	```
+	- Then go the `installPath` directory. If there is a `skills` folder there, go to each of the skills in `<install-path>/skills/<skill-name>/SKILL.md`.
+
+Then, parse the name and description of the skills from the md for every `SKILL.md`.
+
+- The command for invoking skills is `/<skill-name>` . 
+
+- Whenever a skill is from a plugin, doing `/skill-name` should automatically be updated with `/plugin-name:skill-name`. This is because plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
+
+I have attached the first initial contents of a sample `SKILL.md` file below.
+
+```md
+---
+
+name: mcp-builder
+
+description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
+
+license: Complete terms in LICENSE.txt
+
+---
+```
+## Codex
+
+
+Codex reads skills from repository, user, admin, and system locations.
+
+
+| Skill Scope | Location                                                                                                | Suggested use                                                                                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REPO`      | `$CWD/.agents/skills`  <br>Current working directory: where you launch Codex.                           | If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module.                              |
+| `REPO`      | ` $CWD/../.agents/skills`  <br>A folder above CWD when you launch Codex inside a Git repository.        | If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder.                                                                       |
+| `REPO`      | `$REPO_ROOT/.agents/skills`  <br>The topmost root folder when you launch Codex inside a Git repository. | If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository. |
+| `USER`      | `$HOME/.agents/skills`  <br>Any skills checked into the user’s personal folder.                         | Use to curate skills relevant to a user that apply to any repository the user may work in.                                                                                                           |
+| `ADMIN`     | `/etc/codex/skills`  <br>Any skills checked into the machine or container in a shared, system location. | Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine.                                                                                     |
+| `SYSTEM`    | `~/.codex/skills/.system`                                                                               | Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex.                                                                   |
+
+Then, parse the name and description of the skills from the md for every `SKILL.md`.
+
+- The command for invoking skills is `$<skill-name>`
+## Gemini
+- Gets all skills from `~/.gemini/skills`, `~/.agents/skills`, `.gemini/skills`, `.agents/skills`
+- command for invoking skills is same as Claude.
+
+
+## Cursor
+[Skill directories](https://cursor.com/docs/skills?utm_source=chatgpt.com#skill-directories)
+Skills are automatically loaded from these locations:
+
+|Location|Scope|
+|---|---|
+|`.agents/skills/`|Project-level|
+|`.cursor/skills/`|Project-level|
+|`~/.cursor/skills/`|User-level (global)|
+Then, parse the name and description of the skills from the md for every `SKILL.md`.
+
+- command for invoking skills is same as Claude.

docs/backend/llm-unifier-helper.md

@@ -0,0 +1,461 @@
+# How each session processes sessions
+- The way each session processes the sessions is already setup in `server/src/modules/providers`. Port over the existing logic to the new classes if possible. 
+
+# How to start, resume, and stop a session
+
+## Claude
+A new session is created by calling `query({ prompt, options })` which yields an async stream of SDK messages.  The session ID can be provided explicitly by using `resume` option and passing the session id (`sdkOptions.resume = sessionId;`).
+
+https://platform.claude.com/docs/en/agent-sdk/typescript#types
+
+Session can be stopped midway using `queryInstance.interrupt()`
+ https://platform.claude.com/docs/en/agent-sdk/typescript#methods
+ 
+## Codex
+- Starting - `const thread = codex.startThread(threadOptions)`
+- Resuming - `codex.resumeThread(sessionId, threadOptions);`
+- Stop a session 
+	```
+	    // Execute with streaming
+
+    const streamedTurn = await thread.runStreamed(command, {
+
+      signal: abortController.signal
+
+    });
+	```
+### About Abort controllers
+- Think of `AbortController` as a **cancel button for async work**.
+- **Controller** = thing that sends the cancel command.
+- **Signal** = thing that receives or carries the cancel state
+
+```js
+const controller = new AbortController();
+
+fetch("https://api.example.com/data", {
+  signal: controller.signal
+})
+  .then(response => response.json())
+  .then(data => {
+    console.log("Finished:", data);
+  })
+  .catch(error => {
+    if (error.name === "AbortError") {
+      console.log("The request was cancelled");
+    } else {
+      console.error("Real error:", error);
+    }
+  });
+
+// Cancel it after 2 seconds
+setTimeout(() => {
+  controller.abort();
+}, 2000);
+```
+- `AbortController` does **not magically stop all JavaScript everywhere**. It only works if the API or function you are using actually supports cancellation via a signal. `fetch` does. Your own custom async functions can too, but you have to write that support yourself. In codex, the method `runStreamed` supports it as well.
+```js
+function wait(ms, { signal } = {}) {
+  return new Promise((resolve, reject) => {
+  // if signal was aborted EVEN BEFORE the function started, return back.
+  // This catches the case where someone did this first:
+  // controller.abort("Cancelled already");
+  // wait(5000, { signal: controller.signal });
+    if (signal?.aborted) {
+      reject(signal.reason); // it supports custom reasoning as well.
+      return;
+    }
+
+    const timeoutId = setTimeout(() => {
+      resolve("Done waiting");
+    }, ms);
+	
+	// when the signal.abort event is fired (when controller.abort() is called somewhere else), it sends an `abort` event.
+	// When we get this, remove the timeoutId
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeoutId);
+      reject(signal.reason);
+    });
+  });
+}
+
+
+// ---------------- USAGE --------------------
+const controller = new AbortController();
+
+wait(5000, { signal: controller.signal })
+  .then(result => {
+    console.log(result);
+  })
+  .catch(error => {
+    console.log("Cancelled:", error);
+  });
+
+setTimeout(() => {
+  controller.abort("User cancelled the wait");
+}, 1000);
+
+```
+
+
+## Gemini
+### Start
+
+spawn `gemini --prompt "actualprompt" --model "actual model", --output-format 'stream-json'`
+
+- Stream `json` output format send responses in terms of a series of `json` chunks. If we store it, we would use .`jsonl` format.
+- Allowed tools aren't needed as it's depreciated.
+```
+      --allowed-tools             [DEPRECATED: Use Policy Engine instead See
+                                  https://geminicli.com/docs/core/policy-engine] Tools that are allowed 
+                                  to run without confirmation     
+```
+
+- `--prompt` allows us to run just one prompt in headless mode. It will automatically trust the workspace directory so it won't ask us whether we trust the workspace or not.
+
+### Stop/Abort a session
+```js
+try {
+	geminiProc.kill('SIGTERM'); // gracefully terminates the process. It ASKS the process to shut down cleanly. The process can catch it, save state, close files, and exit
+	setTimeout(() => {
+			geminiProc.kill('SIGKILL'); // kills it immediately
+		}
+	}, 2000); // Wait 2 seconds before force kill
+
+	return true;
+} catch (error) {
+	return false;
+}
+```
+
+### resume
+- spawn `gemini <the above formats> --resume <sessionId>`
+
+### To receive a response
+```
+child.stdout.on('data', (chunk) => {
+	const text = chunk.toString();
+	...
+})
+
+child.stderr.on('data', (chunk) => {
+  const text = chunk.toString();
+  ...
+}
+```
+
+## Cursor
+### Start
+- spawn `cursor-agent --print --trust --output-format 'stream-json' <actual-prompt'>`
+This won't be able to run shell commands like `git init`. To be able to run those, `--yolo` must be passed.
+
+### Resume
+- spawn `cursor-agent <above commands> --resume <sessionID>`
+
+### abort
+- same approach as gemini.
+
+
+# How to fetch (list the model types supported for each model...find out if there is an easy way to fetch automatically from the files)
+
+## Claude
+
+`query.supportedModels()` returns `ModelInfo[]`.
+```ts
+/**
+ * Information about an available model.
+ */
+export declare type ModelInfo = {
+    /**
+     * Model identifier to use in API calls
+     */
+    value: string;
+    /**
+     * Human-readable display name
+     */
+    displayName: string;
+    /**
+     * Description of the model's capabilities
+     */
+    description: string;
+    /**
+     * Whether this model supports effort levels
+     */
+    supportsEffort?: boolean;
+    /**
+     * Available effort levels for this model
+     */
+    supportedEffortLevels?: ('low' | 'medium' | 'high' | 'max')[];
+    /**
+     * Whether this model supports adaptive thinking (Claude decides when and how much to think)
+     */
+    supportsAdaptiveThinking?: boolean;
+};
+```
+
+```
+supported models = [
+  {
+    value: 'default',
+    displayName: 'Default (recommended)',
+    description: 'Use the default model (currently Sonnet 4.6) · $3/$15 per Mtok',
+    supportsEffort: true,
+    supportedEffortLevels: [ 'low', 'medium', 'high', 'max' ],
+    supportsAdaptiveThinking: true
+  },
+  {
+    value: 'sonnet[1m]',
+    displayName: 'Sonnet (1M context)',
+    description: 'Sonnet 4.6 for long sessions · $6/$22.50 per Mtok',
+    supportsEffort: true,
+    supportedEffortLevels: [ 'low', 'medium', 'high', 'max' ],
+    supportsAdaptiveThinking: true
+  },
+  {
+    value: 'opus',
+    displayName: 'Opus',
+    description: 'Opus 4.6 · Most capable for complex work · $5/$25 per Mtok',
+    supportsEffort: true,
+    supportedEffortLevels: [ 'low', 'medium', 'high', 'max' ],
+    supportsAdaptiveThinking: true
+  },
+  {
+    value: 'opus[1m]',
+    displayName: 'Opus (1M context)',
+    description: 'Opus 4.6 for long sessions · $10/$37.50 per Mtok',
+    supportsEffort: true,
+    supportedEffortLevels: [ 'low', 'medium', 'high', 'max' ],
+    supportsAdaptiveThinking: true
+  },
+  {
+    value: 'haiku',
+    displayName: 'Haiku',
+    description: 'Haiku 4.5 · Fastest for quick answers · $1/$5 per Mtok'
+  },
+  {
+    value: 'sonnet',
+    displayName: 'sonnet',
+    description: 'Custom model',
+    supportsEffort: true,
+    supportedEffortLevels: [ 'low', 'medium', 'high', 'max' ],
+    supportsAdaptiveThinking: true
+  }
+]
+```
+
+## Codex
+
+- Found in `.codex/models_cache.json`. It's in the `models` attribute. 
+```json
+{
+	...,
+	"models": [
+		    {
+      "slug": "gpt-5.4",
+      "display_name": "gpt-5.4",
+      "description": "Latest frontier agentic coding model.",
+      "default_reasoning_level": "medium",
+      "supported_reasoning_levels": [
+        {
+          "effort": "low",
+          "description": "Fast responses with lighter reasoning"
+        },
+        {
+          "effort": "medium",
+          "description": "Balances speed and reasoning depth for everyday tasks"
+        },
+        {
+          "effort": "high",
+          "description": "Greater reasoning depth for complex problems"
+        },
+        {
+          "effort": "xhigh",
+          "description": "Extra high reasoning depth for complex problems"
+        }
+      ],
+      "shell_type": "shell_command",
+      "visibility": "list",
+      "supported_in_api": true,
+      "priority": 1,
+      "availability_nux": null,
+      "upgrade": null,
+      "base_instructions": "...",
+      "model_messages": {
+        "instructions_template": "...",
+        "instructions_variables": {
+          "personality_default": "",
+          "personality_friendly": "..."
+        }
+      },
+      "supports_reasoning_summaries": true,
+      "default_reasoning_summary": "none",
+      "support_verbosity": true,
+      "default_verbosity": "low",
+      "apply_patch_tool_type": "freeform",
+      "web_search_tool_type": "text_and_image",
+      "truncation_policy": {
+        "mode": "tokens",
+        "limit": 10000
+      },
+      "supports_parallel_tool_calls": true,
+      "supports_image_detail_original": true,
+      "context_window": 272000,
+      "effective_context_window_percent": 95,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text",
+        "image"
+      ],
+      "supports_search_tool": true
+    },
+    {
+	    ...
+    }
+	]
+}
+```
+
+## Gemini
+- There is no way to automatically do this. So, use this 
+![[Pasted image 20260401124033.png]]
+
+The above is for free one. The below contains for all.
+
+```
+  OPTIONS: [
+    { value: 'gemini-3.1-pro-preview', label: 'Gemini 3.1 Pro Preview' },
+    { value: 'gemini-3-pro-preview', label: 'Gemini 3 Pro Preview' },
+    { value: 'gemini-3-flash-preview', label: 'Gemini 3 Flash Preview' },
+    { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash' },
+    { value: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro' },
+    { value: 'gemini-2.0-flash-lite', label: 'Gemini 2.0 Flash Lite' },
+    { value: 'gemini-2.0-flash', label: 'Gemini 2.0 Flash' },
+    { value: 'gemini-2.0-pro-exp', label: 'Gemini 2.0 Pro Experimental' },
+    { value: 'gemini-2.0-flash-thinking-exp', label: 'Gemini 2.0 Flash Thinking' }
+  ],
+```
+
+## Cursor
+- spawn `cursor-agent --list-models` and parse the ANSI output.
+```js
+function parseModelLine(line) {
+  const trimmed = line.trim();
+
+  if (!trimmed || trimmed === 'Available models' || trimmed.startsWith('Loading models') || trimmed.startsWith('Tip:')) {
+    return null;
+  }
+
+  const match = trimmed.match(/^(.+?)\s+-\s+(.+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const name = match[1].trim();
+  let description = match[2].trim();
+  const current = /\(current\)/i.test(description);
+  const defaultModel = /\(default\)/i.test(description);
+
+  description = description.replace(/\s*\((current|default)\)/gi, '').replace(/\s{2,}/g, ' ').trim();
+
+  return {
+    name,
+    description,
+    current,
+    default: defaultModel,
+  };
+}
+
+function parseModelsOutput(text) {
+  const models = [];
+
+  for (const line of stripAnsi(text).split(/\r?\n/)) {
+    const parsed = parseModelLine(line);
+    if (parsed) {
+      models.push(parsed);
+    }
+  }
+
+  return models;
+}
+
+
+// ------------ tHE ABOVE RETURNS ------------
+[
+  {
+    "name": "auto",
+    "description": "Auto",
+    "current": true,
+    "default": false
+  },
+  {
+    "name": "composer-2-fast",
+    "description": "Composer 2 Fast",
+    "current": false,
+    "default": true
+  },
+  {
+    "name": "composer-2",
+    "description": "Composer 2",
+    "current": false,
+    "default": false
+  },
+  ...
+]
+```
+
+# How to fetch session history
+- In the sessions table, there is a `jsonl_path` column. Go to directly that and parse the JSONLs from there. For `gemini`, the `jsonl_path` actually points to a gemini JSON file (since Gemini stores information in JSON rather than JSONL). DON'T use the LEGACY fetcher.
+
+# How to search conversations for each provider
+- Go to all the JSONL path directories from the database and use `@vscode/ripgrep` library for searching something.
+
+
+# How to change thinking modes for each model
+## Claude
+- Passed through `query` options through `effort: <'low' | 'medium' | 'high' | 'max'>`
+
+Default is high.
+
+## Codex
+- passed through `threadOptions`
+
+```
+
+type ModelReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+type ThreadOptions = {
+    model?: string;
+    sandboxMode?: SandboxMode;
+    workingDirectory?: string;
+    skipGitRepoCheck?: boolean;
+    modelReasoningEffort?: ModelReasoningEffort;
+    networkAccessEnabled?: boolean;
+    webSearchMode?: WebSearchMode;
+    webSearchEnabled?: boolean;
+    approvalPolicy?: ApprovalMode;
+    additionalDirectories?: string[];
+};
+
+
+```
+- `minimal` is supported only by `GPT-5`
+
+## Gemini
+- Not changeable. We can only select the different providers that have different thinking levels by themselves.
+
+## Cursor
+- Same as gemini. 
+
+
+# How to set/change models at start/after a session response respectively?
+## Claude
+- Initially can be set at start using `queryOptions.model`
+- Just resume the session by updating the model in `threadoptions`
+
+## Codex
+- Same as claude
+
+## Gemini
+- Just add the `--model <model-name>` property in the new spawned command. If there is something to resume, add `--resume <sessionID>`
+## Cursor
+- Just add the `--model <model-name>` property in the new spawned command. If there is something to resume, add `--resume <sessionID>`. In other words, same as gemini.
+

docs/testing/llm-unifier-backend-testing.md

@@ -0,0 +1,41 @@
+# LLM Unifier Backend Testing Report
+
+Date: 2026-04-06
+
+## Scope
+This report validates the backend functionality checklist in `docs/backend/llm-unifier-helper.md`.
+
+## Test Files Added
+- `server/src/modules/llm/llm-unifier.providers.test.ts`
+- `server/src/modules/llm/llm-unifier.sessions.test.ts`
+
+Each test case includes an inline comment describing which helper requirement it covers.
+
+## Command Used
+```powershell
+$env:TSX_TSCONFIG_PATH='server/tsconfig.json'; npm run test:server -- server/src/modules/llm/llm-unifier.providers.test.ts server/src/modules/llm/llm-unifier.sessions.test.ts
+```
+
+## Result
+- Total tests: 32
+- Passed: 32
+- Failed: 0
+
+## Requirement Coverage Matrix
+| Helper requirement | Coverage |
+| --- | --- |
+| Session processing logic orchestration | `llmSessionsService.synchronizeSessions aggregates processed counts and failures`, `llmSessionsService.synchronizeProvider honors fullRescan option` |
+| Start/resume behavior: Cursor | `cursor provider builds start/resume CLI invocations correctly` |
+| Start/resume behavior: Gemini | `gemini provider builds start/resume CLI invocations and exposes curated models` |
+| Start/resume/stop behavior: Codex (`startThread`, `resumeThread`, abort controller) | `codex provider start/resume use correct SDK thread methods and stop aborts signal` |
+| Claude helper behavior (effort mapping, runtime permission handler, event normalization) | `claude provider helper mappings match unifier contract` |
+| Model listing: Cursor (`--list-models` parsing) | `cursor provider parses model list output into normalized models` |
+| Model listing: Gemini (curated options) | `gemini provider builds start/resume CLI invocations and exposes curated models` |
+| Model listing: Codex (`~/.codex/models_cache.json`) | `codex provider reads models_cache.json and maps model metadata` |
+| Runtime permission/thinking support constraints | `llmService rejects unsupported runtime permission and thinking mode combinations`, `providers enforce capability gates for model/thinking updates` |
+| Thinking mode + model preference persistence across launches | `codex provider applies saved model/thinking preferences on subsequent launch` |
+| Session history from DB `jsonl_path` (JSONL + Gemini JSON), no legacy fetcher path | `llmSessionsService.getSessionHistory parses JSONL and Gemini JSON correctly` |
+| Session artifact deletion using processor path | `llmSessionsService.deleteSessionArtifacts validates ids and deletes disk/db artifacts` |
+| Session rename/update path | `llmSessionsService.updateSessionCustomName validates existence before updating` |
+| Conversation search over indexed transcript paths with provider/case filters | `conversationSearchService searches indexed transcripts with provider and case filters` |
+

docs/testing/llm-unifier-helper-2-backend-testing.md

@@ -0,0 +1,56 @@
+# LLM Unifier Helper-2 Backend Testing Report
+
+Date: 2026-04-06
+
+## Scope
+This report validates every backend functionality listed in:
+- `docs/backend/llm-unifier-helper-2.md`
+
+All test cases include inline comments that describe which helper-2 requirement they cover.
+
+## Test Files
+- `server/src/modules/llm/llm-unifier.providers.test.ts`
+- `server/src/modules/llm/llm-unifier.sessions.test.ts`
+- `server/src/modules/llm/llm-unifier.images.test.ts`
+- `server/src/modules/llm/llm-unifier.mcp.test.ts`
+- `server/src/modules/llm/llm-unifier.skills.test.ts`
+
+## package.json Scripts
+- `test:server` now includes the full unifier suite.
+- Added `test:server:llm-unifier-2` for running only helper-2 unifier coverage.
+
+## Commands Used
+```powershell
+npm run typecheck:server
+npm run test:server:llm-unifier-2
+npm run test:server
+```
+
+## Results
+- `typecheck:server`: pass
+- `test:server:llm-unifier-2`: pass (`30/30`)
+- `test:server`: pass (`30/30`)
+
+## Requirement Coverage Matrix
+| Helper-2 requirement | Test coverage |
+| --- | --- |
+| Universal image upload into `.cloudcli/assets` | `llmAssetsService stores uploaded images in .cloudcli/assets` |
+| Image upload validation for supported image mime types | `llmAssetsService rejects unsupported image mime types` |
+| Claude image prompt as content blocks with base64 images | `claude provider builds async prompt payload with base64 image blocks` |
+| Codex image prompt via `local_image` entries | `codex provider sends local_image prompt items when image paths are provided` |
+| Gemini/Cursor image handling by appending image path array to prompt | `gemini and cursor providers append image path arrays to prompts` |
+| Start payload imagePaths validation | `llmService rejects invalid imagePaths payloads before provider execution` |
+| MCP list grouped by User/Local/Project | `llmMcpService handles claude MCP scopes/transports with file-backed persistence` |
+| MCP add/remove/update behavior backed by provider config files | `llmMcpService handles claude MCP scopes/transports with file-backed persistence`, `llmMcpService handles codex MCP TOML config and capability validation`, `llmMcpService handles gemini and cursor MCP JSON config formats` |
+| Claude MCP transports: stdio/http/sse and scopes: user/local/project | `llmMcpService handles claude MCP scopes/transports with file-backed persistence` |
+| Codex MCP transports: stdio/http and scopes: user/project | `llmMcpService handles codex MCP TOML config and capability validation` |
+| Gemini MCP transports: stdio/http/sse and scopes: user/project | `llmMcpService handles gemini and cursor MCP JSON config formats` |
+| Cursor MCP transports: stdio/http/sse and scopes: user/project | `llmMcpService handles gemini and cursor MCP JSON config formats` |
+| Global MCP adder supports only `http` and `stdio` and applies to all providers | `llmMcpService global adder writes to all providers and rejects unsupported transports` |
+| MCP run/connectivity checks (stdio and http) | `llmMcpService runProviderServer probes stdio and http MCP servers` |
+| Claude skills fetch (user/project/plugin) and plugin namespacing | `llmSkillsService lists claude user/project/plugin skills with proper invocation names` |
+| Codex skills fetch (repo/user/admin/system path model; tested repo/user/system paths) and `$` invocation | `llmSkillsService lists codex skills from repo/user/system locations with dollar invocation` |
+| Gemini skills fetch from documented directories and `/` invocation | `llmSkillsService lists gemini skills from documented directories` |
+| Cursor skills fetch from documented directories and `/` invocation | `llmSkillsService lists cursor skills from documented directories` |
+| Existing unifier provider/session baseline behaviors remain passing | `llm-unifier.providers.test.ts`, `llm-unifier.sessions.test.ts` full suite |
+

package-lock.json

@@ -24,6 +24,7 @@
         "@openai/codex-sdk": "^0.101.0",
         "@replit/codemirror-minimap": "^0.5.2",
         "@tailwindcss/typography": "^0.5.16",
+        "@types/multer": "^2.1.0",
         "@uiw/react-codemirror": "^4.23.13",
         "@xterm/addon-clipboard": "^0.1.0",
         "@xterm/addon-fit": "^0.10.0",
@@ -77,9 +78,17 @@
         "@commitlint/config-conventional": "^20.4.3",
         "@eslint/js": "^9.39.3",
         "@release-it/conventional-changelog": "^10.0.5",
+        "@types/bcrypt": "^6.0.0",
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/cors": "^2.8.19",
+        "@types/cross-spawn": "^6.0.6",
+        "@types/express": "^5.0.3",
+        "@types/jsonwebtoken": "^9.0.10",
         "@types/node": "^22.19.7",
         "@types/react": "^18.2.43",
         "@types/react-dom": "^18.2.17",
+        "@types/web-push": "^3.6.4",
+        "@types/ws": "^8.18.1",
         "@vitejs/plugin-react": "^4.6.0",
         "auto-changelog": "^2.5.0",
         "autoprefixer": "^10.4.16",
@@ -99,6 +108,8 @@
         "release-it": "^19.0.5",
         "sharp": "^0.34.2",
         "tailwindcss": "^3.4.0",
+        "tsc-alias": "^1.8.16",
+        "tsx": "^4.20.6",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.56.1",
         "vite": "^7.0.4"
@@ -3732,6 +3743,65 @@
         "@babel/types": "^7.20.7"
       }
     },
+    "node_modules/@types/bcrypt": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@types/bcrypt/-/bcrypt-6.0.0.tgz",
+      "integrity": "sha512-/oJGukuH3D2+D+3H4JWLaAsJ/ji86dhRidzZ/Od7H/i8g+aCmvkeCc6Ni/f9uxGLSQVCRZkX2/lqEFG2BvWtlQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/better-sqlite3": {
+      "version": "7.6.13",
+      "resolved": "https://registry.npmjs.org/@types/better-sqlite3/-/better-sqlite3-7.6.13.tgz",
+      "integrity": "sha512-NMv9ASNARoKksWtsq/SHakpYAYnhBrQgGD8zkLYk/jaK8jUGn08CfEdTRgYhMypUQAfzSP8W6gNLe0q19/t4VA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/body-parser": {
+      "version": "1.19.6",
+      "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
+      "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/connect": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/connect": {
+      "version": "3.4.38",
+      "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
+      "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/cors": {
+      "version": "2.8.19",
+      "resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz",
+      "integrity": "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/cross-spawn": {
+      "version": "6.0.6",
+      "resolved": "https://registry.npmjs.org/@types/cross-spawn/-/cross-spawn-6.0.6.tgz",
+      "integrity": "sha512-fXRhhUkG4H3TQk5dBhQ7m/JDdSNHKwR2BBia62lhwEIq9xGiQKLxd6LymNhn47SjXhsUEPmxi+PKw2OkW4LLjA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/debug": {
       "version": "4.1.12",
       "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
@@ -3756,6 +3826,29 @@
         "@types/estree": "*"
       }
     },
+    "node_modules/@types/express": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
+      "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/body-parser": "*",
+        "@types/express-serve-static-core": "^5.0.0",
+        "@types/serve-static": "^2"
+      }
+    },
+    "node_modules/@types/express-serve-static-core": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz",
+      "integrity": "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "@types/qs": "*",
+        "@types/range-parser": "*",
+        "@types/send": "*"
+      }
+    },
     "node_modules/@types/hast": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
@@ -3765,6 +3858,12 @@
         "@types/unist": "*"
       }
     },
+    "node_modules/@types/http-errors": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
+      "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
+      "license": "MIT"
+    },
     "node_modules/@types/json-schema": {
       "version": "7.0.15",
       "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
@@ -3772,6 +3871,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/jsonwebtoken": {
+      "version": "9.0.10",
+      "resolved": "https://registry.npmjs.org/@types/jsonwebtoken/-/jsonwebtoken-9.0.10.tgz",
+      "integrity": "sha512-asx5hIG9Qmf/1oStypjanR7iKTv0gXQ1Ov/jfrX6kS/EO0OFni8orbmGCn0672NHR3kXHwpAwR+B368ZGN/2rA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/ms": "*",
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/katex": {
       "version": "0.16.7",
       "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.7.tgz",
@@ -3793,11 +3903,19 @@
       "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
       "license": "MIT"
     },
+    "node_modules/@types/multer": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/multer/-/multer-2.1.0.tgz",
+      "integrity": "sha512-zYZb0+nJhOHtPpGDb3vqPjwpdeGlGC157VpkqNQL+UU2qwoacoQ7MpsAmUptI/0Oa127X32JzWDqQVEXp2RcIA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/express": "*"
+      }
+    },
     "node_modules/@types/node": {
       "version": "22.19.7",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.7.tgz",
       "integrity": "sha512-MciR4AKGHWl7xwxkBa6xUGxQJ4VBOmPTF7sL+iGzuahOFaO0jHCsuEfS80pan1ef4gWId1oWOweIhrDEYLuaOw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "undici-types": "~6.21.0"
@@ -3823,6 +3941,18 @@
       "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
       "license": "MIT"
     },
+    "node_modules/@types/qs": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.0.tgz",
+      "integrity": "sha512-JawvT8iBVWpzTrz3EGw9BTQFg3BQNmwERdKE22vlTxawwtbyUSlMppvZYKLZzB5zgACXdXxbD3m1bXaMqP/9ow==",
+      "license": "MIT"
+    },
+    "node_modules/@types/range-parser": {
+      "version": "1.2.7",
+      "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
+      "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
+      "license": "MIT"
+    },
     "node_modules/@types/react": {
       "version": "18.3.23",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.23.tgz",
@@ -3843,12 +3973,51 @@
         "@types/react": "^18.0.0"
       }
     },
+    "node_modules/@types/send": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
+      "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/serve-static": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz",
+      "integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/http-errors": "*",
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/unist": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
       "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==",
       "license": "MIT"
     },
+    "node_modules/@types/web-push": {
+      "version": "3.6.4",
+      "resolved": "https://registry.npmjs.org/@types/web-push/-/web-push-3.6.4.tgz",
+      "integrity": "sha512-GnJmSr40H3RAnj0s34FNTcJi1hmWFV5KXugE0mYWnYhgTAHLJ/dJKAwDmvPJYMke0RplY2XE9LnM4hqSqKIjhQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@typescript-eslint/eslint-plugin": {
       "version": "8.56.1",
       "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.56.1.tgz",
@@ -4816,6 +4985,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/array-union": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz",
+      "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/array.prototype.findlast": {
       "version": "1.2.5",
       "resolved": "https://registry.npmjs.org/array.prototype.findlast/-/array.prototype.findlast-1.2.5.tgz",
@@ -6674,6 +6853,19 @@
       "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==",
       "license": "Apache-2.0"
     },
+    "node_modules/dir-glob": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz",
+      "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-type": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/dlv": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz",
@@ -8520,6 +8712,27 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/globby": {
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz",
+      "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "array-union": "^2.1.0",
+        "dir-glob": "^3.0.1",
+        "fast-glob": "^3.2.9",
+        "ignore": "^5.2.0",
+        "merge2": "^1.4.1",
+        "slash": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -12027,6 +12240,20 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
+    "node_modules/mylas": {
+      "version": "2.1.14",
+      "resolved": "https://registry.npmjs.org/mylas/-/mylas-2.1.14.tgz",
+      "integrity": "sha512-BzQguy9W9NJgoVn2mRWzbFrFWWztGCcng2QI9+41frfk+Athwgx3qhqhvStz7ExeUUu7Kzw427sNzHpEZNINog==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/raouldeheer"
+      }
+    },
     "node_modules/mz": {
       "version": "2.7.0",
       "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz",
@@ -12990,6 +13217,16 @@
       "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
       "license": "MIT"
     },
+    "node_modules/path-type": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
+      "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/pathe": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
@@ -13052,6 +13289,19 @@
         "pathe": "^2.0.3"
       }
     },
+    "node_modules/plimit-lit": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/plimit-lit/-/plimit-lit-1.6.1.tgz",
+      "integrity": "sha512-B7+VDyb8Tl6oMJT9oSO2CW8XC/T4UcJGrwOVoNGwOQsQYhlpfajmrMj5xeejqaASq3V/EqThyOeATEOMuSEXiA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "queue-lit": "^1.5.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/possible-typed-array-names": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz",
@@ -13413,6 +13663,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/queue-lit": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/queue-lit/-/queue-lit-1.5.2.tgz",
+      "integrity": "sha512-tLc36IOPeMAubu8BkW8YDBV+WyIgKlYU7zUNs0J5Vk9skSZ4JfGlPOqplP0aHdfv7HL0B2Pg6nwiq60Qc6M2Hw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -15174,6 +15434,16 @@
         "is-arrayish": "^0.3.1"
       }
     },
+    "node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/slice-ansi": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-8.0.0.tgz",
@@ -16480,12 +16750,599 @@
       "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==",
       "license": "Apache-2.0"
     },
+    "node_modules/tsc-alias": {
+      "version": "1.8.16",
+      "resolved": "https://registry.npmjs.org/tsc-alias/-/tsc-alias-1.8.16.tgz",
+      "integrity": "sha512-QjCyu55NFyRSBAl6+MTFwplpFcnm2Pq01rR/uxfqJoLMm6X3O14KEGtaSDZpJYaE1bJBGDjD0eSuiIWPe2T58g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chokidar": "^3.5.3",
+        "commander": "^9.0.0",
+        "get-tsconfig": "^4.10.0",
+        "globby": "^11.0.4",
+        "mylas": "^2.1.9",
+        "normalize-path": "^3.0.0",
+        "plimit-lit": "^1.2.6"
+      },
+      "bin": {
+        "tsc-alias": "dist/bin/index.js"
+      },
+      "engines": {
+        "node": ">=16.20.2"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/chokidar": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
+      "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "anymatch": "~3.1.2",
+        "braces": "~3.0.2",
+        "glob-parent": "~5.1.2",
+        "is-binary-path": "~2.1.0",
+        "is-glob": "~4.0.1",
+        "normalize-path": "~3.0.0",
+        "readdirp": "~3.6.0"
+      },
+      "engines": {
+        "node": ">= 8.10.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/commander": {
+      "version": "9.5.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz",
+      "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || >=14"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/glob-parent": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/readdirp": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz",
+      "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "picomatch": "^2.2.1"
+      },
+      "engines": {
+        "node": ">=8.10.0"
+      }
+    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
       "license": "0BSD"
     },
+    "node_modules/tsx": {
+      "version": "4.21.0",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
+      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.27.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",
+      "integrity": "sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.3.tgz",
+      "integrity": "sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.3.tgz",
+      "integrity": "sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.3.tgz",
+      "integrity": "sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.3.tgz",
+      "integrity": "sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.3.tgz",
+      "integrity": "sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.3.tgz",
+      "integrity": "sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.3.tgz",
+      "integrity": "sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.3.tgz",
+      "integrity": "sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.3.tgz",
+      "integrity": "sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.3.tgz",
+      "integrity": "sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.3.tgz",
+      "integrity": "sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.3.tgz",
+      "integrity": "sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.3.tgz",
+      "integrity": "sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.3.tgz",
+      "integrity": "sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.3.tgz",
+      "integrity": "sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.3.tgz",
+      "integrity": "sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.3.tgz",
+      "integrity": "sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.3.tgz",
+      "integrity": "sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.3.tgz",
+      "integrity": "sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.3.tgz",
+      "integrity": "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/esbuild": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
+      "integrity": "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.3",
+        "@esbuild/android-arm": "0.27.3",
+        "@esbuild/android-arm64": "0.27.3",
+        "@esbuild/android-x64": "0.27.3",
+        "@esbuild/darwin-arm64": "0.27.3",
+        "@esbuild/darwin-x64": "0.27.3",
+        "@esbuild/freebsd-arm64": "0.27.3",
+        "@esbuild/freebsd-x64": "0.27.3",
+        "@esbuild/linux-arm": "0.27.3",
+        "@esbuild/linux-arm64": "0.27.3",
+        "@esbuild/linux-ia32": "0.27.3",
+        "@esbuild/linux-loong64": "0.27.3",
+        "@esbuild/linux-mips64el": "0.27.3",
+        "@esbuild/linux-ppc64": "0.27.3",
+        "@esbuild/linux-riscv64": "0.27.3",
+        "@esbuild/linux-s390x": "0.27.3",
+        "@esbuild/linux-x64": "0.27.3",
+        "@esbuild/netbsd-arm64": "0.27.3",
+        "@esbuild/netbsd-x64": "0.27.3",
+        "@esbuild/openbsd-arm64": "0.27.3",
+        "@esbuild/openbsd-x64": "0.27.3",
+        "@esbuild/openharmony-arm64": "0.27.3",
+        "@esbuild/sunos-x64": "0.27.3",
+        "@esbuild/win32-arm64": "0.27.3",
+        "@esbuild/win32-ia32": "0.27.3",
+        "@esbuild/win32-x64": "0.27.3"
+      }
+    },
     "node_modules/tunnel-agent": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
@@ -16727,7 +17584,6 @@
       "version": "6.21.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
       "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/unified": {

package.json

@@ -3,7 +3,7 @@
   "version": "1.26.3",
   "description": "A web-based UI for Claude Code CLI",
   "type": "module",
-  "main": "server/index.js",
+  "main": "server/start.js",
   "bin": {
     "claude-code-ui": "server/cli.js",
     "cloudcli": "server/cli.js"
@@ -25,16 +25,23 @@
   },
   "scripts": {
     "dev": "concurrently --kill-others \"npm run server\" \"npm run client\"",
-    "server": "node server/index.js",
+    "server:dev": "tsx watch --tsconfig server/tsconfig.json server/src/bootstrap.ts",
+    "server": "tsx --tsconfig server/tsconfig.json server/src/bootstrap.ts",
+    "server:build": "tsc -p server/tsconfig.json && tsc-alias -p server/tsconfig.json",
+    "server:start": "node server/start.js",
     "client": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:client": "tsc --noEmit -p tsconfig.json",
+    "typecheck:server": "tsc --noEmit -p server/tsconfig.json",
+    "test:server": "tsx --tsconfig server/tsconfig.json --test server/src/modules/ai-runtime/tests/*.test.ts",
+    "verify:server": "npm run typecheck:server && npm run test:server && npm run server:build",
+    "typecheck": "npm run typecheck:client && npm run typecheck:server",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "start": "npm run build && npm run server",
+    "start": "npm run build && npm run server:build && npm run server:start",
     "release": "./release.sh",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && npm run server:build",
     "postinstall": "node scripts/fix-node-pty.js",
     "prepare": "husky"
   },
@@ -62,6 +69,7 @@
     "@openai/codex-sdk": "^0.101.0",
     "@replit/codemirror-minimap": "^0.5.2",
     "@tailwindcss/typography": "^0.5.16",
+    "@types/multer": "^2.1.0",
     "@uiw/react-codemirror": "^4.23.13",
     "@xterm/addon-clipboard": "^0.1.0",
     "@xterm/addon-fit": "^0.10.0",
@@ -111,9 +119,17 @@
     "@commitlint/config-conventional": "^20.4.3",
     "@eslint/js": "^9.39.3",
     "@release-it/conventional-changelog": "^10.0.5",
+    "@types/bcrypt": "^6.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/cors": "^2.8.19",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/express": "^5.0.3",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^22.19.7",
     "@types/react": "^18.2.43",
     "@types/react-dom": "^18.2.17",
+    "@types/web-push": "^3.6.4",
+    "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^4.6.0",
     "auto-changelog": "^2.5.0",
     "autoprefixer": "^10.4.16",
@@ -133,6 +149,8 @@
     "release-it": "^19.0.5",
     "sharp": "^0.34.2",
     "tailwindcss": "^3.4.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
     "vite": "^7.0.4"

scripts/generate-backend-inventory.mjs

@@ -0,0 +1,657 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..');
+const serverRoot = path.join(projectRoot, 'server');
+const clientRoot = path.join(projectRoot, 'src');
+const docsRoot = path.join(projectRoot, 'docs', 'backend');
+
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'];
+const routeDefinitionPattern = /\b(app|router)\.(get|post|put|delete|patch)\(\s*(['"`])(.+?)\3/g;
+const defaultImportPattern =
+  /^import\s+([A-Za-z0-9_$]+)(?:\s*,\s*\{[^}]+\})?\s+from\s+['"](.+?)['"];$/gm;
+const incomingRealtimePattern = /data\.type === '([^']+)'/g;
+const outgoingRealtimePattern = /type:\s*'([^']+)'/g;
+
+fs.mkdirSync(docsRoot, { recursive: true });
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function walkFiles(dirPath, files = []) {
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.name === 'dist' || entry.name === 'node_modules') {
+      continue;
+    }
+
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(fullPath, files);
+      continue;
+    }
+
+    files.push(fullPath);
+  }
+
+  return files;
+}
+
+function getLineNumber(content, index) {
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+
+function splitArgs(argumentSource) {
+  return argumentSource
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean);
+}
+
+function sanitizeObjectKey(key) {
+  return key
+    .replace(/^[\s{]+|[\s}]+$/g, '')
+    .replace(/=.*$/, '')
+    .replace(/:.+$/, '')
+    .replace(/\?/g, '')
+    .trim();
+}
+
+function collectObjectKeys(block, accessor) {
+  const keys = new Set();
+  const directPattern = new RegExp(`req\\.${accessor}\\.([A-Za-z0-9_]+)`, 'g');
+  const destructuringPattern = new RegExp(`\\{([^}]*)\\}\\s*=\\s*req\\.${accessor}`, 'gs');
+
+  for (const match of block.matchAll(directPattern)) {
+    keys.add(match[1]);
+  }
+
+  for (const match of block.matchAll(destructuringPattern)) {
+    for (const rawKey of match[1].split(',')) {
+      const key = sanitizeObjectKey(rawKey);
+      if (key) {
+        keys.add(key);
+      }
+    }
+  }
+
+  return [...keys].sort();
+}
+
+function normalizeJoinedPath(basePath, routePath) {
+  const safeBase = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  if (!routePath || routePath === '/') {
+    return safeBase || '/';
+  }
+
+  if (routePath === '*') {
+    return routePath;
+  }
+
+  const safeRoute = routePath.startsWith('/') ? routePath : `/${routePath}`;
+  return `${safeBase}${safeRoute}` || '/';
+}
+
+function getStaticSearchTokens(routePath) {
+  const cleaned = routePath.replace(/:[A-Za-z0-9_]+/g, '').replace(/\*/g, '');
+  const segments = cleaned.split('/').filter(Boolean);
+  const tokens = new Set();
+
+  if (cleaned && cleaned !== '/') {
+    tokens.add(cleaned.endsWith('/') ? cleaned : `${cleaned}`);
+  }
+
+  for (let index = segments.length; index >= 2; index -= 1) {
+    tokens.add(`/${segments.slice(0, index).join('/')}/`);
+  }
+
+  if (segments.length > 0) {
+    tokens.add(`/${segments.slice(0, 1).join('/')}/`);
+  }
+
+  return [...tokens].filter(Boolean);
+}
+
+function classifyTag(routePath) {
+  if (routePath === '*' || routePath === '/health' || routePath.startsWith('/api/system')) {
+    return 'System';
+  }
+
+  if (routePath.startsWith('/api/auth')) return 'Auth';
+  if (routePath.startsWith('/api/user')) return 'User';
+  if (routePath.startsWith('/api/settings')) return 'Settings';
+  if (routePath.startsWith('/api/git')) return 'Git';
+  if (routePath.startsWith('/api/taskmaster')) return 'TaskMaster';
+  if (routePath.startsWith('/api/plugins')) return 'Plugins';
+  if (routePath.startsWith('/api/agent')) return 'Agent';
+  if (routePath.startsWith('/api/commands')) return 'Commands';
+  if (routePath.startsWith('/api/mcp')) return 'MCP';
+  if (routePath.startsWith('/api/cli')) return 'CLI Auth';
+  if (
+    routePath.startsWith('/api/cursor') ||
+    routePath.startsWith('/api/codex') ||
+    routePath.startsWith('/api/gemini')
+  ) {
+    return 'Providers';
+  }
+
+  if (routePath.startsWith('/api/search') || routePath.includes('/sessions')) {
+    return 'Sessions';
+  }
+
+  if (routePath.includes('/files') || routePath.includes('/file') || routePath.includes('/upload')) {
+    return 'Files';
+  }
+
+  if (routePath.startsWith('/api/projects') || routePath.startsWith('/api/create-folder')) {
+    return 'Projects';
+  }
+
+  return 'Realtime';
+}
+
+function classifyPriority(tag, routePath) {
+  if (
+    tag === 'Agent' ||
+    tag === 'TaskMaster' ||
+    tag === 'Git' ||
+    routePath.startsWith('/api/projects') ||
+    routePath.startsWith('/api/search')
+  ) {
+    return 'high';
+  }
+
+  if (
+    tag === 'Providers' ||
+    tag === 'Commands' ||
+    tag === 'MCP' ||
+    tag === 'Plugins' ||
+    tag === 'Settings' ||
+    tag === 'Auth' ||
+    tag === 'User'
+  ) {
+    return 'medium';
+  }
+
+  return 'low';
+}
+
+function describePurpose(method, routePath) {
+  const verb = method.toUpperCase();
+
+  if (routePath === '/health') {
+    return 'Expose server health, timestamp, and install mode for diagnostics.';
+  }
+
+  if (routePath === '*') {
+    return 'Serve the React application fallback for non-API routes.';
+  }
+
+  if (routePath.startsWith('/api/system/update')) {
+    return 'Run the application update workflow on the host machine.';
+  }
+
+  if (routePath.startsWith('/api/auth/status')) return 'Report whether authentication is configured.';
+  if (routePath.startsWith('/api/auth/register')) return 'Create the first local user account.';
+  if (routePath.startsWith('/api/auth/login')) return 'Authenticate a local user and issue a token.';
+  if (routePath.startsWith('/api/auth/user')) return 'Return the currently authenticated user.';
+  if (routePath.startsWith('/api/auth/logout')) return 'Invalidate the current authenticated session.';
+
+  if (routePath.startsWith('/api/user/git-config')) return 'Read or update stored git identity settings.';
+  if (routePath.startsWith('/api/user/complete-onboarding')) return 'Mark onboarding as completed for the current user.';
+  if (routePath.startsWith('/api/user/onboarding-status')) return 'Return onboarding completion status for the current user.';
+
+  if (routePath.startsWith('/api/settings/api-keys')) return 'Manage local API keys used to access the backend.';
+  if (routePath.startsWith('/api/settings/credentials')) return 'Manage stored provider and GitHub credentials.';
+
+  if (routePath.startsWith('/api/projects/create-workspace')) {
+    return 'Create or register a workspace and optionally clone a GitHub repository into it.';
+  }
+
+  if (routePath.startsWith('/api/projects/clone-progress')) {
+    return 'Stream workspace cloning progress events to the frontend.';
+  }
+
+  if (routePath === '/api/projects') return 'List detected projects and workspaces.';
+  if (routePath.startsWith('/api/projects/create')) return 'Manually add a project path to the workspace list.';
+  if (routePath.startsWith('/api/projects/:projectName/sessions/:sessionId/token-usage')) {
+    return 'Report token usage for a stored provider session.';
+  }
+
+  if (routePath.includes('/sessions/:sessionId/messages')) {
+    return 'Return paginated messages for a stored session.';
+  }
+
+  if (routePath.includes('/sessions')) {
+    return 'List or manage sessions associated with a project or provider.';
+  }
+
+  if (routePath.includes('/files') || routePath.includes('/file')) {
+    return 'Read, write, create, rename, delete, or upload project files.';
+  }
+
+  if (routePath.startsWith('/api/search/conversations')) {
+    return 'Search conversation history across stored projects and stream results.';
+  }
+
+  if (routePath.startsWith('/api/browse-filesystem')) {
+    return 'Browse local directories so the UI can suggest workspace locations.';
+  }
+
+  if (routePath.startsWith('/api/create-folder')) {
+    return 'Create a new directory on the local filesystem.';
+  }
+
+  if (routePath.startsWith('/api/transcribe')) {
+    return 'Transcribe uploaded audio and optionally enhance the result for prompts or tasks.';
+  }
+
+  if (routePath.includes('/upload-images')) {
+    return 'Upload images for chat use and return browser-safe data URLs.';
+  }
+
+  if (routePath.startsWith('/api/git/status')) return 'Read git status information for a project.';
+  if (routePath.startsWith('/api/git/diff')) return 'Return git diff output for a project or file.';
+  if (routePath.startsWith('/api/git/file-with-diff')) return 'Return file content together with diff context.';
+  if (routePath.startsWith('/api/git/branches')) return 'List git branches for a project.';
+  if (routePath.startsWith('/api/git/commits')) return 'List recent commits for a project.';
+  if (routePath.startsWith('/api/git/commit-diff')) return 'Return diff details for a specific commit.';
+  if (routePath.startsWith('/api/git/remote-status')) return 'Report remote sync status for a project repository.';
+  if (routePath.startsWith('/api/git/generate-commit-message')) return 'Generate an AI-assisted commit message from the current diff.';
+
+  if (routePath.startsWith('/api/taskmaster')) {
+    return 'Manage TaskMaster detection, PRDs, tasks, templates, and automation for a project.';
+  }
+
+  if (routePath.startsWith('/api/commands')) {
+    return 'List, load, or execute slash commands available to the chat experience.';
+  }
+
+  if (routePath.startsWith('/api/mcp-utils')) {
+    return 'Return MCP helper information used by setup flows.';
+  }
+
+  if (routePath.startsWith('/api/mcp')) {
+    return 'Manage Claude MCP CLI and configuration state.';
+  }
+
+  if (routePath.startsWith('/api/cursor')) {
+    return 'Manage Cursor configuration, MCP settings, and stored sessions.';
+  }
+
+  if (routePath.startsWith('/api/codex')) {
+    return 'Manage Codex configuration, MCP settings, and stored sessions.';
+  }
+
+  if (routePath.startsWith('/api/gemini')) {
+    return 'Manage Gemini session history for the UI.';
+  }
+
+  if (routePath.startsWith('/api/cli')) {
+    return 'Report local authentication status for provider CLIs.';
+  }
+
+  if (routePath.startsWith('/api/plugins')) {
+    return 'List, install, update, serve, enable, or remove plugins.';
+  }
+
+  if (routePath.startsWith('/api/agent')) {
+    return 'Accept external agent jobs that run a provider against a local or cloned project.';
+  }
+
+  return `${verb} ${routePath} for backend runtime support.`;
+}
+
+function describeSuccessShape(block, transport) {
+  if (transport === 'sse' || block.includes('text/event-stream')) {
+    return 'Server-sent events stream with progress/result/error events.';
+  }
+
+  if (block.includes('res.sendFile')) {
+    return 'Static file or HTML response.';
+  }
+
+  if (block.includes('res.redirect')) {
+    return 'HTTP redirect response.';
+  }
+
+  if (block.includes('res.json({ success: true')) {
+    return 'JSON object with an explicit success flag and payload.';
+  }
+
+  if (block.includes('res.json({')) {
+    return 'Structured JSON object response.';
+  }
+
+  if (block.includes('res.json(')) {
+    return 'JSON payload returned directly from service logic.';
+  }
+
+  return 'Mixed response shape; inspect handler during refactor.';
+}
+
+function describeErrorShape(block, transport) {
+  if (transport === 'sse' || block.includes('text/event-stream')) {
+    return 'Streamed error event or JSON error fallback.';
+  }
+
+  if (block.includes("res.status(500).json({ error:")) {
+    return 'JSON object with error message and optional details.';
+  }
+
+  if (block.includes("res.status(400).json({ error:")) {
+    return 'JSON validation error response.';
+  }
+
+  if (block.includes('res.status(')) {
+    return 'JSON error response with HTTP status code.';
+  }
+
+  return 'Handler-specific error behavior.';
+}
+
+function describeSideEffects(method, routePath) {
+  const effects = [];
+
+  if (method !== 'get') {
+    effects.push('Mutates backend or external state.');
+  }
+
+  if (routePath.includes('/git')) effects.push('Touches git repositories or local git config.');
+  if (routePath.includes('/projects') || routePath.includes('/file') || routePath.includes('/files')) {
+    effects.push('Touches local workspace files or directories.');
+  }
+  if (routePath.includes('/agent')) effects.push('Invokes external AI providers and may modify project files.');
+  if (routePath.includes('/taskmaster')) effects.push('Reads or writes TaskMaster project assets.');
+  if (routePath.includes('/plugins')) effects.push('Installs, updates, or serves plugin assets/processes.');
+  if (routePath.includes('/settings') || routePath.includes('/auth') || routePath.includes('/credentials')) {
+    effects.push('Reads or writes local authentication or credential state.');
+  }
+  if (routePath.includes('/mcp')) effects.push('Reads or writes MCP CLI configuration.');
+  if (routePath.includes('/transcribe')) effects.push('Processes uploaded files and external model responses.');
+
+  return effects.length > 0 ? effects : ['Read-only backend query.'];
+}
+
+function collectFrontendConsumers(routePath, clientFiles) {
+  const tokens = getStaticSearchTokens(routePath);
+  const consumers = new Set();
+
+  for (const file of clientFiles) {
+    const content = readText(file);
+    if (tokens.some(token => token && content.includes(token))) {
+      consumers.add(toPosix(path.relative(projectRoot, file)));
+    }
+  }
+
+  return [...consumers].sort();
+}
+
+function detectTransport(block) {
+  if (block.includes('text/event-stream')) {
+    return 'sse';
+  }
+
+  return 'http';
+}
+
+function parseMounts(runtimeContent) {
+  const routeImports = new Map();
+
+  for (const match of runtimeContent.matchAll(defaultImportPattern)) {
+    if (match[2].includes('/routes/')) {
+      routeImports.set(match[1], match[2]);
+    }
+  }
+
+  const mounts = new Map();
+  const mountPattern = /app\.use\(\s*(['"`])([^'"`]+)\1\s*,\s*([^)]+?)\);/g;
+
+  for (const match of runtimeContent.matchAll(mountPattern)) {
+    const basePath = match[2];
+    const args = splitArgs(match[3]);
+    const routeVariable = args.at(-1);
+    if (!routeVariable || !routeImports.has(routeVariable)) {
+      continue;
+    }
+
+    mounts.set(routeVariable, {
+      basePath,
+      routeImport: routeImports.get(routeVariable),
+      authMode: args.includes('authenticateToken')
+        ? 'bearer_token'
+        : args.includes('validateExternalApiKey')
+          ? 'api_key_or_platform'
+          : 'public_or_optional_api_key',
+    });
+  }
+
+  return mounts;
+}
+
+function parseRoutes(filePath, fullPathPrefix, authMode, clientFiles) {
+  const content = readText(filePath);
+  const matches = [...content.matchAll(routeDefinitionPattern)];
+  const routes = [];
+
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index];
+    const nextMatch = matches[index + 1];
+    const routeMethod = match[2].toUpperCase();
+    const routePath = match[4];
+    const startIndex = match.index ?? 0;
+    const endIndex = nextMatch?.index ?? content.length;
+    const block = content.slice(startIndex, endIndex);
+    const declarationEnd = block.indexOf('=>');
+    const declarationSnippet = declarationEnd === -1 ? block : block.slice(0, declarationEnd);
+    const fullPath = fullPathPrefix
+      ? normalizeJoinedPath(fullPathPrefix, routePath)
+      : routePath;
+    const transport = detectTransport(block);
+    const tag = classifyTag(fullPath);
+    const pathParams = [...fullPath.matchAll(/:([A-Za-z0-9_]+)/g)].map(token => token[1]);
+    const queryParams = collectObjectKeys(block, 'query');
+    const bodyHints = collectObjectKeys(block, 'body');
+    const localAuthMode =
+      fullPath === '/health' ||
+      fullPath === '/api/auth/status' ||
+      fullPath === '/api/auth/register' ||
+      fullPath === '/api/auth/login' ||
+      fullPath === '*'
+        ? 'public'
+        : declarationSnippet.includes('authenticateToken')
+          ? 'bearer_token'
+          : declarationSnippet.includes('validateExternalApiKey')
+            ? 'api_key_or_platform'
+            : authMode;
+
+    routes.push({
+      transport,
+      method: routeMethod,
+      path: fullPath,
+      tag,
+      authMode: localAuthMode,
+      sourceFile: toPosix(path.relative(projectRoot, filePath)),
+      sourceLine: getLineNumber(content, startIndex),
+      purpose: describePurpose(routeMethod, fullPath),
+      consumerFiles: collectFrontendConsumers(fullPath, clientFiles),
+      inputs: {
+        pathParams,
+        queryParams,
+        bodyHints,
+      },
+      successShape: describeSuccessShape(block, transport),
+      errorShape: describeErrorShape(block, transport),
+      sideEffects: describeSideEffects(routeMethod.toLowerCase(), fullPath),
+      priority: classifyPriority(tag, fullPath),
+    });
+  }
+
+  return routes;
+}
+
+function parseRealtimeContracts(runtimeFile) {
+  const content = readText(runtimeFile);
+  const incoming = new Set();
+  const outgoing = new Set();
+
+  for (const match of content.matchAll(incomingRealtimePattern)) {
+    incoming.add(match[1]);
+  }
+
+  const websocketSectionIndex = content.indexOf("wss.on('connection'");
+  const websocketSection = websocketSectionIndex === -1 ? content : content.slice(websocketSectionIndex);
+
+  for (const match of websocketSection.matchAll(outgoingRealtimePattern)) {
+    outgoing.add(match[1]);
+  }
+
+  return {
+    incomingMessageTypes: [...incoming].sort(),
+    outgoingMessageTypes: [...outgoing].sort(),
+  };
+}
+
+function escapeCsv(value) {
+  const stringValue = Array.isArray(value) ? value.join('; ') : String(value ?? '');
+  const escaped = stringValue.replace(/"/g, '""');
+  return `"${escaped}"`;
+}
+
+function writeCsv(filePath, records) {
+  const header = [
+    'transport',
+    'method',
+    'path',
+    'tag',
+    'authMode',
+    'sourceFile',
+    'sourceLine',
+    'purpose',
+    'consumerFiles',
+    'pathParams',
+    'queryParams',
+    'bodyHints',
+    'successShape',
+    'errorShape',
+    'sideEffects',
+    'priority',
+  ];
+
+  const rows = [
+    header.join(','),
+    ...records.map(record => [
+      record.transport,
+      record.method,
+      record.path,
+      record.tag,
+      record.authMode,
+      record.sourceFile,
+      record.sourceLine,
+      record.purpose,
+      record.consumerFiles,
+      record.inputs.pathParams,
+      record.inputs.queryParams,
+      record.inputs.bodyHints,
+      record.successShape,
+      record.errorShape,
+      record.sideEffects,
+      record.priority,
+    ].map(escapeCsv).join(',')),
+  ];
+
+  fs.writeFileSync(filePath, `${rows.join('\n')}\n`);
+}
+
+function writeMarkdown(filePath, summary, records, realtimeContracts) {
+  const grouped = new Map();
+
+  for (const record of records) {
+    if (!grouped.has(record.tag)) {
+      grouped.set(record.tag, []);
+    }
+
+    grouped.get(record.tag).push(record);
+  }
+
+  const lines = [
+    '# Backend Inventory',
+    '',
+    `Generated on ${summary.generatedAt}.`,
+    '',
+    '## Summary',
+    '',
+    `- HTTP routes: ${summary.httpRoutes}`,
+    `- SSE routes: ${summary.sseRoutes}`,
+    `- Modular routes: ${summary.modularRoutes}`,
+    `- Inline routes: ${summary.inlineRoutes}`,
+    `- Route files scanned: ${summary.routeFilesScanned}`,
+    '',
+    '## Realtime Contracts',
+    '',
+    `- Incoming websocket message types (${realtimeContracts.incomingMessageTypes.length}): ${realtimeContracts.incomingMessageTypes.join(', ')}`,
+    `- Outgoing websocket message types (${realtimeContracts.outgoingMessageTypes.length}): ${realtimeContracts.outgoingMessageTypes.join(', ')}`,
+    '',
+  ];
+
+  for (const [tag, tagRecords] of [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    lines.push(`## ${tag}`);
+    lines.push('');
+    lines.push('| Method | Path | Auth | Purpose | Consumers | Source |');
+    lines.push('| --- | --- | --- | --- | --- | --- |');
+
+    for (const record of tagRecords.sort((left, right) => left.path.localeCompare(right.path))) {
+      lines.push(
+        `| ${record.method} | \`${record.path}\` | ${record.authMode} | ${record.purpose} | ${record.consumerFiles.join('<br>') || '-'} | ${record.sourceFile}:${record.sourceLine} |`
+      );
+    }
+
+    lines.push('');
+  }
+
+  fs.writeFileSync(filePath, `${lines.join('\n')}\n`);
+}
+
+const clientFiles = walkFiles(clientRoot).filter(filePath => /\.(js|jsx|ts|tsx)$/.test(filePath));
+const legacyRuntimePath = path.join(serverRoot, 'index.js');
+const runtimeContent = readText(legacyRuntimePath);
+const mounts = parseMounts(runtimeContent);
+const records = [];
+
+records.push(...parseRoutes(legacyRuntimePath, '', 'mixed_or_inline', clientFiles));
+
+for (const [routeVariable, mount] of mounts.entries()) {
+  const relativeImport = mount.routeImport.replace('./', '');
+  const routeFilePath = path.join(serverRoot, relativeImport);
+  records.push(...parseRoutes(routeFilePath, mount.basePath, mount.authMode, clientFiles));
+}
+
+const realtimeContracts = parseRealtimeContracts(legacyRuntimePath);
+const summary = {
+  generatedAt: new Date().toISOString(),
+  httpRoutes: records.filter(record => record.transport === 'http').length,
+  sseRoutes: records.filter(record => record.transport === 'sse').length,
+  modularRoutes: records.filter(record => record.sourceFile.includes('/routes/')).length,
+  inlineRoutes: records.filter(record => record.sourceFile === 'server/index.js').length,
+  routeFilesScanned: new Set(records.map(record => record.sourceFile)).size,
+};
+
+fs.writeFileSync(
+  path.join(docsRoot, 'endpoint-inventory.json'),
+  JSON.stringify({ summary, realtimeContracts, records }, null, 2)
+);
+
+writeCsv(path.join(docsRoot, 'endpoint-inventory.csv'), records);
+writeMarkdown(path.join(docsRoot, 'endpoint-inventory.md'), summary, records, realtimeContracts);
+
+console.log('[inventory] Generated docs/backend/endpoint-inventory.{json,csv,md}');
+console.log(
+  `[inventory] HTTP=${summary.httpRoutes} SSE=${summary.sseRoutes} Modular=${summary.modularRoutes} Inline=${summary.inlineRoutes}`
+);

server/routes/agent.js

@@ -875,8 +875,9 @@ router.post('/', validateExternalApiKey, async (req, res) => {
     // Determine the final project path
     if (githubUrl) {
       // Clone repository (to projectPath if provided, otherwise generate path)
+      // TODO: use credinitalsDB when refactoring
       const tokenToUse = githubToken || githubTokensDb.getActiveGithubToken(req.user.id);
-
+      
       let targetPath;
       if (projectPath) {
         targetPath = projectPath;
@@ -995,6 +996,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         console.log('🔄 Starting GitHub branch/PR creation workflow...');
 
         // Get GitHub token
+        // TODO: use credinitalsDB when refactoring
         const tokenToUse = githubToken || githubTokensDb.getActiveGithubToken(req.user.id);
 
         if (!tokenToUse) {

server/src/app.ts

@@ -0,0 +1,32 @@
+import './config/load-env-vars.js';
+
+import { pathToFileURL } from 'url';
+
+import { getRuntimePaths } from '@/config/runtime.js';
+import type { ServerApplication } from '@/shared/types/app.js';
+import { logger } from '@/shared/utils/logger.js';
+
+export function createServerApplication(): ServerApplication {
+  const runtimePaths = getRuntimePaths();
+  
+  return {
+    runtimePaths,
+    start: async () => {
+      // ----------------------------------------------
+      // Legacy backend Runner
+      // logger.info('Bootstrapping backend via legacy runtime bridge', {
+      //   legacyRuntime: runtimePaths.legacyRuntimePath,
+      // });
+      // await import(pathToFileURL(runtimePaths.legacyRuntimePath).href);
+      // ----------------------------------------------
+
+
+      // ----------------------------------------------
+      // Refactor backend Runner
+      logger.info('Bootstrapping backend via refactor runtime', {
+        refactorRuntime: runtimePaths.refactorRuntimePath,
+      });
+      await import(pathToFileURL(runtimePaths.refactorRuntimePath).href);
+    },
+  };
+}

server/src/bootstrap.ts

@@ -0,0 +1,8 @@
+import { createServerApplication } from '@/app.js';
+
+async function startServerApplication(): Promise<void> {
+  const application = createServerApplication();
+  await application.start();
+}
+
+await startServerApplication();

server/src/config/env.ts

@@ -0,0 +1,5 @@
+/**
+ * Environment Flag: Is Platform
+ * Indicates if the app is running in Platform mode (hosted) or OSS mode (self-hosted)
+ */
+export const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';

server/src/config/load-env-vars.ts

@@ -0,0 +1,30 @@
+// Load environment variables from .env before other imports execute.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+try {
+  const envPath = path.join(__dirname, '../../../.env');
+  const envFile = fs.readFileSync(envPath, 'utf8');
+  envFile.split('\n').forEach(line => {
+    const trimmedLine = line.trim();
+    if (trimmedLine && !trimmedLine.startsWith('#')) {
+      const [key, ...valueParts] = trimmedLine.split('=');
+      if (key && valueParts.length > 0 && !process.env[key]) {
+        process.env[key] = valueParts.join('=').trim();
+      }
+    }
+  });
+} catch (e: any) {
+  console.log('No .env file found or error reading it:', e.message);
+}
+
+// Set a default DATABASE_PATH if not already set by .env to ~/.cloudcli/auth.db
+if (!process.env.DATABASE_PATH) {
+  process.env.DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
+}

server/src/config/runtime.ts

@@ -0,0 +1,27 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import type { RuntimePaths } from '@/shared/types/app.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const RUN_REFACTOR_WITH_SRC = true;
+
+export function getRuntimePaths(): RuntimePaths {
+  const serverSrcDir = path.resolve(__dirname, '..');
+  const serverDir = path.resolve(serverSrcDir, '..');
+  const refactorRuntimePath =
+    RUN_REFACTOR_WITH_SRC
+      ? path.join(serverDir, 'src', 'runner.ts')
+      : path.join(serverDir, 'dist', 'runner.js');
+
+  return {
+    serverSrcDir,
+    serverDir,
+    projectRoot: path.resolve(serverDir, '..'),
+    legacyRuntimePath: path.join(serverDir, 'index.js'),
+    bootstrapEntrypointPath: path.join(serverDir, 'dist', 'bootstrap.js'),
+    refactorRuntimePath
+  };
+}

server/src/modules/agent/.gitkeep

@@ -0,0 +1 @@
+

server/src/modules/ai-runtime/ai-runtime.registry.ts

@@ -0,0 +1,42 @@
+import type { IProvider } from '@/modules/ai-runtime/types/index.js';
+import { ClaudeProvider } from '@/modules/ai-runtime/providers/claude/claude.provider.js';
+import { CodexProvider } from '@/modules/ai-runtime/providers/codex/codex.provider.js';
+import { CursorProvider } from '@/modules/ai-runtime/providers/cursor/cursor.provider.js';
+import { GeminiProvider } from '@/modules/ai-runtime/providers/gemini/gemini.provider.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+import { AppError } from '@/shared/utils/app-error.js';
+
+const providers: Record<LLMProvider, IProvider> = {
+  claude: new ClaudeProvider(),
+  codex: new CodexProvider(),
+  cursor: new CursorProvider(),
+  gemini: new GeminiProvider(),
+};
+
+/**
+ * Central registry for resolving provider implementations by id.
+ */
+export const llmProviderRegistry = {
+  /**
+   * Returns all registered providers.
+   */
+  listProviders(): IProvider[] {
+    return Object.values(providers);
+  },
+
+  /**
+   * Resolves one provider or throws a typed 400 error.
+   */
+  resolveProvider(provider: string): IProvider {
+    const key = provider as LLMProvider;
+    const resolvedProvider = providers[key];
+    if (!resolvedProvider) {
+      throw new AppError(`Unsupported provider "${provider}".`, {
+        code: 'UNSUPPORTED_PROVIDER',
+        statusCode: 400,
+      });
+    }
+
+    return resolvedProvider;
+  },
+};

server/src/modules/ai-runtime/ai-runtime.routes.ts

@@ -0,0 +1,563 @@
+import express, { type NextFunction, type Request, type Response } from 'express';
+
+import { asyncHandler } from '@/shared/http/async-handler.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { createApiErrorResponse, createApiSuccessResponse } from '@/shared/http/api-response.js';
+import { llmService } from '@/modules/ai-runtime/services/ai-runtime.service.js';
+import { llmAuthService } from '@/modules/ai-runtime/services/auth.service.js';
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+import { llmMcpService } from '@/modules/ai-runtime/services/mcp.service.js';
+import { llmSkillsService } from '@/modules/ai-runtime/services/skills.service.js';
+import type { McpScope, McpTransport, UpsertProviderMcpServerInput } from '@/modules/ai-runtime/types/index.js';
+import { llmMessagesUnifier } from '@/modules/ai-runtime/services/messages-unifier.service.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+import { logger } from '@/shared/utils/logger.js';
+
+const router = express.Router();
+
+/**
+ * Safely reads an Express path parameter that may arrive as string or string[].
+ */
+const readPathParam = (value: unknown, name: string): string => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value) && typeof value[0] === 'string') {
+    return value[0];
+  }
+
+  throw new AppError(`${name} path parameter is invalid.`, {
+    code: 'INVALID_PATH_PARAMETER',
+    statusCode: 400,
+  });
+};
+
+const normalizeProviderParam = (value: unknown): string =>
+  readPathParam(value, 'provider').trim().toLowerCase();
+
+/**
+ * Validates and normalizes rename payload.
+ */
+const parseRenamePayload = (payload: unknown): { summary: string } => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const summary = typeof body.summary === 'string' ? body.summary.trim() : '';
+  if (!summary) {
+    throw new AppError('summary is required.', {
+      code: 'SUMMARY_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  if (summary.length > 500) {
+    throw new AppError('summary must not exceed 500 characters.', {
+      code: 'SUMMARY_TOO_LONG',
+      statusCode: 400,
+    });
+  }
+
+  return { summary };
+};
+
+/**
+ * Reads optional query values and trims surrounding whitespace.
+ */
+const readOptionalQueryString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+/**
+ * Validates MCP scope query/body values.
+ */
+const parseMcpScope = (value: unknown): McpScope | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalized = readOptionalQueryString(value);
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized === 'user' || normalized === 'local' || normalized === 'project') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported MCP scope "${normalized}".`, {
+    code: 'INVALID_MCP_SCOPE',
+    statusCode: 400,
+  });
+};
+
+/**
+ * Validates MCP transport query/body values.
+ */
+const parseMcpTransport = (value: unknown): McpTransport => {
+  const normalized = readOptionalQueryString(value);
+  if (!normalized) {
+    throw new AppError('transport is required.', {
+      code: 'MCP_TRANSPORT_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  if (normalized === 'stdio' || normalized === 'http' || normalized === 'sse') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported MCP transport "${normalized}".`, {
+    code: 'INVALID_MCP_TRANSPORT',
+    statusCode: 400,
+  });
+};
+
+/**
+ * Parses and validates MCP upsert payload.
+ */
+const parseMcpUpsertPayload = (payload: unknown): UpsertProviderMcpServerInput => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const name = readOptionalQueryString(body.name);
+  if (!name) {
+    throw new AppError('name is required.', {
+      code: 'MCP_NAME_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  const transport = parseMcpTransport(body.transport);
+  const scope = parseMcpScope(body.scope);
+  const workspacePath = readOptionalQueryString(body.workspacePath);
+
+  return {
+    name,
+    transport,
+    scope,
+    workspacePath,
+    command: readOptionalQueryString(body.command),
+    args: Array.isArray(body.args) ? body.args.filter((entry): entry is string => typeof entry === 'string') : undefined,
+    env: typeof body.env === 'object' && body.env !== null
+      ? Object.fromEntries(
+          Object.entries(body.env as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+    cwd: readOptionalQueryString(body.cwd),
+    url: readOptionalQueryString(body.url),
+    headers: typeof body.headers === 'object' && body.headers !== null
+      ? Object.fromEntries(
+          Object.entries(body.headers as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+    envVars: Array.isArray(body.envVars)
+      ? body.envVars.filter((entry): entry is string => typeof entry === 'string')
+      : undefined,
+    bearerTokenEnvVar: readOptionalQueryString(body.bearerTokenEnvVar),
+    envHttpHeaders: typeof body.envHttpHeaders === 'object' && body.envHttpHeaders !== null
+      ? Object.fromEntries(
+          Object.entries(body.envHttpHeaders as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+  };
+};
+
+/**
+ * Converts any provider route parameter into the strongly typed provider union.
+ */
+const parseProvider = (value: unknown): LLMProvider => {
+  const normalized = normalizeProviderParam(value);
+  if (normalized === 'claude' || normalized === 'codex' || normalized === 'cursor' || normalized === 'gemini') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported provider "${normalized}".`, {
+    code: 'UNSUPPORTED_PROVIDER',
+    statusCode: 400,
+  });
+};
+
+/**
+ * Enriches provider session snapshots with normalized message types for frontend rendering.
+ */
+const formatSessionSnapshot = (
+  provider: LLMProvider,
+  snapshot: {
+    sessionId: string;
+    events: Array<{
+      timestamp: string;
+      channel: 'sdk' | 'stdout' | 'stderr' | 'json' | 'system' | 'error';
+      message?: string;
+      data?: unknown;
+    }>;
+  },
+) => ({
+  ...snapshot,
+  messages: llmMessagesUnifier.normalizeSessionEvents(provider, snapshot.sessionId, snapshot.events),
+});
+
+router.get(
+  '/providers',
+  asyncHandler(async (_req: Request, res: Response) => {
+    res.json(createApiSuccessResponse({ providers: llmService.listProviders() }));
+  }),
+);
+
+router.get(
+  '/providers/:provider/models',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const models = await llmService.listModels(provider);
+    res.json(createApiSuccessResponse({ provider, models }));
+  }),
+);
+
+router.get(
+  '/providers/:provider/auth/status',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const auth = await llmAuthService.getProviderAuthStatus(provider);
+    res.json(createApiSuccessResponse({ provider, auth }));
+  }),
+);
+
+router.get(
+  '/providers/:provider/sessions',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const sessions = llmService.listSessions(provider).map((session) => formatSessionSnapshot(provider, session));
+    res.json(createApiSuccessResponse({ provider, sessions }));
+  }),
+);
+
+router.get(
+  '/providers/:provider/sessions/:sessionId',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const session = llmService.getSession(provider, sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" not found for provider "${provider}".`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    res.json(createApiSuccessResponse({ provider, session: formatSessionSnapshot(provider, session) }));
+  }),
+);
+
+router.post(
+  '/providers/:provider/sessions/start',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const snapshot = await llmService.startSession(provider, req.body);
+    const formattedSnapshot = formatSessionSnapshot(provider, snapshot);
+    res.status(202).json(
+      createApiSuccessResponse({
+        provider,
+        session: formattedSnapshot,
+      }),
+    );
+  }),
+);
+
+router.post(
+  '/providers/:provider/sessions/:sessionId/resume',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+
+    const snapshot = await llmService.resumeSession(provider, sessionId, req.body);
+    res.status(202).json(createApiSuccessResponse({ provider, session: formatSessionSnapshot(provider, snapshot) }));
+  }),
+);
+
+router.post(
+  '/providers/:provider/sessions/:sessionId/stop',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const stopped = await llmService.stopSession(provider, sessionId);
+    res.json(createApiSuccessResponse({ provider, sessionId, stopped }));
+  }),
+);
+
+/**
+ * Lists MCP servers for one provider grouped by user/local/project scopes.
+ */
+router.get(
+  '/providers/:provider/mcp/servers',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const scope = parseMcpScope(req.query.scope);
+
+    if (scope) {
+      const servers = await llmMcpService.listProviderMcpServersForScope(provider, scope, { workspacePath });
+      res.json(createApiSuccessResponse({ provider, scope, servers }));
+      return;
+    }
+
+    const groupedServers = await llmMcpService.listProviderMcpServers(provider, { workspacePath });
+    res.json(createApiSuccessResponse({ provider, scopes: groupedServers }));
+  }),
+);
+
+/**
+ * Adds one MCP server for one provider and scope.
+ */
+router.post(
+  '/providers/:provider/mcp/servers',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const payload = parseMcpUpsertPayload(req.body);
+    const server = await llmMcpService.upsertProviderMcpServer(provider, payload);
+    res.status(201).json(createApiSuccessResponse({ server }));
+  }),
+);
+
+/**
+ * Updates one provider MCP server definition.
+ */
+router.put(
+  '/providers/:provider/mcp/servers/:name',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const payload = parseMcpUpsertPayload({
+      ...((req.body && typeof req.body === 'object') ? req.body as Record<string, unknown> : {}),
+      name: readPathParam(req.params.name, 'name'),
+    });
+    const server = await llmMcpService.upsertProviderMcpServer(provider, payload);
+    res.json(createApiSuccessResponse({ server }));
+  }),
+);
+
+/**
+ * Removes one provider MCP server from its configured scope.
+ */
+router.delete(
+  '/providers/:provider/mcp/servers/:name',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const scope = parseMcpScope(req.query.scope);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const result = await llmMcpService.removeProviderMcpServer(provider, {
+      name: readPathParam(req.params.name, 'name'),
+      scope,
+      workspacePath,
+    });
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+/**
+ * Executes a lightweight startup/connectivity probe for one provider MCP server.
+ */
+router.post(
+  '/providers/:provider/mcp/servers/:name/run',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const body = (req.body as Record<string, unknown> | undefined) ?? {};
+    const scope = parseMcpScope(body.scope ?? req.query.scope);
+    const workspacePath = readOptionalQueryString(body.workspacePath ?? req.query.workspacePath);
+    const result = await llmMcpService.runProviderMcpServer(provider, {
+      name: readPathParam(req.params.name, 'name'),
+      scope,
+      workspacePath,
+    });
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+/**
+ * Adds one HTTP/stdio MCP server to every provider.
+ */
+router.post(
+  '/mcp/servers/global',
+  asyncHandler(async (req: Request, res: Response) => {
+    const payload = parseMcpUpsertPayload(req.body);
+    if (payload.scope === 'local') {
+      throw new AppError('Global MCP add supports only "user" or "project" scopes.', {
+        code: 'INVALID_GLOBAL_MCP_SCOPE',
+        statusCode: 400,
+      });
+    }
+    const results = await llmMcpService.addMcpServerToAllProviders({
+      ...payload,
+      scope: payload.scope === 'user' ? 'user' : 'project',
+    });
+    res.status(201).json(createApiSuccessResponse({ results }));
+  }),
+);
+
+/**
+ * Lists provider-specific skills from all documented skill directories.
+ */
+router.get(
+  '/providers/:provider/skills',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const skills = await llmSkillsService.listProviderSkills(provider, { workspacePath });
+    res.json(createApiSuccessResponse({ provider, skills }));
+  }),
+);
+
+/**
+ * Lists skills for one provider or for all providers in a single response.
+ */
+router.get(
+  '/skills',
+  asyncHandler(async (req: Request, res: Response) => {
+    const providerQuery = readOptionalQueryString(req.query.provider);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    if (providerQuery) {
+      const provider = parseProvider(providerQuery);
+      const skills = await llmSkillsService.listProviderSkills(provider, { workspacePath });
+      res.json(createApiSuccessResponse({ provider, skills }));
+      return;
+    }
+
+    const providers: LLMProvider[] = ['claude', 'codex', 'cursor', 'gemini'];
+    const byProvider = Object.fromEntries(
+      await Promise.all(
+        providers.map(async (provider) => ([
+          provider,
+          await llmSkillsService.listProviderSkills(provider, { workspacePath }),
+        ])),
+      ),
+    );
+    res.json(createApiSuccessResponse({ providers: byProvider }));
+  }),
+);
+
+router.get(
+  '/sessions/:sessionId/messages',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const history = await llmSessionsService.getSessionHistory(sessionId);
+    res.json(createApiSuccessResponse({
+      sessionId,
+      provider: history.provider,
+      messages: history.messages,
+    }));
+  }),
+);
+
+router.get(
+  '/sessions/:sessionId/history',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const history = await llmSessionsService.getSessionHistory(sessionId);
+    res.json(createApiSuccessResponse(history));
+  }),
+);
+
+/**
+ * Renames one indexed session by writing the custom summary into DB.
+ */
+router.put(
+  '/sessions/:sessionId/rename',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const { summary } = parseRenamePayload(req.body);
+    llmSessionsService.updateSessionCustomName(sessionId, summary);
+    res.json(createApiSuccessResponse({ sessionId, summary }));
+  }),
+);
+
+/**
+ * Returns DB-indexed sessions discovered by the session-processor scan.
+ */
+router.get(
+  '/sessions/index',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider =
+      typeof req.query.provider === 'string' ? req.query.provider.trim().toLowerCase() : undefined;
+    const sessions = llmSessionsService.listIndexedSessions(provider);
+    res.json(createApiSuccessResponse({ provider: provider ?? null, sessions }));
+  }),
+);
+
+/**
+ * Returns one DB-indexed session metadata row.
+ */
+router.get(
+  '/sessions/:sessionId',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const session = llmSessionsService.getIndexedSession(sessionId);
+    res.json(createApiSuccessResponse({ session }));
+  }),
+);
+
+/**
+ * Triggers provider disk scans and refreshes the shared sessions table.
+ */
+router.post(
+  '/sessions/sync',
+  asyncHandler(async (_req: Request, res: Response) => {
+    const syncResult = await llmSessionsService.synchronizeSessions();
+    res.json(createApiSuccessResponse(syncResult));
+  }),
+);
+
+/**
+ * Deletes provider-specific session artifacts and removes the DB row.
+ */
+router.delete(
+  '/sessions/:sessionId',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = readPathParam(req.params.sessionId, 'sessionId');
+    const result = await llmSessionsService.deleteSessionArtifacts(sessionId);
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+/**
+ * Normalizes route-level failures to a consistent JSON API shape.
+ */
+router.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
+  if (res.headersSent) {
+    return;
+  }
+
+  if (error instanceof AppError) {
+    res
+      .status(error.statusCode)
+      .json(createApiErrorResponse(error.code, error.message, undefined, error.details));
+    return;
+  }
+
+  const message = error instanceof Error ? error.message : 'Unexpected LLM route failure.';
+  logger.error(message, {
+    module: 'ai-runtime.routes',
+  });
+
+  res.status(500).json(createApiErrorResponse('INTERNAL_ERROR', message));
+});
+
+export default router;

server/src/modules/ai-runtime/providers/base/abstract.provider.ts

@@ -0,0 +1,173 @@
+import type {
+  IProvider,
+  IProviderAuthRuntime,
+  IProviderMcpRuntime,
+  IProviderSessionSynchronizerRuntime,
+  IProviderSkillsRuntime,
+  MutableProviderSession,
+  ProviderCapabilities,
+  ProviderExecutionFamily,
+  ProviderModel,
+  ProviderSessionEvent,
+  ProviderSessionSnapshot,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+
+const MAX_EVENT_BUFFER_SIZE = 2_000;
+
+/**
+ * Shared provider base for session lifecycle state and capability gating.
+ */
+export abstract class AbstractProvider implements IProvider {
+  readonly id: LLMProvider;
+  readonly family: ProviderExecutionFamily;
+  readonly capabilities: ProviderCapabilities;
+  abstract readonly mcp: IProviderMcpRuntime;
+  abstract readonly skills: IProviderSkillsRuntime;
+  abstract readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime;
+  abstract readonly auth: IProviderAuthRuntime;
+
+  protected readonly sessions = new Map<string, MutableProviderSession>();
+
+  protected constructor(
+    id: LLMProvider,
+    family: ProviderExecutionFamily,
+    capabilities: ProviderCapabilities,
+  ) {
+    this.id = id;
+    this.family = family;
+    this.capabilities = capabilities;
+  }
+
+  abstract listModels(): Promise<ProviderModel[]>;
+  abstract launchSession(input: StartSessionInput): Promise<ProviderSessionSnapshot>;
+  abstract resumeSession(
+    input: StartSessionInput & { sessionId: string },
+  ): Promise<ProviderSessionSnapshot>;
+
+  /**
+   * Returns one in-memory session snapshot when present.
+   */
+  getSession(sessionId: string): ProviderSessionSnapshot | null {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return null;
+    }
+
+    return this.toSnapshot(session);
+  }
+
+  /**
+   * Returns snapshots of all in-memory sessions.
+   */
+  listSessions(): ProviderSessionSnapshot[] {
+    return [...this.sessions.values()].map((session) => this.toSnapshot(session));
+  }
+
+  /**
+   * Requests a graceful session stop.
+   */
+  async stopSession(sessionId: string): Promise<boolean> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const stopped = await session.stop();
+    if (stopped && session.status === 'running') {
+      this.updateSessionStatus(session, 'stopped');
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'system',
+        message: 'Session stop requested.',
+        data: {
+          sessionId,
+          sessionStatus: 'SESSION_ABORTED',
+        },
+      });
+    }
+
+    return stopped;
+  }
+
+  /**
+   * Creates mutable internal session state and registers it in memory.
+   */
+  protected createSessionRecord(
+    sessionId: string,
+    input: {
+      model?: string;
+      thinkingMode?: string;
+    },
+  ): MutableProviderSession {
+    const session: MutableProviderSession = {
+      sessionId,
+      provider: this.id,
+      family: this.family,
+      status: 'running',
+      startedAt: new Date().toISOString(),
+      model: input.model,
+      thinkingMode: input.thinkingMode,
+      events: [],
+      completion: Promise.resolve(),
+      stop: async () => false,
+    };
+
+    this.sessions.set(sessionId, session);
+
+    this.appendEvent(session, {
+      timestamp: session.startedAt,
+      channel: 'system',
+      message: 'Session started.',
+      data: {
+        sessionId,
+        sessionStatus: 'STARTED',
+      },
+    });
+
+    return session;
+  }
+
+  /**
+   * Appends an event while enforcing the configured ring-buffer size.
+   */
+  protected appendEvent(session: MutableProviderSession, event: ProviderSessionEvent): void {
+    session.events.push(event);
+
+    if (session.events.length > MAX_EVENT_BUFFER_SIZE) {
+      session.events.splice(0, session.events.length - MAX_EVENT_BUFFER_SIZE);
+    }
+  }
+
+  /**
+   * Marks the terminal state for a session.
+   */
+  protected updateSessionStatus(
+    session: MutableProviderSession,
+    status: MutableProviderSession['status'],
+    error?: string,
+  ): void {
+    session.status = status;
+    session.endedAt = new Date().toISOString();
+    session.error = error;
+  }
+
+  /**
+   * Converts mutable internal session state to an external snapshot.
+   */
+  protected toSnapshot(session: MutableProviderSession): ProviderSessionSnapshot {
+    return {
+      sessionId: session.sessionId,
+      provider: session.provider,
+      family: session.family,
+      status: session.status,
+      startedAt: session.startedAt,
+      endedAt: session.endedAt,
+      model: session.model,
+      thinkingMode: session.thinkingMode,
+      events: [...session.events],
+      error: session.error,
+    };
+  }
+}

server/src/modules/ai-runtime/providers/base/base-cli.provider.ts

@@ -0,0 +1,296 @@
+import { randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+
+import spawn from 'cross-spawn';
+
+import { AbstractProvider } from '@/modules/ai-runtime/providers/base/abstract.provider.js';
+import type {
+  MutableProviderSession,
+  ProviderCapabilities,
+  ProviderSessionEvent,
+  ProviderSessionSnapshot,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { createStreamLineAccumulator } from '@/shared/platform/stream.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+
+type CreateCliInvocationInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+};
+
+type CliInvocation = {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+};
+
+const PROCESS_SHUTDOWN_GRACE_PERIOD_MS = 2_000;
+
+/**
+ * Base class for CLI-driven providers with streamed stdout/stderr parsing.
+ */
+export abstract class BaseCliProvider extends AbstractProvider {
+  protected constructor(providerId: LLMProvider, capabilities: ProviderCapabilities) {
+    super(providerId, 'cli', capabilities);
+  }
+
+  /**
+   * Starts a new CLI session and begins process output streaming.
+   */
+  async launchSession(input: StartSessionInput): Promise<ProviderSessionSnapshot> {
+    return this.startSessionInternal({
+      ...input,
+      sessionId: input.sessionId ?? randomUUID(),
+      isResume: false,
+    });
+  }
+
+  /**
+   * Resumes an existing CLI session and begins process output streaming.
+   */
+  async resumeSession(input: StartSessionInput & { sessionId: string }): Promise<ProviderSessionSnapshot> {
+    return this.startSessionInternal({
+      ...input,
+      isResume: true,
+    });
+  }
+
+  /**
+   * Implemented by concrete CLI providers to describe command invocation.
+   */
+  protected abstract createCliInvocation(input: CreateCliInvocationInput): CliInvocation;
+
+  /**
+   * Appends uploaded image paths to prompt text for CLI providers that only accept string prompts.
+   */
+  protected appendImagePathsToPrompt(prompt: string, imagePaths?: string[]): string {
+    if (!imagePaths || imagePaths.length === 0) {
+      return prompt;
+    }
+
+    return `${prompt}\n\n${JSON.stringify(imagePaths)}`;
+  }
+
+  /**
+   * Maps one stdout/stderr line into either JSON or plain-text event shapes.
+   */
+  protected mapCliOutputLine(line: string, channel: 'stdout' | 'stderr'): ProviderSessionEvent {
+    const parsedJson = this.tryParseJson(line);
+    if (parsedJson !== null) {
+      return {
+        timestamp: new Date().toISOString(),
+        channel: 'json',
+        data: parsedJson,
+      };
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      channel,
+      message: line,
+    };
+  }
+
+  /**
+   * Runs a one-off CLI command and returns full stdout text on success.
+   */
+  protected async runCommandForOutput(command: string, args: string[]): Promise<string> {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: process.cwd(),
+      env: process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    const closePromise = once(child, 'close');
+    const errorPromise = once(child, 'error').then(([error]) => {
+      throw error;
+    });
+
+    await Promise.race([closePromise, errorPromise]);
+
+    if ((child.exitCode ?? 1) !== 0) {
+      const message = stderr.trim() || `Command "${command}" failed with code ${child.exitCode}`;
+      throw new Error(message);
+    }
+
+    return stdout;
+  }
+
+  /**
+   * Boots one CLI child process and wires stream handlers to the session buffer.
+   */
+  private async startSessionInternal(input: CreateCliInvocationInput): Promise<ProviderSessionSnapshot> {
+    const session = this.createSessionRecord(input.sessionId, {
+      model: input.model,
+      thinkingMode: input.thinkingMode,
+    });
+
+    const invocation = this.createCliInvocation(input);
+
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: invocation.cwd ?? input.workspacePath ?? process.cwd(),
+      env: {
+        ...process.env,
+        ...invocation.env,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }) as ChildProcessWithoutNullStreams;
+
+    const stop = async (): Promise<boolean> => this.terminateChildProcess(child);
+    session.stop = stop;
+
+    const stdoutAccumulator = createStreamLineAccumulator({ preserveEmptyLines: false });
+    const stderrAccumulator = createStreamLineAccumulator({ preserveEmptyLines: false });
+
+    child.stdout.on('data', (chunk) => {
+      const lines = stdoutAccumulator.push(chunk);
+      for (const line of lines) {
+        const event = this.mapCliOutputLine(line, 'stdout');
+        this.appendEvent(session, event);
+      }
+    });
+
+    child.stderr.on('data', (chunk) => {
+      const lines = stderrAccumulator.push(chunk);
+      for (const line of lines) {
+        const event = this.mapCliOutputLine(line, 'stderr');
+        this.appendEvent(session, event);
+      }
+    });
+
+    session.completion = this.waitForCliProcess(
+      session,
+      child,
+      stdoutAccumulator,
+      stderrAccumulator,
+    );
+    return this.toSnapshot(session);
+  }
+
+  /**
+   * Waits for process completion/error and marks final session status.
+   */
+  private async waitForCliProcess(
+    session: MutableProviderSession,
+    child: ChildProcessWithoutNullStreams,
+    stdoutAccumulator: { flush: () => string[] },
+    stderrAccumulator: { flush: () => string[] },
+  ): Promise<void> {
+    const closePromise = once(child, 'close') as Promise<[number | null, NodeJS.Signals | null]>;
+    const errorPromise = once(child, 'error') as Promise<[Error]>;
+    const raceResult = await Promise.race([
+      closePromise.then((result) => ({ type: 'close' as const, result })),
+      errorPromise.then((result) => ({ type: 'error' as const, result })),
+    ]);
+
+    const pendingStdout = stdoutAccumulator.flush();
+    const pendingStderr = stderrAccumulator.flush();
+
+    for (const line of pendingStdout) {
+      this.appendEvent(session, this.mapCliOutputLine(line, 'stdout'));
+    }
+
+    for (const line of pendingStderr) {
+      this.appendEvent(session, this.mapCliOutputLine(line, 'stderr'));
+    }
+
+    if (raceResult.type === 'error') {
+      const [error] = raceResult.result;
+      const message = error.message || 'CLI process failed before start.';
+      this.updateSessionStatus(session, 'failed', message);
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'error',
+        message,
+      });
+      return;
+    }
+
+    const [code, signal] = raceResult.result;
+
+    if (session.status === 'stopped') {
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'system',
+        message: `Session stopped (${signal ?? 'SIGTERM'}).`,
+      });
+      return;
+    }
+
+    if (code === 0) {
+      this.updateSessionStatus(session, 'completed');
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'system',
+        message: 'Session completed.',
+        data: {
+          sessionId: session.sessionId,
+          sessionStatus: 'COMPLETED',
+        },
+      });
+      return;
+    }
+
+    const message = `CLI command exited with code ${code ?? 'null'}${signal ? ` (signal: ${signal})` : ''}`;
+    this.updateSessionStatus(session, 'failed', message);
+    this.appendEvent(session, {
+      timestamp: new Date().toISOString(),
+      channel: 'error',
+      message,
+    });
+  }
+
+  /**
+   * Attempts graceful termination first, then force-kills when necessary.
+   */
+  private async terminateChildProcess(child: ChildProcessWithoutNullStreams): Promise<boolean> {
+    if (child.killed || child.exitCode !== null) {
+      return true;
+    }
+
+    try {
+      child.kill('SIGTERM');
+      await Promise.race([
+        once(child, 'close'),
+        new Promise((resolve) => setTimeout(resolve, PROCESS_SHUTDOWN_GRACE_PERIOD_MS)),
+      ]);
+
+      if (child.exitCode === null) {
+        child.kill('SIGKILL');
+      }
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Best-effort JSON parser for stream-json providers.
+   */
+  private tryParseJson(line: string): unknown | null {
+    const trimmed = line.trim();
+    if (!trimmed || (!trimmed.startsWith('{') && !trimmed.startsWith('['))) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return null;
+    }
+  }
+}

server/src/modules/ai-runtime/providers/base/base-sdk.provider.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto';
+
+import { AbstractProvider } from '@/modules/ai-runtime/providers/base/abstract.provider.js';
+import type {
+  MutableProviderSession,
+  ProviderCapabilities,
+  ProviderSessionEvent,
+  ProviderSessionSnapshot,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+
+type CreateSdkExecutionInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+  emitEvent?: (event: ProviderSessionEvent) => void;
+};
+
+type SdkExecution = {
+  stream: AsyncIterable<unknown>;
+  stop: () => Promise<boolean>;
+};
+
+/**
+ * Base class for SDK-driven providers with async stream consumption.
+ */
+export abstract class BaseSdkProvider extends AbstractProvider {
+  protected constructor(providerId: LLMProvider, capabilities: ProviderCapabilities) {
+    super(providerId, 'sdk', capabilities);
+  }
+
+  /**
+   * Starts a new SDK session and begins event streaming.
+   */
+  async launchSession(input: StartSessionInput): Promise<ProviderSessionSnapshot> {
+    return this.startSessionInternal({
+      ...input,
+      sessionId: input.sessionId ?? randomUUID(),
+      isResume: false,
+    });
+  }
+
+  /**
+   * Resumes an existing SDK session and begins event streaming.
+   */
+  async resumeSession(input: StartSessionInput & { sessionId: string }): Promise<ProviderSessionSnapshot> {
+    return this.startSessionInternal({
+      ...input,
+      isResume: true,
+    });
+  }
+
+  /**
+   * Implemented by concrete SDK providers to create a running execution.
+   */
+  protected abstract createSdkExecution(input: CreateSdkExecutionInput): Promise<SdkExecution>;
+
+  /**
+   * Normalizes raw SDK events to the shared event shape.
+   */
+  protected mapSdkEvent(rawEvent: unknown): ProviderSessionEvent | null {
+    return {
+      timestamp: new Date().toISOString(),
+      channel: 'sdk',
+      data: rawEvent,
+    };
+  }
+
+  /**
+   * Initializes one SDK execution and wires it to the internal session record.
+   */
+  private async startSessionInternal(input: CreateSdkExecutionInput): Promise<ProviderSessionSnapshot> {
+    const session = this.createSessionRecord(input.sessionId, {
+      model: input.model,
+      thinkingMode: input.thinkingMode,
+    });
+
+    let execution: SdkExecution;
+    try {
+      execution = await this.createSdkExecution({
+        ...input,
+        emitEvent: (event) => {
+          this.appendEvent(session, event);
+        },
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to start SDK session';
+      this.updateSessionStatus(session, 'failed', message);
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'error',
+        message,
+      });
+      throw error;
+    }
+
+    session.stop = execution.stop;
+
+    session.completion = this.consumeStream(session, execution.stream);
+    return this.toSnapshot(session);
+  }
+
+  /**
+   * Drains SDK events until completion/error and updates final status.
+   */
+  private async consumeStream(
+    session: MutableProviderSession,
+    stream: AsyncIterable<unknown>,
+  ): Promise<void> {
+    try {
+      for await (const sdkEvent of stream) {
+        const normalized = this.mapSdkEvent(sdkEvent);
+        if (normalized) {
+          this.appendEvent(session, normalized);
+        }
+      }
+
+      // after stream completion, only update status if not already stopped by user
+      if (session.status === 'running') {
+        this.updateSessionStatus(session, 'completed');
+        this.appendEvent(session, {
+          timestamp: new Date().toISOString(),
+          channel: 'system',
+          message: 'Session completed.',
+          data: {
+            sessionId: session.sessionId,
+            sessionStatus: 'COMPLETED',
+          },
+        });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown SDK execution failure';
+
+      if (session.status === 'stopped') {
+        this.appendEvent(session, {
+          timestamp: new Date().toISOString(),
+          channel: 'system',
+          message: 'Session stopped.',
+        });
+        return;
+      }
+
+      this.updateSessionStatus(session, 'failed', message);
+      this.appendEvent(session, {
+        timestamp: new Date().toISOString(),
+        channel: 'error',
+        message,
+      });
+    }
+  }
+}

server/src/modules/ai-runtime/providers/claude/claude-auth.runtime.ts

@@ -0,0 +1,120 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import type { IProviderAuthRuntime, ProviderAuthStatus } from '@/modules/ai-runtime/types/index.js';
+
+type ClaudeCredentialsFile = {
+  email?: string;
+  user?: string;
+  claudeAiOauth?: {
+    accessToken?: string;
+    expiresAt?: number | string;
+  };
+};
+
+/**
+ * Reads auth status for Claude from env/settings and OAuth credentials.
+ */
+export class ClaudeAuthRuntime implements IProviderAuthRuntime {
+  async getStatus(): Promise<ProviderAuthStatus> {
+    try {
+      if (process.env.ANTHROPIC_API_KEY?.trim()) {
+        return {
+          provider: 'claude',
+          authenticated: true,
+          email: 'API Key Auth',
+          method: 'api_key',
+        };
+      }
+
+      const settingsEnv = await this.loadClaudeSettingsEnv();
+      if (settingsEnv.ANTHROPIC_API_KEY?.trim()) {
+        return {
+          provider: 'claude',
+          authenticated: true,
+          email: 'API Key Auth',
+          method: 'api_key',
+        };
+      }
+
+      if (settingsEnv.ANTHROPIC_AUTH_TOKEN?.trim()) {
+        return {
+          provider: 'claude',
+          authenticated: true,
+          email: 'Configured via settings.json',
+          method: 'api_key',
+        };
+      }
+
+      const credentialsPath = path.join(os.homedir(), '.claude', '.credentials.json');
+      const content = await readFile(credentialsPath, 'utf8');
+      const credentials = JSON.parse(content) as ClaudeCredentialsFile;
+      const oauth = credentials.claudeAiOauth;
+      const accessToken = oauth?.accessToken;
+
+      if (accessToken && !this.isExpired(oauth?.expiresAt)) {
+        return {
+          provider: 'claude',
+          authenticated: true,
+          email: credentials.email ?? credentials.user ?? null,
+          method: 'credentials_file',
+        };
+      }
+
+      return {
+        provider: 'claude',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Not authenticated',
+      };
+    } catch {
+      return {
+        provider: 'claude',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Not authenticated',
+      };
+    }
+  }
+
+  /**
+   * Reads optional env values from ~/.claude/settings.json.
+   */
+  private async loadClaudeSettingsEnv(): Promise<Record<string, string>> {
+    try {
+      const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+      const content = await readFile(settingsPath, 'utf8');
+      const settings = JSON.parse(content) as { env?: unknown };
+      if (!settings.env || typeof settings.env !== 'object') {
+        return {};
+      }
+
+      return Object.fromEntries(
+        Object.entries(settings.env as Record<string, unknown>).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string',
+        ),
+      );
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Returns true when an OAuth expiration timestamp is in the past.
+   */
+  private isExpired(expiresAt: number | string | undefined): boolean {
+    if (expiresAt === undefined) {
+      return false;
+    }
+
+    if (typeof expiresAt === 'number') {
+      return Date.now() >= expiresAt;
+    }
+
+    const numeric = Number.parseInt(expiresAt, 10);
+    return Number.isFinite(numeric) ? Date.now() >= numeric : false;
+  }
+}

server/src/modules/ai-runtime/providers/claude/claude-mcp.runtime.ts

@@ -0,0 +1,154 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import type {
+  McpScope,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { BaseProviderMcpRuntime } from '@/modules/ai-runtime/providers/shared/mcp/base-provider-mcp.runtime.js';
+import {
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.js';
+
+/**
+ * Claude MCP runtime backed by `~/.claude.json` and project `.mcp.json`.
+ */
+export class ClaudeMcpRuntime extends BaseProviderMcpRuntime {
+  constructor() {
+    super('claude', ['user', 'local', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  /**
+   * Reads Claude MCP servers from user/local/project config locations.
+   */
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    if (scope === 'project') {
+      const filePath = path.join(workspacePath, '.mcp.json');
+      const config = await readJsonConfig(filePath);
+      return readObjectRecord(config.mcpServers) ?? {};
+    }
+
+    const filePath = path.join(os.homedir(), '.claude.json');
+    const config = await readJsonConfig(filePath);
+    if (scope === 'user') {
+      return readObjectRecord(config.mcpServers) ?? {};
+    }
+
+    const projects = readObjectRecord(config.projects) ?? {};
+    const projectConfig = readObjectRecord(projects[workspacePath]) ?? {};
+    return readObjectRecord(projectConfig.mcpServers) ?? {};
+  }
+
+  /**
+   * Writes Claude MCP servers to user/local/project config locations.
+   */
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    if (scope === 'project') {
+      const filePath = path.join(workspacePath, '.mcp.json');
+      const config = await readJsonConfig(filePath);
+      config.mcpServers = servers;
+      await writeJsonConfig(filePath, config);
+      return;
+    }
+
+    const filePath = path.join(os.homedir(), '.claude.json');
+    const config = await readJsonConfig(filePath);
+    if (scope === 'user') {
+      config.mcpServers = servers;
+      await writeJsonConfig(filePath, config);
+      return;
+    }
+
+    const projects = readObjectRecord(config.projects) ?? {};
+    const projectConfig = readObjectRecord(projects[workspacePath]) ?? {};
+    projectConfig.mcpServers = servers;
+    projects[workspacePath] = projectConfig;
+    config.projects = projects;
+    await writeJsonConfig(filePath, config);
+  }
+
+  /**
+   * Builds one Claude-native server object from the unified input payload.
+   */
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        type: 'stdio',
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: input.transport,
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  /**
+   * Normalizes one Claude server object.
+   */
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'claude',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      const transport = readOptionalString(config.type) === 'sse' ? 'sse' : 'http';
+      return {
+        provider: 'claude',
+        name,
+        scope,
+        transport,
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/src/modules/ai-runtime/providers/claude/claude-session-synchronizer.runtime.ts

@@ -0,0 +1,112 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import {
+  buildLookupMap,
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/modules/ai-runtime/providers/shared/session-synchronizer/session-synchronizer.utils.js';
+import type { IProviderSessionSynchronizerRuntime } from '@/modules/ai-runtime/types/index.js';
+
+type ParsedSession = {
+  sessionId: string;
+  workspacePath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Claude transcript artifacts.
+ */
+export class ClaudeSessionSynchronizerRuntime implements IProviderSessionSynchronizerRuntime {
+  private readonly provider = 'claude' as const;
+  private readonly claudeHome = path.join(os.homedir(), '.claude');
+
+  /**
+   * Scans ~/.claude projects and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const nameMap = await buildLookupMap(path.join(this.claudeHome, 'history.jsonl'), 'sessionId', 'display');
+    const files = await findFilesRecursivelyCreatedAfter(
+      path.join(this.claudeHome, 'projects'),
+      '.jsonl',
+      since ?? null,
+    );
+
+    let processed = 0;
+    for (const filePath of files) {
+      const parsed = await this.processSessionFile(filePath, nameMap);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.workspacePath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath,
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Claude session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<boolean> {
+    if (!filePath.endsWith('.jsonl')) {
+      return false;
+    }
+
+    const nameMap = await buildLookupMap(path.join(this.claudeHome, 'history.jsonl'), 'sessionId', 'display');
+    const parsed = await this.processSessionFile(filePath, nameMap);
+    if (!parsed) {
+      return false;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.workspacePath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath,
+    );
+
+    return true;
+  }
+
+  /**
+   * Extracts session metadata from one Claude JSONL session file.
+   */
+  private async processSessionFile(
+    filePath: string,
+    nameMap: Map<string, string>,
+  ): Promise<ParsedSession | null> {
+    return extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, unknown>;
+      const sessionId = typeof data.sessionId === 'string' ? data.sessionId : undefined;
+      const workspacePath = typeof data.cwd === 'string' ? data.cwd : undefined;
+
+      if (!sessionId || !workspacePath) {
+        return null;
+      }
+
+      return {
+        sessionId,
+        workspacePath,
+        sessionName: normalizeSessionName(nameMap.get(sessionId), 'Untitled Claude Session'),
+      };
+    });
+  }
+}

server/src/modules/ai-runtime/providers/claude/claude-skills.runtime.ts

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { IProviderSkillsRuntime, ProviderSkill } from '@/modules/ai-runtime/types/index.js';
+import { deduplicateSkills, listSkillsFromDirectory } from '@/modules/ai-runtime/providers/shared/skills/skills-runtime.utils.js';
+
+/**
+ * Claude skills runtime backed by user/project/plugin skill directories.
+ */
+export class ClaudeSkillsRuntime implements IProviderSkillsRuntime {
+  /**
+   * Lists all available Claude skills from user/project/plugin locations.
+   */
+  async listSkills(options?: { workspacePath?: string }): Promise<ProviderSkill[]> {
+    const workspacePath = path.resolve(options?.workspacePath ?? process.cwd());
+    const home = os.homedir();
+    const skills: ProviderSkill[] = [];
+
+    skills.push(
+      ...(await listSkillsFromDirectory({
+        provider: 'claude',
+        scope: 'user',
+        skillsDirectory: path.join(home, '.claude', 'skills'),
+        invocationPrefix: '/',
+      })),
+    );
+
+    skills.push(
+      ...(await listSkillsFromDirectory({
+        provider: 'claude',
+        scope: 'project',
+        skillsDirectory: path.join(workspacePath, '.claude', 'skills'),
+        invocationPrefix: '/',
+      })),
+    );
+
+    const enabledPlugins = await this.readClaudeEnabledPlugins();
+    if (!enabledPlugins.length) {
+      return skills;
+    }
+
+    const installedPluginIndex = await this.readClaudeInstalledPluginIndex();
+    for (const pluginId of enabledPlugins) {
+      const pluginInstalls = installedPluginIndex[pluginId];
+      if (!Array.isArray(pluginInstalls)) {
+        continue;
+      }
+
+      const pluginNamespace = pluginId.split('@')[0] ?? pluginId;
+      for (const install of pluginInstalls) {
+        if (!install || typeof install !== 'object') {
+          continue;
+        }
+        const installPath = typeof (install as Record<string, unknown>).installPath === 'string'
+          ? (install as Record<string, unknown>).installPath as string
+          : '';
+        if (!installPath) {
+          continue;
+        }
+
+        const pluginSkills = await listSkillsFromDirectory({
+          provider: 'claude',
+          scope: 'plugin',
+          skillsDirectory: path.join(installPath, 'skills'),
+          invocationPrefix: '/',
+          pluginName: pluginNamespace,
+        });
+
+        for (const skill of pluginSkills) {
+          skill.invocation = `/${pluginNamespace}:${skill.name}`;
+          skill.pluginName = pluginNamespace;
+        }
+
+        skills.push(...pluginSkills);
+      }
+    }
+
+    return deduplicateSkills(skills);
+  }
+
+  /**
+   * Reads Claude enabled plugin map from `~/.claude/settings.json`.
+   */
+  private async readClaudeEnabledPlugins(): Promise<string[]> {
+    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    try {
+      const settingsContent = await readFile(settingsPath, 'utf8');
+      const settings = JSON.parse(settingsContent) as Record<string, unknown>;
+      const enabledPlugins = settings.enabledPlugins;
+      if (!enabledPlugins || typeof enabledPlugins !== 'object' || Array.isArray(enabledPlugins)) {
+        return [];
+      }
+
+      const enabledRecords = enabledPlugins as Record<string, unknown>;
+      return Object.entries(enabledRecords)
+        .filter(([, enabled]) => enabled === true)
+        .map(([pluginId]) => pluginId);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Reads Claude installed plugin index from `~/.claude/plugins/installed_plugins.json`.
+   */
+  private async readClaudeInstalledPluginIndex(): Promise<Record<string, unknown[]>> {
+    const pluginIndexPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    try {
+      const indexContent = await readFile(pluginIndexPath, 'utf8');
+      const index = JSON.parse(indexContent) as Record<string, unknown>;
+      const plugins = index.plugins;
+      if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins)) {
+        return {};
+      }
+
+      const normalized: Record<string, unknown[]> = {};
+      for (const [pluginId, entries] of Object.entries(plugins as Record<string, unknown>)) {
+        normalized[pluginId] = Array.isArray(entries) ? entries : [];
+      }
+
+      return normalized;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return {};
+      }
+      throw error;
+    }
+  }
+}

server/src/modules/ai-runtime/providers/claude/claude.provider.ts

@@ -0,0 +1,325 @@
+import {
+  query,
+  type CanUseTool,
+  type ModelInfo,
+  type Options,
+} from '@anthropic-ai/claude-agent-sdk';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { BaseSdkProvider } from '@/modules/ai-runtime/providers/base/base-sdk.provider.js';
+import type {
+  IProviderAuthRuntime,
+  IProviderMcpRuntime,
+  IProviderSessionSynchronizerRuntime,
+  IProviderSkillsRuntime,
+  ProviderModel,
+  ProviderSessionEvent,
+  RuntimePermissionMode,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { ClaudeMcpRuntime } from '@/modules/ai-runtime/providers/claude/claude-mcp.runtime.js';
+import { ClaudeAuthRuntime } from '@/modules/ai-runtime/providers/claude/claude-auth.runtime.js';
+import { ClaudeSkillsRuntime } from '@/modules/ai-runtime/providers/claude/claude-skills.runtime.js';
+import { ClaudeSessionSynchronizerRuntime } from '@/modules/ai-runtime/providers/claude/claude-session-synchronizer.runtime.js';
+
+type ClaudeExecutionInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+  emitEvent?: (event: ProviderSessionEvent) => void;
+};
+
+const CLAUDE_THINKING_LEVELS = new Set(['low', 'medium', 'high', 'max']);
+const SUPPORTED_CLAUDE_IMAGE_TYPES = new Map<string, 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp'>([
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.png', 'image/png'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+]);
+
+type ClaudeUserPromptMessage = {
+  type: 'user';
+  message: {
+    role: 'user';
+    content: Array<
+      | {
+          type: 'text';
+          text: string;
+        }
+      | {
+          type: 'image';
+          source: {
+            type: 'base64';
+            media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+            data: string;
+          };
+        }
+    >;
+  };
+  parent_tool_use_id: null;
+  timestamp: string;
+};
+
+/**
+ * Safely reads one optional string value from unknown data.
+ */
+const readString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length ? normalized : undefined;
+};
+
+/**
+ * Claude SDK provider implementation.
+ */
+export class ClaudeProvider extends BaseSdkProvider {
+  readonly auth: IProviderAuthRuntime = new ClaudeAuthRuntime();
+  readonly mcp: IProviderMcpRuntime = new ClaudeMcpRuntime();
+  readonly skills: IProviderSkillsRuntime = new ClaudeSkillsRuntime();
+  readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime = new ClaudeSessionSynchronizerRuntime();
+
+  constructor() {
+    super('claude', {
+      supportsRuntimePermissionRequests: true,
+      supportsThinkingModeControl: true,
+    });
+  }
+
+  /**
+   * Retrieves available Claude models from the SDK.
+   */
+  async listModels(): Promise<ProviderModel[]> {
+    const probe = query({
+      prompt: 'model_probe',
+      options: {
+        permissionMode: 'plan',
+      },
+    });
+
+    try {
+      const models = await probe.supportedModels();
+      return models.map((model) => this.mapModelInfo(model));
+    } finally {
+      probe.close();
+    }
+  }
+
+  /**
+   * Creates a Claude SDK query execution for start/resume flows.
+   */
+  protected async createSdkExecution(input: ClaudeExecutionInput): Promise<{
+    stream: AsyncIterable<unknown>;
+    stop: () => Promise<boolean>;
+  }> {
+    const options: Options = {
+      cwd: input.workspacePath,
+      model: input.model,
+      effort: this.resolveClaudeEffort(input.thinkingMode),
+      canUseTool: this.resolvePermissionHandler(input.runtimePermissionMode, input.emitEvent),
+    };
+
+    if (input.isResume) {
+      options.resume = input.sessionId;
+    } else {
+      options.sessionId = input.sessionId;
+    }
+
+    const promptInput = await this.buildPromptInput(input.prompt, input.imagePaths, input.workspacePath);
+    const queryInstance = query({
+      prompt: promptInput as any,
+      options,
+    });
+
+    return {
+      stream: queryInstance,
+      stop: async () => {
+        await queryInstance.interrupt();
+        return true;
+      },
+    };
+  }
+
+  /**
+   * Builds a Claude prompt payload. When images are present, this returns an async iterable user message.
+   */
+  private async buildPromptInput(
+    prompt: string,
+    imagePaths?: string[],
+    workspacePath?: string,
+  ): Promise<string | AsyncIterable<ClaudeUserPromptMessage>> {
+    if (!imagePaths || imagePaths.length === 0) {
+      return prompt;
+    }
+
+    const content: ClaudeUserPromptMessage['message']['content'] = [
+      { type: 'text', text: prompt },
+    ];
+
+    for (const imagePath of imagePaths) {
+      const resolvedPath = path.isAbsolute(imagePath)
+        ? imagePath
+        : path.resolve(workspacePath ?? process.cwd(), imagePath);
+      const extension = path.extname(resolvedPath).toLowerCase();
+      const mediaType = SUPPORTED_CLAUDE_IMAGE_TYPES.get(extension);
+      if (!mediaType) {
+        continue;
+      }
+
+      const imageBytes = await readFile(resolvedPath);
+      content.push({
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: mediaType,
+          data: imageBytes.toString('base64'),
+        },
+      });
+    }
+
+    const sdkPrompt = (async function* (): AsyncIterable<ClaudeUserPromptMessage> {
+      yield {
+        type: 'user',
+        message: {
+          role: 'user',
+          content,
+        },
+        parent_tool_use_id: null,
+        timestamp: new Date().toISOString(),
+      };
+    })();
+
+    return sdkPrompt;
+  }
+
+  /**
+   * Produces compact event metadata for frontend stream rendering.
+   */
+  protected mapSdkEvent(rawEvent: unknown): ProviderSessionEvent | null {
+    if (typeof rawEvent !== 'object' || rawEvent === null) {
+      return {
+        timestamp: new Date().toISOString(),
+        channel: 'sdk',
+        message: String(rawEvent),
+      };
+    }
+
+    const messageType = this.getStringProperty(rawEvent, 'type');
+    const messageSubtype = this.getStringProperty(rawEvent, 'subtype');
+    const message = [messageType, messageSubtype].filter(Boolean).join(':') || 'claude_event';
+
+    return {
+      timestamp: new Date().toISOString(),
+      channel: 'sdk',
+      message,
+      data: rawEvent,
+    };
+  }
+
+  /**
+   * Normalizes Claude model metadata to the shared model shape.
+   */
+  private mapModelInfo(model: ModelInfo): ProviderModel {
+    return {
+      value: model.value,
+      displayName: model.displayName,
+      description: model.description,
+      supportsThinkingModes: Boolean(model.supportsEffort),
+      supportedThinkingModes: model.supportedEffortLevels,
+    };
+  }
+
+  /**
+   * Maps requested thinking mode to Claude effort levels.
+   */
+  private resolveClaudeEffort(thinkingMode?: string): Options['effort'] {
+    if (!thinkingMode) {
+      return 'high';
+    }
+
+    const normalized = thinkingMode.trim().toLowerCase();
+    if (CLAUDE_THINKING_LEVELS.has(normalized)) {
+      return normalized as Options['effort'];
+    }
+
+    return 'high';
+  }
+
+  /**
+   * Builds a runtime permission callback when explicit allow/deny is requested.
+   */
+  private resolvePermissionHandler(
+    mode?: RuntimePermissionMode,
+    emitEvent?: (event: ProviderSessionEvent) => void,
+  ): CanUseTool | undefined {
+    if (!mode || mode === 'ask') {
+      return undefined;
+    }
+
+    if (mode === 'allow') {
+      return async (toolName, input, options) => {
+        const optionsRecord = options as Record<string, unknown>;
+        emitEvent?.({
+          timestamp: new Date().toISOString(),
+          channel: 'system',
+          message: `Tool permission requested for "${toolName}".`,
+          data: {
+            type: 'tool_use_request',
+            toolName,
+            input,
+            toolUseID: options.toolUseID,
+            title: readString(optionsRecord.title),
+            displayName: readString(optionsRecord.displayName),
+            description: readString(optionsRecord.description),
+            blockedPath: options.blockedPath,
+          },
+        });
+        return { behavior: 'allow' };
+      };
+    }
+
+    return async (toolName, input, options) => {
+      const optionsRecord = options as Record<string, unknown>;
+      emitEvent?.({
+        timestamp: new Date().toISOString(),
+        channel: 'system',
+        message: `Tool permission denied for "${toolName}".`,
+        data: {
+          type: 'tool_use_request',
+          toolName,
+          input,
+          toolUseID: options.toolUseID,
+          title: readString(optionsRecord.title),
+          displayName: readString(optionsRecord.displayName),
+          description: readString(optionsRecord.description),
+          blockedPath: options.blockedPath,
+        },
+      });
+      return {
+        behavior: 'deny',
+        message: 'Permission denied by runtime permission mode.',
+        interrupt: false,
+      };
+    };
+  }
+
+  /**
+   * Reads one optional string property from an unknown event object.
+   */
+  private getStringProperty(value: unknown, key: string): string | undefined {
+    if (!value || typeof value !== 'object') {
+      return undefined;
+    }
+
+    const record = value as Record<string, unknown>;
+    const rawValue = record[key];
+    if (typeof rawValue !== 'string') {
+      return undefined;
+    }
+
+    return rawValue;
+  }
+}

server/src/modules/ai-runtime/providers/codex/codex-auth.runtime.ts

@@ -0,0 +1,88 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import type { IProviderAuthRuntime, ProviderAuthStatus } from '@/modules/ai-runtime/types/index.js';
+
+type CodexAuthFile = {
+  OPENAI_API_KEY?: string;
+  tokens?: {
+    id_token?: string;
+    access_token?: string;
+  };
+};
+
+/**
+ * Reads auth status from ~/.codex/auth.json.
+ */
+export class CodexAuthRuntime implements IProviderAuthRuntime {
+  async getStatus(): Promise<ProviderAuthStatus> {
+    try {
+      const authPath = path.join(os.homedir(), '.codex', 'auth.json');
+      const content = await readFile(authPath, 'utf8');
+      const auth = JSON.parse(content) as CodexAuthFile;
+      const tokens = auth.tokens ?? {};
+
+      if (tokens.id_token || tokens.access_token) {
+        return {
+          provider: 'codex',
+          authenticated: true,
+          email: this.extractEmail(tokens.id_token),
+          method: 'token_file',
+        };
+      }
+
+      if (auth.OPENAI_API_KEY?.trim()) {
+        return {
+          provider: 'codex',
+          authenticated: true,
+          email: 'API Key Auth',
+          method: 'api_key',
+        };
+      }
+
+      return {
+        provider: 'codex',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'No valid tokens found',
+      };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      return {
+        provider: 'codex',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: code === 'ENOENT'
+          ? 'Codex not configured'
+          : (error instanceof Error ? error.message : 'Failed to read Codex auth state'),
+      };
+    }
+  }
+
+  /**
+   * Best-effort id_token email extraction from JWT payload.
+   */
+  private extractEmail(idToken: string | undefined): string {
+    if (!idToken) {
+      return 'Authenticated';
+    }
+
+    try {
+      const parts = idToken.split('.');
+      if (parts.length < 2) {
+        return 'Authenticated';
+      }
+
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) as {
+        email?: string;
+        user?: string;
+      };
+      return payload.email ?? payload.user ?? 'Authenticated';
+    } catch {
+      return 'Authenticated';
+    }
+  }
+}

server/src/modules/ai-runtime/providers/codex/codex-mcp.runtime.ts

@@ -0,0 +1,133 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import type {
+  McpScope,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { BaseProviderMcpRuntime } from '@/modules/ai-runtime/providers/shared/mcp/base-provider-mcp.runtime.js';
+import {
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  readTomlConfig,
+  writeTomlConfig,
+} from '@/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.js';
+
+/**
+ * Codex MCP runtime backed by user/project `.codex/config.toml`.
+ */
+export class CodexMcpRuntime extends BaseProviderMcpRuntime {
+  constructor() {
+    super('codex', ['user', 'project'], ['stdio', 'http']);
+  }
+
+  /**
+   * Reads Codex MCP servers from user/project config.toml scopes.
+   */
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.codex', 'config.toml')
+      : path.join(workspacePath, '.codex', 'config.toml');
+    const config = await readTomlConfig(filePath);
+    return readObjectRecord(config.mcp_servers) ?? {};
+  }
+
+  /**
+   * Writes Codex MCP servers to user/project config.toml scopes.
+   */
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.codex', 'config.toml')
+      : path.join(workspacePath, '.codex', 'config.toml');
+    const config = await readTomlConfig(filePath);
+    config.mcp_servers = servers;
+    await writeTomlConfig(filePath, config);
+  }
+
+  /**
+   * Builds one Codex-native server object from the unified input payload.
+   */
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        env_vars: input.envVars ?? [],
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      url: input.url,
+      bearer_token_env_var: input.bearerTokenEnvVar,
+      http_headers: input.headers ?? {},
+      env_http_headers: input.envHttpHeaders ?? {},
+    };
+  }
+
+  /**
+   * Normalizes one Codex server object.
+   */
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'codex',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+        envVars: readStringArray(config.env_vars),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      return {
+        provider: 'codex',
+        name,
+        scope,
+        transport: 'http',
+        url: config.url,
+        headers: readStringRecord(config.http_headers),
+        bearerTokenEnvVar: readOptionalString(config.bearer_token_env_var),
+        envHttpHeaders: readStringRecord(config.env_http_headers),
+      };
+    }
+
+    return null;
+  }
+}

server/src/modules/ai-runtime/providers/codex/codex-session-synchronizer.runtime.ts

@@ -0,0 +1,113 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import {
+  buildLookupMap,
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/modules/ai-runtime/providers/shared/session-synchronizer/session-synchronizer.utils.js';
+import type { IProviderSessionSynchronizerRuntime } from '@/modules/ai-runtime/types/index.js';
+
+type ParsedSession = {
+  sessionId: string;
+  workspacePath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Codex transcript artifacts.
+ */
+export class CodexSessionSynchronizerRuntime implements IProviderSessionSynchronizerRuntime {
+  private readonly provider = 'codex' as const;
+  private readonly codexHome = path.join(os.homedir(), '.codex');
+
+  /**
+   * Scans ~/.codex sessions and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const nameMap = await buildLookupMap(path.join(this.codexHome, 'session_index.jsonl'), 'id', 'thread_name');
+    const files = await findFilesRecursivelyCreatedAfter(
+      path.join(this.codexHome, 'sessions'),
+      '.jsonl',
+      since ?? null,
+    );
+
+    let processed = 0;
+    for (const filePath of files) {
+      const parsed = await this.processSessionFile(filePath, nameMap);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.workspacePath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath,
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Codex session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<boolean> {
+    if (!filePath.endsWith('.jsonl')) {
+      return false;
+    }
+
+    const nameMap = await buildLookupMap(path.join(this.codexHome, 'session_index.jsonl'), 'id', 'thread_name');
+    const parsed = await this.processSessionFile(filePath, nameMap);
+    if (!parsed) {
+      return false;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.workspacePath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath,
+    );
+
+    return true;
+  }
+
+  /**
+   * Extracts session metadata from one Codex JSONL session file.
+   */
+  private async processSessionFile(
+    filePath: string,
+    nameMap: Map<string, string>,
+  ): Promise<ParsedSession | null> {
+    return extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, unknown>;
+      const payload = data.payload as Record<string, unknown> | undefined;
+      const sessionId = typeof payload?.id === 'string' ? payload.id : undefined;
+      const workspacePath = typeof payload?.cwd === 'string' ? payload.cwd : undefined;
+
+      if (!sessionId || !workspacePath) {
+        return null;
+      }
+
+      return {
+        sessionId,
+        workspacePath,
+        sessionName: normalizeSessionName(nameMap.get(sessionId), 'Untitled Codex Session'),
+      };
+    });
+  }
+}

server/src/modules/ai-runtime/providers/codex/codex-skills.runtime.ts

@@ -0,0 +1,47 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import type { IProviderSkillsRuntime, ProviderSkill, ProviderSkillScope } from '@/modules/ai-runtime/types/index.js';
+import {
+  deduplicateDirectories,
+  deduplicateSkills,
+  findGitRepoRoot,
+  listSkillsFromDirectory,
+} from '@/modules/ai-runtime/providers/shared/skills/skills-runtime.utils.js';
+
+/**
+ * Codex skills runtime backed by repo/user/admin/system skill directories.
+ */
+export class CodexSkillsRuntime implements IProviderSkillsRuntime {
+  /**
+   * Lists all available Codex skills from documented directories.
+   */
+  async listSkills(options?: { workspacePath?: string }): Promise<ProviderSkill[]> {
+    const workspacePath = path.resolve(options?.workspacePath ?? process.cwd());
+    const home = os.homedir();
+    const repoRoot = await findGitRepoRoot(workspacePath);
+    const candidateDirectories: Array<{ scope: ProviderSkillScope; directory: string }> = [
+      { scope: 'repo', directory: path.join(workspacePath, '.agents', 'skills') },
+      { scope: 'repo', directory: path.join(workspacePath, '..', '.agents', 'skills') },
+      { scope: 'user', directory: path.join(home, '.agents', 'skills') },
+      { scope: 'admin', directory: path.join(path.sep, 'etc', 'codex', 'skills') },
+      { scope: 'system', directory: path.join(home, '.codex', 'skills', '.system') },
+    ];
+    if (repoRoot) {
+      candidateDirectories.push({ scope: 'repo', directory: path.join(repoRoot, '.agents', 'skills') });
+    }
+
+    const skills: ProviderSkill[] = [];
+    for (const candidate of deduplicateDirectories(candidateDirectories)) {
+      const loadedSkills = await listSkillsFromDirectory({
+        provider: 'codex',
+        scope: candidate.scope,
+        skillsDirectory: candidate.directory,
+        invocationPrefix: '$',
+      });
+      skills.push(...loadedSkills);
+    }
+
+    return deduplicateSkills(skills);
+  }
+}

server/src/modules/ai-runtime/providers/codex/codex.provider.ts

@@ -0,0 +1,241 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { BaseSdkProvider } from '@/modules/ai-runtime/providers/base/base-sdk.provider.js';
+import type {
+  IProviderAuthRuntime,
+  IProviderMcpRuntime,
+  IProviderSessionSynchronizerRuntime,
+  IProviderSkillsRuntime,
+  ProviderModel,
+  ProviderSessionEvent,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { CodexMcpRuntime } from '@/modules/ai-runtime/providers/codex/codex-mcp.runtime.js';
+import { CodexAuthRuntime } from '@/modules/ai-runtime/providers/codex/codex-auth.runtime.js';
+import { CodexSkillsRuntime } from '@/modules/ai-runtime/providers/codex/codex-skills.runtime.js';
+import { CodexSessionSynchronizerRuntime } from '@/modules/ai-runtime/providers/codex/codex-session-synchronizer.runtime.js';
+import { AppError } from '@/shared/utils/app-error.js';
+
+type CodexExecutionInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+};
+
+type CodexModelCacheEntry = {
+  slug?: string;
+  display_name?: string;
+  description?: string;
+  supported_reasoning_levels?: Array<{
+    effort?: string;
+    description?: string;
+  }>;
+  priority?: number;
+};
+
+type CodexSdkClient = {
+  startThread: (options?: Record<string, unknown>) => CodexThread;
+  resumeThread: (sessionId: string, options?: Record<string, unknown>) => CodexThread;
+};
+
+type CodexThread = {
+  runStreamed: (
+    prompt:
+      | string
+      | Array<
+          | {
+              type: 'text';
+              text: string;
+            }
+          | {
+              type: 'local_image';
+              path: string;
+            }
+        >,
+    options?: {
+      signal?: AbortSignal;
+    },
+  ) => Promise<{
+    events: AsyncIterable<unknown>;
+  }>;
+};
+
+type CodexSdkModule = {
+  Codex: new () => CodexSdkClient;
+};
+
+/**
+ * Codex SDK provider implementation.
+ */
+export class CodexProvider extends BaseSdkProvider {
+  readonly auth: IProviderAuthRuntime = new CodexAuthRuntime();
+  readonly mcp: IProviderMcpRuntime = new CodexMcpRuntime();
+  readonly skills: IProviderSkillsRuntime = new CodexSkillsRuntime();
+  readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime = new CodexSessionSynchronizerRuntime();
+
+  private codexClientPromise: Promise<CodexSdkClient> | null = null;
+
+  constructor() {
+    super('codex', {
+      supportsRuntimePermissionRequests: false,
+      supportsThinkingModeControl: true,
+    });
+  }
+
+  /**
+   * Reads codex models from ~/.codex/models_cache.json.
+   */
+  async listModels(): Promise<ProviderModel[]> {
+    const modelCachePath = path.join(os.homedir(), '.codex', 'models_cache.json');
+    let content: string;
+    try {
+      content = await readFile(modelCachePath, 'utf8');
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code === 'ENOENT') {
+        throw new AppError('Codex model cache was not found. Expected ~/.codex/models_cache.json.', {
+          code: 'CODEX_MODEL_CACHE_NOT_FOUND',
+          statusCode: 404,
+        });
+      }
+
+      throw error;
+    }
+
+    const parsed = JSON.parse(content) as { models?: CodexModelCacheEntry[] };
+
+    const models = parsed.models ?? [];
+    return models
+      .filter((entry) => Boolean(entry.slug))
+      .map((entry) => ({
+        value: entry.slug as string,
+        displayName: entry.display_name ?? entry.slug ?? 'unknown',
+        description: entry.description,
+        default: entry.priority === 1,
+        supportsThinkingModes: Boolean(entry.supported_reasoning_levels?.length),
+        supportedThinkingModes: entry.supported_reasoning_levels
+          ?.map((level) => level.effort)
+          .filter((effort): effort is string => typeof effort === 'string'),
+      }));
+  }
+
+  /**
+   * Creates a Codex thread execution and wires abort support.
+   */
+  protected async createSdkExecution(input: CodexExecutionInput): Promise<{
+    stream: AsyncIterable<unknown>;
+    stop: () => Promise<boolean>;
+  }> {
+    const client = await this.getCodexClient();
+
+    const threadOptions: Record<string, unknown> = {
+      model: input.model,
+      workingDirectory: input.workspacePath,
+      modelReasoningEffort: input.thinkingMode,
+    };
+
+    const thread = input.isResume
+      ? client.resumeThread(input.sessionId, threadOptions)
+      : client.startThread(threadOptions);
+
+    const abortController = new AbortController();
+    const promptInput = this.buildPromptInput(input.prompt, input.imagePaths, input.workspacePath);
+    const streamedTurn = await thread.runStreamed(promptInput, {
+      signal: abortController.signal,
+    });
+
+    return {
+      stream: streamedTurn.events,
+      stop: async () => {
+        abortController.abort('Session stop requested');
+        return true;
+      },
+    };
+  }
+
+  /**
+   * Returns a shared Codex SDK client instance for this provider.
+   */
+  private async getCodexClient(): Promise<CodexSdkClient> {
+    if (!this.codexClientPromise) {
+      this.codexClientPromise = this.loadCodexSdkModule()
+        .then((sdkModule) => new sdkModule.Codex())
+        .catch((error) => {
+          this.codexClientPromise = null;
+          throw error;
+        });
+    }
+
+    return this.codexClientPromise;
+  }
+
+  /**
+   * Builds Codex prompt items. Images are sent as `local_image` entries for SDK-native image support.
+   */
+  private buildPromptInput(
+    prompt: string,
+    imagePaths?: string[],
+    workspacePath?: string,
+  ): string | Array<{ type: 'text'; text: string } | { type: 'local_image'; path: string }> {
+    if (!imagePaths || imagePaths.length === 0) {
+      return prompt;
+    }
+
+    const resolvedImagePaths = imagePaths.map((imagePath) => (
+      path.isAbsolute(imagePath)
+        ? imagePath
+        : path.resolve(workspacePath ?? process.cwd(), imagePath)
+    ));
+
+    return [
+      { type: 'text', text: prompt },
+      ...resolvedImagePaths.map((resolvedPath) => ({
+        type: 'local_image' as const,
+        path: resolvedPath,
+      })),
+    ];
+  }
+
+  /**
+   * Normalizes Codex stream events into the shared event shape.
+   */
+  protected mapSdkEvent(rawEvent: unknown): ProviderSessionEvent | null {
+    if (typeof rawEvent !== 'object' || rawEvent === null) {
+      return {
+        timestamp: new Date().toISOString(),
+        channel: 'sdk',
+        message: String(rawEvent),
+      };
+    }
+
+    const record = rawEvent as Record<string, unknown>;
+    const message = typeof record.type === 'string' ? record.type : 'codex_event';
+
+    return {
+      timestamp: new Date().toISOString(),
+      channel: 'sdk',
+      message,
+      data: rawEvent,
+    };
+  }
+
+  /**
+   * Dynamically imports the Codex SDK to support environments where it is optional.
+   */
+  private async loadCodexSdkModule(): Promise<CodexSdkModule> {
+    try {
+      const sdkModule = (await import('@openai/codex-sdk')) as unknown as CodexSdkModule;
+      if (!sdkModule?.Codex) {
+        throw new Error('Codex SDK did not export "Codex".');
+      }
+      return sdkModule;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to import Codex SDK';
+      throw new AppError(`Codex SDK is unavailable: ${message}`, {
+        code: 'CODEX_SDK_UNAVAILABLE',
+        statusCode: 503,
+      });
+    }
+  }
+}

server/src/modules/ai-runtime/providers/cursor/cursor-auth.runtime.ts

@@ -0,0 +1,126 @@
+import spawn from 'cross-spawn';
+
+import type { IProviderAuthRuntime, ProviderAuthStatus } from '@/modules/ai-runtime/types/index.js';
+
+const CURSOR_STATUS_TIMEOUT_MS = 5_000;
+
+/**
+ * Reads auth status from `cursor-agent status`.
+ */
+export class CursorAuthRuntime implements IProviderAuthRuntime {
+  async getStatus(): Promise<ProviderAuthStatus> {
+    return new Promise((resolve) => {
+      let completed = false;
+      let childProcess: ReturnType<typeof spawn> | null = null;
+      const timeout = setTimeout(() => {
+        if (completed) {
+          return;
+        }
+
+        completed = true;
+        if (childProcess) {
+          childProcess.kill();
+        }
+
+        resolve({
+          provider: 'cursor',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Command timeout',
+        });
+      }, CURSOR_STATUS_TIMEOUT_MS);
+
+      try {
+        childProcess = spawn('cursor-agent', ['status']);
+      } catch {
+        clearTimeout(timeout);
+        completed = true;
+        resolve({
+          provider: 'cursor',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Cursor CLI not found or not installed',
+        });
+        return;
+      }
+
+      let stdout = '';
+      let stderr = '';
+
+      childProcess.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+
+      childProcess.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+      });
+
+      childProcess.on('close', (code) => {
+        if (completed) {
+          return;
+        }
+
+        completed = true;
+        clearTimeout(timeout);
+
+        if (code === 0) {
+          const emailMatch = stdout.match(/Logged in as ([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i);
+          if (emailMatch) {
+            resolve({
+              provider: 'cursor',
+              authenticated: true,
+              email: emailMatch[1],
+              method: null,
+            });
+            return;
+          }
+
+          if (stdout.includes('Logged in')) {
+            resolve({
+              provider: 'cursor',
+              authenticated: true,
+              email: 'Logged in',
+              method: null,
+            });
+            return;
+          }
+
+          resolve({
+            provider: 'cursor',
+            authenticated: false,
+            email: null,
+            method: null,
+            error: 'Not logged in',
+          });
+          return;
+        }
+
+        resolve({
+          provider: 'cursor',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: stderr.trim() || 'Not logged in',
+        });
+      });
+
+      childProcess.on('error', () => {
+        if (completed) {
+          return;
+        }
+
+        completed = true;
+        clearTimeout(timeout);
+        resolve({
+          provider: 'cursor',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Cursor CLI not found or not installed',
+        });
+      });
+    });
+  }
+}

server/src/modules/ai-runtime/providers/cursor/cursor-mcp.runtime.ts

@@ -0,0 +1,127 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import type {
+  McpScope,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { BaseProviderMcpRuntime } from '@/modules/ai-runtime/providers/shared/mcp/base-provider-mcp.runtime.js';
+import {
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.js';
+
+/**
+ * Cursor MCP runtime backed by user/project `.cursor/mcp.json`.
+ */
+export class CursorMcpRuntime extends BaseProviderMcpRuntime {
+  constructor() {
+    super('cursor', ['user', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  /**
+   * Reads Cursor MCP servers from user/project config files.
+   */
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.cursor', 'mcp.json')
+      : path.join(workspacePath, '.cursor', 'mcp.json');
+    const config = await readJsonConfig(filePath);
+    return readObjectRecord(config.mcpServers) ?? {};
+  }
+
+  /**
+   * Writes Cursor MCP servers to user/project config files.
+   */
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.cursor', 'mcp.json')
+      : path.join(workspacePath, '.cursor', 'mcp.json');
+    const config = await readJsonConfig(filePath);
+    config.mcpServers = servers;
+    await writeJsonConfig(filePath, config);
+  }
+
+  /**
+   * Builds one Cursor-native server object from the unified input payload.
+   */
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  /**
+   * Normalizes one Cursor server object.
+   */
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'cursor',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      return {
+        provider: 'cursor',
+        name,
+        scope,
+        transport: 'http',
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/src/modules/ai-runtime/providers/cursor/cursor-session-synchronizer.runtime.ts

@@ -0,0 +1,165 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import {
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  listDirectoryEntriesSafe,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/modules/ai-runtime/providers/shared/session-synchronizer/session-synchronizer.utils.js';
+import type { IProviderSessionSynchronizerRuntime } from '@/modules/ai-runtime/types/index.js';
+
+type ParsedSession = {
+  sessionId: string;
+  workspacePath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Cursor transcript artifacts.
+ */
+export class CursorSessionSynchronizerRuntime implements IProviderSessionSynchronizerRuntime {
+  private readonly provider = 'cursor' as const;
+  private readonly cursorHome = path.join(os.homedir(), '.cursor');
+
+  /**
+   * Scans Cursor chats and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const projectsDir = path.join(this.cursorHome, 'projects');
+    const projectEntries = await listDirectoryEntriesSafe(projectsDir);
+    const seenWorkspacePaths = new Set<string>();
+
+    let processed = 0;
+    for (const entry of projectEntries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const workerLogPath = path.join(projectsDir, entry.name, 'worker.log');
+      const workspacePath = await this.extractWorkspacePathFromWorkerLog(workerLogPath);
+      if (!workspacePath || seenWorkspacePaths.has(workspacePath)) {
+        continue;
+      }
+
+      seenWorkspacePaths.add(workspacePath);
+      const workspaceHash = this.md5(workspacePath);
+      const chatsDir = path.join(this.cursorHome, 'chats', workspaceHash);
+      const files = await findFilesRecursivelyCreatedAfter(chatsDir, '.jsonl', since ?? null);
+
+      for (const filePath of files) {
+        const parsed = await this.processSessionFile(filePath);
+        if (!parsed) {
+          continue;
+        }
+
+        const timestamps = await readFileTimestamps(filePath);
+        sessionsDb.createSession(
+          parsed.sessionId,
+          this.provider,
+          parsed.workspacePath,
+          parsed.sessionName,
+          timestamps.createdAt,
+          timestamps.updatedAt,
+          filePath,
+        );
+        processed += 1;
+      }
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Cursor session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<boolean> {
+    if (!filePath.endsWith('.jsonl')) {
+      return false;
+    }
+
+    const parsed = await this.processSessionFile(filePath);
+    if (!parsed) {
+      return false;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.workspacePath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath,
+    );
+
+    return true;
+  }
+
+  /**
+   * Produces the same workspace hash Cursor uses in chat directory names.
+   */
+  private md5(input: string): string {
+    return crypto.createHash('md5').update(input).digest('hex');
+  }
+
+  /**
+   * Extracts workspace path from Cursor worker.log.
+   */
+  private async extractWorkspacePathFromWorkerLog(filePath: string): Promise<string | null> {
+    try {
+      const fileStream = fs.createReadStream(filePath, { encoding: 'utf8' });
+      const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+      for await (const line of lineReader) {
+        const match = line.match(/workspacePath=(.*)$/);
+        const workspacePath = match?.[1]?.trim();
+        if (workspacePath) {
+          lineReader.close();
+          fileStream.close();
+          return workspacePath;
+        }
+      }
+    } catch {
+      // Missing worker logs are valid for partial/incomplete session data.
+    }
+
+    return null;
+  }
+
+  /**
+   * Extracts session metadata from one Cursor JSONL session file.
+   */
+  private async processSessionFile(filePath: string): Promise<ParsedSession | null> {
+    const sessionId = path.basename(filePath, '.jsonl');
+    const grandparentDir = path.dirname(path.dirname(filePath));
+    const workerLogPath = path.join(grandparentDir, 'worker.log');
+    const workspacePath = await this.extractWorkspacePathFromWorkerLog(workerLogPath);
+
+    if (!workspacePath) {
+      return null;
+    }
+
+    return extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, any>;
+      if (data.role !== 'user') {
+        return null;
+      }
+
+      const text = typeof data.message?.content?.[0]?.text === 'string' ? data.message.content[0].text : '';
+      const firstLine = text.replace(/<\/?user_query>/g, '').trim().split('\n')[0];
+
+      return {
+        sessionId,
+        workspacePath,
+        sessionName: normalizeSessionName(firstLine, 'Untitled Cursor Session'),
+      };
+    });
+  }
+}

server/src/modules/ai-runtime/providers/cursor/cursor-skills.runtime.ts

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import type { IProviderSkillsRuntime, ProviderSkill, ProviderSkillScope } from '@/modules/ai-runtime/types/index.js';
+import {
+  deduplicateDirectories,
+  deduplicateSkills,
+  listSkillsFromDirectory,
+} from '@/modules/ai-runtime/providers/shared/skills/skills-runtime.utils.js';
+
+/**
+ * Cursor skills runtime backed by user/project skill directories.
+ */
+export class CursorSkillsRuntime implements IProviderSkillsRuntime {
+  /**
+   * Lists all available Cursor skills from documented directories.
+   */
+  async listSkills(options?: { workspacePath?: string }): Promise<ProviderSkill[]> {
+    const workspacePath = path.resolve(options?.workspacePath ?? process.cwd());
+    const home = os.homedir();
+    const candidateDirectories: Array<{ scope: ProviderSkillScope; directory: string }> = [
+      { scope: 'project', directory: path.join(workspacePath, '.agents', 'skills') },
+      { scope: 'project', directory: path.join(workspacePath, '.cursor', 'skills') },
+      { scope: 'user', directory: path.join(home, '.cursor', 'skills') },
+    ];
+
+    const skills: ProviderSkill[] = [];
+    for (const candidate of deduplicateDirectories(candidateDirectories)) {
+      const loadedSkills = await listSkillsFromDirectory({
+        provider: 'cursor',
+        scope: candidate.scope,
+        skillsDirectory: candidate.directory,
+        invocationPrefix: '/',
+      });
+      skills.push(...loadedSkills);
+    }
+
+    return deduplicateSkills(skills);
+  }
+}

server/src/modules/ai-runtime/providers/cursor/cursor.provider.ts

@@ -0,0 +1,137 @@
+import { BaseCliProvider } from '@/modules/ai-runtime/providers/base/base-cli.provider.js';
+import type {
+  IProviderAuthRuntime,
+  IProviderMcpRuntime,
+  IProviderSessionSynchronizerRuntime,
+  IProviderSkillsRuntime,
+  ProviderModel,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { CursorMcpRuntime } from '@/modules/ai-runtime/providers/cursor/cursor-mcp.runtime.js';
+import { CursorAuthRuntime } from '@/modules/ai-runtime/providers/cursor/cursor-auth.runtime.js';
+import { CursorSkillsRuntime } from '@/modules/ai-runtime/providers/cursor/cursor-skills.runtime.js';
+import { CursorSessionSynchronizerRuntime } from '@/modules/ai-runtime/providers/cursor/cursor-session-synchronizer.runtime.js';
+
+type CursorExecutionInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+};
+
+const ANSI_REGEX =
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping.
+  /\u001b\[[0-9;]*m/g;
+
+/**
+ * Cursor CLI provider implementation.
+ */
+export class CursorProvider extends BaseCliProvider {
+  readonly auth: IProviderAuthRuntime = new CursorAuthRuntime();
+  readonly mcp: IProviderMcpRuntime = new CursorMcpRuntime();
+  readonly skills: IProviderSkillsRuntime = new CursorSkillsRuntime();
+  readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime = new CursorSessionSynchronizerRuntime();
+
+  constructor() {
+    super('cursor', {
+      supportsRuntimePermissionRequests: false,
+      supportsThinkingModeControl: false,
+    });
+  }
+
+  /**
+   * Lists cursor models by parsing `cursor-agent --list-models`.
+   */
+  async listModels(): Promise<ProviderModel[]> {
+    const output = await this.runCommandForOutput('cursor-agent', ['--list-models']);
+    return this.parseModelsOutput(output);
+  }
+
+  /**
+   * Creates the command invocation for cursor start/resume flows.
+   */
+  protected createCliInvocation(input: CursorExecutionInput): {
+    command: string;
+    args: string[];
+    cwd?: string;
+  } {
+    const promptWithImagePaths = this.appendImagePathsToPrompt(input.prompt, input.imagePaths);
+    const args = ['--print', '--trust', '--output-format', 'stream-json'];
+
+    if (input.allowYolo) {
+      args.push('--yolo');
+    }
+
+    if (input.model) {
+      args.push('--model', input.model);
+    }
+
+    if (input.isResume) {
+      args.push('--resume', input.sessionId);
+    }
+
+    args.push(promptWithImagePaths);
+
+    return {
+      command: 'cursor-agent',
+      args,
+      cwd: input.workspacePath,
+    };
+  }
+
+  /**
+   * Parses full model-list output into normalized model entries.
+   */
+  private parseModelsOutput(output: string): ProviderModel[] {
+    const models: ProviderModel[] = [];
+    const lines = output.replace(ANSI_REGEX, '').split(/\r?\n/);
+
+    for (const line of lines) {
+      const parsed = this.parseModelLine(line);
+      if (!parsed) {
+        continue;
+      }
+      models.push(parsed);
+    }
+
+    return models;
+  }
+
+  /**
+   * Parses one cursor model line.
+   */
+  private parseModelLine(line: string): ProviderModel | null {
+    const trimmed = line.trim();
+    if (
+      !trimmed ||
+      trimmed === 'Available models' ||
+      trimmed.startsWith('Loading models') ||
+      trimmed.startsWith('Tip:')
+    ) {
+      return null;
+    }
+
+    const match = trimmed.match(/^(.+?)\s+-\s+(.+)$/);
+    if (!match) {
+      return null;
+    }
+
+    const value = match[1].trim();
+    const descriptionRaw = match[2].trim();
+
+    const current = /\(current\)/i.test(descriptionRaw);
+    const defaultModel = /\(default\)/i.test(descriptionRaw);
+    const description = descriptionRaw
+      .replace(/\s*\((current|default)\)/gi, '')
+      .replace(/\s{2,}/g, ' ')
+      .trim();
+
+    return {
+      value,
+      displayName: value,
+      description,
+      current,
+      default: defaultModel,
+      supportsThinkingModes: false,
+      supportedThinkingModes: [],
+    };
+  }
+}

server/src/modules/ai-runtime/providers/gemini/gemini-auth.runtime.ts

@@ -0,0 +1,115 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import type { IProviderAuthRuntime, ProviderAuthStatus } from '@/modules/ai-runtime/types/index.js';
+
+type GeminiOauthCreds = {
+  access_token?: string;
+  refresh_token?: string;
+};
+
+/**
+ * Reads auth status from env and Gemini OAuth files.
+ */
+export class GeminiAuthRuntime implements IProviderAuthRuntime {
+  async getStatus(): Promise<ProviderAuthStatus> {
+    if (process.env.GEMINI_API_KEY?.trim()) {
+      return {
+        provider: 'gemini',
+        authenticated: true,
+        email: 'API Key Auth',
+        method: 'api_key',
+      };
+    }
+
+    try {
+      const credsPath = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
+      const content = await readFile(credsPath, 'utf8');
+      const creds = JSON.parse(content) as GeminiOauthCreds;
+      if (!creds.access_token) {
+        return {
+          provider: 'gemini',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'No valid tokens found in oauth_creds',
+        };
+      }
+
+      const validated = await this.resolveEmailFromAccessToken(creds.access_token);
+      if (validated.email) {
+        return {
+          provider: 'gemini',
+          authenticated: true,
+          email: validated.email,
+          method: 'oauth',
+        };
+      }
+
+      if (!validated.tokenValid && !creds.refresh_token) {
+        return {
+          provider: 'gemini',
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Access token invalid and no refresh token found',
+        };
+      }
+
+      const fallbackEmail = await this.readActiveGoogleAccountEmail();
+      return {
+        provider: 'gemini',
+        authenticated: true,
+        email: fallbackEmail ?? 'OAuth Session',
+        method: 'oauth',
+      };
+    } catch {
+      return {
+        provider: 'gemini',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Gemini CLI not configured',
+      };
+    }
+  }
+
+  /**
+   * Validates token and extracts email via Google's tokeninfo endpoint.
+   */
+  private async resolveEmailFromAccessToken(
+    accessToken: string,
+  ): Promise<{ tokenValid: boolean; email: string | null }> {
+    try {
+      const response = await fetch(`https://oauth2.googleapis.com/tokeninfo?access_token=${accessToken}`);
+      if (!response.ok) {
+        return { tokenValid: false, email: null };
+      }
+
+      const tokenInfo = await response.json() as { email?: string };
+      return {
+        tokenValid: true,
+        email: tokenInfo.email ?? null,
+      };
+    } catch {
+      return { tokenValid: false, email: null };
+    }
+  }
+
+  /**
+   * Reads active Google account email from ~/.gemini/google_accounts.json.
+   */
+  private async readActiveGoogleAccountEmail(): Promise<string | null> {
+    try {
+      const accountsPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
+      const content = await readFile(accountsPath, 'utf8');
+      const accounts = JSON.parse(content) as { active?: string };
+      return typeof accounts.active === 'string' && accounts.active.trim()
+        ? accounts.active
+        : null;
+    } catch {
+      return null;
+    }
+  }
+}

server/src/modules/ai-runtime/providers/gemini/gemini-mcp.runtime.ts

@@ -0,0 +1,129 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import type {
+  McpScope,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { BaseProviderMcpRuntime } from '@/modules/ai-runtime/providers/shared/mcp/base-provider-mcp.runtime.js';
+import {
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.js';
+
+/**
+ * Gemini MCP runtime backed by user/project `.gemini/settings.json`.
+ */
+export class GeminiMcpRuntime extends BaseProviderMcpRuntime {
+  constructor() {
+    super('gemini', ['user', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  /**
+   * Reads Gemini MCP servers from user/project config files.
+   */
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.gemini', 'settings.json')
+      : path.join(workspacePath, '.gemini', 'settings.json');
+    const config = await readJsonConfig(filePath);
+    return readObjectRecord(config.mcpServers) ?? {};
+  }
+
+  /**
+   * Writes Gemini MCP servers to user/project config files.
+   */
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.gemini', 'settings.json')
+      : path.join(workspacePath, '.gemini', 'settings.json');
+    const config = await readJsonConfig(filePath);
+    config.mcpServers = servers;
+    await writeJsonConfig(filePath, config);
+  }
+
+  /**
+   * Builds one Gemini-native server object from the unified input payload.
+   */
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: input.transport,
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  /**
+   * Normalizes one Gemini server object.
+   */
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'gemini',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      const transport = readOptionalString(config.type) === 'sse' ? 'sse' : 'http';
+      return {
+        provider: 'gemini',
+        name,
+        scope,
+        transport,
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/src/modules/ai-runtime/providers/gemini/gemini-session-synchronizer.runtime.ts

@@ -0,0 +1,162 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import {
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/modules/ai-runtime/providers/shared/session-synchronizer/session-synchronizer.utils.js';
+import type { IProviderSessionSynchronizerRuntime } from '@/modules/ai-runtime/types/index.js';
+
+type ParsedSession = {
+  sessionId: string;
+  workspacePath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Gemini transcript artifacts.
+ */
+export class GeminiSessionSynchronizerRuntime implements IProviderSessionSynchronizerRuntime {
+  private readonly provider = 'gemini' as const;
+  private readonly geminiHome = path.join(os.homedir(), '.gemini');
+
+  /**
+   * Scans Gemini session JSON files and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const legacySessionFiles = await findFilesRecursivelyCreatedAfter(
+      path.join(this.geminiHome, 'sessions'),
+      '.json',
+      since ?? null,
+    );
+    const tempFiles = await findFilesRecursivelyCreatedAfter(
+      path.join(this.geminiHome, 'tmp'),
+      '.json',
+      since ?? null,
+    );
+    const files = [...legacySessionFiles, ...tempFiles];
+
+    let processed = 0;
+    for (const filePath of files) {
+      if (
+        filePath.startsWith(path.join(this.geminiHome, 'tmp')) &&
+        !filePath.includes(`${path.sep}chats${path.sep}`)
+      ) {
+        continue;
+      }
+
+      const parsed = await this.processSessionFile(filePath);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.workspacePath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath,
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Gemini session JSON file.
+   */
+  async synchronizeFile(filePath: string): Promise<boolean> {
+    if (!filePath.endsWith('.json')) {
+      return false;
+    }
+
+    if (
+      filePath.startsWith(path.join(this.geminiHome, 'tmp')) &&
+      !filePath.includes(`${path.sep}chats${path.sep}`)
+    ) {
+      return false;
+    }
+
+    const parsed = await this.processSessionFile(filePath);
+    if (!parsed) {
+      return false;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.workspacePath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath,
+    );
+
+    return true;
+  }
+
+  /**
+   * Extracts session metadata from one Gemini JSON artifact.
+   */
+  private async processSessionFile(filePath: string): Promise<ParsedSession | null> {
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const data = JSON.parse(content) as Record<string, any>;
+
+      const sessionId =
+        typeof data.sessionId === 'string'
+          ? data.sessionId
+          : typeof data.id === 'string'
+            ? data.id
+            : undefined;
+      if (!sessionId) {
+        return null;
+      }
+
+      let workspacePath = typeof data.projectPath === 'string' ? data.projectPath : '';
+
+      if (!workspacePath && filePath.includes(`${path.sep}chats${path.sep}`)) {
+        const chatsDir = path.dirname(filePath);
+        const workspaceDir = path.dirname(chatsDir);
+        const projectRootPath = path.join(workspaceDir, '.project_root');
+
+        try {
+          const rootContent = await readFile(projectRootPath, 'utf8');
+          workspacePath = rootContent.trim();
+        } catch {
+          // Some Gemini artifacts do not ship a .project_root marker.
+        }
+      }
+
+      if (!workspacePath) {
+        return null;
+      }
+
+      const messages = Array.isArray(data.messages) ? data.messages : [];
+      const firstMessage = messages[0] as Record<string, any> | undefined;
+      let rawName: string | undefined;
+
+      if (Array.isArray(firstMessage?.content) && typeof firstMessage.content[0]?.text === 'string') {
+        rawName = firstMessage.content[0].text;
+      } else if (typeof firstMessage?.content === 'string') {
+        rawName = firstMessage.content;
+      }
+
+      return {
+        sessionId,
+        workspacePath,
+        sessionName: normalizeSessionName(rawName, 'New Gemini Chat'),
+      };
+    } catch {
+      return null;
+    }
+  }
+}

server/src/modules/ai-runtime/providers/gemini/gemini-skills.runtime.ts

@@ -0,0 +1,41 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import type { IProviderSkillsRuntime, ProviderSkill, ProviderSkillScope } from '@/modules/ai-runtime/types/index.js';
+import {
+  deduplicateDirectories,
+  deduplicateSkills,
+  listSkillsFromDirectory,
+} from '@/modules/ai-runtime/providers/shared/skills/skills-runtime.utils.js';
+
+/**
+ * Gemini skills runtime backed by user/project skill directories.
+ */
+export class GeminiSkillsRuntime implements IProviderSkillsRuntime {
+  /**
+   * Lists all available Gemini skills from documented directories.
+   */
+  async listSkills(options?: { workspacePath?: string }): Promise<ProviderSkill[]> {
+    const workspacePath = path.resolve(options?.workspacePath ?? process.cwd());
+    const home = os.homedir();
+    const candidateDirectories: Array<{ scope: ProviderSkillScope; directory: string }> = [
+      { scope: 'user', directory: path.join(home, '.gemini', 'skills') },
+      { scope: 'user', directory: path.join(home, '.agents', 'skills') },
+      { scope: 'project', directory: path.join(workspacePath, '.gemini', 'skills') },
+      { scope: 'project', directory: path.join(workspacePath, '.agents', 'skills') },
+    ];
+
+    const skills: ProviderSkill[] = [];
+    for (const candidate of deduplicateDirectories(candidateDirectories)) {
+      const loadedSkills = await listSkillsFromDirectory({
+        provider: 'gemini',
+        scope: candidate.scope,
+        skillsDirectory: candidate.directory,
+        invocationPrefix: '/',
+      });
+      skills.push(...loadedSkills);
+    }
+
+    return deduplicateSkills(skills);
+  }
+}

server/src/modules/ai-runtime/providers/gemini/gemini.provider.ts

@@ -0,0 +1,80 @@
+import { BaseCliProvider } from '@/modules/ai-runtime/providers/base/base-cli.provider.js';
+import type {
+  IProviderAuthRuntime,
+  IProviderMcpRuntime,
+  IProviderSessionSynchronizerRuntime,
+  IProviderSkillsRuntime,
+  ProviderModel,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+import { GeminiMcpRuntime } from '@/modules/ai-runtime/providers/gemini/gemini-mcp.runtime.js';
+import { GeminiAuthRuntime } from '@/modules/ai-runtime/providers/gemini/gemini-auth.runtime.js';
+import { GeminiSkillsRuntime } from '@/modules/ai-runtime/providers/gemini/gemini-skills.runtime.js';
+import { GeminiSessionSynchronizerRuntime } from '@/modules/ai-runtime/providers/gemini/gemini-session-synchronizer.runtime.js';
+
+type GeminiExecutionInput = StartSessionInput & {
+  sessionId: string;
+  isResume: boolean;
+};
+
+const GEMINI_MODELS: ProviderModel[] = [
+  { value: 'gemini-3.1-pro-preview', displayName: 'Gemini 3.1 Pro Preview' },
+  { value: 'gemini-3-pro-preview', displayName: 'Gemini 3 Pro Preview' },
+  { value: 'gemini-3-flash-preview', displayName: 'Gemini 3 Flash Preview' },
+  { value: 'gemini-2.5-flash', displayName: 'Gemini 2.5 Flash' },
+  { value: 'gemini-2.5-pro', displayName: 'Gemini 2.5 Pro' },
+  { value: 'gemini-2.0-flash-lite', displayName: 'Gemini 2.0 Flash Lite' },
+  { value: 'gemini-2.0-flash', displayName: 'Gemini 2.0 Flash' },
+  { value: 'gemini-2.0-pro-exp', displayName: 'Gemini 2.0 Pro Experimental' },
+  { value: 'gemini-2.0-flash-thinking-exp', displayName: 'Gemini 2.0 Flash Thinking' },
+];
+
+/**
+ * Gemini CLI provider implementation.
+ */
+export class GeminiProvider extends BaseCliProvider {
+  readonly auth: IProviderAuthRuntime = new GeminiAuthRuntime();
+  readonly mcp: IProviderMcpRuntime = new GeminiMcpRuntime();
+  readonly skills: IProviderSkillsRuntime = new GeminiSkillsRuntime();
+  readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime = new GeminiSessionSynchronizerRuntime();
+
+  constructor() {
+    super('gemini', {
+      supportsRuntimePermissionRequests: false,
+      supportsThinkingModeControl: false,
+    });
+  }
+
+  /**
+   * Returns curated Gemini model options from the refactor doc.
+   */
+  async listModels(): Promise<ProviderModel[]> {
+    return GEMINI_MODELS;
+  }
+
+  /**
+   * Creates the command invocation for gemini start/resume flows.
+   */
+  protected createCliInvocation(input: GeminiExecutionInput): {
+    command: string;
+    args: string[];
+    cwd?: string;
+  } {
+    const promptWithImagePaths = this.appendImagePathsToPrompt(input.prompt, input.imagePaths);
+    const args = ['--prompt', promptWithImagePaths, '--output-format', 'stream-json'];
+
+    if (input.model) {
+      args.push('--model', input.model);
+    }
+
+    if (input.isResume) {
+      args.push('--resume', input.sessionId);
+    }
+
+    return {
+      command: 'gemini',
+      args,
+      cwd: input.workspacePath,
+    };
+  }
+}

server/src/modules/ai-runtime/providers/provider.interface.ts

@@ -0,0 +1 @@
+export * from '@/modules/ai-runtime/types/index.js';

server/src/modules/ai-runtime/providers/shared/mcp/base-provider-mcp.runtime.ts

@@ -0,0 +1,236 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import type {
+  IProviderMcpRuntime,
+  McpScope,
+  McpTransport,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+import {
+  normalizeServerName,
+  resolveWorkspacePath,
+  runHttpServerProbe,
+  runStdioServerProbe,
+} from '@/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.js';
+
+/**
+ * Shared MCP runtime for provider-specific config readers/writers.
+ */
+export abstract class BaseProviderMcpRuntime implements IProviderMcpRuntime {
+  protected readonly provider: LLMProvider;
+  protected readonly supportedScopes: McpScope[];
+  protected readonly supportedTransports: McpTransport[];
+
+  protected constructor(
+    provider: LLMProvider,
+    supportedScopes: McpScope[],
+    supportedTransports: McpTransport[],
+  ) {
+    this.provider = provider;
+    this.supportedScopes = supportedScopes;
+    this.supportedTransports = supportedTransports;
+  }
+
+  /**
+   * Lists MCP servers grouped by user/local/project scopes.
+   */
+  async listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const grouped: Record<McpScope, ProviderMcpServer[]> = {
+      user: [],
+      local: [],
+      project: [],
+    };
+
+    for (const scope of this.supportedScopes) {
+      grouped[scope] = await this.listServersForScope(scope, options);
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Lists MCP servers for one scope.
+   */
+  async listServersForScope(
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    if (!this.supportedScopes.includes(scope)) {
+      return [];
+    }
+
+    const workspacePath = resolveWorkspacePath(options?.workspacePath);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    return Object.entries(scopedServers)
+      .map(([name, rawConfig]) => this.normalizeServerConfig(scope, name, rawConfig))
+      .filter((entry): entry is ProviderMcpServer => entry !== null);
+  }
+
+  /**
+   * Adds or updates one MCP server.
+   */
+  async upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer> {
+    const scope = input.scope ?? 'project';
+    this.assertScopeAndTransport(scope, input.transport);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    scopedServers[normalizedName] = this.buildServerConfig(input);
+    await this.writeScopedServers(scope, workspacePath, scopedServers);
+
+    return {
+      provider: this.provider,
+      name: normalizedName,
+      scope,
+      transport: input.transport,
+      command: input.command,
+      args: input.args,
+      env: input.env,
+      cwd: input.cwd,
+      url: input.url,
+      headers: input.headers,
+      envVars: input.envVars,
+      bearerTokenEnvVar: input.bearerTokenEnvVar,
+      envHttpHeaders: input.envHttpHeaders,
+    };
+  }
+
+  /**
+   * Removes one MCP server for the selected scope.
+   */
+  async removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const scope = input.scope ?? 'project';
+    this.assertScope(scope);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    const removed = Object.prototype.hasOwnProperty.call(scopedServers, normalizedName);
+    if (removed) {
+      delete scopedServers[normalizedName];
+      await this.writeScopedServers(scope, workspacePath, scopedServers);
+    }
+
+    return { removed, provider: this.provider, name: normalizedName, scope };
+  }
+
+  /**
+   * Executes a lightweight startup/connectivity probe for one configured MCP server.
+   */
+  async runServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{
+    provider: LLMProvider;
+    name: string;
+    scope: McpScope;
+    transport: McpTransport;
+    reachable: boolean;
+    statusCode?: number;
+    error?: string;
+  }> {
+    const scope = input.scope ?? 'project';
+    this.assertScope(scope);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    const rawConfig = scopedServers[normalizedName];
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      throw new AppError(`MCP server "${normalizedName}" was not found.`, {
+        code: 'MCP_SERVER_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    const normalized = this.normalizeServerConfig(scope, normalizedName, rawConfig);
+    if (!normalized) {
+      throw new AppError(`MCP server "${normalizedName}" has an invalid configuration.`, {
+        code: 'MCP_SERVER_INVALID_CONFIG',
+        statusCode: 400,
+      });
+    }
+
+    if (normalized.transport === 'stdio') {
+      const result = await runStdioServerProbe(normalized, workspacePath);
+      return {
+        provider: this.provider,
+        name: normalizedName,
+        scope,
+        transport: normalized.transport,
+        reachable: result.reachable,
+        error: result.error,
+      };
+    }
+
+    const result = await runHttpServerProbe(normalized.url ?? '');
+    return {
+      provider: this.provider,
+      name: normalizedName,
+      scope,
+      transport: normalized.transport,
+      reachable: result.reachable,
+      statusCode: result.statusCode,
+      error: result.error,
+    };
+  }
+
+  /**
+   * Reads one scope's raw server map from provider-native files.
+   */
+  protected abstract readScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * Persists one scope's raw server map back to provider-native files.
+   */
+  protected abstract writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void>;
+
+  /**
+   * Creates one provider-native config object from a unified input payload.
+   */
+  protected abstract buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown>;
+
+  /**
+   * Maps one provider-native server object into the unified response shape.
+   */
+  protected abstract normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null;
+
+  /**
+   * Ensures one scope is supported for the current provider.
+   */
+  protected assertScope(scope: McpScope): void {
+    if (!this.supportedScopes.includes(scope)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${scope}" MCP scope.`, {
+        code: 'MCP_SCOPE_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+
+  /**
+   * Ensures one scope + transport pair is supported for the current provider.
+   */
+  protected assertScopeAndTransport(scope: McpScope, transport: McpTransport): void {
+    this.assertScope(scope);
+    if (!this.supportedTransports.includes(transport)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${transport}" MCP transport.`, {
+        code: 'MCP_TRANSPORT_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+}

server/src/modules/ai-runtime/providers/shared/mcp/mcp-runtime.utils.ts

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { once } from 'node:events';
+
+import spawn from 'cross-spawn';
+import TOML from '@iarna/toml';
+
+import type { ProviderMcpServer } from '@/modules/ai-runtime/types/index.js';
+import { AppError } from '@/shared/utils/app-error.js';
+
+/**
+ * Resolves workspace paths once so all scope loaders read from a consistent absolute root.
+ */
+export const resolveWorkspacePath = (workspacePath?: string): string =>
+  path.resolve(workspacePath ?? process.cwd());
+
+/**
+ * Restricts MCP server names to non-empty trimmed strings.
+ */
+export const normalizeServerName = (name: string): string => {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new AppError('MCP server name is required.', {
+      code: 'MCP_SERVER_NAME_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return normalized;
+};
+
+/**
+ * Reads plain object records.
+ */
+export const readObjectRecord = (value: unknown): Record<string, unknown> | null => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+};
+
+/**
+ * Reads optional strings.
+ */
+export const readOptionalString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length ? normalized : undefined;
+};
+
+/**
+ * Reads optional string arrays.
+ */
+export const readStringArray = (value: unknown): string[] | undefined => {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value.filter((entry): entry is string => typeof entry === 'string');
+};
+
+/**
+ * Reads optional string maps.
+ */
+export const readStringRecord = (value: unknown): Record<string, string> | undefined => {
+  const record = readObjectRecord(value);
+  if (!record) {
+    return undefined;
+  }
+
+  const normalized: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry === 'string') {
+      normalized[key] = entry;
+    }
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+};
+
+/**
+ * Safely reads a JSON config file and returns an empty object when missing.
+ */
+export const readJsonConfig = async (filePath: string): Promise<Record<string, unknown>> => {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    return readObjectRecord(parsed) ?? {};
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+};
+
+/**
+ * Writes one JSON config with stable formatting.
+ */
+export const writeJsonConfig = async (filePath: string, data: Record<string, unknown>): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+};
+
+/**
+ * Safely reads a TOML config and returns an empty object when missing.
+ */
+export const readTomlConfig = async (filePath: string): Promise<Record<string, unknown>> => {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    const parsed = TOML.parse(content) as Record<string, unknown>;
+    return readObjectRecord(parsed) ?? {};
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+};
+
+/**
+ * Writes one TOML config file.
+ */
+export const writeTomlConfig = async (filePath: string, data: Record<string, unknown>): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const toml = TOML.stringify(data as any);
+  await writeFile(filePath, toml, 'utf8');
+};
+
+/**
+ * Runs a short stdio process startup probe.
+ */
+export const runStdioServerProbe = async (
+  server: ProviderMcpServer,
+  workspacePath: string,
+): Promise<{ reachable: boolean; error?: string }> => {
+  if (!server.command) {
+    return { reachable: false, error: 'Missing stdio command.' };
+  }
+
+  try {
+    const child = spawn(server.command, server.args ?? [], {
+      cwd: server.cwd ? path.resolve(workspacePath, server.cwd) : workspacePath,
+      env: {
+        ...process.env,
+        ...(server.env ?? {}),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const timeout = setTimeout(() => {
+      if (!child.killed && child.exitCode === null) {
+        child.kill('SIGTERM');
+      }
+    }, 1_500);
+
+    const errorPromise = once(child, 'error').then(([error]) => {
+      throw error;
+    });
+    const closePromise = once(child, 'close');
+    await Promise.race([closePromise, errorPromise]);
+    clearTimeout(timeout);
+
+    if (typeof child.exitCode === 'number' && child.exitCode !== 0) {
+      return {
+        reachable: false,
+        error: `Process exited with code ${child.exitCode}.`,
+      };
+    }
+
+    return { reachable: true };
+  } catch (error) {
+    return {
+      reachable: false,
+      error: error instanceof Error ? error.message : 'Failed to start stdio process',
+    };
+  }
+};
+
+/**
+ * Runs a lightweight HTTP/SSE reachability probe.
+ */
+export const runHttpServerProbe = async (
+  url: string,
+): Promise<{ reachable: boolean; statusCode?: number; error?: string }> => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3_000);
+  try {
+    const response = await fetch(url, { method: 'GET', signal: controller.signal });
+    clearTimeout(timeout);
+    return {
+      reachable: true,
+      statusCode: response.status,
+    };
+  } catch (error) {
+    clearTimeout(timeout);
+    return {
+      reachable: false,
+      error: error instanceof Error ? error.message : 'Network probe failed',
+    };
+  }
+};

server/src/modules/ai-runtime/providers/shared/session-synchronizer/session-synchronizer.utils.ts

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+/**
+ * Keeps extracted session names compact and UI-safe.
+ */
+export function normalizeSessionName(rawValue: string | undefined, fallback: string): string {
+  const normalized = (rawValue ?? '').replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return fallback;
+  }
+
+  return normalized.slice(0, 120);
+}
+
+/**
+ * Returns directory entries or an empty array when the directory does not exist.
+ */
+export async function listDirectoryEntriesSafe(
+  directoryPath: string,
+): Promise<import('node:fs').Dirent[]> {
+  try {
+    return await fsp.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Builds a lookup map from a JSONL index file by extracting a key/value pair per row.
+ * The first occurrence of a key wins so we preserve earliest metadata.
+ */
+export async function buildLookupMap(
+  filePath: string,
+  keyField: string,
+  valueField: string,
+): Promise<Map<string, string>> {
+  const lookup = new Map<string, string>();
+
+  try {
+    const fileStream = fs.createReadStream(filePath);
+    const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of lineReader) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      const key = parsed[keyField];
+      const value = parsed[valueField];
+
+      if (typeof key === 'string' && typeof value === 'string' && !lookup.has(key)) {
+        lookup.set(key, value);
+      }
+    }
+  } catch {
+    // Missing index files are normal for users who have not used a provider yet.
+  }
+
+  return lookup;
+}
+
+/**
+ * Recursively scans for files with a given extension and optionally filters
+ * them to only files created after `lastScanAt`.
+ */
+export async function findFilesRecursivelyCreatedAfter(
+  rootDir: string,
+  extension: string,
+  lastScanAt: Date | null,
+  fileList: string[] = [],
+): Promise<string[]> {
+  try {
+    const entries = await fsp.readdir(rootDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(rootDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await findFilesRecursivelyCreatedAfter(fullPath, extension, lastScanAt, fileList);
+        continue;
+      }
+
+      if (!entry.isFile() || !entry.name.endsWith(extension)) {
+        continue;
+      }
+
+      if (!lastScanAt) {
+        fileList.push(fullPath);
+        continue;
+      }
+
+      const stats = await fsp.stat(fullPath);
+      if (stats.birthtime > lastScanAt) {
+        fileList.push(fullPath);
+      }
+    }
+  } catch {
+    // Missing provider directories should not fail the full sync.
+  }
+
+  return fileList;
+}
+
+/**
+ * Reads JSONL rows until the extractor yields a valid session identity.
+ */
+export async function extractFirstValidJsonlData<T>(
+  filePath: string,
+  extractor: (parsedJson: unknown) => T | null | undefined,
+): Promise<T | null> {
+  try {
+    const fileStream = fs.createReadStream(filePath);
+    const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of lineReader) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      const parsed = JSON.parse(trimmed);
+      const extracted = extractor(parsed);
+      if (extracted) {
+        lineReader.close();
+        fileStream.close();
+        return extracted;
+      }
+    }
+  } catch {
+    // Ignore malformed session files and continue scanning.
+  }
+
+  return null;
+}
+
+/**
+ * Reads filesystem timestamps for DB metadata fields.
+ */
+export async function readFileTimestamps(
+  filePath: string,
+): Promise<{ createdAt?: string; updatedAt?: string }> {
+  try {
+    const stat = await fsp.stat(filePath);
+    return {
+      createdAt: stat.birthtime.toISOString(),
+      updatedAt: stat.mtime.toISOString(),
+    };
+  } catch {
+    return {};
+  }
+}

server/src/modules/ai-runtime/providers/shared/skills/skills-runtime.utils.ts

@@ -0,0 +1,154 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { LLMProvider } from '@/shared/types/app.js';
+import type { ProviderSkill, ProviderSkillScope } from '@/modules/ai-runtime/types/index.js';
+
+/**
+ * Tests whether a path exists.
+ */
+export const pathExists = async (targetPath: string): Promise<boolean> => {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Parses frontmatter metadata from SKILL.md files.
+ */
+export const parseSkillFrontmatter = (content: string): { name?: string; description?: string } => {
+  if (!content.startsWith('---')) {
+    return {};
+  }
+
+  const closingDelimiterIndex = content.indexOf('\n---', 3);
+  if (closingDelimiterIndex < 0) {
+    return {};
+  }
+
+  const frontmatter = content.slice(3, closingDelimiterIndex).trim();
+  const metadata: { name?: string; description?: string } = {};
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const separatorIndex = line.indexOf(':');
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const rawValue = line.slice(separatorIndex + 1).trim();
+    const value = rawValue.replace(/^["']|["']$/g, '');
+    if (key === 'name') {
+      metadata.name = value;
+    } else if (key === 'description') {
+      metadata.description = value;
+    }
+  }
+
+  return metadata;
+};
+
+/**
+ * Reads SKILL.md files from a `<skills-dir>/<skill-name>/SKILL.md` directory layout.
+ */
+export const listSkillsFromDirectory = async (input: {
+  provider: LLMProvider;
+  scope: ProviderSkillScope;
+  skillsDirectory: string;
+  invocationPrefix: '/' | '$';
+  pluginName?: string;
+}): Promise<ProviderSkill[]> => {
+  if (!(await pathExists(input.skillsDirectory))) {
+    return [];
+  }
+
+  const entries = await readdir(input.skillsDirectory, { withFileTypes: true });
+  const skills: ProviderSkill[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillDirectory = path.join(input.skillsDirectory, entry.name);
+    const skillFilePath = path.join(skillDirectory, 'SKILL.md');
+    if (!(await pathExists(skillFilePath))) {
+      continue;
+    }
+
+    const skillMarkdown = await readFile(skillFilePath, 'utf8');
+    const metadata = parseSkillFrontmatter(skillMarkdown);
+    const skillName = metadata.name ?? entry.name;
+    const invocation = `${input.invocationPrefix}${skillName}`;
+    skills.push({
+      provider: input.provider,
+      scope: input.scope,
+      name: skillName,
+      description: metadata.description,
+      invocation,
+      filePath: skillFilePath,
+      pluginName: input.pluginName,
+    });
+  }
+
+  return skills;
+};
+
+/**
+ * Finds the closest git root by walking up from the current workspace path.
+ */
+export const findGitRepoRoot = async (startPath: string): Promise<string | null> => {
+  let currentPath = path.resolve(startPath);
+  while (true) {
+    const gitPath = path.join(currentPath, '.git');
+    if (await pathExists(gitPath)) {
+      return currentPath;
+    }
+
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      return null;
+    }
+
+    currentPath = parentPath;
+  }
+};
+
+/**
+ * Deduplicates directory candidates by absolute path.
+ */
+export const deduplicateDirectories = (
+  entries: Array<{ scope: ProviderSkillScope; directory: string }>,
+): Array<{ scope: ProviderSkillScope; directory: string }> => {
+  const seen = new Set<string>();
+  const deduplicated: Array<{ scope: ProviderSkillScope; directory: string }> = [];
+  for (const entry of entries) {
+    const normalizedDirectory = path.resolve(entry.directory);
+    if (seen.has(normalizedDirectory)) {
+      continue;
+    }
+    seen.add(normalizedDirectory);
+    deduplicated.push({ scope: entry.scope, directory: normalizedDirectory });
+  }
+
+  return deduplicated;
+};
+
+/**
+ * Deduplicates skills by provider + invocation command.
+ */
+export const deduplicateSkills = (skills: ProviderSkill[]): ProviderSkill[] => {
+  const seen = new Set<string>();
+  const deduplicated: ProviderSkill[] = [];
+  for (const skill of skills) {
+    const key = `${skill.provider}:${skill.invocation}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduplicated.push(skill);
+  }
+
+  return deduplicated;
+};

server/src/modules/ai-runtime/services/ai-runtime.service.ts

@@ -0,0 +1,191 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import type {
+  ProviderModel,
+  ProviderSessionSnapshot,
+  RuntimePermissionMode,
+  StartSessionInput,
+} from '@/modules/ai-runtime/types/index.js';
+
+/**
+ * Converts unknown request values into optional trimmed strings.
+ */
+const normalizeOptionalString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+/**
+ * Validates and normalizes optional image path arrays.
+ */
+const normalizeImagePaths = (value: unknown): string[] | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AppError('imagePaths must be an array of strings.', {
+      code: 'INVALID_IMAGE_PATHS',
+      statusCode: 400,
+    });
+  }
+
+  const normalizedPaths = value
+    .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+    .filter((entry) => entry.length > 0);
+
+  if (normalizedPaths.length !== value.length) {
+    throw new AppError('imagePaths must contain non-empty strings only.', {
+      code: 'INVALID_IMAGE_PATHS',
+      statusCode: 400,
+    });
+  }
+
+  return normalizedPaths;
+};
+
+/**
+ * Validates and normalizes runtime permission mode.
+ */
+const normalizePermissionMode = (value: unknown): RuntimePermissionMode | undefined => {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized === 'ask' || normalized === 'allow' || normalized === 'deny') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported runtimePermissionMode "${normalized}".`, {
+    code: 'INVALID_RUNTIME_PERMISSION_MODE',
+    statusCode: 400,
+  });
+};
+
+/**
+ * Facade over provider implementations with payload validation and capability checks.
+ */
+export const llmService = {
+  listProviders(): Array<{
+    id: LLMProvider;
+    family: 'sdk' | 'cli';
+    capabilities: {
+      supportsRuntimePermissionRequests: boolean;
+      supportsThinkingModeControl: boolean;
+    };
+  }> {
+    return llmProviderRegistry.listProviders().map((provider) => ({
+      id: provider.id,
+      family: provider.family,
+      capabilities: {
+        supportsRuntimePermissionRequests: provider.capabilities.supportsRuntimePermissionRequests,
+        supportsThinkingModeControl: provider.capabilities.supportsThinkingModeControl,
+      },
+    }));
+  },
+
+  async listModels(providerName: string): Promise<ProviderModel[]> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.listModels();
+  },
+
+  listSessions(providerName: string): ProviderSessionSnapshot[] {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.listSessions();
+  },
+
+  getSession(providerName: string, sessionId: string): ProviderSessionSnapshot | null {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.getSession(sessionId);
+  },
+
+  async startSession(providerName: string, payload: unknown): Promise<ProviderSessionSnapshot> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    const input = parseStartPayload(payload);
+    validateCapabilityContracts(provider.capabilities, input);
+    return provider.launchSession(input);
+  },
+
+  async resumeSession(
+    providerName: string,
+    sessionId: string,
+    payload: unknown,
+  ): Promise<ProviderSessionSnapshot> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    const input = parseStartPayload(payload);
+    validateCapabilityContracts(provider.capabilities, input);
+    return provider.resumeSession({ ...input, sessionId });
+  },
+
+  async stopSession(providerName: string, sessionId: string): Promise<boolean> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.stopSession(sessionId);
+  },
+};
+
+/**
+ * Parses and validates session start/resume request payloads.
+ */
+function parseStartPayload(payload: unknown): StartSessionInput {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const prompt = normalizeOptionalString(body.prompt);
+  if (!prompt) {
+    throw new AppError('prompt is required.', {
+      code: 'PROMPT_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return {
+    prompt,
+    workspacePath: normalizeOptionalString(body.workspacePath),
+    sessionId: normalizeOptionalString(body.sessionId),
+    model: normalizeOptionalString(body.model),
+    thinkingMode: normalizeOptionalString(body.thinkingMode),
+    imagePaths: normalizeImagePaths(body.imagePaths),
+    runtimePermissionMode: normalizePermissionMode(body.runtimePermissionMode),
+    allowYolo: body.allowYolo === true,
+  };
+}
+
+/**
+ * Enforces capability contracts before provider invocation.
+ */
+function validateCapabilityContracts(
+  capabilities: {
+    supportsRuntimePermissionRequests: boolean;
+    supportsThinkingModeControl: boolean;
+  },
+  input: StartSessionInput,
+): void {
+  if (
+    input.runtimePermissionMode &&
+    input.runtimePermissionMode !== 'ask' &&
+    !capabilities.supportsRuntimePermissionRequests
+  ) {
+    throw new AppError('Runtime permission requests are not supported by this provider.', {
+      code: 'RUNTIME_PERMISSION_NOT_SUPPORTED',
+      statusCode: 400,
+    });
+  }
+
+  if (input.thinkingMode && !capabilities.supportsThinkingModeControl) {
+    throw new AppError('Thinking mode is not supported by this provider.', {
+      code: 'THINKING_MODE_NOT_SUPPORTED',
+      statusCode: 400,
+    });
+  }
+}

server/src/modules/ai-runtime/services/auth.service.ts

@@ -0,0 +1,12 @@
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import type { ProviderAuthStatus } from '@/modules/ai-runtime/types/index.js';
+
+export const llmAuthService = {
+  /**
+   * Returns auth status for one provider.
+   */
+  async getProviderAuthStatus(providerName: string): Promise<ProviderAuthStatus> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.auth.getStatus();
+  },
+};

server/src/modules/ai-runtime/services/mcp.service.ts

@@ -0,0 +1,106 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import type {
+  McpScope,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/modules/ai-runtime/types/index.js';
+
+export const llmMcpService = {
+  /**
+   * Lists MCP servers for one provider grouped by supported scopes.
+   */
+  async listProviderMcpServers(
+    providerName: string,
+    options?: { workspacePath?: string },
+  ): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.mcp.listServers(options);
+  },
+
+  /**
+   * Lists MCP servers for one provider scope.
+   */
+  async listProviderMcpServersForScope(
+    providerName: string,
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.mcp.listServersForScope(scope, options);
+  },
+
+  /**
+   * Adds or updates one provider MCP server.
+   */
+  async upsertProviderMcpServer(
+    providerName: string,
+    input: UpsertProviderMcpServerInput,
+  ): Promise<ProviderMcpServer> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.mcp.upsertServer(input);
+  },
+
+  /**
+   * Removes one provider MCP server.
+   */
+  async removeProviderMcpServer(
+    providerName: string,
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.mcp.removeServer(input);
+  },
+
+  /**
+   * Runs one provider MCP server probe.
+   */
+  async runProviderMcpServer(
+    providerName: string,
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{
+    provider: LLMProvider;
+    name: string;
+    scope: McpScope;
+    transport: 'stdio' | 'http' | 'sse';
+    reachable: boolean;
+    statusCode?: number;
+    error?: string;
+  }> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.mcp.runServer(input);
+  },
+
+  /**
+   * Adds one HTTP/stdio MCP server to every provider.
+   */
+  async addMcpServerToAllProviders(
+    input: Omit<UpsertProviderMcpServerInput, 'scope'> & { scope?: Exclude<McpScope, 'local'> },
+  ): Promise<Array<{ provider: LLMProvider; created: boolean; error?: string }>> {
+    if (input.transport !== 'stdio' && input.transport !== 'http') {
+      throw new AppError('Global MCP add supports only "stdio" and "http".', {
+        code: 'INVALID_GLOBAL_MCP_TRANSPORT',
+        statusCode: 400,
+      });
+    }
+
+    const scope = input.scope ?? 'project';
+    const results: Array<{ provider: LLMProvider; created: boolean; error?: string }> = [];
+    const providers = llmProviderRegistry.listProviders();
+    for (const provider of providers) {
+      try {
+        await provider.mcp.upsertServer({ ...input, scope });
+        results.push({ provider: provider.id, created: true });
+      } catch (error) {
+        results.push({
+          provider: provider.id,
+          created: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    return results;
+  },
+};

server/src/modules/ai-runtime/services/messages-unifier.service.ts

@@ -0,0 +1,908 @@
+import type { ProviderSessionEvent } from '@/modules/ai-runtime/types/index.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+
+export type UnifiedMessageType =
+  | 'user_message'
+  | 'thinking_message'
+  | 'assistant_message'
+  | 'assistant_error_message'
+  | 'tool_use_request'
+  | 'tool_call_success'
+  | 'tool_call_error'
+  | 'todo_task_list'
+  | 'session_started'
+  | 'session_completed'
+  | 'session_interrupted';
+
+export type UnifiedSessionStatus = 'STARTED' | 'COMPLETED' | 'SESSION_ABORTED';
+
+export type UnifiedChatMessage = {
+  timestamp: string;
+  provider: LLMProvider;
+  sessionId: string;
+  type: UnifiedMessageType;
+  text?: string;
+  images?: string[];
+  toolName?: string;
+  toolCallId?: string;
+  status?: 'success' | 'error';
+  has_progress_indicator?: boolean;
+  sessionStatus?: UnifiedSessionStatus;
+  data?: unknown;
+  raw?: unknown;
+};
+
+type MessageContext = {
+  provider: LLMProvider;
+  sessionId: string;
+  timestamp?: string;
+};
+
+/**
+ * Unifies provider-specific history/event payloads into one frontend-safe message contract.
+ */
+export const llmMessagesUnifier = {
+  /**
+   * Converts in-memory provider session events to unified chat messages.
+   */
+  normalizeSessionEvents(
+    provider: LLMProvider,
+    sessionId: string,
+    events: ProviderSessionEvent[],
+  ): UnifiedChatMessage[] {
+    const messages: UnifiedChatMessage[] = [];
+    for (const event of events) {
+      const normalized = this.normalizeUnknown(provider, sessionId, event.data ?? event.message ?? event, event.timestamp);
+      if (normalized.length === 0 && event.message) {
+        messages.push(createMessage({
+          provider,
+          sessionId,
+          timestamp: event.timestamp,
+          type: event.channel === 'error' ? 'assistant_error_message' : 'assistant_message',
+          text: event.message,
+          raw: event,
+        }));
+        continue;
+      }
+
+      messages.push(...normalized);
+    }
+
+    return messages;
+  },
+
+  /**
+   * Converts DB history payload entries to unified chat messages.
+   */
+  normalizeHistoryEntries(
+    provider: LLMProvider,
+    sessionId: string,
+    entries: unknown[],
+  ): UnifiedChatMessage[] {
+    const messages: UnifiedChatMessage[] = [];
+    for (const entry of entries) {
+      messages.push(...this.normalizeUnknown(provider, sessionId, entry));
+    }
+
+    return messages;
+  },
+
+  /**
+   * Converts one raw provider payload to zero-or-more normalized messages.
+   */
+  normalizeUnknown(
+    provider: LLMProvider,
+    sessionId: string,
+    raw: unknown,
+    timestamp?: string,
+  ): UnifiedChatMessage[] {
+    const context: MessageContext = { provider, sessionId, timestamp };
+    if (!raw || typeof raw !== 'object') {
+      return [];
+    }
+
+    const preUnified = normalizePreUnifiedPayload(raw as Record<string, unknown>, context);
+    if (preUnified) {
+      return preUnified;
+    }
+
+    if (provider === 'claude') {
+      return normalizeClaudePayload(raw as Record<string, unknown>, context);
+    }
+
+    if (provider === 'codex') {
+      return normalizeCodexPayload(raw as Record<string, unknown>, context);
+    }
+
+    if (provider === 'gemini') {
+      return normalizeGeminiPayload(raw as Record<string, unknown>, context);
+    }
+
+    return normalizeCursorPayload(raw as Record<string, unknown>, context);
+  },
+};
+
+/**
+ * Maps already-unified custom payloads (for example permission callbacks) without provider parsing.
+ */
+function normalizePreUnifiedPayload(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage[] | null {
+  const type = readString(raw.type);
+  if (!type) {
+    return null;
+  }
+
+  if (
+    type !== 'user_message' &&
+    type !== 'thinking_message' &&
+    type !== 'assistant_message' &&
+    type !== 'assistant_error_message' &&
+    type !== 'tool_use_request' &&
+    type !== 'tool_call_success' &&
+    type !== 'tool_call_error' &&
+    type !== 'todo_task_list' &&
+    type !== 'session_started' &&
+    type !== 'session_completed' &&
+    type !== 'session_interrupted'
+  ) {
+    return null;
+  }
+
+  const statusValue = readString(raw.status);
+  const status =
+    statusValue === 'success' || statusValue === 'error'
+      ? statusValue
+      : undefined;
+  const sessionStatus = readString(raw.sessionStatus);
+  const normalizedSessionStatus =
+    sessionStatus === 'STARTED' || sessionStatus === 'COMPLETED' || sessionStatus === 'SESSION_ABORTED'
+      ? sessionStatus
+      : undefined;
+  const hasProgressIndicator =
+    readBoolean(raw.has_progress_indicator) ?? readBoolean(raw.hasProgressIndicator);
+
+  return [
+    createMessage({
+      ...context,
+      timestamp: readString(raw.timestamp) ?? context.timestamp,
+      type,
+      text: readString(raw.text) ?? readString(raw.message),
+      images: readStringArray(raw.images),
+      toolName: readString(raw.toolName) ?? readString(raw.name),
+      toolCallId: readString(raw.toolCallId) ?? readString(raw.toolUseID) ?? readString(raw.call_id),
+      status,
+      has_progress_indicator: hasProgressIndicator,
+      sessionStatus: normalizedSessionStatus,
+      data: raw.data ?? raw.input ?? raw.payload,
+      raw,
+    }),
+  ];
+}
+
+/**
+ * Normalizes Claude payloads from both SDK stream and disk history.
+ */
+function normalizeClaudePayload(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage[] {
+  const sessionStatusMessage = normalizeSessionStatus(raw, context);
+  if (sessionStatusMessage) {
+    return [sessionStatusMessage];
+  }
+
+  const type = readString(raw.type);
+  const timestamp = readString(raw.timestamp) ?? context.timestamp;
+
+  if (type === 'assistant') {
+    const messages: UnifiedChatMessage[] = [];
+    if (readString(raw.error)) {
+      messages.push(createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_error_message',
+        text: readString(raw.error),
+        raw,
+      }));
+    }
+
+    const messageRecord = readRecord(raw.message);
+    const contentBlocks = readArray(messageRecord?.content);
+    for (const contentBlock of contentBlocks) {
+      const block = readRecord(contentBlock);
+      if (!block) {
+        continue;
+      }
+
+      const blockType = readString(block.type);
+      if (blockType === 'thinking') {
+        const thinkingText = readString(block.thinking) ?? 'Thinking';
+        messages.push(createMessage({
+          ...context,
+          timestamp,
+          type: 'thinking_message',
+          text: thinkingText.length ? thinkingText : 'Thinking',
+          raw: block,
+        }));
+        continue;
+      }
+
+      if (blockType === 'text') {
+        const text = readString(block.text);
+        if (text) {
+          messages.push(createMessage({
+            ...context,
+            timestamp,
+            type: 'assistant_message',
+            text,
+            raw: block,
+          }));
+        }
+        continue;
+      }
+
+      if (blockType === 'tool_use') {
+        const toolName = readString(block.name);
+        const toolInput = readRecord(block.input) ?? block.input;
+
+        if (toolName === 'TaskCreate' || toolName === 'TaskUpdate') {
+          messages.push(createMessage({
+            ...context,
+            timestamp,
+            type: 'todo_task_list',
+            toolName,
+            has_progress_indicator: true,
+            data: toolInput,
+            raw: block,
+          }));
+          continue;
+        }
+
+        messages.push(createMessage({
+          ...context,
+          timestamp,
+          type: 'tool_use_request',
+          toolName,
+          toolCallId: readString(block.id),
+          data: toolInput,
+          raw: block,
+        }));
+      }
+    }
+
+    return messages;
+  }
+
+  if (type === 'user') {
+    // Tool results are emitted as user messages in Claude JSONL and should be treated as assistant tool results.
+    if (raw.toolUseResult !== undefined) {
+      const toolUseResult = readRecord(raw.toolUseResult) ?? raw.toolUseResult;
+      const successValue = readBoolean((toolUseResult as Record<string, unknown>)?.success);
+      const status: 'success' | 'error' = successValue === false ? 'error' : 'success';
+
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: status === 'success' ? 'tool_call_success' : 'tool_call_error',
+          status,
+          data: toolUseResult,
+          raw,
+        }),
+      ];
+    }
+
+    const messageRecord = readRecord(raw.message);
+    const content = readArray(messageRecord?.content);
+    const textParts: string[] = [];
+    const images: string[] = [];
+    for (const contentBlock of content) {
+      const block = readRecord(contentBlock);
+      if (!block) {
+        continue;
+      }
+
+      if (readString(block.type) === 'text') {
+        const text = readString(block.text);
+        if (text) {
+          textParts.push(text);
+        }
+      }
+
+      if (readString(block.type) === 'image') {
+        const source = readRecord(block.source);
+        const data = readString(source?.data);
+        if (data) {
+          images.push(data);
+        }
+      }
+    }
+
+    if (!textParts.length && !images.length) {
+      return [];
+    }
+
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'user_message',
+        text: textParts.join('\n'),
+        images: images.length ? images : undefined,
+        raw,
+      }),
+    ];
+  }
+
+  return [];
+}
+
+/**
+ * Normalizes Codex payloads from SDK stream/history JSONL.
+ */
+function normalizeCodexPayload(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage[] {
+  const sessionStatusMessage = normalizeSessionStatus(raw, context);
+  if (sessionStatusMessage) {
+    return [sessionStatusMessage];
+  }
+
+  const timestamp = readString(raw.timestamp) ?? context.timestamp;
+  const type = readString(raw.type);
+
+  if (type === 'error') {
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_error_message',
+        text: readString(raw.message) ?? 'Codex stream error',
+        raw,
+      }),
+    ];
+  }
+
+  if (type === 'event_msg') {
+    const payload = readRecord(raw.payload);
+    const payloadType = readString(payload?.type);
+    if (payloadType === 'user_message') {
+      const text = readString(payload?.message);
+      const localImages = readStringArray(payload?.local_images);
+      const remoteImages = readStringArray(payload?.images);
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: 'user_message',
+          text,
+          images: [...localImages, ...remoteImages],
+          raw,
+        }),
+      ];
+    }
+
+    if (payloadType === 'exec_command_end') {
+      const status = readString(payload?.status) === 'failed' ? 'error' : 'success';
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: status === 'success' ? 'tool_call_success' : 'tool_call_error',
+          status,
+          toolName: 'shell_command',
+          toolCallId: readString(payload?.call_id),
+          data: payload,
+          raw,
+        }),
+      ];
+    }
+  }
+
+  if (type === 'response_item') {
+    const payload = readRecord(raw.payload);
+    const payloadType = readString(payload?.type);
+    if (payloadType === 'reasoning') {
+      const summary = readArray(payload?.summary);
+      const summaryText = summary
+        .map((entry) => {
+          if (typeof entry === 'string') {
+            return entry;
+          }
+          const record = readRecord(entry);
+          return readString(record?.text) ?? readString(record?.summary) ?? '';
+        })
+        .filter((entry) => entry.length > 0)
+        .join('\n');
+
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: 'thinking_message',
+          text: summaryText || 'Reasoning',
+          data: payload,
+          raw,
+        }),
+      ];
+    }
+
+    if (payloadType === 'function_call') {
+      const toolName = readString(payload?.name);
+      const toolCallId = readString(payload?.call_id);
+      const argsText = readString(payload?.arguments);
+      const parsedArgs = parseJsonSafely(argsText) ?? argsText;
+
+      if (toolName === 'update_plan') {
+        return [
+          createMessage({
+            ...context,
+            timestamp,
+            type: 'todo_task_list',
+            toolName,
+            toolCallId,
+            has_progress_indicator: true,
+            data: parsedArgs,
+            raw,
+          }),
+        ];
+      }
+
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: 'tool_use_request',
+          toolName,
+          toolCallId,
+          data: parsedArgs,
+          raw,
+        }),
+      ];
+    }
+
+    if (payloadType === 'function_call_output') {
+      const output = readString(payload?.output) ?? '';
+      const status: 'success' | 'error' = /exit code:\s*0/i.test(output) ? 'success' : 'error';
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: status === 'success' ? 'tool_call_success' : 'tool_call_error',
+          status,
+          toolCallId: readString(payload?.call_id),
+          text: output,
+          data: payload,
+          raw,
+        }),
+      ];
+    }
+
+    if (payloadType === 'message') {
+      const role = readString(payload?.role);
+      const content = readArray(payload?.content);
+      const text = content
+        .map((entry) => {
+          const block = readRecord(entry);
+          return readString(block?.text) ?? '';
+        })
+        .filter(Boolean)
+        .join('\n');
+
+      if (role === 'user' && text.includes('<turn_aborted>')) {
+        return [
+          createMessage({
+            ...context,
+            timestamp,
+            type: 'session_interrupted',
+            sessionStatus: 'SESSION_ABORTED',
+            text,
+            raw,
+          }),
+        ];
+      }
+
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: role === 'user' ? 'user_message' : 'assistant_message',
+          text,
+          data: payload,
+          raw,
+        }),
+      ];
+    }
+
+    if (payloadType === 'error') {
+      return [
+        createMessage({
+          ...context,
+          timestamp,
+          type: 'assistant_error_message',
+          text: readString(payload?.message) ?? 'Codex error',
+          data: payload,
+          raw,
+        }),
+      ];
+    }
+  }
+
+  // SDK thread item-based events
+  const item = readRecord(raw.item);
+  if (!item) {
+    return [];
+  }
+
+  const itemType = readString(item.type);
+  if (itemType === 'reasoning') {
+    const text = readString(item.summary) ?? 'Reasoning';
+    return [createMessage({ ...context, timestamp, type: 'thinking_message', text, raw })];
+  }
+
+  if (itemType === 'error') {
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_error_message',
+        text: readString(item.message) ?? 'Codex item error',
+        raw,
+      }),
+    ];
+  }
+
+  if (itemType === 'todo_list') {
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'todo_task_list',
+        has_progress_indicator: true,
+        data: item,
+        raw,
+      }),
+    ];
+  }
+
+  if (itemType === 'agent_message') {
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_message',
+        text: readString(item.message) ?? '',
+        raw,
+      }),
+    ];
+  }
+
+  return [];
+}
+
+/**
+ * Normalizes Gemini payloads from JSON history files and runtime stream chunks.
+ */
+function normalizeGeminiPayload(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage[] {
+  const sessionStatusMessage = normalizeSessionStatus(raw, context);
+  if (sessionStatusMessage) {
+    return [sessionStatusMessage];
+  }
+
+  if (Array.isArray(raw.messages)) {
+    const messages: UnifiedChatMessage[] = [];
+    for (const message of raw.messages) {
+      const parsedMessage = readRecord(message);
+      if (!parsedMessage) {
+        continue;
+      }
+
+      messages.push(...normalizeGeminiPayload(parsedMessage, context));
+    }
+    return messages;
+  }
+
+  const timestamp = readString(raw.timestamp) ?? context.timestamp;
+  const type = readString(raw.type);
+  const unified: UnifiedChatMessage[] = [];
+
+  if (type === 'user') {
+    const text = readArray(raw.content)
+      .map((entry) => readString(readRecord(entry)?.text) ?? '')
+      .filter(Boolean)
+      .join('\n');
+    unified.push(createMessage({
+      ...context,
+      timestamp,
+      type: 'user_message',
+      text,
+      raw,
+    }));
+  }
+
+  if (type === 'gemini') {
+    const assistantText = readString(raw.content) ?? '';
+    if (assistantText.length) {
+      unified.push(createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_message',
+        text: assistantText,
+        raw,
+      }));
+    }
+  }
+
+  const thoughts = readArray(raw.thoughts);
+  for (const thought of thoughts) {
+    const thoughtRecord = readRecord(thought);
+    if (!thoughtRecord) {
+      continue;
+    }
+    const text = readString(thoughtRecord.description) ?? readString(thoughtRecord.subject) ?? 'Thinking';
+    unified.push(createMessage({
+      ...context,
+      timestamp: readString(thoughtRecord.timestamp) ?? timestamp,
+      type: 'thinking_message',
+      text,
+      raw: thoughtRecord,
+    }));
+  }
+
+  const toolCalls = readArray(raw.toolCalls);
+  for (const toolCall of toolCalls) {
+    const toolRecord = readRecord(toolCall);
+    if (!toolRecord) {
+      continue;
+    }
+
+    const status = readString(toolRecord.status) === 'error' ? 'error' : 'success';
+    unified.push(createMessage({
+      ...context,
+      timestamp: readString(toolRecord.timestamp) ?? timestamp,
+      type: status === 'success' ? 'tool_call_success' : 'tool_call_error',
+      status,
+      toolName: readString(toolRecord.displayName) ?? readString(toolRecord.name),
+      toolCallId: readString(toolRecord.id),
+      data: {
+        args: toolRecord.args,
+        result: toolRecord.result,
+        resultDisplay: toolRecord.resultDisplay,
+      },
+      raw: toolRecord,
+    }));
+  }
+
+  return unified;
+}
+
+/**
+ * Normalizes Cursor payloads from JSONL entries.
+ */
+function normalizeCursorPayload(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage[] {
+  const sessionStatusMessage = normalizeSessionStatus(raw, context);
+  if (sessionStatusMessage) {
+    return [sessionStatusMessage];
+  }
+
+  const role = readString(raw.role);
+  const timestamp = readString(raw.timestamp) ?? context.timestamp;
+  const message = readRecord(raw.message);
+  const content = readArray(message?.content);
+  const normalized: UnifiedChatMessage[] = [];
+
+  if (role === 'user') {
+    const text = content
+      .map((entry) => readString(readRecord(entry)?.text) ?? '')
+      .filter(Boolean)
+      .join('\n');
+    const strippedText = stripCursorUserQueryTags(text);
+    if (!strippedText) {
+      return [];
+    }
+
+    return [
+      createMessage({
+        ...context,
+        timestamp,
+        type: 'user_message',
+        text: strippedText,
+        raw,
+      }),
+    ];
+  }
+
+  if (role !== 'assistant') {
+    return [];
+  }
+
+  for (const entry of content) {
+    const block = readRecord(entry);
+    if (!block) {
+      continue;
+    }
+
+    const blockType = readString(block.type);
+    if (blockType === 'text') {
+      const text = readString(block.text);
+      if (!text) {
+        continue;
+      }
+
+      normalized.push(createMessage({
+        ...context,
+        timestamp,
+        type: 'assistant_message',
+        text,
+        raw: block,
+      }));
+      continue;
+    }
+
+    if (blockType === 'tool_use') {
+      const toolName = readString(block.name);
+      const input = block.input;
+      if (toolName === 'CreatePlan') {
+        normalized.push(createMessage({
+          ...context,
+          timestamp,
+          type: 'todo_task_list',
+          toolName,
+          has_progress_indicator: false,
+          data: input,
+          raw: block,
+        }));
+        continue;
+      }
+
+      normalized.push(createMessage({
+        ...context,
+        timestamp,
+        type: 'tool_call_success',
+        status: 'success',
+        toolName,
+        data: input,
+        raw: block,
+      }));
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Maps shared session status payloads into unified session event message types.
+ */
+function normalizeSessionStatus(
+  raw: Record<string, unknown>,
+  context: MessageContext,
+): UnifiedChatMessage | null {
+  const sessionStatus = readString(raw.sessionStatus);
+  if (!sessionStatus) {
+    return null;
+  }
+
+  if (sessionStatus === 'STARTED') {
+    return createMessage({
+      ...context,
+      timestamp: readString(raw.timestamp) ?? context.timestamp,
+      type: 'session_started',
+      sessionStatus: 'STARTED',
+      raw,
+    });
+  }
+
+  if (sessionStatus === 'COMPLETED') {
+    return createMessage({
+      ...context,
+      timestamp: readString(raw.timestamp) ?? context.timestamp,
+      type: 'session_completed',
+      sessionStatus: 'COMPLETED',
+      raw,
+    });
+  }
+
+  if (sessionStatus === 'SESSION_ABORTED') {
+    return createMessage({
+      ...context,
+      timestamp: readString(raw.timestamp) ?? context.timestamp,
+      type: 'session_interrupted',
+      sessionStatus: 'SESSION_ABORTED',
+      raw,
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Strips cursor `<user_query>...</user_query>` wrappers from user messages.
+ */
+function stripCursorUserQueryTags(value: string): string {
+  return value
+    .replace(/<user_query>/gi, '')
+    .replace(/<\/user_query>/gi, '')
+    .trim();
+}
+
+/**
+ * Creates one normalized message with defaults.
+ */
+function createMessage(input: Omit<UnifiedChatMessage, 'timestamp'> & { timestamp?: string }): UnifiedChatMessage {
+  return {
+    ...input,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * Safe object record cast.
+ */
+function readRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+
+  return value as Record<string, unknown>;
+}
+
+/**
+ * Safe array cast.
+ */
+function readArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/**
+ * Safe string parser.
+ */
+function readString(value: unknown): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+/**
+ * Safe boolean parser.
+ */
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+/**
+ * Safe string-array parser.
+ */
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry): entry is string => typeof entry === 'string');
+}
+
+/**
+ * Best-effort JSON parse helper.
+ */
+function parseJsonSafely(value?: string): unknown {
+  if (!value) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}

server/src/modules/ai-runtime/services/sessions-watcher.service.ts

@@ -0,0 +1,146 @@
+import chokidar from 'chokidar';
+import os from 'node:os';
+import path from 'node:path';
+import { promises as fsPromises } from 'node:fs';
+
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+import { logger } from '@/shared/utils/logger.js';
+
+// File system watchers for provider project/session folders
+const PROVIDER_WATCH_PATHS: Array<{ provider: LLMProvider; rootPath: string }> = [
+  {
+    provider: 'claude',
+    rootPath: path.join(os.homedir(), '.claude', 'projects'),
+  },
+  {
+    provider: 'cursor',
+    rootPath: path.join(os.homedir(), '.cursor', 'chats'),
+  },
+  {
+    provider: 'codex',
+    rootPath: path.join(os.homedir(), '.codex', 'sessions'),
+  },
+  {
+    provider: 'gemini',
+    rootPath: path.join(os.homedir(), '.gemini', 'sessions'),
+  },
+  {
+    provider: 'gemini',
+    rootPath: path.join(os.homedir(), '.gemini', 'tmp'),
+  },
+];
+
+const WATCHER_IGNORED_PATTERNS = [
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/*.tmp',
+  '**/*.swp',
+  '**/.DS_Store',
+];
+
+
+const watchers: any[] = [];
+type EventType = 'add' | 'change';
+
+/**
+ * Handles watcher update events and triggers provider index synchronization.
+ */
+async function onUpdate(
+  eventType: EventType,
+  filePath: string,
+  provider: LLMProvider,
+): Promise<void> {
+  if (!isWatcherTargetFile(provider, filePath)) {
+    return;
+  }
+
+  try {
+    const result = await llmSessionsService.synchronizeProviderFile(provider, filePath);
+    logger.info(`LLM watcher sync complete for provider "${provider}" after ${eventType}`, {
+      filePath,
+      indexed: result.indexed,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`LLM watcher sync failed for provider "${provider}"`, {
+      eventType,
+      filePath,
+      error: message,
+    });
+  }
+}
+
+/**
+ * Filters watcher events to provider-specific transcript artifact file types.
+ */
+function isWatcherTargetFile(provider: LLMProvider, filePath: string): boolean {
+  if (provider === 'gemini') {
+    return filePath.endsWith('.json');
+  }
+
+  return filePath.endsWith('.jsonl');
+}
+
+/**
+ * Initializes LLM session watchers and performs an initial index sync.
+ */
+export async function initializeWatcher(): Promise<void> {
+  logger.info('Setting up LLM session watchers...');
+
+  const initialSync = await llmSessionsService.synchronizeSessions();
+  logger.info('Initial LLM session sync complete.', {
+    processedByProvider: initialSync.processedByProvider,
+    failures: initialSync.failures,
+  });
+
+  for (const { provider, rootPath } of PROVIDER_WATCH_PATHS) {
+    try {
+      // chokidar v4 emits ENOENT via the "error" event for missing roots and will not auto-recover.
+      // Ensure provider folders exist before creating the watcher so watching stays active.
+      await fsPromises.mkdir(rootPath, { recursive: true });
+
+      const watcher = chokidar.watch(rootPath, {
+        ignored: WATCHER_IGNORED_PATTERNS,
+        persistent: true,
+        // Don't fire events for existing files on startup
+        ignoreInitial: true,
+        followSymlinks: false,
+        // Reasonable depth limit
+        depth: 6,
+        // Use polling to fix Windows fs.watch buffering/batching issues.
+        // It now stops relying on native filesystem events and checks for changes at intervals.
+        usePolling: true,
+        // Poll every 2000ms
+        interval: 2_000,
+        // Large binary files are more expensive to poll than text files.
+        binaryInterval: 6_000,
+        // Removed awaitWriteFinish to prevent delays when LLM streams to the file
+      });
+
+      watcher
+        .on('add', (filePath: string) => {
+          void onUpdate('add', filePath, provider);
+        })
+        .on('change', (filePath: string) => {
+          void onUpdate('change', filePath, provider);
+        })
+        .on('error', (error: unknown) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.error(`LLM watcher error for provider "${provider}"`, {
+            error: message,
+          });
+        });
+
+      watchers.push(watcher);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`Failed to initialize LLM watcher for provider "${provider}"`, {
+        rootPath,
+        error: message,
+      });
+    }
+  }
+}

server/src/modules/ai-runtime/services/sessions.service.ts

@@ -0,0 +1,260 @@
+import path from 'node:path';
+import fsp, { readFile } from 'node:fs/promises';
+
+import { scanStateDb } from '@/shared/database/repositories/scan-state.db.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { workspaceOriginalPathsDb } from '@/shared/database/repositories/workspace-original-paths.db.js';
+import type { LLMProvider } from '@/shared/types/app.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import { llmMessagesUnifier, type UnifiedChatMessage } from '@/modules/ai-runtime/services/messages-unifier.service.js';
+
+type SyncResult = {
+  processedByProvider: Record<LLMProvider, number>;
+  failures: string[];
+};
+
+type SessionHistoryPayload = {
+  sessionId: string;
+  provider: string;
+  workspacePath: string;
+  filePath: string;
+  fileType: 'jsonl' | 'json';
+  entries: unknown[];
+  messages: UnifiedChatMessage[];
+};
+
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9._-]{1,120}$/;
+
+/**
+ * Restricts session IDs before they are used in DB/filesystem operations.
+ */
+function sanitizeSessionId(sessionId: string): string {
+  const value = String(sessionId).trim();
+  if (!SESSION_ID_PATTERN.test(value)) {
+    throw new AppError('Invalid session ID format.', {
+      code: 'INVALID_SESSION_ID',
+      statusCode: 400,
+    });
+  }
+  return value;
+}
+
+/**
+ * Removes one file if it exists.
+ */
+async function removeFileIfExists(filePath: string): Promise<boolean> {
+  try {
+    await fsp.unlink(filePath);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Parses newline-delimited JSON files and preserves malformed lines as raw entries.
+ */
+const parseJsonl = (content: string): unknown[] => {
+  const entries: unknown[] = [];
+  const lines = content.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      entries.push({ raw: trimmed, parseError: true });
+    }
+  }
+
+  return entries;
+};
+
+/**
+ * Parses JSON files and normalizes object payloads into a single-element array.
+ */
+const parseJson = (content: string): unknown[] => {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return [{ raw: content, parseError: true }];
+  }
+};
+
+/**
+ * Orchestrates provider-specific session indexers and DB-path based cleanup.
+ */
+export const llmSessionsService = {
+  /**
+   * Lists indexed sessions from the shared DB, optionally scoped to one provider.
+   */
+  listIndexedSessions(provider?: string) {
+    const allSessions = sessionsDb.getAllSessions();
+    if (!provider) {
+      return allSessions;
+    }
+
+    return allSessions.filter((session) => session.provider === provider);
+  },
+
+  /**
+   * Reads one indexed session metadata row.
+   */
+  getIndexedSession(sessionId: string) {
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    const workspace = workspaceOriginalPathsDb.getWorkspacePath(session.workspace_path);
+    return {
+      ...session,
+      workspace_id: workspace?.workspace_id ?? null,
+    };
+  },
+
+  /**
+   * Runs all provider indexers and updates `scan_state.last_scanned_at`.
+   */
+  async synchronizeSessions(): Promise<SyncResult> {
+    const lastScanAt = scanStateDb.getLastScannedAt();
+    const processedByProvider: Record<LLMProvider, number> = {
+      claude: 0,
+      codex: 0,
+      cursor: 0,
+      gemini: 0,
+    };
+    const failures: string[] = [];
+
+    // Provider-specific session indexers used by the sync orchestrator.
+    const results = await Promise.allSettled(llmProviderRegistry.listProviders().map(async (provider) => ({
+      provider: provider.id,
+      processed: await provider.sessionSynchronizer.synchronize(lastScanAt ?? undefined),
+    })));
+
+    for (const result of results) {
+      if (result.status === 'fulfilled') {
+        processedByProvider[result.value.provider] = result.value.processed;
+        continue;
+      }
+
+      const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      failures.push(reason);
+    }
+
+    scanStateDb.updateLastScannedAt();
+
+    return {
+      processedByProvider,
+      failures,
+    };
+  },
+
+  /**
+   * Indexes one provider artifact file without running a full provider rescan.
+   */
+  async synchronizeProviderFile(
+    provider: LLMProvider,
+    filePath: string,
+  ): Promise<{ provider: LLMProvider; indexed: boolean }> {
+    const resolvedProvider = llmProviderRegistry.listProviders().find((entry) => entry.id === provider);
+    if (!resolvedProvider) {
+      throw new AppError(`No session indexer registered for provider "${provider}".`, {
+        code: 'SESSION_INDEXER_NOT_FOUND',
+        statusCode: 500,
+      });
+    }
+
+    const indexed = await resolvedProvider.sessionSynchronizer.synchronizeFile(filePath);
+    return { provider, indexed };
+  },
+
+  updateSessionCustomName(sessionId: string, sessionCustomName: string): void {
+    const sessionMetadata = sessionsDb.getSessionById(sessionId);
+    if (!sessionMetadata) {
+      throw new AppError('Session not found.', {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    sessionsDb.updateSessionCustomName(sessionId, sessionCustomName);
+  },
+
+  /**
+   * Deletes a session artifact using only DB `jsonl_path`, then removes the DB row.
+   */
+  async deleteSessionArtifacts(rawSessionId: string): Promise<{
+    sessionId: string;
+    deletedFromDisk: boolean;
+    deletedFromDatabase: boolean;
+  }> {
+    const sessionId = sanitizeSessionId(rawSessionId);
+    const existingSession = sessionsDb.getSessionById(sessionId);
+    const jsonlPath = existingSession?.jsonl_path ?? null;
+    const deletedFromDisk = jsonlPath ? await removeFileIfExists(jsonlPath) : false;
+
+    if (existingSession) {
+      sessionsDb.deleteSession(sessionId);
+    }
+
+    return {
+      sessionId,
+      deletedFromDisk,
+      deletedFromDatabase: Boolean(existingSession),
+    };
+  },
+
+  /**
+   * Reads session history directly from `sessions.jsonl_path` without legacy fetchers.
+   */
+  async getSessionHistory(sessionId: string): Promise<SessionHistoryPayload> {
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    if (!session.jsonl_path) {
+      throw new AppError(`Session "${sessionId}" does not have a history file path.`, {
+        code: 'SESSION_HISTORY_NOT_AVAILABLE',
+        statusCode: 404,
+      });
+    }
+
+    const filePath = session.jsonl_path;
+    const fileContent = await readFile(filePath, 'utf8');
+    const extension = path.extname(filePath).toLowerCase();
+    const isGeminiJson = session.provider === 'gemini' || extension === '.json';
+    const entries = isGeminiJson ? parseJson(fileContent) : parseJsonl(fileContent);
+
+    return {
+      sessionId: session.session_id,
+      provider: session.provider,
+      workspacePath: session.workspace_path,
+      filePath,
+      fileType: isGeminiJson ? 'json' : 'jsonl',
+      entries,
+      messages: llmMessagesUnifier.normalizeHistoryEntries(
+        session.provider,
+        session.session_id,
+        entries,
+      ),
+    };
+  },
+};

server/src/modules/ai-runtime/services/skills.service.ts

@@ -0,0 +1,15 @@
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import type { ProviderSkill } from '@/modules/ai-runtime/types/index.js';
+
+export const llmSkillsService = {
+  /**
+   * Lists skills for one provider.
+   */
+  async listProviderSkills(
+    providerName: string,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderSkill[]> {
+    const provider = llmProviderRegistry.resolveProvider(providerName);
+    return provider.skills.listSkills(options);
+  },
+};

server/src/modules/ai-runtime/tests/images.test.ts

@@ -0,0 +1,211 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmAssetsService } from '@/modules/assets/assets.service.js';
+import { ClaudeProvider } from '@/modules/ai-runtime/providers/claude/claude.provider.js';
+import { CodexProvider } from '@/modules/ai-runtime/providers/codex/codex.provider.js';
+import { CursorProvider } from '@/modules/ai-runtime/providers/cursor/cursor.provider.js';
+import { GeminiProvider } from '@/modules/ai-runtime/providers/gemini/gemini.provider.js';
+import { llmService } from '@/modules/ai-runtime/services/ai-runtime.service.js';
+
+const asyncEvents = async function* (events: unknown[]) {
+  for (const event of events) {
+    yield event;
+  }
+};
+
+/**
+ * This test covers the universal image-upload flow: store uploads under `.cloudcli/assets`.
+ */
+test('llmAssetsService stores uploaded images in .cloudcli/assets', { concurrency: false }, async () => {
+  const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-assets-'));
+  try {
+    const images = await llmAssetsService.storeUploadedImages(
+      [
+        {
+          originalname: 'photo.jpg',
+          mimetype: 'image/jpeg',
+          size: 3,
+          buffer: Buffer.from([0x01, 0x02, 0x03]),
+        },
+        {
+          originalname: 'diagram.png',
+          mimetype: 'image/png',
+          size: 4,
+          buffer: Buffer.from([0x11, 0x12, 0x13, 0x14]),
+        },
+      ],
+      { workspacePath: workspaceRoot },
+    );
+
+    assert.equal(images.length, 2);
+    assert.ok(images[0]?.relativePath.startsWith('.cloudcli/assets/'));
+    assert.ok(images[1]?.relativePath.startsWith('.cloudcli/assets/'));
+    await fs.access(images[0]!.absolutePath);
+    await fs.access(images[1]!.absolutePath);
+  } finally {
+    await fs.rm(workspaceRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers upload validation: unsupported mime types are rejected.
+ */
+test('llmAssetsService rejects unsupported image mime types', async () => {
+  await assert.rejects(
+    llmAssetsService.storeUploadedImages([
+      {
+        originalname: 'file.bmp',
+        mimetype: 'image/bmp',
+        size: 4,
+        buffer: Buffer.from([0x10, 0x20, 0x30, 0x40]),
+      },
+    ]),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'UNSUPPORTED_IMAGE_TYPE' &&
+      error.statusCode === 400,
+  );
+});
+
+/**
+ * This test covers Claude image input support: prompt becomes async iterable with text + base64 image blocks.
+ */
+test('claude provider builds async prompt payload with base64 image blocks', { concurrency: false }, async () => {
+  const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-claude-img-'));
+  const imagePath = path.join(workspaceRoot, 'sample.jpg');
+  const imageBytes = Buffer.from([0xaa, 0xbb, 0xcc]);
+  await fs.writeFile(imagePath, imageBytes);
+
+  try {
+    const provider = new ClaudeProvider() as any;
+    const promptPayload = await provider.buildPromptInput(
+      'describe this',
+      [imagePath],
+      workspaceRoot,
+    );
+
+    assert.equal(typeof promptPayload[Symbol.asyncIterator], 'function');
+    const iterator = promptPayload[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.equal(first.done, false);
+
+    const message = first.value as {
+      type: string;
+      message: {
+        role: string;
+        content: Array<Record<string, unknown>>;
+      };
+    };
+
+    assert.equal(message.type, 'user');
+    assert.equal(message.message.role, 'user');
+    assert.equal(message.message.content[0]?.type, 'text');
+    assert.equal(message.message.content[0]?.text, 'describe this');
+    assert.equal(message.message.content[1]?.type, 'image');
+    const imageBlock = message.message.content[1] as {
+      source: {
+        type: string;
+        media_type: string;
+        data: string;
+      };
+    };
+    assert.equal(imageBlock.source.type, 'base64');
+    assert.equal(imageBlock.source.media_type, 'image/jpeg');
+    assert.equal(imageBlock.source.data, imageBytes.toString('base64'));
+  } finally {
+    await fs.rm(workspaceRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Codex image input support: runStreamed receives text + local_image items.
+ */
+test('codex provider sends local_image prompt items when image paths are provided', async () => {
+  const provider = new CodexProvider() as any;
+  let capturedPrompt: unknown;
+
+  provider.loadCodexSdkModule = async () => ({
+    Codex: class {
+      startThread() {
+        return {
+          async runStreamed(prompt: unknown) {
+            capturedPrompt = prompt;
+            return { events: asyncEvents([]) };
+          },
+        };
+      }
+
+      resumeThread() {
+        return {
+          async runStreamed(prompt: unknown) {
+            capturedPrompt = prompt;
+            return { events: asyncEvents([]) };
+          },
+        };
+      }
+    },
+  });
+
+  await provider.createSdkExecution({
+    prompt: 'analyze this image',
+    sessionId: 'codex-image-1',
+    isResume: false,
+    imagePaths: ['assets/a.png'],
+    workspacePath: '/tmp/workspace',
+  });
+
+  assert.ok(Array.isArray(capturedPrompt));
+  const promptItems = capturedPrompt as Array<Record<string, unknown>>;
+  assert.equal(promptItems[0]?.type, 'text');
+  assert.equal(promptItems[0]?.text, 'analyze this image');
+  assert.equal(promptItems[1]?.type, 'local_image');
+  assert.equal(promptItems[1]?.path, path.resolve('/tmp/workspace', 'assets/a.png'));
+});
+
+/**
+ * This test covers Gemini/Cursor image handling: image paths are appended to the prompt payload.
+ */
+test('gemini and cursor providers append image path arrays to prompts', () => {
+  const geminiProvider = new GeminiProvider() as any;
+  const cursorProvider = new CursorProvider() as any;
+
+  const geminiInvocation = geminiProvider.createCliInvocation({
+    prompt: 'summarize',
+    sessionId: 'g-1',
+    isResume: false,
+    imagePaths: ['scripts/pic.jpg'],
+  });
+
+  const cursorInvocation = cursorProvider.createCliInvocation({
+    prompt: 'summarize',
+    sessionId: 'c-1',
+    isResume: false,
+    imagePaths: ['scripts/pic.jpg'],
+  });
+
+  const geminiPrompt = geminiInvocation.args[1];
+  const cursorPrompt = cursorInvocation.args[cursorInvocation.args.length - 1];
+  assert.ok(typeof geminiPrompt === 'string' && geminiPrompt.includes('["scripts/pic.jpg"]'));
+  assert.ok(typeof cursorPrompt === 'string' && cursorPrompt.includes('["scripts/pic.jpg"]'));
+});
+
+/**
+ * This test covers API payload validation: imagePaths must be an array of strings.
+ */
+test('llmService rejects invalid imagePaths payloads before provider execution', async () => {
+  await assert.rejects(
+    llmService.startSession('cursor', {
+      prompt: 'hello',
+      imagePaths: [1, 2, 3],
+    }),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_IMAGE_PATHS' &&
+      error.statusCode === 400,
+  );
+});

server/src/modules/ai-runtime/tests/mcp.test.ts

@@ -0,0 +1,350 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import TOML from '@iarna/toml';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmMcpService } from '@/modules/ai-runtime/services/mcp.service.js';
+
+const patchHomeDir = (nextHomeDir: string) => {
+  const original = os.homedir;
+  (os as any).homedir = () => nextHomeDir;
+  return () => {
+    (os as any).homedir = original;
+  };
+};
+
+const readJson = async (filePath: string): Promise<Record<string, unknown>> => {
+  const content = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(content) as Record<string, unknown>;
+};
+
+/**
+ * This test covers Claude MCP support for all scopes (user/local/project) and all transports (stdio/http/sse),
+ * including add, update/list, and remove operations.
+ */
+test('llmMcpService handles claude MCP scopes/transports with file-backed persistence', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-claude-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await llmMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-user-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'my-server'],
+      env: { API_KEY: 'secret' },
+    });
+
+    await llmMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-local-http',
+      scope: 'local',
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      headers: { Authorization: 'Bearer token' },
+      workspacePath,
+    });
+
+    await llmMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-project-sse',
+      scope: 'project',
+      transport: 'sse',
+      url: 'https://example.com/sse',
+      headers: { 'X-API-Key': 'abc' },
+      workspacePath,
+    });
+
+    const grouped = await llmMcpService.listProviderMcpServers('claude', { workspacePath });
+    assert.ok(grouped.user.some((server) => server.name === 'claude-user-stdio' && server.transport === 'stdio'));
+    assert.ok(grouped.local.some((server) => server.name === 'claude-local-http' && server.transport === 'http'));
+    assert.ok(grouped.project.some((server) => server.name === 'claude-project-sse' && server.transport === 'sse'));
+
+    // update behavior is the same upsert route with same name
+    await llmMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-project-sse',
+      scope: 'project',
+      transport: 'sse',
+      url: 'https://example.com/sse-updated',
+      headers: { 'X-API-Key': 'updated' },
+      workspacePath,
+    });
+
+    const projectConfig = await readJson(path.join(workspacePath, '.mcp.json'));
+    const projectServers = projectConfig.mcpServers as Record<string, unknown>;
+    const projectServer = projectServers['claude-project-sse'] as Record<string, unknown>;
+    assert.equal(projectServer.url, 'https://example.com/sse-updated');
+
+    const removeResult = await llmMcpService.removeProviderMcpServer('claude', {
+      name: 'claude-local-http',
+      scope: 'local',
+      workspacePath,
+    });
+    assert.equal(removeResult.removed, true);
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Codex MCP support for user/project scopes, stdio/http formats,
+ * and validation for unsupported scope/transport combinations.
+ */
+test('llmMcpService handles codex MCP TOML config and capability validation', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-codex-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await llmMcpService.upsertProviderMcpServer('codex', {
+      name: 'codex-user-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'python',
+      args: ['server.py'],
+      env: { API_KEY: 'x' },
+      envVars: ['API_KEY'],
+      cwd: '/tmp',
+    });
+
+    await llmMcpService.upsertProviderMcpServer('codex', {
+      name: 'codex-project-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://codex.example.com/mcp',
+      headers: { 'X-Custom-Header': 'value' },
+      envHttpHeaders: { 'X-API-Key': 'MY_API_KEY_ENV' },
+      bearerTokenEnvVar: 'MY_API_TOKEN',
+      workspacePath,
+    });
+
+    const userTomlPath = path.join(tempRoot, '.codex', 'config.toml');
+    const userConfig = TOML.parse(await fs.readFile(userTomlPath, 'utf8')) as Record<string, unknown>;
+    const userServers = userConfig.mcp_servers as Record<string, unknown>;
+    const userStdio = userServers['codex-user-stdio'] as Record<string, unknown>;
+    assert.equal(userStdio.command, 'python');
+
+    const projectTomlPath = path.join(workspacePath, '.codex', 'config.toml');
+    const projectConfig = TOML.parse(await fs.readFile(projectTomlPath, 'utf8')) as Record<string, unknown>;
+    const projectServers = projectConfig.mcp_servers as Record<string, unknown>;
+    const projectHttp = projectServers['codex-project-http'] as Record<string, unknown>;
+    assert.equal(projectHttp.url, 'https://codex.example.com/mcp');
+
+    await assert.rejects(
+      llmMcpService.upsertProviderMcpServer('codex', {
+        name: 'codex-local',
+        scope: 'local',
+        transport: 'stdio',
+        command: 'node',
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_SCOPE_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+
+    await assert.rejects(
+      llmMcpService.upsertProviderMcpServer('codex', {
+        name: 'codex-sse',
+        scope: 'project',
+        transport: 'sse',
+        url: 'https://example.com/sse',
+        workspacePath,
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_TRANSPORT_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Gemini/Cursor MCP JSON formats and user/project scope persistence.
+ */
+test('llmMcpService handles gemini and cursor MCP JSON config formats', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-gc-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await llmMcpService.upsertProviderMcpServer('gemini', {
+      name: 'gemini-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'node',
+      args: ['server.js'],
+      env: { TOKEN: '$TOKEN' },
+      cwd: './server',
+    });
+
+    await llmMcpService.upsertProviderMcpServer('gemini', {
+      name: 'gemini-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://gemini.example.com/mcp',
+      headers: { Authorization: 'Bearer token' },
+      workspacePath,
+    });
+
+    await llmMcpService.upsertProviderMcpServer('cursor', {
+      name: 'cursor-stdio',
+      scope: 'project',
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'mcp-server'],
+      env: { API_KEY: 'value' },
+      workspacePath,
+    });
+
+    await llmMcpService.upsertProviderMcpServer('cursor', {
+      name: 'cursor-http',
+      scope: 'user',
+      transport: 'http',
+      url: 'http://localhost:3333/mcp',
+      headers: { API_KEY: 'value' },
+    });
+
+    const geminiUserConfig = await readJson(path.join(tempRoot, '.gemini', 'settings.json'));
+    const geminiUserServer = (geminiUserConfig.mcpServers as Record<string, unknown>)['gemini-stdio'] as Record<string, unknown>;
+    assert.equal(geminiUserServer.command, 'node');
+    assert.equal(geminiUserServer.type, undefined);
+
+    const geminiProjectConfig = await readJson(path.join(workspacePath, '.gemini', 'settings.json'));
+    const geminiProjectServer = (geminiProjectConfig.mcpServers as Record<string, unknown>)['gemini-http'] as Record<string, unknown>;
+    assert.equal(geminiProjectServer.type, 'http');
+
+    const cursorUserConfig = await readJson(path.join(tempRoot, '.cursor', 'mcp.json'));
+    const cursorHttpServer = (cursorUserConfig.mcpServers as Record<string, unknown>)['cursor-http'] as Record<string, unknown>;
+    assert.equal(cursorHttpServer.url, 'http://localhost:3333/mcp');
+    assert.equal(cursorHttpServer.type, undefined);
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers the global MCP adder requirement: only http/stdio are allowed and
+ * one payload is written to all providers.
+ */
+test('llmMcpService global adder writes to all providers and rejects unsupported transports', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-global-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    const globalResult = await llmMcpService.addMcpServerToAllProviders({
+      name: 'global-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://global.example.com/mcp',
+      workspacePath,
+    });
+
+    assert.equal(globalResult.length, 4);
+    assert.ok(globalResult.every((entry) => entry.created === true));
+
+    const claudeProject = await readJson(path.join(workspacePath, '.mcp.json'));
+    assert.ok((claudeProject.mcpServers as Record<string, unknown>)['global-http']);
+
+    const codexProject = TOML.parse(await fs.readFile(path.join(workspacePath, '.codex', 'config.toml'), 'utf8')) as Record<string, unknown>;
+    assert.ok((codexProject.mcp_servers as Record<string, unknown>)['global-http']);
+
+    const geminiProject = await readJson(path.join(workspacePath, '.gemini', 'settings.json'));
+    assert.ok((geminiProject.mcpServers as Record<string, unknown>)['global-http']);
+
+    const cursorProject = await readJson(path.join(workspacePath, '.cursor', 'mcp.json'));
+    assert.ok((cursorProject.mcpServers as Record<string, unknown>)['global-http']);
+
+    await assert.rejects(
+      llmMcpService.addMcpServerToAllProviders({
+        name: 'global-sse',
+        scope: 'project',
+        transport: 'sse',
+        url: 'https://example.com/sse',
+        workspacePath,
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'INVALID_GLOBAL_MCP_TRANSPORT' &&
+        error.statusCode === 400,
+    );
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers "run" behavior for both stdio and http MCP servers.
+ */
+test('llmMcpService runProviderServer probes stdio and http MCP servers', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-run-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  const server = http.createServer((_req, res) => {
+    res.statusCode = 200;
+    res.end('ok');
+  });
+
+  try {
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    const url = `http://127.0.0.1:${address.port}/mcp`;
+
+    await llmMcpService.upsertProviderMcpServer('gemini', {
+      name: 'probe-http',
+      scope: 'project',
+      transport: 'http',
+      url,
+      workspacePath,
+    });
+
+    await llmMcpService.upsertProviderMcpServer('cursor', {
+      name: 'probe-stdio',
+      scope: 'project',
+      transport: 'stdio',
+      command: process.execPath,
+      args: ['-e', 'process.exit(0)'],
+      workspacePath,
+    });
+
+    const httpProbe = await llmMcpService.runProviderMcpServer('gemini', {
+      name: 'probe-http',
+      scope: 'project',
+      workspacePath,
+    });
+    assert.equal(httpProbe.reachable, true);
+    assert.equal(httpProbe.transport, 'http');
+
+    const stdioProbe = await llmMcpService.runProviderMcpServer('cursor', {
+      name: 'probe-stdio',
+      scope: 'project',
+      workspacePath,
+    });
+    assert.equal(stdioProbe.reachable, true);
+    assert.equal(stdioProbe.transport, 'stdio');
+  } finally {
+    server.close();
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+

server/src/modules/ai-runtime/tests/messages-unifier.test.ts

@@ -0,0 +1,337 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { llmMessagesUnifier } from '@/modules/ai-runtime/services/messages-unifier.service.js';
+
+/**
+ * This test covers helper-3 Claude normalization: user/assistant/thinking/tool-use/tool-result/error.
+ */
+test('llmMessagesUnifier normalizes claude message categories', () => {
+  const sessionId = 'claude-session-1';
+
+  const thinking = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'assistant',
+    timestamp: '2026-04-06T10:00:00.000Z',
+    message: {
+      content: [
+        { type: 'thinking', thinking: '' },
+        { type: 'text', text: 'Assistant response' },
+        { type: 'tool_use', id: 'toolu_1', name: 'Read', input: { file_path: 'a.txt' } },
+      ],
+    },
+  });
+  assert.equal(thinking[0]?.type, 'thinking_message');
+  assert.equal(thinking[0]?.text, 'Thinking');
+  assert.equal(thinking[1]?.type, 'assistant_message');
+  assert.equal(thinking[2]?.type, 'tool_use_request');
+
+  const user = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'user',
+    message: {
+      content: [
+        { type: 'text', text: 'hello there' },
+        {
+          type: 'image',
+          source: {
+            type: 'base64',
+            media_type: 'image/png',
+            data: 'image-b64',
+          },
+        },
+      ],
+    },
+  });
+  assert.equal(user[0]?.type, 'user_message');
+  assert.equal(user[0]?.text, 'hello there');
+  assert.deepEqual(user[0]?.images, ['image-b64']);
+
+  const toolResult = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'user',
+    toolUseResult: { success: false, reason: 'denied' },
+  });
+  assert.equal(toolResult[0]?.type, 'tool_call_error');
+
+  const toolResultSuccess = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'user',
+    toolUseResult: { type: 'create', filePath: 'hello.py' },
+  });
+  assert.equal(toolResultSuccess[0]?.type, 'tool_call_success');
+
+  const todo = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'assistant',
+    message: {
+      content: [
+        {
+          type: 'tool_use',
+          id: 'toolu_todo',
+          name: 'TaskUpdate',
+          input: { taskId: '1', status: 'in_progress' },
+        },
+      ],
+    },
+  });
+  assert.equal(todo[0]?.type, 'todo_task_list');
+  assert.equal(todo[0]?.has_progress_indicator, true);
+
+  const assistantError = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'assistant',
+    error: 'rate_limit',
+    message: { content: [] },
+  });
+  assert.equal(assistantError[0]?.type, 'assistant_error_message');
+});
+
+/**
+ * This test covers helper-3 Codex normalization: user_message, reasoning fallback, tool request/success/error, todo plan updates.
+ */
+test('llmMessagesUnifier normalizes codex message categories', () => {
+  const sessionId = 'codex-session-1';
+
+  const user = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'event_msg',
+    payload: {
+      type: 'user_message',
+      message: 'run command',
+      local_images: ['a.png'],
+      images: ['b.png'],
+    },
+  });
+  assert.equal(user[0]?.type, 'user_message');
+  assert.deepEqual(user[0]?.images, ['a.png', 'b.png']);
+
+  const reasoning = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'reasoning',
+      summary: [],
+    },
+  });
+  assert.equal(reasoning[0]?.type, 'thinking_message');
+  assert.equal(reasoning[0]?.text, 'Reasoning');
+
+  const toolRequest = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'function_call',
+      name: 'shell_command',
+      arguments: '{"command":"echo hi"}',
+      call_id: 'call_1',
+    },
+  });
+  assert.equal(toolRequest[0]?.type, 'tool_use_request');
+
+  const assistantMessage = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'message',
+      role: 'assistant',
+      content: [{ type: 'output_text', text: 'Command finished' }],
+    },
+  });
+  assert.equal(assistantMessage[0]?.type, 'assistant_message');
+  assert.equal(assistantMessage[0]?.text, 'Command finished');
+
+  const todo = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'function_call',
+      name: 'update_plan',
+      arguments: '{"plan":[{"step":"A","status":"in_progress"}]}',
+      call_id: 'call_2',
+    },
+  });
+  assert.equal(todo[0]?.type, 'todo_task_list');
+  assert.equal(todo[0]?.has_progress_indicator, true);
+
+  const toolError = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'event_msg',
+    payload: {
+      type: 'exec_command_end',
+      status: 'failed',
+      call_id: 'call_3',
+    },
+  });
+  assert.equal(toolError[0]?.type, 'tool_call_error');
+
+  const toolSuccess = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'function_call_output',
+      call_id: 'call_4',
+      output: 'Exit code: 0\nWall time: 0.1 seconds',
+    },
+  });
+  assert.equal(toolSuccess[0]?.type, 'tool_call_success');
+
+  const interruptedTurn = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'message',
+      role: 'user',
+      content: [{ type: 'input_text', text: '<turn_aborted>\nInterrupted\n</turn_aborted>' }],
+    },
+  });
+  assert.equal(interruptedTurn[0]?.type, 'session_interrupted');
+
+  const payloadError = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'response_item',
+    payload: {
+      type: 'error',
+      message: 'codex payload error',
+    },
+  });
+  assert.equal(payloadError[0]?.type, 'assistant_error_message');
+
+  const streamError = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    type: 'error',
+    message: 'codex stream error',
+  });
+  assert.equal(streamError[0]?.type, 'assistant_error_message');
+});
+
+/**
+ * This test covers helper-3 Gemini normalization from JSON history: user/assistant/thought/tool-call success and error.
+ */
+test('llmMessagesUnifier normalizes gemini history categories', () => {
+  const sessionId = 'gemini-session-1';
+  const messages = llmMessagesUnifier.normalizeUnknown('gemini', sessionId, {
+    sessionId,
+    messages: [
+      {
+        type: 'user',
+        timestamp: '2026-04-01T10:00:00.000Z',
+        content: [{ text: 'create files' }],
+      },
+      {
+        type: 'gemini',
+        timestamp: '2026-04-01T10:00:01.000Z',
+        content: 'I will do it',
+        thoughts: [{ subject: 'Planning', description: 'Thinking path' }],
+        toolCalls: [
+          { id: 't1', name: 'write_file', displayName: 'Write File', status: 'success' },
+          { id: 't2', name: 'write_file', status: 'error' },
+        ],
+      },
+    ],
+  });
+
+  assert.ok(messages.some((message) => message.type === 'user_message'));
+  assert.ok(messages.some((message) => message.type === 'assistant_message'));
+  assert.ok(messages.some((message) => message.type === 'thinking_message'));
+  assert.ok(messages.some((message) => message.type === 'tool_call_success'));
+  assert.ok(messages.some((message) => message.type === 'tool_call_error'));
+
+  const assistantIndex = messages.findIndex((message) => message.type === 'assistant_message');
+  const thinkingIndex = messages.findIndex((message) => message.type === 'thinking_message');
+  assert.ok(assistantIndex >= 0);
+  assert.ok(thinkingIndex > assistantIndex);
+
+  const successfulTool = messages.find((message) => message.type === 'tool_call_success');
+  assert.equal(successfulTool?.toolName, 'Write File');
+});
+
+/**
+ * This test covers helper-3 Cursor normalization: strip user_query tags and parse CreatePlan as todo with no progress indicator.
+ */
+test('llmMessagesUnifier normalizes cursor categories and strips user_query tags', () => {
+  const sessionId = 'cursor-session-1';
+  const user = llmMessagesUnifier.normalizeUnknown('cursor', sessionId, {
+    role: 'user',
+    message: {
+      content: [{ type: 'text', text: '<user_query>\nhello world\n</user_query>' }],
+    },
+  });
+  assert.equal(user[0]?.type, 'user_message');
+  assert.equal(user[0]?.text, 'hello world');
+
+  const assistant = llmMessagesUnifier.normalizeUnknown('cursor', sessionId, {
+    role: 'assistant',
+    message: {
+      content: [
+        { type: 'text', text: 'Starting work' },
+        {
+          type: 'tool_use',
+          name: 'CreatePlan',
+          input: {
+            todos: [{ id: '1', content: 'Do it' }],
+          },
+        },
+        {
+          type: 'tool_use',
+          name: 'ApplyPatch',
+          input: {
+            patch: '*** Begin Patch',
+          },
+        },
+      ],
+    },
+  });
+
+  assert.ok(assistant.some((message) => message.type === 'assistant_message'));
+  const todoMessage = assistant.find((message) => message.type === 'todo_task_list');
+  assert.equal(todoMessage?.has_progress_indicator, false);
+  assert.ok(assistant.some((message) => message.type === 'tool_call_success'));
+});
+
+/**
+ * This test covers shared session status normalization: started/completed/interrupted payloads.
+ */
+test('llmMessagesUnifier normalizes shared session status events', () => {
+  const sessionId = 'shared-session-1';
+  const started = llmMessagesUnifier.normalizeUnknown('codex', sessionId, {
+    sessionId,
+    sessionStatus: 'STARTED',
+  });
+  assert.equal(started[0]?.type, 'session_started');
+
+  const completed = llmMessagesUnifier.normalizeUnknown('gemini', sessionId, {
+    sessionId,
+    sessionStatus: 'COMPLETED',
+  });
+  assert.equal(completed[0]?.type, 'session_completed');
+
+  const interrupted = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    sessionId,
+    sessionStatus: 'SESSION_ABORTED',
+  });
+  assert.equal(interrupted[0]?.type, 'session_interrupted');
+});
+
+/**
+ * This test covers helper-3 notification flow: Claude permission callbacks should surface as tool_use_request.
+ */
+test('llmMessagesUnifier normalizes pre-unified tool_use_request payloads', () => {
+  const sessionId = 'permission-session-1';
+  const messages = llmMessagesUnifier.normalizeUnknown('claude', sessionId, {
+    type: 'tool_use_request',
+    toolName: 'Read',
+    input: { filePath: 'notes.txt' },
+    toolUseID: 'toolu_123',
+    title: 'Claude wants to read notes.txt',
+  });
+
+  assert.equal(messages[0]?.type, 'tool_use_request');
+  assert.equal(messages[0]?.toolName, 'Read');
+  assert.equal(messages[0]?.toolCallId, 'toolu_123');
+});
+
+/**
+ * This test covers helper-3 runtime-event fallback behavior for non-JSON stdout/stderr stream messages.
+ */
+test('llmMessagesUnifier normalizes fallback session events with channel-aware error typing', () => {
+  const messages = llmMessagesUnifier.normalizeSessionEvents('gemini', 'runtime-session-1', [
+    {
+      timestamp: '2026-04-06T12:00:00.000Z',
+      channel: 'stdout',
+      message: 'Process started',
+    },
+    {
+      timestamp: '2026-04-06T12:00:01.000Z',
+      channel: 'error',
+      message: 'Process failed',
+    },
+  ]);
+
+  assert.equal(messages[0]?.type, 'assistant_message');
+  assert.equal(messages[1]?.type, 'assistant_error_message');
+});

server/src/modules/ai-runtime/tests/providers.test.ts

@@ -0,0 +1,326 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import { llmService } from '@/modules/ai-runtime/services/ai-runtime.service.js';
+import { CursorProvider } from '@/modules/ai-runtime/providers/cursor/cursor.provider.js';
+import { GeminiProvider } from '@/modules/ai-runtime/providers/gemini/gemini.provider.js';
+import { CodexProvider } from '@/modules/ai-runtime/providers/codex/codex.provider.js';
+import { ClaudeProvider } from '@/modules/ai-runtime/providers/claude/claude.provider.js';
+
+const asyncEvents = async function* (events: unknown[]) {
+  for (const event of events) {
+    yield event;
+  }
+};
+
+// This test covers Cursor start/resume command construction, including yolo/model/resume flags.
+test('cursor provider builds start/resume CLI invocations correctly', () => {
+  const provider = new CursorProvider() as any;
+
+  const start = provider.createCliInvocation({
+    prompt: 'build feature',
+    sessionId: 'cursor-session-1',
+    isResume: false,
+    model: 'composer-2',
+    allowYolo: true,
+    workspacePath: '/tmp/workspace',
+  });
+  assert.equal(start.command, 'cursor-agent');
+  assert.deepEqual(start.args, [
+    '--print',
+    '--trust',
+    '--output-format',
+    'stream-json',
+    '--yolo',
+    '--model',
+    'composer-2',
+    'build feature',
+  ]);
+
+  const resume = provider.createCliInvocation({
+    prompt: 'continue',
+    sessionId: 'cursor-session-1',
+    isResume: true,
+    workspacePath: '/tmp/workspace',
+  });
+  assert.equal(resume.command, 'cursor-agent');
+  assert.deepEqual(resume.args, [
+    '--print',
+    '--trust',
+    '--output-format',
+    'stream-json',
+    '--resume',
+    'cursor-session-1',
+    'continue',
+  ]);
+});
+
+// This test covers Cursor model-list parsing, including ANSI stripping and current/default flags.
+test('cursor provider parses model list output into normalized models', async () => {
+  const provider = new CursorProvider() as any;
+
+  provider.runCommandForOutput = async () => [
+    '\u001b[32mAvailable models\u001b[0m',
+    'auto - Auto (current)',
+    'composer-2-fast - Composer 2 Fast (default)',
+    'Tip: use --model',
+  ].join('\n');
+
+  const models = await provider.listModels();
+  assert.equal(models.length, 2);
+  assert.deepEqual(models[0], {
+    value: 'auto',
+    displayName: 'auto',
+    description: 'Auto',
+    current: true,
+    default: false,
+    supportsThinkingModes: false,
+    supportedThinkingModes: [],
+  });
+  assert.equal(models[1].value, 'composer-2-fast');
+  assert.equal(models[1].default, true);
+});
+
+// This test covers Gemini start/resume CLI construction and curated model list contract.
+test('gemini provider builds start/resume CLI invocations and exposes curated models', async () => {
+  const provider = new GeminiProvider() as any;
+
+  const start = provider.createCliInvocation({
+    prompt: 'explain architecture',
+    sessionId: 'gemini-session-1',
+    isResume: false,
+    model: 'gemini-2.5-pro',
+    workspacePath: '/tmp/workspace',
+  });
+  assert.equal(start.command, 'gemini');
+  assert.deepEqual(start.args, [
+    '--prompt',
+    'explain architecture',
+    '--output-format',
+    'stream-json',
+    '--model',
+    'gemini-2.5-pro',
+  ]);
+
+  const resume = provider.createCliInvocation({
+    prompt: 'continue',
+    sessionId: 'gemini-session-1',
+    isResume: true,
+    workspacePath: '/tmp/workspace',
+  });
+  assert.deepEqual(resume.args, [
+    '--prompt',
+    'continue',
+    '--output-format',
+    'stream-json',
+    '--resume',
+    'gemini-session-1',
+  ]);
+
+  const models = await provider.listModels();
+  assert.ok(models.some((model: { value?: string }) => model.value === 'gemini-2.5-pro'));
+});
+
+// This test covers Codex start/resume behavior and abort-controller based stop behavior.
+test('codex provider start/resume use correct SDK thread methods and stop aborts signal', async () => {
+  const provider = new CodexProvider() as any;
+
+  const calls: Array<{ fn: 'start' | 'resume'; sessionId?: string; options: Record<string, unknown> }> = [];
+  let capturedSignal: AbortSignal | undefined;
+
+  const fakeThread = {
+    async runStreamed(_prompt: string, options?: { signal?: AbortSignal }) {
+      capturedSignal = options?.signal;
+      return { events: asyncEvents([{ type: 'chunk' }]) };
+    },
+  };
+
+  provider.loadCodexSdkModule = async () => ({
+    Codex: class {
+      startThread(options?: Record<string, unknown>) {
+        calls.push({ fn: 'start', options: options ?? {} });
+        return fakeThread;
+      }
+
+      resumeThread(sessionId: string, options?: Record<string, unknown>) {
+        calls.push({ fn: 'resume', sessionId, options: options ?? {} });
+        return fakeThread;
+      }
+    },
+  });
+
+  const startExec = await provider.createSdkExecution({
+    prompt: 'start codex',
+    sessionId: 'codex-session-1',
+    isResume: false,
+    model: 'gpt-5.4',
+    thinkingMode: 'high',
+    workspacePath: '/tmp/workspace',
+  });
+  assert.equal(calls[0]?.fn, 'start');
+  assert.equal(calls[0]?.options.model, 'gpt-5.4');
+  assert.equal(calls[0]?.options.modelReasoningEffort, 'high');
+  assert.equal(calls[0]?.options.workingDirectory, '/tmp/workspace');
+
+  assert.equal(await startExec.stop(), true);
+  assert.equal(capturedSignal?.aborted, true);
+
+  await provider.createSdkExecution({
+    prompt: 'resume codex',
+    sessionId: 'codex-session-1',
+    isResume: true,
+    workspacePath: '/tmp/workspace',
+  });
+  assert.equal(calls[1]?.fn, 'resume');
+  assert.equal(calls[1]?.sessionId, 'codex-session-1');
+});
+
+// This test covers Codex model-list loading from ~/.codex/models_cache.json and model-shape mapping.
+test('codex provider reads models_cache.json and maps model metadata', async () => {
+  const provider = new CodexProvider();
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'codex-models-'));
+  const codexDir = path.join(tempRoot, '.codex');
+  await fs.mkdir(codexDir, { recursive: true });
+  await fs.writeFile(
+    path.join(codexDir, 'models_cache.json'),
+    JSON.stringify({
+      models: [
+        {
+          slug: 'gpt-5.4',
+          display_name: 'GPT-5.4',
+          description: 'Latest frontier agentic coding model.',
+          priority: 1,
+          supported_reasoning_levels: [
+            { effort: 'low' },
+            { effort: 'medium' },
+            { effort: 'high' },
+          ],
+        },
+      ],
+    }),
+    'utf8',
+  );
+
+  const originalHomeDir = os.homedir;
+  (os as any).homedir = () => tempRoot;
+
+  try {
+    const models = await provider.listModels();
+    assert.equal(models.length, 1);
+    assert.equal(models[0]?.value, 'gpt-5.4');
+    assert.equal(models[0]?.default, true);
+    assert.deepEqual(models[0]?.supportedThinkingModes, ['low', 'medium', 'high']);
+  } finally {
+    (os as any).homedir = originalHomeDir;
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+// This test covers explicit start/resume payload control for model/thinking without implicit persistence.
+test('codex provider does not persist model/thinking between launches', async () => {
+  const provider = new CodexProvider() as any;
+  const threadOptionsHistory: Record<string, unknown>[] = [];
+
+  provider.loadCodexSdkModule = async () => ({
+    Codex: class {
+      startThread(options?: Record<string, unknown>) {
+        threadOptionsHistory.push(options ?? {});
+        return {
+          async runStreamed() {
+            return { events: asyncEvents([]) };
+          },
+        };
+      }
+
+      resumeThread() {
+        return {
+          async runStreamed() {
+            return { events: asyncEvents([]) };
+          },
+        };
+      }
+    },
+  });
+
+  await provider.launchSession({
+    prompt: 'explicit launch options',
+    sessionId: 'codex-pref-1',
+    model: 'gpt-5.4',
+    thinkingMode: 'xhigh',
+  });
+
+  await provider.launchSession({
+    prompt: 'follow-up launch without options',
+    sessionId: 'codex-pref-1',
+  });
+
+  assert.equal(threadOptionsHistory.length, 2);
+  assert.equal((threadOptionsHistory[0] as { model?: string }).model, 'gpt-5.4');
+  assert.equal((threadOptionsHistory[0] as { modelReasoningEffort?: string }).modelReasoningEffort, 'xhigh');
+  assert.equal((threadOptionsHistory[1] as { model?: string }).model, undefined);
+  assert.equal((threadOptionsHistory[1] as { modelReasoningEffort?: string }).modelReasoningEffort, undefined);
+});
+
+// This test covers Claude thinking-level mapping, runtime permission handlers, and model/event normalization.
+test('claude provider helper mappings match unifier contract', async () => {
+  const provider = new ClaudeProvider() as any;
+
+  assert.equal(provider.resolveClaudeEffort(undefined), 'high');
+  assert.equal(provider.resolveClaudeEffort('low'), 'low');
+  assert.equal(provider.resolveClaudeEffort('not-real'), 'high');
+
+  const allowHandler = provider.resolvePermissionHandler('allow');
+  const denyHandler = provider.resolvePermissionHandler('deny');
+  const askHandler = provider.resolvePermissionHandler('ask');
+  assert.equal(typeof allowHandler, 'function');
+  assert.equal(typeof denyHandler, 'function');
+  assert.equal(askHandler, undefined);
+
+  const allowResult = await allowHandler?.();
+  const denyResult = await denyHandler?.();
+  assert.deepEqual(allowResult, { behavior: 'allow' });
+  assert.equal(denyResult?.behavior, 'deny');
+
+  const mappedModel = provider.mapModelInfo({
+    value: 'default',
+    displayName: 'Default',
+    description: 'Default Claude model',
+    supportsEffort: true,
+    supportedEffortLevels: ['low', 'medium', 'high', 'max'],
+  });
+  assert.equal(mappedModel.value, 'default');
+  assert.equal(mappedModel.supportsThinkingModes, true);
+  assert.deepEqual(mappedModel.supportedThinkingModes, ['low', 'medium', 'high', 'max']);
+
+  const mappedEvent = provider.mapSdkEvent({ type: 'message', subtype: 'delta' });
+  assert.equal(mappedEvent?.message, 'message:delta');
+});
+
+// This test covers service-level capability validation for runtime permissions and thinking mode support.
+test('llmService rejects unsupported runtime permission and thinking mode combinations', async () => {
+  await assert.rejects(
+    llmService.startSession('cursor', {
+      prompt: 'hello',
+      runtimePermissionMode: 'allow',
+    }),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'RUNTIME_PERMISSION_NOT_SUPPORTED' &&
+      error.statusCode === 400,
+  );
+
+  await assert.rejects(
+    llmService.startSession('cursor', {
+      prompt: 'hello',
+      thinkingMode: 'high',
+    }),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'THINKING_MODE_NOT_SUPPORTED' &&
+      error.statusCode === 400,
+  );
+});

server/src/modules/ai-runtime/tests/sessions.test.ts

@@ -0,0 +1,378 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { AppError } from '@/shared/utils/app-error.js';
+import { scanStateDb } from '@/shared/database/repositories/scan-state.db.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { workspaceOriginalPathsDb } from '@/shared/database/repositories/workspace-original-paths.db.js';
+import { llmProviderRegistry } from '@/modules/ai-runtime/ai-runtime.registry.js';
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+import { conversationSearchService } from '@/modules/conversations/conversation-search.service.js';
+
+const patchMethod = <T extends object, K extends keyof T>(target: T, key: K, replacement: T[K]) => {
+  const original = target[key];
+  (target as any)[key] = replacement;
+  return () => {
+    (target as any)[key] = original;
+  };
+};
+
+// This test covers multi-provider synchronization orchestration and failure aggregation.
+test('llmSessionsService.synchronizeSessions aggregates processed counts and failures', { concurrency: false }, async () => {
+  let updateLastScannedAtCalls = 0;
+  const restoreScanDate = patchMethod(scanStateDb, 'getLastScannedAt', () => new Date('2026-04-01T00:00:00.000Z'));
+  const restoreUpdateScanDate = patchMethod(scanStateDb, 'updateLastScannedAt', () => {
+    updateLastScannedAtCalls += 1;
+  });
+  const restoreProviders = patchMethod(llmProviderRegistry, 'listProviders', () => ([
+    {
+      id: 'claude',
+      sessionSynchronizer: {
+        async synchronize() {
+          return 3;
+        },
+      },
+    },
+    {
+      id: 'codex',
+      sessionSynchronizer: {
+        async synchronize() {
+          throw new Error('codex index failed');
+        },
+      },
+    },
+  ] as any));
+
+  try {
+    const result = await llmSessionsService.synchronizeSessions();
+    assert.equal(result.processedByProvider.claude, 3);
+    assert.equal(result.processedByProvider.codex, 0);
+    assert.equal(result.processedByProvider.cursor, 0);
+    assert.equal(result.processedByProvider.gemini, 0);
+    assert.equal(result.failures.length, 1);
+    assert.equal(result.failures[0], 'codex index failed');
+    assert.equal(updateLastScannedAtCalls, 1);
+  } finally {
+    restoreProviders();
+    restoreUpdateScanDate();
+    restoreScanDate();
+  }
+});
+
+// This test covers single-file indexing delegation used by the watcher (no full provider rescan).
+test('llmSessionsService.synchronizeProviderFile delegates to provider indexer file sync', { concurrency: false }, async () => {
+  let synchronizeCalls = 0;
+  let synchronizeFilePath: string | null = null;
+  const restoreProviders = patchMethod(llmProviderRegistry, 'listProviders', () => ([
+    {
+      id: 'claude',
+      sessionSynchronizer: {
+        async synchronize() {
+          synchronizeCalls += 1;
+          return 0;
+        },
+        async synchronizeFile(filePath: string) {
+          synchronizeFilePath = filePath;
+          return true;
+        },
+      },
+    },
+  ] as any));
+
+  try {
+    const result = await llmSessionsService.synchronizeProviderFile('claude', '/tmp/claude-session.jsonl');
+    assert.equal(result.provider, 'claude');
+    assert.equal(result.indexed, true);
+    assert.equal(synchronizeFilePath, '/tmp/claude-session.jsonl');
+    assert.equal(synchronizeCalls, 0);
+  } finally {
+    restoreProviders();
+  }
+});
+
+// This test covers session rename persistence and not-found guardrails.
+test('llmSessionsService.updateSessionCustomName validates existence before updating', { concurrency: false }, () => {
+  let updated: { sessionId: string; customName: string } | null = null;
+  const restoreGetById = patchMethod(sessionsDb, 'getSessionById', (sessionId: string) => (
+    sessionId === 'known-session'
+      ? {
+          session_id: 'known-session',
+          provider: 'claude',
+          workspace_path: '/tmp/workspace',
+          jsonl_path: null,
+          custom_name: null,
+          created_at: '2026-04-01T00:00:00.000Z',
+          updated_at: '2026-04-01T00:00:00.000Z',
+        }
+      : null
+  ));
+  const restoreUpdateName = patchMethod(sessionsDb, 'updateSessionCustomName', (sessionId: string, customName: string) => {
+    updated = { sessionId, customName };
+  });
+
+  try {
+    llmSessionsService.updateSessionCustomName('known-session', 'New Session Name');
+    assert.deepEqual(updated, {
+      sessionId: 'known-session',
+      customName: 'New Session Name',
+    });
+
+    assert.throws(
+      () => llmSessionsService.updateSessionCustomName('missing-session', 'Nope'),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'SESSION_NOT_FOUND' &&
+        error.statusCode === 404,
+    );
+  } finally {
+    restoreUpdateName();
+    restoreGetById();
+  }
+});
+
+// This test covers fetching one indexed DB session metadata row from getSessionById.
+test('llmSessionsService.getIndexedSession returns DB session metadata', { concurrency: false }, () => {
+  const restoreGetById = patchMethod(sessionsDb, 'getSessionById', (sessionId: string) => (
+    sessionId === 'known-session'
+      ? {
+          session_id: 'known-session',
+          provider: 'claude',
+          workspace_path: '/tmp/workspace',
+          jsonl_path: '/tmp/workspace/session.jsonl',
+          custom_name: 'Custom Session Name',
+          created_at: '2026-04-01T00:00:00.000Z',
+          updated_at: '2026-04-02T00:00:00.000Z',
+        }
+      : null
+  ));
+  const restoreGetWorkspacePath = patchMethod(workspaceOriginalPathsDb, 'getWorkspacePath', (workspacePath: string) => (
+    workspacePath === '/tmp/workspace'
+      ? {
+          workspace_id: 'workspace-123',
+          workspace_path: workspacePath,
+          custom_workspace_name: 'Workspace Custom Name',
+          isStarred: 0,
+        }
+      : null
+  ));
+
+  try {
+    const session = llmSessionsService.getIndexedSession('known-session');
+    assert.deepEqual(session, {
+      session_id: 'known-session',
+      provider: 'claude',
+      workspace_path: '/tmp/workspace',
+      jsonl_path: '/tmp/workspace/session.jsonl',
+      custom_name: 'Custom Session Name',
+      created_at: '2026-04-01T00:00:00.000Z',
+      updated_at: '2026-04-02T00:00:00.000Z',
+      workspace_id: 'workspace-123',
+    });
+
+    assert.throws(
+      () => llmSessionsService.getIndexedSession('missing-session'),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'SESSION_NOT_FOUND' &&
+        error.statusCode === 404,
+    );
+  } finally {
+    restoreGetWorkspacePath();
+    restoreGetById();
+  }
+});
+
+// This test covers delete behavior using only DB jsonl_path, including invalid id validation.
+test('llmSessionsService.deleteSessionArtifacts validates ids and deletes disk/db artifacts', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-delete-session-'));
+  const transcriptPath = path.join(tempRoot, 'session.jsonl');
+  await fs.writeFile(transcriptPath, '{"ok":true}\n', 'utf8');
+
+  let deletedSessionId: string | null = null;
+  const restoreGetById = patchMethod(sessionsDb, 'getSessionById', (sessionId: string) => (
+    sessionId === 'session-123'
+      ? {
+          session_id: 'session-123',
+          provider: 'cursor',
+          workspace_path: '/tmp/workspace',
+          jsonl_path: transcriptPath,
+          custom_name: null,
+          created_at: '2026-04-01T00:00:00.000Z',
+          updated_at: '2026-04-01T00:00:00.000Z',
+        }
+      : null
+  ));
+  const restoreDelete = patchMethod(sessionsDb, 'deleteSession', (sessionId: string) => {
+    deletedSessionId = sessionId;
+  });
+
+  try {
+    await assert.rejects(
+      llmSessionsService.deleteSessionArtifacts('../invalid'),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'INVALID_SESSION_ID' &&
+        error.statusCode === 400,
+    );
+
+    const deleted = await llmSessionsService.deleteSessionArtifacts('session-123');
+    assert.equal(deleted.sessionId, 'session-123');
+    assert.equal(deleted.deletedFromDatabase, true);
+    assert.equal(deleted.deletedFromDisk, true);
+    assert.equal(deletedSessionId, 'session-123');
+    await assert.rejects(fs.access(transcriptPath));
+
+    const missing = await llmSessionsService.deleteSessionArtifacts('session-404');
+    assert.equal(missing.deletedFromDatabase, false);
+    assert.equal(missing.deletedFromDisk, false);
+  } finally {
+    restoreDelete();
+    restoreGetById();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+// This test covers session-history parsing for JSONL (including malformed lines) and Gemini JSON files.
+test('llmSessionsService.getSessionHistory parses JSONL and Gemini JSON correctly', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-history-'));
+  const jsonlPath = path.join(tempRoot, 'session.jsonl');
+  const jsonPath = path.join(tempRoot, 'gemini.json');
+  await fs.writeFile(jsonlPath, '{"message":"hello"}\nnot-json\n', 'utf8');
+  await fs.writeFile(jsonPath, '{"messages":[{"text":"hi"}]}', 'utf8');
+
+  const restoreGetById = patchMethod(sessionsDb, 'getSessionById', (sessionId: string) => {
+    if (sessionId === 'jsonl-session') {
+      return {
+        session_id: 'jsonl-session',
+        provider: 'cursor',
+        workspace_path: '/tmp/workspace',
+        jsonl_path: jsonlPath,
+        custom_name: null,
+        created_at: '2026-04-01T00:00:00.000Z',
+        updated_at: '2026-04-01T00:00:00.000Z',
+      };
+    }
+
+    if (sessionId === 'json-session') {
+      return {
+        session_id: 'json-session',
+        provider: 'gemini',
+        workspace_path: '/tmp/workspace',
+        jsonl_path: jsonPath,
+        custom_name: null,
+        created_at: '2026-04-01T00:00:00.000Z',
+        updated_at: '2026-04-01T00:00:00.000Z',
+      };
+    }
+
+    if (sessionId === 'missing-history-path') {
+      return {
+        session_id: 'missing-history-path',
+        provider: 'claude',
+        workspace_path: '/tmp/workspace',
+        jsonl_path: null,
+        custom_name: null,
+        created_at: '2026-04-01T00:00:00.000Z',
+        updated_at: '2026-04-01T00:00:00.000Z',
+      };
+    }
+
+    return null;
+  });
+
+  try {
+    const jsonlHistory = await llmSessionsService.getSessionHistory('jsonl-session');
+    assert.equal(jsonlHistory.fileType, 'jsonl');
+    assert.equal(Array.isArray(jsonlHistory.entries), true);
+    assert.equal(jsonlHistory.entries.length, 2);
+    assert.deepEqual(jsonlHistory.entries[0], { message: 'hello' });
+    assert.deepEqual(jsonlHistory.entries[1], { raw: 'not-json', parseError: true });
+
+    const geminiHistory = await llmSessionsService.getSessionHistory('json-session');
+    assert.equal(geminiHistory.fileType, 'json');
+    assert.equal(geminiHistory.entries.length, 1);
+    assert.deepEqual(geminiHistory.entries[0], { messages: [{ text: 'hi' }] });
+
+    await assert.rejects(
+      llmSessionsService.getSessionHistory('unknown-session'),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'SESSION_NOT_FOUND' &&
+        error.statusCode === 404,
+    );
+
+    await assert.rejects(
+      llmSessionsService.getSessionHistory('missing-history-path'),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'SESSION_HISTORY_NOT_AVAILABLE' &&
+        error.statusCode === 404,
+    );
+  } finally {
+    restoreGetById();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+// This test covers conversation search over indexed transcript files with provider/case filters.
+test('conversationSearchService searches indexed transcripts with provider and case filters', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-search-'));
+  const cursorPath = path.join(tempRoot, 'cursor.jsonl');
+  const codexPath = path.join(tempRoot, 'codex.jsonl');
+  await fs.writeFile(cursorPath, 'hello world\nNeedle lower\n', 'utf8');
+  await fs.writeFile(codexPath, 'HELLO WORLD\nNEEDLE UPPER\n', 'utf8');
+
+  const restoreGetAll = patchMethod(sessionsDb, 'getAllSessions', () => ([
+    {
+      session_id: 'cursor-s',
+      provider: 'cursor',
+      workspace_path: '/tmp/workspace-cursor',
+      jsonl_path: cursorPath,
+      custom_name: null,
+      created_at: '2026-04-01T00:00:00.000Z',
+      updated_at: '2026-04-01T00:00:00.000Z',
+    },
+    {
+      session_id: 'codex-s',
+      provider: 'codex',
+      workspace_path: '/tmp/workspace-codex',
+      jsonl_path: codexPath,
+      custom_name: null,
+      created_at: '2026-04-01T00:00:00.000Z',
+      updated_at: '2026-04-01T00:00:00.000Z',
+    },
+  ]));
+
+  try {
+    await assert.rejects(
+      conversationSearchService.search({ query: '   ' }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'SEARCH_QUERY_REQUIRED' &&
+        error.statusCode === 400,
+    );
+
+    const anyProviderResults = await conversationSearchService.search({
+      query: 'needle',
+      caseSensitive: false,
+      limit: 20,
+    });
+    assert.ok(anyProviderResults.some((entry) => entry.sessionId === 'cursor-s'));
+    assert.ok(anyProviderResults.some((entry) => entry.sessionId === 'codex-s'));
+
+    const codexOnlyResults = await conversationSearchService.search({
+      query: 'NEEDLE',
+      caseSensitive: true,
+      provider: 'codex',
+      limit: 20,
+    });
+    assert.ok(codexOnlyResults.length >= 1);
+    assert.ok(codexOnlyResults.every((entry) => entry.provider === 'codex'));
+  } finally {
+    restoreGetAll();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});

server/src/modules/ai-runtime/tests/skills.test.ts

@@ -0,0 +1,208 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { llmSkillsService } from '@/modules/ai-runtime/services/skills.service.js';
+
+const patchHomeDir = (nextHomeDir: string) => {
+  const original = os.homedir;
+  (os as any).homedir = () => nextHomeDir;
+  return () => {
+    (os as any).homedir = original;
+  };
+};
+
+const createSkill = async (
+  rootSkillsDirectory: string,
+  directoryName: string,
+  metadata: {
+    name: string;
+    description: string;
+  },
+) => {
+  const skillDirectory = path.join(rootSkillsDirectory, directoryName);
+  await fs.mkdir(skillDirectory, { recursive: true });
+  await fs.writeFile(
+    path.join(skillDirectory, 'SKILL.md'),
+    `---\nname: ${metadata.name}\ndescription: ${metadata.description}\n---\n\n# ${metadata.name}\n`,
+    'utf8',
+  );
+};
+
+/**
+ * This test covers Claude skills fetching from user/project/plugin locations and plugin namespace invocation.
+ */
+test('llmSkillsService lists claude user/project/plugin skills with proper invocation names', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-claude-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  const pluginInstallPath = path.join(tempRoot, 'plugin-install');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await createSkill(path.join(tempRoot, '.claude', 'skills'), 'user-helper', {
+      name: 'user-helper',
+      description: 'User skill description',
+    });
+    await createSkill(path.join(workspacePath, '.claude', 'skills'), 'project-helper', {
+      name: 'project-helper',
+      description: 'Project skill description',
+    });
+    await createSkill(path.join(pluginInstallPath, 'skills'), 'plugin-helper', {
+      name: 'plugin-helper',
+      description: 'Plugin skill description',
+    });
+
+    await fs.mkdir(path.join(tempRoot, '.claude', 'plugins'), { recursive: true });
+    await fs.writeFile(
+      path.join(tempRoot, '.claude', 'settings.json'),
+      JSON.stringify({
+        enabledPlugins: {
+          'example-skills@anthropic-agent-skills': true,
+        },
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(tempRoot, '.claude', 'plugins', 'installed_plugins.json'),
+      JSON.stringify({
+        version: 2,
+        plugins: {
+          'example-skills@anthropic-agent-skills': [
+            {
+              installPath: pluginInstallPath,
+            },
+          ],
+        },
+      }),
+      'utf8',
+    );
+
+    const skills = await llmSkillsService.listProviderSkills('claude', { workspacePath });
+    assert.ok(skills.some((skill) => skill.scope === 'user' && skill.invocation === '/user-helper'));
+    assert.ok(skills.some((skill) => skill.scope === 'project' && skill.invocation === '/project-helper'));
+    assert.ok(skills.some((skill) => skill.scope === 'plugin' && skill.invocation === '/example-skills:plugin-helper'));
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Codex skills discovery across repo/user/system locations and `$` invocation prefix.
+ */
+test('llmSkillsService lists codex skills from repo/user/system locations with dollar invocation', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-codex-'));
+  const repoRoot = path.join(tempRoot, 'repo');
+  const workspacePath = path.join(repoRoot, 'packages', 'app');
+  await fs.mkdir(workspacePath, { recursive: true });
+  await fs.mkdir(path.join(repoRoot, '.git'), { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await createSkill(path.join(workspacePath, '.agents', 'skills'), 'cwd-skill', {
+      name: 'cwd-skill',
+      description: 'cwd skill',
+    });
+    await createSkill(path.join(workspacePath, '..', '.agents', 'skills'), 'parent-skill', {
+      name: 'parent-skill',
+      description: 'parent skill',
+    });
+    await createSkill(path.join(repoRoot, '.agents', 'skills'), 'repo-root-skill', {
+      name: 'repo-root-skill',
+      description: 'repo root skill',
+    });
+    await createSkill(path.join(tempRoot, '.agents', 'skills'), 'user-skill', {
+      name: 'user-skill',
+      description: 'user skill',
+    });
+    await createSkill(path.join(tempRoot, '.codex', 'skills', '.system'), 'system-skill', {
+      name: 'system-skill',
+      description: 'system skill',
+    });
+
+    const skills = await llmSkillsService.listProviderSkills('codex', { workspacePath });
+    assert.ok(skills.some((skill) => skill.name === 'cwd-skill' && skill.invocation === '$cwd-skill'));
+    assert.ok(skills.some((skill) => skill.name === 'parent-skill' && skill.invocation === '$parent-skill'));
+    assert.ok(skills.some((skill) => skill.name === 'repo-root-skill' && skill.invocation === '$repo-root-skill'));
+    assert.ok(skills.some((skill) => skill.name === 'user-skill' && skill.invocation === '$user-skill'));
+    assert.ok(skills.some((skill) => skill.name === 'system-skill' && skill.invocation === '$system-skill'));
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Gemini skill fetch locations and slash-based invocation format.
+ */
+test('llmSkillsService lists gemini skills from documented directories', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-gemini-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await createSkill(path.join(tempRoot, '.gemini', 'skills'), 'home-gemini', {
+      name: 'home-gemini',
+      description: 'home gemini skill',
+    });
+    await createSkill(path.join(tempRoot, '.agents', 'skills'), 'home-agents', {
+      name: 'home-agents',
+      description: 'home agents skill',
+    });
+    await createSkill(path.join(workspacePath, '.gemini', 'skills'), 'project-gemini', {
+      name: 'project-gemini',
+      description: 'project gemini skill',
+    });
+    await createSkill(path.join(workspacePath, '.agents', 'skills'), 'project-agents', {
+      name: 'project-agents',
+      description: 'project agents skill',
+    });
+
+    const skills = await llmSkillsService.listProviderSkills('gemini', { workspacePath });
+    assert.ok(skills.some((skill) => skill.invocation === '/home-gemini'));
+    assert.ok(skills.some((skill) => skill.invocation === '/home-agents'));
+    assert.ok(skills.some((skill) => skill.invocation === '/project-gemini'));
+    assert.ok(skills.some((skill) => skill.invocation === '/project-agents'));
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Cursor skill fetch locations and slash-based invocation format.
+ */
+test('llmSkillsService lists cursor skills from documented directories', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-cursor-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await createSkill(path.join(workspacePath, '.agents', 'skills'), 'project-agents', {
+      name: 'project-agents',
+      description: 'project agents skill',
+    });
+    await createSkill(path.join(workspacePath, '.cursor', 'skills'), 'project-cursor', {
+      name: 'project-cursor',
+      description: 'project cursor skill',
+    });
+    await createSkill(path.join(tempRoot, '.cursor', 'skills'), 'user-cursor', {
+      name: 'user-cursor',
+      description: 'user cursor skill',
+    });
+
+    const skills = await llmSkillsService.listProviderSkills('cursor', { workspacePath });
+    assert.ok(skills.some((skill) => skill.invocation === '/project-agents'));
+    assert.ok(skills.some((skill) => skill.invocation === '/project-cursor'));
+    assert.ok(skills.some((skill) => skill.invocation === '/user-cursor'));
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+

server/src/modules/ai-runtime/types/auth.types.ts

@@ -0,0 +1,19 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+
+/**
+ * Provider authentication status normalized for frontend consumption.
+ */
+export type ProviderAuthStatus = {
+  provider: LLMProvider;
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+/**
+ * Auth runtime contract for one provider.
+ */
+export interface IProviderAuthRuntime {
+  getStatus(): Promise<ProviderAuthStatus>;
+}

server/src/modules/ai-runtime/types/index.ts

@@ -0,0 +1,5 @@
+export * from '@/modules/ai-runtime/types/provider.types.js';
+export * from '@/modules/ai-runtime/types/mcp.types.js';
+export * from '@/modules/ai-runtime/types/skills.types.js';
+export * from '@/modules/ai-runtime/types/session-synchronizer.types.js';
+export * from '@/modules/ai-runtime/types/auth.types.js';

server/src/modules/ai-runtime/types/mcp.types.ts

@@ -0,0 +1,66 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+
+export type McpScope = 'user' | 'local' | 'project';
+
+export type McpTransport = 'stdio' | 'http' | 'sse';
+
+/**
+ * Provider MCP server descriptor normalized for frontend consumption.
+ */
+export type ProviderMcpServer = {
+  provider: LLMProvider;
+  name: string;
+  scope: McpScope;
+  transport: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+/**
+ * Shared payload shape for MCP server create/update operations.
+ */
+export type UpsertProviderMcpServerInput = {
+  name: string;
+  scope?: McpScope;
+  transport: McpTransport;
+  workspacePath?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+/**
+ * MCP runtime contract for one provider.
+ */
+export interface IProviderMcpRuntime {
+  listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>>;
+  listServersForScope(scope: McpScope, options?: { workspacePath?: string }): Promise<ProviderMcpServer[]>;
+  upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer>;
+  removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }>;
+  runServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{
+    provider: LLMProvider;
+    name: string;
+    scope: McpScope;
+    transport: McpTransport;
+    reachable: boolean;
+    statusCode?: number;
+    error?: string;
+  }>;
+}

server/src/modules/ai-runtime/types/provider.types.ts

@@ -0,0 +1,104 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+import type { IProviderMcpRuntime } from '@/modules/ai-runtime/types/mcp.types.js';
+import type { IProviderSkillsRuntime } from '@/modules/ai-runtime/types/skills.types.js';
+import type { IProviderSessionSynchronizerRuntime } from '@/modules/ai-runtime/types/session-synchronizer.types.js';
+import type { IProviderAuthRuntime } from '@/modules/ai-runtime/types/auth.types.js';
+
+export type ProviderExecutionFamily = 'sdk' | 'cli';
+
+export type ProviderSessionStatus = 'running' | 'completed' | 'failed' | 'stopped';
+
+export type RuntimePermissionMode = 'ask' | 'allow' | 'deny';
+
+/**
+ * Advertises optional provider behaviors so route/service code can gate features.
+ */
+export type ProviderCapabilities = {
+  supportsRuntimePermissionRequests: boolean;
+  supportsThinkingModeControl: boolean;
+};
+
+/**
+ * Provider model descriptor normalized for frontend consumption.
+ */
+export type ProviderModel = {
+  value: string;
+  displayName: string;
+  description?: string;
+  default?: boolean;
+  current?: boolean;
+  supportsThinkingModes?: boolean;
+  supportedThinkingModes?: string[];
+};
+
+/**
+ * Unified in-memory event emitted while a provider session runs.
+ */
+export type ProviderSessionEvent = {
+  timestamp: string;
+  channel: 'sdk' | 'stdout' | 'stderr' | 'json' | 'system' | 'error';
+  message?: string;
+  data?: unknown;
+};
+
+/**
+ * Common launch/resume payload consumed by all providers.
+ */
+export type StartSessionInput = {
+  prompt: string;
+  workspacePath?: string;
+  sessionId?: string;
+  model?: string;
+  thinkingMode?: string;
+  imagePaths?: string[];
+  runtimePermissionMode?: RuntimePermissionMode;
+  allowYolo?: boolean;
+};
+
+/**
+ * Snapshot shape exposed externally for a provider session.
+ */
+export type ProviderSessionSnapshot = {
+  sessionId: string;
+  provider: LLMProvider;
+  family: ProviderExecutionFamily;
+  status: ProviderSessionStatus;
+  startedAt: string;
+  endedAt?: string;
+  model?: string;
+  thinkingMode?: string;
+  events: ProviderSessionEvent[];
+  error?: string;
+};
+
+/**
+ * Provider contract that both SDK and CLI families implement.
+ */
+export interface IProvider {
+  readonly id: LLMProvider;
+  readonly family: ProviderExecutionFamily;
+  readonly capabilities: ProviderCapabilities;
+  readonly mcp: IProviderMcpRuntime;
+  readonly skills: IProviderSkillsRuntime;
+  readonly sessionSynchronizer: IProviderSessionSynchronizerRuntime;
+  readonly auth: IProviderAuthRuntime;
+
+  listModels(): Promise<ProviderModel[]>;
+
+  launchSession(input: StartSessionInput): Promise<ProviderSessionSnapshot>;
+  resumeSession(input: StartSessionInput & { sessionId: string }): Promise<ProviderSessionSnapshot>;
+
+  stopSession(sessionId: string): Promise<boolean>;
+
+  getSession(sessionId: string): ProviderSessionSnapshot | null;
+  listSessions(): ProviderSessionSnapshot[];
+}
+
+/**
+ * Internal mutable session state used by provider base classes.
+ */
+export type MutableProviderSession = Omit<ProviderSessionSnapshot, 'events'> & {
+  events: ProviderSessionEvent[];
+  completion: Promise<void>;
+  stop: () => Promise<boolean>;
+};

server/src/modules/ai-runtime/types/session-synchronizer.types.ts

@@ -0,0 +1,14 @@
+/**
+ * Contract for provider-specific session indexing logic.
+ */
+export interface IProviderSessionSynchronizerRuntime {
+  /**
+   * Scans provider session artifacts and upserts discovered sessions into DB.
+   */
+  synchronize(since?: Date): Promise<number>;
+
+  /**
+   * Parses and upserts one provider artifact file without running a full directory scan.
+   */
+  synchronizeFile(filePath: string): Promise<boolean>;
+}

server/src/modules/ai-runtime/types/skills.types.ts

@@ -0,0 +1,23 @@
+import type { LLMProvider } from '@/shared/types/app.js';
+
+export type ProviderSkillScope = 'user' | 'project' | 'plugin' | 'repo' | 'admin' | 'system';
+
+/**
+ * Unified skill descriptor returned by provider skill runtimes.
+ */
+export type ProviderSkill = {
+  provider: LLMProvider;
+  scope: ProviderSkillScope;
+  name: string;
+  description?: string;
+  invocation: string;
+  filePath: string;
+  pluginName?: string;
+};
+
+/**
+ * Skills runtime contract for one provider.
+ */
+export interface IProviderSkillsRuntime {
+  listSkills(options?: { workspacePath?: string }): Promise<ProviderSkill[]>;
+}

server/src/modules/api-keys/api-keys.routes.js

@@ -0,0 +1,86 @@
+import express from 'express';
+import { apiKeysDb } from '@/shared/database/repositories/api-keys.js';
+
+const router = express.Router();
+
+// ===============================
+// API Keys Management
+// ===============================
+
+// Get all API keys for the authenticated user
+router.get('/', async (req, res) => {
+  try {
+    const apiKeys = apiKeysDb.getApiKeys(req.user.id);
+    // Don't send the full API key in the list for security
+    const sanitizedKeys = apiKeys.map(key => ({
+      ...key,
+      api_key: key.api_key.substring(0, 10) + '...'
+    }));
+    res.json({ apiKeys: sanitizedKeys });
+  } catch (error) {
+    console.error('Error fetching API keys:', error);
+    res.status(500).json({ error: 'Failed to fetch API keys' });
+  }
+});
+
+// Create a new API key
+router.post('/', async (req, res) => {
+  try {
+    const { keyName } = req.body;
+
+    if (!keyName || !keyName.trim()) {
+      return res.status(400).json({ error: 'Key name is required' });
+    }
+
+    const result = apiKeysDb.createApiKey(req.user.id, keyName.trim());
+    res.json({
+      success: true,
+      apiKey: result
+    });
+  } catch (error) {
+    console.error('Error creating API key:', error);
+    res.status(500).json({ error: 'Failed to create API key' });
+  }
+});
+
+// Delete an API key
+router.delete('/:keyId', async (req, res) => {
+  try {
+    const { keyId } = req.params;
+    const success = apiKeysDb.deleteApiKey(req.user.id, parseInt(keyId));
+
+    if (success) {
+      res.json({ success: true });
+    } else {
+      res.status(404).json({ error: 'API key not found' });
+    }
+  } catch (error) {
+    console.error('Error deleting API key:', error);
+    res.status(500).json({ error: 'Failed to delete API key' });
+  }
+});
+
+// Toggle API key active status
+router.patch('/:keyId/toggle', async (req, res) => {
+  try {
+    const { keyId } = req.params;
+    const { isActive } = req.body;
+
+    if (typeof isActive !== 'boolean') {
+      return res.status(400).json({ error: 'isActive must be a boolean' });
+    }
+
+    const success = apiKeysDb.toggleApiKey(req.user.id, parseInt(keyId), isActive);
+
+    if (success) {
+      res.json({ success: true });
+    } else {
+      res.status(404).json({ error: 'API key not found' });
+    }
+  } catch (error) {
+    console.error('Error toggling API key:', error);
+    res.status(500).json({ error: 'Failed to toggle API key' });
+  }
+});
+
+export default router;

server/src/modules/assets/assets.routes.ts

@@ -0,0 +1,74 @@
+import express, { type NextFunction, type Request, type Response } from 'express';
+import multer from 'multer';
+
+import { asyncHandler } from '@/shared/http/async-handler.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { createApiErrorResponse, createApiSuccessResponse } from '@/shared/http/api-response.js';
+import { llmAssetsService } from '@/modules/assets/assets.service.js';
+import { logger } from '@/shared/utils/logger.js';
+
+const router = express.Router();
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: {
+    files: 10,
+    fileSize: 20 * 1024 * 1024,
+  },
+});
+
+/**
+ * Reads optional query/body values and trims surrounding whitespace.
+ */
+const readOptionalQueryString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+/**
+ * Uploads one or more images into `.cloudcli/assets` so providers can reuse file paths.
+ */
+router.post(
+  '/images',
+  upload.array('images', 10),
+  asyncHandler(async (req: Request, res: Response) => {
+    const workspacePath = readOptionalQueryString((req.body as Record<string, unknown> | undefined)?.workspacePath);
+    const filesValue = (req as Request & { files?: unknown }).files;
+    const files = Array.isArray(filesValue) ? filesValue as Array<{
+      originalname: string;
+      mimetype: string;
+      size: number;
+      buffer: Buffer;
+    }> : [];
+    const images = await llmAssetsService.storeUploadedImages(files, { workspacePath });
+    res.status(201).json(createApiSuccessResponse({ images }));
+  }),
+);
+
+/**
+ * Normalizes route-level failures to a consistent JSON API shape.
+ */
+router.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
+  if (res.headersSent) {
+    return;
+  }
+
+  if (error instanceof AppError) {
+    res
+      .status(error.statusCode)
+      .json(createApiErrorResponse(error.code, error.message, undefined, error.details));
+    return;
+  }
+
+  const message = error instanceof Error ? error.message : 'Unexpected assets route failure.';
+  logger.error(message, {
+    module: 'assets.routes',
+  });
+
+  res.status(500).json(createApiErrorResponse('INTERNAL_ERROR', message));
+});
+
+export default router;

server/src/modules/assets/assets.service.ts

@@ -0,0 +1,85 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { AppError } from '@/shared/utils/app-error.js';
+
+const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+  'image/jpeg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+]);
+
+const MIME_TO_EXTENSION: Record<string, string> = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/gif': '.gif',
+  'image/webp': '.webp',
+};
+
+type UploadedImage = {
+  originalname: string;
+  mimetype: string;
+  size: number;
+  buffer: Buffer;
+};
+
+export type StoredImageAsset = {
+  originalName: string;
+  storedName: string;
+  absolutePath: string;
+  relativePath: string;
+  mimeType: string;
+  size: number;
+};
+
+/**
+ * Persists uploaded images in `.cloudcli/assets` and returns resolved paths for provider calls.
+ */
+export const llmAssetsService = {
+  async storeUploadedImages(
+    images: UploadedImage[],
+    options?: {
+      workspacePath?: string;
+    },
+  ): Promise<StoredImageAsset[]> {
+    if (!images.length) {
+      throw new AppError('At least one image file is required.', {
+        code: 'IMAGE_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const workspaceRoot = path.resolve(options?.workspacePath ?? process.cwd());
+    const assetsDirectory = path.join(workspaceRoot, '.cloudcli', 'assets');
+    await mkdir(assetsDirectory, { recursive: true });
+
+    const storedAssets: StoredImageAsset[] = [];
+    for (const image of images) {
+      if (!SUPPORTED_IMAGE_MIME_TYPES.has(image.mimetype)) {
+        throw new AppError(`Unsupported image type "${image.mimetype}".`, {
+          code: 'UNSUPPORTED_IMAGE_TYPE',
+          statusCode: 400,
+        });
+      }
+
+      const extension = (MIME_TO_EXTENSION[image.mimetype] ?? path.extname(image.originalname)) || '.img';
+      const storedName = `${Date.now()}-${randomUUID()}${extension}`;
+      const absolutePath = path.join(assetsDirectory, storedName);
+
+      await writeFile(absolutePath, image.buffer);
+
+      storedAssets.push({
+        originalName: image.originalname,
+        storedName,
+        absolutePath,
+        relativePath: path.relative(workspaceRoot, absolutePath).replace(/\\/g, '/'),
+        mimeType: image.mimetype,
+        size: image.size,
+      });
+    }
+
+    return storedAssets;
+  },
+};

server/src/modules/auth/auth.middleware.ts

@@ -0,0 +1,164 @@
+import type { Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { userDb } from '@/shared/database/repositories/users.js';
+import { appConfigDb } from '@/shared/database/repositories/app-config.js';
+import { IS_PLATFORM } from '@/config/env.js';
+import type { AuthenticatedRequest } from '@/shared/types/http.js';
+import { logger } from '@/shared/utils/logger.js';
+import { CreateUserResult } from '@/shared/database/types.js';
+
+// Use env var if set, otherwise auto-generate a unique secret per installation
+export const JWT_SECRET = process.env.JWT_SECRET || appConfigDb.getOrCreateJwtSecret();
+
+/**
+ * Optional API key middleware.
+ * If API_KEY is set in the environment, all requests to the API must include
+ * an 'x-api-key' header matching the configured value.
+ */
+export const validateApiKey = (req: AuthenticatedRequest, res: Response, next: NextFunction): void => {
+  // Skip API key validation if not configured
+  if (!process.env.API_KEY) {
+    next();
+    return;
+  }
+  
+  const apiKey = req.headers['x-api-key'];
+  if (apiKey !== process.env.API_KEY) {
+    res.status(401).json({ error: 'Invalid API key' });
+    return;
+  }
+  next();
+};
+
+/**
+ * JWT authentication middleware.
+ * Verifies the JWT token and attaches the user to the request object.
+ * In Platform mode, it bypasses JWT validation and uses the first database user.
+ */
+export const authenticateToken = async (
+  req: AuthenticatedRequest, 
+  res: Response, 
+  next: NextFunction
+): Promise<void> => {
+  // Platform mode: use single database user
+  if (IS_PLATFORM) {
+    try {
+      const user = userDb.getFirstUser();
+      if (!user) {
+        res.status(500).json({ error: 'Platform mode: No user found in database' });
+        return;
+      }
+      req.user = user;
+      next();
+      return;
+    } catch (error) {
+      logger.error('Platform mode error:', { error });
+      res.status(500).json({ error: 'Platform mode: Failed to fetch user' });
+      return;
+    }
+  }
+
+  // Normal OSS JWT validation
+  const authHeader = req.headers['authorization'];
+  let token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+  // Also check query param for SSE endpoints (EventSource can't set headers)
+  if (!token && req.query.token) {
+    token = req.query.token as string;
+  }
+
+  if (!token) {
+    res.status(401).json({ error: 'Access denied. No token provided.' });
+    return;
+  }
+
+  try {
+    const decoded = jwt.verify(token, JWT_SECRET) as jwt.JwtPayload;
+
+    // Verify user still exists and is active
+    if (!decoded.userId) {
+      res.status(401).json({ error: 'Invalid token payload.' });
+      return;
+    }
+
+    const user = userDb.getUserById(decoded.userId as number);
+    if (!user) {
+      res.status(401).json({ error: 'Invalid token. User not found.' });
+      return;
+    }
+
+    // Auto-refresh: if token is past halfway through its lifetime, issue a new one
+    if (decoded.exp && decoded.iat) {
+      const now = Math.floor(Date.now() / 1000);
+      const halfLife = (decoded.exp - decoded.iat) / 2;
+      if (now > decoded.iat + halfLife) {
+        const newToken = generateToken({ id: user.id, username: user.username });
+        res.setHeader('X-Refreshed-Token', newToken);
+      }
+    }
+
+    req.user = user;
+    next();
+  } catch (error) {
+    logger.error('Token verification error:', { error });
+    res.status(403).json({ error: 'Invalid token' });
+    return;
+  }
+};
+
+/**
+ * Generates a JWT token for the given user.
+ * Valid for 7 days.
+ */
+export const generateToken = (user: CreateUserResult): string => {
+  return jwt.sign(
+    {
+      userId: user.id,
+      username: user.username
+    },
+    JWT_SECRET,
+    { expiresIn: '7d' }
+  );
+};
+
+/**
+ * WebSocket authentication function.
+ * Validates a JWT token for WebSocket connections.
+ * Returns the authenticated user payload or null if invalid.
+ */
+export const authenticateWebSocket = (token: string | null): { userId: number; username: string; id?: number } | null => {
+  // Platform mode: bypass token validation, return first user
+  if (IS_PLATFORM) {
+    try {
+      const user = userDb.getFirstUser();
+      if (user) {
+        return { id: user.id, userId: user.id, username: user.username };
+      }
+      return null;
+    } catch (error) {
+      logger.error('Platform mode WebSocket error:', { error });
+      return null;
+    }
+  }
+
+  // Normal OSS JWT validation
+  if (!token) {
+    return null;
+  }
+
+  try {
+    const decoded = jwt.verify(token, JWT_SECRET) as jwt.JwtPayload;
+    
+    if (!decoded.userId) return null;
+
+    // Verify user actually exists in database (matches REST authenticateToken behavior)
+    const user = userDb.getUserById(decoded.userId as number);
+    if (!user) {
+      return null;
+    }
+    return { userId: user.id, username: user.username };
+  } catch (error) {
+    logger.error('WebSocket token verification error:', { error });
+    return null;
+  }
+};

server/src/modules/auth/auth.routes.ts

@@ -0,0 +1,159 @@
+import express, { type Request, type Response } from 'express';
+import bcrypt from 'bcrypt';
+import { userDb } from '@/shared/database/repositories/users.js';
+import { getConnection } from '@/shared/database/connection.js';
+import { generateToken, authenticateToken } from './auth.middleware.js';
+import type { AuthenticatedRequest } from '@/shared/types/http.js';
+import { logger } from '@/shared/utils/logger.js';
+
+export const authRoutes = express.Router();
+
+/**
+ * Check auth status and setup requirements
+ * GET /api/auth/status
+ */
+authRoutes.get('/status', (req: Request, res: Response) => {
+  try {
+    const hasUsers = userDb.hasUsers();
+    res.json({ 
+      needsSetup: !hasUsers,
+      isAuthenticated: false // Will be overridden by frontend if token exists
+    });
+  } catch (error) {
+    logger.error('Auth status error:', { error });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+/**
+ * User registration (setup) - only allowed if no users exist
+ * POST /api/auth/register
+ */
+authRoutes.post('/register', async (req: Request, res: Response): Promise<void> => {
+  try {
+    const { username, password } = req.body;
+    
+    // Validate input
+    if (!username || !password) {
+      res.status(400).json({ error: 'Username and password are required' });
+      return;
+    }
+    
+    if (username.length < 3 || password.length < 6) {
+      res.status(400).json({ error: 'Username must be at least 3 characters, password at least 6 characters' });
+      return;
+    }
+    
+    const db = getConnection();
+    
+    // Use a transaction to prevent race conditions
+    db.prepare('BEGIN').run();
+    try {
+      // Check if users already exist (only allow one user)
+      const hasUsers = userDb.hasUsers();
+      if (hasUsers) {
+        db.prepare('ROLLBACK').run();
+        res.status(403).json({ error: 'User already exists. This is a single-user system.' });
+        return;
+      }
+      
+      // Hash password
+      const saltRounds = 12;
+      const passwordHash = await bcrypt.hash(password, saltRounds);
+      
+      // Create user
+      const user = userDb.createUser(username, passwordHash);
+      
+      // Generate token
+      const token = generateToken(user);
+      
+      db.prepare('COMMIT').run();
+
+      // Update last login (non-fatal, outside transaction)
+      userDb.updateLastLogin(Number(user.id));
+
+      res.json({
+        success: true,
+        user: { id: user.id, username: user.username },
+        token
+      });
+    } catch (error) {
+      db.prepare('ROLLBACK').run();
+      throw error;
+    }
+    
+  } catch (error: any) {
+    logger.error('Registration error:', { error });
+    if (error.code === 'SQLITE_CONSTRAINT_UNIQUE') {
+      res.status(409).json({ error: 'Username already exists' });
+    } else {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+});
+
+/**
+ * User login
+ * POST /api/auth/login
+ */
+authRoutes.post('/login', async (req: Request, res: Response): Promise<void> => {
+  try {
+    const { username, password } = req.body;
+    
+    // Validate input
+    if (!username || !password) {
+      res.status(400).json({ error: 'Username and password are required' });
+      return;
+    }
+    
+    // Get user from database
+    const user = userDb.getUserByUsername(username);
+    if (!user) {
+      res.status(401).json({ error: 'Invalid username or password' });
+      return;
+    }
+    
+    // Verify password
+    const isValidPassword = await bcrypt.compare(password, user.password_hash);
+    if (!isValidPassword) {
+      res.status(401).json({ error: 'Invalid username or password' });
+      return;
+    }
+    
+    // Generate token
+    const token = generateToken(user);
+    
+    // Update last login
+    userDb.updateLastLogin(user.id);
+    
+    res.json({
+      success: true,
+      user: { id: user.id, username: user.username },
+      token
+    });
+    
+  } catch (error) {
+    logger.error('Login error:', { error });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+/**
+ * Get current user (protected route)
+ * GET /api/auth/user
+ */
+authRoutes.get('/user', authenticateToken, (req: AuthenticatedRequest, res: Response) => {
+  res.json({
+    user: req.user
+  });
+});
+
+/**
+ * Logout (client-side token removal, but this endpoint can be used for logging)
+ * POST /api/auth/logout
+ */
+authRoutes.post('/logout', authenticateToken, (req: AuthenticatedRequest, res: Response) => {
+  // In a simple JWT system, logout is mainly client-side
+  // This endpoint exists for consistency and potential future logging
+  res.json({ success: true, message: 'Logged out successfully' });
+});

server/src/modules/codex/codex.routes.js

@@ -0,0 +1,329 @@
+import express from 'express';
+import spawn from 'cross-spawn';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import TOML from '@iarna/toml';
+import { getCodexSessions } from '../../../projects.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+
+const router = express.Router();
+
+function createCliResponder(res) {
+  let responded = false;
+  return (status, payload) => {
+    if (responded || res.headersSent) {
+      return;
+    }
+    responded = true;
+    res.status(status).json(payload);
+  };
+}
+
+router.get('/config', async (req, res) => {
+  try {
+    const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+    const content = await fs.readFile(configPath, 'utf8');
+    const config = TOML.parse(content);
+
+    res.json({
+      success: true,
+      config: {
+        model: config.model || null,
+        mcpServers: config.mcp_servers || {},
+        approvalMode: config.approval_mode || 'suggest'
+      }
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      res.json({
+        success: true,
+        config: {
+          model: null,
+          mcpServers: {},
+          approvalMode: 'suggest'
+        }
+      });
+    } else {
+      console.error('Error reading Codex config:', error);
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+});
+
+router.get('/sessions', async (req, res) => {
+  try {
+    const { projectPath } = req.query;
+
+    if (!projectPath) {
+      return res.status(400).json({ success: false, error: 'projectPath query parameter required' });
+    }
+
+    const sessions = await getCodexSessions(projectPath);
+    sessionsDb.applyCustomSessionNames(sessions, 'codex');
+    res.json({ success: true, sessions });
+  } catch (error) {
+    console.error('Error fetching Codex sessions:', error);
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+router.delete('/sessions/:sessionId', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    await llmSessionsService.deleteSessionArtifacts(sessionId);
+    res.json({ success: true });
+  } catch (error) {
+    console.error(`Error deleting Codex session ${req.params.sessionId}:`, error);
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+// MCP Server Management Routes
+
+router.get('/mcp/cli/list', async (req, res) => {
+  try {
+    const respond = createCliResponder(res);
+    const proc = spawn('codex', ['mcp', 'list'], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
+    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        respond(200, { success: true, output: stdout, servers: parseCodexListOutput(stdout) });
+      } else {
+        respond(500, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
+      }
+    });
+
+    proc.on('error', (error) => {
+      const isMissing = error?.code === 'ENOENT';
+      respond(isMissing ? 503 : 500, {
+        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
+        details: error.message,
+        code: error.code
+      });
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to list MCP servers', details: error.message });
+  }
+});
+
+router.post('/mcp/cli/add', async (req, res) => {
+  try {
+    const { name, command, args = [], env = {} } = req.body;
+
+    if (!name || !command) {
+      return res.status(400).json({ error: 'name and command are required' });
+    }
+
+    // Build: codex mcp add <name> [-e KEY=VAL]... -- <command> [args...]
+    let cliArgs = ['mcp', 'add', name];
+
+    Object.entries(env).forEach(([key, value]) => {
+      cliArgs.push('-e', `${key}=${value}`);
+    });
+
+    cliArgs.push('--', command);
+
+    if (args && args.length > 0) {
+      cliArgs.push(...args);
+    }
+
+    const respond = createCliResponder(res);
+    const proc = spawn('codex', cliArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
+    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        respond(200, { success: true, output: stdout, message: `MCP server "${name}" added successfully` });
+      } else {
+        respond(400, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
+      }
+    });
+
+    proc.on('error', (error) => {
+      const isMissing = error?.code === 'ENOENT';
+      respond(isMissing ? 503 : 500, {
+        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
+        details: error.message,
+        code: error.code
+      });
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
+  }
+});
+
+router.delete('/mcp/cli/remove/:name', async (req, res) => {
+  try {
+    const { name } = req.params;
+
+    const respond = createCliResponder(res);
+    const proc = spawn('codex', ['mcp', 'remove', name], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
+    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        respond(200, { success: true, output: stdout, message: `MCP server "${name}" removed successfully` });
+      } else {
+        respond(400, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
+      }
+    });
+
+    proc.on('error', (error) => {
+      const isMissing = error?.code === 'ENOENT';
+      respond(isMissing ? 503 : 500, {
+        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
+        details: error.message,
+        code: error.code
+      });
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to remove MCP server', details: error.message });
+  }
+});
+
+router.get('/mcp/cli/get/:name', async (req, res) => {
+  try {
+    const { name } = req.params;
+
+    const respond = createCliResponder(res);
+    const proc = spawn('codex', ['mcp', 'get', name], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
+    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        respond(200, { success: true, output: stdout, server: parseCodexGetOutput(stdout) });
+      } else {
+        respond(404, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
+      }
+    });
+
+    proc.on('error', (error) => {
+      const isMissing = error?.code === 'ENOENT';
+      respond(isMissing ? 503 : 500, {
+        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
+        details: error.message,
+        code: error.code
+      });
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to get MCP server details', details: error.message });
+  }
+});
+
+router.get('/mcp/config/read', async (req, res) => {
+  try {
+    const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+
+    let configData = null;
+
+    try {
+      const fileContent = await fs.readFile(configPath, 'utf8');
+      configData = TOML.parse(fileContent);
+    } catch (error) {
+      // Config file doesn't exist
+    }
+
+    if (!configData) {
+      return res.json({ success: true, configPath, servers: [] });    }
+
+    const servers = [];
+
+    if (configData.mcp_servers && typeof configData.mcp_servers === 'object') {
+      for (const [name, config] of Object.entries(configData.mcp_servers)) {
+        servers.push({
+          id: name,
+          name: name,
+          type: 'stdio',
+          scope: 'user',
+          config: {
+            command: config.command || '',
+            args: config.args || [],
+            env: config.env || {}
+          },
+          raw: config
+        });
+      }
+    }
+
+    res.json({ success: true, configPath, servers });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to read Codex configuration', details: error.message });
+  }
+});
+
+function parseCodexListOutput(output) {
+  const servers = [];
+  const lines = output.split('\n').filter(line => line.trim());
+
+  for (const line of lines) {
+    if (line.includes(':')) {
+      const colonIndex = line.indexOf(':');
+      const name = line.substring(0, colonIndex).trim();
+
+      if (!name) continue;
+
+      const rest = line.substring(colonIndex + 1).trim();
+      let description = rest;
+      let status = 'unknown';
+
+      if (rest.includes('✓') || rest.includes('✗')) {
+        const statusMatch = rest.match(/(.*?)\s*-\s*([✓✗].*)$/);
+        if (statusMatch) {
+          description = statusMatch[1].trim();
+          status = statusMatch[2].includes('✓') ? 'connected' : 'failed';
+        }
+      }
+
+      servers.push({ name, type: 'stdio', status, description });
+    }
+  }
+
+  return servers;
+}
+
+function parseCodexGetOutput(output) {
+  try {
+    const jsonMatch = output.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+
+    const server = { raw_output: output };
+    const lines = output.split('\n');
+
+    for (const line of lines) {
+      if (line.includes('Name:')) server.name = line.split(':')[1]?.trim();
+      else if (line.includes('Type:')) server.type = line.split(':')[1]?.trim();
+      else if (line.includes('Command:')) server.command = line.split(':')[1]?.trim();
+    }
+
+    return server;
+  } catch (error) {
+    return { raw_output: output, parse_error: error.message };
+  }
+}
+
+export default router;

server/src/modules/commands/commands.routes.js

@@ -0,0 +1,601 @@
+import express from 'express';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import os from 'os';
+import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '../../../../shared/modelConstants.js';
+import { parseFrontmatter } from '../../../utils/frontmatter.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const router = express.Router();
+
+/**
+ * Recursively scan directory for command files (.md)
+ * @param {string} dir - Directory to scan
+ * @param {string} baseDir - Base directory for relative paths
+ * @param {string} namespace - Namespace for commands (e.g., 'project', 'user')
+ * @returns {Promise<Array>} Array of command objects
+ */
+async function scanCommandsDirectory(dir, baseDir, namespace) {
+  const commands = [];
+
+  try {
+    // Check if directory exists
+    await fs.access(dir);
+
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Recursively scan subdirectories
+        const subCommands = await scanCommandsDirectory(fullPath, baseDir, namespace);
+        commands.push(...subCommands);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Parse markdown file for metadata
+        try {
+          const content = await fs.readFile(fullPath, 'utf8');
+          const { data: frontmatter, content: commandContent } = parseFrontmatter(content);
+
+          // Calculate relative path from baseDir for command name
+          const relativePath = path.relative(baseDir, fullPath);
+          // Remove .md extension and convert to command name
+          const commandName = '/' + relativePath.replace(/\.md$/, '').replace(/\\/g, '/');
+
+          // Extract description from frontmatter or first line of content
+          let description = frontmatter.description || '';
+          if (!description) {
+            const firstLine = commandContent.trim().split('\n')[0];
+            description = firstLine.replace(/^#+\s*/, '').trim();
+          }
+
+          commands.push({
+            name: commandName,
+            path: fullPath,
+            relativePath,
+            description,
+            namespace,
+            metadata: frontmatter
+          });
+        } catch (err) {
+          console.error(`Error parsing command file ${fullPath}:`, err.message);
+        }
+      }
+    }
+  } catch (err) {
+    // Directory doesn't exist or can't be accessed - this is okay
+    if (err.code !== 'ENOENT' && err.code !== 'EACCES') {
+      console.error(`Error scanning directory ${dir}:`, err.message);
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Built-in commands that are always available
+ */
+const builtInCommands = [
+  {
+    name: '/help',
+    description: 'Show help documentation for Claude Code',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/clear',
+    description: 'Clear the conversation history',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/model',
+    description: 'Switch or view the current AI model',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/cost',
+    description: 'Display token usage and cost information',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/memory',
+    description: 'Open CLAUDE.md memory file for editing',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/config',
+    description: 'Open settings and configuration',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/status',
+    description: 'Show system status and version information',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
+  {
+    name: '/rewind',
+    description: 'Rewind the conversation to a previous state',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  }
+];
+
+/**
+ * Built-in command handlers
+ * Each handler returns { type: 'builtin', action: string, data: any }
+ */
+const builtInHandlers = {
+  '/help': async (args, context) => {
+    const helpText = `# Claude Code Commands
+
+## Built-in Commands
+
+${builtInCommands.map(cmd => `### ${cmd.name}
+${cmd.description}
+`).join('\n')}
+
+## Custom Commands
+
+Custom commands can be created in:
+- Project: \`.claude/commands/\` (project-specific)
+- User: \`~/.claude/commands/\` (available in all projects)
+
+### Command Syntax
+
+- **Arguments**: Use \`$ARGUMENTS\` for all args or \`$1\`, \`$2\`, etc. for positional
+- **File Includes**: Use \`@filename\` to include file contents
+- **Bash Commands**: Use \`!command\` to execute bash commands
+
+### Examples
+
+\`\`\`markdown
+/mycommand arg1 arg2
+\`\`\`
+`;
+
+    return {
+      type: 'builtin',
+      action: 'help',
+      data: {
+        content: helpText,
+        format: 'markdown'
+      }
+    };
+  },
+
+  '/clear': async (args, context) => {
+    return {
+      type: 'builtin',
+      action: 'clear',
+      data: {
+        message: 'Conversation history cleared'
+      }
+    };
+  },
+
+  '/model': async (args, context) => {
+    // Read available models from centralized constants
+    const availableModels = {
+      claude: CLAUDE_MODELS.OPTIONS.map(o => o.value),
+      cursor: CURSOR_MODELS.OPTIONS.map(o => o.value),
+      codex: CODEX_MODELS.OPTIONS.map(o => o.value)
+    };
+
+    const currentProvider = context?.provider || 'claude';
+    const currentModel = context?.model || CLAUDE_MODELS.DEFAULT;
+
+    return {
+      type: 'builtin',
+      action: 'model',
+      data: {
+        current: {
+          provider: currentProvider,
+          model: currentModel
+        },
+        available: availableModels,
+        message: args.length > 0
+          ? `Switching to model: ${args[0]}`
+          : `Current model: ${currentModel}`
+      }
+    };
+  },
+
+  '/cost': async (args, context) => {
+    const tokenUsage = context?.tokenUsage || {};
+    const provider = context?.provider || 'claude';
+    const model =
+      context?.model ||
+      (provider === 'cursor'
+        ? CURSOR_MODELS.DEFAULT
+        : provider === 'codex'
+          ? CODEX_MODELS.DEFAULT
+          : CLAUDE_MODELS.DEFAULT);
+
+    const used = Number(tokenUsage.used ?? tokenUsage.totalUsed ?? tokenUsage.total_tokens ?? 0) || 0;
+    const total =
+      Number(
+        tokenUsage.total ??
+          tokenUsage.contextWindow ??
+          parseInt(process.env.CONTEXT_WINDOW || '160000', 10),
+      ) || 160000;
+    const percentage = total > 0 ? Number(((used / total) * 100).toFixed(1)) : 0;
+
+    const inputTokensRaw =
+      Number(
+        tokenUsage.inputTokens ??
+          tokenUsage.input ??
+          tokenUsage.cumulativeInputTokens ??
+          tokenUsage.promptTokens ??
+          0,
+      ) || 0;
+    const outputTokens =
+      Number(
+        tokenUsage.outputTokens ??
+          tokenUsage.output ??
+          tokenUsage.cumulativeOutputTokens ??
+          tokenUsage.completionTokens ??
+          0,
+      ) || 0;
+    const cacheTokens =
+      Number(
+        tokenUsage.cacheReadTokens ??
+          tokenUsage.cacheCreationTokens ??
+          tokenUsage.cacheTokens ??
+          tokenUsage.cachedTokens ??
+          0,
+      ) || 0;
+
+    // If we only have total used tokens, treat them as input for display/estimation.
+    const inputTokens =
+      inputTokensRaw > 0 || outputTokens > 0 || cacheTokens > 0 ? inputTokensRaw + cacheTokens : used;
+
+    // Rough default rates by provider (USD / 1M tokens).
+    const pricingByProvider = {
+      claude: { input: 3, output: 15 },
+      cursor: { input: 3, output: 15 },
+      codex: { input: 1.5, output: 6 },
+    };
+    const rates = pricingByProvider[provider] || pricingByProvider.claude;
+
+    const inputCost = (inputTokens / 1_000_000) * rates.input;
+    const outputCost = (outputTokens / 1_000_000) * rates.output;
+    const totalCost = inputCost + outputCost;
+
+    return {
+      type: 'builtin',
+      action: 'cost',
+      data: {
+        tokenUsage: {
+          used,
+          total,
+          percentage,
+        },
+        cost: {
+          input: inputCost.toFixed(4),
+          output: outputCost.toFixed(4),
+          total: totalCost.toFixed(4),
+        },
+        model,
+      },
+    };
+  },
+
+  '/status': async (args, context) => {
+    // Read version from package.json
+    const packageJsonPath = path.join(path.dirname(__dirname), '..', 'package.json');
+    let version = 'unknown';
+    let packageName = 'claude-code-ui';
+
+    try {
+      const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+      version = packageJson.version;
+      packageName = packageJson.name;
+    } catch (err) {
+      console.error('Error reading package.json:', err);
+    }
+
+    const uptime = process.uptime();
+    const uptimeMinutes = Math.floor(uptime / 60);
+    const uptimeHours = Math.floor(uptimeMinutes / 60);
+    const uptimeFormatted = uptimeHours > 0
+      ? `${uptimeHours}h ${uptimeMinutes % 60}m`
+      : `${uptimeMinutes}m`;
+
+    return {
+      type: 'builtin',
+      action: 'status',
+      data: {
+        version,
+        packageName,
+        uptime: uptimeFormatted,
+        uptimeSeconds: Math.floor(uptime),
+        model: context?.model || 'claude-sonnet-4.5',
+        provider: context?.provider || 'claude',
+        nodeVersion: process.version,
+        platform: process.platform
+      }
+    };
+  },
+
+  '/memory': async (args, context) => {
+    const projectPath = context?.projectPath;
+
+    if (!projectPath) {
+      return {
+        type: 'builtin',
+        action: 'memory',
+        data: {
+          error: 'No project selected',
+          message: 'Please select a project to access its CLAUDE.md file'
+        }
+      };
+    }
+
+    const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+
+    // Check if CLAUDE.md exists
+    let exists = false;
+    try {
+      await fs.access(claudeMdPath);
+      exists = true;
+    } catch (err) {
+      // File doesn't exist
+    }
+
+    return {
+      type: 'builtin',
+      action: 'memory',
+      data: {
+        path: claudeMdPath,
+        exists,
+        message: exists
+          ? `Opening CLAUDE.md at ${claudeMdPath}`
+          : `CLAUDE.md not found at ${claudeMdPath}. Create it to store project-specific instructions.`
+      }
+    };
+  },
+
+  '/config': async (args, context) => {
+    return {
+      type: 'builtin',
+      action: 'config',
+      data: {
+        message: 'Opening settings...'
+      }
+    };
+  },
+
+  '/rewind': async (args, context) => {
+    const steps = args[0] ? parseInt(args[0]) : 1;
+
+    if (isNaN(steps) || steps < 1) {
+      return {
+        type: 'builtin',
+        action: 'rewind',
+        data: {
+          error: 'Invalid steps parameter',
+          message: 'Usage: /rewind [number] - Rewind conversation by N steps (default: 1)'
+        }
+      };
+    }
+
+    return {
+      type: 'builtin',
+      action: 'rewind',
+      data: {
+        steps,
+        message: `Rewinding conversation by ${steps} step${steps > 1 ? 's' : ''}...`
+      }
+    };
+  }
+};
+
+/**
+ * POST /api/commands/list
+ * List all available commands from project and user directories
+ */
+router.post('/list', async (req, res) => {
+  try {
+    const { projectPath } = req.body;
+    const allCommands = [...builtInCommands];
+
+    // Scan project-level commands (.claude/commands/)
+    if (projectPath) {
+      const projectCommandsDir = path.join(projectPath, '.claude', 'commands');
+      const projectCommands = await scanCommandsDirectory(
+        projectCommandsDir,
+        projectCommandsDir,
+        'project'
+      );
+      allCommands.push(...projectCommands);
+    }
+
+    // Scan user-level commands (~/.claude/commands/)
+    const homeDir = os.homedir();
+    const userCommandsDir = path.join(homeDir, '.claude', 'commands');
+    const userCommands = await scanCommandsDirectory(
+      userCommandsDir,
+      userCommandsDir,
+      'user'
+    );
+    allCommands.push(...userCommands);
+
+    // Separate built-in and custom commands
+    const customCommands = allCommands.filter(cmd => cmd.namespace !== 'builtin');
+
+    // Sort commands alphabetically by name
+    customCommands.sort((a, b) => a.name.localeCompare(b.name));
+
+    res.json({
+      builtIn: builtInCommands,
+      custom: customCommands,
+      count: allCommands.length
+    });
+  } catch (error) {
+    console.error('Error listing commands:', error);
+    res.status(500).json({
+      error: 'Failed to list commands',
+      message: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/commands/load
+ * Load a specific command file and return its content and metadata
+ */
+router.post('/load', async (req, res) => {
+  try {
+    const { commandPath } = req.body;
+
+    if (!commandPath) {
+      return res.status(400).json({
+        error: 'Command path is required'
+      });
+    }
+
+    // Security: Prevent path traversal
+    const resolvedPath = path.resolve(commandPath);
+    if (!resolvedPath.startsWith(path.resolve(os.homedir())) &&
+        !resolvedPath.includes('.claude/commands')) {
+      return res.status(403).json({
+        error: 'Access denied',
+        message: 'Command must be in .claude/commands directory'
+      });
+    }
+
+    // Read and parse the command file
+    const content = await fs.readFile(commandPath, 'utf8');
+    const { data: metadata, content: commandContent } = parseFrontmatter(content);
+
+    res.json({
+      path: commandPath,
+      metadata,
+      content: commandContent
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return res.status(404).json({
+        error: 'Command not found',
+        message: `Command file not found: ${req.body.commandPath}`
+      });
+    }
+
+    console.error('Error loading command:', error);
+    res.status(500).json({
+      error: 'Failed to load command',
+      message: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/commands/execute
+ * Execute a command with argument replacement
+ * This endpoint prepares the command content but doesn't execute bash commands yet
+ * (that will be handled in the command parser utility)
+ */
+router.post('/execute', async (req, res) => {
+  try {
+    const { commandName, commandPath, args = [], context = {} } = req.body;
+
+    if (!commandName) {
+      return res.status(400).json({
+        error: 'Command name is required'
+      });
+    }
+
+    // Handle built-in commands
+    const handler = builtInHandlers[commandName];
+    if (handler) {
+      try {
+        const result = await handler(args, context);
+        return res.json({
+          ...result,
+          command: commandName
+        });
+      } catch (error) {
+        console.error(`Error executing built-in command ${commandName}:`, error);
+        return res.status(500).json({
+          error: 'Command execution failed',
+          message: error.message,
+          command: commandName
+        });
+      }
+    }
+
+    // Handle custom commands
+    if (!commandPath) {
+      return res.status(400).json({
+        error: 'Command path is required for custom commands'
+      });
+    }
+
+    // Load command content
+    // Security: validate commandPath is within allowed directories
+    {
+      const resolvedPath = path.resolve(commandPath);
+      const userBase = path.resolve(path.join(os.homedir(), '.claude', 'commands'));
+      const projectBase = context?.projectPath
+        ? path.resolve(path.join(context.projectPath, '.claude', 'commands'))
+        : null;
+      const isUnder = (base) => {
+        const rel = path.relative(base, resolvedPath);
+        return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+      };
+      if (!(isUnder(userBase) || (projectBase && isUnder(projectBase)))) {
+        return res.status(403).json({
+          error: 'Access denied',
+          message: 'Command must be in .claude/commands directory'
+        });
+      }
+    }
+    const content = await fs.readFile(commandPath, 'utf8');
+    const { data: metadata, content: commandContent } = parseFrontmatter(content);
+    // Basic argument replacement (will be enhanced in command parser utility)
+    let processedContent = commandContent;
+
+    // Replace $ARGUMENTS with all arguments joined
+    const argsString = args.join(' ');
+    processedContent = processedContent.replace(/\$ARGUMENTS/g, argsString);
+
+    // Replace $1, $2, etc. with positional arguments
+    args.forEach((arg, index) => {
+      const placeholder = `$${index + 1}`;
+      processedContent = processedContent.replace(new RegExp(`\\${placeholder}\\b`, 'g'), arg);
+    });
+
+    res.json({
+      type: 'custom',
+      command: commandName,
+      content: processedContent,
+      metadata,
+      hasFileIncludes: processedContent.includes('@'),
+      hasBashCommands: processedContent.includes('!')
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return res.status(404).json({
+        error: 'Command not found',
+        message: `Command file not found: ${req.body.commandPath}`
+      });
+    }
+
+    console.error('Error executing command:', error);
+    res.status(500).json({
+      error: 'Failed to execute command',
+      message: error.message
+    });
+  }
+});
+
+export default router;

server/src/modules/conversations/conversation-search.service.ts

@@ -0,0 +1,264 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { once } from 'node:events';
+
+import spawn from 'cross-spawn';
+
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { AppError } from '@/shared/utils/app-error.js';
+
+type SearchResult = {
+  sessionId: string;
+  provider: string;
+  filePath: string;
+  lineNumber: number;
+  lineText: string;
+};
+
+type SearchInput = {
+  query: string;
+  provider?: string;
+  caseSensitive?: boolean;
+  limit?: number;
+  signal?: AbortSignal;
+};
+
+/**
+ * Normalizes file paths so DB session paths match ripgrep paths across platforms.
+ */
+const normalizePathForLookup = (filePath: string): string =>
+  process.platform === 'win32' ? path.normalize(filePath).toLowerCase() : path.normalize(filePath);
+
+/**
+ * Searches all indexed session transcript files for a text query.
+ */
+export const conversationSearchService = {
+  /**
+   * Uses ripgrep first for speed, then falls back to direct file scanning.
+   */
+  async search(input: SearchInput): Promise<SearchResult[]> {
+    const query = input.query.trim();
+    if (!query) {
+      throw new AppError('query is required.', {
+        code: 'SEARCH_QUERY_REQUIRED',
+        statusCode: 400,
+      });
+    }
+    if (input.signal?.aborted) {
+      return [];
+    }
+
+    const limit = Math.min(Math.max(input.limit ?? 50, 1), 500);
+    const allSessions = sessionsDb
+      .getAllSessions()
+      .filter((session) => Boolean(session.jsonl_path))
+      .filter((session) => (input.provider ? session.provider === input.provider : true));
+
+    if (allSessions.length === 0) {
+      return [];
+    }
+
+    const sessionByFile = new Map(
+      allSessions
+        .filter((session): session is typeof session & { jsonl_path: string } => Boolean(session.jsonl_path))
+        .map((session) => [normalizePathForLookup(session.jsonl_path), session]),
+    );
+
+    const uniqueDirectories = [...new Set(allSessions.map((session) => path.dirname(session.jsonl_path as string)))];
+    const rgResults = await runRipgrepSearch(query, uniqueDirectories, {
+      caseSensitive: input.caseSensitive ?? false,
+      limit,
+      signal: input.signal,
+    });
+
+    if (rgResults.length > 0) {
+      const mappedResults: SearchResult[] = [];
+
+      for (const match of rgResults) {
+        const session = sessionByFile.get(normalizePathForLookup(match.filePath));
+        if (!session) {
+          continue;
+        }
+
+        mappedResults.push({
+          sessionId: session.session_id,
+          provider: session.provider,
+          filePath: match.filePath,
+          lineNumber: match.lineNumber,
+          lineText: match.lineText,
+        });
+
+        if (mappedResults.length >= limit) {
+          break;
+        }
+      }
+
+      return mappedResults;
+    }
+
+    return fallbackFileSearch(query, sessionByFile, {
+      caseSensitive: input.caseSensitive ?? false,
+      limit,
+      signal: input.signal,
+    });
+  },
+};
+
+/**
+ * Runs ripgrep in JSON mode and maps each match to a minimal search shape.
+ */
+async function runRipgrepSearch(
+  query: string,
+  directories: string[],
+  options: {
+    caseSensitive: boolean;
+    limit: number;
+    signal?: AbortSignal;
+  },
+): Promise<Array<{ filePath: string; lineNumber: number; lineText: string }>> {
+  if (options.signal?.aborted) {
+    return [];
+  }
+
+  const args = ['--json', '--line-number', '--no-heading'];
+
+  if (!options.caseSensitive) {
+    args.push('-i');
+  }
+
+  args.push('--max-count', String(options.limit), '--', query, ...directories);
+
+  const child = spawn('rg', args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    cwd: process.cwd(),
+    env: process.env,
+  });
+  const abortListener = () => {
+    if (!child.killed && child.exitCode === null) {
+      child.kill('SIGTERM');
+    }
+  };
+  options.signal?.addEventListener('abort', abortListener, { once: true });
+
+  let stdout = '';
+  child.stdout?.on('data', (chunk) => {
+    stdout += chunk.toString();
+  });
+
+  try {
+    const closePromise = once(child, 'close');
+    const errorPromise = once(child, 'error').then(([error]) => {
+      throw error;
+    });
+    await Promise.race([closePromise, errorPromise]);
+  } catch {
+    options.signal?.removeEventListener('abort', abortListener);
+    return [];
+  }
+  options.signal?.removeEventListener('abort', abortListener);
+
+  if (child.exitCode !== 0 && child.exitCode !== 1) {
+    return [];
+  }
+  if (options.signal?.aborted) {
+    return [];
+  }
+
+  const matches: Array<{ filePath: string; lineNumber: number; lineText: string }> = [];
+
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    let parsed: any;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (parsed?.type !== 'match') {
+      continue;
+    }
+
+    const filePath = parsed?.data?.path?.text;
+    const lineNumber = parsed?.data?.line_number;
+    const lineText = parsed?.data?.lines?.text;
+
+    if (
+      typeof filePath !== 'string' ||
+      typeof lineNumber !== 'number' ||
+      typeof lineText !== 'string'
+    ) {
+      continue;
+    }
+
+    matches.push({
+      filePath,
+      lineNumber,
+      lineText: lineText.trimEnd(),
+    });
+
+    if (matches.length >= options.limit) {
+      break;
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Fallback search path when ripgrep is unavailable or returns no structured matches.
+ */
+async function fallbackFileSearch(
+  query: string,
+  sessionByFile: Map<string, { session_id: string; provider: string; jsonl_path: string | null }>,
+  options: {
+    caseSensitive: boolean;
+    limit: number;
+    signal?: AbortSignal;
+  },
+): Promise<SearchResult[]> {
+  const results: SearchResult[] = [];
+  const queryForMatch = options.caseSensitive ? query : query.toLowerCase();
+
+  for (const [, session] of sessionByFile) {
+    if (options.signal?.aborted) {
+      return results;
+    }
+
+    if (!session.jsonl_path) {
+      continue;
+    }
+
+    const content = await readFile(session.jsonl_path, 'utf8');
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      if (options.signal?.aborted) {
+        return results;
+      }
+
+      const line = lines[index];
+      const source = options.caseSensitive ? line : line.toLowerCase();
+
+      if (!source.includes(queryForMatch)) {
+        continue;
+      }
+
+      results.push({
+        sessionId: session.session_id,
+        provider: session.provider,
+        filePath: session.jsonl_path,
+        lineNumber: index + 1,
+        lineText: line,
+      });
+
+      if (results.length >= options.limit) {
+        return results;
+      }
+    }
+  }
+
+  return results;
+}

server/src/modules/conversations/conversations.routes.ts

@@ -0,0 +1,432 @@
+import express, { type NextFunction, type Request, type Response } from 'express';
+import path from 'node:path';
+
+import { conversationSearchService } from '@/modules/conversations/conversation-search.service.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { workspaceOriginalPathsDb } from '@/shared/database/repositories/workspace-original-paths.db.js';
+import { AppError } from '@/shared/utils/app-error.js';
+import { createApiErrorResponse } from '@/shared/http/api-response.js';
+import { logger } from '@/shared/utils/logger.js';
+
+const router = express.Router();
+
+type SearchResult = Awaited<ReturnType<typeof conversationSearchService.search>>[number];
+
+type ConversationSearchHighlight = {
+  start: number;
+  end: number;
+};
+
+type ConversationSearchMatch = {
+  role: 'user' | 'assistant';
+  snippet: string;
+  highlights: ConversationSearchHighlight[];
+  timestamp: string | null;
+  provider: string;
+  messageUuid: string | null;
+};
+
+type ConversationSearchSession = {
+  sessionId: string;
+  provider: string;
+  sessionSummary: string;
+  matches: ConversationSearchMatch[];
+};
+
+type ConversationSearchProjectResult = {
+  projectName: string;
+  projectDisplayName: string;
+  sessions: ConversationSearchSession[];
+};
+
+const normalizeQueryWords = (query: string): string[] =>
+  [...new Set(query.toLowerCase().split(/\s+/).filter((word) => word.length > 0))];
+
+const normalizeWhitespace = (value: string): string => value.replace(/\s+/g, ' ').trim();
+
+const readOptionalString = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+};
+
+const readOptionalTimestamp = (value: unknown): string | null => {
+  if (typeof value === 'string') {
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) {
+      return parsed.toISOString();
+    }
+  }
+
+  return null;
+};
+
+const encodeLegacyProjectName = (workspacePath: string): string =>
+  workspacePath.replace(/[\\/:\s~_]/g, '-');
+
+const getWorkspaceDisplayName = (workspacePath: string, customWorkspaceName: string | null): string => {
+  if (customWorkspaceName?.trim()) {
+    return customWorkspaceName.trim();
+  }
+
+  const normalizedPath = workspacePath.trim().replace(/[\\/]+$/, '');
+  const baseName = path.basename(normalizedPath);
+  return baseName || workspacePath;
+};
+
+const collectTextFromMessageContent = (content: unknown): string | null => {
+  if (typeof content === 'string') {
+    const normalized = normalizeWhitespace(content);
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  if (Array.isArray(content)) {
+    const text = content
+      .map((part) => {
+        if (!part || typeof part !== 'object') {
+          return '';
+        }
+
+        const textPart = (part as Record<string, unknown>).text;
+        return typeof textPart === 'string' ? textPart : '';
+      })
+      .join(' ');
+    const normalized = normalizeWhitespace(text);
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  return null;
+};
+
+const parseLineMatchPayload = (lineText: string): {
+  role: 'user' | 'assistant';
+  text: string;
+  timestamp: string | null;
+  messageUuid: string | null;
+} => {
+  const defaultPayload = {
+    role: 'assistant' as const,
+    text: normalizeWhitespace(lineText),
+    timestamp: null,
+    messageUuid: null,
+  };
+
+  let parsedLine: unknown;
+  try {
+    parsedLine = JSON.parse(lineText);
+  } catch {
+    return defaultPayload;
+  }
+
+  if (!parsedLine || typeof parsedLine !== 'object' || Array.isArray(parsedLine)) {
+    return defaultPayload;
+  }
+
+  const parsedRecord = parsedLine as Record<string, unknown>;
+  const message = parsedRecord.message;
+  const messageRecord =
+    message && typeof message === 'object' && !Array.isArray(message)
+      ? (message as Record<string, unknown>)
+      : null;
+
+  const roleValue = readOptionalString(messageRecord?.role ?? parsedRecord.role);
+  const role = roleValue === 'user' ? 'user' : 'assistant';
+
+  const textFromMessage = collectTextFromMessageContent(messageRecord?.content ?? parsedRecord.content);
+  const textFromInline = readOptionalString(parsedRecord.text);
+  const text = normalizeWhitespace(textFromMessage ?? textFromInline ?? lineText);
+
+  const timestamp = readOptionalTimestamp(
+    parsedRecord.timestamp ?? parsedRecord.created_at ?? parsedRecord.createdAt ?? parsedRecord.time,
+  );
+  const messageUuid = readOptionalString(parsedRecord.uuid ?? messageRecord?.uuid);
+
+  return {
+    role,
+    text,
+    timestamp,
+    messageUuid,
+  };
+};
+
+const buildSnippetWithHighlights = (
+  text: string,
+  queryWords: string[],
+): {
+  snippet: string;
+  highlights: ConversationSearchHighlight[];
+} => {
+  const normalizedText = normalizeWhitespace(text);
+  if (!normalizedText) {
+    return { snippet: '', highlights: [] };
+  }
+
+  const lowerText = normalizedText.toLowerCase();
+  let firstMatchIndex = -1;
+
+  for (const word of queryWords) {
+    const index = lowerText.indexOf(word);
+    if (index >= 0 && (firstMatchIndex === -1 || index < firstMatchIndex)) {
+      firstMatchIndex = index;
+    }
+  }
+
+  const targetIndex = firstMatchIndex >= 0 ? firstMatchIndex : 0;
+  const snippetLength = 180;
+  const halfLength = Math.floor(snippetLength / 2);
+  const start = Math.max(0, targetIndex - halfLength);
+  const end = Math.min(normalizedText.length, start + snippetLength);
+  const prefix = start > 0 ? '...' : '';
+  const suffix = end < normalizedText.length ? '...' : '';
+  const snippetBody = normalizedText.slice(start, end);
+  const snippet = `${prefix}${snippetBody}${suffix}`;
+  const snippetLower = snippet.toLowerCase();
+  const highlights: ConversationSearchHighlight[] = [];
+
+  for (const word of queryWords) {
+    let fromIndex = 0;
+    while (fromIndex < snippetLower.length) {
+      const index = snippetLower.indexOf(word, fromIndex);
+      if (index < 0) {
+        break;
+      }
+
+      highlights.push({
+        start: index,
+        end: index + word.length,
+      });
+      fromIndex = index + word.length;
+    }
+  }
+
+  highlights.sort((left, right) => left.start - right.start);
+  const mergedHighlights: ConversationSearchHighlight[] = [];
+  for (const highlight of highlights) {
+    const previous = mergedHighlights[mergedHighlights.length - 1];
+    if (previous && highlight.start <= previous.end) {
+      previous.end = Math.max(previous.end, highlight.end);
+    } else {
+      mergedHighlights.push({ ...highlight });
+    }
+  }
+
+  return {
+    snippet,
+    highlights: mergedHighlights,
+  };
+};
+
+const buildProjectResults = (
+  searchResults: SearchResult[],
+  queryWords: string[],
+): { projectResults: ConversationSearchProjectResult[]; totalMatches: number } => {
+  const workspaceRows = workspaceOriginalPathsDb.getWorkspacePaths();
+  const customWorkspaceNameByPath = new Map(
+    workspaceRows.map((workspaceRow) => [workspaceRow.workspace_path, workspaceRow.custom_workspace_name]),
+  );
+
+  const sessions = sessionsDb.getAllSessions();
+  const sessionByProviderAndId = new Map(
+    sessions.map((session) => [`${session.provider}:${session.session_id}`, session]),
+  );
+  const sessionById = new Map(sessions.map((session) => [session.session_id, session]));
+
+  const projects = new Map<
+    string,
+    {
+      projectResult: ConversationSearchProjectResult;
+      sessions: Map<string, ConversationSearchSession>;
+    }
+  >();
+  let totalMatches = 0;
+
+  for (const result of searchResults) {
+    const sessionRow =
+      sessionByProviderAndId.get(`${result.provider}:${result.sessionId}`) ??
+      sessionById.get(result.sessionId);
+    const workspacePath = sessionRow?.workspace_path ?? path.dirname(result.filePath);
+    const projectName = encodeLegacyProjectName(workspacePath);
+    const projectDisplayName = getWorkspaceDisplayName(
+      workspacePath,
+      customWorkspaceNameByPath.get(workspacePath) ?? null,
+    );
+
+    let projectEntry = projects.get(projectName);
+    if (!projectEntry) {
+      projectEntry = {
+        projectResult: {
+          projectName,
+          projectDisplayName,
+          sessions: [],
+        },
+        sessions: new Map<string, ConversationSearchSession>(),
+      };
+      projects.set(projectName, projectEntry);
+    }
+
+    const sessionMapKey = `${result.provider}:${result.sessionId}`;
+    let sessionEntry = projectEntry.sessions.get(sessionMapKey);
+    if (!sessionEntry) {
+      sessionEntry = {
+        sessionId: result.sessionId,
+        provider: result.provider,
+        sessionSummary: sessionRow?.custom_name?.trim() || 'Untitled Session',
+        matches: [],
+      };
+      projectEntry.sessions.set(sessionMapKey, sessionEntry);
+      projectEntry.projectResult.sessions.push(sessionEntry);
+    }
+
+    // Keep payload compact and consistent with previous search UX.
+    if (sessionEntry.matches.length >= 2) {
+      continue;
+    }
+
+    const parsedLine = parseLineMatchPayload(result.lineText);
+    const { snippet, highlights } = buildSnippetWithHighlights(parsedLine.text, queryWords);
+    if (!snippet) {
+      continue;
+    }
+
+    sessionEntry.matches.push({
+      role: parsedLine.role,
+      snippet,
+      highlights,
+      timestamp: parsedLine.timestamp,
+      provider: result.provider,
+      messageUuid: parsedLine.messageUuid,
+    });
+    totalMatches += 1;
+  }
+
+  return {
+    projectResults: [...projects.values()]
+      .map((entry) => entry.projectResult)
+      .filter((projectResult) => projectResult.sessions.length > 0),
+    totalMatches,
+  };
+};
+
+router.get('/search', async (req: Request, res: Response) => {
+  const queryParam = typeof req.query.q === 'string'
+    ? req.query.q
+    : (typeof req.query.query === 'string' ? req.query.query : '');
+  const query = queryParam.trim();
+  const provider = typeof req.query.provider === 'string' ? req.query.provider.trim().toLowerCase() : undefined;
+  const caseSensitive = req.query.caseSensitive === 'true';
+  const parsedLimit = Number.parseInt(String(req.query.limit), 10);
+  const limit = Number.isNaN(parsedLimit) ? 50 : Math.max(1, Math.min(parsedLimit, 100));
+
+  if (query.length < 2) {
+    res.status(400).json(createApiErrorResponse('SEARCH_QUERY_TOO_SHORT', 'Query must be at least 2 characters.'));
+    return;
+  }
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+
+  let closed = false;
+  const abortController = new AbortController();
+  req.on('close', () => {
+    closed = true;
+    abortController.abort();
+  });
+
+  try {
+    const searchResults = await conversationSearchService.search({
+      query,
+      provider,
+      caseSensitive,
+      limit,
+      signal: abortController.signal,
+    });
+    if (closed) {
+      return;
+    }
+
+    const queryWords = normalizeQueryWords(query);
+    const { projectResults, totalMatches } = buildProjectResults(searchResults, queryWords);
+    const totalProjects = projectResults.length;
+    let scannedProjects = 0;
+
+    if (totalProjects === 0) {
+      res.write(
+        `event: progress\ndata: ${JSON.stringify({
+          totalMatches: 0,
+          scannedProjects: 0,
+          totalProjects: 0,
+        })}\n\n`,
+      );
+    }
+
+    for (const projectResult of projectResults) {
+      if (closed) {
+        break;
+      }
+
+      scannedProjects += 1;
+      res.write(
+        `event: result\ndata: ${JSON.stringify({
+          projectResult,
+          totalMatches,
+          scannedProjects,
+          totalProjects,
+        })}\n\n`,
+      );
+    }
+
+    if (!closed) {
+      res.write('event: done\ndata: {}\n\n');
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Conversation search failed.';
+    logger.error(message, {
+      module: 'conversations.routes',
+    });
+    if (!closed) {
+      res.write(`event: error\ndata: ${JSON.stringify({ error: 'Search failed' })}\n\n`);
+    }
+  } finally {
+    if (!closed) {
+      res.end();
+    }
+  }
+});
+
+/**
+ * Normalizes route-level failures to a consistent JSON API shape.
+ */
+router.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
+  if (res.headersSent) {
+    return;
+  }
+
+  if (error instanceof AppError) {
+    res
+      .status(error.statusCode)
+      .json(createApiErrorResponse(error.code, error.message, undefined, error.details));
+    return;
+  }
+
+  const message =
+    error instanceof Error ? error.message : 'Unexpected conversations route failure.';
+  logger.error(message, {
+    module: 'conversations.routes',
+  });
+
+  res.status(500).json(createApiErrorResponse('INTERNAL_ERROR', message));
+});
+
+export default router;

server/src/modules/credentials/credentials.routes.js

@@ -0,0 +1,98 @@
+import express from 'express';
+import { credentialsDb } from '@/shared/database/repositories/credentials.js';
+
+const router = express.Router();
+
+// ===============================
+// Generic Credentials Management
+// ===============================
+
+// Get all credentials for the authenticated user (optionally filtered by type)
+router.get('/', async (req, res) => {
+  try {
+    const { type } = req.query;
+    const credentials = credentialsDb.getCredentials(req.user.id, type || null);
+    // Don't send the actual credential values for security
+    res.json({ credentials });
+  } catch (error) {
+    console.error('Error fetching credentials:', error);
+    res.status(500).json({ error: 'Failed to fetch credentials' });
+  }
+});
+
+// Create a new credential
+router.post('/', async (req, res) => {
+  try {
+    const { credentialName, credentialType, credentialValue, description } = req.body;
+
+    if (!credentialName || !credentialName.trim()) {
+      return res.status(400).json({ error: 'Credential name is required' });
+    }
+
+    if (!credentialType || !credentialType.trim()) {
+      return res.status(400).json({ error: 'Credential type is required' });
+    }
+
+    if (!credentialValue || !credentialValue.trim()) {
+      return res.status(400).json({ error: 'Credential value is required' });
+    }
+
+    const result = credentialsDb.createCredential(
+      req.user.id,
+      credentialName.trim(),
+      credentialType.trim(),
+      credentialValue.trim(),
+      description?.trim() || null
+    );
+
+    res.json({
+      success: true,
+      credential: result
+    });
+  } catch (error) {
+    console.error('Error creating credential:', error);
+    res.status(500).json({ error: 'Failed to create credential' });
+  }
+});
+
+// Delete a credential
+router.delete('/:credentialId', async (req, res) => {
+  try {
+    const { credentialId } = req.params;
+    const success = credentialsDb.deleteCredential(req.user.id, parseInt(credentialId));
+
+    if (success) {
+      res.json({ success: true });
+    } else {
+      res.status(404).json({ error: 'Credential not found' });
+    }
+  } catch (error) {
+    console.error('Error deleting credential:', error);
+    res.status(500).json({ error: 'Failed to delete credential' });
+  }
+});
+
+// Toggle credential active status
+router.patch('/:credentialId/toggle', async (req, res) => {
+  try {
+    const { credentialId } = req.params;
+    const { isActive } = req.body;
+
+    if (typeof isActive !== 'boolean') {
+      return res.status(400).json({ error: 'isActive must be a boolean' });
+    }
+
+    const success = credentialsDb.toggleCredential(req.user.id, parseInt(credentialId), isActive);
+
+    if (success) {
+      res.json({ success: true });
+    } else {
+      res.status(404).json({ error: 'Credential not found' });
+    }
+  } catch (error) {
+    console.error('Error toggling credential:', error);
+    res.status(500).json({ error: 'Failed to toggle credential' });
+  }
+});
+
+export default router;

server/src/modules/cursor/cursor.routes.js

@@ -0,0 +1,798 @@
+import express from 'express';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import spawn from 'cross-spawn';
+import sqlite3 from 'sqlite3';
+import { open } from 'sqlite';
+import crypto from 'crypto';
+import { CURSOR_MODELS } from '../../../../shared/modelConstants.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+
+const router = express.Router();
+
+// GET /api/cursor/config - Read Cursor CLI configuration
+router.get('/config', async (req, res) => {
+  try {
+    const configPath = path.join(os.homedir(), '.cursor', 'cli-config.json');
+    
+    try {
+      const configContent = await fs.readFile(configPath, 'utf8');
+      const config = JSON.parse(configContent);
+      
+      res.json({
+        success: true,
+        config: config,
+        path: configPath
+      });
+    } catch (error) {
+      // Config doesn't exist or is invalid
+      console.log('Cursor config not found or invalid:', error.message);
+      
+      // Return default config
+      res.json({
+        success: true,
+        config: {
+          version: 1,
+          model: {
+            modelId: CURSOR_MODELS.DEFAULT,
+            displayName: "GPT-5"
+          },
+          permissions: {
+            allow: [],
+            deny: []
+          }
+        },
+        isDefault: true
+      });
+    }
+  } catch (error) {
+    console.error('Error reading Cursor config:', error);
+    res.status(500).json({ 
+      error: 'Failed to read Cursor configuration', 
+      details: error.message 
+    });
+  }
+});
+
+// POST /api/cursor/config - Update Cursor CLI configuration
+router.post('/config', async (req, res) => {
+  try {
+    const { permissions, model } = req.body;
+    const configPath = path.join(os.homedir(), '.cursor', 'cli-config.json');
+    
+    // Read existing config or create default
+    let config = {
+      version: 1,
+      editor: {
+        vimMode: false
+      },
+      hasChangedDefaultModel: false,
+      privacyCache: {
+        ghostMode: false,
+        privacyMode: 3,
+        updatedAt: Date.now()
+      }
+    };
+    
+    try {
+      const existing = await fs.readFile(configPath, 'utf8');
+      config = JSON.parse(existing);
+    } catch (error) {
+      // Config doesn't exist, use defaults
+      console.log('Creating new Cursor config');
+    }
+    
+    // Update permissions if provided
+    if (permissions) {
+      config.permissions = {
+        allow: permissions.allow || [],
+        deny: permissions.deny || []
+      };
+    }
+    
+    // Update model if provided
+    if (model) {
+      config.model = model;
+      config.hasChangedDefaultModel = true;
+    }
+    
+    // Ensure directory exists
+    const configDir = path.dirname(configPath);
+    await fs.mkdir(configDir, { recursive: true });
+    
+    // Write updated config
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+    
+    res.json({
+      success: true,
+      config: config,
+      message: 'Cursor configuration updated successfully'
+    });
+  } catch (error) {
+    console.error('Error updating Cursor config:', error);
+    res.status(500).json({ 
+      error: 'Failed to update Cursor configuration', 
+      details: error.message 
+    });
+  }
+});
+
+// GET /api/cursor/mcp - Read Cursor MCP servers configuration
+router.get('/mcp', async (req, res) => {
+  try {
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    
+    try {
+      const mcpContent = await fs.readFile(mcpPath, 'utf8');
+      const mcpConfig = JSON.parse(mcpContent);
+      
+      // Convert to UI-friendly format
+      const servers = [];
+      if (mcpConfig.mcpServers && typeof mcpConfig.mcpServers === 'object') {
+        for (const [name, config] of Object.entries(mcpConfig.mcpServers)) {
+          const server = {
+            id: name,
+            name: name,
+            type: 'stdio',
+            scope: 'cursor',
+            config: {},
+            raw: config
+          };
+          
+          // Determine transport type and extract config
+          if (config.command) {
+            server.type = 'stdio';
+            server.config.command = config.command;
+            server.config.args = config.args || [];
+            server.config.env = config.env || {};
+          } else if (config.url) {
+            server.type = config.transport || 'http';
+            server.config.url = config.url;
+            server.config.headers = config.headers || {};
+          }
+          
+          servers.push(server);
+        }
+      }
+      
+      res.json({
+        success: true,
+        servers: servers,
+        path: mcpPath
+      });
+    } catch (error) {
+      // MCP config doesn't exist
+      console.log('Cursor MCP config not found:', error.message);
+      res.json({
+        success: true,
+        servers: [],
+        isDefault: true
+      });
+    }
+  } catch (error) {
+    console.error('Error reading Cursor MCP config:', error);
+    res.status(500).json({ 
+      error: 'Failed to read Cursor MCP configuration', 
+      details: error.message 
+    });
+  }
+});
+
+// POST /api/cursor/mcp/add - Add MCP server to Cursor configuration
+router.post('/mcp/add', async (req, res) => {
+  try {
+    const { name, type = 'stdio', command, args = [], url, headers = {}, env = {} } = req.body;
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    
+    console.log(`➕ Adding MCP server to Cursor config: ${name}`);
+    
+    // Read existing config or create new
+    let mcpConfig = { mcpServers: {} };
+    
+    try {
+      const existing = await fs.readFile(mcpPath, 'utf8');
+      mcpConfig = JSON.parse(existing);
+      if (!mcpConfig.mcpServers) {
+        mcpConfig.mcpServers = {};
+      }
+    } catch (error) {
+      console.log('Creating new Cursor MCP config');
+    }
+    
+    // Build server config based on type
+    let serverConfig = {};
+    
+    if (type === 'stdio') {
+      serverConfig = {
+        command: command,
+        args: args,
+        env: env
+      };
+    } else if (type === 'http' || type === 'sse') {
+      serverConfig = {
+        url: url,
+        transport: type,
+        headers: headers
+      };
+    }
+    
+    // Add server to config
+    mcpConfig.mcpServers[name] = serverConfig;
+    
+    // Ensure directory exists
+    const mcpDir = path.dirname(mcpPath);
+    await fs.mkdir(mcpDir, { recursive: true });
+    
+    // Write updated config
+    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
+    
+    res.json({
+      success: true,
+      message: `MCP server "${name}" added to Cursor configuration`,
+      config: mcpConfig
+    });
+  } catch (error) {
+    console.error('Error adding MCP server to Cursor:', error);
+    res.status(500).json({ 
+      error: 'Failed to add MCP server', 
+      details: error.message 
+    });
+  }
+});
+
+// DELETE /api/cursor/mcp/:name - Remove MCP server from Cursor configuration
+router.delete('/mcp/:name', async (req, res) => {
+  try {
+    const { name } = req.params;
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    
+    console.log(`🗑️ Removing MCP server from Cursor config: ${name}`);
+    
+    // Read existing config
+    let mcpConfig = { mcpServers: {} };
+    
+    try {
+      const existing = await fs.readFile(mcpPath, 'utf8');
+      mcpConfig = JSON.parse(existing);
+    } catch (error) {
+      return res.status(404).json({ 
+        error: 'Cursor MCP configuration not found' 
+      });
+    }
+    
+    // Check if server exists
+    if (!mcpConfig.mcpServers || !mcpConfig.mcpServers[name]) {
+      return res.status(404).json({ 
+        error: `MCP server "${name}" not found in Cursor configuration` 
+      });
+    }
+    
+    // Remove server from config
+    delete mcpConfig.mcpServers[name];
+    
+    // Write updated config
+    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
+    
+    res.json({
+      success: true,
+      message: `MCP server "${name}" removed from Cursor configuration`,
+      config: mcpConfig
+    });
+  } catch (error) {
+    console.error('Error removing MCP server from Cursor:', error);
+    res.status(500).json({ 
+      error: 'Failed to remove MCP server', 
+      details: error.message 
+    });
+  }
+});
+
+// POST /api/cursor/mcp/add-json - Add MCP server using JSON format
+router.post('/mcp/add-json', async (req, res) => {
+  try {
+    const { name, jsonConfig } = req.body;
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    
+    console.log(`➕ Adding MCP server to Cursor config via JSON: ${name}`);
+    
+    // Validate and parse JSON config
+    let parsedConfig;
+    try {
+      parsedConfig = typeof jsonConfig === 'string' ? JSON.parse(jsonConfig) : jsonConfig;
+    } catch (parseError) {
+      return res.status(400).json({ 
+        error: 'Invalid JSON configuration', 
+        details: parseError.message 
+      });
+    }
+    
+    // Read existing config or create new
+    let mcpConfig = { mcpServers: {} };
+    
+    try {
+      const existing = await fs.readFile(mcpPath, 'utf8');
+      mcpConfig = JSON.parse(existing);
+      if (!mcpConfig.mcpServers) {
+        mcpConfig.mcpServers = {};
+      }
+    } catch (error) {
+      console.log('Creating new Cursor MCP config');
+    }
+    
+    // Add server to config
+    mcpConfig.mcpServers[name] = parsedConfig;
+    
+    // Ensure directory exists
+    const mcpDir = path.dirname(mcpPath);
+    await fs.mkdir(mcpDir, { recursive: true });
+    
+    // Write updated config
+    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
+    
+    res.json({
+      success: true,
+      message: `MCP server "${name}" added to Cursor configuration via JSON`,
+      config: mcpConfig
+    });
+  } catch (error) {
+    console.error('Error adding MCP server to Cursor via JSON:', error);
+    res.status(500).json({ 
+      error: 'Failed to add MCP server', 
+      details: error.message 
+    });
+  }
+});
+
+// GET /api/cursor/sessions - Get Cursor sessions from SQLite database
+router.get('/sessions', async (req, res) => {
+  try {
+    const { projectPath } = req.query;
+    
+    // Calculate cwdID hash for the project path (Cursor uses MD5 hash)
+    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
+    const cursorChatsPath = path.join(os.homedir(), '.cursor', 'chats', cwdId);
+    
+    
+    // Check if the directory exists
+    try {
+      await fs.access(cursorChatsPath);
+    } catch (error) {
+      // No sessions for this project
+      return res.json({ 
+        success: true, 
+        sessions: [],
+        cwdId: cwdId,
+        path: cursorChatsPath
+      });
+    }
+    
+    // List all session directories
+    const sessionDirs = await fs.readdir(cursorChatsPath);
+    const sessions = [];
+    
+    for (const sessionId of sessionDirs) {
+      const sessionPath = path.join(cursorChatsPath, sessionId);
+      const storeDbPath = path.join(sessionPath, 'store.db');
+      let dbStatMtimeMs = null;
+      
+      try {
+        // Check if store.db exists
+        await fs.access(storeDbPath);
+        
+        // Capture store.db mtime as a reliable fallback timestamp (last activity)
+        try {
+          const stat = await fs.stat(storeDbPath);
+          dbStatMtimeMs = stat.mtimeMs;
+        } catch (_) {}
+
+        // Open SQLite database
+        const db = await open({
+          filename: storeDbPath,
+          driver: sqlite3.Database,
+          mode: sqlite3.OPEN_READONLY
+        });
+        
+        // Get metadata from meta table
+        const metaRows = await db.all(`
+          SELECT key, value FROM meta
+        `);
+        
+        let sessionData = {
+          id: sessionId,
+          name: 'Untitled Session',
+          createdAt: null,
+          mode: null,
+          projectPath: projectPath,
+          lastMessage: null,
+          messageCount: 0
+        };
+        
+        // Parse meta table entries
+        for (const row of metaRows) {
+          if (row.value) {
+            try {
+              // Try to decode as hex-encoded JSON
+              const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
+              if (hexMatch) {
+                const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
+                const data = JSON.parse(jsonStr);
+                
+                if (row.key === 'agent') {
+                  sessionData.name = data.name || sessionData.name;
+                  // Normalize createdAt to ISO string in milliseconds
+                  let createdAt = data.createdAt;
+                  if (typeof createdAt === 'number') {
+                    if (createdAt < 1e12) {
+                      createdAt = createdAt * 1000; // seconds -> ms
+                    }
+                    sessionData.createdAt = new Date(createdAt).toISOString();
+                  } else if (typeof createdAt === 'string') {
+                    const n = Number(createdAt);
+                    if (!Number.isNaN(n)) {
+                      const ms = n < 1e12 ? n * 1000 : n;
+                      sessionData.createdAt = new Date(ms).toISOString();
+                    } else {
+                      // Assume it's already an ISO/date string
+                      const d = new Date(createdAt);
+                      sessionData.createdAt = isNaN(d.getTime()) ? null : d.toISOString();
+                    }
+                  } else {
+                    sessionData.createdAt = sessionData.createdAt || null;
+                  }
+                  sessionData.mode = data.mode;
+                  sessionData.agentId = data.agentId;
+                  sessionData.latestRootBlobId = data.latestRootBlobId;
+                }
+              } else {
+                // If not hex, use raw value for simple keys
+                if (row.key === 'name') {
+                  sessionData.name = row.value.toString();
+                }
+              }
+            } catch (e) {
+              console.log(`Could not parse meta value for key ${row.key}:`, e.message);
+            }
+          }
+        }
+        
+        // Get message count from JSON blobs only (actual messages, not DAG structure)
+        try {
+          const blobCount = await db.get(`
+            SELECT COUNT(*) as count 
+            FROM blobs 
+            WHERE substr(data, 1, 1) = X'7B'
+          `);
+          sessionData.messageCount = blobCount.count;
+          
+          // Get the most recent JSON blob for preview (actual message, not DAG structure)
+          const lastBlob = await db.get(`
+            SELECT data FROM blobs 
+            WHERE substr(data, 1, 1) = X'7B'
+            ORDER BY rowid DESC 
+            LIMIT 1
+          `);
+          
+          if (lastBlob && lastBlob.data) {
+            try {
+              // Try to extract readable preview from blob (may contain binary with embedded JSON)
+              const raw = lastBlob.data.toString('utf8');
+              let preview = '';
+              // Attempt direct JSON parse
+              try {
+                const parsed = JSON.parse(raw);
+                if (parsed?.content) {
+                  if (Array.isArray(parsed.content)) {
+                    const firstText = parsed.content.find(p => p?.type === 'text' && p.text)?.text || '';
+                    preview = firstText;
+                  } else if (typeof parsed.content === 'string') {
+                    preview = parsed.content;
+                  }
+                }
+              } catch (_) {}
+              if (!preview) {
+                // Strip non-printable and try to find JSON chunk
+                const cleaned = raw.replace(/[^\x09\x0A\x0D\x20-\x7E]/g, '');
+                const s = cleaned;
+                const start = s.indexOf('{');
+                const end = s.lastIndexOf('}');
+                if (start !== -1 && end > start) {
+                  const jsonStr = s.slice(start, end + 1);
+                  try {
+                    const parsed = JSON.parse(jsonStr);
+                    if (parsed?.content) {
+                      if (Array.isArray(parsed.content)) {
+                        const firstText = parsed.content.find(p => p?.type === 'text' && p.text)?.text || '';
+                        preview = firstText;
+                      } else if (typeof parsed.content === 'string') {
+                        preview = parsed.content;
+                      }
+                    }
+                  } catch (_) {
+                    preview = s;
+                  }
+                } else {
+                  preview = s;
+                }
+              }
+              if (preview && preview.length > 0) {
+                sessionData.lastMessage = preview.substring(0, 100) + (preview.length > 100 ? '...' : '');
+              }
+            } catch (e) {
+              console.log('Could not parse blob data:', e.message);
+            }
+          }
+        } catch (e) {
+          console.log('Could not read blobs:', e.message);
+        }
+        
+        await db.close();
+
+        // Finalize createdAt: use parsed meta value when valid, else fall back to store.db mtime
+        if (!sessionData.createdAt) {
+          if (dbStatMtimeMs && Number.isFinite(dbStatMtimeMs)) {
+            sessionData.createdAt = new Date(dbStatMtimeMs).toISOString();
+          }
+        }
+        
+        sessions.push(sessionData);
+        
+      } catch (error) {
+        console.log(`Could not read session ${sessionId}:`, error.message);
+      }
+    }
+    
+    // Fallback: ensure createdAt is a valid ISO string (use session directory mtime as last resort)
+    for (const s of sessions) {
+      if (!s.createdAt) {
+        try {
+          const sessionDir = path.join(cursorChatsPath, s.id);
+          const st = await fs.stat(sessionDir);
+          s.createdAt = new Date(st.mtimeMs).toISOString();
+        } catch {
+          s.createdAt = new Date().toISOString();
+        }
+      }
+    }
+    // Sort sessions by creation date (newest first)
+    sessions.sort((a, b) => {
+      if (!a.createdAt) return 1;
+      if (!b.createdAt) return -1;
+      return new Date(b.createdAt) - new Date(a.createdAt);
+    });
+    
+    sessionsDb.applyCustomSessionNames(sessions, 'cursor');
+
+    res.json({
+      success: true,
+      sessions: sessions,
+      cwdId: cwdId,
+      path: cursorChatsPath
+    });
+    
+  } catch (error) {
+    console.error('Error reading Cursor sessions:', error);
+    res.status(500).json({ 
+      error: 'Failed to read Cursor sessions', 
+      details: error.message 
+    });
+  }
+});
+
+// GET /api/cursor/sessions/:sessionId - Get specific Cursor session from SQLite
+router.get('/sessions/:sessionId', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const { projectPath } = req.query;
+    
+    // Calculate cwdID hash for the project path
+    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
+    const storeDbPath = path.join(os.homedir(), '.cursor', 'chats', cwdId, sessionId, 'store.db');
+    
+    
+    // Open SQLite database
+    const db = await open({
+      filename: storeDbPath,
+      driver: sqlite3.Database,
+      mode: sqlite3.OPEN_READONLY
+    });
+    
+    // Get all blobs to build the DAG structure
+    const allBlobs = await db.all(`
+      SELECT rowid, id, data FROM blobs
+    `);
+    
+    // Build the DAG structure from parent-child relationships
+    const blobMap = new Map(); // id -> blob data
+    const parentRefs = new Map(); // blob id -> [parent blob ids]
+    const childRefs = new Map(); // blob id -> [child blob ids]
+    const jsonBlobs = []; // Clean JSON messages
+    
+    for (const blob of allBlobs) {
+      blobMap.set(blob.id, blob);
+      
+      // Check if this is a JSON blob (actual message) or protobuf (DAG structure)
+      if (blob.data && blob.data[0] === 0x7B) { // Starts with '{' - JSON blob
+        try {
+          const parsed = JSON.parse(blob.data.toString('utf8'));
+          jsonBlobs.push({ ...blob, parsed });
+        } catch (e) {
+          console.log('Failed to parse JSON blob:', blob.rowid);
+        }
+      } else if (blob.data) { // Protobuf blob - extract parent references
+        const parents = [];
+        let i = 0;
+        
+        // Scan for parent references (0x0A 0x20 followed by 32-byte hash)
+        while (i < blob.data.length - 33) {
+          if (blob.data[i] === 0x0A && blob.data[i+1] === 0x20) {
+            const parentHash = blob.data.slice(i+2, i+34).toString('hex');
+            if (blobMap.has(parentHash)) {
+              parents.push(parentHash);
+            }
+            i += 34;
+          } else {
+            i++;
+          }
+        }
+        
+        if (parents.length > 0) {
+          parentRefs.set(blob.id, parents);
+          // Update child references
+          for (const parentId of parents) {
+            if (!childRefs.has(parentId)) {
+              childRefs.set(parentId, []);
+            }
+            childRefs.get(parentId).push(blob.id);
+          }
+        }
+      }
+    }
+    
+    // Perform topological sort to get chronological order
+    const visited = new Set();
+    const sorted = [];
+    
+    // DFS-based topological sort
+    function visit(nodeId) {
+      if (visited.has(nodeId)) return;
+      visited.add(nodeId);
+      
+      // Visit all parents first (dependencies)
+      const parents = parentRefs.get(nodeId) || [];
+      for (const parentId of parents) {
+        visit(parentId);
+      }
+      
+      // Add this node after all its parents
+      const blob = blobMap.get(nodeId);
+      if (blob) {
+        sorted.push(blob);
+      }
+    }
+    
+    // Start with nodes that have no parents (roots)
+    for (const blob of allBlobs) {
+      if (!parentRefs.has(blob.id)) {
+        visit(blob.id);
+      }
+    }
+    
+    // Visit any remaining nodes (disconnected components)
+    for (const blob of allBlobs) {
+      visit(blob.id);
+    }
+    
+    // Now extract JSON messages in the order they appear in the sorted DAG
+    const messageOrder = new Map(); // JSON blob id -> order index
+    let orderIndex = 0;
+    
+    for (const blob of sorted) {
+      // Check if this blob references any JSON messages
+      if (blob.data && blob.data[0] !== 0x7B) { // Protobuf blob
+        // Look for JSON blob references
+        for (const jsonBlob of jsonBlobs) {
+          try {
+            const jsonIdBytes = Buffer.from(jsonBlob.id, 'hex');
+            if (blob.data.includes(jsonIdBytes)) {
+              if (!messageOrder.has(jsonBlob.id)) {
+                messageOrder.set(jsonBlob.id, orderIndex++);
+              }
+            }
+          } catch (e) {
+            // Skip if can't convert ID
+          }
+        }
+      }
+    }
+    
+    // Sort JSON blobs by their appearance order in the DAG
+    const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
+      const orderA = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
+      const orderB = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
+      if (orderA !== orderB) return orderA - orderB;
+      // Fallback to rowid if not in order map
+      return a.rowid - b.rowid;
+    });
+    
+    // Use sorted JSON blobs
+    const blobs = sortedJsonBlobs.map((blob, idx) => ({
+      ...blob,
+      sequence_num: idx + 1,
+      original_rowid: blob.rowid
+    }));
+    
+    // Get metadata from meta table
+    const metaRows = await db.all(`
+      SELECT key, value FROM meta
+    `);
+    
+    // Parse metadata
+    let metadata = {};
+    for (const row of metaRows) {
+      if (row.value) {
+        try {
+          // Try to decode as hex-encoded JSON
+          const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
+          if (hexMatch) {
+            const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
+            metadata[row.key] = JSON.parse(jsonStr);
+          } else {
+            metadata[row.key] = row.value.toString();
+          }
+        } catch (e) {
+          metadata[row.key] = row.value.toString();
+        }
+      }
+    }
+    
+    // Extract messages from sorted JSON blobs
+    const messages = [];
+    for (const blob of blobs) {
+      try {
+        // We already parsed JSON blobs earlier
+        const parsed = blob.parsed;
+        
+        if (parsed) {
+          // Filter out ONLY system messages at the server level
+          // Check both direct role and nested message.role
+          const role = parsed?.role || parsed?.message?.role;
+          if (role === 'system') {
+            continue; // Skip only system messages
+          }
+          messages.push({ 
+            id: blob.id, 
+            sequence: blob.sequence_num,
+            rowid: blob.original_rowid, 
+            content: parsed 
+          });
+        }
+      } catch (e) {
+        // Skip blobs that cause errors
+        console.log(`Skipping blob ${blob.id}: ${e.message}`);
+      }
+    }
+    
+    await db.close();
+    
+    res.json({ 
+      success: true, 
+      session: {
+        id: sessionId,
+        projectPath: projectPath,
+        messages: messages,
+        metadata: metadata,
+        cwdId: cwdId
+      }
+    });
+    
+  } catch (error) {
+    console.error('Error reading Cursor session:', error);
+    res.status(500).json({ 
+      error: 'Failed to read Cursor session', 
+      details: error.message 
+    });
+  }
+});
+
+export default router;

server/src/modules/files/.gitkeep

@@ -0,0 +1 @@
+

server/src/modules/files/files.routes.js

@@ -0,0 +1,944 @@
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import mime from 'mime-types';
+import fetch from 'node-fetch';
+import { promises as fsPromises } from 'fs';
+import { authenticateToken } from '../auth/auth.middleware.js';
+
+const router = express.Router();
+
+const extractProjectDirectory = (projectName) => {
+    return new Promise((resolve, reject) => {
+        //  just return the original project name for now, since we are no longer encoding the path in the project name
+        resolve(projectName);
+    });
+}
+
+/**
+ * Validate that a path is within the project root
+ * @param {string} projectRoot - The project root path
+ * @param {string} targetPath - The path to validate
+ * @returns {{ valid: boolean, resolved?: string, error?: string }}
+ */
+function validatePathInProject(projectRoot, targetPath) {
+    const resolved = path.isAbsolute(targetPath)
+        ? path.resolve(targetPath)
+        : path.resolve(projectRoot, targetPath);
+    const normalizedRoot = path.resolve(projectRoot) + path.sep;
+    if (!resolved.startsWith(normalizedRoot)) {
+        return { valid: false, error: 'Path must be under project root' };
+    }
+    return { valid: true, resolved };
+}
+
+/**
+ * Validate filename - check for invalid characters
+ * @param {string} name - The filename to validate
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateFilename(name) {
+    if (!name || !name.trim()) {
+        return { valid: false, error: 'Filename cannot be empty' };
+    }
+    // Check for invalid characters (Windows + Unix)
+    const invalidChars = /[<>:"/\\|?*\x00-\x1f]/;
+    if (invalidChars.test(name)) {
+        return { valid: false, error: 'Filename contains invalid characters' };
+    }
+    // Check for reserved names (Windows)
+    const reserved = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+    if (reserved.test(name)) {
+        return { valid: false, error: 'Filename is a reserved name' };
+    }
+    // Check for dots only
+    if (/^\.+$/.test(name)) {
+        return { valid: false, error: 'Filename cannot be only dots' };
+    }
+    return { valid: true };
+}
+
+// Helper function to convert permissions to rwx format
+function permToRwx(perm) {
+    const r = perm & 4 ? 'r' : '-';
+    const w = perm & 2 ? 'w' : '-';
+    const x = perm & 1 ? 'x' : '-';
+    return r + w + x;
+}
+
+async function getFileTree(dirPath, maxDepth = 3, currentDepth = 0, showHidden = true) {
+    // Using fsPromises from import
+    const items = [];
+
+    try {
+        const entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
+
+        for (const entry of entries) {
+            // Debug: log all entries including hidden files
+
+
+            // Skip heavy build directories and VCS directories
+            if (entry.name === 'node_modules' ||
+                entry.name === 'dist' ||
+                entry.name === 'build' ||
+                entry.name === '.git' ||
+                entry.name === '.svn' ||
+                entry.name === '.hg') continue;
+
+            const itemPath = path.join(dirPath, entry.name);
+            const item = {
+                name: entry.name,
+                path: itemPath,
+                type: entry.isDirectory() ? 'directory' : 'file'
+            };
+
+            // Get file stats for additional metadata
+            try {
+                const stats = await fsPromises.stat(itemPath);
+                item.size = stats.size;
+                item.modified = stats.mtime.toISOString();
+
+                // Convert permissions to rwx format
+                const mode = stats.mode;
+                const ownerPerm = (mode >> 6) & 7;
+                const groupPerm = (mode >> 3) & 7;
+                const otherPerm = mode & 7;
+                item.permissions = ((mode >> 6) & 7).toString() + ((mode >> 3) & 7).toString() + (mode & 7).toString();
+                item.permissionsRwx = permToRwx(ownerPerm) + permToRwx(groupPerm) + permToRwx(otherPerm);
+            } catch (statError) {
+                // If stat fails, provide default values
+                item.size = 0;
+                item.modified = null;
+                item.permissions = '000';
+                item.permissionsRwx = '---------';
+            }
+
+            if (entry.isDirectory() && currentDepth < maxDepth) {
+                // Recursively get subdirectories but limit depth
+                try {
+                    // Check if we can access the directory before trying to read it
+                    await fsPromises.access(item.path, fs.constants.R_OK);
+                    item.children = await getFileTree(item.path, maxDepth, currentDepth + 1, showHidden);
+                } catch (e) {
+                    // Silently skip directories we can't access (permission denied, etc.)
+                    item.children = [];
+                }
+            }
+
+            items.push(item);
+        }
+    } catch (error) {
+        // Only log non-permission errors to avoid spam
+        if (error.code !== 'EACCES' && error.code !== 'EPERM') {
+            console.error('Error reading directory:', error);
+        }
+    }
+
+    return items.sort((a, b) => {
+        if (a.type !== b.type) {
+            return a.type === 'directory' ? -1 : 1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+}
+
+// Read file content endpoint
+router.get('/api/projects/:projectName/file', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { filePath } = req.query;
+
+
+        // Security: ensure the requested path is inside the project root
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        console.log("PROJECT NAME IS: ", projectName);
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        console.log("PROJECT ROOT IS: ", projectRoot);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Handle both absolute and relative paths
+        const resolved = path.isAbsolute(filePath)
+            ? path.resolve(filePath)
+            : path.resolve(projectRoot, filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot)) {
+            return res.status(403).json({ error: 'Path must be under project root' });
+        }
+
+        const content = await fsPromises.readFile(resolved, 'utf8');
+        res.json({ content, path: resolved });
+    } catch (error) {
+        console.error('Error reading file:', error);
+        if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File not found' });
+        } else if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+// Serve binary file content endpoint (for images, etc.)
+router.get('/api/projects/:projectName/files/content', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { path: filePath } = req.query;
+
+
+        // Security: ensure the requested path is inside the project root
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        const resolved = path.resolve(filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot)) {
+            return res.status(403).json({ error: 'Path must be under project root' });
+        }
+
+        // Check if file exists
+        try {
+            await fsPromises.access(resolved);
+        } catch (error) {
+            return res.status(404).json({ error: 'File not found' });
+        }
+
+        // Get file extension and set appropriate content type
+        const mimeType = mime.lookup(resolved) || 'application/octet-stream';
+        res.setHeader('Content-Type', mimeType);
+
+        // Stream the file
+        const fileStream = fs.createReadStream(resolved);
+        fileStream.pipe(res);
+
+        fileStream.on('error', (error) => {
+            console.error('Error streaming file:', error);
+            if (!res.headersSent) {
+                res.status(500).json({ error: 'Error reading file' });
+            }
+        });
+
+    } catch (error) {
+        console.error('Error serving binary file:', error);
+        if (!res.headersSent) {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+// Save file content endpoint
+router.put('/api/projects/:projectName/file', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { filePath, content } = req.body;
+
+
+        // Security: ensure the requested path is inside the project root
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        if (content === undefined) {
+            return res.status(400).json({ error: 'Content is required' });
+        }
+
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Handle both absolute and relative paths
+        const resolved = path.isAbsolute(filePath)
+            ? path.resolve(filePath)
+            : path.resolve(projectRoot, filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot)) {
+            return res.status(403).json({ error: 'Path must be under project root' });
+        }
+
+        // Write the new content
+        await fsPromises.writeFile(resolved, content, 'utf8');
+
+        res.json({
+            success: true,
+            path: resolved,
+            message: 'File saved successfully'
+        });
+    } catch (error) {
+        console.error('Error saving file:', error);
+        if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File or directory not found' });
+        } else if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+router.get('/api/projects/:projectName/files', authenticateToken, async (req, res) => {
+    try {
+
+        // Using fsPromises from import
+
+        // Use extractProjectDirectory to get the actual project path
+        let actualPath;
+        try {
+            console.log("Extracting project directory for:", req.params.projectName);
+            actualPath = await extractProjectDirectory(req.params.projectName);
+            console.log("Extracted project directory:", actualPath);
+        } catch (error) {
+            console.error('Error extracting project directory:', error);
+            // Fallback to simple dash replacement
+            actualPath = req.params.projectName.replace(/-/g, '/');
+        }
+
+        // Check if path exists
+        try {
+            await fsPromises.access(actualPath);
+        } catch (e) {
+            return res.status(404).json({ error: `Project path not found: ${actualPath}` });
+        }
+
+        const files = await getFileTree(actualPath, 10, 0, true);
+        res.json(files);
+    } catch (error) {
+        console.error('[ERROR] File tree error:', error.message);
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// ============================================================================
+// FILE OPERATIONS API ENDPOINTS
+// ============================================================================
+
+// POST /api/projects/:projectName/files/create - Create new file or directory
+router.post('/api/projects/:projectName/files/create', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { path: parentPath, type, name } = req.body;
+
+        // Validate input
+        if (!name || !type) {
+            return res.status(400).json({ error: 'Name and type are required' });
+        }
+
+        if (!['file', 'directory'].includes(type)) {
+            return res.status(400).json({ error: 'Type must be "file" or "directory"' });
+        }
+
+        const nameValidation = validateFilename(name);
+        if (!nameValidation.valid) {
+            return res.status(400).json({ error: nameValidation.error });
+        }
+
+        // Get project root
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Build and validate target path
+        const targetDir = parentPath || '';
+        const targetPath = targetDir ? path.join(targetDir, name) : name;
+        const validation = validatePathInProject(projectRoot, targetPath);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+
+        const resolvedPath = validation.resolved;
+
+        // Check if already exists
+        try {
+            await fsPromises.access(resolvedPath);
+            return res.status(409).json({ error: `${type === 'file' ? 'File' : 'Directory'} already exists` });
+        } catch {
+            // Doesn't exist, which is what we want
+        }
+
+        // Create file or directory
+        if (type === 'directory') {
+            await fsPromises.mkdir(resolvedPath, { recursive: false });
+        } else {
+            // Ensure parent directory exists
+            const parentDir = path.dirname(resolvedPath);
+            try {
+                await fsPromises.access(parentDir);
+            } catch {
+                await fsPromises.mkdir(parentDir, { recursive: true });
+            }
+            await fsPromises.writeFile(resolvedPath, '', 'utf8');
+        }
+
+        res.json({
+            success: true,
+            path: resolvedPath,
+            name,
+            type,
+            message: `${type === 'file' ? 'File' : 'Directory'} created successfully`
+        });
+    } catch (error) {
+        console.error('Error creating file/directory:', error);
+        if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'Parent directory not found' });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+// PUT /api/projects/:projectName/files/rename - Rename file or directory
+router.put('/api/projects/:projectName/files/rename', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { oldPath, newName } = req.body;
+
+        // Validate input
+        if (!oldPath || !newName) {
+            return res.status(400).json({ error: 'oldPath and newName are required' });
+        }
+
+        const nameValidation = validateFilename(newName);
+        if (!nameValidation.valid) {
+            return res.status(400).json({ error: nameValidation.error });
+        }
+
+        // Get project root
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Validate old path
+        const oldValidation = validatePathInProject(projectRoot, oldPath);
+        if (!oldValidation.valid) {
+            return res.status(403).json({ error: oldValidation.error });
+        }
+
+        const resolvedOldPath = oldValidation.resolved;
+
+        // Check if old path exists
+        try {
+            await fsPromises.access(resolvedOldPath);
+        } catch {
+            return res.status(404).json({ error: 'File or directory not found' });
+        }
+
+        // Build and validate new path
+        const parentDir = path.dirname(resolvedOldPath);
+        const resolvedNewPath = path.join(parentDir, newName);
+        const newValidation = validatePathInProject(projectRoot, resolvedNewPath);
+        if (!newValidation.valid) {
+            return res.status(403).json({ error: newValidation.error });
+        }
+
+        // Check if new path already exists
+        try {
+            await fsPromises.access(resolvedNewPath);
+            return res.status(409).json({ error: 'A file or directory with this name already exists' });
+        } catch {
+            // Doesn't exist, which is what we want
+        }
+
+        // Rename
+        await fsPromises.rename(resolvedOldPath, resolvedNewPath);
+
+        res.json({
+            success: true,
+            oldPath: resolvedOldPath,
+            newPath: resolvedNewPath,
+            newName,
+            message: 'Renamed successfully'
+        });
+    } catch (error) {
+        console.error('Error renaming file/directory:', error);
+        if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File or directory not found' });
+        } else if (error.code === 'EXDEV') {
+            res.status(400).json({ error: 'Cannot move across different filesystems' });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+// DELETE /api/projects/:projectName/files - Delete file or directory
+router.delete('/api/projects/:projectName/files', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { path: targetPath, type } = req.body;
+
+        // Validate input
+        if (!targetPath) {
+            return res.status(400).json({ error: 'Path is required' });
+        }
+
+        // Get project root
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Validate path
+        const validation = validatePathInProject(projectRoot, targetPath);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+
+        const resolvedPath = validation.resolved;
+
+        // Check if path exists and get stats
+        let stats;
+        try {
+            stats = await fsPromises.stat(resolvedPath);
+        } catch {
+            return res.status(404).json({ error: 'File or directory not found' });
+        }
+
+        // Prevent deleting the project root itself
+        if (resolvedPath === path.resolve(projectRoot)) {
+            return res.status(403).json({ error: 'Cannot delete project root directory' });
+        }
+
+        // Delete based on type
+        if (stats.isDirectory()) {
+            await fsPromises.rm(resolvedPath, { recursive: true, force: true });
+        } else {
+            await fsPromises.unlink(resolvedPath);
+        }
+
+        res.json({
+            success: true,
+            path: resolvedPath,
+            type: stats.isDirectory() ? 'directory' : 'file',
+            message: 'Deleted successfully'
+        });
+    } catch (error) {
+        console.error('Error deleting file/directory:', error);
+        if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File or directory not found' });
+        } else if (error.code === 'ENOTEMPTY') {
+            res.status(400).json({ error: 'Directory is not empty' });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    }
+});
+
+// POST /api/projects/:projectName/files/upload - Upload files
+// Dynamic import of multer for file uploads
+const uploadFilesHandler = async (req, res) => {
+    // Dynamic import of multer
+    const multer = (await import('multer')).default;
+
+    const uploadMiddleware = multer({
+        storage: multer.diskStorage({
+            destination: (req, file, cb) => {
+                cb(null, os.tmpdir());
+            },
+            filename: (req, file, cb) => {
+                // Use a unique temp name, but preserve original name in file.originalname
+                // Note: file.originalname may contain path separators for folder uploads
+                const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+                // For temp file, just use a safe unique name without the path
+                cb(null, `upload-${uniqueSuffix}`);
+            }
+        }),
+        limits: {
+            fileSize: 50 * 1024 * 1024, // 50MB limit
+            files: 20 // Max 20 files at once
+        }
+    });
+
+    // Use multer middleware
+    uploadMiddleware.array('files', 20)(req, res, async (err) => {
+        if (err) {
+            console.error('Multer error:', err);
+            if (err.code === 'LIMIT_FILE_SIZE') {
+                return res.status(400).json({ error: 'File too large. Maximum size is 50MB.' });
+            }
+            if (err.code === 'LIMIT_FILE_COUNT') {
+                return res.status(400).json({ error: 'Too many files. Maximum is 20 files.' });
+            }
+            return res.status(500).json({ error: err.message });
+        }
+
+        try {
+            const { projectName } = req.params;
+            const { targetPath, relativePaths } = req.body;
+
+            // Parse relative paths if provided (for folder uploads)
+            let filePaths = [];
+            if (relativePaths) {
+                try {
+                    filePaths = JSON.parse(relativePaths);
+                } catch (e) {
+                    console.log('[DEBUG] Failed to parse relativePaths:', relativePaths);
+                }
+            }
+
+            console.log('[DEBUG] File upload request:', {
+                projectName,
+                targetPath: JSON.stringify(targetPath),
+                targetPathType: typeof targetPath,
+                filesCount: req.files?.length,
+                relativePaths: filePaths
+            });
+
+            if (!req.files || req.files.length === 0) {
+                return res.status(400).json({ error: 'No files provided' });
+            }
+
+            // Get project root
+            const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+            if (!projectRoot) {
+                return res.status(404).json({ error: 'Project not found' });
+            }
+
+            console.log('[DEBUG] Project root:', projectRoot);
+
+            // Validate and resolve target path
+            // If targetPath is empty or '.', use project root directly
+            const targetDir = targetPath || '';
+            let resolvedTargetDir;
+
+            console.log('[DEBUG] Target dir:', JSON.stringify(targetDir));
+
+            if (!targetDir || targetDir === '.' || targetDir === './') {
+                // Empty path means upload to project root
+                resolvedTargetDir = path.resolve(projectRoot);
+                console.log('[DEBUG] Using project root as target:', resolvedTargetDir);
+            } else {
+                const validation = validatePathInProject(projectRoot, targetDir);
+                if (!validation.valid) {
+                    console.log('[DEBUG] Path validation failed:', validation.error);
+                    return res.status(403).json({ error: validation.error });
+                }
+                resolvedTargetDir = validation.resolved;
+                console.log('[DEBUG] Resolved target dir:', resolvedTargetDir);
+            }
+
+            // Ensure target directory exists
+            try {
+                await fsPromises.access(resolvedTargetDir);
+            } catch {
+                await fsPromises.mkdir(resolvedTargetDir, { recursive: true });
+            }
+
+            // Move uploaded files from temp to target directory
+            const uploadedFiles = [];
+            console.log('[DEBUG] Processing files:', req.files.map(f => ({ originalname: f.originalname, path: f.path })));
+            for (let i = 0; i < req.files.length; i++) {
+                const file = req.files[i];
+                // Use relative path if provided (for folder uploads), otherwise use originalname
+                const fileName = (filePaths && filePaths[i]) ? filePaths[i] : file.originalname;
+                console.log('[DEBUG] Processing file:', fileName, '(originalname:', file.originalname + ')');
+                const destPath = path.join(resolvedTargetDir, fileName);
+
+                // Validate destination path
+                const destValidation = validatePathInProject(projectRoot, destPath);
+                if (!destValidation.valid) {
+                    console.log('[DEBUG] Destination validation failed for:', destPath);
+                    // Clean up temp file
+                    await fsPromises.unlink(file.path).catch(() => {});
+                    continue;
+                }
+
+                // Ensure parent directory exists (for nested files from folder upload)
+                const parentDir = path.dirname(destPath);
+                try {
+                    await fsPromises.access(parentDir);
+                } catch {
+                    await fsPromises.mkdir(parentDir, { recursive: true });
+                }
+
+                // Move file (copy + unlink to handle cross-device scenarios)
+                await fsPromises.copyFile(file.path, destPath);
+                await fsPromises.unlink(file.path);
+
+                uploadedFiles.push({
+                    name: fileName,
+                    path: destPath,
+                    size: file.size,
+                    mimeType: file.mimetype
+                });
+            }
+
+            res.json({
+                success: true,
+                files: uploadedFiles,
+                targetPath: resolvedTargetDir,
+                message: `Uploaded ${uploadedFiles.length} file(s) successfully`
+            });
+        } catch (error) {
+            console.error('Error uploading files:', error);
+            // Clean up any remaining temp files
+            if (req.files) {
+                for (const file of req.files) {
+                    await fsPromises.unlink(file.path).catch(() => {});
+                }
+            }
+            if (error.code === 'EACCES') {
+                res.status(403).json({ error: 'Permission denied' });
+            } else {
+                res.status(500).json({ error: error.message });
+            }
+        }
+    });
+};
+
+router.post('/api/projects/:projectName/files/upload', authenticateToken, uploadFilesHandler);
+
+// Audio transcription endpoint
+router.post('/api/transcribe', authenticateToken, async (req, res) => {
+    try {
+        const multer = (await import('multer')).default;
+        const upload = multer({ storage: multer.memoryStorage() });
+
+        // Handle multipart form data
+        upload.single('audio')(req, res, async (err) => {
+            if (err) {
+                return res.status(400).json({ error: 'Failed to process audio file' });
+            }
+
+            if (!req.file) {
+                return res.status(400).json({ error: 'No audio file provided' });
+            }
+
+            const apiKey = process.env.OPENAI_API_KEY;
+            if (!apiKey) {
+                return res.status(500).json({ error: 'OpenAI API key not configured. Please set OPENAI_API_KEY in server environment.' });
+            }
+
+            try {
+                // Create form data for OpenAI
+                const FormData = (await import('form-data')).default;
+                const formData = new FormData();
+                formData.append('file', req.file.buffer, {
+                    filename: req.file.originalname,
+                    contentType: req.file.mimetype
+                });
+                formData.append('model', 'whisper-1');
+                formData.append('response_format', 'json');
+                formData.append('language', 'en');
+
+                // Make request to OpenAI
+                const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${apiKey}`,
+                        ...formData.getHeaders()
+                    },
+                    body: formData
+                });
+
+                if (!response.ok) {
+                    const errorData = await response.json().catch(() => ({}));
+                    throw new Error(errorData.error?.message || `Whisper API error: ${response.status}`);
+                }
+
+                const data = await response.json();
+                let transcribedText = data.text || '';
+
+                // Check if enhancement mode is enabled
+                const mode = req.body.mode || 'default';
+
+                // If no transcribed text, return empty
+                if (!transcribedText) {
+                    return res.json({ text: '' });
+                }
+
+                // If default mode, return transcribed text without enhancement
+                if (mode === 'default') {
+                    return res.json({ text: transcribedText });
+                }
+
+                // Handle different enhancement modes
+                try {
+                    const OpenAI = (await import('openai')).default;
+                    const openai = new OpenAI({ apiKey });
+
+                    let prompt, systemMessage, temperature = 0.7, maxTokens = 800;
+
+                    switch (mode) {
+                        case 'prompt':
+                            systemMessage = 'You are an expert prompt engineer who creates clear, detailed, and effective prompts.';
+                            prompt = `You are an expert prompt engineer. Transform the following rough instruction into a clear, detailed, and context-aware AI prompt.
+
+Your enhanced prompt should:
+1. Be specific and unambiguous
+2. Include relevant context and constraints
+3. Specify the desired output format
+4. Use clear, actionable language
+5. Include examples where helpful
+6. Consider edge cases and potential ambiguities
+
+Transform this rough instruction into a well-crafted prompt:
+"${transcribedText}"
+
+Enhanced prompt:`;
+                            break;
+
+                        case 'vibe':
+                        case 'instructions':
+                        case 'architect':
+                            systemMessage = 'You are a helpful assistant that formats ideas into clear, actionable instructions for AI agents.';
+                            temperature = 0.5; // Lower temperature for more controlled output
+                            prompt = `Transform the following idea into clear, well-structured instructions that an AI agent can easily understand and execute.
+
+IMPORTANT RULES:
+- Format as clear, step-by-step instructions
+- Add reasonable implementation details based on common patterns
+- Only include details directly related to what was asked
+- Do NOT add features or functionality not mentioned
+- Keep the original intent and scope intact
+- Use clear, actionable language an agent can follow
+
+Transform this idea into agent-friendly instructions:
+"${transcribedText}"
+
+Agent instructions:`;
+                            break;
+
+                        default:
+                            // No enhancement needed
+                            break;
+                    }
+
+                    // Only make GPT call if we have a prompt
+                    if (prompt) {
+                        const completion = await openai.chat.completions.create({
+                            model: 'gpt-4o-mini',
+                            messages: [
+                                { role: 'system', content: systemMessage },
+                                { role: 'user', content: prompt }
+                            ],
+                            temperature: temperature,
+                            max_tokens: maxTokens
+                        });
+
+                        transcribedText = completion.choices[0].message.content || transcribedText;
+                    }
+
+                } catch (gptError) {
+                    console.error('GPT processing error:', gptError);
+                    // Fall back to original transcription if GPT fails
+                }
+
+                res.json({ text: transcribedText });
+
+            } catch (error) {
+                console.error('Transcription error:', error);
+                res.status(500).json({ error: error.message });
+            }
+        });
+    } catch (error) {
+        console.error('Endpoint error:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Image upload endpoint
+router.post('/api/projects/:projectName/upload-images', authenticateToken, async (req, res) => {
+    try {
+        const multer = (await import('multer')).default;
+        const path = (await import('path')).default;
+        const fs = (await import('fs')).promises;
+        const os = (await import('os')).default;
+
+        // Configure multer for image uploads
+        const storage = multer.diskStorage({
+            destination: async (req, file, cb) => {
+                const uploadDir = path.join(os.tmpdir(), 'claude-ui-uploads', String(req.user.id));
+                await fs.mkdir(uploadDir, { recursive: true });
+                cb(null, uploadDir);
+            },
+            filename: (req, file, cb) => {
+                const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+                const sanitizedName = file.originalname.replace(/[^a-zA-Z0-9.-]/g, '_');
+                cb(null, uniqueSuffix + '-' + sanitizedName);
+            }
+        });
+
+        const fileFilter = (req, file, cb) => {
+            const allowedMimes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'];
+            if (allowedMimes.includes(file.mimetype)) {
+                cb(null, true);
+            } else {
+                cb(new Error('Invalid file type. Only JPEG, PNG, GIF, WebP, and SVG are allowed.'));
+            }
+        };
+
+        const upload = multer({
+            storage,
+            fileFilter,
+            limits: {
+                fileSize: 5 * 1024 * 1024, // 5MB
+                files: 5
+            }
+        });
+
+        // Handle multipart form data
+        upload.array('images', 5)(req, res, async (err) => {
+            if (err) {
+                return res.status(400).json({ error: err.message });
+            }
+
+            if (!req.files || req.files.length === 0) {
+                return res.status(400).json({ error: 'No image files provided' });
+            }
+
+            try {
+                // Process uploaded images
+                const processedImages = await Promise.all(
+                    req.files.map(async (file) => {
+                        // Read file and convert to base64
+                        const buffer = await fs.readFile(file.path);
+                        const base64 = buffer.toString('base64');
+                        const mimeType = file.mimetype;
+
+                        // Clean up temp file immediately
+                        await fs.unlink(file.path);
+
+                        return {
+                            name: file.originalname,
+                            data: `data:${mimeType};base64,${base64}`,
+                            size: file.size,
+                            mimeType: mimeType
+                        };
+                    })
+                );
+
+                res.json({ images: processedImages });
+            } catch (error) {
+                console.error('Error processing images:', error);
+                // Clean up any remaining files
+                await Promise.all(req.files.map(f => fs.unlink(f.path).catch(() => { })));
+                res.status(500).json({ error: 'Failed to process images' });
+            }
+        });
+    } catch (error) {
+        console.error('Error in image upload endpoint:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+export default router;

server/src/modules/gemini/gemini.routes.js

@@ -0,0 +1,24 @@
+import express from 'express';
+import sessionManager from '../../../sessionManager.js';
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+
+const router = express.Router();
+
+router.delete('/sessions/:sessionId', async (req, res) => {
+    try {
+        const { sessionId } = req.params;
+
+        if (!sessionId || typeof sessionId !== 'string' || !/^[a-zA-Z0-9_.-]{1,100}$/.test(sessionId)) {
+            return res.status(400).json({ success: false, error: 'Invalid session ID format' });
+        }
+
+        await sessionManager.deleteSession(sessionId);
+        await llmSessionsService.deleteSessionArtifacts(sessionId);
+        res.json({ success: true });
+    } catch (error) {
+        console.error(`Error deleting Gemini session ${req.params.sessionId}:`, error);
+        res.status(500).json({ success: false, error: error.message });
+    }
+});
+
+export default router;

server/src/modules/git/.gitkeep

@@ -0,0 +1 @@
+

server/src/modules/health/health.routes.js

@@ -0,0 +1,21 @@
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const router = express.Router();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const installMode = fs.existsSync(path.join(__dirname, '../../../../.git')) ? 'git' : 'npm';
+
+// Public health check endpoint (no authentication required)
+router.get('/health', (req, res) => {
+    res.json({
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        installMode
+    });
+});
+
+export default router;

server/src/modules/mcp-utils/mcp-utils.routes.js

@@ -0,0 +1,48 @@
+/**
+ * MCP UTILITIES API ROUTES
+ * ========================
+ * 
+ * API endpoints for MCP server detection and configuration utilities.
+ * These endpoints expose centralized MCP detection functionality.
+ */
+
+import express from 'express';
+import { detectTaskMasterMCPServer, getAllMCPServers } from '../../../utils/mcp-detector.js';
+
+const router = express.Router();
+
+/**
+ * GET /api/mcp-utils/taskmaster-server
+ * Check if TaskMaster MCP server is configured
+ */
+router.get('/taskmaster-server', async (req, res) => {
+    try {
+        const result = await detectTaskMasterMCPServer();
+        res.json(result);
+    } catch (error) {
+        console.error('TaskMaster MCP detection error:', error);
+        res.status(500).json({
+            error: 'Failed to detect TaskMaster MCP server',
+            message: error.message
+        });
+    }
+});
+
+/**
+ * GET /api/mcp-utils/all-servers
+ * Get all configured MCP servers
+ */
+router.get('/all-servers', async (req, res) => {
+    try {
+        const result = await getAllMCPServers();
+        res.json(result);
+    } catch (error) {
+        console.error('MCP servers detection error:', error);
+        res.status(500).json({
+            error: 'Failed to get MCP servers',
+            message: error.message
+        });
+    }
+});
+
+export default router;

server/src/modules/mcp/mcp.routes.js

@@ -0,0 +1,540 @@
+import express from 'express';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import spawn from 'cross-spawn';
+
+const router = express.Router();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Claude CLI command routes
+
+// GET /api/mcp/cli/list - List MCP servers using Claude CLI
+router.get('/cli/list', async (req, res) => {
+  try {
+    console.log('📋 Listing MCP servers using Claude CLI');
+    
+    const process = spawn('claude', ['mcp', 'list'], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    
+    let stdout = '';
+    let stderr = '';
+    
+    process.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    process.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    process.on('close', (code) => {
+      if (code === 0) {
+        res.json({ success: true, output: stdout, servers: parseClaudeListOutput(stdout) });
+      } else {
+        console.error('Claude CLI error:', stderr);
+        res.status(500).json({ error: 'Claude CLI command failed', details: stderr });
+      }
+    });
+    
+    process.on('error', (error) => {
+      console.error('Error running Claude CLI:', error);
+      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
+    });
+  } catch (error) {
+    console.error('Error listing MCP servers via CLI:', error);
+    res.status(500).json({ error: 'Failed to list MCP servers', details: error.message });
+  }
+});
+
+// POST /api/mcp/cli/add - Add MCP server using Claude CLI
+router.post('/cli/add', async (req, res) => {
+  try {
+    const { name, type = 'stdio', command, args = [], url, headers = {}, env = {}, scope = 'user', projectPath } = req.body;
+    
+    console.log(`➕ Adding MCP server using Claude CLI (${scope} scope):`, name);
+    
+    let cliArgs = ['mcp', 'add'];
+    
+    // Add scope flag
+    cliArgs.push('--scope', scope);
+    
+    if (type === 'http') {
+      cliArgs.push('--transport', 'http', name, url);
+      // Add headers if provided
+      Object.entries(headers).forEach(([key, value]) => {
+        cliArgs.push('--header', `${key}: ${value}`);
+      });
+    } else if (type === 'sse') {
+      cliArgs.push('--transport', 'sse', name, url);
+      // Add headers if provided
+      Object.entries(headers).forEach(([key, value]) => {
+        cliArgs.push('--header', `${key}: ${value}`);
+      });
+    } else {
+      // stdio (default): claude mcp add --scope user <name> <command> [args...]
+      cliArgs.push(name);
+      // Add environment variables
+      Object.entries(env).forEach(([key, value]) => {
+        cliArgs.push('-e', `${key}=${value}`);
+      });
+      cliArgs.push(command);
+      if (args && args.length > 0) {
+        cliArgs.push(...args);
+      }
+    }
+    
+    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs.join(' '));
+    
+    // For local scope, we need to run the command in the project directory
+    const spawnOptions = {
+      stdio: ['pipe', 'pipe', 'pipe']
+    };
+    
+    if (scope === 'local' && projectPath) {
+      spawnOptions.cwd = projectPath;
+      console.log('📁 Running in project directory:', projectPath);
+    }
+    
+    const process = spawn('claude', cliArgs, spawnOptions);
+    
+    let stdout = '';
+    let stderr = '';
+    
+    process.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    process.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    process.on('close', (code) => {
+      if (code === 0) {
+        res.json({ success: true, output: stdout, message: `MCP server "${name}" added successfully` });
+      } else {
+        console.error('Claude CLI error:', stderr);
+        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
+      }
+    });
+    
+    process.on('error', (error) => {
+      console.error('Error running Claude CLI:', error);
+      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
+    });
+  } catch (error) {
+    console.error('Error adding MCP server via CLI:', error);
+    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
+  }
+});
+
+// POST /api/mcp/cli/add-json - Add MCP server using JSON format
+router.post('/cli/add-json', async (req, res) => {
+  try {
+    const { name, jsonConfig, scope = 'user', projectPath } = req.body;
+    
+    console.log('➕ Adding MCP server using JSON format:', name);
+    
+    // Validate and parse JSON config
+    let parsedConfig;
+    try {
+      parsedConfig = typeof jsonConfig === 'string' ? JSON.parse(jsonConfig) : jsonConfig;
+    } catch (parseError) {
+      return res.status(400).json({ 
+        error: 'Invalid JSON configuration', 
+        details: parseError.message 
+      });
+    }
+    
+    // Validate required fields
+    if (!parsedConfig.type) {
+      return res.status(400).json({ 
+        error: 'Invalid configuration', 
+        details: 'Missing required field: type' 
+      });
+    }
+    
+    if (parsedConfig.type === 'stdio' && !parsedConfig.command) {
+      return res.status(400).json({ 
+        error: 'Invalid configuration', 
+        details: 'stdio type requires a command field' 
+      });
+    }
+    
+    if ((parsedConfig.type === 'http' || parsedConfig.type === 'sse') && !parsedConfig.url) {
+      return res.status(400).json({ 
+        error: 'Invalid configuration', 
+        details: `${parsedConfig.type} type requires a url field` 
+      });
+    }
+    
+    // Build the command: claude mcp add-json --scope <scope> <name> '<json>'
+    const cliArgs = ['mcp', 'add-json', '--scope', scope, name];
+    
+    // Add the JSON config as a properly formatted string
+    const jsonString = JSON.stringify(parsedConfig);
+    cliArgs.push(jsonString);
+    
+    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs[0], cliArgs[1], cliArgs[2], cliArgs[3], cliArgs[4], jsonString);
+    
+    // For local scope, we need to run the command in the project directory
+    const spawnOptions = {
+      stdio: ['pipe', 'pipe', 'pipe']
+    };
+    
+    if (scope === 'local' && projectPath) {
+      spawnOptions.cwd = projectPath;
+      console.log('📁 Running in project directory:', projectPath);
+    }
+    
+    const process = spawn('claude', cliArgs, spawnOptions);
+    
+    let stdout = '';
+    let stderr = '';
+    
+    process.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    process.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    process.on('close', (code) => {
+      if (code === 0) {
+        res.json({ success: true, output: stdout, message: `MCP server "${name}" added successfully via JSON` });
+      } else {
+        console.error('Claude CLI error:', stderr);
+        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
+      }
+    });
+    
+    process.on('error', (error) => {
+      console.error('Error running Claude CLI:', error);
+      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
+    });
+  } catch (error) {
+    console.error('Error adding MCP server via JSON:', error);
+    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
+  }
+});
+
+// DELETE /api/mcp/cli/remove/:name - Remove MCP server using Claude CLI
+router.delete('/cli/remove/:name', async (req, res) => {
+  try {
+    const { name } = req.params;
+    const { scope } = req.query; // Get scope from query params
+    
+    // Handle the ID format (remove scope prefix if present)
+    let actualName = name;
+    let actualScope = scope;
+    
+    // If the name includes a scope prefix like "local:test", extract it
+    if (name.includes(':')) {
+      const [prefix, serverName] = name.split(':');
+      actualName = serverName;
+      actualScope = actualScope || prefix; // Use prefix as scope if not provided in query
+    }
+    
+    console.log('🗑️ Removing MCP server using Claude CLI:', actualName, 'scope:', actualScope);
+    
+    // Build command args based on scope
+    let cliArgs = ['mcp', 'remove'];
+    
+    // Add scope flag if it's local scope
+    if (actualScope === 'local') {
+      cliArgs.push('--scope', 'local');
+    } else if (actualScope === 'user' || !actualScope) {
+      // User scope is default, but we can be explicit
+      cliArgs.push('--scope', 'user');
+    }
+    
+    cliArgs.push(actualName);
+    
+    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs.join(' '));
+    
+    const process = spawn('claude', cliArgs, {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    
+    let stdout = '';
+    let stderr = '';
+    
+    process.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    process.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    process.on('close', (code) => {
+      if (code === 0) {
+        res.json({ success: true, output: stdout, message: `MCP server "${name}" removed successfully` });
+      } else {
+        console.error('Claude CLI error:', stderr);
+        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
+      }
+    });
+    
+    process.on('error', (error) => {
+      console.error('Error running Claude CLI:', error);
+      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
+    });
+  } catch (error) {
+    console.error('Error removing MCP server via CLI:', error);
+    res.status(500).json({ error: 'Failed to remove MCP server', details: error.message });
+  }
+});
+
+// GET /api/mcp/cli/get/:name - Get MCP server details using Claude CLI
+router.get('/cli/get/:name', async (req, res) => {
+  try {
+    const { name } = req.params;
+    
+    console.log('📄 Getting MCP server details using Claude CLI:', name);
+    
+    const process = spawn('claude', ['mcp', 'get', name], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    
+    let stdout = '';
+    let stderr = '';
+    
+    process.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    process.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    process.on('close', (code) => {
+      if (code === 0) {
+        res.json({ success: true, output: stdout, server: parseClaudeGetOutput(stdout) });
+      } else {
+        console.error('Claude CLI error:', stderr);
+        res.status(404).json({ error: 'Claude CLI command failed', details: stderr });
+      }
+    });
+    
+    process.on('error', (error) => {
+      console.error('Error running Claude CLI:', error);
+      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
+    });
+  } catch (error) {
+    console.error('Error getting MCP server details via CLI:', error);
+    res.status(500).json({ error: 'Failed to get MCP server details', details: error.message });
+  }
+});
+
+// GET /api/mcp/config/read - Read MCP servers directly from Claude config files
+router.get('/config/read', async (req, res) => {
+  try {
+    console.log('📖 Reading MCP servers from Claude config files');
+    
+    const homeDir = os.homedir();
+    const configPaths = [
+      path.join(homeDir, '.claude.json'),
+      path.join(homeDir, '.claude', 'settings.json')
+    ];
+    
+    let configData = null;
+    let configPath = null;
+    
+    // Try to read from either config file
+    for (const filepath of configPaths) {
+      try {
+        const fileContent = await fs.readFile(filepath, 'utf8');
+        configData = JSON.parse(fileContent);
+        configPath = filepath;
+        console.log(`✅ Found Claude config at: ${filepath}`);
+        break;
+      } catch (error) {
+        // File doesn't exist or is not valid JSON, try next
+        console.log(`ℹ️ Config not found or invalid at: ${filepath}`);
+      }
+    }
+    
+    if (!configData) {
+      return res.json({ 
+        success: false, 
+        message: 'No Claude configuration file found',
+        servers: [] 
+      });
+    }
+    
+    // Extract MCP servers from the config
+    const servers = [];
+    
+    // Check for user-scoped MCP servers (at root level)
+    if (configData.mcpServers && typeof configData.mcpServers === 'object' && Object.keys(configData.mcpServers).length > 0) {
+      console.log('🔍 Found user-scoped MCP servers:', Object.keys(configData.mcpServers));
+      for (const [name, config] of Object.entries(configData.mcpServers)) {
+        const server = {
+          id: name,
+          name: name,
+          type: 'stdio', // Default type
+          scope: 'user',  // User scope - available across all projects
+          config: {},
+          raw: config // Include raw config for full details
+        };
+        
+        // Determine transport type and extract config
+        if (config.command) {
+          server.type = 'stdio';
+          server.config.command = config.command;
+          server.config.args = config.args || [];
+          server.config.env = config.env || {};
+        } else if (config.url) {
+          server.type = config.transport || 'http';
+          server.config.url = config.url;
+          server.config.headers = config.headers || {};
+        }
+        
+        servers.push(server);
+      }
+    }
+    
+    // Check for local-scoped MCP servers (project-specific)
+    const currentProjectPath = process.cwd();
+    
+    // Check under 'projects' key
+    if (configData.projects && configData.projects[currentProjectPath]) {
+      const projectConfig = configData.projects[currentProjectPath];
+      if (projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object' && Object.keys(projectConfig.mcpServers).length > 0) {
+        console.log(`🔍 Found local-scoped MCP servers for ${currentProjectPath}:`, Object.keys(projectConfig.mcpServers));
+        for (const [name, config] of Object.entries(projectConfig.mcpServers)) {
+          const server = {
+            id: `local:${name}`,  // Prefix with scope for uniqueness
+            name: name,           // Keep original name
+            type: 'stdio', // Default type
+            scope: 'local',  // Local scope - only for this project
+            projectPath: currentProjectPath,
+            config: {},
+            raw: config // Include raw config for full details
+          };
+          
+          // Determine transport type and extract config
+          if (config.command) {
+            server.type = 'stdio';
+            server.config.command = config.command;
+            server.config.args = config.args || [];
+            server.config.env = config.env || {};
+          } else if (config.url) {
+            server.type = config.transport || 'http';
+            server.config.url = config.url;
+            server.config.headers = config.headers || {};
+          }
+          
+          servers.push(server);
+        }
+      }
+    }
+    
+    console.log(`📋 Found ${servers.length} MCP servers in config`);
+    
+    res.json({ 
+      success: true, 
+      configPath: configPath,
+      servers: servers 
+    });
+  } catch (error) {
+    console.error('Error reading Claude config:', error);
+    res.status(500).json({ 
+      error: 'Failed to read Claude configuration', 
+      details: error.message 
+    });
+  }
+});
+
+// Helper functions to parse Claude CLI output
+function parseClaudeListOutput(output) {
+  const servers = [];
+  const lines = output.split('\n').filter(line => line.trim());
+  
+  for (const line of lines) {
+    // Skip the header line
+    if (line.includes('Checking MCP server health')) continue;
+    
+    // Parse lines like "test: test test - ✗ Failed to connect"
+    // or "server-name: command or description - ✓ Connected"
+    if (line.includes(':')) {
+      const colonIndex = line.indexOf(':');
+      const name = line.substring(0, colonIndex).trim();
+      
+      // Skip empty names
+      if (!name) continue;
+      
+      // Extract the rest after the name
+      const rest = line.substring(colonIndex + 1).trim();
+      
+      // Try to extract description and status
+      let description = rest;
+      let status = 'unknown';
+      let type = 'stdio'; // default type
+      
+      // Check for status indicators
+      if (rest.includes('✓') || rest.includes('✗')) {
+        const statusMatch = rest.match(/(.*?)\s*-\s*([✓✗].*)$/);
+        if (statusMatch) {
+          description = statusMatch[1].trim();
+          status = statusMatch[2].includes('✓') ? 'connected' : 'failed';
+        }
+      }
+      
+      // Try to determine type from description
+      if (description.startsWith('http://') || description.startsWith('https://')) {
+        type = 'http';
+      }
+      
+      servers.push({
+        name,
+        type,
+        status: status || 'active',
+        description
+      });
+    }
+  }
+  
+  console.log('🔍 Parsed Claude CLI servers:', servers);
+  return servers;
+}
+
+function parseClaudeGetOutput(output) {
+  // Parse the output from 'claude mcp get <name>' command
+  // This is a simple parser - might need adjustment based on actual output format
+  try {
+    // Try to extract JSON if present
+    const jsonMatch = output.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+    
+    // Otherwise, parse as text
+    const server = { raw_output: output };
+    const lines = output.split('\n');
+    
+    for (const line of lines) {
+      if (line.includes('Name:')) {
+        server.name = line.split(':')[1]?.trim();
+      } else if (line.includes('Type:')) {
+        server.type = line.split(':')[1]?.trim();
+      } else if (line.includes('Command:')) {
+        server.command = line.split(':')[1]?.trim();
+      } else if (line.includes('URL:')) {
+        server.url = line.split(':')[1]?.trim();
+      }
+    }
+    
+    return server;
+  } catch (error) {
+    return { raw_output: output, parse_error: error.message };
+  }
+}
+
+export default router;

server/src/modules/messages/messages.routes.js

@@ -0,0 +1,61 @@
+/**
+ * Unified messages endpoint.
+ *
+ * GET /api/sessions/:sessionId/messages?provider=claude&projectName=foo&limit=50&offset=0
+ *
+ * Replaces the four provider-specific session message endpoints with a single route
+ * that delegates to the appropriate adapter via the provider registry.
+ *
+ * @module routes/messages
+ */
+
+import express from 'express';
+import { getProvider, getAllProviders } from '../../../providers/registry.js';
+
+const router = express.Router();
+
+/**
+ * GET /api/sessions/:sessionId/messages
+ *
+ * Auth: authenticateToken applied at mount level in index.js
+ *
+ * Query params:
+ *   provider    - 'claude' | 'cursor' | 'codex' | 'gemini' (default: 'claude')
+ *   projectName - required for claude provider
+ *   projectPath - required for cursor provider (absolute path used for cwdId hash)
+ *   limit       - page size (omit or null for all)
+ *   offset      - pagination offset (default: 0)
+ */
+router.get('/:sessionId/messages', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const provider = req.query.provider || 'claude';
+    const projectName = req.query.projectName || '';
+    const projectPath = req.query.projectPath || '';
+    const limitParam = req.query.limit;
+    const limit = limitParam !== undefined && limitParam !== null && limitParam !== ''
+      ? parseInt(limitParam, 10)
+      : null;
+    const offset = parseInt(req.query.offset || '0', 10);
+
+    const adapter = getProvider(provider);
+    if (!adapter) {
+      const available = getAllProviders().join(', ');
+      return res.status(400).json({ error: `Unknown provider: ${provider}. Available: ${available}` });
+    }
+
+    const result = await adapter.fetchHistory(sessionId, {
+      projectName,
+      projectPath,
+      limit,
+      offset,
+    });
+
+    return res.json(result);
+  } catch (error) {
+    console.error('Error fetching unified messages:', error);
+    return res.status(500).json({ error: 'Failed to fetch messages' });
+  }
+});
+
+export default router;

server/src/modules/notification-preferences/notification-preferences.routes.js

@@ -0,0 +1,30 @@
+import express from 'express';
+import { notificationPreferencesDb } from '@/shared/database/repositories/notification-preferences.js';
+
+const router = express.Router();
+
+// ===============================
+// Notification Preferences
+// ===============================
+
+router.get('/', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.getNotificationPreferences(req.user.id);
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error fetching notification preferences:', error);
+    res.status(500).json({ error: 'Failed to fetch notification preferences' });
+  }
+});
+
+router.put('/', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.updateNotificationPreferences(req.user.id, req.body || {});
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error saving notification preferences:', error);
+    res.status(500).json({ error: 'Failed to save notification preferences' });
+  }
+});
+
+export default router;

server/src/modules/plugins/plugins.routes.js

@@ -0,0 +1,307 @@
+import express from 'express';
+import path from 'path';
+import http from 'http';
+import mime from 'mime-types';
+import fs from 'fs';
+import {
+  scanPlugins,
+  getPluginsConfig,
+  getPluginsDir,
+  savePluginsConfig,
+  getPluginDir,
+  resolvePluginAssetPath,
+  installPluginFromGit,
+  updatePluginFromGit,
+  uninstallPlugin,
+} from '../../../utils/plugin-loader.js';
+import {
+  startPluginServer,
+  stopPluginServer,
+  getPluginPort,
+  isPluginRunning,
+} from '../../../utils/plugin-process-manager.js';
+
+const router = express.Router();
+
+// GET / — List all installed plugins (includes server running status)
+router.get('/', (req, res) => {
+  try {
+    const plugins = scanPlugins().map(p => ({
+      ...p,
+      serverRunning: p.server ? isPluginRunning(p.name) : false,
+    }));
+    res.json({ plugins });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to scan plugins', details: err.message });
+  }
+});
+
+// GET /:name/manifest — Get single plugin manifest
+router.get('/:name/manifest', (req, res) => {
+  try {
+    if (!/^[a-zA-Z0-9_-]+$/.test(req.params.name)) {
+      return res.status(400).json({ error: 'Invalid plugin name' });
+    }
+    const plugins = scanPlugins();
+    const plugin = plugins.find(p => p.name === req.params.name);
+    if (!plugin) {
+      return res.status(404).json({ error: 'Plugin not found' });
+    }
+    res.json(plugin);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to read plugin manifest', details: err.message });
+  }
+});
+
+// GET /:name/assets/* — Serve plugin static files
+router.get('/:name/assets/*', (req, res) => {
+  const pluginName = req.params.name;
+  if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+    return res.status(400).json({ error: 'Invalid plugin name' });
+  }
+  const assetPath = req.params[0];
+
+  if (!assetPath) {
+    return res.status(400).json({ error: 'No asset path specified' });
+  }
+
+  const resolvedPath = resolvePluginAssetPath(pluginName, assetPath);
+  if (!resolvedPath) {
+    return res.status(404).json({ error: 'Asset not found' });
+  }
+
+  try {
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isFile()) {
+      return res.status(404).json({ error: 'Asset not found' });
+    }
+  } catch {
+    return res.status(404).json({ error: 'Asset not found' });
+  }
+
+  const contentType = mime.lookup(resolvedPath) || 'application/octet-stream';
+  res.setHeader('Content-Type', contentType);
+  // Prevent CDN/proxy caching of plugin assets so updates take effect immediately
+  res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+  res.setHeader('Pragma', 'no-cache');
+  res.setHeader('Expires', '0');
+  const stream = fs.createReadStream(resolvedPath);
+  stream.on('error', () => {
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Failed to read asset' });
+    } else {
+      res.end();
+    }
+  });
+  stream.pipe(res);
+});
+
+// PUT /:name/enable — Toggle plugin enabled/disabled (starts/stops server if applicable)
+router.put('/:name/enable', async (req, res) => {
+  try {
+    const { enabled } = req.body;
+    if (typeof enabled !== 'boolean') {
+      return res.status(400).json({ error: '"enabled" must be a boolean' });
+    }
+
+    const plugins = scanPlugins();
+    const plugin = plugins.find(p => p.name === req.params.name);
+    if (!plugin) {
+      return res.status(404).json({ error: 'Plugin not found' });
+    }
+
+    const config = getPluginsConfig();
+    config[req.params.name] = { ...config[req.params.name], enabled };
+    savePluginsConfig(config);
+
+    // Start or stop the plugin server as needed
+    if (plugin.server) {
+      if (enabled && !isPluginRunning(plugin.name)) {
+        const pluginDir = getPluginDir(plugin.name);
+        if (pluginDir) {
+          try {
+            await startPluginServer(plugin.name, pluginDir, plugin.server);
+          } catch (err) {
+            console.error(`[Plugins] Failed to start server for "${plugin.name}":`, err.message);
+          }
+        }
+      } else if (!enabled && isPluginRunning(plugin.name)) {
+        await stopPluginServer(plugin.name);
+      }
+    }
+
+    res.json({ success: true, name: req.params.name, enabled });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to update plugin', details: err.message });
+  }
+});
+
+// POST /install — Install plugin from git URL
+router.post('/install', async (req, res) => {
+  try {
+    const { url } = req.body;
+    if (!url || typeof url !== 'string') {
+      return res.status(400).json({ error: '"url" is required and must be a string' });
+    }
+
+    // Basic URL validation
+    if (!url.startsWith('https://') && !url.startsWith('git@')) {
+      return res.status(400).json({ error: 'URL must start with https:// or git@' });
+    }
+
+    const manifest = await installPluginFromGit(url);
+
+    // Auto-start the server if the plugin has one (enabled by default)
+    if (manifest.server) {
+      const pluginDir = getPluginDir(manifest.name);
+      if (pluginDir) {
+        try {
+          await startPluginServer(manifest.name, pluginDir, manifest.server);
+        } catch (err) {
+          console.error(`[Plugins] Failed to start server for "${manifest.name}":`, err.message);
+        }
+      }
+    }
+
+    res.json({ success: true, plugin: manifest });
+  } catch (err) {
+    res.status(400).json({ error: 'Failed to install plugin', details: err.message });
+  }
+});
+
+// POST /:name/update — Pull latest from git (restarts server if running)
+router.post('/:name/update', async (req, res) => {
+  try {
+    const pluginName = req.params.name;
+
+    if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+      return res.status(400).json({ error: 'Invalid plugin name' });
+    }
+
+    const wasRunning = isPluginRunning(pluginName);
+    if (wasRunning) {
+      await stopPluginServer(pluginName);
+    }
+
+    const manifest = await updatePluginFromGit(pluginName);
+
+    // Restart server if it was running before the update
+    if (wasRunning && manifest.server) {
+      const pluginDir = getPluginDir(pluginName);
+      if (pluginDir) {
+        try {
+          await startPluginServer(pluginName, pluginDir, manifest.server);
+        } catch (err) {
+          console.error(`[Plugins] Failed to restart server for "${pluginName}":`, err.message);
+        }
+      }
+    }
+
+    res.json({ success: true, plugin: manifest });
+  } catch (err) {
+    res.status(400).json({ error: 'Failed to update plugin', details: err.message });
+  }
+});
+
+// ALL /:name/rpc/* — Proxy requests to plugin's server subprocess
+router.all('/:name/rpc/*', async (req, res) => {
+  const pluginName = req.params.name;
+  const rpcPath = req.params[0] || '';
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+    return res.status(400).json({ error: 'Invalid plugin name' });
+  }
+
+  let port = getPluginPort(pluginName);
+  if (!port) {
+    // Lazily start the plugin server if it exists and is enabled
+    const plugins = scanPlugins();
+    const plugin = plugins.find(p => p.name === pluginName);
+    if (!plugin || !plugin.server) {
+      return res.status(503).json({ error: 'Plugin server is not running' });
+    }
+    if (!plugin.enabled) {
+      return res.status(503).json({ error: 'Plugin is disabled' });
+    }
+    const pluginDir = path.join(getPluginsDir(), plugin.dirName);
+    try {
+      port = await startPluginServer(pluginName, pluginDir, plugin.server);
+    } catch (err) {
+      return res.status(503).json({ error: 'Plugin server failed to start', details: err.message });
+    }
+  }
+
+  // Inject configured secrets as headers
+  const config = getPluginsConfig();
+  const pluginConfig = config[pluginName] || {};
+  const secrets = pluginConfig.secrets || {};
+
+  const headers = {
+    'content-type': req.headers['content-type'] || 'application/json',
+  };
+
+  // Add per-plugin user-configured secrets as X-Plugin-Secret-* headers
+  for (const [key, value] of Object.entries(secrets)) {
+    headers[`x-plugin-secret-${key.toLowerCase()}`] = String(value);
+  }
+
+  // Reconstruct query string
+  const qs = req.url.includes('?') ? '?' + req.url.split('?').slice(1).join('?') : '';
+
+  const options = {
+    hostname: '127.0.0.1',
+    port,
+    path: `/${rpcPath}${qs}`,
+    method: req.method,
+    headers,
+  };
+
+  const proxyReq = http.request(options, (proxyRes) => {
+    res.writeHead(proxyRes.statusCode, proxyRes.headers);
+    proxyRes.pipe(res);
+  });
+
+  proxyReq.on('error', (err) => {
+    if (!res.headersSent) {
+      res.status(502).json({ error: 'Plugin server error', details: err.message });
+    } else {
+      res.end();
+    }
+  });
+
+  // Forward body (already parsed by express JSON middleware, so re-stringify).
+  // Check content-length to detect whether a body was actually sent, since
+  // req.body can be falsy for valid payloads like 0, false, null, or {}.
+  const hasBody = req.headers['content-length'] && parseInt(req.headers['content-length'], 10) > 0;
+  if (hasBody && req.body !== undefined) {
+    const bodyStr = JSON.stringify(req.body);
+    proxyReq.setHeader('content-length', Buffer.byteLength(bodyStr));
+    proxyReq.write(bodyStr);
+  }
+
+  proxyReq.end();
+});
+
+// DELETE /:name — Uninstall plugin (stops server first)
+router.delete('/:name', async (req, res) => {
+  try {
+    const pluginName = req.params.name;
+
+    // Validate name format to prevent path traversal
+    if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+      return res.status(400).json({ error: 'Invalid plugin name' });
+    }
+
+    // Stop server and wait for the process to fully exit before deleting files
+    if (isPluginRunning(pluginName)) {
+      await stopPluginServer(pluginName);
+    }
+
+    await uninstallPlugin(pluginName);
+    res.json({ success: true, name: pluginName });
+  } catch (err) {
+    res.status(400).json({ error: 'Failed to uninstall plugin', details: err.message });
+  }
+});
+
+export default router;

server/src/modules/projects/.gitkeep

@@ -0,0 +1 @@
+

server/src/modules/projects/projects.inline.routes.js

@@ -0,0 +1,381 @@
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import { promises as fsPromises } from 'fs';
+import {
+    getProjects,
+    getSessions,
+    renameProject,
+    deleteProject,
+    searchConversations
+} from '../../../projects.js';
+import { sessionsDb } from '@/shared/database/repositories/sessions.db.js';
+import { workspaceOriginalPathsDb } from '@/shared/database/repositories/workspace-original-paths.db.js';
+import { llmSessionsService } from '@/modules/ai-runtime/services/sessions.service.js';
+import { authenticateToken } from '../auth/auth.middleware.js';
+import { getWorkspaceNameFromPath, WORKSPACES_ROOT, validateWorkspacePath } from './projects.utils.js';
+
+const router = express.Router();
+
+// Broadcast progress to all connected WebSocket clients
+function broadcastProgress(req, progress) {
+    const connectedClients = req.app.locals.connectedClients;
+    if (!connectedClients) return;
+
+    const message = JSON.stringify({
+        type: 'loading_progress',
+        ...progress
+    });
+    connectedClients.forEach(client => {
+        if (client.readyState === 1) {
+            client.send(message);
+        }
+    });
+}
+
+router.get('/api/projects', authenticateToken, async (req, res) => {
+    try {
+        const projects = await getProjects((progress) => broadcastProgress(req, progress));
+        res.json(projects);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+router.get('/api/projects/:projectName/sessions', authenticateToken, async (req, res) => {
+    try {
+        const { limit = 5, offset = 0 } = req.query;
+        const result = await getSessions(req.params.projectName, parseInt(limit), parseInt(offset));
+        sessionsDb.applyCustomSessionNames(result.sessions, 'claude');
+        res.json(result);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Rename project endpoint
+router.put('/api/projects/:projectName/rename', authenticateToken, async (req, res) => {
+    try {
+        const { displayName } = req.body;
+        await renameProject(req.params.projectName, displayName);
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Delete session endpoint
+router.delete('/api/projects/:projectName/sessions/:sessionId', authenticateToken, async (req, res) => {
+    try {
+        const { projectName, sessionId } = req.params;
+        console.log(`[API] Deleting session: ${sessionId} from project: ${projectName}`);
+        await llmSessionsService.deleteSessionArtifacts(sessionId);
+        console.log(`[API] Session ${sessionId} deleted successfully`);
+        res.json({ success: true });
+    } catch (error) {
+        console.error(`[API] Error deleting session ${req.params.sessionId}:`, error);
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Delete project endpoint (force=true to delete with sessions)
+router.delete('/api/projects/:projectName', authenticateToken, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const force = req.query.force === 'true';
+        await deleteProject(projectName, force);
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Create project endpoint
+router.post('/api/projects/create', authenticateToken, async (req, res) => {
+    try {
+        const { path: projectPath } = req.body;
+
+        if (!projectPath || !projectPath.trim()) {
+            return res.status(400).json({ error: 'Project path is required' });
+        }
+
+        const resolvedPath = path.resolve(projectPath.trim());
+        const validation = await validateWorkspacePath(resolvedPath);
+        if (!validation.valid) {
+            return res.status(400).json({
+                error: 'Invalid workspace path',
+                details: validation.error
+            });
+        }
+
+        const safePath = validation.resolvedPath || resolvedPath;
+        workspaceOriginalPathsDb.createWorkspacePath(safePath, getWorkspaceNameFromPath(safePath));
+        res.json({ success: true, message: 'Workspace saved successfully' });
+    } catch (error) {
+        console.error('Error creating project:', error);
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Search conversations content (SSE streaming)
+router.get('/api/search/conversations', authenticateToken, async (req, res) => {
+    const query = typeof req.query.q === 'string' ? req.query.q.trim() : '';
+    const parsedLimit = Number.parseInt(String(req.query.limit), 10);
+    const limit = Number.isNaN(parsedLimit) ? 50 : Math.max(1, Math.min(parsedLimit, 100));
+
+    if (query.length < 2) {
+        return res.status(400).json({ error: 'Query must be at least 2 characters' });
+    }
+
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    });
+
+    let closed = false;
+    const abortController = new AbortController();
+    req.on('close', () => { closed = true; abortController.abort(); });
+
+    try {
+        await searchConversations(query, limit, ({ projectResult, totalMatches, scannedProjects, totalProjects }) => {
+            if (closed) return;
+            if (projectResult) {
+                res.write(`event: result\ndata: ${JSON.stringify({ projectResult, totalMatches, scannedProjects, totalProjects })}\n\n`);
+            } else {
+                res.write(`event: progress\ndata: ${JSON.stringify({ totalMatches, scannedProjects, totalProjects })}\n\n`);
+            }
+        }, abortController.signal);
+        if (!closed) {
+            res.write(`event: done\ndata: {}\n\n`);
+        }
+    } catch (error) {
+        console.error('Error searching conversations:', error);
+        if (!closed) {
+            res.write(`event: error\ndata: ${JSON.stringify({ error: 'Search failed' })}\n\n`);
+        }
+    } finally {
+        if (!closed) {
+            res.end();
+        }
+    }
+});
+
+const expandWorkspacePath = (inputPath) => {
+    if (!inputPath) return inputPath;
+    if (inputPath === '~') {
+        return WORKSPACES_ROOT;
+    }
+    if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+        return path.join(WORKSPACES_ROOT, inputPath.slice(2));
+    }
+    return inputPath;
+};
+
+// Browse filesystem endpoint for project suggestions - uses existing getFileTree
+router.get('/api/browse-filesystem', authenticateToken, async (req, res) => {
+    try {
+        const { path: dirPath } = req.query;
+
+        console.log('[API] Browse filesystem request for path:', dirPath);
+        console.log('[API] WORKSPACES_ROOT is:', WORKSPACES_ROOT);
+        // Default to home directory if no path provided
+        const defaultRoot = WORKSPACES_ROOT;
+        let targetPath = dirPath ? expandWorkspacePath(dirPath) : defaultRoot;
+
+        // Resolve and normalize the path
+        targetPath = path.resolve(targetPath);
+
+        // Security check - ensure path is within allowed workspace root
+        const validation = await validateWorkspacePath(targetPath);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+        const resolvedPath = validation.resolvedPath || targetPath;
+
+        // Security check - ensure path is accessible
+        try {
+            await fs.promises.access(resolvedPath);
+            const stats = await fs.promises.stat(resolvedPath);
+
+            if (!stats.isDirectory()) {
+                return res.status(400).json({ error: 'Path is not a directory' });
+            }
+        } catch (err) {
+            return res.status(404).json({ error: 'Directory not accessible' });
+        }
+
+        // Use existing getFileTree function with shallow depth (only direct children)
+        const fileTree = await getFileTree(resolvedPath, 1, 0, false); // maxDepth=1, showHidden=false
+
+        // Filter only directories and format for suggestions
+        const directories = fileTree
+            .filter(item => item.type === 'directory')
+            .map(item => ({
+                path: item.path,
+                name: item.name,
+                type: 'directory'
+            }))
+            .sort((a, b) => {
+                const aHidden = a.name.startsWith('.');
+                const bHidden = b.name.startsWith('.');
+                if (aHidden && !bHidden) return 1;
+                if (!aHidden && bHidden) return -1;
+                return a.name.localeCompare(b.name);
+            });
+
+        // Add common directories if browsing home directory
+        const suggestions = [];
+        let resolvedWorkspaceRoot = defaultRoot;
+        try {
+            resolvedWorkspaceRoot = await fsPromises.realpath(defaultRoot);
+        } catch (error) {
+            // Use default root as-is if realpath fails
+        }
+        if (resolvedPath === resolvedWorkspaceRoot) {
+            const commonDirs = ['Desktop', 'Documents', 'Projects', 'Development', 'Dev', 'Code', 'workspace'];
+            const existingCommon = directories.filter(dir => commonDirs.includes(dir.name));
+            const otherDirs = directories.filter(dir => !commonDirs.includes(dir.name));
+
+            suggestions.push(...existingCommon, ...otherDirs);
+        } else {
+            suggestions.push(...directories);
+        }
+
+        res.json({
+            path: resolvedPath,
+            suggestions: suggestions
+        });
+
+    } catch (error) {
+        console.error('Error browsing filesystem:', error);
+        res.status(500).json({ error: 'Failed to browse filesystem' });
+    }
+});
+
+router.post('/api/create-folder', authenticateToken, async (req, res) => {
+    try {
+        const { path: folderPath } = req.body;
+        if (!folderPath) {
+            return res.status(400).json({ error: 'Path is required' });
+        }
+        const expandedPath = expandWorkspacePath(folderPath);
+        const resolvedInput = path.resolve(expandedPath);
+        const validation = await validateWorkspacePath(resolvedInput);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+        const targetPath = validation.resolvedPath || resolvedInput;
+        const parentDir = path.dirname(targetPath);
+        try {
+            await fs.promises.access(parentDir);
+        } catch (err) {
+            return res.status(404).json({ error: 'Parent directory does not exist' });
+        }
+        try {
+            await fs.promises.access(targetPath);
+            return res.status(409).json({ error: 'Folder already exists' });
+        } catch (err) {
+            // Folder doesn't exist, which is what we want
+        }
+        try {
+            await fs.promises.mkdir(targetPath, { recursive: false });
+            res.json({ success: true, path: targetPath });
+        } catch (mkdirError) {
+            if (mkdirError.code === 'EEXIST') {
+                return res.status(409).json({ error: 'Folder already exists' });
+            }
+            throw mkdirError;
+        }
+    } catch (error) {
+        console.error('Error creating folder:', error);
+        res.status(500).json({ error: 'Failed to create folder' });
+    }
+});
+
+// Helper function to convert permissions to rwx format
+function permToRwx(perm) {
+    const r = perm & 4 ? 'r' : '-';
+    const w = perm & 2 ? 'w' : '-';
+    const x = perm & 1 ? 'x' : '-';
+    return r + w + x;
+}
+
+async function getFileTree(dirPath, maxDepth = 3, currentDepth = 0, showHidden = true) {
+    // Using fsPromises from import
+    const items = [];
+
+    try {
+        const entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
+
+        for (const entry of entries) {
+            // Debug: log all entries including hidden files
+
+
+            // Skip heavy build directories and VCS directories
+            if (entry.name === 'node_modules' ||
+                entry.name === 'dist' ||
+                entry.name === 'build' ||
+                entry.name === '.git' ||
+                entry.name === '.svn' ||
+                entry.name === '.hg') continue;
+
+            const itemPath = path.join(dirPath, entry.name);
+            const item = {
+                name: entry.name,
+                path: itemPath,
+                type: entry.isDirectory() ? 'directory' : 'file'
+            };
+
+            // Get file stats for additional metadata
+            try {
+                const stats = await fsPromises.stat(itemPath);
+                item.size = stats.size;
+                item.modified = stats.mtime.toISOString();
+
+                // Convert permissions to rwx format
+                const mode = stats.mode;
+                const ownerPerm = (mode >> 6) & 7;
+                const groupPerm = (mode >> 3) & 7;
+                const otherPerm = mode & 7;
+                item.permissions = ((mode >> 6) & 7).toString() + ((mode >> 3) & 7).toString() + (mode & 7).toString();
+                item.permissionsRwx = permToRwx(ownerPerm) + permToRwx(groupPerm) + permToRwx(otherPerm);
+            } catch (statError) {
+                // If stat fails, provide default values
+                item.size = 0;
+                item.modified = null;
+                item.permissions = '000';
+                item.permissionsRwx = '---------';
+            }
+
+            if (entry.isDirectory() && currentDepth < maxDepth) {
+                // Recursively get subdirectories but limit depth
+                try {
+                    // Check if we can access the directory before trying to read it
+                    await fsPromises.access(item.path, fs.constants.R_OK);
+                    item.children = await getFileTree(item.path, maxDepth, currentDepth + 1, showHidden);
+                } catch (e) {
+                    // Silently skip directories we can't access (permission denied, etc.)
+                    item.children = [];
+                }
+            }
+
+            items.push(item);
+        }
+    } catch (error) {
+        // Only log non-permission errors to avoid spam
+        if (error.code !== 'EACCES' && error.code !== 'EPERM') {
+            console.error('Error reading directory:', error);
+        }
+    }
+
+    return items.sort((a, b) => {
+        if (a.type !== b.type) {
+            return a.type === 'directory' ? -1 : 1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+}
+
+export default router;

server/src/modules/projects/projects.routes.js

@@ -0,0 +1,288 @@
+import express from 'express';
+import { promises as fs } from 'fs';
+import path from 'path';
+import spawn from 'cross-spawn';
+import { githubTokensDb } from '@/shared/database/repositories/github-tokens.js';
+import { workspaceOriginalPathsDb } from '@/shared/database/repositories/workspace-original-paths.db.js';
+import { getWorkspaceNameFromPath, validateWorkspacePath } from './projects.utils.js';
+
+const router = express.Router();
+
+function sanitizeGitError(message, token) {
+  if (!message || !token) return message;
+  return message.replace(new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '***');
+}
+
+router.patch('/workspace-name', async (req, res) => {
+  try {
+    const { path: workspacePath, customWorkspaceName } = req.body;
+
+    if (!workspacePath || !String(workspacePath).trim()) {
+      return res.status(400).json({ error: 'path is required' });
+    }
+
+    const normalizedPath = path.resolve(String(workspacePath).trim());
+    const validation = await validateWorkspacePath(normalizedPath);
+    if (!validation.valid) {
+      return res.status(400).json({
+        error: 'Invalid workspace path',
+        details: validation.error,
+      });
+    }
+
+    const safePath = validation.resolvedPath || normalizedPath;
+    const normalizedCustomName =
+      typeof customWorkspaceName === 'string' && customWorkspaceName.trim()
+        ? customWorkspaceName.trim()
+        : null;
+
+    workspaceOriginalPathsDb.updateCustomWorkspaceName(safePath, normalizedCustomName);
+
+    return res.json({
+      success: true,
+      message: 'Workspace name updated successfully',
+    });
+  } catch (error) {
+    console.error('Error updating workspace name:', error);
+    return res.status(500).json({
+      error: 'Failed to update workspace name',
+      details: process.env.NODE_ENV === 'development' ? error.message : undefined,
+    });
+  }
+});
+
+/**
+ * Create or add a workspace
+ * POST /api/projects/create-workspace
+ *
+ * Body:
+ * - path: string (workspace path)
+ */
+router.post('/create-workspace', async (req, res) => {
+  try {
+    const { path: workspacePath } = req.body;
+
+    // Validate required fields
+    if (!workspacePath) {
+      return res.status(400).json({ error: 'path is required' });
+    }
+
+    // Cloning must go through the SSE clone endpoint.
+    if (req.body.githubUrl || req.body.githubTokenId || req.body.newGithubToken) {
+      return res.status(400).json({
+        error: 'Git clone options are not supported on /create-workspace. Use /clone-progress instead.',
+      });
+    }
+
+    // Validate path safety before any operations
+    const validation = await validateWorkspacePath(workspacePath);
+    if (!validation.valid) {
+      return res.status(400).json({
+        error: 'Invalid workspace path',
+        details: validation.error
+      });
+    }
+
+    const absolutePath = validation.resolvedPath;
+
+    // Add existing workspace or create it if it doesn't exist.
+    let workspaceAlreadyExists = false;
+    try {
+      const stats = await fs.stat(absolutePath);
+      if (!stats.isDirectory()) {
+        return res.status(400).json({ error: 'Path exists but is not a directory' });
+      }
+      workspaceAlreadyExists = true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        await fs.mkdir(absolutePath, { recursive: true });
+      } else {
+        throw error;
+      }
+    }
+
+    workspaceOriginalPathsDb.createWorkspacePath(absolutePath, getWorkspaceNameFromPath(absolutePath));
+    return res.json({
+      success: true,
+      message: workspaceAlreadyExists ? 'Workspace added successfully' : 'Workspace created successfully'
+    });
+
+  } catch (error) {
+    console.error('Error creating workspace:', error);
+    res.status(500).json({
+      error: error.message || 'Failed to create workspace',
+      details: process.env.NODE_ENV === 'development' ? error.stack : undefined
+    });
+  }
+});
+
+/**
+ * Helper function to get GitHub token from database
+ */
+async function getGithubTokenById(tokenId, userId) {
+  return githubTokensDb.getGithubTokenById(userId, Number.parseInt(String(tokenId), 10));
+}
+
+/**
+ * Clone repository with progress streaming (SSE)
+ * GET /api/projects/clone-progress
+ */
+router.get('/clone-progress', async (req, res) => {
+  const { path: workspacePath, githubUrl, githubTokenId, newGithubToken } = req.query;
+
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.flushHeaders();
+
+  const sendEvent = (type, data) => {
+    res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
+  };
+
+  try {
+    if (!workspacePath || !githubUrl) {
+      sendEvent('error', { message: 'workspacePath and githubUrl are required' });
+      res.end();
+      return;
+    }
+
+    const validation = await validateWorkspacePath(workspacePath);
+    if (!validation.valid) {
+      sendEvent('error', { message: validation.error });
+      res.end();
+      return;
+    }
+
+    const absolutePath = validation.resolvedPath;
+
+    try {
+      const existingPathStats = await fs.stat(absolutePath);
+      if (!existingPathStats.isDirectory()) {
+        sendEvent('error', { message: 'Path exists but is not a directory' });
+        res.end();
+        return;
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        await fs.mkdir(absolutePath, { recursive: true });
+      } else {
+        throw error;
+      }
+    }
+
+    let githubToken = null;
+    if (githubTokenId) {
+      const token = await getGithubTokenById(parseInt(githubTokenId), req.user.id);
+      if (!token) {
+        sendEvent('error', { message: 'GitHub token not found' });
+        res.end();
+        return;
+      }
+      githubToken = token.github_token;
+    } else if (newGithubToken) {
+      githubToken = newGithubToken;
+    }
+
+    const normalizedUrl = githubUrl.replace(/\/+$/, '').replace(/\.git$/, '');
+    const repoName = normalizedUrl.split('/').pop() || 'repository';
+    const clonePath = path.join(absolutePath, repoName);
+
+    // Check if clone destination already exists to prevent data loss
+    try {
+      await fs.access(clonePath);
+      sendEvent('error', { message: `Directory "${repoName}" already exists. Please choose a different location or remove the existing directory.` });
+      res.end();
+      return;
+    } catch (err) {
+      // Directory doesn't exist, which is what we want
+    }
+
+    let cloneUrl = githubUrl;
+    if (githubToken) {
+      try {
+        const url = new URL(githubUrl);
+        url.username = githubToken;
+        url.password = '';
+        cloneUrl = url.toString();
+      } catch (error) {
+        // SSH URL or invalid - use as-is
+      }
+    }
+
+    sendEvent('progress', { message: `Cloning into '${repoName}'...` });
+
+    const gitProcess = spawn('git', ['clone', '--progress', cloneUrl, clonePath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0'
+      }
+    });
+
+    let lastError = '';
+
+    gitProcess.stdout.on('data', (data) => {
+      const message = data.toString().trim();
+      if (message) {
+        sendEvent('progress', { message });
+      }
+    });
+
+    gitProcess.stderr.on('data', (data) => {
+      const message = data.toString().trim();
+      lastError = message;
+      if (message) {
+        sendEvent('progress', { message });
+      }
+    });
+
+    gitProcess.on('close', async (code) => {
+      if (code === 0) {
+        try {
+          workspaceOriginalPathsDb.createWorkspacePath(clonePath, getWorkspaceNameFromPath(clonePath));
+          sendEvent('complete', { message: 'Repository cloned successfully' });
+        } catch (error) {
+          sendEvent('error', { message: `Clone succeeded but failed to register workspace: ${error.message}` });
+        }
+      } else {
+        const sanitizedError = sanitizeGitError(lastError, githubToken);
+        let errorMessage = 'Git clone failed';
+        if (lastError.includes('Authentication failed') || lastError.includes('could not read Username')) {
+          errorMessage = 'Authentication failed. Please check your credentials.';
+        } else if (lastError.includes('Repository not found')) {
+          errorMessage = 'Repository not found. Please check the URL and ensure you have access.';
+        } else if (lastError.includes('already exists')) {
+          errorMessage = 'Directory already exists';
+        } else if (sanitizedError) {
+          errorMessage = sanitizedError;
+        }
+        try {
+          await fs.rm(clonePath, { recursive: true, force: true });
+        } catch (cleanupError) {
+          console.error('Failed to clean up after clone failure:', sanitizeGitError(cleanupError.message, githubToken));
+        }
+        sendEvent('error', { message: errorMessage });
+      }
+      res.end();
+    });
+
+    gitProcess.on('error', (error) => {
+      if (error.code === 'ENOENT') {
+        sendEvent('error', { message: 'Git is not installed or not in PATH' });
+      } else {
+        sendEvent('error', { message: error.message });
+      }
+      res.end();
+    });
+
+    req.on('close', () => {
+      gitProcess.kill();
+    });
+
+  } catch (error) {
+    sendEvent('error', { message: error.message });
+    res.end();
+  }
+});
+
+export default router;

server/src/modules/projects/projects.utils.ts

@@ -0,0 +1,159 @@
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Configure allowed workspace root (defaults to user's home directory)
+export const WORKSPACES_ROOT = process.env.WORKSPACES_ROOT || os.homedir();
+
+// System-critical paths that should never be used as workspace directories
+export const FORBIDDEN_PATHS = [
+  // Unix
+  '/',
+  '/etc',
+  '/bin',
+  '/sbin',
+  '/usr',
+  '/dev',
+  '/proc',
+  '/sys',
+  '/var',
+  '/boot',
+  '/root',
+  '/lib',
+  '/lib64',
+  '/opt',
+  '/tmp',
+  '/run',
+  // Windows
+  'C:\\Windows',
+  'C:\\Program Files',
+  'C:\\Program Files (x86)',
+  'C:\\ProgramData',
+  'C:\\System Volume Information',
+  'C:\\$Recycle.Bin',
+];
+
+export const getWorkspaceNameFromPath = (workspacePath: string): string => {
+  const trimmed = workspacePath.trim();
+  const normalizedPath = path.normalize(trimmed).replace(/[\\/]+$/, '');
+  const baseName = path.basename(normalizedPath);
+  return baseName || normalizedPath;
+};
+
+/**
+ * Validates that a path is safe for workspace operations.
+ */
+export async function validateWorkspacePath(requestedPath: string): Promise<{
+  valid: boolean;
+  resolvedPath?: string;
+  error?: string;
+}> {
+  try {
+    // Resolve to absolute path
+    const absolutePath = path.resolve(requestedPath);
+
+    // Check if path is a forbidden system directory
+    const normalizedPath = path.normalize(absolutePath);
+    if (FORBIDDEN_PATHS.includes(normalizedPath) || normalizedPath === '/') {
+      return {
+        valid: false,
+        error: 'Cannot use system-critical directories as workspace locations',
+      };
+    }
+
+    // Additional check for paths starting with forbidden directories
+    for (const forbidden of FORBIDDEN_PATHS) {
+      if (normalizedPath === forbidden || normalizedPath.startsWith(forbidden + path.sep)) {
+        // Exception: /var/tmp and similar user-accessible paths might be allowed
+        // but /var itself and most /var subdirectories should be blocked
+        if (
+          forbidden === '/var' &&
+          (normalizedPath.startsWith('/var/tmp') || normalizedPath.startsWith('/var/folders'))
+        ) {
+          continue;
+        }
+
+        return {
+          valid: false,
+          error: `Cannot create workspace in system directory: ${forbidden}`,
+        };
+      }
+    }
+
+    // Try to resolve the real path (following symlinks)
+    let realPath: string;
+    try {
+      // Check if path exists to resolve real path
+      await fs.access(absolutePath);
+      realPath = await fs.realpath(absolutePath);
+    } catch (error: any) {
+      if (error.code === 'ENOENT') {
+        // Path doesn't exist yet - check parent directory
+        const parentPath = path.dirname(absolutePath);
+        try {
+          const parentRealPath = await fs.realpath(parentPath);
+
+          // Reconstruct the full path with real parent
+          realPath = path.join(parentRealPath, path.basename(absolutePath));
+        } catch (parentError: any) {
+          if (parentError.code === 'ENOENT') {
+            // Parent doesn't exist either - use the absolute path as-is
+            // We'll validate it's within allowed root
+            realPath = absolutePath;
+          } else {
+            throw parentError;
+          }
+        }
+      } else {
+        throw error;
+      }
+    }
+
+    // Resolve the workspace root to its real path
+    const resolvedWorkspaceRoot = await fs.realpath(WORKSPACES_ROOT);
+
+    // Ensure the resolved path is contained within the allowed workspace root
+    if (!realPath.startsWith(resolvedWorkspaceRoot + path.sep) && realPath !== resolvedWorkspaceRoot) {
+      return {
+        valid: false,
+        error: `Workspace path must be within the allowed workspace root: ${WORKSPACES_ROOT}`,
+      };
+    }
+
+    // Additional symlink check for existing paths
+    try {
+      await fs.access(absolutePath);
+      const stats = await fs.lstat(absolutePath);
+
+      if (stats.isSymbolicLink()) {
+        // Verify symlink target is also within allowed root
+        const linkTarget = await fs.readlink(absolutePath);
+        const resolvedTarget = path.resolve(path.dirname(absolutePath), linkTarget);
+        const realTarget = await fs.realpath(resolvedTarget);
+
+        if (!realTarget.startsWith(resolvedWorkspaceRoot + path.sep) && realTarget !== resolvedWorkspaceRoot) {
+          return {
+            valid: false,
+            error: 'Symlink target is outside the allowed workspace root',
+          };
+        }
+      }
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      // Path doesn't exist - that's fine for new workspace creation
+    }
+
+    return {
+      valid: true,
+      resolvedPath: realPath,
+    };
+  } catch (error: any) {
+    return {
+      valid: false,
+      error: `Path validation failed: ${error.message}`,
+    };
+  }
+}
+

server/src/modules/push-sub/push-sub.routes.js

@@ -0,0 +1,81 @@
+import express from 'express';
+import { notificationPreferencesDb } from '@/shared/database/repositories/notification-preferences.js';
+import { pushSubscriptionsDb } from '@/shared/database/repositories/push-subscriptions.js';
+import { getPublicKey } from '@/modules/push-sub/push-sub.services.js';
+import { createNotificationEvent, notifyUserIfEnabled } from '@/services/notification-orchestrator.js';
+
+const router = express.Router();
+
+// ===============================
+// Push Subscription Management
+// ===============================
+
+router.get('/vapid-public-key', async (req, res) => {
+  try {
+    const publicKey = getPublicKey();
+    res.json({ publicKey });
+  } catch (error) {
+    console.error('Error fetching VAPID public key:', error);
+    res.status(500).json({ error: 'Failed to fetch VAPID public key' });
+  }
+});
+
+router.post('/subscribe', async (req, res) => {
+  try {
+    const { endpoint, keys } = req.body;
+    if (!endpoint || !keys?.p256dh || !keys?.auth) {
+      return res.status(400).json({ error: 'Missing subscription fields' });
+    }
+    pushSubscriptionsDb.createPushSubscription(req.user.id, endpoint, keys.p256dh, keys.auth);
+
+    // Enable webPush in preferences so the confirmation goes through the full pipeline
+    const currentPrefs = notificationPreferencesDb.getNotificationPreferences(req.user.id);
+    if (!currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updateNotificationPreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs?.channels, webPush: true },
+      });
+    }
+
+    res.json({ success: true });
+
+    // Send a confirmation push through the full notification pipeline
+    const event = createNotificationEvent({
+      provider: 'system',
+      kind: 'info',
+      code: 'push.enabled',
+      meta: { message: 'Push notifications are now enabled!' },
+      severity: 'info'
+    });
+    notifyUserIfEnabled({ userId: req.user.id, event });
+  } catch (error) {
+    console.error('Error saving push subscription:', error);
+    res.status(500).json({ error: 'Failed to save push subscription' });
+  }
+});
+
+router.post('/unsubscribe', async (req, res) => {
+  try {
+    const { endpoint } = req.body;
+    if (!endpoint) {
+      return res.status(400).json({ error: 'Missing endpoint' });
+    }
+    pushSubscriptionsDb.deletePushSubscription(endpoint);
+
+    // Disable webPush in preferences to match subscription state
+    const currentPrefs = notificationPreferencesDb.getNotificationPreferences(req.user.id);
+    if (currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updateNotificationPreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs.channels, webPush: false },
+      });
+    }
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error removing push subscription:', error);
+    res.status(500).json({ error: 'Failed to remove push subscription' });
+  }
+});
+
+export default router;

server/src/modules/push-sub/push-sub.services.ts

@@ -0,0 +1,42 @@
+import webPush from 'web-push';
+
+import { vapidKeysDb } from '@/shared/database/repositories/vapid-keys.js';
+
+type VapidKeyPair = {
+  publicKey: string;
+  privateKey: string;
+};
+
+let cachedKeys: VapidKeyPair | null = null;
+
+function ensureVapidKeys(): VapidKeyPair {
+  if (cachedKeys) return cachedKeys;
+
+  const existingKeys = vapidKeysDb.getVapidKeys();
+  if (existingKeys) {
+    cachedKeys = existingKeys;
+    return existingKeys;
+  }
+
+  const generatedKeys = webPush.generateVAPIDKeys();
+  vapidKeysDb.createVapidKeys(generatedKeys.publicKey, generatedKeys.privateKey);
+  cachedKeys = generatedKeys;
+  return generatedKeys;
+}
+
+function getPublicKey(): string {
+  return ensureVapidKeys().publicKey;
+}
+
+function configureWebPush(): void {
+  const keys = ensureVapidKeys();
+  webPush.setVapidDetails(
+    'mailto:noreply@claudecodeui.local',
+    keys.publicKey,
+    keys.privateKey
+  );
+  console.log('Web Push notifications configured');
+}
+
+export { ensureVapidKeys, getPublicKey, configureWebPush };
+