From 9209a1eaa57ad0af93b21c67e959e9d0b6c9c077 Mon Sep 17 00:00:00 2001
From: DevMando <codefilez@gmail.com>
Date: Tue, 3 Nov 2026 22:47:32 -0800
Subject: [PATCH] chore: organize CLI components into feature folders

---
 README.md                                     |  4 ++--
 docs/CHANGELOG.md                             |  4 ++++
 docs/cli-maintainability.md                   |  4 ++--
 .../{ => Activity}/AgentStatus.razor          |  1 +
 .../{ => Activity}/CommandPreviewView.razor   |  1 +
 .../{ => Activity}/MusicStatus.razor          |  1 +
 .../{ => Activity}/OperationDisplay.razor     |  1 +
 .../{ => Activity}/PlanStepEditor.razor       |  1 +
 .../Components/{ => Activity}/StatusBar.razor |  1 +
 .../{ => Conversation}/ChatMessage.razor      |  1 +
 .../{ => Conversation}/ContextMeterLine.razor |  1 +
 .../ConversationEntry.razor                   |  1 +
 .../ConversationTranscript.razor              |  1 +
 .../{ => Conversation}/ConversationView.razor |  1 +
 .../RenderableContent.razor                   |  1 +
 .../{ => Conversation}/ScrollPreview.razor    |  1 +
 .../{ => Conversation}/UserPrompt.razor       |  1 +
 .../{ => Input}/ApprovalSelect.razor          |  1 +
 .../{ => Input}/AutocompletePopup.razor       |  1 +
 .../{ => Input}/CommandSuggestionRow.razor    |  1 +
 .../{ => Input}/FileSuggestionRow.razor       |  1 +
 .../{ => Input}/ModelPickerPopup.razor        |  1 +
 .../Components/{ => Input}/Prompt.razor       |  1 +
 .../Components/{ => Input}/PromptInput.razor  |  1 +
 .../{ => Onboarding}/OllamaPullPanel.razor    |  1 +
 .../{ => Onboarding}/SetupWizardPanel.razor   |  1 +
 .../{ => Project}/AgentFileExplorer.razor     |  1 +
 .../{ => Project}/AgentGitChanges.razor       |  1 +
 .../{ => Project}/DirectoryBrowser.razor      |  1 +
 src/MandoCode/Components/README.md            | 21 +++++++++++++++++++
 .../{ => Sessions}/AgentHistoryBrowser.razor  |  1 +
 .../AgentHistoryConversation.razor            |  1 +
 .../ContextSnapshotsPanel.razor               |  1 +
 .../{ => Settings}/AgentSettingsPanel.razor   |  1 +
 .../{ => Settings}/ConfigMenu.razor           |  1 +
 .../IntegrationSettingsPanel.razor            |  1 +
 .../{ => Settings}/McpToolsViewer.razor       |  1 +
 .../Components/{ => Shell}/App.Attachments.cs |  0
 .../Components/{ => Shell}/App.Commands.cs    |  0
 .../{ => Shell}/App.Integrations.cs           |  0
 .../Components/{ => Shell}/App.Lifecycle.cs   |  0
 .../Components/{ => Shell}/App.Planning.cs    |  0
 .../Components/{ => Shell}/App.Requests.cs    |  0
 .../{ => Shell}/App.TerminalEffects.cs        |  0
 .../Components/{ => Shell}/App.razor          |  1 +
 .../Components/{ => Shell}/AsciiArt.razor     |  1 +
 .../Components/{ => Shell}/Banner.razor       |  1 +
 .../Components/{ => Shell}/ChatShell.razor    |  1 +
 .../Components/{ => Shell}/HelpDisplay.razor  |  1 +
 .../Components/{ => Shell}/HomeView.razor     |  1 +
 .../{ => Workspaces}/AgentGridRow.razor       |  1 +
 .../{ => Workspaces}/AgentGridSlot.razor      |  1 +
 .../{ => Workspaces}/AgentNavigationBar.razor |  1 +
 .../{ => Workspaces}/AgentPaneContent.razor   |  1 +
 .../{ => Workspaces}/AgentWorkspaceView.razor |  1 +
 .../TerminalWorkspaceView.razor               |  1 +
 .../{ => Workspaces}/WorkspaceButton.razor    |  1 +
 .../{ => Workspaces}/WorkspacePicker.razor    |  1 +
 .../{ => Workspaces}/WorkspaceSurface.razor   |  1 +
 .../{ => Workspaces}/WorkspaceTab.razor       |  1 +
 60 files changed, 78 insertions(+), 4 deletions(-)
 rename src/MandoCode/Components/{ => Activity}/AgentStatus.razor (98%)
 rename src/MandoCode/Components/{ => Activity}/CommandPreviewView.razor (98%)
 rename src/MandoCode/Components/{ => Activity}/MusicStatus.razor (95%)
 rename src/MandoCode/Components/{ => Activity}/OperationDisplay.razor (94%)
 rename src/MandoCode/Components/{ => Activity}/PlanStepEditor.razor (99%)
 rename src/MandoCode/Components/{ => Activity}/StatusBar.razor (95%)
 rename src/MandoCode/Components/{ => Conversation}/ChatMessage.razor (92%)
 rename src/MandoCode/Components/{ => Conversation}/ContextMeterLine.razor (98%)
 rename src/MandoCode/Components/{ => Conversation}/ConversationEntry.razor (95%)
 rename src/MandoCode/Components/{ => Conversation}/ConversationTranscript.razor (98%)
 rename src/MandoCode/Components/{ => Conversation}/ConversationView.razor (99%)
 rename src/MandoCode/Components/{ => Conversation}/RenderableContent.razor (96%)
 rename src/MandoCode/Components/{ => Conversation}/ScrollPreview.razor (98%)
 rename src/MandoCode/Components/{ => Conversation}/UserPrompt.razor (91%)
 rename src/MandoCode/Components/{ => Input}/ApprovalSelect.razor (99%)
 rename src/MandoCode/Components/{ => Input}/AutocompletePopup.razor (99%)
 rename src/MandoCode/Components/{ => Input}/CommandSuggestionRow.razor (98%)
 rename src/MandoCode/Components/{ => Input}/FileSuggestionRow.razor (98%)
 rename src/MandoCode/Components/{ => Input}/ModelPickerPopup.razor (97%)
 rename src/MandoCode/Components/{ => Input}/Prompt.razor (94%)
 rename src/MandoCode/Components/{ => Input}/PromptInput.razor (99%)
 rename src/MandoCode/Components/{ => Onboarding}/OllamaPullPanel.razor (99%)
 rename src/MandoCode/Components/{ => Onboarding}/SetupWizardPanel.razor (99%)
 rename src/MandoCode/Components/{ => Project}/AgentFileExplorer.razor (99%)
 rename src/MandoCode/Components/{ => Project}/AgentGitChanges.razor (99%)
 rename src/MandoCode/Components/{ => Project}/DirectoryBrowser.razor (99%)
 create mode 100644 src/MandoCode/Components/README.md
 rename src/MandoCode/Components/{ => Sessions}/AgentHistoryBrowser.razor (99%)
 rename src/MandoCode/Components/{ => Sessions}/AgentHistoryConversation.razor (99%)
 rename src/MandoCode/Components/{ => Sessions}/ContextSnapshotsPanel.razor (99%)
 rename src/MandoCode/Components/{ => Settings}/AgentSettingsPanel.razor (99%)
 rename src/MandoCode/Components/{ => Settings}/ConfigMenu.razor (98%)
 rename src/MandoCode/Components/{ => Settings}/IntegrationSettingsPanel.razor (99%)
 rename src/MandoCode/Components/{ => Settings}/McpToolsViewer.razor (98%)
 rename src/MandoCode/Components/{ => Shell}/App.Attachments.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.Commands.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.Integrations.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.Lifecycle.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.Planning.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.Requests.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.TerminalEffects.cs (100%)
 rename src/MandoCode/Components/{ => Shell}/App.razor (99%)
 rename src/MandoCode/Components/{ => Shell}/AsciiArt.razor (93%)
 rename src/MandoCode/Components/{ => Shell}/Banner.razor (99%)
 rename src/MandoCode/Components/{ => Shell}/ChatShell.razor (99%)
 rename src/MandoCode/Components/{ => Shell}/HelpDisplay.razor (98%)
 rename src/MandoCode/Components/{ => Shell}/HomeView.razor (98%)
 rename src/MandoCode/Components/{ => Workspaces}/AgentGridRow.razor (97%)
 rename src/MandoCode/Components/{ => Workspaces}/AgentGridSlot.razor (96%)
 rename src/MandoCode/Components/{ => Workspaces}/AgentNavigationBar.razor (99%)
 rename src/MandoCode/Components/{ => Workspaces}/AgentPaneContent.razor (99%)
 rename src/MandoCode/Components/{ => Workspaces}/AgentWorkspaceView.razor (98%)
 rename src/MandoCode/Components/{ => Workspaces}/TerminalWorkspaceView.razor (99%)
 rename src/MandoCode/Components/{ => Workspaces}/WorkspaceButton.razor (98%)
 rename src/MandoCode/Components/{ => Workspaces}/WorkspacePicker.razor (99%)
 rename src/MandoCode/Components/{ => Workspaces}/WorkspaceSurface.razor (95%)
 rename src/MandoCode/Components/{ => Workspaces}/WorkspaceTab.razor (96%)

diff --git a/README.md b/README.md
index a2e79ad..b39c9a7 100644
--- a/README.md
+++ b/README.md
@@ -632,7 +632,7 @@ Type `@` anywhere in your input (after a space or at position 0) to trigger file
 
 ```
 explain @src/MandoCode/Services/AIService.cs to me
-what does the ProcessFileReferences method do in @src/MandoCode/Components/App.razor
+what does the ProcessFileReferences method do in @src/MandoCode/Components/Shell/App.razor
 refactor @src/MandoCode/Models/LoadingMessages.cs to use fewer spinners
 ```
 
@@ -892,7 +892,7 @@ This simulation replaces the package update command, verifies the helper waits f
 
 ```
 src/MandoCode/
-  Components/        Razor UI (App, Banner, HelpDisplay, ConfigMenu, Prompt)
+  Components/        Razor UI grouped by feature (see Components/README.md)
   Services/          Core logic (AI, markdown, syntax, tokens, music, diffs, input state machine)
   Models/            Data models, config, system prompts, educational content
   Plugins/           Tool classes bound as AIFunctions (FileSystem, WebSearch, Planning, Skills)
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 513b93e..566b026 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to MandoCode will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+
+- Group CLI components into feature folders for shell, workspaces, conversations, input, project browsing, sessions, settings, onboarding, and activity. Keep component namespaces and behavior unchanged, and document where new components belong.
+
 ## [0.16.1] - 2026-10-21
 
 **Startup and component stability.** The chat prompt now waits for model validation and MCP initialization to finish. Prompt state changes run together on the UI dispatcher, and agents closed during startup cannot start an input loop afterward. RazorConsole remains at 0.6.0.
diff --git a/docs/cli-maintainability.md b/docs/cli-maintainability.md
index 3f97621..60b23be 100644
--- a/docs/cli-maintainability.md
+++ b/docs/cli-maintainability.md
@@ -1,6 +1,6 @@
 # CLI maintenance boundaries
 
-The CLI is composed from Razor components. `App.razor` retains layout and coordinating state; its partial class files group commands, planning, attachments, integrations, request processing, lifecycle, and terminal effects. Partial files share component state and are not independent services. Extract reusable operations into services rather than adding unrelated responsibilities to these files.
+The CLI is composed from Razor components grouped by feature under `src/MandoCode/Components/`; see the [component folder guide](../src/MandoCode/Components/README.md). Explicit `@namespace MandoCode.Components` declarations preserve component type names after moving files. `Components/Shell/App.razor` retains layout and coordinating state; its partial class files group commands, planning, attachments, integrations, request processing, lifecycle, and terminal effects. Partial files share component state and are not independent services. Extract reusable operations into services rather than adding unrelated responsibilities to these files.
 
 ## State and input
 
@@ -10,7 +10,7 @@ The CLI is composed from Razor components. `App.razor` retains layout and coordi
 
 ## Agent lifetime
 
-`App.Lifecycle.cs` resolves per-agent services from the pane scope, subscribes to events, and releases pending requests on shutdown. `CallbackRegistrations` releases a callback only if it is still owned by that registration. Event delegates must also be detached on disposal. Shared workspace services are resolved from the host; cross-agent operations resolve the target agent's scope.
+`Components/Shell/App.Lifecycle.cs` resolves per-agent services from the pane scope, subscribes to events, and releases pending requests on shutdown. `CallbackRegistrations` releases a callback only if it is still owned by that registration. Event delegates must also be detached on disposal. Shared workspace services are resolved from the host; cross-agent operations resolve the target agent's scope.
 
 ## Shared engine
 
diff --git a/src/MandoCode/Components/AgentStatus.razor b/src/MandoCode/Components/Activity/AgentStatus.razor
similarity index 98%
rename from src/MandoCode/Components/AgentStatus.razor
rename to src/MandoCode/Components/Activity/AgentStatus.razor
index ca663be..3d9ac02 100644
--- a/src/MandoCode/Components/AgentStatus.razor
+++ b/src/MandoCode/Components/Activity/AgentStatus.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using System.Text
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
diff --git a/src/MandoCode/Components/CommandPreviewView.razor b/src/MandoCode/Components/Activity/CommandPreviewView.razor
similarity index 98%
rename from src/MandoCode/Components/CommandPreviewView.razor
rename to src/MandoCode/Components/Activity/CommandPreviewView.razor
index d8e347c..916eac7 100644
--- a/src/MandoCode/Components/CommandPreviewView.razor
+++ b/src/MandoCode/Components/Activity/CommandPreviewView.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 <Panel Border="BoxBorder.Rounded" BorderColor="@(new Color(86, 182, 194))" Expand="true" Title="@Preview.Shell">
     <Rows>
diff --git a/src/MandoCode/Components/MusicStatus.razor b/src/MandoCode/Components/Activity/MusicStatus.razor
similarity index 95%
rename from src/MandoCode/Components/MusicStatus.razor
rename to src/MandoCode/Components/Activity/MusicStatus.razor
index 682783c..3360c87 100644
--- a/src/MandoCode/Components/MusicStatus.razor
+++ b/src/MandoCode/Components/Activity/MusicStatus.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Services
 @using MandoCode.Translators
 
diff --git a/src/MandoCode/Components/OperationDisplay.razor b/src/MandoCode/Components/Activity/OperationDisplay.razor
similarity index 94%
rename from src/MandoCode/Components/OperationDisplay.razor
rename to src/MandoCode/Components/Activity/OperationDisplay.razor
index 84abf2a..fcd7208 100644
--- a/src/MandoCode/Components/OperationDisplay.razor
+++ b/src/MandoCode/Components/Activity/OperationDisplay.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Models
 @using MandoCode.Services
 @using MandoCode.Translators
diff --git a/src/MandoCode/Components/PlanStepEditor.razor b/src/MandoCode/Components/Activity/PlanStepEditor.razor
similarity index 99%
rename from src/MandoCode/Components/PlanStepEditor.razor
rename to src/MandoCode/Components/Activity/PlanStepEditor.razor
index 519e252..a774649 100644
--- a/src/MandoCode/Components/PlanStepEditor.razor
+++ b/src/MandoCode/Components/Activity/PlanStepEditor.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Input
 @using RazorConsole.Core.Focus
 @using RazorConsole.Core.Rendering
diff --git a/src/MandoCode/Components/StatusBar.razor b/src/MandoCode/Components/Activity/StatusBar.razor
similarity index 95%
rename from src/MandoCode/Components/StatusBar.razor
rename to src/MandoCode/Components/Activity/StatusBar.razor
index eaf8b0e..93b8e64 100644
--- a/src/MandoCode/Components/StatusBar.razor
+++ b/src/MandoCode/Components/Activity/StatusBar.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Services
 
 @if (!string.IsNullOrEmpty(_display))
diff --git a/src/MandoCode/Components/ChatMessage.razor b/src/MandoCode/Components/Conversation/ChatMessage.razor
similarity index 92%
rename from src/MandoCode/Components/ChatMessage.razor
rename to src/MandoCode/Components/Conversation/ChatMessage.razor
index 2113066..5c7d9cd 100644
--- a/src/MandoCode/Components/ChatMessage.razor
+++ b/src/MandoCode/Components/Conversation/ChatMessage.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Models
 
 @foreach (var opAnsi in Message.OperationAnsi)
diff --git a/src/MandoCode/Components/ContextMeterLine.razor b/src/MandoCode/Components/Conversation/ContextMeterLine.razor
similarity index 98%
rename from src/MandoCode/Components/ContextMeterLine.razor
rename to src/MandoCode/Components/Conversation/ContextMeterLine.razor
index 4c5e329..1d8efb1 100644
--- a/src/MandoCode/Components/ContextMeterLine.razor
+++ b/src/MandoCode/Components/Conversation/ContextMeterLine.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Components
 @using MandoCode.Services
diff --git a/src/MandoCode/Components/ConversationEntry.razor b/src/MandoCode/Components/Conversation/ConversationEntry.razor
similarity index 95%
rename from src/MandoCode/Components/ConversationEntry.razor
rename to src/MandoCode/Components/Conversation/ConversationEntry.razor
index d26a35f..1054cac 100644
--- a/src/MandoCode/Components/ConversationEntry.razor
+++ b/src/MandoCode/Components/Conversation/ConversationEntry.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @* data-canvas opts into the widget pipeline's Spectre fallback; our middleware
    supplies the cached rich renderable, including code blocks and tool results. *@
 @if (Entry.Command is { } command)
diff --git a/src/MandoCode/Components/ConversationTranscript.razor b/src/MandoCode/Components/Conversation/ConversationTranscript.razor
similarity index 98%
rename from src/MandoCode/Components/ConversationTranscript.razor
rename to src/MandoCode/Components/Conversation/ConversationTranscript.razor
index 6938cbc..0ea44d6 100644
--- a/src/MandoCode/Components/ConversationTranscript.razor
+++ b/src/MandoCode/Components/Conversation/ConversationTranscript.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @foreach (var entry in Entries)
 {
     <Rows @key="entry.Id">
diff --git a/src/MandoCode/Components/ConversationView.razor b/src/MandoCode/Components/Conversation/ConversationView.razor
similarity index 99%
rename from src/MandoCode/Components/ConversationView.razor
rename to src/MandoCode/Components/Conversation/ConversationView.razor
index 52fb9a7..4222505 100644
--- a/src/MandoCode/Components/ConversationView.razor
+++ b/src/MandoCode/Components/Conversation/ConversationView.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Rendering
 @inject ScrollableLayoutCoordinator LayoutCoordinator
 @inject RazorConsole.Core.Focus.FocusManager Focus
diff --git a/src/MandoCode/Components/RenderableContent.razor b/src/MandoCode/Components/Conversation/RenderableContent.razor
similarity index 96%
rename from src/MandoCode/Components/RenderableContent.razor
rename to src/MandoCode/Components/Conversation/RenderableContent.razor
index b6a56eb..2fd7b41 100644
--- a/src/MandoCode/Components/RenderableContent.razor
+++ b/src/MandoCode/Components/Conversation/RenderableContent.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console.Rendering
 @inject IServiceProvider Services
 @implements IDisposable
diff --git a/src/MandoCode/Components/ScrollPreview.razor b/src/MandoCode/Components/Conversation/ScrollPreview.razor
similarity index 98%
rename from src/MandoCode/Components/ScrollPreview.razor
rename to src/MandoCode/Components/Conversation/ScrollPreview.razor
index b219c7f..43b2d13 100644
--- a/src/MandoCode/Components/ScrollPreview.razor
+++ b/src/MandoCode/Components/Conversation/ScrollPreview.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Components
 @using MandoCode.Services
diff --git a/src/MandoCode/Components/UserPrompt.razor b/src/MandoCode/Components/Conversation/UserPrompt.razor
similarity index 91%
rename from src/MandoCode/Components/UserPrompt.razor
rename to src/MandoCode/Components/Conversation/UserPrompt.razor
index 7efa795..add3625 100644
--- a/src/MandoCode/Components/UserPrompt.razor
+++ b/src/MandoCode/Components/Conversation/UserPrompt.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @* A submitted prompt is a stable transcript child, independent of the live composer. *@
 <Rows>
     <Box FillWidth="true">
diff --git a/src/MandoCode/Components/ApprovalSelect.razor b/src/MandoCode/Components/Input/ApprovalSelect.razor
similarity index 99%
rename from src/MandoCode/Components/ApprovalSelect.razor
rename to src/MandoCode/Components/Input/ApprovalSelect.razor
index 5f2cb88..f7227c8 100644
--- a/src/MandoCode/Components/ApprovalSelect.razor
+++ b/src/MandoCode/Components/Input/ApprovalSelect.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Microsoft.AspNetCore.Components.Web
 @using Spectre.Console
 @using RazorConsole.Components
diff --git a/src/MandoCode/Components/AutocompletePopup.razor b/src/MandoCode/Components/Input/AutocompletePopup.razor
similarity index 99%
rename from src/MandoCode/Components/AutocompletePopup.razor
rename to src/MandoCode/Components/Input/AutocompletePopup.razor
index 0d6ece4..94b242d 100644
--- a/src/MandoCode/Components/AutocompletePopup.razor
+++ b/src/MandoCode/Components/Input/AutocompletePopup.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
 
diff --git a/src/MandoCode/Components/CommandSuggestionRow.razor b/src/MandoCode/Components/Input/CommandSuggestionRow.razor
similarity index 98%
rename from src/MandoCode/Components/CommandSuggestionRow.razor
rename to src/MandoCode/Components/Input/CommandSuggestionRow.razor
index 94b275d..51370a1 100644
--- a/src/MandoCode/Components/CommandSuggestionRow.razor
+++ b/src/MandoCode/Components/Input/CommandSuggestionRow.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
diff --git a/src/MandoCode/Components/FileSuggestionRow.razor b/src/MandoCode/Components/Input/FileSuggestionRow.razor
similarity index 98%
rename from src/MandoCode/Components/FileSuggestionRow.razor
rename to src/MandoCode/Components/Input/FileSuggestionRow.razor
index 5fec777..62c7d66 100644
--- a/src/MandoCode/Components/FileSuggestionRow.razor
+++ b/src/MandoCode/Components/Input/FileSuggestionRow.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
diff --git a/src/MandoCode/Components/ModelPickerPopup.razor b/src/MandoCode/Components/Input/ModelPickerPopup.razor
similarity index 97%
rename from src/MandoCode/Components/ModelPickerPopup.razor
rename to src/MandoCode/Components/Input/ModelPickerPopup.razor
index 4336cf9..aa29be3 100644
--- a/src/MandoCode/Components/ModelPickerPopup.razor
+++ b/src/MandoCode/Components/Input/ModelPickerPopup.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
 
diff --git a/src/MandoCode/Components/Prompt.razor b/src/MandoCode/Components/Input/Prompt.razor
similarity index 94%
rename from src/MandoCode/Components/Prompt.razor
rename to src/MandoCode/Components/Input/Prompt.razor
index 5d3bdfc..5eef754 100644
--- a/src/MandoCode/Components/Prompt.razor
+++ b/src/MandoCode/Components/Input/Prompt.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 
 @code {
diff --git a/src/MandoCode/Components/PromptInput.razor b/src/MandoCode/Components/Input/PromptInput.razor
similarity index 99%
rename from src/MandoCode/Components/PromptInput.razor
rename to src/MandoCode/Components/Input/PromptInput.razor
index 31c39bd..e4dc31b 100644
--- a/src/MandoCode/Components/PromptInput.razor
+++ b/src/MandoCode/Components/Input/PromptInput.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @inject IServiceProvider Services
 @using MandoCode.Models
 @using MandoCode.Services
diff --git a/src/MandoCode/Components/OllamaPullPanel.razor b/src/MandoCode/Components/Onboarding/OllamaPullPanel.razor
similarity index 99%
rename from src/MandoCode/Components/OllamaPullPanel.razor
rename to src/MandoCode/Components/Onboarding/OllamaPullPanel.razor
index 9f4185a..0213923 100644
--- a/src/MandoCode/Components/OllamaPullPanel.razor
+++ b/src/MandoCode/Components/Onboarding/OllamaPullPanel.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @using RazorConsole.Core.Input
diff --git a/src/MandoCode/Components/SetupWizardPanel.razor b/src/MandoCode/Components/Onboarding/SetupWizardPanel.razor
similarity index 99%
rename from src/MandoCode/Components/SetupWizardPanel.razor
rename to src/MandoCode/Components/Onboarding/SetupWizardPanel.razor
index 51ca67f..31e79b9 100644
--- a/src/MandoCode/Components/SetupWizardPanel.razor
+++ b/src/MandoCode/Components/Onboarding/SetupWizardPanel.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Input
 @inject RazorConsole.Core.Focus.FocusManager Focus
diff --git a/src/MandoCode/Components/AgentFileExplorer.razor b/src/MandoCode/Components/Project/AgentFileExplorer.razor
similarity index 99%
rename from src/MandoCode/Components/AgentFileExplorer.razor
rename to src/MandoCode/Components/Project/AgentFileExplorer.razor
index 99e8a7f..39bb33e 100644
--- a/src/MandoCode/Components/AgentFileExplorer.razor
+++ b/src/MandoCode/Components/Project/AgentFileExplorer.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using System.Diagnostics
 @inject RazorConsole.Core.Focus.FocusManager Focus
diff --git a/src/MandoCode/Components/AgentGitChanges.razor b/src/MandoCode/Components/Project/AgentGitChanges.razor
similarity index 99%
rename from src/MandoCode/Components/AgentGitChanges.razor
rename to src/MandoCode/Components/Project/AgentGitChanges.razor
index 27122ae..fa14a61 100644
--- a/src/MandoCode/Components/AgentGitChanges.razor
+++ b/src/MandoCode/Components/Project/AgentGitChanges.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @inject RazorConsole.Core.Focus.FocusManager Focus
diff --git a/src/MandoCode/Components/DirectoryBrowser.razor b/src/MandoCode/Components/Project/DirectoryBrowser.razor
similarity index 99%
rename from src/MandoCode/Components/DirectoryBrowser.razor
rename to src/MandoCode/Components/Project/DirectoryBrowser.razor
index aeafb35..88c2797 100644
--- a/src/MandoCode/Components/DirectoryBrowser.razor
+++ b/src/MandoCode/Components/Project/DirectoryBrowser.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @inject RazorConsole.Core.Focus.FocusManager Focus
 
diff --git a/src/MandoCode/Components/README.md b/src/MandoCode/Components/README.md
new file mode 100644
index 0000000..3a69522
--- /dev/null
+++ b/src/MandoCode/Components/README.md
@@ -0,0 +1,21 @@
+# CLI components
+
+Components are grouped by the feature they render:
+
+| Folder | Responsibility |
+| --- | --- |
+| Shell | Application coordination, main chat shell, home screen, and help |
+| Workspaces | Workspace tabs, picker, agent pane headers, and grid layout |
+| Conversation | Transcript entries, messages, previews, and context meter |
+| Input | Prompt input, autocomplete suggestions, model picker, and approval selection |
+| Project | File explorer, Git changes, and directory browser |
+| Sessions | Saved-agent history and context snapshots |
+| Settings | Agent configuration, integrations, and MCP tools |
+| Onboarding | Setup wizard and model downloads |
+| Activity | Agent/command status, operation previews, music, and plan-step editing |
+
+Each Razor component explicitly declares `@namespace MandoCode.Components`.
+This matches the feature-folder convention used by Services: folders organize
+source without changing public type names or component references. Keep all
+`App` partial files together in Shell so their shared lifecycle state stays visible.
+Shared Razor imports remain in `src/MandoCode/_Imports.razor`.
diff --git a/src/MandoCode/Components/AgentHistoryBrowser.razor b/src/MandoCode/Components/Sessions/AgentHistoryBrowser.razor
similarity index 99%
rename from src/MandoCode/Components/AgentHistoryBrowser.razor
rename to src/MandoCode/Components/Sessions/AgentHistoryBrowser.razor
index 548e623..f9bef88 100644
--- a/src/MandoCode/Components/AgentHistoryBrowser.razor
+++ b/src/MandoCode/Components/Sessions/AgentHistoryBrowser.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using Microsoft.Extensions.DependencyInjection
 @using Microsoft.AspNetCore.Components.Web
diff --git a/src/MandoCode/Components/AgentHistoryConversation.razor b/src/MandoCode/Components/Sessions/AgentHistoryConversation.razor
similarity index 99%
rename from src/MandoCode/Components/AgentHistoryConversation.razor
rename to src/MandoCode/Components/Sessions/AgentHistoryConversation.razor
index 0c666f2..c2611bd 100644
--- a/src/MandoCode/Components/AgentHistoryConversation.razor
+++ b/src/MandoCode/Components/Sessions/AgentHistoryConversation.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @using RazorConsole.Core.Rendering
diff --git a/src/MandoCode/Components/ContextSnapshotsPanel.razor b/src/MandoCode/Components/Sessions/ContextSnapshotsPanel.razor
similarity index 99%
rename from src/MandoCode/Components/ContextSnapshotsPanel.razor
rename to src/MandoCode/Components/Sessions/ContextSnapshotsPanel.razor
index b536295..2cf32b8 100644
--- a/src/MandoCode/Components/ContextSnapshotsPanel.razor
+++ b/src/MandoCode/Components/Sessions/ContextSnapshotsPanel.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using RazorConsole.Core.Input
 @using Spectre.Console
diff --git a/src/MandoCode/Components/AgentSettingsPanel.razor b/src/MandoCode/Components/Settings/AgentSettingsPanel.razor
similarity index 99%
rename from src/MandoCode/Components/AgentSettingsPanel.razor
rename to src/MandoCode/Components/Settings/AgentSettingsPanel.razor
index 5c1476d..4b03fae 100644
--- a/src/MandoCode/Components/AgentSettingsPanel.razor
+++ b/src/MandoCode/Components/Settings/AgentSettingsPanel.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Models
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
diff --git a/src/MandoCode/Components/ConfigMenu.razor b/src/MandoCode/Components/Settings/ConfigMenu.razor
similarity index 98%
rename from src/MandoCode/Components/ConfigMenu.razor
rename to src/MandoCode/Components/Settings/ConfigMenu.razor
index 1f791aa..99d5f4b 100644
--- a/src/MandoCode/Components/ConfigMenu.razor
+++ b/src/MandoCode/Components/Settings/ConfigMenu.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Models
 @using MandoCode.Services
 @using Spectre.Console
diff --git a/src/MandoCode/Components/IntegrationSettingsPanel.razor b/src/MandoCode/Components/Settings/IntegrationSettingsPanel.razor
similarity index 99%
rename from src/MandoCode/Components/IntegrationSettingsPanel.razor
rename to src/MandoCode/Components/Settings/IntegrationSettingsPanel.razor
index aa8d9d0..bd2ab86 100644
--- a/src/MandoCode/Components/IntegrationSettingsPanel.razor
+++ b/src/MandoCode/Components/Settings/IntegrationSettingsPanel.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Models
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
diff --git a/src/MandoCode/Components/McpToolsViewer.razor b/src/MandoCode/Components/Settings/McpToolsViewer.razor
similarity index 98%
rename from src/MandoCode/Components/McpToolsViewer.razor
rename to src/MandoCode/Components/Settings/McpToolsViewer.razor
index 582dba5..c323872 100644
--- a/src/MandoCode/Components/McpToolsViewer.razor
+++ b/src/MandoCode/Components/Settings/McpToolsViewer.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @inject RazorConsole.Core.Focus.FocusManager Focus
diff --git a/src/MandoCode/Components/App.Attachments.cs b/src/MandoCode/Components/Shell/App.Attachments.cs
similarity index 100%
rename from src/MandoCode/Components/App.Attachments.cs
rename to src/MandoCode/Components/Shell/App.Attachments.cs
diff --git a/src/MandoCode/Components/App.Commands.cs b/src/MandoCode/Components/Shell/App.Commands.cs
similarity index 100%
rename from src/MandoCode/Components/App.Commands.cs
rename to src/MandoCode/Components/Shell/App.Commands.cs
diff --git a/src/MandoCode/Components/App.Integrations.cs b/src/MandoCode/Components/Shell/App.Integrations.cs
similarity index 100%
rename from src/MandoCode/Components/App.Integrations.cs
rename to src/MandoCode/Components/Shell/App.Integrations.cs
diff --git a/src/MandoCode/Components/App.Lifecycle.cs b/src/MandoCode/Components/Shell/App.Lifecycle.cs
similarity index 100%
rename from src/MandoCode/Components/App.Lifecycle.cs
rename to src/MandoCode/Components/Shell/App.Lifecycle.cs
diff --git a/src/MandoCode/Components/App.Planning.cs b/src/MandoCode/Components/Shell/App.Planning.cs
similarity index 100%
rename from src/MandoCode/Components/App.Planning.cs
rename to src/MandoCode/Components/Shell/App.Planning.cs
diff --git a/src/MandoCode/Components/App.Requests.cs b/src/MandoCode/Components/Shell/App.Requests.cs
similarity index 100%
rename from src/MandoCode/Components/App.Requests.cs
rename to src/MandoCode/Components/Shell/App.Requests.cs
diff --git a/src/MandoCode/Components/App.TerminalEffects.cs b/src/MandoCode/Components/Shell/App.TerminalEffects.cs
similarity index 100%
rename from src/MandoCode/Components/App.TerminalEffects.cs
rename to src/MandoCode/Components/Shell/App.TerminalEffects.cs
diff --git a/src/MandoCode/Components/App.razor b/src/MandoCode/Components/Shell/App.razor
similarity index 99%
rename from src/MandoCode/Components/App.razor
rename to src/MandoCode/Components/Shell/App.razor
index cc901cf..670c166 100644
--- a/src/MandoCode/Components/App.razor
+++ b/src/MandoCode/Components/Shell/App.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @inject IServiceProvider Services
 @using Microsoft.Extensions.DependencyInjection
 @using MandoCode.Models
diff --git a/src/MandoCode/Components/AsciiArt.razor b/src/MandoCode/Components/Shell/AsciiArt.razor
similarity index 93%
rename from src/MandoCode/Components/AsciiArt.razor
rename to src/MandoCode/Components/Shell/AsciiArt.razor
index 007aa39..b316973 100644
--- a/src/MandoCode/Components/AsciiArt.razor
+++ b/src/MandoCode/Components/Shell/AsciiArt.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using MandoCode.Services
 
 <RenderableContent Content="@PaneColors.Render(_art, Pane, constrainWidth: false)" />
diff --git a/src/MandoCode/Components/Banner.razor b/src/MandoCode/Components/Shell/Banner.razor
similarity index 99%
rename from src/MandoCode/Components/Banner.razor
rename to src/MandoCode/Components/Shell/Banner.razor
index fec975c..3ba4526 100644
--- a/src/MandoCode/Components/Banner.razor
+++ b/src/MandoCode/Components/Shell/Banner.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console;
 
 <AsciiArt Lines="@Artwork" />
diff --git a/src/MandoCode/Components/ChatShell.razor b/src/MandoCode/Components/Shell/ChatShell.razor
similarity index 99%
rename from src/MandoCode/Components/ChatShell.razor
rename to src/MandoCode/Components/Shell/ChatShell.razor
index dd359e5..6f12299 100644
--- a/src/MandoCode/Components/ChatShell.razor
+++ b/src/MandoCode/Components/Shell/ChatShell.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @inject RazorConsole.Core.Rendering.ITerminalViewport Viewport
diff --git a/src/MandoCode/Components/HelpDisplay.razor b/src/MandoCode/Components/Shell/HelpDisplay.razor
similarity index 98%
rename from src/MandoCode/Components/HelpDisplay.razor
rename to src/MandoCode/Components/Shell/HelpDisplay.razor
index 870637d..7651637 100644
--- a/src/MandoCode/Components/HelpDisplay.razor
+++ b/src/MandoCode/Components/Shell/HelpDisplay.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 
 @*
diff --git a/src/MandoCode/Components/HomeView.razor b/src/MandoCode/Components/Shell/HomeView.razor
similarity index 98%
rename from src/MandoCode/Components/HomeView.razor
rename to src/MandoCode/Components/Shell/HomeView.razor
index d8ab660..6ff2c36 100644
--- a/src/MandoCode/Components/HomeView.razor
+++ b/src/MandoCode/Components/Shell/HomeView.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 
diff --git a/src/MandoCode/Components/AgentGridRow.razor b/src/MandoCode/Components/Workspaces/AgentGridRow.razor
similarity index 97%
rename from src/MandoCode/Components/AgentGridRow.razor
rename to src/MandoCode/Components/Workspaces/AgentGridRow.razor
index fe3bf58..a77d743 100644
--- a/src/MandoCode/Components/AgentGridRow.razor
+++ b/src/MandoCode/Components/Workspaces/AgentGridRow.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 
 @if (Workspace.Panes.Any(p => AgentWorkspace.Column(p.Slot) == Row))
diff --git a/src/MandoCode/Components/AgentGridSlot.razor b/src/MandoCode/Components/Workspaces/AgentGridSlot.razor
similarity index 96%
rename from src/MandoCode/Components/AgentGridSlot.razor
rename to src/MandoCode/Components/Workspaces/AgentGridSlot.razor
index 3415b17..1c9694d 100644
--- a/src/MandoCode/Components/AgentGridSlot.razor
+++ b/src/MandoCode/Components/Workspaces/AgentGridSlot.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 
 @if (Pane is not null)
diff --git a/src/MandoCode/Components/AgentNavigationBar.razor b/src/MandoCode/Components/Workspaces/AgentNavigationBar.razor
similarity index 99%
rename from src/MandoCode/Components/AgentNavigationBar.razor
rename to src/MandoCode/Components/Workspaces/AgentNavigationBar.razor
index e266c42..6278e76 100644
--- a/src/MandoCode/Components/AgentNavigationBar.razor
+++ b/src/MandoCode/Components/Workspaces/AgentNavigationBar.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @inject WorkspaceRegistry Registry
diff --git a/src/MandoCode/Components/AgentPaneContent.razor b/src/MandoCode/Components/Workspaces/AgentPaneContent.razor
similarity index 99%
rename from src/MandoCode/Components/AgentPaneContent.razor
rename to src/MandoCode/Components/Workspaces/AgentPaneContent.razor
index a607194..75bd229 100644
--- a/src/MandoCode/Components/AgentPaneContent.razor
+++ b/src/MandoCode/Components/Workspaces/AgentPaneContent.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @using Microsoft.Extensions.DependencyInjection
diff --git a/src/MandoCode/Components/AgentWorkspaceView.razor b/src/MandoCode/Components/Workspaces/AgentWorkspaceView.razor
similarity index 98%
rename from src/MandoCode/Components/AgentWorkspaceView.razor
rename to src/MandoCode/Components/Workspaces/AgentWorkspaceView.razor
index a4d8946..518c88d 100644
--- a/src/MandoCode/Components/AgentWorkspaceView.razor
+++ b/src/MandoCode/Components/Workspaces/AgentWorkspaceView.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @inject AgentWorkspace DefaultWorkspace
diff --git a/src/MandoCode/Components/TerminalWorkspaceView.razor b/src/MandoCode/Components/Workspaces/TerminalWorkspaceView.razor
similarity index 99%
rename from src/MandoCode/Components/TerminalWorkspaceView.razor
rename to src/MandoCode/Components/Workspaces/TerminalWorkspaceView.razor
index f5fa04e..161af07 100644
--- a/src/MandoCode/Components/TerminalWorkspaceView.razor
+++ b/src/MandoCode/Components/Workspaces/TerminalWorkspaceView.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Renderables
 @using Spectre.Console
 @using Microsoft.Extensions.DependencyInjection
diff --git a/src/MandoCode/Components/WorkspaceButton.razor b/src/MandoCode/Components/Workspaces/WorkspaceButton.razor
similarity index 98%
rename from src/MandoCode/Components/WorkspaceButton.razor
rename to src/MandoCode/Components/Workspaces/WorkspaceButton.razor
index 26f95cc..8fdc06e 100644
--- a/src/MandoCode/Components/WorkspaceButton.razor
+++ b/src/MandoCode/Components/Workspaces/WorkspaceButton.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @using RazorConsole.Core.Renderables
 @inject WorkspaceRegistry Registry
diff --git a/src/MandoCode/Components/WorkspacePicker.razor b/src/MandoCode/Components/Workspaces/WorkspacePicker.razor
similarity index 99%
rename from src/MandoCode/Components/WorkspacePicker.razor
rename to src/MandoCode/Components/Workspaces/WorkspacePicker.razor
index 732e6fc..9eba11d 100644
--- a/src/MandoCode/Components/WorkspacePicker.razor
+++ b/src/MandoCode/Components/Workspaces/WorkspacePicker.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using RazorConsole.Core.Input
 @using Spectre.Console
 @inject WorkspaceRegistry Registry
diff --git a/src/MandoCode/Components/WorkspaceSurface.razor b/src/MandoCode/Components/Workspaces/WorkspaceSurface.razor
similarity index 95%
rename from src/MandoCode/Components/WorkspaceSurface.razor
rename to src/MandoCode/Components/Workspaces/WorkspaceSurface.razor
index 45d6e88..b9d425b 100644
--- a/src/MandoCode/Components/WorkspaceSurface.razor
+++ b/src/MandoCode/Components/Workspaces/WorkspaceSurface.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @if (!Workspace.IsClosed)
 {
     @* grid selects the renderer's Spectre fallback, which emits zero cells when hidden. *@
diff --git a/src/MandoCode/Components/WorkspaceTab.razor b/src/MandoCode/Components/Workspaces/WorkspaceTab.razor
similarity index 96%
rename from src/MandoCode/Components/WorkspaceTab.razor
rename to src/MandoCode/Components/Workspaces/WorkspaceTab.razor
index 1a11ed0..0d34167 100644
--- a/src/MandoCode/Components/WorkspaceTab.razor
+++ b/src/MandoCode/Components/Workspaces/WorkspaceTab.razor
@@ -1,3 +1,4 @@
+@namespace MandoCode.Components
 @using Spectre.Console
 @inject WorkspaceRegistry Registry