From 4e2b407d35160b898764a096fa4984fbb022f774 Mon Sep 17 00:00:00 2001
From: Amber Agent <amber@ambient-code.ai>
Date: Fri, 5 Dec 2025 23:57:37 +0000
Subject: [PATCH] feat(frontend): clarify workspace purpose in GUI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add clearer descriptions and help text throughout the UI to explain what
workspaces are and their purpose:

- Updated CreateWorkspaceDialog to explain workspaces are isolated
  environments for managing agentic sessions with their own settings,
  permissions, and resources
- Enhanced projects page header and card descriptions to clarify
  workspaces organize AI-powered agentic sessions
- Improved project details page fallback description
- Added explanatory text to WorkspaceTab clarifying it shows the session's
  working directory with files created/modified by the AI agent
- Enhanced empty state messages to be more descriptive

Fixes #409

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 components/frontend/src/app/projects/[name]/page.tsx         | 2 +-
 components/frontend/src/app/projects/page.tsx                | 5 ++---
 .../frontend/src/components/create-workspace-dialog.tsx      | 2 +-
 components/frontend/src/components/session/WorkspaceTab.tsx  | 5 +++--
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/components/frontend/src/app/projects/[name]/page.tsx b/components/frontend/src/app/projects/[name]/page.tsx
index 2779578dd..5194df718 100644
--- a/components/frontend/src/app/projects/[name]/page.tsx
+++ b/components/frontend/src/app/projects/[name]/page.tsx
@@ -80,7 +80,7 @@ export default function ProjectDetailsPage() {
         <div className="px-6 pt-6 pb-4">
           <PageHeader
             title={project?.displayName || projectName}
-            description={project?.description || 'Workspace details and configuration'}
+            description={project?.description || 'Manage agentic sessions, configure settings, and control access for this workspace'}
           />
         </div>
 
diff --git a/components/frontend/src/app/projects/page.tsx b/components/frontend/src/app/projects/page.tsx
index 56687e094..717f4447d 100644
--- a/components/frontend/src/app/projects/page.tsx
+++ b/components/frontend/src/app/projects/page.tsx
@@ -143,7 +143,7 @@ export default function ProjectsPage() {
         <div className="container mx-auto px-6 py-4">
           <PageHeader
             title="Workspaces"
-            description="Select or create a workspace to get started"
+            description="Workspaces are isolated environments for organizing AI-powered agentic sessions. Create a workspace to get started."
           />
         </div>
       </div>
@@ -164,8 +164,7 @@ export default function ProjectsPage() {
               <div>
                 <CardTitle>Workspaces</CardTitle>
                 <CardDescription>
-                  Configure and manage workspace settings, resource limits, and access
-                  controls
+                  Each workspace provides an isolated environment for your team to run agentic sessions, manage API keys, and control access permissions
                 </CardDescription>
               </div>
               <div className="flex gap-2">
diff --git a/components/frontend/src/components/create-workspace-dialog.tsx b/components/frontend/src/components/create-workspace-dialog.tsx
index 7db3cf35b..c71e20aa4 100644
--- a/components/frontend/src/components/create-workspace-dialog.tsx
+++ b/components/frontend/src/components/create-workspace-dialog.tsx
@@ -167,7 +167,7 @@ export function CreateWorkspaceDialog({
         <DialogHeader className="space-y-3">
           <DialogTitle>Create New Workspace</DialogTitle>
           <DialogDescription>
-            Set up a new workspace for your team
+            A workspace is an isolated environment where your team can create and manage AI-powered agentic sessions. Each workspace has its own settings, permissions, and resources.
           </DialogDescription>
         </DialogHeader>
 
diff --git a/components/frontend/src/components/session/WorkspaceTab.tsx b/components/frontend/src/components/session/WorkspaceTab.tsx
index 2bef267e4..c5546103f 100644
--- a/components/frontend/src/components/session/WorkspaceTab.tsx
+++ b/components/frontend/src/components/session/WorkspaceTab.tsx
@@ -71,7 +71,8 @@ const WorkspaceTab: React.FC<WorkspaceTabProps> = ({ session, wsLoading, wsUnava
     <div className="grid grid-cols-1 gap-0">
       <div className="border rounded-md overflow-hidden">
         <div className="p-3 border-b flex items-center justify-between">
-          <div className="flex-1">
+          <div className="flex-1 space-y-1">
+            <p className="text-xs text-muted-foreground">Session working directory - files created and modified by the AI agent</p>
             {k8sResources?.pvcName ? (
               <div className="flex items-center gap-2">
                 <Badge variant="outline" className="text-xs">
@@ -99,7 +100,7 @@ const WorkspaceTab: React.FC<WorkspaceTabProps> = ({ session, wsLoading, wsUnava
             <EmptyState
               icon={FolderOpen}
               title="No files yet"
-              description="The workspace is empty. Files will appear here as the session progresses."
+              description="This session's working directory is empty. Files will appear here as the AI agent clones repositories and creates or modifies files."
             />
           ) : (
             <FileTree nodes={wsTree} selectedPath={wsSelectedPath} onSelect={onSelect} onToggle={onToggle} />