merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/ui/src/pages/Activity.tsx

@@ -0,0 +1,140 @@
+import { useEffect, useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { activityApi } from "../api/activity";
+import { agentsApi } from "../api/agents";
+import { issuesApi } from "../api/issues";
+import { projectsApi } from "../api/projects";
+import { goalsApi } from "../api/goals";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { EmptyState } from "../components/EmptyState";
+import { ActivityRow } from "../components/ActivityRow";
+import { PageSkeleton } from "../components/PageSkeleton";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { History } from "lucide-react";
+import type { Agent } from "@paperclipai/shared";
+
+export function Activity() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const [filter, setFilter] = useState("all");
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Activity" }]);
+  }, [setBreadcrumbs]);
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: queryKeys.activity(selectedCompanyId!),
+    queryFn: () => activityApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: issues } = useQuery({
+    queryKey: queryKeys.issues.list(selectedCompanyId!),
+    queryFn: () => issuesApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: projects } = useQuery({
+    queryKey: queryKeys.projects.list(selectedCompanyId!),
+    queryFn: () => projectsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: goals } = useQuery({
+    queryKey: queryKeys.goals.list(selectedCompanyId!),
+    queryFn: () => goalsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const agentMap = useMemo(() => {
+    const map = new Map<string, Agent>();
+    for (const a of agents ?? []) map.set(a.id, a);
+    return map;
+  }, [agents]);
+
+  const entityNameMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const i of issues ?? []) map.set(`issue:${i.id}`, i.identifier ?? i.id.slice(0, 8));
+    for (const a of agents ?? []) map.set(`agent:${a.id}`, a.name);
+    for (const p of projects ?? []) map.set(`project:${p.id}`, p.name);
+    for (const g of goals ?? []) map.set(`goal:${g.id}`, g.title);
+    return map;
+  }, [issues, agents, projects, goals]);
+
+  const entityTitleMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const i of issues ?? []) map.set(`issue:${i.id}`, i.title);
+    return map;
+  }, [issues]);
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={History} message="Select a company to view activity." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  const filtered =
+    data && filter !== "all"
+      ? data.filter((e) => e.entityType === filter)
+      : data;
+
+  const entityTypes = data
+    ? [...new Set(data.map((e) => e.entityType))].sort()
+    : [];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-end">
+        <Select value={filter} onValueChange={setFilter}>
+          <SelectTrigger className="w-[140px] h-8 text-xs">
+            <SelectValue placeholder="Filter by type" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All types</SelectItem>
+            {entityTypes.map((type) => (
+              <SelectItem key={type} value={type}>
+                {type.charAt(0).toUpperCase() + type.slice(1)}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {filtered && filtered.length === 0 && (
+        <EmptyState icon={History} message="No activity yet." />
+      )}
+
+      {filtered && filtered.length > 0 && (
+        <div className="border border-border divide-y divide-border">
+          {filtered.map((event) => (
+            <ActivityRow
+              key={event.id}
+              event={event}
+              agentMap={agentMap}
+              entityNameMap={entityNameMap}
+              entityTitleMap={entityTitleMap}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Agents.tsx

@@ -0,0 +1,414 @@
+import { useState, useEffect, useMemo } from "react";
+import { Link, useNavigate, useLocation } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { agentsApi, type OrgNode } from "../api/agents";
+import { heartbeatsApi } from "../api/heartbeats";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useSidebar } from "../context/SidebarContext";
+import { queryKeys } from "../lib/queryKeys";
+import { StatusBadge } from "../components/StatusBadge";
+import { agentStatusDot, agentStatusDotDefault } from "../lib/status-colors";
+import { EntityRow } from "../components/EntityRow";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { relativeTime, cn, agentRouteRef, agentUrl } from "../lib/utils";
+import { PageTabBar } from "../components/PageTabBar";
+import { Tabs } from "@/components/ui/tabs";
+import { Button } from "@/components/ui/button";
+import { Bot, Plus, List, GitBranch, SlidersHorizontal } from "lucide-react";
+import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
+
+const adapterLabels: Record<string, string> = {
+  claude_local: "Claude",
+  codex_local: "Codex",
+  gemini_local: "Gemini",
+  opencode_local: "OpenCode",
+  cursor: "Cursor",
+  openclaw_gateway: "OpenClaw Gateway",
+  process: "Process",
+  http: "HTTP",
+};
+
+const roleLabels = AGENT_ROLE_LABELS as Record<string, string>;
+
+type FilterTab = "all" | "active" | "paused" | "error";
+
+function matchesFilter(status: string, tab: FilterTab, showTerminated: boolean): boolean {
+  if (status === "terminated") return showTerminated;
+  if (tab === "all") return true;
+  if (tab === "active") return status === "active" || status === "running" || status === "idle";
+  if (tab === "paused") return status === "paused";
+  if (tab === "error") return status === "error";
+  return true;
+}
+
+function filterAgents(agents: Agent[], tab: FilterTab, showTerminated: boolean): Agent[] {
+  return agents
+    .filter((a) => matchesFilter(a.status, tab, showTerminated))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function filterOrgTree(nodes: OrgNode[], tab: FilterTab, showTerminated: boolean): OrgNode[] {
+  return nodes
+    .reduce<OrgNode[]>((acc, node) => {
+      const filteredReports = filterOrgTree(node.reports, tab, showTerminated);
+      if (matchesFilter(node.status, tab, showTerminated) || filteredReports.length > 0) {
+        acc.push({ ...node, reports: filteredReports });
+      }
+      return acc;
+    }, [])
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function Agents() {
+  const { selectedCompanyId } = useCompany();
+  const { openNewAgent } = useDialog();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { isMobile } = useSidebar();
+  const pathSegment = location.pathname.split("/").pop() ?? "all";
+  const tab: FilterTab = (pathSegment === "all" || pathSegment === "active" || pathSegment === "paused" || pathSegment === "error") ? pathSegment : "all";
+  const [view, setView] = useState<"list" | "org">("org");
+  const forceListView = isMobile;
+  const effectiveView: "list" | "org" = forceListView ? "list" : view;
+  const [showTerminated, setShowTerminated] = useState(false);
+  const [filtersOpen, setFiltersOpen] = useState(false);
+
+  const { data: agents, isLoading, error } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: orgTree } = useQuery({
+    queryKey: queryKeys.org(selectedCompanyId!),
+    queryFn: () => agentsApi.org(selectedCompanyId!),
+    enabled: !!selectedCompanyId && effectiveView === "org",
+  });
+
+  const { data: runs } = useQuery({
+    queryKey: queryKeys.heartbeats(selectedCompanyId!),
+    queryFn: () => heartbeatsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+    refetchInterval: 15_000,
+  });
+
+  // Map agentId -> first live run + live run count
+  const liveRunByAgent = useMemo(() => {
+    const map = new Map<string, { runId: string; liveCount: number }>();
+    for (const r of runs ?? []) {
+      if (r.status !== "running" && r.status !== "queued") continue;
+      const existing = map.get(r.agentId);
+      if (existing) {
+        existing.liveCount += 1;
+        continue;
+      }
+      map.set(r.agentId, { runId: r.id, liveCount: 1 });
+    }
+    return map;
+  }, [runs]);
+
+  const agentMap = useMemo(() => {
+    const map = new Map<string, Agent>();
+    for (const a of agents ?? []) map.set(a.id, a);
+    return map;
+  }, [agents]);
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Agents" }]);
+  }, [setBreadcrumbs]);
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={Bot} message="Select a company to view agents." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  const filtered = filterAgents(agents ?? [], tab, showTerminated);
+  const filteredOrg = filterOrgTree(orgTree ?? [], tab, showTerminated);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <Tabs value={tab} onValueChange={(v) => navigate(`/agents/${v}`)}>
+          <PageTabBar
+            items={[
+              { value: "all", label: "All" },
+              { value: "active", label: "Active" },
+              { value: "paused", label: "Paused" },
+              { value: "error", label: "Error" },
+            ]}
+            value={tab}
+            onValueChange={(v) => navigate(`/agents/${v}`)}
+          />
+        </Tabs>
+        <div className="flex items-center gap-2">
+          {/* Filters */}
+          <div className="relative">
+            <button
+              className={cn(
+                "flex items-center gap-1.5 px-2 py-1.5 text-xs transition-colors border border-border",
+                filtersOpen || showTerminated ? "text-foreground bg-accent" : "text-muted-foreground hover:bg-accent/50"
+              )}
+              onClick={() => setFiltersOpen(!filtersOpen)}
+            >
+              <SlidersHorizontal className="h-3 w-3" />
+              Filters
+              {showTerminated && <span className="ml-0.5 px-1 bg-foreground/10 rounded text-[10px]">1</span>}
+            </button>
+            {filtersOpen && (
+              <div className="absolute right-0 top-full mt-1 z-50 w-48 border border-border bg-popover shadow-md p-1">
+                <button
+                  className="flex items-center gap-2 w-full px-2 py-1.5 text-xs text-left hover:bg-accent/50 transition-colors"
+                  onClick={() => setShowTerminated(!showTerminated)}
+                >
+                  <span className={cn(
+                    "flex items-center justify-center h-3.5 w-3.5 border border-border rounded-sm",
+                    showTerminated && "bg-foreground"
+                  )}>
+                    {showTerminated && <span className="text-background text-[10px] leading-none">&#10003;</span>}
+                  </span>
+                  Show terminated
+                </button>
+              </div>
+            )}
+          </div>
+          {/* View toggle */}
+          {!forceListView && (
+            <div className="flex items-center border border-border">
+              <button
+                className={cn(
+                  "p-1.5 transition-colors",
+                  effectiveView === "list" ? "bg-accent text-foreground" : "text-muted-foreground hover:bg-accent/50"
+                )}
+                onClick={() => setView("list")}
+              >
+                <List className="h-3.5 w-3.5" />
+              </button>
+              <button
+                className={cn(
+                  "p-1.5 transition-colors",
+                  effectiveView === "org" ? "bg-accent text-foreground" : "text-muted-foreground hover:bg-accent/50"
+                )}
+                onClick={() => setView("org")}
+              >
+                <GitBranch className="h-3.5 w-3.5" />
+              </button>
+            </div>
+          )}
+          <Button size="sm" variant="outline" onClick={openNewAgent}>
+            <Plus className="h-3.5 w-3.5 mr-1.5" />
+            New Agent
+          </Button>
+        </div>
+      </div>
+
+      {filtered.length > 0 && (
+        <p className="text-xs text-muted-foreground">{filtered.length} agent{filtered.length !== 1 ? "s" : ""}</p>
+      )}
+
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {agents && agents.length === 0 && (
+        <EmptyState
+          icon={Bot}
+          message="Create your first agent to get started."
+          action="New Agent"
+          onAction={openNewAgent}
+        />
+      )}
+
+      {/* List view */}
+      {effectiveView === "list" && filtered.length > 0 && (
+        <div className="border border-border">
+          {filtered.map((agent) => {
+            return (
+              <EntityRow
+                key={agent.id}
+                title={agent.name}
+                subtitle={`${roleLabels[agent.role] ?? agent.role}${agent.title ? ` - ${agent.title}` : ""}`}
+                to={agentUrl(agent)}
+                leading={
+                  <span className="relative flex h-2.5 w-2.5">
+                    <span
+                      className={`absolute inline-flex h-full w-full rounded-full ${agentStatusDot[agent.status] ?? agentStatusDotDefault}`}
+                    />
+                  </span>
+                }
+                trailing={
+                  <div className="flex items-center gap-3">
+                    <span className="sm:hidden">
+                      {liveRunByAgent.has(agent.id) ? (
+                        <LiveRunIndicator
+                          agentRef={agentRouteRef(agent)}
+                          runId={liveRunByAgent.get(agent.id)!.runId}
+                          liveCount={liveRunByAgent.get(agent.id)!.liveCount}
+                        />
+                      ) : (
+                        <StatusBadge status={agent.status} />
+                      )}
+                    </span>
+                    <div className="hidden sm:flex items-center gap-3">
+                      {liveRunByAgent.has(agent.id) && (
+                        <LiveRunIndicator
+                          agentRef={agentRouteRef(agent)}
+                          runId={liveRunByAgent.get(agent.id)!.runId}
+                          liveCount={liveRunByAgent.get(agent.id)!.liveCount}
+                        />
+                      )}
+                      <span className="text-xs text-muted-foreground font-mono w-14 text-right">
+                        {adapterLabels[agent.adapterType] ?? agent.adapterType}
+                      </span>
+                      <span className="text-xs text-muted-foreground w-16 text-right">
+                        {agent.lastHeartbeatAt ? relativeTime(agent.lastHeartbeatAt) : "—"}
+                      </span>
+                      <span className="w-20 flex justify-end">
+                        <StatusBadge status={agent.status} />
+                      </span>
+                    </div>
+                  </div>
+                }
+              />
+            );
+          })}
+        </div>
+      )}
+
+      {effectiveView === "list" && agents && agents.length > 0 && filtered.length === 0 && (
+        <p className="text-sm text-muted-foreground text-center py-8">
+          No agents match the selected filter.
+        </p>
+      )}
+
+      {/* Org chart view */}
+      {effectiveView === "org" && filteredOrg.length > 0 && (
+        <div className="border border-border py-1">
+          {filteredOrg.map((node) => (
+            <OrgTreeNode key={node.id} node={node} depth={0} agentMap={agentMap} liveRunByAgent={liveRunByAgent} />
+          ))}
+        </div>
+      )}
+
+      {effectiveView === "org" && orgTree && orgTree.length > 0 && filteredOrg.length === 0 && (
+        <p className="text-sm text-muted-foreground text-center py-8">
+          No agents match the selected filter.
+        </p>
+      )}
+
+      {effectiveView === "org" && orgTree && orgTree.length === 0 && (
+        <p className="text-sm text-muted-foreground text-center py-8">
+          No organizational hierarchy defined.
+        </p>
+      )}
+    </div>
+  );
+}
+
+function OrgTreeNode({
+  node,
+  depth,
+  agentMap,
+  liveRunByAgent,
+}: {
+  node: OrgNode;
+  depth: number;
+  agentMap: Map<string, Agent>;
+  liveRunByAgent: Map<string, { runId: string; liveCount: number }>;
+}) {
+  const agent = agentMap.get(node.id);
+
+  const statusColor = agentStatusDot[node.status] ?? agentStatusDotDefault;
+
+  return (
+    <div style={{ paddingLeft: depth * 24 }}>
+      <Link
+        to={agent ? agentUrl(agent) : `/agents/${node.id}`}
+        className="flex items-center gap-3 px-3 py-2 hover:bg-accent/30 transition-colors w-full text-left no-underline text-inherit"
+      >
+        <span className="relative flex h-2.5 w-2.5 shrink-0">
+          <span className={`absolute inline-flex h-full w-full rounded-full ${statusColor}`} />
+        </span>
+        <div className="flex-1 min-w-0">
+          <span className="text-sm font-medium">{node.name}</span>
+          <span className="text-xs text-muted-foreground ml-2">
+            {roleLabels[node.role] ?? node.role}
+            {agent?.title ? ` - ${agent.title}` : ""}
+          </span>
+        </div>
+        <div className="flex items-center gap-3 shrink-0">
+          <span className="sm:hidden">
+            {liveRunByAgent.has(node.id) ? (
+              <LiveRunIndicator
+                agentRef={agent ? agentRouteRef(agent) : node.id}
+                runId={liveRunByAgent.get(node.id)!.runId}
+                liveCount={liveRunByAgent.get(node.id)!.liveCount}
+              />
+            ) : (
+              <StatusBadge status={node.status} />
+            )}
+          </span>
+          <div className="hidden sm:flex items-center gap-3">
+            {liveRunByAgent.has(node.id) && (
+              <LiveRunIndicator
+                agentRef={agent ? agentRouteRef(agent) : node.id}
+                runId={liveRunByAgent.get(node.id)!.runId}
+                liveCount={liveRunByAgent.get(node.id)!.liveCount}
+              />
+            )}
+            {agent && (
+              <>
+                <span className="text-xs text-muted-foreground font-mono w-14 text-right">
+                  {adapterLabels[agent.adapterType] ?? agent.adapterType}
+                </span>
+                <span className="text-xs text-muted-foreground w-16 text-right">
+                  {agent.lastHeartbeatAt ? relativeTime(agent.lastHeartbeatAt) : "—"}
+                </span>
+              </>
+            )}
+            <span className="w-20 flex justify-end">
+              <StatusBadge status={node.status} />
+            </span>
+          </div>
+        </div>
+      </Link>
+      {node.reports && node.reports.length > 0 && (
+        <div className="border-l border-border/50 ml-4">
+          {node.reports.map((child) => (
+            <OrgTreeNode key={child.id} node={child} depth={depth + 1} agentMap={agentMap} liveRunByAgent={liveRunByAgent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function LiveRunIndicator({
+  agentRef,
+  runId,
+  liveCount,
+}: {
+  agentRef: string;
+  runId: string;
+  liveCount: number;
+}) {
+  return (
+    <Link
+      to={`/agents/${agentRef}/runs/${runId}`}
+      className="flex items-center gap-1.5 px-2 py-0.5 rounded-full bg-blue-500/10 hover:bg-blue-500/20 transition-colors no-underline"
+      onClick={(e) => e.stopPropagation()}
+    >
+      <span className="relative flex h-2 w-2">
+        <span className="animate-pulse absolute inline-flex h-full w-full rounded-full bg-blue-400 opacity-75" />
+        <span className="relative inline-flex rounded-full h-2 w-2 bg-blue-500" />
+      </span>
+      <span className="text-[11px] font-medium text-blue-600 dark:text-blue-400">
+        Live{liveCount > 1 ? ` (${liveCount})` : ""}
+      </span>
+    </Link>
+  );
+}

paperclip-reference/ui/src/pages/ApprovalDetail.tsx

@@ -0,0 +1,368 @@
+import { useEffect, useMemo, useState } from "react";
+import { Link, useNavigate, useParams, useSearchParams } from "@/lib/router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { approvalsApi } from "../api/approvals";
+import { agentsApi } from "../api/agents";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { StatusBadge } from "../components/StatusBadge";
+import { Identity } from "../components/Identity";
+import { approvalLabel, typeIcon, defaultTypeIcon, ApprovalPayloadRenderer } from "../components/ApprovalPayload";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { CheckCircle2, ChevronRight, Sparkles } from "lucide-react";
+import type { ApprovalComment } from "@paperclipai/shared";
+import { MarkdownBody } from "../components/MarkdownBody";
+
+export function ApprovalDetail() {
+  const { approvalId } = useParams<{ approvalId: string }>();
+  const { selectedCompanyId, setSelectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const queryClient = useQueryClient();
+  const [commentBody, setCommentBody] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [showRawPayload, setShowRawPayload] = useState(false);
+
+  const { data: approval, isLoading } = useQuery({
+    queryKey: queryKeys.approvals.detail(approvalId!),
+    queryFn: () => approvalsApi.get(approvalId!),
+    enabled: !!approvalId,
+  });
+  const resolvedCompanyId = approval?.companyId ?? selectedCompanyId;
+
+  const { data: comments } = useQuery({
+    queryKey: queryKeys.approvals.comments(approvalId!),
+    queryFn: () => approvalsApi.listComments(approvalId!),
+    enabled: !!approvalId,
+  });
+
+  const { data: linkedIssues } = useQuery({
+    queryKey: queryKeys.approvals.issues(approvalId!),
+    queryFn: () => approvalsApi.listIssues(approvalId!),
+    enabled: !!approvalId,
+  });
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(resolvedCompanyId ?? ""),
+    queryFn: () => agentsApi.list(resolvedCompanyId ?? ""),
+    enabled: !!resolvedCompanyId,
+  });
+
+  useEffect(() => {
+    if (!approval?.companyId || approval.companyId === selectedCompanyId) return;
+    setSelectedCompanyId(approval.companyId, { source: "route_sync" });
+  }, [approval?.companyId, selectedCompanyId, setSelectedCompanyId]);
+
+  const agentNameById = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const agent of agents ?? []) map.set(agent.id, agent.name);
+    return map;
+  }, [agents]);
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Approvals", href: "/approvals" },
+      { label: approval?.id?.slice(0, 8) ?? approvalId ?? "Approval" },
+    ]);
+  }, [setBreadcrumbs, approval, approvalId]);
+
+  const refresh = () => {
+    if (!approvalId) return;
+    queryClient.invalidateQueries({ queryKey: queryKeys.approvals.detail(approvalId) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.approvals.comments(approvalId) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.approvals.issues(approvalId) });
+    if (approval?.companyId) {
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(approval.companyId) });
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.approvals.list(approval.companyId, "pending"),
+      });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(approval.companyId) });
+    }
+  };
+
+  const approveMutation = useMutation({
+    mutationFn: () => approvalsApi.approve(approvalId!),
+    onSuccess: () => {
+      setError(null);
+      refresh();
+      navigate(`/approvals/${approvalId}?resolved=approved`, { replace: true });
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Approve failed"),
+  });
+
+  const rejectMutation = useMutation({
+    mutationFn: () => approvalsApi.reject(approvalId!),
+    onSuccess: () => {
+      setError(null);
+      refresh();
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Reject failed"),
+  });
+
+  const revisionMutation = useMutation({
+    mutationFn: () => approvalsApi.requestRevision(approvalId!),
+    onSuccess: () => {
+      setError(null);
+      refresh();
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Revision request failed"),
+  });
+
+  const resubmitMutation = useMutation({
+    mutationFn: () => approvalsApi.resubmit(approvalId!),
+    onSuccess: () => {
+      setError(null);
+      refresh();
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Resubmit failed"),
+  });
+
+  const addCommentMutation = useMutation({
+    mutationFn: () => approvalsApi.addComment(approvalId!, commentBody.trim()),
+    onSuccess: () => {
+      setCommentBody("");
+      setError(null);
+      refresh();
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Comment failed"),
+  });
+
+  const deleteAgentMutation = useMutation({
+    mutationFn: (agentId: string) => agentsApi.remove(agentId),
+    onSuccess: () => {
+      setError(null);
+      refresh();
+      navigate("/approvals");
+    },
+    onError: (err) => setError(err instanceof Error ? err.message : "Delete failed"),
+  });
+
+  if (isLoading) return <PageSkeleton variant="detail" />;
+  if (!approval) return <p className="text-sm text-muted-foreground">Approval not found.</p>;
+
+  const payload = approval.payload as Record<string, unknown>;
+  const linkedAgentId = typeof payload.agentId === "string" ? payload.agentId : null;
+  const isActionable = approval.status === "pending" || approval.status === "revision_requested";
+  const isBudgetApproval = approval.type === "budget_override_required";
+  const TypeIcon = typeIcon[approval.type] ?? defaultTypeIcon;
+  const showApprovedBanner = searchParams.get("resolved") === "approved" && approval.status === "approved";
+  const primaryLinkedIssue = linkedIssues?.[0] ?? null;
+  const resolvedCta =
+    primaryLinkedIssue
+      ? {
+          label:
+            (linkedIssues?.length ?? 0) > 1
+              ? "Review linked issues"
+              : "Review linked issue",
+          to: `/issues/${primaryLinkedIssue.identifier ?? primaryLinkedIssue.id}`,
+        }
+      : linkedAgentId
+        ? {
+            label: "Open hired agent",
+            to: `/agents/${linkedAgentId}`,
+          }
+        : {
+            label: "Back to approvals",
+            to: "/approvals",
+          };
+
+  return (
+    <div className="space-y-6 max-w-3xl">
+      {showApprovedBanner && (
+        <div className="border border-green-300 dark:border-green-700/40 bg-green-50 dark:bg-green-900/20 rounded-lg px-4 py-3 animate-in fade-in zoom-in-95 duration-300">
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex items-start gap-2">
+              <div className="relative mt-0.5">
+                <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-300" />
+                <Sparkles className="h-3 w-3 text-green-500 dark:text-green-200 absolute -right-2 -top-1 animate-pulse" />
+              </div>
+              <div>
+                <p className="text-sm text-green-800 dark:text-green-100 font-medium">Approval confirmed</p>
+                <p className="text-xs text-green-700 dark:text-green-200/90">
+                  Requesting agent was notified to review this approval and linked issues.
+                </p>
+              </div>
+            </div>
+            <Button
+              size="sm"
+              variant="outline"
+              className="border-green-400 dark:border-green-600/50 text-green-800 dark:text-green-100 hover:bg-green-100 dark:hover:bg-green-900/30"
+              onClick={() => navigate(resolvedCta.to)}
+            >
+              {resolvedCta.label}
+            </Button>
+          </div>
+        </div>
+      )}
+      <div className="border border-border rounded-lg p-4 space-y-3">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-2">
+            <TypeIcon className="h-5 w-5 text-muted-foreground shrink-0" />
+            <div>
+              <h2 className="text-lg font-semibold">{approvalLabel(approval.type, approval.payload as Record<string, unknown> | null)}</h2>
+              <p className="text-xs text-muted-foreground font-mono">{approval.id}</p>
+            </div>
+          </div>
+          <StatusBadge status={approval.status} />
+        </div>
+        <div className="text-sm space-y-1">
+          {approval.requestedByAgentId && (
+            <div className="flex items-center gap-2">
+              <span className="text-muted-foreground text-xs">Requested by</span>
+              <Identity
+                name={agentNameById.get(approval.requestedByAgentId) ?? approval.requestedByAgentId.slice(0, 8)}
+                size="sm"
+              />
+            </div>
+          )}
+          <ApprovalPayloadRenderer type={approval.type} payload={payload} />
+          <button
+            type="button"
+            className="flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground transition-colors mt-2"
+            onClick={() => setShowRawPayload((v) => !v)}
+          >
+            <ChevronRight className={`h-3 w-3 transition-transform ${showRawPayload ? "rotate-90" : ""}`} />
+            See full request
+          </button>
+          {showRawPayload && (
+            <pre className="text-xs bg-muted/40 rounded-md p-3 overflow-x-auto">
+              {JSON.stringify(payload, null, 2)}
+            </pre>
+          )}
+          {approval.decisionNote && (
+            <p className="text-xs text-muted-foreground">Decision note: {approval.decisionNote}</p>
+          )}
+        </div>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        {linkedIssues && linkedIssues.length > 0 && (
+          <div className="pt-2 border-t border-border/60">
+            <p className="text-xs text-muted-foreground mb-1.5">Linked Issues</p>
+            <div className="space-y-1.5">
+              {linkedIssues.map((issue) => (
+                <Link
+                  key={issue.id}
+                  to={`/issues/${issue.identifier ?? issue.id}`}
+                  className="block text-xs rounded border border-border/70 px-2 py-1.5 hover:bg-accent/20"
+                >
+                  <span className="font-mono text-muted-foreground mr-2">
+                    {issue.identifier ?? issue.id.slice(0, 8)}
+                  </span>
+                  <span>{issue.title}</span>
+                </Link>
+              ))}
+            </div>
+            <p className="text-[11px] text-muted-foreground mt-2">
+              Linked issues remain open until the requesting agent follows up and closes them.
+            </p>
+          </div>
+        )}
+        <div className="flex flex-wrap items-center gap-2">
+          {isActionable && !isBudgetApproval && (
+            <>
+              <Button
+                size="sm"
+                className="bg-green-700 hover:bg-green-600 text-white"
+                onClick={() => approveMutation.mutate()}
+                disabled={approveMutation.isPending}
+              >
+                Approve
+              </Button>
+              <Button
+                variant="destructive"
+                size="sm"
+                onClick={() => rejectMutation.mutate()}
+                disabled={rejectMutation.isPending}
+              >
+                Reject
+              </Button>
+            </>
+          )}
+          {isBudgetApproval && approval.status === "pending" && (
+            <p className="text-sm text-muted-foreground">
+              Resolve this budget stop from the budget controls on <Link to="/costs" className="underline underline-offset-2">/costs</Link>.
+            </p>
+          )}
+          {approval.status === "pending" && (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => revisionMutation.mutate()}
+              disabled={revisionMutation.isPending}
+            >
+              Request revision
+            </Button>
+          )}
+          {approval.status === "revision_requested" && (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => resubmitMutation.mutate()}
+              disabled={resubmitMutation.isPending}
+            >
+              Mark resubmitted
+            </Button>
+          )}
+          {approval.status === "rejected" && approval.type === "hire_agent" && linkedAgentId && (
+            <Button
+              size="sm"
+              variant="outline"
+              className="text-destructive border-destructive/40"
+              onClick={() => {
+                if (!window.confirm("Delete this disapproved agent? This cannot be undone.")) return;
+                deleteAgentMutation.mutate(linkedAgentId);
+              }}
+              disabled={deleteAgentMutation.isPending}
+            >
+              Delete disapproved agent
+            </Button>
+          )}
+        </div>
+      </div>
+
+      <div className="border border-border rounded-lg p-4 space-y-3">
+        <h3 className="text-sm font-medium">Comments ({comments?.length ?? 0})</h3>
+        <div className="space-y-2">
+          {(comments ?? []).map((comment: ApprovalComment) => (
+            <div key={comment.id} className="border border-border/60 rounded-md p-3">
+              <div className="flex items-center justify-between mb-1">
+                {comment.authorAgentId ? (
+                  <Link to={`/agents/${comment.authorAgentId}`} className="hover:underline">
+                    <Identity
+                      name={agentNameById.get(comment.authorAgentId) ?? comment.authorAgentId.slice(0, 8)}
+                      size="sm"
+                    />
+                  </Link>
+                ) : (
+                  <Identity name="Board" size="sm" />
+                )}
+                <span className="text-xs text-muted-foreground">
+                  {new Date(comment.createdAt).toLocaleString()}
+                </span>
+              </div>
+              <MarkdownBody className="text-sm">{comment.body}</MarkdownBody>
+            </div>
+          ))}
+        </div>
+        <Textarea
+          value={commentBody}
+          onChange={(e) => setCommentBody(e.target.value)}
+          placeholder="Add a comment..."
+          rows={3}
+        />
+        <div className="flex justify-end">
+          <Button
+            size="sm"
+            onClick={() => addCommentMutation.mutate()}
+            disabled={!commentBody.trim() || addCommentMutation.isPending}
+          >
+            {addCommentMutation.isPending ? "Posting…" : "Post comment"}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Approvals.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useState } from "react";
+import { useNavigate, useLocation } from "@/lib/router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { approvalsApi } from "../api/approvals";
+import { agentsApi } from "../api/agents";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { cn } from "../lib/utils";
+import { PageTabBar } from "../components/PageTabBar";
+import { Tabs } from "@/components/ui/tabs";
+import { ShieldCheck } from "lucide-react";
+import { ApprovalCard } from "../components/ApprovalCard";
+import { PageSkeleton } from "../components/PageSkeleton";
+
+type StatusFilter = "pending" | "all";
+
+export function Approvals() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const pathSegment = location.pathname.split("/").pop() ?? "pending";
+  const statusFilter: StatusFilter = pathSegment === "all" ? "all" : "pending";
+  const [actionError, setActionError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Approvals" }]);
+  }, [setBreadcrumbs]);
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: queryKeys.approvals.list(selectedCompanyId!),
+    queryFn: () => approvalsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const approveMutation = useMutation({
+    mutationFn: (id: string) => approvalsApi.approve(id),
+    onSuccess: (_approval, id) => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(selectedCompanyId!) });
+      navigate(`/approvals/${id}?resolved=approved`);
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to approve");
+    },
+  });
+
+  const rejectMutation = useMutation({
+    mutationFn: (id: string) => approvalsApi.reject(id),
+    onSuccess: () => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(selectedCompanyId!) });
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to reject");
+    },
+  });
+
+  const filtered = (data ?? [])
+    .filter(
+      (a) => statusFilter === "all" || a.status === "pending" || a.status === "revision_requested",
+    )
+    .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+
+  const pendingCount = (data ?? []).filter(
+    (a) => a.status === "pending" || a.status === "revision_requested",
+  ).length;
+
+  if (!selectedCompanyId) {
+    return <p className="text-sm text-muted-foreground">Select a company first.</p>;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="approvals" />;
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <Tabs value={statusFilter} onValueChange={(v) => navigate(`/approvals/${v}`)}>
+          <PageTabBar items={[
+            { value: "pending", label: <>Pending{pendingCount > 0 && (
+              <span className={cn(
+                "ml-1.5 rounded-full px-1.5 py-0.5 text-[10px] font-medium",
+                "bg-yellow-500/20 text-yellow-500"
+              )}>
+                {pendingCount}
+              </span>
+            )}</> },
+            { value: "all", label: "All" },
+          ]} />
+        </Tabs>
+      </div>
+
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+      {actionError && <p className="text-sm text-destructive">{actionError}</p>}
+
+      {filtered.length === 0 && (
+        <div className="flex flex-col items-center justify-center py-16 text-center">
+          <ShieldCheck className="h-8 w-8 text-muted-foreground/30 mb-3" />
+          <p className="text-sm text-muted-foreground">
+            {statusFilter === "pending" ? "No pending approvals." : "No approvals yet."}
+          </p>
+        </div>
+      )}
+
+      {filtered.length > 0 && (
+        <div className="grid gap-3">
+          {filtered.map((approval) => (
+            <ApprovalCard
+              key={approval.id}
+              approval={approval}
+              requesterAgent={approval.requestedByAgentId ? (agents ?? []).find((a) => a.id === approval.requestedByAgentId) ?? null : null}
+              onApprove={() => approveMutation.mutate(approval.id)}
+              onReject={() => rejectMutation.mutate(approval.id)}
+              detailLink={`/approvals/${approval.id}`}
+              isPending={approveMutation.isPending || rejectMutation.isPending}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Auth.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useSearchParams } from "@/lib/router";
+import { authApi } from "../api/auth";
+import { queryKeys } from "../lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { AsciiArtAnimation } from "@/components/AsciiArtAnimation";
+import { Sparkles } from "lucide-react";
+
+type AuthMode = "sign_in" | "sign_up";
+
+export function AuthPage() {
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const [mode, setMode] = useState<AuthMode>("sign_in");
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  const nextPath = useMemo(() => searchParams.get("next") || "/", [searchParams]);
+  const { data: session, isLoading: isSessionLoading } = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+    retry: false,
+  });
+
+  useEffect(() => {
+    if (session) {
+      navigate(nextPath, { replace: true });
+    }
+  }, [session, navigate, nextPath]);
+
+  const mutation = useMutation({
+    mutationFn: async () => {
+      if (mode === "sign_in") {
+        await authApi.signInEmail({ email: email.trim(), password });
+        return;
+      }
+      await authApi.signUpEmail({
+        name: name.trim(),
+        email: email.trim(),
+        password,
+      });
+    },
+    onSuccess: async () => {
+      setError(null);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      navigate(nextPath, { replace: true });
+    },
+    onError: (err) => {
+      setError(err instanceof Error ? err.message : "Authentication failed");
+    },
+  });
+
+  const canSubmit =
+    email.trim().length > 0 &&
+    password.trim().length > 0 &&
+    (mode === "sign_in" || (name.trim().length > 0 && password.trim().length >= 8));
+
+  if (isSessionLoading) {
+    return (
+      <div className="fixed inset-0 flex items-center justify-center">
+        <p className="text-sm text-muted-foreground">Loading…</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="fixed inset-0 flex bg-background">
+      {/* Left half — form */}
+      <div className="w-full md:w-1/2 flex flex-col overflow-y-auto">
+        <div className="w-full max-w-md mx-auto my-auto px-8 py-12">
+          <div className="flex items-center gap-2 mb-8">
+            <Sparkles className="h-4 w-4 text-muted-foreground" />
+            <span className="text-sm font-medium">Paperclip</span>
+          </div>
+
+          <h1 className="text-xl font-semibold">
+            {mode === "sign_in" ? "Sign in to Paperclip" : "Create your Paperclip account"}
+          </h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            {mode === "sign_in"
+              ? "Use your email and password to access this instance."
+              : "Create an account for this instance. Email confirmation is not required in v1."}
+          </p>
+
+          <form
+            className="mt-6 space-y-4"
+            method="post"
+            action={mode === "sign_up" ? "/api/auth/sign-up/email" : "/api/auth/sign-in/email"}
+            onSubmit={(event) => {
+              event.preventDefault();
+              if (mutation.isPending) return;
+              if (!canSubmit) {
+                setError("Please fill in all required fields.");
+                return;
+              }
+              mutation.mutate();
+            }}
+          >
+            {mode === "sign_up" && (
+              <div>
+                <label htmlFor="name" className="text-xs text-muted-foreground mb-1 block">Name</label>
+                <input
+                  id="name"
+                  name="name"
+                  className="w-full rounded-md border border-border bg-transparent px-3 py-2 text-sm outline-none focus:ring-1 focus:ring-ring placeholder:text-muted-foreground/50"
+                  value={name}
+                  onChange={(event) => setName(event.target.value)}
+                  autoComplete="name"
+                  autoFocus
+                />
+              </div>
+            )}
+            <div>
+              <label htmlFor="email" className="text-xs text-muted-foreground mb-1 block">Email</label>
+              <input
+                id="email"
+                name="email"
+                className="w-full rounded-md border border-border bg-transparent px-3 py-2 text-sm outline-none focus:ring-1 focus:ring-ring placeholder:text-muted-foreground/50"
+                type="email"
+                value={email}
+                onChange={(event) => setEmail(event.target.value)}
+                autoComplete="email"
+                autoFocus={mode === "sign_in"}
+              />
+            </div>
+            <div>
+              <label htmlFor="password" className="text-xs text-muted-foreground mb-1 block">Password</label>
+              <input
+                id="password"
+                name="password"
+                className="w-full rounded-md border border-border bg-transparent px-3 py-2 text-sm outline-none focus:ring-1 focus:ring-ring placeholder:text-muted-foreground/50"
+                type="password"
+                value={password}
+                onChange={(event) => setPassword(event.target.value)}
+                autoComplete={mode === "sign_in" ? "current-password" : "new-password"}
+              />
+            </div>
+            {error && <p className="text-xs text-destructive">{error}</p>}
+            <Button
+              type="submit"
+              disabled={mutation.isPending}
+              aria-disabled={!canSubmit || mutation.isPending}
+              className={`w-full ${!canSubmit && !mutation.isPending ? "opacity-50" : ""}`}
+            >
+              {mutation.isPending
+                ? "Working…"
+                : mode === "sign_in"
+                  ? "Sign In"
+                  : "Create Account"}
+            </Button>
+          </form>
+
+          <div className="mt-5 text-sm text-muted-foreground">
+            {mode === "sign_in" ? "Need an account?" : "Already have an account?"}{" "}
+            <button
+              type="button"
+              className="font-medium text-foreground underline underline-offset-2"
+              onClick={() => {
+                setError(null);
+                setMode(mode === "sign_in" ? "sign_up" : "sign_in");
+              }}
+            >
+              {mode === "sign_in" ? "Create one" : "Sign in"}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Right half — ASCII art animation (hidden on mobile) */}
+      <div className="hidden md:block w-1/2 overflow-hidden">
+        <AsciiArtAnimation />
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/BoardClaim.tsx

@@ -0,0 +1,125 @@
+import { useMemo } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Link, useParams, useSearchParams } from "@/lib/router";
+import { accessApi } from "../api/access";
+import { authApi } from "../api/auth";
+import { queryKeys } from "../lib/queryKeys";
+import { Button } from "@/components/ui/button";
+
+export function BoardClaimPage() {
+  const queryClient = useQueryClient();
+  const params = useParams();
+  const [searchParams] = useSearchParams();
+  const token = (params.token ?? "").trim();
+  const code = (searchParams.get("code") ?? "").trim();
+  const currentPath = useMemo(
+    () => `/board-claim/${encodeURIComponent(token)}${code ? `?code=${encodeURIComponent(code)}` : ""}`,
+    [token, code],
+  );
+
+  const sessionQuery = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+    retry: false,
+  });
+  const statusQuery = useQuery({
+    queryKey: ["board-claim", token, code],
+    queryFn: () => accessApi.getBoardClaimStatus(token, code),
+    enabled: token.length > 0 && code.length > 0,
+    retry: false,
+  });
+
+  const claimMutation = useMutation({
+    mutationFn: () => accessApi.claimBoard(token, code),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.health });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.stats });
+      await statusQuery.refetch();
+    },
+  });
+
+  if (!token || !code) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-destructive">Invalid board claim URL.</div>;
+  }
+
+  if (statusQuery.isLoading || sessionQuery.isLoading) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading claim challenge...</div>;
+  }
+
+  if (statusQuery.error) {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Claim challenge unavailable</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            {statusQuery.error instanceof Error ? statusQuery.error.message : "Challenge is invalid or expired."}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const status = statusQuery.data;
+  if (!status) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-destructive">Claim challenge unavailable.</div>;
+  }
+
+  if (status.status === "claimed") {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Board ownership claimed</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            This instance is now linked to your authenticated user.
+          </p>
+          <Button asChild className="mt-4">
+            <Link to="/">Open board</Link>
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  if (!sessionQuery.data) {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Sign in required</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Sign in or create an account, then return to this page to claim Board ownership.
+          </p>
+          <Button asChild className="mt-4">
+            <Link to={`/auth?next=${encodeURIComponent(currentPath)}`}>Sign in / Create account</Link>
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">
+        <h1 className="text-xl font-semibold">Claim Board ownership</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          This will promote your user to instance admin and migrate company ownership access from local trusted mode.
+        </p>
+
+        {claimMutation.error && (
+          <p className="mt-3 text-sm text-destructive">
+            {claimMutation.error instanceof Error ? claimMutation.error.message : "Failed to claim board ownership"}
+          </p>
+        )}
+
+        <Button
+          className="mt-5"
+          onClick={() => claimMutation.mutate()}
+          disabled={claimMutation.isPending}
+        >
+          {claimMutation.isPending ? "Claiming…" : "Claim ownership"}
+        </Button>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/CliAuth.tsx

@@ -0,0 +1,184 @@
+import { useMemo } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Link, useParams, useSearchParams } from "@/lib/router";
+import { Button } from "@/components/ui/button";
+import { accessApi } from "../api/access";
+import { authApi } from "../api/auth";
+import { queryKeys } from "../lib/queryKeys";
+
+export function CliAuthPage() {
+  const queryClient = useQueryClient();
+  const params = useParams();
+  const [searchParams] = useSearchParams();
+  const challengeId = (params.id ?? "").trim();
+  const token = (searchParams.get("token") ?? "").trim();
+  const currentPath = useMemo(
+    () => `/cli-auth/${encodeURIComponent(challengeId)}${token ? `?token=${encodeURIComponent(token)}` : ""}`,
+    [challengeId, token],
+  );
+
+  const sessionQuery = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+    retry: false,
+  });
+  const challengeQuery = useQuery({
+    queryKey: ["cli-auth-challenge", challengeId, token],
+    queryFn: () => accessApi.getCliAuthChallenge(challengeId, token),
+    enabled: challengeId.length > 0 && token.length > 0,
+    retry: false,
+  });
+
+  const approveMutation = useMutation({
+    mutationFn: () => accessApi.approveCliAuthChallenge(challengeId, token),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
+      await challengeQuery.refetch();
+    },
+  });
+
+  const cancelMutation = useMutation({
+    mutationFn: () => accessApi.cancelCliAuthChallenge(challengeId, token),
+    onSuccess: async () => {
+      await challengeQuery.refetch();
+    },
+  });
+
+  if (!challengeId || !token) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-destructive">Invalid CLI auth URL.</div>;
+  }
+
+  if (sessionQuery.isLoading || challengeQuery.isLoading) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading CLI auth challenge...</div>;
+  }
+
+  if (challengeQuery.error) {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">CLI auth challenge unavailable</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            {challengeQuery.error instanceof Error ? challengeQuery.error.message : "Challenge is invalid or expired."}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const challenge = challengeQuery.data;
+  if (!challenge) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-destructive">CLI auth challenge unavailable.</div>;
+  }
+
+  if (challenge.status === "approved") {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-xl font-semibold">CLI access approved</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            The Paperclip CLI can now finish authentication on the requesting machine.
+          </p>
+          <p className="mt-4 text-sm text-muted-foreground">
+            Command: <span className="font-mono text-foreground">{challenge.command}</span>
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  if (challenge.status === "cancelled" || challenge.status === "expired") {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-xl font-semibold">
+            {challenge.status === "expired" ? "CLI auth challenge expired" : "CLI auth challenge cancelled"}
+          </h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Start the CLI auth flow again from your terminal to generate a new approval request.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  if (challenge.requiresSignIn || !sessionQuery.data) {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-xl font-semibold">Sign in required</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Sign in or create an account, then return to this page to approve the CLI access request.
+          </p>
+          <Button asChild className="mt-4">
+            <Link to={`/auth?next=${encodeURIComponent(currentPath)}`}>Sign in / Create account</Link>
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">
+        <h1 className="text-xl font-semibold">Approve Paperclip CLI access</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          A local Paperclip CLI process is requesting board access to this instance.
+        </p>
+
+        <div className="mt-5 space-y-3 text-sm">
+          <div>
+            <div className="text-muted-foreground">Command</div>
+            <div className="font-mono text-foreground">{challenge.command}</div>
+          </div>
+          <div>
+            <div className="text-muted-foreground">Client</div>
+            <div className="text-foreground">{challenge.clientName ?? "paperclipai cli"}</div>
+          </div>
+          <div>
+            <div className="text-muted-foreground">Requested access</div>
+            <div className="text-foreground">
+              {challenge.requestedAccess === "instance_admin_required" ? "Instance admin" : "Board"}
+            </div>
+          </div>
+          {challenge.requestedCompanyName && (
+            <div>
+              <div className="text-muted-foreground">Requested company</div>
+              <div className="text-foreground">{challenge.requestedCompanyName}</div>
+            </div>
+          )}
+        </div>
+
+        {(approveMutation.error || cancelMutation.error) && (
+          <p className="mt-4 text-sm text-destructive">
+            {(approveMutation.error ?? cancelMutation.error) instanceof Error
+              ? ((approveMutation.error ?? cancelMutation.error) as Error).message
+              : "Failed to update CLI auth challenge"}
+          </p>
+        )}
+
+        {!challenge.canApprove && (
+          <p className="mt-4 text-sm text-destructive">
+            This challenge requires instance-admin access. Sign in with an instance admin account to approve it.
+          </p>
+        )}
+
+        <div className="mt-5 flex gap-3">
+          <Button
+            onClick={() => approveMutation.mutate()}
+            disabled={!challenge.canApprove || approveMutation.isPending || cancelMutation.isPending}
+          >
+            {approveMutation.isPending ? "Approving..." : "Approve CLI access"}
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            onClick={() => cancelMutation.mutate()}
+            disabled={approveMutation.isPending || cancelMutation.isPending}
+          >
+            {cancelMutation.isPending ? "Cancelling..." : "Cancel"}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Companies.tsx

@@ -0,0 +1,297 @@
+import { useState, useEffect } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { companiesApi } from "../api/companies";
+import { queryKeys } from "../lib/queryKeys";
+import { formatCents, relativeTime } from "../lib/utils";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Pencil,
+  Check,
+  X,
+  Plus,
+  MoreHorizontal,
+  Trash2,
+  Users,
+  CircleDot,
+  DollarSign,
+  Calendar,
+} from "lucide-react";
+
+export function Companies() {
+  const {
+    companies,
+    selectedCompanyId,
+    setSelectedCompanyId,
+    loading,
+    error,
+  } = useCompany();
+  const { openOnboarding } = useDialog();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+
+  const { data: stats } = useQuery({
+    queryKey: queryKeys.companies.stats,
+    queryFn: () => companiesApi.stats(),
+  });
+
+  // Inline edit state
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editName, setEditName] = useState("");
+  const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
+
+  const editMutation = useMutation({
+    mutationFn: ({ id, newName }: { id: string; newName: string }) =>
+      companiesApi.update(id, { name: newName }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      setEditingId(null);
+    },
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: string) => companiesApi.remove(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.stats });
+      setConfirmDeleteId(null);
+    },
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Companies" }]);
+  }, [setBreadcrumbs]);
+
+  function startEdit(companyId: string, currentName: string) {
+    setEditingId(companyId);
+    setEditName(currentName);
+  }
+
+  function saveEdit() {
+    if (!editingId || !editName.trim()) return;
+    editMutation.mutate({ id: editingId, newName: editName.trim() });
+  }
+
+  function cancelEdit() {
+    setEditingId(null);
+    setEditName("");
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-end">
+        <Button size="sm" onClick={() => openOnboarding()}>
+          <Plus className="h-3.5 w-3.5 mr-1.5" />
+          New Company
+        </Button>
+      </div>
+
+      <div className="h-6">
+        {loading && <p className="text-sm text-muted-foreground">Loading companies...</p>}
+        {error && <p className="text-sm text-destructive">{error.message}</p>}
+      </div>
+
+      <div className="grid gap-4">
+        {companies.map((company) => {
+          const selected = company.id === selectedCompanyId;
+          const isEditing = editingId === company.id;
+          const isConfirmingDelete = confirmDeleteId === company.id;
+          const companyStats = stats?.[company.id];
+          const agentCount = companyStats?.agentCount ?? 0;
+          const issueCount = companyStats?.issueCount ?? 0;
+          const budgetPct =
+            company.budgetMonthlyCents > 0
+              ? Math.round(
+                  (company.spentMonthlyCents / company.budgetMonthlyCents) * 100,
+                )
+              : 0;
+
+          return (
+            <div
+              key={company.id}
+              role="button"
+              tabIndex={0}
+              onClick={() => setSelectedCompanyId(company.id)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" || e.key === " ") {
+                  e.preventDefault();
+                  setSelectedCompanyId(company.id);
+                }
+              }}
+              className={`group text-left bg-card border rounded-lg p-5 transition-colors cursor-pointer ${
+                selected
+                  ? "border-primary ring-1 ring-primary"
+                  : "border-border hover:border-muted-foreground/30"
+              }`}
+            >
+              {/* Header row: name + menu */}
+              <div className="flex items-start justify-between gap-3">
+                <div className="flex-1 min-w-0">
+                  {isEditing ? (
+                    <div
+                      className="flex items-center gap-2"
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      <Input
+                        value={editName}
+                        onChange={(e) => setEditName(e.target.value)}
+                        className="h-7 text-sm"
+                        autoFocus
+                        onKeyDown={(e) => {
+                          if (e.key === "Enter") saveEdit();
+                          if (e.key === "Escape") cancelEdit();
+                        }}
+                      />
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={saveEdit}
+                        disabled={editMutation.isPending}
+                      >
+                        <Check className="h-3.5 w-3.5 text-green-500" />
+                      </Button>
+                      <Button variant="ghost" size="icon-xs" onClick={cancelEdit}>
+                        <X className="h-3.5 w-3.5 text-muted-foreground" />
+                      </Button>
+                    </div>
+                  ) : (
+                    <div className="flex items-center gap-2">
+                      <h3 className="font-semibold text-base">{company.name}</h3>
+                      <span
+                        className={`inline-flex items-center rounded-full px-2 py-0.5 text-[11px] font-medium ${
+                          company.status === "active"
+                            ? "bg-green-500/10 text-green-600 dark:text-green-400"
+                            : company.status === "paused"
+                              ? "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400"
+                              : "bg-muted text-muted-foreground"
+                        }`}
+                      >
+                        {company.status}
+                      </span>
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        className="text-muted-foreground opacity-0 group-hover:opacity-100"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          startEdit(company.id, company.name);
+                        }}
+                      >
+                        <Pencil className="h-3 w-3" />
+                      </Button>
+                    </div>
+                  )}
+                  {company.description && !isEditing && (
+                    <p className="text-sm text-muted-foreground mt-1 line-clamp-2">
+                      {company.description}
+                    </p>
+                  )}
+                </div>
+
+                {/* Three-dot menu */}
+                <div onClick={(e) => e.stopPropagation()}>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        className="text-muted-foreground opacity-0 group-hover:opacity-100 data-[state=open]:opacity-100"
+                      >
+                        <MoreHorizontal className="h-4 w-4" />
+                      </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end">
+                      <DropdownMenuItem
+                        onClick={() => startEdit(company.id, company.name)}
+                      >
+                        <Pencil className="h-3.5 w-3.5" />
+                        Rename
+                      </DropdownMenuItem>
+                      <DropdownMenuSeparator />
+                      <DropdownMenuItem
+                        variant="destructive"
+                        onClick={() => setConfirmDeleteId(company.id)}
+                      >
+                        <Trash2 className="h-3.5 w-3.5" />
+                        Delete Company
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </div>
+              </div>
+
+              {/* Stats row */}
+              <div className="flex items-center gap-3 sm:gap-5 mt-4 text-sm text-muted-foreground flex-wrap">
+                <div className="flex items-center gap-1.5">
+                  <Users className="h-3.5 w-3.5" />
+                  <span>
+                    {agentCount} {agentCount === 1 ? "agent" : "agents"}
+                  </span>
+                </div>
+                <div className="flex items-center gap-1.5">
+                  <CircleDot className="h-3.5 w-3.5" />
+                  <span>
+                    {issueCount} {issueCount === 1 ? "issue" : "issues"}
+                  </span>
+                </div>
+                <div className="flex items-center gap-1.5 tabular-nums">
+                  <DollarSign className="h-3.5 w-3.5" />
+                  <span>
+                    {formatCents(company.spentMonthlyCents)}
+                    {company.budgetMonthlyCents > 0
+                      ? <> / {formatCents(company.budgetMonthlyCents)} <span className="text-xs">({budgetPct}%)</span></>
+                      : <span className="text-xs ml-1">Unlimited budget</span>}
+                  </span>
+                </div>
+                <div className="flex items-center gap-1.5 ml-auto">
+                  <Calendar className="h-3.5 w-3.5" />
+                  <span>Created {relativeTime(company.createdAt)}</span>
+                </div>
+              </div>
+
+              {/* Delete confirmation */}
+              {isConfirmingDelete && (
+                <div
+                  className="mt-4 flex items-center justify-between bg-destructive/5 border border-destructive/20 rounded-md px-4 py-3"
+                  onClick={(e) => e.stopPropagation()}
+                >
+                  <p className="text-sm text-destructive font-medium">
+                    Delete this company and all its data? This cannot be undone.
+                  </p>
+                  <div className="flex items-center gap-2 ml-4 shrink-0">
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => setConfirmDeleteId(null)}
+                      disabled={deleteMutation.isPending}
+                    >
+                      Cancel
+                    </Button>
+                    <Button
+                      variant="destructive"
+                      size="sm"
+                      onClick={() => deleteMutation.mutate(company.id)}
+                      disabled={deleteMutation.isPending}
+                    >
+                      {deleteMutation.isPending ? "Deleting…" : "Delete"}
+                    </Button>
+                  </div>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/CompanySettings.tsx

@@ -0,0 +1,661 @@
+import { ChangeEvent, useEffect, useState } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useToast } from "../context/ToastContext";
+import { companiesApi } from "../api/companies";
+import { accessApi } from "../api/access";
+import { assetsApi } from "../api/assets";
+import { queryKeys } from "../lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { Settings, Check, Download, Upload } from "lucide-react";
+import { CompanyPatternIcon } from "../components/CompanyPatternIcon";
+import {
+  Field,
+  ToggleField,
+  HintIcon
+} from "../components/agent-config-primitives";
+
+type AgentSnippetInput = {
+  onboardingTextUrl: string;
+  connectionCandidates?: string[] | null;
+  testResolutionUrl?: string | null;
+};
+
+export function CompanySettings() {
+  const {
+    companies,
+    selectedCompany,
+    selectedCompanyId,
+    setSelectedCompanyId
+  } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const { pushToast } = useToast();
+  const queryClient = useQueryClient();
+  // General settings local state
+  const [companyName, setCompanyName] = useState("");
+  const [description, setDescription] = useState("");
+  const [brandColor, setBrandColor] = useState("");
+  const [logoUrl, setLogoUrl] = useState("");
+  const [logoUploadError, setLogoUploadError] = useState<string | null>(null);
+
+  // Sync local state from selected company
+  useEffect(() => {
+    if (!selectedCompany) return;
+    setCompanyName(selectedCompany.name);
+    setDescription(selectedCompany.description ?? "");
+    setBrandColor(selectedCompany.brandColor ?? "");
+    setLogoUrl(selectedCompany.logoUrl ?? "");
+  }, [selectedCompany]);
+
+  const [inviteError, setInviteError] = useState<string | null>(null);
+  const [inviteSnippet, setInviteSnippet] = useState<string | null>(null);
+  const [snippetCopied, setSnippetCopied] = useState(false);
+  const [snippetCopyDelightId, setSnippetCopyDelightId] = useState(0);
+
+  const generalDirty =
+    !!selectedCompany &&
+    (companyName !== selectedCompany.name ||
+      description !== (selectedCompany.description ?? "") ||
+      brandColor !== (selectedCompany.brandColor ?? ""));
+
+  const generalMutation = useMutation({
+    mutationFn: (data: {
+      name: string;
+      description: string | null;
+      brandColor: string | null;
+    }) => companiesApi.update(selectedCompanyId!, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+    }
+  });
+
+  const settingsMutation = useMutation({
+    mutationFn: (requireApproval: boolean) =>
+      companiesApi.update(selectedCompanyId!, {
+        requireBoardApprovalForNewAgents: requireApproval
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+    }
+  });
+
+  const inviteMutation = useMutation({
+    mutationFn: () =>
+      accessApi.createOpenClawInvitePrompt(selectedCompanyId!),
+    onSuccess: async (invite) => {
+      setInviteError(null);
+      const base = window.location.origin.replace(/\/+$/, "");
+      const onboardingTextLink =
+        invite.onboardingTextUrl ??
+        invite.onboardingTextPath ??
+        `/api/invites/${invite.token}/onboarding.txt`;
+      const absoluteUrl = onboardingTextLink.startsWith("http")
+        ? onboardingTextLink
+        : `${base}${onboardingTextLink}`;
+      setSnippetCopied(false);
+      setSnippetCopyDelightId(0);
+      let snippet: string;
+      try {
+        const manifest = await accessApi.getInviteOnboarding(invite.token);
+        snippet = buildAgentSnippet({
+          onboardingTextUrl: absoluteUrl,
+          connectionCandidates:
+            manifest.onboarding.connectivity?.connectionCandidates ?? null,
+          testResolutionUrl:
+            manifest.onboarding.connectivity?.testResolutionEndpoint?.url ??
+            null
+        });
+      } catch {
+        snippet = buildAgentSnippet({
+          onboardingTextUrl: absoluteUrl,
+          connectionCandidates: null,
+          testResolutionUrl: null
+        });
+      }
+      setInviteSnippet(snippet);
+      try {
+        await navigator.clipboard.writeText(snippet);
+        setSnippetCopied(true);
+        setSnippetCopyDelightId((prev) => prev + 1);
+        setTimeout(() => setSnippetCopied(false), 2000);
+      } catch {
+        /* clipboard may not be available */
+      }
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.sidebarBadges(selectedCompanyId!)
+      });
+    },
+    onError: (err) => {
+      setInviteError(
+        err instanceof Error ? err.message : "Failed to create invite"
+      );
+    }
+  });
+
+  const syncLogoState = (nextLogoUrl: string | null) => {
+    setLogoUrl(nextLogoUrl ?? "");
+    void queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+  };
+
+  const logoUploadMutation = useMutation({
+    mutationFn: (file: File) =>
+      assetsApi
+        .uploadCompanyLogo(selectedCompanyId!, file)
+        .then((asset) => companiesApi.update(selectedCompanyId!, { logoAssetId: asset.assetId })),
+    onSuccess: (company) => {
+      syncLogoState(company.logoUrl);
+      setLogoUploadError(null);
+    }
+  });
+
+  const clearLogoMutation = useMutation({
+    mutationFn: () => companiesApi.update(selectedCompanyId!, { logoAssetId: null }),
+    onSuccess: (company) => {
+      setLogoUploadError(null);
+      syncLogoState(company.logoUrl);
+    }
+  });
+
+  function handleLogoFileChange(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0] ?? null;
+    event.currentTarget.value = "";
+    if (!file) return;
+    setLogoUploadError(null);
+    logoUploadMutation.mutate(file);
+  }
+
+  function handleClearLogo() {
+    clearLogoMutation.mutate();
+  }
+
+  useEffect(() => {
+    setInviteError(null);
+    setInviteSnippet(null);
+    setSnippetCopied(false);
+    setSnippetCopyDelightId(0);
+  }, [selectedCompanyId]);
+
+  const archiveMutation = useMutation({
+    mutationFn: ({
+      companyId,
+      nextCompanyId
+    }: {
+      companyId: string;
+      nextCompanyId: string | null;
+    }) => companiesApi.archive(companyId).then(() => ({ nextCompanyId })),
+    onSuccess: async ({ nextCompanyId }) => {
+      if (nextCompanyId) {
+        setSelectedCompanyId(nextCompanyId);
+      }
+      await queryClient.invalidateQueries({
+        queryKey: queryKeys.companies.all
+      });
+      await queryClient.invalidateQueries({
+        queryKey: queryKeys.companies.stats
+      });
+    }
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+      { label: "Settings" }
+    ]);
+  }, [setBreadcrumbs, selectedCompany?.name]);
+
+  if (!selectedCompany) {
+    return (
+      <div className="text-sm text-muted-foreground">
+        No company selected. Select a company from the switcher above.
+      </div>
+    );
+  }
+
+  function handleSaveGeneral() {
+    generalMutation.mutate({
+      name: companyName.trim(),
+      description: description.trim() || null,
+      brandColor: brandColor || null
+    });
+  }
+
+  return (
+    <div className="max-w-2xl space-y-6">
+      <div className="flex items-center gap-2">
+        <Settings className="h-5 w-5 text-muted-foreground" />
+        <h1 className="text-lg font-semibold">Company Settings</h1>
+      </div>
+
+      {/* General */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+          General
+        </div>
+        <div className="space-y-3 rounded-md border border-border px-4 py-4">
+          <Field label="Company name" hint="The display name for your company.">
+            <input
+              className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+              type="text"
+              value={companyName}
+              onChange={(e) => setCompanyName(e.target.value)}
+            />
+          </Field>
+          <Field
+            label="Description"
+            hint="Optional description shown in the company profile."
+          >
+            <input
+              className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+              type="text"
+              value={description}
+              placeholder="Optional company description"
+              onChange={(e) => setDescription(e.target.value)}
+            />
+          </Field>
+        </div>
+      </div>
+
+      {/* Appearance */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+          Appearance
+        </div>
+        <div className="space-y-3 rounded-md border border-border px-4 py-4">
+          <div className="flex items-start gap-4">
+            <div className="shrink-0">
+              <CompanyPatternIcon
+                companyName={companyName || selectedCompany.name}
+                logoUrl={logoUrl || null}
+                brandColor={brandColor || null}
+                className="rounded-[14px]"
+              />
+            </div>
+            <div className="flex-1 space-y-3">
+              <Field
+                label="Logo"
+                hint="Upload a PNG, JPEG, WEBP, GIF, or SVG logo image."
+              >
+                <div className="space-y-2">
+                  <input
+                    type="file"
+                    accept="image/png,image/jpeg,image/webp,image/gif,image/svg+xml"
+                    onChange={handleLogoFileChange}
+                    className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none file:mr-4 file:rounded-md file:border-0 file:bg-muted file:px-2.5 file:py-1 file:text-xs"
+                  />
+                  {logoUrl && (
+                    <div className="flex items-center gap-2">
+                      <Button
+                        size="sm"
+                        variant="outline"
+                        onClick={handleClearLogo}
+                        disabled={clearLogoMutation.isPending}
+                      >
+                        {clearLogoMutation.isPending ? "Removing..." : "Remove logo"}
+                      </Button>
+                    </div>
+                  )}
+                  {(logoUploadMutation.isError || logoUploadError) && (
+                    <span className="text-xs text-destructive">
+                      {logoUploadError ??
+                        (logoUploadMutation.error instanceof Error
+                          ? logoUploadMutation.error.message
+                          : "Logo upload failed")}
+                    </span>
+                  )}
+                  {clearLogoMutation.isError && (
+                    <span className="text-xs text-destructive">
+                      {clearLogoMutation.error.message}
+                    </span>
+                  )}
+                  {logoUploadMutation.isPending && (
+                    <span className="text-xs text-muted-foreground">Uploading logo...</span>
+                  )}
+                </div>
+              </Field>
+              <Field
+                label="Brand color"
+                hint="Sets the hue for the company icon. Leave empty for auto-generated color."
+              >
+                <div className="flex items-center gap-2">
+                  <input
+                    type="color"
+                    value={brandColor || "#6366f1"}
+                    onChange={(e) => setBrandColor(e.target.value)}
+                    className="h-8 w-8 cursor-pointer rounded border border-border bg-transparent p-0"
+                  />
+                  <input
+                    type="text"
+                    value={brandColor}
+                    onChange={(e) => {
+                      const v = e.target.value;
+                      if (v === "" || /^#[0-9a-fA-F]{0,6}$/.test(v)) {
+                        setBrandColor(v);
+                      }
+                    }}
+                    placeholder="Auto"
+                    className="w-28 rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm font-mono outline-none"
+                  />
+                  {brandColor && (
+                    <Button
+                      size="sm"
+                      variant="ghost"
+                      onClick={() => setBrandColor("")}
+                      className="text-xs text-muted-foreground"
+                    >
+                      Clear
+                    </Button>
+                  )}
+                </div>
+              </Field>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Save button for General + Appearance */}
+      {generalDirty && (
+        <div className="flex items-center gap-2">
+          <Button
+            size="sm"
+            onClick={handleSaveGeneral}
+            disabled={generalMutation.isPending || !companyName.trim()}
+          >
+            {generalMutation.isPending ? "Saving..." : "Save changes"}
+          </Button>
+          {generalMutation.isSuccess && (
+            <span className="text-xs text-muted-foreground">Saved</span>
+          )}
+          {generalMutation.isError && (
+            <span className="text-xs text-destructive">
+              {generalMutation.error instanceof Error
+                  ? generalMutation.error.message
+                  : "Failed to save"}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Hiring */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+          Hiring
+        </div>
+        <div className="rounded-md border border-border px-4 py-3">
+          <ToggleField
+            label="Require board approval for new hires"
+            hint="New agent hires stay pending until approved by board."
+            checked={!!selectedCompany.requireBoardApprovalForNewAgents}
+            onChange={(v) => settingsMutation.mutate(v)}
+          />
+        </div>
+      </div>
+
+      {/* Invites */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+          Invites
+        </div>
+        <div className="space-y-3 rounded-md border border-border px-4 py-4">
+          <div className="flex items-center gap-1.5">
+            <span className="text-xs text-muted-foreground">
+              Generate an OpenClaw agent invite snippet.
+            </span>
+            <HintIcon text="Creates a short-lived OpenClaw agent invite and renders a copy-ready prompt." />
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              size="sm"
+              onClick={() => inviteMutation.mutate()}
+              disabled={inviteMutation.isPending}
+            >
+              {inviteMutation.isPending
+                ? "Generating..."
+                : "Generate OpenClaw Invite Prompt"}
+            </Button>
+          </div>
+          {inviteError && (
+            <p className="text-sm text-destructive">{inviteError}</p>
+          )}
+          {inviteSnippet && (
+            <div className="rounded-md border border-border bg-muted/30 p-2">
+              <div className="flex items-center justify-between gap-2">
+                <div className="text-xs text-muted-foreground">
+                  OpenClaw Invite Prompt
+                </div>
+                {snippetCopied && (
+                  <span
+                    key={snippetCopyDelightId}
+                    className="flex items-center gap-1 text-xs text-green-600 animate-pulse"
+                  >
+                    <Check className="h-3 w-3" />
+                    Copied
+                  </span>
+                )}
+              </div>
+              <div className="mt-1 space-y-1.5">
+                <textarea
+                  className="h-[28rem] w-full rounded-md border border-border bg-background px-2 py-1.5 font-mono text-xs outline-none"
+                  value={inviteSnippet}
+                  readOnly
+                />
+                <div className="flex justify-end">
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    onClick={async () => {
+                      try {
+                        await navigator.clipboard.writeText(inviteSnippet);
+                        setSnippetCopied(true);
+                        setSnippetCopyDelightId((prev) => prev + 1);
+                        setTimeout(() => setSnippetCopied(false), 2000);
+                      } catch {
+                        /* clipboard may not be available */
+                      }
+                    }}
+                  >
+                    {snippetCopied ? "Copied snippet" : "Copy snippet"}
+                  </Button>
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Import / Export */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+          Company Packages
+        </div>
+        <div className="rounded-md border border-border px-4 py-4">
+          <p className="text-sm text-muted-foreground">
+            Import and export have moved to dedicated pages accessible from the{" "}
+            <a href="/org" className="underline hover:text-foreground">Org Chart</a> header.
+          </p>
+          <div className="mt-3 flex items-center gap-2">
+            <Button size="sm" variant="outline" asChild>
+              <a href="/company/export">
+                <Download className="mr-1.5 h-3.5 w-3.5" />
+                Export
+              </a>
+            </Button>
+            <Button size="sm" variant="outline" asChild>
+              <a href="/company/import">
+                <Upload className="mr-1.5 h-3.5 w-3.5" />
+                Import
+              </a>
+            </Button>
+          </div>
+        </div>
+      </div>
+
+      {/* Danger Zone */}
+      <div className="space-y-4">
+        <div className="text-xs font-medium text-destructive uppercase tracking-wide">
+          Danger Zone
+        </div>
+        <div className="space-y-3 rounded-md border border-destructive/40 bg-destructive/5 px-4 py-4">
+          <p className="text-sm text-muted-foreground">
+            Archive this company to hide it from the sidebar. This persists in
+            the database.
+          </p>
+          <div className="flex items-center gap-2">
+            <Button
+              size="sm"
+              variant="destructive"
+              disabled={
+                archiveMutation.isPending ||
+                selectedCompany.status === "archived"
+              }
+              onClick={() => {
+                if (!selectedCompanyId) return;
+                const confirmed = window.confirm(
+                  `Archive company "${selectedCompany.name}"? It will be hidden from the sidebar.`
+                );
+                if (!confirmed) return;
+                const nextCompanyId =
+                  companies.find(
+                    (company) =>
+                      company.id !== selectedCompanyId &&
+                      company.status !== "archived"
+                  )?.id ?? null;
+                archiveMutation.mutate({
+                  companyId: selectedCompanyId,
+                  nextCompanyId
+                });
+              }}
+            >
+              {archiveMutation.isPending
+                ? "Archiving..."
+                : selectedCompany.status === "archived"
+                ? "Already archived"
+                : "Archive company"}
+            </Button>
+            {archiveMutation.isError && (
+              <span className="text-xs text-destructive">
+                {archiveMutation.error instanceof Error
+                  ? archiveMutation.error.message
+                  : "Failed to archive company"}
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function buildAgentSnippet(input: AgentSnippetInput) {
+  const candidateUrls = buildCandidateOnboardingUrls(input);
+  const resolutionTestUrl = buildResolutionTestUrl(input);
+
+  const candidateList =
+    candidateUrls.length > 0
+      ? candidateUrls.map((u) => `- ${u}`).join("\n")
+      : "- (No candidate URLs available yet.)";
+
+  const connectivityBlock =
+    candidateUrls.length === 0
+      ? `No candidate URLs are available. Ask your user to configure a reachable hostname in Paperclip, then retry.
+Suggested steps:
+- choose a hostname that resolves to the Paperclip host from your runtime
+- run: pnpm paperclipai allowed-hostname <host>
+- restart Paperclip
+- verify with: curl -fsS http://<host>:3100/api/health
+- regenerate this invite snippet`
+      : `If none are reachable, ask your user to add a reachable hostname in Paperclip, restart, and retry.
+Suggested command:
+- pnpm paperclipai allowed-hostname <host>
+Then verify with: curl -fsS <base-url>/api/health`;
+
+  const resolutionLine = resolutionTestUrl
+    ? `\nYou MUST test Paperclip-to-gateway reachability, call: ${resolutionTestUrl}?url=<urlencoded-gateway-url> (using the hostname that worked above). Do not assume your 172.x is necessarily reachable from Paperclip. Test it. `
+    : "";
+
+  return `You're invited to join a Paperclip organization.
+
+The URLs you should try are:
+${candidateList}
+
+Connectivity guidance:
+If you are running on a different machine than Paperclip, Paperclip must be reachable at one of the hostnames used above.
+Verify the hostname works from your runtime with: GET <base-url>/api/health
+
+${connectivityBlock}
+
+For your "agentName", just use your own agent name (OpenClaw or whatever your name is) and send it directly.
+You also need to send a gateway URL that Paperclip can access. Check your config and include that URL.${resolutionLine}
+
+---
+
+This onboarding flow is for OpenClaw Gateway.
+When you submit the join request, use:
+- \`adapterType: "openclaw_gateway"\`
+- \`agentDefaultsPayload.url\` as your \`ws://\` or \`wss://\` gateway URL
+- \`agentDefaultsPayload.headers["x-openclaw-token"]\` with your gateway token
+- (legacy accepted) \`agentDefaultsPayload.headers["x-openclaw-auth"]\`
+- Keep device auth enabled (recommended). If \`devicePrivateKeyPem\` is omitted, Paperclip will generate and persist one during join so pairing approvals remain stable.
+- Only use \`disableDeviceAuth=true\` for special environments where pairing cannot be completed.
+
+Do NOT use \`/v1/responses\` or \`/hooks/*\` in this join flow.
+
+Before you do anything, please respond to your user that you understand the instructions and you're going to work on them. Then do the step above in another session called "paperclip-onboarding" and then tell your user when you're done. Update your user in intermediate steps along the way so they know what's going on.
+
+Then after you've connected to Paperclip (exchanged keys etc.) you MUST review and follow the onboarding instructions in onboarding.txt they give you.
+
+`;
+}
+
+function buildCandidateOnboardingUrls(input: AgentSnippetInput): string[] {
+  const candidates = (input.connectionCandidates ?? [])
+    .map((candidate) => candidate.trim())
+    .filter(Boolean);
+  const urls = new Set<string>();
+  let onboardingUrl: URL | null = null;
+
+  try {
+    onboardingUrl = new URL(input.onboardingTextUrl);
+    urls.add(onboardingUrl.toString());
+  } catch {
+    const trimmed = input.onboardingTextUrl.trim();
+    if (trimmed) {
+      urls.add(trimmed);
+    }
+  }
+
+  if (!onboardingUrl) {
+    for (const candidate of candidates) {
+      urls.add(candidate);
+    }
+    return Array.from(urls);
+  }
+
+  const onboardingPath = `${onboardingUrl.pathname}${onboardingUrl.search}`;
+  for (const candidate of candidates) {
+    try {
+      const base = new URL(candidate);
+      urls.add(`${base.origin}${onboardingPath}`);
+    } catch {
+      urls.add(candidate);
+    }
+  }
+
+  return Array.from(urls);
+}
+
+function buildResolutionTestUrl(input: AgentSnippetInput): string | null {
+  const explicit = input.testResolutionUrl?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const onboardingUrl = new URL(input.onboardingTextUrl);
+    const testPath = onboardingUrl.pathname.replace(
+      /\/onboarding\.txt$/,
+      "/test-resolution"
+    );
+    return `${onboardingUrl.origin}${testPath}`;
+  } catch {
+    return null;
+  }
+}

paperclip-reference/ui/src/pages/Dashboard.tsx

@@ -0,0 +1,387 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Link } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { dashboardApi } from "../api/dashboard";
+import { activityApi } from "../api/activity";
+import { issuesApi } from "../api/issues";
+import { agentsApi } from "../api/agents";
+import { projectsApi } from "../api/projects";
+import { heartbeatsApi } from "../api/heartbeats";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { MetricCard } from "../components/MetricCard";
+import { EmptyState } from "../components/EmptyState";
+import { StatusIcon } from "../components/StatusIcon";
+
+import { ActivityRow } from "../components/ActivityRow";
+import { Identity } from "../components/Identity";
+import { timeAgo } from "../lib/timeAgo";
+import { cn, formatCents } from "../lib/utils";
+import { Bot, CircleDot, DollarSign, ShieldCheck, LayoutDashboard, PauseCircle } from "lucide-react";
+import { ActiveAgentsPanel } from "../components/ActiveAgentsPanel";
+import { ChartCard, RunActivityChart, PriorityChart, IssueStatusChart, SuccessRateChart } from "../components/ActivityCharts";
+import { PageSkeleton } from "../components/PageSkeleton";
+import type { Agent, Issue } from "@paperclipai/shared";
+import { PluginSlotOutlet } from "@/plugins/slots";
+
+function getRecentIssues(issues: Issue[]): Issue[] {
+  return [...issues]
+    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+}
+
+export function Dashboard() {
+  const { selectedCompanyId, companies } = useCompany();
+  const { openOnboarding } = useDialog();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const [animatedActivityIds, setAnimatedActivityIds] = useState<Set<string>>(new Set());
+  const seenActivityIdsRef = useRef<Set<string>>(new Set());
+  const hydratedActivityRef = useRef(false);
+  const activityAnimationTimersRef = useRef<number[]>([]);
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Dashboard" }]);
+  }, [setBreadcrumbs]);
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: queryKeys.dashboard(selectedCompanyId!),
+    queryFn: () => dashboardApi.summary(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: activity } = useQuery({
+    queryKey: queryKeys.activity(selectedCompanyId!),
+    queryFn: () => activityApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: issues } = useQuery({
+    queryKey: queryKeys.issues.list(selectedCompanyId!),
+    queryFn: () => issuesApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: projects } = useQuery({
+    queryKey: queryKeys.projects.list(selectedCompanyId!),
+    queryFn: () => projectsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: runs } = useQuery({
+    queryKey: queryKeys.heartbeats(selectedCompanyId!),
+    queryFn: () => heartbeatsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const recentIssues = issues ? getRecentIssues(issues) : [];
+  const recentActivity = useMemo(() => (activity ?? []).slice(0, 10), [activity]);
+
+  useEffect(() => {
+    for (const timer of activityAnimationTimersRef.current) {
+      window.clearTimeout(timer);
+    }
+    activityAnimationTimersRef.current = [];
+    seenActivityIdsRef.current = new Set();
+    hydratedActivityRef.current = false;
+    setAnimatedActivityIds(new Set());
+  }, [selectedCompanyId]);
+
+  useEffect(() => {
+    if (recentActivity.length === 0) return;
+
+    const seen = seenActivityIdsRef.current;
+    const currentIds = recentActivity.map((event) => event.id);
+
+    if (!hydratedActivityRef.current) {
+      for (const id of currentIds) seen.add(id);
+      hydratedActivityRef.current = true;
+      return;
+    }
+
+    const newIds = currentIds.filter((id) => !seen.has(id));
+    if (newIds.length === 0) {
+      for (const id of currentIds) seen.add(id);
+      return;
+    }
+
+    setAnimatedActivityIds((prev) => {
+      const next = new Set(prev);
+      for (const id of newIds) next.add(id);
+      return next;
+    });
+
+    for (const id of newIds) seen.add(id);
+
+    const timer = window.setTimeout(() => {
+      setAnimatedActivityIds((prev) => {
+        const next = new Set(prev);
+        for (const id of newIds) next.delete(id);
+        return next;
+      });
+      activityAnimationTimersRef.current = activityAnimationTimersRef.current.filter((t) => t !== timer);
+    }, 980);
+    activityAnimationTimersRef.current.push(timer);
+  }, [recentActivity]);
+
+  useEffect(() => {
+    return () => {
+      for (const timer of activityAnimationTimersRef.current) {
+        window.clearTimeout(timer);
+      }
+    };
+  }, []);
+
+  const agentMap = useMemo(() => {
+    const map = new Map<string, Agent>();
+    for (const a of agents ?? []) map.set(a.id, a);
+    return map;
+  }, [agents]);
+
+  const entityNameMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const i of issues ?? []) map.set(`issue:${i.id}`, i.identifier ?? i.id.slice(0, 8));
+    for (const a of agents ?? []) map.set(`agent:${a.id}`, a.name);
+    for (const p of projects ?? []) map.set(`project:${p.id}`, p.name);
+    return map;
+  }, [issues, agents, projects]);
+
+  const entityTitleMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const i of issues ?? []) map.set(`issue:${i.id}`, i.title);
+    return map;
+  }, [issues]);
+
+  const agentName = (id: string | null) => {
+    if (!id || !agents) return null;
+    return agents.find((a) => a.id === id)?.name ?? null;
+  };
+
+  if (!selectedCompanyId) {
+    if (companies.length === 0) {
+      return (
+        <EmptyState
+          icon={LayoutDashboard}
+          message="Welcome to Paperclip. Set up your first company and agent to get started."
+          action="Get Started"
+          onAction={openOnboarding}
+        />
+      );
+    }
+    return (
+      <EmptyState icon={LayoutDashboard} message="Create or select a company to view the dashboard." />
+    );
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="dashboard" />;
+  }
+
+  const hasNoAgents = agents !== undefined && agents.length === 0;
+
+  return (
+    <div className="space-y-6">
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {hasNoAgents && (
+        <div className="flex items-center justify-between gap-3 rounded-md border border-amber-300 bg-amber-50 px-4 py-3 dark:border-amber-500/25 dark:bg-amber-950/60">
+          <div className="flex items-center gap-2.5">
+            <Bot className="h-4 w-4 text-amber-600 dark:text-amber-400 shrink-0" />
+            <p className="text-sm text-amber-900 dark:text-amber-100">
+              You have no agents.
+            </p>
+          </div>
+          <button
+            onClick={() => openOnboarding({ initialStep: 2, companyId: selectedCompanyId! })}
+            className="text-sm font-medium text-amber-700 hover:text-amber-900 dark:text-amber-300 dark:hover:text-amber-100 underline underline-offset-2 shrink-0"
+          >
+            Create one here
+          </button>
+        </div>
+      )}
+
+      <ActiveAgentsPanel companyId={selectedCompanyId!} />
+
+      {data && (
+        <>
+          {data.budgets.activeIncidents > 0 ? (
+            <div className="flex items-start justify-between gap-3 rounded-xl border border-red-500/20 bg-[linear-gradient(180deg,rgba(255,80,80,0.12),rgba(255,255,255,0.02))] px-4 py-3">
+              <div className="flex items-start gap-2.5">
+                <PauseCircle className="mt-0.5 h-4 w-4 shrink-0 text-red-300" />
+                <div>
+                  <p className="text-sm font-medium text-red-50">
+                    {data.budgets.activeIncidents} active budget incident{data.budgets.activeIncidents === 1 ? "" : "s"}
+                  </p>
+                  <p className="text-xs text-red-100/70">
+                    {data.budgets.pausedAgents} agents paused · {data.budgets.pausedProjects} projects paused · {data.budgets.pendingApprovals} pending budget approvals
+                  </p>
+                </div>
+              </div>
+              <Link to="/costs" className="text-sm underline underline-offset-2 text-red-100">
+                Open budgets
+              </Link>
+            </div>
+          ) : null}
+
+          <div className="grid grid-cols-2 xl:grid-cols-4 gap-1 sm:gap-2">
+            <MetricCard
+              icon={Bot}
+              value={data.agents.active + data.agents.running + data.agents.paused + data.agents.error}
+              label="Agents Enabled"
+              to="/agents"
+              description={
+                <span>
+                  {data.agents.running} running{", "}
+                  {data.agents.paused} paused{", "}
+                  {data.agents.error} errors
+                </span>
+              }
+            />
+            <MetricCard
+              icon={CircleDot}
+              value={data.tasks.inProgress}
+              label="Tasks In Progress"
+              to="/issues"
+              description={
+                <span>
+                  {data.tasks.open} open{", "}
+                  {data.tasks.blocked} blocked
+                </span>
+              }
+            />
+            <MetricCard
+              icon={DollarSign}
+              value={formatCents(data.costs.monthSpendCents)}
+              label="Month Spend"
+              to="/costs"
+              description={
+                <span>
+                  {data.costs.monthBudgetCents > 0
+                    ? `${data.costs.monthUtilizationPercent}% of ${formatCents(data.costs.monthBudgetCents)} budget`
+                    : "Unlimited budget"}
+                </span>
+              }
+            />
+            <MetricCard
+              icon={ShieldCheck}
+              value={data.pendingApprovals + data.budgets.pendingApprovals}
+              label="Pending Approvals"
+              to="/approvals"
+              description={
+                <span>
+                  {data.budgets.pendingApprovals > 0
+                    ? `${data.budgets.pendingApprovals} budget overrides awaiting board review`
+                    : "Awaiting board review"}
+                </span>
+              }
+            />
+          </div>
+
+          <div className="grid grid-cols-2 lg:grid-cols-4 gap-4">
+            <ChartCard title="Run Activity" subtitle="Last 14 days">
+              <RunActivityChart runs={runs ?? []} />
+            </ChartCard>
+            <ChartCard title="Issues by Priority" subtitle="Last 14 days">
+              <PriorityChart issues={issues ?? []} />
+            </ChartCard>
+            <ChartCard title="Issues by Status" subtitle="Last 14 days">
+              <IssueStatusChart issues={issues ?? []} />
+            </ChartCard>
+            <ChartCard title="Success Rate" subtitle="Last 14 days">
+              <SuccessRateChart runs={runs ?? []} />
+            </ChartCard>
+          </div>
+
+          <PluginSlotOutlet
+            slotTypes={["dashboardWidget"]}
+            context={{ companyId: selectedCompanyId }}
+            className="grid gap-4 md:grid-cols-2"
+            itemClassName="rounded-lg border bg-card p-4 shadow-sm"
+          />
+
+          <div className="grid md:grid-cols-2 gap-4">
+            {/* Recent Activity */}
+            {recentActivity.length > 0 && (
+              <div className="min-w-0">
+                <h3 className="text-sm font-semibold text-muted-foreground uppercase tracking-wide mb-3">
+                  Recent Activity
+                </h3>
+                <div className="border border-border divide-y divide-border overflow-hidden">
+                  {recentActivity.map((event) => (
+                    <ActivityRow
+                      key={event.id}
+                      event={event}
+                      agentMap={agentMap}
+                      entityNameMap={entityNameMap}
+                      entityTitleMap={entityTitleMap}
+                      className={animatedActivityIds.has(event.id) ? "activity-row-enter" : undefined}
+                    />
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {/* Recent Tasks */}
+            <div className="min-w-0">
+              <h3 className="text-sm font-semibold text-muted-foreground uppercase tracking-wide mb-3">
+                Recent Tasks
+              </h3>
+              {recentIssues.length === 0 ? (
+                <div className="border border-border p-4">
+                  <p className="text-sm text-muted-foreground">No tasks yet.</p>
+                </div>
+              ) : (
+                <div className="border border-border divide-y divide-border overflow-hidden">
+                  {recentIssues.slice(0, 10).map((issue) => (
+                    <Link
+                      key={issue.id}
+                      to={`/issues/${issue.identifier ?? issue.id}`}
+                      className="px-4 py-3 text-sm cursor-pointer hover:bg-accent/50 transition-colors no-underline text-inherit block"
+                    >
+                      <div className="flex items-start gap-2 sm:items-center sm:gap-3">
+                        {/* Status icon - left column on mobile */}
+                        <span className="shrink-0 sm:hidden">
+                          <StatusIcon status={issue.status} />
+                        </span>
+
+                        {/* Right column on mobile: title + metadata stacked */}
+                        <span className="flex min-w-0 flex-1 flex-col gap-1 sm:contents">
+                          <span className="line-clamp-2 text-sm sm:order-2 sm:flex-1 sm:min-w-0 sm:line-clamp-none sm:truncate">
+                            {issue.title}
+                          </span>
+                          <span className="flex items-center gap-2 sm:order-1 sm:shrink-0">
+                            <span className="hidden sm:inline-flex"><StatusIcon status={issue.status} /></span>
+                            <span className="text-xs font-mono text-muted-foreground">
+                              {issue.identifier ?? issue.id.slice(0, 8)}
+                            </span>
+                            {issue.assigneeAgentId && (() => {
+                              const name = agentName(issue.assigneeAgentId);
+                              return name
+                                ? <span className="hidden sm:inline-flex"><Identity name={name} size="sm" /></span>
+                                : null;
+                            })()}
+                            <span className="text-xs text-muted-foreground sm:hidden">&middot;</span>
+                            <span className="text-xs text-muted-foreground shrink-0 sm:order-last">
+                              {timeAgo(issue.updatedAt)}
+                            </span>
+                          </span>
+                        </span>
+                      </div>
+                    </Link>
+                  ))}
+                </div>
+              )}
+            </div>
+          </div>
+
+        </>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/ExecutionWorkspaceDetail.tsx

@@ -0,0 +1,82 @@
+import { Link, useParams } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { ExternalLink } from "lucide-react";
+import { executionWorkspacesApi } from "../api/execution-workspaces";
+import { queryKeys } from "../lib/queryKeys";
+
+function isSafeExternalUrl(value: string | null | undefined) {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function DetailRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex items-start gap-3 py-1.5">
+      <div className="w-28 shrink-0 text-xs text-muted-foreground">{label}</div>
+      <div className="min-w-0 flex-1 text-sm">{children}</div>
+    </div>
+  );
+}
+
+export function ExecutionWorkspaceDetail() {
+  const { workspaceId } = useParams<{ workspaceId: string }>();
+
+  const { data: workspace, isLoading, error } = useQuery({
+    queryKey: queryKeys.executionWorkspaces.detail(workspaceId!),
+    queryFn: () => executionWorkspacesApi.get(workspaceId!),
+    enabled: Boolean(workspaceId),
+  });
+
+  if (isLoading) return <p className="text-sm text-muted-foreground">Loading...</p>;
+  if (error) return <p className="text-sm text-destructive">{error instanceof Error ? error.message : "Failed to load workspace"}</p>;
+  if (!workspace) return null;
+
+  return (
+    <div className="max-w-2xl space-y-4">
+      <div className="space-y-1">
+        <div className="text-xs text-muted-foreground">Execution workspace</div>
+        <h1 className="text-2xl font-semibold">{workspace.name}</h1>
+        <div className="text-sm text-muted-foreground">
+          {workspace.status} · {workspace.mode} · {workspace.providerType}
+        </div>
+      </div>
+
+      <div className="rounded-lg border border-border p-4">
+        <DetailRow label="Project">
+          {workspace.projectId ? <Link to={`/projects/${workspace.projectId}`} className="hover:underline">{workspace.projectId}</Link> : "None"}
+        </DetailRow>
+        <DetailRow label="Source issue">
+          {workspace.sourceIssueId ? <Link to={`/issues/${workspace.sourceIssueId}`} className="hover:underline">{workspace.sourceIssueId}</Link> : "None"}
+        </DetailRow>
+        <DetailRow label="Branch">{workspace.branchName ?? "None"}</DetailRow>
+        <DetailRow label="Base ref">{workspace.baseRef ?? "None"}</DetailRow>
+        <DetailRow label="Working dir">
+          <span className="break-all font-mono text-xs">{workspace.cwd ?? "None"}</span>
+        </DetailRow>
+        <DetailRow label="Provider ref">
+          <span className="break-all font-mono text-xs">{workspace.providerRef ?? "None"}</span>
+        </DetailRow>
+        <DetailRow label="Repo URL">
+          {workspace.repoUrl && isSafeExternalUrl(workspace.repoUrl) ? (
+            <a href={workspace.repoUrl} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 hover:underline">
+              {workspace.repoUrl}
+              <ExternalLink className="h-3 w-3" />
+            </a>
+          ) : workspace.repoUrl ? (
+            <span className="break-all font-mono text-xs">{workspace.repoUrl}</span>
+          ) : "None"}
+        </DetailRow>
+        <DetailRow label="Opened">{new Date(workspace.openedAt).toLocaleString()}</DetailRow>
+        <DetailRow label="Last used">{new Date(workspace.lastUsedAt).toLocaleString()}</DetailRow>
+        <DetailRow label="Cleanup">
+          {workspace.cleanupEligibleAt ? `${new Date(workspace.cleanupEligibleAt).toLocaleString()}${workspace.cleanupReason ? ` · ${workspace.cleanupReason}` : ""}` : "Not scheduled"}
+        </DetailRow>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/GoalDetail.tsx

@@ -0,0 +1,196 @@
+import { useEffect } from "react";
+import { useParams } from "@/lib/router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { goalsApi } from "../api/goals";
+import { projectsApi } from "../api/projects";
+import { assetsApi } from "../api/assets";
+import { usePanel } from "../context/PanelContext";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { GoalProperties } from "../components/GoalProperties";
+import { GoalTree } from "../components/GoalTree";
+import { StatusBadge } from "../components/StatusBadge";
+import { InlineEditor } from "../components/InlineEditor";
+import { EntityRow } from "../components/EntityRow";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { projectUrl } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Plus } from "lucide-react";
+import type { Goal, Project } from "@paperclipai/shared";
+
+export function GoalDetail() {
+  const { goalId } = useParams<{ goalId: string }>();
+  const { selectedCompanyId, setSelectedCompanyId } = useCompany();
+  const { openNewGoal } = useDialog();
+  const { openPanel, closePanel } = usePanel();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+
+  const {
+    data: goal,
+    isLoading,
+    error
+  } = useQuery({
+    queryKey: queryKeys.goals.detail(goalId!),
+    queryFn: () => goalsApi.get(goalId!),
+    enabled: !!goalId
+  });
+  const resolvedCompanyId = goal?.companyId ?? selectedCompanyId;
+
+  const { data: allGoals } = useQuery({
+    queryKey: queryKeys.goals.list(resolvedCompanyId!),
+    queryFn: () => goalsApi.list(resolvedCompanyId!),
+    enabled: !!resolvedCompanyId
+  });
+
+  const { data: allProjects } = useQuery({
+    queryKey: queryKeys.projects.list(resolvedCompanyId!),
+    queryFn: () => projectsApi.list(resolvedCompanyId!),
+    enabled: !!resolvedCompanyId
+  });
+
+  useEffect(() => {
+    if (!goal?.companyId || goal.companyId === selectedCompanyId) return;
+    setSelectedCompanyId(goal.companyId, { source: "route_sync" });
+  }, [goal?.companyId, selectedCompanyId, setSelectedCompanyId]);
+
+  const updateGoal = useMutation({
+    mutationFn: (data: Record<string, unknown>) =>
+      goalsApi.update(goalId!, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.goals.detail(goalId!)
+      });
+      if (resolvedCompanyId) {
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.goals.list(resolvedCompanyId)
+        });
+      }
+    }
+  });
+
+  const uploadImage = useMutation({
+    mutationFn: async (file: File) => {
+      if (!resolvedCompanyId) throw new Error("No company selected");
+      return assetsApi.uploadImage(
+        resolvedCompanyId,
+        file,
+        `goals/${goalId ?? "draft"}`
+      );
+    }
+  });
+
+  const childGoals = (allGoals ?? []).filter((g) => g.parentId === goalId);
+  const linkedProjects = (allProjects ?? []).filter((p) => {
+    if (!goalId) return false;
+    if (p.goalIds.includes(goalId)) return true;
+    if (p.goals.some((goalRef) => goalRef.id === goalId)) return true;
+    return p.goalId === goalId;
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Goals", href: "/goals" },
+      { label: goal?.title ?? goalId ?? "Goal" }
+    ]);
+  }, [setBreadcrumbs, goal, goalId]);
+
+  useEffect(() => {
+    if (goal) {
+      openPanel(
+        <GoalProperties
+          goal={goal}
+          onUpdate={(data) => updateGoal.mutate(data)}
+        />
+      );
+    }
+    return () => closePanel();
+  }, [goal]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (isLoading) return <PageSkeleton variant="detail" />;
+  if (error) return <p className="text-sm text-destructive">{error.message}</p>;
+  if (!goal) return null;
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-3">
+        <div className="flex items-center gap-2">
+          <span className="text-xs uppercase text-muted-foreground">
+            {goal.level}
+          </span>
+          <StatusBadge status={goal.status} />
+        </div>
+
+        <InlineEditor
+          value={goal.title}
+          onSave={(title) => updateGoal.mutate({ title })}
+          as="h2"
+          className="text-xl font-bold"
+        />
+
+        <InlineEditor
+          value={goal.description ?? ""}
+          onSave={(description) => updateGoal.mutate({ description })}
+          as="p"
+          className="text-sm text-muted-foreground"
+          placeholder="Add a description..."
+          multiline
+          imageUploadHandler={async (file) => {
+            const asset = await uploadImage.mutateAsync(file);
+            return asset.contentPath;
+          }}
+        />
+      </div>
+
+      <Tabs defaultValue="children">
+        <TabsList>
+          <TabsTrigger value="children">
+            Sub-Goals ({childGoals.length})
+          </TabsTrigger>
+          <TabsTrigger value="projects">
+            Projects ({linkedProjects.length})
+          </TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="children" className="mt-4 space-y-3">
+          <div className="flex items-center justify-start">
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => openNewGoal({ parentId: goalId })}
+            >
+              <Plus className="h-3.5 w-3.5 mr-1.5" />
+              Sub Goal
+            </Button>
+          </div>
+          {childGoals.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No sub-goals.</p>
+          ) : (
+            <GoalTree goals={childGoals} goalLink={(g) => `/goals/${g.id}`} />
+          )}
+        </TabsContent>
+
+        <TabsContent value="projects" className="mt-4">
+          {linkedProjects.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No linked projects.</p>
+          ) : (
+            <div className="border border-border">
+              {linkedProjects.map((project) => (
+                <EntityRow
+                  key={project.id}
+                  title={project.name}
+                  subtitle={project.description ?? undefined}
+                  to={projectUrl(project)}
+                  trailing={<StatusBadge status={project.status} />}
+                />
+              ))}
+            </div>
+          )}
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Goals.tsx

@@ -0,0 +1,63 @@
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { goalsApi } from "../api/goals";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { GoalTree } from "../components/GoalTree";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { Button } from "@/components/ui/button";
+import { Target, Plus } from "lucide-react";
+
+export function Goals() {
+  const { selectedCompanyId } = useCompany();
+  const { openNewGoal } = useDialog();
+  const { setBreadcrumbs } = useBreadcrumbs();
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Goals" }]);
+  }, [setBreadcrumbs]);
+
+  const { data: goals, isLoading, error } = useQuery({
+    queryKey: queryKeys.goals.list(selectedCompanyId!),
+    queryFn: () => goalsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={Target} message="Select a company to view goals." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  return (
+    <div className="space-y-4">
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {goals && goals.length === 0 && (
+        <EmptyState
+          icon={Target}
+          message="No goals yet."
+          action="Add Goal"
+          onAction={() => openNewGoal()}
+        />
+      )}
+
+      {goals && goals.length > 0 && (
+        <>
+          <div className="flex items-center justify-start">
+            <Button size="sm" variant="outline" onClick={() => openNewGoal()}>
+              <Plus className="h-3.5 w-3.5 mr-1.5" />
+              New Goal
+            </Button>
+          </div>
+          <GoalTree goals={goals} goalLink={(goal) => `/goals/${goal.id}`} />
+        </>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Inbox.tsx

@@ -0,0 +1,963 @@
+import { useEffect, useMemo, useState } from "react";
+import { Link, useLocation, useNavigate } from "@/lib/router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { approvalsApi } from "../api/approvals";
+import { accessApi } from "../api/access";
+import { ApiError } from "../api/client";
+import { dashboardApi } from "../api/dashboard";
+import { issuesApi } from "../api/issues";
+import { agentsApi } from "../api/agents";
+import { heartbeatsApi } from "../api/heartbeats";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { createIssueDetailLocationState } from "../lib/issueDetailBreadcrumb";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { IssueRow } from "../components/IssueRow";
+
+import { StatusIcon } from "../components/StatusIcon";
+import { StatusBadge } from "../components/StatusBadge";
+import { approvalLabel, defaultTypeIcon, typeIcon } from "../components/ApprovalPayload";
+import { timeAgo } from "../lib/timeAgo";
+import { Button } from "@/components/ui/button";
+import { Separator } from "@/components/ui/separator";
+import { Tabs } from "@/components/ui/tabs";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Inbox as InboxIcon,
+  AlertTriangle,
+  XCircle,
+  X,
+  RotateCcw,
+  UserPlus,
+} from "lucide-react";
+import { PageTabBar } from "../components/PageTabBar";
+import type { Approval, HeartbeatRun, Issue, JoinRequest } from "@paperclipai/shared";
+import {
+  ACTIONABLE_APPROVAL_STATUSES,
+  getApprovalsForTab,
+  getInboxWorkItems,
+  getLatestFailedRunsByAgent,
+  getRecentTouchedIssues,
+  InboxApprovalFilter,
+  saveLastInboxTab,
+  shouldShowInboxSection,
+  type InboxTab,
+} from "../lib/inbox";
+import { useDismissedInboxItems } from "../hooks/useInboxBadge";
+
+type InboxCategoryFilter =
+  | "everything"
+  | "issues_i_touched"
+  | "join_requests"
+  | "approvals"
+  | "failed_runs"
+  | "alerts";
+type SectionKey =
+  | "work_items"
+  | "alerts";
+
+function firstNonEmptyLine(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const line = value.split("\n").map((chunk) => chunk.trim()).find(Boolean);
+  return line ?? null;
+}
+
+function runFailureMessage(run: HeartbeatRun): string {
+  return firstNonEmptyLine(run.error) ?? firstNonEmptyLine(run.stderrExcerpt) ?? "Run exited with an error.";
+}
+
+function approvalStatusLabel(status: Approval["status"]): string {
+  return status.replaceAll("_", " ");
+}
+
+function readIssueIdFromRun(run: HeartbeatRun): string | null {
+  const context = run.contextSnapshot;
+  if (!context) return null;
+
+  const issueId = context["issueId"];
+  if (typeof issueId === "string" && issueId.length > 0) return issueId;
+
+  const taskId = context["taskId"];
+  if (typeof taskId === "string" && taskId.length > 0) return taskId;
+
+  return null;
+}
+
+function FailedRunInboxRow({
+  run,
+  issueById,
+  agentName: linkedAgentName,
+  issueLinkState,
+  onDismiss,
+  onRetry,
+  isRetrying,
+}: {
+  run: HeartbeatRun;
+  issueById: Map<string, Issue>;
+  agentName: string | null;
+  issueLinkState: unknown;
+  onDismiss: () => void;
+  onRetry: () => void;
+  isRetrying: boolean;
+}) {
+  const issueId = readIssueIdFromRun(run);
+  const issue = issueId ? issueById.get(issueId) ?? null : null;
+  const displayError = runFailureMessage(run);
+
+  return (
+    <div className="group border-b border-border px-2 py-2.5 last:border-b-0 sm:px-1 sm:pr-3 sm:py-2">
+      <div className="flex items-start gap-2 sm:items-center">
+        <Link
+          to={`/agents/${run.agentId}/runs/${run.id}`}
+          className="flex min-w-0 flex-1 items-start gap-2 no-underline text-inherit transition-colors hover:bg-accent/50"
+        >
+          <span className="hidden h-2 w-2 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="hidden h-3.5 w-3.5 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="mt-0.5 shrink-0 rounded-md bg-red-500/20 p-1.5 sm:mt-0">
+            <XCircle className="h-4 w-4 text-red-600 dark:text-red-400" />
+          </span>
+          <span className="min-w-0 flex-1">
+            <span className="line-clamp-2 text-sm font-medium sm:truncate sm:line-clamp-none">
+              {issue ? (
+                <>
+                  <span className="font-mono text-muted-foreground mr-1.5">
+                    {issue.identifier ?? issue.id.slice(0, 8)}
+                  </span>
+                  {issue.title}
+                </>
+              ) : (
+                <>Failed run{linkedAgentName ? ` — ${linkedAgentName}` : ""}</>
+              )}
+            </span>
+            <span className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+              <StatusBadge status={run.status} />
+              {linkedAgentName && issue ? <span>{linkedAgentName}</span> : null}
+              <span className="truncate max-w-[300px]">{displayError}</span>
+              <span>{timeAgo(run.createdAt)}</span>
+            </span>
+          </span>
+        </Link>
+        <div className="hidden shrink-0 items-center gap-2 sm:flex">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="h-8 shrink-0 px-2.5"
+            onClick={onRetry}
+            disabled={isRetrying}
+          >
+            <RotateCcw className="mr-1.5 h-3.5 w-3.5" />
+            {isRetrying ? "Retrying…" : "Retry"}
+          </Button>
+          <button
+            type="button"
+            onClick={onDismiss}
+            className="rounded-md p-1 text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover:opacity-100"
+            aria-label="Dismiss"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+      </div>
+      <div className="mt-3 flex gap-2 sm:hidden">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8 shrink-0 px-2.5"
+          onClick={onRetry}
+          disabled={isRetrying}
+        >
+          <RotateCcw className="mr-1.5 h-3.5 w-3.5" />
+          {isRetrying ? "Retrying…" : "Retry"}
+        </Button>
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="rounded-md p-1 text-muted-foreground hover:bg-accent hover:text-foreground"
+          aria-label="Dismiss"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function ApprovalInboxRow({
+  approval,
+  requesterName,
+  onApprove,
+  onReject,
+  isPending,
+}: {
+  approval: Approval;
+  requesterName: string | null;
+  onApprove: () => void;
+  onReject: () => void;
+  isPending: boolean;
+}) {
+  const Icon = typeIcon[approval.type] ?? defaultTypeIcon;
+  const label = approvalLabel(approval.type, approval.payload as Record<string, unknown> | null);
+  const showResolutionButtons =
+    approval.type !== "budget_override_required" &&
+    ACTIONABLE_APPROVAL_STATUSES.has(approval.status);
+
+  return (
+    <div className="border-b border-border px-2 py-2.5 last:border-b-0 sm:px-1 sm:pr-3 sm:py-2">
+      <div className="flex items-start gap-2 sm:items-center">
+        <Link
+          to={`/approvals/${approval.id}`}
+          className="flex min-w-0 flex-1 items-start gap-2 no-underline text-inherit transition-colors hover:bg-accent/50"
+        >
+          <span className="hidden h-2 w-2 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="hidden h-3.5 w-3.5 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="mt-0.5 shrink-0 rounded-md bg-muted p-1.5 sm:mt-0">
+            <Icon className="h-4 w-4 text-muted-foreground" />
+          </span>
+          <span className="min-w-0 flex-1">
+            <span className="line-clamp-2 text-sm font-medium sm:truncate sm:line-clamp-none">
+              {label}
+            </span>
+            <span className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+              <span className="capitalize">{approvalStatusLabel(approval.status)}</span>
+              {requesterName ? <span>requested by {requesterName}</span> : null}
+              <span>updated {timeAgo(approval.updatedAt)}</span>
+            </span>
+          </span>
+        </Link>
+        {showResolutionButtons ? (
+          <div className="hidden shrink-0 items-center gap-2 sm:flex">
+            <Button
+              size="sm"
+              className="h-8 bg-green-700 px-3 text-white hover:bg-green-600"
+              onClick={onApprove}
+              disabled={isPending}
+            >
+              Approve
+            </Button>
+            <Button
+              variant="destructive"
+              size="sm"
+              className="h-8 px-3"
+              onClick={onReject}
+              disabled={isPending}
+            >
+              Reject
+            </Button>
+          </div>
+        ) : null}
+      </div>
+      {showResolutionButtons ? (
+        <div className="mt-3 flex gap-2 sm:hidden">
+          <Button
+            size="sm"
+            className="h-8 bg-green-700 px-3 text-white hover:bg-green-600"
+            onClick={onApprove}
+            disabled={isPending}
+          >
+            Approve
+          </Button>
+          <Button
+            variant="destructive"
+            size="sm"
+            className="h-8 px-3"
+            onClick={onReject}
+            disabled={isPending}
+          >
+            Reject
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function JoinRequestInboxRow({
+  joinRequest,
+  onApprove,
+  onReject,
+  isPending,
+}: {
+  joinRequest: JoinRequest;
+  onApprove: () => void;
+  onReject: () => void;
+  isPending: boolean;
+}) {
+  const label =
+    joinRequest.requestType === "human"
+      ? "Human join request"
+      : `Agent join request${joinRequest.agentName ? `: ${joinRequest.agentName}` : ""}`;
+
+  return (
+    <div className="border-b border-border px-2 py-2.5 last:border-b-0 sm:px-1 sm:pr-3 sm:py-2">
+      <div className="flex items-start gap-2 sm:items-center">
+        <div className="flex min-w-0 flex-1 items-start gap-2">
+          <span className="hidden h-2 w-2 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="hidden h-3.5 w-3.5 shrink-0 sm:inline-flex" aria-hidden="true" />
+          <span className="mt-0.5 shrink-0 rounded-md bg-muted p-1.5 sm:mt-0">
+            <UserPlus className="h-4 w-4 text-muted-foreground" />
+          </span>
+          <span className="min-w-0 flex-1">
+            <span className="line-clamp-2 text-sm font-medium sm:truncate sm:line-clamp-none">
+              {label}
+            </span>
+            <span className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+              <span>requested {timeAgo(joinRequest.createdAt)} from IP {joinRequest.requestIp}</span>
+              {joinRequest.adapterType && <span>adapter: {joinRequest.adapterType}</span>}
+            </span>
+          </span>
+        </div>
+        <div className="hidden shrink-0 items-center gap-2 sm:flex">
+          <Button
+            size="sm"
+            className="h-8 bg-green-700 px-3 text-white hover:bg-green-600"
+            onClick={onApprove}
+            disabled={isPending}
+          >
+            Approve
+          </Button>
+          <Button
+            variant="destructive"
+            size="sm"
+            className="h-8 px-3"
+            onClick={onReject}
+            disabled={isPending}
+          >
+            Reject
+          </Button>
+        </div>
+      </div>
+      <div className="mt-3 flex gap-2 sm:hidden">
+        <Button
+          size="sm"
+          className="h-8 bg-green-700 px-3 text-white hover:bg-green-600"
+          onClick={onApprove}
+          disabled={isPending}
+        >
+          Approve
+        </Button>
+        <Button
+          variant="destructive"
+          size="sm"
+          className="h-8 px-3"
+          onClick={onReject}
+          disabled={isPending}
+        >
+          Reject
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export function Inbox() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const queryClient = useQueryClient();
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [allCategoryFilter, setAllCategoryFilter] = useState<InboxCategoryFilter>("everything");
+  const [allApprovalFilter, setAllApprovalFilter] = useState<InboxApprovalFilter>("all");
+  const { dismissed, dismiss } = useDismissedInboxItems();
+
+  const pathSegment = location.pathname.split("/").pop() ?? "recent";
+  const tab: InboxTab =
+    pathSegment === "all" || pathSegment === "unread" ? pathSegment : "recent";
+  const issueLinkState = useMemo(
+    () =>
+      createIssueDetailLocationState(
+        "Inbox",
+        `${location.pathname}${location.search}${location.hash}`,
+      ),
+    [location.pathname, location.search, location.hash],
+  );
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Inbox" }]);
+  }, [setBreadcrumbs]);
+
+  useEffect(() => {
+    saveLastInboxTab(tab);
+  }, [tab]);
+
+  const {
+    data: approvals,
+    isLoading: isApprovalsLoading,
+    error: approvalsError,
+  } = useQuery({
+    queryKey: queryKeys.approvals.list(selectedCompanyId!),
+    queryFn: () => approvalsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const {
+    data: joinRequests = [],
+    isLoading: isJoinRequestsLoading,
+  } = useQuery({
+    queryKey: queryKeys.access.joinRequests(selectedCompanyId!),
+    queryFn: async () => {
+      try {
+        return await accessApi.listJoinRequests(selectedCompanyId!, "pending_approval");
+      } catch (err) {
+        if (err instanceof ApiError && (err.status === 403 || err.status === 401)) {
+          return [];
+        }
+        throw err;
+      }
+    },
+    enabled: !!selectedCompanyId,
+    retry: false,
+  });
+
+  const { data: dashboard, isLoading: isDashboardLoading } = useQuery({
+    queryKey: queryKeys.dashboard(selectedCompanyId!),
+    queryFn: () => dashboardApi.summary(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: issues, isLoading: isIssuesLoading } = useQuery({
+    queryKey: queryKeys.issues.list(selectedCompanyId!),
+    queryFn: () => issuesApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+  const {
+    data: touchedIssuesRaw = [],
+    isLoading: isTouchedIssuesLoading,
+  } = useQuery({
+    queryKey: queryKeys.issues.listTouchedByMe(selectedCompanyId!),
+    queryFn: () =>
+      issuesApi.list(selectedCompanyId!, {
+        touchedByUserId: "me",
+        status: "backlog,todo,in_progress,in_review,blocked,done",
+      }),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: heartbeatRuns, isLoading: isRunsLoading } = useQuery({
+    queryKey: queryKeys.heartbeats(selectedCompanyId!),
+    queryFn: () => heartbeatsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const touchedIssues = useMemo(() => getRecentTouchedIssues(touchedIssuesRaw), [touchedIssuesRaw]);
+  const unreadTouchedIssues = useMemo(
+    () => touchedIssues.filter((issue) => issue.isUnreadForMe),
+    [touchedIssues],
+  );
+  const issuesToRender = useMemo(
+    () => (tab === "unread" ? unreadTouchedIssues : touchedIssues),
+    [tab, touchedIssues, unreadTouchedIssues],
+  );
+
+  const agentById = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const agent of agents ?? []) map.set(agent.id, agent.name);
+    return map;
+  }, [agents]);
+
+  const issueById = useMemo(() => {
+    const map = new Map<string, Issue>();
+    for (const issue of issues ?? []) map.set(issue.id, issue);
+    return map;
+  }, [issues]);
+
+  const failedRuns = useMemo(
+    () => getLatestFailedRunsByAgent(heartbeatRuns ?? []).filter((r) => !dismissed.has(`run:${r.id}`)),
+    [heartbeatRuns, dismissed],
+  );
+  const liveIssueIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const run of heartbeatRuns ?? []) {
+      if (run.status !== "running" && run.status !== "queued") continue;
+      const issueId = readIssueIdFromRun(run);
+      if (issueId) ids.add(issueId);
+    }
+    return ids;
+  }, [heartbeatRuns]);
+
+  const approvalsToRender = useMemo(
+    () => getApprovalsForTab(approvals ?? [], tab, allApprovalFilter),
+    [approvals, tab, allApprovalFilter],
+  );
+  const showJoinRequestsCategory =
+    allCategoryFilter === "everything" || allCategoryFilter === "join_requests";
+  const showTouchedCategory =
+    allCategoryFilter === "everything" || allCategoryFilter === "issues_i_touched";
+  const showApprovalsCategory =
+    allCategoryFilter === "everything" || allCategoryFilter === "approvals";
+  const showFailedRunsCategory =
+    allCategoryFilter === "everything" || allCategoryFilter === "failed_runs";
+  const showAlertsCategory = allCategoryFilter === "everything" || allCategoryFilter === "alerts";
+  const failedRunsForTab = useMemo(() => {
+    if (tab === "all" && !showFailedRunsCategory) return [];
+    return failedRuns;
+  }, [failedRuns, tab, showFailedRunsCategory]);
+
+  const joinRequestsForTab = useMemo(() => {
+    if (tab === "all" && !showJoinRequestsCategory) return [];
+    if (tab === "recent") return joinRequests;
+    if (tab === "unread") return joinRequests;
+    return joinRequests;
+  }, [joinRequests, tab, showJoinRequestsCategory]);
+
+  const workItemsToRender = useMemo(
+    () =>
+      getInboxWorkItems({
+        issues: tab === "all" && !showTouchedCategory ? [] : issuesToRender,
+        approvals: tab === "all" && !showApprovalsCategory ? [] : approvalsToRender,
+        failedRuns: failedRunsForTab,
+        joinRequests: joinRequestsForTab,
+      }),
+    [approvalsToRender, issuesToRender, showApprovalsCategory, showTouchedCategory, tab, failedRunsForTab, joinRequestsForTab],
+  );
+
+  const agentName = (id: string | null) => {
+    if (!id) return null;
+    return agentById.get(id) ?? null;
+  };
+
+  const approveMutation = useMutation({
+    mutationFn: (id: string) => approvalsApi.approve(id),
+    onSuccess: (_approval, id) => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(selectedCompanyId!) });
+      navigate(`/approvals/${id}?resolved=approved`);
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to approve");
+    },
+  });
+
+  const rejectMutation = useMutation({
+    mutationFn: (id: string) => approvalsApi.reject(id),
+    onSuccess: () => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(selectedCompanyId!) });
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to reject");
+    },
+  });
+
+  const approveJoinMutation = useMutation({
+    mutationFn: (joinRequest: JoinRequest) =>
+      accessApi.approveJoinRequest(selectedCompanyId!, joinRequest.id),
+    onSuccess: () => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.access.joinRequests(selectedCompanyId!) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.sidebarBadges(selectedCompanyId!) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(selectedCompanyId!) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to approve join request");
+    },
+  });
+
+  const rejectJoinMutation = useMutation({
+    mutationFn: (joinRequest: JoinRequest) =>
+      accessApi.rejectJoinRequest(selectedCompanyId!, joinRequest.id),
+    onSuccess: () => {
+      setActionError(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.access.joinRequests(selectedCompanyId!) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.sidebarBadges(selectedCompanyId!) });
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to reject join request");
+    },
+  });
+
+  const [retryingRunIds, setRetryingRunIds] = useState<Set<string>>(new Set());
+
+  const retryRunMutation = useMutation({
+    mutationFn: async (run: HeartbeatRun) => {
+      const payload: Record<string, unknown> = {};
+      const context = run.contextSnapshot as Record<string, unknown> | null;
+      if (context) {
+        if (typeof context.issueId === "string" && context.issueId) payload.issueId = context.issueId;
+        if (typeof context.taskId === "string" && context.taskId) payload.taskId = context.taskId;
+        if (typeof context.taskKey === "string" && context.taskKey) payload.taskKey = context.taskKey;
+      }
+      const result = await agentsApi.wakeup(run.agentId, {
+        source: "on_demand",
+        triggerDetail: "manual",
+        reason: "retry_failed_run",
+        payload,
+      });
+      if (!("id" in result)) {
+        throw new Error("Retry was skipped because the agent is not currently invokable.");
+      }
+      return { newRun: result, originalRun: run };
+    },
+    onMutate: (run) => {
+      setRetryingRunIds((prev) => new Set(prev).add(run.id));
+    },
+    onSuccess: ({ newRun, originalRun }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.heartbeats(originalRun.companyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.heartbeats(originalRun.companyId, originalRun.agentId) });
+      navigate(`/agents/${originalRun.agentId}/runs/${newRun.id}`);
+    },
+    onSettled: (_data, _error, run) => {
+      if (!run) return;
+      setRetryingRunIds((prev) => {
+        const next = new Set(prev);
+        next.delete(run.id);
+        return next;
+      });
+    },
+  });
+
+  const [fadingOutIssues, setFadingOutIssues] = useState<Set<string>>(new Set());
+
+  const invalidateInboxIssueQueries = () => {
+    if (!selectedCompanyId) return;
+    queryClient.invalidateQueries({ queryKey: queryKeys.issues.listTouchedByMe(selectedCompanyId) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.issues.listUnreadTouchedByMe(selectedCompanyId) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.sidebarBadges(selectedCompanyId) });
+  };
+
+  const markReadMutation = useMutation({
+    mutationFn: (id: string) => issuesApi.markRead(id),
+    onMutate: (id) => {
+      setFadingOutIssues((prev) => new Set(prev).add(id));
+    },
+    onSuccess: () => {
+      invalidateInboxIssueQueries();
+    },
+    onSettled: (_data, _error, id) => {
+      setTimeout(() => {
+        setFadingOutIssues((prev) => {
+          const next = new Set(prev);
+          next.delete(id);
+          return next;
+        });
+      }, 300);
+    },
+  });
+
+  const markAllReadMutation = useMutation({
+    mutationFn: async (issueIds: string[]) => {
+      await Promise.all(issueIds.map((issueId) => issuesApi.markRead(issueId)));
+    },
+    onMutate: (issueIds) => {
+      setFadingOutIssues((prev) => {
+        const next = new Set(prev);
+        for (const issueId of issueIds) next.add(issueId);
+        return next;
+      });
+    },
+    onSuccess: () => {
+      invalidateInboxIssueQueries();
+    },
+    onSettled: (_data, _error, issueIds) => {
+      setTimeout(() => {
+        setFadingOutIssues((prev) => {
+          const next = new Set(prev);
+          for (const issueId of issueIds) next.delete(issueId);
+          return next;
+        });
+      }, 300);
+    },
+  });
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={InboxIcon} message="Select a company to view inbox." />;
+  }
+
+  const hasRunFailures = failedRuns.length > 0;
+  const showAggregateAgentError = !!dashboard && dashboard.agents.error > 0 && !hasRunFailures && !dismissed.has("alert:agent-errors");
+  const showBudgetAlert =
+    !!dashboard &&
+    dashboard.costs.monthBudgetCents > 0 &&
+    dashboard.costs.monthUtilizationPercent >= 80 &&
+    !dismissed.has("alert:budget");
+  const hasAlerts = showAggregateAgentError || showBudgetAlert;
+  const showWorkItemsSection = workItemsToRender.length > 0;
+  const showAlertsSection = shouldShowInboxSection({
+    tab,
+    hasItems: hasAlerts,
+    showOnRecent: hasAlerts,
+    showOnUnread: hasAlerts,
+    showOnAll: showAlertsCategory && hasAlerts,
+  });
+
+  const visibleSections = [
+    showAlertsSection ? "alerts" : null,
+    showWorkItemsSection ? "work_items" : null,
+  ].filter((key): key is SectionKey => key !== null);
+
+  const allLoaded =
+    !isJoinRequestsLoading &&
+    !isApprovalsLoading &&
+    !isDashboardLoading &&
+    !isIssuesLoading &&
+    !isTouchedIssuesLoading &&
+    !isRunsLoading;
+
+  const showSeparatorBefore = (key: SectionKey) => visibleSections.indexOf(key) > 0;
+  const unreadIssueIds = unreadTouchedIssues
+    .filter((issue) => !fadingOutIssues.has(issue.id))
+    .map((issue) => issue.id);
+  const canMarkAllRead = unreadIssueIds.length > 0;
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex flex-wrap items-center gap-2">
+          <Tabs value={tab} onValueChange={(value) => navigate(`/inbox/${value}`)}>
+            <PageTabBar
+              items={[
+                {
+                  value: "recent",
+                  label: "Recent",
+                },
+                { value: "unread", label: "Unread" },
+                { value: "all", label: "All" },
+              ]}
+            />
+          </Tabs>
+
+          {canMarkAllRead && (
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              className="h-8 shrink-0"
+              onClick={() => markAllReadMutation.mutate(unreadIssueIds)}
+              disabled={markAllReadMutation.isPending}
+            >
+              {markAllReadMutation.isPending ? "Marking…" : "Mark all as read"}
+            </Button>
+          )}
+        </div>
+
+        {tab === "all" && (
+          <div className="flex flex-wrap items-center gap-2 sm:justify-end">
+            <Select
+              value={allCategoryFilter}
+              onValueChange={(value) => setAllCategoryFilter(value as InboxCategoryFilter)}
+            >
+              <SelectTrigger className="h-8 w-[170px] text-xs">
+                <SelectValue placeholder="Category" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="everything">All categories</SelectItem>
+                <SelectItem value="issues_i_touched">My recent issues</SelectItem>
+                <SelectItem value="join_requests">Join requests</SelectItem>
+                <SelectItem value="approvals">Approvals</SelectItem>
+                <SelectItem value="failed_runs">Failed runs</SelectItem>
+                <SelectItem value="alerts">Alerts</SelectItem>
+              </SelectContent>
+            </Select>
+
+            {showApprovalsCategory && (
+              <Select
+                value={allApprovalFilter}
+                onValueChange={(value) => setAllApprovalFilter(value as InboxApprovalFilter)}
+              >
+                <SelectTrigger className="h-8 w-[170px] text-xs">
+                  <SelectValue placeholder="Approval status" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="all">All approval statuses</SelectItem>
+                  <SelectItem value="actionable">Needs action</SelectItem>
+                  <SelectItem value="resolved">Resolved</SelectItem>
+                </SelectContent>
+              </Select>
+            )}
+          </div>
+        )}
+      </div>
+
+      {approvalsError && <p className="text-sm text-destructive">{approvalsError.message}</p>}
+      {actionError && <p className="text-sm text-destructive">{actionError}</p>}
+
+      {!allLoaded && visibleSections.length === 0 && (
+        <PageSkeleton variant="inbox" />
+      )}
+
+      {allLoaded && visibleSections.length === 0 && (
+        <EmptyState
+          icon={InboxIcon}
+          message={
+            tab === "unread"
+              ? "No new inbox items."
+              : tab === "recent"
+                ? "No recent inbox items."
+                : "No inbox items match these filters."
+          }
+        />
+      )}
+
+      {showWorkItemsSection && (
+        <>
+          {showSeparatorBefore("work_items") && <Separator />}
+          <div>
+            <div className="overflow-hidden rounded-xl border border-border bg-card">
+              {workItemsToRender.map((item) => {
+                if (item.kind === "approval") {
+                  return (
+                    <ApprovalInboxRow
+                      key={`approval:${item.approval.id}`}
+                      approval={item.approval}
+                      requesterName={agentName(item.approval.requestedByAgentId)}
+                      onApprove={() => approveMutation.mutate(item.approval.id)}
+                      onReject={() => rejectMutation.mutate(item.approval.id)}
+                      isPending={approveMutation.isPending || rejectMutation.isPending}
+                    />
+                  );
+                }
+
+                if (item.kind === "failed_run") {
+                  return (
+                    <FailedRunInboxRow
+                      key={`run:${item.run.id}`}
+                      run={item.run}
+                      issueById={issueById}
+                      agentName={agentName(item.run.agentId)}
+                      issueLinkState={issueLinkState}
+                      onDismiss={() => dismiss(`run:${item.run.id}`)}
+                      onRetry={() => retryRunMutation.mutate(item.run)}
+                      isRetrying={retryingRunIds.has(item.run.id)}
+                    />
+                  );
+                }
+
+                if (item.kind === "join_request") {
+                  return (
+                    <JoinRequestInboxRow
+                      key={`join:${item.joinRequest.id}`}
+                      joinRequest={item.joinRequest}
+                      onApprove={() => approveJoinMutation.mutate(item.joinRequest)}
+                      onReject={() => rejectJoinMutation.mutate(item.joinRequest)}
+                      isPending={approveJoinMutation.isPending || rejectJoinMutation.isPending}
+                    />
+                  );
+                }
+
+                const issue = item.issue;
+                const isUnread = issue.isUnreadForMe && !fadingOutIssues.has(issue.id);
+                const isFading = fadingOutIssues.has(issue.id);
+                return (
+                  <IssueRow
+                    key={`issue:${issue.id}`}
+                    issue={issue}
+                    issueLinkState={issueLinkState}
+                    desktopMetaLeading={(
+                      <>
+                        <span className="hidden shrink-0 sm:inline-flex">
+                          <StatusIcon status={issue.status} />
+                        </span>
+                        <span className="shrink-0 font-mono text-xs text-muted-foreground">
+                          {issue.identifier ?? issue.id.slice(0, 8)}
+                        </span>
+                        {liveIssueIds.has(issue.id) && (
+                          <span className="inline-flex items-center gap-1 rounded-full bg-blue-500/10 px-1.5 py-0.5 sm:gap-1.5 sm:px-2">
+                            <span className="relative flex h-2 w-2">
+                              <span className="absolute inline-flex h-full w-full animate-pulse rounded-full bg-blue-400 opacity-75" />
+                              <span className="relative inline-flex h-2 w-2 rounded-full bg-blue-500" />
+                            </span>
+                            <span className="hidden text-[11px] font-medium text-blue-600 dark:text-blue-400 sm:inline">
+                              Live
+                            </span>
+                          </span>
+                        )}
+                      </>
+                    )}
+                    mobileMeta={
+                      issue.lastExternalCommentAt
+                        ? `commented ${timeAgo(issue.lastExternalCommentAt)}`
+                        : `updated ${timeAgo(issue.updatedAt)}`
+                    }
+                    unreadState={isUnread ? "visible" : isFading ? "fading" : "hidden"}
+                    onMarkRead={() => markReadMutation.mutate(issue.id)}
+                    trailingMeta={
+                      issue.lastExternalCommentAt
+                        ? `commented ${timeAgo(issue.lastExternalCommentAt)}`
+                        : `updated ${timeAgo(issue.updatedAt)}`
+                    }
+                  />
+                );
+              })}
+            </div>
+          </div>
+        </>
+      )}
+
+      {showAlertsSection && (
+        <>
+          {showSeparatorBefore("alerts") && <Separator />}
+          <div>
+            <h3 className="mb-3 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+              Alerts
+            </h3>
+            <div className="divide-y divide-border border border-border">
+              {showAggregateAgentError && (
+                <div className="group/alert relative flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/50">
+                  <Link
+                    to="/agents"
+                    className="flex flex-1 cursor-pointer items-center gap-3 no-underline text-inherit"
+                  >
+                    <AlertTriangle className="h-4 w-4 shrink-0 text-red-600 dark:text-red-400" />
+                    <span className="text-sm">
+                      <span className="font-medium">{dashboard!.agents.error}</span>{" "}
+                      {dashboard!.agents.error === 1 ? "agent has" : "agents have"} errors
+                    </span>
+                  </Link>
+                  <button
+                    type="button"
+                    onClick={() => dismiss("alert:agent-errors")}
+                    className="rounded-md p-1 text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover/alert:opacity-100"
+                    aria-label="Dismiss"
+                  >
+                    <X className="h-3.5 w-3.5" />
+                  </button>
+                </div>
+              )}
+              {showBudgetAlert && (
+                <div className="group/alert relative flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/50">
+                  <Link
+                    to="/costs"
+                    className="flex flex-1 cursor-pointer items-center gap-3 no-underline text-inherit"
+                  >
+                    <AlertTriangle className="h-4 w-4 shrink-0 text-yellow-400" />
+                    <span className="text-sm">
+                      Budget at{" "}
+                      <span className="font-medium">{dashboard!.costs.monthUtilizationPercent}%</span>{" "}
+                      utilization this month
+                    </span>
+                  </Link>
+                  <button
+                    type="button"
+                    onClick={() => dismiss("alert:budget")}
+                    className="rounded-md p-1 text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover/alert:opacity-100"
+                    aria-label="Dismiss"
+                  >
+                    <X className="h-3.5 w-3.5" />
+                  </button>
+                </div>
+              )}
+            </div>
+          </div>
+        </>
+      )}
+
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/InstanceExperimentalSettings.tsx

@@ -0,0 +1,139 @@
+import { useEffect, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { FlaskConical } from "lucide-react";
+import { instanceSettingsApi } from "@/api/instanceSettings";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { cn } from "../lib/utils";
+
+export function InstanceExperimentalSettings() {
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const [actionError, setActionError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Instance Settings" },
+      { label: "Experimental" },
+    ]);
+  }, [setBreadcrumbs]);
+
+  const experimentalQuery = useQuery({
+    queryKey: queryKeys.instance.experimentalSettings,
+    queryFn: () => instanceSettingsApi.getExperimental(),
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: async (patch: { enableIsolatedWorkspaces?: boolean; autoRestartDevServerWhenIdle?: boolean }) =>
+      instanceSettingsApi.updateExperimental(patch),
+    onSuccess: async () => {
+      setActionError(null);
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.instance.experimentalSettings }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.health }),
+      ]);
+    },
+    onError: (error) => {
+      setActionError(error instanceof Error ? error.message : "Failed to update experimental settings.");
+    },
+  });
+
+  if (experimentalQuery.isLoading) {
+    return <div className="text-sm text-muted-foreground">Loading experimental settings...</div>;
+  }
+
+  if (experimentalQuery.error) {
+    return (
+      <div className="text-sm text-destructive">
+        {experimentalQuery.error instanceof Error
+          ? experimentalQuery.error.message
+          : "Failed to load experimental settings."}
+      </div>
+    );
+  }
+
+  const enableIsolatedWorkspaces = experimentalQuery.data?.enableIsolatedWorkspaces === true;
+  const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;
+
+  return (
+    <div className="max-w-4xl space-y-6">
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <FlaskConical className="h-5 w-5 text-muted-foreground" />
+          <h1 className="text-lg font-semibold">Experimental</h1>
+        </div>
+        <p className="text-sm text-muted-foreground">
+          Opt into features that are still being evaluated before they become default behavior.
+        </p>
+      </div>
+
+      {actionError && (
+        <div className="rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+          {actionError}
+        </div>
+      )}
+
+      <section className="rounded-xl border border-border bg-card p-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="space-y-1.5">
+            <h2 className="text-sm font-semibold">Enable Isolated Workspaces</h2>
+            <p className="max-w-2xl text-sm text-muted-foreground">
+              Show execution workspace controls in project configuration and allow isolated workspace behavior for new
+              and existing issue runs.
+            </p>
+          </div>
+          <button
+            type="button"
+            data-slot="toggle"
+            aria-label="Toggle isolated workspaces experimental setting"
+            disabled={toggleMutation.isPending}
+            className={cn(
+              "relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-60",
+              enableIsolatedWorkspaces ? "bg-green-600" : "bg-muted",
+            )}
+            onClick={() => toggleMutation.mutate({ enableIsolatedWorkspaces: !enableIsolatedWorkspaces })}
+          >
+            <span
+              className={cn(
+                "inline-block h-3.5 w-3.5 rounded-full bg-white transition-transform",
+                enableIsolatedWorkspaces ? "translate-x-4.5" : "translate-x-0.5",
+              )}
+            />
+          </button>
+        </div>
+      </section>
+
+      <section className="rounded-xl border border-border bg-card p-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="space-y-1.5">
+            <h2 className="text-sm font-semibold">Auto-Restart Dev Server When Idle</h2>
+            <p className="max-w-2xl text-sm text-muted-foreground">
+              In `pnpm dev:once`, wait for all queued and running local agent runs to finish, then restart the server
+              automatically when backend changes or migrations make the current boot stale.
+            </p>
+          </div>
+          <button
+            type="button"
+            data-slot="toggle"
+            aria-label="Toggle guarded dev-server auto-restart"
+            disabled={toggleMutation.isPending}
+            className={cn(
+              "relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-60",
+              autoRestartDevServerWhenIdle ? "bg-green-600" : "bg-muted",
+            )}
+            onClick={() =>
+              toggleMutation.mutate({ autoRestartDevServerWhenIdle: !autoRestartDevServerWhenIdle })
+            }
+          >
+            <span
+              className={cn(
+                "inline-block h-3.5 w-3.5 rounded-full bg-white transition-transform",
+                autoRestartDevServerWhenIdle ? "translate-x-4.5" : "translate-x-0.5",
+              )}
+            />
+          </button>
+        </div>
+      </section>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/InstanceGeneralSettings.tsx

@@ -0,0 +1,104 @@
+import { useEffect, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { SlidersHorizontal } from "lucide-react";
+import { instanceSettingsApi } from "@/api/instanceSettings";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { cn } from "../lib/utils";
+
+export function InstanceGeneralSettings() {
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const [actionError, setActionError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Instance Settings" },
+      { label: "General" },
+    ]);
+  }, [setBreadcrumbs]);
+
+  const generalQuery = useQuery({
+    queryKey: queryKeys.instance.generalSettings,
+    queryFn: () => instanceSettingsApi.getGeneral(),
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: async (enabled: boolean) =>
+      instanceSettingsApi.updateGeneral({ censorUsernameInLogs: enabled }),
+    onSuccess: async () => {
+      setActionError(null);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.instance.generalSettings });
+    },
+    onError: (error) => {
+      setActionError(error instanceof Error ? error.message : "Failed to update general settings.");
+    },
+  });
+
+  if (generalQuery.isLoading) {
+    return <div className="text-sm text-muted-foreground">Loading general settings...</div>;
+  }
+
+  if (generalQuery.error) {
+    return (
+      <div className="text-sm text-destructive">
+        {generalQuery.error instanceof Error
+          ? generalQuery.error.message
+          : "Failed to load general settings."}
+      </div>
+    );
+  }
+
+  const censorUsernameInLogs = generalQuery.data?.censorUsernameInLogs === true;
+
+  return (
+    <div className="max-w-4xl space-y-6">
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <SlidersHorizontal className="h-5 w-5 text-muted-foreground" />
+          <h1 className="text-lg font-semibold">General</h1>
+        </div>
+        <p className="text-sm text-muted-foreground">
+          Configure instance-wide defaults that affect how operator-visible logs are displayed.
+        </p>
+      </div>
+
+      {actionError && (
+        <div className="rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+          {actionError}
+        </div>
+      )}
+
+      <section className="rounded-xl border border-border bg-card p-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="space-y-1.5">
+            <h2 className="text-sm font-semibold">Censor username in logs</h2>
+            <p className="max-w-2xl text-sm text-muted-foreground">
+              Hide the username segment in home-directory paths and similar operator-visible log output. Standalone
+              username mentions outside of paths are not yet masked in the live transcript view. This is off by
+              default.
+            </p>
+          </div>
+          <button
+            type="button"
+            data-slot="toggle"
+            aria-label="Toggle username log censoring"
+            disabled={toggleMutation.isPending}
+            className={cn(
+              "relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-60",
+              censorUsernameInLogs ? "bg-green-600" : "bg-muted",
+            )}
+            onClick={() => toggleMutation.mutate(!censorUsernameInLogs)}
+          >
+            <span
+              className={cn(
+                "inline-block h-3.5 w-3.5 rounded-full bg-white transition-transform",
+                censorUsernameInLogs ? "translate-x-4.5" : "translate-x-0.5",
+              )}
+            />
+          </button>
+        </div>
+      </section>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/InstanceSettings.tsx

@@ -0,0 +1,283 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Clock3, ExternalLink, Settings } from "lucide-react";
+import type { InstanceSchedulerHeartbeatAgent } from "@paperclipai/shared";
+import { Link } from "@/lib/router";
+import { heartbeatsApi } from "../api/heartbeats";
+import { agentsApi } from "../api/agents";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { EmptyState } from "../components/EmptyState";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { queryKeys } from "../lib/queryKeys";
+import { formatDateTime, relativeTime } from "../lib/utils";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function humanize(value: string) {
+  return value.replaceAll("_", " ");
+}
+
+function buildAgentHref(agent: InstanceSchedulerHeartbeatAgent) {
+  return `/${agent.companyIssuePrefix}/agents/${encodeURIComponent(agent.agentUrlKey)}`;
+}
+
+export function InstanceSettings() {
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const [actionError, setActionError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Instance Settings" },
+      { label: "Heartbeats" },
+    ]);
+  }, [setBreadcrumbs]);
+
+  const heartbeatsQuery = useQuery({
+    queryKey: queryKeys.instance.schedulerHeartbeats,
+    queryFn: () => heartbeatsApi.listInstanceSchedulerAgents(),
+    refetchInterval: 15_000,
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: async (agentRow: InstanceSchedulerHeartbeatAgent) => {
+      const agent = await agentsApi.get(agentRow.id, agentRow.companyId);
+      const runtimeConfig = asRecord(agent.runtimeConfig) ?? {};
+      const heartbeat = asRecord(runtimeConfig.heartbeat) ?? {};
+
+      return agentsApi.update(
+        agentRow.id,
+        {
+          runtimeConfig: {
+            ...runtimeConfig,
+            heartbeat: {
+              ...heartbeat,
+              enabled: !agentRow.heartbeatEnabled,
+            },
+          },
+        },
+        agentRow.companyId,
+      );
+    },
+    onSuccess: async (_, agentRow) => {
+      setActionError(null);
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.instance.schedulerHeartbeats }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(agentRow.companyId) }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agentRow.id) }),
+      ]);
+    },
+    onError: (error) => {
+      setActionError(error instanceof Error ? error.message : "Failed to update heartbeat.");
+    },
+  });
+
+  const disableAllMutation = useMutation({
+    mutationFn: async (agentRows: InstanceSchedulerHeartbeatAgent[]) => {
+      const enabled = agentRows.filter((a) => a.heartbeatEnabled);
+      if (enabled.length === 0) return enabled;
+
+      const results = await Promise.allSettled(
+        enabled.map(async (agentRow) => {
+          const agent = await agentsApi.get(agentRow.id, agentRow.companyId);
+          const runtimeConfig = asRecord(agent.runtimeConfig) ?? {};
+          const heartbeat = asRecord(runtimeConfig.heartbeat) ?? {};
+          await agentsApi.update(
+            agentRow.id,
+            {
+              runtimeConfig: {
+                ...runtimeConfig,
+                heartbeat: { ...heartbeat, enabled: false },
+              },
+            },
+            agentRow.companyId,
+          );
+        }),
+      );
+
+      const failures = results.filter((result): result is PromiseRejectedResult => result.status === "rejected");
+      if (failures.length > 0) {
+        const firstError = failures[0]?.reason;
+        const detail = firstError instanceof Error ? firstError.message : "Unknown error";
+        throw new Error(
+          failures.length === 1
+            ? `Failed to disable 1 timer heartbeat: ${detail}`
+            : `Failed to disable ${failures.length} of ${enabled.length} timer heartbeats. First error: ${detail}`,
+        );
+      }
+      return enabled;
+    },
+    onSuccess: async (updatedRows) => {
+      setActionError(null);
+      const companies = new Set(updatedRows.map((row) => row.companyId));
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.instance.schedulerHeartbeats }),
+        ...Array.from(companies, (companyId) =>
+          queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(companyId) }),
+        ),
+        ...updatedRows.map((row) =>
+          queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(row.id) }),
+        ),
+      ]);
+    },
+    onError: (error) => {
+      setActionError(error instanceof Error ? error.message : "Failed to disable all heartbeats.");
+    },
+  });
+
+  const agents = heartbeatsQuery.data ?? [];
+  const activeCount = agents.filter((agent) => agent.schedulerActive).length;
+  const disabledCount = agents.length - activeCount;
+  const enabledCount = agents.filter((agent) => agent.heartbeatEnabled).length;
+  const anyEnabled = enabledCount > 0;
+
+  const grouped = useMemo(() => {
+    const map = new Map<string, { companyName: string; agents: InstanceSchedulerHeartbeatAgent[] }>();
+    for (const agent of agents) {
+      let group = map.get(agent.companyId);
+      if (!group) {
+        group = { companyName: agent.companyName, agents: [] };
+        map.set(agent.companyId, group);
+      }
+      group.agents.push(agent);
+    }
+    return [...map.values()];
+  }, [agents]);
+
+  if (heartbeatsQuery.isLoading) {
+    return <div className="text-sm text-muted-foreground">Loading scheduler heartbeats...</div>;
+  }
+
+  if (heartbeatsQuery.error) {
+    return (
+      <div className="text-sm text-destructive">
+        {heartbeatsQuery.error instanceof Error
+          ? heartbeatsQuery.error.message
+          : "Failed to load scheduler heartbeats."}
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-5xl space-y-6">
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <Settings className="h-5 w-5 text-muted-foreground" />
+          <h1 className="text-lg font-semibold">Scheduler Heartbeats</h1>
+        </div>
+        <p className="text-sm text-muted-foreground">
+          Agents with a timer heartbeat enabled across all of your companies.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 text-sm text-muted-foreground">
+        <span><span className="font-semibold text-foreground">{activeCount}</span> active</span>
+        <span><span className="font-semibold text-foreground">{disabledCount}</span> disabled</span>
+        <span><span className="font-semibold text-foreground">{grouped.length}</span> {grouped.length === 1 ? "company" : "companies"}</span>
+        {anyEnabled && (
+          <Button
+            variant="destructive"
+            size="sm"
+            className="ml-auto h-7 text-xs"
+            disabled={disableAllMutation.isPending}
+            onClick={() => {
+              const noun = enabledCount === 1 ? "agent" : "agents";
+              if (!window.confirm(`Disable timer heartbeats for all ${enabledCount} enabled ${noun}?`)) {
+                return;
+              }
+              disableAllMutation.mutate(agents);
+            }}
+          >
+            {disableAllMutation.isPending ? "Disabling..." : "Disable All"}
+          </Button>
+        )}
+      </div>
+
+      {actionError && (
+        <div className="rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+          {actionError}
+        </div>
+      )}
+
+      {agents.length === 0 ? (
+        <EmptyState
+          icon={Clock3}
+          message="No scheduler heartbeats match the current criteria."
+        />
+      ) : (
+        <div className="space-y-4">
+          {grouped.map((group) => (
+            <Card key={group.companyName}>
+              <CardContent className="p-0">
+                <div className="border-b px-3 py-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                  {group.companyName}
+                </div>
+                <div className="divide-y">
+                  {group.agents.map((agent) => {
+                    const saving = toggleMutation.isPending && toggleMutation.variables?.id === agent.id;
+                    return (
+                      <div
+                        key={agent.id}
+                        className="flex items-center gap-3 px-3 py-2 text-sm"
+                      >
+                        <Badge
+                          variant={agent.schedulerActive ? "default" : "outline"}
+                          className="shrink-0 text-[10px] px-1.5 py-0"
+                        >
+                          {agent.schedulerActive ? "On" : "Off"}
+                        </Badge>
+                        <Link
+                          to={buildAgentHref(agent)}
+                          className="font-medium truncate hover:underline"
+                        >
+                          {agent.agentName}
+                        </Link>
+                        <span className="hidden sm:inline text-muted-foreground truncate">
+                          {humanize(agent.title ?? agent.role)}
+                        </span>
+                        <span className="text-muted-foreground tabular-nums shrink-0">
+                          {agent.intervalSec}s
+                        </span>
+                        <span
+                          className="hidden md:inline text-muted-foreground truncate"
+                          title={agent.lastHeartbeatAt ? formatDateTime(agent.lastHeartbeatAt) : undefined}
+                        >
+                          {agent.lastHeartbeatAt
+                            ? relativeTime(agent.lastHeartbeatAt)
+                            : "never"}
+                        </span>
+                        <span className="ml-auto flex items-center gap-1.5 shrink-0">
+                          <Link
+                            to={buildAgentHref(agent)}
+                            className="text-muted-foreground hover:text-foreground"
+                            title="Full agent config"
+                          >
+                            <ExternalLink className="h-3.5 w-3.5" />
+                          </Link>
+                          <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-6 px-2 text-xs"
+                            disabled={saving}
+                            onClick={() => toggleMutation.mutate(agent)}
+                          >
+                            {saving ? "..." : agent.heartbeatEnabled ? "Disable Timer Heartbeat" : "Enable Timer Heartbeat"}
+                          </Button>
+                        </span>
+                      </div>
+                    );
+                  })}
+                </div>
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/InviteLanding.tsx

@@ -0,0 +1,319 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Link, useParams } from "@/lib/router";
+import { accessApi } from "../api/access";
+import { authApi } from "../api/auth";
+import { healthApi } from "../api/health";
+import { queryKeys } from "../lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { AGENT_ADAPTER_TYPES } from "@paperclipai/shared";
+import type { AgentAdapterType, JoinRequest } from "@paperclipai/shared";
+
+type JoinType = "human" | "agent";
+const joinAdapterOptions: AgentAdapterType[] = [...AGENT_ADAPTER_TYPES];
+
+const adapterLabels: Record<string, string> = {
+  claude_local: "Claude (local)",
+  codex_local: "Codex (local)",
+  gemini_local: "Gemini CLI (local)",
+  opencode_local: "OpenCode (local)",
+  pi_local: "Pi (local)",
+  openclaw_gateway: "OpenClaw Gateway",
+  cursor: "Cursor (local)",
+  process: "Process",
+  http: "HTTP",
+};
+
+const ENABLED_INVITE_ADAPTERS = new Set(["claude_local", "codex_local", "gemini_local", "opencode_local", "pi_local", "cursor"]);
+
+function dateTime(value: string) {
+  return new Date(value).toLocaleString();
+}
+
+function readNestedString(value: unknown, path: string[]): string | null {
+  let current: unknown = value;
+  for (const segment of path) {
+    if (!current || typeof current !== "object") return null;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return typeof current === "string" && current.trim().length > 0 ? current : null;
+}
+
+export function InviteLandingPage() {
+  const queryClient = useQueryClient();
+  const params = useParams();
+  const token = (params.token ?? "").trim();
+  const [joinType, setJoinType] = useState<JoinType>("human");
+  const [agentName, setAgentName] = useState("");
+  const [adapterType, setAdapterType] = useState<AgentAdapterType>("claude_local");
+  const [capabilities, setCapabilities] = useState("");
+  const [result, setResult] = useState<{ kind: "bootstrap" | "join"; payload: unknown } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const healthQuery = useQuery({
+    queryKey: queryKeys.health,
+    queryFn: () => healthApi.get(),
+    retry: false,
+  });
+  const sessionQuery = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+    retry: false,
+  });
+  const inviteQuery = useQuery({
+    queryKey: queryKeys.access.invite(token),
+    queryFn: () => accessApi.getInvite(token),
+    enabled: token.length > 0,
+    retry: false,
+  });
+
+  const invite = inviteQuery.data;
+  const allowedJoinTypes = invite?.allowedJoinTypes ?? "both";
+  const availableJoinTypes = useMemo(() => {
+    if (invite?.inviteType === "bootstrap_ceo") return ["human"] as JoinType[];
+    if (allowedJoinTypes === "both") return ["human", "agent"] as JoinType[];
+    return [allowedJoinTypes] as JoinType[];
+  }, [invite?.inviteType, allowedJoinTypes]);
+
+  useEffect(() => {
+    if (!availableJoinTypes.includes(joinType)) {
+      setJoinType(availableJoinTypes[0] ?? "human");
+    }
+  }, [availableJoinTypes, joinType]);
+
+  const requiresAuthForHuman =
+    joinType === "human" &&
+    healthQuery.data?.deploymentMode === "authenticated" &&
+    !sessionQuery.data;
+
+  const acceptMutation = useMutation({
+    mutationFn: async () => {
+      if (!invite) throw new Error("Invite not found");
+      if (invite.inviteType === "bootstrap_ceo") {
+        return accessApi.acceptInvite(token, { requestType: "human" });
+      }
+      if (joinType === "human") {
+        return accessApi.acceptInvite(token, { requestType: "human" });
+      }
+      return accessApi.acceptInvite(token, {
+        requestType: "agent",
+        agentName: agentName.trim(),
+        adapterType,
+        capabilities: capabilities.trim() || null,
+      });
+    },
+    onSuccess: async (payload) => {
+      setError(null);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      const asBootstrap =
+        payload && typeof payload === "object" && "bootstrapAccepted" in (payload as Record<string, unknown>);
+      setResult({ kind: asBootstrap ? "bootstrap" : "join", payload });
+    },
+    onError: (err) => {
+      setError(err instanceof Error ? err.message : "Failed to accept invite");
+    },
+  });
+
+  if (!token) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-destructive">Invalid invite token.</div>;
+  }
+
+  if (inviteQuery.isLoading || healthQuery.isLoading || sessionQuery.isLoading) {
+    return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading invite...</div>;
+  }
+
+  if (inviteQuery.error || !invite) {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Invite not available</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            This invite may be expired, revoked, or already used.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  if (result?.kind === "bootstrap") {
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Bootstrap complete</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            The first instance admin is now configured. You can continue to the board.
+          </p>
+          <Button asChild className="mt-4">
+            <Link to="/">Open board</Link>
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  if (result?.kind === "join") {
+    const payload = result.payload as JoinRequest & {
+      claimSecret?: string;
+      claimApiKeyPath?: string;
+      onboarding?: Record<string, unknown>;
+      diagnostics?: Array<{
+        code: string;
+        level: "info" | "warn";
+        message: string;
+        hint?: string;
+      }>;
+    };
+    const claimSecret = typeof payload.claimSecret === "string" ? payload.claimSecret : null;
+    const claimApiKeyPath = typeof payload.claimApiKeyPath === "string" ? payload.claimApiKeyPath : null;
+    const onboardingSkillUrl = readNestedString(payload.onboarding, ["skill", "url"]);
+    const onboardingSkillPath = readNestedString(payload.onboarding, ["skill", "path"]);
+    const onboardingInstallPath = readNestedString(payload.onboarding, ["skill", "installPath"]);
+    const onboardingTextUrl = readNestedString(payload.onboarding, ["textInstructions", "url"]);
+    const onboardingTextPath = readNestedString(payload.onboarding, ["textInstructions", "path"]);
+    const diagnostics = Array.isArray(payload.diagnostics) ? payload.diagnostics : [];
+    return (
+      <div className="mx-auto max-w-xl py-10">
+        <div className="rounded-lg border border-border bg-card p-6">
+          <h1 className="text-lg font-semibold">Join request submitted</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Your request is pending admin approval. You will not have access until approved.
+          </p>
+          <div className="mt-4 rounded-md border border-border bg-muted/30 p-3 text-xs text-muted-foreground">
+            Request ID: <span className="font-mono">{payload.id}</span>
+          </div>
+          {claimSecret && claimApiKeyPath && (
+            <div className="mt-3 space-y-1 rounded-md border border-border bg-muted/30 p-3 text-xs text-muted-foreground">
+              <p className="font-medium text-foreground">One-time claim secret (save now)</p>
+              <p className="font-mono break-all">{claimSecret}</p>
+              <p className="font-mono break-all">POST {claimApiKeyPath}</p>
+            </div>
+          )}
+          {(onboardingSkillUrl || onboardingSkillPath || onboardingInstallPath) && (
+            <div className="mt-3 space-y-1 rounded-md border border-border bg-muted/30 p-3 text-xs text-muted-foreground">
+              <p className="font-medium text-foreground">Paperclip skill bootstrap</p>
+              {onboardingSkillUrl && <p className="font-mono break-all">GET {onboardingSkillUrl}</p>}
+              {!onboardingSkillUrl && onboardingSkillPath && <p className="font-mono break-all">GET {onboardingSkillPath}</p>}
+              {onboardingInstallPath && <p className="font-mono break-all">Install to {onboardingInstallPath}</p>}
+            </div>
+          )}
+          {(onboardingTextUrl || onboardingTextPath) && (
+            <div className="mt-3 space-y-1 rounded-md border border-border bg-muted/30 p-3 text-xs text-muted-foreground">
+              <p className="font-medium text-foreground">Agent-readable onboarding text</p>
+              {onboardingTextUrl && <p className="font-mono break-all">GET {onboardingTextUrl}</p>}
+              {!onboardingTextUrl && onboardingTextPath && <p className="font-mono break-all">GET {onboardingTextPath}</p>}
+            </div>
+          )}
+          {diagnostics.length > 0 && (
+            <div className="mt-3 space-y-1 rounded-md border border-border bg-muted/30 p-3 text-xs text-muted-foreground">
+              <p className="font-medium text-foreground">Connectivity diagnostics</p>
+              {diagnostics.map((diag, idx) => (
+                <div key={`${diag.code}:${idx}`} className="space-y-0.5">
+                  <p className={diag.level === "warn" ? "text-amber-600 dark:text-amber-400" : undefined}>
+                    [{diag.level}] {diag.message}
+                  </p>
+                  {diag.hint && <p className="font-mono break-all">{diag.hint}</p>}
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">
+        <h1 className="text-xl font-semibold">
+          {invite.inviteType === "bootstrap_ceo" ? "Bootstrap your Paperclip instance" : "Join this Paperclip company"}
+        </h1>
+        <p className="mt-2 text-sm text-muted-foreground">Invite expires {dateTime(invite.expiresAt)}.</p>
+
+        {invite.inviteType !== "bootstrap_ceo" && (
+          <div className="mt-5 flex gap-2">
+            {availableJoinTypes.map((type) => (
+              <button
+                key={type}
+                type="button"
+                onClick={() => setJoinType(type)}
+                className={`rounded-md border px-3 py-1.5 text-sm ${
+                  joinType === type
+                    ? "border-foreground bg-foreground text-background"
+                    : "border-border bg-background text-foreground"
+                }`}
+              >
+                Join as {type}
+              </button>
+            ))}
+          </div>
+        )}
+
+        {joinType === "agent" && invite.inviteType !== "bootstrap_ceo" && (
+          <div className="mt-4 space-y-3">
+            <label className="block text-sm">
+              <span className="mb-1 block text-muted-foreground">Agent name</span>
+              <input
+                className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm"
+                value={agentName}
+                onChange={(event) => setAgentName(event.target.value)}
+              />
+            </label>
+            <label className="block text-sm">
+              <span className="mb-1 block text-muted-foreground">Adapter type</span>
+              <select
+                className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm"
+                value={adapterType}
+                onChange={(event) => setAdapterType(event.target.value as AgentAdapterType)}
+              >
+                {joinAdapterOptions.map((type) => (
+                  <option key={type} value={type} disabled={!ENABLED_INVITE_ADAPTERS.has(type)}>
+                    {adapterLabels[type]}{!ENABLED_INVITE_ADAPTERS.has(type) ? " (Coming soon)" : ""}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="block text-sm">
+              <span className="mb-1 block text-muted-foreground">Capabilities (optional)</span>
+              <textarea
+                className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm"
+                rows={4}
+                value={capabilities}
+                onChange={(event) => setCapabilities(event.target.value)}
+              />
+            </label>
+          </div>
+        )}
+
+        {requiresAuthForHuman && (
+          <div className="mt-4 rounded-md border border-border bg-muted/30 p-3 text-sm">
+            Sign in or create an account before submitting a human join request.
+            <div className="mt-2">
+              <Button asChild size="sm" variant="outline">
+                <Link to={`/auth?next=${encodeURIComponent(`/invite/${token}`)}`}>Sign in / Create account</Link>
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {error && <p className="mt-3 text-sm text-destructive">{error}</p>}
+
+        <Button
+          className="mt-5"
+          disabled={
+            acceptMutation.isPending ||
+            (joinType === "agent" && invite.inviteType !== "bootstrap_ceo" && agentName.trim().length === 0) ||
+            requiresAuthForHuman
+          }
+          onClick={() => acceptMutation.mutate()}
+        >
+          {acceptMutation.isPending
+            ? "Submitting…"
+            : invite.inviteType === "bootstrap_ceo"
+              ? "Accept bootstrap invite"
+              : "Submit join request"}
+        </Button>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Issues.tsx

@@ -0,0 +1,124 @@
+import { useEffect, useMemo, useCallback, useRef } from "react";
+import { useLocation, useSearchParams } from "@/lib/router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { issuesApi } from "../api/issues";
+import { agentsApi } from "../api/agents";
+import { projectsApi } from "../api/projects";
+import { heartbeatsApi } from "../api/heartbeats";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { createIssueDetailLocationState } from "../lib/issueDetailBreadcrumb";
+import { EmptyState } from "../components/EmptyState";
+import { IssuesList } from "../components/IssuesList";
+import { CircleDot } from "lucide-react";
+
+export function Issues() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const location = useLocation();
+  const [searchParams] = useSearchParams();
+  const queryClient = useQueryClient();
+
+  const initialSearch = searchParams.get("q") ?? "";
+  const participantAgentId = searchParams.get("participantAgentId") ?? undefined;
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const handleSearchChange = useCallback((search: string) => {
+    clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => {
+      const trimmedSearch = search.trim();
+      const currentSearch = new URLSearchParams(window.location.search).get("q") ?? "";
+      if (currentSearch === trimmedSearch) return;
+
+      const url = new URL(window.location.href);
+      if (trimmedSearch) {
+        url.searchParams.set("q", trimmedSearch);
+      } else {
+        url.searchParams.delete("q");
+      }
+
+      const nextUrl = `${url.pathname}${url.search}${url.hash}`;
+      window.history.replaceState(window.history.state, "", nextUrl);
+    }, 300);
+  }, []);
+
+  useEffect(() => {
+    return () => clearTimeout(debounceRef.current);
+  }, []);
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: projects } = useQuery({
+    queryKey: queryKeys.projects.list(selectedCompanyId!),
+    queryFn: () => projectsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: liveRuns } = useQuery({
+    queryKey: queryKeys.liveRuns(selectedCompanyId!),
+    queryFn: () => heartbeatsApi.liveRunsForCompany(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+    refetchInterval: 5000,
+  });
+
+  const liveIssueIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const run of liveRuns ?? []) {
+      if (run.issueId) ids.add(run.issueId);
+    }
+    return ids;
+  }, [liveRuns]);
+
+  const issueLinkState = useMemo(
+    () =>
+      createIssueDetailLocationState(
+        "Issues",
+        `${location.pathname}${location.search}${location.hash}`,
+      ),
+    [location.pathname, location.search, location.hash],
+  );
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Issues" }]);
+  }, [setBreadcrumbs]);
+
+  const { data: issues, isLoading, error } = useQuery({
+    queryKey: [...queryKeys.issues.list(selectedCompanyId!), "participant-agent", participantAgentId ?? "__all__"],
+    queryFn: () => issuesApi.list(selectedCompanyId!, { participantAgentId }),
+    enabled: !!selectedCompanyId,
+  });
+
+  const updateIssue = useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Record<string, unknown> }) =>
+      issuesApi.update(id, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.issues.list(selectedCompanyId!) });
+    },
+  });
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={CircleDot} message="Select a company to view issues." />;
+  }
+
+  return (
+    <IssuesList
+      issues={issues ?? []}
+      isLoading={isLoading}
+      error={error as Error | null}
+      agents={agents}
+      projects={projects}
+      liveIssueIds={liveIssueIds}
+      viewStateKey="paperclip:issues-view"
+      issueLinkState={issueLinkState}
+      initialAssignees={searchParams.get("assignee") ? [searchParams.get("assignee")!] : undefined}
+      initialSearch={initialSearch}
+      onSearchChange={handleSearchChange}
+      onUpdateIssue={(id, data) => updateIssue.mutate({ id, data })}
+      searchFilters={participantAgentId ? { participantAgentId } : undefined}
+    />
+  );
+}

paperclip-reference/ui/src/pages/MyIssues.tsx

@@ -0,0 +1,72 @@
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { issuesApi } from "../api/issues";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { StatusIcon } from "../components/StatusIcon";
+
+import { EntityRow } from "../components/EntityRow";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { formatDate } from "../lib/utils";
+import { ListTodo } from "lucide-react";
+
+export function MyIssues() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "My Issues" }]);
+  }, [setBreadcrumbs]);
+
+  const { data: issues, isLoading, error } = useQuery({
+    queryKey: queryKeys.issues.list(selectedCompanyId!),
+    queryFn: () => issuesApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={ListTodo} message="Select a company to view your issues." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  // Show issues that are not assigned (user-created or unassigned)
+  const myIssues = (issues ?? []).filter(
+    (i) => !i.assigneeAgentId && !["done", "cancelled"].includes(i.status)
+  );
+
+  return (
+    <div className="space-y-4">
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {myIssues.length === 0 && (
+        <EmptyState icon={ListTodo} message="No issues assigned to you." />
+      )}
+
+      {myIssues.length > 0 && (
+        <div className="border border-border">
+          {myIssues.map((issue) => (
+            <EntityRow
+              key={issue.id}
+              identifier={issue.identifier ?? issue.id.slice(0, 8)}
+              title={issue.title}
+              to={`/issues/${issue.identifier ?? issue.id}`}
+              leading={
+                <StatusIcon status={issue.status} />
+              }
+              trailing={
+                <span className="text-xs text-muted-foreground">
+                  {formatDate(issue.createdAt)}
+                </span>
+              }
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/NewAgent.tsx

@@ -0,0 +1,352 @@
+import { useState, useEffect } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useSearchParams } from "@/lib/router";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { agentsApi } from "../api/agents";
+import { companySkillsApi } from "../api/companySkills";
+import { queryKeys } from "../lib/queryKeys";
+import { AGENT_ROLES } from "@paperclipai/shared";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Shield } from "lucide-react";
+import { cn, agentUrl } from "../lib/utils";
+import { roleLabels } from "../components/agent-config-primitives";
+import { AgentConfigForm, type CreateConfigValues } from "../components/AgentConfigForm";
+import { defaultCreateValues } from "../components/agent-config-defaults";
+import { getUIAdapter } from "../adapters";
+import { ReportsToPicker } from "../components/ReportsToPicker";
+import {
+  DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX,
+  DEFAULT_CODEX_LOCAL_MODEL,
+} from "@paperclipai/adapter-codex-local";
+import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
+import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+
+const SUPPORTED_ADVANCED_ADAPTER_TYPES = new Set<CreateConfigValues["adapterType"]>([
+  "claude_local",
+  "codex_local",
+  "gemini_local",
+  "opencode_local",
+  "pi_local",
+  "cursor",
+  "openclaw_gateway",
+]);
+
+function createValuesForAdapterType(
+  adapterType: CreateConfigValues["adapterType"],
+): CreateConfigValues {
+  const { adapterType: _discard, ...defaults } = defaultCreateValues;
+  const nextValues: CreateConfigValues = { ...defaults, adapterType };
+  if (adapterType === "codex_local") {
+    nextValues.model = DEFAULT_CODEX_LOCAL_MODEL;
+    nextValues.dangerouslyBypassSandbox =
+      DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX;
+  } else if (adapterType === "gemini_local") {
+    nextValues.model = DEFAULT_GEMINI_LOCAL_MODEL;
+  } else if (adapterType === "cursor") {
+    nextValues.model = DEFAULT_CURSOR_LOCAL_MODEL;
+  } else if (adapterType === "opencode_local") {
+    nextValues.model = "";
+  }
+  return nextValues;
+}
+
+export function NewAgent() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const presetAdapterType = searchParams.get("adapterType");
+
+  const [name, setName] = useState("");
+  const [title, setTitle] = useState("");
+  const [role, setRole] = useState("general");
+  const [reportsTo, setReportsTo] = useState<string | null>(null);
+  const [configValues, setConfigValues] = useState<CreateConfigValues>(defaultCreateValues);
+  const [selectedSkillKeys, setSelectedSkillKeys] = useState<string[]>([]);
+  const [roleOpen, setRoleOpen] = useState(false);
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const {
+    data: adapterModels,
+    error: adapterModelsError,
+    isLoading: adapterModelsLoading,
+    isFetching: adapterModelsFetching,
+  } = useQuery({
+    queryKey: selectedCompanyId
+      ? queryKeys.agents.adapterModels(selectedCompanyId, configValues.adapterType)
+      : ["agents", "none", "adapter-models", configValues.adapterType],
+    queryFn: () => agentsApi.adapterModels(selectedCompanyId!, configValues.adapterType),
+    enabled: Boolean(selectedCompanyId),
+  });
+
+  const { data: companySkills } = useQuery({
+    queryKey: queryKeys.companySkills.list(selectedCompanyId ?? ""),
+    queryFn: () => companySkillsApi.list(selectedCompanyId!),
+    enabled: Boolean(selectedCompanyId),
+  });
+
+  const isFirstAgent = !agents || agents.length === 0;
+  const effectiveRole = isFirstAgent ? "ceo" : role;
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Agents", href: "/agents" },
+      { label: "New Agent" },
+    ]);
+  }, [setBreadcrumbs]);
+
+  useEffect(() => {
+    if (isFirstAgent) {
+      if (!name) setName("CEO");
+      if (!title) setTitle("CEO");
+    }
+  }, [isFirstAgent]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    const requested = presetAdapterType;
+    if (!requested) return;
+    if (!SUPPORTED_ADVANCED_ADAPTER_TYPES.has(requested as CreateConfigValues["adapterType"])) {
+      return;
+    }
+    setConfigValues((prev) => {
+      if (prev.adapterType === requested) return prev;
+      return createValuesForAdapterType(requested as CreateConfigValues["adapterType"]);
+    });
+  }, [presetAdapterType]);
+
+  const createAgent = useMutation({
+    mutationFn: (data: Record<string, unknown>) =>
+      agentsApi.hire(selectedCompanyId!, data),
+    onSuccess: (result) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(selectedCompanyId!) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.approvals.list(selectedCompanyId!) });
+      navigate(agentUrl(result.agent));
+    },
+    onError: (error) => {
+      setFormError(error instanceof Error ? error.message : "Failed to create agent");
+    },
+  });
+
+  function buildAdapterConfig() {
+    const adapter = getUIAdapter(configValues.adapterType);
+    return adapter.buildAdapterConfig(configValues);
+  }
+
+  function handleSubmit() {
+    if (!selectedCompanyId || !name.trim()) return;
+    setFormError(null);
+    if (configValues.adapterType === "opencode_local") {
+      const selectedModel = configValues.model.trim();
+      if (!selectedModel) {
+        setFormError("OpenCode requires an explicit model in provider/model format.");
+        return;
+      }
+      if (adapterModelsError) {
+        setFormError(
+          adapterModelsError instanceof Error
+            ? adapterModelsError.message
+            : "Failed to load OpenCode models.",
+        );
+        return;
+      }
+      if (adapterModelsLoading || adapterModelsFetching) {
+        setFormError("OpenCode models are still loading. Please wait and try again.");
+        return;
+      }
+      const discovered = adapterModels ?? [];
+      if (!discovered.some((entry) => entry.id === selectedModel)) {
+        setFormError(
+          discovered.length === 0
+            ? "No OpenCode models discovered. Run `opencode models` and authenticate providers."
+            : `Configured OpenCode model is unavailable: ${selectedModel}`,
+        );
+        return;
+      }
+    }
+    createAgent.mutate({
+      name: name.trim(),
+      role: effectiveRole,
+      ...(title.trim() ? { title: title.trim() } : {}),
+      ...(reportsTo ? { reportsTo } : {}),
+      ...(selectedSkillKeys.length > 0 ? { desiredSkills: selectedSkillKeys } : {}),
+      adapterType: configValues.adapterType,
+      adapterConfig: buildAdapterConfig(),
+      runtimeConfig: {
+        heartbeat: {
+          enabled: configValues.heartbeatEnabled,
+          intervalSec: configValues.intervalSec,
+          wakeOnDemand: true,
+          cooldownSec: 10,
+          maxConcurrentRuns: 1,
+        },
+      },
+      budgetMonthlyCents: 0,
+    });
+  }
+
+  const availableSkills = (companySkills ?? []).filter((skill) => !skill.key.startsWith("paperclipai/paperclip/"));
+
+  function toggleSkill(key: string, checked: boolean) {
+    setSelectedSkillKeys((prev) => {
+      if (checked) {
+        return prev.includes(key) ? prev : [...prev, key];
+      }
+      return prev.filter((value) => value !== key);
+    });
+  }
+
+  return (
+    <div className="mx-auto max-w-2xl space-y-6">
+      <div>
+        <h1 className="text-lg font-semibold">New Agent</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Advanced agent configuration
+        </p>
+      </div>
+
+      <div className="border border-border">
+        {/* Name */}
+        <div className="px-4 pt-4 pb-2">
+          <input
+            className="w-full text-lg font-semibold bg-transparent outline-none placeholder:text-muted-foreground/50"
+            placeholder="Agent name"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            autoFocus
+          />
+        </div>
+
+        {/* Title */}
+        <div className="px-4 pb-2">
+          <input
+            className="w-full bg-transparent outline-none text-sm text-muted-foreground placeholder:text-muted-foreground/40"
+            placeholder="Title (e.g. VP of Engineering)"
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+          />
+        </div>
+
+        {/* Property chips: Role + Reports To */}
+        <div className="flex items-center gap-1.5 px-4 py-2 border-t border-border flex-wrap">
+          <Popover open={roleOpen} onOpenChange={setRoleOpen}>
+            <PopoverTrigger asChild>
+              <button
+                className={cn(
+                  "inline-flex items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs hover:bg-accent/50 transition-colors",
+                  isFirstAgent && "opacity-60 cursor-not-allowed"
+                )}
+                disabled={isFirstAgent}
+              >
+                <Shield className="h-3 w-3 text-muted-foreground" />
+                {roleLabels[effectiveRole] ?? effectiveRole}
+              </button>
+            </PopoverTrigger>
+            <PopoverContent className="w-36 p-1" align="start">
+              {AGENT_ROLES.map((r) => (
+                <button
+                  key={r}
+                  className={cn(
+                    "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
+                    r === role && "bg-accent"
+                  )}
+                  onClick={() => { setRole(r); setRoleOpen(false); }}
+                >
+                  {roleLabels[r] ?? r}
+                </button>
+              ))}
+            </PopoverContent>
+          </Popover>
+
+          <ReportsToPicker
+            agents={agents ?? []}
+            value={reportsTo}
+            onChange={setReportsTo}
+            disabled={isFirstAgent}
+          />
+        </div>
+
+        {/* Shared config form */}
+        <AgentConfigForm
+          mode="create"
+          values={configValues}
+          onChange={(patch) => setConfigValues((prev) => ({ ...prev, ...patch }))}
+          adapterModels={adapterModels}
+        />
+
+        <div className="border-t border-border px-4 py-4">
+          <div className="space-y-3">
+            <div>
+              <h2 className="text-sm font-medium">Company skills</h2>
+              <p className="mt-1 text-xs text-muted-foreground">
+                Optional skills from the company library. Built-in Paperclip runtime skills are added automatically.
+              </p>
+            </div>
+            {availableSkills.length === 0 ? (
+              <p className="text-xs text-muted-foreground">
+                No optional company skills installed yet.
+              </p>
+            ) : (
+              <div className="space-y-3">
+                {availableSkills.map((skill) => {
+                  const inputId = `skill-${skill.id}`;
+                  const checked = selectedSkillKeys.includes(skill.key);
+                  return (
+                    <div key={skill.id} className="flex items-start gap-3">
+                      <Checkbox
+                        id={inputId}
+                        checked={checked}
+                        onCheckedChange={(next) => toggleSkill(skill.key, next === true)}
+                      />
+                      <label htmlFor={inputId} className="grid gap-1 leading-none">
+                        <span className="text-sm font-medium">{skill.name}</span>
+                        <span className="text-xs text-muted-foreground">
+                          {skill.description ?? skill.key}
+                        </span>
+                      </label>
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="border-t border-border px-4 py-3">
+          {isFirstAgent && (
+            <p className="text-xs text-muted-foreground mb-2">This will be the CEO</p>
+          )}
+          {formError && (
+            <p className="text-xs text-destructive mb-2">{formError}</p>
+          )}
+          <div className="flex items-center justify-end gap-2">
+            <Button variant="outline" size="sm" onClick={() => navigate("/agents")}>
+              Cancel
+            </Button>
+            <Button
+              size="sm"
+              disabled={!name.trim() || createAgent.isPending}
+              onClick={handleSubmit}
+            >
+              {createAgent.isPending ? "Creating…" : "Create agent"}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/NotFound.tsx

@@ -0,0 +1,66 @@
+import { useEffect } from "react";
+import { Link, useLocation } from "@/lib/router";
+import { AlertTriangle, Compass } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useCompany } from "../context/CompanyContext";
+
+type NotFoundScope = "board" | "invalid_company_prefix" | "global";
+
+interface NotFoundPageProps {
+  scope?: NotFoundScope;
+  requestedPrefix?: string;
+}
+
+export function NotFoundPage({ scope = "global", requestedPrefix }: NotFoundPageProps) {
+  const location = useLocation();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const { companies, selectedCompany } = useCompany();
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Not Found" }]);
+  }, [setBreadcrumbs]);
+
+  const fallbackCompany = selectedCompany ?? companies[0] ?? null;
+  const dashboardHref = fallbackCompany ? `/${fallbackCompany.issuePrefix}/dashboard` : "/";
+  const currentPath = `${location.pathname}${location.search}${location.hash}`;
+  const normalizedPrefix = requestedPrefix?.toUpperCase();
+
+  const title = scope === "invalid_company_prefix" ? "Company not found" : "Page not found";
+  const description =
+    scope === "invalid_company_prefix"
+      ? `No company matches prefix "${normalizedPrefix ?? "unknown"}".`
+      : "This route does not exist.";
+
+  return (
+    <div className="mx-auto max-w-2xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">
+        <div className="flex items-center gap-3">
+          <div className="rounded-md border border-destructive/20 bg-destructive/10 p-2">
+            <AlertTriangle className="h-5 w-5 text-destructive" />
+          </div>
+          <div>
+            <h1 className="text-xl font-semibold">{title}</h1>
+            <p className="text-sm text-muted-foreground">{description}</p>
+          </div>
+        </div>
+
+        <div className="mt-4 rounded-md border border-border bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
+          Requested path: <code className="font-mono">{currentPath}</code>
+        </div>
+
+        <div className="mt-5 flex flex-wrap gap-2">
+          <Button asChild>
+            <Link to={dashboardHref}>
+              <Compass className="mr-1.5 h-4 w-4" />
+              Open dashboard
+            </Link>
+          </Button>
+          <Button variant="outline" asChild>
+            <Link to="/">Go home</Link>
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Org.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useState } from "react";
+import { Link } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { agentsApi, type OrgNode } from "../api/agents";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { StatusBadge } from "../components/StatusBadge";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { ChevronRight, GitBranch } from "lucide-react";
+import { cn } from "../lib/utils";
+
+function OrgTree({
+  nodes,
+  depth = 0,
+  hrefFn,
+}: {
+  nodes: OrgNode[];
+  depth?: number;
+  hrefFn: (id: string) => string;
+}) {
+  return (
+    <div>
+      {nodes.map((node) => (
+        <OrgTreeNode key={node.id} node={node} depth={depth} hrefFn={hrefFn} />
+      ))}
+    </div>
+  );
+}
+
+function OrgTreeNode({
+  node,
+  depth,
+  hrefFn,
+}: {
+  node: OrgNode;
+  depth: number;
+  hrefFn: (id: string) => string;
+}) {
+  const [expanded, setExpanded] = useState(true);
+  const hasChildren = node.reports.length > 0;
+
+  return (
+    <div>
+      <Link
+        to={hrefFn(node.id)}
+        className="flex items-center gap-2 px-3 py-2 rounded-md text-sm transition-colors cursor-pointer hover:bg-accent/50 no-underline text-inherit"
+        style={{ paddingLeft: `${depth * 16 + 12}px` }}
+      >
+        {hasChildren ? (
+          <button
+            className="p-0.5"
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              setExpanded(!expanded);
+            }}
+          >
+            <ChevronRight
+              className={cn("h-3 w-3 transition-transform", expanded && "rotate-90")}
+            />
+          </button>
+        ) : (
+          <span className="w-4" />
+        )}
+        <span
+          className={cn(
+            "h-2 w-2 rounded-full shrink-0",
+            node.status === "active"
+              ? "bg-green-400"
+              : node.status === "paused"
+                ? "bg-yellow-400"
+                : node.status === "pending_approval"
+                  ? "bg-amber-400"
+                : node.status === "error"
+                  ? "bg-red-400"
+                  : "bg-neutral-400"
+          )}
+        />
+        <span className="font-medium flex-1">{node.name}</span>
+        <span className="text-xs text-muted-foreground">{node.role}</span>
+        <StatusBadge status={node.status} />
+      </Link>
+      {hasChildren && expanded && (
+        <OrgTree nodes={node.reports} depth={depth + 1} hrefFn={hrefFn} />
+      )}
+    </div>
+  );
+}
+
+export function Org() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Org Chart" }]);
+  }, [setBreadcrumbs]);
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: queryKeys.org(selectedCompanyId!),
+    queryFn: () => agentsApi.org(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={GitBranch} message="Select a company to view org chart." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  return (
+    <div className="space-y-4">
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {data && data.length === 0 && (
+        <EmptyState
+          icon={GitBranch}
+          message="No agents in the organization. Create agents to build your org chart."
+        />
+      )}
+
+      {data && data.length > 0 && (
+        <div className="border border-border py-1">
+          <OrgTree nodes={data} hrefFn={(id) => `/agents/${id}`} />
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/OrgChart.tsx

@@ -0,0 +1,446 @@
+import { useEffect, useRef, useState, useMemo, useCallback } from "react";
+import { Link, useNavigate } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { agentsApi, type OrgNode } from "../api/agents";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { agentUrl } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { AgentIcon } from "../components/AgentIconPicker";
+import { Download, Network, Upload } from "lucide-react";
+import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
+
+// Layout constants
+const CARD_W = 200;
+const CARD_H = 100;
+const GAP_X = 32;
+const GAP_Y = 80;
+const PADDING = 60;
+
+// ── Tree layout types ───────────────────────────────────────────────────
+
+interface LayoutNode {
+  id: string;
+  name: string;
+  role: string;
+  status: string;
+  x: number;
+  y: number;
+  children: LayoutNode[];
+}
+
+// ── Layout algorithm ────────────────────────────────────────────────────
+
+/** Compute the width each subtree needs. */
+function subtreeWidth(node: OrgNode): number {
+  if (node.reports.length === 0) return CARD_W;
+  const childrenW = node.reports.reduce((sum, c) => sum + subtreeWidth(c), 0);
+  const gaps = (node.reports.length - 1) * GAP_X;
+  return Math.max(CARD_W, childrenW + gaps);
+}
+
+/** Recursively assign x,y positions. */
+function layoutTree(node: OrgNode, x: number, y: number): LayoutNode {
+  const totalW = subtreeWidth(node);
+  const layoutChildren: LayoutNode[] = [];
+
+  if (node.reports.length > 0) {
+    const childrenW = node.reports.reduce((sum, c) => sum + subtreeWidth(c), 0);
+    const gaps = (node.reports.length - 1) * GAP_X;
+    let cx = x + (totalW - childrenW - gaps) / 2;
+
+    for (const child of node.reports) {
+      const cw = subtreeWidth(child);
+      layoutChildren.push(layoutTree(child, cx, y + CARD_H + GAP_Y));
+      cx += cw + GAP_X;
+    }
+  }
+
+  return {
+    id: node.id,
+    name: node.name,
+    role: node.role,
+    status: node.status,
+    x: x + (totalW - CARD_W) / 2,
+    y,
+    children: layoutChildren,
+  };
+}
+
+/** Layout all root nodes side by side. */
+function layoutForest(roots: OrgNode[]): LayoutNode[] {
+  if (roots.length === 0) return [];
+
+  const totalW = roots.reduce((sum, r) => sum + subtreeWidth(r), 0);
+  const gaps = (roots.length - 1) * GAP_X;
+  let x = PADDING;
+  const y = PADDING;
+
+  const result: LayoutNode[] = [];
+  for (const root of roots) {
+    const w = subtreeWidth(root);
+    result.push(layoutTree(root, x, y));
+    x += w + GAP_X;
+  }
+
+  // Compute bounds and return
+  return result;
+}
+
+/** Flatten layout tree to list of nodes. */
+function flattenLayout(nodes: LayoutNode[]): LayoutNode[] {
+  const result: LayoutNode[] = [];
+  function walk(n: LayoutNode) {
+    result.push(n);
+    n.children.forEach(walk);
+  }
+  nodes.forEach(walk);
+  return result;
+}
+
+/** Collect all parent→child edges. */
+function collectEdges(nodes: LayoutNode[]): Array<{ parent: LayoutNode; child: LayoutNode }> {
+  const edges: Array<{ parent: LayoutNode; child: LayoutNode }> = [];
+  function walk(n: LayoutNode) {
+    for (const c of n.children) {
+      edges.push({ parent: n, child: c });
+      walk(c);
+    }
+  }
+  nodes.forEach(walk);
+  return edges;
+}
+
+// ── Status dot colors (raw hex for SVG) ─────────────────────────────────
+
+const adapterLabels: Record<string, string> = {
+  claude_local: "Claude",
+  codex_local: "Codex",
+  gemini_local: "Gemini",
+  opencode_local: "OpenCode",
+  cursor: "Cursor",
+  openclaw_gateway: "OpenClaw Gateway",
+  process: "Process",
+  http: "HTTP",
+};
+
+const statusDotColor: Record<string, string> = {
+  running: "#22d3ee",
+  active: "#4ade80",
+  paused: "#facc15",
+  idle: "#facc15",
+  error: "#f87171",
+  terminated: "#a3a3a3",
+};
+const defaultDotColor = "#a3a3a3";
+
+// ── Main component ──────────────────────────────────────────────────────
+
+export function OrgChart() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const navigate = useNavigate();
+
+  const { data: orgTree, isLoading } = useQuery({
+    queryKey: queryKeys.org(selectedCompanyId!),
+    queryFn: () => agentsApi.org(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  const agentMap = useMemo(() => {
+    const m = new Map<string, Agent>();
+    for (const a of agents ?? []) m.set(a.id, a);
+    return m;
+  }, [agents]);
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Org Chart" }]);
+  }, [setBreadcrumbs]);
+
+  // Layout computation
+  const layout = useMemo(() => layoutForest(orgTree ?? []), [orgTree]);
+  const allNodes = useMemo(() => flattenLayout(layout), [layout]);
+  const edges = useMemo(() => collectEdges(layout), [layout]);
+
+  // Compute SVG bounds
+  const bounds = useMemo(() => {
+    if (allNodes.length === 0) return { width: 800, height: 600 };
+    let maxX = 0, maxY = 0;
+    for (const n of allNodes) {
+      maxX = Math.max(maxX, n.x + CARD_W);
+      maxY = Math.max(maxY, n.y + CARD_H);
+    }
+    return { width: maxX + PADDING, height: maxY + PADDING };
+  }, [allNodes]);
+
+  // Pan & zoom state
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [pan, setPan] = useState({ x: 0, y: 0 });
+  const [zoom, setZoom] = useState(1);
+  const [dragging, setDragging] = useState(false);
+  const dragStart = useRef({ x: 0, y: 0, panX: 0, panY: 0 });
+
+  // Center the chart on first load
+  const hasInitialized = useRef(false);
+  useEffect(() => {
+    if (hasInitialized.current || allNodes.length === 0 || !containerRef.current) return;
+    hasInitialized.current = true;
+
+    const container = containerRef.current;
+    const containerW = container.clientWidth;
+    const containerH = container.clientHeight;
+
+    // Fit chart to container
+    const scaleX = (containerW - 40) / bounds.width;
+    const scaleY = (containerH - 40) / bounds.height;
+    const fitZoom = Math.min(scaleX, scaleY, 1);
+
+    const chartW = bounds.width * fitZoom;
+    const chartH = bounds.height * fitZoom;
+
+    setZoom(fitZoom);
+    setPan({
+      x: (containerW - chartW) / 2,
+      y: (containerH - chartH) / 2,
+    });
+  }, [allNodes, bounds]);
+
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    if (e.button !== 0) return;
+    // Don't drag if clicking a card
+    const target = e.target as HTMLElement;
+    if (target.closest("[data-org-card]")) return;
+    setDragging(true);
+    dragStart.current = { x: e.clientX, y: e.clientY, panX: pan.x, panY: pan.y };
+  }, [pan]);
+
+  const handleMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!dragging) return;
+    const dx = e.clientX - dragStart.current.x;
+    const dy = e.clientY - dragStart.current.y;
+    setPan({ x: dragStart.current.panX + dx, y: dragStart.current.panY + dy });
+  }, [dragging]);
+
+  const handleMouseUp = useCallback(() => {
+    setDragging(false);
+  }, []);
+
+  const handleWheel = useCallback((e: React.WheelEvent) => {
+    e.preventDefault();
+    const container = containerRef.current;
+    if (!container) return;
+
+    const rect = container.getBoundingClientRect();
+    const mouseX = e.clientX - rect.left;
+    const mouseY = e.clientY - rect.top;
+
+    const factor = e.deltaY < 0 ? 1.1 : 0.9;
+    const newZoom = Math.min(Math.max(zoom * factor, 0.2), 2);
+
+    // Zoom toward mouse position
+    const scale = newZoom / zoom;
+    setPan({
+      x: mouseX - scale * (mouseX - pan.x),
+      y: mouseY - scale * (mouseY - pan.y),
+    });
+    setZoom(newZoom);
+  }, [zoom, pan]);
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={Network} message="Select a company to view the org chart." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="org-chart" />;
+  }
+
+  if (orgTree && orgTree.length === 0) {
+    return <EmptyState icon={Network} message="No organizational hierarchy defined." />;
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+    <div className="mb-2 flex items-center justify-start gap-2 shrink-0">
+      <Link to="/company/import">
+        <Button variant="outline" size="sm">
+          <Upload className="mr-1.5 h-3.5 w-3.5" />
+          Import company
+        </Button>
+      </Link>
+      <Link to="/company/export">
+        <Button variant="outline" size="sm">
+          <Download className="mr-1.5 h-3.5 w-3.5" />
+          Export company
+        </Button>
+      </Link>
+    </div>
+    <div
+      ref={containerRef}
+      className="w-full flex-1 min-h-0 overflow-hidden relative bg-muted/20 border border-border rounded-lg"
+      style={{ cursor: dragging ? "grabbing" : "grab" }}
+      onMouseDown={handleMouseDown}
+      onMouseMove={handleMouseMove}
+      onMouseUp={handleMouseUp}
+      onMouseLeave={handleMouseUp}
+      onWheel={handleWheel}
+    >
+      {/* Zoom controls */}
+      <div className="absolute top-3 right-3 z-10 flex flex-col gap-1">
+        <button
+          className="w-7 h-7 flex items-center justify-center bg-background border border-border rounded text-sm hover:bg-accent transition-colors"
+          onClick={() => {
+            const newZoom = Math.min(zoom * 1.2, 2);
+            const container = containerRef.current;
+            if (container) {
+              const cx = container.clientWidth / 2;
+              const cy = container.clientHeight / 2;
+              const scale = newZoom / zoom;
+              setPan({ x: cx - scale * (cx - pan.x), y: cy - scale * (cy - pan.y) });
+            }
+            setZoom(newZoom);
+          }}
+          aria-label="Zoom in"
+        >
+          +
+        </button>
+        <button
+          className="w-7 h-7 flex items-center justify-center bg-background border border-border rounded text-sm hover:bg-accent transition-colors"
+          onClick={() => {
+            const newZoom = Math.max(zoom * 0.8, 0.2);
+            const container = containerRef.current;
+            if (container) {
+              const cx = container.clientWidth / 2;
+              const cy = container.clientHeight / 2;
+              const scale = newZoom / zoom;
+              setPan({ x: cx - scale * (cx - pan.x), y: cy - scale * (cy - pan.y) });
+            }
+            setZoom(newZoom);
+          }}
+          aria-label="Zoom out"
+        >
+          &minus;
+        </button>
+        <button
+          className="w-7 h-7 flex items-center justify-center bg-background border border-border rounded text-[10px] hover:bg-accent transition-colors"
+          onClick={() => {
+            if (!containerRef.current) return;
+            const cW = containerRef.current.clientWidth;
+            const cH = containerRef.current.clientHeight;
+            const scaleX = (cW - 40) / bounds.width;
+            const scaleY = (cH - 40) / bounds.height;
+            const fitZoom = Math.min(scaleX, scaleY, 1);
+            const chartW = bounds.width * fitZoom;
+            const chartH = bounds.height * fitZoom;
+            setZoom(fitZoom);
+            setPan({ x: (cW - chartW) / 2, y: (cH - chartH) / 2 });
+          }}
+          title="Fit to screen"
+          aria-label="Fit chart to screen"
+        >
+          Fit
+        </button>
+      </div>
+
+      {/* SVG layer for edges */}
+      <svg
+        className="absolute inset-0 pointer-events-none"
+        style={{
+          width: "100%",
+          height: "100%",
+        }}
+      >
+        <g transform={`translate(${pan.x}, ${pan.y}) scale(${zoom})`}>
+          {edges.map(({ parent, child }) => {
+            const x1 = parent.x + CARD_W / 2;
+            const y1 = parent.y + CARD_H;
+            const x2 = child.x + CARD_W / 2;
+            const y2 = child.y;
+            const midY = (y1 + y2) / 2;
+
+            return (
+              <path
+                key={`${parent.id}-${child.id}`}
+                d={`M ${x1} ${y1} L ${x1} ${midY} L ${x2} ${midY} L ${x2} ${y2}`}
+                fill="none"
+                stroke="var(--border)"
+                strokeWidth={1.5}
+              />
+            );
+          })}
+        </g>
+      </svg>
+
+      {/* Card layer */}
+      <div
+        className="absolute inset-0"
+        style={{
+          transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+          transformOrigin: "0 0",
+        }}
+      >
+        {allNodes.map((node) => {
+          const agent = agentMap.get(node.id);
+          const dotColor = statusDotColor[node.status] ?? defaultDotColor;
+
+          return (
+            <div
+              key={node.id}
+              data-org-card
+              className="absolute bg-card border border-border rounded-lg shadow-sm hover:shadow-md hover:border-foreground/20 transition-[box-shadow,border-color] duration-150 cursor-pointer select-none"
+              style={{
+                left: node.x,
+                top: node.y,
+                width: CARD_W,
+                minHeight: CARD_H,
+              }}
+              onClick={() => navigate(agent ? agentUrl(agent) : `/agents/${node.id}`)}
+            >
+              <div className="flex items-center px-4 py-3 gap-3">
+                {/* Agent icon + status dot */}
+                <div className="relative shrink-0">
+                  <div className="w-9 h-9 rounded-full bg-muted flex items-center justify-center">
+                    <AgentIcon icon={agent?.icon} className="h-4.5 w-4.5 text-foreground/70" />
+                  </div>
+                  <span
+                    className="absolute -bottom-0.5 -right-0.5 h-3 w-3 rounded-full border-2 border-card"
+                    style={{ backgroundColor: dotColor }}
+                  />
+                </div>
+                {/* Name + role + adapter type */}
+                <div className="flex flex-col items-start min-w-0 flex-1">
+                  <span className="text-sm font-semibold text-foreground leading-tight">
+                    {node.name}
+                  </span>
+                  <span className="text-[11px] text-muted-foreground leading-tight mt-0.5">
+                    {agent?.title ?? roleLabel(node.role)}
+                  </span>
+                  {agent && (
+                    <span className="text-[10px] text-muted-foreground/60 font-mono leading-tight mt-1">
+                      {adapterLabels[agent.adapterType] ?? agent.adapterType}
+                    </span>
+                  )}
+                </div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+    </div>
+  );
+}
+
+const roleLabels: Record<string, string> = AGENT_ROLE_LABELS;
+
+function roleLabel(role: string): string {
+  return roleLabels[role] ?? role;
+}

paperclip-reference/ui/src/pages/PluginManager.tsx

@@ -0,0 +1,509 @@
+/**
+ * @fileoverview Plugin Manager page — admin UI for discovering,
+ * installing, enabling/disabling, and uninstalling plugins.
+ *
+ * @see PLUGIN_SPEC.md §9 — Plugin Marketplace / Manager
+ */
+import { useEffect, useMemo, useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import type { PluginRecord } from "@paperclipai/shared";
+import { Link } from "@/lib/router";
+import { AlertTriangle, FlaskConical, Plus, Power, Puzzle, Settings, Trash } from "lucide-react";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { useToast } from "@/context/ToastContext";
+import { cn } from "@/lib/utils";
+
+function firstNonEmptyLine(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const line = value
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find(Boolean);
+  return line ?? null;
+}
+
+function getPluginErrorSummary(plugin: PluginRecord): string {
+  return firstNonEmptyLine(plugin.lastError) ?? "Plugin entered an error state without a stored error message.";
+}
+
+/**
+ * PluginManager page component.
+ *
+ * Provides a management UI for the Paperclip plugin system:
+ * - Lists all installed plugins with their status, version, and category badges.
+ * - Allows installing new plugins by npm package name.
+ * - Provides per-plugin actions: enable, disable, navigate to settings.
+ * - Uninstall with a two-step confirmation dialog to prevent accidental removal.
+ *
+ * Data flow:
+ * - Reads from `GET /api/plugins` via `pluginsApi.list()`.
+ * - Mutations (install / uninstall / enable / disable) invalidate
+ *   `queryKeys.plugins.all` so the list refreshes automatically.
+ *
+ * @see PluginSettings — linked from the Settings icon on each plugin row.
+ * @see doc/plugins/PLUGIN_SPEC.md §3 — Plugin Lifecycle for status semantics.
+ */
+export function PluginManager() {
+  const { selectedCompany } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const { pushToast } = useToast();
+
+  const [installPackage, setInstallPackage] = useState("");
+  const [installDialogOpen, setInstallDialogOpen] = useState(false);
+  const [uninstallPluginId, setUninstallPluginId] = useState<string | null>(null);
+  const [uninstallPluginName, setUninstallPluginName] = useState<string>("");
+  const [errorDetailsPlugin, setErrorDetailsPlugin] = useState<PluginRecord | null>(null);
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+      { label: "Settings", href: "/instance/settings/heartbeats" },
+      { label: "Plugins" },
+    ]);
+  }, [selectedCompany?.name, setBreadcrumbs]);
+
+  const { data: plugins, isLoading, error } = useQuery({
+    queryKey: queryKeys.plugins.all,
+    queryFn: () => pluginsApi.list(),
+  });
+
+  const examplesQuery = useQuery({
+    queryKey: queryKeys.plugins.examples,
+    queryFn: () => pluginsApi.listExamples(),
+  });
+
+  const invalidatePluginQueries = () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.plugins.all });
+    queryClient.invalidateQueries({ queryKey: queryKeys.plugins.examples });
+    queryClient.invalidateQueries({ queryKey: queryKeys.plugins.uiContributions });
+  };
+
+  const installMutation = useMutation({
+    mutationFn: (params: { packageName: string; version?: string; isLocalPath?: boolean }) =>
+      pluginsApi.install(params),
+    onSuccess: () => {
+      invalidatePluginQueries();
+      setInstallDialogOpen(false);
+      setInstallPackage("");
+      pushToast({ title: "Plugin installed successfully", tone: "success" });
+    },
+    onError: (err: Error) => {
+      pushToast({ title: "Failed to install plugin", body: err.message, tone: "error" });
+    },
+  });
+
+  const uninstallMutation = useMutation({
+    mutationFn: (pluginId: string) => pluginsApi.uninstall(pluginId),
+    onSuccess: () => {
+      invalidatePluginQueries();
+      pushToast({ title: "Plugin uninstalled successfully", tone: "success" });
+    },
+    onError: (err: Error) => {
+      pushToast({ title: "Failed to uninstall plugin", body: err.message, tone: "error" });
+    },
+  });
+
+  const enableMutation = useMutation({
+    mutationFn: (pluginId: string) => pluginsApi.enable(pluginId),
+    onSuccess: () => {
+      invalidatePluginQueries();
+      pushToast({ title: "Plugin enabled", tone: "success" });
+    },
+    onError: (err: Error) => {
+      pushToast({ title: "Failed to enable plugin", body: err.message, tone: "error" });
+    },
+  });
+
+  const disableMutation = useMutation({
+    mutationFn: (pluginId: string) => pluginsApi.disable(pluginId),
+    onSuccess: () => {
+      invalidatePluginQueries();
+      pushToast({ title: "Plugin disabled", tone: "info" });
+    },
+    onError: (err: Error) => {
+      pushToast({ title: "Failed to disable plugin", body: err.message, tone: "error" });
+    },
+  });
+
+  const installedPlugins = plugins ?? [];
+  const examples = examplesQuery.data ?? [];
+  const installedByPackageName = new Map(installedPlugins.map((plugin) => [plugin.packageName, plugin]));
+  const examplePackageNames = new Set(examples.map((example) => example.packageName));
+  const errorSummaryByPluginId = useMemo(
+    () =>
+      new Map(
+        installedPlugins.map((plugin) => [plugin.id, getPluginErrorSummary(plugin)])
+      ),
+    [installedPlugins]
+  );
+
+  if (isLoading) return <div className="p-4 text-sm text-muted-foreground">Loading plugins...</div>;
+  if (error) return <div className="p-4 text-sm text-destructive">Failed to load plugins.</div>;
+
+  return (
+    <div className="space-y-6 max-w-5xl">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Puzzle className="h-6 w-6 text-muted-foreground" />
+          <h1 className="text-xl font-semibold">Plugin Manager</h1>
+        </div>
+        
+        <Dialog open={installDialogOpen} onOpenChange={setInstallDialogOpen}>
+          <DialogTrigger asChild>
+            <Button size="sm" className="gap-2">
+              <Plus className="h-4 w-4" />
+              Install Plugin
+            </Button>
+          </DialogTrigger>
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Install Plugin</DialogTitle>
+              <DialogDescription>
+                Enter the npm package name of the plugin you wish to install.
+              </DialogDescription>
+            </DialogHeader>
+            <div className="grid gap-4 py-4">
+              <div className="grid gap-2">
+                <Label htmlFor="packageName">npm Package Name</Label>
+                <Input
+                  id="packageName"
+                  placeholder="@paperclipai/plugin-example"
+                  value={installPackage}
+                  onChange={(e) => setInstallPackage(e.target.value)}
+                />
+              </div>
+            </div>
+            <DialogFooter>
+              <Button variant="outline" onClick={() => setInstallDialogOpen(false)}>Cancel</Button>
+              <Button
+                onClick={() => installMutation.mutate({ packageName: installPackage })}
+                disabled={!installPackage || installMutation.isPending}
+              >
+                {installMutation.isPending ? "Installing..." : "Install"}
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 px-4 py-3">
+        <div className="flex items-start gap-3">
+          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-amber-700" />
+          <div className="space-y-1 text-sm">
+            <p className="font-medium text-foreground">Plugins are alpha.</p>
+            <p className="text-muted-foreground">
+              The plugin runtime and API surface are still changing. Expect breaking changes while this feature settles.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <section className="space-y-3">
+        <div className="flex items-center gap-2">
+          <FlaskConical className="h-5 w-5 text-muted-foreground" />
+          <h2 className="text-base font-semibold">Available Plugins</h2>
+          <Badge variant="outline">Examples</Badge>
+        </div>
+
+        {examplesQuery.isLoading ? (
+          <div className="text-sm text-muted-foreground">Loading bundled examples...</div>
+        ) : examplesQuery.error ? (
+          <div className="text-sm text-destructive">Failed to load bundled examples.</div>
+        ) : examples.length === 0 ? (
+          <div className="rounded-md border border-dashed px-4 py-3 text-sm text-muted-foreground">
+            No bundled example plugins were found in this checkout.
+          </div>
+        ) : (
+          <ul className="divide-y rounded-md border bg-card">
+            {examples.map((example) => {
+              const installedPlugin = installedByPackageName.get(example.packageName);
+              const installPending =
+                installMutation.isPending &&
+                installMutation.variables?.isLocalPath &&
+                installMutation.variables.packageName === example.localPath;
+
+              return (
+                <li key={example.packageName}>
+                  <div className="flex items-center gap-4 px-4 py-3">
+                    <div className="min-w-0 flex-1">
+                      <div className="flex flex-wrap items-center gap-2">
+                        <span className="font-medium">{example.displayName}</span>
+                        <Badge variant="outline">Example</Badge>
+                        {installedPlugin ? (
+                          <Badge
+                            variant={installedPlugin.status === "ready" ? "default" : "secondary"}
+                            className={installedPlugin.status === "ready" ? "bg-green-600 hover:bg-green-700" : ""}
+                          >
+                            {installedPlugin.status}
+                          </Badge>
+                        ) : (
+                          <Badge variant="secondary">Not installed</Badge>
+                        )}
+                      </div>
+                      <p className="mt-1 text-sm text-muted-foreground">{example.description}</p>
+                      <p className="mt-1 text-xs text-muted-foreground">{example.packageName}</p>
+                    </div>
+                    <div className="flex items-center gap-2 shrink-0">
+                      {installedPlugin ? (
+                        <>
+                          {installedPlugin.status !== "ready" && (
+                            <Button
+                              variant="outline"
+                              size="sm"
+                              disabled={enableMutation.isPending}
+                              onClick={() => enableMutation.mutate(installedPlugin.id)}
+                            >
+                              Enable
+                            </Button>
+                          )}
+                          <Button variant="outline" size="sm" asChild>
+                            <Link to={`/instance/settings/plugins/${installedPlugin.id}`}>
+                              {installedPlugin.status === "ready" ? "Open Settings" : "Review"}
+                            </Link>
+                          </Button>
+                        </>
+                      ) : (
+                        <Button
+                          size="sm"
+                          disabled={installPending || installMutation.isPending}
+                          onClick={() =>
+                            installMutation.mutate({
+                              packageName: example.localPath,
+                              isLocalPath: true,
+                            })
+                          }
+                        >
+                          {installPending ? "Installing..." : "Install Example"}
+                        </Button>
+                      )}
+                    </div>
+                  </div>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </section>
+
+      <section className="space-y-3">
+        <div className="flex items-center gap-2">
+          <Puzzle className="h-5 w-5 text-muted-foreground" />
+          <h2 className="text-base font-semibold">Installed Plugins</h2>
+        </div>
+
+        {!installedPlugins.length ? (
+          <Card className="bg-muted/30">
+            <CardContent className="flex flex-col items-center justify-center py-10">
+              <Puzzle className="h-10 w-10 text-muted-foreground mb-4" />
+              <p className="text-sm font-medium">No plugins installed</p>
+              <p className="text-xs text-muted-foreground mt-1">
+                Install a plugin to extend functionality.
+              </p>
+            </CardContent>
+          </Card>
+        ) : (
+          <ul className="divide-y rounded-md border bg-card">
+            {installedPlugins.map((plugin) => (
+              <li key={plugin.id}>
+                <div className="flex items-start gap-4 px-4 py-3">
+                  <div className="min-w-0 flex-1">
+                    <div className="flex flex-wrap items-center gap-2">
+                      <Link
+                        to={`/instance/settings/plugins/${plugin.id}`}
+                        className="font-medium hover:underline truncate block"
+                        title={plugin.manifestJson.displayName ?? plugin.packageName}
+                      >
+                        {plugin.manifestJson.displayName ?? plugin.packageName}
+                      </Link>
+                      {examplePackageNames.has(plugin.packageName) && (
+                        <Badge variant="outline">Example</Badge>
+                      )}
+                    </div>
+                    <div>
+                      <p className="text-xs text-muted-foreground mt-0.5 truncate" title={plugin.packageName}>
+                        {plugin.packageName} · v{plugin.manifestJson.version ?? plugin.version}
+                      </p>
+                    </div>
+                    <p className="text-sm text-muted-foreground truncate mt-0.5" title={plugin.manifestJson.description}>
+                      {plugin.manifestJson.description || "No description provided."}
+                    </p>
+                    {plugin.status === "error" && (
+                      <div className="mt-3 rounded-md border border-red-500/25 bg-red-500/[0.06] px-3 py-2">
+                        <div className="flex flex-wrap items-start gap-3">
+                          <div className="min-w-0 flex-1">
+                            <div className="flex items-center gap-2 text-sm font-medium text-red-700 dark:text-red-300">
+                              <AlertTriangle className="h-4 w-4 shrink-0" />
+                              <span>Plugin error</span>
+                            </div>
+                            <p
+                              className="mt-1 text-sm text-red-700/90 dark:text-red-200/90 break-words"
+                              title={plugin.lastError ?? undefined}
+                            >
+                              {errorSummaryByPluginId.get(plugin.id)}
+                            </p>
+                          </div>
+                          <Button
+                            variant="outline"
+                            size="sm"
+                            className="border-red-500/30 bg-background/60 text-red-700 hover:bg-red-500/10 hover:text-red-800 dark:text-red-200 dark:hover:text-red-100"
+                            onClick={() => setErrorDetailsPlugin(plugin)}
+                          >
+                            View full error
+                          </Button>
+                        </div>
+                      </div>
+                    )}
+                  </div>
+                  <div className="flex shrink-0 self-center">
+                    <div className="flex flex-col items-end gap-2">
+                      <div className="flex items-center gap-2">
+                        <Badge
+                          variant={
+                            plugin.status === "ready"
+                              ? "default"
+                              : plugin.status === "error"
+                                ? "destructive"
+                              : "secondary"
+                          }
+                          className={cn(
+                            "shrink-0",
+                            plugin.status === "ready" ? "bg-green-600 hover:bg-green-700" : ""
+                          )}
+                        >
+                          {plugin.status}
+                        </Badge>
+                        <Button
+                          variant="outline"
+                          size="icon-sm"
+                          className="h-8 w-8"
+                          title={plugin.status === "ready" ? "Disable" : "Enable"}
+                          onClick={() => {
+                            if (plugin.status === "ready") {
+                              disableMutation.mutate(plugin.id);
+                            } else {
+                              enableMutation.mutate(plugin.id);
+                            }
+                          }}
+                          disabled={enableMutation.isPending || disableMutation.isPending}
+                        >
+                          <Power className={cn("h-4 w-4", plugin.status === "ready" ? "text-green-600" : "")} />
+                        </Button>
+                        <Button
+                          variant="outline"
+                          size="icon-sm"
+                          className="h-8 w-8 text-destructive hover:text-destructive"
+                          title="Uninstall"
+                          onClick={() => {
+                            setUninstallPluginId(plugin.id);
+                            setUninstallPluginName(plugin.manifestJson.displayName ?? plugin.packageName);
+                          }}
+                          disabled={uninstallMutation.isPending}
+                        >
+                          <Trash className="h-4 w-4" />
+                        </Button>
+                      </div>
+                      <Button variant="outline" size="sm" className="mt-2 h-8" asChild>
+                        <Link to={`/instance/settings/plugins/${plugin.id}`}>
+                          <Settings className="h-4 w-4" />
+                          Configure
+                        </Link>
+                      </Button>
+                    </div>
+                  </div>
+                </div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      <Dialog
+        open={uninstallPluginId !== null}
+        onOpenChange={(open) => { if (!open) setUninstallPluginId(null); }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Uninstall Plugin</DialogTitle>
+            <DialogDescription>
+              Are you sure you want to uninstall <strong>{uninstallPluginName}</strong>? This action cannot be undone.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setUninstallPluginId(null)}>Cancel</Button>
+            <Button
+              variant="destructive"
+              disabled={uninstallMutation.isPending}
+              onClick={() => {
+                if (uninstallPluginId) {
+                  uninstallMutation.mutate(uninstallPluginId, {
+                    onSettled: () => setUninstallPluginId(null),
+                  });
+                }
+              }}
+            >
+              {uninstallMutation.isPending ? "Uninstalling..." : "Uninstall"}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog
+        open={errorDetailsPlugin !== null}
+        onOpenChange={(open) => { if (!open) setErrorDetailsPlugin(null); }}
+      >
+        <DialogContent className="sm:max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>Error Details</DialogTitle>
+            <DialogDescription>
+              {errorDetailsPlugin?.manifestJson.displayName ?? errorDetailsPlugin?.packageName ?? "Plugin"} hit an error state.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="space-y-4">
+            <div className="rounded-md border border-red-500/25 bg-red-500/[0.06] px-4 py-3">
+              <div className="flex items-start gap-3">
+                <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-red-700 dark:text-red-300" />
+                <div className="space-y-1 text-sm">
+                  <p className="font-medium text-red-700 dark:text-red-300">
+                    What errored
+                  </p>
+                  <p className="text-red-700/90 dark:text-red-200/90 break-words">
+                    {errorDetailsPlugin ? getPluginErrorSummary(errorDetailsPlugin) : "No error summary available."}
+                  </p>
+                </div>
+              </div>
+            </div>
+            <div className="space-y-2">
+              <p className="text-sm font-medium">Full error output</p>
+              <pre className="max-h-[50vh] overflow-auto rounded-md border bg-muted/40 p-3 text-xs leading-5 whitespace-pre-wrap break-words">
+                {errorDetailsPlugin?.lastError ?? "No stored error message."}
+              </pre>
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setErrorDetailsPlugin(null)}>
+              Close
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/PluginPage.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useMemo } from "react";
+import { Link, Navigate, useParams } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { PluginSlotMount } from "@/plugins/slots";
+import { Button } from "@/components/ui/button";
+import { ArrowLeft } from "lucide-react";
+import { NotFoundPage } from "./NotFound";
+
+/**
+ * Company-context plugin page. Renders a plugin's `page` slot at
+ * `/:companyPrefix/plugins/:pluginId` when the plugin declares a page slot
+ * and is enabled for that company.
+ *
+ * @see doc/plugins/PLUGIN_SPEC.md §19.2 — Company-Context Routes
+ * @see doc/plugins/PLUGIN_SPEC.md §24.4 — Company-Context Plugin Page
+ */
+export function PluginPage() {
+  const { companyPrefix: routeCompanyPrefix, pluginId, pluginRoutePath } = useParams<{
+    companyPrefix?: string;
+    pluginId?: string;
+    pluginRoutePath?: string;
+  }>();
+  const { companies, selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const routeCompany = useMemo(() => {
+    if (!routeCompanyPrefix) return null;
+    const requested = routeCompanyPrefix.toUpperCase();
+    return companies.find((c) => c.issuePrefix.toUpperCase() === requested) ?? null;
+  }, [companies, routeCompanyPrefix]);
+  const hasInvalidCompanyPrefix = Boolean(routeCompanyPrefix) && !routeCompany;
+
+  const resolvedCompanyId = useMemo(() => {
+    if (routeCompany) return routeCompany.id;
+    if (routeCompanyPrefix) return null;
+    return selectedCompanyId ?? null;
+  }, [routeCompany, routeCompanyPrefix, selectedCompanyId]);
+
+  const companyPrefix = useMemo(
+    () => (resolvedCompanyId ? companies.find((c) => c.id === resolvedCompanyId)?.issuePrefix ?? null : null),
+    [companies, resolvedCompanyId],
+  );
+
+  const { data: contributions } = useQuery({
+    queryKey: queryKeys.plugins.uiContributions,
+    queryFn: () => pluginsApi.listUiContributions(),
+    enabled: !!resolvedCompanyId && (!!pluginId || !!pluginRoutePath),
+  });
+
+  const pageSlot = useMemo(() => {
+    if (!contributions) return null;
+    if (pluginId) {
+      const contribution = contributions.find((c) => c.pluginId === pluginId);
+      if (!contribution) return null;
+      const slot = contribution.slots.find((s) => s.type === "page");
+      if (!slot) return null;
+      return {
+        ...slot,
+        pluginId: contribution.pluginId,
+        pluginKey: contribution.pluginKey,
+        pluginDisplayName: contribution.displayName,
+        pluginVersion: contribution.version,
+      };
+    }
+    if (!pluginRoutePath) return null;
+    const matches = contributions.flatMap((contribution) => {
+      const slot = contribution.slots.find((entry) => entry.type === "page" && entry.routePath === pluginRoutePath);
+      if (!slot) return [];
+      return [{
+        ...slot,
+        pluginId: contribution.pluginId,
+        pluginKey: contribution.pluginKey,
+        pluginDisplayName: contribution.displayName,
+        pluginVersion: contribution.version,
+      }];
+    });
+    if (matches.length !== 1) return null;
+    return matches[0] ?? null;
+  }, [pluginId, pluginRoutePath, contributions]);
+
+  const context = useMemo(
+    () => ({
+      companyId: resolvedCompanyId ?? null,
+      companyPrefix,
+    }),
+    [resolvedCompanyId, companyPrefix],
+  );
+
+  useEffect(() => {
+    if (pageSlot) {
+      setBreadcrumbs([
+        { label: "Plugins", href: "/instance/settings/plugins" },
+        { label: pageSlot.pluginDisplayName },
+      ]);
+    }
+  }, [pageSlot, companyPrefix, setBreadcrumbs]);
+
+  if (!resolvedCompanyId) {
+    if (hasInvalidCompanyPrefix) {
+      return <NotFoundPage scope="invalid_company_prefix" requestedPrefix={routeCompanyPrefix} />;
+    }
+    return (
+      <div className="space-y-4">
+        <p className="text-sm text-muted-foreground">Select a company to view this page.</p>
+      </div>
+    );
+  }
+
+  if (!contributions) {
+    return <div className="text-sm text-muted-foreground">Loading…</div>;
+  }
+
+  if (!pluginId && pluginRoutePath) {
+    const duplicateMatches = contributions.filter((contribution) =>
+      contribution.slots.some((slot) => slot.type === "page" && slot.routePath === pluginRoutePath),
+    );
+    if (duplicateMatches.length > 1) {
+      return (
+        <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+          Multiple plugins declare the route <code>{pluginRoutePath}</code>. Use the plugin-id route until the conflict is resolved.
+        </div>
+      );
+    }
+  }
+
+  if (!pageSlot) {
+    if (pluginRoutePath) {
+      return <NotFoundPage scope="board" />;
+    }
+    // No page slot: redirect to plugin settings where plugin info is always shown
+    const settingsPath = pluginId ? `/instance/settings/plugins/${pluginId}` : "/instance/settings/plugins";
+    return <Navigate to={settingsPath} replace />;
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <Button variant="ghost" size="sm" asChild>
+          <Link to={companyPrefix ? `/${companyPrefix}/dashboard` : "/dashboard"}>
+            <ArrowLeft className="h-4 w-4 mr-1" />
+            Back
+          </Link>
+        </Button>
+      </div>
+      <PluginSlotMount
+        slot={pageSlot}
+        context={context}
+        className="min-h-[200px]"
+        missingBehavior="placeholder"
+      />
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/PluginSettings.tsx

@@ -0,0 +1,836 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { Puzzle, ArrowLeft, ShieldAlert, ActivitySquare, CheckCircle, XCircle, Loader2, Clock, Cpu, Webhook, CalendarClock, AlertTriangle } from "lucide-react";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { Link, Navigate, useParams } from "@/lib/router";
+import { PluginSlotMount, usePluginSlots } from "@/plugins/slots";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+import { Tabs, TabsContent } from "@/components/ui/tabs";
+import { PageTabBar } from "@/components/PageTabBar";
+import {
+  JsonSchemaForm,
+  validateJsonSchemaForm,
+  getDefaultValues,
+  type JsonSchemaNode,
+} from "@/components/JsonSchemaForm";
+
+/**
+ * PluginSettings page component.
+ *
+ * Detailed settings and diagnostics page for a single installed plugin.
+ * Navigated to from {@link PluginManager} via the Settings gear icon.
+ *
+ * Displays:
+ * - Plugin identity: display name, id, version, description, categories.
+ * - Manifest-declared capabilities (what data and features the plugin can access).
+ * - Health check results (only for `ready` plugins; polled every 30 seconds).
+ * - Runtime dashboard: worker status/uptime, recent job runs, webhook deliveries.
+ * - Auto-generated config form from `instanceConfigSchema` (when no custom settings page).
+ * - Plugin-contributed settings UI via `<PluginSlotOutlet type="settingsPage" />`.
+ *
+ * Data flow:
+ * - `GET /api/plugins/:pluginId` — plugin record (refreshes on mount).
+ * - `GET /api/plugins/:pluginId/health` — health diagnostics (polling).
+ *   Only fetched when `plugin.status === "ready"`.
+ * - `GET /api/plugins/:pluginId/dashboard` — aggregated runtime dashboard data (polling).
+ * - `GET /api/plugins/:pluginId/config` — current config values.
+ * - `POST /api/plugins/:pluginId/config` — save config values.
+ * - `POST /api/plugins/:pluginId/config/test` — test configuration.
+ *
+ * URL params:
+ * - `companyPrefix` — the company slug (for breadcrumb links).
+ * - `pluginId` — UUID of the plugin to display.
+ *
+ * @see PluginManager — parent list page.
+ * @see doc/plugins/PLUGIN_SPEC.md §13 — Plugin Health Checks.
+ * @see doc/plugins/PLUGIN_SPEC.md §19.8 — Plugin Settings UI.
+ */
+export function PluginSettings() {
+  const { selectedCompany, selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const { companyPrefix, pluginId } = useParams<{ companyPrefix?: string; pluginId: string }>();
+  const [activeTab, setActiveTab] = useState<"configuration" | "status">("configuration");
+
+  const { data: plugin, isLoading: pluginLoading } = useQuery({
+    queryKey: queryKeys.plugins.detail(pluginId!),
+    queryFn: () => pluginsApi.get(pluginId!),
+    enabled: !!pluginId,
+  });
+
+  const { data: healthData, isLoading: healthLoading } = useQuery({
+    queryKey: queryKeys.plugins.health(pluginId!),
+    queryFn: () => pluginsApi.health(pluginId!),
+    enabled: !!pluginId && plugin?.status === "ready",
+    refetchInterval: 30000,
+  });
+
+  const { data: dashboardData } = useQuery({
+    queryKey: queryKeys.plugins.dashboard(pluginId!),
+    queryFn: () => pluginsApi.dashboard(pluginId!),
+    enabled: !!pluginId,
+    refetchInterval: 30000,
+  });
+
+  const { data: recentLogs } = useQuery({
+    queryKey: queryKeys.plugins.logs(pluginId!),
+    queryFn: () => pluginsApi.logs(pluginId!, { limit: 50 }),
+    enabled: !!pluginId && plugin?.status === "ready",
+    refetchInterval: 30000,
+  });
+
+  // Fetch existing config for the plugin
+  const configSchema = plugin?.manifestJson?.instanceConfigSchema as JsonSchemaNode | undefined;
+  const hasConfigSchema = configSchema && configSchema.properties && Object.keys(configSchema.properties).length > 0;
+
+  const { data: configData, isLoading: configLoading } = useQuery({
+    queryKey: queryKeys.plugins.config(pluginId!),
+    queryFn: () => pluginsApi.getConfig(pluginId!),
+    enabled: !!pluginId && !!hasConfigSchema,
+  });
+
+  const { slots } = usePluginSlots({
+    slotTypes: ["settingsPage"],
+    companyId: selectedCompanyId,
+    enabled: !!selectedCompanyId,
+  });
+
+  // Filter slots to only show settings pages for this specific plugin
+  const pluginSlots = slots.filter((slot) => slot.pluginId === pluginId);
+
+  // If the plugin has a custom settingsPage slot, prefer that over auto-generated form
+  const hasCustomSettingsPage = pluginSlots.length > 0;
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+      { label: "Settings", href: "/instance/settings/heartbeats" },
+      { label: "Plugins", href: "/instance/settings/plugins" },
+      { label: plugin?.manifestJson?.displayName ?? plugin?.packageName ?? "Plugin Details" },
+    ]);
+  }, [selectedCompany?.name, setBreadcrumbs, companyPrefix, plugin]);
+
+  useEffect(() => {
+    setActiveTab("configuration");
+  }, [pluginId]);
+
+  if (pluginLoading) {
+    return <div className="p-4 text-sm text-muted-foreground">Loading plugin details...</div>;
+  }
+
+  if (!plugin) {
+    return <Navigate to="/instance/settings/plugins" replace />;
+  }
+
+  const displayStatus = plugin.status;
+  const statusVariant =
+    plugin.status === "ready"
+      ? "default"
+      : plugin.status === "error"
+        ? "destructive"
+        : "secondary";
+  const pluginDescription = plugin.manifestJson.description || "No description provided.";
+  const pluginCapabilities = plugin.manifestJson.capabilities ?? [];
+
+  return (
+    <div className="space-y-6 max-w-5xl">
+      <div className="flex items-center gap-4">
+        <Link to="/instance/settings/plugins">
+          <Button variant="outline" size="icon" className="h-8 w-8">
+            <ArrowLeft className="h-4 w-4" />
+          </Button>
+        </Link>
+        <div className="flex items-center gap-2">
+          <Puzzle className="h-6 w-6 text-muted-foreground" />
+          <h1 className="text-xl font-semibold">{plugin.manifestJson.displayName ?? plugin.packageName}</h1>
+          <Badge variant={statusVariant} className="ml-2">
+            {displayStatus}
+          </Badge>
+          <Badge variant="outline" className="ml-1">
+            v{plugin.manifestJson.version ?? plugin.version}
+          </Badge>
+        </div>
+      </div>
+
+      <Tabs value={activeTab} onValueChange={(value) => setActiveTab(value as "configuration" | "status")} className="space-y-6">
+        <PageTabBar
+          align="start"
+          items={[
+            { value: "configuration", label: "Configuration" },
+            { value: "status", label: "Status" },
+          ]}
+          value={activeTab}
+          onValueChange={(value) => setActiveTab(value as "configuration" | "status")}
+        />
+
+        <TabsContent value="configuration" className="space-y-6">
+          <div className="space-y-8">
+            <section className="space-y-5">
+              <h2 className="text-base font-semibold">About</h2>
+              <div className="grid gap-8 lg:grid-cols-[minmax(0,1.4fr)_minmax(220px,0.8fr)]">
+                <div className="space-y-2">
+                  <h3 className="text-sm font-medium text-muted-foreground">Description</h3>
+                  <p className="text-sm leading-6 text-foreground/90">{pluginDescription}</p>
+                </div>
+                <div className="space-y-4 text-sm">
+                  <div className="space-y-1.5">
+                    <h3 className="font-medium text-muted-foreground">Author</h3>
+                    <p className="text-foreground">{plugin.manifestJson.author}</p>
+                  </div>
+                  <div className="space-y-2">
+                    <h3 className="font-medium text-muted-foreground">Categories</h3>
+                    <div className="flex flex-wrap gap-2">
+                      {plugin.categories.length > 0 ? (
+                        plugin.categories.map((category) => (
+                          <Badge key={category} variant="outline" className="capitalize">
+                            {category}
+                          </Badge>
+                        ))
+                      ) : (
+                        <span className="text-foreground">None</span>
+                      )}
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </section>
+
+            <Separator />
+
+            <section className="space-y-4">
+              <div className="space-y-1">
+                <h2 className="text-base font-semibold">Settings</h2>
+              </div>
+              {hasCustomSettingsPage ? (
+                <div className="space-y-3">
+                  {pluginSlots.map((slot) => (
+                    <PluginSlotMount
+                      key={`${slot.pluginKey}:${slot.id}`}
+                      slot={slot}
+                      context={{
+                        companyId: selectedCompanyId,
+                        companyPrefix: companyPrefix ?? null,
+                      }}
+                      missingBehavior="placeholder"
+                    />
+                  ))}
+                </div>
+              ) : hasConfigSchema ? (
+                <PluginConfigForm
+                  pluginId={pluginId!}
+                  schema={configSchema!}
+                  initialValues={configData?.configJson}
+                  isLoading={configLoading}
+                  pluginStatus={plugin.status}
+                  supportsConfigTest={(plugin as unknown as { supportsConfigTest?: boolean }).supportsConfigTest === true}
+                />
+              ) : (
+                <p className="text-sm text-muted-foreground">
+                  This plugin does not require any settings.
+                </p>
+              )}
+            </section>
+          </div>
+        </TabsContent>
+
+        <TabsContent value="status" className="space-y-6">
+          <div className="grid gap-6 xl:grid-cols-[minmax(0,1.2fr)_320px]">
+            <div className="space-y-6">
+              <Card>
+                <CardHeader>
+                  <CardTitle className="text-base flex items-center gap-1.5">
+                    <Cpu className="h-4 w-4" />
+                    Runtime Dashboard
+                  </CardTitle>
+                  <CardDescription>
+                    Worker process, scheduled jobs, and webhook deliveries
+                  </CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-6">
+                  {dashboardData ? (
+                    <>
+                      <div>
+                        <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+                          <Cpu className="h-3.5 w-3.5 text-muted-foreground" />
+                          Worker Process
+                        </h3>
+                        {dashboardData.worker ? (
+                          <div className="grid grid-cols-2 gap-3 text-sm">
+                            <div className="flex justify-between">
+                              <span className="text-muted-foreground">Status</span>
+                              <Badge variant={dashboardData.worker.status === "running" ? "default" : "secondary"}>
+                                {dashboardData.worker.status}
+                              </Badge>
+                            </div>
+                            <div className="flex justify-between">
+                              <span className="text-muted-foreground">PID</span>
+                              <span className="font-mono text-xs">{dashboardData.worker.pid ?? "—"}</span>
+                            </div>
+                            <div className="flex justify-between">
+                              <span className="text-muted-foreground">Uptime</span>
+                              <span className="text-xs">{formatUptime(dashboardData.worker.uptime)}</span>
+                            </div>
+                            <div className="flex justify-between">
+                              <span className="text-muted-foreground">Pending RPCs</span>
+                              <span className="text-xs">{dashboardData.worker.pendingRequests}</span>
+                            </div>
+                            {dashboardData.worker.totalCrashes > 0 && (
+                              <>
+                                <div className="flex justify-between col-span-2">
+                                  <span className="text-muted-foreground flex items-center gap-1">
+                                    <AlertTriangle className="h-3 w-3 text-amber-500" />
+                                    Crashes
+                                  </span>
+                                  <span className="text-xs">
+                                    {dashboardData.worker.consecutiveCrashes} consecutive / {dashboardData.worker.totalCrashes} total
+                                  </span>
+                                </div>
+                                {dashboardData.worker.lastCrashAt && (
+                                  <div className="flex justify-between col-span-2">
+                                    <span className="text-muted-foreground">Last Crash</span>
+                                    <span className="text-xs">{formatTimestamp(dashboardData.worker.lastCrashAt)}</span>
+                                  </div>
+                                )}
+                              </>
+                            )}
+                          </div>
+                        ) : (
+                          <p className="text-sm text-muted-foreground italic">No worker process registered.</p>
+                        )}
+                      </div>
+
+                      <Separator />
+
+                      <div>
+                        <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+                          <CalendarClock className="h-3.5 w-3.5 text-muted-foreground" />
+                          Recent Job Runs
+                        </h3>
+                        {dashboardData.recentJobRuns.length > 0 ? (
+                          <div className="space-y-2">
+                            {dashboardData.recentJobRuns.map((run) => (
+                              <div
+                                key={run.id}
+                                className="flex items-center justify-between gap-2 rounded-md bg-muted/50 px-2 py-1.5 text-sm"
+                              >
+                                <div className="flex min-w-0 items-center gap-2">
+                                  <JobStatusDot status={run.status} />
+                                  <span className="truncate font-mono text-xs" title={run.jobKey ?? run.jobId}>
+                                    {run.jobKey ?? run.jobId.slice(0, 8)}
+                                  </span>
+                                  <Badge variant="outline" className="px-1 py-0 text-[10px]">
+                                    {run.trigger}
+                                  </Badge>
+                                </div>
+                                <div className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                                  {run.durationMs != null ? <span>{formatDuration(run.durationMs)}</span> : null}
+                                  <span title={run.createdAt}>{formatRelativeTime(run.createdAt)}</span>
+                                </div>
+                              </div>
+                            ))}
+                          </div>
+                        ) : (
+                          <p className="text-sm text-muted-foreground italic">No job runs recorded yet.</p>
+                        )}
+                      </div>
+
+                      <Separator />
+
+                      <div>
+                        <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+                          <Webhook className="h-3.5 w-3.5 text-muted-foreground" />
+                          Recent Webhook Deliveries
+                        </h3>
+                        {dashboardData.recentWebhookDeliveries.length > 0 ? (
+                          <div className="space-y-2">
+                            {dashboardData.recentWebhookDeliveries.map((delivery) => (
+                              <div
+                                key={delivery.id}
+                                className="flex items-center justify-between gap-2 rounded-md bg-muted/50 px-2 py-1.5 text-sm"
+                              >
+                                <div className="flex min-w-0 items-center gap-2">
+                                  <DeliveryStatusDot status={delivery.status} />
+                                  <span className="truncate font-mono text-xs" title={delivery.webhookKey}>
+                                    {delivery.webhookKey}
+                                  </span>
+                                </div>
+                                <div className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                                  {delivery.durationMs != null ? <span>{formatDuration(delivery.durationMs)}</span> : null}
+                                  <span title={delivery.createdAt}>{formatRelativeTime(delivery.createdAt)}</span>
+                                </div>
+                              </div>
+                            ))}
+                          </div>
+                        ) : (
+                          <p className="text-sm text-muted-foreground italic">No webhook deliveries recorded yet.</p>
+                        )}
+                      </div>
+
+                      <div className="flex items-center gap-1.5 border-t border-border/50 pt-2 text-xs text-muted-foreground">
+                        <Clock className="h-3 w-3" />
+                        Last checked: {new Date(dashboardData.checkedAt).toLocaleTimeString()}
+                      </div>
+                    </>
+                  ) : (
+                    <p className="text-sm text-muted-foreground">
+                      Runtime diagnostics are unavailable right now.
+                    </p>
+                  )}
+                </CardContent>
+              </Card>
+
+              {recentLogs && recentLogs.length > 0 ? (
+                <Card>
+                  <CardHeader>
+                    <CardTitle className="text-base flex items-center gap-1.5">
+                      <ActivitySquare className="h-4 w-4" />
+                      Recent Logs
+                    </CardTitle>
+                    <CardDescription>Last {recentLogs.length} log entries</CardDescription>
+                  </CardHeader>
+                  <CardContent>
+                    <div className="max-h-64 space-y-1 overflow-y-auto font-mono text-xs">
+                      {recentLogs.map((entry) => (
+                        <div
+                          key={entry.id}
+                          className={`flex gap-2 py-0.5 ${
+                            entry.level === "error"
+                              ? "text-destructive"
+                              : entry.level === "warn"
+                                ? "text-yellow-600 dark:text-yellow-400"
+                                : entry.level === "debug"
+                                  ? "text-muted-foreground/60"
+                                  : "text-muted-foreground"
+                          }`}
+                        >
+                          <span className="shrink-0 text-muted-foreground/50">{new Date(entry.createdAt).toLocaleTimeString()}</span>
+                          <Badge variant="outline" className="h-4 shrink-0 px-1 text-[10px]">{entry.level}</Badge>
+                          <span className="truncate" title={entry.message}>{entry.message}</span>
+                        </div>
+                      ))}
+                    </div>
+                  </CardContent>
+                </Card>
+              ) : null}
+            </div>
+
+            <div className="space-y-6">
+              <Card>
+                <CardHeader>
+                  <CardTitle className="text-base flex items-center gap-1.5">
+                    <ActivitySquare className="h-4 w-4" />
+                    Health Status
+                  </CardTitle>
+                </CardHeader>
+                <CardContent>
+                  {healthLoading ? (
+                    <p className="text-sm text-muted-foreground">Checking health...</p>
+                  ) : healthData ? (
+                    <div className="space-y-4 text-sm">
+                      <div className="flex items-center justify-between">
+                        <span className="text-muted-foreground">Overall</span>
+                        <Badge variant={healthData.healthy ? "default" : "destructive"}>
+                          {healthData.status}
+                        </Badge>
+                      </div>
+
+                      {healthData.checks.length > 0 ? (
+                        <div className="space-y-2 border-t border-border/50 pt-2">
+                          {healthData.checks.map((check, i) => (
+                            <div key={i} className="flex items-start justify-between gap-2">
+                              <span className="truncate text-muted-foreground" title={check.name}>
+                                {check.name}
+                              </span>
+                              {check.passed ? (
+                                <CheckCircle className="h-4 w-4 shrink-0 text-green-500" />
+                              ) : (
+                                <XCircle className="h-4 w-4 shrink-0 text-destructive" />
+                              )}
+                            </div>
+                          ))}
+                        </div>
+                      ) : null}
+
+                      {healthData.lastError ? (
+                        <div className="break-words rounded border border-destructive/20 bg-destructive/10 p-2 text-xs text-destructive">
+                          {healthData.lastError}
+                        </div>
+                      ) : null}
+                    </div>
+                  ) : (
+                    <div className="space-y-3 text-sm text-muted-foreground">
+                      <div className="flex items-center justify-between">
+                        <span>Lifecycle</span>
+                        <Badge variant={statusVariant}>{displayStatus}</Badge>
+                      </div>
+                      <p>Health checks run once the plugin is ready.</p>
+                      {plugin.lastError ? (
+                        <div className="break-words rounded border border-destructive/20 bg-destructive/10 p-2 text-xs text-destructive">
+                          {plugin.lastError}
+                        </div>
+                      ) : null}
+                    </div>
+                  )}
+                </CardContent>
+              </Card>
+
+              <Card>
+                <CardHeader>
+                  <CardTitle className="text-base">Details</CardTitle>
+                </CardHeader>
+                <CardContent className="space-y-3 text-sm text-muted-foreground">
+                  <div className="flex justify-between gap-3">
+                    <span>Plugin ID</span>
+                    <span className="font-mono text-xs text-right">{plugin.id}</span>
+                  </div>
+                  <div className="flex justify-between gap-3">
+                    <span>Plugin Key</span>
+                    <span className="font-mono text-xs text-right">{plugin.pluginKey}</span>
+                  </div>
+                  <div className="flex justify-between gap-3">
+                    <span>NPM Package</span>
+                    <span className="max-w-[170px] truncate text-right text-xs" title={plugin.packageName}>
+                      {plugin.packageName}
+                    </span>
+                  </div>
+                  <div className="flex justify-between gap-3">
+                    <span>Version</span>
+                    <span className="text-right text-foreground">v{plugin.manifestJson.version ?? plugin.version}</span>
+                  </div>
+                </CardContent>
+              </Card>
+
+              <Card>
+                <CardHeader>
+                  <CardTitle className="text-base flex items-center gap-1.5">
+                    <ShieldAlert className="h-4 w-4" />
+                    Permissions
+                  </CardTitle>
+                </CardHeader>
+                <CardContent>
+                  {pluginCapabilities.length > 0 ? (
+                    <ul className="space-y-2 text-sm text-muted-foreground">
+                      {pluginCapabilities.map((cap) => (
+                        <li key={cap} className="rounded-md bg-muted/40 px-2.5 py-2 font-mono text-xs text-foreground/85">
+                          {cap}
+                        </li>
+                      ))}
+                    </ul>
+                  ) : (
+                    <p className="text-sm text-muted-foreground italic">No special permissions requested.</p>
+                  )}
+                </CardContent>
+              </Card>
+            </div>
+          </div>
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PluginConfigForm — auto-generated form for instanceConfigSchema
+// ---------------------------------------------------------------------------
+
+interface PluginConfigFormProps {
+  pluginId: string;
+  schema: JsonSchemaNode;
+  initialValues?: Record<string, unknown>;
+  isLoading?: boolean;
+  /** Current plugin lifecycle status — "Test Configuration" only available when `ready`. */
+  pluginStatus?: string;
+  /** Whether the plugin worker implements `validateConfig`. */
+  supportsConfigTest?: boolean;
+}
+
+/**
+ * Inner component that manages form state, validation, save, and "Test Configuration"
+ * for the auto-generated plugin config form.
+ *
+ * Separated from PluginSettings to isolate re-render scope — only the form
+ * re-renders on field changes, not the entire page.
+ */
+function PluginConfigForm({ pluginId, schema, initialValues, isLoading, pluginStatus, supportsConfigTest }: PluginConfigFormProps) {
+  const queryClient = useQueryClient();
+
+  // Form values: start with saved values, fall back to schema defaults
+  const [values, setValues] = useState<Record<string, unknown>>(() => ({
+    ...getDefaultValues(schema),
+    ...(initialValues ?? {}),
+  }));
+
+  // Sync when saved config loads asynchronously — only on first load so we
+  // don't overwrite in-progress user edits if the query refetches (e.g. on
+  // window focus).
+  const hasHydratedRef = useRef(false);
+  useEffect(() => {
+    if (initialValues && !hasHydratedRef.current) {
+      hasHydratedRef.current = true;
+      setValues({
+        ...getDefaultValues(schema),
+        ...initialValues,
+      });
+    }
+  }, [initialValues, schema]);
+
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [saveMessage, setSaveMessage] = useState<{ type: "success" | "error"; text: string } | null>(null);
+  const [testResult, setTestResult] = useState<{ type: "success" | "error"; text: string } | null>(null);
+
+  // Dirty tracking: compare against initial values
+  const isDirty = JSON.stringify(values) !== JSON.stringify({
+    ...getDefaultValues(schema),
+    ...(initialValues ?? {}),
+  });
+
+  // Save mutation
+  const saveMutation = useMutation({
+    mutationFn: (configJson: Record<string, unknown>) =>
+      pluginsApi.saveConfig(pluginId, configJson),
+    onSuccess: () => {
+      setSaveMessage({ type: "success", text: "Configuration saved." });
+      setTestResult(null);
+      queryClient.invalidateQueries({ queryKey: queryKeys.plugins.config(pluginId) });
+      // Clear success message after 3s
+      setTimeout(() => setSaveMessage(null), 3000);
+    },
+    onError: (err: Error) => {
+      setSaveMessage({ type: "error", text: err.message || "Failed to save configuration." });
+    },
+  });
+
+  // Test configuration mutation
+  const testMutation = useMutation({
+    mutationFn: (configJson: Record<string, unknown>) =>
+      pluginsApi.testConfig(pluginId, configJson),
+    onSuccess: (result) => {
+      if (result.valid) {
+        setTestResult({ type: "success", text: "Configuration test passed." });
+      } else {
+        setTestResult({ type: "error", text: result.message || "Configuration test failed." });
+      }
+    },
+    onError: (err: Error) => {
+      setTestResult({ type: "error", text: err.message || "Configuration test failed." });
+    },
+  });
+
+  const handleChange = useCallback((newValues: Record<string, unknown>) => {
+    setValues(newValues);
+    // Clear field-level errors as the user types
+    setErrors({});
+    setSaveMessage(null);
+  }, []);
+
+  const handleSave = useCallback(() => {
+    // Validate before saving
+    const validationErrors = validateJsonSchemaForm(schema, values);
+    if (Object.keys(validationErrors).length > 0) {
+      setErrors(validationErrors);
+      return;
+    }
+    setErrors({});
+    saveMutation.mutate(values);
+  }, [schema, values, saveMutation]);
+
+  const handleTestConnection = useCallback(() => {
+    // Validate before testing
+    const validationErrors = validateJsonSchemaForm(schema, values);
+    if (Object.keys(validationErrors).length > 0) {
+      setErrors(validationErrors);
+      return;
+    }
+    setErrors({});
+    setTestResult(null);
+    testMutation.mutate(values);
+  }, [schema, values, testMutation]);
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground py-4">
+        <Loader2 className="h-4 w-4 animate-spin" />
+        Loading configuration...
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <JsonSchemaForm
+        schema={schema}
+        values={values}
+        onChange={handleChange}
+        errors={errors}
+        disabled={saveMutation.isPending}
+      />
+
+      {/* Status messages */}
+      {saveMessage && (
+        <div
+          className={`text-sm p-2 rounded border ${
+            saveMessage.type === "success"
+              ? "text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/30 dark:border-green-900"
+              : "text-destructive bg-destructive/10 border-destructive/20"
+          }`}
+        >
+          {saveMessage.text}
+        </div>
+      )}
+
+      {testResult && (
+        <div
+          className={`text-sm p-2 rounded border ${
+            testResult.type === "success"
+              ? "text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/30 dark:border-green-900"
+              : "text-destructive bg-destructive/10 border-destructive/20"
+          }`}
+        >
+          {testResult.text}
+        </div>
+      )}
+
+      {/* Action buttons */}
+      <div className="flex items-center gap-2 pt-2">
+        <Button
+          onClick={handleSave}
+          disabled={saveMutation.isPending || !isDirty}
+          size="sm"
+        >
+          {saveMutation.isPending ? (
+            <>
+              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+              Saving...
+            </>
+          ) : (
+            "Save Configuration"
+          )}
+        </Button>
+        {pluginStatus === "ready" && supportsConfigTest && (
+          <Button
+            variant="outline"
+            onClick={handleTestConnection}
+            disabled={testMutation.isPending}
+            size="sm"
+          >
+            {testMutation.isPending ? (
+              <>
+                <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                Testing...
+              </>
+            ) : (
+              "Test Configuration"
+            )}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard helper components and formatting utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an uptime value (in milliseconds) to a human-readable string.
+ */
+function formatUptime(uptimeMs: number | null): string {
+  if (uptimeMs == null) return "—";
+  const totalSeconds = Math.floor(uptimeMs / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  if (minutes < 60) return `${minutes}m ${totalSeconds % 60}s`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h`;
+}
+
+/**
+ * Format a duration in milliseconds to a compact display string.
+ */
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+/**
+ * Format an ISO timestamp to a relative time string (e.g., "2m ago").
+ */
+function formatRelativeTime(isoString: string): string {
+  const now = Date.now();
+  const then = new Date(isoString).getTime();
+  const diffMs = now - then;
+
+  if (diffMs < 0) return "just now";
+  const seconds = Math.floor(diffMs / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+/**
+ * Format a unix timestamp (ms since epoch) to a locale string.
+ */
+function formatTimestamp(epochMs: number): string {
+  return new Date(epochMs).toLocaleString();
+}
+
+/**
+ * Status indicator dot for job run statuses.
+ */
+function JobStatusDot({ status }: { status: string }) {
+  const colorClass =
+    status === "success" || status === "succeeded"
+      ? "bg-green-500"
+      : status === "failed"
+        ? "bg-red-500"
+        : status === "running"
+          ? "bg-blue-500 animate-pulse"
+          : status === "cancelled"
+            ? "bg-gray-400"
+            : "bg-amber-500"; // queued, pending
+  return (
+    <span
+      className={`inline-block h-2 w-2 rounded-full shrink-0 ${colorClass}`}
+      title={status}
+    />
+  );
+}
+
+/**
+ * Status indicator dot for webhook delivery statuses.
+ */
+function DeliveryStatusDot({ status }: { status: string }) {
+  const colorClass =
+    status === "processed" || status === "success"
+      ? "bg-green-500"
+      : status === "failed"
+        ? "bg-red-500"
+        : status === "received"
+          ? "bg-blue-500"
+          : "bg-amber-500"; // pending
+  return (
+    <span
+      className={`inline-block h-2 w-2 rounded-full shrink-0 ${colorClass}`}
+      title={status}
+    />
+  );
+}

paperclip-reference/ui/src/pages/ProjectDetail.tsx

@@ -0,0 +1,632 @@
+import { useCallback, useEffect, useMemo, useState, useRef } from "react";
+import { useParams, useNavigate, useLocation, Navigate } from "@/lib/router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { PROJECT_COLORS, isUuidLike, type BudgetPolicySummary } from "@paperclipai/shared";
+import { budgetsApi } from "../api/budgets";
+import { projectsApi } from "../api/projects";
+import { issuesApi } from "../api/issues";
+import { agentsApi } from "../api/agents";
+import { heartbeatsApi } from "../api/heartbeats";
+import { assetsApi } from "../api/assets";
+import { usePanel } from "../context/PanelContext";
+import { useCompany } from "../context/CompanyContext";
+import { useToast } from "../context/ToastContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { ProjectProperties, type ProjectConfigFieldKey, type ProjectFieldSaveState } from "../components/ProjectProperties";
+import { InlineEditor } from "../components/InlineEditor";
+import { StatusBadge } from "../components/StatusBadge";
+import { BudgetPolicyCard } from "../components/BudgetPolicyCard";
+import { IssuesList } from "../components/IssuesList";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { PageTabBar } from "../components/PageTabBar";
+import { projectRouteRef, cn } from "../lib/utils";
+import { Tabs } from "@/components/ui/tabs";
+import { PluginLauncherOutlet } from "@/plugins/launchers";
+import { PluginSlotMount, PluginSlotOutlet, usePluginSlots } from "@/plugins/slots";
+
+/* ── Top-level tab types ── */
+
+type ProjectBaseTab = "overview" | "list" | "configuration" | "budget";
+type ProjectPluginTab = `plugin:${string}`;
+type ProjectTab = ProjectBaseTab | ProjectPluginTab;
+
+function isProjectPluginTab(value: string | null): value is ProjectPluginTab {
+  return typeof value === "string" && value.startsWith("plugin:");
+}
+
+function resolveProjectTab(pathname: string, projectId: string): ProjectTab | null {
+  const segments = pathname.split("/").filter(Boolean);
+  const projectsIdx = segments.indexOf("projects");
+  if (projectsIdx === -1 || segments[projectsIdx + 1] !== projectId) return null;
+  const tab = segments[projectsIdx + 2];
+  if (tab === "overview") return "overview";
+  if (tab === "configuration") return "configuration";
+  if (tab === "budget") return "budget";
+  if (tab === "issues") return "list";
+  return null;
+}
+
+/* ── Overview tab content ── */
+
+function OverviewContent({
+  project,
+  onUpdate,
+  imageUploadHandler,
+}: {
+  project: { description: string | null; status: string; targetDate: string | null };
+  onUpdate: (data: Record<string, unknown>) => void;
+  imageUploadHandler?: (file: File) => Promise<string>;
+}) {
+  return (
+    <div className="space-y-6">
+      <InlineEditor
+        value={project.description ?? ""}
+        onSave={(description) => onUpdate({ description })}
+        as="p"
+        className="text-sm text-muted-foreground"
+        placeholder="Add a description..."
+        multiline
+        imageUploadHandler={imageUploadHandler}
+      />
+
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 text-sm">
+        <div>
+          <span className="text-muted-foreground">Status</span>
+          <div className="mt-1">
+            <StatusBadge status={project.status} />
+          </div>
+        </div>
+        {project.targetDate && (
+          <div>
+            <span className="text-muted-foreground">Target Date</span>
+            <p>{project.targetDate}</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* ── Color picker popover ── */
+
+function ColorPicker({
+  currentColor,
+  onSelect,
+}: {
+  currentColor: string;
+  onSelect: (color: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [open]);
+
+  return (
+    <div className="relative" ref={ref}>
+      <button
+        onClick={() => setOpen(!open)}
+        className="shrink-0 h-5 w-5 rounded-md cursor-pointer hover:ring-2 hover:ring-foreground/20 transition-[box-shadow]"
+        style={{ backgroundColor: currentColor }}
+        aria-label="Change project color"
+      />
+      {open && (
+        <div className="absolute top-full left-0 mt-2 p-2 bg-popover border border-border rounded-lg shadow-lg z-50 w-max">
+          <div className="grid grid-cols-5 gap-1.5">
+            {PROJECT_COLORS.map((color) => (
+              <button
+                key={color}
+                onClick={() => {
+                  onSelect(color);
+                  setOpen(false);
+                }}
+                className={`h-6 w-6 rounded-md cursor-pointer transition-[transform,box-shadow] duration-150 hover:scale-110 ${
+                  color === currentColor
+                    ? "ring-2 ring-foreground ring-offset-1 ring-offset-background"
+                    : "hover:ring-2 hover:ring-foreground/30"
+                }`}
+                style={{ backgroundColor: color }}
+                aria-label={`Select color ${color}`}
+              />
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/* ── List (issues) tab content ── */
+
+function ProjectIssuesList({ projectId, companyId }: { projectId: string; companyId: string }) {
+  const queryClient = useQueryClient();
+
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(companyId),
+    queryFn: () => agentsApi.list(companyId),
+    enabled: !!companyId,
+  });
+
+  const { data: liveRuns } = useQuery({
+    queryKey: queryKeys.liveRuns(companyId),
+    queryFn: () => heartbeatsApi.liveRunsForCompany(companyId),
+    enabled: !!companyId,
+    refetchInterval: 5000,
+  });
+
+  const liveIssueIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const run of liveRuns ?? []) {
+      if (run.issueId) ids.add(run.issueId);
+    }
+    return ids;
+  }, [liveRuns]);
+
+  const { data: issues, isLoading, error } = useQuery({
+    queryKey: queryKeys.issues.listByProject(companyId, projectId),
+    queryFn: () => issuesApi.list(companyId, { projectId }),
+    enabled: !!companyId,
+  });
+
+  const updateIssue = useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Record<string, unknown> }) =>
+      issuesApi.update(id, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.issues.listByProject(companyId, projectId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.issues.list(companyId) });
+    },
+  });
+
+  return (
+    <IssuesList
+      issues={issues ?? []}
+      isLoading={isLoading}
+      error={error as Error | null}
+      agents={agents}
+      liveIssueIds={liveIssueIds}
+      projectId={projectId}
+      viewStateKey={`paperclip:project-view:${projectId}`}
+      onUpdateIssue={(id, data) => updateIssue.mutate({ id, data })}
+    />
+  );
+}
+
+/* ── Main project page ── */
+
+export function ProjectDetail() {
+  const { companyPrefix, projectId, filter } = useParams<{
+    companyPrefix?: string;
+    projectId: string;
+    filter?: string;
+  }>();
+  const { companies, selectedCompanyId, setSelectedCompanyId } = useCompany();
+  const { closePanel } = usePanel();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const { pushToast } = useToast();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [fieldSaveStates, setFieldSaveStates] = useState<Partial<Record<ProjectConfigFieldKey, ProjectFieldSaveState>>>({});
+  const fieldSaveRequestIds = useRef<Partial<Record<ProjectConfigFieldKey, number>>>({});
+  const fieldSaveTimers = useRef<Partial<Record<ProjectConfigFieldKey, ReturnType<typeof setTimeout>>>>({});
+  const routeProjectRef = projectId ?? "";
+  const routeCompanyId = useMemo(() => {
+    if (!companyPrefix) return null;
+    const requestedPrefix = companyPrefix.toUpperCase();
+    return companies.find((company) => company.issuePrefix.toUpperCase() === requestedPrefix)?.id ?? null;
+  }, [companies, companyPrefix]);
+  const lookupCompanyId = routeCompanyId ?? selectedCompanyId ?? undefined;
+  const canFetchProject = routeProjectRef.length > 0 && (isUuidLike(routeProjectRef) || Boolean(lookupCompanyId));
+  const activeRouteTab = routeProjectRef ? resolveProjectTab(location.pathname, routeProjectRef) : null;
+  const pluginTabFromSearch = useMemo(() => {
+    const tab = new URLSearchParams(location.search).get("tab");
+    return isProjectPluginTab(tab) ? tab : null;
+  }, [location.search]);
+  const activeTab = activeRouteTab ?? pluginTabFromSearch;
+
+  const { data: project, isLoading, error } = useQuery({
+    queryKey: [...queryKeys.projects.detail(routeProjectRef), lookupCompanyId ?? null],
+    queryFn: () => projectsApi.get(routeProjectRef, lookupCompanyId),
+    enabled: canFetchProject,
+  });
+  const canonicalProjectRef = project ? projectRouteRef(project) : routeProjectRef;
+  const projectLookupRef = project?.id ?? routeProjectRef;
+  const resolvedCompanyId = project?.companyId ?? selectedCompanyId;
+  const {
+    slots: pluginDetailSlots,
+    isLoading: pluginDetailSlotsLoading,
+  } = usePluginSlots({
+    slotTypes: ["detailTab"],
+    entityType: "project",
+    companyId: resolvedCompanyId,
+    enabled: !!resolvedCompanyId,
+  });
+  const pluginTabItems = useMemo(
+    () => pluginDetailSlots.map((slot) => ({
+      value: `plugin:${slot.pluginKey}:${slot.id}` as ProjectPluginTab,
+      label: slot.displayName,
+      slot,
+    })),
+    [pluginDetailSlots],
+  );
+  const activePluginTab = pluginTabItems.find((item) => item.value === activeTab) ?? null;
+
+  useEffect(() => {
+    if (!project?.companyId || project.companyId === selectedCompanyId) return;
+    setSelectedCompanyId(project.companyId, { source: "route_sync" });
+  }, [project?.companyId, selectedCompanyId, setSelectedCompanyId]);
+
+  const invalidateProject = () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(routeProjectRef) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(projectLookupRef) });
+    if (resolvedCompanyId) {
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.list(resolvedCompanyId) });
+    }
+  };
+
+  const updateProject = useMutation({
+    mutationFn: (data: Record<string, unknown>) =>
+      projectsApi.update(projectLookupRef, data, resolvedCompanyId ?? lookupCompanyId),
+    onSuccess: invalidateProject,
+  });
+
+  const archiveProject = useMutation({
+    mutationFn: (archived: boolean) =>
+      projectsApi.update(
+        projectLookupRef,
+        { archivedAt: archived ? new Date().toISOString() : null },
+        resolvedCompanyId ?? lookupCompanyId,
+      ),
+    onSuccess: (updatedProject, archived) => {
+      invalidateProject();
+      const name = updatedProject?.name ?? project?.name ?? "Project";
+      if (archived) {
+        pushToast({ title: `"${name}" has been archived`, tone: "success" });
+        navigate("/dashboard");
+      } else {
+        pushToast({ title: `"${name}" has been unarchived`, tone: "success" });
+      }
+    },
+    onError: (_, archived) => {
+      pushToast({
+        title: archived ? "Failed to archive project" : "Failed to unarchive project",
+        tone: "error",
+      });
+    },
+  });
+
+  const uploadImage = useMutation({
+    mutationFn: async (file: File) => {
+      if (!resolvedCompanyId) throw new Error("No company selected");
+      return assetsApi.uploadImage(resolvedCompanyId, file, `projects/${projectLookupRef || "draft"}`);
+    },
+  });
+
+  const { data: budgetOverview } = useQuery({
+    queryKey: queryKeys.budgets.overview(resolvedCompanyId ?? "__none__"),
+    queryFn: () => budgetsApi.overview(resolvedCompanyId!),
+    enabled: !!resolvedCompanyId,
+    refetchInterval: 30_000,
+    staleTime: 5_000,
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([
+      { label: "Projects", href: "/projects" },
+      { label: project?.name ?? routeProjectRef ?? "Project" },
+    ]);
+  }, [setBreadcrumbs, project, routeProjectRef]);
+
+  useEffect(() => {
+    if (!project) return;
+    if (routeProjectRef === canonicalProjectRef) return;
+    if (isProjectPluginTab(activeTab)) {
+      navigate(`/projects/${canonicalProjectRef}?tab=${encodeURIComponent(activeTab)}`, { replace: true });
+      return;
+    }
+    if (activeTab === "overview") {
+      navigate(`/projects/${canonicalProjectRef}/overview`, { replace: true });
+      return;
+    }
+    if (activeTab === "configuration") {
+      navigate(`/projects/${canonicalProjectRef}/configuration`, { replace: true });
+      return;
+    }
+    if (activeTab === "budget") {
+      navigate(`/projects/${canonicalProjectRef}/budget`, { replace: true });
+      return;
+    }
+    if (activeTab === "list") {
+      if (filter) {
+        navigate(`/projects/${canonicalProjectRef}/issues/${filter}`, { replace: true });
+        return;
+      }
+      navigate(`/projects/${canonicalProjectRef}/issues`, { replace: true });
+      return;
+    }
+    navigate(`/projects/${canonicalProjectRef}`, { replace: true });
+  }, [project, routeProjectRef, canonicalProjectRef, activeTab, filter, navigate]);
+
+  useEffect(() => {
+    closePanel();
+    return () => closePanel();
+  }, [closePanel]);
+
+  useEffect(() => {
+    return () => {
+      Object.values(fieldSaveTimers.current).forEach((timer) => {
+        if (timer) clearTimeout(timer);
+      });
+    };
+  }, []);
+
+  const setFieldState = useCallback((field: ProjectConfigFieldKey, state: ProjectFieldSaveState) => {
+    setFieldSaveStates((current) => ({ ...current, [field]: state }));
+  }, []);
+
+  const scheduleFieldReset = useCallback((field: ProjectConfigFieldKey, delayMs: number) => {
+    const existing = fieldSaveTimers.current[field];
+    if (existing) clearTimeout(existing);
+    fieldSaveTimers.current[field] = setTimeout(() => {
+      setFieldSaveStates((current) => {
+        const next = { ...current };
+        delete next[field];
+        return next;
+      });
+      delete fieldSaveTimers.current[field];
+    }, delayMs);
+  }, []);
+
+  const updateProjectField = useCallback(async (field: ProjectConfigFieldKey, data: Record<string, unknown>) => {
+    const requestId = (fieldSaveRequestIds.current[field] ?? 0) + 1;
+    fieldSaveRequestIds.current[field] = requestId;
+    setFieldState(field, "saving");
+    try {
+      await projectsApi.update(projectLookupRef, data, resolvedCompanyId ?? lookupCompanyId);
+      invalidateProject();
+      if (fieldSaveRequestIds.current[field] !== requestId) return;
+      setFieldState(field, "saved");
+      scheduleFieldReset(field, 1800);
+    } catch (error) {
+      if (fieldSaveRequestIds.current[field] !== requestId) return;
+      setFieldState(field, "error");
+      scheduleFieldReset(field, 3000);
+      throw error;
+    }
+  }, [invalidateProject, lookupCompanyId, projectLookupRef, resolvedCompanyId, scheduleFieldReset, setFieldState]);
+
+  const projectBudgetSummary = useMemo(() => {
+    const matched = budgetOverview?.policies.find(
+      (policy) => policy.scopeType === "project" && policy.scopeId === (project?.id ?? routeProjectRef),
+    );
+    if (matched) return matched;
+    return {
+      policyId: "",
+      companyId: resolvedCompanyId ?? "",
+      scopeType: "project",
+      scopeId: project?.id ?? routeProjectRef,
+      scopeName: project?.name ?? "Project",
+      metric: "billed_cents",
+      windowKind: "lifetime",
+      amount: 0,
+      observedAmount: 0,
+      remainingAmount: 0,
+      utilizationPercent: 0,
+      warnPercent: 80,
+      hardStopEnabled: true,
+      notifyEnabled: true,
+      isActive: false,
+      status: "ok",
+      paused: Boolean(project?.pausedAt),
+      pauseReason: project?.pauseReason ?? null,
+      windowStart: new Date(),
+      windowEnd: new Date(),
+    } satisfies BudgetPolicySummary;
+  }, [budgetOverview?.policies, project, resolvedCompanyId, routeProjectRef]);
+
+  const budgetMutation = useMutation({
+    mutationFn: (amount: number) =>
+      budgetsApi.upsertPolicy(resolvedCompanyId!, {
+        scopeType: "project",
+        scopeId: project?.id ?? routeProjectRef,
+        amount,
+        windowKind: "lifetime",
+      }),
+    onSuccess: () => {
+      if (!resolvedCompanyId) return;
+      queryClient.invalidateQueries({ queryKey: queryKeys.budgets.overview(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(routeProjectRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(projectLookupRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.list(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.dashboard(resolvedCompanyId) });
+    },
+  });
+
+  if (pluginTabFromSearch && !pluginDetailSlotsLoading && !activePluginTab) {
+    return <Navigate to={`/projects/${canonicalProjectRef}/issues`} replace />;
+  }
+
+  // Redirect bare /projects/:id to cached tab or default /issues
+  if (routeProjectRef && activeTab === null) {
+    let cachedTab: string | null = null;
+    if (project?.id) {
+      try { cachedTab = localStorage.getItem(`paperclip:project-tab:${project.id}`); } catch {}
+    }
+    if (cachedTab === "overview") {
+      return <Navigate to={`/projects/${canonicalProjectRef}/overview`} replace />;
+    }
+    if (cachedTab === "configuration") {
+      return <Navigate to={`/projects/${canonicalProjectRef}/configuration`} replace />;
+    }
+    if (cachedTab === "budget") {
+      return <Navigate to={`/projects/${canonicalProjectRef}/budget`} replace />;
+    }
+    if (isProjectPluginTab(cachedTab)) {
+      return <Navigate to={`/projects/${canonicalProjectRef}?tab=${encodeURIComponent(cachedTab)}`} replace />;
+    }
+    return <Navigate to={`/projects/${canonicalProjectRef}/issues`} replace />;
+  }
+
+  if (isLoading) return <PageSkeleton variant="detail" />;
+  if (error) return <p className="text-sm text-destructive">{error.message}</p>;
+  if (!project) return null;
+
+  const handleTabChange = (tab: ProjectTab) => {
+    // Cache the active tab per project
+    if (project?.id) {
+      try { localStorage.setItem(`paperclip:project-tab:${project.id}`, tab); } catch {}
+    }
+    if (isProjectPluginTab(tab)) {
+      navigate(`/projects/${canonicalProjectRef}?tab=${encodeURIComponent(tab)}`);
+      return;
+    }
+    if (tab === "overview") {
+      navigate(`/projects/${canonicalProjectRef}/overview`);
+    } else if (tab === "budget") {
+      navigate(`/projects/${canonicalProjectRef}/budget`);
+    } else if (tab === "configuration") {
+      navigate(`/projects/${canonicalProjectRef}/configuration`);
+    } else {
+      navigate(`/projects/${canonicalProjectRef}/issues`);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-start gap-3">
+        <div className="h-7 flex items-center">
+          <ColorPicker
+            currentColor={project.color ?? "#6366f1"}
+            onSelect={(color) => updateProject.mutate({ color })}
+          />
+        </div>
+        <div className="min-w-0 space-y-2">
+          <InlineEditor
+            value={project.name}
+            onSave={(name) => updateProject.mutate({ name })}
+            as="h2"
+            className="text-xl font-bold"
+          />
+          {project.pauseReason === "budget" ? (
+            <div className="inline-flex items-center gap-2 rounded-full border border-red-500/30 bg-red-500/10 px-3 py-1 text-[11px] font-medium uppercase tracking-[0.18em] text-red-200">
+              <span className="h-2 w-2 rounded-full bg-red-400" />
+              Paused by budget hard stop
+            </div>
+          ) : null}
+        </div>
+      </div>
+
+      <PluginSlotOutlet
+        slotTypes={["toolbarButton", "contextMenuItem"]}
+        entityType="project"
+        context={{
+          companyId: resolvedCompanyId ?? null,
+          companyPrefix: companyPrefix ?? null,
+          projectId: project.id,
+          projectRef: canonicalProjectRef,
+          entityId: project.id,
+          entityType: "project",
+        }}
+        className="flex flex-wrap gap-2"
+        itemClassName="inline-flex"
+        missingBehavior="placeholder"
+      />
+
+      <PluginLauncherOutlet
+        placementZones={["toolbarButton"]}
+        entityType="project"
+        context={{
+          companyId: resolvedCompanyId ?? null,
+          companyPrefix: companyPrefix ?? null,
+          projectId: project.id,
+          projectRef: canonicalProjectRef,
+          entityId: project.id,
+          entityType: "project",
+        }}
+        className="flex flex-wrap gap-2"
+        itemClassName="inline-flex"
+      />
+
+      <Tabs value={activeTab ?? "list"} onValueChange={(value) => handleTabChange(value as ProjectTab)}>
+        <PageTabBar
+          items={[
+            { value: "list", label: "Issues" },
+            { value: "overview", label: "Overview" },
+            { value: "configuration", label: "Configuration" },
+            { value: "budget", label: "Budget" },
+            ...pluginTabItems.map((item) => ({
+              value: item.value,
+              label: item.label,
+            })),
+          ]}
+          align="start"
+          value={activeTab ?? "list"}
+          onValueChange={(value) => handleTabChange(value as ProjectTab)}
+        />
+      </Tabs>
+
+      {activeTab === "overview" && (
+        <OverviewContent
+          project={project}
+          onUpdate={(data) => updateProject.mutate(data)}
+          imageUploadHandler={async (file) => {
+            const asset = await uploadImage.mutateAsync(file);
+            return asset.contentPath;
+          }}
+        />
+      )}
+
+      {activeTab === "list" && project?.id && resolvedCompanyId && (
+        <ProjectIssuesList projectId={project.id} companyId={resolvedCompanyId} />
+      )}
+
+      {activeTab === "configuration" && (
+        <div className="max-w-4xl">
+          <ProjectProperties
+            project={project}
+            onUpdate={(data) => updateProject.mutate(data)}
+            onFieldUpdate={updateProjectField}
+            getFieldSaveState={(field) => fieldSaveStates[field] ?? "idle"}
+            onArchive={(archived) => archiveProject.mutate(archived)}
+            archivePending={archiveProject.isPending}
+          />
+        </div>
+      )}
+
+      {activeTab === "budget" && resolvedCompanyId ? (
+        <div className="max-w-3xl">
+          <BudgetPolicyCard
+            summary={projectBudgetSummary}
+            variant="plain"
+            isSaving={budgetMutation.isPending}
+            onSave={(amount) => budgetMutation.mutate(amount)}
+          />
+        </div>
+      ) : null}
+
+      {activePluginTab && (
+        <PluginSlotMount
+          slot={activePluginTab.slot}
+          context={{
+            companyId: resolvedCompanyId,
+            companyPrefix: companyPrefix ?? null,
+            projectId: project.id,
+            projectRef: canonicalProjectRef,
+            entityId: project.id,
+            entityType: "project",
+          }}
+          missingBehavior="placeholder"
+        />
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Projects.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { projectsApi } from "../api/projects";
+import { useCompany } from "../context/CompanyContext";
+import { useDialog } from "../context/DialogContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { queryKeys } from "../lib/queryKeys";
+import { EntityRow } from "../components/EntityRow";
+import { StatusBadge } from "../components/StatusBadge";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { formatDate, projectUrl } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { Hexagon, Plus } from "lucide-react";
+
+export function Projects() {
+  const { selectedCompanyId } = useCompany();
+  const { openNewProject } = useDialog();
+  const { setBreadcrumbs } = useBreadcrumbs();
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Projects" }]);
+  }, [setBreadcrumbs]);
+
+  const { data: allProjects, isLoading, error } = useQuery({
+    queryKey: queryKeys.projects.list(selectedCompanyId!),
+    queryFn: () => projectsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+  const projects = useMemo(
+    () => (allProjects ?? []).filter((p) => !p.archivedAt),
+    [allProjects],
+  );
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={Hexagon} message="Select a company to view projects." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="list" />;
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-end">
+        <Button size="sm" variant="outline" onClick={openNewProject}>
+          <Plus className="h-4 w-4 mr-1" />
+          Add Project
+        </Button>
+      </div>
+
+      {error && <p className="text-sm text-destructive">{error.message}</p>}
+
+      {!isLoading && projects.length === 0 && (
+        <EmptyState
+          icon={Hexagon}
+          message="No projects yet."
+          action="Add Project"
+          onAction={openNewProject}
+        />
+      )}
+
+      {projects.length > 0 && (
+        <div className="border border-border">
+          {projects.map((project) => (
+            <EntityRow
+              key={project.id}
+              title={project.name}
+              subtitle={project.description ?? undefined}
+              to={projectUrl(project)}
+              trailing={
+                <div className="flex items-center gap-3">
+                  {project.targetDate && (
+                    <span className="text-xs text-muted-foreground">
+                      {formatDate(project.targetDate)}
+                    </span>
+                  )}
+                  <StatusBadge status={project.status} />
+                </div>
+              }
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/Routines.tsx

@@ -0,0 +1,661 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@/lib/router";
+import { ChevronDown, ChevronRight, MoreHorizontal, Play, Plus, Repeat } from "lucide-react";
+import { routinesApi } from "../api/routines";
+import { agentsApi } from "../api/agents";
+import { projectsApi } from "../api/projects";
+import { useCompany } from "../context/CompanyContext";
+import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useToast } from "../context/ToastContext";
+import { queryKeys } from "../lib/queryKeys";
+import { getRecentAssigneeIds, sortAgentsByRecency, trackRecentAssignee } from "../lib/recent-assignees";
+import { EmptyState } from "../components/EmptyState";
+import { PageSkeleton } from "../components/PageSkeleton";
+import { AgentIcon } from "../components/AgentIconPicker";
+import { InlineEntitySelector, type InlineEntityOption } from "../components/InlineEntitySelector";
+import { MarkdownEditor, type MarkdownEditorRef } from "../components/MarkdownEditor";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import { Dialog, DialogContent } from "@/components/ui/dialog";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+
+const concurrencyPolicies = ["coalesce_if_active", "always_enqueue", "skip_if_active"];
+const catchUpPolicies = ["skip_missed", "enqueue_missed_with_cap"];
+const concurrencyPolicyDescriptions: Record<string, string> = {
+  coalesce_if_active: "If a run is already active, keep just one follow-up run queued.",
+  always_enqueue: "Queue every trigger occurrence, even if the routine is already running.",
+  skip_if_active: "Drop new trigger occurrences while a run is still active.",
+};
+const catchUpPolicyDescriptions: Record<string, string> = {
+  skip_missed: "Ignore windows that were missed while the scheduler or routine was paused.",
+  enqueue_missed_with_cap: "Catch up missed schedule windows in capped batches after recovery.",
+};
+
+function autoResizeTextarea(element: HTMLTextAreaElement | null) {
+  if (!element) return;
+  element.style.height = "auto";
+  element.style.height = `${element.scrollHeight}px`;
+}
+
+function formatLastRunTimestamp(value: Date | string | null | undefined) {
+  if (!value) return "Never";
+  return new Date(value).toLocaleString();
+}
+
+function nextRoutineStatus(currentStatus: string, enabled: boolean) {
+  if (currentStatus === "archived" && enabled) return "active";
+  return enabled ? "active" : "paused";
+}
+
+export function Routines() {
+  const { selectedCompanyId } = useCompany();
+  const { setBreadcrumbs } = useBreadcrumbs();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const { pushToast } = useToast();
+  const descriptionEditorRef = useRef<MarkdownEditorRef>(null);
+  const titleInputRef = useRef<HTMLTextAreaElement | null>(null);
+  const assigneeSelectorRef = useRef<HTMLButtonElement | null>(null);
+  const projectSelectorRef = useRef<HTMLButtonElement | null>(null);
+  const [runningRoutineId, setRunningRoutineId] = useState<string | null>(null);
+  const [statusMutationRoutineId, setStatusMutationRoutineId] = useState<string | null>(null);
+  const [composerOpen, setComposerOpen] = useState(false);
+  const [advancedOpen, setAdvancedOpen] = useState(false);
+  const [draft, setDraft] = useState({
+    title: "",
+    description: "",
+    projectId: "",
+    assigneeAgentId: "",
+    priority: "medium",
+    concurrencyPolicy: "coalesce_if_active",
+    catchUpPolicy: "skip_missed",
+  });
+
+  useEffect(() => {
+    setBreadcrumbs([{ label: "Routines" }]);
+  }, [setBreadcrumbs]);
+
+  const { data: routines, isLoading, error } = useQuery({
+    queryKey: queryKeys.routines.list(selectedCompanyId!),
+    queryFn: () => routinesApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+  const { data: agents } = useQuery({
+    queryKey: queryKeys.agents.list(selectedCompanyId!),
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+  const { data: projects } = useQuery({
+    queryKey: queryKeys.projects.list(selectedCompanyId!),
+    queryFn: () => projectsApi.list(selectedCompanyId!),
+    enabled: !!selectedCompanyId,
+  });
+
+  useEffect(() => {
+    autoResizeTextarea(titleInputRef.current);
+  }, [draft.title, composerOpen]);
+
+  const createRoutine = useMutation({
+    mutationFn: () =>
+      routinesApi.create(selectedCompanyId!, {
+        ...draft,
+        description: draft.description.trim() || null,
+      }),
+    onSuccess: async (routine) => {
+      setDraft({
+        title: "",
+        description: "",
+        projectId: "",
+        assigneeAgentId: "",
+        priority: "medium",
+        concurrencyPolicy: "coalesce_if_active",
+        catchUpPolicy: "skip_missed",
+      });
+      setComposerOpen(false);
+      setAdvancedOpen(false);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) });
+      pushToast({
+        title: "Routine created",
+        body: "Add the first trigger to turn it into a live workflow.",
+        tone: "success",
+      });
+      navigate(`/routines/${routine.id}?tab=triggers`);
+    },
+  });
+
+  const updateRoutineStatus = useMutation({
+    mutationFn: ({ id, status }: { id: string; status: string }) => routinesApi.update(id, { status }),
+    onMutate: ({ id }) => {
+      setStatusMutationRoutineId(id);
+    },
+    onSuccess: async (_, variables) => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(variables.id) }),
+      ]);
+    },
+    onSettled: () => {
+      setStatusMutationRoutineId(null);
+    },
+    onError: (mutationError) => {
+      pushToast({
+        title: "Failed to update routine",
+        body: mutationError instanceof Error ? mutationError.message : "Paperclip could not update the routine.",
+        tone: "error",
+      });
+    },
+  });
+
+  const runRoutine = useMutation({
+    mutationFn: (id: string) => routinesApi.run(id),
+    onMutate: (id) => {
+      setRunningRoutineId(id);
+    },
+    onSuccess: async (_, id) => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(id) }),
+      ]);
+    },
+    onSettled: () => {
+      setRunningRoutineId(null);
+    },
+    onError: (mutationError) => {
+      pushToast({
+        title: "Routine run failed",
+        body: mutationError instanceof Error ? mutationError.message : "Paperclip could not start the routine run.",
+        tone: "error",
+      });
+    },
+  });
+
+  const recentAssigneeIds = useMemo(() => getRecentAssigneeIds(), [composerOpen]);
+  const assigneeOptions = useMemo<InlineEntityOption[]>(
+    () =>
+      sortAgentsByRecency(
+        (agents ?? []).filter((agent) => agent.status !== "terminated"),
+        recentAssigneeIds,
+      ).map((agent) => ({
+        id: agent.id,
+        label: agent.name,
+        searchText: `${agent.name} ${agent.role} ${agent.title ?? ""}`,
+      })),
+    [agents, recentAssigneeIds],
+  );
+  const projectOptions = useMemo<InlineEntityOption[]>(
+    () =>
+      (projects ?? []).map((project) => ({
+        id: project.id,
+        label: project.name,
+        searchText: project.description ?? "",
+      })),
+    [projects],
+  );
+  const agentById = useMemo(
+    () => new Map((agents ?? []).map((agent) => [agent.id, agent])),
+    [agents],
+  );
+  const projectById = useMemo(
+    () => new Map((projects ?? []).map((project) => [project.id, project])),
+    [projects],
+  );
+  const currentAssignee = draft.assigneeAgentId ? agentById.get(draft.assigneeAgentId) ?? null : null;
+  const currentProject = draft.projectId ? projectById.get(draft.projectId) ?? null : null;
+
+  if (!selectedCompanyId) {
+    return <EmptyState icon={Repeat} message="Select a company to view routines." />;
+  }
+
+  if (isLoading) {
+    return <PageSkeleton variant="issues-list" />;
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+        <div className="space-y-1">
+          <h1 className="text-2xl font-semibold tracking-tight flex items-center gap-2">
+            Routines
+            <span className="rounded-full bg-amber-100 px-2 py-0.5 text-xs font-medium text-amber-800 dark:bg-amber-900/30 dark:text-amber-400">Beta</span>
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            Recurring work definitions that materialize into auditable execution issues.
+          </p>
+        </div>
+        <Button onClick={() => setComposerOpen(true)}>
+          <Plus className="mr-2 h-4 w-4" />
+          Create routine
+        </Button>
+      </div>
+
+      <Dialog
+        open={composerOpen}
+        onOpenChange={(open) => {
+          if (!createRoutine.isPending) {
+            setComposerOpen(open);
+          }
+        }}
+      >
+        <DialogContent showCloseButton={false} className="max-w-3xl gap-0 overflow-hidden p-0">
+          <div className="flex flex-wrap items-center justify-between gap-3 border-b border-border/60 px-5 py-3">
+            <div>
+              <p className="text-xs font-medium uppercase tracking-[0.2em] text-muted-foreground">New routine</p>
+              <p className="text-sm text-muted-foreground">
+                Define the recurring work first. Trigger setup comes next on the detail page.
+              </p>
+            </div>
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                setComposerOpen(false);
+                setAdvancedOpen(false);
+              }}
+              disabled={createRoutine.isPending}
+            >
+              Cancel
+            </Button>
+          </div>
+
+          <div className="px-5 pt-5 pb-3">
+            <textarea
+              ref={titleInputRef}
+              className="w-full resize-none overflow-hidden bg-transparent text-xl font-semibold outline-none placeholder:text-muted-foreground/50"
+              placeholder="Routine title"
+              rows={1}
+              value={draft.title}
+              onChange={(event) => {
+                setDraft((current) => ({ ...current, title: event.target.value }));
+                autoResizeTextarea(event.target);
+              }}
+              onKeyDown={(event) => {
+                if (event.key === "Enter" && !event.metaKey && !event.ctrlKey && !event.nativeEvent.isComposing) {
+                  event.preventDefault();
+                  descriptionEditorRef.current?.focus();
+                  return;
+                }
+                if (event.key === "Tab" && !event.shiftKey) {
+                  event.preventDefault();
+                  if (draft.assigneeAgentId) {
+                    if (draft.projectId) {
+                      descriptionEditorRef.current?.focus();
+                    } else {
+                      projectSelectorRef.current?.focus();
+                    }
+                  } else {
+                    assigneeSelectorRef.current?.focus();
+                  }
+                }
+              }}
+              autoFocus
+            />
+          </div>
+
+          <div className="px-5 pb-3">
+            <div className="overflow-x-auto overscroll-x-contain">
+              <div className="inline-flex min-w-full flex-wrap items-center gap-2 text-sm text-muted-foreground sm:min-w-max sm:flex-nowrap">
+                <span>For</span>
+                <InlineEntitySelector
+                  ref={assigneeSelectorRef}
+                  value={draft.assigneeAgentId}
+                  options={assigneeOptions}
+                  placeholder="Assignee"
+                  noneLabel="No assignee"
+                  searchPlaceholder="Search assignees..."
+                  emptyMessage="No assignees found."
+                  onChange={(assigneeAgentId) => {
+                    if (assigneeAgentId) trackRecentAssignee(assigneeAgentId);
+                    setDraft((current) => ({ ...current, assigneeAgentId }));
+                  }}
+                  onConfirm={() => {
+                    if (draft.projectId) {
+                      descriptionEditorRef.current?.focus();
+                    } else {
+                      projectSelectorRef.current?.focus();
+                    }
+                  }}
+                  renderTriggerValue={(option) =>
+                    option ? (
+                      currentAssignee ? (
+                        <>
+                          <AgentIcon icon={currentAssignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                          <span className="truncate">{option.label}</span>
+                        </>
+                      ) : (
+                        <span className="truncate">{option.label}</span>
+                      )
+                    ) : (
+                      <span className="text-muted-foreground">Assignee</span>
+                    )
+                  }
+                  renderOption={(option) => {
+                    if (!option.id) return <span className="truncate">{option.label}</span>;
+                    const assignee = agentById.get(option.id);
+                    return (
+                      <>
+                        {assignee ? <AgentIcon icon={assignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" /> : null}
+                        <span className="truncate">{option.label}</span>
+                      </>
+                    );
+                  }}
+                />
+                <span>in</span>
+                <InlineEntitySelector
+                  ref={projectSelectorRef}
+                  value={draft.projectId}
+                  options={projectOptions}
+                  placeholder="Project"
+                  noneLabel="No project"
+                  searchPlaceholder="Search projects..."
+                  emptyMessage="No projects found."
+                  onChange={(projectId) => setDraft((current) => ({ ...current, projectId }))}
+                  onConfirm={() => descriptionEditorRef.current?.focus()}
+                  renderTriggerValue={(option) =>
+                    option && currentProject ? (
+                      <>
+                        <span
+                          className="h-3.5 w-3.5 shrink-0 rounded-sm"
+                          style={{ backgroundColor: currentProject.color ?? "#64748b" }}
+                        />
+                        <span className="truncate">{option.label}</span>
+                      </>
+                    ) : (
+                      <span className="text-muted-foreground">Project</span>
+                    )
+                  }
+                  renderOption={(option) => {
+                    if (!option.id) return <span className="truncate">{option.label}</span>;
+                    const project = projectById.get(option.id);
+                    return (
+                      <>
+                        <span
+                          className="h-3.5 w-3.5 shrink-0 rounded-sm"
+                          style={{ backgroundColor: project?.color ?? "#64748b" }}
+                        />
+                        <span className="truncate">{option.label}</span>
+                      </>
+                    );
+                  }}
+                />
+              </div>
+            </div>
+          </div>
+
+          <div className="border-t border-border/60 px-5 py-4">
+            <MarkdownEditor
+              ref={descriptionEditorRef}
+              value={draft.description}
+              onChange={(description) => setDraft((current) => ({ ...current, description }))}
+              placeholder="Add instructions..."
+              bordered={false}
+              contentClassName="min-h-[160px] text-sm text-muted-foreground"
+              onSubmit={() => {
+                if (!createRoutine.isPending && draft.title.trim() && draft.projectId && draft.assigneeAgentId) {
+                  createRoutine.mutate();
+                }
+              }}
+            />
+          </div>
+
+          <div className="border-t border-border/60 px-5 py-3">
+            <Collapsible open={advancedOpen} onOpenChange={setAdvancedOpen}>
+              <CollapsibleTrigger className="flex w-full items-center justify-between text-left">
+                <div>
+                  <p className="text-sm font-medium">Advanced delivery settings</p>
+                  <p className="text-sm text-muted-foreground">Keep policy controls secondary to the work definition.</p>
+                </div>
+                {advancedOpen ? <ChevronDown className="h-4 w-4 text-muted-foreground" /> : <ChevronRight className="h-4 w-4 text-muted-foreground" />}
+              </CollapsibleTrigger>
+              <CollapsibleContent className="pt-3">
+                <div className="grid gap-4 md:grid-cols-2">
+                  <div className="space-y-2">
+                    <p className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Concurrency</p>
+                    <Select
+                      value={draft.concurrencyPolicy}
+                      onValueChange={(concurrencyPolicy) => setDraft((current) => ({ ...current, concurrencyPolicy }))}
+                    >
+                      <SelectTrigger>
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {concurrencyPolicies.map((value) => (
+                          <SelectItem key={value} value={value}>{value.replaceAll("_", " ")}</SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <p className="text-xs text-muted-foreground">{concurrencyPolicyDescriptions[draft.concurrencyPolicy]}</p>
+                  </div>
+                  <div className="space-y-2">
+                    <p className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Catch-up</p>
+                    <Select
+                      value={draft.catchUpPolicy}
+                      onValueChange={(catchUpPolicy) => setDraft((current) => ({ ...current, catchUpPolicy }))}
+                    >
+                      <SelectTrigger>
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {catchUpPolicies.map((value) => (
+                          <SelectItem key={value} value={value}>{value.replaceAll("_", " ")}</SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <p className="text-xs text-muted-foreground">{catchUpPolicyDescriptions[draft.catchUpPolicy]}</p>
+                  </div>
+                </div>
+              </CollapsibleContent>
+            </Collapsible>
+          </div>
+
+          <div className="flex flex-col gap-3 border-t border-border/60 px-5 py-4 sm:flex-row sm:items-center sm:justify-between">
+            <div className="text-sm text-muted-foreground">
+              After creation, Paperclip takes you straight to trigger setup for schedules, webhooks, or internal runs.
+            </div>
+            <div className="flex flex-col gap-2 sm:items-end">
+              <Button
+                onClick={() => createRoutine.mutate()}
+                disabled={
+                  createRoutine.isPending ||
+                  !draft.title.trim() ||
+                  !draft.projectId ||
+                  !draft.assigneeAgentId
+                }
+              >
+                <Plus className="mr-2 h-4 w-4" />
+                {createRoutine.isPending ? "Creating..." : "Create routine"}
+              </Button>
+              {createRoutine.isError ? (
+                <p className="text-sm text-destructive">
+                  {createRoutine.error instanceof Error ? createRoutine.error.message : "Failed to create routine"}
+                </p>
+              ) : null}
+            </div>
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      {error ? (
+        <Card>
+          <CardContent className="pt-6 text-sm text-destructive">
+            {error instanceof Error ? error.message : "Failed to load routines"}
+          </CardContent>
+        </Card>
+      ) : null}
+
+      <div>
+        {(routines ?? []).length === 0 ? (
+          <div className="py-12">
+            <EmptyState
+              icon={Repeat}
+              message="No routines yet. Use Create routine to define the first recurring workflow."
+            />
+          </div>
+        ) : (
+          <div className="overflow-x-auto">
+            <table className="min-w-full text-sm">
+              <thead>
+                <tr className="text-left text-xs text-muted-foreground border-b border-border">
+                  <th className="px-3 py-2 font-medium">Name</th>
+                  <th className="px-3 py-2 font-medium">Project</th>
+                  <th className="px-3 py-2 font-medium">Agent</th>
+                  <th className="px-3 py-2 font-medium">Last run</th>
+                  <th className="px-3 py-2 font-medium">Enabled</th>
+                  <th className="w-12 px-3 py-2" />
+                </tr>
+              </thead>
+              <tbody>
+                {(routines ?? []).map((routine) => {
+                  const enabled = routine.status === "active";
+                  const isArchived = routine.status === "archived";
+                  const isStatusPending = statusMutationRoutineId === routine.id;
+                  return (
+                    <tr
+                      key={routine.id}
+                      className="align-middle border-b border-border transition-colors hover:bg-accent/50 last:border-b-0 cursor-pointer"
+                      onClick={() => navigate(`/routines/${routine.id}`)}
+                    >
+                      <td className="px-3 py-2.5">
+                        <div className="min-w-[180px]">
+                          <span className="font-medium">
+                            {routine.title}
+                          </span>
+                          {(isArchived || routine.status === "paused") && (
+                            <div className="mt-1 text-xs text-muted-foreground">
+                              {isArchived ? "archived" : "paused"}
+                            </div>
+                          )}
+                        </div>
+                      </td>
+                      <td className="px-3 py-2.5">
+                        {routine.projectId ? (
+                          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                            <span
+                              className="shrink-0 h-3 w-3 rounded-sm"
+                              style={{ backgroundColor: projectById.get(routine.projectId)?.color ?? "#6366f1" }}
+                            />
+                            <span className="truncate">{projectById.get(routine.projectId)?.name ?? "Unknown"}</span>
+                          </div>
+                        ) : (
+                          <span className="text-xs text-muted-foreground">—</span>
+                        )}
+                      </td>
+                      <td className="px-3 py-2.5">
+                        {routine.assigneeAgentId ? (() => {
+                          const agent = agentById.get(routine.assigneeAgentId);
+                          return agent ? (
+                            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                              <AgentIcon icon={agent.icon} className="h-4 w-4 shrink-0" />
+                              <span className="truncate">{agent.name}</span>
+                            </div>
+                          ) : (
+                            <span className="text-xs text-muted-foreground">Unknown</span>
+                          );
+                        })() : (
+                          <span className="text-xs text-muted-foreground">—</span>
+                        )}
+                      </td>
+                      <td className="px-3 py-2.5 text-muted-foreground">
+                        <div>{formatLastRunTimestamp(routine.lastRun?.triggeredAt)}</div>
+                        {routine.lastRun ? (
+                          <div className="mt-1 text-xs">{routine.lastRun.status.replaceAll("_", " ")}</div>
+                        ) : null}
+                      </td>
+                      <td className="px-3 py-2.5" onClick={(e) => e.stopPropagation()}>
+                        <div className="flex items-center gap-3">
+                          <button
+                            type="button"
+                            role="switch"
+                            data-slot="toggle"
+                            aria-checked={enabled}
+                            aria-label={enabled ? `Disable ${routine.title}` : `Enable ${routine.title}`}
+                            disabled={isStatusPending || isArchived}
+                            className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors ${
+                              enabled ? "bg-foreground" : "bg-muted"
+                            } ${isStatusPending || isArchived ? "cursor-not-allowed opacity-50" : ""}`}
+                            onClick={() =>
+                              updateRoutineStatus.mutate({
+                                id: routine.id,
+                                status: nextRoutineStatus(routine.status, !enabled),
+                              })
+                            }
+                          >
+                            <span
+                              className={`inline-block h-5 w-5 rounded-full bg-background shadow-sm transition-transform ${
+                                enabled ? "translate-x-5" : "translate-x-0.5"
+                              }`}
+                            />
+                          </button>
+                          <span className="text-xs text-muted-foreground">
+                            {isArchived ? "Archived" : enabled ? "On" : "Off"}
+                          </span>
+                        </div>
+                      </td>
+                      <td className="px-3 py-2.5 text-right" onClick={(e) => e.stopPropagation()}>
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <Button variant="ghost" size="icon-sm" aria-label={`More actions for ${routine.title}`}>
+                              <MoreHorizontal className="h-4 w-4" />
+                            </Button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent align="end">
+                            <DropdownMenuItem onClick={() => navigate(`/routines/${routine.id}`)}>
+                              Edit
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                              disabled={runningRoutineId === routine.id || isArchived}
+                              onClick={() => runRoutine.mutate(routine.id)}
+                            >
+                              {runningRoutineId === routine.id ? "Running..." : "Run now"}
+                            </DropdownMenuItem>
+                            <DropdownMenuSeparator />
+                            <DropdownMenuItem
+                              onClick={() =>
+                                updateRoutineStatus.mutate({
+                                  id: routine.id,
+                                  status: enabled ? "paused" : "active",
+                                })
+                              }
+                              disabled={isStatusPending || isArchived}
+                            >
+                              {enabled ? "Pause" : "Enable"}
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                              onClick={() =>
+                                updateRoutineStatus.mutate({
+                                  id: routine.id,
+                                  status: routine.status === "archived" ? "active" : "archived",
+                                })
+                              }
+                              disabled={isStatusPending}
+                            >
+                              {routine.status === "archived" ? "Restore" : "Archive"}
+                            </DropdownMenuItem>
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

paperclip-reference/ui/src/pages/RunTranscriptUxLab.tsx

@@ -0,0 +1,334 @@
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { cn, formatDateTime } from "../lib/utils";
+import { Identity } from "../components/Identity";
+import { StatusBadge } from "../components/StatusBadge";
+import { RunTranscriptView, type TranscriptDensity, type TranscriptMode } from "../components/transcript/RunTranscriptView";
+import { runTranscriptFixtureEntries, runTranscriptFixtureMeta } from "../fixtures/runTranscriptFixtures";
+import { ExternalLink, FlaskConical, LayoutPanelLeft, MonitorCog, PanelsTopLeft, RadioTower } from "lucide-react";
+
+type SurfaceId = "detail" | "live" | "dashboard";
+
+const surfaceOptions: Array<{
+  id: SurfaceId;
+  label: string;
+  eyebrow: string;
+  description: string;
+  icon: typeof LayoutPanelLeft;
+}> = [
+  {
+    id: "detail",
+    label: "Run Detail",
+    eyebrow: "Full transcript",
+    description: "The long-form run page with the `Nice | Raw` toggle and the most inspectable transcript view.",
+    icon: MonitorCog,
+  },
+  {
+    id: "live",
+    label: "Issue Widget",
+    eyebrow: "Live stream",
+    description: "The issue-detail live run widget, optimized for following an active run without leaving the task page.",
+    icon: RadioTower,
+  },
+  {
+    id: "dashboard",
+    label: "Dashboard Card",
+    eyebrow: "Dense card",
+    description: "The active-agents dashboard card, tuned for compact scanning while keeping the same transcript language.",
+    icon: PanelsTopLeft,
+  },
+];
+
+function previewEntries(surface: SurfaceId) {
+  if (surface === "dashboard") {
+    return runTranscriptFixtureEntries.slice(-9);
+  }
+  if (surface === "live") {
+    return runTranscriptFixtureEntries.slice(-14);
+  }
+  return runTranscriptFixtureEntries;
+}
+
+function RunDetailPreview({
+  mode,
+  streaming,
+  density,
+}: {
+  mode: TranscriptMode;
+  streaming: boolean;
+  density: TranscriptDensity;
+}) {
+  return (
+    <div className="overflow-hidden rounded-xl border border-border/70 bg-background/80 shadow-[0_24px_60px_rgba(15,23,42,0.08)]">
+      <div className="border-b border-border/60 bg-background/90 px-5 py-4">
+        <div className="flex flex-wrap items-center gap-2">
+          <Badge variant="outline" className="uppercase tracking-[0.18em] text-[10px]">
+            Run Detail
+          </Badge>
+          <StatusBadge status={streaming ? "running" : "succeeded"} />
+          <span className="text-xs text-muted-foreground">
+            {formatDateTime(runTranscriptFixtureMeta.startedAt)}
+          </span>
+        </div>
+        <div className="mt-2 text-sm font-medium">
+          Transcript ({runTranscriptFixtureEntries.length})
+        </div>
+      </div>
+      <div className="max-h-[720px] overflow-y-auto bg-[radial-gradient(circle_at_top_left,rgba(8,145,178,0.08),transparent_36%),radial-gradient(circle_at_bottom_right,rgba(245,158,11,0.10),transparent_28%)] p-5">
+        <RunTranscriptView
+          entries={runTranscriptFixtureEntries}
+          mode={mode}
+          density={density}
+          streaming={streaming}
+        />
+      </div>
+    </div>
+  );
+}
+
+function LiveWidgetPreview({
+  streaming,
+  mode,
+  density,
+}: {
+  streaming: boolean;
+  mode: TranscriptMode;
+  density: TranscriptDensity;
+}) {
+  return (
+    <div className="overflow-hidden rounded-xl border border-cyan-500/25 bg-background/85 shadow-[0_20px_50px_rgba(6,182,212,0.10)]">
+      <div className="border-b border-border/60 bg-cyan-500/[0.05] px-5 py-4">
+        <div className="text-xs font-semibold uppercase tracking-[0.2em] text-cyan-700 dark:text-cyan-300">
+          Live Runs
+        </div>
+        <div className="mt-1 text-xs text-muted-foreground">
+          Compact live transcript stream for the issue detail page.
+        </div>
+      </div>
+      <div className="px-5 py-4">
+        <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+          <div className="min-w-0">
+            <Identity name={runTranscriptFixtureMeta.agentName} size="sm" />
+            <div className="mt-2 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+              <span className="rounded-full border border-border/70 bg-background/70 px-2 py-1 font-mono">
+                {runTranscriptFixtureMeta.sourceRunId.slice(0, 8)}
+              </span>
+              <StatusBadge status={streaming ? "running" : "succeeded"} />
+              <span>{formatDateTime(runTranscriptFixtureMeta.startedAt)}</span>
+            </div>
+          </div>
+          <span className="inline-flex items-center gap-1 rounded-full border border-border/70 bg-background/70 px-2.5 py-1 text-[11px] text-muted-foreground">
+            Open run
+            <ExternalLink className="h-3 w-3" />
+          </span>
+        </div>
+        <div className="max-h-[460px] overflow-y-auto pr-1">
+          <RunTranscriptView
+            entries={previewEntries("live")}
+            mode={mode}
+            density={density}
+            limit={density === "compact" ? 10 : 12}
+            streaming={streaming}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function DashboardPreview({
+  streaming,
+  mode,
+  density,
+}: {
+  streaming: boolean;
+  mode: TranscriptMode;
+  density: TranscriptDensity;
+}) {
+  return (
+    <div className="max-w-md">
+      <div className={cn(
+        "flex h-[320px] flex-col overflow-hidden rounded-xl border shadow-[0_20px_40px_rgba(15,23,42,0.10)]",
+        streaming
+          ? "border-cyan-500/25 bg-cyan-500/[0.04]"
+          : "border-border bg-background/75",
+      )}>
+        <div className="border-b border-border/60 px-4 py-4">
+          <div className="flex items-start justify-between gap-3">
+            <div className="min-w-0">
+              <div className="flex items-center gap-2">
+                <span className={cn(
+                  "inline-flex h-2.5 w-2.5 rounded-full",
+                  streaming ? "bg-cyan-500 shadow-[0_0_0_6px_rgba(34,211,238,0.12)]" : "bg-muted-foreground/35",
+                )} />
+                <Identity name={runTranscriptFixtureMeta.agentName} size="sm" />
+              </div>
+              <div className="mt-2 text-[11px] text-muted-foreground">
+                {streaming ? "Live now" : "Finished 2m ago"}
+              </div>
+            </div>
+            <span className="rounded-full border border-border/70 bg-background/70 px-2 py-1 text-[10px] text-muted-foreground">
+              <ExternalLink className="h-2.5 w-2.5" />
+            </span>
+          </div>
+          <div className="mt-3 rounded-lg border border-border/60 bg-background/60 px-3 py-2 text-xs text-cyan-700 dark:text-cyan-300">
+            {runTranscriptFixtureMeta.issueIdentifier} - {runTranscriptFixtureMeta.issueTitle}
+          </div>
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto p-4">
+          <RunTranscriptView
+            entries={previewEntries("dashboard")}
+            mode={mode}
+            density={density}
+            limit={density === "compact" ? 6 : 8}
+            streaming={streaming}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function RunTranscriptUxLab() {
+  const [selectedSurface, setSelectedSurface] = useState<SurfaceId>("detail");
+  const [detailMode, setDetailMode] = useState<TranscriptMode>("nice");
+  const [streaming, setStreaming] = useState(true);
+  const [density, setDensity] = useState<TranscriptDensity>("comfortable");
+
+  const selected = surfaceOptions.find((option) => option.id === selectedSurface) ?? surfaceOptions[0];
+
+  return (
+    <div className="space-y-6">
+      <div className="overflow-hidden rounded-2xl border border-border/70 bg-[linear-gradient(135deg,rgba(8,145,178,0.08),transparent_28%),linear-gradient(180deg,rgba(245,158,11,0.08),transparent_40%),var(--background)] shadow-[0_28px_70px_rgba(15,23,42,0.10)]">
+        <div className="grid gap-6 lg:grid-cols-[260px_minmax(0,1fr)]">
+          <aside className="border-b border-border/60 bg-background/75 p-5 lg:border-b-0 lg:border-r">
+            <div className="mb-5">
+              <div className="inline-flex items-center gap-2 rounded-full border border-cyan-500/25 bg-cyan-500/[0.08] px-3 py-1 text-[10px] font-semibold uppercase tracking-[0.24em] text-cyan-700 dark:text-cyan-300">
+                <FlaskConical className="h-3.5 w-3.5" />
+                UX Lab
+              </div>
+              <h1 className="mt-4 text-2xl font-semibold tracking-tight">Run Transcript Fixtures</h1>
+              <p className="mt-2 text-sm text-muted-foreground">
+                Built from a real Paperclip development run, then sanitized so no secrets, local paths, or environment details survive into the fixture.
+              </p>
+            </div>
+
+            <div className="space-y-2">
+              {surfaceOptions.map((option) => {
+                const Icon = option.icon;
+                return (
+                  <button
+                    key={option.id}
+                    type="button"
+                    onClick={() => setSelectedSurface(option.id)}
+                    className={cn(
+                      "w-full rounded-xl border px-4 py-3 text-left transition-all",
+                      selectedSurface === option.id
+                        ? "border-cyan-500/35 bg-cyan-500/[0.10] shadow-[0_12px_24px_rgba(6,182,212,0.12)]"
+                        : "border-border/70 bg-background/70 hover:border-cyan-500/20 hover:bg-cyan-500/[0.04]",
+                    )}
+                  >
+                    <div className="flex items-start gap-3">
+                      <span className="rounded-lg border border-current/15 p-2 text-cyan-700 dark:text-cyan-300">
+                        <Icon className="h-4 w-4" />
+                      </span>
+                      <span className="min-w-0">
+                        <span className="block text-[10px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                          {option.eyebrow}
+                        </span>
+                        <span className="mt-1 block text-sm font-medium">{option.label}</span>
+                        <span className="mt-1 block text-xs text-muted-foreground">
+                          {option.description}
+                        </span>
+                      </span>
+                    </div>
+                  </button>
+                );
+              })}
+            </div>
+          </aside>
+
+          <main className="min-w-0 p-5">
+            <div className="mb-5 flex flex-col gap-4 xl:flex-row xl:items-end xl:justify-between">
+              <div>
+                <div className="text-[11px] font-semibold uppercase tracking-[0.22em] text-muted-foreground">
+                  {selected.eyebrow}
+                </div>
+                <h2 className="mt-1 text-2xl font-semibold">{selected.label}</h2>
+                <p className="mt-2 max-w-2xl text-sm text-muted-foreground">
+                  {selected.description}
+                </p>
+              </div>
+
+              <div className="flex flex-wrap items-center gap-2">
+                <Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
+                  Source run {runTranscriptFixtureMeta.sourceRunId.slice(0, 8)}
+                </Badge>
+                <Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
+                  {runTranscriptFixtureMeta.issueIdentifier}
+                </Badge>
+              </div>
+            </div>
+
+            <div className="mb-5 flex flex-wrap items-center gap-2">
+              <span className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                Controls
+              </span>
+              <div className="inline-flex rounded-full border border-border/70 bg-background/80 p-1">
+                {(["nice", "raw"] as const).map((mode) => (
+                  <button
+                    key={mode}
+                    type="button"
+                    className={cn(
+                      "rounded-full px-3 py-1 text-xs font-medium capitalize transition-colors",
+                      detailMode === mode ? "bg-accent text-foreground" : "text-muted-foreground hover:text-foreground",
+                    )}
+                    onClick={() => setDetailMode(mode)}
+                  >
+                    {mode}
+                  </button>
+                ))}
+              </div>
+              <div className="inline-flex rounded-full border border-border/70 bg-background/80 p-1">
+                {(["comfortable", "compact"] as const).map((nextDensity) => (
+                  <button
+                    key={nextDensity}
+                    type="button"
+                    className={cn(
+                      "rounded-full px-3 py-1 text-xs font-medium capitalize transition-colors",
+                      density === nextDensity ? "bg-accent text-foreground" : "text-muted-foreground hover:text-foreground",
+                    )}
+                    onClick={() => setDensity(nextDensity)}
+                  >
+                    {nextDensity}
+                  </button>
+                ))}
+              </div>
+              <Button
+                variant="outline"
+                size="sm"
+                className="rounded-full"
+                onClick={() => setStreaming((value) => !value)}
+              >
+                {streaming ? "Show settled state" : "Show streaming state"}
+              </Button>
+            </div>
+
+            {selectedSurface === "detail" ? (
+              <div className={cn(density === "compact" && "max-w-5xl")}>
+                <RunDetailPreview mode={detailMode} streaming={streaming} density={density} />
+              </div>
+            ) : selectedSurface === "live" ? (
+              <div className={cn(density === "compact" && "max-w-4xl")}>
+                <LiveWidgetPreview streaming={streaming} mode={detailMode} density={density} />
+              </div>
+            ) : (
+              <DashboardPreview streaming={streaming} mode={detailMode} density={density} />
+            )}
+          </main>
+        </div>
+      </div>
+    </div>
+  );
+}