Skip to content

The open-source app everyone uses to manage agents at work

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

Dotta2de893f624b1
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 099c6359ac..2611a0eb39 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -43,6 +43,17 @@ This starts:
`pnpm dev` and `pnpm dev:once` are now idempotent for the current repo and instance: if the matching Paperclip dev runner is already alive, Paperclip reports the existing process instead of starting a duplicate.
+## Storybook
+
+The board UI Storybook keeps stories and Storybook config under `ui/storybook/` so component review files stay out of the app source routes.
+
+```sh
+pnpm storybook
+pnpm build-storybook
+```
+
+These run the `@paperclipai/ui` Storybook on port `6006` and build the static output to `ui/storybook-static/`.
+
Inspect or stop the current repo's managed dev runner:
```sh
diff --git a/package.json b/package.json
index ce666bfaf3..21894e98a2 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,8 @@
"dev:stop": "pnpm --filter @paperclipai/server exec tsx ../scripts/dev-service.ts stop",
"dev:server": "pnpm --filter @paperclipai/server dev",
"dev:ui": "pnpm --filter @paperclipai/ui dev",
+ "storybook": "pnpm --filter @paperclipai/ui storybook",
+ "build-storybook": "pnpm --filter @paperclipai/ui build-storybook",
"build": "pnpm run preflight:workspace-links && pnpm -r build",
"typecheck": "pnpm run preflight:workspace-links && pnpm -r typecheck",
"test": "pnpm run test:run",
diff --git a/ui/README.md b/ui/README.md
index 0e688669e3..b33021d111 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -6,6 +6,15 @@ Published static assets for the Paperclip board UI.
The npm package contains the production build under `dist/`. It does not ship the UI source tree or workspace-only dependencies.
+## Storybook
+
+Storybook config, stories, and fixtures live under `ui/storybook/`.
+
+```sh
+pnpm --filter @paperclipai/ui storybook
+pnpm --filter @paperclipai/ui build-storybook
+```
+
## Typical use
Install the package, then serve or copy the built files from `node_modules/@paperclipai/ui/dist`.
diff --git a/ui/package.json b/ui/package.json
index 020e2ec2f8..dda6e7154b 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -16,9 +16,11 @@
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
+ "storybook": "storybook dev -p 6006 -c storybook/.storybook",
+ "build-storybook": "storybook build -c storybook/.storybook -o storybook-static",
"preview": "vite preview",
"typecheck": "tsc -b",
- "clean": "rm -rf dist tsconfig.tsbuildinfo",
+ "clean": "rm -rf dist storybook-static tsconfig.tsbuildinfo",
"prepack": "rm -f package.dev.json && cp package.json package.dev.json && node ../scripts/generate-ui-package-json.mjs",
"postpack": "if [ -f package.dev.json ]; then mv package.dev.json package.json; fi"
},
@@ -61,12 +63,16 @@
},
"devDependencies": {
"@tailwindcss/vite": "^4.0.7",
+ "@storybook/addon-a11y": "10.3.5",
+ "@storybook/addon-docs": "10.3.5",
+ "@storybook/react-vite": "10.3.5",
"@types/node": "^25.2.3",
"@types/react": "^19.0.8",
"@types/react-dom": "^19.0.3",
"@vitejs/plugin-react": "^4.3.4",
"tailwindcss": "^4.0.7",
"typescript": "^5.7.3",
+ "storybook": "10.3.5",
"vite": "^6.1.0",
"vitest": "^3.0.5"
}
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index 1a82d1a613..f495dc0e4d 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -40,9 +40,6 @@ import { PluginManager } from "./pages/PluginManager";
import { PluginSettings } from "./pages/PluginSettings";
import { AdapterManager } from "./pages/AdapterManager";
import { PluginPage } from "./pages/PluginPage";
-import { IssueChatUxLab } from "./pages/IssueChatUxLab";
-import { InviteUxLab } from "./pages/InviteUxLab";
-import { RunTranscriptUxLab } from "./pages/RunTranscriptUxLab";
import { OrgChart } from "./pages/OrgChart";
import { NewAgent } from "./pages/NewAgent";
import { AuthPage } from "./pages/Auth";
@@ -122,9 +119,6 @@ function boardRoutes() {
<Route path="inbox/new" element={<Navigate to="/inbox/mine" replace />} />
<Route path="u/:userSlug" element={<UserProfile />} />
<Route path="design-guide" element={<DesignGuide />} />
- <Route path="tests/ux/chat" element={<IssueChatUxLab />} />
- <Route path="tests/ux/invites" element={<InviteUxLab />} />
- <Route path="tests/ux/runs" element={<RunTranscriptUxLab />} />
<Route path="instance/settings/adapters" element={<AdapterManager />} />
<Route path=":pluginRoutePath" element={<PluginPage />} />
<Route path="*" element={<NotFoundPage scope="board" />} />
@@ -303,8 +297,6 @@ export function App() {
<Route path="execution-workspaces/:workspaceId/configuration" element={<UnprefixedBoardRedirect />} />
<Route path="execution-workspaces/:workspaceId/runtime-logs" element={<UnprefixedBoardRedirect />} />
<Route path="execution-workspaces/:workspaceId/issues" element={<UnprefixedBoardRedirect />} />
- <Route path="tests/ux/chat" element={<UnprefixedBoardRedirect />} />
- <Route path="tests/ux/runs" element={<UnprefixedBoardRedirect />} />
<Route path=":companyPrefix" element={<Layout />}>
{boardRoutes()}
</Route>
diff --git a/ui/src/components/BudgetIncidentCard.tsx b/ui/src/components/BudgetIncidentCard.tsx
index 7a24e4a0ea..49836819cf 100644
--- a/ui/src/components/BudgetIncidentCard.tsx
+++ b/ui/src/components/BudgetIncidentCard.tsx
@@ -2,6 +2,7 @@ import { useState } from "react";
import type { BudgetIncident } from "@paperclipai/shared";
import { AlertOctagon, ArrowUpRight, PauseCircle } from "lucide-react";
import { formatCents } from "../lib/utils";
+import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { Input } from "@/components/ui/input";
@@ -16,6 +17,14 @@ function parseDollarInput(value: string) {
return Math.round(parsed * 100);
}
+function incidentStateLabel(incident: BudgetIncident) {
+ if (incident.status === "resolved") return "Resolved";
+ if (incident.status === "dismissed") return "Dismissed";
+ if (incident.approvalStatus === "revision_requested") return "Escalated";
+ if (incident.approvalStatus === "pending") return "Pending approval";
+ return "Open";
+}
+
export function BudgetIncidentCard({
incident,
onRaiseAndResume,
@@ -31,14 +40,20 @@ export function BudgetIncidentCard({
centsInputValue(Math.max(incident.amountObserved + 1000, incident.amountLimit)),
);
const parsed = parseDollarInput(draftAmount);
+ const stateLabel = incidentStateLabel(incident);
return (
<Card className="overflow-hidden border-red-500/20 bg-[linear-gradient(180deg,rgba(255,70,70,0.10),rgba(255,255,255,0.02))]">
<CardHeader className="px-5 pt-5 pb-3">
<div className="flex items-start justify-between gap-3">
<div>
- <div className="text-[11px] uppercase tracking-[0.22em] text-red-200/80">
- {incident.scopeType} hard stop
+ <div className="flex flex-wrap items-center gap-2">
+ <div className="text-[11px] uppercase tracking-[0.22em] text-red-200/80">
+ {incident.scopeType} hard stop
+ </div>
+ <Badge variant={incident.status === "resolved" ? "outline" : "secondary"}>
+ {stateLabel}
+ </Badge>
</div>
<CardTitle className="mt-1 text-base text-red-50">{incident.scopeName}</CardTitle>
<CardDescription className="mt-1 text-red-100/70">
diff --git a/ui/src/components/BudgetSidebarMarker.tsx b/ui/src/components/BudgetSidebarMarker.tsx
index 43f10b9526..07e5ddfc07 100644
--- a/ui/src/components/BudgetSidebarMarker.tsx
+++ b/ui/src/components/BudgetSidebarMarker.tsx
@@ -1,11 +1,33 @@
import { DollarSign } from "lucide-react";
-export function BudgetSidebarMarker({ title = "Paused by budget" }: { title?: string }) {
+export type BudgetSidebarMarkerLevel = "healthy" | "warning" | "critical";
+
+const levelClasses: Record<BudgetSidebarMarkerLevel, string> = {
+ healthy: "bg-emerald-500/90 text-white",
+ warning: "bg-amber-500/95 text-amber-950",
+ critical: "bg-red-500/90 text-white",
+};
+
+const defaultTitles: Record<BudgetSidebarMarkerLevel, string> = {
+ healthy: "Budget healthy",
+ warning: "Budget warning",
+ critical: "Paused by budget",
+};
+
+export function BudgetSidebarMarker({
+ title,
+ level = "critical",
+}: {
+ title?: string;
+ level?: BudgetSidebarMarkerLevel;
+}) {
+ const accessibleTitle = title ?? defaultTitles[level];
+
return (
<span
- title={title}
- aria-label={title}
- className="ml-auto inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-red-500/90 text-white shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
+ title={accessibleTitle}
+ aria-label={accessibleTitle}
+ className={`ml-auto inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full shadow-[0_0_0_1px_rgba(255,255,255,0.08)] ${levelClasses[level]}`}
>
<DollarSign className="h-3 w-3" />
</span>
diff --git a/ui/src/components/CompanySwitcher.tsx b/ui/src/components/CompanySwitcher.tsx
index aefe1020f0..2d009dba38 100644
--- a/ui/src/components/CompanySwitcher.tsx
+++ b/ui/src/components/CompanySwitcher.tsx
@@ -10,6 +10,7 @@ import {
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Button } from "@/components/ui/button";
+import { useState } from "react";
function statusDotColor(status?: string): string {
switch (status) {
@@ -24,12 +25,20 @@ function statusDotColor(status?: string): string {
}
}
-export function CompanySwitcher() {
+interface CompanySwitcherProps {
+ open?: boolean;
+ onOpenChange?: (open: boolean) => void;
+}
+
+export function CompanySwitcher({ open: controlledOpen, onOpenChange }: CompanySwitcherProps = {}) {
+ const [internalOpen, setInternalOpen] = useState(false);
const { companies, selectedCompany, setSelectedCompanyId } = useCompany();
const sidebarCompanies = companies.filter((company) => company.status !== "archived");
+ const open = controlledOpen ?? internalOpen;
+ const setOpen = onOpenChange ?? setInternalOpen;
return (
- <DropdownMenu>
+ <DropdownMenu open={open} onOpenChange={setOpen}>
<DropdownMenuTrigger asChild>
<Button
variant="ghost"
diff --git a/ui/src/components/KeyboardShortcutsCheatsheet.tsx b/ui/src/components/KeyboardShortcutsCheatsheet.tsx
index 45d6858ded..6c09ce0f5a 100644
--- a/ui/src/components/KeyboardShortcutsCheatsheet.tsx
+++ b/ui/src/components/KeyboardShortcutsCheatsheet.tsx
@@ -51,6 +51,45 @@ function KeyCap({ children }: { children: string }) {
);
}
+export function KeyboardShortcutsCheatsheetContent() {
+ return (
+ <>
+ <div className="divide-y divide-border border-t border-border">
+ {sections.map((section) => (
+ <div key={section.title} className="px-5 py-3">
+ <h3 className="mb-2 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+ {section.title}
+ </h3>
+ <div className="space-y-1.5">
+ {section.shortcuts.map((shortcut) => (
+ <div
+ key={shortcut.label + shortcut.keys.join()}
+ className="flex items-center justify-between gap-4"
+ >
+ <span className="text-sm text-foreground/90">{shortcut.label}</span>
+ <div className="flex items-center gap-1">
+ {shortcut.keys.map((key, i) => (
+ <span key={key} className="flex items-center gap-1">
+ {i > 0 && <span className="text-xs text-muted-foreground">then</span>}
+ <KeyCap>{key}</KeyCap>
+ </span>
+ ))}
+ </div>
+ </div>
+ ))}
+ </div>
+ </div>
+ ))}
+ </div>
+ <div className="border-t border-border px-5 py-3">
+ <p className="text-xs text-muted-foreground">
+ Press <KeyCap>Esc</KeyCap> to close &middot; Shortcuts are disabled in text fields
+ </p>
+ </div>
+ </>
+ );
+}
+
export function KeyboardShortcutsCheatsheet({
open,
onOpenChange,
@@ -64,38 +103,7 @@ export function KeyboardShortcutsCheatsheet({
<DialogHeader className="px-5 pt-5 pb-3">
<DialogTitle className="text-base">Keyboard shortcuts</DialogTitle>
</DialogHeader>
- <div className="divide-y divide-border border-t border-border">
- {sections.map((section) => (
- <div key={section.title} className="px-5 py-3">
- <h3 className="mb-2 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
- {section.title}
- </h3>
- <div className="space-y-1.5">
- {section.shortcuts.map((shortcut) => (
- <div
- key={shortcut.label + shortcut.keys.join()}
- className="flex items-center justify-between gap-4"
- >
- <span className="text-sm text-foreground/90">{shortcut.label}</span>
- <div className="flex items-center gap-1">
- {shortcut.keys.map((key, i) => (
- <span key={key} className="flex items-center gap-1">
- {i > 0 && <span className="text-xs text-muted-foreground">then</span>}
- <KeyCap>{key}</KeyCap>
- </span>
- ))}
- </div>
- </div>
- ))}
- </div>
- </div>
- ))}
- </div>
- <div className="border-t border-border px-5 py-3">
- <p className="text-xs text-muted-foreground">
- Press <KeyCap>Esc</KeyCap> to close &middot; Shortcuts are disabled in text fields
- </p>
- </div>
+ <KeyboardShortcutsCheatsheetContent />
</DialogContent>
</Dialog>
);
diff --git a/ui/src/components/MarkdownEditor.tsx b/ui/src/components/MarkdownEditor.tsx
index 66d37e448f..94f7e0bf38 100644
--- a/ui/src/components/MarkdownEditor.tsx
+++ b/ui/src/components/MarkdownEditor.tsx
@@ -73,6 +73,8 @@ interface MarkdownEditorProps {
mentions?: MentionOption[];
/** Called on Cmd/Ctrl+Enter */
onSubmit?: () => void;
+ /** Render the rich editor without allowing edits. */
+ readOnly?: boolean;
}
export interface MarkdownEditorRef {
@@ -492,6 +494,7 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
bordered = true,
mentions,
onSubmit,
+ readOnly = false,
}: MarkdownEditorProps, forwardedRef) {
const editorValue = useMemo(() => prepareMarkdownForEditor(value), [value]);
const { slashCommands } = useEditorAutocomplete();
@@ -944,7 +947,9 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
ref={fallbackTextareaRef}
value={value}
placeholder={placeholder}
+ readOnly={readOnly}
onChange={(event) => {
+ if (readOnly) return;
onChange(event.target.value);
autoSizeFallbackTextarea(event.target);
}}
@@ -974,6 +979,7 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
className,
)}
onKeyDownCapture={(e) => {
+ if (readOnly) return;
// Cmd/Ctrl+Enter to submit
if (onSubmit && e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
e.preventDefault();
@@ -1031,21 +1037,25 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
}
}}
onDragEnter={(evt) => {
+ if (readOnly) return;
if (!canDropFile || !hasFilePayload(evt)) return;
dragDepthRef.current += 1;
setIsDragOver(true);
}}
onDragOver={(evt) => {
+ if (readOnly) return;
if (!canDropFile || !hasFilePayload(evt)) return;
evt.preventDefault();
evt.dataTransfer.dropEffect = "copy";
}}
onDragLeave={() => {
+ if (readOnly) return;
if (!canDropFile) return;
dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
if (dragDepthRef.current === 0) setIsDragOver(false);
}}
onDrop={(evt) => {
+ if (readOnly) return;
dragDepthRef.current = 0;
setIsDragOver(false);
if (!onDropFile) return;
@@ -1073,7 +1083,9 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
ref={setEditorRef}
markdown={editorValue}
placeholder={placeholder}
+ readOnly={readOnly}
onChange={(next) => {
+ if (readOnly) return;
const echo = echoIgnoreMarkdownRef.current;
if (echo !== null && next === echo) {
echoIgnoreMarkdownRef.current = null;
diff --git a/ui/src/components/SidebarAccountMenu.tsx b/ui/src/components/SidebarAccountMenu.tsx
index ec6e1367de..df97aab4ad 100644
--- a/ui/src/components/SidebarAccountMenu.tsx
+++ b/ui/src/components/SidebarAccountMenu.tsx
@@ -26,6 +26,8 @@ const DOCS_URL = "https://docs.paperclip.ing/";
interface SidebarAccountMenuProps {
deploymentMode?: DeploymentMode;
instanceSettingsTarget: string;
+ open?: boolean;
+ onOpenChange?: (open: boolean) => void;
version?: string | null;
}
@@ -102,12 +104,16 @@ function MenuAction({ label, description, icon: Icon, onClick, href, external =
export function SidebarAccountMenu({
deploymentMode,
instanceSettingsTarget,
+ open: controlledOpen,
+ onOpenChange,
version,
}: SidebarAccountMenuProps) {
- const [open, setOpen] = useState(false);
+ const [internalOpen, setInternalOpen] = useState(false);
const queryClient = useQueryClient();
const { isMobile, setSidebarOpen } = useSidebar();
const { theme, toggleTheme } = useTheme();
+ const open = controlledOpen ?? internalOpen;
+ const setOpen = onOpenChange ?? setInternalOpen;
const { data: session } = useQuery({
queryKey: queryKeys.auth.session,
queryFn: () => authApi.getSession(),
diff --git a/ui/src/components/SidebarCompanyMenu.tsx b/ui/src/components/SidebarCompanyMenu.tsx
index c10c0a41f6..53d9a58cff 100644
--- a/ui/src/components/SidebarCompanyMenu.tsx
+++ b/ui/src/components/SidebarCompanyMenu.tsx
@@ -16,11 +16,18 @@ import { useCompany } from "@/context/CompanyContext";
import { queryKeys } from "@/lib/queryKeys";
import { useSidebar } from "../context/SidebarContext";
-export function SidebarCompanyMenu() {
- const [open, setOpen] = useState(false);
+interface SidebarCompanyMenuProps {
+ open?: boolean;
+ onOpenChange?: (open: boolean) => void;
+}
+
+export function SidebarCompanyMenu({ open: controlledOpen, onOpenChange }: SidebarCompanyMenuProps = {}) {
+ const [internalOpen, setInternalOpen] = useState(false);
const queryClient = useQueryClient();
const { selectedCompany } = useCompany();
const { isMobile, setSidebarOpen } = useSidebar();
+ const open = controlledOpen ?? internalOpen;
+ const setOpen = onOpenChange ?? setInternalOpen;
const { data: session } = useQuery({
queryKey: queryKeys.auth.session,
queryFn: () => authApi.getSession(),
diff --git a/ui/storybook/.gitignore b/ui/storybook/.gitignore
new file mode 100644
index 0000000000..20687473be
--- /dev/null
+++ b/ui/storybook/.gitignore
@@ -0,0 +1 @@
+storybook-static
diff --git a/ui/storybook/.storybook/main.ts b/ui/storybook/.storybook/main.ts
new file mode 100644
index 0000000000..e7e2dadaf0
--- /dev/null
+++ b/ui/storybook/.storybook/main.ts
@@ -0,0 +1,32 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { StorybookConfig } from "@storybook/react-vite";
+import tailwindcss from "@tailwindcss/vite";
+import { mergeConfig } from "vite";
+
+const storybookConfigDir = path.dirname(fileURLToPath(import.meta.url));
+
+const config: StorybookConfig = {
+ stories: ["../stories/**/*.stories.@(ts|tsx|mdx)"],
+ staticDirs: ["../../public"],
+ addons: ["@storybook/addon-docs", "@storybook/addon-a11y"],
+ framework: {
+ name: "@storybook/react-vite",
+ options: {},
+ },
+ docs: {
+ autodocs: true,
+ },
+ viteFinal: async (baseConfig) =>
+ mergeConfig(baseConfig, {
+ plugins: [tailwindcss()],
+ resolve: {
+ alias: {
+ "@": path.resolve(storybookConfigDir, "../../src"),
+ lexical: path.resolve(storybookConfigDir, "../../node_modules/lexical/Lexical.mjs"),
+ },
+ },
+ }),
+};
+
+export default config;
diff --git a/ui/storybook/.storybook/preview.tsx b/ui/storybook/.storybook/preview.tsx
new file mode 100644
index 0000000000..46a01e9e5c
--- /dev/null
+++ b/ui/storybook/.storybook/preview.tsx
@@ -0,0 +1,271 @@
+import { useEffect, useState, type ReactNode } from "react";
+import type { Preview } from "@storybook/react-vite";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "@/lib/router";
+import { BreadcrumbProvider } from "@/context/BreadcrumbContext";
+import { CompanyProvider } from "@/context/CompanyContext";
+import { DialogProvider } from "@/context/DialogContext";
+import { EditorAutocompleteProvider } from "@/context/EditorAutocompleteContext";
+import { PanelProvider } from "@/context/PanelContext";
+import { SidebarProvider } from "@/context/SidebarContext";
+import { ThemeProvider } from "@/context/ThemeContext";
+import { ToastProvider } from "@/context/ToastContext";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import {
+ storybookAgents,
+ storybookApprovals,
+ storybookAuthSession,
+ storybookCompanies,
+ storybookDashboardSummary,
+ storybookIssues,
+ storybookLiveRuns,
+ storybookProjects,
+ storybookSidebarBadges,
+} from "../fixtures/paperclipData";
+import "@mdxeditor/editor/style.css";
+import "./tailwind-entry.css";
+import "./styles.css";
+
+function installStorybookApiFixtures() {
+ if (typeof window === "undefined") return;
+ const currentWindow = window as typeof window & {
+ __paperclipStorybookFetchInstalled?: boolean;
+ };
+ if (currentWindow.__paperclipStorybookFetchInstalled) return;
+
+ const originalFetch = window.fetch.bind(window);
+ currentWindow.__paperclipStorybookFetchInstalled = true;
+
+ window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+ const rawUrl =
+ typeof input === "string"
+ ? input
+ : input instanceof URL
+ ? input.href
+ : input.url;
+ const url = new URL(rawUrl, window.location.origin);
+
+ if (url.pathname === "/api/auth/get-session") {
+ return Response.json(storybookAuthSession);
+ }
+
+ if (url.pathname === "/api/companies") {
+ return Response.json(storybookCompanies);
+ }
+
+ if (url.pathname === "/api/companies/company-storybook/user-directory") {
+ return Response.json({
+ users: [
+ {
+ principalId: "user-board",
+ status: "active",
+ user: {
+ id: "user-board",
+ email: "[email protected]",
+ name: "Board Operator",
+ image: null,
+ },
+ },
+ {
+ principalId: "user-product",
+ status: "active",
+ user: {
+ id: "user-product",
+ email: "[email protected]",
+ name: "Product Lead",
+ image: null,
+ },
+ },
+ ],
+ });
+ }
+
+ if (url.pathname === "/api/instance/settings/experimental") {
+ return Response.json({
+ enableIsolatedWorkspaces: true,
+ autoRestartDevServerWhenIdle: false,
+ });
+ }
+
+ if (url.pathname === "/api/plugins/ui-contributions") {
+ return Response.json([]);
+ }
+
+ const companyResourceMatch = url.pathname.match(/^\/api\/companies\/([^/]+)\/([^/]+)$/);
+ if (companyResourceMatch) {
+ const [, companyId, resource] = companyResourceMatch;
+ if (resource === "agents") {
+ return Response.json(companyId === "company-storybook" ? storybookAgents : []);
+ }
+ if (resource === "projects") {
+ return Response.json(companyId === "company-storybook" ? storybookProjects : []);
+ }
+ if (resource === "approvals") {
+ return Response.json(companyId === "company-storybook" ? storybookApprovals : []);
+ }
+ if (resource === "dashboard") {
+ return Response.json({
+ ...storybookDashboardSummary,
+ companyId,
+ });
+ }
+ if (resource === "heartbeat-runs") {
+ return Response.json([]);
+ }
+ if (resource === "live-runs") {
+ return Response.json(companyId === "company-storybook" ? storybookLiveRuns : []);
+ }
+ if (resource === "inbox-dismissals") {
+ return Response.json([]);
+ }
+ if (resource === "sidebar-badges") {
+ return Response.json(
+ companyId === "company-storybook"
+ ? storybookSidebarBadges
+ : { inbox: 0, approvals: 0, failedRuns: 0, joinRequests: 0 },
+ );
+ }
+ if (resource === "join-requests") {
+ return Response.json([]);
+ }
+ if (resource === "issues") {
+ const query = url.searchParams.get("q")?.trim().toLowerCase();
+ const issues = companyId === "company-storybook" ? storybookIssues : [];
+ return Response.json(
+ query
+ ? issues.filter((issue) =>
+ `${issue.identifier ?? ""} ${issue.title} ${issue.description ?? ""}`.toLowerCase().includes(query),
+ )
+ : issues,
+ );
+ }
+ }
+
+ if (url.pathname.startsWith("/api/invites/") && url.pathname.endsWith("/logo")) {
+ return new Response(null, { status: 204 });
+ }
+
+ return originalFetch(input, init);
+ };
+}
+
+function applyStorybookTheme(theme: "light" | "dark") {
+ if (typeof document === "undefined") return;
+ document.documentElement.classList.toggle("dark", theme === "dark");
+ document.documentElement.style.colorScheme = theme;
+}
+
+function StorybookProviders({
+ children,
+ theme,
+}: {
+ children: ReactNode;
+ theme: "light" | "dark";
+}) {
+ const [queryClient] = useState(
+ () =>
+ new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Number.POSITIVE_INFINITY,
+ },
+ },
+ }),
+ );
+
+ useEffect(() => {
+ applyStorybookTheme(theme);
+ installStorybookApiFixtures();
+ }, [theme]);
+
+ return (
+ <QueryClientProvider client={queryClient}>
+ <ThemeProvider>
+ <MemoryRouter initialEntries={["/PAP/storybook"]}>
+ <CompanyProvider>
+ <EditorAutocompleteProvider>
+ <ToastProvider>
+ <TooltipProvider>
+ <BreadcrumbProvider>
+ <SidebarProvider>
+ <PanelProvider>
+ <DialogProvider>{children}</DialogProvider>
+ </PanelProvider>
+ </SidebarProvider>
+ </BreadcrumbProvider>
+ </TooltipProvider>
+ </ToastProvider>
+ </EditorAutocompleteProvider>
+ </CompanyProvider>
+ </MemoryRouter>
+ </ThemeProvider>
+ </QueryClientProvider>
+ );
+}
+
+const preview: Preview = {
+ decorators: [
+ (Story, context) => {
+ const theme = context.globals.theme === "light" ? "light" : "dark";
+ return (
+ <StorybookProviders key={theme} theme={theme}>
+ <Story />
+ </StorybookProviders>
+ );
+ },
+ ],
+ globalTypes: {
+ theme: {
+ description: "Paperclip color mode",
+ defaultValue: "dark",
+ toolbar: {
+ title: "Theme",
+ icon: "mirror",
+ items: [
+ { value: "dark", title: "Dark" },
+ { value: "light", title: "Light" },
+ ],
+ dynamicTitle: true,
+ },
+ },
+ },
+ parameters: {
+ actions: { argTypesRegex: "^on[A-Z].*" },
+ a11y: {
+ test: "error",
+ },
+ backgrounds: {
+ disable: true,
+ },
+ controls: {
+ expanded: true,
+ matchers: {
+ color: /(background|color)$/i,
+ date: /Date$/i,
+ },
+ },
+ docs: {
+ toc: true,
+ },
+ layout: "fullscreen",
+ viewport: {
+ viewports: {
+ mobile: {
+ name: "Mobile",
+ styles: { width: "390px", height: "844px" },
+ },
+ tablet: {
+ name: "Tablet",
+ styles: { width: "834px", height: "1112px" },
+ },
+ desktop: {
+ name: "Desktop",
+ styles: { width: "1440px", height: "960px" },
+ },
+ },
+ },
+ },
+};
+
+export default preview;
diff --git a/ui/storybook/.storybook/styles.css b/ui/storybook/.storybook/styles.css
new file mode 100644
index 0000000000..c3bfb71314
--- /dev/null
+++ b/ui/storybook/.storybook/styles.css
@@ -0,0 +1,49 @@
+html,
+body,
+#storybook-root {
+ min-height: 100%;
+}
+
+body {
+ overflow: auto;
+ background: var(--background);
+}
+
+.sb-show-main {
+ background: var(--background);
+ color: var(--foreground);
+}
+
+.paperclip-story {
+ min-height: 100vh;
+ background:
+ linear-gradient(180deg, color-mix(in oklab, var(--muted) 28%, transparent), transparent 340px),
+ var(--background);
+ color: var(--foreground);
+ padding: 24px;
+}
+
+.paperclip-story__inner {
+ margin: 0 auto;
+ max-width: 1180px;
+}
+
+.paperclip-story__frame {
+ border: 1px solid var(--border);
+ background: color-mix(in oklab, var(--card) 86%, transparent);
+ box-shadow: 0 24px 90px color-mix(in oklab, black 16%, transparent);
+}
+
+.paperclip-story__label {
+ color: var(--muted-foreground);
+ font-size: 11px;
+ font-weight: 700;
+ letter-spacing: 0.18em;
+ text-transform: uppercase;
+}
+
+@media (max-width: 640px) {
+ .paperclip-story {
+ padding: 16px;
+ }
+}
diff --git a/ui/storybook/.storybook/tailwind-entry.css b/ui/storybook/.storybook/tailwind-entry.css
new file mode 100644
index 0000000000..4d76eea8f7
--- /dev/null
+++ b/ui/storybook/.storybook/tailwind-entry.css
@@ -0,0 +1,2 @@
+@import "../../src/index.css";
+@source "../../src";
diff --git a/ui/storybook/fixtures/paperclipData.ts b/ui/storybook/fixtures/paperclipData.ts
new file mode 100644
index 0000000000..60b88476e3
--- /dev/null
+++ b/ui/storybook/fixtures/paperclipData.ts
@@ -0,0 +1,1301 @@
+import type {
+ ActivityEvent,
+ Agent,
+ Approval,
+ AuthSession,
+ BudgetPolicySummary,
+ Company,
+ DashboardSummary,
+ ExecutionWorkspace,
+ Goal,
+ Issue,
+ IssueDocument,
+ IssueLabel,
+ Project,
+ SidebarBadges,
+ WorkspaceRuntimeService,
+} from "@paperclipai/shared";
+import type { RunForIssue } from "@/api/activity";
+import type { LiveRunForIssue } from "@/api/heartbeats";
+
+const now = new Date("2026-04-20T12:00:00.000Z");
+const recent = (minutesAgo: number) => new Date(now.getTime() - minutesAgo * 60_000);
+const storybookRepoRoot = "~/paperclip";
+const storybookWorkspaceRoot = `${storybookRepoRoot}/.paperclip/workspaces`;
+const storybookWorktreeRoot = `${storybookRepoRoot}/.paperclip/worktrees`;
+
+export const storybookCompanies: Company[] = [
+ {
+ id: "company-storybook",
+ name: "Paperclip Storybook",
+ description: "Fixture company for isolated UI review.",
+ status: "active",
+ pauseReason: null,
+ pausedAt: null,
+ issuePrefix: "PAP",
+ issueCounter: 1641,
+ budgetMonthlyCents: 250_000,
+ spentMonthlyCents: 67_500,
+ requireBoardApprovalForNewAgents: true,
+ feedbackDataSharingEnabled: true,
+ feedbackDataSharingConsentAt: null,
+ feedbackDataSharingConsentByUserId: null,
+ feedbackDataSharingTermsVersion: null,
+ brandColor: "#0f766e",
+ logoAssetId: null,
+ logoUrl: null,
+ createdAt: new Date("2026-04-01T09:00:00.000Z"),
+ updatedAt: now,
+ },
+ {
+ id: "company-research",
+ name: "Research Bureau",
+ description: "A second active company for rail and switcher state coverage.",
+ status: "active",
+ pauseReason: null,
+ pausedAt: null,
+ issuePrefix: "RES",
+ issueCounter: 88,
+ budgetMonthlyCents: 180_000,
+ spentMonthlyCents: 39_500,
+ requireBoardApprovalForNewAgents: false,
+ feedbackDataSharingEnabled: false,
+ feedbackDataSharingConsentAt: null,
+ feedbackDataSharingConsentByUserId: null,
+ feedbackDataSharingTermsVersion: null,
+ brandColor: "#4f46e5",
+ logoAssetId: null,
+ logoUrl: null,
+ createdAt: new Date("2026-04-03T09:00:00.000Z"),
+ updatedAt: recent(10),
+ },
+ {
+ id: "company-paused",
+ name: "Launch Ops",
+ description: "Paused company for inactive switcher treatment.",
+ status: "paused",
+ pauseReason: "manual",
+ pausedAt: recent(240),
+ issuePrefix: "OPS",
+ issueCounter: 204,
+ budgetMonthlyCents: 90_000,
+ spentMonthlyCents: 91_200,
+ requireBoardApprovalForNewAgents: true,
+ feedbackDataSharingEnabled: false,
+ feedbackDataSharingConsentAt: null,
+ feedbackDataSharingConsentByUserId: null,
+ feedbackDataSharingTermsVersion: null,
+ brandColor: "#c2410c",
+ logoAssetId: null,
+ logoUrl: null,
+ createdAt: new Date("2026-04-05T09:00:00.000Z"),
+ updatedAt: recent(240),
+ },
+];
+
+export const storybookAuthSession: AuthSession = {
+ session: {
+ id: "session-storybook",
+ userId: "user-board",
+ },
+ user: {
+ id: "user-board",
+ name: "Riley Board",
+ email: "[email protected]",
+ image: null,
+ },
+};
+
+export const storybookAgents: Agent[] = [
+ {
+ id: "agent-codex",
+ companyId: "company-storybook",
+ name: "CodexCoder",
+ urlKey: "codexcoder",
+ role: "engineer",
+ title: "Senior Product Engineer",
+ icon: "code",
+ status: "running",
+ reportsTo: "agent-cto",
+ capabilities: "Ships full-stack Paperclip product tasks, Storybook coverage, and verification.",
+ adapterType: "codex_local",
+ adapterConfig: {},
+ runtimeConfig: {},
+ budgetMonthlyCents: 125_000,
+ spentMonthlyCents: 43_200,
+ pauseReason: null,
+ pausedAt: null,
+ permissions: { canCreateAgents: false },
+ lastHeartbeatAt: recent(3),
+ metadata: null,
+ createdAt: recent(12_000),
+ updatedAt: recent(3),
+ },
+ {
+ id: "agent-qa",
+ companyId: "company-storybook",
+ name: "QAChecker",
+ urlKey: "qachecker",
+ role: "qa",
+ title: "QA Engineer",
+ icon: "shield",
+ status: "idle",
+ reportsTo: "agent-cto",
+ capabilities: "Validates browser flows, acceptance criteria, and release smoke tests.",
+ adapterType: "claude_local",
+ adapterConfig: {},
+ runtimeConfig: {},
+ budgetMonthlyCents: 80_000,
+ spentMonthlyCents: 18_900,
+ pauseReason: null,
+ pausedAt: null,
+ permissions: { canCreateAgents: false },
+ lastHeartbeatAt: recent(24),
+ metadata: null,
+ createdAt: recent(11_000),
+ updatedAt: recent(24),
+ },
+ {
+ id: "agent-cto",
+ companyId: "company-storybook",
+ name: "CTO",
+ urlKey: "cto",
+ role: "cto",
+ title: "CTO",
+ icon: "crown",
+ status: "active",
+ reportsTo: null,
+ capabilities: "Reviews architecture, quality gates, and engineering priority tradeoffs.",
+ adapterType: "codex_local",
+ adapterConfig: {},
+ runtimeConfig: {},
+ budgetMonthlyCents: 200_000,
+ spentMonthlyCents: 54_000,
+ pauseReason: null,
+ pausedAt: null,
+ permissions: { canCreateAgents: true },
+ lastHeartbeatAt: recent(41),
+ metadata: null,
+ createdAt: recent(14_000),
+ updatedAt: recent(41),
+ },
+];
+
+export const storybookAgentMap = new Map(storybookAgents.map((agent) => [agent.id, agent]));
+
+export const storybookIssueLabels: IssueLabel[] = [
+ {
+ id: "label-ui",
+ companyId: "company-storybook",
+ name: "UI",
+ color: "#0f766e",
+ createdAt: recent(20_000),
+ updatedAt: recent(20_000),
+ },
+ {
+ id: "label-docs",
+ companyId: "company-storybook",
+ name: "Design system",
+ color: "#f59e0b",
+ createdAt: recent(20_000),
+ updatedAt: recent(20_000),
+ },
+ {
+ id: "label-backend",
+ companyId: "company-storybook",
+ name: "API",
+ color: "#2563eb",
+ createdAt: recent(18_000),
+ updatedAt: recent(18_000),
+ },
+ {
+ id: "label-risk",
+ companyId: "company-storybook",
+ name: "Risk",
+ color: "#dc2626",
+ createdAt: recent(16_000),
+ updatedAt: recent(16_000),
+ },
+];
+
+const storybookIssueLabelMap = new Map(storybookIssueLabels.map((label) => [label.id, label]));
+
+function labelsFor(ids: string[]) {
+ return ids.map((id) => storybookIssueLabelMap.get(id)).filter((label): label is IssueLabel => Boolean(label));
+}
+
+export const storybookGoals: Goal[] = [
+ {
+ id: "goal-company",
+ companyId: "company-storybook",
+ title: "Build Paperclip",
+ description: "Make Paperclip the control plane operators trust for autonomous AI companies.",
+ level: "company",
+ status: "active",
+ parentId: null,
+ ownerAgentId: "agent-cto",
+ createdAt: recent(30_000),
+ updatedAt: recent(8),
+ },
+ {
+ id: "goal-board-ux",
+ companyId: "company-storybook",
+ title: "Tighten board operator visibility",
+ description: "Every project, goal, and workspace surface should reveal ownership, progress, and runtime state at a glance.",
+ level: "team",
+ status: "active",
+ parentId: "goal-company",
+ ownerAgentId: "agent-codex",
+ createdAt: recent(19_000),
+ updatedAt: recent(18),
+ },
+ {
+ id: "goal-agent-runtime",
+ companyId: "company-storybook",
+ title: "Stabilize agent runtime loops",
+ description: "Keep local and isolated workspaces predictable while preserving operator control.",
+ level: "team",
+ status: "planned",
+ parentId: "goal-company",
+ ownerAgentId: "agent-cto",
+ createdAt: recent(17_500),
+ updatedAt: recent(60),
+ },
+ {
+ id: "goal-storybook",
+ companyId: "company-storybook",
+ title: "Complete Storybook review coverage",
+ description: "Capture dense board UI states in fixture-backed stories before release review.",
+ level: "task",
+ status: "active",
+ parentId: "goal-board-ux",
+ ownerAgentId: "agent-codex",
+ createdAt: recent(9_000),
+ updatedAt: recent(3),
+ },
+ {
+ id: "goal-budget-safety",
+ companyId: "company-storybook",
+ title: "Enforce spend guardrails",
+ description: "Budget hard stops should be visible before they surprise operators.",
+ level: "agent",
+ status: "achieved",
+ parentId: "goal-agent-runtime",
+ ownerAgentId: "agent-qa",
+ createdAt: recent(12_000),
+ updatedAt: recent(120),
+ },
+ {
+ id: "goal-archived-import",
+ companyId: "company-storybook",
+ title: "Retire old import wizard",
+ description: "Legacy import wizard work is preserved for audit only.",
+ level: "task",
+ status: "cancelled",
+ parentId: "goal-board-ux",
+ ownerAgentId: null,
+ createdAt: recent(24_000),
+ updatedAt: recent(2_500),
+ },
+];
+
+function createRuntimeService(
+ overrides: Partial<WorkspaceRuntimeService> = {},
+): WorkspaceRuntimeService {
+ return {
+ id: overrides.id ?? "service-storybook",
+ companyId: overrides.companyId ?? "company-storybook",
+ projectId: overrides.projectId ?? "project-board-ui",
+ projectWorkspaceId: overrides.projectWorkspaceId ?? "workspace-board-ui",
+ executionWorkspaceId: overrides.executionWorkspaceId ?? "execution-workspace-storybook",
+ issueId: overrides.issueId ?? "issue-storybook-1",
+ scopeType: overrides.scopeType ?? "execution_workspace",
+ scopeId: overrides.scopeId ?? "execution-workspace-storybook",
+ serviceName: overrides.serviceName ?? "storybook",
+ status: overrides.status ?? "running",
+ lifecycle: overrides.lifecycle ?? "ephemeral",
+ reuseKey: overrides.reuseKey ?? "storybook",
+ command: overrides.command ?? "pnpm storybook",
+ cwd: overrides.cwd ?? `${storybookRepoRoot}/ui`,
+ port: overrides.port ?? 6006,
+ url: overrides.url ?? "http://localhost:6006",
+ provider: overrides.provider ?? "local_process",
+ providerRef: overrides.providerRef ?? null,
+ ownerAgentId: overrides.ownerAgentId ?? "agent-codex",
+ startedByRunId: overrides.startedByRunId ?? "run-storybook",
+ lastUsedAt: overrides.lastUsedAt ?? recent(4),
+ startedAt: overrides.startedAt ?? recent(16),
+ stoppedAt: overrides.stoppedAt ?? null,
+ stopPolicy: overrides.stopPolicy ?? null,
+ healthStatus: overrides.healthStatus ?? "healthy",
+ configIndex: overrides.configIndex ?? 0,
+ createdAt: overrides.createdAt ?? recent(16),
+ updatedAt: overrides.updatedAt ?? recent(4),
+ };
+}
+
+const storybookWorkspaceRuntime = {
+ commands: [
+ {
+ id: "storybook",
+ name: "Storybook",
+ kind: "service",
+ command: "pnpm storybook",
+ cwd: "ui",
+ lifecycle: "shared",
+ },
+ {
+ id: "typecheck-ui",
+ name: "UI typecheck",
+ kind: "job",
+ command: "pnpm --filter @paperclipai/ui typecheck",
+ cwd: ".",
+ },
+ ],
+};
+
+export const storybookProjectWorkspaces: Project["workspaces"] = [
+ {
+ id: "workspace-board-ui",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ name: "Board UI",
+ sourceType: "local_path" as const,
+ cwd: `${storybookRepoRoot}/ui`,
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ repoRef: "master",
+ defaultRef: "master",
+ visibility: "default" as const,
+ setupCommand: "pnpm install",
+ cleanupCommand: null,
+ remoteProvider: null,
+ remoteWorkspaceRef: null,
+ sharedWorkspaceKey: "board-ui",
+ metadata: null,
+ runtimeConfig: {
+ workspaceRuntime: storybookWorkspaceRuntime,
+ desiredState: "running" as const,
+ serviceStates: { storybook: "running" as const },
+ },
+ isPrimary: true,
+ runtimeServices: [createRuntimeService()],
+ createdAt: recent(20_000),
+ updatedAt: recent(4),
+ },
+ {
+ id: "workspace-docs-remote",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ name: "Docs preview sandbox",
+ sourceType: "remote_managed",
+ cwd: null,
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ repoRef: "preview/docs-workspaces",
+ defaultRef: "master",
+ visibility: "advanced",
+ setupCommand: "pnpm install",
+ cleanupCommand: "pnpm dev:stop",
+ remoteProvider: "vercel_sandbox",
+ remoteWorkspaceRef: "vcsb_storybook_docs_0420",
+ sharedWorkspaceKey: "docs-preview",
+ metadata: { region: "iad1", ttlHours: 8 },
+ runtimeConfig: {
+ workspaceRuntime: {
+ commands: [
+ {
+ id: "docs",
+ name: "Docs preview",
+ kind: "service",
+ command: "pnpm docs:dev",
+ cwd: ".",
+ lifecycle: "ephemeral",
+ },
+ ],
+ },
+ desiredState: "stopped",
+ serviceStates: { docs: "stopped" },
+ },
+ isPrimary: false,
+ runtimeServices: [
+ createRuntimeService({
+ id: "service-docs-preview",
+ projectWorkspaceId: "workspace-docs-remote",
+ executionWorkspaceId: null,
+ issueId: "issue-storybook-6",
+ scopeType: "project_workspace",
+ scopeId: "workspace-docs-remote",
+ serviceName: "docs",
+ status: "stopped",
+ lifecycle: "ephemeral",
+ reuseKey: "docs-preview",
+ command: "pnpm docs:dev",
+ cwd: null,
+ port: 4173,
+ url: "https://paperclip-docs-preview.vercel.app",
+ healthStatus: "unknown",
+ lastUsedAt: recent(48),
+ startedAt: recent(72),
+ stoppedAt: recent(46),
+ createdAt: recent(72),
+ updatedAt: recent(46),
+ }),
+ ],
+ createdAt: recent(2_000),
+ updatedAt: recent(46),
+ },
+ {
+ id: "workspace-release-local",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ name: "Release smoke local checkout",
+ sourceType: "local_path",
+ cwd: `${storybookWorkspaceRoot}/release-smoke`,
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ repoRef: "release/smoke-2026-04-20",
+ defaultRef: "master",
+ visibility: "advanced",
+ setupCommand: "pnpm install",
+ cleanupCommand: "pnpm dev:stop",
+ remoteProvider: null,
+ remoteWorkspaceRef: null,
+ sharedWorkspaceKey: "release-smoke",
+ metadata: null,
+ runtimeConfig: {
+ workspaceRuntime: {
+ commands: [
+ {
+ id: "release-smoke",
+ name: "Release smoke",
+ kind: "job",
+ command: "pnpm test:release-smoke",
+ cwd: ".",
+ },
+ ],
+ },
+ desiredState: "stopped",
+ serviceStates: null,
+ },
+ isPrimary: false,
+ runtimeServices: [],
+ createdAt: recent(7_200),
+ updatedAt: recent(90),
+ },
+];
+
+export const storybookExecutionWorkspaces: ExecutionWorkspace[] = [
+ {
+ id: "execution-workspace-storybook",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-board-ui",
+ sourceIssueId: "issue-storybook-1",
+ mode: "isolated_workspace",
+ strategyType: "git_worktree",
+ name: "PAP-1641 storybook worktree",
+ status: "active",
+ cwd: `${storybookWorktreeRoot}/PAP-1641-create-super-detailed-storybooks-for-our-project`,
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ baseRef: "master",
+ branchName: "PAP-1641-create-super-detailed-storybooks-for-our-project",
+ providerType: "git_worktree",
+ providerRef: null,
+ derivedFromExecutionWorkspaceId: null,
+ lastUsedAt: recent(3),
+ openedAt: recent(90),
+ closedAt: null,
+ cleanupEligibleAt: null,
+ cleanupReason: null,
+ config: null,
+ metadata: null,
+ runtimeServices: storybookProjectWorkspaces[0]!.runtimeServices,
+ createdAt: recent(90),
+ updatedAt: recent(3),
+ },
+ {
+ id: "execution-workspace-cleanup",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-release-local",
+ sourceIssueId: "issue-storybook-8",
+ mode: "isolated_workspace",
+ strategyType: "git_worktree",
+ name: "PAP-1608 release smoke cleanup",
+ status: "cleanup_failed",
+ cwd: `${storybookWorktreeRoot}/PAP-1608-release-smoke-cleanup`,
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ baseRef: "master",
+ branchName: "PAP-1608-release-smoke-cleanup",
+ providerType: "git_worktree",
+ providerRef: null,
+ derivedFromExecutionWorkspaceId: null,
+ lastUsedAt: recent(120),
+ openedAt: recent(260),
+ closedAt: recent(118),
+ cleanupEligibleAt: recent(115),
+ cleanupReason: "release smoke finished but the local worktree still has generated artifacts",
+ config: {
+ provisionCommand: null,
+ teardownCommand: "pnpm dev:stop && rm -rf ui/storybook-static",
+ cleanupCommand: null,
+ workspaceRuntime: storybookWorkspaceRuntime,
+ desiredState: "stopped",
+ serviceStates: { storybook: "stopped" },
+ },
+ metadata: { dirtyEntryCount: 3 },
+ runtimeServices: [
+ createRuntimeService({
+ id: "service-cleanup-storybook",
+ projectWorkspaceId: "workspace-release-local",
+ executionWorkspaceId: "execution-workspace-cleanup",
+ issueId: "issue-storybook-8",
+ scopeId: "execution-workspace-cleanup",
+ status: "failed",
+ healthStatus: "unhealthy",
+ url: "http://localhost:6007",
+ port: 6007,
+ lastUsedAt: recent(130),
+ startedAt: recent(210),
+ stoppedAt: recent(125),
+ updatedAt: recent(120),
+ }),
+ ],
+ createdAt: recent(260),
+ updatedAt: recent(120),
+ },
+];
+
+function createProject(overrides: Partial<Project> = {}): Project {
+ const id = overrides.id ?? "project-board-ui";
+ return {
+ id,
+ companyId: "company-storybook",
+ urlKey: "board-ui",
+ goalId: "goal-company",
+ goalIds: ["goal-company", "goal-board-ux"],
+ goals: storybookGoals
+ .filter((goal) => goal.id === "goal-company" || goal.id === "goal-board-ux")
+ .map(({ id, title }) => ({ id, title })),
+ name: "Board UI",
+ description: "Navigation, command, and operator layout polish.",
+ status: "in_progress",
+ leadAgentId: "agent-codex",
+ targetDate: "2026-04-30",
+ color: "#0f766e",
+ env: null,
+ pauseReason: null,
+ pausedAt: null,
+ executionWorkspacePolicy: {
+ enabled: true,
+ defaultMode: "isolated_workspace",
+ allowIssueOverride: true,
+ defaultProjectWorkspaceId: "workspace-board-ui",
+ workspaceStrategy: {
+ type: "git_worktree",
+ baseRef: "master",
+ branchTemplate: "{issueIdentifier}-{slug}",
+ worktreeParentDir: storybookWorktreeRoot,
+ provisionCommand: null,
+ teardownCommand: null,
+ },
+ workspaceRuntime: null,
+ branchPolicy: null,
+ pullRequestPolicy: null,
+ runtimePolicy: null,
+ cleanupPolicy: null,
+ },
+ codebase: {
+ workspaceId: "workspace-board-ui",
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ repoRef: "master",
+ defaultRef: "master",
+ repoName: "paperclip",
+ localFolder: storybookRepoRoot,
+ managedFolder: ".paperclip/worktrees/storybook",
+ effectiveLocalFolder: storybookRepoRoot,
+ origin: "local_folder",
+ },
+ workspaces: storybookProjectWorkspaces,
+ primaryWorkspace: storybookProjectWorkspaces[0]!,
+ archivedAt: null,
+ createdAt: recent(18_000),
+ updatedAt: recent(12),
+ ...overrides,
+ };
+}
+
+export const storybookProjects: Project[] = [
+ createProject(),
+ createProject({
+ id: "project-runtime",
+ urlKey: "agent-runtime",
+ name: "Agent Runtime",
+ description: "Heartbeat, adapters, and execution trace work.",
+ status: "planned",
+ leadAgentId: "agent-cto",
+ color: "#2563eb",
+ updatedAt: recent(60),
+ }),
+ createProject({
+ id: "project-budget",
+ urlKey: "budget-guardrails",
+ name: "Budget Guardrails",
+ description: "Hard-stop and approval flow review surfaces.",
+ status: "in_progress",
+ leadAgentId: "agent-qa",
+ color: "#f59e0b",
+ pauseReason: "budget",
+ pausedAt: recent(90),
+ updatedAt: recent(90),
+ }),
+ createProject({
+ id: "project-archived-import",
+ urlKey: "archived-import-wizard",
+ name: "Archived Import Wizard",
+ description: "Preserved for audit after the import workflow moved into company packages.",
+ status: "cancelled",
+ leadAgentId: null,
+ goalId: "goal-archived-import",
+ goalIds: ["goal-archived-import"],
+ goals: [{ id: "goal-archived-import", title: "Retire old import wizard" }],
+ color: "#64748b",
+ workspaces: [],
+ primaryWorkspace: null,
+ codebase: {
+ workspaceId: null,
+ repoUrl: null,
+ repoRef: null,
+ defaultRef: null,
+ repoName: null,
+ localFolder: null,
+ managedFolder: "",
+ effectiveLocalFolder: "Not configured",
+ origin: "local_folder",
+ },
+ executionWorkspacePolicy: {
+ enabled: false,
+ defaultMode: "shared_workspace",
+ allowIssueOverride: false,
+ defaultProjectWorkspaceId: null,
+ workspaceStrategy: null,
+ workspaceRuntime: null,
+ branchPolicy: null,
+ pullRequestPolicy: null,
+ runtimePolicy: null,
+ cleanupPolicy: null,
+ },
+ archivedAt: recent(2_400),
+ updatedAt: recent(2_400),
+ }),
+];
+
+export function createIssue(overrides: Partial<Issue> = {}): Issue {
+ return {
+ id: "issue-storybook-1",
+ companyId: "company-storybook",
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-board-ui",
+ goalId: "goal-company",
+ parentId: null,
+ title: "Create super-detailed storybooks for the project",
+ description: "Set up Storybook and move UX review surfaces into stories.",
+ status: "in_progress",
+ priority: "high",
+ assigneeAgentId: "agent-codex",
+ assigneeUserId: null,
+ checkoutRunId: "run-storybook",
+ executionRunId: "run-storybook",
+ executionAgentNameKey: "codexcoder",
+ executionLockedAt: recent(28),
+ createdByAgentId: null,
+ createdByUserId: "user-board",
+ issueNumber: 1641,
+ identifier: "PAP-1641",
+ requestDepth: 0,
+ billingCode: "product",
+ assigneeAdapterOverrides: null,
+ executionWorkspaceId: "execution-workspace-storybook",
+ executionWorkspacePreference: "project",
+ executionWorkspaceSettings: null,
+ startedAt: recent(28),
+ completedAt: null,
+ cancelledAt: null,
+ hiddenAt: null,
+ labelIds: ["label-ui", "label-docs"],
+ labels: labelsFor(["label-ui", "label-docs"]),
+ blockedBy: [],
+ blocks: [],
+ planDocument: null,
+ documentSummaries: [],
+ legacyPlanDocument: null,
+ project: storybookProjects[0]!,
+ goal: null,
+ currentExecutionWorkspace: storybookExecutionWorkspaces[0]!,
+ workProducts: [],
+ mentionedProjects: [],
+ myLastTouchAt: recent(8),
+ lastExternalCommentAt: recent(70),
+ lastActivityAt: recent(3),
+ isUnreadForMe: true,
+ createdAt: recent(90),
+ updatedAt: recent(3),
+ ...overrides,
+ };
+}
+
+export const storybookIssues: Issue[] = [
+ createIssue(),
+ createIssue({
+ id: "issue-storybook-2",
+ title: "Add budget hard-stop incident review",
+ description: "Trace why a hard stop paused the agent and add a board-facing incident summary.",
+ status: "blocked",
+ priority: "critical",
+ assigneeAgentId: "agent-qa",
+ checkoutRunId: null,
+ executionRunId: null,
+ executionLockedAt: null,
+ startedAt: null,
+ identifier: "PAP-1528",
+ issueNumber: 1528,
+ billingCode: "reliability",
+ projectId: "project-budget",
+ projectWorkspaceId: null,
+ labelIds: ["label-risk", "label-backend"],
+ labels: labelsFor(["label-risk", "label-backend"]),
+ blockedBy: [
+ {
+ id: "issue-storybook-7",
+ identifier: "PAP-1591",
+ title: "Confirm project budget override policy",
+ status: "in_review",
+ priority: "high",
+ assigneeAgentId: null,
+ assigneeUserId: "user-board",
+ },
+ ],
+ lastActivityAt: recent(18),
+ }),
+ createIssue({
+ id: "issue-storybook-3",
+ title: "QA invite flow on authenticated private mode",
+ status: "in_review",
+ priority: "medium",
+ assigneeAgentId: null,
+ assigneeUserId: "user-board",
+ checkoutRunId: null,
+ executionRunId: null,
+ executionLockedAt: null,
+ identifier: "PAP-1602",
+ issueNumber: 1602,
+ completedAt: null,
+ lastActivityAt: recent(49),
+ isUnreadForMe: false,
+ }),
+ createIssue({
+ id: "issue-storybook-4",
+ parentId: "issue-storybook-1",
+ title: "Extract issue row density fixtures",
+ description: "Create fixture-backed rows for unread, selected, nested, and grouped issue management views.",
+ status: "todo",
+ priority: "medium",
+ assigneeAgentId: "agent-codex",
+ checkoutRunId: null,
+ executionRunId: null,
+ executionLockedAt: null,
+ startedAt: null,
+ identifier: "PAP-1668",
+ issueNumber: 1668,
+ labelIds: ["label-ui"],
+ labels: labelsFor(["label-ui"]),
+ lastActivityAt: recent(31),
+ isUnreadForMe: true,
+ }),
+ createIssue({
+ id: "issue-storybook-5",
+ parentId: "issue-storybook-1",
+ title: "Review document editor empty states",
+ description: "Validate plan and notes documents in issue detail before handing the Storybook preview to QA.",
+ status: "done",
+ priority: "low",
+ assigneeAgentId: "agent-qa",
+ checkoutRunId: null,
+ executionRunId: "run-storybook-qa",
+ executionLockedAt: null,
+ completedAt: recent(22),
+ identifier: "PAP-1669",
+ issueNumber: 1669,
+ labelIds: ["label-docs"],
+ labels: labelsFor(["label-docs"]),
+ lastActivityAt: recent(22),
+ isUnreadForMe: false,
+ }),
+ createIssue({
+ id: "issue-storybook-6",
+ title: "Publish static Storybook preview",
+ description: "Build the static preview and attach the generated artifact to the parent issue.",
+ status: "todo",
+ priority: "high",
+ assigneeAgentId: null,
+ assigneeUserId: null,
+ checkoutRunId: null,
+ executionRunId: null,
+ executionLockedAt: null,
+ startedAt: null,
+ identifier: "PAP-1670",
+ issueNumber: 1670,
+ labelIds: ["label-ui", "label-risk"],
+ labels: labelsFor(["label-ui", "label-risk"]),
+ lastActivityAt: recent(64),
+ isUnreadForMe: false,
+ }),
+ createIssue({
+ id: "issue-storybook-7",
+ title: "Confirm project budget override policy",
+ description: "Board review needed before increasing the project budget for long-running browser verification.",
+ status: "in_review",
+ priority: "high",
+ assigneeAgentId: null,
+ assigneeUserId: "user-board",
+ checkoutRunId: null,
+ executionRunId: null,
+ executionLockedAt: null,
+ startedAt: null,
+ identifier: "PAP-1591",
+ issueNumber: 1591,
+ billingCode: "governance",
+ projectId: "project-budget",
+ projectWorkspaceId: null,
+ labelIds: ["label-risk"],
+ labels: labelsFor(["label-risk"]),
+ lastActivityAt: recent(85),
+ isUnreadForMe: false,
+ }),
+ createIssue({
+ id: "issue-storybook-8",
+ title: "Clean up release smoke worktree",
+ description: "Close the isolated release smoke workspace after static preview review.",
+ status: "blocked",
+ priority: "medium",
+ assigneeAgentId: "agent-codex",
+ checkoutRunId: null,
+ executionRunId: "run-release-smoke-cleanup",
+ executionLockedAt: null,
+ startedAt: recent(260),
+ identifier: "PAP-1608",
+ issueNumber: 1608,
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-release-local",
+ executionWorkspaceId: "execution-workspace-cleanup",
+ labelIds: ["label-ui", "label-risk"],
+ labels: labelsFor(["label-ui", "label-risk"]),
+ lastActivityAt: recent(120),
+ isUnreadForMe: false,
+ }),
+];
+
+export const storybookIssueDocuments: IssueDocument[] = [
+ {
+ id: "document-plan-storybook",
+ companyId: "company-storybook",
+ issueId: "issue-storybook-1",
+ key: "plan",
+ title: "Plan",
+ format: "markdown",
+ body: [
+ "# Plan",
+ "",
+ "- Add issue-management stories for list, filters, detail, documents, runs, and workspace cards.",
+ "- Use existing product components instead of mock-only approximations.",
+ "- Verify the Storybook build after the fixture expansion.",
+ ].join("\n"),
+ latestRevisionId: "revision-plan-3",
+ latestRevisionNumber: 3,
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ updatedByAgentId: "agent-codex",
+ updatedByUserId: null,
+ createdAt: recent(80),
+ updatedAt: recent(8),
+ },
+ {
+ id: "document-notes-storybook",
+ companyId: "company-storybook",
+ issueId: "issue-storybook-1",
+ key: "notes",
+ title: "Review Notes",
+ format: "markdown",
+ body: [
+ "# Review Notes",
+ "",
+ "- The issue list needs group headers and dense trailing columns.",
+ "- The filters popover should show selected status, priority, and assignee filters.",
+ "- Workspace copy must expose branch, path, and runtime status.",
+ ].join("\n"),
+ latestRevisionId: "revision-notes-1",
+ latestRevisionNumber: 1,
+ createdByAgentId: null,
+ createdByUserId: "user-board",
+ updatedByAgentId: null,
+ updatedByUserId: "user-board",
+ createdAt: recent(55),
+ updatedAt: recent(12),
+ },
+];
+
+export const storybookContinuationHandoff: IssueDocument = {
+ id: "document-continuation-storybook",
+ companyId: "company-storybook",
+ issueId: "issue-storybook-1",
+ key: "continuation_summary",
+ title: "Continuation handoff",
+ format: "markdown",
+ body: [
+ "Current state: issue-management stories have the fixture surface mapped.",
+ "",
+ "Next action: run the Storybook build, inspect the issue management story, then request QA visual review if the build passes.",
+ "",
+ "Important files: `ui/storybook/stories/issue-management.stories.tsx` and `ui/storybook/fixtures/paperclipData.ts`.",
+ ].join("\n"),
+ latestRevisionId: "revision-continuation-1",
+ latestRevisionNumber: 1,
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ updatedByAgentId: "agent-codex",
+ updatedByUserId: null,
+ createdAt: recent(18),
+ updatedAt: recent(5),
+};
+
+export const storybookIssueRuns: RunForIssue[] = [
+ {
+ runId: "run-storybook",
+ status: "running",
+ agentId: "agent-codex",
+ adapterType: "codex_local",
+ startedAt: recent(28).toISOString(),
+ finishedAt: null,
+ createdAt: recent(28).toISOString(),
+ invocationSource: "manual",
+ usageJson: { costCents: 142, inputTokens: 38400, outputTokens: 7200 },
+ resultJson: null,
+ logBytes: 62_400,
+ livenessState: null,
+ livenessReason: null,
+ continuationAttempt: 1,
+ lastUsefulActionAt: recent(3).toISOString(),
+ nextAction: "Finish the issue-management Storybook and verify the static build.",
+ },
+ {
+ runId: "run-storybook-qa",
+ status: "succeeded",
+ agentId: "agent-qa",
+ adapterType: "claude_local",
+ startedAt: recent(110).toISOString(),
+ finishedAt: recent(94).toISOString(),
+ createdAt: recent(110).toISOString(),
+ invocationSource: "manual",
+ usageJson: { costCents: 38, inputTokens: 12200, outputTokens: 1900 },
+ resultJson: { stopReason: "completed" },
+ logBytes: 18_400,
+ livenessState: "advanced",
+ livenessReason: "Verified the document editor empty state and left concrete screenshot notes.",
+ continuationAttempt: 0,
+ lastUsefulActionAt: recent(96).toISOString(),
+ nextAction: "Re-run after final story fixture additions land.",
+ },
+ {
+ runId: "run-storybook-plan",
+ status: "succeeded",
+ agentId: "agent-codex",
+ adapterType: "codex_local",
+ startedAt: recent(210).toISOString(),
+ finishedAt: recent(196).toISOString(),
+ createdAt: recent(210).toISOString(),
+ invocationSource: "scheduler",
+ usageJson: { costCents: 24, inputTokens: 9100, outputTokens: 1100 },
+ resultJson: { stopReason: "completed" },
+ logBytes: 9800,
+ livenessState: "plan_only",
+ livenessReason: "Identified Storybook coverage gaps but did not edit files in that run.",
+ continuationAttempt: 0,
+ lastUsefulActionAt: null,
+ nextAction: "Implement issue-management stories in the next heartbeat.",
+ },
+];
+
+export const storybookApprovals: Approval[] = [
+ {
+ id: "approval-hire-designer",
+ companyId: "company-storybook",
+ type: "hire_agent",
+ requestedByAgentId: "agent-cto",
+ requestedByUserId: null,
+ status: "pending",
+ payload: {
+ name: "DesignSystemCoder",
+ role: "designer",
+ title: "Design System Engineer",
+ icon: "sparkles",
+ adapterType: "codex_local",
+ capabilities: "Owns component quality, visual regression stories, and design-system consolidation.",
+ desiredSkills: ["frontend-design", "web-design-guidelines"],
+ },
+ decisionNote: null,
+ decidedByUserId: null,
+ decidedAt: null,
+ createdAt: recent(42),
+ updatedAt: recent(42),
+ },
+ {
+ id: "approval-budget",
+ companyId: "company-storybook",
+ type: "budget_override_required",
+ requestedByAgentId: "agent-codex",
+ requestedByUserId: null,
+ status: "revision_requested",
+ payload: {
+ scopeName: "Paperclip App",
+ scopeType: "project",
+ windowKind: "calendar_month_utc",
+ metric: "billed_cents",
+ budgetAmount: 120_000,
+ observedAmount: 131_400,
+ guidance: "Raise the project budget only after current release smoke checks are green.",
+ },
+ decisionNote: "Need a tighter verification list before approving more spend.",
+ decidedByUserId: "user-board",
+ decidedAt: recent(12),
+ createdAt: recent(75),
+ updatedAt: recent(12),
+ },
+ {
+ id: "approval-board",
+ companyId: "company-storybook",
+ type: "request_board_approval",
+ requestedByAgentId: "agent-cto",
+ requestedByUserId: null,
+ status: "approved",
+ payload: {
+ title: "Publish the Storybook preview for design review",
+ summary: "Build the static Storybook and attach the generated URL to the release issue.",
+ recommendedAction: "Approve publishing the preview for internal board review.",
+ nextActionOnApproval: "Run build-storybook, upload the static artifact, and request QA visual review.",
+ risks: [
+ "Stories may expose stale fixture copy if not maintained with UI changes.",
+ "Preview screenshots can hide responsive regressions unless mobile viewports are checked.",
+ ],
+ },
+ decisionNote: "Approved for internal-only review.",
+ decidedByUserId: "user-board",
+ decidedAt: recent(4),
+ createdAt: recent(55),
+ updatedAt: recent(4),
+ },
+];
+
+export const storybookBudgetSummaries: BudgetPolicySummary[] = [
+ {
+ policyId: "budget-company-ok",
+ companyId: "company-storybook",
+ scopeType: "company",
+ scopeId: "company-storybook",
+ scopeName: "Paperclip Storybook",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ amount: 250_000,
+ observedAmount: 67_500,
+ remainingAmount: 182_500,
+ utilizationPercent: 27,
+ warnPercent: 80,
+ hardStopEnabled: true,
+ notifyEnabled: true,
+ isActive: true,
+ status: "ok",
+ paused: false,
+ pauseReason: null,
+ windowStart: new Date("2026-04-01T00:00:00.000Z"),
+ windowEnd: new Date("2026-05-01T00:00:00.000Z"),
+ },
+ {
+ policyId: "budget-project-warning",
+ companyId: "company-storybook",
+ scopeType: "project",
+ scopeId: "project-board-ui",
+ scopeName: "Paperclip App",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ amount: 120_000,
+ observedAmount: 103_100,
+ remainingAmount: 16_900,
+ utilizationPercent: 86,
+ warnPercent: 80,
+ hardStopEnabled: true,
+ notifyEnabled: true,
+ isActive: true,
+ status: "warning",
+ paused: false,
+ pauseReason: null,
+ windowStart: new Date("2026-04-01T00:00:00.000Z"),
+ windowEnd: new Date("2026-05-01T00:00:00.000Z"),
+ },
+ {
+ policyId: "budget-agent-hard-stop",
+ companyId: "company-storybook",
+ scopeType: "agent",
+ scopeId: "agent-codex",
+ scopeName: "CodexCoder",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ amount: 40_000,
+ observedAmount: 43_200,
+ remainingAmount: 0,
+ utilizationPercent: 108,
+ warnPercent: 80,
+ hardStopEnabled: true,
+ notifyEnabled: true,
+ isActive: true,
+ status: "hard_stop",
+ paused: true,
+ pauseReason: "budget",
+ windowStart: new Date("2026-04-01T00:00:00.000Z"),
+ windowEnd: new Date("2026-05-01T00:00:00.000Z"),
+ },
+];
+
+export const storybookActivityEvents: ActivityEvent[] = [
+ {
+ id: "activity-1",
+ companyId: "company-storybook",
+ actorType: "agent",
+ actorId: "agent-codex",
+ action: "issue.status_changed",
+ entityType: "issue",
+ entityId: "issue-storybook-1",
+ agentId: "agent-codex",
+ runId: "run-storybook",
+ details: { from: "todo", to: "in_progress" },
+ createdAt: recent(28),
+ },
+ {
+ id: "activity-2",
+ companyId: "company-storybook",
+ actorType: "user",
+ actorId: "user-board",
+ action: "approval.revision_requested",
+ entityType: "approval",
+ entityId: "approval-budget",
+ agentId: null,
+ runId: null,
+ details: { type: "budget_override_required" },
+ createdAt: recent(12),
+ },
+ {
+ id: "activity-3",
+ companyId: "company-storybook",
+ actorType: "system",
+ actorId: "system",
+ action: "budget.hard_stop",
+ entityType: "agent",
+ entityId: "agent-codex",
+ agentId: "agent-codex",
+ runId: null,
+ details: { observedAmount: 43_200, budgetAmount: 40_000 },
+ createdAt: recent(7),
+ },
+];
+
+export const storybookEntityNameMap = new Map<string, string>([
+ ["issue:issue-storybook-1", "PAP-1641"],
+ ["issue:issue-storybook-2", "PAP-1528"],
+ ["issue:issue-storybook-3", "PAP-1602"],
+ ["issue:issue-storybook-4", "PAP-1668"],
+ ["issue:issue-storybook-5", "PAP-1669"],
+ ["issue:issue-storybook-6", "PAP-1670"],
+ ["issue:issue-storybook-7", "PAP-1591"],
+ ["approval:approval-budget", "Budget override"],
+ ["agent:agent-codex", "CodexCoder"],
+ ["agent:agent-qa", "QAChecker"],
+ ["agent:agent-cto", "CTO"],
+]);
+
+export const storybookEntityTitleMap = new Map<string, string>([
+ ["issue:issue-storybook-1", "Create super-detailed storybooks for the project"],
+ ["issue:issue-storybook-2", "Add budget hard-stop incident review"],
+ ["issue:issue-storybook-3", "QA invite flow on authenticated private mode"],
+ ["issue:issue-storybook-4", "Extract issue row density fixtures"],
+ ["issue:issue-storybook-5", "Review document editor empty states"],
+ ["issue:issue-storybook-6", "Publish static Storybook preview"],
+ ["issue:issue-storybook-7", "Confirm project budget override policy"],
+]);
+
+export const storybookSidebarBadges: SidebarBadges = {
+ inbox: 7,
+ approvals: 2,
+ failedRuns: 1,
+ joinRequests: 1,
+};
+
+export const storybookDashboardSummary: DashboardSummary = {
+ companyId: "company-storybook",
+ agents: {
+ active: 3,
+ running: 1,
+ paused: 0,
+ error: 0,
+ },
+ tasks: {
+ open: 12,
+ inProgress: 4,
+ blocked: 1,
+ done: 36,
+ },
+ costs: {
+ monthSpendCents: 67_500,
+ monthBudgetCents: 250_000,
+ monthUtilizationPercent: 27,
+ },
+ pendingApprovals: 2,
+ budgets: {
+ activeIncidents: 1,
+ pendingApprovals: 1,
+ pausedAgents: 0,
+ pausedProjects: 1,
+ },
+ runActivity: [
+ { date: "2026-04-07", succeeded: 4, failed: 0, other: 1, total: 5 },
+ { date: "2026-04-08", succeeded: 5, failed: 1, other: 0, total: 6 },
+ { date: "2026-04-09", succeeded: 3, failed: 0, other: 1, total: 4 },
+ { date: "2026-04-10", succeeded: 6, failed: 0, other: 0, total: 6 },
+ { date: "2026-04-11", succeeded: 4, failed: 1, other: 0, total: 5 },
+ { date: "2026-04-12", succeeded: 2, failed: 0, other: 1, total: 3 },
+ { date: "2026-04-13", succeeded: 5, failed: 0, other: 1, total: 6 },
+ { date: "2026-04-14", succeeded: 6, failed: 1, other: 0, total: 7 },
+ { date: "2026-04-15", succeeded: 4, failed: 0, other: 1, total: 5 },
+ { date: "2026-04-16", succeeded: 7, failed: 0, other: 0, total: 7 },
+ { date: "2026-04-17", succeeded: 6, failed: 1, other: 0, total: 7 },
+ { date: "2026-04-18", succeeded: 3, failed: 0, other: 1, total: 4 },
+ { date: "2026-04-19", succeeded: 5, failed: 0, other: 1, total: 6 },
+ { date: "2026-04-20", succeeded: 4, failed: 0, other: 2, total: 6 },
+ ],
+};
+
+export const storybookLiveRuns: LiveRunForIssue[] = [
+ {
+ id: "run-storybook",
+ status: "running",
+ invocationSource: "manual",
+ triggerDetail: "issue_assigned",
+ startedAt: recent(28).toISOString(),
+ finishedAt: null,
+ createdAt: recent(28).toISOString(),
+ agentId: "agent-codex",
+ agentName: "CodexCoder",
+ adapterType: "codex_local",
+ issueId: "issue-storybook-1",
+ livenessState: "advanced",
+ livenessReason: null,
+ continuationAttempt: 0,
+ lastUsefulActionAt: recent(3).toISOString(),
+ nextAction: "Build fixture-backed navigation stories",
+ },
+];
diff --git a/ui/storybook/stories/agent-management.stories.tsx b/ui/storybook/stories/agent-management.stories.tsx
new file mode 100644
index 0000000000..a77ed84e56
--- /dev/null
+++ b/ui/storybook/stories/agent-management.stories.tsx
@@ -0,0 +1,757 @@
+import { useState, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useQueryClient } from "@tanstack/react-query";
+import { Edit3, RotateCcw, Settings2 } from "lucide-react";
+import {
+ AGENT_ICON_NAMES,
+ type Agent,
+ type AgentRuntimeState,
+ type CompanySecret,
+ type EnvBinding,
+} from "@paperclipai/shared";
+import { ActiveAgentsPanel } from "@/components/ActiveAgentsPanel";
+import { AgentConfigForm, type CreateConfigValues } from "@/components/AgentConfigForm";
+import { defaultCreateValues } from "@/components/agent-config-defaults";
+import {
+ DraftInput,
+ DraftTextarea,
+ Field,
+ ToggleField,
+ help,
+} from "@/components/agent-config-primitives";
+import { AgentIcon, AgentIconPicker } from "@/components/AgentIconPicker";
+import { AgentProperties } from "@/components/AgentProperties";
+import { RunButton, PauseResumeButton } from "@/components/AgentActionButtons";
+import type { LiveRunForIssue } from "@/api/heartbeats";
+import type { AdapterInfo } from "@/api/adapters";
+import { queryKeys } from "@/lib/queryKeys";
+import { cn } from "@/lib/utils";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+import { Separator } from "@/components/ui/separator";
+import { storybookAgents, storybookIssues } from "../fixtures/paperclipData";
+
+const COMPANY_ID = "company-storybook";
+const now = new Date("2026-04-20T12:00:00.000Z");
+const recent = (minutesAgo: number) => new Date(now.getTime() - minutesAgo * 60_000);
+
+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 agentWith(overrides: Partial<Agent>): Agent {
+ return {
+ ...storybookAgents[0]!,
+ ...overrides,
+ adapterConfig: {
+ ...storybookAgents[0]!.adapterConfig,
+ ...(overrides.adapterConfig ?? {}),
+ },
+ runtimeConfig: {
+ ...storybookAgents[0]!.runtimeConfig,
+ ...(overrides.runtimeConfig ?? {}),
+ },
+ permissions: {
+ ...storybookAgents[0]!.permissions,
+ ...(overrides.permissions ?? {}),
+ },
+ metadata: overrides.metadata ?? storybookAgents[0]!.metadata,
+ };
+}
+
+const agentManagementAgents: Agent[] = [
+ agentWith({
+ id: "agent-codex",
+ name: "CodexCoder",
+ urlKey: "codexcoder",
+ status: "running",
+ icon: "code",
+ role: "engineer",
+ title: "Senior Product Engineer",
+ reportsTo: "agent-cto",
+ capabilities: "Owns full-stack product changes, Storybook coverage, and local verification loops.",
+ adapterType: "codex_local",
+ adapterConfig: {
+ command: "codex",
+ model: "gpt-5.4",
+ modelReasoningEffort: "high",
+ search: true,
+ dangerouslyBypassApprovalsAndSandbox: true,
+ promptTemplate:
+ "You are {{ agent.name }}. Work only on the checked-out issue, keep comments concise, and verify before handoff.",
+ instructionsFilePath: "agents/codexcoder/AGENTS.md",
+ extraArgs: ["--full-auto"],
+ env: {
+ OPENAI_API_KEY: { type: "secret_ref", secretId: "secret-openai", version: "latest" },
+ PAPERCLIP_TRACE: { type: "plain", value: "storybook" },
+ } satisfies Record<string, EnvBinding>,
+ timeoutSec: 7200,
+ graceSec: 20,
+ },
+ runtimeConfig: {
+ heartbeat: {
+ enabled: true,
+ intervalSec: 900,
+ wakeOnDemand: true,
+ cooldownSec: 30,
+ maxConcurrentRuns: 2,
+ },
+ },
+ lastHeartbeatAt: recent(2),
+ updatedAt: recent(2),
+ }),
+ agentWith({
+ id: "agent-qa",
+ name: "QAChecker",
+ urlKey: "qachecker",
+ status: "idle",
+ icon: "shield",
+ role: "qa",
+ title: "QA Engineer",
+ reportsTo: "agent-cto",
+ capabilities: "Runs targeted browser checks, release smoke tests, and visual Storybook reviews.",
+ adapterType: "claude_local",
+ adapterConfig: {
+ command: "claude",
+ model: "claude-sonnet-4.5",
+ effort: "medium",
+ dangerouslySkipPermissions: false,
+ chrome: true,
+ instructionsFilePath: "agents/qachecker/AGENTS.md",
+ env: {
+ PLAYWRIGHT_HEADLESS: { type: "plain", value: "false" },
+ } satisfies Record<string, EnvBinding>,
+ },
+ runtimeConfig: {
+ heartbeat: {
+ enabled: false,
+ intervalSec: 1800,
+ wakeOnDemand: true,
+ cooldownSec: 60,
+ maxConcurrentRuns: 1,
+ },
+ },
+ lastHeartbeatAt: recent(31),
+ updatedAt: recent(31),
+ }),
+ agentWith({
+ id: "agent-cto",
+ name: "CTO",
+ urlKey: "cto",
+ status: "paused",
+ icon: "crown",
+ role: "cto",
+ title: "CTO",
+ reportsTo: null,
+ capabilities: "Reviews engineering strategy, architecture risk, and high-impact implementation tradeoffs.",
+ adapterType: "codex_local",
+ pauseReason: "manual",
+ pausedAt: recent(18),
+ permissions: { canCreateAgents: true },
+ adapterConfig: {
+ command: "codex",
+ model: "gpt-5.4",
+ modelReasoningEffort: "xhigh",
+ search: false,
+ },
+ runtimeConfig: {
+ heartbeat: {
+ enabled: true,
+ intervalSec: 3600,
+ wakeOnDemand: false,
+ cooldownSec: 120,
+ maxConcurrentRuns: 1,
+ },
+ },
+ lastHeartbeatAt: recent(57),
+ updatedAt: recent(18),
+ }),
+ agentWith({
+ id: "agent-observability",
+ name: "OpsWatch",
+ urlKey: "opswatch",
+ status: "error",
+ icon: "radar",
+ role: "devops",
+ title: "Runtime Operations Engineer",
+ reportsTo: "agent-cto",
+ capabilities: "Monitors local runners, workspace services, and stuck-run recovery signals.",
+ adapterType: "http",
+ pauseReason: null,
+ pausedAt: null,
+ adapterConfig: {
+ webhookUrl: "https://ops.internal.example/heartbeat",
+ payloadTemplateJson: JSON.stringify({ channel: "paperclip-storybook", priority: "normal" }, null, 2),
+ env: {
+ OPS_WEBHOOK_TOKEN: { type: "secret_ref", secretId: "secret-ops-webhook", version: 3 },
+ } satisfies Record<string, EnvBinding>,
+ },
+ runtimeConfig: {
+ heartbeat: {
+ enabled: true,
+ intervalSec: 600,
+ wakeOnDemand: true,
+ cooldownSec: 45,
+ maxConcurrentRuns: 1,
+ },
+ },
+ lastHeartbeatAt: recent(9),
+ updatedAt: recent(9),
+ }),
+];
+
+const runtimeState: AgentRuntimeState = {
+ agentId: "agent-codex",
+ companyId: COMPANY_ID,
+ adapterType: "codex_local",
+ sessionId: "session-codex-storybook-management-20260420",
+ sessionDisplayId: "codex-storybook-20260420",
+ sessionParamsJson: {
+ issueIdentifier: "PAP-1670",
+ workspaceStrategy: "git_worktree",
+ },
+ stateJson: {
+ currentIssue: "PAP-1670",
+ workspace: "PAP-1641-create-super-detailed-storybooks-for-our-project",
+ },
+ lastRunId: "run-agent-management-live",
+ lastRunStatus: "running",
+ totalInputTokens: 286_400,
+ totalOutputTokens: 42_900,
+ totalCachedInputTokens: 113_200,
+ totalCostCents: 4320,
+ lastError: "Previous run lost its Storybook Vite websocket after a local server restart.",
+ createdAt: recent(8_000),
+ updatedAt: recent(2),
+};
+
+const storybookSecrets: CompanySecret[] = [
+ {
+ id: "secret-openai",
+ companyId: COMPANY_ID,
+ name: "OPENAI_API_KEY",
+ provider: "local_encrypted",
+ externalRef: null,
+ latestVersion: 5,
+ description: "Primary coding model key for local Codex agents.",
+ createdByAgentId: null,
+ createdByUserId: "user-board",
+ createdAt: recent(21_000),
+ updatedAt: recent(400),
+ },
+ {
+ id: "secret-ops-webhook",
+ companyId: COMPANY_ID,
+ name: "OPS_WEBHOOK_TOKEN",
+ provider: "local_encrypted",
+ externalRef: null,
+ latestVersion: 3,
+ description: "Webhook token for runtime observability callbacks.",
+ createdByAgentId: "agent-cto",
+ createdByUserId: null,
+ createdAt: recent(12_000),
+ updatedAt: recent(80),
+ },
+];
+
+const adapterFixtures: AdapterInfo[] = [
+ {
+ type: "codex_local",
+ label: "Codex Local",
+ source: "builtin",
+ modelsCount: 3,
+ loaded: true,
+ disabled: false,
+ capabilities: {
+ supportsInstructionsBundle: true,
+ supportsSkills: true,
+ supportsLocalAgentJwt: true,
+ requiresMaterializedRuntimeSkills: true,
+ },
+ },
+ {
+ type: "claude_local",
+ label: "Claude Local",
+ source: "builtin",
+ modelsCount: 2,
+ loaded: true,
+ disabled: false,
+ capabilities: {
+ supportsInstructionsBundle: true,
+ supportsSkills: true,
+ supportsLocalAgentJwt: true,
+ requiresMaterializedRuntimeSkills: true,
+ },
+ },
+ {
+ type: "http",
+ label: "HTTP Webhook",
+ source: "builtin",
+ modelsCount: 0,
+ loaded: true,
+ disabled: false,
+ capabilities: {
+ supportsInstructionsBundle: false,
+ supportsSkills: false,
+ supportsLocalAgentJwt: false,
+ requiresMaterializedRuntimeSkills: false,
+ },
+ },
+];
+
+const liveRuns: LiveRunForIssue[] = [
+ {
+ id: "run-agent-management-live",
+ status: "running",
+ invocationSource: "assignment",
+ triggerDetail: "issue_assigned",
+ startedAt: recent(8).toISOString(),
+ finishedAt: null,
+ createdAt: recent(8).toISOString(),
+ agentId: "agent-codex",
+ agentName: "CodexCoder",
+ adapterType: "codex_local",
+ issueId: "issue-storybook-1",
+ livenessState: "advanced",
+ livenessReason: null,
+ continuationAttempt: 0,
+ lastUsefulActionAt: recent(1).toISOString(),
+ nextAction: "Run a targeted Storybook static build.",
+ },
+ {
+ id: "run-agent-management-queued",
+ status: "queued",
+ invocationSource: "on_demand",
+ triggerDetail: "manual",
+ startedAt: null,
+ finishedAt: null,
+ createdAt: recent(3).toISOString(),
+ agentId: "agent-qa",
+ agentName: "QAChecker",
+ adapterType: "claude_local",
+ issueId: "issue-storybook-3",
+ livenessState: null,
+ livenessReason: "Waiting for current visual review to finish.",
+ continuationAttempt: 0,
+ lastUsefulActionAt: null,
+ nextAction: "Open the Storybook preview and capture mobile screenshots.",
+ },
+ {
+ id: "run-agent-management-succeeded",
+ status: "succeeded",
+ invocationSource: "timer",
+ triggerDetail: "scheduler",
+ startedAt: recent(48).toISOString(),
+ finishedAt: recent(39).toISOString(),
+ createdAt: recent(48).toISOString(),
+ agentId: "agent-cto",
+ agentName: "CTO",
+ adapterType: "codex_local",
+ issueId: "issue-storybook-2",
+ livenessState: "completed",
+ livenessReason: null,
+ continuationAttempt: 0,
+ lastUsefulActionAt: recent(39).toISOString(),
+ nextAction: null,
+ },
+ {
+ id: "run-agent-management-failed",
+ status: "failed",
+ invocationSource: "automation",
+ triggerDetail: "routine",
+ startedAt: recent(76).toISOString(),
+ finishedAt: recent(70).toISOString(),
+ createdAt: recent(76).toISOString(),
+ agentId: "agent-observability",
+ agentName: "OpsWatch",
+ adapterType: "http",
+ issueId: null,
+ livenessState: "blocked",
+ livenessReason: "Webhook returned 503 during local runtime restart.",
+ continuationAttempt: 1,
+ lastUsefulActionAt: recent(72).toISOString(),
+ nextAction: "Retry after runtime service health check recovers.",
+ },
+];
+
+function StorybookQueryFixtures({ children }: { children: ReactNode }) {
+ const queryClient = useQueryClient();
+
+ queryClient.setQueryData(queryKeys.agents.list(COMPANY_ID), agentManagementAgents);
+ queryClient.setQueryData(queryKeys.secrets.list(COMPANY_ID), storybookSecrets);
+ queryClient.setQueryData(queryKeys.adapters.all, adapterFixtures);
+ queryClient.setQueryData(queryKeys.issues.list(COMPANY_ID), storybookIssues);
+ queryClient.setQueryData([...queryKeys.issues.list(COMPANY_ID), "with-routine-executions"], storybookIssues);
+ queryClient.setQueryData([...queryKeys.liveRuns(COMPANY_ID), "dashboard"], liveRuns);
+ queryClient.setQueryData(queryKeys.instance.generalSettings, { censorUsernameInLogs: false });
+ queryClient.setQueryData(queryKeys.agents.adapterModels(COMPANY_ID, "codex_local"), [
+ { id: "gpt-5.4", label: "GPT-5.4" },
+ { id: "gpt-5.4-mini", label: "GPT-5.4 Mini" },
+ { id: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
+ ]);
+ queryClient.setQueryData(queryKeys.agents.detectModel(COMPANY_ID, "codex_local"), {
+ model: "gpt-5.4",
+ provider: "openai",
+ source: "config",
+ candidates: ["gpt-5.4", "gpt-5.4-mini"],
+ });
+ queryClient.setQueryData(queryKeys.agents.adapterModels(COMPANY_ID, "claude_local"), [
+ { id: "claude-sonnet-4.5", label: "Claude Sonnet 4.5" },
+ { id: "claude-opus-4.1", label: "Claude Opus 4.1" },
+ ]);
+
+ return children;
+}
+
+function AgentConfigFormStory() {
+ const [values, setValues] = useState<CreateConfigValues>({
+ ...defaultCreateValues,
+ adapterType: "codex_local",
+ command: "codex",
+ model: "gpt-5.4",
+ thinkingEffort: "high",
+ search: true,
+ dangerouslyBypassSandbox: true,
+ promptTemplate:
+ "You are {{ agent.name }}. Read the assigned issue, make a small verified change, and update the task.",
+ extraArgs: "--full-auto, --search",
+ envBindings: {
+ OPENAI_API_KEY: { type: "secret_ref", secretId: "secret-openai", version: "latest" },
+ PAPERCLIP_TRACE: { type: "plain", value: "storybook" },
+ },
+ runtimeServicesJson: JSON.stringify(
+ [
+ {
+ name: "storybook",
+ command: "pnpm storybook",
+ url: "http://localhost:6006",
+ },
+ ],
+ null,
+ 2,
+ ),
+ heartbeatEnabled: true,
+ intervalSec: 900,
+ });
+
+ return (
+ <AgentConfigForm
+ mode="create"
+ values={values}
+ onChange={(patch) => setValues((current) => ({ ...current, ...patch }))}
+ sectionLayout="cards"
+ showAdapterTestEnvironmentButton={false}
+ />
+ );
+}
+
+function IconPickerMatrix() {
+ const [selectedIcon, setSelectedIcon] = useState("code");
+ const visibleIcons = AGENT_ICON_NAMES.slice(0, 28);
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-[280px_minmax(0,1fr)]">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Selected identity</CardTitle>
+ <CardDescription>The real picker trigger updates the selected fixture state.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-4">
+ <div className="flex items-center gap-3 rounded-lg border border-border bg-background/70 p-4">
+ <div className="flex h-11 w-11 items-center justify-center rounded-lg border border-border bg-accent/40">
+ <AgentIcon icon={selectedIcon} className="h-5 w-5" />
+ </div>
+ <div>
+ <div className="text-sm font-medium">StorybookEngineer</div>
+ <div className="font-mono text-xs text-muted-foreground">{selectedIcon}</div>
+ </div>
+ </div>
+ <AgentIconPicker value={selectedIcon} onChange={setSelectedIcon}>
+ <Button variant="outline" className="w-full justify-start">
+ <Settings2 className="h-4 w-4" />
+ Open icon picker
+ </Button>
+ </AgentIconPicker>
+ </CardContent>
+ </Card>
+
+ <div className="rounded-xl border border-border bg-background/70 p-4">
+ <div className="grid grid-cols-7 gap-2 sm:grid-cols-10 md:grid-cols-14">
+ {visibleIcons.map((name) => (
+ <button
+ key={name}
+ type="button"
+ title={name}
+ onClick={() => setSelectedIcon(name)}
+ className={cn(
+ "flex h-10 w-10 items-center justify-center rounded-lg border border-border transition-colors hover:bg-accent",
+ selectedIcon === name && "border-primary bg-primary/10 text-primary ring-1 ring-primary",
+ )}
+ >
+ <AgentIcon icon={name} className="h-4 w-4" />
+ </button>
+ ))}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+function AgentActionsMatrix() {
+ const actionAgents = [
+ agentManagementAgents[0]!,
+ agentManagementAgents[1]!,
+ agentManagementAgents[2]!,
+ agentManagementAgents[3]!,
+ ];
+
+ return (
+ <div className="grid gap-4 xl:grid-cols-4">
+ {actionAgents.map((agent) => {
+ const paused = agent.status === "paused";
+ const runDisabled = agent.status === "running" || agent.status === "paused";
+ const restartDisabled = agent.status === "paused";
+
+ return (
+ <Card key={agent.id} className="shadow-none">
+ <CardHeader>
+ <div className="flex items-start justify-between gap-3">
+ <div className="flex items-center gap-3">
+ <span className="flex h-9 w-9 items-center justify-center rounded-lg border border-border bg-accent/40">
+ <AgentIcon icon={agent.icon} className="h-4 w-4" />
+ </span>
+ <div>
+ <CardTitle className="text-base">{agent.name}</CardTitle>
+ <CardDescription>{agent.title}</CardDescription>
+ </div>
+ </div>
+ <Badge variant={agent.status === "error" ? "destructive" : "outline"}>{agent.status}</Badge>
+ </div>
+ </CardHeader>
+ <CardContent className="flex flex-wrap gap-2">
+ <PauseResumeButton
+ isPaused={paused}
+ onPause={() => undefined}
+ onResume={() => undefined}
+ disabled={agent.status === "running"}
+ />
+ <RunButton
+ label={agent.status === "running" ? "Running" : "Run now"}
+ onClick={() => undefined}
+ disabled={runDisabled}
+ />
+ <Button variant="outline" size="sm" disabled={restartDisabled}>
+ <RotateCcw className="h-3.5 w-3.5 sm:mr-1" />
+ <span className="hidden sm:inline">Restart</span>
+ </Button>
+ <Button variant="ghost" size="sm">
+ <Edit3 className="h-3.5 w-3.5 sm:mr-1" />
+ <span className="hidden sm:inline">Edit</span>
+ </Button>
+ </CardContent>
+ </Card>
+ );
+ })}
+ </div>
+ );
+}
+
+function ConfigPrimitivesStory() {
+ const [textValue, setTextValue] = useState("gpt-5.4");
+ const [selectValue, setSelectValue] = useState("git_worktree");
+ const [toggleValue, setToggleValue] = useState(true);
+ const [jsonValue, setJsonValue] = useState(JSON.stringify({
+ runtimeServices: [
+ { name: "api", command: "pnpm dev:once", healthUrl: "http://localhost:3100/api/health" },
+ ],
+ env: { PAPERCLIP_BIND: "lan" },
+ }, null, 2));
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-2">
+ <div className="space-y-4 rounded-xl border border-border bg-background/70 p-4">
+ <Field label="Text field" hint={help.model}>
+ <DraftInput
+ value={textValue}
+ onCommit={setTextValue}
+ immediate
+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 font-mono text-sm outline-none"
+ />
+ </Field>
+ <Field label="Select field" hint={help.workspaceStrategy}>
+ <Select value={selectValue} onValueChange={setSelectValue}>
+ <SelectTrigger className="w-full">
+ <SelectValue placeholder="Workspace strategy" />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="project_primary">Project primary</SelectItem>
+ <SelectItem value="git_worktree">Git worktree</SelectItem>
+ <SelectItem value="agent_home">Agent home</SelectItem>
+ </SelectContent>
+ </Select>
+ </Field>
+ <ToggleField
+ label="Toggle field"
+ hint={help.wakeOnDemand}
+ checked={toggleValue}
+ onChange={setToggleValue}
+ />
+ </div>
+ <div className="rounded-xl border border-border bg-background/70 p-4">
+ <Field label="JSON editor" hint={help.runtimeServicesJson}>
+ <DraftTextarea
+ value={jsonValue}
+ onCommit={setJsonValue}
+ immediate
+ minRows={10}
+ placeholder='{"runtimeServices":[]}'
+ />
+ </Field>
+ </div>
+ </div>
+ );
+}
+
+function AgentManagementStories() {
+ return (
+ <StorybookQueryFixtures>
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner 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">Agent management</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Agent details, controls, and config surfaces</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Management stories exercise the dense pieces of the agent lifecycle: status detail panels,
+ adapter configuration, icon identity, run controls, live-agent cards, and the config-field primitives
+ used inside the form.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">adapter config</Badge>
+ <Badge variant="outline">runtime policy</Badge>
+ <Badge variant="outline">env bindings</Badge>
+ </div>
+ </div>
+ </section>
+
+ <Section eyebrow="AgentProperties" title="Full detail panel with runtime and reporting data">
+ <div className="grid gap-5 lg:grid-cols-[380px_minmax(0,1fr)]">
+ <Card className="shadow-none">
+ <CardHeader>
+ <div className="flex items-start gap-3">
+ <span className="flex h-11 w-11 items-center justify-center rounded-lg border border-border bg-accent/40">
+ <AgentIcon icon={agentManagementAgents[0]!.icon} className="h-5 w-5" />
+ </span>
+ <div>
+ <CardTitle>{agentManagementAgents[0]!.name}</CardTitle>
+ <CardDescription>{agentManagementAgents[0]!.capabilities}</CardDescription>
+ </div>
+ </div>
+ </CardHeader>
+ <CardContent>
+ <AgentProperties agent={agentManagementAgents[0]!} runtimeState={runtimeState} />
+ </CardContent>
+ </Card>
+ <div className="rounded-xl border border-border bg-background/70 p-5">
+ <div className="mb-4 flex flex-wrap gap-2">
+ <Badge variant="secondary">session populated</Badge>
+ <Badge variant="secondary">last error shown</Badge>
+ <Badge variant="secondary">manager lookup seeded</Badge>
+ </div>
+ <div className="grid gap-3 text-sm md:grid-cols-2">
+ <div className="rounded-lg border border-border p-3">
+ <div className="text-xs text-muted-foreground">Budget</div>
+ <div className="mt-1 font-mono">${(agentManagementAgents[0]!.budgetMonthlyCents / 100).toFixed(0)} / month</div>
+ </div>
+ <div className="rounded-lg border border-border p-3">
+ <div className="text-xs text-muted-foreground">Spent</div>
+ <div className="mt-1 font-mono">${(agentManagementAgents[0]!.spentMonthlyCents / 100).toFixed(0)}</div>
+ </div>
+ <div className="rounded-lg border border-border p-3">
+ <div className="text-xs text-muted-foreground">Instructions</div>
+ <div className="mt-1 break-all font-mono text-xs">
+ {String(agentManagementAgents[0]!.adapterConfig.instructionsFilePath)}
+ </div>
+ </div>
+ <div className="rounded-lg border border-border p-3">
+ <div className="text-xs text-muted-foreground">Runtime policy</div>
+ <div className="mt-1 font-mono text-xs">heartbeat / 900s / max 2</div>
+ </div>
+ </div>
+ </div>
+ </div>
+ </Section>
+
+ <Section eyebrow="AgentConfigForm" title="Adapter selection, runtime config, and env vars">
+ <div className="max-w-4xl">
+ <AgentConfigFormStory />
+ </div>
+ </Section>
+
+ <Section eyebrow="AgentIconPicker" title="Available icon grid with selected state">
+ <IconPickerMatrix />
+ </Section>
+
+ <Section eyebrow="AgentActionButtons" title="Pause, resume, restart, edit, and run actions by state">
+ <AgentActionsMatrix />
+ </Section>
+
+ <Section eyebrow="ActiveAgentsPanel" title="Mixed live, queued, succeeded, and failed agent runs">
+ <ActiveAgentsPanel companyId={COMPANY_ID} />
+ </Section>
+
+ <Section eyebrow="agent-config-primitives" title="Individual text, select, toggle, and JSON field types">
+ <ConfigPrimitivesStory />
+ </Section>
+
+ <Separator />
+ </main>
+ </div>
+ </StorybookQueryFixtures>
+ );
+}
+
+const meta = {
+ title: "Product/Agent Management",
+ component: AgentManagementStories,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Agent management stories cover detail, configuration, icon, action, live-run, and config primitive states using extended Paperclip fixtures.",
+ },
+ },
+ },
+} satisfies Meta<typeof AgentManagementStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ManagementMatrix: Story = {};
diff --git a/ui/storybook/stories/budget-finance.stories.tsx b/ui/storybook/stories/budget-finance.stories.tsx
new file mode 100644
index 0000000000..f47ff68aa1
--- /dev/null
+++ b/ui/storybook/stories/budget-finance.stories.tsx
@@ -0,0 +1,774 @@
+import type { ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type {
+ BudgetIncident,
+ CostByBiller,
+ CostByProviderModel,
+ CostWindowSpendRow,
+ FinanceByBiller,
+ FinanceByKind,
+ FinanceEvent,
+ QuotaWindow,
+} from "@paperclipai/shared";
+import { AlertTriangle, CheckCircle2, CreditCard, Landmark, ReceiptText, WalletCards } from "lucide-react";
+import { AccountingModelCard } from "@/components/AccountingModelCard";
+import { BillerSpendCard } from "@/components/BillerSpendCard";
+import { BudgetIncidentCard } from "@/components/BudgetIncidentCard";
+import { BudgetSidebarMarker, type BudgetSidebarMarkerLevel } from "@/components/BudgetSidebarMarker";
+import { ClaudeSubscriptionPanel } from "@/components/ClaudeSubscriptionPanel";
+import { CodexSubscriptionPanel } from "@/components/CodexSubscriptionPanel";
+import { FinanceBillerCard } from "@/components/FinanceBillerCard";
+import { FinanceKindCard } from "@/components/FinanceKindCard";
+import { FinanceTimelineCard } from "@/components/FinanceTimelineCard";
+import { ProviderQuotaCard } from "@/components/ProviderQuotaCard";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+
+const now = new Date("2026-04-20T12:00:00.000Z");
+const windowStart = new Date("2026-04-01T00:00:00.000Z");
+const windowEnd = new Date("2026-05-01T00:00:00.000Z");
+const at = (minutesAgo: number) => new Date(now.getTime() - minutesAgo * 60_000);
+
+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 CaseFrame({
+ title,
+ detail,
+ tone,
+ children,
+}: {
+ title: string;
+ detail: string;
+ tone: "healthy" | "warning" | "critical";
+ children: ReactNode;
+}) {
+ const toneClasses = {
+ healthy: "border-emerald-500/30 bg-emerald-500/5 text-emerald-500",
+ warning: "border-amber-500/30 bg-amber-500/5 text-amber-500",
+ critical: "border-red-500/30 bg-red-500/5 text-red-500",
+ } satisfies Record<typeof tone, string>;
+
+ return (
+ <div className="space-y-3">
+ <div className={`rounded-lg border px-3 py-2 ${toneClasses[tone]}`}>
+ <div className="text-sm font-medium text-foreground">{title}</div>
+ <div className="mt-1 text-xs leading-5 text-muted-foreground">{detail}</div>
+ </div>
+ {children}
+ </div>
+ );
+}
+
+const budgetIncidents: BudgetIncident[] = [
+ {
+ id: "incident-agent-resolved",
+ companyId: "company-storybook",
+ policyId: "budget-agent-codex",
+ scopeType: "agent",
+ scopeId: "agent-codex",
+ scopeName: "CodexCoder",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ windowStart,
+ windowEnd,
+ thresholdType: "hard",
+ amountLimit: 40_000,
+ amountObserved: 42_450,
+ status: "resolved",
+ approvalId: "approval-budget-resolved",
+ approvalStatus: "approved",
+ resolvedAt: at(42),
+ createdAt: at(180),
+ updatedAt: at(42),
+ },
+ {
+ id: "incident-project-pending",
+ companyId: "company-storybook",
+ policyId: "budget-project-app",
+ scopeType: "project",
+ scopeId: "project-board-ui",
+ scopeName: "Paperclip App",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ windowStart,
+ windowEnd,
+ thresholdType: "hard",
+ amountLimit: 120_000,
+ amountObserved: 131_400,
+ status: "open",
+ approvalId: "approval-budget-pending",
+ approvalStatus: "pending",
+ resolvedAt: null,
+ createdAt: at(32),
+ updatedAt: at(8),
+ },
+ {
+ id: "incident-company-escalated",
+ companyId: "company-storybook",
+ policyId: "budget-company",
+ scopeType: "company",
+ scopeId: "company-storybook",
+ scopeName: "Paperclip Storybook",
+ metric: "billed_cents",
+ windowKind: "calendar_month_utc",
+ windowStart,
+ windowEnd,
+ thresholdType: "hard",
+ amountLimit: 250_000,
+ amountObserved: 287_300,
+ status: "open",
+ approvalId: "approval-budget-escalated",
+ approvalStatus: "revision_requested",
+ resolvedAt: null,
+ createdAt: at(14),
+ updatedAt: at(2),
+ },
+];
+
+const providerRowsByProvider: Record<string, CostByProviderModel[]> = {
+ anthropic: [
+ {
+ provider: "anthropic",
+ biller: "anthropic",
+ billingType: "subscription_included",
+ model: "claude-sonnet-4.5",
+ costCents: 0,
+ inputTokens: 1_420_000,
+ cachedInputTokens: 210_000,
+ outputTokens: 385_000,
+ apiRunCount: 0,
+ subscriptionRunCount: 38,
+ subscriptionCachedInputTokens: 210_000,
+ subscriptionInputTokens: 1_420_000,
+ subscriptionOutputTokens: 385_000,
+ },
+ {
+ provider: "anthropic",
+ biller: "anthropic",
+ billingType: "metered_api",
+ model: "claude-opus-4.5",
+ costCents: 11_240,
+ inputTokens: 280_000,
+ cachedInputTokens: 35_000,
+ outputTokens: 92_000,
+ apiRunCount: 7,
+ subscriptionRunCount: 0,
+ subscriptionCachedInputTokens: 0,
+ subscriptionInputTokens: 0,
+ subscriptionOutputTokens: 0,
+ },
+ ],
+ openai: [
+ {
+ provider: "openai",
+ biller: "openai",
+ billingType: "subscription_included",
+ model: "gpt-5.4-codex",
+ costCents: 0,
+ inputTokens: 1_050_000,
+ cachedInputTokens: 164_000,
+ outputTokens: 318_000,
+ apiRunCount: 0,
+ subscriptionRunCount: 26,
+ subscriptionCachedInputTokens: 164_000,
+ subscriptionInputTokens: 1_050_000,
+ subscriptionOutputTokens: 318_000,
+ },
+ {
+ provider: "openai",
+ biller: "openai",
+ billingType: "subscription_overage",
+ model: "gpt-5.3-codex-spark",
+ costCents: 18_900,
+ inputTokens: 620_000,
+ cachedInputTokens: 91_000,
+ outputTokens: 250_000,
+ apiRunCount: 9,
+ subscriptionRunCount: 12,
+ subscriptionCachedInputTokens: 91_000,
+ subscriptionInputTokens: 410_000,
+ subscriptionOutputTokens: 160_000,
+ },
+ ],
+ openrouter: [
+ {
+ provider: "anthropic",
+ biller: "openrouter",
+ billingType: "credits",
+ model: "anthropic/claude-sonnet-4.5",
+ costCents: 22_640,
+ inputTokens: 760_000,
+ cachedInputTokens: 120_000,
+ outputTokens: 220_000,
+ apiRunCount: 19,
+ subscriptionRunCount: 0,
+ subscriptionCachedInputTokens: 0,
+ subscriptionInputTokens: 0,
+ subscriptionOutputTokens: 0,
+ },
+ {
+ provider: "google",
+ biller: "openrouter",
+ billingType: "credits",
+ model: "google/gemini-3-pro",
+ costCents: 8_920,
+ inputTokens: 430_000,
+ cachedInputTokens: 44_000,
+ outputTokens: 118_000,
+ apiRunCount: 11,
+ subscriptionRunCount: 0,
+ subscriptionCachedInputTokens: 0,
+ subscriptionInputTokens: 0,
+ subscriptionOutputTokens: 0,
+ },
+ ],
+};
+
+const providerWindowRows: Record<string, CostWindowSpendRow[]> = {
+ anthropic: [
+ { provider: "anthropic", biller: "anthropic", window: "5h", windowHours: 5, costCents: 1_240, inputTokens: 82_000, cachedInputTokens: 11_000, outputTokens: 19_000 },
+ { provider: "anthropic", biller: "anthropic", window: "24h", windowHours: 24, costCents: 3_870, inputTokens: 218_000, cachedInputTokens: 32_000, outputTokens: 64_000 },
+ { provider: "anthropic", biller: "anthropic", window: "7d", windowHours: 168, costCents: 11_240, inputTokens: 1_700_000, cachedInputTokens: 245_000, outputTokens: 477_000 },
+ ],
+ openai: [
+ { provider: "openai", biller: "openai", window: "5h", windowHours: 5, costCents: 4_920, inputTokens: 148_000, cachedInputTokens: 18_000, outputTokens: 56_000 },
+ { provider: "openai", biller: "openai", window: "24h", windowHours: 24, costCents: 10_430, inputTokens: 398_000, cachedInputTokens: 52_000, outputTokens: 130_000 },
+ { provider: "openai", biller: "openai", window: "7d", windowHours: 168, costCents: 18_900, inputTokens: 1_670_000, cachedInputTokens: 255_000, outputTokens: 568_000 },
+ ],
+ openrouter: [
+ { provider: "openrouter", biller: "openrouter", window: "5h", windowHours: 5, costCents: 7_880, inputTokens: 210_000, cachedInputTokens: 20_000, outputTokens: 73_000 },
+ { provider: "openrouter", biller: "openrouter", window: "24h", windowHours: 24, costCents: 14_630, inputTokens: 506_000, cachedInputTokens: 51_000, outputTokens: 150_000 },
+ { provider: "openrouter", biller: "openrouter", window: "7d", windowHours: 168, costCents: 31_560, inputTokens: 1_190_000, cachedInputTokens: 164_000, outputTokens: 338_000 },
+ ],
+};
+
+const claudeQuotaWindows: QuotaWindow[] = [
+ { label: "Current session", usedPercent: 46, resetsAt: at(-180).toISOString(), valueLabel: null, detail: "Healthy session headroom for review tasks." },
+ { label: "Current week all models", usedPercent: 74, resetsAt: at(-5_300).toISOString(), valueLabel: null, detail: "Warning threshold after the release documentation run." },
+ { label: "Current week Opus only", usedPercent: 92, resetsAt: at(-5_300).toISOString(), valueLabel: null, detail: "Critical model-specific budget: route default work to Sonnet." },
+ { label: "Extra usage", usedPercent: null, resetsAt: null, valueLabel: "$18.40 overage", detail: "Overage billing is enabled for board-approved release checks." },
+];
+
+const codexQuotaWindows: QuotaWindow[] = [
+ { label: "5h limit", usedPercent: 38, resetsAt: at(-92).toISOString(), valueLabel: null, detail: "Healthy short-window capacity." },
+ { label: "Weekly limit", usedPercent: 83, resetsAt: at(-4_720).toISOString(), valueLabel: null, detail: "Warning: schedule high-context follow-ups after reset." },
+ { label: "Credits", usedPercent: null, resetsAt: null, valueLabel: "$61.25 remaining", detail: "Credit balance after subscription-covered runs." },
+ { label: "GPT-5.3 Codex Spark weekly limit", usedPercent: 96, resetsAt: at(-4_720).toISOString(), valueLabel: null, detail: "Critical model window for Spark-heavy story generation." },
+];
+
+const billerSpendRows: Array<{
+ state: "healthy" | "warning" | "critical";
+ row: CostByBiller;
+ providerRows: CostByProviderModel[];
+ totalCompanySpendCents: number;
+ weekSpendCents: number;
+}> = [
+ {
+ state: "healthy",
+ row: {
+ biller: "anthropic",
+ costCents: 11_240,
+ inputTokens: 1_700_000,
+ cachedInputTokens: 245_000,
+ outputTokens: 477_000,
+ apiRunCount: 7,
+ subscriptionRunCount: 38,
+ subscriptionCachedInputTokens: 210_000,
+ subscriptionInputTokens: 1_420_000,
+ subscriptionOutputTokens: 385_000,
+ providerCount: 1,
+ modelCount: 2,
+ },
+ providerRows: providerRowsByProvider.anthropic,
+ totalCompanySpendCents: 83_000,
+ weekSpendCents: 3_870,
+ },
+ {
+ state: "warning",
+ row: {
+ biller: "openai",
+ costCents: 18_900,
+ inputTokens: 1_670_000,
+ cachedInputTokens: 255_000,
+ outputTokens: 568_000,
+ apiRunCount: 9,
+ subscriptionRunCount: 38,
+ subscriptionCachedInputTokens: 255_000,
+ subscriptionInputTokens: 1_460_000,
+ subscriptionOutputTokens: 478_000,
+ providerCount: 1,
+ modelCount: 2,
+ },
+ providerRows: providerRowsByProvider.openai,
+ totalCompanySpendCents: 218_000,
+ weekSpendCents: 10_430,
+ },
+ {
+ state: "critical",
+ row: {
+ biller: "openrouter",
+ costCents: 31_560,
+ inputTokens: 1_190_000,
+ cachedInputTokens: 164_000,
+ outputTokens: 338_000,
+ apiRunCount: 30,
+ subscriptionRunCount: 0,
+ subscriptionCachedInputTokens: 0,
+ subscriptionInputTokens: 0,
+ subscriptionOutputTokens: 0,
+ providerCount: 2,
+ modelCount: 2,
+ },
+ providerRows: providerRowsByProvider.openrouter,
+ totalCompanySpendCents: 286_000,
+ weekSpendCents: 14_630,
+ },
+];
+
+const financeBillerRows: FinanceByBiller[] = [
+ {
+ biller: "openai",
+ debitCents: 74_200,
+ creditCents: 12_000,
+ netCents: 62_200,
+ estimatedDebitCents: 18_400,
+ eventCount: 7,
+ kindCount: 3,
+ },
+ {
+ biller: "aws_bedrock",
+ debitCents: 45_880,
+ creditCents: 0,
+ netCents: 45_880,
+ estimatedDebitCents: 45_880,
+ eventCount: 4,
+ kindCount: 2,
+ },
+];
+
+const financeKindRows: FinanceByKind[] = [
+ {
+ eventKind: "inference_charge",
+ debitCents: 49_820,
+ creditCents: 0,
+ netCents: 49_820,
+ estimatedDebitCents: 12_700,
+ eventCount: 9,
+ billerCount: 3,
+ },
+ {
+ eventKind: "log_storage_charge",
+ debitCents: 8_760,
+ creditCents: 0,
+ netCents: 8_760,
+ estimatedDebitCents: 8_760,
+ eventCount: 3,
+ billerCount: 1,
+ },
+ {
+ eventKind: "provisioned_capacity_charge",
+ debitCents: 42_900,
+ creditCents: 0,
+ netCents: 42_900,
+ estimatedDebitCents: 42_900,
+ eventCount: 2,
+ billerCount: 1,
+ },
+ {
+ eventKind: "credit_refund",
+ debitCents: 0,
+ creditCents: 12_000,
+ netCents: -12_000,
+ estimatedDebitCents: 0,
+ eventCount: 1,
+ billerCount: 1,
+ },
+];
+
+const financeTimelineRows: FinanceEvent[] = [
+ {
+ id: "finance-event-openai-invoice",
+ companyId: "company-storybook",
+ agentId: null,
+ issueId: null,
+ projectId: "project-board-ui",
+ goalId: "goal-company",
+ heartbeatRunId: null,
+ costEventId: null,
+ billingCode: "product",
+ description: "Monthly ChatGPT/Codex business plan charge for engineering agents.",
+ eventKind: "platform_fee",
+ direction: "debit",
+ biller: "openai",
+ provider: "openai",
+ executionAdapterType: "codex_local",
+ pricingTier: "business",
+ region: "us",
+ model: null,
+ quantity: 8,
+ unit: "request",
+ amountCents: 40_000,
+ currency: "USD",
+ estimated: false,
+ externalInvoiceId: "INV-2026-04-OPENAI-1184",
+ metadataJson: { paymentMethod: "corporate-card" },
+ occurredAt: at(1_260),
+ createdAt: at(1_255),
+ },
+ {
+ id: "finance-event-bedrock-compute",
+ companyId: "company-storybook",
+ agentId: "agent-codex",
+ issueId: "issue-storybook-1",
+ projectId: "project-board-ui",
+ goalId: "goal-company",
+ heartbeatRunId: "run-storybook",
+ costEventId: null,
+ billingCode: "product",
+ description: "Provisioned Bedrock capacity for release smoke testing.",
+ eventKind: "provisioned_capacity_charge",
+ direction: "debit",
+ biller: "aws_bedrock",
+ provider: "anthropic",
+ executionAdapterType: "claude_local",
+ pricingTier: "provisioned",
+ region: "us-east-1",
+ model: "claude-sonnet-4.5",
+ quantity: 14,
+ unit: "model_unit_hour",
+ amountCents: 42_900,
+ currency: "USD",
+ estimated: true,
+ externalInvoiceId: "AWS-EST-7713",
+ metadataJson: { purchaseOrder: "PO-STORYBOOK-APR" },
+ occurredAt: at(420),
+ createdAt: at(416),
+ },
+ {
+ id: "finance-event-log-storage",
+ companyId: "company-storybook",
+ agentId: null,
+ issueId: null,
+ projectId: "project-observability",
+ goalId: "goal-company",
+ heartbeatRunId: null,
+ costEventId: null,
+ billingCode: "ops",
+ description: "Log retention and audit bundle storage.",
+ eventKind: "log_storage_charge",
+ direction: "debit",
+ biller: "cloudflare",
+ provider: "cloudflare",
+ executionAdapterType: null,
+ pricingTier: "standard",
+ region: "global",
+ model: null,
+ quantity: 312,
+ unit: "gb_month",
+ amountCents: 8_760,
+ currency: "USD",
+ estimated: true,
+ externalInvoiceId: "CF-APR-2026-0091",
+ metadataJson: null,
+ occurredAt: at(210),
+ createdAt: at(205),
+ },
+ {
+ id: "finance-event-credit-refund",
+ companyId: "company-storybook",
+ agentId: null,
+ issueId: null,
+ projectId: null,
+ goalId: "goal-company",
+ heartbeatRunId: null,
+ costEventId: null,
+ billingCode: "finance",
+ description: "Credit refund after duplicate OpenAI top-up.",
+ eventKind: "credit_refund",
+ direction: "credit",
+ biller: "openai",
+ provider: "openai",
+ executionAdapterType: null,
+ pricingTier: null,
+ region: null,
+ model: null,
+ quantity: 120,
+ unit: "credit_usd",
+ amountCents: 12_000,
+ currency: "USD",
+ estimated: false,
+ externalInvoiceId: "CR-2026-04-OPENAI-041",
+ metadataJson: null,
+ occurredAt: at(64),
+ createdAt: at(61),
+ },
+];
+
+const sidebarMarkers: Array<{
+ level: BudgetSidebarMarkerLevel;
+ label: string;
+ detail: string;
+ icon: typeof CheckCircle2;
+}> = [
+ {
+ level: "healthy",
+ label: "Healthy",
+ detail: "27% of company budget used",
+ icon: CheckCircle2,
+ },
+ {
+ level: "warning",
+ label: "Warning",
+ detail: "86% of project budget used",
+ icon: AlertTriangle,
+ },
+ {
+ level: "critical",
+ label: "Critical",
+ detail: "Agent paused by hard stop",
+ icon: WalletCards,
+ },
+];
+
+function BudgetFinanceMatrix() {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner 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">Budget and finance</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Spend controls, quotas, and accounting surfaces</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Fixture-backed coverage for the board's cost-control components: active incidents, sidebar budget markers,
+ provider quotas, biller allocation, account-level finance events, and subscription quota windows.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">healthy</Badge>
+ <Badge variant="outline">warning</Badge>
+ <Badge variant="outline">critical</Badge>
+ </div>
+ </div>
+ </section>
+
+ <Section eyebrow="Incidents" title="BudgetIncidentCard resolution, pending, and escalated states">
+ <div className="grid gap-5 xl:grid-cols-3">
+ <CaseFrame title="Resolved raise-and-resume" detail="Approval approved and incident resolved after the budget was raised." tone="healthy">
+ <BudgetIncidentCard
+ incident={budgetIncidents[0]!}
+ onKeepPaused={() => undefined}
+ onRaiseAndResume={() => undefined}
+ />
+ </CaseFrame>
+ <CaseFrame title="Pending board decision" detail="Project execution is paused while a budget approval waits for review." tone="warning">
+ <BudgetIncidentCard
+ incident={budgetIncidents[1]!}
+ onKeepPaused={() => undefined}
+ onRaiseAndResume={() => undefined}
+ />
+ </CaseFrame>
+ <CaseFrame title="Escalated hard stop" detail="Company spend exceeded the cap and the first approval needs revision." tone="critical">
+ <BudgetIncidentCard
+ incident={budgetIncidents[2]!}
+ onKeepPaused={() => undefined}
+ onRaiseAndResume={() => undefined}
+ />
+ </CaseFrame>
+ </div>
+ </Section>
+
+ <Section eyebrow="Sidebar" title="BudgetSidebarMarker healthy, warning, and critical indicators">
+ <div className="grid gap-4 md:grid-cols-3">
+ {sidebarMarkers.map((marker) => {
+ const Icon = marker.icon;
+ return (
+ <div key={marker.level} className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="flex items-center gap-3">
+ <Icon className="h-4 w-4 text-muted-foreground" />
+ <div className="min-w-0">
+ <div className="text-sm font-medium">{marker.label}</div>
+ <div className="text-xs text-muted-foreground">{marker.detail}</div>
+ </div>
+ <BudgetSidebarMarker level={marker.level} title={`${marker.label} budget indicator`} />
+ </div>
+ </div>
+ );
+ })}
+ </div>
+ </Section>
+
+ <Section eyebrow="Providers" title="ProviderQuotaCard usage bars and subscription quota windows">
+ <div className="grid gap-5 xl:grid-cols-3">
+ <CaseFrame title="Healthy provider" detail="Anthropic subscription usage still has room in short and weekly windows." tone="healthy">
+ <ProviderQuotaCard
+ provider="anthropic"
+ rows={providerRowsByProvider.anthropic}
+ budgetMonthlyCents={250_000}
+ totalCompanySpendCents={83_000}
+ weekSpendCents={3_870}
+ windowRows={providerWindowRows.anthropic}
+ showDeficitNotch={false}
+ quotaWindows={claudeQuotaWindows}
+ quotaSource="anthropic-oauth"
+ />
+ </CaseFrame>
+ <CaseFrame title="Warning provider" detail="Codex weekly usage is high and subscription overage has started." tone="warning">
+ <ProviderQuotaCard
+ provider="openai"
+ rows={providerRowsByProvider.openai}
+ budgetMonthlyCents={250_000}
+ totalCompanySpendCents={218_000}
+ weekSpendCents={10_430}
+ windowRows={providerWindowRows.openai}
+ showDeficitNotch={false}
+ quotaWindows={codexQuotaWindows}
+ quotaSource="codex-rpc"
+ />
+ </CaseFrame>
+ <CaseFrame title="Critical biller" detail="OpenRouter credits are beyond the monthly allocation and show deficit treatment." tone="critical">
+ <ProviderQuotaCard
+ provider="openrouter"
+ rows={providerRowsByProvider.openrouter}
+ budgetMonthlyCents={250_000}
+ totalCompanySpendCents={286_000}
+ weekSpendCents={14_630}
+ windowRows={providerWindowRows.openrouter}
+ showDeficitNotch
+ quotaWindows={[
+ { label: "Credits", usedPercent: 97, resetsAt: null, valueLabel: "$8.17 remaining", detail: "Critical credit balance before next top-up." },
+ { label: "Requests", usedPercent: 89, resetsAt: at(-520).toISOString(), valueLabel: null, detail: "Warning-level gateway request window." },
+ ]}
+ quotaSource="openrouter"
+ />
+ </CaseFrame>
+ </div>
+ </Section>
+
+ <Section eyebrow="Accounting" title="AccountingModelCard cost allocation reference">
+ <AccountingModelCard />
+ </Section>
+
+ <Section eyebrow="Billers" title="BillerSpendCard period comparison and upstream provider split">
+ <div className="grid gap-5 xl:grid-cols-3">
+ {billerSpendRows.map((entry) => (
+ <CaseFrame
+ key={entry.row.biller}
+ title={`${entry.state[0]!.toUpperCase()}${entry.state.slice(1)} allocation`}
+ detail="The card compares period spend, weekly spend, billing types, and upstream providers."
+ tone={entry.state}
+ >
+ <BillerSpendCard
+ row={entry.row}
+ weekSpendCents={entry.weekSpendCents}
+ budgetMonthlyCents={250_000}
+ totalCompanySpendCents={entry.totalCompanySpendCents}
+ providerRows={entry.providerRows}
+ />
+ </CaseFrame>
+ ))}
+ </div>
+ </Section>
+
+ <Section eyebrow="Finance" title="FinanceBillerCard, FinanceKindCard, and invoice timeline">
+ <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_390px]">
+ <div className="space-y-5">
+ <div className="grid gap-5 md:grid-cols-2">
+ {financeBillerRows.map((row) => (
+ <FinanceBillerCard key={row.biller} row={row} />
+ ))}
+ </div>
+ <FinanceTimelineCard rows={financeTimelineRows} />
+ </div>
+ <div className="space-y-5">
+ <FinanceKindCard rows={financeKindRows} />
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2 text-base">
+ <ReceiptText className="h-4 w-4" />
+ Category fixtures
+ </CardTitle>
+ <CardDescription>Compute, storage, and API-style finance rows are represented by provisioned capacity, log storage, and inference charges.</CardDescription>
+ </CardHeader>
+ <CardContent className="grid gap-3 text-sm sm:grid-cols-3 xl:grid-cols-1">
+ {[
+ { label: "Compute", value: "$429.00", icon: Landmark },
+ { label: "Storage", value: "$87.60", icon: CreditCard },
+ { label: "API", value: "$498.20", icon: WalletCards },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <div key={item.label} className="flex items-center justify-between gap-3 border border-border p-3">
+ <span className="inline-flex items-center gap-2 text-muted-foreground">
+ <Icon className="h-4 w-4" />
+ {item.label}
+ </span>
+ <span className="font-mono font-medium">{item.value}</span>
+ </div>
+ );
+ })}
+ </CardContent>
+ </Card>
+ </div>
+ </div>
+ </Section>
+
+ <Section eyebrow="Subscriptions" title="ClaudeSubscriptionPanel and CodexSubscriptionPanel status windows">
+ <div className="grid gap-5 xl:grid-cols-2">
+ <ClaudeSubscriptionPanel windows={claudeQuotaWindows} source="anthropic-oauth" />
+ <CodexSubscriptionPanel windows={codexQuotaWindows} source="codex-rpc" />
+ </div>
+ <div className="mt-5 grid gap-5 xl:grid-cols-2">
+ <ClaudeSubscriptionPanel
+ windows={[]}
+ source="claude-cli"
+ error="Claude CLI quota polling timed out after 10s. Last successful sample was 18 minutes ago."
+ />
+ <CodexSubscriptionPanel
+ windows={[]}
+ source="codex-wham"
+ error="Codex app server is unavailable, so live subscription windows cannot be refreshed."
+ />
+ </div>
+ </Section>
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Product/Budget & Finance",
+ component: BudgetFinanceMatrix,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Budget and finance stories cover incident resolution states, sidebar markers, provider and biller quotas, finance ledgers, and Claude/Codex subscription panels.",
+ },
+ },
+ },
+} satisfies Meta<typeof BudgetFinanceMatrix>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const FullMatrix: Story = {};
diff --git a/ui/storybook/stories/chat-comments.stories.tsx b/ui/storybook/stories/chat-comments.stories.tsx
new file mode 100644
index 0000000000..620b96c881
--- /dev/null
+++ b/ui/storybook/stories/chat-comments.stories.tsx
@@ -0,0 +1,713 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Agent, FeedbackVote, IssueComment } from "@paperclipai/shared";
+import type { TranscriptEntry } from "@/adapters";
+import type { LiveRunForIssue } from "@/api/heartbeats";
+import { CommentThread } from "@/components/CommentThread";
+import { IssueChatThread } from "@/components/IssueChatThread";
+import { RunChatSurface } from "@/components/RunChatSurface";
+import type { InlineEntityOption } from "@/components/InlineEntitySelector";
+import type { MentionOption } from "@/components/MarkdownEditor";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import type {
+ IssueChatComment,
+ IssueChatLinkedRun,
+ IssueChatTranscriptEntry,
+} from "@/lib/issue-chat-messages";
+import type { IssueTimelineEvent } from "@/lib/issue-timeline-events";
+import { storybookAgentMap, storybookAgents } from "../fixtures/paperclipData";
+
+const companyId = "company-storybook";
+const projectId = "project-board-ui";
+const issueId = "issue-chat-comments";
+const currentUserId = "user-board";
+
+type StoryComment = IssueComment & {
+ runId?: string | null;
+ runAgentId?: string | null;
+ clientId?: string;
+ clientStatus?: "pending" | "queued";
+ queueState?: "queued";
+ queueTargetRunId?: string | null;
+};
+
+const codexAgent = storybookAgents.find((agent) => agent.id === "agent-codex") ?? storybookAgents[0]!;
+const qaAgent = storybookAgents.find((agent) => agent.id === "agent-qa") ?? storybookAgents[1]!;
+const ctoAgent = storybookAgents.find((agent) => agent.id === "agent-cto") ?? storybookAgents[2]!;
+
+const boardUserLabels = new Map<string, string>([
+ ["user-board", "Riley Board"],
+ ["user-product", "Mara Product"],
+]);
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <section className="paperclip-story__frame overflow-hidden">
+ <div className="flex flex-wrap items-start justify-between gap-3 border-b border-border px-5 py-4">
+ <div>
+ <div className="paperclip-story__label">{eyebrow}</div>
+ <h2 className="mt-1 text-xl font-semibold">{title}</h2>
+ </div>
+ </div>
+ <div className="p-5">{children}</div>
+ </section>
+ );
+}
+
+function ScenarioCard({
+ title,
+ description,
+ children,
+}: {
+ title: string;
+ description: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>{title}</CardTitle>
+ <CardDescription>{description}</CardDescription>
+ </CardHeader>
+ <CardContent>{children}</CardContent>
+ </Card>
+ );
+}
+
+function createComment(overrides: Partial<StoryComment>): StoryComment {
+ const createdAt = overrides.createdAt ?? new Date("2026-04-20T14:00:00.000Z");
+ return {
+ id: "comment-default",
+ companyId,
+ issueId,
+ authorAgentId: null,
+ authorUserId: currentUserId,
+ body: "",
+ createdAt,
+ updatedAt: overrides.updatedAt ?? createdAt,
+ ...overrides,
+ };
+}
+
+function createSystemEvent(overrides: Partial<IssueTimelineEvent>): IssueTimelineEvent {
+ return {
+ id: "event-default",
+ createdAt: new Date("2026-04-20T14:00:00.000Z"),
+ actorType: "system",
+ actorId: "paperclip",
+ statusChange: {
+ from: "todo",
+ to: "in_progress",
+ },
+ ...overrides,
+ };
+}
+
+const mentionOptions: MentionOption[] = [
+ {
+ id: `agent:${codexAgent.id}`,
+ name: codexAgent.name,
+ kind: "agent",
+ agentId: codexAgent.id,
+ agentIcon: codexAgent.icon,
+ },
+ {
+ id: `agent:${qaAgent.id}`,
+ name: qaAgent.name,
+ kind: "agent",
+ agentId: qaAgent.id,
+ agentIcon: qaAgent.icon,
+ },
+ {
+ id: `project:${projectId}`,
+ name: "Board UI",
+ kind: "project",
+ projectId,
+ projectColor: "#0f766e",
+ },
+];
+
+const reassignOptions: InlineEntityOption[] = [
+ {
+ id: `agent:${codexAgent.id}`,
+ label: codexAgent.name,
+ searchText: `${codexAgent.name} engineer codex`,
+ },
+ {
+ id: `agent:${qaAgent.id}`,
+ label: qaAgent.name,
+ searchText: `${qaAgent.name} qa browser review`,
+ },
+ {
+ id: `agent:${ctoAgent.id}`,
+ label: ctoAgent.name,
+ searchText: `${ctoAgent.name} architecture review`,
+ },
+ {
+ id: `user:${currentUserId}`,
+ label: "Riley Board",
+ searchText: "board operator",
+ },
+];
+
+const singleComment = [
+ createComment({
+ id: "comment-single-board",
+ body: "Please make the issue chat states reviewable in Storybook before the next UI pass.",
+ createdAt: new Date("2026-04-20T13:12:00.000Z"),
+ }),
+];
+
+const longThreadComments = [
+ createComment({
+ id: "comment-long-board",
+ body: "The chat surface should show the operator request first, then agent progress, then review follow-up. Keep the density close to the issue page.",
+ createdAt: new Date("2026-04-20T13:02:00.000Z"),
+ }),
+ createComment({
+ id: "comment-long-agent",
+ authorAgentId: codexAgent.id,
+ authorUserId: null,
+ body: "I found the existing `IssueChatThread` and `RunChatSurface` components and am building the stories around those props.",
+ createdAt: new Date("2026-04-20T13:08:00.000Z"),
+ runId: "run-comment-thread-01",
+ runAgentId: codexAgent.id,
+ }),
+ createComment({
+ id: "comment-long-product",
+ authorUserId: "user-product",
+ body: "Also include the old comment timeline so we can compare it with the assistant-style issue chat.",
+ createdAt: new Date("2026-04-20T13:16:00.000Z"),
+ }),
+ createComment({
+ id: "comment-long-qa",
+ authorAgentId: qaAgent.id,
+ authorUserId: null,
+ body: "QA note: the thread should stay readable with long markdown and when a queued operator reply is visible.",
+ createdAt: new Date("2026-04-20T13:24:00.000Z"),
+ runId: "run-comment-thread-02",
+ runAgentId: qaAgent.id,
+ }),
+];
+
+const markdownComments = [
+ createComment({
+ id: "comment-markdown-board",
+ body: [
+ "Acceptance criteria:",
+ "",
+ "- Cover empty, single, and long comment states",
+ "- Show a code block in a comment",
+ "- Include a link to [the issue guide](/issues/PAP-1676)",
+ "",
+ "```ts",
+ "const success = stories.some((story) => story.includes(\"IssueChatThread\"));",
+ "```",
+ ].join("\n"),
+ createdAt: new Date("2026-04-20T13:28:00.000Z"),
+ }),
+ createComment({
+ id: "comment-mentions-agent",
+ authorAgentId: codexAgent.id,
+ authorUserId: null,
+ body: "@QAChecker I added the fixture coverage. Please focus browser review on links, code blocks, and the queued comment treatment.",
+ createdAt: new Date("2026-04-20T13:35:00.000Z"),
+ runId: "run-markdown-01",
+ runAgentId: codexAgent.id,
+ }),
+];
+
+const queuedComment = createComment({
+ id: "comment-queued-board",
+ body: "@CodexCoder after this run finishes, add a compact embedded variant too.",
+ createdAt: new Date("2026-04-20T13:39:00.000Z"),
+ clientId: "client-queued-storybook",
+ clientStatus: "queued",
+ queueState: "queued",
+ queueTargetRunId: "run-live-chat-01",
+});
+
+const commentTimelineEvents: IssueTimelineEvent[] = [
+ createSystemEvent({
+ id: "event-system-checkout",
+ createdAt: new Date("2026-04-20T13:04:00.000Z"),
+ actorType: "system",
+ actorId: "paperclip",
+ statusChange: {
+ from: "todo",
+ to: "in_progress",
+ },
+ }),
+ createSystemEvent({
+ id: "event-board-reassign",
+ createdAt: new Date("2026-04-20T13:18:00.000Z"),
+ actorType: "user",
+ actorId: currentUserId,
+ assigneeChange: {
+ from: { agentId: codexAgent.id, userId: null },
+ to: { agentId: qaAgent.id, userId: null },
+ },
+ statusChange: undefined,
+ }),
+];
+
+const commentLinkedRuns = [
+ {
+ runId: "run-comment-thread-01",
+ status: "succeeded",
+ agentId: codexAgent.id,
+ createdAt: new Date("2026-04-20T13:07:00.000Z"),
+ startedAt: new Date("2026-04-20T13:07:00.000Z"),
+ finishedAt: new Date("2026-04-20T13:11:00.000Z"),
+ },
+ {
+ runId: "run-comment-thread-02",
+ status: "running",
+ agentId: qaAgent.id,
+ createdAt: new Date("2026-04-20T13:22:00.000Z"),
+ startedAt: new Date("2026-04-20T13:22:00.000Z"),
+ finishedAt: null,
+ },
+];
+
+const feedbackVotes: FeedbackVote[] = [
+ {
+ id: "feedback-chat-comment-01",
+ companyId,
+ issueId,
+ targetType: "issue_comment",
+ targetId: "comment-issue-agent",
+ authorUserId: currentUserId,
+ vote: "up",
+ reason: null,
+ sharedWithLabs: false,
+ sharedAt: null,
+ consentVersion: null,
+ redactionSummary: null,
+ createdAt: new Date("2026-04-20T13:52:00.000Z"),
+ updatedAt: new Date("2026-04-20T13:52:00.000Z"),
+ },
+];
+
+const liveRun: LiveRunForIssue = {
+ id: "run-live-chat-01",
+ status: "running",
+ invocationSource: "manual",
+ triggerDetail: "comment",
+ createdAt: "2026-04-20T13:40:00.000Z",
+ startedAt: "2026-04-20T13:40:02.000Z",
+ finishedAt: null,
+ agentId: codexAgent.id,
+ agentName: codexAgent.name,
+ adapterType: "codex_local",
+ issueId,
+};
+
+const liveRunTranscript: TranscriptEntry[] = [
+ {
+ kind: "assistant",
+ ts: "2026-04-20T13:40:08.000Z",
+ text: "I am wiring the chat and comments Storybook coverage now.",
+ },
+ {
+ kind: "thinking",
+ ts: "2026-04-20T13:40:12.000Z",
+ text: "Need fixtures that exercise MarkdownBody, assistant-ui messages, and the embedded run transcript path without reaching the API.",
+ },
+ {
+ kind: "tool_call",
+ ts: "2026-04-20T13:40:18.000Z",
+ name: "rg",
+ toolUseId: "tool-live-rg",
+ input: {
+ query: "IssueChatThread",
+ cwd: "ui/src",
+ },
+ },
+ {
+ kind: "tool_result",
+ ts: "2026-04-20T13:40:20.000Z",
+ toolUseId: "tool-live-rg",
+ content: "ui/src/components/IssueChatThread.tsx\nui/src/components/RunChatSurface.tsx",
+ isError: false,
+ },
+ {
+ kind: "assistant",
+ ts: "2026-04-20T13:40:31.000Z",
+ text: [
+ "The live run should render code blocks as part of the assistant response:",
+ "",
+ "```tsx",
+ "<RunChatSurface run={run} transcript={entries} hasOutput />",
+ "```",
+ ].join("\n"),
+ },
+ {
+ kind: "tool_call",
+ ts: "2026-04-20T13:40:44.000Z",
+ name: "apply_patch",
+ toolUseId: "tool-live-patch",
+ input: {
+ file: "ui/storybook/stories/chat-comments.stories.tsx",
+ action: "add fixtures",
+ },
+ },
+ {
+ kind: "tool_result",
+ ts: "2026-04-20T13:40:49.000Z",
+ toolUseId: "tool-live-patch",
+ content: "Added Storybook scenarios for comment thread, run chat, and issue chat.",
+ isError: false,
+ },
+];
+
+const issueChatComments: IssueChatComment[] = [
+ createComment({
+ id: "comment-issue-board",
+ body: "Please turn the comment thread into a reviewable chat surface. I need to see operator messages, agent output, system events, and live run progress together.",
+ createdAt: new Date("2026-04-20T13:44:00.000Z"),
+ }),
+ createComment({
+ id: "comment-issue-agent",
+ authorAgentId: codexAgent.id,
+ authorUserId: null,
+ body: "I kept the existing component contracts and added fixtures with realistic Paperclip work: checkout, comments, linked runs, and review feedback.",
+ createdAt: new Date("2026-04-20T13:50:00.000Z"),
+ runId: "run-issue-chat-01",
+ runAgentId: codexAgent.id,
+ }),
+ createComment({
+ id: "comment-issue-queued",
+ body: "@QAChecker please do a quick visual pass after the Storybook build is green.",
+ createdAt: new Date("2026-04-20T13:56:00.000Z"),
+ clientId: "client-issue-queued",
+ clientStatus: "queued",
+ queueState: "queued",
+ queueTargetRunId: liveRun.id,
+ }),
+];
+
+const issueTimelineEvents: IssueTimelineEvent[] = [
+ createSystemEvent({
+ id: "event-issue-checkout",
+ createdAt: new Date("2026-04-20T13:42:00.000Z"),
+ actorType: "system",
+ actorId: "paperclip",
+ statusChange: {
+ from: "todo",
+ to: "in_progress",
+ },
+ }),
+ createSystemEvent({
+ id: "event-issue-assignee",
+ createdAt: new Date("2026-04-20T13:43:00.000Z"),
+ actorType: "user",
+ actorId: currentUserId,
+ statusChange: undefined,
+ assigneeChange: {
+ from: { agentId: null, userId: null },
+ to: { agentId: codexAgent.id, userId: null },
+ },
+ }),
+];
+
+const issueLinkedRuns: IssueChatLinkedRun[] = [
+ {
+ runId: "run-issue-chat-01",
+ status: "succeeded",
+ agentId: codexAgent.id,
+ agentName: codexAgent.name,
+ adapterType: "codex_local",
+ createdAt: new Date("2026-04-20T13:46:00.000Z"),
+ startedAt: new Date("2026-04-20T13:46:00.000Z"),
+ finishedAt: new Date("2026-04-20T13:51:00.000Z"),
+ hasStoredOutput: true,
+ },
+];
+
+const issueTranscriptsByRunId = new Map<string, readonly IssueChatTranscriptEntry[]>([
+ [
+ "run-issue-chat-01",
+ [
+ {
+ kind: "thinking",
+ ts: "2026-04-20T13:46:10.000Z",
+ text: "Checking the existing Storybook organization before adding a new product group.",
+ },
+ {
+ kind: "tool_call",
+ ts: "2026-04-20T13:46:16.000Z",
+ name: "read_file",
+ toolUseId: "tool-issue-read",
+ input: {
+ path: "ui/storybook/stories/overview.stories.tsx",
+ },
+ },
+ {
+ kind: "tool_result",
+ ts: "2026-04-20T13:46:19.000Z",
+ toolUseId: "tool-issue-read",
+ content: "The coverage map already lists Chat & comments as a planned section.",
+ isError: false,
+ },
+ {
+ kind: "assistant",
+ ts: "2026-04-20T13:49:00.000Z",
+ text: "Added the story file and kept every fixture local to the story so product data fixtures stay stable.",
+ },
+ {
+ kind: "diff",
+ ts: "2026-04-20T13:49:04.000Z",
+ changeType: "file_header",
+ text: "diff --git a/ui/storybook/stories/chat-comments.stories.tsx b/ui/storybook/stories/chat-comments.stories.tsx",
+ },
+ {
+ kind: "diff",
+ ts: "2026-04-20T13:49:05.000Z",
+ changeType: "add",
+ text: "+export const FullSurfaceMatrix: Story = {};",
+ },
+ ],
+ ],
+ [liveRun.id, liveRunTranscript],
+]);
+
+function ThreadProps({
+ comments,
+ queuedComments = [],
+ timelineEvents = [],
+}: {
+ comments: StoryComment[];
+ queuedComments?: StoryComment[];
+ timelineEvents?: IssueTimelineEvent[];
+}) {
+ return (
+ <CommentThread
+ comments={comments}
+ queuedComments={queuedComments}
+ linkedRuns={commentLinkedRuns}
+ timelineEvents={timelineEvents}
+ companyId={companyId}
+ projectId={projectId}
+ issueStatus="in_progress"
+ agentMap={storybookAgentMap}
+ currentUserId={currentUserId}
+ onAdd={async () => {}}
+ enableReassign
+ reassignOptions={reassignOptions}
+ currentAssigneeValue={`agent:${codexAgent.id}`}
+ suggestedAssigneeValue={`agent:${codexAgent.id}`}
+ mentions={mentionOptions}
+ onInterruptQueued={async () => {}}
+ />
+ );
+}
+
+function CommentThreadMatrix() {
+ return (
+ <Section eyebrow="CommentThread" title="Timeline comments across empty, single, long, markdown, and queued states">
+ <div className="grid gap-5 xl:grid-cols-2">
+ <ScenarioCard title="Empty thread" description="No timeline entries yet, with the composer ready for the first comment.">
+ <ThreadProps comments={[]} />
+ </ScenarioCard>
+ <ScenarioCard title="Single board comment" description="A minimal operator request with timestamp and composer controls.">
+ <ThreadProps comments={singleComment} />
+ </ScenarioCard>
+ <ScenarioCard title="Long mixed-author thread" description="Board, product, agent, linked run, and system timeline entries in one stack.">
+ <ThreadProps comments={longThreadComments} timelineEvents={commentTimelineEvents} />
+ </ScenarioCard>
+ <ScenarioCard title="Markdown, code, mentions, and links" description="Markdown rendering with code fences, @mentions, links, and a queued reply.">
+ <ThreadProps comments={markdownComments} queuedComments={[queuedComment]} />
+ </ScenarioCard>
+ </div>
+ </Section>
+ );
+}
+
+function RunChatMatrix() {
+ return (
+ <Section eyebrow="RunChatSurface" title="Live run chat with streaming output, tools, and code blocks">
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_360px]">
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <RunChatSurface
+ run={liveRun}
+ transcript={liveRunTranscript}
+ hasOutput
+ companyId={companyId}
+ />
+ </div>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Run fixture shape</CardTitle>
+ <CardDescription>Streaming transcript entries mixed into the same chat renderer used by issue chat.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-3 text-sm">
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Status</span>
+ <Badge variant="secondary">running</Badge>
+ </div>
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Tool calls</span>
+ <span className="font-mono text-xs">rg, apply_patch</span>
+ </div>
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Transcript entries</span>
+ <span className="font-mono text-xs">{liveRunTranscript.length}</span>
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+ );
+}
+
+function IssueChatMatrix() {
+ return (
+ <Section eyebrow="IssueChatThread" title="Issue-specific chat with timeline events, linked runs, and live output">
+ <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_420px]">
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <IssueChatThread
+ comments={issueChatComments}
+ linkedRuns={issueLinkedRuns}
+ timelineEvents={issueTimelineEvents}
+ liveRuns={[liveRun]}
+ feedbackVotes={feedbackVotes}
+ feedbackDataSharingPreference="allowed"
+ companyId={companyId}
+ projectId={projectId}
+ issueStatus="in_progress"
+ agentMap={storybookAgentMap}
+ currentUserId={currentUserId}
+ userLabelMap={boardUserLabels}
+ onAdd={async () => {}}
+ onVote={async () => {}}
+ onStopRun={async () => {}}
+ enableReassign
+ reassignOptions={reassignOptions}
+ currentAssigneeValue={`agent:${codexAgent.id}`}
+ suggestedAssigneeValue={`agent:${codexAgent.id}`}
+ mentions={mentionOptions}
+ enableLiveTranscriptPolling={false}
+ transcriptsByRunId={issueTranscriptsByRunId}
+ hasOutputForRun={(runId) => issueTranscriptsByRunId.has(runId)}
+ includeSucceededRunsWithoutOutput
+ onInterruptQueued={async () => {}}
+ onCancelQueued={() => undefined}
+ />
+ </div>
+ <div className="space-y-5">
+ <ScenarioCard title="Empty issue chat" description="The standalone empty state before an operator or agent posts.">
+ <IssueChatThread
+ comments={[]}
+ timelineEvents={[]}
+ linkedRuns={[]}
+ liveRuns={[]}
+ companyId={companyId}
+ projectId={projectId}
+ agentMap={storybookAgentMap}
+ currentUserId={currentUserId}
+ onAdd={async () => {}}
+ enableLiveTranscriptPolling={false}
+ emptyMessage="No chat yet. The first operator note will start the issue conversation."
+ />
+ </ScenarioCard>
+ <ScenarioCard title="Disabled composer" description="Review state where the conversation remains readable but input is paused.">
+ <IssueChatThread
+ comments={singleComment}
+ timelineEvents={[]}
+ linkedRuns={[]}
+ liveRuns={[]}
+ companyId={companyId}
+ projectId={projectId}
+ agentMap={storybookAgentMap}
+ currentUserId={currentUserId}
+ onAdd={async () => {}}
+ showJumpToLatest={false}
+ enableLiveTranscriptPolling={false}
+ composerDisabledReason="This issue is in review. Request changes or approve it from the review controls."
+ />
+ </ScenarioCard>
+ </div>
+ </div>
+ </Section>
+ );
+}
+
+function ChatCommentsStories() {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">
+ <section className="paperclip-story__frame p-6">
+ <div className="paperclip-story__label">Chat & Comments</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Threaded work conversations</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Fixture-backed coverage for classic issue comments, embedded run chat, and the assistant-style issue chat
+ surface. The scenarios use Paperclip operational content with mixed authors, system timeline events,
+ markdown, code blocks, @mentions, links, queued comments, tool calls, and streaming run output.
+ </p>
+ </section>
+
+ <CommentThreadMatrix />
+ <RunChatMatrix />
+ <IssueChatMatrix />
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Product/Chat & Comments",
+ component: ChatCommentsStories,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Chat and comments stories exercise CommentThread, RunChatSurface, and IssueChatThread across empty, single, long, markdown, mention, timeline, queued, linked-run, and streaming transcript states.",
+ },
+ },
+ },
+} satisfies Meta<typeof ChatCommentsStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const FullSurfaceMatrix: Story = {};
+
+export const CommentThreads: Story = {
+ render: () => (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner">
+ <CommentThreadMatrix />
+ </main>
+ </div>
+ ),
+};
+
+export const LiveRunChat: Story = {
+ render: () => (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner">
+ <RunChatMatrix />
+ </main>
+ </div>
+ ),
+};
+
+export const IssueChatWithTimeline: Story = {
+ render: () => (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner">
+ <IssueChatMatrix />
+ </main>
+ </div>
+ ),
+};
diff --git a/ui/storybook/stories/control-plane-surfaces.stories.tsx b/ui/storybook/stories/control-plane-surfaces.stories.tsx
new file mode 100644
index 0000000000..98e4a1fc5c
--- /dev/null
+++ b/ui/storybook/stories/control-plane-surfaces.stories.tsx
@@ -0,0 +1,266 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AlertTriangle, CheckCircle2, Clock3, Eye, GitPullRequest, Inbox, WalletCards } from "lucide-react";
+import { ActivityRow } from "@/components/ActivityRow";
+import { ApprovalCard } from "@/components/ApprovalCard";
+import { BudgetPolicyCard } from "@/components/BudgetPolicyCard";
+import { Identity } from "@/components/Identity";
+import { IssueRow } from "@/components/IssueRow";
+import { PriorityIcon } from "@/components/PriorityIcon";
+import { StatusBadge } from "@/components/StatusBadge";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+ storybookActivityEvents,
+ storybookAgentMap,
+ storybookAgents,
+ storybookApprovals,
+ storybookBudgetSummaries,
+ storybookEntityNameMap,
+ storybookEntityTitleMap,
+ storybookIssues,
+} from "../fixtures/paperclipData";
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.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 ControlPlaneSurfaces() {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner 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">Product surfaces</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Control-plane boards and cards</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Paperclip's common board surfaces are deliberately dense: task rows, approvals, budget policy cards,
+ and audit rows all need to scan quickly while preserving enough state to make autonomous work governable.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">company scoped</Badge>
+ <Badge variant="outline">single assignee</Badge>
+ <Badge variant="outline">auditable</Badge>
+ </div>
+ </div>
+ </section>
+
+ <Section eyebrow="Issues" title="Inbox/task rows across selection and unread states">
+ <div className="overflow-hidden rounded-xl border border-border bg-background/70">
+ {storybookIssues.map((issue, index) => (
+ <IssueRow
+ key={issue.id}
+ issue={issue}
+ selected={index === 0}
+ unreadState={index === 0 ? "visible" : index === 1 ? "hidden" : null}
+ onMarkRead={() => undefined}
+ onArchive={() => undefined}
+ desktopTrailing={
+ <span className="hidden items-center gap-2 lg:inline-flex">
+ <PriorityIcon priority={issue.priority} showLabel />
+ {issue.assigneeAgentId ? (
+ <Identity name={storybookAgentMap.get(issue.assigneeAgentId)?.name ?? "Unassigned"} size="sm" />
+ ) : (
+ <span className="text-xs text-muted-foreground">Board</span>
+ )}
+ </span>
+ }
+ trailingMeta={index === 0 ? "3m ago" : index === 1 ? "blocked by budget" : "review requested"}
+ mobileMeta={<StatusBadge status={issue.status} />}
+ titleSuffix={
+ index === 0 ? (
+ <span className="ml-2 inline-flex align-middle">
+ <Badge variant="secondary">Storybook</Badge>
+ </span>
+ ) : null
+ }
+ />
+ ))}
+ </div>
+ </Section>
+
+ <Section eyebrow="Approvals" title="Governance cards for pending, revision, and approved decisions">
+ <div className="grid gap-5 xl:grid-cols-3">
+ {storybookApprovals.map((approval) => (
+ <ApprovalCard
+ key={approval.id}
+ approval={approval}
+ requesterAgent={approval.requestedByAgentId ? storybookAgentMap.get(approval.requestedByAgentId) ?? null : null}
+ onApprove={approval.status === "pending" ? () => undefined : undefined}
+ onReject={approval.status === "pending" ? () => undefined : undefined}
+ detailLink={`/approvals/${approval.id}`}
+ />
+ ))}
+ </div>
+ </Section>
+
+ <Section eyebrow="Budgets" title="Healthy, warning, and hard-stop budget policy cards">
+ <div className="grid gap-5 xl:grid-cols-3">
+ {storybookBudgetSummaries.map((summary, index) => (
+ <BudgetPolicyCard
+ key={summary.policyId}
+ summary={summary}
+ compact={index === 0}
+ onSave={index === 1 ? () => undefined : undefined}
+ />
+ ))}
+ </div>
+ <div className="mt-5 rounded-xl border border-border bg-background/70 p-5">
+ <BudgetPolicyCard
+ summary={storybookBudgetSummaries[2]!}
+ variant="plain"
+ onSave={() => undefined}
+ />
+ </div>
+ </Section>
+
+ <Section eyebrow="Activity" title="Audit rows with agent, user, and system actors">
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_360px]">
+ <div className="overflow-hidden rounded-xl border border-border bg-background/70">
+ {storybookActivityEvents.map((event) => (
+ <ActivityRow
+ key={event.id}
+ event={event}
+ agentMap={storybookAgentMap}
+ entityNameMap={storybookEntityNameMap}
+ entityTitleMap={storybookEntityTitleMap}
+ />
+ ))}
+ </div>
+
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Run summary card language</CardTitle>
+ <CardDescription>Compact status treatments used around live work.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-3">
+ {[
+ { icon: Clock3, label: "Running", detail: "CodexCoder is editing Storybook fixtures", tone: "text-cyan-600" },
+ { icon: GitPullRequest, label: "Review", detail: "QAChecker requested browser screenshots", tone: "text-amber-600" },
+ { icon: CheckCircle2, label: "Verified", detail: "Vitest and static Storybook build passed", tone: "text-emerald-600" },
+ { icon: AlertTriangle, label: "Blocked", detail: "Budget hard stop paused a run", tone: "text-red-600" },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <div key={item.label} className="flex items-start gap-3 rounded-lg border border-border bg-background/70 p-3">
+ <Icon className={`mt-0.5 h-4 w-4 ${item.tone}`} />
+ <div>
+ <div className="text-sm font-medium">{item.label}</div>
+ <div className="text-xs leading-5 text-muted-foreground">{item.detail}</div>
+ </div>
+ </div>
+ );
+ })}
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+
+ <Section eyebrow="Agents" title="Org snippets and quick scan identity">
+ <div className="grid gap-4 md:grid-cols-3">
+ {storybookAgents.map((agent) => (
+ <Card key={agent.id} className="shadow-none">
+ <CardHeader>
+ <div className="flex items-start justify-between gap-3">
+ <Identity name={agent.name} size="lg" />
+ <StatusBadge status={agent.status} />
+ </div>
+ <CardDescription>{agent.title}</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-3 text-sm">
+ <p className="leading-6 text-muted-foreground">{agent.capabilities}</p>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">{agent.role}</Badge>
+ <Badge variant="outline">{agent.adapterType}</Badge>
+ <Badge variant="outline" className="gap-1">
+ <WalletCards className="h-3 w-3" />
+ ${(agent.spentMonthlyCents / 100).toFixed(0)} spent
+ </Badge>
+ </div>
+ </CardContent>
+ </Card>
+ ))}
+ </div>
+ </Section>
+
+ <Section eyebrow="Quicklook" title="Side-panel density reference">
+ <div className="grid gap-4 lg:grid-cols-[320px_minmax(0,1fr)]">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <Inbox className="h-4 w-4" />
+ Inbox slice
+ </CardTitle>
+ <CardDescription>Small panels should keep controls reachable without nested cards.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-2">
+ <div className="flex items-center justify-between text-sm">
+ <span>Unread</span>
+ <span className="font-mono">7</span>
+ </div>
+ <div className="flex items-center justify-between text-sm">
+ <span>Needs review</span>
+ <span className="font-mono">3</span>
+ </div>
+ <div className="flex items-center justify-between text-sm">
+ <span>Blocked</span>
+ <span className="font-mono">1</span>
+ </div>
+ </CardContent>
+ </Card>
+ <div className="rounded-xl border border-border bg-background/70 p-5">
+ <div className="mb-4 flex items-center gap-2 text-sm font-medium">
+ <Eye className="h-4 w-4 text-muted-foreground" />
+ Review target
+ </div>
+ <IssueRow
+ issue={storybookIssues[0]!}
+ selected
+ unreadState="visible"
+ onMarkRead={() => undefined}
+ desktopTrailing={<PriorityIcon priority="high" showLabel />}
+ trailingMeta="active run"
+ />
+ </div>
+ </div>
+ </Section>
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Product/Control Plane Surfaces",
+ component: ControlPlaneSurfaces,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Product-surface stories exercise the board UI components that carry Paperclip's task, approval, budget, activity, and agent governance workflows.",
+ },
+ },
+ },
+} satisfies Meta<typeof ControlPlaneSurfaces>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const BoardStateMatrix: Story = {};
diff --git a/ui/storybook/stories/data-viz-misc.stories.tsx b/ui/storybook/stories/data-viz-misc.stories.tsx
new file mode 100644
index 0000000000..2022b3cd43
--- /dev/null
+++ b/ui/storybook/stories/data-viz-misc.stories.tsx
@@ -0,0 +1,757 @@
+import { useEffect, useMemo, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { HeartbeatRun, Issue } from "@paperclipai/shared";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+ Archive,
+ Bot,
+ CheckCircle2,
+ Clock3,
+ FileCode2,
+ FolderKanban,
+ ListFilter,
+ Loader2,
+ Play,
+ ShieldCheck,
+ Sparkles,
+} from "lucide-react";
+import {
+ ChartCard,
+ IssueStatusChart,
+ PriorityChart,
+ RunActivityChart,
+ SuccessRateChart,
+} from "@/components/ActivityCharts";
+import { AsciiArtAnimation } from "@/components/AsciiArtAnimation";
+import { CompanyPatternIcon } from "@/components/CompanyPatternIcon";
+import { EntityRow } from "@/components/EntityRow";
+import { FilterBar, type FilterValue } from "@/components/FilterBar";
+import { KanbanBoard } from "@/components/KanbanBoard";
+import { LiveRunWidget } from "@/components/LiveRunWidget";
+import { OnboardingWizard } from "@/components/OnboardingWizard";
+import {
+ buildFileTree,
+ collectAllPaths,
+ countFiles,
+ PackageFileTree,
+ parseFrontmatter,
+ type FileTreeNode,
+} from "@/components/PackageFileTree";
+import { PageSkeleton } from "@/components/PageSkeleton";
+import { StatusBadge } from "@/components/StatusBadge";
+import { SwipeToArchive } from "@/components/SwipeToArchive";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { useDialog } from "@/context/DialogContext";
+import { queryKeys } from "@/lib/queryKeys";
+import {
+ createIssue,
+ storybookAgents,
+ storybookIssues,
+ storybookLiveRuns,
+} from "../fixtures/paperclipData";
+
+const companyId = "company-storybook";
+const primaryIssueId = "issue-storybook-1";
+
+function StoryShell({ children }: { children: React.ReactNode }) {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">{children}</main>
+ </div>
+ );
+}
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.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 daysAgo(days: number, hour = 12): Date {
+ const date = new Date();
+ date.setHours(hour, 0, 0, 0);
+ date.setDate(date.getDate() - days);
+ return date;
+}
+
+function makeHeartbeatRun(overrides: Partial<HeartbeatRun>): HeartbeatRun {
+ const createdAt = overrides.createdAt ?? daysAgo(1);
+ const run: HeartbeatRun = {
+ id: "run-fixture",
+ companyId,
+ agentId: "agent-codex",
+ invocationSource: "on_demand",
+ triggerDetail: "manual",
+ status: "succeeded",
+ startedAt: createdAt,
+ finishedAt: new Date(createdAt.getTime() + 11 * 60_000),
+ error: null,
+ wakeupRequestId: null,
+ exitCode: 0,
+ signal: null,
+ usageJson: null,
+ resultJson: null,
+ sessionIdBefore: null,
+ sessionIdAfter: null,
+ logStore: null,
+ logRef: null,
+ logBytes: 0,
+ logSha256: null,
+ logCompressed: false,
+ stdoutExcerpt: null,
+ stderrExcerpt: null,
+ errorCode: null,
+ externalRunId: null,
+ processPid: null,
+ processGroupId: null,
+ processStartedAt: createdAt,
+ retryOfRunId: null,
+ processLossRetryCount: 0,
+ livenessState: "completed",
+ livenessReason: null,
+ continuationAttempt: 0,
+ lastUsefulActionAt: null,
+ nextAction: null,
+ contextSnapshot: null,
+ ...overrides,
+ createdAt,
+ updatedAt: overrides.updatedAt ?? createdAt,
+ };
+ return run;
+}
+
+const activityRuns: HeartbeatRun[] = [
+ makeHeartbeatRun({ id: "run-chart-1", status: "succeeded", createdAt: daysAgo(13), startedAt: daysAgo(13) }),
+ makeHeartbeatRun({ id: "run-chart-2", status: "succeeded", createdAt: daysAgo(10), startedAt: daysAgo(10) }),
+ makeHeartbeatRun({ id: "run-chart-3", status: "failed", createdAt: daysAgo(10), startedAt: daysAgo(10, 15), exitCode: 1 }),
+ makeHeartbeatRun({ id: "run-chart-4", status: "running", createdAt: daysAgo(7), startedAt: daysAgo(7), finishedAt: null }),
+ makeHeartbeatRun({ id: "run-chart-5", status: "succeeded", createdAt: daysAgo(5), startedAt: daysAgo(5) }),
+ makeHeartbeatRun({ id: "run-chart-6", status: "timed_out", createdAt: daysAgo(3), startedAt: daysAgo(3), errorCode: "timeout" }),
+ makeHeartbeatRun({ id: "run-chart-7", status: "succeeded", createdAt: daysAgo(1), startedAt: daysAgo(1) }),
+ makeHeartbeatRun({ id: "run-chart-8", status: "succeeded", createdAt: daysAgo(1, 16), startedAt: daysAgo(1, 16) }),
+];
+
+const activityIssues = [
+ { priority: "high", status: "in_progress", createdAt: daysAgo(13) },
+ { priority: "critical", status: "blocked", createdAt: daysAgo(11) },
+ { priority: "medium", status: "todo", createdAt: daysAgo(9) },
+ { priority: "medium", status: "in_review", createdAt: daysAgo(9, 16) },
+ { priority: "low", status: "done", createdAt: daysAgo(6) },
+ { priority: "high", status: "todo", createdAt: daysAgo(4) },
+ { priority: "critical", status: "in_progress", createdAt: daysAgo(2) },
+ { priority: "medium", status: "done", createdAt: daysAgo(1) },
+];
+
+const kanbanIssues: Issue[] = [
+ ...storybookIssues,
+ createIssue({
+ id: "issue-kanban-backlog",
+ identifier: "PAP-1701",
+ issueNumber: 1701,
+ title: "Sketch company analytics dashboard",
+ status: "backlog",
+ priority: "low",
+ assigneeAgentId: "agent-cto",
+ }),
+ createIssue({
+ id: "issue-kanban-cancelled",
+ identifier: "PAP-1702",
+ issueNumber: 1702,
+ title: "Remove obsolete color token migration",
+ status: "cancelled",
+ priority: "medium",
+ assigneeAgentId: null,
+ }),
+];
+
+const packageFiles: Record<string, string> = {
+ "COMPANY.md": "---\nname: Paperclip Storybook\nkind: company\n---\nFixture company package for UI review.",
+ "agents/codexcoder/AGENTS.md": "---\nname: CodexCoder\nskills:\n - frontend-design\n - paperclip\n---\nShips product UI and verifies changes.",
+ "agents/qachecker/AGENTS.md": "---\nname: QAChecker\nskills:\n - web-design-guidelines\n---\nReviews browser behavior and acceptance criteria.",
+ "projects/board-ui/PROJECT.md": "---\ntitle: Board UI\nstatus: in_progress\n---\nStorybook and operator control-plane surfaces.",
+ "tasks/PAP-1641.md": "---\ntitle: Create super-detailed storybooks\npriority: high\n---\nParent issue for Storybook coverage.",
+ "tasks/PAP-1677.md": "---\ntitle: Data Visualization & Misc stories\npriority: medium\n---\nFixture task for this story file.",
+ "skills/frontend-design/SKILL.md": "---\nname: frontend-design\n---\nDesign quality guidance.",
+};
+
+const actionMap = new Map([
+ ["COMPANY.md", "replace"],
+ ["agents/codexcoder/AGENTS.md", "update"],
+ ["agents/qachecker/AGENTS.md", "create"],
+ ["tasks/PAP-1677.md", "create"],
+]);
+
+function ActivityChartsMatrix({ empty = false }: { empty?: boolean }) {
+ const runs = empty ? [] : activityRuns;
+ const issues = empty ? [] : activityIssues;
+
+ return (
+ <StoryShell>
+ <Section eyebrow="ActivityCharts" title={empty ? "Empty activity timelines" : "Two-week activity timelines"}>
+ <div className="grid gap-4 md:grid-cols-2">
+ <ChartCard title="Run activity" subtitle="Succeeded, failed, and in-flight heartbeats">
+ <RunActivityChart runs={runs} />
+ </ChartCard>
+ <ChartCard title="Success rate" subtitle="Daily completion ratio">
+ <SuccessRateChart runs={runs} />
+ </ChartCard>
+ <ChartCard title="Issue priority" subtitle="Created issues by urgency">
+ <PriorityChart issues={issues} />
+ </ChartCard>
+ <ChartCard title="Issue status" subtitle="Created issues by workflow state">
+ <IssueStatusChart issues={issues} />
+ </ChartCard>
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function KanbanBoardDemo({ empty = false }: { empty?: boolean }) {
+ const [issues, setIssues] = useState<Issue[]>(empty ? [] : kanbanIssues);
+ const liveIssueIds = useMemo(() => new Set(["issue-storybook-1", "issue-kanban-backlog"]), []);
+
+ return (
+ <StoryShell>
+ <Section eyebrow="KanbanBoard" title={empty ? "Collapsed empty workflow columns" : "Draggable issue cards by status"}>
+ <KanbanBoard
+ issues={issues}
+ agents={storybookAgents}
+ liveIssueIds={liveIssueIds}
+ onUpdateIssue={(id, data) => {
+ setIssues((current) =>
+ current.map((issue) => (issue.id === id ? { ...issue, ...data } : issue)),
+ );
+ }}
+ />
+ </Section>
+ </StoryShell>
+ );
+}
+
+function FilterBarDemo({ empty = false }: { empty?: boolean }) {
+ const [filters, setFilters] = useState<FilterValue[]>(
+ empty
+ ? []
+ : [
+ { key: "status", label: "Status", value: "In progress" },
+ { key: "assignee", label: "Assignee", value: "CodexCoder" },
+ { key: "priority", label: "Priority", value: "High" },
+ { key: "project", label: "Project", value: "Board UI" },
+ ],
+ );
+
+ return (
+ <StoryShell>
+ <Section eyebrow="FilterBar" title={empty ? "No active filters" : "Active removable filter chips"}>
+ <div className="rounded-lg border border-dashed border-border bg-background/70 p-4">
+ <FilterBar
+ filters={filters}
+ onRemove={(key) => setFilters((current) => current.filter((filter) => filter.key !== key))}
+ onClear={() => setFilters([])}
+ />
+ {filters.length === 0 && (
+ <div className="flex items-center gap-2 text-sm text-muted-foreground">
+ <ListFilter className="h-4 w-4" />
+ No filters are active.
+ </div>
+ )}
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function LiveRunWidgetStory({ empty = false, loading = false }: { empty?: boolean; loading?: boolean }) {
+ const queryClient = useQueryClient();
+
+ useEffect(() => {
+ if (loading) return;
+ queryClient.setQueryData(queryKeys.issues.liveRuns(primaryIssueId), empty ? [] : storybookLiveRuns);
+ queryClient.setQueryData(queryKeys.issues.activeRun(primaryIssueId), empty ? null : storybookLiveRuns[0]);
+ }, [empty, loading, queryClient]);
+
+ if (loading) {
+ return (
+ <StoryShell>
+ <Section eyebrow="LiveRunWidget" title="Loading live run status">
+ <div className="flex items-center gap-3 rounded-xl border border-border bg-background/70 p-4 text-sm text-muted-foreground">
+ <Loader2 className="h-4 w-4 animate-spin" />
+ Waiting for the first run poll.
+ </div>
+ </Section>
+ </StoryShell>
+ );
+ }
+
+ return (
+ <StoryShell>
+ <Section eyebrow="LiveRunWidget" title={empty ? "No active run" : "Streaming run indicator"}>
+ <LiveRunWidget issueId={primaryIssueId} />
+ {empty && (
+ <div className="flex items-center gap-3 rounded-xl border border-border bg-background/70 p-4 text-sm text-muted-foreground">
+ <Clock3 className="h-4 w-4" />
+ The widget renders no panel when the issue has no live runs.
+ </div>
+ )}
+ </Section>
+ </StoryShell>
+ );
+}
+
+function OpenOnboardingOnMount({ initialStep }: { initialStep: 1 | 2 }) {
+ const { openOnboarding } = useDialog();
+ const queryClient = useQueryClient();
+
+ useEffect(() => {
+ queryClient.setQueryData(queryKeys.agents.adapterModels(companyId, "claude_local"), [
+ { id: "claude-sonnet-4-5", label: "Claude Sonnet 4.5" },
+ { id: "claude-opus-4-1", label: "Claude Opus 4.1" },
+ ]);
+ openOnboarding(initialStep === 1 ? { initialStep } : { initialStep, companyId });
+ }, [initialStep, openOnboarding, queryClient]);
+
+ return <OnboardingWizard />;
+}
+
+function PackageFileTreeDemo({ empty = false }: { empty?: boolean }) {
+ const nodes = useMemo(
+ () => (empty ? [] : buildFileTree(packageFiles, actionMap)),
+ [empty],
+ );
+ const allFilePaths = useMemo(() => collectAllPaths(nodes, "file"), [nodes]);
+ const [expandedDirs, setExpandedDirs] = useState(() => collectAllPaths(nodes, "dir"));
+ const [checkedFiles, setCheckedFiles] = useState(() => allFilePaths);
+ const [selectedFile, setSelectedFile] = useState<string | null>(empty ? null : "tasks/PAP-1677.md");
+
+ useEffect(() => {
+ setExpandedDirs(collectAllPaths(nodes, "dir"));
+ setCheckedFiles(allFilePaths);
+ setSelectedFile(empty ? null : "tasks/PAP-1677.md");
+ }, [allFilePaths, empty, nodes]);
+
+ const selectedContent = selectedFile ? packageFiles[selectedFile] ?? "" : "";
+ const frontmatter = selectedContent ? parseFrontmatter(selectedContent) : null;
+
+ function toggleDir(path: string) {
+ setExpandedDirs((current) => {
+ const next = new Set(current);
+ if (next.has(path)) next.delete(path);
+ else next.add(path);
+ return next;
+ });
+ }
+
+ function toggleCheck(path: string, kind: "file" | "dir") {
+ setCheckedFiles((current) => {
+ const next = new Set(current);
+ const paths =
+ kind === "file"
+ ? [path]
+ : [...collectAllPaths(findNode(nodes, path)?.children ?? [], "file")];
+ const shouldCheck = paths.some((candidate) => !next.has(candidate));
+ for (const candidate of paths) {
+ if (shouldCheck) next.add(candidate);
+ else next.delete(candidate);
+ }
+ return next;
+ });
+ }
+
+ return (
+ <StoryShell>
+ <Section eyebrow="PackageFileTree" title={empty ? "Empty package export" : "Selectable company package tree"}>
+ {empty ? (
+ <div className="rounded-lg border border-dashed border-border bg-background/70 p-6 text-sm text-muted-foreground">
+ No files are included in this package preview.
+ </div>
+ ) : (
+ <div className="grid gap-4 lg:grid-cols-[minmax(280px,0.9fr)_minmax(0,1.1fr)]">
+ <div className="overflow-hidden rounded-lg border border-border bg-background/70">
+ <div className="flex items-center justify-between border-b border-border px-4 py-3 text-sm">
+ <span className="font-medium">Package contents</span>
+ <Badge variant="outline">{countFiles(nodes)} files</Badge>
+ </div>
+ <PackageFileTree
+ nodes={nodes}
+ selectedFile={selectedFile}
+ expandedDirs={expandedDirs}
+ checkedFiles={checkedFiles}
+ onToggleDir={toggleDir}
+ onSelectFile={setSelectedFile}
+ onToggleCheck={toggleCheck}
+ renderFileExtra={(node) =>
+ node.action ? (
+ <Badge variant="secondary" className="ml-auto text-[10px]">
+ {node.action}
+ </Badge>
+ ) : null
+ }
+ />
+ </div>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2 text-base">
+ <FileCode2 className="h-4 w-4" />
+ {selectedFile}
+ </CardTitle>
+ <CardDescription>Frontmatter and markdown body parsed from the selected package file.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-3">
+ {frontmatter ? (
+ <div className="grid gap-2 sm:grid-cols-2">
+ {Object.entries(frontmatter.data).map(([key, value]) => (
+ <div key={key} className="rounded-md border border-border bg-background/70 p-2">
+ <div className="text-[10px] uppercase text-muted-foreground">{key}</div>
+ <div className="mt-1 text-sm">{Array.isArray(value) ? value.join(", ") : value}</div>
+ </div>
+ ))}
+ </div>
+ ) : null}
+ <pre className="max-h-56 overflow-auto rounded-md bg-muted/40 p-3 text-xs leading-5">
+ {frontmatter?.body.trim() || selectedContent}
+ </pre>
+ </CardContent>
+ </Card>
+ </div>
+ )}
+ </Section>
+ </StoryShell>
+ );
+}
+
+function findNode(nodes: FileTreeNode[], path: string): FileTreeNode | null {
+ for (const node of nodes) {
+ if (node.path === path) return node;
+ const child = findNode(node.children, path);
+ if (child) return child;
+ }
+ return null;
+}
+
+function EntityRowsDemo({ empty = false }: { empty?: boolean }) {
+ const rows = empty
+ ? []
+ : [
+ {
+ id: "agent",
+ leading: <Bot className="h-4 w-4 text-cyan-600" />,
+ identifier: "agent",
+ title: "CodexCoder",
+ subtitle: "Senior Product Engineer · active in Storybook worktree",
+ trailing: <StatusBadge status="running" />,
+ selected: true,
+ },
+ {
+ id: "issue",
+ leading: <FolderKanban className="h-4 w-4 text-emerald-600" />,
+ identifier: "PAP-1677",
+ title: "Storybook: Data Visualization & Misc stories",
+ subtitle: "Medium priority · Board UI project",
+ trailing: <Badge variant="secondary">UI</Badge>,
+ },
+ {
+ id: "approval",
+ leading: <ShieldCheck className="h-4 w-4 text-amber-600" />,
+ identifier: "approval",
+ title: "Publish Storybook preview",
+ subtitle: "Approved for internal design review",
+ trailing: <CheckCircle2 className="h-4 w-4 text-emerald-600" />,
+ },
+ ];
+
+ return (
+ <StoryShell>
+ <Section eyebrow="EntityRow" title={empty ? "Empty list container" : "Generic list rows"}>
+ <div className="overflow-hidden rounded-lg border border-border bg-background/70">
+ {rows.map((row) => (
+ <EntityRow
+ key={row.id}
+ leading={row.leading}
+ identifier={row.identifier}
+ title={row.title}
+ subtitle={row.subtitle}
+ trailing={row.trailing}
+ selected={row.selected}
+ to={row.id === "issue" ? "/PAP/issues/PAP-1677" : undefined}
+ />
+ ))}
+ {rows.length === 0 && (
+ <div className="p-6 text-sm text-muted-foreground">No entities match this view.</div>
+ )}
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function SwipeToArchiveDemo({ disabled = false }: { disabled?: boolean }) {
+ const [archived, setArchived] = useState(false);
+
+ return (
+ <StoryShell>
+ <Section eyebrow="SwipeToArchive" title={disabled ? "Disabled mobile gesture" : "Mobile archive gesture"}>
+ <div className="mx-auto w-full max-w-sm overflow-hidden rounded-2xl border border-border bg-background shadow-sm">
+ <div className="border-b border-border px-4 py-3 text-xs uppercase tracking-wide text-muted-foreground">
+ Inbox
+ </div>
+ {archived ? (
+ <div className="flex items-center justify-center gap-2 p-8 text-sm text-muted-foreground">
+ <Archive className="h-4 w-4" />
+ Archived
+ </div>
+ ) : (
+ <SwipeToArchive
+ selected
+ disabled={disabled}
+ onArchive={() => setArchived(true)}
+ >
+ <EntityRow
+ leading={<Play className="h-4 w-4 text-cyan-600" />}
+ identifier="PAP-1677"
+ title="Storybook: Data Visualization & Misc stories"
+ subtitle={disabled ? "Gesture disabled while review is locked" : "Swipe left on touch devices to archive"}
+ trailing={<Badge variant="outline">mobile</Badge>}
+ />
+ </SwipeToArchive>
+ )}
+ <Button
+ variant="ghost"
+ size="sm"
+ className="m-3"
+ onClick={() => setArchived(false)}
+ >
+ Reset
+ </Button>
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function CompanyPatternIconMatrix() {
+ const companies = [
+ { name: "Paperclip Storybook", color: "#0f766e" },
+ { name: "Research Bureau", color: "#2563eb" },
+ { name: "Launch Ops", color: "#c2410c" },
+ { name: "Atlas Finance", color: "#7c3aed" },
+ ];
+ const sizes = ["h-8 w-8 text-xs", "h-11 w-11 text-base", "h-16 w-16 text-xl", "h-24 w-24 text-3xl"];
+
+ return (
+ <StoryShell>
+ <Section eyebrow="CompanyPatternIcon" title="Generated company pattern icons by size">
+ <div className="grid gap-4 md:grid-cols-2">
+ {companies.map((company) => (
+ <Card key={company.name} className="shadow-none">
+ <CardHeader>
+ <CardTitle className="text-base">{company.name}</CardTitle>
+ <CardDescription>{company.color}</CardDescription>
+ </CardHeader>
+ <CardContent className="flex flex-wrap items-end gap-4">
+ {sizes.map((size) => (
+ <CompanyPatternIcon
+ key={size}
+ companyName={company.name}
+ brandColor={company.color}
+ className={size}
+ />
+ ))}
+ </CardContent>
+ </Card>
+ ))}
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function AsciiArtAnimationDemo({ loading = false }: { loading?: boolean }) {
+ return (
+ <StoryShell>
+ <Section eyebrow="AsciiArtAnimation" title={loading ? "Loading art surface" : "Animated ASCII paperclip field"}>
+ <div className="h-[360px] overflow-hidden rounded-xl border border-border bg-background">
+ {loading ? (
+ <div className="flex h-full items-center justify-center gap-3 text-sm text-muted-foreground">
+ <Loader2 className="h-4 w-4 animate-spin" />
+ Preparing animation canvas
+ </div>
+ ) : (
+ <AsciiArtAnimation />
+ )}
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function PageSkeletonMatrix() {
+ const variants = [
+ "list",
+ "issues-list",
+ "detail",
+ "dashboard",
+ "approvals",
+ "costs",
+ "inbox",
+ "org-chart",
+ ] as const;
+
+ return (
+ <StoryShell>
+ <Section eyebrow="PageSkeleton" title="Loading skeletons for page layouts">
+ <div className="grid gap-5 xl:grid-cols-2">
+ {variants.map((variant) => (
+ <Card key={variant} className="shadow-none">
+ <CardHeader>
+ <CardTitle className="text-base">{variant}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <div className="max-h-[420px] overflow-hidden">
+ <PageSkeleton variant={variant} />
+ </div>
+ </CardContent>
+ </Card>
+ ))}
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+const meta = {
+ title: "Product/Data Visualization & Misc",
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Fixture-backed stories for charting, board, filtering, live run, onboarding, package preview, entity row, mobile gesture, generated icon, ASCII animation, and skeleton states.",
+ },
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ActivityChartsPopulated: Story = {
+ name: "ActivityCharts / Populated",
+ render: () => <ActivityChartsMatrix />,
+};
+
+export const ActivityChartsEmpty: Story = {
+ name: "ActivityCharts / Empty",
+ render: () => <ActivityChartsMatrix empty />,
+};
+
+export const KanbanBoardPopulated: Story = {
+ name: "KanbanBoard / Populated",
+ render: () => <KanbanBoardDemo />,
+};
+
+export const KanbanBoardEmpty: Story = {
+ name: "KanbanBoard / Empty",
+ render: () => <KanbanBoardDemo empty />,
+};
+
+export const FilterBarPopulated: Story = {
+ name: "FilterBar / Populated",
+ render: () => <FilterBarDemo />,
+};
+
+export const FilterBarEmpty: Story = {
+ name: "FilterBar / Empty",
+ render: () => <FilterBarDemo empty />,
+};
+
+export const LiveRunWidgetPopulated: Story = {
+ name: "LiveRunWidget / Populated",
+ render: () => <LiveRunWidgetStory />,
+};
+
+export const LiveRunWidgetLoading: Story = {
+ name: "LiveRunWidget / Loading",
+ render: () => <LiveRunWidgetStory loading />,
+};
+
+export const LiveRunWidgetEmpty: Story = {
+ name: "LiveRunWidget / Empty",
+ render: () => <LiveRunWidgetStory empty />,
+};
+
+export const OnboardingWizardCompanyStep: Story = {
+ name: "OnboardingWizard / Company Step",
+ render: () => <OpenOnboardingOnMount initialStep={1} />,
+};
+
+export const OnboardingWizardAgentStep: Story = {
+ name: "OnboardingWizard / Agent Step",
+ render: () => <OpenOnboardingOnMount initialStep={2} />,
+};
+
+export const PackageFileTreePopulated: Story = {
+ name: "PackageFileTree / Populated",
+ render: () => <PackageFileTreeDemo />,
+};
+
+export const PackageFileTreeEmpty: Story = {
+ name: "PackageFileTree / Empty",
+ render: () => <PackageFileTreeDemo empty />,
+};
+
+export const EntityRowPopulated: Story = {
+ name: "EntityRow / Populated",
+ render: () => <EntityRowsDemo />,
+};
+
+export const EntityRowEmpty: Story = {
+ name: "EntityRow / Empty",
+ render: () => <EntityRowsDemo empty />,
+};
+
+export const SwipeToArchiveMobile: Story = {
+ name: "SwipeToArchive / Mobile",
+ render: () => <SwipeToArchiveDemo />,
+};
+
+export const SwipeToArchiveDisabled: Story = {
+ name: "SwipeToArchive / Disabled",
+ render: () => <SwipeToArchiveDemo disabled />,
+};
+
+export const CompanyPatternIconSizes: Story = {
+ name: "CompanyPatternIcon / Sizes",
+ render: () => <CompanyPatternIconMatrix />,
+};
+
+export const AsciiArtAnimationPopulated: Story = {
+ name: "AsciiArtAnimation / Populated",
+ render: () => <AsciiArtAnimationDemo />,
+};
+
+export const AsciiArtAnimationLoading: Story = {
+ name: "AsciiArtAnimation / Loading",
+ render: () => <AsciiArtAnimationDemo loading />,
+};
+
+export const PageSkeletonLayouts: Story = {
+ name: "PageSkeleton / Layouts",
+ render: () => <PageSkeletonMatrix />,
+};
diff --git a/ui/storybook/stories/dialogs-modals.stories.tsx b/ui/storybook/stories/dialogs-modals.stories.tsx
new file mode 100644
index 0000000000..4a2cc720b5
--- /dev/null
+++ b/ui/storybook/stories/dialogs-modals.stories.tsx
@@ -0,0 +1,836 @@
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type {
+ DocumentRevision,
+ ExecutionWorkspaceCloseReadiness,
+ Goal,
+ IssueAttachment,
+} from "@paperclipai/shared";
+import { useQueryClient } from "@tanstack/react-query";
+import { Badge } from "@/components/ui/badge";
+import { DocumentDiffModal } from "@/components/DocumentDiffModal";
+import { ExecutionWorkspaceCloseDialog } from "@/components/ExecutionWorkspaceCloseDialog";
+import { ImageGalleryModal } from "@/components/ImageGalleryModal";
+import { NewAgentDialog } from "@/components/NewAgentDialog";
+import { NewGoalDialog } from "@/components/NewGoalDialog";
+import { NewIssueDialog } from "@/components/NewIssueDialog";
+import { NewProjectDialog } from "@/components/NewProjectDialog";
+import { PathInstructionsModal } from "@/components/PathInstructionsModal";
+import { useCompany } from "@/context/CompanyContext";
+import { useDialog } from "@/context/DialogContext";
+import { queryKeys } from "@/lib/queryKeys";
+import {
+ storybookAgents,
+ storybookAuthSession,
+ storybookCompanies,
+ storybookExecutionWorkspaces,
+ storybookIssueDocuments,
+ storybookIssueLabels,
+ storybookIssues,
+ storybookProjects,
+} from "../fixtures/paperclipData";
+
+const COMPANY_ID = "company-storybook";
+const SELECTED_COMPANY_STORAGE_KEY = "paperclip.selectedCompanyId";
+const ISSUE_DRAFT_STORAGE_KEY = "paperclip:issue-draft";
+
+const storybookGoals: Goal[] = [
+ {
+ id: "goal-company",
+ companyId: COMPANY_ID,
+ title: "Build Paperclip",
+ description: "Make autonomous companies easier to run and govern.",
+ level: "company",
+ status: "active",
+ parentId: null,
+ ownerAgentId: "agent-cto",
+ createdAt: new Date("2026-04-01T09:00:00.000Z"),
+ updatedAt: new Date("2026-04-20T11:00:00.000Z"),
+ },
+ {
+ id: "goal-storybook",
+ companyId: COMPANY_ID,
+ title: "Complete Storybook coverage",
+ description: "Expose dense board UI states for review before release.",
+ level: "team",
+ status: "active",
+ parentId: "goal-company",
+ ownerAgentId: "agent-codex",
+ createdAt: new Date("2026-04-17T09:00:00.000Z"),
+ updatedAt: new Date("2026-04-20T11:10:00.000Z"),
+ },
+ {
+ id: "goal-governance",
+ companyId: COMPANY_ID,
+ title: "Tighten governance review",
+ description: "Make review and approval gates visible in every operator flow.",
+ level: "team",
+ status: "planned",
+ parentId: "goal-company",
+ ownerAgentId: "agent-cto",
+ createdAt: new Date("2026-04-18T09:00:00.000Z"),
+ updatedAt: new Date("2026-04-20T11:15:00.000Z"),
+ },
+];
+
+const documentRevisions: DocumentRevision[] = [
+ {
+ id: "revision-plan-1",
+ companyId: COMPANY_ID,
+ documentId: "document-plan-storybook",
+ issueId: "issue-storybook-1",
+ key: "plan",
+ revisionNumber: 1,
+ title: "Plan",
+ format: "markdown",
+ body: [
+ "# Plan",
+ "",
+ "- Add overview stories for the dashboard.",
+ "- Create issue list stories for filters and grouping.",
+ "- Ask QA to review the final Storybook build.",
+ ].join("\n"),
+ changeSummary: "Initial plan",
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ createdAt: new Date("2026-04-20T08:00:00.000Z"),
+ },
+ {
+ id: "revision-plan-2",
+ companyId: COMPANY_ID,
+ documentId: "document-plan-storybook",
+ issueId: "issue-storybook-1",
+ key: "plan",
+ revisionNumber: 2,
+ title: "Plan",
+ format: "markdown",
+ body: [
+ "# Plan",
+ "",
+ "- Add overview stories for the dashboard.",
+ "- Create issue list stories for filters, grouping, and workspace state.",
+ "- Add dialog stories for issue, goal, project, and workspace workflows.",
+ "- Ask QA to review the final Storybook build.",
+ ].join("\n"),
+ changeSummary: "Expanded component coverage",
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ createdAt: new Date("2026-04-20T10:00:00.000Z"),
+ },
+ {
+ id: "revision-plan-3",
+ companyId: COMPANY_ID,
+ documentId: "document-plan-storybook",
+ issueId: "issue-storybook-1",
+ key: "plan",
+ revisionNumber: 3,
+ title: "Plan",
+ format: "markdown",
+ body: storybookIssueDocuments[0]?.body ?? "",
+ changeSummary: "Aligned with current issue scope",
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ createdAt: new Date("2026-04-20T11:30:00.000Z"),
+ },
+];
+
+const closeReadinessReady: ExecutionWorkspaceCloseReadiness = {
+ workspaceId: "execution-workspace-storybook",
+ state: "ready_with_warnings",
+ blockingReasons: [],
+ warnings: [
+ "The branch is still two commits ahead of master.",
+ "One shared runtime service will be stopped during cleanup.",
+ ],
+ linkedIssues: [
+ {
+ id: "issue-storybook-1",
+ identifier: "PAP-1641",
+ title: "Create super-detailed storybooks for the project",
+ status: "done",
+ isTerminal: true,
+ },
+ {
+ id: "issue-storybook-6",
+ identifier: "PAP-1670",
+ title: "Publish static Storybook preview",
+ status: "todo",
+ isTerminal: false,
+ },
+ ],
+ plannedActions: [
+ {
+ kind: "stop_runtime_services",
+ label: "Stop Storybook preview",
+ description: "Stops the managed Storybook preview service before archiving the workspace record.",
+ command: "pnpm dev:stop",
+ },
+ {
+ kind: "git_worktree_remove",
+ label: "Remove git worktree",
+ description: "Removes the issue worktree from the local worktree parent directory.",
+ command: "git worktree remove .paperclip/worktrees/PAP-1641-create-super-detailed-storybooks-for-our-project",
+ },
+ {
+ kind: "archive_record",
+ label: "Archive workspace record",
+ description: "Keeps audit history while removing the workspace from active workspace views.",
+ command: null,
+ },
+ ],
+ isDestructiveCloseAllowed: true,
+ isSharedWorkspace: false,
+ isProjectPrimaryWorkspace: false,
+ git: {
+ repoRoot: "/Users/dotta/paperclip",
+ workspacePath: "/Users/dotta/paperclip/.paperclip/worktrees/PAP-1641-create-super-detailed-storybooks-for-our-project",
+ branchName: "PAP-1641-create-super-detailed-storybooks-for-our-project",
+ baseRef: "master",
+ hasDirtyTrackedFiles: true,
+ hasUntrackedFiles: false,
+ dirtyEntryCount: 3,
+ untrackedEntryCount: 0,
+ aheadCount: 2,
+ behindCount: 0,
+ isMergedIntoBase: false,
+ createdByRuntime: true,
+ },
+ runtimeServices: storybookExecutionWorkspaces[0]?.runtimeServices ?? [],
+};
+
+const closeReadinessBlocked: ExecutionWorkspaceCloseReadiness = {
+ ...closeReadinessReady,
+ state: "blocked",
+ blockingReasons: [
+ "PAP-1670 is still open and references this execution workspace.",
+ "The worktree has dirty tracked files that have not been committed.",
+ ],
+ warnings: [],
+ plannedActions: closeReadinessReady.plannedActions.slice(0, 1),
+};
+
+const galleryImages: IssueAttachment[] = [
+ {
+ id: "attachment-storybook-dashboard",
+ companyId: COMPANY_ID,
+ issueId: "issue-storybook-1",
+ issueCommentId: null,
+ assetId: "asset-dashboard",
+ provider: "storybook",
+ objectKey: "storybook/dashboard-preview.svg",
+ contentType: "image/svg+xml",
+ byteSize: 1480,
+ sha256: "storybook-dashboard-preview",
+ originalFilename: "dashboard-preview.png",
+ createdByAgentId: "agent-codex",
+ createdByUserId: null,
+ createdAt: new Date("2026-04-20T10:30:00.000Z"),
+ updatedAt: new Date("2026-04-20T10:30:00.000Z"),
+ contentPath:
+ "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1400' height='900' viewBox='0 0 1400 900'%3E%3Crect width='1400' height='900' fill='%230f172a'/%3E%3Crect x='88' y='96' width='1224' height='708' rx='28' fill='%23111827' stroke='%23334155' stroke-width='4'/%3E%3Crect x='136' y='148' width='264' height='604' rx='18' fill='%231e293b'/%3E%3Crect x='444' y='148' width='380' height='190' rx='18' fill='%230f766e'/%3E%3Crect x='860' y='148' width='348' height='190' rx='18' fill='%232563eb'/%3E%3Crect x='444' y='382' width='764' height='104' rx='18' fill='%23334155'/%3E%3Crect x='444' y='526' width='764' height='104' rx='18' fill='%23334155'/%3E%3Crect x='444' y='670' width='520' height='82' rx='18' fill='%23334155'/%3E%3Ccircle cx='236' cy='236' r='58' fill='%2314b8a6'/%3E%3Crect x='188' y='334' width='164' height='18' rx='9' fill='%2394a3b8'/%3E%3Crect x='188' y='386' width='128' height='18' rx='9' fill='%2364748b'/%3E%3Crect x='188' y='438' width='176' height='18' rx='9' fill='%2364748b'/%3E%3C/svg%3E",
+ },
+ {
+ id: "attachment-storybook-diff",
+ companyId: COMPANY_ID,
+ issueId: "issue-storybook-1",
+ issueCommentId: null,
+ assetId: "asset-diff",
+ provider: "storybook",
+ objectKey: "storybook/diff-preview.svg",
+ contentType: "image/svg+xml",
+ byteSize: 1320,
+ sha256: "storybook-diff-preview",
+ originalFilename: "document-diff-preview.png",
+ createdByAgentId: "agent-qa",
+ createdByUserId: null,
+ createdAt: new Date("2026-04-20T10:40:00.000Z"),
+ updatedAt: new Date("2026-04-20T10:40:00.000Z"),
+ contentPath:
+ "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1400' height='900' viewBox='0 0 1400 900'%3E%3Crect width='1400' height='900' fill='%23171717'/%3E%3Crect x='110' y='104' width='1180' height='692' rx='24' fill='%230a0a0a' stroke='%23333333' stroke-width='4'/%3E%3Crect x='160' y='164' width='1080' height='48' rx='12' fill='%23262626'/%3E%3Crect x='160' y='260' width='1080' height='52' fill='%2315221a'/%3E%3Crect x='160' y='312' width='1080' height='52' fill='%23231818'/%3E%3Crect x='160' y='364' width='1080' height='52' fill='%2315221a'/%3E%3Crect x='160' y='468' width='1080' height='52' fill='%23231818'/%3E%3Crect x='160' y='520' width='1080' height='52' fill='%2315221a'/%3E%3Crect x='220' y='276' width='720' height='18' rx='9' fill='%2374c69d'/%3E%3Crect x='220' y='328' width='540' height='18' rx='9' fill='%23fca5a5'/%3E%3Crect x='220' y='380' width='820' height='18' rx='9' fill='%2374c69d'/%3E%3Crect x='220' y='484' width='480' height='18' rx='9' fill='%23fca5a5'/%3E%3Crect x='220' y='536' width='760' height='18' rx='9' fill='%2374c69d'/%3E%3C/svg%3E",
+ },
+];
+
+function Section({
+ eyebrow,
+ title,
+ description,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ description?: 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>
+ <div className="mt-1 flex flex-wrap items-end justify-between gap-3">
+ <div>
+ <h2 className="text-xl font-semibold">{title}</h2>
+ {description ? (
+ <p className="mt-2 max-w-3xl text-sm leading-6 text-muted-foreground">{description}</p>
+ ) : null}
+ </div>
+ </div>
+ </div>
+ <div className="p-5">{children}</div>
+ </section>
+ );
+}
+
+function StoryShell({ children }: { children: ReactNode }) {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">{children}</main>
+ </div>
+ );
+}
+
+function DialogBackdropFrame({
+ eyebrow,
+ title,
+ description,
+ badges,
+}: {
+ eyebrow: string;
+ title: string;
+ description: string;
+ badges: string[];
+}) {
+ return (
+ <StoryShell>
+ <Section eyebrow={eyebrow} title={title} description={description}>
+ <div className="grid gap-4 md:grid-cols-[minmax(0,1fr)_260px]">
+ <div className="space-y-3">
+ <div className="h-3 w-36 rounded-full bg-muted" />
+ <div className="h-24 rounded-lg border border-dashed border-border bg-muted/30" />
+ <div className="grid gap-3 sm:grid-cols-3">
+ <div className="h-16 rounded-lg border border-border bg-background/70" />
+ <div className="h-16 rounded-lg border border-border bg-background/70" />
+ <div className="h-16 rounded-lg border border-border bg-background/70" />
+ </div>
+ </div>
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 text-sm font-medium">Story state</div>
+ <div className="flex flex-wrap gap-2">
+ {badges.map((badge) => (
+ <Badge key={badge} variant="outline">
+ {badge}
+ </Badge>
+ ))}
+ </div>
+ </div>
+ </div>
+ </Section>
+ </StoryShell>
+ );
+}
+
+function hydrateDialogQueries(queryClient: ReturnType<typeof useQueryClient>) {
+ queryClient.setQueryData(queryKeys.companies.all, storybookCompanies);
+ queryClient.setQueryData(queryKeys.auth.session, storybookAuthSession);
+ queryClient.setQueryData(queryKeys.agents.list(COMPANY_ID), storybookAgents);
+ queryClient.setQueryData(queryKeys.projects.list(COMPANY_ID), storybookProjects);
+ queryClient.setQueryData(queryKeys.goals.list(COMPANY_ID), storybookGoals);
+ queryClient.setQueryData(queryKeys.issues.list(COMPANY_ID), storybookIssues);
+ queryClient.setQueryData(queryKeys.issues.labels(COMPANY_ID), storybookIssueLabels);
+ queryClient.setQueryData(queryKeys.issues.documents("issue-storybook-1"), storybookIssueDocuments);
+ queryClient.setQueryData(queryKeys.issues.documentRevisions("issue-storybook-1", "plan"), documentRevisions);
+ queryClient.setQueryData(queryKeys.executionWorkspaces.closeReadiness("execution-workspace-storybook"), closeReadinessReady);
+ queryClient.setQueryData(queryKeys.executionWorkspaces.closeReadiness("execution-workspace-blocked"), closeReadinessBlocked);
+ queryClient.setQueryData(
+ queryKeys.executionWorkspaces.list(COMPANY_ID, {
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-board-ui",
+ reuseEligible: true,
+ }),
+ storybookExecutionWorkspaces,
+ );
+ queryClient.setQueryData(queryKeys.instance.experimentalSettings, {
+ enableIsolatedWorkspaces: true,
+ enableRoutineTriggers: true,
+ });
+ queryClient.setQueryData(queryKeys.access.companyUserDirectory(COMPANY_ID), {
+ users: [
+ {
+ principalId: "user-board",
+ status: "active",
+ user: {
+ id: "user-board",
+ email: "[email protected]",
+ name: "Riley Board",
+ image: null,
+ },
+ },
+ ],
+ });
+ queryClient.setQueryData(
+ queryKeys.sidebarPreferences.projectOrder(COMPANY_ID, storybookAuthSession.user.id),
+ { orderedIds: storybookProjects.map((project) => project.id), updatedAt: null },
+ );
+ queryClient.setQueryData(queryKeys.adapters.all, [
+ {
+ type: "codex_local",
+ label: "Codex local",
+ source: "builtin",
+ modelsCount: 5,
+ loaded: true,
+ disabled: false,
+ capabilities: {
+ supportsInstructionsBundle: true,
+ supportsSkills: true,
+ supportsLocalAgentJwt: true,
+ requiresMaterializedRuntimeSkills: false,
+ },
+ },
+ {
+ type: "claude_local",
+ label: "Claude local",
+ source: "builtin",
+ modelsCount: 4,
+ loaded: true,
+ disabled: false,
+ capabilities: {
+ supportsInstructionsBundle: true,
+ supportsSkills: true,
+ supportsLocalAgentJwt: true,
+ requiresMaterializedRuntimeSkills: false,
+ },
+ },
+ ]);
+ queryClient.setQueryData(queryKeys.agents.adapterModels(COMPANY_ID, "codex_local"), [
+ { id: "gpt-5.4", label: "GPT-5.4" },
+ { id: "gpt-5.4-mini", label: "GPT-5.4 Mini" },
+ ]);
+}
+
+function StorybookDialogFixtures({ children }: { children: ReactNode }) {
+ const queryClient = useQueryClient();
+ const [ready] = useState(() => {
+ if (typeof window !== "undefined") {
+ window.localStorage.setItem(SELECTED_COMPANY_STORAGE_KEY, COMPANY_ID);
+ window.localStorage.removeItem(ISSUE_DRAFT_STORAGE_KEY);
+ }
+ hydrateDialogQueries(queryClient);
+ return true;
+ });
+
+ return ready ? children : null;
+}
+
+function useIssueCreateErrorMock(enabled: boolean) {
+ useLayoutEffect(() => {
+ if (!enabled || typeof window === "undefined") return undefined;
+
+ const originalFetch = window.fetch.bind(window);
+ window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+ const rawUrl =
+ typeof input === "string"
+ ? input
+ : input instanceof URL
+ ? input.href
+ : input.url;
+ const url = new URL(rawUrl, window.location.origin);
+ if (url.pathname === `/api/companies/${COMPANY_ID}/issues` && init?.method === "POST") {
+ return Response.json(
+ { error: "Validation failed: add a reviewer before creating governed release work." },
+ { status: 422 },
+ );
+ }
+ return originalFetch(input, init);
+ };
+
+ return () => {
+ window.fetch = originalFetch;
+ };
+ }, [enabled]);
+}
+
+function setFieldValue(element: HTMLInputElement | HTMLTextAreaElement, value: string) {
+ const prototype = Object.getPrototypeOf(element) as HTMLInputElement | HTMLTextAreaElement;
+ const valueSetter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+ valueSetter?.call(element, value);
+ element.dispatchEvent(new Event("input", { bubbles: true }));
+ element.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+function fillFirstField(selector: string, value: string) {
+ const element = document.querySelector<HTMLInputElement | HTMLTextAreaElement>(selector);
+ if (!element) return false;
+ setFieldValue(element, value);
+ return true;
+}
+
+function clickButtonByText(text: string) {
+ const buttons = Array.from(document.querySelectorAll<HTMLButtonElement>("button"));
+ const button = buttons.find((candidate) => candidate.textContent?.trim().includes(text));
+ button?.click();
+}
+
+function useOpenWhenCompanyReady(open: () => void) {
+ const { selectedCompanyId, setSelectedCompanyId } = useCompany();
+ const didOpenRef = useRef(false);
+
+ useLayoutEffect(() => {
+ if (selectedCompanyId !== COMPANY_ID) {
+ setSelectedCompanyId(COMPANY_ID);
+ return;
+ }
+ if (didOpenRef.current) return;
+ didOpenRef.current = true;
+ open();
+ }, [open, selectedCompanyId, setSelectedCompanyId]);
+}
+
+function IssueDialogOpener({
+ variant,
+}: {
+ variant: "empty" | "prefilled" | "validation";
+}) {
+ const { openNewIssue } = useDialog();
+ useIssueCreateErrorMock(variant === "validation");
+
+ useOpenWhenCompanyReady(() => {
+ openNewIssue(
+ variant === "empty"
+ ? {}
+ : {
+ title: variant === "validation" ? "Ship guarded release checklist" : "Create dialog Storybook coverage",
+ description: [
+ "Cover modal flows with fixture-backed states.",
+ "",
+ "- Keep dialogs open by default",
+ "- Show project workspace selection",
+ "- Include reviewer and approver context",
+ ].join("\n"),
+ status: "todo",
+ priority: "high",
+ projectId: "project-board-ui",
+ projectWorkspaceId: "workspace-board-ui",
+ assigneeAgentId: "agent-codex",
+ executionWorkspaceMode: "isolated_workspace",
+ },
+ );
+ });
+
+ useEffect(() => {
+ if (variant !== "validation") return undefined;
+ const timer = window.setTimeout(() => {
+ clickButtonByText("Create Issue");
+ }, 500);
+ return () => window.clearTimeout(timer);
+ }, [variant]);
+
+ return <NewIssueDialog />;
+}
+
+function AgentDialogOpener({ advanced }: { advanced?: boolean }) {
+ const { openNewAgent } = useDialog();
+
+ useOpenWhenCompanyReady(() => {
+ openNewAgent();
+ });
+
+ useEffect(() => {
+ if (!advanced) return undefined;
+ const timer = window.setTimeout(() => {
+ clickButtonByText("advanced configuration");
+ }, 250);
+ return () => window.clearTimeout(timer);
+ }, [advanced]);
+
+ return <NewAgentDialog />;
+}
+
+function GoalDialogOpener({ populated }: { populated?: boolean }) {
+ const { openNewGoal } = useDialog();
+
+ useOpenWhenCompanyReady(() => {
+ openNewGoal(populated ? { parentId: "goal-company" } : {});
+ });
+
+ useEffect(() => {
+ if (!populated) return undefined;
+ const timer = window.setTimeout(() => {
+ fillFirstField("input[placeholder='Goal title']", "Add modal review coverage");
+ }, 250);
+ return () => window.clearTimeout(timer);
+ }, [populated]);
+
+ return <NewGoalDialog />;
+}
+
+function ProjectDialogOpener({ populated }: { populated?: boolean }) {
+ const { openNewProject } = useDialog();
+
+ useOpenWhenCompanyReady(() => {
+ openNewProject();
+ });
+
+ useEffect(() => {
+ if (!populated) return undefined;
+ const timer = window.setTimeout(() => {
+ fillFirstField("input[placeholder='Project name']", "Storybook review workspace");
+ fillFirstField("input[placeholder='https://github.com/org/repo']", "https://github.com/paperclipai/paperclip");
+ fillFirstField("input[placeholder='/absolute/path/to/workspace']", "/Users/dotta/paperclip/ui");
+ fillFirstField("input[type='date']", "2026-04-30");
+ }, 250);
+ return () => window.clearTimeout(timer);
+ }, [populated]);
+
+ return <NewProjectDialog />;
+}
+
+function DialogStory({
+ eyebrow,
+ title,
+ description,
+ badges,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ description: string;
+ badges: string[];
+ children: ReactNode;
+}) {
+ return (
+ <StorybookDialogFixtures>
+ <DialogBackdropFrame eyebrow={eyebrow} title={title} description={description} badges={badges} />
+ {children}
+ </StorybookDialogFixtures>
+ );
+}
+
+function ExecutionWorkspaceDialogStory({ blocked }: { blocked?: boolean }) {
+ const workspace = storybookExecutionWorkspaces[0]!;
+ return (
+ <DialogStory
+ eyebrow="ExecutionWorkspaceCloseDialog"
+ title={blocked ? "Blocked workspace close confirmation" : "Workspace close confirmation"}
+ description="The close dialog exposes linked issues, git state, runtime services, and planned cleanup actions before archiving an execution workspace."
+ badges={blocked ? ["blocked", "dirty worktree", "linked issue"] : ["ready with warnings", "cleanup actions"]}
+ >
+ <ExecutionWorkspaceCloseDialog
+ workspaceId={blocked ? "execution-workspace-blocked" : workspace.id}
+ workspaceName={blocked ? "PAP-1670 publish preview worktree" : workspace.name}
+ currentStatus={workspace.status}
+ open
+ onOpenChange={() => undefined}
+ />
+ </DialogStory>
+ );
+}
+
+function DocumentDiffModalStory() {
+ return (
+ <DialogStory
+ eyebrow="DocumentDiffModal"
+ title="Revision diff view"
+ description="The diff modal compares document revisions with selectable old and new snapshots."
+ badges={["revision selector", "line diff", "document history"]}
+ >
+ <DocumentDiffModal
+ issueId="issue-storybook-1"
+ documentKey="plan"
+ latestRevisionNumber={3}
+ open
+ onOpenChange={() => undefined}
+ />
+ </DialogStory>
+ );
+}
+
+function ImageGalleryModalStory() {
+ return (
+ <DialogStory
+ eyebrow="ImageGalleryModal"
+ title="Attachment gallery"
+ description="The image gallery opens full-screen with attachment metadata, download action, and previous/next navigation."
+ badges={["full-screen", "navigation", "visual attachment"]}
+ >
+ <ImageGalleryModal images={galleryImages} initialIndex={0} open onOpenChange={() => undefined} />
+ </DialogStory>
+ );
+}
+
+function PathInstructionsModalStory() {
+ return (
+ <DialogStory
+ eyebrow="PathInstructionsModal"
+ title="Absolute path instructions"
+ description="The path helper opens directly to platform-specific steps for copying a full local workspace path."
+ badges={["macOS", "Windows", "Linux"]}
+ >
+ <PathInstructionsModal open onOpenChange={() => undefined} />
+ </DialogStory>
+ );
+}
+
+const meta = {
+ title: "Product/Dialogs & Modals",
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Open-state stories for Paperclip creation dialogs, workspace confirmations, document diffing, image attachments, and path helper modals.",
+ },
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const NewIssueEmpty: Story = {
+ name: "New Issue - Empty",
+ render: () => (
+ <DialogStory
+ eyebrow="NewIssueDialog"
+ title="Empty issue form"
+ description="Default issue creation state with no assignee, project, priority, or workspace selected."
+ badges={["empty", "creation", "draft"]}
+ >
+ <IssueDialogOpener variant="empty" />
+ </DialogStory>
+ ),
+};
+
+export const NewIssuePrefilled: Story = {
+ name: "New Issue - Prefilled",
+ render: () => (
+ <DialogStory
+ eyebrow="NewIssueDialog"
+ title="Prefilled issue form"
+ description="Populated issue creation state with project context, assignee, priority, description, and isolated workspace selection."
+ badges={["populated", "assignee", "workspace"]}
+ >
+ <IssueDialogOpener variant="prefilled" />
+ </DialogStory>
+ ),
+};
+
+export const NewIssueValidationError: Story = {
+ name: "New Issue - Validation Error",
+ render: () => (
+ <DialogStory
+ eyebrow="NewIssueDialog"
+ title="Validation error after submit"
+ description="The submit path is mocked to return a 422 so the footer error state remains visible for review."
+ badges={["validation", "422", "error"]}
+ >
+ <IssueDialogOpener variant="validation" />
+ </DialogStory>
+ ),
+};
+
+export const NewAgentRecommendation: Story = {
+ name: "New Agent - Recommendation",
+ render: () => (
+ <DialogStory
+ eyebrow="NewAgentDialog"
+ title="Recommended CEO-assisted setup"
+ description="Initial agent creation wizard state that routes operators toward CEO-owned agent setup."
+ badges={["empty", "wizard", "CEO handoff"]}
+ >
+ <AgentDialogOpener />
+ </DialogStory>
+ ),
+};
+
+export const NewAgentAdapterSelection: Story = {
+ name: "New Agent - Adapter Selection",
+ render: () => (
+ <DialogStory
+ eyebrow="NewAgentDialog"
+ title="Advanced adapter selection"
+ description="Advanced branch of the agent creation wizard showing registered adapter choices and recommended states."
+ badges={["populated", "adapters", "advanced"]}
+ >
+ <AgentDialogOpener advanced />
+ </DialogStory>
+ ),
+};
+
+export const NewGoalEmpty: Story = {
+ name: "New Goal - Empty",
+ render: () => (
+ <DialogStory
+ eyebrow="NewGoalDialog"
+ title="Empty goal form"
+ description="Default goal creation state with status, level, and parent-goal controls available."
+ badges={["empty", "goal", "parent picker"]}
+ >
+ <GoalDialogOpener />
+ </DialogStory>
+ ),
+};
+
+export const NewGoalWithParent: Story = {
+ name: "New Goal - Parent Selected",
+ render: () => (
+ <DialogStory
+ eyebrow="NewGoalDialog"
+ title="Goal creation with parent context"
+ description="Populated goal creation state with a seeded title and company-level parent goal selected."
+ badges={["populated", "sub-goal", "parent selected"]}
+ >
+ <GoalDialogOpener populated />
+ </DialogStory>
+ ),
+};
+
+export const NewProjectEmpty: Story = {
+ name: "New Project - Empty",
+ render: () => (
+ <DialogStory
+ eyebrow="NewProjectDialog"
+ title="Empty project form"
+ description="Default project creation state with description, goal, target date, and workspace fields empty."
+ badges={["empty", "project", "workspace"]}
+ >
+ <ProjectDialogOpener />
+ </DialogStory>
+ ),
+};
+
+export const NewProjectWorkspaceConfig: Story = {
+ name: "New Project - Workspace Config",
+ render: () => (
+ <DialogStory
+ eyebrow="NewProjectDialog"
+ title="Project creation with workspace config"
+ description="Populated project creation state with repo URL, local folder path, and target date filled in."
+ badges={["populated", "repo URL", "local path"]}
+ >
+ <ProjectDialogOpener populated />
+ </DialogStory>
+ ),
+};
+
+export const ExecutionWorkspaceCloseReady: Story = {
+ name: "Execution Workspace Close - Ready",
+ render: () => <ExecutionWorkspaceDialogStory />,
+};
+
+export const ExecutionWorkspaceCloseBlocked: Story = {
+ name: "Execution Workspace Close - Blocked",
+ render: () => <ExecutionWorkspaceDialogStory blocked />,
+};
+
+export const DocumentDiffOpen: Story = {
+ name: "Document Diff",
+ render: () => <DocumentDiffModalStory />,
+};
+
+export const ImageGalleryOpen: Story = {
+ name: "Image Gallery",
+ render: () => <ImageGalleryModalStory />,
+};
+
+export const PathInstructionsOpen: Story = {
+ name: "Path Instructions",
+ render: () => <PathInstructionsModalStory />,
+};
diff --git a/ui/storybook/stories/forms-editors.stories.tsx b/ui/storybook/stories/forms-editors.stories.tsx
new file mode 100644
index 0000000000..b73a276901
--- /dev/null
+++ b/ui/storybook/stories/forms-editors.stories.tsx
@@ -0,0 +1,712 @@
+import { useMemo, useState, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Agent, CompanySecret, EnvBinding, Project, RoutineVariable } from "@paperclipai/shared";
+import { Code2, FileText, ListPlus, RotateCcw, Table2 } from "lucide-react";
+import { EnvVarEditor } from "@/components/EnvVarEditor";
+import { ExecutionParticipantPicker } from "@/components/ExecutionParticipantPicker";
+import { InlineEditor } from "@/components/InlineEditor";
+import { InlineEntitySelector, type InlineEntityOption } from "@/components/InlineEntitySelector";
+import { JsonSchemaForm, type JsonSchemaNode, getDefaultValues } from "@/components/JsonSchemaForm";
+import { MarkdownBody } from "@/components/MarkdownBody";
+import { MarkdownEditor, type MentionOption } from "@/components/MarkdownEditor";
+import { ReportsToPicker } from "@/components/ReportsToPicker";
+import {
+ RoutineRunVariablesDialog,
+ type RoutineRunDialogSubmitData,
+} from "@/components/RoutineRunVariablesDialog";
+import { RoutineVariablesEditor, RoutineVariablesHint } from "@/components/RoutineVariablesEditor";
+import { ScheduleEditor, describeSchedule } from "@/components/ScheduleEditor";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { buildExecutionPolicy } from "@/lib/issue-execution-policy";
+import { createIssue, storybookAgents } from "../fixtures/paperclipData";
+
+function Section({
+ eyebrow,
+ title,
+ description,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ description?: 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>
+ <div className="mt-1 flex flex-wrap items-end justify-between gap-3">
+ <div>
+ <h2 className="text-xl font-semibold">{title}</h2>
+ {description ? (
+ <p className="mt-2 max-w-3xl text-sm leading-6 text-muted-foreground">{description}</p>
+ ) : null}
+ </div>
+ </div>
+ </div>
+ <div className="p-5">{children}</div>
+ </section>
+ );
+}
+
+function StatePanel({
+ label,
+ detail,
+ children,
+ disabled = false,
+}: {
+ label: string;
+ detail?: string;
+ children: ReactNode;
+ disabled?: boolean;
+}) {
+ return (
+ <div className="min-w-0 rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 flex min-h-6 flex-wrap items-start justify-between gap-2">
+ <div>
+ <div className="text-sm font-medium">{label}</div>
+ {detail ? <div className="mt-1 text-xs leading-5 text-muted-foreground">{detail}</div> : null}
+ </div>
+ {disabled ? <Badge variant="outline">disabled</Badge> : null}
+ </div>
+ <div className={disabled ? "pointer-events-none opacity-55" : undefined}>{children}</div>
+ </div>
+ );
+}
+
+function StoryShell({ children }: { children: ReactNode }) {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">{children}</main>
+ </div>
+ );
+}
+
+const reviewMarkdown = `# Release review
+
+Ship criteria for the board UI refresh:
+
+- [x] Preserve company-scoped routes
+- [x] Keep comments and task updates auditable
+- [ ] Attach screenshots after QA
+
+| Surface | Owner | State |
+| --- | --- | --- |
+| Issues | CodexCoder | In progress |
+| Approvals | CTO | Ready |
+
+\`\`\`ts
+const shouldRun = issue.status === "in_progress" && issue.companyId === company.id;
+\`\`\`
+
+See [the implementation notes](https://github.com/paperclipai/paperclip).`;
+
+const editorMentions: MentionOption[] = [
+ { id: "agent-codex", name: "CodexCoder", kind: "agent", agentId: "agent-codex", agentIcon: "code" },
+ { id: "agent-qa", name: "QAChecker", kind: "agent", agentId: "agent-qa", agentIcon: "shield" },
+ { id: "project-board-ui", name: "Board UI", kind: "project", projectId: "project-board-ui", projectColor: "#0f766e" },
+ { id: "user-board", name: "Board Operator", kind: "user", userId: "user-board" },
+];
+
+const adapterSchema: JsonSchemaNode = {
+ type: "object",
+ required: ["adapterName", "apiKey", "concurrency"],
+ properties: {
+ adapterName: {
+ type: "string",
+ title: "Adapter name",
+ description: "Human-readable name shown in the adapter manager.",
+ minLength: 3,
+ default: "Codex local",
+ },
+ mode: {
+ type: "string",
+ title: "Run mode",
+ enum: ["review", "implementation", "maintenance"],
+ default: "implementation",
+ },
+ apiKey: {
+ type: "string",
+ title: "API key",
+ format: "secret-ref",
+ description: "Stored with the active Paperclip secret provider.",
+ },
+ concurrency: {
+ type: "integer",
+ title: "Max concurrent runs",
+ minimum: 1,
+ maximum: 6,
+ default: 2,
+ },
+ dryRun: {
+ type: "boolean",
+ title: "Dry run first",
+ description: "Require a preview run before mutating company data.",
+ default: true,
+ },
+ notes: {
+ type: "string",
+ title: "Operator notes",
+ format: "textarea",
+ maxLength: 500,
+ description: "Shown to the agent before checkout.",
+ },
+ allowedCommands: {
+ type: "array",
+ title: "Allowed commands",
+ description: "Commands this adapter can run without extra approval.",
+ items: { type: "string", default: "pnpm test" },
+ minItems: 1,
+ },
+ advanced: {
+ type: "object",
+ title: "Advanced guardrails",
+ properties: {
+ timeoutSeconds: { type: "integer", title: "Timeout seconds", minimum: 60, default: 900 },
+ requireApproval: { type: "boolean", title: "Require board approval", default: false },
+ },
+ },
+ },
+};
+
+const validAdapterValues = {
+ ...getDefaultValues(adapterSchema),
+ adapterName: "Codex local",
+ mode: "implementation",
+ apiKey: "secret:openai-api-key",
+ concurrency: 2,
+ dryRun: true,
+ notes: "Use the project worktree and post a concise task update before handoff.",
+ allowedCommands: ["pnpm --filter @paperclipai/ui typecheck", "pnpm build-storybook"],
+ advanced: { timeoutSeconds: 900, requireApproval: false },
+};
+
+const invalidAdapterValues = {
+ ...validAdapterValues,
+ adapterName: "AI",
+ apiKey: "",
+ concurrency: 9,
+};
+
+const adapterErrors = {
+ "/adapterName": "Must be at least 3 characters",
+ "/apiKey": "This field is required",
+ "/concurrency": "Must be at most 6",
+};
+
+const storybookSecrets: CompanySecret[] = [
+ {
+ id: "secret-openai",
+ companyId: "company-storybook",
+ name: "OPENAI_API_KEY",
+ provider: "local_encrypted",
+ externalRef: null,
+ latestVersion: 3,
+ description: null,
+ createdByAgentId: null,
+ createdByUserId: "user-board",
+ createdAt: new Date("2026-04-18T10:00:00.000Z"),
+ updatedAt: new Date("2026-04-20T10:00:00.000Z"),
+ },
+ {
+ id: "secret-github",
+ companyId: "company-storybook",
+ name: "GITHUB_TOKEN",
+ provider: "local_encrypted",
+ externalRef: null,
+ latestVersion: 1,
+ description: null,
+ createdByAgentId: null,
+ createdByUserId: "user-board",
+ createdAt: new Date("2026-04-19T10:00:00.000Z"),
+ updatedAt: new Date("2026-04-19T10:00:00.000Z"),
+ },
+];
+
+const filledEnv: Record<string, EnvBinding> = {
+ NODE_ENV: { type: "plain", value: "development" },
+ OPENAI_API_KEY: { type: "secret_ref", secretId: "secret-openai", version: "latest" },
+};
+
+const routineVariables: RoutineVariable[] = [
+ {
+ name: "repo",
+ label: "Repository",
+ type: "text",
+ defaultValue: "paperclipai/paperclip",
+ required: true,
+ options: [],
+ },
+ {
+ name: "priority",
+ label: "Priority",
+ type: "select",
+ defaultValue: "medium",
+ required: true,
+ options: ["low", "medium", "high"],
+ },
+ {
+ name: "include_browser",
+ label: "Include browser QA",
+ type: "boolean",
+ defaultValue: true,
+ required: false,
+ options: [],
+ },
+ {
+ name: "notes",
+ label: "Run notes",
+ type: "textarea",
+ defaultValue: "Capture any visible layout regressions.",
+ required: false,
+ options: [],
+ },
+];
+
+const storybookProject: Project = {
+ id: "project-board-ui",
+ companyId: "company-storybook",
+ urlKey: "board-ui",
+ goalId: "goal-company",
+ goalIds: ["goal-company"],
+ goals: [{ id: "goal-company", title: "We're building Paperclip" }],
+ name: "Board UI",
+ description: "Control-plane interface, Storybook review surfaces, and operator workflows.",
+ status: "in_progress",
+ leadAgentId: "agent-codex",
+ targetDate: null,
+ color: "#0f766e",
+ env: null,
+ pauseReason: null,
+ pausedAt: null,
+ executionWorkspacePolicy: null,
+ codebase: {
+ workspaceId: "workspace-board-ui",
+ repoUrl: "https://github.com/paperclipai/paperclip",
+ repoRef: "master",
+ defaultRef: "master",
+ repoName: "paperclip",
+ localFolder: "/Users/dotta/paperclip",
+ managedFolder: "paperclip",
+ effectiveLocalFolder: "/Users/dotta/paperclip",
+ origin: "local_folder",
+ },
+ workspaces: [],
+ primaryWorkspace: null,
+ archivedAt: null,
+ createdAt: new Date("2026-04-01T10:00:00.000Z"),
+ updatedAt: new Date("2026-04-20T10:00:00.000Z"),
+};
+
+const entityOptions: InlineEntityOption[] = [
+ { id: "issue-1672", label: "Storybook forms and editors", searchText: "PAP-1672 ui story coverage" },
+ { id: "project-board-ui", label: "Board UI", searchText: "project frontend Storybook" },
+ { id: "agent-codex", label: "CodexCoder", searchText: "engineer implementation" },
+];
+
+function MarkdownEditorGallery() {
+ const [emptyMarkdown, setEmptyMarkdown] = useState("");
+ const [filledMarkdown, setFilledMarkdown] = useState(reviewMarkdown);
+ const [actionMarkdown, setActionMarkdown] = useState("Draft an update for @CodexCoder and /check-pr.");
+
+ return (
+ <Section
+ eyebrow="MarkdownEditor"
+ title="Composer states with content, read-only mode, and action buttons"
+ description="The editor is controlled in all examples so reviewers can type, trigger mentions, and see command insertion behavior."
+ >
+ <div className="grid gap-4 lg:grid-cols-2">
+ <StatePanel label="Empty" detail="Placeholder, border, and mention-ready empty state.">
+ <MarkdownEditor
+ value={emptyMarkdown}
+ onChange={setEmptyMarkdown}
+ placeholder="Write a task update..."
+ mentions={editorMentions}
+ />
+ </StatePanel>
+ <StatePanel label="Filled" detail="Long-form markdown with a table and fenced code block.">
+ <MarkdownEditor value={filledMarkdown} onChange={setFilledMarkdown} mentions={editorMentions} />
+ </StatePanel>
+ <StatePanel label="Read-only" detail="Uses the editor rendering path without accepting edits." disabled>
+ <MarkdownEditor value={reviewMarkdown} onChange={() => undefined} readOnly mentions={editorMentions} />
+ </StatePanel>
+ <StatePanel label="Toolbar actions" detail="External controls exercise insertion actions around the editor.">
+ <div className="mb-3 flex flex-wrap gap-2">
+ <Button size="sm" variant="outline" onClick={() => setActionMarkdown((value) => `${value}\n\n## Next action\n`)}>
+ <FileText className="mr-2 h-4 w-4" />
+ Heading
+ </Button>
+ <Button size="sm" variant="outline" onClick={() => setActionMarkdown((value) => `${value}\n\n- Verify typecheck\n- Build Storybook\n`)}>
+ <ListPlus className="mr-2 h-4 w-4" />
+ List
+ </Button>
+ <Button size="sm" variant="outline" onClick={() => setActionMarkdown((value) => `${value}\n\n| Field | State |\n| --- | --- |\n| Forms | Ready |\n`)}>
+ <Table2 className="mr-2 h-4 w-4" />
+ Table
+ </Button>
+ <Button size="sm" variant="outline" onClick={() => setActionMarkdown((value) => `${value}\n\n\`\`\`sh\npnpm build-storybook\n\`\`\`\n`)}>
+ <Code2 className="mr-2 h-4 w-4" />
+ Code
+ </Button>
+ <Button size="sm" variant="ghost" onClick={() => setActionMarkdown("Draft an update for @CodexCoder and /check-pr.")}>
+ <RotateCcw className="mr-2 h-4 w-4" />
+ Reset
+ </Button>
+ </div>
+ <MarkdownEditor value={actionMarkdown} onChange={setActionMarkdown} mentions={editorMentions} />
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function MarkdownBodyGallery() {
+ return (
+ <Section
+ eyebrow="MarkdownBody"
+ title="Rendered markdown for task documents and comments"
+ description="GFM coverage includes headings, task lists, links, tables, and code blocks in the app's prose wrapper."
+ >
+ <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_320px]">
+ <StatePanel label="Filled markdown" detail="Mixed document syntax with code and table overflow handling.">
+ <MarkdownBody linkIssueReferences={false}>{reviewMarkdown}</MarkdownBody>
+ </StatePanel>
+ <div className="space-y-4">
+ <StatePanel label="Empty">
+ <MarkdownBody>{""}</MarkdownBody>
+ <p className="text-sm text-muted-foreground">No markdown body content.</p>
+ </StatePanel>
+ <StatePanel label="Disabled container" disabled>
+ <MarkdownBody linkIssueReferences={false}>A read-only preview can be dimmed by the parent surface.</MarkdownBody>
+ </StatePanel>
+ </div>
+ </div>
+ </Section>
+ );
+}
+
+function JsonSchemaFormGallery() {
+ const [filledValues, setFilledValues] = useState<Record<string, unknown>>(validAdapterValues);
+ const [errorValues, setErrorValues] = useState<Record<string, unknown>>(invalidAdapterValues);
+
+ return (
+ <Section
+ eyebrow="JsonSchemaForm"
+ title="Generated adapter configuration forms"
+ description="The schema exercises strings, enums, secrets, numbers, booleans, arrays, objects, validation errors, and disabled controls."
+ >
+ <div className="grid gap-4 xl:grid-cols-2">
+ <StatePanel label="Filled">
+ <JsonSchemaForm schema={adapterSchema} values={filledValues} onChange={setFilledValues} />
+ </StatePanel>
+ <StatePanel label="Validation errors">
+ <JsonSchemaForm schema={adapterSchema} values={errorValues} onChange={setErrorValues} errors={adapterErrors} />
+ </StatePanel>
+ <StatePanel label="Empty schema">
+ <JsonSchemaForm schema={{ type: "object", properties: {} }} values={{}} onChange={() => undefined} />
+ </StatePanel>
+ <StatePanel label="Disabled" disabled>
+ <JsonSchemaForm schema={adapterSchema} values={filledValues} onChange={() => undefined} disabled />
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function InlineEditorGallery() {
+ const [title, setTitle] = useState("Storybook: Forms & Editors stories");
+ const [description, setDescription] = useState(
+ "Create fixture-backed editor stories for the board UI, then verify Storybook builds.",
+ );
+ const [emptyTitle, setEmptyTitle] = useState("");
+
+ return (
+ <Section eyebrow="InlineEditor" title="Inline title and description editing">
+ <div className="grid gap-4 lg:grid-cols-3">
+ <StatePanel label="Title editing" detail="Click the title to edit and press Enter to save.">
+ <InlineEditor value={title} onSave={setTitle} as="h2" className="text-2xl font-semibold" />
+ </StatePanel>
+ <StatePanel label="Description editing" detail="Multiline markdown editor with autosave affordance.">
+ <InlineEditor value={description} onSave={setDescription} as="p" multiline nullable />
+ </StatePanel>
+ <StatePanel label="Empty nullable title" detail="Placeholder state for optional inline fields.">
+ <InlineEditor value={emptyTitle} onSave={setEmptyTitle} as="h2" nullable placeholder="Untitled issue" />
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function EnvVarEditorGallery() {
+ const [emptyEnv, setEmptyEnv] = useState<Record<string, EnvBinding>>({});
+ const [env, setEnv] = useState<Record<string, EnvBinding>>(filledEnv);
+ const createSecret = async (name: string): Promise<CompanySecret> => ({
+ ...storybookSecrets[0]!,
+ id: `secret-${name.toLowerCase()}`,
+ name,
+ latestVersion: 1,
+ });
+
+ return (
+ <Section eyebrow="EnvVarEditor" title="Runtime environment bindings">
+ <div className="grid gap-4 lg:grid-cols-3">
+ <StatePanel label="Empty add row" detail="Trailing blank row is the add state.">
+ <EnvVarEditor value={emptyEnv} secrets={storybookSecrets} onCreateSecret={createSecret} onChange={(next) => setEmptyEnv(next ?? {})} />
+ </StatePanel>
+ <StatePanel label="Plain and secret values" detail="Filled rows show edit, seal, secret select, and remove controls.">
+ <EnvVarEditor value={env} secrets={storybookSecrets} onCreateSecret={createSecret} onChange={(next) => setEnv(next ?? {})} />
+ </StatePanel>
+ <StatePanel label="Disabled shell" disabled>
+ <EnvVarEditor value={filledEnv} secrets={storybookSecrets} onCreateSecret={createSecret} onChange={() => undefined} />
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function ScheduleEditorGallery() {
+ const [emptyCron, setEmptyCron] = useState("");
+ const [weeklyCron, setWeeklyCron] = useState("30 9 * * 1");
+ const [customCron, setCustomCron] = useState("15 16 1 * *");
+
+ return (
+ <Section eyebrow="ScheduleEditor" title="Cron picker with human-readable previews">
+ <div className="grid gap-4 lg:grid-cols-3">
+ <StatePanel label="Empty default" detail={describeSchedule(emptyCron)}>
+ <ScheduleEditor value={emptyCron} onChange={setEmptyCron} />
+ </StatePanel>
+ <StatePanel label="Weekly filled" detail={describeSchedule(weeklyCron)}>
+ <ScheduleEditor value={weeklyCron} onChange={setWeeklyCron} />
+ </StatePanel>
+ <StatePanel label="Custom disabled preview" detail={describeSchedule(customCron)} disabled>
+ <ScheduleEditor value={customCron} onChange={setCustomCron} />
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function RoutineVariablesGallery() {
+ const [variables, setVariables] = useState<RoutineVariable[]>(routineVariables);
+
+ return (
+ <Section
+ eyebrow="RoutineVariablesEditor"
+ title="Detected runtime variable definitions"
+ description="Variable rows are synced from title and instructions placeholders, then configured with types, defaults, required flags, and select options."
+ >
+ <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_320px]">
+ <StatePanel label="Detected variables">
+ <RoutineVariablesEditor
+ title="Review {{repo}} at {{priority}} priority"
+ description="Include browser QA: {{include_browser}}\n\nOperator notes: {{notes}}"
+ value={variables}
+ onChange={setVariables}
+ />
+ </StatePanel>
+ <div className="space-y-4">
+ <StatePanel label="Empty hint">
+ <RoutineVariablesHint />
+ </StatePanel>
+ <StatePanel label="Disabled shell" disabled>
+ <RoutineVariablesEditor
+ title="Review {{repo}}"
+ description="Use {{priority}} priority"
+ value={variables.slice(0, 2)}
+ onChange={() => undefined}
+ />
+ </StatePanel>
+ </div>
+ </div>
+ </Section>
+ );
+}
+
+function PickerGallery() {
+ const [issue, setIssue] = useState(() =>
+ createIssue({
+ executionPolicy: buildExecutionPolicy({
+ reviewerValues: ["agent:agent-qa"],
+ approverValues: ["user:user-board"],
+ }),
+ }),
+ );
+ const [manager, setManager] = useState<string | null>("agent-cto");
+ const [selectorValue, setSelectorValue] = useState("project-board-ui");
+ const agentsWithTerminated: Agent[] = useMemo(
+ () => [
+ ...storybookAgents,
+ {
+ ...storybookAgents[1]!,
+ id: "agent-legacy",
+ name: "LegacyReviewer",
+ status: "terminated",
+ reportsTo: null,
+ },
+ ],
+ [],
+ );
+
+ return (
+ <Section
+ eyebrow="Pickers"
+ title="Execution participants, reporting hierarchy, and inline entity selection"
+ description="Closed trigger states stay compact, while the dropdowns are interactive for search and selection review."
+ >
+ <div className="grid gap-4 xl:grid-cols-3">
+ <StatePanel label="ExecutionParticipantPicker" detail="Review and approval participants share the same policy object.">
+ <div className="flex flex-wrap gap-3">
+ <ExecutionParticipantPicker
+ issue={issue}
+ stageType="review"
+ agents={storybookAgents}
+ currentUserId="user-board"
+ onUpdate={(patch) => setIssue((current) => ({ ...current, ...patch }))}
+ />
+ <ExecutionParticipantPicker
+ issue={issue}
+ stageType="approval"
+ agents={storybookAgents}
+ currentUserId="user-board"
+ onUpdate={(patch) => setIssue((current) => ({ ...current, ...patch }))}
+ />
+ </div>
+ </StatePanel>
+ <StatePanel label="ReportsToPicker" detail="Selected manager, CEO disabled state, and filtered hierarchy choices.">
+ <div className="flex flex-wrap gap-3">
+ <ReportsToPicker agents={agentsWithTerminated} value={manager} onChange={setManager} excludeAgentIds={["agent-codex"]} />
+ <ReportsToPicker agents={agentsWithTerminated} value={null} onChange={() => undefined} disabled />
+ </div>
+ </StatePanel>
+ <StatePanel label="InlineEntitySelector" detail="Search/select dropdown for issue, project, and agent entities.">
+ <div className="flex flex-wrap gap-3">
+ <InlineEntitySelector
+ value={selectorValue}
+ options={entityOptions}
+ recentOptionIds={["issue-1672"]}
+ placeholder="Entity"
+ noneLabel="No entity"
+ searchPlaceholder="Search entities..."
+ emptyMessage="No matching entity."
+ onChange={setSelectorValue}
+ />
+ <div className="pointer-events-none opacity-55">
+ <InlineEntitySelector
+ value=""
+ options={entityOptions}
+ placeholder="Entity"
+ noneLabel="No entity"
+ searchPlaceholder="Search entities..."
+ emptyMessage="No matching entity."
+ onChange={() => undefined}
+ />
+ </div>
+ </div>
+ </StatePanel>
+ </div>
+ </Section>
+ );
+}
+
+function FormsEditorsShowcase() {
+ return (
+ <StoryShell>
+ <section className="paperclip-story__frame p-6">
+ <div className="flex flex-wrap items-start justify-between gap-5">
+ <div>
+ <div className="paperclip-story__label">Forms and editors</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Paperclip form controls under realistic state</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Dense control-plane forms need to hold empty, filled, validation, and disabled states without losing scan
+ speed. These fixtures keep the components reviewable outside production routes.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">empty</Badge>
+ <Badge variant="outline">filled</Badge>
+ <Badge variant="outline">validation</Badge>
+ <Badge variant="outline">disabled</Badge>
+ </div>
+ </div>
+ </section>
+
+ <MarkdownEditorGallery />
+ <MarkdownBodyGallery />
+ <JsonSchemaFormGallery />
+ <InlineEditorGallery />
+ <EnvVarEditorGallery />
+ <ScheduleEditorGallery />
+ <RoutineVariablesGallery />
+ <PickerGallery />
+ </StoryShell>
+ );
+}
+
+function RoutineRunDialogStory() {
+ const [open, setOpen] = useState(true);
+ const [submitted, setSubmitted] = useState<RoutineRunDialogSubmitData | null>(null);
+
+ return (
+ <StoryShell>
+ <Section
+ eyebrow="RoutineRunVariablesDialog"
+ title="Manual routine run configuration"
+ description="The dialog collects runtime variables, the target assignee, and optional project context before creating the run issue."
+ >
+ <div className="flex flex-wrap items-center gap-3">
+ <Button onClick={() => setOpen(true)}>Open run dialog</Button>
+ {submitted ? (
+ <pre className="max-w-full overflow-x-auto rounded-md border border-border bg-muted/40 px-3 py-2 text-xs">
+ {JSON.stringify(submitted, null, 2)}
+ </pre>
+ ) : (
+ <span className="text-sm text-muted-foreground">Submit the dialog to inspect the payload.</span>
+ )}
+ </div>
+ </Section>
+ <RoutineRunVariablesDialog
+ open={open}
+ onOpenChange={setOpen}
+ companyId="company-storybook"
+ routineName="Weekly release review"
+ projects={[storybookProject]}
+ agents={storybookAgents}
+ defaultProjectId="project-board-ui"
+ defaultAssigneeAgentId="agent-codex"
+ variables={routineVariables}
+ isPending={false}
+ onSubmit={(data) => {
+ setSubmitted({ ...data });
+ setOpen(false);
+ }}
+ />
+ </StoryShell>
+ );
+}
+
+const meta = {
+ title: "Components/Forms & Editors",
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Fixture-backed stories for Paperclip form controls, markdown editors, inline editors, schedule controls, runtime-variable dialogs, and selection pickers.",
+ },
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const AllFormsAndEditors: Story = {
+ name: "All Forms And Editors",
+ render: () => <FormsEditorsShowcase />,
+};
+
+export const RoutineRunVariablesDialogOpen: Story = {
+ name: "Routine Run Variables Dialog",
+ render: () => <RoutineRunDialogStory />,
+};
diff --git a/ui/storybook/stories/foundations.stories.tsx b/ui/storybook/stories/foundations.stories.tsx
new file mode 100644
index 0000000000..94c1a6874e
--- /dev/null
+++ b/ui/storybook/stories/foundations.stories.tsx
@@ -0,0 +1,300 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AlertTriangle, ArrowRight, Check, Copy, Play, Plus, Save, Search, Settings } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+ Card,
+ CardContent,
+ CardDescription,
+ CardFooter,
+ CardHeader,
+ CardTitle,
+} from "@/components/ui/card";
+import { Checkbox } from "@/components/ui/checkbox";
+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 { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+import { Separator } from "@/components/ui/separator";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Textarea } from "@/components/ui/textarea";
+import { ToggleSwitch } from "@/components/ui/toggle-switch";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+
+const buttonVariants = ["default", "secondary", "outline", "ghost", "destructive", "link"] as const;
+const buttonSizes = ["xs", "sm", "default", "lg", "icon", "icon-sm"] as const;
+const badgeVariants = ["default", "secondary", "outline", "destructive", "ghost", "link"] as const;
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.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 FoundationsMatrix() {
+ const [autoMode, setAutoMode] = useState(true);
+ const [boardApproval, setBoardApproval] = useState(true);
+
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">
+ <section className="paperclip-story__frame p-6">
+ <div className="paperclip-story__label">Foundations</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Primitives and interaction states</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ A dense pass over the base controls that Paperclip pages use for operational actions, filtering,
+ approvals, and settings.
+ </p>
+ </section>
+
+ <Section eyebrow="Actions" title="Button variants and sizes">
+ <div className="space-y-6">
+ <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
+ {buttonVariants.map((variant) => (
+ <div key={variant} className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 text-xs font-medium capitalize text-muted-foreground">{variant}</div>
+ <div className="flex flex-wrap items-center gap-2">
+ <Button variant={variant}>
+ <Play className="h-4 w-4" />
+ Invoke run
+ </Button>
+ <Button variant={variant} disabled>
+ Disabled
+ </Button>
+ </div>
+ </div>
+ ))}
+ </div>
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 text-xs font-medium text-muted-foreground">Sizes and icon-only actions</div>
+ <div className="flex flex-wrap items-center gap-2">
+ {buttonSizes.map((size) => (
+ <Button key={size} size={size} variant={size.startsWith("icon") ? "outline" : "secondary"}>
+ {size.startsWith("icon") ? <Settings /> : size}
+ </Button>
+ ))}
+ </div>
+ </div>
+ </div>
+ </Section>
+
+ <Section eyebrow="Status labels" title="Badges and compact metadata">
+ <div className="flex flex-wrap gap-2">
+ {badgeVariants.map((variant) => (
+ <Badge key={variant} variant={variant}>
+ {variant === "destructive" ? <AlertTriangle /> : variant === "default" ? <Check /> : null}
+ {variant}
+ </Badge>
+ ))}
+ <Badge variant="outline" className="font-mono">
+ PAP-1641
+ </Badge>
+ <Badge variant="secondary">
+ <ArrowRight />
+ in review
+ </Badge>
+ </div>
+ </Section>
+
+ <Section eyebrow="Inputs" title="Form controls with real Paperclip copy">
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_360px]">
+ <div className="space-y-4">
+ <div className="grid gap-2">
+ <Label htmlFor="story-title">Issue title</Label>
+ <Input id="story-title" defaultValue="Create Storybook coverage for the board UI" />
+ </div>
+ <div className="grid gap-2">
+ <Label htmlFor="story-summary">Comment</Label>
+ <Textarea
+ id="story-summary"
+ defaultValue={"Implemented the foundation stories.\nNext action: run static build verification."}
+ rows={5}
+ />
+ </div>
+ <div className="grid gap-2 sm:grid-cols-2">
+ <div className="grid gap-2">
+ <Label>Priority</Label>
+ <Select defaultValue="high">
+ <SelectTrigger className="w-full">
+ <SelectValue placeholder="Priority" />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="critical">Critical</SelectItem>
+ <SelectItem value="high">High</SelectItem>
+ <SelectItem value="medium">Medium</SelectItem>
+ <SelectItem value="low">Low</SelectItem>
+ </SelectContent>
+ </Select>
+ </div>
+ <div className="grid gap-2">
+ <Label>Assignee</Label>
+ <Select defaultValue="codexcoder">
+ <SelectTrigger className="w-full">
+ <SelectValue placeholder="Assignee" />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="codexcoder">CodexCoder</SelectItem>
+ <SelectItem value="qachecker">QAChecker</SelectItem>
+ <SelectItem value="board">Board</SelectItem>
+ </SelectContent>
+ </Select>
+ </div>
+ </div>
+ </div>
+
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Governed settings</CardTitle>
+ <CardDescription>Switches, checkboxes, and validation copy in one compact panel.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-4">
+ <div className="flex items-center justify-between gap-4 rounded-lg border border-border p-3">
+ <div>
+ <div className="text-sm font-medium">Auto mode</div>
+ <div className="text-xs text-muted-foreground">Let agents continue after review approval.</div>
+ </div>
+ <ToggleSwitch checked={autoMode} onCheckedChange={setAutoMode} />
+ </div>
+ <label className="flex items-start gap-3 rounded-lg border border-border p-3 text-sm">
+ <Checkbox checked={boardApproval} onCheckedChange={(value) => setBoardApproval(value === true)} />
+ <span>
+ <span className="font-medium">Require board approval for new agents</span>
+ <span className="mt-1 block text-xs text-muted-foreground">
+ Mirrors the company-level governance control.
+ </span>
+ </span>
+ </label>
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+
+ <Section eyebrow="Navigation" title="Tabs, overlays, and modal affordances">
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_320px]">
+ <Tabs defaultValue="details" className="rounded-lg border border-border bg-background/70 p-4">
+ <TabsList variant="line">
+ <TabsTrigger value="details">Details</TabsTrigger>
+ <TabsTrigger value="activity">Activity</TabsTrigger>
+ <TabsTrigger value="budget">Budget</TabsTrigger>
+ </TabsList>
+ <TabsContent value="details" className="pt-5 text-sm leading-6 text-muted-foreground">
+ The line tab style is used on dense detail pages where the content, not the tab chrome, needs to dominate.
+ </TabsContent>
+ <TabsContent value="activity" className="pt-5 text-sm leading-6 text-muted-foreground">
+ Activity copy stays compact and pairs with timestamped rows in the product stories.
+ </TabsContent>
+ <TabsContent value="budget" className="pt-5 text-sm leading-6 text-muted-foreground">
+ Budget controls surface warning and hard-stop states in the control-plane stories.
+ </TabsContent>
+ </Tabs>
+
+ <div className="space-y-3">
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <Button variant="outline" className="w-full justify-start">
+ <Search className="h-4 w-4" />
+ Hover for tooltip
+ </Button>
+ </TooltipTrigger>
+ <TooltipContent>Search issues, agents, projects, and approvals.</TooltipContent>
+ </Tooltip>
+
+ <Popover>
+ <PopoverTrigger asChild>
+ <Button variant="outline" className="w-full justify-start">
+ <Copy className="h-4 w-4" />
+ Open popover
+ </Button>
+ </PopoverTrigger>
+ <PopoverContent align="start" className="w-72">
+ <div className="text-sm font-medium">Copy-safe detail</div>
+ <p className="mt-1 text-xs leading-5 text-muted-foreground">
+ Popovers should keep quick metadata close to the control that opened them.
+ </p>
+ </PopoverContent>
+ </Popover>
+
+ <Dialog>
+ <DialogTrigger asChild>
+ <Button className="w-full justify-start">
+ <Plus className="h-4 w-4" />
+ Open dialog
+ </Button>
+ </DialogTrigger>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Create issue</DialogTitle>
+ <DialogDescription>
+ Dialogs should keep the primary decision and risk clear without leaving the current board context.
+ </DialogDescription>
+ </DialogHeader>
+ <Separator />
+ <div className="grid gap-2">
+ <Label htmlFor="dialog-title">Title</Label>
+ <Input id="dialog-title" defaultValue="Review Storybook visual coverage" />
+ </div>
+ <DialogFooter>
+ <Button variant="outline">Cancel</Button>
+ <Button>
+ <Save className="h-4 w-4" />
+ Save
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </div>
+ </div>
+ </Section>
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Foundations/Primitive Matrix",
+ component: FoundationsMatrix,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Foundation stories keep base shadcn/Radix primitives visible in every variant and key interaction state used by Paperclip.",
+ },
+ },
+ },
+} satisfies Meta<typeof FoundationsMatrix>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const AllPrimitives: Story = {};
diff --git a/ui/storybook/stories/issue-management.stories.tsx b/ui/storybook/stories/issue-management.stories.tsx
new file mode 100644
index 0000000000..f46fd926f5
--- /dev/null
+++ b/ui/storybook/stories/issue-management.stories.tsx
@@ -0,0 +1,601 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Issue } from "@paperclipai/shared";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+ ArrowDownAZ,
+ ArrowUpDown,
+ Check,
+ Columns3,
+ Filter,
+ GitBranch,
+ LayoutList,
+ Link2,
+ PanelRight,
+ Rows3,
+} from "lucide-react";
+import { IssueColumnPicker, InboxIssueMetaLeading, InboxIssueTrailingColumns } from "@/components/IssueColumns";
+import { IssueContinuationHandoff } from "@/components/IssueContinuationHandoff";
+import { IssueDocumentsSection } from "@/components/IssueDocumentsSection";
+import { IssueFiltersPopover } from "@/components/IssueFiltersPopover";
+import { IssueGroupHeader } from "@/components/IssueGroupHeader";
+import { IssueLinkQuicklook, IssueQuicklookCard } from "@/components/IssueLinkQuicklook";
+import { IssueProperties } from "@/components/IssueProperties";
+import { IssueRunLedgerContent } from "@/components/IssueRunLedger";
+import { IssuesList } from "@/components/IssuesList";
+import { IssuesQuicklook } from "@/components/IssuesQuicklook";
+import { IssueWorkspaceCard } from "@/components/IssueWorkspaceCard";
+import { Identity } from "@/components/Identity";
+import { PriorityIcon } from "@/components/PriorityIcon";
+import { StatusBadge } from "@/components/StatusBadge";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { countActiveIssueFilters, defaultIssueFilterState, type IssueFilterState } from "@/lib/issue-filters";
+import { DEFAULT_INBOX_ISSUE_COLUMNS, type InboxIssueColumn } from "@/lib/inbox";
+import { queryKeys } from "@/lib/queryKeys";
+import {
+ storybookAgentMap,
+ storybookAgents,
+ storybookAuthSession,
+ storybookCompanies,
+ storybookContinuationHandoff,
+ storybookExecutionWorkspaces,
+ storybookIssueDocuments,
+ storybookIssueLabels,
+ storybookIssueRuns,
+ storybookIssues,
+ storybookProjects,
+} from "../fixtures/paperclipData";
+
+const companyId = "company-storybook";
+const issueListViewKey = "storybook:issue-management:list";
+const scopedIssueListViewKey = `${issueListViewKey}:${companyId}`;
+const visibleColumns: InboxIssueColumn[] = ["status", "id", "assignee", "project", "workspace", "labels", "updated"];
+
+const issueDocumentSummaries = storybookIssueDocuments.map(({ body: _body, ...summary }) => summary);
+const primaryIssue: Issue = {
+ ...storybookIssues[0]!,
+ planDocument: storybookIssueDocuments.find((document) => document.key === "plan") ?? null,
+ documentSummaries: issueDocumentSummaries,
+ currentExecutionWorkspace: storybookExecutionWorkspaces[0]!,
+};
+const childIssues = storybookIssues.filter((issue) => issue.parentId === primaryIssue.id);
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.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 hydrateStorybookQueries(queryClient: ReturnType<typeof useQueryClient>) {
+ queryClient.setQueryData(queryKeys.companies.all, storybookCompanies);
+ queryClient.setQueryData(queryKeys.auth.session, storybookAuthSession);
+ queryClient.setQueryData(queryKeys.agents.list(companyId), storybookAgents);
+ queryClient.setQueryData(queryKeys.projects.list(companyId), storybookProjects);
+ queryClient.setQueryData(queryKeys.issues.list(companyId), storybookIssues);
+ queryClient.setQueryData(queryKeys.issues.labels(companyId), storybookIssueLabels);
+ queryClient.setQueryData(queryKeys.issues.documents(primaryIssue.id), storybookIssueDocuments);
+ queryClient.setQueryData(queryKeys.issues.runs(primaryIssue.id), storybookIssueRuns);
+ queryClient.setQueryData(queryKeys.issues.liveRuns(primaryIssue.id), []);
+ queryClient.setQueryData(queryKeys.issues.activeRun(primaryIssue.id), null);
+ queryClient.setQueryData(queryKeys.instance.experimentalSettings, {
+ enableIsolatedWorkspaces: true,
+ enableRoutineTriggers: true,
+ });
+ queryClient.setQueryData(queryKeys.access.companyUserDirectory(companyId), {
+ users: [
+ {
+ principalId: "user-board",
+ status: "active",
+ user: {
+ id: "user-board",
+ email: "[email protected]",
+ name: "Riley Board",
+ image: null,
+ },
+ },
+ ],
+ });
+ queryClient.setQueryData(
+ queryKeys.sidebarPreferences.projectOrder(companyId, storybookAuthSession.user.id),
+ { orderedIds: storybookProjects.map((project) => project.id), updatedAt: null },
+ );
+ queryClient.setQueryData(
+ queryKeys.executionWorkspaces.summaryList(companyId),
+ storybookExecutionWorkspaces.map((workspace) => ({
+ id: workspace.id,
+ name: workspace.name,
+ mode: workspace.mode,
+ projectWorkspaceId: workspace.projectWorkspaceId,
+ })),
+ );
+ queryClient.setQueryData(
+ queryKeys.executionWorkspaces.list(companyId, {
+ projectId: primaryIssue.projectId ?? undefined,
+ projectWorkspaceId: primaryIssue.projectWorkspaceId ?? undefined,
+ reuseEligible: true,
+ }),
+ storybookExecutionWorkspaces,
+ );
+}
+
+function seedIssueListLocalStorage() {
+ if (typeof window === "undefined") return;
+ window.localStorage.setItem(
+ scopedIssueListViewKey,
+ JSON.stringify({
+ ...defaultIssueFilterState,
+ sortField: "priority",
+ sortDir: "desc",
+ groupBy: "status",
+ viewMode: "list",
+ nestingEnabled: true,
+ collapsedGroups: [],
+ collapsedParents: [],
+ }),
+ );
+ window.localStorage.setItem(`${scopedIssueListViewKey}:issue-columns`, JSON.stringify(visibleColumns));
+}
+
+function StorybookData({ children }: { children: React.ReactNode }) {
+ const queryClient = useQueryClient();
+ const [ready] = useState(() => {
+ hydrateStorybookQueries(queryClient);
+ seedIssueListLocalStorage();
+ return true;
+ });
+
+ return ready ? children : null;
+}
+
+function ColumnConfigurationMatrix() {
+ const [columns, setColumns] = useState<InboxIssueColumn[]>(visibleColumns);
+ const visibleColumnSet = useMemo(() => new Set(columns), [columns]);
+ const triggerRef = useRef<HTMLDivElement | null>(null);
+
+ useEffect(() => {
+ const timer = window.setTimeout(() => {
+ triggerRef.current?.querySelector("button")?.click();
+ }, 150);
+ return () => window.clearTimeout(timer);
+ }, []);
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_340px]">
+ <div className="overflow-hidden rounded-lg border border-border bg-background/70">
+ <div className="grid grid-cols-[minmax(0,1fr)_minmax(420px,0.9fr)] items-center border-b border-border px-4 py-2 text-[11px] font-semibold uppercase text-muted-foreground">
+ <span>Issue</span>
+ <span className="grid grid-cols-[6rem_7rem_9rem_6rem_4.5rem] gap-2">
+ <span>Assignee</span>
+ <span>Project</span>
+ <span>Workspace</span>
+ <span>Tags</span>
+ <span className="text-right">Updated</span>
+ </span>
+ </div>
+ {storybookIssues.slice(0, 3).map((issue) => (
+ <div key={issue.id} className="grid grid-cols-[minmax(0,1fr)_minmax(420px,0.9fr)] items-center border-b border-border/60 px-4 py-3 last:border-b-0">
+ <div className="flex min-w-0 items-center gap-2">
+ <InboxIssueMetaLeading
+ issue={issue}
+ isLive={issue.id === primaryIssue.id}
+ showStatus={visibleColumnSet.has("status")}
+ showIdentifier={visibleColumnSet.has("id")}
+ />
+ <span className="truncate text-sm font-medium">{issue.title}</span>
+ </div>
+ <InboxIssueTrailingColumns
+ issue={issue}
+ columns={columns.filter((column) => !["status", "id"].includes(column))}
+ projectName={storybookProjects.find((project) => project.id === issue.projectId)?.name ?? null}
+ projectColor={storybookProjects.find((project) => project.id === issue.projectId)?.color ?? null}
+ workspaceId={issue.projectWorkspaceId ?? issue.executionWorkspaceId}
+ workspaceName={issue.currentExecutionWorkspace?.name ?? "Board UI"}
+ assigneeName={issue.assigneeAgentId ? storybookAgentMap.get(issue.assigneeAgentId)?.name ?? null : null}
+ assigneeUserName={issue.assigneeUserId ? "Riley Board" : null}
+ currentUserId="user-board"
+ parentIdentifier={storybookIssues.find((candidate) => candidate.id === issue.parentId)?.identifier ?? null}
+ parentTitle={storybookIssues.find((candidate) => candidate.id === issue.parentId)?.title ?? null}
+ />
+ </div>
+ ))}
+ </div>
+
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <Columns3 className="h-4 w-4" />
+ Column configuration
+ </CardTitle>
+ <CardDescription>Open picker plus sort state tokens used beside issue rows.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-4">
+ <div ref={triggerRef}>
+ <IssueColumnPicker
+ availableColumns={["status", "id", "assignee", "project", "workspace", "parent", "labels", "updated"]}
+ visibleColumnSet={visibleColumnSet}
+ onToggleColumn={(column, enabled) => {
+ setColumns((current) => {
+ const next = enabled ? [...current, column] : current.filter((value) => value !== column);
+ return DEFAULT_INBOX_ISSUE_COLUMNS.filter((candidate) => next.includes(candidate)).concat(
+ next.filter((candidate) => !DEFAULT_INBOX_ISSUE_COLUMNS.includes(candidate)),
+ );
+ });
+ }}
+ onResetColumns={() => setColumns(DEFAULT_INBOX_ISSUE_COLUMNS)}
+ title="Choose which issue columns stay visible"
+ />
+ </div>
+ <div className="space-y-2">
+ {[
+ { label: "Priority", icon: ArrowUpDown, state: "descending" },
+ { label: "Title", icon: ArrowDownAZ, state: "ascending" },
+ { label: "Updated", icon: Check, state: "active default" },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <div key={item.label} className="flex items-center justify-between rounded-md border border-border bg-background/70 px-3 py-2 text-sm">
+ <span className="flex items-center gap-2">
+ <Icon className="h-3.5 w-3.5 text-muted-foreground" />
+ {item.label}
+ </span>
+ <span className="text-xs text-muted-foreground">{item.state}</span>
+ </div>
+ );
+ })}
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+ );
+}
+
+function GroupHeaderMatrix() {
+ const rows = [
+ { label: "In progress", trailing: "1 issue", badge: <StatusBadge status="in_progress" /> },
+ { label: "High priority", trailing: "3 issues", badge: <PriorityIcon priority="high" showLabel /> },
+ { label: "CodexCoder", trailing: "3 assigned", badge: <Identity name="CodexCoder" size="sm" /> },
+ ];
+
+ return (
+ <div className="grid gap-4 md:grid-cols-3">
+ {rows.map((row, index) => (
+ <div key={row.label} className="rounded-lg border border-border bg-background/70 p-2">
+ <IssueGroupHeader
+ label={row.label}
+ collapsible
+ collapsed={index === 1}
+ trailing={<span className="text-xs text-muted-foreground">{row.trailing}</span>}
+ />
+ <div className="border-t border-border px-3 py-4">{row.badge}</div>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+function OpenFiltersPopover() {
+ const [state, setState] = useState<IssueFilterState>({
+ ...defaultIssueFilterState,
+ statuses: ["in_progress", "blocked", "in_review"],
+ priorities: ["critical", "high"],
+ assignees: ["agent-codex", "agent-qa", "__unassigned"],
+ });
+ const triggerRef = useRef<HTMLDivElement | null>(null);
+
+ useEffect(() => {
+ const timer = window.setTimeout(() => {
+ triggerRef.current?.querySelector("button")?.click();
+ }, 150);
+ return () => window.clearTimeout(timer);
+ }, []);
+
+ return (
+ <div className="flex min-h-[500px] items-start justify-end rounded-lg border border-dashed border-border bg-background/60 p-4">
+ <div ref={triggerRef}>
+ <IssueFiltersPopover
+ state={state}
+ onChange={(patch) => setState((current) => ({ ...current, ...patch }))}
+ activeFilterCount={countActiveIssueFilters(state, true)}
+ agents={storybookAgents.map((agent) => ({ id: agent.id, name: agent.name }))}
+ projects={storybookProjects.map((project) => ({ id: project.id, name: project.name }))}
+ labels={storybookIssueLabels.map((label) => ({ id: label.id, name: label.name, color: label.color }))}
+ currentUserId="user-board"
+ enableRoutineVisibilityFilter
+ buttonVariant="outline"
+ workspaces={storybookExecutionWorkspaces.map((workspace) => ({ id: workspace.id, name: workspace.name }))}
+ creators={[
+ { id: "user:user-board", label: "Riley Board", kind: "user", searchText: "board user human" },
+ ...storybookAgents.map((agent) => ({
+ id: `agent:${agent.id}`,
+ label: agent.name,
+ kind: "agent" as const,
+ searchText: `${agent.name} ${agent.role}`,
+ })),
+ ]}
+ />
+ </div>
+ </div>
+ );
+}
+
+function RunLedgerWithCostColumns() {
+ return (
+ <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_380px]">
+ <IssueRunLedgerContent
+ runs={storybookIssueRuns}
+ activeRun={null}
+ liveRuns={[]}
+ issueStatus={primaryIssue.status}
+ childIssues={childIssues}
+ agentMap={storybookAgentMap}
+ />
+ <div className="overflow-hidden rounded-lg border border-border bg-background/70">
+ <div className="grid grid-cols-[1fr_90px_80px_70px] gap-2 border-b border-border px-3 py-2 text-[11px] font-semibold uppercase text-muted-foreground">
+ <span>Run</span>
+ <span>Status</span>
+ <span>Duration</span>
+ <span className="text-right">Cost</span>
+ </div>
+ {storybookIssueRuns.map((run) => {
+ const start = run.startedAt ? new Date(run.startedAt).getTime() : null;
+ const end = run.finishedAt ? new Date(run.finishedAt).getTime() : Date.now();
+ const minutes = start ? Math.max(1, Math.round((end - start) / 60_000)) : null;
+ const costCents = typeof run.usageJson?.costCents === "number" ? run.usageJson.costCents : 0;
+ return (
+ <div key={run.runId} className="grid grid-cols-[1fr_90px_80px_70px] gap-2 border-b border-border/60 px-3 py-2 text-xs last:border-b-0">
+ <span className="min-w-0 truncate font-mono">{run.runId}</span>
+ <span className="capitalize text-muted-foreground">{run.status}</span>
+ <span className="text-muted-foreground">{minutes ? `${minutes}m` : "unknown"}</span>
+ <span className="text-right font-mono">${(costCents / 100).toFixed(2)}</span>
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
+
+function WorkspaceCardWithRuntime() {
+ const service = primaryIssue.currentExecutionWorkspace?.runtimeServices?.[0] ?? null;
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_360px]">
+ <IssueWorkspaceCard
+ issue={primaryIssue}
+ project={storybookProjects[0]!}
+ onUpdate={() => undefined}
+ />
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <GitBranch className="h-4 w-4" />
+ Runtime status
+ </CardTitle>
+ <CardDescription>Branch, path, and running service context paired with the workspace card.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-3 text-sm">
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Branch</span>
+ <span className="truncate font-mono text-xs">{primaryIssue.currentExecutionWorkspace?.branchName}</span>
+ </div>
+ <div className="space-y-1">
+ <span className="text-muted-foreground">Path</span>
+ <div className="break-all rounded-md border border-border bg-background/70 p-2 font-mono text-xs">
+ {primaryIssue.currentExecutionWorkspace?.cwd}
+ </div>
+ </div>
+ {service ? (
+ <div className="flex items-center justify-between gap-3 rounded-md border border-border bg-background/70 px-3 py-2">
+ <span>{service.serviceName}</span>
+ <Badge variant="outline">{service.status}</Badge>
+ </div>
+ ) : null}
+ </CardContent>
+ </Card>
+ </div>
+ );
+}
+
+function QuicklookSurfaces() {
+ return (
+ <div className="grid gap-5 lg:grid-cols-2">
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 flex items-center gap-2 text-sm font-medium">
+ <Link2 className="h-4 w-4 text-muted-foreground" />
+ IssueLinkQuicklook
+ </div>
+ <IssueLinkQuicklook
+ issuePathId={primaryIssue.identifier ?? primaryIssue.id}
+ issuePrefetch={primaryIssue}
+ to={`/PAP/issues/${primaryIssue.identifier}`}
+ className="font-mono text-sm text-primary hover:underline"
+ >
+ {primaryIssue.identifier}
+ </IssueLinkQuicklook>
+ <div className="mt-4 rounded-md border border-border bg-popover p-3 shadow-xl">
+ <IssueQuicklookCard
+ issue={primaryIssue}
+ linkTo={`/PAP/issues/${primaryIssue.identifier}`}
+ compact
+ />
+ </div>
+ </div>
+
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <div className="mb-3 flex items-center gap-2 text-sm font-medium">
+ <PanelRight className="h-4 w-4 text-muted-foreground" />
+ IssuesQuicklook
+ </div>
+ <IssuesQuicklook issue={storybookIssues[2]!}>
+ <Button variant="outline" size="sm">Hover preview trigger</Button>
+ </IssuesQuicklook>
+ <div className="mt-4 rounded-md border border-border bg-card p-3">
+ <IssueQuicklookCard
+ issue={storybookIssues[2]!}
+ linkTo={`/PAP/issues/${storybookIssues[2]!.identifier}`}
+ />
+ </div>
+ </div>
+ </div>
+ );
+}
+
+function IssueManagementStories() {
+ return (
+ <StorybookData>
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner 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">Issue management</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">List, detail, filters, runs, and workspace states</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Fixture-backed issue management stories cover the operational states used by the board when reviewing,
+ filtering, handing off, and continuing agent work.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">7 issues</Badge>
+ <Badge variant="outline">3 agents</Badge>
+ <Badge variant="outline">workspace aware</Badge>
+ </div>
+ </div>
+ </section>
+
+ <Section eyebrow="IssuesList" title="Full list view with grouped issue rows and column headers">
+ <div className="mb-3 grid grid-cols-[minmax(0,1fr)_120px_120px_110px] gap-3 rounded-lg border border-border bg-background/70 px-4 py-2 text-[11px] font-semibold uppercase text-muted-foreground">
+ <span>Issue</span>
+ <span>Assignee</span>
+ <span>Workspace</span>
+ <span className="text-right">Updated</span>
+ </div>
+ <IssuesList
+ issues={storybookIssues}
+ agents={storybookAgents}
+ projects={storybookProjects}
+ liveIssueIds={new Set([primaryIssue.id])}
+ viewStateKey={issueListViewKey}
+ onUpdateIssue={() => undefined}
+ createIssueLabel="issue"
+ enableRoutineVisibilityFilter
+ />
+ </Section>
+
+ <Section eyebrow="IssueColumns" title="Column configuration and sorting states">
+ <ColumnConfigurationMatrix />
+ </Section>
+
+ <Section eyebrow="IssueGroupHeader" title="Grouped by status, priority, and assignee">
+ <GroupHeaderMatrix />
+ </Section>
+
+ <Section eyebrow="IssueProperties" title="Full issue detail sidebar with all property fields">
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_380px]">
+ <div className="space-y-4 rounded-lg border border-border bg-background/70 p-5">
+ <div className="flex flex-wrap items-center gap-2">
+ <StatusBadge status={primaryIssue.status} />
+ <PriorityIcon priority={primaryIssue.priority} showLabel />
+ <Badge variant="secondary">{primaryIssue.identifier}</Badge>
+ </div>
+ <h3 className="text-2xl font-semibold tracking-tight">{primaryIssue.title}</h3>
+ <p className="max-w-2xl text-sm leading-6 text-muted-foreground">{primaryIssue.description}</p>
+ </div>
+ <div className="rounded-lg border border-border bg-background/70 p-4">
+ <IssueProperties
+ issue={primaryIssue}
+ childIssues={childIssues}
+ onAddSubIssue={() => undefined}
+ onUpdate={() => undefined}
+ inline
+ />
+ </div>
+ </div>
+ </Section>
+
+ <Section eyebrow="IssueDocumentsSection" title="Documents list with plan and notes documents">
+ <IssueDocumentsSection
+ issue={primaryIssue}
+ canDeleteDocuments
+ feedbackDataSharingPreference="allowed"
+ />
+ </Section>
+
+ <Section eyebrow="IssueFiltersPopover" title="Open filter popover with status, priority, and assignee filters">
+ <OpenFiltersPopover />
+ </Section>
+
+ <Section eyebrow="IssueContinuationHandoff" title="Expanded handoff for continuing work across runs">
+ <IssueContinuationHandoff document={storybookContinuationHandoff} focusSignal={1} />
+ </Section>
+
+ <Section eyebrow="IssueRunLedger" title="Run history table with status, duration, and cost columns">
+ <RunLedgerWithCostColumns />
+ </Section>
+
+ <Section eyebrow="IssueWorkspaceCard" title="Workspace info card with branch, path, and runtime status">
+ <WorkspaceCardWithRuntime />
+ </Section>
+
+ <Section eyebrow="Quicklook" title="Linked issue popup and side-panel quick look">
+ <QuicklookSurfaces />
+ </Section>
+
+ <section className="grid gap-4 md:grid-cols-3">
+ {[
+ { icon: LayoutList, label: "List density", detail: "Grouped rows keep status and ownership visible." },
+ { icon: Filter, label: "Filtering", detail: "Selected filters are explicit and clearable." },
+ { icon: Rows3, label: "Detail panels", detail: "Properties, documents, runs, and workspaces stay close to the task." },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <Card key={item.label} className="paperclip-story__frame shadow-none">
+ <CardHeader>
+ <Icon className="h-4 w-4 text-muted-foreground" />
+ <CardTitle>{item.label}</CardTitle>
+ <CardDescription>{item.detail}</CardDescription>
+ </CardHeader>
+ </Card>
+ );
+ })}
+ </section>
+ </main>
+ </div>
+ </StorybookData>
+ );
+}
+
+const meta = {
+ title: "Product/Issue Management",
+ component: IssueManagementStories,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Issue-management stories exercise the full list, column, grouping, property, document, filter, continuation, run, workspace, and quicklook surfaces.",
+ },
+ },
+ },
+} satisfies Meta<typeof IssueManagementStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const FullSurfaceMatrix: Story = {};
diff --git a/ui/storybook/stories/navigation-layout.stories.tsx b/ui/storybook/stories/navigation-layout.stories.tsx
new file mode 100644
index 0000000000..89e95105d7
--- /dev/null
+++ b/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 = {};
diff --git a/ui/storybook/stories/overview.stories.tsx b/ui/storybook/stories/overview.stories.tsx
new file mode 100644
index 0000000000..c95b2126a6
--- /dev/null
+++ b/ui/storybook/stories/overview.stories.tsx
@@ -0,0 +1,203 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+ BookOpen,
+ Bot,
+ CheckCircle2,
+ FlaskConical,
+ FolderKanban,
+ FormInput,
+ Layers3,
+ LayoutDashboard,
+ ListTodo,
+ MessageSquare,
+ PanelLeft,
+ Route,
+ ShieldCheck,
+ Wallet,
+} from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+
+const storyGroups = [
+ {
+ title: "Foundations",
+ icon: Layers3,
+ stories: "Buttons, badges, form controls, tabs, cards, dialogs, overlays",
+ why: "Baseline tokens and primitives before product components add state.",
+ },
+ {
+ title: "Control Plane Surfaces",
+ icon: ShieldCheck,
+ stories: "Issue rows, approvals, budget cards, activity rows, metrics",
+ why: "The V1 board UI depends on these dense operational patterns staying legible.",
+ },
+ {
+ title: "UX Labs",
+ icon: FlaskConical,
+ stories: "Issue chat, run transcripts, invite/access flows",
+ why: "The old `/tests/ux/*` pages are fixture-backed Storybook stories now.",
+ },
+ {
+ title: "Navigation & Layout",
+ icon: PanelLeft,
+ stories: "Sidebar, breadcrumbs, command palette, company rail, mobile nav",
+ why: "Navigation chrome frames every board interaction and needs mobile parity.",
+ },
+ {
+ title: "Agent Management",
+ icon: Bot,
+ stories: "Agent properties, config forms, icon picker, action buttons",
+ why: "Agent lifecycle is the primary governance surface for operators.",
+ },
+ {
+ title: "Issue Management",
+ icon: ListTodo,
+ stories: "Issue lists, filters, properties, documents, run ledger, workspace cards",
+ why: "Issues are the core work unit — every view state matters for scan speed.",
+ },
+ {
+ title: "Forms & Editors",
+ icon: FormInput,
+ stories: "Markdown editor, JSON schema forms, env vars, schedule editor, pickers",
+ why: "Rich editors need isolated review for empty, filled, and validation states.",
+ },
+ {
+ title: "Budget & Finance",
+ icon: Wallet,
+ stories: "Incident cards, provider quotas, biller spend, subscription panels",
+ why: "Financial controls are safety-critical and need threshold state coverage.",
+ },
+ {
+ title: "Dialogs & Modals",
+ icon: LayoutDashboard,
+ stories: "New issue/agent/goal/project dialogs, diff modal, image gallery",
+ why: "Dialogs interrupt flow — they must be scannable and self-explanatory.",
+ },
+ {
+ title: "Projects & Goals",
+ icon: FolderKanban,
+ stories: "Project properties, workspace cards, goal trees, runtime controls",
+ why: "Hierarchical views (goals, projects, workspaces) need expand/collapse coverage.",
+ },
+ {
+ title: "Chat & Comments",
+ icon: MessageSquare,
+ stories: "Comment threads, run chat, issue chat with timeline events",
+ why: "Threaded conversations mix agent/user/system authors and need density review.",
+ },
+];
+
+const coverageRows = [
+ ["System primitives", "Covered", "State matrix across size, variant, disabled, icon, and overlay behavior"],
+ ["Status language", "Covered", "Issue/agent lifecycle badges, priorities, quota thresholds, and empty states"],
+ ["Task surfaces", "Covered", "Inbox-style rows with unread, selected, archive, and trailing metadata states"],
+ ["Governance", "Covered", "Pending, revision-requested, approved, and budget-specific approval payloads"],
+ ["Budget controls", "Covered", "Healthy, warning, hard-stop, compact, plain, and editable card variants"],
+ ["Execution UX", "Covered", "Run transcript detail, live widget, dashboard card, streaming and settled views"],
+ ["Invite UX", "Covered", "Fixture-backed access roles, invite landing, pending, accepted, expired, and error states"],
+ ["Navigation & layout", "Planned", "Sidebar, breadcrumbs, command palette, company rail, mobile nav"],
+ ["Agent management", "Planned", "Agent properties, config forms, icon picker, action buttons, active panel"],
+ ["Issue management", "Planned", "Issue lists, filters, properties, documents, run ledger, workspace cards"],
+ ["Forms & editors", "Planned", "Markdown editor, JSON schema, env vars, schedule editor, pickers"],
+ ["Budget & finance", "Planned", "Incident cards, provider quotas, biller spend, subscription panels"],
+ ["Dialogs & modals", "Planned", "New issue/agent/goal/project dialogs, diff modal, image gallery"],
+ ["Projects & goals", "Planned", "Project properties, workspace cards, goal trees, runtime controls"],
+ ["Chat & comments", "Covered", "Comment threads, run chat, issue chat with timeline events"],
+ ["Data viz & misc", "Planned", "Activity charts, kanban, filter bar, live widget, onboarding, skeletons"],
+ ["Full app pages", "Deferred", "API-driven route stories after page data loaders can be fixture-injected"],
+];
+
+function StorybookGuide() {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-8">
+ <section className="paperclip-story__frame overflow-hidden p-6 sm:p-8">
+ <div className="flex flex-wrap items-start justify-between gap-6">
+ <div className="max-w-3xl">
+ <div className="paperclip-story__label flex items-center gap-2">
+ <BookOpen className="h-4 w-4" />
+ Paperclip Storybook
+ </div>
+ <h1 className="mt-3 text-3xl font-semibold tracking-tight sm:text-4xl">
+ Board UI stories for real control-plane states
+ </h1>
+ <p className="mt-4 text-sm leading-6 text-muted-foreground sm:text-base">
+ This Storybook is organized as a review workspace for Paperclip's operator UI: primitives first,
+ product surfaces second, and the former UX test routes as isolated fixture-backed stories.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">React 19</Badge>
+ <Badge variant="outline">Vite</Badge>
+ <Badge variant="outline">Tailwind 4</Badge>
+ <Badge variant="outline">Fixture backed</Badge>
+ </div>
+ </div>
+ </section>
+
+ <section className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+ {storyGroups.map((group) => {
+ const Icon = group.icon;
+ return (
+ <Card key={group.title} className="paperclip-story__frame shadow-none">
+ <CardHeader>
+ <div className="flex h-10 w-10 items-center justify-center border border-border bg-background">
+ <Icon className="h-4 w-4 text-muted-foreground" />
+ </div>
+ <CardTitle>{group.title}</CardTitle>
+ <CardDescription>{group.stories}</CardDescription>
+ </CardHeader>
+ <CardContent className="text-sm leading-6 text-muted-foreground">
+ {group.why}
+ </CardContent>
+ </Card>
+ );
+ })}
+ </section>
+
+ <section className="paperclip-story__frame overflow-hidden">
+ <div className="border-b border-border px-5 py-4">
+ <div className="paperclip-story__label flex items-center gap-2">
+ <Route className="h-4 w-4" />
+ Coverage Map
+ </div>
+ </div>
+ <div className="divide-y divide-border">
+ {coverageRows.map(([area, status, detail]) => (
+ <div key={area} className="grid gap-3 px-5 py-4 text-sm sm:grid-cols-[180px_120px_minmax(0,1fr)]">
+ <div className="font-medium">{area}</div>
+ <div>
+ <span className="inline-flex items-center gap-1.5 rounded-full border border-border bg-background px-2 py-0.5 text-xs text-muted-foreground">
+ {status === "Covered" ? <CheckCircle2 className="h-3 w-3 text-emerald-500" /> : null}
+ {status === "Planned" ? <Route className="h-3 w-3 text-cyan-500" /> : null}
+ {status}
+ </span>
+ </div>
+ <div className="text-muted-foreground">{detail}</div>
+ </div>
+ ))}
+ </div>
+ </section>
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Overview/Storybook Guide",
+ component: StorybookGuide,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "The overview story explains the local organization and the coverage contract for Paperclip's Storybook.",
+ },
+ },
+ },
+} satisfies Meta<typeof StorybookGuide>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const CoverageGuide: Story = {};
diff --git a/ui/storybook/stories/projects-goals-workspaces.stories.tsx b/ui/storybook/stories/projects-goals-workspaces.stories.tsx
new file mode 100644
index 0000000000..76d83d9d2a
--- /dev/null
+++ b/ui/storybook/stories/projects-goals-workspaces.stories.tsx
@@ -0,0 +1,516 @@
+import { useMemo, useState, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useQueryClient } from "@tanstack/react-query";
+import type { Goal, Project } from "@paperclipai/shared";
+import { Archive, Boxes, FolderGit2, GitBranch, Network, Play, RotateCcw, Square } from "lucide-react";
+import { GoalProperties } from "@/components/GoalProperties";
+import { GoalTree } from "@/components/GoalTree";
+import { ProjectProperties, type ProjectConfigFieldKey, type ProjectFieldSaveState } from "@/components/ProjectProperties";
+import { ProjectWorkspacesContent } from "@/components/ProjectWorkspacesContent";
+import { ProjectWorkspaceSummaryCard } from "@/components/ProjectWorkspaceSummaryCard";
+import {
+ WorkspaceRuntimeControls,
+ buildWorkspaceRuntimeControlSections,
+ type WorkspaceRuntimeControlRequest,
+} from "@/components/WorkspaceRuntimeControls";
+import { WorktreeBanner } from "@/components/WorktreeBanner";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { queryKeys } from "@/lib/queryKeys";
+import { buildProjectWorkspaceSummaries } from "@/lib/project-workspaces-tab";
+import {
+ storybookAgents,
+ storybookAuthSession,
+ storybookCompanies,
+ storybookExecutionWorkspaces,
+ storybookGoals,
+ storybookIssues,
+ storybookProjectWorkspaces,
+ storybookProjects,
+} from "../fixtures/paperclipData";
+
+const COMPANY_ID = "company-storybook";
+const boardProject = storybookProjects.find((project) => project.id === "project-board-ui") ?? storybookProjects[0]!;
+const archivedProject =
+ storybookProjects.find((project) => project.id === "project-archived-import")
+ ?? storybookProjects[storybookProjects.length - 1]!;
+
+const goalProgress = new Map<string, number>([
+ ["goal-company", 62],
+ ["goal-board-ux", 74],
+ ["goal-agent-runtime", 48],
+ ["goal-storybook", 88],
+ ["goal-budget-safety", 100],
+ ["goal-archived-import", 18],
+]);
+
+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 hydrateStorybookQueries(queryClient: ReturnType<typeof useQueryClient>) {
+ queryClient.setQueryData(queryKeys.auth.session, storybookAuthSession);
+ queryClient.setQueryData(queryKeys.companies.all, storybookCompanies);
+ queryClient.setQueryData(queryKeys.agents.list(COMPANY_ID), storybookAgents);
+ queryClient.setQueryData(queryKeys.projects.list(COMPANY_ID), storybookProjects);
+ queryClient.setQueryData(queryKeys.projects.detail(boardProject.id), boardProject);
+ queryClient.setQueryData(queryKeys.projects.detail(boardProject.urlKey), boardProject);
+ queryClient.setQueryData(queryKeys.projects.detail(archivedProject.id), archivedProject);
+ queryClient.setQueryData(queryKeys.goals.list(COMPANY_ID), storybookGoals);
+ for (const goal of storybookGoals) {
+ queryClient.setQueryData(queryKeys.goals.detail(goal.id), goal);
+ }
+ queryClient.setQueryData(queryKeys.issues.list(COMPANY_ID), storybookIssues);
+ queryClient.setQueryData(queryKeys.issues.listByProject(COMPANY_ID, boardProject.id), storybookIssues);
+ queryClient.setQueryData(queryKeys.secrets.list(COMPANY_ID), []);
+ queryClient.setQueryData(queryKeys.instance.experimentalSettings, {
+ enableIsolatedWorkspaces: true,
+ enableRoutineTriggers: true,
+ });
+ queryClient.setQueryData(queryKeys.executionWorkspaces.list(COMPANY_ID), storybookExecutionWorkspaces);
+ queryClient.setQueryData(
+ queryKeys.executionWorkspaces.list(COMPANY_ID, { projectId: boardProject.id }),
+ storybookExecutionWorkspaces,
+ );
+ queryClient.setQueryData(
+ queryKeys.executionWorkspaces.summaryList(COMPANY_ID),
+ storybookExecutionWorkspaces.map((workspace) => ({
+ id: workspace.id,
+ name: workspace.name,
+ mode: workspace.mode,
+ projectWorkspaceId: workspace.projectWorkspaceId,
+ })),
+ );
+}
+
+function StorybookData({ children }: { children: ReactNode }) {
+ const queryClient = useQueryClient();
+ const [ready] = useState(() => {
+ hydrateStorybookQueries(queryClient);
+ return true;
+ });
+
+ return ready ? children : null;
+}
+
+function stateForProjectField(field: ProjectConfigFieldKey): ProjectFieldSaveState {
+ if (field === "env" || field === "execution_workspace_branch_template") return "saved";
+ if (field === "execution_workspace_worktree_parent_dir") return "saving";
+ return "idle";
+}
+
+function ProjectPropertiesMatrix() {
+ const editableProject: Project = useMemo(
+ () => ({
+ ...boardProject,
+ env: {
+ STORYBOOK_REVIEW: { type: "plain", value: "enabled" },
+ OPENAI_API_KEY: { type: "secret_ref", secretId: "secret-openai", version: "latest" },
+ },
+ }),
+ [],
+ );
+
+ return (
+ <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_420px]">
+ <div className="rounded-lg border border-border bg-background p-4">
+ <ProjectProperties
+ project={editableProject}
+ onFieldUpdate={() => undefined}
+ getFieldSaveState={stateForProjectField}
+ onArchive={() => undefined}
+ />
+ </div>
+ <div className="space-y-4">
+ <div className="rounded-lg border border-border bg-background p-4">
+ <div className="mb-3 flex items-center justify-between gap-3">
+ <div>
+ <div className="text-sm font-medium">{archivedProject.name}</div>
+ <div className="text-xs text-muted-foreground">Archived, no workspace configured</div>
+ </div>
+ <Badge variant="outline" className="gap-1">
+ <Archive className="h-3 w-3" />
+ archived
+ </Badge>
+ </div>
+ <ProjectProperties
+ project={archivedProject}
+ onFieldUpdate={() => undefined}
+ onArchive={() => undefined}
+ archivePending={false}
+ />
+ </div>
+ <div className="grid gap-3 sm:grid-cols-3 xl:grid-cols-1">
+ {[
+ { label: "Goals linked", value: boardProject.goalIds.length, icon: Network },
+ { label: "Workspaces", value: boardProject.workspaces.length, icon: Boxes },
+ { label: "Runtime services", value: boardProject.primaryWorkspace?.runtimeServices?.length ?? 0, icon: Play },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <div key={item.label} className="rounded-lg border border-border bg-background p-4">
+ <Icon className="h-4 w-4 text-muted-foreground" />
+ <div className="mt-3 text-2xl font-semibold">{item.value}</div>
+ <div className="text-xs text-muted-foreground">{item.label}</div>
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+function WorkspacesMatrix() {
+ const summaries = buildProjectWorkspaceSummaries({
+ project: boardProject,
+ issues: storybookIssues.filter((issue) => issue.projectId === boardProject.id),
+ executionWorkspaces: storybookExecutionWorkspaces,
+ });
+ const localSummary = summaries.find((summary) => summary.kind === "project_workspace" && summary.workspaceId === "workspace-board-ui");
+ const remoteSummary = summaries.find((summary) => summary.workspaceId === "workspace-docs-remote");
+ const cleanupSummary = summaries.find((summary) => summary.executionWorkspaceStatus === "cleanup_failed");
+ const featuredSummaries = [localSummary, remoteSummary, cleanupSummary].filter(
+ (summary): summary is NonNullable<typeof summary> => Boolean(summary),
+ );
+
+ return (
+ <div className="space-y-5">
+ <ProjectWorkspacesContent
+ companyId={COMPANY_ID}
+ projectId={boardProject.id}
+ projectRef={boardProject.urlKey}
+ summaries={summaries}
+ />
+ <div className="grid gap-4 xl:grid-cols-3">
+ {featuredSummaries.map((summary) => (
+ <ProjectWorkspaceSummaryCard
+ key={summary.key}
+ projectRef={boardProject.urlKey}
+ summary={summary}
+ runtimeActionKey={summary.runningServiceCount > 0 ? `${summary.key}:stop` : null}
+ runtimeActionPending={summary.runningServiceCount > 0}
+ onRuntimeAction={() => undefined}
+ onCloseWorkspace={() => undefined}
+ />
+ ))}
+ </div>
+ <div className="rounded-lg border border-dashed border-border p-5 text-sm text-muted-foreground">
+ <ProjectWorkspacesContent
+ companyId={COMPANY_ID}
+ projectId={archivedProject.id}
+ projectRef={archivedProject.urlKey}
+ summaries={[]}
+ />
+ </div>
+ </div>
+ );
+}
+
+function GoalProgressRow({ goal }: { goal: Goal }) {
+ const progress = goalProgress.get(goal.id) ?? 0;
+ const childCount = storybookGoals.filter((candidate) => candidate.parentId === goal.id).length;
+
+ return (
+ <div className="rounded-lg border border-border bg-background p-3">
+ <div className="flex items-start justify-between gap-3">
+ <div className="min-w-0">
+ <div className="truncate text-sm font-medium">{goal.title}</div>
+ <div className="mt-1 text-xs text-muted-foreground">
+ {goal.level} · {childCount} child goal{childCount === 1 ? "" : "s"}
+ </div>
+ </div>
+ <span className="font-mono text-xs text-muted-foreground">{progress}%</span>
+ </div>
+ <div className="mt-3 h-2 overflow-hidden rounded-full bg-muted" aria-label={`${progress}% complete`}>
+ <div className="h-full rounded-full bg-primary" style={{ width: `${progress}%` }} />
+ </div>
+ </div>
+ );
+}
+
+function GoalPropertiesMatrix() {
+ const selectedGoal = storybookGoals.find((goal) => goal.id === "goal-board-ux") ?? storybookGoals[0]!;
+ const childGoals = storybookGoals.filter((goal) => goal.parentId === selectedGoal.id);
+ const linkedProjects = storybookProjects.filter((project) => project.goalIds.includes(selectedGoal.id));
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_340px]">
+ <div className="space-y-4">
+ <div className="rounded-lg border border-border bg-background p-5">
+ <div className="flex flex-wrap items-start justify-between gap-4">
+ <div>
+ <div className="paperclip-story__label">Goal detail composition</div>
+ <h3 className="mt-2 text-xl font-semibold">{selectedGoal.title}</h3>
+ <p className="mt-2 max-w-2xl text-sm leading-6 text-muted-foreground">{selectedGoal.description}</p>
+ </div>
+ <Badge variant="outline">{selectedGoal.status}</Badge>
+ </div>
+ <div className="mt-5 grid gap-3 md:grid-cols-3">
+ <GoalProgressRow goal={selectedGoal} />
+ <div className="rounded-lg border border-border bg-background p-3">
+ <div className="text-2xl font-semibold">{childGoals.length}</div>
+ <div className="text-xs text-muted-foreground">Child goals</div>
+ </div>
+ <div className="rounded-lg border border-border bg-background p-3">
+ <div className="text-2xl font-semibold">{linkedProjects.length}</div>
+ <div className="text-xs text-muted-foreground">Linked projects</div>
+ </div>
+ </div>
+ </div>
+ <div className="grid gap-3 md:grid-cols-2">
+ {childGoals.map((goal) => (
+ <GoalProgressRow key={goal.id} goal={goal} />
+ ))}
+ </div>
+ </div>
+ <div className="rounded-lg border border-border bg-background p-4">
+ <GoalProperties goal={selectedGoal} onUpdate={() => undefined} />
+ </div>
+ </div>
+ );
+}
+
+function GoalTreeMatrix() {
+ const [selectedGoal, setSelectedGoal] = useState<Goal | null>(storybookGoals[1] ?? null);
+
+ return (
+ <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_320px]">
+ <div className="overflow-hidden rounded-lg border border-border bg-background">
+ <GoalTree
+ goals={storybookGoals}
+ onSelect={setSelectedGoal}
+ />
+ </div>
+ <div className="rounded-lg border border-border bg-background p-4">
+ <div className="paperclip-story__label">Selected goal</div>
+ {selectedGoal ? (
+ <div className="mt-3 space-y-3">
+ <div>
+ <div className="text-sm font-medium">{selectedGoal.title}</div>
+ <div className="mt-1 text-xs text-muted-foreground">{selectedGoal.description}</div>
+ </div>
+ <GoalProgressRow goal={selectedGoal} />
+ </div>
+ ) : (
+ <p className="mt-3 text-sm text-muted-foreground">Select a goal row to inspect its progress state.</p>
+ )}
+ </div>
+ </div>
+ );
+}
+
+function RuntimeControlsMatrix() {
+ const primaryWorkspace = storybookProjectWorkspaces[0]!;
+ const remoteWorkspace = storybookProjectWorkspaces.find((workspace) => workspace.id === "workspace-docs-remote")!;
+ const runningSections = buildWorkspaceRuntimeControlSections({
+ runtimeConfig: primaryWorkspace.runtimeConfig?.workspaceRuntime,
+ runtimeServices: primaryWorkspace.runtimeServices,
+ canStartServices: true,
+ canRunJobs: true,
+ });
+ const stoppedSections = buildWorkspaceRuntimeControlSections({
+ runtimeConfig: remoteWorkspace.runtimeConfig?.workspaceRuntime,
+ runtimeServices: remoteWorkspace.runtimeServices,
+ canStartServices: true,
+ canRunJobs: true,
+ });
+ const disabledSections = buildWorkspaceRuntimeControlSections({
+ runtimeConfig: {
+ commands: [
+ { id: "web", name: "Web app", kind: "service", command: "pnpm dev" },
+ { id: "migrate", name: "Migrate database", kind: "job", command: "pnpm db:migrate" },
+ ],
+ },
+ runtimeServices: [],
+ canStartServices: false,
+ canRunJobs: false,
+ });
+ const pendingRequest: WorkspaceRuntimeControlRequest = {
+ action: "restart",
+ workspaceCommandId: "storybook",
+ runtimeServiceId: "service-storybook",
+ serviceIndex: 0,
+ };
+
+ return (
+ <div className="grid gap-5 xl:grid-cols-3">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <Square className="h-4 w-4" />
+ Running services
+ </CardTitle>
+ <CardDescription>Stop and restart actions with a pending request spinner.</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <WorkspaceRuntimeControls
+ sections={runningSections}
+ isPending
+ pendingRequest={pendingRequest}
+ onAction={() => undefined}
+ />
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <Play className="h-4 w-4" />
+ Stopped remote preview
+ </CardTitle>
+ <CardDescription>Startable remote workspace service with URL history.</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <WorkspaceRuntimeControls sections={stoppedSections} onAction={() => undefined} />
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <RotateCcw className="h-4 w-4" />
+ Missing prerequisites
+ </CardTitle>
+ <CardDescription>Disabled runtime controls when no workspace path is available.</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <WorkspaceRuntimeControls
+ sections={disabledSections}
+ disabledHint="Add a workspace path before starting runtime services."
+ square
+ onAction={() => undefined}
+ />
+ </CardContent>
+ </Card>
+ </div>
+ );
+}
+
+function setWorktreeMeta(name: string, content: string) {
+ if (typeof document === "undefined") return;
+ let element = document.querySelector(`meta[name="${name}"]`);
+ if (!element) {
+ element = document.createElement("meta");
+ element.setAttribute("name", name);
+ document.head.appendChild(element);
+ }
+ element.setAttribute("content", content);
+}
+
+function WorktreeBannerMatrix() {
+ setWorktreeMeta("paperclip-worktree-enabled", "true");
+ setWorktreeMeta("paperclip-worktree-name", "PAP-1675-projects-goals-workspaces");
+ setWorktreeMeta("paperclip-worktree-color", "#0f766e");
+ setWorktreeMeta("paperclip-worktree-text-color", "#ecfeff");
+
+ return (
+ <div className="space-y-4">
+ <div className="overflow-hidden rounded-lg border border-border bg-background">
+ <WorktreeBanner />
+ </div>
+ <div className="grid gap-3 md:grid-cols-3">
+ {[
+ { label: "Branch", value: "PAP-1675-projects-goals-workspaces", icon: GitBranch },
+ { label: "Workspace", value: "Project Storybook worktree", icon: FolderGit2 },
+ { label: "Context", value: "visible before layout chrome", icon: Boxes },
+ ].map((item) => {
+ const Icon = item.icon;
+ return (
+ <div key={item.label} className="rounded-lg border border-border bg-background p-4">
+ <Icon className="h-4 w-4 text-muted-foreground" />
+ <div className="mt-3 text-xs uppercase tracking-[0.14em] text-muted-foreground">{item.label}</div>
+ <div className="mt-1 break-all font-mono text-xs">{item.value}</div>
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
+
+function ProjectsGoalsWorkspacesStories() {
+ return (
+ <StorybookData>
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner 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">Projects, goals, and workspaces</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Hierarchical planning and runtime surfaces</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ Fixture-backed project and goal stories cover editable project properties, local and remote workspace
+ cards, cleanup failures, goal hierarchy states, and runtime command controls.
+ </p>
+ </div>
+ <div className="flex flex-wrap gap-2">
+ <Badge variant="outline">active</Badge>
+ <Badge variant="outline">archived</Badge>
+ <Badge variant="outline">local workspace</Badge>
+ <Badge variant="outline">remote workspace</Badge>
+ </div>
+ </div>
+ </section>
+
+ <Section eyebrow="ProjectProperties" title="Full project detail panels with codebase, goals, env, and archive states">
+ <ProjectPropertiesMatrix />
+ </Section>
+
+ <Section eyebrow="ProjectWorkspacesContent" title="Workspace list with local, remote, cleanup-failed, and empty states">
+ <WorkspacesMatrix />
+ </Section>
+
+ <Section eyebrow="GoalProperties" title="Goal detail panel with progress and child goal context">
+ <GoalPropertiesMatrix />
+ </Section>
+
+ <Section eyebrow="GoalTree" title="Hierarchical goal tree with expand/collapse and progress sidecar">
+ <GoalTreeMatrix />
+ </Section>
+
+ <Section eyebrow="WorkspaceRuntimeControls" title="Runtime start, stop, restart, and disabled command states">
+ <RuntimeControlsMatrix />
+ </Section>
+
+ <Section eyebrow="WorktreeBanner" title="Worktree context banner with branch identity">
+ <WorktreeBannerMatrix />
+ </Section>
+ </main>
+ </div>
+ </StorybookData>
+ );
+}
+
+const meta = {
+ title: "Product/Projects Goals Workspaces",
+ component: ProjectsGoalsWorkspacesStories,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Projects, goals, and workspaces stories cover project properties, workspace cards/lists, goal hierarchy panels, runtime controls, and worktree branding states.",
+ },
+ },
+ },
+} satisfies Meta<typeof ProjectsGoalsWorkspacesStories>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const SurfaceMatrix: Story = {};
diff --git a/ui/storybook/stories/status-language.stories.tsx b/ui/storybook/stories/status-language.stories.tsx
new file mode 100644
index 0000000000..5c0e207db9
--- /dev/null
+++ b/ui/storybook/stories/status-language.stories.tsx
@@ -0,0 +1,211 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AGENT_STATUSES, ISSUE_PRIORITIES, ISSUE_STATUSES } from "@paperclipai/shared";
+import { Bot, CheckCircle2, Clock3, DollarSign, FolderKanban, Inbox, MessageSquare, Users } from "lucide-react";
+import { CopyText } from "@/components/CopyText";
+import { EmptyState } from "@/components/EmptyState";
+import { Identity } from "@/components/Identity";
+import { MetricCard } from "@/components/MetricCard";
+import { PriorityIcon } from "@/components/PriorityIcon";
+import { QuotaBar } from "@/components/QuotaBar";
+import { StatusBadge } from "@/components/StatusBadge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+
+function Section({
+ eyebrow,
+ title,
+ children,
+}: {
+ eyebrow: string;
+ title: string;
+ children: React.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 StatusLanguage() {
+ const [priority, setPriority] = useState("high");
+
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner space-y-6">
+ <section className="paperclip-story__frame p-6">
+ <div className="paperclip-story__label">Language</div>
+ <h1 className="mt-2 text-3xl font-semibold tracking-tight">Status, priority, identity, and metrics</h1>
+ <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+ These components carry the operational vocabulary of the board: who is acting, what state work is in,
+ how urgent it is, and whether capacity or spend needs attention.
+ </p>
+ </section>
+
+ <Section eyebrow="Lifecycle" title="Issue and agent statuses">
+ <div className="grid gap-4 md:grid-cols-2">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Issue statuses</CardTitle>
+ <CardDescription>Every task transition state in the V1 issue lifecycle.</CardDescription>
+ </CardHeader>
+ <CardContent className="flex flex-wrap gap-2">
+ {ISSUE_STATUSES.map((status) => (
+ <StatusBadge key={status} status={status} />
+ ))}
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Agent statuses</CardTitle>
+ <CardDescription>Runtime and governance states shown in org, sidebar, and detail surfaces.</CardDescription>
+ </CardHeader>
+ <CardContent className="flex flex-wrap gap-2">
+ {AGENT_STATUSES.map((status) => (
+ <StatusBadge key={status} status={status} />
+ ))}
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+
+ <Section eyebrow="Priority" title="Static labels and editable popover trigger">
+ <div className="grid gap-4 lg:grid-cols-[1fr_320px]">
+ <div className="grid gap-3 sm:grid-cols-2">
+ {ISSUE_PRIORITIES.map((item) => (
+ <div key={item} className="flex items-center justify-between rounded-lg border border-border bg-background/70 p-4">
+ <PriorityIcon priority={item} showLabel />
+ <span className="font-mono text-xs text-muted-foreground">{item}</span>
+ </div>
+ ))}
+ </div>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Editable priority</CardTitle>
+ <CardDescription>Click the control to inspect the same popover used in issue rows.</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <PriorityIcon priority={priority} onChange={setPriority} showLabel />
+ <div className="mt-3 text-xs text-muted-foreground">Current value: {priority}</div>
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+
+ <Section eyebrow="Identity" title="Agent and user chips">
+ <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>XS</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <Identity name="CodexCoder" size="xs" />
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Small</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <Identity name="Board User" size="sm" initials="BU" />
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Default</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <Identity name="DesignSystemCoder" />
+ </CardContent>
+ </Card>
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Long label</CardTitle>
+ </CardHeader>
+ <CardContent className="max-w-[220px]">
+ <Identity name="Senior Product Engineering Reviewer" size="lg" />
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+
+ <Section eyebrow="Dashboard" title="Metrics, quota bars, empty states, and copy affordances">
+ <div className="grid gap-5 xl:grid-cols-[minmax(0,1fr)_360px]">
+ <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-4">
+ <MetricCard icon={Users} value={8} label="Active agents" description="3 running right now" to="/agents/active" />
+ <MetricCard icon={FolderKanban} value={27} label="Open issues" description="5 in review" to="/issues" />
+ <MetricCard icon={DollarSign} value="$675" label="MTD spend" description="27% of budget" to="/costs" />
+ <MetricCard icon={Clock3} value="14m" label="P95 run age" description="last 24 hours" />
+ </div>
+
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Copyable identifiers</CardTitle>
+ <CardDescription>Click values to exercise the status tooltip.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-2 text-sm">
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Issue</span>
+ <CopyText text="PAP-1641" className="font-mono">PAP-1641</CopyText>
+ </div>
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">Run</span>
+ <CopyText text="49442f05-f1c1-45c5-88d3-1e5b871dbb8b" className="font-mono">
+ 49442f05
+ </CopyText>
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+
+ <div className="mt-5 grid gap-5 lg:grid-cols-[minmax(0,1fr)_360px]">
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Quota thresholds</CardTitle>
+ <CardDescription>Green, warning, and hard-stop-adjacent progress treatments.</CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-5">
+ <QuotaBar label="Company budget" percentUsed={27} leftLabel="$675 used" rightLabel="$2,500 cap" />
+ <QuotaBar label="Project budget" percentUsed={86} leftLabel="$1,031 used" rightLabel="$1,200 cap" />
+ <QuotaBar label="Agent budget" percentUsed={108} leftLabel="$432 used" rightLabel="$400 cap" showDeficitNotch />
+ </CardContent>
+ </Card>
+
+ <Card className="shadow-none">
+ <CardHeader>
+ <CardTitle>Empty state</CardTitle>
+ <CardDescription>Used when a list has no meaningful rows yet.</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <EmptyState icon={Inbox} message="No assigned work is waiting in this queue." action="Create issue" onAction={() => undefined} />
+ </CardContent>
+ </Card>
+ </div>
+ </Section>
+ </main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "Foundations/Status Language",
+ component: StatusLanguage,
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "Status-language stories show the reusable operational labels, identity chips, metrics, and capacity indicators used throughout the board.",
+ },
+ },
+ },
+} satisfies Meta<typeof StatusLanguage>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const FullMatrix: Story = {};
diff --git a/ui/storybook/stories/ux-labs.stories.tsx b/ui/storybook/stories/ux-labs.stories.tsx
new file mode 100644
index 0000000000..e3c872fecc
--- /dev/null
+++ b/ui/storybook/stories/ux-labs.stories.tsx
@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { IssueChatUxLab } from "@/pages/IssueChatUxLab";
+import { InviteUxLab } from "@/pages/InviteUxLab";
+import { RunTranscriptUxLab } from "@/pages/RunTranscriptUxLab";
+
+function StoryFrame({ children }: { children: React.ReactNode }) {
+ return (
+ <div className="paperclip-story">
+ <main className="paperclip-story__inner">{children}</main>
+ </div>
+ );
+}
+
+const meta = {
+ title: "UX Labs/Converted Test Pages",
+ parameters: {
+ docs: {
+ description: {
+ component:
+ "The former in-app UX test routes are represented here as Storybook stories so fixture-backed review surfaces stay out of production routing.",
+ },
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const IssueChatReviewSurface: Story = {
+ name: "Issue Chat Review Surface",
+ render: () => (
+ <StoryFrame>
+ <IssueChatUxLab />
+ </StoryFrame>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "Exercises assistant-ui issue chat states: timeline events, live run stream, queued message, feedback controls, submitting bubble, empty state, and disabled composer.",
+ },
+ },
+ },
+};
+
+export const RunTranscriptFixtures: Story = {
+ name: "Run Transcript Fixtures",
+ render: () => (
+ <StoryFrame>
+ <RunTranscriptUxLab />
+ </StoryFrame>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "Exercises run transcript presentation across the run detail page, issue live widget, and dashboard card density.",
+ },
+ },
+ },
+};
+
+export const InviteAndAccessFlow: Story = {
+ name: "Invite And Access Flow",
+ render: () => (
+ <StoryFrame>
+ <InviteUxLab />
+ </StoryFrame>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "Exercises invitation and access UX states with fixture-backed role choices, landing frames, history, and failure treatments.",
+ },
+ },
+ },
+};
diff --git a/ui/tsconfig.json b/ui/tsconfig.json
index 32b378d226..521b07a356 100644
--- a/ui/tsconfig.json
+++ b/ui/tsconfig.json
@@ -17,5 +17,5 @@
"lexical": ["./node_modules/lexical/index.d.ts"]
}
},
- "include": ["src"]
+ "include": ["src", "storybook"]
}