feat: redesign dashboard with sidebar layout and table components

- Add new Table UI component with rich features (sorting, empty states, interactive rows)
- Create DashboardLayout component with sidebar navigation
- Redesign Agents page with table layout showing provider, tools, and actions
- Redesign Collections page with table layout showing visibility and tool counts
- Add surface-secondary color token for proper dark mode support
- Add home and user icons to icon library
- Fix missing foreground-quaternary with muted color

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

Co-Authored-By: Claude <noreply@anthropic.com>

apps/web/src/app/dashboard/agents/page.tsx

@@ -1,12 +1,22 @@
 'use client';
 
 import type { AIProvider } from '@tpmjs/types/agent';
+import { Badge } from '@tpmjs/ui/Badge/Badge';
 import { Button } from '@tpmjs/ui/Button/Button';
 import { Icon } from '@tpmjs/ui/Icon/Icon';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableEmpty,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@tpmjs/ui/Table/Table';
 import Link from 'next/link';
 import { useRouter } from 'next/navigation';
 import { useCallback, useEffect, useState } from 'react';
-import { AppHeader } from '~/components/AppHeader';
+import { DashboardLayout } from '~/components/dashboard/DashboardLayout';
 
 interface Agent {
   id: string;
@@ -29,6 +39,23 @@ const PROVIDER_DISPLAY_NAMES: Record<AIProvider, string> = {
   MISTRAL: 'Mistral',
 };
 
+const PROVIDER_COLORS: Record<AIProvider, 'default' | 'secondary' | 'outline'> = {
+  OPENAI: 'default',
+  ANTHROPIC: 'secondary',
+  GOOGLE: 'outline',
+  GROQ: 'outline',
+  MISTRAL: 'outline',
+};
+
+function formatDate(dateString: string): string {
+  const date = new Date(dateString);
+  return date.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
 export default function AgentsPage(): React.ReactElement {
   const router = useRouter();
   const [agents, setAgents] = useState<Agent[]>([]);
@@ -62,7 +89,8 @@ export default function AgentsPage(): React.ReactElement {
     fetchAgents();
   }, [fetchAgents]);
 
-  const handleDelete = async (id: string) => {
+  const handleDelete = async (id: string, e: React.MouseEvent) => {
+    e.stopPropagation();
     if (!confirm('Are you sure you want to delete this agent? This action cannot be undone.')) {
       return;
     }
@@ -88,144 +116,172 @@ export default function AgentsPage(): React.ReactElement {
     }
   };
 
-  if (isLoading) {
-    return (
-      <div className="min-h-screen bg-background">
-        <AppHeader />
-        <div className="max-w-6xl mx-auto py-12 px-4">
-          <div className="animate-pulse">
-            <div className="h-8 bg-surface-secondary rounded w-48 mb-8" />
-            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-              {[1, 2, 3].map((i) => (
-                <div key={i} className="h-48 bg-surface-secondary rounded-lg" />
-              ))}
-            </div>
-          </div>
-        </div>
-      </div>
-    );
-  }
-
   if (error) {
     return (
-      <div className="min-h-screen bg-background">
-        <AppHeader />
-        <div className="max-w-6xl mx-auto py-12 px-4">
-          <div className="text-center py-16">
-            <Icon icon="alertCircle" size="lg" className="mx-auto text-error mb-4" />
-            <h2 className="text-lg font-medium text-foreground mb-2">Error</h2>
-            <p className="text-foreground-secondary mb-4">{error}</p>
-            <Button onClick={fetchAgents}>Try Again</Button>
-          </div>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div className="min-h-screen bg-background">
-      <AppHeader />
-      <div className="max-w-6xl mx-auto py-12 px-4">
-        {/* Header */}
-        <div className="flex items-center justify-between mb-8">
-          <div className="flex items-center gap-4">
-            <Link
-              href="/dashboard"
-              className="text-foreground-secondary hover:text-foreground transition-colors"
-            >
-              <Icon icon="arrowLeft" size="sm" />
-            </Link>
-            <h1 className="text-2xl font-bold text-foreground">My Agents</h1>
-          </div>
+      <DashboardLayout
+        title="Agents"
+        actions={
           <Link href="/dashboard/agents/new">
             <Button>
               <Icon icon="plus" size="sm" className="mr-2" />
               New Agent
             </Button>
           </Link>
+        }
+      >
+        <div className="text-center py-16">
+          <Icon icon="alertCircle" size="lg" className="mx-auto text-error mb-4" />
+          <h2 className="text-lg font-medium text-foreground mb-2">Error</h2>
+          <p className="text-foreground-secondary mb-4">{error}</p>
+          <Button onClick={fetchAgents}>Try Again</Button>
         </div>
+      </DashboardLayout>
+    );
+  }
 
-        {/* Empty State */}
-        {agents.length === 0 && (
-          <div className="text-center py-16 bg-background border border-border rounded-lg">
-            <div className="w-16 h-16 rounded-full bg-primary/10 flex items-center justify-center mx-auto mb-4">
-              <Icon icon="terminal" size="lg" className="text-primary" />
-            </div>
-            <h2 className="text-lg font-medium text-foreground mb-2">No agents yet</h2>
-            <p className="text-foreground-secondary mb-6 max-w-md mx-auto">
-              Create your first AI agent to start chatting with tools. Agents can use any tools from
-              your collections or individual tools.
-            </p>
-            <Link href="/dashboard/agents/new">
-              <Button>
-                <Icon icon="plus" size="sm" className="mr-2" />
-                Create Your First Agent
-              </Button>
-            </Link>
-          </div>
-        )}
-
-        {/* Agents Grid */}
-        {agents.length > 0 && (
-          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-            {agents.map((agent) => (
-              <div
-                key={agent.id}
-                className="bg-background border border-border rounded-lg p-6 hover:border-foreground/20 transition-colors group"
-              >
-                <div className="flex items-start justify-between mb-4">
-                  <div className="flex items-center gap-3">
-                    <div className="w-10 h-10 rounded-lg bg-primary/10 flex items-center justify-center">
-                      <Icon icon="terminal" size="sm" className="text-primary" />
-                    </div>
-                    <div>
-                      <h3 className="font-medium text-foreground">{agent.name}</h3>
-                      <p className="text-xs text-foreground-tertiary">
-                        {PROVIDER_DISPLAY_NAMES[agent.provider]} / {agent.modelId}
-                      </p>
-                    </div>
+  return (
+    <DashboardLayout
+      title="Agents"
+      subtitle={
+        agents.length > 0 ? `${agents.length} agent${agents.length !== 1 ? 's' : ''}` : undefined
+      }
+      actions={
+        <Link href="/dashboard/agents/new">
+          <Button>
+            <Icon icon="plus" size="sm" className="mr-2" />
+            New Agent
+          </Button>
+        </Link>
+      }
+    >
+      <div className="bg-background border border-border rounded-lg overflow-hidden">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-[300px]">Name</TableHead>
+              <TableHead>Provider</TableHead>
+              <TableHead>Tools</TableHead>
+              <TableHead>Updated</TableHead>
+              <TableHead className="w-[140px] text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              // Loading skeleton
+              <>
+                {[0, 1, 2].map((idx) => (
+                  <TableRow key={`agent-skeleton-${idx}`}>
+                    <TableCell>
+                      <div className="flex items-center gap-3">
+                        <div className="w-8 h-8 rounded-lg bg-surface-secondary animate-pulse" />
+                        <div className="space-y-1.5">
+                          <div className="h-4 w-32 bg-surface-secondary rounded animate-pulse" />
+                          <div className="h-3 w-48 bg-surface-secondary rounded animate-pulse" />
+                        </div>
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-5 w-20 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-4 w-12 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-4 w-24 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-8 w-24 bg-surface-secondary rounded animate-pulse ml-auto" />
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </>
+            ) : agents.length === 0 ? (
+              <TableEmpty
+                colSpan={5}
+                icon={
+                  <div className="w-16 h-16 rounded-full bg-primary/10 flex items-center justify-center">
+                    <Icon icon="terminal" size="lg" className="text-primary" />
                   </div>
-                </div>
-
-                {agent.description && (
-                  <p className="text-sm text-foreground-secondary mb-4 line-clamp-2">
-                    {agent.description}
-                  </p>
-                )}
-
-                <div className="flex items-center gap-4 text-sm text-foreground-tertiary mb-4">
-                  <span className="flex items-center gap-1">
-                    <Icon icon="puzzle" size="xs" />
-                    {agent.toolCount + agent.collectionCount * 5} tools
-                  </span>
-                </div>
-
-                <div className="flex items-center gap-2 pt-4 border-t border-border">
-                  <Link href={`/dashboard/agents/${agent.id}/chat`} className="flex-1">
-                    <Button size="sm" className="w-full">
-                      <Icon icon="message" size="xs" className="mr-1" />
-                      Chat
+                }
+                title="No agents yet"
+                description="Create your first AI agent to start chatting with tools. Agents can use any tools from your collections or individual tools."
+                action={
+                  <Link href="/dashboard/agents/new">
+                    <Button>
+                      <Icon icon="plus" size="sm" className="mr-2" />
+                      Create Your First Agent
                     </Button>
                   </Link>
-                  <Link href={`/dashboard/agents/${agent.id}`}>
-                    <Button size="sm" variant="secondary">
-                      <Icon icon="edit" size="xs" />
-                    </Button>
-                  </Link>
-                  <Button
-                    size="sm"
-                    variant="outline"
-                    onClick={() => handleDelete(agent.id)}
-                    disabled={deletingId === agent.id}
-                  >
-                    <Icon icon="trash" size="xs" />
-                  </Button>
-                </div>
-              </div>
-            ))}
-          </div>
-        )}
+                }
+              />
+            ) : (
+              agents.map((agent) => (
+                <TableRow
+                  key={agent.id}
+                  interactive
+                  onClick={() => router.push(`/dashboard/agents/${agent.id}`)}
+                  className="cursor-pointer"
+                >
+                  <TableCell>
+                    <div className="flex items-center gap-3">
+                      <div className="w-8 h-8 rounded-lg bg-primary/10 flex items-center justify-center flex-shrink-0">
+                        <Icon icon="terminal" size="sm" className="text-primary" />
+                      </div>
+                      <div className="min-w-0">
+                        <p className="font-medium text-foreground truncate">{agent.name}</p>
+                        {agent.description && (
+                          <p className="text-sm text-foreground-tertiary truncate max-w-[250px]">
+                            {agent.description}
+                          </p>
+                        )}
+                      </div>
+                    </div>
+                  </TableCell>
+                  <TableCell>
+                    <div className="flex items-center gap-2">
+                      <Badge variant={PROVIDER_COLORS[agent.provider]} size="sm">
+                        {PROVIDER_DISPLAY_NAMES[agent.provider]}
+                      </Badge>
+                      <span className="text-xs text-foreground-tertiary">{agent.modelId}</span>
+                    </div>
+                  </TableCell>
+                  <TableCell>
+                    <span className="text-foreground-secondary">
+                      {agent.toolCount + agent.collectionCount * 5}
+                    </span>
+                  </TableCell>
+                  <TableCell>
+                    <span className="text-foreground-secondary text-sm">
+                      {formatDate(agent.updatedAt)}
+                    </span>
+                  </TableCell>
+                  <TableCell>
+                    <div className="flex items-center justify-end gap-1">
+                      <Link
+                        href={`/dashboard/agents/${agent.id}/chat`}
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        <Button size="sm" variant="default">
+                          <Icon icon="message" size="xs" className="mr-1" />
+                          Chat
+                        </Button>
+                      </Link>
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        onClick={(e) => handleDelete(agent.id, e)}
+                        disabled={deletingId === agent.id}
+                      >
+                        <Icon icon="trash" size="xs" />
+                      </Button>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
       </div>
-    </div>
+    </DashboardLayout>
   );
 }

apps/web/src/app/dashboard/collections/page.tsx

@@ -1,13 +1,21 @@
 'use client';
 
+import { Badge } from '@tpmjs/ui/Badge/Badge';
 import { Button } from '@tpmjs/ui/Button/Button';
 import { Icon } from '@tpmjs/ui/Icon/Icon';
-import Link from 'next/link';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableEmpty,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@tpmjs/ui/Table/Table';
 import { useRouter } from 'next/navigation';
 import { useCallback, useEffect, useState } from 'react';
-import { AppHeader } from '~/components/AppHeader';
 import { CollectionForm } from '~/components/collections/CollectionForm';
-import { CollectionList } from '~/components/collections/CollectionList';
+import { DashboardLayout } from '~/components/dashboard/DashboardLayout';
 
 interface Collection {
   id: string;
@@ -18,6 +26,15 @@ interface Collection {
   updatedAt: string;
 }
 
+function formatDate(dateString: string): string {
+  const date = new Date(dateString);
+  return date.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
 export default function CollectionsPage(): React.ReactElement {
   const router = useRouter();
   const [collections, setCollections] = useState<Collection[]>([]);
@@ -79,7 +96,8 @@ export default function CollectionsPage(): React.ReactElement {
     }
   };
 
-  const handleDelete = async (id: string) => {
+  const handleDelete = async (id: string, e: React.MouseEvent) => {
+    e.stopPropagation();
     if (
       !confirm('Are you sure you want to delete this collection? This action cannot be undone.')
     ) {
@@ -108,79 +126,170 @@ export default function CollectionsPage(): React.ReactElement {
     }
   };
 
-  if (isLoading) {
-    return (
-      <div className="min-h-screen bg-background">
-        <AppHeader />
-        <div className="max-w-6xl mx-auto py-12 px-4">
-          <div className="animate-pulse">
-            <div className="h-8 bg-surface-secondary rounded w-48 mb-8" />
-            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-              {[1, 2, 3].map((i) => (
-                <div key={i} className="h-48 bg-surface-secondary rounded-lg" />
-              ))}
-            </div>
-          </div>
-        </div>
-      </div>
-    );
-  }
-
   if (error) {
     return (
-      <div className="min-h-screen bg-background">
-        <AppHeader />
-        <div className="max-w-6xl mx-auto py-12 px-4">
-          <div className="text-center py-16">
-            <Icon icon="alertCircle" size="lg" className="mx-auto text-error mb-4" />
-            <h2 className="text-lg font-medium text-foreground mb-2">Error</h2>
-            <p className="text-foreground-secondary mb-4">{error}</p>
-            <Button onClick={fetchCollections}>Try Again</Button>
-          </div>
+      <DashboardLayout
+        title="Collections"
+        actions={
+          <Button onClick={() => setShowCreateForm(true)}>
+            <Icon icon="plus" size="sm" className="mr-2" />
+            New Collection
+          </Button>
+        }
+      >
+        <div className="text-center py-16">
+          <Icon icon="alertCircle" size="lg" className="mx-auto text-error mb-4" />
+          <h2 className="text-lg font-medium text-foreground mb-2">Error</h2>
+          <p className="text-foreground-secondary mb-4">{error}</p>
+          <Button onClick={fetchCollections}>Try Again</Button>
         </div>
-      </div>
+      </DashboardLayout>
     );
   }
 
   return (
-    <div className="min-h-screen bg-background">
-      <AppHeader />
-      <div className="max-w-6xl mx-auto py-12 px-4">
-        {/* Header */}
-        <div className="flex items-center justify-between mb-8">
-          <div className="flex items-center gap-4">
-            <Link
-              href="/dashboard"
-              className="text-foreground-secondary hover:text-foreground transition-colors"
-            >
-              <Icon icon="arrowLeft" size="sm" />
-            </Link>
-            <h1 className="text-2xl font-bold text-foreground">My Collections</h1>
-          </div>
-          {!showCreateForm && (
-            <Button onClick={() => setShowCreateForm(true)}>
-              <Icon icon="plus" size="sm" className="mr-2" />
-              New Collection
-            </Button>
-          )}
+    <DashboardLayout
+      title="Collections"
+      subtitle={
+        collections.length > 0
+          ? `${collections.length} collection${collections.length !== 1 ? 's' : ''}`
+          : undefined
+      }
+      actions={
+        !showCreateForm && (
+          <Button onClick={() => setShowCreateForm(true)}>
+            <Icon icon="plus" size="sm" className="mr-2" />
+            New Collection
+          </Button>
+        )
+      }
+    >
+      {/* Create Form */}
+      {showCreateForm && (
+        <div className="bg-background border border-border rounded-lg p-6 mb-6">
+          <h2 className="text-lg font-medium text-foreground mb-4">Create New Collection</h2>
+          <CollectionForm
+            onSubmit={handleCreate}
+            onCancel={() => setShowCreateForm(false)}
+            isSubmitting={isCreating}
+            submitLabel="Create Collection"
+          />
         </div>
+      )}
 
-        {/* Create Form */}
-        {showCreateForm && (
-          <div className="bg-background border border-border rounded-lg p-6 mb-8">
-            <h2 className="text-lg font-medium text-foreground mb-4">Create New Collection</h2>
-            <CollectionForm
-              onSubmit={handleCreate}
-              onCancel={() => setShowCreateForm(false)}
-              isSubmitting={isCreating}
-              submitLabel="Create Collection"
-            />
-          </div>
-        )}
-
-        {/* Collections List */}
-        <CollectionList collections={collections} onDelete={handleDelete} deletingId={deletingId} />
+      {/* Collections Table */}
+      <div className="bg-background border border-border rounded-lg overflow-hidden">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-[350px]">Name</TableHead>
+              <TableHead>Tools</TableHead>
+              <TableHead>Visibility</TableHead>
+              <TableHead>Updated</TableHead>
+              <TableHead className="w-[100px] text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              // Loading skeleton
+              <>
+                {[0, 1, 2].map((idx) => (
+                  <TableRow key={`collection-skeleton-${idx}`}>
+                    <TableCell>
+                      <div className="flex items-center gap-3">
+                        <div className="w-8 h-8 rounded-lg bg-surface-secondary animate-pulse" />
+                        <div className="space-y-1.5">
+                          <div className="h-4 w-32 bg-surface-secondary rounded animate-pulse" />
+                          <div className="h-3 w-48 bg-surface-secondary rounded animate-pulse" />
+                        </div>
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-4 w-12 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-5 w-16 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-4 w-24 bg-surface-secondary rounded animate-pulse" />
+                    </TableCell>
+                    <TableCell>
+                      <div className="h-8 w-8 bg-surface-secondary rounded animate-pulse ml-auto" />
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </>
+            ) : collections.length === 0 ? (
+              <TableEmpty
+                colSpan={5}
+                icon={
+                  <div className="w-16 h-16 rounded-full bg-primary/10 flex items-center justify-center">
+                    <Icon icon="folder" size="lg" className="text-primary" />
+                  </div>
+                }
+                title="No collections yet"
+                description="Create a collection to organize your tools. Collections make it easy to group related tools together and share them with your agents."
+                action={
+                  <Button onClick={() => setShowCreateForm(true)}>
+                    <Icon icon="plus" size="sm" className="mr-2" />
+                    Create Your First Collection
+                  </Button>
+                }
+              />
+            ) : (
+              collections.map((collection) => (
+                <TableRow
+                  key={collection.id}
+                  interactive
+                  onClick={() => router.push(`/dashboard/collections/${collection.id}`)}
+                  className="cursor-pointer"
+                >
+                  <TableCell>
+                    <div className="flex items-center gap-3">
+                      <div className="w-8 h-8 rounded-lg bg-primary/10 flex items-center justify-center flex-shrink-0">
+                        <Icon icon="folder" size="sm" className="text-primary" />
+                      </div>
+                      <div className="min-w-0">
+                        <p className="font-medium text-foreground truncate">{collection.name}</p>
+                        {collection.description && (
+                          <p className="text-sm text-foreground-tertiary truncate max-w-[280px]">
+                            {collection.description}
+                          </p>
+                        )}
+                      </div>
+                    </div>
+                  </TableCell>
+                  <TableCell>
+                    <span className="text-foreground-secondary">{collection.toolCount}</span>
+                  </TableCell>
+                  <TableCell>
+                    <Badge variant={collection.isPublic ? 'default' : 'outline'} size="sm">
+                      {collection.isPublic ? 'Public' : 'Private'}
+                    </Badge>
+                  </TableCell>
+                  <TableCell>
+                    <span className="text-foreground-secondary text-sm">
+                      {formatDate(collection.updatedAt)}
+                    </span>
+                  </TableCell>
+                  <TableCell>
+                    <div className="flex items-center justify-end">
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        onClick={(e) => handleDelete(collection.id, e)}
+                        disabled={deletingId === collection.id}
+                      >
+                        <Icon icon="trash" size="xs" />
+                      </Button>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
       </div>
-    </div>
+    </DashboardLayout>
   );
 }

apps/web/src/app/globals.css

@@ -8,6 +8,7 @@
     /* Backgrounds & Surfaces - DRAMATIC CONTRAST */
     --background: 220 15% 96%; /* Light blue-gray background */
     --surface: 0 0% 100%; /* Pure white - cards really pop! */
+    --surface-secondary: 220 15% 94%; /* Subtle gray for secondary surfaces */
     --surface-elevated: 0 0% 100%; /* White (elevated) */
     --surface-overlay: 0 0% 100%; /* White overlays */
 
@@ -103,6 +104,7 @@
     /* Backgrounds & Surfaces */
     --background: 210 10% 5%; /* #0d0d0f - Almost black */
     --surface: 210 10% 8%; /* #14141a - Slightly lighter */
+    --surface-secondary: 210 10% 10%; /* Secondary surfaces */
     --surface-elevated: 210 10% 12%; /* #1c1c24 - Cards, modals */
     --surface-overlay: 210 10% 16%; /* #25252f - Overlays, popovers */
 

apps/web/src/app/tool/tool-search/page.tsx

@@ -369,7 +369,7 @@ export default function ToolSearchPage(): React.ReactElement {
               <CardContent className="pt-6 pb-6 text-center space-y-6">
                 {/* Icon/Visual Element */}
                 <div className="flex justify-center">
-                  <div className="w-16 h-16 rounded-full bg-foreground-quaternary/50 flex items-center justify-center">
+                  <div className="w-16 h-16 rounded-full bg-muted flex items-center justify-center">
                     <Icon icon="x" size="lg" className="text-foreground-tertiary" />
                   </div>
                 </div>

apps/web/src/components/dashboard/DashboardLayout.tsx

@@ -0,0 +1,206 @@
+'use client';
+
+import { useSession } from '@/lib/auth-client';
+import { Button } from '@tpmjs/ui/Button/Button';
+import { Icon, type IconName } from '@tpmjs/ui/Icon/Icon';
+import Link from 'next/link';
+import { usePathname, useRouter } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { AppHeader } from '../AppHeader';
+
+interface NavItem {
+  href: string;
+  label: string;
+  icon: IconName;
+  badge?: number;
+}
+
+const navItems: NavItem[] = [
+  { href: '/dashboard', label: 'Overview', icon: 'home' },
+  { href: '/dashboard/agents', label: 'Agents', icon: 'terminal' },
+  { href: '/dashboard/collections', label: 'Collections', icon: 'folder' },
+  { href: '/dashboard/settings/api-keys', label: 'API Keys', icon: 'key' },
+];
+
+interface DashboardLayoutProps {
+  children: React.ReactNode;
+  /** Title displayed in the header */
+  title: string;
+  /** Optional subtitle/description */
+  subtitle?: string;
+  /** Action buttons for the header */
+  actions?: React.ReactNode;
+  /** Whether to show back button */
+  showBackButton?: boolean;
+  /** Custom back URL (defaults to parent route) */
+  backUrl?: string;
+}
+
+export function DashboardLayout({
+  children,
+  title,
+  subtitle,
+  actions,
+  showBackButton,
+  backUrl,
+}: DashboardLayoutProps): React.ReactElement {
+  const pathname = usePathname();
+  const router = useRouter();
+  const { data: session, isPending } = useSession();
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  // Redirect to sign-in if not authenticated
+  useEffect(() => {
+    if (!isPending && !session) {
+      router.push('/sign-in');
+    }
+  }, [isPending, session, router]);
+
+  // Close sidebar on route change - pathname dependency triggers this effect
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname triggers effect
+  useEffect(() => {
+    setSidebarOpen(false);
+  }, [pathname]);
+
+  const isActive = (href: string) => {
+    if (href === '/dashboard') {
+      return pathname === '/dashboard';
+    }
+    return pathname.startsWith(href);
+  };
+
+  const getBackUrl = () => {
+    if (backUrl) return backUrl;
+    // Get parent route
+    const parts = pathname.split('/').filter(Boolean);
+    parts.pop();
+    return parts.length > 0 ? `/${parts.join('/')}` : '/dashboard';
+  };
+
+  if (isPending) {
+    return (
+      <div className="min-h-screen bg-background">
+        <AppHeader />
+        <div className="flex items-center justify-center h-[calc(100vh-64px)]">
+          <div className="animate-pulse text-foreground-secondary">Loading...</div>
+        </div>
+      </div>
+    );
+  }
+
+  if (!session) {
+    return <div />;
+  }
+
+  return (
+    <div className="min-h-screen bg-background">
+      <AppHeader />
+
+      <div className="flex">
+        {/* Mobile sidebar backdrop */}
+        {sidebarOpen && (
+          <button
+            type="button"
+            className="fixed inset-0 bg-black/50 z-40 lg:hidden cursor-default"
+            onClick={() => setSidebarOpen(false)}
+            aria-label="Close sidebar"
+          />
+        )}
+
+        {/* Sidebar */}
+        <aside
+          className={`
+            fixed lg:sticky top-16 left-0 z-50 lg:z-0
+            w-64 h-[calc(100vh-64px)] bg-background border-r border-border
+            transform transition-transform lg:transform-none
+            ${sidebarOpen ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'}
+          `}
+        >
+          <nav className="p-4 space-y-1">
+            {navItems.map((item) => (
+              <Link
+                key={item.href}
+                href={item.href}
+                className={`
+                  flex items-center gap-3 px-3 py-2 rounded-lg text-sm font-medium transition-colors
+                  ${
+                    isActive(item.href)
+                      ? 'bg-primary/10 text-primary'
+                      : 'text-foreground-secondary hover:text-foreground hover:bg-surface'
+                  }
+                `}
+              >
+                <Icon icon={item.icon} size="sm" />
+                <span>{item.label}</span>
+                {item.badge !== undefined && item.badge > 0 && (
+                  <span className="ml-auto text-xs bg-surface-secondary px-1.5 py-0.5 rounded-full">
+                    {item.badge}
+                  </span>
+                )}
+              </Link>
+            ))}
+          </nav>
+
+          {/* User section at bottom */}
+          <div className="absolute bottom-0 left-0 right-0 p-4 border-t border-border">
+            <div className="flex items-center gap-3">
+              <div className="w-8 h-8 rounded-full bg-primary/10 flex items-center justify-center">
+                <Icon icon="user" size="sm" className="text-primary" />
+              </div>
+              <div className="flex-1 min-w-0">
+                <p className="text-sm font-medium text-foreground truncate">
+                  {session.user?.name || 'User'}
+                </p>
+                <p className="text-xs text-foreground-tertiary truncate">{session.user?.email}</p>
+              </div>
+            </div>
+          </div>
+        </aside>
+
+        {/* Main content */}
+        <main className="flex-1 min-w-0">
+          {/* Content header */}
+          <div className="sticky top-16 z-10 bg-background border-b border-border">
+            <div className="px-6 py-4">
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-4">
+                  {/* Mobile menu button */}
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="lg:hidden"
+                    onClick={() => setSidebarOpen(true)}
+                  >
+                    <Icon icon="menu" size="sm" />
+                  </Button>
+
+                  {/* Back button */}
+                  {showBackButton && (
+                    <Link
+                      href={getBackUrl()}
+                      className="text-foreground-secondary hover:text-foreground transition-colors"
+                    >
+                      <Icon icon="arrowLeft" size="sm" />
+                    </Link>
+                  )}
+
+                  {/* Title */}
+                  <div>
+                    <h1 className="text-xl font-semibold text-foreground">{title}</h1>
+                    {subtitle && <p className="text-sm text-foreground-secondary">{subtitle}</p>}
+                  </div>
+                </div>
+
+                {/* Actions */}
+                {actions && <div className="flex items-center gap-2">{actions}</div>}
+              </div>
+            </div>
+          </div>
+
+          {/* Page content */}
+          <div className="p-6">{children}</div>
+        </main>
+      </div>
+    </div>
+  );
+}