[codex] add comprehensive UI Storybook coverage (#4132)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The board UI is the main operator surface, so its component and
workflow coverage needs to stay reviewable as the product grows.
> - This branch adds Storybook as a dedicated UI reference surface for
core Paperclip screens and interaction patterns.
> - That work spans Storybook infrastructure, app-level provider wiring,
and a large fixture set that can render real control-plane states
without a live backend.
> - The branch also expands coverage across agents, budgets, issues,
chat, dialogs, navigation, projects, and data visualization so future UI
changes have a concrete visual baseline.
> - This pull request packages that Storybook work on top of the latest
`master`, excludes the lockfile from the final diff per repo policy, and
fixes one fixture contract drift caught during verification.
> - The benefit is a single reviewable PR that adds broad UI
documentation and regression-surfacing coverage without losing the
existing branch work.

## What Changed

- Added Storybook 10 wiring for the UI package, including root scripts,
UI package scripts, Storybook config, preview wrappers, Tailwind
entrypoints, and setup docs.
- Added a large fixture-backed data source for Storybook so complex
board states can render without a live server.
- Added story suites covering foundations, status language,
control-plane surfaces, overview, UX labs, agent management, budget and
finance, forms and editors, issue management, navigation and layout,
chat and comments, data visualization, dialogs and modals, and
projects/goals/workspaces.
- Adjusted several UI components for Storybook parity so dialogs, menus,
keyboard shortcuts, budget markers, markdown editing, and related
surfaces render correctly in isolation.
- Rebasing work for PR assembly: replayed the branch onto current
`master`, removed `pnpm-lock.yaml` from the final PR diff, and aligned
the dashboard fixture with the current `DashboardSummary.runActivity`
API contract.

## Verification

- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/ui build-storybook`
- Manual diff audit after rebase: verified the PR no longer includes
`pnpm-lock.yaml` and now cleanly targets current `master`.
- Before/after UI note: before this branch there was no dedicated
Storybook surface for these Paperclip views; after this branch the local
Storybook build includes the new overview and domain story suites in
`ui/storybook-static`.

## Risks

- Large static fixture files can drift from shared types as dashboard
and UI contracts evolve; this PR already needed one fixture correction
for `runActivity`.
- Storybook bundle output includes some large chunks, so future growth
may need chunking work if build performance becomes an issue.
- Several component tweaks were made for isolated rendering parity, so
reviewers should spot-check key board surfaces against the live app
behavior.

## Model Used

- OpenAI Codex, GPT-5-based coding agent in the Paperclip harness; exact
serving model ID is not exposed in-runtime to the agent.
- Tool-assisted workflow with terminal execution, git operations, local
typecheck/build verification, and GitHub CLI PR creation.
- Context window/reasoning mode not surfaced by the harness.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/storybook/stories/navigation-layout.stories.tsx

@@ -0,0 +1,360 @@
+import { useEffect, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  Bot,
+  CircleDot,
+  House,
+  Inbox,
+  LayoutDashboard,
+  SquarePen,
+  Users,
+} from "lucide-react";
+import { BreadcrumbBar } from "@/components/BreadcrumbBar";
+import { CommandPalette } from "@/components/CommandPalette";
+import { CompanyRail } from "@/components/CompanyRail";
+import { CompanySwitcher } from "@/components/CompanySwitcher";
+import { KeyboardShortcutsCheatsheetContent } from "@/components/KeyboardShortcutsCheatsheet";
+import { MobileBottomNav } from "@/components/MobileBottomNav";
+import { PageTabBar } from "@/components/PageTabBar";
+import { Sidebar } from "@/components/Sidebar";
+import { SidebarAccountMenu } from "@/components/SidebarAccountMenu";
+import { SidebarCompanyMenu } from "@/components/SidebarCompanyMenu";
+import { StatusBadge } from "@/components/StatusBadge";
+import { Badge } from "@/components/ui/badge";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from "@/components/ui/command";
+import { Tabs } from "@/components/ui/tabs";
+import { BreadcrumbProvider, useBreadcrumbs, type Breadcrumb } from "@/context/BreadcrumbContext";
+import { useNavigate } from "@/lib/router";
+import { cn } from "@/lib/utils";
+import {
+  storybookAgents,
+  storybookIssues,
+  storybookProjects,
+  storybookSidebarBadges,
+} from "../fixtures/paperclipData";
+
+function Section({
+  eyebrow,
+  title,
+  children,
+}: {
+  eyebrow: string;
+  title: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="paperclip-story__frame overflow-hidden">
+      <div className="border-b border-border px-5 py-4">
+        <div className="paperclip-story__label">{eyebrow}</div>
+        <h2 className="mt-1 text-xl font-semibold">{title}</h2>
+      </div>
+      <div className="p-5">{children}</div>
+    </section>
+  );
+}
+
+function RouteSetter({ to }: { to: string }) {
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    navigate(to, { replace: true });
+  }, [navigate, to]);
+
+  return null;
+}
+
+function SidebarShell({ collapsed = false }: { collapsed?: boolean }) {
+  return (
+    <div className="h-[520px] overflow-hidden border border-border bg-background">
+      <div className="flex h-full min-h-0">
+        <CompanyRail />
+        <div className={cn("overflow-hidden transition-[width]", collapsed ? "w-0" : "w-60")}>
+          <Sidebar />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function BreadcrumbScenario({ breadcrumbs }: { breadcrumbs: Breadcrumb[] }) {
+  const { setBreadcrumbs } = useBreadcrumbs();
+
+  useEffect(() => {
+    setBreadcrumbs(breadcrumbs);
+  }, [breadcrumbs, setBreadcrumbs]);
+
+  return (
+    <div className="overflow-hidden border border-border bg-background">
+      <BreadcrumbBar />
+    </div>
+  );
+}
+
+function BreadcrumbSnapshot({ breadcrumbs }: { breadcrumbs: Breadcrumb[] }) {
+  return (
+    <BreadcrumbProvider>
+      <BreadcrumbScenario breadcrumbs={breadcrumbs} />
+    </BreadcrumbProvider>
+  );
+}
+
+const tabItems = [
+  { value: "overview", label: "Overview" },
+  { value: "issues", label: "Issues" },
+  { value: "runs", label: "Runs" },
+  { value: "approvals", label: "Approvals" },
+  { value: "budget", label: "Budget" },
+  { value: "activity", label: "Activity" },
+  { value: "settings", label: "Settings" },
+  { value: "history", label: "History" },
+];
+
+const mobileNavItems = [
+  { label: "Home", icon: House },
+  { label: "Issues", icon: CircleDot },
+  { label: "Create", icon: SquarePen },
+  { label: "Agents", icon: Users },
+  { label: "Inbox", icon: Inbox, badge: storybookSidebarBadges.inbox },
+];
+
+function MobileBottomNavActiveStateMatrix() {
+  return (
+    <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-5">
+      {mobileNavItems.map((activeItem) => (
+        <div key={activeItem.label} className="overflow-hidden border border-border bg-background">
+          <div className="grid h-16 grid-cols-5 px-1">
+            {mobileNavItems.map((item) => {
+              const Icon = item.icon;
+              const active = item.label === activeItem.label;
+              return (
+                <div
+                  key={item.label}
+                  className={cn(
+                    "relative flex min-w-0 flex-col items-center justify-center gap-1 rounded-md text-[10px] font-medium",
+                    active ? "text-foreground" : "text-muted-foreground",
+                  )}
+                >
+                  <span className="relative">
+                    <Icon className={cn("h-[18px] w-[18px]", active && "stroke-[2.3]")} />
+                    {item.badge ? (
+                      <span className="absolute -right-2 -top-2 rounded-full bg-primary px-1.5 py-0.5 text-[10px] leading-none text-primary-foreground">
+                        {item.badge}
+                      </span>
+                    ) : null}
+                  </span>
+                  <span className="truncate">{item.label}</span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function CommandResultsSurface() {
+  return (
+    <Command className="rounded-none border border-border">
+      <CommandInput value="story" readOnly placeholder="Search issues, agents, projects..." />
+      <CommandList className="max-h-none">
+        <CommandGroup heading="Actions">
+          <CommandItem>
+            <SquarePen className="mr-2 h-4 w-4" />
+            Create new issue
+            <span className="ml-auto text-xs text-muted-foreground">C</span>
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Issues">
+          {storybookIssues.slice(0, 2).map((issue) => (
+            <CommandItem key={issue.id}>
+              <CircleDot className="mr-2 h-4 w-4" />
+              <span className="mr-2 font-mono text-xs text-muted-foreground">{issue.identifier}</span>
+              <span className="flex-1 truncate">{issue.title}</span>
+              <StatusBadge status={issue.status} />
+            </CommandItem>
+          ))}
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Agents">
+          {storybookAgents.map((agent) => (
+            <CommandItem key={agent.id}>
+              <Bot className="mr-2 h-4 w-4" />
+              {agent.name}
+              <span className="ml-2 text-xs text-muted-foreground">{agent.role}</span>
+            </CommandItem>
+          ))}
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Projects">
+          {storybookProjects.map((project) => (
+            <CommandItem key={project.id}>
+              <LayoutDashboard className="mr-2 h-4 w-4" />
+              {project.name}
+            </CommandItem>
+          ))}
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  );
+}
+
+function CommandEmptySurface() {
+  return (
+    <Command className="rounded-none border border-border">
+      <CommandInput value="no matching command" readOnly placeholder="Search issues, agents, projects..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+      </CommandList>
+    </Command>
+  );
+}
+
+function NavigationLayoutStories() {
+  return (
+    <div className="paperclip-story">
+      <RouteSetter to="/PAP/projects/board-ui/issues" />
+      <main className="paperclip-story__inner max-w-[1320px] space-y-6">
+        <section className="paperclip-story__frame p-6">
+          <div className="flex flex-wrap items-start justify-between gap-5">
+            <div>
+              <div className="paperclip-story__label">Navigation and layout</div>
+              <h1 className="mt-2 text-3xl font-semibold tracking-tight">Sidebar, command, tabs, and mobile chrome</h1>
+              <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+                Fixture-backed navigation states for the board shell: company switching, dense work navigation,
+                breadcrumbs, command discovery, and mobile entry points.
+              </p>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              <Badge variant="outline">fixture backed</Badge>
+              <Badge variant="outline">company scoped</Badge>
+              <Badge variant="outline">responsive chrome</Badge>
+            </div>
+          </div>
+        </section>
+
+        <Section eyebrow="Sidebar" title="Expanded and collapsed shell states">
+          <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_220px]">
+            <SidebarShell />
+            <SidebarShell collapsed />
+          </div>
+        </Section>
+
+        <Section eyebrow="Company rail" title="Multi-company rail with selected, inactive, live, and unread indicators">
+          <div className="h-[420px] w-[72px] overflow-hidden border border-border bg-background">
+            <CompanyRail />
+          </div>
+        </Section>
+
+        <Section eyebrow="Menus" title="Account, company, and switcher menus in open state">
+          <div className="grid gap-5 xl:grid-cols-3">
+            <div className="relative h-[440px] overflow-hidden border border-border bg-background">
+              <div className="absolute bottom-0 left-0 w-72">
+                <SidebarAccountMenu
+                  deploymentMode="authenticated"
+                  instanceSettingsTarget="/instance/settings/general"
+                  open
+                  onOpenChange={() => undefined}
+                  version="0.3.1"
+                />
+              </div>
+            </div>
+
+            <div className="h-[260px] overflow-hidden border border-border bg-background p-3">
+              <SidebarCompanyMenu open onOpenChange={() => undefined} />
+            </div>
+
+            <div className="h-[320px] overflow-hidden border border-border bg-background p-4">
+              <CompanySwitcher open onOpenChange={() => undefined} />
+            </div>
+          </div>
+        </Section>
+
+        <Section eyebrow="Breadcrumbs" title="Home, project issue, and agent run depth levels">
+          <div className="grid gap-4">
+            <BreadcrumbSnapshot breadcrumbs={[{ label: "Dashboard", href: "/dashboard" }]} />
+            <BreadcrumbSnapshot
+              breadcrumbs={[
+                { label: "Projects", href: "/projects" },
+                { label: "Board UI", href: "/projects/board-ui/issues" },
+                { label: "PAP-1641" },
+              ]}
+            />
+            <BreadcrumbSnapshot
+              breadcrumbs={[
+                { label: "Agents", href: "/agents" },
+                { label: "CodexCoder", href: "/agents/codexcoder" },
+                { label: "Run run-storybook" },
+              ]}
+            />
+          </div>
+        </Section>
+
+        <Section eyebrow="Page tabs" title="Active and overflow tab bars">
+          <div className="space-y-5">
+            <Tabs value="issues" className="overflow-x-auto">
+              <PageTabBar items={tabItems.slice(0, 4)} value="issues" align="start" />
+            </Tabs>
+            <Tabs value="activity" className="overflow-x-auto">
+              <PageTabBar items={tabItems} value="activity" align="start" />
+            </Tabs>
+          </div>
+        </Section>
+
+        <Section eyebrow="Mobile bottom nav" title="Actual mobile bar and all active item states">
+          <div className="space-y-5">
+            <div className="relative h-24 max-w-sm overflow-hidden border border-border bg-background [&>nav]:!absolute [&>nav]:!bottom-0 [&>nav]:!left-0 [&>nav]:!right-0 [&>nav]:!z-0 [&>nav]:!block">
+              <MobileBottomNav visible />
+            </div>
+            <MobileBottomNavActiveStateMatrix />
+          </div>
+        </Section>
+
+        <Section eyebrow="Command palette" title="Open command results and empty state">
+          <CommandPalette />
+          <div className="grid gap-5 xl:grid-cols-2">
+            <CommandResultsSurface />
+            <CommandEmptySurface />
+          </div>
+        </Section>
+
+        <Section eyebrow="Keyboard shortcuts" title="Rendered shortcuts cheatsheet">
+          <div className="max-w-md overflow-hidden border border-border bg-background">
+            <div className="px-5 pb-3 pt-5">
+              <h3 className="text-base font-semibold">Keyboard shortcuts</h3>
+            </div>
+            <KeyboardShortcutsCheatsheetContent />
+          </div>
+        </Section>
+      </main>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Product/Navigation & Layout",
+  component: NavigationLayoutStories,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Navigation and layout stories cover the board shell components that orient operators across companies, work surfaces, command search, breadcrumbs, tabs, and mobile navigation.",
+      },
+    },
+  },
+} satisfies Meta<typeof NavigationLayoutStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const BoardChromeMatrix: Story = {};