feat(web): add teams page and RBAC navigation/route gating (MS21-UI-005, RBAC-001, RBAC-002)

apps/web/src/app/(authenticated)/settings/page.tsx

@@ -230,6 +230,7 @@ const categories: CategoryConfig[] = [
     title: "Teams",
     description: "Create and manage teams within your active workspace.",
     href: "/settings/teams",
+    adminOnly: true,
     accent: "var(--ms-blue-400)",
     iconBg: "rgba(47, 128, 255, 0.12)",
     icon: (

apps/web/src/app/(authenticated)/settings/teams/page.test.tsx

@@ -1,9 +1,12 @@
 import type { ReactElement, ReactNode } from "react";
 import type { TeamRecord } from "@/lib/api/teams";
 
-import { render, screen } from "@testing-library/react";
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { fetchTeams } from "@/lib/api/teams";
+import { createTeam, deleteTeam, fetchTeams, updateTeam } from "@/lib/api/teams";
+import { fetchUserWorkspaces } from "@/lib/api/workspaces";
 
 import TeamsSettingsPage from "./page";
 
@@ -22,9 +25,19 @@ vi.mock("next/link", () => ({
 vi.mock("@/lib/api/teams", () => ({
   fetchTeams: vi.fn(),
   createTeam: vi.fn(),
+  updateTeam: vi.fn(),
+  deleteTeam: vi.fn(),
+}));
+
+vi.mock("@/lib/api/workspaces", () => ({
+  fetchUserWorkspaces: vi.fn(),
 }));
 
 const fetchTeamsMock = vi.mocked(fetchTeams);
+const createTeamMock = vi.mocked(createTeam);
+const updateTeamMock = vi.mocked(updateTeam);
+const deleteTeamMock = vi.mocked(deleteTeam);
+const fetchUserWorkspacesMock = vi.mocked(fetchUserWorkspaces);
 
 const baseTeam: TeamRecord = {
   id: "team-1",
@@ -42,6 +55,33 @@ const baseTeam: TeamRecord = {
 describe("TeamsSettingsPage", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    fetchTeamsMock.mockResolvedValue([]);
+    fetchUserWorkspacesMock.mockResolvedValue([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.OWNER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+  });
+
+  it("shows access denied to non-admin users", async () => {
+    fetchUserWorkspacesMock.mockResolvedValueOnce([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.MEMBER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Access Denied")).toBeInTheDocument();
+    expect(fetchTeamsMock).not.toHaveBeenCalled();
   });
 
   it("loads and renders teams from the API", async () => {
@@ -49,9 +89,7 @@ describe("TeamsSettingsPage", () => {
 
     render(<TeamsSettingsPage />);
 
-    expect(screen.getByText("Loading teams...")).toBeInTheDocument();
+    expect(await screen.findByText("Team Directory")).toBeInTheDocument();
-
-    expect(await screen.findByText("Your Teams (1)")).toBeInTheDocument();
     expect(screen.getByText("Platform Team")).toBeInTheDocument();
     expect(fetchTeamsMock).toHaveBeenCalledTimes(1);
   });
@@ -61,8 +99,8 @@ describe("TeamsSettingsPage", () => {
 
     render(<TeamsSettingsPage />);
 
-    expect(await screen.findByText("Your Teams (0)")).toBeInTheDocument();
+    expect(await screen.findByText("No Teams Yet")).toBeInTheDocument();
-    expect(screen.getByText("No teams yet")).toBeInTheDocument();
+    expect(screen.getByText("Create the first team to get started.")).toBeInTheDocument();
   });
 
   it("shows error state and does not show empty state", async () => {
@@ -71,6 +109,82 @@ describe("TeamsSettingsPage", () => {
     render(<TeamsSettingsPage />);
 
     expect(await screen.findByText("Unable to load teams")).toBeInTheDocument();
-    expect(screen.queryByText("No teams yet")).not.toBeInTheDocument();
+  });
+
+  it("creates a team from the create dialog", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    createTeamMock.mockResolvedValue({
+      ...baseTeam,
+      id: "team-2",
+      name: "Design Team",
+      description: "Owns design quality",
+    });
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    const triggerButton = screen.getByRole("button", { name: "Create Team" });
+    await user.click(triggerButton);
+
+    await user.type(screen.getByLabelText("Name"), "Design Team");
+    await user.type(screen.getByLabelText("Description"), "Owns design quality");
+
+    const submitButton = screen.getAllByRole("button", { name: "Create Team" })[1];
+    if (!submitButton) {
+      throw new Error("Expected create-team submit button to be rendered");
+    }
+    await user.click(submitButton);
+
+    await waitFor(() => {
+      expect(createTeamMock).toHaveBeenCalledWith({
+        name: "Design Team",
+        description: "Owns design quality",
+      });
+    });
+  });
+
+  it("opens team details and updates name", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    updateTeamMock.mockResolvedValue({
+      ...baseTeam,
+      name: "Platform Engineering",
+    });
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    await user.click(screen.getByText("Platform Team"));
+
+    const nameInput = await screen.findByLabelText("Name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Platform Engineering");
+    await user.click(screen.getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(updateTeamMock).toHaveBeenCalledWith("team-1", {
+        name: "Platform Engineering",
+      });
+    });
+  });
+
+  it("deletes a team from the confirmation dialog", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    deleteTeamMock.mockResolvedValue();
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Delete" }));
+    await user.click(screen.getByRole("button", { name: "Delete Team" }));
+
+    await waitFor(() => {
+      expect(deleteTeamMock).toHaveBeenCalledWith("team-1");
+    });
   });
 });

apps/web/src/app/(authenticated)/settings/teams/page.tsx

@@ -1,244 +1,582 @@
 "use client";
 
-import type { ReactElement, SyntheticEvent } from "react";
+import {
-
+  useCallback,
-import { useCallback, useEffect, useState } from "react";
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+  type ReactElement,
+  type SyntheticEvent,
+} from "react";
 import Link from "next/link";
-import { createTeam, fetchTeams, type CreateTeamDto, type TeamRecord } from "@/lib/api/teams";
+import { Plus, Trash2, Users } from "lucide-react";
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { SettingsAccessDenied } from "@/components/settings/SettingsAccessDenied";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import {
+  createTeam,
+  deleteTeam,
+  fetchTeams,
+  updateTeam,
+  type CreateTeamDto,
+  type TeamRecord,
+  type UpdateTeamDto,
+} from "@/lib/api/teams";
+import { fetchUserWorkspaces } from "@/lib/api/workspaces";
 
-function getErrorMessage(error: unknown, fallback: string): string {
+const INITIAL_CREATE_FORM = {
-  if (error instanceof Error) {
+  name: "",
-    return error.message;
+  description: "",
+};
+
+const INITIAL_DETAIL_FORM = {
+  name: "",
+  description: "",
+};
+
+interface DetailInitialState {
+  name: string;
+  description: string;
 }
 
-  return fallback;
+function toMemberLabel(count: number): string {
+  return `${String(count)} member${count === 1 ? "" : "s"}`;
 }
 
 export default function TeamsSettingsPage(): ReactElement {
   const [teams, setTeams] = useState<TeamRecord[]>([]);
-  const [isLoading, setIsLoading] = useState(true);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
-  const [loadError, setLoadError] = useState<string | null>(null);
+  const [isRefreshing, setIsRefreshing] = useState<boolean>(false);
-  const [isCreateDialogOpen, setIsCreateDialogOpen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
-  const [isCreating, setIsCreating] = useState(false);
+  const [isAdmin, setIsAdmin] = useState<boolean | null>(null);
-  const [newTeamName, setNewTeamName] = useState("");
+
-  const [newTeamDescription, setNewTeamDescription] = useState("");
+  const [isCreateOpen, setIsCreateOpen] = useState<boolean>(false);
+  const [createForm, setCreateForm] = useState(INITIAL_CREATE_FORM);
   const [createError, setCreateError] = useState<string | null>(null);
+  const [isCreating, setIsCreating] = useState<boolean>(false);
 
-  const loadTeams = useCallback(async (): Promise<void> => {
+  const [detailTarget, setDetailTarget] = useState<TeamRecord | null>(null);
-    setIsLoading(true);
+  const [detailForm, setDetailForm] = useState(INITIAL_DETAIL_FORM);
+  const [detailInitial, setDetailInitial] = useState<DetailInitialState | null>(null);
+  const [detailError, setDetailError] = useState<string | null>(null);
+  const [isSavingDetails, setIsSavingDetails] = useState<boolean>(false);
 
+  const [deleteTarget, setDeleteTarget] = useState<TeamRecord | null>(null);
+  const [isDeleting, setIsDeleting] = useState<boolean>(false);
+
+  const loadTeams = useCallback(async (showLoadingState: boolean): Promise<void> => {
     try {
+      if (showLoadingState) {
+        setIsLoading(true);
+      } else {
+        setIsRefreshing(true);
+      }
+
       const data = await fetchTeams();
       setTeams(data);
-      setLoadError(null);
+      setError(null);
-    } catch (error) {
+    } catch (err: unknown) {
-      setLoadError(getErrorMessage(error, "Failed to load teams"));
+      setError(err instanceof Error ? err.message : "Failed to load teams");
     } finally {
       setIsLoading(false);
+      setIsRefreshing(false);
     }
   }, []);
 
   useEffect(() => {
-    void loadTeams();
+    fetchUserWorkspaces()
-  }, [loadTeams]);
+      .then((workspaces) => {
+        const adminRoles: WorkspaceMemberRole[] = [
+          WorkspaceMemberRole.OWNER,
+          WorkspaceMemberRole.ADMIN,
+        ];
 
-  const handleCreateTeam = async (e: SyntheticEvent<HTMLFormElement>): Promise<void> => {
+        setIsAdmin(workspaces.some((workspace) => adminRoles.includes(workspace.role)));
-    e.preventDefault();
+      })
+      .catch(() => {
+        setIsAdmin(true); // fail open
+      });
+  }, []);
 
-    const teamName = newTeamName.trim();
+  useEffect(() => {
-    if (!teamName) return;
+    if (isAdmin !== true) {
+      return;
+    }
 
-    setIsCreating(true);
+    void loadTeams(true);
+  }, [isAdmin, loadTeams]);
+
+  function resetCreateForm(): void {
+    setCreateForm(INITIAL_CREATE_FORM);
+    setCreateError(null);
+  }
+
+  function openTeamDetails(team: TeamRecord): void {
+    const nextDetailForm = {
+      name: team.name,
+      description: team.description ?? "",
+    };
+
+    setDetailTarget(team);
+    setDetailForm(nextDetailForm);
+    setDetailInitial({
+      name: nextDetailForm.name,
+      description: nextDetailForm.description,
+    });
+    setDetailError(null);
+  }
+
+  function resetTeamDetails(): void {
+    setDetailTarget(null);
+    setDetailForm(INITIAL_DETAIL_FORM);
+    setDetailInitial(null);
+    setDetailError(null);
+  }
+
+  function handleTeamRowKeyDown(event: KeyboardEvent<HTMLDivElement>, team: TeamRecord): void {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      openTeamDetails(team);
+    }
+  }
+
+  async function handleCreateSubmit(event: SyntheticEvent): Promise<void> {
+    event.preventDefault();
     setCreateError(null);
 
-    try {
+    const name = createForm.name.trim();
-      const description = newTeamDescription.trim();
+    if (!name) {
-      const dto: CreateTeamDto = { name: teamName };
+      setCreateError("Name is required.");
-      if (description.length > 0) {
+      return;
+    }
+
+    const description = createForm.description.trim();
+    const dto: CreateTeamDto = { name };
+    if (description) {
       dto.description = description;
     }
 
+    try {
+      setIsCreating(true);
       await createTeam(dto);
-      setNewTeamName("");
+      setIsCreateOpen(false);
-      setNewTeamDescription("");
+      resetCreateForm();
-      setIsCreateDialogOpen(false);
+      await loadTeams(false);
-      await loadTeams();
+    } catch (err: unknown) {
-    } catch (error) {
+      setCreateError(err instanceof Error ? err.message : "Failed to create team");
-      setCreateError(getErrorMessage(error, "Failed to create team"));
     } finally {
       setIsCreating(false);
     }
-  };
-
-  return (
-    <main className="container mx-auto px-4 py-8 max-w-5xl">
-      <div className="mb-8">
-        <div className="flex items-center justify-between mb-2">
-          <h1 className="text-3xl font-bold text-gray-900">Teams</h1>
-          <Link href="/settings" className="text-sm text-blue-600 hover:text-blue-700">
-            {"<-"} Back to Settings
-          </Link>
-        </div>
-        <p className="text-gray-600">Manage teams in your active workspace</p>
-      </div>
-
-      <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6 mb-6">
-        <div className="flex items-center justify-between gap-4">
-          <div>
-            <h2 className="text-lg font-semibold text-gray-900">Create New Team</h2>
-            <p className="text-sm text-gray-600 mt-1">
-              Add a team to organize members and permissions.
-            </p>
-          </div>
-          <button
-            type="button"
-            onClick={() => {
-              setCreateError(null);
-              setIsCreateDialogOpen(true);
-            }}
-            className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 font-medium"
-          >
-            Create Team
-          </button>
-        </div>
-      </div>
-
-      {isCreateDialogOpen && (
-        <div
-          className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 px-4"
-          role="dialog"
-        >
-          <div className="w-full max-w-lg rounded-lg border border-gray-200 bg-white p-6 shadow-xl">
-            <h3 className="text-lg font-semibold text-gray-900">Create New Team</h3>
-            <p className="mt-1 text-sm text-gray-600">
-              Enter a team name and optional description.
-            </p>
-
-            <form onSubmit={handleCreateTeam} className="mt-4 space-y-4">
-              <div>
-                <label htmlFor="team-name" className="mb-1 block text-sm font-medium text-gray-700">
-                  Team Name
-                </label>
-                <input
-                  id="team-name"
-                  type="text"
-                  value={newTeamName}
-                  onChange={(e) => {
-                    setNewTeamName(e.target.value);
-                  }}
-                  placeholder="Enter team name..."
-                  disabled={isCreating}
-                  className="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
-                  autoFocus
-                />
-              </div>
-
-              <div>
-                <label
-                  htmlFor="team-description"
-                  className="mb-1 block text-sm font-medium text-gray-700"
-                >
-                  Description (optional)
-                </label>
-                <textarea
-                  id="team-description"
-                  value={newTeamDescription}
-                  onChange={(e) => {
-                    setNewTeamDescription(e.target.value);
-                  }}
-                  placeholder="Describe this team's purpose..."
-                  disabled={isCreating}
-                  rows={3}
-                  className="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
-                />
-              </div>
-
-              {createError !== null && (
-                <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700">
-                  {createError}
-                </div>
-              )}
-
-              <div className="flex justify-end gap-3">
-                <button
-                  type="button"
-                  onClick={() => {
-                    if (!isCreating) {
-                      setIsCreateDialogOpen(false);
   }
-                  }}
-                  disabled={isCreating}
-                  className="px-4 py-2 rounded-lg border border-gray-300 text-gray-700 hover:bg-gray-50 disabled:cursor-not-allowed"
-                >
-                  Cancel
-                </button>
-                <button
-                  type="submit"
-                  disabled={isCreating || !newTeamName.trim()}
-                  className="px-5 py-2 rounded-lg bg-blue-600 text-white font-medium hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-50"
-                >
-                  {isCreating ? "Creating..." : "Create Team"}
-                </button>
-              </div>
-            </form>
-          </div>
-        </div>
-      )}
 
-      <div className="space-y-4">
+  async function handleDetailSubmit(event: SyntheticEvent): Promise<void> {
-        <h2 className="text-xl font-semibold text-gray-900">
+    event.preventDefault();
-          Your Teams ({isLoading ? "..." : teams.length})
+
-        </h2>
+    if (detailTarget === null || detailInitial === null) {
-        {loadError !== null ? (
+      return;
-          <div className="rounded-md border border-red-200 bg-red-50 px-4 py-3 text-red-700">
+    }
-            {loadError}
+
-          </div>
+    const name = detailForm.name.trim();
-        ) : isLoading ? (
+    if (!name) {
-          <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-12 text-center text-gray-600">
+      setDetailError("Name is required.");
-            Loading teams...
+      return;
-          </div>
+    }
-        ) : teams.length === 0 ? (
+
-          <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-12 text-center">
+    const nextDescription = detailForm.description.trim();
-            <svg
+    const normalizedNextDescription = nextDescription.length > 0 ? nextDescription : null;
-              className="mx-auto h-12 w-12 text-gray-400 mb-4"
+    const normalizedInitialDescription =
-              fill="none"
+      detailInitial.description.trim().length > 0 ? detailInitial.description.trim() : null;
-              stroke="currentColor"
+
-              viewBox="0 0 24 24"
+    const dto: UpdateTeamDto = {};
-            >
+
-              <path
+    if (name !== detailInitial.name) {
-                strokeLinecap="round"
+      dto.name = name;
-                strokeLinejoin="round"
+    }
-                strokeWidth={2}
+
-                d="M17 20h5V8H2v12h5m10 0v-4a3 3 0 10-6 0v4m6 0H7"
+    if (normalizedNextDescription !== normalizedInitialDescription) {
-              />
+      dto.description = normalizedNextDescription;
-            </svg>
+    }
-            <h3 className="text-lg font-medium text-gray-900 mb-2">No teams yet</h3>
+
-            <p className="text-gray-600">Create your first team to get started</p>
+    if (Object.keys(dto).length === 0) {
-          </div>
+      resetTeamDetails();
-        ) : (
+      return;
-          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+    }
-            {teams.map((team) => (
+
-              <article
+    try {
-                key={team.id}
+      setIsSavingDetails(true);
-                className="rounded-lg border border-gray-200 bg-white p-5 shadow-sm"
+      setDetailError(null);
-                data-testid="team-card"
+      await updateTeam(detailTarget.id, dto);
-              >
+      resetTeamDetails();
-                <h3 className="text-lg font-semibold text-gray-900">{team.name}</h3>
+      await loadTeams(false);
-                {team.description ? (
+    } catch (err: unknown) {
-                  <p className="mt-1 text-sm text-gray-600">{team.description}</p>
+      setDetailError(err instanceof Error ? err.message : "Failed to update team");
-                ) : (
+    } finally {
-                  <p className="mt-1 text-sm text-gray-400 italic">No description</p>
+      setIsSavingDetails(false);
-                )}
+    }
-                <div className="mt-4 flex items-center gap-3 text-xs text-gray-500">
+  }
-                  <span>{team._count?.members ?? 0} members</span>
+
-                  <span>|</span>
+  async function confirmDelete(): Promise<void> {
-                  <span>Created {new Date(team.createdAt).toLocaleDateString()}</span>
+    if (!deleteTarget) {
-                </div>
+      return;
-              </article>
+    }
-            ))}
+
-          </div>
+    try {
-        )}
+      setIsDeleting(true);
-      </div>
+      await deleteTeam(deleteTarget.id);
-    </main>
+      setDeleteTarget(null);
+      await loadTeams(false);
+      setError(null);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to delete team");
+    } finally {
+      setIsDeleting(false);
+    }
+  }
+
+  if (isAdmin === null) {
+    return (
+      <Card className="max-w-2xl mx-auto mt-8">
+        <CardContent className="py-12 text-center text-muted-foreground">
+          Checking permissions...
+        </CardContent>
+      </Card>
+    );
+  }
+
+  if (!isAdmin) {
+    return <SettingsAccessDenied message="You need Admin or Owner role to manage teams." />;
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto p-6 space-y-6">
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <div className="flex items-center gap-3">
+            <h1 className="text-3xl font-bold">Teams</h1>
+            <Badge variant="outline">{teams.length} total</Badge>
+          </div>
+          <p className="text-muted-foreground mt-1">Create and manage workspace teams</p>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            onClick={() => {
+              void loadTeams(false);
+            }}
+            disabled={isLoading || isRefreshing}
+          >
+            {isRefreshing ? "Refreshing..." : "Refresh"}
+          </Button>
+
+          <Dialog
+            open={isCreateOpen}
+            onOpenChange={(open) => {
+              if (!open && !isCreating) {
+                resetCreateForm();
+              }
+              setIsCreateOpen(open);
+            }}
+          >
+            <DialogTrigger asChild>
+              <Button>
+                <Plus className="h-4 w-4 mr-2" />
+                Create Team
+              </Button>
+            </DialogTrigger>
+            <DialogContent>
+              <DialogHeader>
+                <DialogTitle>Create Team</DialogTitle>
+                <DialogDescription>
+                  Create a team in the active workspace to organize members and permissions.
+                </DialogDescription>
+              </DialogHeader>
+
+              <form
+                onSubmit={(event) => {
+                  void handleCreateSubmit(event);
+                }}
+                className="space-y-4"
+              >
+                <div className="space-y-2">
+                  <Label htmlFor="create-name">Name</Label>
+                  <Input
+                    id="create-name"
+                    value={createForm.name}
+                    onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                      setCreateForm((prev) => ({ ...prev, name: event.target.value }));
+                    }}
+                    placeholder="Platform Team"
+                    maxLength={100}
+                    required
+                  />
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="create-description">Description</Label>
+                  <Textarea
+                    id="create-description"
+                    value={createForm.description}
+                    onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+                      setCreateForm((prev) => ({ ...prev, description: event.target.value }));
+                    }}
+                    placeholder="Owns platform services and infrastructure"
+                    maxLength={500}
+                    rows={4}
+                  />
+                </div>
+
+                {createError ? (
+                  <p className="text-sm text-destructive" role="alert">
+                    {createError}
+                  </p>
+                ) : null}
+
+                <DialogFooter>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    onClick={() => {
+                      if (!isCreating) {
+                        setIsCreateOpen(false);
+                        resetCreateForm();
+                      }
+                    }}
+                    disabled={isCreating}
+                  >
+                    Cancel
+                  </Button>
+                  <Button type="submit" disabled={isCreating}>
+                    {isCreating ? "Creating..." : "Create Team"}
+                  </Button>
+                </DialogFooter>
+              </form>
+            </DialogContent>
+          </Dialog>
+        </div>
+      </div>
+
+      <div>
+        <Link href="/settings" className="text-sm text-blue-600 hover:text-blue-700">
+          ← Back to Settings
+        </Link>
+      </div>
+
+      {error ? (
+        <Card>
+          <CardContent className="py-4">
+            <p className="text-sm text-destructive" role="alert">
+              {error}
+            </p>
+          </CardContent>
+        </Card>
+      ) : null}
+
+      {isLoading ? (
+        <Card>
+          <CardContent className="py-12 text-center text-muted-foreground">
+            Loading teams...
+          </CardContent>
+        </Card>
+      ) : teams.length === 0 ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>No Teams Yet</CardTitle>
+            <CardDescription>Create the first team to get started.</CardDescription>
+          </CardHeader>
+        </Card>
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Team Directory</CardTitle>
+            <CardDescription>
+              Click a team to view details or edit name and description.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-3">
+            {teams.map((team) => {
+              const memberCount = team._count?.members ?? 0;
+              const description = team.description?.trim();
+
+              return (
+                <div
+                  key={team.id}
+                  className="rounded-md border p-4 flex flex-col gap-3 md:flex-row md:items-center md:justify-between cursor-pointer hover:bg-muted/30"
+                  role="button"
+                  tabIndex={0}
+                  onClick={() => {
+                    openTeamDetails(team);
+                  }}
+                  onKeyDown={(event) => {
+                    handleTeamRowKeyDown(event, team);
+                  }}
+                >
+                  <div className="space-y-1 min-w-0">
+                    <p className="font-semibold truncate">{team.name}</p>
+                    <p className="text-sm text-muted-foreground truncate">
+                      {description && description.length > 0 ? description : "No description"}
+                    </p>
+                  </div>
+
+                  <div className="flex items-center gap-2 flex-wrap md:justify-end">
+                    <Badge variant="outline">
+                      <Users className="h-3.5 w-3.5 mr-1" />
+                      {toMemberLabel(memberCount)}
+                    </Badge>
+                    <Badge variant="secondary">
+                      Created {new Date(team.createdAt).toLocaleDateString()}
+                    </Badge>
+                    <Button
+                      variant="destructive"
+                      size="sm"
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        setDeleteTarget(team);
+                      }}
+                    >
+                      <Trash2 className="h-4 w-4 mr-2" />
+                      Delete
+                    </Button>
+                  </div>
+                </div>
+              );
+            })}
+          </CardContent>
+        </Card>
+      )}
+
+      <Dialog
+        open={detailTarget !== null}
+        onOpenChange={(open) => {
+          if (!open && !isSavingDetails) {
+            resetTeamDetails();
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Team Details</DialogTitle>
+            <DialogDescription>
+              Edit team details for {detailTarget?.name ?? "selected team"}.
+            </DialogDescription>
+          </DialogHeader>
+
+          <form
+            onSubmit={(event) => {
+              void handleDetailSubmit(event);
+            }}
+            className="space-y-4"
+          >
+            <div className="space-y-2">
+              <Label htmlFor="detail-name">Name</Label>
+              <Input
+                id="detail-name"
+                value={detailForm.name}
+                onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                  setDetailForm((prev) => ({ ...prev, name: event.target.value }));
+                }}
+                placeholder="Team name"
+                maxLength={100}
+                disabled={isSavingDetails}
+                required
+              />
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="detail-description">Description</Label>
+              <Textarea
+                id="detail-description"
+                value={detailForm.description}
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+                  setDetailForm((prev) => ({ ...prev, description: event.target.value }));
+                }}
+                placeholder="Describe this team"
+                maxLength={500}
+                rows={4}
+                disabled={isSavingDetails}
+              />
+            </div>
+
+            {detailError !== null ? (
+              <p className="text-sm text-destructive" role="alert">
+                {detailError}
+              </p>
+            ) : null}
+
+            <DialogFooter>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => {
+                  if (!isSavingDetails) {
+                    resetTeamDetails();
+                  }
+                }}
+                disabled={isSavingDetails}
+              >
+                Cancel
+              </Button>
+              <Button type="submit" disabled={isSavingDetails}>
+                {isSavingDetails ? "Saving..." : "Save Changes"}
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+
+      <AlertDialog
+        open={deleteTarget !== null}
+        onOpenChange={(open) => {
+          if (!open && !isDeleting) {
+            setDeleteTarget(null);
+          }
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete Team</AlertDialogTitle>
+            <AlertDialogDescription>
+              Delete {deleteTarget?.name}? Team members will be removed from this team assignment.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={isDeleting}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              disabled={isDeleting}
+              onClick={() => {
+                void confirmDelete();
+              }}
+            >
+              {isDeleting ? "Deleting..." : "Delete Team"}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
   );
 }

apps/web/src/app/(authenticated)/settings/users/page.test.tsx

@@ -118,6 +118,23 @@ describe("UsersSettingsPage", () => {
     });
   });
 
+  it("shows access denied to non-admin users", async () => {
+    fetchUserWorkspacesMock.mockResolvedValueOnce([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.MEMBER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("Access Denied")).toBeInTheDocument();
+    expect(fetchAdminUsersMock).not.toHaveBeenCalled();
+  });
+
   it("invites a user with email and role from the dialog", async () => {
     const user = userEvent.setup();
     render(<UsersSettingsPage />);

apps/web/src/app/(authenticated)/settings/users/page.tsx

@@ -56,6 +56,7 @@ import {
   type UpdateUserDto,
 } from "@/lib/api/admin";
 import { fetchUserWorkspaces, updateWorkspaceMemberRole } from "@/lib/api/workspaces";
+import { SettingsAccessDenied } from "@/components/settings/SettingsAccessDenied";
 
 const ROLE_PRIORITY: Record<WorkspaceMemberRole, number> = {
   [WorkspaceMemberRole.OWNER]: 4,
@@ -146,10 +147,6 @@ export default function UsersSettingsPage(): ReactElement {
     }
   }, []);
 
-  useEffect(() => {
-    void loadUsers(true);
-  }, [loadUsers]);
-
   useEffect(() => {
     fetchUserWorkspaces()
       .then((workspaces) => {
@@ -167,6 +164,14 @@ export default function UsersSettingsPage(): ReactElement {
       });
   }, []);
 
+  useEffect(() => {
+    if (isAdmin !== true) {
+      return;
+    }
+
+    void loadUsers(true);
+  }, [isAdmin, loadUsers]);
+
   function resetInviteForm(): void {
     setInviteForm(INITIAL_INVITE_FORM);
     setInviteError(null);
@@ -332,17 +337,20 @@ export default function UsersSettingsPage(): ReactElement {
     }
   }
 
-  if (isAdmin === false) {
+  if (isAdmin === null) {
     return (
-      <div className="p-8 max-w-2xl">
+      <Card className="max-w-2xl mx-auto mt-8">
-        <div className="rounded-lg border border-red-200 bg-red-50 p-6 text-center">
+        <CardContent className="py-12 text-center text-muted-foreground">
-          <p className="text-lg font-semibold text-red-700">Access Denied</p>
+          Checking permissions...
-          <p className="mt-2 text-sm text-red-600">You need Admin or Owner role to manage users.</p>
+        </CardContent>
-        </div>
+      </Card>
-      </div>
     );
   }
 
+  if (!isAdmin) {
+    return <SettingsAccessDenied message="You need Admin or Owner role to manage users." />;
+  }
+
   return (
     <div className="max-w-6xl mx-auto p-6 space-y-6">
       <div className="flex items-start justify-between gap-4">

apps/web/src/components/settings/SettingsAccessDenied.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+
+interface SettingsAccessDeniedProps {
+  message: string;
+}
+
+export function SettingsAccessDenied({ message }: SettingsAccessDeniedProps): ReactElement {
+  return (
+    <div className="p-8 max-w-2xl">
+      <div className="rounded-lg border border-red-200 bg-red-50 p-6 text-center">
+        <p className="text-lg font-semibold text-red-700">Access Denied</p>
+        <p className="mt-2 text-sm text-red-600">{message}</p>
+      </div>
+    </div>
+  );
+}

apps/web/src/lib/api/teams.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import * as client from "./client";
-import { fetchTeams, createTeam, fetchTeamMembers } from "./teams";
+import { fetchTeams, createTeam, fetchTeamMembers, updateTeam, deleteTeam } from "./teams";
 
 vi.mock("./client");
 
@@ -44,6 +44,18 @@ describe("createTeam", (): void => {
   });
 });
 
+describe("updateTeam", (): void => {
+  it("patches team endpoint", async (): Promise<void> => {
+    vi.mocked(client.apiPatch).mockResolvedValueOnce({ id: "t1", name: "Platform" } as never);
+    await updateTeam("t1", { name: "Platform" });
+    expect(client.apiPatch).toHaveBeenCalledWith(
+      "/api/workspaces/ws-1/teams/t1",
+      expect.objectContaining({ name: "Platform" }),
+      "ws-1"
+    );
+  });
+});
+
 describe("fetchTeamMembers", (): void => {
   it("calls members endpoint for team", async (): Promise<void> => {
     vi.mocked(client.apiGet).mockResolvedValueOnce([] as never);
@@ -51,3 +63,11 @@ describe("fetchTeamMembers", (): void => {
     expect(client.apiGet).toHaveBeenCalledWith("/api/workspaces/ws-1/teams/t-1/members", "ws-1");
   });
 });
+
+describe("deleteTeam", (): void => {
+  it("deletes team endpoint", async (): Promise<void> => {
+    vi.mocked(client.apiDelete).mockResolvedValueOnce(undefined as never);
+    await deleteTeam("t1");
+    expect(client.apiDelete).toHaveBeenCalledWith("/api/workspaces/ws-1/teams/t1", "ws-1");
+  });
+});

apps/web/src/lib/api/teams.ts

@@ -4,7 +4,7 @@
  */
 
 import type { TeamMemberRole } from "@mosaic/shared";
-import { apiDelete, apiGet, apiPost } from "./client";
+import { apiDelete, apiGet, apiPatch, apiPost } from "./client";
 
 const WORKSPACE_STORAGE_KEY = "mosaic-workspace-id";
 
@@ -55,6 +55,11 @@ export interface CreateTeamDto {
   description?: string;
 }
 
+export interface UpdateTeamDto {
+  name?: string;
+  description?: string | null;
+}
+
 export interface AddTeamMemberDto {
   userId: string;
   role?: TeamMemberRole;
@@ -80,6 +85,22 @@ export async function createTeam(dto: CreateTeamDto, workspaceId?: string): Prom
   );
 }
 
+/**
+ * Update a team in the active workspace.
+ */
+export async function updateTeam(
+  teamId: string,
+  dto: UpdateTeamDto,
+  workspaceId?: string
+): Promise<TeamRecord> {
+  const resolvedWorkspaceId = resolveWorkspaceId(workspaceId);
+  return apiPatch<TeamRecord>(
+    `/api/workspaces/${resolvedWorkspaceId}/teams/${teamId}`,
+    dto,
+    resolvedWorkspaceId
+  );
+}
+
 /**
  * Fetch team members for a team in the active workspace.
  * The current backend route shape is workspace-scoped team membership.