Merge pull request #252 from 0xjjjjjj/fix/mobile-responsive

fix: mobile-responsive layout, Bun builds, z-index fixes

frontend/cypress/e2e/mobile_sidebar.cy.ts

@@ -0,0 +1,155 @@
+/// <reference types="cypress" />
+
+import { setupCommonPageTestHooks } from "../support/testHooks";
+
+describe("/dashboard - mobile sidebar", () => {
+  const apiBase = "**/api/v1";
+
+  setupCommonPageTestHooks(apiBase);
+
+  const emptySeries = {
+    primary: { range: "7d", bucket: "day", points: [] },
+    comparison: { range: "7d", bucket: "day", points: [] },
+  };
+
+  function stubDashboardApis() {
+    cy.intercept("GET", `${apiBase}/metrics/dashboard*`, {
+      statusCode: 200,
+      body: {
+        generated_at: new Date().toISOString(),
+        range: "7d",
+        kpis: {
+          inbox_tasks: 0,
+          in_progress_tasks: 0,
+          review_tasks: 0,
+          done_tasks: 0,
+          tasks_in_progress: 0,
+          active_agents: 0,
+          error_rate_pct: 0,
+          median_cycle_time_hours_7d: null,
+        },
+        throughput: emptySeries,
+        cycle_time: emptySeries,
+        error_rate: emptySeries,
+        wip: emptySeries,
+        pending_approvals: { items: [], total: 0 },
+      },
+    }).as("dashboardMetrics");
+
+    cy.intercept("GET", `${apiBase}/boards*`, {
+      statusCode: 200,
+      body: { items: [], total: 0 },
+    }).as("boardsList");
+
+    cy.intercept("GET", `${apiBase}/agents*`, {
+      statusCode: 200,
+      body: { items: [], total: 0 },
+    }).as("agentsList");
+
+    cy.intercept("GET", `${apiBase}/activity*`, {
+      statusCode: 200,
+      body: { items: [], total: 0 },
+    }).as("activityList");
+
+    cy.intercept("GET", `${apiBase}/gateways/status*`, {
+      statusCode: 200,
+      body: { gateways: [] },
+    }).as("gatewaysStatus");
+
+    cy.intercept("GET", `${apiBase}/board-groups*`, {
+      statusCode: 200,
+      body: { items: [], total: 0 },
+    }).as("boardGroupsList");
+  }
+
+  function visitDashboardAuthenticated() {
+    stubDashboardApis();
+    cy.loginWithLocalAuth();
+    cy.visit("/dashboard");
+    cy.waitForAppLoaded();
+  }
+
+  it("auth negative: signed-out user does not see hamburger button", () => {
+    cy.visit("/dashboard");
+    cy.contains("h1", /local authentication/i, { timeout: 30_000 }).should(
+      "be.visible",
+    );
+    cy.get('[aria-label="Toggle navigation"]').should("not.exist");
+  });
+
+  it("mobile: hamburger button visible and sidebar hidden by default", () => {
+    cy.viewport(375, 812);
+    visitDashboardAuthenticated();
+
+    cy.get('[aria-label="Toggle navigation"]').should("be.visible");
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "closed");
+    cy.get("aside").should("not.be.visible");
+  });
+
+  it("desktop: hamburger button hidden and sidebar always visible", () => {
+    cy.viewport(1280, 800);
+    visitDashboardAuthenticated();
+
+    cy.get('[aria-label="Toggle navigation"]').should("not.be.visible");
+    cy.get("aside").should("be.visible");
+  });
+
+  it("mobile: click hamburger opens sidebar and shows backdrop", () => {
+    cy.viewport(375, 812);
+    visitDashboardAuthenticated();
+
+    cy.get('[aria-label="Toggle navigation"]').click();
+
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "open");
+    cy.get("aside").should("be.visible");
+    cy.get('[data-cy="sidebar-backdrop"]').should("exist");
+  });
+
+  it("mobile: click backdrop closes sidebar", () => {
+    cy.viewport(375, 812);
+    visitDashboardAuthenticated();
+
+    // Open sidebar first
+    cy.get('[aria-label="Toggle navigation"]').click();
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "open");
+
+    // Click the backdrop overlay
+    cy.get('[data-cy="sidebar-backdrop"]').click({ force: true });
+
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "closed");
+    cy.get("aside").should("not.be.visible");
+  });
+
+  it("mobile: clicking a nav link closes sidebar", () => {
+    cy.viewport(375, 812);
+    visitDashboardAuthenticated();
+
+    // Open sidebar
+    cy.get('[aria-label="Toggle navigation"]').click();
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "open");
+    cy.get("aside").should("be.visible");
+
+    // Click a navigation link inside the sidebar
+    cy.get("aside").within(() => {
+      cy.contains("a", "Boards").click();
+    });
+
+    // Sidebar should close after navigation
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "closed");
+  });
+
+  it("mobile: pressing Escape closes sidebar", () => {
+    cy.viewport(375, 812);
+    visitDashboardAuthenticated();
+
+    // Open sidebar
+    cy.get('[aria-label="Toggle navigation"]').click();
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "open");
+
+    // Press Escape
+    cy.get("body").type("{esc}");
+
+    cy.get("[data-sidebar]").should("have.attr", "data-sidebar", "closed");
+    cy.get("aside").should("not.be.visible");
+  });
+});

frontend/src/app/activity/page.tsx

@@ -1508,7 +1508,7 @@ export default function ActivityPage() {
             <DashboardSidebar />
             <main className="flex-1 overflow-y-auto bg-slate-50">
               <div className="sticky top-0 z-30 border-b border-slate-200 bg-white">
-                <div className="px-8 py-6">
+                <div className="px-4 py-4 md:px-8 md:py-6">
                   <div className="flex flex-wrap items-center justify-between gap-4">
                     <div>
                       <div className="flex items-center gap-2">
@@ -1526,7 +1526,7 @@ export default function ActivityPage() {
                 </div>
               </div>
 
-              <div className="p-8">
+              <div className="p-4 md:p-8">
                 {hasUnresolvedDeepLink ? (
                   <div className="mb-4 rounded-lg border border-amber-300 bg-amber-50 p-3 text-sm text-amber-800">
                     Requested activity item is not in the current feed window yet.

frontend/src/app/agents/[agentId]/page.tsx

@@ -162,13 +162,13 @@ export default function AgentDetailPage() {
       <SignedIn>
         <DashboardSidebar />
         {!isAdmin ? (
-          <div className="flex h-full flex-col gap-6 rounded-2xl surface-panel p-8">
+          <div className="flex h-full flex-col gap-6 rounded-2xl surface-panel p-4 md:p-8">
             <div className="rounded-xl border border-[color:var(--border)] bg-[color:var(--surface)] px-6 py-5 text-sm text-muted">
               Only organization owners and admins can access agents.
             </div>
           </div>
         ) : (
-          <div className="flex h-full flex-col gap-6 rounded-2xl surface-panel p-8">
+          <div className="flex h-full flex-col gap-6 rounded-2xl surface-panel p-4 md:p-8">
             <div className="flex flex-wrap items-start justify-between gap-4">
               <div className="space-y-2">
                 <p className="text-xs font-semibold uppercase tracking-[0.3em] text-quiet">

frontend/src/app/approvals/page.tsx

@@ -167,8 +167,8 @@ function GlobalApprovalsInner() {
 
   return (
     <main className="flex-1 overflow-y-auto bg-gradient-to-br from-slate-50 to-slate-100">
-      <div className="p-6">
+      <div className="p-4 md:p-6">
-        <div className="h-[calc(100vh-160px)] min-h-[520px]">
+        <div className="h-[calc(100vh-160px)] min-h-[300px] sm:min-h-[520px]">
           <BoardApprovalsPanel
             boardId="global"
             approvals={approvals}

frontend/src/app/board-groups/[groupId]/page.tsx

@@ -744,7 +744,7 @@ export default function BoardGroupDetailPage() {
         <DashboardSidebar />
         <main className="flex-1 overflow-y-auto bg-slate-50">
           <div className="sticky top-0 z-30 border-b border-slate-200 bg-white shadow-sm">
-            <div className="px-8 py-6">
+            <div className="px-4 py-4 md:px-8 md:py-6">
               <div className="flex flex-wrap items-start justify-between gap-4">
                 <div className="min-w-0">
                   <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
@@ -816,7 +816,7 @@ export default function BoardGroupDetailPage() {
                 </div>
               </div>
 
-              <div className="mt-5 flex flex-wrap items-center gap-3">
+              <div className="mt-5 flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center">
                 <label className="inline-flex items-center gap-2 text-sm text-slate-700">
                   <input
                     type="checkbox"
@@ -948,7 +948,7 @@ export default function BoardGroupDetailPage() {
             </div>
           </div>
 
-          <div className="p-8">
+          <div className="p-4 md:p-8">
             <div className="space-y-6">
               {heartbeatApplyError ? (
                 <div className="rounded-xl border border-rose-200 bg-rose-50 p-4 text-sm text-rose-700 shadow-sm">

frontend/src/app/boards/[boardId]/approvals/page.tsx

@@ -33,9 +33,9 @@ export default function BoardApprovalsPage() {
       <SignedIn>
         <DashboardSidebar />
         <main className="flex-1 overflow-y-auto bg-gradient-to-br from-slate-50 to-slate-100">
-          <div className="p-6">
+          <div className="p-4 md:p-6">
             {boardId ? (
-              <div className="h-[calc(100vh-160px)] min-h-[520px]">
+              <div className="h-[calc(100vh-160px)] min-h-[300px] sm:min-h-[520px]">
                 <BoardApprovalsPanel boardId={boardId} scrollable />
               </div>
             ) : null}

frontend/src/app/boards/[boardId]/page.tsx

@@ -3101,7 +3101,7 @@ export default function BoardDetailPage() {
           )}
         >
           <div className="sticky top-0 z-30 border-b border-slate-200 bg-white shadow-sm">
-            <div className="px-8 py-6">
+            <div className="px-4 py-4 md:px-8 md:py-6">
               <div className="flex flex-wrap items-center justify-between gap-4">
                 <div>
                   <h1 className="mt-2 text-2xl font-semibold text-slate-900 tracking-tight">
@@ -3237,9 +3237,9 @@ export default function BoardDetailPage() {
             </div>
           </div>
 
-          <div className="relative flex gap-6 p-6">
+          <div className="relative flex flex-col gap-4 p-4 md:flex-row md:gap-6 md:p-6">
             {isOrgAdmin ? (
-              <aside className="flex h-full w-64 flex-col rounded-xl border border-slate-200 bg-white shadow-sm">
+              <aside className="flex w-full flex-col rounded-xl border border-slate-200 bg-white shadow-sm md:h-full md:w-64">
                 <div className="flex items-center justify-between border-b border-slate-200 px-4 py-3">
                   <div>
                     <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
@@ -3680,12 +3680,12 @@ export default function BoardDetailPage() {
       ) : null}
       <aside
         className={cn(
-          "fixed right-0 top-0 z-50 h-full w-[max(760px,45vw)] max-w-[99vw] transform bg-white shadow-2xl transition-transform",
+          "fixed right-0 top-0 z-50 h-full w-full max-w-[99vw] transform bg-white shadow-2xl transition-transform md:w-[max(760px,45vw)]",
           isDetailOpen ? "transform-none" : "translate-x-full",
         )}
       >
         <div className="flex h-full flex-col">
-          <div className="flex items-center justify-between border-b border-slate-200 px-6 py-4">
+          <div className="flex items-center justify-between border-b border-slate-200 px-4 py-3 md:px-6 md:py-4">
             <div>
               <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
                 Task detail
@@ -3749,7 +3749,7 @@ export default function BoardDetailPage() {
                       return (
                         <div
                           key={definition.id}
-                          className="grid grid-cols-[160px_1fr] gap-3"
+                          className="grid grid-cols-1 gap-2 sm:grid-cols-[160px_1fr] sm:gap-3"
                         >
                           <dt className="text-xs font-semibold text-slate-600">
                             {definition.label || definition.field_key}
@@ -3993,12 +3993,12 @@ export default function BoardDetailPage() {
 
       <aside
         className={cn(
-          "fixed right-0 top-0 z-50 h-full w-[560px] max-w-[96vw] transform border-l border-slate-200 bg-white shadow-2xl transition-transform",
+          "fixed right-0 top-0 z-50 h-full w-full max-w-[96vw] transform border-l border-slate-200 bg-white shadow-2xl transition-transform md:w-[560px]",
           isChatOpen ? "transform-none" : "translate-x-full",
         )}
       >
         <div className="flex h-full flex-col">
-          <div className="flex items-center justify-between border-b border-slate-200 px-6 py-4">
+          <div className="flex items-center justify-between border-b border-slate-200 px-4 py-3 md:px-6 md:py-4">
             <div>
               <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
                 Board chat
@@ -4055,12 +4055,12 @@ export default function BoardDetailPage() {
 
       <aside
         className={cn(
-          "fixed right-0 top-0 z-50 h-full w-[520px] max-w-[96vw] transform border-l border-slate-200 bg-white shadow-2xl transition-transform",
+          "fixed right-0 top-0 z-50 h-full w-full max-w-[96vw] transform border-l border-slate-200 bg-white shadow-2xl transition-transform md:w-[520px]",
           isLiveFeedOpen ? "transform-none" : "translate-x-full",
         )}
       >
         <div className="flex h-full flex-col">
-          <div className="flex items-center justify-between border-b border-slate-200 px-6 py-4">
+          <div className="flex items-center justify-between border-b border-slate-200 px-4 py-3 md:px-6 md:py-4">
             <div>
               <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
                 Live feed

frontend/src/app/dashboard/page.tsx

@@ -379,7 +379,7 @@ function TopMetricCard({
           : "bg-green-50 text-green-600";
 
   return (
-    <section className="rounded-xl border border-slate-200 bg-white p-6 shadow-sm transition hover:-translate-y-0.5 hover:shadow-md">
+    <section className="rounded-xl border border-slate-200 bg-white p-4 md:p-6 shadow-sm transition hover:-translate-y-0.5 hover:shadow-md">
       <div className="flex items-start justify-between gap-3">
         <div>
           <div className="flex items-center gap-1.5">
@@ -423,7 +423,7 @@ function InfoBlock({
   rows: SummaryRow[];
 }) {
   return (
-    <section className="rounded-xl border border-slate-200 bg-white p-6 shadow-sm">
+    <section className="rounded-xl border border-slate-200 bg-white p-4 md:p-6 shadow-sm">
       <div className="mb-4 flex items-center justify-between gap-3">
         <div className="flex items-center gap-1.5">
           <h3 className="text-lg font-semibold text-slate-900">{title}</h3>
@@ -513,6 +513,8 @@ export default function DashboardPage() {
         enabled: Boolean(isSignedIn),
         refetchInterval: 15_000,
         refetchOnMount: "always",
+        retry: 3,
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 5000),
       },
     },
   );
@@ -899,10 +901,10 @@ export default function DashboardPage() {
       <SignedIn>
         <DashboardSidebar />
         <main className="flex-1 overflow-y-auto bg-slate-50">
-          <div className="p-8">
+          <div className="p-4 md:p-8">
             {metricsQuery.error ? (
               <div className="mb-4 rounded-lg border border-rose-300 bg-rose-50 p-3 text-sm text-rose-700">
-                {metricsQuery.error.message}
+                Load failed: {metricsQuery.error.message}
               </div>
             ) : null}
 
@@ -958,7 +960,7 @@ export default function DashboardPage() {
               />
             </div>
 
-            <section className="mt-4 rounded-xl border border-slate-200 bg-white p-6 shadow-sm">
+            <section className="mt-4 rounded-xl border border-slate-200 bg-white p-4 md:p-6 shadow-sm">
               <div className="mb-3 flex items-center justify-between gap-3">
                 <h3 className="text-lg font-semibold text-slate-900">Pending Approvals</h3>
                 <Link
@@ -1016,7 +1018,7 @@ export default function DashboardPage() {
             </section>
 
             <div className="mt-4 grid grid-cols-1 gap-4 md:grid-cols-2">
-              <section className="min-w-0 overflow-hidden rounded-xl border border-slate-200 bg-white p-6 shadow-sm">
+              <section className="min-w-0 overflow-hidden rounded-xl border border-slate-200 bg-white p-4 md:p-6 shadow-sm">
                 <div className="mb-3 flex items-center justify-between gap-3">
                   <h3 className="text-lg font-semibold text-slate-900">Sessions</h3>
                   <span className="text-xs text-slate-500">{formatCount(activeSessions)}</span>
@@ -1082,7 +1084,7 @@ export default function DashboardPage() {
                 </div>
               </section>
 
-              <section className="min-w-0 overflow-hidden rounded-xl border border-slate-200 bg-white p-6 shadow-sm">
+              <section className="min-w-0 overflow-hidden rounded-xl border border-slate-200 bg-white p-4 md:p-6 shadow-sm">
                 <div className="mb-3 flex items-center justify-between gap-3">
                   <h3 className="text-lg font-semibold text-slate-900">Recent Activity</h3>
                   <Link

frontend/src/app/invite/page.tsx

@@ -76,7 +76,7 @@ function InviteContent() {
       </header>
 
       <main className="mx-auto flex max-w-3xl flex-col gap-6 px-6 py-16">
-        <div className="rounded-2xl border border-[color:var(--border)] bg-[color:var(--surface)] p-8 shadow-sm">
+        <div className="rounded-2xl border border-[color:var(--border)] bg-[color:var(--surface)] p-4 md:p-8 shadow-sm">
           <div className="flex flex-col gap-3">
             <p className="text-xs font-semibold uppercase tracking-[0.3em] text-quiet">
               Organization Invite
@@ -158,7 +158,7 @@ export default function InvitePage() {
             </div>
           </header>
           <main className="mx-auto flex max-w-3xl flex-col gap-6 px-6 py-16">
-            <div className="rounded-2xl border border-[color:var(--border)] bg-[color:var(--surface)] p-8 shadow-sm">
+            <div className="rounded-2xl border border-[color:var(--border)] bg-[color:var(--surface)] p-4 md:p-8 shadow-sm">
               <div className="text-sm text-muted">Loading invite…</div>
             </div>
           </main>

frontend/src/app/organization/page.tsx

@@ -704,7 +704,7 @@ export default function OrganizationPage() {
         <DashboardSidebar />
         <main className="flex-1 overflow-y-auto bg-slate-50">
           <div className="sticky top-0 z-30 border-b border-slate-200 bg-white">
-            <div className="px-8 py-6">
+            <div className="px-4 py-4 md:px-8 md:py-6">
               <div className="flex flex-wrap items-center justify-between gap-6">
                 <div>
                   <div className="flex flex-wrap items-center gap-3">
@@ -775,7 +775,7 @@ export default function OrganizationPage() {
             </div>
           </div>
 
-          <div className="px-8 py-8">
+          <div className="px-4 py-4 md:px-8 md:py-8">
             <div className="overflow-hidden rounded-2xl border border-slate-200 bg-white">
               <div className="flex flex-wrap items-center justify-between gap-3 border-b border-slate-200 px-5 py-4">
                 <div>

frontend/src/components/auth/SignedOutPanel.tsx

@@ -20,8 +20,8 @@ export function SignedOutPanel({
   buttonTestId,
 }: SignedOutPanelProps) {
   return (
-    <div className="col-span-2 flex min-h-[calc(100vh-64px)] items-center justify-center bg-slate-50 p-10 text-center">
+    <div className="col-span-1 md:col-span-2 flex min-h-[calc(100vh-64px)] items-center justify-center bg-slate-50 p-10 text-center">
-      <div className="rounded-xl border border-slate-200 bg-white px-8 py-6 shadow-sm">
+      <div className="rounded-xl border border-slate-200 bg-white px-4 py-4 md:px-8 md:py-6 shadow-sm">
         <p className="text-sm text-slate-600">{message}</p>
         <SignInButton
           mode={mode}

frontend/src/components/board-groups/BoardGroupsTable.tsx

@@ -130,7 +130,7 @@ export function BoardGroupsTable({
       stickyHeader={stickyHeader}
       emptyMessage={emptyMessage}
       rowClassName="transition hover:bg-slate-50"
-      cellClassName="px-6 py-4 align-top"
+      cellClassName="px-3 py-3 md:px-6 md:py-4 align-top"
       rowActions={
         showActions
           ? {

frontend/src/components/boards/BoardsTable.tsx

@@ -162,7 +162,7 @@ export function BoardsTable({
       stickyHeader={stickyHeader}
       emptyMessage={emptyMessage}
       rowClassName="transition hover:bg-slate-50"
-      cellClassName="px-6 py-4 align-top"
+      cellClassName="px-3 py-3 md:px-6 md:py-4 align-top"
       rowActions={
         showActions
           ? {

frontend/src/components/organisms/DashboardSidebar.tsx

@@ -58,7 +58,7 @@ export function DashboardSidebar() {
         : "System degraded";
 
   return (
-    <aside className="flex h-full w-64 flex-col border-r border-slate-200 bg-white">
+    <aside className="fixed inset-y-0 left-0 z-40 flex w-[280px] -translate-x-full flex-col border-r border-slate-200 bg-white pt-16 shadow-lg transition-transform duration-200 ease-in-out [[data-sidebar=open]_&]:translate-x-0 md:relative md:inset-auto md:z-auto md:w-[260px] md:translate-x-0 md:pt-0 md:shadow-none md:transition-none">
       <div className="flex-1 px-3 py-4">
         <p className="px-3 text-xs font-semibold uppercase tracking-wider text-slate-500">
           Navigation

frontend/src/components/tables/DataTable.tsx

@@ -59,10 +59,10 @@ export function DataTable<TData>({
   stickyHeader = false,
   tableClassName = "w-full text-left text-sm",
   headerClassName,
-  headerCellClassName = "px-6 py-3",
+  headerCellClassName = "px-3 py-2 md:px-6 md:py-3",
   bodyClassName = "divide-y divide-slate-100",
   rowClassName = "hover:bg-slate-50",
-  cellClassName = "px-6 py-4",
+  cellClassName = "px-3 py-3 md:px-6 md:py-4",
 }: DataTableProps<TData>) {
   const resolvedRowActions = rowActions
     ? (rowActions.actions ??

frontend/src/components/templates/DashboardPageLayout.tsx

@@ -75,7 +75,7 @@ export function DashboardPageLayout({
               headerClassName,
             )}
           >
-            <div className="px-8 py-6">
+            <div className="px-4 py-4 md:px-8 md:py-6">
               {headerActions ? (
                 <div className="flex flex-wrap items-center justify-between gap-4">
                   <div>
@@ -103,7 +103,7 @@ export function DashboardPageLayout({
             </div>
           </div>
 
-          <div className={cn("p-8", contentClassName)}>
+          <div className={cn("p-4 md:p-8", contentClassName)}>
             {showAdminOnlyNotice ? (
               <AdminOnlyNotice message={adminOnlyMessage ?? ""} />
             ) : (

frontend/src/components/templates/DashboardShell.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { useEffect } from "react";
+import { useCallback, useEffect, useState } from "react";
 import type { ReactNode } from "react";
 import { usePathname, useRouter } from "next/navigation";
+import { Menu, X } from "lucide-react";
 
 import { SignedIn, useAuth } from "@/auth/clerk";
 
@@ -21,6 +22,14 @@ export function DashboardShell({ children }: { children: ReactNode }) {
   const pathname = usePathname();
   const { isSignedIn } = useAuth();
   const isOnboardingPath = pathname === "/onboarding";
+  const [sidebarState, setSidebarState] = useState({ open: false, path: pathname });
+  // Close sidebar on navigation using React's "store info from previous
+  // renders" pattern — conditional setState during render resets immediately
+  // without extra commits, avoiding both set-state-in-effect and refs rules.
+  if (sidebarState.path !== pathname) {
+    setSidebarState({ open: false, path: pathname });
+  }
+  const sidebarOpen = sidebarState.open;
 
   const meQuery = useGetMeApiV1UsersMeGet<
     getMeApiV1UsersMeGetResponse,
@@ -68,22 +77,47 @@ export function DashboardShell({ children }: { children: ReactNode }) {
     };
   }, []);
 
+  const toggleSidebar = useCallback(
+    () => setSidebarState((prev) => ({ open: !prev.open, path: pathname })),
+    [pathname],
+  );
+
+  // Dismiss sidebar on Escape
+  useEffect(() => {
+    if (!sidebarOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setSidebarState((prev) => ({ ...prev, open: false }));
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [sidebarOpen]);
+
   return (
-    <div className="min-h-screen bg-app text-strong">
+    <div className="min-h-screen bg-app text-strong" data-sidebar={sidebarOpen ? "open" : "closed"}>
-      <header className="sticky top-0 z-40 border-b border-slate-200 bg-white shadow-sm">
+      <header className="sticky top-0 z-50 border-b border-slate-200 bg-white shadow-sm">
-        <div className="grid grid-cols-[260px_1fr_auto] items-center gap-0 py-3">
+        <div className="flex items-center py-3">
-          <div className="flex items-center px-6">
+          <div className="flex items-center px-4 md:px-6 md:w-[260px]">
+            {isSignedIn ? (
+              <button
+                type="button"
+                className="mr-3 rounded-lg p-2 text-slate-600 hover:bg-slate-100 md:hidden"
+                onClick={toggleSidebar}
+                aria-label="Toggle navigation"
+              >
+                {sidebarOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
+              </button>
+            ) : null}
             <BrandMark />
           </div>
           <SignedIn>
-            <div className="flex items-center">
+            <div className="hidden md:flex flex-1 items-center">
               <div className="max-w-[220px]">
                 <OrgSwitcher />
               </div>
             </div>
           </SignedIn>
           <SignedIn>
-            <div className="flex items-center gap-3 px-6">
+            <div className="ml-auto flex items-center gap-3 px-4 md:px-6">
               <div className="hidden text-right lg:block">
                 <p className="text-sm font-semibold text-slate-900">
                   {displayName}
@@ -95,7 +129,18 @@ export function DashboardShell({ children }: { children: ReactNode }) {
           </SignedIn>
         </div>
       </header>
-      <div className="grid min-h-[calc(100vh-64px)] grid-cols-[260px_1fr] bg-slate-50">
+
+      {/* Mobile sidebar overlay */}
+      {sidebarOpen ? (
+        <div
+          className="fixed inset-0 z-40 bg-black/30 md:hidden"
+          onClick={toggleSidebar}
+          aria-hidden="true"
+          data-cy="sidebar-backdrop"
+        />
+      ) : null}
+
+      <div className="grid min-h-[calc(100vh-64px)] grid-cols-1 md:grid-cols-[260px_1fr] bg-slate-50">
         {children}
       </div>
     </div>