feat: add workspace system and sidebar layout (UI design system Phase A+B)

Backend: Workspace model, migration (036), schemas, CRUD API endpoints. Adds workspace_id to trees and categories, seeds 4 default workspaces per account, auto-assigns existing trees by tree_type. Frontend: Complete AppLayout rewrite from top-nav to CSS Grid shell with persistent sidebar + topbar. New components: WorkspaceSwitcher, NavItem, CategoryList, TagCloud, TopBar, Sidebar. Dashboard components: QuickStats, FiltersBar, SectionGroup, TreeListItem, SessionsPanel. WorkspaceStore with localStorage persistence. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-15 01:16:33 -05:00
parent ef829f06a4
commit d6f4286570
31 changed files with 1431 additions and 250 deletions
--- a/backend/alembic/versions/036_add_workspaces.py
+++ b/backend/alembic/versions/036_add_workspaces.py
@@ -0,0 +1,102 @@
+"""Add workspaces table, workspace_id to trees and categories, color to categories
+
+Revision ID: 036
+Revises: 035
+Create Date: 2026-02-15
+
+Adds workspace system for organizational context above folders.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = '036'
+down_revision: Union[str, None] = '035'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Create workspaces table
+    op.create_table(
+        'workspaces',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('name', sa.String(100), nullable=False),
+        sa.Column('slug', sa.String(100), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('icon', sa.String(10), nullable=True),
+        sa.Column('accent_color', sa.String(7), nullable=True),
+        sa.Column('account_id', UUID(as_uuid=True), sa.ForeignKey('accounts.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('is_default', sa.Boolean(), nullable=False, server_default='false'),
+        sa.Column('sort_order', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('NOW()')),
+        sa.UniqueConstraint('slug', 'account_id', name='uq_workspaces_slug_account'),
+    )
+    op.create_index('ix_workspaces_slug', 'workspaces', ['slug'])
+    op.create_index('ix_workspaces_account_id', 'workspaces', ['account_id'])
+
+    # Add workspace_id to trees
+    op.add_column('trees', sa.Column('workspace_id', UUID(as_uuid=True), nullable=True))
+    op.create_foreign_key('fk_trees_workspace_id', 'trees', 'workspaces', ['workspace_id'], ['id'], ondelete='SET NULL')
+    op.create_index('ix_trees_workspace_id', 'trees', ['workspace_id'])
+
+    # Add color and workspace_id to tree_categories
+    op.add_column('tree_categories', sa.Column('color', sa.String(7), nullable=True, server_default='#3b82f6'))
+    op.add_column('tree_categories', sa.Column('workspace_id', UUID(as_uuid=True), nullable=True))
+    op.create_foreign_key('fk_tree_categories_workspace_id', 'tree_categories', 'workspaces', ['workspace_id'], ['id'], ondelete='SET NULL')
+    op.create_index('ix_tree_categories_workspace_id', 'tree_categories', ['workspace_id'])
+
+    # Seed default workspaces for each existing account and assign trees
+    op.execute("""
+        -- Create default workspaces for each account
+        INSERT INTO workspaces (name, slug, description, icon, accent_color, account_id, is_default, sort_order)
+        SELECT 'Troubleshooting', 'troubleshooting', 'Break/fix decision trees', '🔧', '#ef4444', a.id, true, 0
+        FROM accounts a;
+
+        INSERT INTO workspaces (name, slug, description, icon, accent_color, account_id, is_default, sort_order)
+        SELECT 'Procedures', 'procedures', 'Step-by-step operational flows', '📋', '#3b82f6', a.id, false, 1
+        FROM accounts a;
+
+        INSERT INTO workspaces (name, slug, description, icon, accent_color, account_id, is_default, sort_order)
+        SELECT 'Policies', 'policies', 'Compliance & policy builders', '📜', '#8b5cf6', a.id, false, 2
+        FROM accounts a;
+
+        INSERT INTO workspaces (name, slug, description, icon, accent_color, account_id, is_default, sort_order)
+        SELECT 'Finance', 'finance', 'Billing & procurement flows', '💰', '#22c55e', a.id, false, 3
+        FROM accounts a;
+
+        -- Assign existing trees to appropriate workspace based on tree_type
+        UPDATE trees t
+        SET workspace_id = w.id
+        FROM workspaces w
+        WHERE w.account_id = t.account_id
+          AND w.slug = 'troubleshooting'
+          AND t.tree_type = 'troubleshooting';
+
+        UPDATE trees t
+        SET workspace_id = w.id
+        FROM workspaces w
+        WHERE w.account_id = t.account_id
+          AND w.slug = 'procedures'
+          AND t.tree_type = 'procedural';
+    """)
+
+
+def downgrade() -> None:
+    op.drop_index('ix_tree_categories_workspace_id', 'tree_categories')
+    op.drop_constraint('fk_tree_categories_workspace_id', 'tree_categories', type_='foreignkey')
+    op.drop_column('tree_categories', 'workspace_id')
+    op.drop_column('tree_categories', 'color')
+
+    op.drop_index('ix_trees_workspace_id', 'trees')
+    op.drop_constraint('fk_trees_workspace_id', 'trees', type_='foreignkey')
+    op.drop_column('trees', 'workspace_id')
+
+    op.drop_index('ix_workspaces_account_id', 'workspaces')
+    op.drop_index('ix_workspaces_slug', 'workspaces')
+    op.drop_table('workspaces')
--- a/backend/app/api/endpoints/workspaces.py
+++ b/backend/app/api/endpoints/workspaces.py
@@ -0,0 +1,154 @@
+from typing import Annotated
+from uuid import UUID
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+
+from app.core.database import get_db
+from app.models.workspace import Workspace
+from app.models.tree import Tree
+from app.models.user import User
+from app.schemas.workspace import WorkspaceCreate, WorkspaceUpdate, WorkspaceResponse
+from app.api.deps import get_current_active_user
+
+router = APIRouter(prefix="/workspaces", tags=["workspaces"])
+
+
+@router.get("", response_model=list[WorkspaceResponse])
+async def list_workspaces(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """List all workspaces for the user's account."""
+    if not current_user.account_id:
+        return []
+
+    # Get workspaces with tree counts
+    query = (
+        select(
+            Workspace,
+            func.count(Tree.id).label("tree_count")
+        )
+        .outerjoin(Tree, (Tree.workspace_id == Workspace.id) & (Tree.deleted_at.is_(None)))
+        .where(Workspace.account_id == current_user.account_id)
+        .group_by(Workspace.id)
+        .order_by(Workspace.sort_order, Workspace.name)
+    )
+    result = await db.execute(query)
+    rows = result.all()
+
+    return [
+        WorkspaceResponse(
+            **{c.key: getattr(ws, c.key) for c in Workspace.__table__.columns},
+            tree_count=tree_count
+        )
+        for ws, tree_count in rows
+    ]
+
+
+@router.post("", response_model=WorkspaceResponse, status_code=status.HTTP_201_CREATED)
+async def create_workspace(
+    data: WorkspaceCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Create a new workspace."""
+    if not current_user.account_id:
+        raise HTTPException(status_code=400, detail="No account found")
+
+    # Check slug uniqueness within account
+    existing = await db.execute(
+        select(Workspace).where(
+            Workspace.account_id == current_user.account_id,
+            Workspace.slug == data.slug
+        )
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail="Workspace slug already exists")
+
+    workspace = Workspace(
+        name=data.name,
+        slug=data.slug,
+        description=data.description,
+        icon=data.icon,
+        accent_color=data.accent_color,
+        account_id=current_user.account_id,
+        sort_order=data.sort_order,
+    )
+    db.add(workspace)
+    await db.flush()
+    await db.commit()
+
+    return WorkspaceResponse(
+        **{c.key: getattr(workspace, c.key) for c in Workspace.__table__.columns},
+        tree_count=0
+    )
+
+
+@router.patch("/{workspace_id}", response_model=WorkspaceResponse)
+async def update_workspace(
+    workspace_id: UUID,
+    data: WorkspaceUpdate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Update a workspace."""
+    workspace = await db.get(Workspace, workspace_id)
+    if not workspace or workspace.account_id != current_user.account_id:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+
+    update_data = data.model_dump(exclude_unset=True)
+    if "slug" in update_data:
+        existing = await db.execute(
+            select(Workspace).where(
+                Workspace.account_id == current_user.account_id,
+                Workspace.slug == update_data["slug"],
+                Workspace.id != workspace_id
+            )
+        )
+        if existing.scalar_one_or_none():
+            raise HTTPException(status_code=409, detail="Workspace slug already exists")
+
+    for key, value in update_data.items():
+        setattr(workspace, key, value)
+
+    await db.commit()
+
+    # Get tree count
+    count_result = await db.execute(
+        select(func.count(Tree.id)).where(
+            Tree.workspace_id == workspace_id,
+            Tree.deleted_at.is_(None)
+        )
+    )
+    tree_count = count_result.scalar() or 0
+
+    return WorkspaceResponse(
+        **{c.key: getattr(workspace, c.key) for c in Workspace.__table__.columns},
+        tree_count=tree_count
+    )
+
+
+@router.delete("/{workspace_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_workspace(
+    workspace_id: UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Delete a workspace. Trees are unassigned, not deleted."""
+    workspace = await db.get(Workspace, workspace_id)
+    if not workspace or workspace.account_id != current_user.account_id:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+
+    if workspace.is_default:
+        raise HTTPException(status_code=400, detail="Cannot delete the default workspace")
+
+    # Unassign trees (set workspace_id to NULL)
+    await db.execute(
+        Tree.__table__.update()
+        .where(Tree.workspace_id == workspace_id)
+        .values(workspace_id=None)
+    )
+
+    await db.delete(workspace)
+    await db.commit()
--- a/backend/app/api/router.py
+++ b/backend/app/api/router.py
@@ -1,5 +1,5 @@
 from fastapi import APIRouter
-from app.api.endpoints import auth, trees, sessions, invite, categories, tags, folders, step_categories, steps, admin, accounts, webhooks, shares, shared, tree_markdown
+from app.api.endpoints import auth, trees, sessions, invite, categories, tags, folders, step_categories, steps, admin, accounts, webhooks, shares, shared, tree_markdown, workspaces
 from app.api.endpoints import admin_dashboard, admin_audit, admin_plan_limits, admin_feature_flags, admin_settings, admin_categories

 api_router = APIRouter()
@@ -25,3 +25,4 @@ api_router.include_router(webhooks.router)
 api_router.include_router(shares.router)
 api_router.include_router(shared.router)  # Public endpoints (no auth)
 api_router.include_router(tree_markdown.router)
+api_router.include_router(workspaces.router)
--- a/backend/app/models/init.py
+++ b/backend/app/models/init.py
@@ -20,6 +20,7 @@ from .session_share import SessionShare, SessionShareView
 from .account_limit_override import AccountLimitOverride
 from .feature_flag import FeatureFlag, PlanFeatureDefault, AccountFeatureOverride
 from .platform_setting import PlatformSetting
+from .workspace import Workspace

 __all__ = [
    "User",
@@ -51,4 +52,5 @@ __all__ = [
    "PlanFeatureDefault",
    "AccountFeatureOverride",
    "PlatformSetting",
+    "Workspace",
 ]
--- a/backend/app/models/account.py
+++ b/backend/app/models/account.py
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
    from app.models.step_category import StepCategory
    from app.models.step_library import StepLibrary
    from app.models.account_limit_override import AccountLimitOverride
+    from app.models.workspace import Workspace


 class Account(Base):
@@ -45,3 +46,4 @@ class Account(Base):
    step_categories: Mapped[list["StepCategory"]] = relationship("StepCategory", foreign_keys="[StepCategory.account_id]", back_populates="account")
    step_library: Mapped[list["StepLibrary"]] = relationship("StepLibrary", foreign_keys="[StepLibrary.account_id]", back_populates="account")
    limit_override: Mapped[Optional["AccountLimitOverride"]] = relationship("AccountLimitOverride", back_populates="account", uselist=False)
+    workspaces: Mapped[list["Workspace"]] = relationship("Workspace", back_populates="account")
--- a/backend/app/models/category.py
+++ b/backend/app/models/category.py
@@ -11,6 +11,7 @@ if TYPE_CHECKING:
    from app.models.team import Team
    from app.models.account import Account
    from app.models.user import User
+    from app.models.workspace import Workspace


 class TreeCategory(Base):
@@ -47,6 +48,17 @@ class TreeCategory(Base):
    )
    display_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0, index=True)
    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    color: Mapped[Optional[str]] = mapped_column(
+        String(7), nullable=True, default='#3b82f6',
+        comment="Hex color for category dot indicator"
+    )
+    workspace_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("workspaces.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+        comment="Workspace this category belongs to"
+    )
    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("users.id", ondelete="SET NULL"),
@@ -67,6 +79,7 @@ class TreeCategory(Base):
    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="categories")
    creator: Mapped[Optional["User"]] = relationship("User", foreign_keys=[created_by])
    trees: Mapped[list["Tree"]] = relationship("Tree", back_populates="category_rel")
+    workspace: Mapped[Optional["Workspace"]] = relationship("Workspace", back_populates="categories")

    @property
    def is_global(self) -> bool:
--- a/backend/app/models/tree.py
+++ b/backend/app/models/tree.py
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
    from app.models.tag import TreeTag
    from app.models.folder import UserFolder
    from app.models.tree_share import TreeShare
+    from app.models.workspace import Workspace


 class Tree(Base):
@@ -120,6 +121,13 @@ class Tree(Base):
        onupdate=lambda: datetime.now(timezone.utc)
    )
    usage_count: Mapped[int] = mapped_column(Integer, default=0)
+    workspace_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("workspaces.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+        comment="Workspace this tree belongs to (organizational context)"
+    )

    # Fork tracking
    parent_tree_id: Mapped[Optional[uuid.UUID]] = mapped_column(
@@ -184,6 +192,8 @@ class Tree(Base):
        cascade="all, delete-orphan"
    )

+    workspace: Mapped[Optional["Workspace"]] = relationship("Workspace", back_populates="trees")
+
    # New organization relationships
    category_rel: Mapped[Optional["TreeCategory"]] = relationship("TreeCategory", back_populates="trees")
    tags: Mapped[list["TreeTag"]] = relationship(
--- a/backend/app/models/workspace.py
+++ b/backend/app/models/workspace.py
@@ -0,0 +1,57 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, Text, DateTime, ForeignKey, Boolean, Integer, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.account import Account
+    from app.models.tree import Tree
+    from app.models.category import TreeCategory
+
+
+class Workspace(Base):
+    """Workspaces are the top-level organizational context for trees/flows.
+
+    They sit above the folder system — a workspace scopes which trees/flows
+    are visible, while folders remain for personal organization within.
+    """
+    __tablename__ = "workspaces"
+    __table_args__ = (
+        UniqueConstraint('slug', 'account_id', name='uq_workspaces_slug_account'),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    slug: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    icon: Mapped[Optional[str]] = mapped_column(String(10), nullable=True)
+    accent_color: Mapped[Optional[str]] = mapped_column(String(7), nullable=True)
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    is_default: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    sort_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc)
+    )
+
+    # Relationships
+    account: Mapped["Account"] = relationship("Account", back_populates="workspaces")
+    trees: Mapped[list["Tree"]] = relationship("Tree", back_populates="workspace")
+    categories: Mapped[list["TreeCategory"]] = relationship("TreeCategory", back_populates="workspace")
--- a/backend/app/schemas/category.py
+++ b/backend/app/schemas/category.py
@@ -36,6 +36,8 @@ class CategoryResponse(CategoryBase):
    account_id: Optional[UUID] = None
    display_order: int
    is_active: bool
+    color: Optional[str] = None
+    workspace_id: Optional[UUID] = None
    created_at: datetime
    updated_at: datetime
    tree_count: int = 0  # Computed field
@@ -52,6 +54,8 @@ class CategoryListResponse(BaseModel):
    account_id: Optional[UUID] = None
    display_order: int
    is_active: bool
+    color: Optional[str] = None
+    workspace_id: Optional[UUID] = None
    tree_count: int = 0

    class Config:
--- a/backend/app/schemas/workspace.py
+++ b/backend/app/schemas/workspace.py
@@ -0,0 +1,39 @@
+import uuid
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class WorkspaceCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    slug: str = Field(..., min_length=1, max_length=100, pattern=r'^[a-z0-9-]+$')
+    description: Optional[str] = None
+    icon: Optional[str] = Field(None, max_length=10)
+    accent_color: Optional[str] = Field(None, pattern=r'^#[0-9a-fA-F]{6}$')
+    sort_order: int = 0
+
+
+class WorkspaceUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    slug: Optional[str] = Field(None, min_length=1, max_length=100, pattern=r'^[a-z0-9-]+$')
+    description: Optional[str] = None
+    icon: Optional[str] = Field(None, max_length=10)
+    accent_color: Optional[str] = Field(None, pattern=r'^#[0-9a-fA-F]{6}$')
+    sort_order: Optional[int] = None
+
+
+class WorkspaceResponse(BaseModel):
+    id: uuid.UUID
+    name: str
+    slug: str
+    description: Optional[str] = None
+    icon: Optional[str] = None
+    accent_color: Optional[str] = None
+    account_id: uuid.UUID
+    is_default: bool
+    sort_order: int
+    tree_count: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -11,3 +11,4 @@ export { default as stepCategoriesApi } from './stepCategories'
 export { default as accountsApi } from './accounts'
 export { default as adminApi } from './admin'
 export { treeMarkdownApi } from './treeMarkdown'
+export { default as workspacesApi } from './workspaces'
--- a/frontend/src/api/workspaces.ts
+++ b/frontend/src/api/workspaces.ts
@@ -0,0 +1,25 @@
+import { apiClient } from './client'
+import type { Workspace, WorkspaceCreate, WorkspaceUpdate } from '@/types'
+
+export const workspacesApi = {
+  list: async (): Promise<Workspace[]> => {
+    const { data } = await apiClient.get('/workspaces')
+    return data
+  },
+
+  create: async (payload: WorkspaceCreate): Promise<Workspace> => {
+    const { data } = await apiClient.post('/workspaces', payload)
+    return data
+  },
+
+  update: async (id: string, payload: WorkspaceUpdate): Promise<Workspace> => {
+    const { data } = await apiClient.patch(`/workspaces/${id}`, payload)
+    return data
+  },
+
+  delete: async (id: string): Promise<void> => {
+    await apiClient.delete(`/workspaces/${id}`)
+  },
+}
+
+export default workspacesApi
--- a/frontend/src/components/dashboard/FiltersBar.tsx
+++ b/frontend/src/components/dashboard/FiltersBar.tsx
@@ -0,0 +1,39 @@
+import { Filter } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+interface FilterChip {
+  id: string
+  label: string
+}
+
+interface FiltersBarProps {
+  filters: FilterChip[]
+  activeFilter: string
+  onFilterChange: (id: string) => void
+}
+
+export function FiltersBar({ filters, activeFilter, onFilterChange }: FiltersBarProps) {
+  return (
+    <div className="fade-in flex items-center gap-1.5 overflow-x-auto py-1" style={{ animationDelay: '100ms' }}>
+      {filters.map(f => (
+        <button
+          key={f.id}
+          onClick={() => onFilterChange(f.id)}
+          className={cn(
+            'shrink-0 rounded-lg border px-3 py-1.5 text-[0.8125rem] font-medium transition-colors',
+            activeFilter === f.id
+              ? 'border-primary/30 bg-primary/10 text-primary'
+              : 'border-border bg-card text-muted-foreground hover:border-border/80 hover:text-foreground'
+          )}
+        >
+          {f.label}
+        </button>
+      ))}
+      <div className="mx-1.5 h-5 w-px shrink-0 bg-border" />
+      <button className="flex shrink-0 items-center gap-1.5 rounded-lg border border-border bg-card px-3 py-1.5 text-[0.8125rem] text-muted-foreground hover:text-foreground transition-colors">
+        <Filter size={14} />
+        More Filters
+      </button>
+    </div>
+  )
+}
--- a/frontend/src/components/dashboard/QuickStats.tsx
+++ b/frontend/src/components/dashboard/QuickStats.tsx
@@ -0,0 +1,44 @@
+import { cn } from '@/lib/utils'
+
+interface StatCard {
+  label: string
+  value: string | number
+  meta?: string
+  gradient?: boolean
+  color?: string
+}
+
+interface QuickStatsProps {
+  stats: StatCard[]
+}
+
+export function QuickStats({ stats }: QuickStatsProps) {
+  return (
+    <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+      {stats.map((stat, i) => (
+        <div
+          key={stat.label}
+          className="fade-in rounded-xl border border-border bg-card p-4 transition-colors hover:border-border/80"
+          style={{ animationDelay: `${50 + i * 30}ms` }}
+        >
+          <p className="font-label text-[0.6875rem] font-semibold uppercase tracking-[0.05em] text-muted-foreground">
+            {stat.label}
+          </p>
+          <p
+            className={cn(
+              'mt-1 font-heading text-2xl font-bold tracking-tight',
+              stat.gradient && 'text-gradient-brand',
+              stat.color
+            )}
+            style={stat.color && !stat.color.startsWith('text-') ? { color: stat.color } : undefined}
+          >
+            {stat.value}
+          </p>
+          {stat.meta && (
+            <p className="mt-0.5 text-[0.6875rem] text-[hsl(var(--text-dimmed))]">{stat.meta}</p>
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
--- a/frontend/src/components/dashboard/SectionGroup.tsx
+++ b/frontend/src/components/dashboard/SectionGroup.tsx
@@ -0,0 +1,40 @@
+import { useState } from 'react'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+interface SectionGroupProps {
+  title: string
+  count?: number
+  defaultOpen?: boolean
+  delay?: number
+  children: React.ReactNode
+}
+
+export function SectionGroup({ title, count, defaultOpen = true, delay = 150, children }: SectionGroupProps) {
+  const [open, setOpen] = useState(defaultOpen)
+
+  return (
+    <div className="fade-in" style={{ animationDelay: `${delay}ms` }}>
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center gap-2 py-2"
+      >
+        <span className="h-2 w-2 shrink-0 rounded-full bg-gradient-brand" />
+        <span className="font-heading text-[0.8125rem] font-bold uppercase tracking-[0.04em] text-foreground">
+          {title}
+        </span>
+        {count !== undefined && (
+          <span className="rounded-full bg-secondary px-2 py-0.5 font-label text-[0.6875rem] text-muted-foreground">
+            {count}
+          </span>
+        )}
+        <div className="flex-1" />
+        <ChevronDown
+          size={14}
+          className={cn('text-muted-foreground transition-transform', !open && '-rotate-90')}
+        />
+      </button>
+      {open && <div className="mt-1 space-y-1">{children}</div>}
+    </div>
+  )
+}
--- a/frontend/src/components/dashboard/SessionsPanel.tsx
+++ b/frontend/src/components/dashboard/SessionsPanel.tsx
@@ -0,0 +1,75 @@
+import { Link } from 'react-router-dom'
+import { cn } from '@/lib/utils'
+
+interface SessionItem {
+  id: string
+  treeName: string
+  status: 'in_progress' | 'completed' | 'abandoned'
+  currentStep?: string
+  totalSteps?: number
+  stepNumber?: number
+  ticketNumber?: string
+  timeAgo: string
+}
+
+interface SessionsPanelProps {
+  sessions: SessionItem[]
+  delay?: number
+}
+
+export function SessionsPanel({ sessions, delay = 200 }: SessionsPanelProps) {
+  if (sessions.length === 0) return null
+
+  return (
+    <div className="fade-in rounded-xl border border-border bg-card" style={{ animationDelay: `${delay}ms` }}>
+      <div className="flex items-center justify-between border-b border-border px-4 py-3">
+        <h3 className="font-heading text-sm font-semibold text-foreground">Recent Sessions</h3>
+        <Link to="/sessions" className="text-[0.6875rem] text-muted-foreground hover:text-foreground transition-colors">
+          View All
+        </Link>
+      </div>
+      <div className="divide-y divide-border">
+        {sessions.map(session => (
+          <Link
+            key={session.id}
+            to={`/sessions/${session.id}`}
+            className="grid items-center gap-3 px-4 py-2.5 transition-colors hover:bg-accent/50"
+            style={{ gridTemplateColumns: '8px 1fr 140px 80px 100px' }}
+          >
+            {/* Status dot */}
+            <span
+              className={cn(
+                'h-2 w-2 rounded-full',
+                session.status === 'completed' ? 'bg-green-500' :
+                session.status === 'in_progress' ? 'bg-amber-500' :
+                'bg-muted-foreground'
+              )}
+            />
+
+            {/* Name */}
+            <span className="text-sm text-foreground truncate">{session.treeName}</span>
+
+            {/* Progress */}
+            <span className="text-[0.6875rem] text-muted-foreground truncate">
+              {session.status === 'completed'
+                ? '✓ Resolved'
+                : session.stepNumber && session.totalSteps
+                  ? `→ step ${session.stepNumber}/${session.totalSteps}`
+                  : '→ In progress'}
+            </span>
+
+            {/* Ticket */}
+            <span className="font-label text-[0.6875rem] text-muted-foreground truncate">
+              {session.ticketNumber || '—'}
+            </span>
+
+            {/* Time */}
+            <span className="text-right text-[0.6875rem] text-[hsl(var(--text-dimmed))]">
+              {session.timeAgo}
+            </span>
+          </Link>
+        ))}
+      </div>
+    </div>
+  )
+}
--- a/frontend/src/components/dashboard/TreeListItem.tsx
+++ b/frontend/src/components/dashboard/TreeListItem.tsx
@@ -0,0 +1,109 @@
+import { useNavigate } from 'react-router-dom'
+import { MoreHorizontal } from 'lucide-react'
+import { getTreeNavigatePath, getTreeEditorPath } from '@/lib/routing'
+
+interface TreeListItemProps {
+  id: string
+  name: string
+  description?: string | null
+  treeType: string
+  category?: { name: string; color?: string } | null
+  tags?: string[]
+  usageCount?: number
+  updatedAt: string
+  icon?: string
+}
+
+export function TreeListItem({
+  id,
+  name,
+  description,
+  treeType,
+  category,
+  tags = [],
+  usageCount = 0,
+  updatedAt,
+  icon,
+}: TreeListItemProps) {
+  const navigate = useNavigate()
+  const categoryColor = category?.color || '#3b82f6'
+
+  const timeAgo = getTimeAgo(updatedAt)
+
+  return (
+    <div
+      onClick={() => navigate(getTreeNavigatePath(id, treeType))}
+      className="group grid cursor-pointer items-center gap-3 rounded-lg border border-transparent bg-card px-4 py-3 transition-colors hover:border-border hover:bg-[hsl(var(--sidebar-hover))]"
+      style={{ gridTemplateColumns: '40px 1fr 130px 80px 100px 40px' }}
+    >
+      {/* Icon box */}
+      <div
+        className="flex h-9 w-9 items-center justify-center rounded-lg text-base"
+        style={{ backgroundColor: `${categoryColor}15` }}
+      >
+        {icon || (treeType === 'procedural' ? '📋' : '🔧')}
+      </div>
+
+      {/* Info */}
+      <div className="min-w-0">
+        <p className="font-heading text-sm font-semibold text-foreground truncate">{name}</p>
+        <div className="mt-0.5 flex items-center gap-2">
+          {tags.slice(0, 3).map(tag => (
+            <span key={tag} className="rounded border border-border bg-secondary px-1.5 py-px font-label text-[0.625rem] text-muted-foreground">
+              {tag}
+            </span>
+          ))}
+          {description && tags.length === 0 && (
+            <span className="text-[0.6875rem] text-muted-foreground truncate">{description}</span>
+          )}
+        </div>
+      </div>
+
+      {/* Category */}
+      <div className="flex items-center gap-1.5">
+        {category && (
+          <>
+            <span className="h-2 w-2 shrink-0 rounded-full" style={{ backgroundColor: categoryColor }} />
+            <span className="font-label text-xs text-muted-foreground truncate">{category.name}</span>
+          </>
+        )}
+      </div>
+
+      {/* Usage count */}
+      <div className="text-right font-label text-xs text-muted-foreground">
+        {usageCount} uses
+      </div>
+
+      {/* Updated */}
+      <div className="text-right text-[0.6875rem] text-[hsl(var(--text-dimmed))]">
+        {timeAgo}
+      </div>
+
+      {/* Actions */}
+      <button
+        onClick={(e) => {
+          e.stopPropagation()
+          navigate(getTreeEditorPath(id, treeType))
+        }}
+        className="flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground opacity-0 transition-opacity hover:bg-accent group-hover:opacity-100"
+      >
+        <MoreHorizontal size={16} />
+      </button>
+    </div>
+  )
+}
+
+function getTimeAgo(dateStr: string): string {
+  const now = Date.now()
+  const date = new Date(dateStr).getTime()
+  const diff = now - date
+  const minutes = Math.floor(diff / 60000)
+  if (minutes < 1) return 'Just now'
+  if (minutes < 60) return `${minutes} min ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  if (days === 1) return 'Yesterday'
+  if (days < 7) return `${days}d ago`
+  return new Date(dateStr).toLocaleDateString()
+}
--- a/frontend/src/components/layout/AppLayout.tsx
+++ b/frontend/src/components/layout/AppLayout.tsx
@@ -1,61 +1,39 @@
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { Link, useLocation, useNavigate, Outlet } from 'react-router-dom'
+import { useEffect, useState, useCallback } from 'react'
+import { Outlet, useLocation, useNavigate, Link } from 'react-router-dom'
+import { Menu, X, LayoutGrid, Box, PenLine, Clock, FileText, Bookmark, Users, Settings, LogOut, Shield } from 'lucide-react'
 import { useAuthStore } from '@/store/authStore'
 import { usePermissions } from '@/hooks/usePermissions'
+import { useWorkspaceStore } from '@/store/workspaceStore'
 import { BrandLogo } from '@/components/common/BrandLogo'
-import { Menu, X, LogOut, User, Shield, ChevronDown, FolderTree, ListOrdered, Layers } from 'lucide-react'
+import { TopBar } from './TopBar'
+import { Sidebar } from './Sidebar'
 import { cn } from '@/lib/utils'

-interface NavItem {
-  path: string
-  label: string
-  children?: { path: string; label: string; icon: React.ReactNode }[]
-}
-
 export function AppLayout() {
  const location = useLocation()
  const navigate = useNavigate()
  const { user, logout } = useAuthStore()
-  const { effectiveRole, isSuperAdmin } = usePermissions()
+  const { effectiveRole } = usePermissions()
+  const fetchWorkspaces = useWorkspaceStore(s => s.fetchWorkspaces)
  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
-  const [flowsDropdownOpen, setFlowsDropdownOpen] = useState(false)
-  const flowsDropdownRef = useRef<HTMLDivElement>(null)

-  const handleLogout = async () => {
-    setMobileMenuOpen(false)
-    await logout()
-    navigate('/login')
-  }
+  // Fetch workspaces on mount
+  useEffect(() => {
+    fetchWorkspaces()
+  }, [fetchWorkspaces])

  // Close mobile menu on route change
  const [prevPath, setPrevPath] = useState(location.pathname)
  if (prevPath !== location.pathname) {
    setPrevPath(location.pathname)
    if (mobileMenuOpen) setMobileMenuOpen(false)
-    setFlowsDropdownOpen(false)
  }

  // Close on Escape
  const handleKeyDown = useCallback((e: KeyboardEvent) => {
-    if (e.key === 'Escape') {
-      setMobileMenuOpen(false)
-      setFlowsDropdownOpen(false)
-    }
+    if (e.key === 'Escape') setMobileMenuOpen(false)
  }, [])

-  // Close dropdown on outside click
-  useEffect(() => {
-    const handleClickOutside = (e: MouseEvent) => {
-      if (flowsDropdownRef.current && !flowsDropdownRef.current.contains(e.target as Node)) {
-        setFlowsDropdownOpen(false)
-      }
-    }
-    if (flowsDropdownOpen) {
-      document.addEventListener('mousedown', handleClickOutside)
-    }
-    return () => document.removeEventListener('mousedown', handleClickOutside)
-  }, [flowsDropdownOpen])
-
  useEffect(() => {
    if (mobileMenuOpen) {
      document.addEventListener('keydown', handleKeyDown)
@@ -69,250 +47,98 @@ export function AppLayout() {
    }
  }, [mobileMenuOpen, handleKeyDown])

-  const isFlowsActive = location.pathname.startsWith('/trees') || location.pathname.startsWith('/flows')
+  const handleLogout = async () => {
+    setMobileMenuOpen(false)
+    await logout()
+    navigate('/login')
+  }

-  const navItems: NavItem[] = [
-    { path: '/', label: 'Home' },
-    {
-      path: '/trees',
-      label: 'Flows',
-      children: [
-        { path: '/trees', label: 'All Flows', icon: <Layers className="h-4 w-4 text-white/50" /> },
-        { path: '/trees?type=troubleshooting', label: 'Troubleshooting', icon: <FolderTree className="h-4 w-4 text-white/50" /> },
-        { path: '/trees?type=procedural', label: 'Procedures', icon: <ListOrdered className="h-4 w-4 text-white/50" /> },
-      ],
-    },
-    { path: '/my-trees', label: 'My Flows' },
-    { path: '/sessions', label: 'Sessions' },
-    { path: '/shares', label: 'My Shares' },
-    { path: '/account', label: 'Account' },
-    ...(isSuperAdmin ? [{ path: '/admin', label: 'Admin Panel' }] : []),
+  const mobileNavItems = [
+    { path: '/', label: 'Dashboard', icon: LayoutGrid },
+    { path: '/trees', label: 'All Flows', icon: Box },
+    { path: '/my-trees', label: 'My Flows', icon: PenLine },
+    { path: '/sessions', label: 'Sessions', icon: Clock },
+    { path: '/shares', label: 'Exports', icon: FileText },
+    { path: '/step-library', label: 'Step Library', icon: Bookmark },
+    { path: '/account', label: 'Team', icon: Users },
+    { path: '/account', label: 'Settings', icon: Settings },
  ]

  return (
-    <div className="min-h-screen bg-black">
-      {/* Subtle radial overlay for depth */}
-      <div className="pointer-events-none fixed inset-0 bg-[radial-gradient(circle_at_50%_0%,rgba(100,100,120,0.03),transparent_50%),radial-gradient(circle_at_80%_80%,rgba(80,80,100,0.02),transparent_50%)]" />
+    <div className="app-shell">
+      {/* Top Bar - spans full width */}
+      <TopBar />

-      {/* Header */}
-      <header className="sticky top-0 z-50 border-b border-white/[0.06] bg-black/80 backdrop-blur-xl">
-        <div className="container mx-auto flex h-16 items-center justify-between px-4">
-          <div className="flex items-center gap-8">
-            {/* Mobile hamburger */}
-            <button
-              onClick={() => setMobileMenuOpen(true)}
-              className="rounded-xl p-2 text-white/50 hover:bg-white/10 hover:text-white transition-all sm:hidden"
-              aria-label="Open menu"
-            >
-              <Menu className="h-5 w-5" />
-            </button>
+      {/* Sidebar - desktop only */}
+      <div className="hidden md:block">
+        <Sidebar />
+      </div>

-            {/* Logo */}
-            <Link to="/" className="flex items-center gap-3 group">
-              <div className="w-9 h-9 rounded-xl bg-white flex items-center justify-center transition-transform group-hover:scale-105">
-                <BrandLogo size="sm" className="h-5 w-5 invert" />
-              </div>
-              <span className="text-xl font-semibold text-white tracking-tight">
-                ResolutionFlow
-              </span>
-            </Link>
-
-            {/* Desktop Navigation */}
-            <nav className="hidden items-center gap-1 sm:flex">
-              {navItems.map((item) => {
-                if (item.children) {
-                  return (
-                    <div key={item.path} className="relative" ref={flowsDropdownRef}>
-                      <button
-                        onClick={() => setFlowsDropdownOpen(!flowsDropdownOpen)}
-                        className={cn(
-                          'flex items-center gap-1 rounded-xl px-4 py-2 text-sm font-medium transition-all',
-                          isFlowsActive
-                            ? 'bg-white/10 text-white border border-white/20'
-                            : 'text-white/50 hover:text-white hover:bg-white/[0.06]'
-                        )}
-                      >
-                        {item.label}
-                        <ChevronDown className={cn('h-3.5 w-3.5 transition-transform', flowsDropdownOpen && 'rotate-180')} />
-                      </button>
-                      {flowsDropdownOpen && (
-                        <div className="absolute left-0 z-50 mt-1 w-52 rounded-lg border border-white/10 bg-black/95 p-1 shadow-xl backdrop-blur-sm">
-                          {item.children.map((child) => (
-                            <Link
-                              key={child.path}
-                              to={child.path}
-                              onClick={() => setFlowsDropdownOpen(false)}
-                              className="flex items-center gap-3 rounded-md px-3 py-2.5 text-sm text-white/70 hover:bg-white/10 hover:text-white"
-                            >
-                              {child.icon}
-                              {child.label}
-                            </Link>
-                          ))}
-                        </div>
-                      )}
-                    </div>
-                  )
-                }
-
-                const isActive = item.path === '/'
-                  ? location.pathname === '/'
-                  : location.pathname.startsWith(item.path)
-
-                return (
-                  <Link
-                    key={item.path}
-                    to={item.path}
-                    className={cn(
-                      'rounded-xl px-4 py-2 text-sm font-medium transition-all',
-                      isActive
-                        ? 'bg-white/10 text-white border border-white/20'
-                        : 'text-white/50 hover:text-white hover:bg-white/[0.06]'
-                    )}
-                  >
-                    {item.label}
-                  </Link>
-                )
-              })}
-            </nav>
-          </div>
-
-          {/* Right side controls */}
-          <div className="flex items-center gap-3">
-            {/* User info */}
-            <div className="hidden items-center gap-3 sm:flex">
-              <div className="flex items-center gap-2 rounded-xl bg-white/[0.06] px-3 py-1.5 border border-white/10">
-                <User className="h-4 w-4 text-white/40" />
-                <span className="text-sm text-white/70">
-                  {user?.name || user?.email}
-                </span>
-              </div>
-
-              {/* Role badge */}
-              {effectiveRole && effectiveRole !== 'engineer' && (
-                <div className="px-3 py-1.5 rounded-xl bg-white/10 border border-white/20">
-                  <span className="flex items-center gap-1.5 text-xs text-white font-semibold">
-                    <Shield className="h-3 w-3" />
-                    {effectiveRole === 'super_admin' ? 'Super Admin' :
-                     effectiveRole === 'owner' ? 'Owner' :
-                     'Viewer'}
-                  </span>
-                </div>
-              )}
-            </div>
-
-            {/* Logout button */}
-            <button
-              onClick={handleLogout}
-              className={cn(
-                'hidden items-center gap-2 rounded-xl px-4 py-2 text-sm font-medium sm:flex',
-                'text-white/50 hover:text-white hover:bg-white/10 transition-all',
-                'border border-white/10 hover:border-white/20'
-              )}
-            >
-              <LogOut className="h-4 w-4" />
-              Logout
-            </button>
-          </div>
-        </div>
-      </header>
+      {/* Mobile hamburger - overlaid on topbar */}
+      <button
+        onClick={() => setMobileMenuOpen(true)}
+        className="fixed left-4 top-3.5 z-50 rounded-lg p-2 text-muted-foreground hover:bg-card hover:text-foreground transition-colors md:hidden"
+        aria-label="Open menu"
+      >
+        <Menu size={20} />
+      </button>

      {/* Mobile Nav Drawer */}
      {mobileMenuOpen && (
-        <div className="fixed inset-0 z-50 sm:hidden">
-          {/* Backdrop */}
+        <div className="fixed inset-0 z-50 md:hidden">
          <div
-            className="absolute inset-0 bg-black/80 backdrop-blur-sm animate-in fade-in duration-200"
+            className="absolute inset-0 bg-black/80 backdrop-blur-sm animate-fade-in"
            onClick={() => setMobileMenuOpen(false)}
            aria-hidden="true"
          />
-
-          {/* Drawer */}
-          <nav className="absolute inset-y-0 left-0 w-72 border-r border-white/[0.06] bg-black shadow-2xl animate-in slide-in-from-left duration-300">
-            <div className="flex h-16 items-center justify-between border-b border-white/[0.06] px-4">
-              <Link to="/" className="flex items-center gap-3">
-                <div className="w-9 h-9 rounded-xl bg-white flex items-center justify-center">
-                  <BrandLogo size="sm" className="h-5 w-5 invert" />
+          <nav className="absolute inset-y-0 left-0 w-72 border-r border-border bg-[hsl(var(--sidebar-bg))] shadow-2xl animate-slide-in-left">
+            <div className="flex h-14 items-center justify-between border-b border-border px-4">
+              <Link to="/" className="flex items-center gap-2.5">
+                <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-gradient-brand">
+                  <BrandLogo size="sm" className="h-4 w-4" />
                </div>
-                <span className="text-xl font-semibold text-white tracking-tight">
-                  ResolutionFlow
-                </span>
+                <span className="text-sm font-heading font-bold">ResolutionFlow</span>
              </Link>
              <button
                onClick={() => setMobileMenuOpen(false)}
-                className="rounded-xl p-2 text-white/50 hover:bg-white/10 hover:text-white transition-all"
+                className="rounded-lg p-2 text-muted-foreground hover:bg-card hover:text-foreground"
                aria-label="Close menu"
              >
-                <X className="h-5 w-5" />
+                <X size={18} />
              </button>
            </div>

-            <div className="flex flex-col p-4">
+            <div className="flex flex-col p-3">
              {/* User info */}
-              <div className="mb-4 border-b border-white/[0.06] pb-4">
-                <div className="flex items-center gap-2 mb-2">
-                  <User className="h-4 w-4 text-white/40" />
-                  <p className="text-sm font-medium text-white">
-                    {user?.name || user?.email}
-                  </p>
-                </div>
+              <div className="mb-3 border-b border-border pb-3 px-3">
+                <p className="text-sm font-medium text-foreground">{user?.name || user?.email}</p>
                {effectiveRole && effectiveRole !== 'engineer' && (
-                  <div className="inline-flex px-3 py-1.5 rounded-xl bg-white/10 border border-white/20">
-                    <span className="flex items-center gap-1.5 text-xs text-white font-semibold">
-                      <Shield className="h-3 w-3" />
-                      {effectiveRole === 'super_admin' ? 'Super Admin' :
-                       effectiveRole === 'owner' ? 'Owner' :
-                       'Viewer'}
-                    </span>
-                  </div>
+                  <span className="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground">
+                    <Shield size={10} />
+                    {effectiveRole === 'super_admin' ? 'Super Admin' : effectiveRole === 'owner' ? 'Owner' : 'Viewer'}
+                  </span>
                )}
              </div>

              {/* Nav items */}
-              <div className="space-y-1">
-                {navItems.map((item) => {
-                  if (item.children) {
-                    return (
-                      <div key={item.path}>
-                        <div className={cn(
-                          'px-4 py-2 text-xs font-semibold uppercase tracking-wider',
-                          isFlowsActive ? 'text-white/60' : 'text-white/30'
-                        )}>
-                          {item.label}
-                        </div>
-                        <div className="space-y-0.5">
-                          {item.children.map((child) => (
-                            <Link
-                              key={child.path}
-                              to={child.path}
-                              className={cn(
-                                'flex items-center gap-3 rounded-xl px-4 py-3 text-sm font-medium transition-all ml-1',
-                                'text-white/50 hover:text-white hover:bg-white/[0.06]'
-                              )}
-                            >
-                              {child.icon}
-                              {child.label}
-                            </Link>
-                          ))}
-                        </div>
-                      </div>
-                    )
-                  }
-
+              <div className="space-y-0.5">
+                {mobileNavItems.map((item) => {
+                  const Icon = item.icon
                  const isActive = item.path === '/'
                    ? location.pathname === '/'
                    : location.pathname.startsWith(item.path)
-
                  return (
                    <Link
-                      key={item.path}
+                      key={item.path + item.label}
                      to={item.path}
                      className={cn(
-                        'block rounded-xl px-4 py-3 text-sm font-medium transition-all',
+                        'flex items-center gap-3 rounded-lg px-3 py-2.5 text-sm font-medium transition-colors',
                        isActive
-                          ? 'bg-white/10 text-white border border-white/20'
-                          : 'text-white/50 hover:text-white hover:bg-white/[0.06]'
+                          ? 'bg-[hsl(var(--sidebar-active))] text-foreground'
+                          : 'text-muted-foreground hover:bg-[hsl(var(--sidebar-hover))] hover:text-foreground'
                      )}
                    >
+                      <Icon size={18} />
                      {item.label}
                    </Link>
                  )
@@ -320,16 +146,12 @@ export function AppLayout() {
              </div>

              {/* Logout */}
-              <div className="mt-4 border-t border-white/[0.06] pt-4">
+              <div className="mt-3 border-t border-border pt-3">
                <button
                  onClick={handleLogout}
-                  className={cn(
-                    'w-full flex items-center gap-2 rounded-xl px-4 py-3 text-sm font-medium',
-                    'text-white/50 hover:text-white hover:bg-white/10 transition-all',
-                    'border border-white/10 hover:border-white/20'
-                  )}
+                  className="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-sm font-medium text-muted-foreground hover:bg-[hsl(var(--sidebar-hover))] hover:text-foreground transition-colors"
                >
-                  <LogOut className="h-4 w-4" />
+                  <LogOut size={18} />
                  Logout
                </button>
              </div>
@@ -339,7 +161,7 @@ export function AppLayout() {
      )}

      {/* Main Content */}
-      <main className="relative animate-in fade-in duration-500">
+      <main className="main-content overflow-y-auto">
        <Outlet />
      </main>
    </div>
--- a/frontend/src/components/layout/NavItem.tsx
+++ b/frontend/src/components/layout/NavItem.tsx
@@ -0,0 +1,51 @@
+import { Link, useLocation } from 'react-router-dom'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+interface NavItemProps {
+  href: string
+  icon: LucideIcon
+  label: string
+  badge?: number | 'dot'
+  matchPaths?: string[]
+}
+
+export function NavItem({ href, icon: Icon, label, badge, matchPaths }: NavItemProps) {
+  const location = useLocation()
+  const isActive = matchPaths
+    ? matchPaths.some(p => location.pathname.startsWith(p))
+    : href === '/'
+      ? location.pathname === '/'
+      : location.pathname.startsWith(href)
+
+  return (
+    <Link
+      to={href}
+      className={cn(
+        'group relative flex items-center gap-3 rounded-lg px-3 py-2 text-[0.8125rem] font-medium transition-all duration-120',
+        isActive
+          ? 'bg-[hsl(var(--sidebar-active))] text-foreground'
+          : 'text-muted-foreground hover:bg-[hsl(var(--sidebar-hover))] hover:text-foreground'
+      )}
+    >
+      {/* Active indicator bar */}
+      {isActive && (
+        <div className="absolute left-0 top-1/2 h-6 w-[3px] -translate-y-1/2 rounded-r-full bg-gradient-brand" />
+      )}
+
+      <Icon size={18} className={cn('shrink-0', isActive ? 'opacity-100' : 'opacity-70')} />
+      <span className="truncate">{label}</span>
+
+      {/* Badge */}
+      {badge !== undefined && badge !== 0 && (
+        badge === 'dot' ? (
+          <span className="ml-auto h-1.5 w-1.5 shrink-0 rounded-full bg-brand-gradient-from" />
+        ) : (
+          <span className="ml-auto shrink-0 rounded-full bg-card border border-border px-2 text-[0.6875rem] font-label text-muted-foreground">
+            {badge}
+          </span>
+        )
+      )}
+    </Link>
+  )
+}
--- a/frontend/src/components/layout/Sidebar.tsx
+++ b/frontend/src/components/layout/Sidebar.tsx
@@ -0,0 +1,97 @@
+import { useEffect, useState } from 'react'
+import { LayoutGrid, Box, PenLine, Clock, FileText, Bookmark, Users, Settings } from 'lucide-react'
+import { useWorkspaceStore } from '@/store/workspaceStore'
+import { getWorkspaceLabels } from '@/constants/workspaceLabels'
+import { WorkspaceSwitcher } from '@/components/workspace/WorkspaceSwitcher'
+import { CategoryList } from '@/components/workspace/CategoryList'
+import { TagCloud } from '@/components/workspace/TagCloud'
+import { NavItem } from './NavItem'
+import { categoriesApi, tagsApi } from '@/api'
+
+interface CategoryItem {
+  id: string
+  name: string
+  color: string
+  count: number
+}
+
+export function Sidebar() {
+  const activeWorkspace = useWorkspaceStore(s => s.getActiveWorkspace())
+  const activeWorkspaceId = useWorkspaceStore(s => s.activeWorkspaceId)
+  const labels = getWorkspaceLabels(activeWorkspace?.slug)
+
+  const [categories, setCategories] = useState<CategoryItem[]>([])
+  const [tags, setTags] = useState<string[]>([])
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null)
+  const [activeTags, setActiveTags] = useState<string[]>([])
+
+  // Fetch categories and tags when workspace changes
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        const [cats, tagList] = await Promise.all([
+          categoriesApi.list(),
+          tagsApi.list().catch(() => []),
+        ])
+        setCategories(cats.map(c => ({
+          id: c.id,
+          name: c.name,
+          color: c.color || '#3b82f6',
+          count: c.tree_count || 0,
+        })))
+        setTags(tagList.map((t: { name: string }) => t.name).slice(0, 15))
+      } catch {
+        // Silently handle errors
+      }
+    }
+    fetchData()
+  }, [activeWorkspaceId])
+
+  const handleTagClick = (tag: string) => {
+    setActiveTags(prev =>
+      prev.includes(tag) ? prev.filter(t => t !== tag) : [...prev, tag]
+    )
+  }
+
+  return (
+    <nav className="sidebar flex flex-col border-r border-border bg-[hsl(var(--sidebar-bg))]">
+      {/* Workspace Switcher */}
+      <WorkspaceSwitcher />
+
+      <div className="border-b border-[hsl(var(--border-subtle))]" />
+
+      {/* Primary Navigation */}
+      <div className="px-3 py-2 space-y-0.5">
+        <NavItem href="/" icon={LayoutGrid} label="Dashboard" />
+        <NavItem href="/trees" icon={Box} label={labels.allItems} matchPaths={['/trees', '/flows']} />
+        <NavItem href="/my-trees" icon={PenLine} label={labels.editor} />
+        <NavItem href="/sessions" icon={Clock} label="Sessions" />
+        <NavItem href="/shares" icon={FileText} label="Exports" />
+        <NavItem href="/step-library" icon={Bookmark} label="Step Library" badge="dot" />
+      </div>
+
+      <div className="border-b border-[hsl(var(--border-subtle))]" />
+
+      {/* Categories */}
+      <CategoryList
+        categories={categories}
+        activeId={activeCategoryId}
+        onSelect={setActiveCategoryId}
+      />
+
+      <div className="border-b border-[hsl(var(--border-subtle))]" />
+
+      {/* Tags */}
+      <TagCloud tags={tags} activeTags={activeTags} onTagClick={handleTagClick} />
+
+      {/* Spacer */}
+      <div className="flex-1" />
+
+      {/* Footer */}
+      <div className="border-t border-[hsl(var(--border-subtle))] px-3 py-2 space-y-0.5">
+        <NavItem href="/account" icon={Users} label="Team" />
+        <NavItem href="/account" icon={Settings} label="Settings" />
+      </div>
+    </nav>
+  )
+}
--- a/frontend/src/components/layout/TopBar.tsx
+++ b/frontend/src/components/layout/TopBar.tsx
@@ -0,0 +1,144 @@
+import { useState, useRef, useEffect } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { Search, Zap, Bell, LogOut, User, Shield, Settings } from 'lucide-react'
+import { useAuthStore } from '@/store/authStore'
+import { usePermissions } from '@/hooks/usePermissions'
+import { useWorkspaceStore } from '@/store/workspaceStore'
+import { getWorkspaceLabels } from '@/constants/workspaceLabels'
+import { BrandLogo } from '@/components/common/BrandLogo'
+import { cn } from '@/lib/utils'
+
+export function TopBar() {
+  const navigate = useNavigate()
+  const { user, logout } = useAuthStore()
+  const { effectiveRole, isSuperAdmin } = usePermissions()
+  const activeWorkspace = useWorkspaceStore(s => s.getActiveWorkspace())
+  const labels = getWorkspaceLabels(activeWorkspace?.slug)
+
+  const [userMenuOpen, setUserMenuOpen] = useState(false)
+  const menuRef = useRef<HTMLDivElement>(null)
+
+  const handleLogout = async () => {
+    setUserMenuOpen(false)
+    await logout()
+    navigate('/login')
+  }
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        setUserMenuOpen(false)
+      }
+    }
+    if (userMenuOpen) document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [userMenuOpen])
+
+  const initials = user?.name
+    ? user.name.split(' ').map(n => n[0]).join('').toUpperCase().slice(0, 2)
+    : user?.email?.[0]?.toUpperCase() || '?'
+
+  return (
+    <header className="topbar flex items-center gap-4 border-b border-border bg-background px-4">
+      {/* Logo area */}
+      <Link to="/" className="flex items-center gap-2.5 pr-4" style={{ width: 'calc(260px - 40px)' }}>
+        <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-gradient-brand">
+          <BrandLogo size="sm" className="h-4 w-4" />
+        </div>
+        <span className="text-sm font-heading font-bold tracking-tight">
+          <span className="text-foreground">Resolution</span>
+          <span className="text-gradient-brand">Flow</span>
+        </span>
+      </Link>
+
+      {/* Search bar */}
+      <div className="relative flex-1" style={{ maxWidth: '480px' }}>
+        <Search size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground" />
+        <input
+          type="text"
+          placeholder={labels.searchPlaceholder}
+          className="w-full rounded-lg border border-border bg-card py-2 pl-9 pr-14 text-[0.8125rem] text-foreground placeholder:text-muted-foreground focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary/20"
+        />
+        <span className="absolute right-3 top-1/2 -translate-y-1/2 rounded border border-border bg-background px-1.5 py-0.5 font-label text-[0.625rem] text-muted-foreground">
+          ⌘K
+        </span>
+      </div>
+
+      {/* Spacer */}
+      <div className="flex-1" />
+
+      {/* Action buttons */}
+      <div className="flex items-center gap-1">
+        <button className="rounded-lg p-2 text-muted-foreground hover:bg-card hover:text-foreground transition-colors" title="Quick Launch">
+          <Zap size={18} />
+        </button>
+        <button className="relative rounded-lg p-2 text-muted-foreground hover:bg-card hover:text-foreground transition-colors" title="Notifications">
+          <Bell size={18} />
+        </button>
+
+        {/* User avatar & menu */}
+        <div className="relative ml-2" ref={menuRef}>
+          <button
+            onClick={() => setUserMenuOpen(!userMenuOpen)}
+            className="flex h-8 w-8 items-center justify-center rounded-full bg-gradient-brand text-xs font-heading font-bold text-white hover:opacity-90 transition-opacity"
+            title={user?.name || user?.email || 'User'}
+          >
+            {initials}
+          </button>
+
+          {userMenuOpen && (
+            <div className="absolute right-0 z-50 mt-2 w-56 rounded-lg border border-border bg-card p-1 shadow-xl animate-scale-in">
+              <div className="border-b border-border px-3 py-2.5 mb-1">
+                <p className="text-sm font-medium text-foreground truncate">{user?.name || user?.email}</p>
+                {effectiveRole && effectiveRole !== 'engineer' && (
+                  <span className="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground">
+                    <Shield size={10} />
+                    {effectiveRole === 'super_admin' ? 'Super Admin' : effectiveRole === 'owner' ? 'Owner' : 'Viewer'}
+                  </span>
+                )}
+              </div>
+              <Link
+                to="/account"
+                onClick={() => setUserMenuOpen(false)}
+                className="flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+              >
+                <User size={14} />
+                Account
+              </Link>
+              <Link
+                to="/account"
+                onClick={() => setUserMenuOpen(false)}
+                className="flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+              >
+                <Settings size={14} />
+                Settings
+              </Link>
+              {isSuperAdmin && (
+                <Link
+                  to="/admin"
+                  onClick={() => setUserMenuOpen(false)}
+                  className="flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+                >
+                  <Shield size={14} />
+                  Admin Panel
+                </Link>
+              )}
+              <div className="border-t border-border mt-1 pt-1">
+                <button
+                  onClick={handleLogout}
+                  className={cn(
+                    'flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm',
+                    'text-muted-foreground hover:bg-accent hover:text-foreground'
+                  )}
+                >
+                  <LogOut size={14} />
+                  Logout
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </header>
+  )
+}
--- a/frontend/src/components/workspace/CategoryList.tsx
+++ b/frontend/src/components/workspace/CategoryList.tsx
@@ -0,0 +1,47 @@
+import { cn } from '@/lib/utils'
+
+interface CategoryItem {
+  id: string
+  name: string
+  color: string
+  count: number
+}
+
+interface CategoryListProps {
+  categories: CategoryItem[]
+  activeId?: string | null
+  onSelect: (id: string | null) => void
+}
+
+export function CategoryList({ categories, activeId, onSelect }: CategoryListProps) {
+  if (categories.length === 0) return null
+
+  return (
+    <div className="px-3 py-2">
+      <p className="mb-2 px-3 font-heading text-[0.6875rem] font-bold uppercase tracking-[0.04em] text-muted-foreground">
+        Categories
+      </p>
+      <div className="space-y-0.5">
+        {categories.map(cat => (
+          <button
+            key={cat.id}
+            onClick={() => onSelect(activeId === cat.id ? null : cat.id)}
+            className={cn(
+              'flex w-full items-center gap-2.5 rounded-lg px-3 py-1.5 text-sm transition-colors',
+              activeId === cat.id
+                ? 'bg-[hsl(var(--sidebar-active))] text-foreground'
+                : 'text-muted-foreground hover:bg-[hsl(var(--sidebar-hover))] hover:text-foreground'
+            )}
+          >
+            <span
+              className="h-2 w-2 shrink-0 rounded-full"
+              style={{ backgroundColor: cat.color }}
+            />
+            <span className="flex-1 truncate text-left">{cat.name}</span>
+            <span className="font-label text-[0.6875rem] text-[hsl(var(--text-dimmed))]">{cat.count}</span>
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
--- a/frontend/src/components/workspace/TagCloud.tsx
+++ b/frontend/src/components/workspace/TagCloud.tsx
@@ -0,0 +1,38 @@
+import { cn } from '@/lib/utils'
+
+interface TagCloudProps {
+  tags: string[]
+  activeTags?: string[]
+  onTagClick: (tag: string) => void
+}
+
+export function TagCloud({ tags, activeTags = [], onTagClick }: TagCloudProps) {
+  if (tags.length === 0) return null
+
+  return (
+    <div className="px-3 py-2">
+      <p className="mb-2 px-3 font-heading text-[0.6875rem] font-bold uppercase tracking-[0.04em] text-muted-foreground">
+        Popular Tags
+      </p>
+      <div className="flex flex-wrap gap-1 px-3">
+        {tags.map(tag => {
+          const isActive = activeTags.includes(tag)
+          return (
+            <button
+              key={tag}
+              onClick={() => onTagClick(tag)}
+              className={cn(
+                'rounded-md border px-2 py-0.5 font-label text-[0.625rem] transition-colors',
+                isActive
+                  ? 'border-primary/30 bg-primary/10 text-primary'
+                  : 'border-border bg-card text-muted-foreground hover:border-primary/20 hover:text-foreground'
+              )}
+            >
+              {tag}
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
--- a/frontend/src/components/workspace/WorkspaceSwitcher.tsx
+++ b/frontend/src/components/workspace/WorkspaceSwitcher.tsx
@@ -0,0 +1,78 @@
+import { useState, useRef, useEffect } from 'react'
+import { ChevronDown, Plus } from 'lucide-react'
+import { useWorkspaceStore } from '@/store/workspaceStore'
+import { toast } from '@/lib/toast'
+import { cn } from '@/lib/utils'
+
+export function WorkspaceSwitcher() {
+  const { workspaces, activeWorkspaceId, setActiveWorkspace } = useWorkspaceStore()
+  const activeWorkspace = workspaces.find(w => w.id === activeWorkspaceId)
+
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false)
+    }
+    if (open) document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [open])
+
+  const handleSwitch = (ws: typeof workspaces[0]) => {
+    if (ws.id !== activeWorkspaceId) {
+      setActiveWorkspace(ws.id)
+      toast.success(`Switched to ${ws.name}`)
+    }
+    setOpen(false)
+  }
+
+  if (!activeWorkspace) return null
+
+  return (
+    <div className="relative px-3 py-2" ref={ref}>
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left hover:bg-[hsl(var(--sidebar-hover))] transition-colors"
+      >
+        <span className="text-lg leading-none">{activeWorkspace.icon || '📁'}</span>
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-heading font-semibold text-foreground truncate">{activeWorkspace.name}</p>
+          {activeWorkspace.description && (
+            <p className="text-[0.6875rem] text-muted-foreground truncate">{activeWorkspace.description}</p>
+          )}
+        </div>
+        <ChevronDown size={14} className={cn('shrink-0 text-muted-foreground transition-transform', open && 'rotate-180')} />
+      </button>
+
+      {open && (
+        <div className="absolute left-3 right-3 z-50 mt-1 rounded-lg border border-border bg-card shadow-xl animate-scale-in">
+          <div className="p-1">
+            {workspaces.map(ws => (
+              <button
+                key={ws.id}
+                onClick={() => handleSwitch(ws)}
+                className={cn(
+                  'flex w-full items-center gap-3 rounded-md px-3 py-2 text-left transition-colors',
+                  ws.id === activeWorkspaceId
+                    ? 'bg-[hsl(var(--sidebar-active))] text-foreground'
+                    : 'text-muted-foreground hover:bg-accent hover:text-foreground'
+                )}
+              >
+                <span className="text-base leading-none">{ws.icon || '📁'}</span>
+                <span className="flex-1 truncate text-sm">{ws.name}</span>
+                <span className="font-label text-[0.6875rem] text-muted-foreground">{ws.tree_count}</span>
+              </button>
+            ))}
+          </div>
+          <div className="border-t border-border p-1">
+            <button className="flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
+              <Plus size={14} />
+              Add workspace…
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
--- a/frontend/src/constants/categoryColors.ts
+++ b/frontend/src/constants/categoryColors.ts
@@ -0,0 +1,12 @@
+export const CATEGORY_COLORS = [
+  '#3b82f6', // blue
+  '#22c55e', // green
+  '#f59e0b', // amber
+  '#ef4444', // red
+  '#8b5cf6', // violet
+  '#06b6d4', // cyan
+  '#ec4899', // pink
+  '#f97316', // orange
+  '#14b8a6', // teal
+  '#6366f1', // indigo
+] as const
--- a/frontend/src/constants/workspaceLabels.ts
+++ b/frontend/src/constants/workspaceLabels.ts
@@ -0,0 +1,45 @@
+export interface WorkspaceLabels {
+  allItems: string
+  editor: string
+  newItem: string
+  searchPlaceholder: string
+}
+
+export const WORKSPACE_LABELS: Record<string, WorkspaceLabels> = {
+  troubleshooting: {
+    allItems: 'All Trees',
+    editor: 'Tree Editor',
+    newItem: 'New Tree',
+    searchPlaceholder: 'Search trees, sessions, tags\u2026',
+  },
+  procedures: {
+    allItems: 'All Procedures',
+    editor: 'Flow Editor',
+    newItem: 'New Procedure',
+    searchPlaceholder: 'Search procedures, runbooks\u2026',
+  },
+  policies: {
+    allItems: 'All Policies',
+    editor: 'Policy Editor',
+    newItem: 'New Policy',
+    searchPlaceholder: 'Search policies, compliance\u2026',
+  },
+  finance: {
+    allItems: 'All Finance Flows',
+    editor: 'Flow Editor',
+    newItem: 'New Flow',
+    searchPlaceholder: 'Search billing, procurement\u2026',
+  },
+}
+
+export const DEFAULT_LABELS: WorkspaceLabels = {
+  allItems: 'All Flows',
+  editor: 'Flow Editor',
+  newItem: 'New Flow',
+  searchPlaceholder: 'Search flows, sessions, tags\u2026',
+}
+
+export function getWorkspaceLabels(slug?: string): WorkspaceLabels {
+  if (slug && slug in WORKSPACE_LABELS) return WORKSPACE_LABELS[slug]
+  return DEFAULT_LABELS
+}
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -27,6 +27,7 @@
    --radius: 0.75rem;

    /* App Shell tokens */
+    --sidebar-w: 260px;
    --sidebar-bg: 240 10% 4.5%;
    --sidebar-hover: 240 6% 12%;
    --sidebar-active: 243 75% 59% / 0.08;
@@ -68,6 +69,50 @@
  }
 }

+/* App Shell Grid Layout */
+.app-shell {
+  display: grid;
+  grid-template-columns: var(--sidebar-w) 1fr;
+  grid-template-rows: 56px 1fr;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.topbar {
+  grid-column: 1 / -1;
+}
+
+.sidebar {
+  overflow-y: auto;
+}
+
+.main-content {
+  overflow-y: auto;
+}
+
+/* Mobile: single column */
+@media (max-width: 767px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* Staggered fade-in for page sections */
+.fade-in {
+  animation: fadeIn 0.3s ease forwards;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* Workspace switch dropdown */
+@keyframes dropIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
 /* Animations */
@keyframes fade-in {
  from { opacity: 0; }
--- a/frontend/src/store/workspaceStore.ts
+++ b/frontend/src/store/workspaceStore.ts
@@ -0,0 +1,50 @@
+import { create } from 'zustand'
+import type { Workspace } from '@/types'
+import { workspacesApi } from '@/api/workspaces'
+
+interface WorkspaceState {
+  workspaces: Workspace[]
+  activeWorkspaceId: string | null
+  loading: boolean
+  setActiveWorkspace: (id: string) => void
+  fetchWorkspaces: () => Promise<void>
+  getActiveWorkspace: () => Workspace | undefined
+}
+
+export const useWorkspaceStore = create<WorkspaceState>((set, get) => ({
+  workspaces: [],
+  activeWorkspaceId: localStorage.getItem('active-workspace-id'),
+  loading: false,
+
+  setActiveWorkspace: (id: string) => {
+    localStorage.setItem('active-workspace-id', id)
+    set({ activeWorkspaceId: id })
+  },
+
+  fetchWorkspaces: async () => {
+    set({ loading: true })
+    try {
+      const workspaces = await workspacesApi.list()
+      const state = get()
+      let activeId = state.activeWorkspaceId
+
+      // If no active workspace or active workspace doesn't exist, use default
+      if (!activeId || !workspaces.find(w => w.id === activeId)) {
+        const defaultWs = workspaces.find(w => w.is_default) || workspaces[0]
+        if (defaultWs) {
+          activeId = defaultWs.id
+          localStorage.setItem('active-workspace-id', activeId)
+        }
+      }
+
+      set({ workspaces, activeWorkspaceId: activeId, loading: false })
+    } catch {
+      set({ loading: false })
+    }
+  },
+
+  getActiveWorkspace: () => {
+    const { workspaces, activeWorkspaceId } = get()
+    return workspaces.find(w => w.id === activeWorkspaceId)
+  },
+}))
--- a/frontend/src/types/category.ts
+++ b/frontend/src/types/category.ts
@@ -8,6 +8,7 @@ export interface Category {
  account_id: string | null
  display_order: number
  is_active: boolean
+  color: string | null
  created_at: string
  updated_at: string
  tree_count: number
@@ -21,6 +22,7 @@ export interface CategoryListItem {
  account_id: string | null
  display_order: number
  is_active: boolean
+  color: string | null
  tree_count: number
 }

--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -8,6 +8,7 @@ export * from './category'
 export * from './folder'
 export * from './step'
 export type { Account, Subscription, PlanLimits, SubscriptionDetails, AccountInvite, AccountMember } from './account'
+export type { Workspace, WorkspaceCreate, WorkspaceUpdate } from './workspace'
 export * from './admin'

 // API response wrapper types
--- a/frontend/src/types/workspace.ts
+++ b/frontend/src/types/workspace.ts
@@ -0,0 +1,32 @@
+export interface Workspace {
+  id: string
+  name: string
+  slug: string
+  description: string | null
+  icon: string | null
+  accent_color: string | null
+  account_id: string
+  is_default: boolean
+  sort_order: number
+  tree_count: number
+  created_at: string
+  updated_at: string
+}
+
+export interface WorkspaceCreate {
+  name: string
+  slug: string
+  description?: string
+  icon?: string
+  accent_color?: string
+  sort_order?: number
+}
+
+export interface WorkspaceUpdate {
+  name?: string
+  slug?: string
+  description?: string
+  icon?: string
+  accent_color?: string
+  sort_order?: number
+}