Upload folder using huggingface_hub

.claude/skills/design-guide/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: design-guide
+description: >
+  Paperclip UI design system guide for building consistent, reusable frontend
+  components. Use when creating new UI components, modifying existing ones,
+  adding pages or features to the frontend, styling UI elements, or when you
+  need to understand the design language and conventions. Covers: component
+  creation, design tokens, typography, status/priority systems, composition
+  patterns, and the /design-guide showcase page. Always use this skill
+  alongside the frontend-design skill (for visual quality) and the
+  web-design-guidelines skill (for web best practices).
+---
+
+# Paperclip Design Guide
+
+Paperclip's UI is a professional-grade control plane — dense, keyboard-driven, dark-themed by default. Every pixel earns its place.
+
+**Always use with:** `frontend-design` (visual polish) and `web-design-guidelines` (web best practices).
+
+---
+
+## 1. Design Principles
+
+- **Dense but scannable.** Maximum information without clicks to reveal. Whitespace separates, not pads.
+- **Keyboard-first.** Global shortcuts (Cmd+K, C, [, ]). Power users rarely touch the mouse.
+- **Contextual, not modal.** Inline editing over dialog boxes. Dropdowns over page navigations.
+- **Dark theme default.** Neutral grays (OKLCH), not pure black. Accent colors for status/priority only. Text is the primary visual element.
+- **Component-driven.** Prefer reusable components that capture style conventions. Build at the right abstraction — not too granular, not too monolithic.
+
+---
+
+## 2. Tech Stack
+
+- **React 19** + **TypeScript** + **Vite**
+- **Tailwind CSS v4** with CSS variables (OKLCH color space)
+- **shadcn/ui** (new-york style, neutral base, CSS variables enabled)
+- **Radix UI** primitives (accessibility, focus management)
+- **Lucide React** icons (16px nav, 14px inline)
+- **class-variance-authority** (CVA) for component variants
+- **clsx + tailwind-merge** via `cn()` utility
+
+Config: `ui/components.json` (aliases: `@/components`, `@/components/ui`, `@/lib`, `@/hooks`)
+
+---
+
+## 3. Design Tokens
+
+All tokens defined as CSS variables in `ui/src/index.css`. Both light and dark themes use OKLCH.
+
+### Colors
+
+Use semantic token names, never raw color values:
+
+| Token | Usage |
+|-------|-------|
+| `--background` / `--foreground` | Page background and primary text |
+| `--card` / `--card-foreground` | Card surfaces |
+| `--primary` / `--primary-foreground` | Primary actions, emphasis |
+| `--secondary` / `--secondary-foreground` | Secondary surfaces |
+| `--muted` / `--muted-foreground` | Subdued text, labels |
+| `--accent` / `--accent-foreground` | Hover states, active nav items |
+| `--destructive` | Destructive actions |
+| `--border` | All borders |
+| `--ring` | Focus rings |
+| `--sidebar-*` | Sidebar-specific variants |
+| `--chart-1` through `--chart-5` | Data visualization |
+
+### Radius
+
+Single `--radius` variable (0.625rem) with derived sizes:
+
+- `rounded-sm` — small inputs, pills
+- `rounded-md` — buttons, inputs, small components
+- `rounded-lg` — cards, dialogs
+- `rounded-xl` — card containers, large components
+- `rounded-full` — badges, avatars, status dots
+
+### Shadows
+
+Minimal shadows: `shadow-xs` (outline buttons), `shadow-sm` (cards). No heavy shadows.
+
+---
+
+## 4. Typography Scale
+
+Use these exact patterns — do not invent new ones:
+
+| Pattern | Classes | Usage |
+|---------|---------|-------|
+| Page title | `text-xl font-bold` | Top of pages |
+| Section title | `text-lg font-semibold` | Major sections |
+| Section heading | `text-sm font-semibold text-muted-foreground uppercase tracking-wide` | Section headers in design guide, sidebar |
+| Card title | `text-sm font-medium` or `text-sm font-semibold` | Card headers, list item titles |
+| Body | `text-sm` | Default body text |
+| Muted | `text-sm text-muted-foreground` | Descriptions, secondary text |
+| Tiny label | `text-xs text-muted-foreground` | Metadata, timestamps, property labels |
+| Mono identifier | `text-xs font-mono text-muted-foreground` | Issue keys (PAP-001), CSS vars |
+| Large stat | `text-2xl font-bold` | Dashboard metric values |
+| Code/log | `font-mono text-xs` | Log output, code snippets |
+
+---
+
+## 5. Status & Priority Systems
+
+### Status Colors (consistent across all entities)
+
+Defined in `StatusBadge.tsx` and `StatusIcon.tsx`:
+
+| Status | Color | Entity types |
+|--------|-------|-------------|
+| active, achieved, completed, succeeded, approved, done | Green shades | Agents, goals, issues, approvals |
+| running | Cyan | Agents |
+| paused | Orange | Agents |
+| idle, pending | Yellow | Agents, approvals |
+| failed, error, rejected, blocked | Red shades | Runs, agents, approvals, issues |
+| archived, planned, backlog, cancelled | Neutral gray | Various |
+| todo | Blue | Issues |
+| in_progress | Indigo | Issues |
+| in_review | Violet | Issues |
+
+### Priority Icons
+
+Defined in `PriorityIcon.tsx`: critical (red/AlertTriangle), high (orange/ArrowUp), medium (yellow/Minus), low (blue/ArrowDown).
+
+### Agent Status Dots
+
+Inline colored dots: running (cyan, animate-pulse), active (green), paused (yellow), error (red), offline (neutral).
+
+---
+
+## 6. Component Hierarchy
+
+Three tiers:
+
+1. **shadcn/ui primitives** (`ui/src/components/ui/`) — Button, Card, Input, Badge, Dialog, Tabs, etc. Do not modify these directly; extend via composition.
+2. **Custom composites** (`ui/src/components/`) — StatusBadge, EntityRow, MetricCard, etc. These capture Paperclip-specific design language.
+3. **Page components** (`ui/src/pages/`) — Compose primitives and composites into full views.
+
+**See [references/component-index.md](references/component-index.md) for the complete component inventory with usage guidance.**
+
+### When to Create a New Component
+
+Create a reusable component when:
+- The same visual pattern appears in 2+ places
+- The pattern has interactive behavior (status changing, inline editing)
+- The pattern encodes domain logic (status colors, priority icons)
+
+Do NOT create a component for:
+- One-off layouts specific to a single page
+- Simple className combinations (use Tailwind directly)
+- Thin wrappers that add no semantic value
+
+---
+
+## 7. Composition Patterns
+
+These patterns describe how components work together. They may not be their own component, but they must be used consistently across the app.
+
+### Entity Row with Status + Priority
+
+The standard list item for issues and similar entities:
+
+```tsx
+<EntityRow
+  leading={<><StatusIcon status="in_progress" /><PriorityIcon priority="high" /></>}
+  identifier="PAP-001"
+  title="Implement authentication flow"
+  subtitle="Assigned to Agent Alpha"
+  trailing={<StatusBadge status="in_progress" />}
+  onClick={() => {}}
+/>
+```
+
+Leading slot always: StatusIcon first, then PriorityIcon. Trailing slot: StatusBadge or timestamp.
+
+### Grouped List
+
+Issues grouped by status header + entity rows:
+
+```tsx
+<div className="flex items-center gap-2 px-4 py-2 bg-muted/50 rounded-t-md">
+  <StatusIcon status="in_progress" />
+  <span className="text-sm font-medium">In Progress</span>
+  <span className="text-xs text-muted-foreground ml-1">2</span>
+</div>
+<div className="border border-border rounded-b-md">
+  <EntityRow ... />
+  <EntityRow ... />
+</div>
+```
+
+### Property Row
+
+Key-value pairs in properties panels:
+
+```tsx
+<div className="flex items-center justify-between py-1.5">
+  <span className="text-xs text-muted-foreground">Status</span>
+  <StatusBadge status="active" />
+</div>
+```
+
+Label is always `text-xs text-muted-foreground`, value on the right. Wrap in a container with `space-y-1`.
+
+### Metric Card Grid
+
+Dashboard metrics in a responsive grid:
+
+```tsx
+<div className="grid md:grid-cols-2 xl:grid-cols-4 gap-4">
+  <MetricCard icon={Bot} value={12} label="Active Agents" description="+3 this week" />
+  ...
+</div>
+```
+
+### Progress Bar (Budget)
+
+Color by threshold: green (<60%), yellow (60-85%), red (>85%):
+
+```tsx
+<div className="w-full h-2 bg-muted rounded-full overflow-hidden">
+  <div className="h-full rounded-full bg-green-400" style={{ width: `${pct}%` }} />
+</div>
+```
+
+### Comment Thread
+
+Author header (name + timestamp) then body, in bordered cards with `space-y-3`. Add comment textarea + button below.
+
+### Cost Table
+
+Standard `<table>` with `text-xs`, header row with `bg-accent/20`, `font-mono` for numeric values.
+
+### Log Viewer
+
+`bg-neutral-950 rounded-lg p-3 font-mono text-xs` container. Color lines by level: default (foreground), WARN (yellow-400), ERROR (red-400), SYS (blue-300). Include live indicator dot when streaming.
+
+---
+
+## 8. Interactive Patterns
+
+### Hover States
+
+- Entity rows: `hover:bg-accent/50`
+- Nav items: `hover:bg-accent/50 hover:text-accent-foreground`
+- Active nav: `bg-accent text-accent-foreground`
+
+### Focus
+
+`focus-visible:ring-ring focus-visible:ring-[3px]` — standard Tailwind focus-visible ring.
+
+### Disabled
+
+`disabled:opacity-50 disabled:pointer-events-none`
+
+### Inline Editing
+
+Use `InlineEditor` component — click text to edit, Enter saves, Escape cancels.
+
+### Popover Selectors
+
+StatusIcon and PriorityIcon use Radix Popover for inline selection. Follow this pattern for any clickable property that opens a picker.
+
+---
+
+## 9. Layout System
+
+Three-zone layout defined in `Layout.tsx`:
+
+```
+┌──────────┬──────────────────────────────┬──────────────────────┐
+│ Sidebar  │  Breadcrumb bar              │                      │
+│ (w-60)   ├──────────────────────────────┤  Properties panel    │
+│          │  Main content (flex-1)       │  (w-80, optional)    │
+└──────────┴──────────────────────────────┴──────────────────────┘
+```
+
+- Sidebar: `w-60`, collapsible, contains CompanySwitcher + SidebarSections
+- Properties panel: `w-80`, shown on detail views, hidden on lists
+- Main content: scrollable, `flex-1`
+
+---
+
+## 10. The /design-guide Page
+
+**Location:** `ui/src/pages/DesignGuide.tsx`
+**Route:** `/design-guide`
+
+This is the living showcase of every component and pattern in the app. It is the source of truth for how things look.
+
+### Rules
+
+1. **When you add a new reusable component, you MUST add it to the design guide page.** Show all variants, sizes, and states.
+2. **When you modify an existing component's API, update its design guide section.**
+3. **When you add a new composition pattern, add a section demonstrating it.**
+4. Follow the existing structure: `<Section title="...">` wrapper with `<SubSection>` for grouping.
+5. Keep sections ordered logically: foundational (colors, typography) first, then primitives, then composites, then patterns.
+
+### Adding a New Section
+
+```tsx
+<Section title="My New Component">
+  <SubSection title="Variants">
+    {/* Show all variants */}
+  </SubSection>
+  <SubSection title="Sizes">
+    {/* Show all sizes */}
+  </SubSection>
+  <SubSection title="States">
+    {/* Show interactive/disabled states */}
+  </SubSection>
+</Section>
+```
+
+---
+
+## 11. Component Index
+
+**See [references/component-index.md](references/component-index.md) for the full component inventory.**
+
+When you create a new reusable component:
+1. Add it to the component index reference file
+2. Add it to the /design-guide page
+3. Follow existing naming and file conventions
+
+---
+
+## 12. File Conventions
+
+- **shadcn primitives:** `ui/src/components/ui/{component}.tsx` — lowercase, kebab-case
+- **Custom components:** `ui/src/components/{ComponentName}.tsx` — PascalCase
+- **Pages:** `ui/src/pages/{PageName}.tsx` — PascalCase
+- **Utilities:** `ui/src/lib/{name}.ts`
+- **Hooks:** `ui/src/hooks/{useName}.ts`
+- **API modules:** `ui/src/api/{entity}.ts`
+- **Context providers:** `ui/src/context/{Name}Context.tsx`
+
+All components use `cn()` from `@/lib/utils` for className merging. All components use CVA for variant definitions when they have multiple visual variants.
+
+---
+
+## 13. Common Mistakes to Avoid
+
+- Using raw hex/rgb colors instead of CSS variable tokens
+- Creating ad-hoc typography styles instead of using the established scale
+- Hardcoding status colors instead of using StatusBadge/StatusIcon
+- Building one-off styled elements when a reusable component exists
+- Adding components without updating the design guide page
+- Using `shadow-md` or heavier — keep shadows minimal (xs, sm only)
+- Using `rounded-2xl` or larger — max is `rounded-xl` (except `rounded-full` for pills)
+- Forgetting dark mode — always use semantic tokens, never hardcode light/dark values

.claude/skills/design-guide/references/component-index.md

@@ -0,0 +1,323 @@
+# Paperclip Component Index
+
+Complete inventory of all UI components. Update this file when adding new reusable components.
+
+---
+
+## Table of Contents
+
+1. [shadcn/ui Primitives](#shadcnui-primitives)
+2. [Custom Components](#custom-components)
+3. [Layout Components](#layout-components)
+4. [Dialog & Form Components](#dialog--form-components)
+5. [Property Panel Components](#property-panel-components)
+6. [Agent Configuration](#agent-configuration)
+7. [Utilities & Hooks](#utilities--hooks)
+
+---
+
+## shadcn/ui Primitives
+
+Location: `ui/src/components/ui/`
+
+These are shadcn/ui base components. Do not modify directly — extend via composition.
+
+| Component | File | Key Props | Notes |
+|-----------|------|-----------|-------|
+| Button | `button.tsx` | `variant` (default, secondary, outline, ghost, destructive, link), `size` (xs, sm, default, lg, icon, icon-xs, icon-sm, icon-lg) | Primary interactive element. Uses CVA. |
+| Card | `card.tsx` | CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter | Compound component. `py-6` default padding. |
+| Input | `input.tsx` | `disabled` | Standard text input. |
+| Badge | `badge.tsx` | `variant` (default, secondary, outline, destructive, ghost) | Generic label/tag. For status, use StatusBadge instead. |
+| Label | `label.tsx` | — | Form label, wraps Radix Label. |
+| Select | `select.tsx` | Trigger, Content, Item, etc. | Radix-based dropdown select. |
+| Separator | `separator.tsx` | `orientation` (horizontal, vertical) | Divider line. |
+| Checkbox | `checkbox.tsx` | `checked`, `onCheckedChange` | Radix checkbox with indicator. |
+| Textarea | `textarea.tsx` | Standard textarea props | Multi-line input. |
+| Avatar | `avatar.tsx` | `size` (sm, default, lg). Includes AvatarGroup, AvatarGroupCount | Image or fallback initials. |
+| Breadcrumb | `breadcrumb.tsx` | BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator, BreadcrumbPage | Navigation breadcrumbs. |
+| Command | `command.tsx` | CommandInput, CommandList, CommandGroup, CommandItem | Command palette / search. Based on cmdk. |
+| Dialog | `dialog.tsx` | DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter | Modal overlay. |
+| DropdownMenu | `dropdown-menu.tsx` | Trigger, Content, Item, Separator, etc. | Context/action menus. |
+| Popover | `popover.tsx` | PopoverTrigger, PopoverContent | Floating content panel. |
+| Tabs | `tabs.tsx` | `variant` (pill, line). TabsList, TabsTrigger, TabsContent | Tabbed navigation. Pill = default, line = underline style. |
+| Tooltip | `tooltip.tsx` | TooltipTrigger, TooltipContent | Hover tooltips. App is wrapped in TooltipProvider. |
+| ScrollArea | `scroll-area.tsx` | — | Custom scrollable container. |
+| Collapsible | `collapsible.tsx` | CollapsibleTrigger, CollapsibleContent | Expand/collapse sections. |
+| Skeleton | `skeleton.tsx` | className for sizing | Loading placeholder with shimmer. |
+| Sheet | `sheet.tsx` | SheetTrigger, SheetContent, SheetHeader, etc. | Side panel overlay. |
+
+---
+
+## Custom Components
+
+Location: `ui/src/components/`
+
+### StatusBadge
+
+**File:** `StatusBadge.tsx`
+**Props:** `status: string`
+**Usage:** Colored pill showing entity status. Supports 20+ statuses with mapped colors.
+
+```tsx
+<StatusBadge status="in_progress" />
+```
+
+Use for displaying status in properties panels, entity rows, and list views. Never hardcode status colors — always use this component.
+
+### StatusIcon
+
+**File:** `StatusIcon.tsx`
+**Props:** `status: string`, `onChange?: (status: string) => void`
+**Usage:** Circle icon representing issue status. When `onChange` provided, opens a popover picker.
+
+```tsx
+<StatusIcon status="todo" onChange={setStatus} />
+```
+
+Supports: backlog, todo, in_progress, in_review, done, cancelled, blocked. Use in entity row leading slots and grouped list headers.
+
+### PriorityIcon
+
+**File:** `PriorityIcon.tsx`
+**Props:** `priority: string`, `onChange?: (priority: string) => void`
+**Usage:** Priority indicator icon. Interactive when `onChange` provided.
+
+```tsx
+<PriorityIcon priority="high" onChange={setPriority} />
+```
+
+Supports: critical, high, medium, low. Use alongside StatusIcon in entity row leading slots.
+
+### EntityRow
+
+**File:** `EntityRow.tsx`
+**Props:** `leading`, `identifier`, `title`, `subtitle?`, `trailing?`, `onClick?`, `selected?`
+**Usage:** Standard list row for issues, agents, projects. Supports hover highlight and selected state.
+
+```tsx
+<EntityRow
+  leading={<><StatusIcon status="todo" /><PriorityIcon priority="medium" /></>}
+  identifier="PAP-003"
+  title="Write API documentation"
+  trailing={<StatusBadge status="todo" />}
+  onClick={() => navigate(`/issues/${id}`)}
+/>
+```
+
+Wrap multiple EntityRows in a `border border-border rounded-md` container.
+
+### MetricCard
+
+**File:** `MetricCard.tsx`
+**Props:** `icon: LucideIcon`, `value: string | number`, `label: string`, `description?: string`
+**Usage:** Dashboard stat card with icon, large value, label, and optional description.
+
+```tsx
+<MetricCard icon={Bot} value={12} label="Active Agents" description="+3 this week" />
+```
+
+Always use in a responsive grid: `grid md:grid-cols-2 xl:grid-cols-4 gap-4`.
+
+### EmptyState
+
+**File:** `EmptyState.tsx`
+**Props:** `icon: LucideIcon`, `message: string`, `action?: string`, `onAction?: () => void`
+**Usage:** Empty list placeholder with icon, message, and optional CTA button.
+
+```tsx
+<EmptyState icon={Inbox} message="No items yet." action="Create Item" onAction={handleCreate} />
+```
+
+### FilterBar
+
+**File:** `FilterBar.tsx`
+**Props:** `filters: FilterValue[]`, `onRemove: (key) => void`, `onClear: () => void`
+**Type:** `FilterValue = { key: string; label: string; value: string }`
+**Usage:** Filter chip display with remove buttons and clear all.
+
+```tsx
+<FilterBar filters={filters} onRemove={handleRemove} onClear={() => setFilters([])} />
+```
+
+### Identity
+
+**File:** `Identity.tsx`
+**Props:** `name: string`, `avatarUrl?: string`, `initials?: string`, `size?: "sm" | "default" | "lg"`
+**Usage:** Avatar + name display for users and agents. Derives initials from name automatically. Three sizes matching Avatar sizes.
+
+```tsx
+<Identity name="Agent Alpha" size="sm" />
+<Identity name="CEO Agent" />
+<Identity name="Backend Service" size="lg" avatarUrl="/img/bot.png" />
+```
+
+Use in property rows, comment headers, assignee displays, and anywhere a user/agent reference is shown.
+
+### InlineEditor
+
+**File:** `InlineEditor.tsx`
+**Props:** `value: string`, `onSave: (val: string) => void`, `as?: string`, `className?: string`
+**Usage:** Click-to-edit text. Renders as display text, clicking enters edit mode. Enter saves, Escape cancels.
+
+```tsx
+<InlineEditor value={title} onSave={updateTitle} as="h2" className="text-xl font-bold" />
+```
+
+### PageSkeleton
+
+**File:** `PageSkeleton.tsx`
+**Props:** `variant: "list" | "detail"`
+**Usage:** Full-page loading skeleton matching list or detail layout.
+
+```tsx
+<PageSkeleton variant="list" />
+```
+
+### CommentThread
+
+**File:** `CommentThread.tsx`
+**Usage:** Comment list with add-comment form. Used on issue and entity detail views.
+
+### GoalTree
+
+**File:** `GoalTree.tsx`
+**Usage:** Hierarchical goal tree with expand/collapse. Used on the goals page.
+
+### CompanySwitcher
+
+**File:** `CompanySwitcher.tsx`
+**Usage:** Company selector dropdown in sidebar header.
+
+---
+
+## Layout Components
+
+### Layout
+
+**File:** `Layout.tsx`
+**Usage:** Main app shell. Three-zone layout: Sidebar + Main content + Properties panel. Wraps all routes.
+
+### Sidebar
+
+**File:** `Sidebar.tsx`
+**Usage:** Left navigation sidebar (`w-60`). Contains CompanySwitcher, search button, new issue button, and SidebarSections.
+
+### SidebarSection
+
+**File:** `SidebarSection.tsx`
+**Usage:** Collapsible sidebar group with header label and chevron toggle.
+
+### SidebarNavItem
+
+**File:** `SidebarNavItem.tsx`
+**Props:** Icon, label, optional badge count
+**Usage:** Individual nav item within a SidebarSection.
+
+### BreadcrumbBar
+
+**File:** `BreadcrumbBar.tsx`
+**Usage:** Top breadcrumb navigation spanning main content + properties panel.
+
+### PropertiesPanel
+
+**File:** `PropertiesPanel.tsx`
+**Usage:** Right-side properties panel (`w-80`). Closeable. Shown on detail views.
+
+### CommandPalette
+
+**File:** `CommandPalette.tsx`
+**Usage:** Cmd+K global search modal. Searches issues, projects, agents.
+
+---
+
+## Dialog & Form Components
+
+### NewIssueDialog
+
+**File:** `NewIssueDialog.tsx`
+**Usage:** Create new issue with project/assignee/priority selection. Supports draft saving.
+
+### NewProjectDialog
+
+**File:** `NewProjectDialog.tsx`
+**Usage:** Create new project dialog.
+
+### NewAgentDialog
+
+**File:** `NewAgentDialog.tsx`
+**Usage:** Create new agent dialog.
+
+### OnboardingWizard
+
+**File:** `OnboardingWizard.tsx`
+**Usage:** Multi-step onboarding flow for new users/companies.
+
+---
+
+## Property Panel Components
+
+These render inside the PropertiesPanel for different entity types:
+
+| Component | File | Entity |
+|-----------|------|--------|
+| IssueProperties | `IssueProperties.tsx` | Issues |
+| AgentProperties | `AgentProperties.tsx` | Agents |
+| ProjectProperties | `ProjectProperties.tsx` | Projects |
+| GoalProperties | `GoalProperties.tsx` | Goals |
+
+All follow the property row pattern: `text-xs text-muted-foreground` label on left, value on right, `py-1.5` spacing.
+
+---
+
+## Agent Configuration
+
+### agent-config-primitives
+
+**File:** `agent-config-primitives.tsx`
+**Exports:** Field, ToggleField, ToggleWithNumber, CollapsibleSection, AutoExpandTextarea, DraftInput
+**Usage:** Reusable form field primitives for agent configuration forms.
+
+### AgentConfigForm
+
+**File:** `AgentConfigForm.tsx`
+**Usage:** Full agent creation/editing form with adapter type selection.
+
+---
+
+## Utilities & Hooks
+
+### cn() — Class Name Merger
+
+**File:** `ui/src/lib/utils.ts`
+**Usage:** Merges class names with clsx + tailwind-merge. Use in every component.
+
+```tsx
+import { cn } from "@/lib/utils";
+<div className={cn("base-classes", conditional && "extra", className)} />
+```
+
+### Formatting Utilities
+
+**File:** `ui/src/lib/utils.ts`
+
+| Function | Usage |
+|----------|-------|
+| `formatCents(cents)` | Money display: `$12.34` |
+| `formatDate(date)` | Date display: `Jan 15, 2025` |
+| `relativeTime(date)` | Relative time: `2m ago`, `Jan 15` |
+| `formatTokens(count)` | Token counts: `1.2M`, `500k` |
+
+### useKeyboardShortcuts
+
+**File:** `ui/src/hooks/useKeyboardShortcuts.ts`
+**Usage:** Global keyboard shortcut handler. Registers Cmd+K, C, [, ], Cmd+Enter.
+
+### Query Keys
+
+**File:** `ui/src/lib/queryKeys.ts`
+**Usage:** Structured React Query key factories for cache management.
+
+### groupBy
+
+**File:** `ui/src/lib/groupBy.ts`
+**Usage:** Generic array grouping utility.

.dockerignore

@@ -1,5 +1,10 @@
-dist-server/
-cli/
-node_modules/
-plandex-server
-plandex-cloud
+.git
+.github
+.paperclip
+.pnpm-store
+node_modules
+**/node_modules
+coverage
+data
+tmp
+*.log

.env.example

@@ -0,0 +1,3 @@
+DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
+PORT=3100
+SERVE_UI=false

.gitattributes

@@ -37,3 +37,5 @@ test/pong/install_dependencies.sh filter=lfs diff=lfs merge=lfs -text
 test/smoke_test.sh filter=lfs diff=lfs merge=lfs -text
 test/test_custom_models.sh filter=lfs diff=lfs merge=lfs -text
 test/test_utils.sh filter=lfs diff=lfs merge=lfs -text
+doc/assets/footer.jpg filter=lfs diff=lfs merge=lfs -text
+doc/assets/header.png filter=lfs diff=lfs merge=lfs -text

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Replace @cryppadotta if a different maintainer or team should own release infrastructure.
+
+.github/** @cryppadotta @devinfoley
+scripts/release*.sh @cryppadotta @devinfoley
+scripts/release-*.mjs @cryppadotta @devinfoley
+scripts/create-github-release.sh @cryppadotta @devinfoley
+scripts/rollback-latest.sh @cryppadotta @devinfoley
+doc/RELEASING.md @cryppadotta @devinfoley
+doc/PUBLISHING.md @cryppadotta @devinfoley
+doc/RELEASE-AUTOMATION-SETUP.md @cryppadotta @devinfoley

.github/workflows/e2e.yml

@@ -0,0 +1,44 @@
+name: E2E Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      skip_llm:
+        description: "Skip LLM-dependent assertions (default: true)"
+        type: boolean
+        default: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      PAPERCLIP_E2E_SKIP_LLM: ${{ inputs.skip_llm && 'true' || 'false' }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: npx playwright install --with-deps chromium
+
+      - name: Run e2e tests
+        run: pnpm run test:e2e
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: |
+            tests/e2e/playwright-report/
+            tests/e2e/test-results/
+          retention-days: 14

.github/workflows/pr-policy.yml

@@ -0,0 +1,49 @@
+name: PR Policy
+
+on:
+  pull_request:
+    branches:
+      - master
+
+concurrency:
+  group: pr-policy-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  policy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Block manual lockfile edits
+        if: github.head_ref != 'chore/refresh-lockfile'
+        run: |
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
+          if printf '%s\n' "$changed" | grep -qx 'pnpm-lock.yaml'; then
+            echo "Do not commit pnpm-lock.yaml in pull requests. CI owns lockfile updates."
+            exit 1
+          fi
+
+      - name: Validate dependency resolution when manifests change
+        run: |
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
+          manifest_pattern='(^|/)package\.json$|^pnpm-workspace\.yaml$|^\.npmrc$|^pnpmfile\.(cjs|js|mjs)$'
+          if printf '%s\n' "$changed" | grep -Eq "$manifest_pattern"; then
+            pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
+          fi

.github/workflows/pr-verify.yml

@@ -0,0 +1,48 @@
+name: PR Verify
+
+on:
+  pull_request:
+    branches:
+      - master
+
+concurrency:
+  group: pr-verify-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+      - name: Release canary dry run
+        run: |
+          git checkout -B master HEAD
+          git checkout -- pnpm-lock.yaml
+          ./scripts/release.sh canary --skip-verify --dry-run

.github/workflows/refresh-lockfile.yml

@@ -0,0 +1,93 @@
+name: Refresh Lockfile
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+concurrency:
+  group: refresh-lockfile-master
+  cancel-in-progress: false
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Refresh pnpm lockfile
+        run: pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
+
+      - name: Fail on unexpected file changes
+        run: |
+          changed="$(git status --porcelain)"
+          if [ -z "$changed" ]; then
+            echo "Lockfile is already up to date."
+            exit 0
+          fi
+          if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
+            echo "Unexpected files changed during lockfile refresh:"
+            echo "$changed"
+            exit 1
+          fi
+
+      - name: Create or update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if git diff --quiet -- pnpm-lock.yaml; then
+            echo "Lockfile unchanged, nothing to do."
+            exit 0
+          fi
+
+          BRANCH="chore/refresh-lockfile"
+          git config user.name "lockfile-bot"
+          git config user.email "lockfile-bot@users.noreply.github.com"
+
+          git checkout -B "$BRANCH"
+          git add pnpm-lock.yaml
+          git commit -m "chore(lockfile): refresh pnpm-lock.yaml"
+          git push --force origin "$BRANCH"
+
+          # Create PR if one doesn't already exist
+          existing=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number')
+          if [ -z "$existing" ]; then
+            gh pr create \
+              --head "$BRANCH" \
+              --title "chore(lockfile): refresh pnpm-lock.yaml" \
+              --body "Auto-generated lockfile refresh after dependencies changed on master. This PR only updates pnpm-lock.yaml."
+            echo "Created new PR."
+          else
+            echo "PR #$existing already exists, branch updated via force push."
+          fi
+
+      - name: Enable auto-merge for lockfile PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          pr_url="$(gh pr list --head chore/refresh-lockfile --json url --jq '.[0].url')"
+          if [ -z "$pr_url" ]; then
+            echo "Error: lockfile PR was not found." >&2
+            exit 1
+          fi
+
+          gh pr merge --auto --squash --delete-branch "$pr_url"

.github/workflows/release.yml

@@ -0,0 +1,260 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+    inputs:
+      source_ref:
+        description: Commit SHA, branch, or tag to publish as stable
+        required: true
+        type: string
+        default: master
+      stable_date:
+        description: Stable release date in UTC (YYYY-MM-DD). Defaults to today.
+        required: false
+        type: string
+      dry_run:
+        description: Preview the stable release without publishing
+        required: true
+        type: boolean
+        default: false
+
+concurrency:
+  group: release-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify_canary:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+  publish_canary:
+    if: github.event_name == 'push'
+    needs: verify_canary
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    environment: npm-canary
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Restore tracked install-time changes
+        run: git checkout -- pnpm-lock.yaml
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish canary
+        env:
+          GITHUB_ACTIONS: "true"
+        run: ./scripts/release.sh canary --skip-verify
+
+      - name: Push canary tag
+        run: |
+          tag="$(git tag --points-at HEAD | grep '^canary/v' | head -1)"
+          if [ -z "$tag" ]; then
+            echo "Error: no canary tag points at HEAD after release." >&2
+            exit 1
+          fi
+          git push origin "refs/tags/${tag}"
+
+  verify_stable:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+  preview_stable:
+    if: github.event_name == 'workflow_dispatch' && inputs.dry_run
+    needs: verify_stable
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Dry-run stable release
+        env:
+          GITHUB_ACTIONS: "true"
+        run: |
+          args=(stable --skip-verify --dry-run)
+          if [ -n "${{ inputs.stable_date }}" ]; then
+            args+=(--date "${{ inputs.stable_date }}")
+          fi
+          ./scripts/release.sh "${args[@]}"
+
+  publish_stable:
+    if: github.event_name == 'workflow_dispatch' && !inputs.dry_run
+    needs: verify_stable
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    environment: npm-stable
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Restore tracked install-time changes
+        run: git checkout -- pnpm-lock.yaml
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish stable
+        env:
+          GITHUB_ACTIONS: "true"
+        run: |
+          args=(stable --skip-verify)
+          if [ -n "${{ inputs.stable_date }}" ]; then
+            args+=(--date "${{ inputs.stable_date }}")
+          fi
+          ./scripts/release.sh "${args[@]}"
+
+      - name: Push stable tag
+        run: |
+          tag="$(git tag --points-at HEAD | grep '^v' | head -1)"
+          if [ -z "$tag" ]; then
+            echo "Error: no stable tag points at HEAD after release." >&2
+            exit 1
+          fi
+          git push origin "refs/tags/${tag}"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="$(git tag --points-at HEAD | grep '^v' | head -1 | sed 's/^v//')"
+          if [ -z "$version" ]; then
+            echo "Error: no v* tag points at HEAD after stable release." >&2
+            exit 1
+          fi
+          ./scripts/create-github-release.sh "$version"

.gitignore

@@ -1,27 +1,50 @@
-.plandex/
-.plandex-dev/
-.plandex-v2/
-.plandex-dev-v2/
-.envkey
-.env
-.env.*
-plandex
-plandex-dev
-plandex-server
-*.exe
 node_modules/
-/tools/
-/static/
-/infra/
-/payments-dashboard/
-.DS_Store
-.goreleaser.yml
 dist/
-__pycache__/
+.env
+*.tsbuildinfo
+drizzle/meta/
+.vite/
+coverage/
+.DS_Store
+data/
+.paperclip/
+.pnpm-store/
+tmp-*
+cli/tmp/
+
+# Scratch/seed scripts (but not scripts/ dir)
+check-*.mjs
+!scripts/check-*.mjs
+new-agent*.json
+newcompany.json
+seed-*.mjs
+server/check-*.mjs
+server/seed-*.mjs
+packages/db/seed-*.mjs
+
+# npm publish build artifacts
+cli/package.dev.json
+
+# Build artifacts in src directories
+server/src/**/*.js
+server/src/**/*.js.map
+server/src/**/*.d.ts
+server/src/**/*.d.ts.map
+tmp/
 
-.aider.*
-*.code-workspace
+# Editor / tool temp files
+*.tmp
+.vscode/
+.claude/settings.local.json
+.paperclip-local/
+/.idea/
+/.agents/
 
-__pycache__/
+# Doc maintenance cursor
+.doc-review-cursor
 
-.repo_ignore
+# Playwright
+tests/e2e/test-results/
+tests/e2e/playwright-report/
+.superset/
+.claude/worktrees/

.mailmap

@@ -0,0 +1 @@
+Dotta <bippadotta@protonmail.com> Forgotten <forgottenrunes@protonmail.com>

.npmrc

@@ -0,0 +1 @@
+auto-install-peers=true

AGENTS.md

@@ -0,0 +1,145 @@
+# AGENTS.md
+
+Guidance for human and AI contributors working in this repository.
+
+## 1. Purpose
+
+Paperclip is a control plane for AI-agent companies.
+The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.
+
+## 2. Read This First
+
+Before making changes, read in this order:
+
+1. `doc/GOAL.md`
+2. `doc/PRODUCT.md`
+3. `doc/SPEC-implementation.md`
+4. `doc/DEVELOPING.md`
+5. `doc/DATABASE.md`
+
+`doc/SPEC.md` is long-horizon product context.
+`doc/SPEC-implementation.md` is the concrete V1 build contract.
+
+## 3. Repo Map
+
+- `server/`: Express REST API and orchestration services
+- `ui/`: React + Vite board UI
+- `packages/db/`: Drizzle schema, migrations, DB clients
+- `packages/shared/`: shared types, constants, validators, API path constants
+- `doc/`: operational and product docs
+
+## 4. Dev Setup (Auto DB)
+
+Use embedded PGlite in dev by leaving `DATABASE_URL` unset.
+
+```sh
+pnpm install
+pnpm dev
+```
+
+This starts:
+
+- API: `http://localhost:3100`
+- UI: `http://localhost:3100` (served by API server in dev middleware mode)
+
+Quick checks:
+
+```sh
+curl http://localhost:3100/api/health
+curl http://localhost:3100/api/companies
+```
+
+Reset local dev DB:
+
+```sh
+rm -rf data/pglite
+pnpm dev
+```
+
+## 5. Core Engineering Rules
+
+1. Keep changes company-scoped.
+Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.
+
+2. Keep contracts synchronized.
+If you change schema/API behavior, update all impacted layers:
+- `packages/db` schema and exports
+- `packages/shared` types/constants/validators
+- `server` routes/services
+- `ui` API clients and pages
+
+3. Preserve control-plane invariants.
+- Single-assignee task model
+- Atomic issue checkout semantics
+- Approval gates for governed actions
+- Budget hard-stop auto-pause behavior
+- Activity logging for mutating actions
+
+4. Do not replace strategic docs wholesale unless asked.
+Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
+
+5. Keep plan docs dated and centralized.
+New plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames.
+
+## 6. Database Change Workflow
+
+When changing data model:
+
+1. Edit `packages/db/src/schema/*.ts`
+2. Ensure new tables are exported from `packages/db/src/schema/index.ts`
+3. Generate migration:
+
+```sh
+pnpm db:generate
+```
+
+4. Validate compile:
+
+```sh
+pnpm -r typecheck
+```
+
+Notes:
+- `packages/db/drizzle.config.ts` reads compiled schema from `dist/schema/*.js`
+- `pnpm db:generate` compiles `packages/db` first
+
+## 7. Verification Before Hand-off
+
+Run this full check before claiming done:
+
+```sh
+pnpm -r typecheck
+pnpm test:run
+pnpm build
+```
+
+If anything cannot be run, explicitly report what was not run and why.
+
+## 8. API and Auth Expectations
+
+- Base path: `/api`
+- Board access is treated as full-control operator context
+- Agent access uses bearer API keys (`agent_api_keys`), hashed at rest
+- Agent keys must not access other companies
+
+When adding endpoints:
+
+- apply company access checks
+- enforce actor permissions (board vs agent)
+- write activity log entries for mutations
+- return consistent HTTP errors (`400/401/403/404/409/422/500`)
+
+## 9. UI Expectations
+
+- Keep routes and nav aligned with available API surface
+- Use company selection context for company-scoped pages
+- Surface failures clearly; do not silently ignore API errors
+
+## 10. Definition of Done
+
+A change is done when all are true:
+
+1. Behavior matches `doc/SPEC-implementation.md`
+2. Typecheck, tests, and build pass
+3. Contracts are synced across db/shared/server/ui
+4. Docs updated when behavior or commands change

Agent.md

@@ -0,0 +1,168 @@
+# Agent.md
+
+1. Deployment Configuration
+Target Space
+Profile: AUXteam
+Space: Plandex
+Full Identifier: AUXteam/Plandex
+Frontend Port: 7860 (mandatory for all Hugging Face Spaces)
+
+Deployment Method
+Choose the correct SDK based on the app type based on the codebase language:
+Docker SDK — for all other applications (recommended default for flexibility)
+
+HF Token
+The environment variable `$HF_TOKEN` will always be provided at execution time.
+Never hardcode the token. Always read it from the environment.
+All monitoring and log‑streaming commands rely on `$HF_TOKEN`.
+
+Required Files
+Dockerfile
+README.md with Hugging Face YAML frontmatter:
+---
+title: Paperclip
+sdk: docker
+app_port: 7860
+---
+.hfignore to exclude unnecessary files
+This Agent.md file (must be committed before deployment)
+
+2. API Exposure and Documentation
+
+Mandatory Endpoints
+Every deployment must expose:
+
+/health
+Returns HTTP 200 when the app is ready.
+Required for Hugging Face to transition the Space from starting → running.
+
+/api-docs
+Documents all available API endpoints.
+Must be reachable at:
+https://AUXteam-Plandex.hf.space/api-docs
+
+Functional Endpoints
+
+### /api/health
+- Method: GET
+- Purpose: Returns API health status
+- Request: null
+- Response: 
+  {
+    "status": "ok",
+    "version": "1.0.0",
+    ...
+  }
+
+### /api/companies
+- Method: GET
+- Purpose: Lists all companies
+- Request: null
+- Response: 
+  [
+    {
+      "id": "123",
+      "name": "My Company"
+    }
+  ]
+
+### /api/companies
+- Method: POST
+- Purpose: Creates a new company
+- Request: 
+  {
+    "name": "My Company",
+    "goal": "Build a product"
+  }
+- Response: 
+  {
+    "id": "123",
+    "name": "My Company",
+    ...
+  }
+
+3. Deployment Workflow
+
+Standard Deployment Command
+After any code change, run:
+`hf upload AUXteam/Plandex --repo-type=space`
+This command must be executed after updating and committing Agent.md.
+
+Deployment Steps
+Ensure all code changes are committed.
+Ensure Agent.md is updated and committed.
+Run the upload command.
+Wait for the Space to build.
+Monitor logs (see next section).
+When the Space is running, execute all test cases.
+
+Continuous Deployment Rule
+After every relevant edit (logic, dependencies, API changes):
+Update Agent.md
+Redeploy using the upload command
+Re-run all test cases
+Confirm /health and /api-docs are functional
+This applies even for long-running projects.
+
+4. Monitoring and Logs
+
+Build Logs (SSE)
+curl -N \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/spaces/AUXteam/Plandex/logs/build"
+
+Run Logs (SSE)
+curl -N \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/spaces/AUXteam/Plandex/logs/run"
+
+Notes
+If the Space stays in starting for too long, /health is usually failing.
+If the Space times out after ~30 minutes, check logs immediately.
+Fix issues, commit changes, redeploy.
+
+5. Test Run Cases (Mandatory After Every Deployment)
+
+1. Health Check
+GET https://AUXteam-Plandex.hf.space/health
+Expected: HTTP 200, body: {"status": "ok"} or similar
+
+2. API Docs Check
+GET https://AUXteam-Plandex.hf.space/api-docs
+Expected: HTTP 200, valid documentation UI or JSON spec
+
+3. Functional Endpoint Tests
+
+POST https://AUXteam-Plandex.hf.space/api/companies
+Payload:
+{
+  "name": "Test Company",
+  "goal": "Testing"
+}
+Expected:
+- HTTP 200
+- JSON with key "id"
+- No error fields
+
+GET https://AUXteam-Plandex.hf.space/api/companies
+Expected:
+- HTTP 200
+- JSON array of companies
+- No error fields
+
+4. End-to-End Behaviour
+Confirm the UI loads (if applicable)
+Confirm API endpoints respond within reasonable time
+Confirm no errors appear in run logs
+
+6. Maintenance Rules
+Agent.md must always reflect the current deployment configuration, API surface, and test cases.
+Any change to:
+API routes
+Dockerfile
+Dependencies
+App logic
+Deployment method
+requires updating this file.
+This file must be committed before every deployment.
+This file is the operational contract for autonomous agents interacting with the project.

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing Guide
+
+Thanks for wanting to contribute!
+
+We really appreciate both small fixes and thoughtful larger changes.
+
+## Two Paths to Get Your Pull Request Accepted
+
+### Path 1: Small, Focused Changes (Fastest way to get merged)
+
+- Pick **one** clear thing to fix/improve
+- Touch the **smallest possible number of files**
+- Make sure the change is very targeted and easy to review
+- All automated checks pass (including Greptile comments)
+- No new lint/test failures
+
+These almost always get merged quickly when they're clean.
+
+### Path 2: Bigger or Impactful Changes
+
+- **First** talk about it in Discord → #dev channel  
+  → Describe what you're trying to solve  
+  → Share rough ideas / approach
+- Once there's rough agreement, build it
+- In your PR include:
+  - Before / After screenshots (or short video if UI/behavior change)
+  - Clear description of what & why
+  - Proof it works (manual testing notes)
+  - All tests passing
+  - All Greptile + other PR comments addressed
+
+PRs that follow this path are **much** more likely to be accepted, even when they're large.
+
+## General Rules (both paths)
+
+- Write clear commit messages
+- Keep PR title + description meaningful
+- One PR = one logical change (unless it's a small related group)
+- Run tests locally first
+- Be kind in discussions 😄
+
+## Writing a Good PR message
+
+Please include a "thinking path" at the top of your PR message that explains from the top of the project down to what you fixed. E.g.:
+
+### Thinking Path Example 1:
+
+> - Paperclip orchestrates ai-agents for zero-human companies
+> - There are many types of adapters for each LLM model provider
+> - But LLM's have a context limit and not all agents can automatically compact their context
+> - So we need to have an adapter-specific configuration for which adapters can and cannot automatically compact their context
+> - This pull request adds per-adapter configuration of compaction, either auto or paperclip managed
+> - That way we can get optimal performance from any adapter/provider in Paperclip
+
+### Thinking Path Example 2:
+
+> - Paperclip orchestrates ai-agents for zero-human companies
+> - But humans want to watch the agents and oversee their work
+> - Human users also operate in teams and so they need their own logins, profiles, views etc.
+> - So we have a multi-user system for humans
+> - But humans want to be able to update their own profile picture and avatar
+> - But the avatar upload form wasn't saving the avatar to the file storage system
+> - So this PR fixes the avatar upload form to use the file storage service
+> - The benefit is we don't have a one-off file storage for just one aspect of the system, which would cause confusion and extra configuration
+
+Then have the rest of your normal PR message after the Thinking Path.
+
+This should include details about what you did, why you did it, why it matters & the benefits, how we can verify it works, and any risks.
+
+Please include screenshots if possible if you have a visible change. (use something like the [agent-browser skill](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) or similar to take screenshots). Ideally, you include before and after screenshots.
+
+Questions? Just ask in #dev — we're happy to help.
+
+Happy hacking!

Dockerfile

@@ -1,55 +1,56 @@
-FROM golang:1.23.3
-
-# Update and install necessary packages including build tools for Tree-sitter and Postgres
-RUN apt-get update && \
-  apt-get install -y git gcc g++ make python3 python3-venv postgresql postgresql-contrib
-
-# Install Python and create a virtual environment for litellm passthrough
-RUN python3 -m venv /opt/venv
-
-# Activate the virtual environment for all following RUN commands
-ENV PATH="/opt/venv/bin:$PATH"
-
-# Now install litellm passthrough dependencies in the virtual environment
-RUN pip install --no-cache-dir "litellm==1.72.6" "fastapi==0.115.12" "uvicorn==0.34.1" "google-cloud-aiplatform==1.96.0" "boto3==1.38.40" "botocore==1.38.40"
+FROM node:lts-trixie-slim AS base
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ca-certificates curl git \
+  && rm -rf /var/lib/apt/lists/*
+RUN corepack enable
 
+FROM base AS deps
 WORKDIR /app
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml .npmrc ./
+COPY cli/package.json cli/
+COPY server/package.json server/
+COPY ui/package.json ui/
+COPY packages/shared/package.json packages/shared/
+COPY packages/db/package.json packages/db/
+COPY packages/adapter-utils/package.json packages/adapter-utils/
+COPY packages/adapters/claude-local/package.json packages/adapters/claude-local/
+COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
+COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
+COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
+COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
+COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
+COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
+
+RUN pnpm install --frozen-lockfile
+
+FROM base AS build
+WORKDIR /app
+COPY --from=deps /app /app
+COPY . .
+RUN pnpm --filter @paperclipai/ui build
+RUN pnpm --filter @paperclipai/server build
+RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" && exit 1)
 
-# Copy go.mod and go.sum for shared and server, and install dependencies
-COPY ./app/shared/go.mod ./app/shared/go.sum ./app/shared/
-RUN cd app/shared && go mod download
-
-COPY ./app/server/go.mod ./app/server/go.sum ./app/server/
-RUN cd app/server && go mod download
-
-# Copy the actual source code
-COPY ./app/server ./app/server
-COPY ./app/shared ./app/shared
-COPY ./app/scripts /scripts
-
-# Set working directory to server
-WORKDIR /app/app/server
-
-# Build the application
-RUN rm -f plandex-server && go build -o plandex-server .
-
-# Setup entrypoint script to start postgres and the server
-RUN echo '#!/bin/bash\n\
-service postgresql start\n\
-su - postgres -c "psql -c \"CREATE USER plandex WITH PASSWORD '\''plandex'\'';\""\n\
-su - postgres -c "psql -c \"CREATE DATABASE plandex OWNER plandex;\""\n\
-export DATABASE_URL="postgres://plandex:plandex@localhost:5432/plandex?sslmode=disable"\n\
-export GOENV=development\n\
-export LOCAL_MODE=1\n\
-export PLANDEX_BASE_DIR=/plandex-server\n\
-export LITELLM_PROXY_DIR=/app/app/server\n\
-mkdir -p /plandex-server\n\
-cd /app/app/server\n\
-./plandex-server' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh
-
-# Set the port and expose it
-ENV PORT=7860
+FROM base AS production
+WORKDIR /app
+COPY --chown=node:node --from=build /app /app
+RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai \
+  && mkdir -p /paperclip \
+  && chown node:node /paperclip
+
+ENV NODE_ENV=production \
+  HOME=/paperclip \
+  HOST=0.0.0.0 \
+  PORT=7860 \
+  SERVE_UI=true \
+  PAPERCLIP_HOME=/paperclip \
+  PAPERCLIP_INSTANCE_ID=default \
+  PAPERCLIP_CONFIG=/paperclip/instances/default/config.json \
+  PAPERCLIP_DEPLOYMENT_MODE=authenticated \
+  PAPERCLIP_DEPLOYMENT_EXPOSURE=private
+
+VOLUME ["/paperclip"]
 EXPOSE 7860
 
-# Command to run the entrypoint script
-CMD ["/app/entrypoint.sh"]
+USER node
+CMD ["node", "--import", "./server/node_modules/tsx/dist/loader.mjs", "server/dist/index.js"]

Dockerfile.onboard-smoke

@@ -0,0 +1,40 @@
+FROM ubuntu:24.04
+
+ARG NODE_MAJOR=20
+ARG PAPERCLIPAI_VERSION=latest
+ARG HOST_UID=10001
+
+ENV DEBIAN_FRONTEND=noninteractive \
+  PAPERCLIP_HOME=/paperclip \
+  PAPERCLIP_OPEN_ON_LISTEN=false \
+  HOST=0.0.0.0 \
+  PORT=3100 \
+  HOME=/home/paperclip \
+  LANG=en_US.UTF-8 \
+  LC_ALL=en_US.UTF-8 \
+  NPM_CONFIG_UPDATE_NOTIFIER=false \
+  NODE_MAJOR=${NODE_MAJOR} \
+  PAPERCLIPAI_VERSION=${PAPERCLIPAI_VERSION}
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ca-certificates curl gnupg locales \
+  && mkdir -p /etc/apt/keyrings \
+  && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
+    | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+  && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" \
+    > /etc/apt/sources.list.d/nodesource.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends nodejs \
+  && locale-gen en_US.UTF-8 \
+  && groupadd --gid 10001 paperclip \
+  && useradd --create-home --shell /bin/bash --uid "${HOST_UID}" --gid 10001 paperclip \
+  && mkdir -p /paperclip /home/paperclip/workspace \
+  && chown -R paperclip:paperclip /paperclip /home/paperclip \
+  && rm -rf /var/lib/apt/lists/*
+
+VOLUME ["/paperclip"]
+WORKDIR /home/paperclip/workspace
+EXPOSE 3100
+USER paperclip
+
+CMD ["bash", "-lc", "set -euo pipefail; mkdir -p \"$PAPERCLIP_HOME\"; npx --yes \"paperclipai@${PAPERCLIPAI_VERSION}\" onboard --yes --data-dir \"$PAPERCLIP_HOME\""]

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 PlandexAI Inc.
+Copyright (c) 2025 Paperclip AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -1,243 +1,285 @@
 ---
-title: Plandex
-emoji: 🚀
-colorFrom: blue
-colorTo: indigo
+title: Paperclip
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-<h1 align="center">
- <a href="https://plandex.ai">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="images/plandex-logo-dark-v2.png"/>
-    <source media="(prefers-color-scheme: light)" srcset="images/plandex-logo-light-v2.png"/>
-    <img width="400" src="images/plandex-logo-dark-bg-v2.png"/>
- </a>
- <br />
-</h1>
-<br />
-
-<div align="center">
-
-<p align="center">
-  <!-- Call to Action Links -->
-  <a href="#install">
-    <b>30-Second Install</b>
-  </a>
-   ·
-  <a href="https://plandex.ai">
-    <b>Website</b>
-  </a>
-   ·
-  <a href="https://docs.plandex.ai/">
-    <b>Docs</b>
-  </a>
-   ·
-  <a href="#examples-">
-    <b>Examples</b>
-  </a>
-   ·
-  <a href="https://docs.plandex.ai/hosting/self-hosting/local-mode-quickstart">
-    <b>Local Self-Hosted Mode</b>
-  </a>
-</p>
-
-<br>
-
-[![Discord](https://img.shields.io/discord/1214825831973785600.svg?style=flat&logo=discord&label=Discord&refresh=1)](https://discord.gg/plandex-ai)
-[![GitHub Repo stars](https://img.shields.io/github/stars/plandex-ai/plandex?style=social)](https://github.com/plandex-ai/plandex)
-[![Twitter Follow](https://img.shields.io/twitter/follow/PlandexAI?style=social)](https://twitter.com/PlandexAI)
-
-</div>
-
-<p align="center">
-  <!-- Badges -->
-<a href="https://github.com/plandex-ai/plandex/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" /></a> <a href="https://github.com/plandex-ai/plandex/releases?q=cli"><img src="https://img.shields.io/github/v/release/plandex-ai/plandex?filter=cli*" alt="Release" /></a>
-<a href="https://github.com/plandex-ai/plandex/releases?q=server"><img src="https://img.shields.io/github/v/release/plandex-ai/plandex?filter=server*" alt="Release" /></a>
-
-  <!-- <a href="https://github.com/your_username/your_project/issues">
-    <img src="https://img.shields.io/github/issues-closed/your_username/your_project.svg" alt="Issues Closed" />
-  </a> -->
-
-</p>
-
-<br />
-
-<div align="center">
-<a href="https://trendshift.io/repositories/8994" target="_blank"><img src="https://trendshift.io/api/badge/repositories/8994" alt="plandex-ai%2Fplandex | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-</div>
-
-<br>
-
-<h1 align="center" >
-  An AI coding agent designed for large tasks and real world projects.<br/><br/>
-</h1>
-
-<!-- <h2 align="center">
-  Designed for large tasks and real world projects.<br/><br/>
-  </h2> -->
-  <br/>
-
-<div align="center">
-  <a href="https://www.youtube.com/watch?v=SFSu2vNmlLk">
-    <img src="images/plandex-v2-yt.png" alt="Plandex v2 Demo Video" width="800">
-  </a>
-</div>
-
-<br/>
-
-💻  Plandex is a terminal-based AI development tool that can **plan and execute** large coding tasks that span many steps and touch dozens of files. It can handle up to 2M tokens of context directly (~100k per file), and can index directories with 20M tokens or more using tree-sitter project maps.
-
-🔬  **A cumulative diff review sandbox** keeps AI-generated changes separate from your project files until they are ready to go. Command execution is controlled so you can easily roll back and debug. Plandex helps you get the most out of AI without leaving behind a mess in your project.
-
-🧠  **Combine the best models** from Anthropic, OpenAI, Google, and open source providers to build entire features and apps with a robust terminal-based workflow.
-
-🚀  Plandex is capable of <strong>full autonomy</strong>—it can load relevant files, plan and implement changes, execute commands, and automatically debug—but it's also highly flexible and configurable, giving developers fine-grained control and a step-by-step review process when needed.
-
-💪  Plandex is designed to be resilient to <strong>large projects and files</strong>. If you've found that others tools struggle once your project gets past a certain size or the changes are too complex, give Plandex a shot.
-
-## Smart context management that works in big projects
-
-- 🐘 **2M token effective context window** with default model pack. Plandex loads only what's needed for each step.
-
-- 🗄️ **Reliable in large projects and files.** Easily generate, review, revise, and apply changes spanning dozens of files.
-
-- 🗺️ **Fast project map generation** and syntax validation with tree-sitter. Supports 30+ languages.
-
-- 💰 **Context caching** is used across the board for OpenAI, Anthropic, and Google models, reducing costs and latency.
-
-## Tight control or full autonomy—it's up to you
-
-- 🚦 **Configurable autonomy:** go from full auto mode to fine-grained control depending on the task.
-
-- 🐞 **Automated debugging** of terminal commands (like builds, linters, tests, deployments, and scripts). If you have Chrome installed, you can also automatically debug browser applications.
-
-## Tools that help you get production-ready results
-
-- 💬 **A project-aware chat mode** that helps you flesh out ideas before moving to implementation. Also great for asking questions and learning about a codebase.
-
-- 🧠 **Easily try + combine models** from multiple providers. Curated model packs offer different tradeoffs of capability, cost, and speed, as well as open source and provider-specific packs.
-
-- 🛡️ **Reliable file edits** that prioritize correctness. While most edits are quick and cheap, Plandex validates both syntax and logic as needed, with multiple fallback layers when there are problems.
-
-- 🔀 **Full-fledged version control** for every update to the plan, including branches for exploring multiple paths or comparing different models.
-
-- 📂 **Git integration** with commit message generation and optional automatic commits.
-
-## Dev-friendly, easy to install
-
-- 🧑‍💻 **REPL mode** with fuzzy auto-complete for commands and file loading. Just run `plandex` in any project to get started.
-
-- 🛠️ **CLI interface** for scripting or piping data into context.
-
-- 📦 **One-line, zero dependency CLI install**. Dockerized local mode for easily self-hosting the server. Cloud-hosting options for extra reliability and convenience.
-
-## Workflow  🔄
-
-<img src="images/plandex-workflow.png" alt="Plandex workflow" width="100%"/>
-
-## Examples  🎥
-
-  <br/>
-
-<div align="center">
-  <a href="https://www.youtube.com/watch?v=g-_76U_nK0Y">
-    <img src="images/plandex-browser-debug-yt.png" alt="Plandex Browser Debugging Example" width="800">
-  </a>
-</div>
-
-<br/>
-
-## Install  📥
-
-```bash
-curl -sL https://plandex.ai/install.sh | bash
-```
-
-**Note:** Windows is supported via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Plandex only works correctly on Windows in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.
-
-[More installation options.](https://docs.plandex.ai/install)
-
-## Hosting  ⚖️
-
-| Option                     | Description                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Plandex Cloud**          | Winding down as of 10/3/2025 and no longer accepting new users. <a href="https://plandex.ai/blog/winding-down">Learn more.</a>                                                                                                                                                                                                                              |
-| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) key (or [other model provider](https://docs.plandex.ai/models/model-providers) accounts and API keys).<br/>• Follow the [local-mode quickstart](https://docs.plandex.ai/hosting/self-hosting/local-mode-quickstart) to get started. |
-
-## Provider keys  🔑
-
-<!-- If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set API keys for the [model providers](https://docs.plandex.ai/models/model-providers) you're using: -->
-
-```bash
-export OPENROUTER_API_KEY=... # if using OpenRouter.ai
-```
-
-<br/>
-
-## Claude Pro/Max subscription  🖇️
-
-If you have a Claude Pro or Max subscription, Plandex can use it when calling Anthropic models. You'll be asked if you want to connect a subscription the first time you run Plandex.
-
-<br/>
-
-## Get started  🚀
-
-First, `cd` into a **project directory** where you want to get something done or chat about the project. Make a new directory first with `mkdir your-project-dir` if you're starting on a new project.
-
-```bash
-cd your-project-dir
-```
-
-For a new project, you might also want to initialize a git repo. Plandex doesn't require that your project is in a git repo, but it does integrate well with git if you use it.
-
-```bash
-git init
-```
-
-Now start the Plandex REPL in your project:
-
-```bash
-plandex
-```
-
-or for short:
-
-```bash
-pdx
-```
-
-<!-- ☁️ _If you're using Plandex Cloud, you'll be prompted at this point to start a trial._
-
-Then just give the REPL help text a quick read, and you're ready go. The REPL starts in _chat mode_ by default, which is good for fleshing out ideas before moving to implementation. Once the task is clear, Plandex will prompt you to switch to _tell mode_ to make a detailed plan and start writing code. -->
-
-<br/>
-
-## Docs  🛠️
-
-### [👉  Full documentation.](https://docs.plandex.ai/)
-
-<br/>
-
-## Discussion and discord  💬
-
-Please feel free to give your feedback, ask questions, report a bug, or just hang out:
-
-- [Discord](https://discord.gg/plandex-ai)
-- [Discussions](https://github.com/plandex-ai/plandex/discussions)
-- [Issues](https://github.com/plandex-ai/plandex/issues)
-
-## Follow and subscribe
-
-- [Follow @PlandexAI](https://x.com/PlandexAI)
-- [Follow @Danenania](https://x.com/Danenania) (Plandex's creator)
-- [Subscribe on YouTube](https://x.com/PlandexAI)
-
-<br/>
-
-## Contributors  👥
-
-⭐️  Please star, fork, explore, and contribute to Plandex. There's a lot of work to do and so much that can be improved.
-
-[Here's an overview on setting up a development environment.](https://docs.plandex.ai/development)
+<p align="center">
+  <img src="doc/assets/header.png" alt="Paperclip — runs your business" width="720" />
+</p>
+
+<p align="center">
+  <a href="#quickstart"><strong>Quickstart</strong></a> &middot;
+  <a href="https://paperclip.ing/docs"><strong>Docs</strong></a> &middot;
+  <a href="https://github.com/paperclipai/paperclip"><strong>GitHub</strong></a> &middot;
+  <a href="https://discord.gg/m4HZY7xNG3"><strong>Discord</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/paperclipai/paperclip/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://github.com/paperclipai/paperclip/stargazers"><img src="https://img.shields.io/github/stars/paperclipai/paperclip?style=flat" alt="Stars" /></a>
+  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/discord/000000000?label=discord" alt="Discord" /></a>
+</p>
+
+<br/>
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/773bdfb2-6d1e-4e30-8c5f-3487d5b70c8f" width="600" controls></video>
+</div>
+
+<br/>
+
+## What is Paperclip?
+
+# Open-source orchestration for zero-human companies
+
+**If OpenClaw is an _employee_, Paperclip is the _company_**
+
+Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business. Bring your own agents, assign goals, and track your agents' work and costs from one dashboard.
+
+It looks like a task manager — but under the hood it has org charts, budgets, governance, goal alignment, and agent coordination.
+
+**Manage business goals, not pull requests.**
+
+|        | Step            | Example                                                            |
+| ------ | --------------- | ------------------------------------------------------------------ |
+| **01** | Define the goal | _"Build the #1 AI note-taking app to $1M MRR."_                    |
+| **02** | Hire the team   | CEO, CTO, engineers, designers, marketers — any bot, any provider. |
+| **03** | Approve and run | Review strategy. Set budgets. Hit go. Monitor from the dashboard.  |
+
+<br/>
+
+> **COMING SOON: Clipmart** — Download and run entire companies with one click. Browse pre-built company templates — full org structures, agent configs, and skills — and import them into your Paperclip instance in seconds.
+
+<br/>
+
+<div align="center">
+<table>
+  <tr>
+    <td align="center"><strong>Works<br/>with</strong></td>
+    <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw" /><br/><sub>OpenClaw</sub></td>
+    <td align="center"><img src="doc/assets/logos/claude.svg" width="32" alt="Claude" /><br/><sub>Claude Code</sub></td>
+    <td align="center"><img src="doc/assets/logos/codex.svg" width="32" alt="Codex" /><br/><sub>Codex</sub></td>
+    <td align="center"><img src="doc/assets/logos/cursor.svg" width="32" alt="Cursor" /><br/><sub>Cursor</sub></td>
+    <td align="center"><img src="doc/assets/logos/bash.svg" width="32" alt="Bash" /><br/><sub>Bash</sub></td>
+    <td align="center"><img src="doc/assets/logos/http.svg" width="32" alt="HTTP" /><br/><sub>HTTP</sub></td>
+  </tr>
+</table>
+
+<em>If it can receive a heartbeat, it's hired.</em>
+
+</div>
+
+<br/>
+
+## Paperclip is right for you if
+
+- ✅ You want to build **autonomous AI companies**
+- ✅ You **coordinate many different agents** (OpenClaw, Codex, Claude, Cursor) toward a common goal
+- ✅ You have **20 simultaneous Claude Code terminals** open and lose track of what everyone is doing
+- ✅ You want agents running **autonomously 24/7**, but still want to audit work and chime in when needed
+- ✅ You want to **monitor costs** and enforce budgets
+- ✅ You want a process for managing agents that **feels like using a task manager**
+- ✅ You want to manage your autonomous businesses **from your phone**
+
+<br/>
+
+## Features
+
+<table>
+<tr>
+<td align="center" width="33%">
+<h3>🔌 Bring Your Own Agent</h3>
+Any agent, any runtime, one org chart. If it can receive a heartbeat, it's hired.
+</td>
+<td align="center" width="33%">
+<h3>🎯 Goal Alignment</h3>
+Every task traces back to the company mission. Agents know <em>what</em> to do and <em>why</em>.
+</td>
+<td align="center" width="33%">
+<h3>💓 Heartbeats</h3>
+Agents wake on a schedule, check work, and act. Delegation flows up and down the org chart.
+</td>
+</tr>
+<tr>
+<td align="center">
+<h3>💰 Cost Control</h3>
+Monthly budgets per agent. When they hit the limit, they stop. No runaway costs.
+</td>
+<td align="center">
+<h3>🏢 Multi-Company</h3>
+One deployment, many companies. Complete data isolation. One control plane for your portfolio.
+</td>
+<td align="center">
+<h3>🎫 Ticket System</h3>
+Every conversation traced. Every decision explained. Full tool-call tracing and immutable audit log.
+</td>
+</tr>
+<tr>
+<td align="center">
+<h3>🛡️ Governance</h3>
+You're the board. Approve hires, override strategy, pause or terminate any agent — at any time.
+</td>
+<td align="center">
+<h3>📊 Org Chart</h3>
+Hierarchies, roles, reporting lines. Your agents have a boss, a title, and a job description.
+</td>
+<td align="center">
+<h3>📱 Mobile Ready</h3>
+Monitor and manage your autonomous businesses from anywhere.
+</td>
+</tr>
+</table>
+
+<br/>
+
+## Problems Paperclip solves
+
+| Without Paperclip                                                                                                                     | With Paperclip                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ❌ You have 20 Claude Code tabs open and can't track which one does what. On reboot you lose everything.                              | ✅ Tasks are ticket-based, conversations are threaded, sessions persist across reboots.                                                |
+| ❌ You manually gather context from several places to remind your bot what you're actually doing.                                     | ✅ Context flows from the task up through the project and company goals — your agent always knows what to do and why.                  |
+| ❌ Folders of agent configs are disorganized and you're re-inventing task management, communication, and coordination between agents. | ✅ Paperclip gives you org charts, ticketing, delegation, and governance out of the box — so you run a company, not a pile of scripts. |
+| ❌ Runaway loops waste hundreds of dollars of tokens and max your quota before you even know what happened.                           | ✅ Cost tracking surfaces token budgets and throttles agents when they're out. Management prioritizes with budgets.                    |
+| ❌ You have recurring jobs (customer support, social, reports) and have to remember to manually kick them off.                        | ✅ Heartbeats handle regular work on a schedule. Management supervises.                                                                |
+| ❌ You have an idea, you have to find your repo, fire up Claude Code, keep a tab open, and babysit it.                                | ✅ Add a task in Paperclip. Your coding agent works on it until it's done. Management reviews their work.                              |
+
+<br/>
+
+## Why Paperclip is special
+
+Paperclip handles the hard orchestration details correctly.
+
+|                                   |                                                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **Atomic execution.**             | Task checkout and budget enforcement are atomic, so no double-work and no runaway spend.                      |
+| **Persistent agent state.**       | Agents resume the same task context across heartbeats instead of restarting from scratch.                     |
+| **Runtime skill injection.**      | Agents can learn Paperclip workflows and project context at runtime, without retraining.                      |
+| **Governance with rollback.**     | Approval gates are enforced, config changes are revisioned, and bad changes can be rolled back safely.        |
+| **Goal-aware execution.**         | Tasks carry full goal ancestry so agents consistently see the "why," not just a title.                        |
+| **Portable company templates.**   | Export/import orgs, agents, and skills with secret scrubbing and collision handling.                          |
+| **True multi-company isolation.** | Every entity is company-scoped, so one deployment can run many companies with separate data and audit trails. |
+
+<br/>
+
+## What Paperclip is not
+
+|                              |                                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Not a chatbot.**           | Agents have jobs, not chat windows.                                                                                  |
+| **Not an agent framework.**  | We don't tell you how to build agents. We tell you how to run a company made of them.                                |
+| **Not a workflow builder.**  | No drag-and-drop pipelines. Paperclip models companies — with org charts, goals, budgets, and governance.            |
+| **Not a prompt manager.**    | Agents bring their own prompts, models, and runtimes. Paperclip manages the organization they work in.               |
+| **Not a single-agent tool.** | This is for teams. If you have one agent, you probably don't need Paperclip. If you have twenty — you definitely do. |
+| **Not a code review tool.**  | Paperclip orchestrates work, not pull requests. Bring your own review process.                                       |
+
+<br/>
+
+## Quickstart
+
+Open source. Self-hosted. No Paperclip account required.
+
+```bash
+npx paperclipai onboard --yes
+```
+
+Or manually:
+
+```bash
+git clone https://github.com/paperclipai/paperclip.git
+cd paperclip
+pnpm install
+pnpm dev
+```
+
+This starts the API server at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no setup required.
+
+> **Requirements:** Node.js 20+, pnpm 9.15+
+
+<br/>
+
+## FAQ
+
+**What does a typical setup look like?**
+Locally, a single Node.js process manages an embedded Postgres and local file storage. For production, point it at your own Postgres and deploy however you like. Configure projects, agents, and goals — the agents take care of the rest.
+
+If you're a solo-entreprenuer you can use Tailscale to access Paperclip on the go. Then later you can deploy to e.g. Vercel when you need it.
+
+**Can I run multiple companies?**
+Yes. A single deployment can run an unlimited number of companies with complete data isolation.
+
+**How is Paperclip different from agents like OpenClaw or Claude Code?**
+Paperclip _uses_ those agents. It orchestrates them into a company — with org charts, budgets, goals, governance, and accountability.
+
+**Why should I use Paperclip instead of just pointing my OpenClaw to Asana or Trello?**
+Agent orchestration has subtleties in how you coordinate who has work checked out, how to maintain sessions, monitoring costs, establishing governance - Paperclip does this for you.
+
+(Bring-your-own-ticket-system is on the Roadmap)
+
+**Do agents run continuously?**
+By default, agents run on scheduled heartbeats and event-based triggers (task assignment, @-mentions). You can also hook in continuous agents like OpenClaw. You bring your agent and Paperclip coordinates.
+
+<br/>
+
+## Development
+
+```bash
+pnpm dev              # Full dev (API + UI, watch mode)
+pnpm dev:once         # Full dev without file watching
+pnpm dev:server       # Server only
+pnpm build            # Build all
+pnpm typecheck        # Type checking
+pnpm test:run         # Run tests
+pnpm db:generate      # Generate DB migration
+pnpm db:migrate       # Apply migrations
+```
+
+See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
+
+<br/>
+
+## Roadmap
+
+- ⚪ Get OpenClaw onboarding easier
+- ⚪ Get cloud agents working e.g. Cursor / e2b agents
+- ⚪ ClipMart - buy and sell entire agent companies
+- ⚪ Easy agent configurations / easier to understand
+- ⚪ Better support for harness engineering
+- 🟢 Plugin system (e.g. if you want to add a knowledgebase, custom tracing, queues, etc)
+- ⚪ Better docs
+
+<br/>
+
+## Contributing
+
+We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.
+
+<br/>
+
+## Community
+
+- [Discord](https://discord.gg/m4HZY7xNG3) — Join the community
+- [GitHub Issues](https://github.com/paperclipai/paperclip/issues) — bugs and feature requests
+- [GitHub Discussions](https://github.com/paperclipai/paperclip/discussions) — ideas and RFC
+
+<br/>
+
+## License
+
+MIT &copy; 2026 Paperclip
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/image?repos=paperclipai/paperclip&type=date&legend=top-left)](https://www.star-history.com/?repos=paperclipai%2Fpaperclip&type=date&legend=top-left)
+
+<br/>
+
+---
+
+<p align="center">
+  <img src="doc/assets/footer.jpg" alt="" width="720" />
+</p>
+
+<p align="center">
+  <sub>Open source under MIT. Built for people who want to run companies, not babysit agents.</sub>
+</p>

cli/CHANGELOG.md

@@ -0,0 +1,138 @@
+# paperclipai
+
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+  - @paperclipai/adapter-claude-local@0.3.1
+  - @paperclipai/adapter-codex-local@0.3.1
+  - @paperclipai/adapter-cursor-local@0.3.1
+  - @paperclipai/adapter-gemini-local@0.3.1
+  - @paperclipai/adapter-openclaw-gateway@0.3.1
+  - @paperclipai/adapter-opencode-local@0.3.1
+  - @paperclipai/adapter-pi-local@0.3.1
+  - @paperclipai/db@0.3.1
+  - @paperclipai/shared@0.3.1
+  - @paperclipai/server@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies [6077ae6]
+- Updated dependencies
+  - @paperclipai/shared@0.3.0
+  - @paperclipai/adapter-utils@0.3.0
+  - @paperclipai/adapter-claude-local@0.3.0
+  - @paperclipai/adapter-codex-local@0.3.0
+  - @paperclipai/adapter-cursor-local@0.3.0
+  - @paperclipai/adapter-openclaw-gateway@0.3.0
+  - @paperclipai/adapter-opencode-local@0.3.0
+  - @paperclipai/adapter-pi-local@0.3.0
+  - @paperclipai/db@0.3.0
+  - @paperclipai/server@0.3.0
+
+## 0.2.7
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.7
+  - @paperclipai/adapter-utils@0.2.7
+  - @paperclipai/db@0.2.7
+  - @paperclipai/adapter-claude-local@0.2.7
+  - @paperclipai/adapter-codex-local@0.2.7
+  - @paperclipai/adapter-openclaw@0.2.7
+  - @paperclipai/server@0.2.7
+
+## 0.2.6
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.6
+  - @paperclipai/adapter-utils@0.2.6
+  - @paperclipai/db@0.2.6
+  - @paperclipai/adapter-claude-local@0.2.6
+  - @paperclipai/adapter-codex-local@0.2.6
+  - @paperclipai/adapter-openclaw@0.2.6
+  - @paperclipai/server@0.2.6
+
+## 0.2.5
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.5
+  - @paperclipai/adapter-utils@0.2.5
+  - @paperclipai/db@0.2.5
+  - @paperclipai/adapter-claude-local@0.2.5
+  - @paperclipai/adapter-codex-local@0.2.5
+  - @paperclipai/adapter-openclaw@0.2.5
+  - @paperclipai/server@0.2.5
+
+## 0.2.4
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.4
+  - @paperclipai/adapter-utils@0.2.4
+  - @paperclipai/db@0.2.4
+  - @paperclipai/adapter-claude-local@0.2.4
+  - @paperclipai/adapter-codex-local@0.2.4
+  - @paperclipai/adapter-openclaw@0.2.4
+  - @paperclipai/server@0.2.4
+
+## 0.2.3
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.3
+  - @paperclipai/adapter-utils@0.2.3
+  - @paperclipai/db@0.2.3
+  - @paperclipai/adapter-claude-local@0.2.3
+  - @paperclipai/adapter-codex-local@0.2.3
+  - @paperclipai/adapter-openclaw@0.2.3
+  - @paperclipai/server@0.2.3
+
+## 0.2.2
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.2
+  - @paperclipai/adapter-utils@0.2.2
+  - @paperclipai/db@0.2.2
+  - @paperclipai/adapter-claude-local@0.2.2
+  - @paperclipai/adapter-codex-local@0.2.2
+  - @paperclipai/adapter-openclaw@0.2.2
+  - @paperclipai/server@0.2.2
+
+## 0.2.1
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.1
+  - @paperclipai/adapter-utils@0.2.1
+  - @paperclipai/db@0.2.1
+  - @paperclipai/adapter-claude-local@0.2.1
+  - @paperclipai/adapter-codex-local@0.2.1
+  - @paperclipai/adapter-openclaw@0.2.1
+  - @paperclipai/server@0.2.1

cli/esbuild.config.mjs

@@ -0,0 +1,65 @@
+/**
+ * esbuild configuration for building the paperclipai CLI for npm.
+ *
+ * Bundles all workspace packages (@paperclipai/*) into a single file.
+ * External npm packages remain as regular dependencies.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "..");
+
+// Workspace packages whose code should be bundled into the CLI.
+// Note: "server" is excluded — it's published separately and resolved at runtime.
+const workspacePaths = [
+  "cli",
+  "packages/db",
+  "packages/shared",
+  "packages/adapter-utils",
+  "packages/adapters/claude-local",
+  "packages/adapters/codex-local",
+  "packages/adapters/openclaw-gateway",
+];
+
+// Workspace packages that should NOT be bundled — they'll be published
+// to npm and resolved at runtime (e.g. @paperclipai/server uses dynamic import).
+const externalWorkspacePackages = new Set([
+  "@paperclipai/server",
+]);
+
+// Collect all external (non-workspace) npm package names
+const externals = new Set();
+for (const p of workspacePaths) {
+  const pkg = JSON.parse(readFileSync(resolve(repoRoot, p, "package.json"), "utf8"));
+  for (const name of Object.keys(pkg.dependencies || {})) {
+    if (externalWorkspacePackages.has(name)) {
+      externals.add(name);
+    } else if (!name.startsWith("@paperclipai/")) {
+      externals.add(name);
+    }
+  }
+  for (const name of Object.keys(pkg.optionalDependencies || {})) {
+    externals.add(name);
+  }
+}
+// Also add all published workspace packages as external
+for (const name of externalWorkspacePackages) {
+  externals.add(name);
+}
+
+/** @type {import('esbuild').BuildOptions} */
+export default {
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node20",
+  format: "esm",
+  outfile: "dist/index.js",
+  banner: { js: "#!/usr/bin/env node" },
+  external: [...externals].sort(),
+  treeShaking: true,
+  sourcemap: true,
+};

cli/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "paperclipai",
+  "version": "0.3.1",
+  "description": "Paperclip CLI — orchestrate AI agent teams to run a business",
+  "type": "module",
+  "bin": {
+    "paperclipai": "./dist/index.js"
+  },
+  "keywords": [
+    "paperclip",
+    "ai",
+    "agents",
+    "orchestration",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "node --input-type=module -e \"import esbuild from 'esbuild'; import config from './esbuild.config.mjs'; await esbuild.build(config);\" && chmod +x dist/index.js",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "@paperclipai/adapter-claude-local": "workspace:*",
+    "@paperclipai/adapter-codex-local": "workspace:*",
+    "@paperclipai/adapter-cursor-local": "workspace:*",
+    "@paperclipai/adapter-gemini-local": "workspace:*",
+    "@paperclipai/adapter-opencode-local": "workspace:*",
+    "@paperclipai/adapter-pi-local": "workspace:*",
+    "@paperclipai/adapter-openclaw-gateway": "workspace:*",
+    "@paperclipai/adapter-utils": "workspace:*",
+    "@paperclipai/db": "workspace:*",
+    "@paperclipai/server": "workspace:*",
+    "@paperclipai/shared": "workspace:*",
+    "drizzle-orm": "0.38.4",
+    "dotenv": "^17.0.1",
+    "commander": "^13.1.0",
+    "embedded-postgres": "^18.1.0-beta.16",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}

cli/src/__tests__/agent-jwt-env.test.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ensureAgentJwtSecret,
+  mergePaperclipEnvEntries,
+  readAgentJwtSecretFromEnv,
+  readPaperclipEnvEntries,
+  resolveAgentJwtEnvFile,
+} from "../config/env.js";
+import { agentJwtSecretCheck } from "../checks/agent-jwt-secret-check.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function tempConfigPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-jwt-env-"));
+  const configDir = path.join(dir, "custom");
+  fs.mkdirSync(configDir, { recursive: true });
+  return path.join(configDir, "config.json");
+}
+
+describe("agent jwt env helpers", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("writes .env next to explicit config path", () => {
+    const configPath = tempConfigPath();
+    const result = ensureAgentJwtSecret(configPath);
+
+    expect(result.created).toBe(true);
+
+    const envPath = resolveAgentJwtEnvFile(configPath);
+    expect(fs.existsSync(envPath)).toBe(true);
+    const contents = fs.readFileSync(envPath, "utf-8");
+    expect(contents).toContain("PAPERCLIP_AGENT_JWT_SECRET=");
+  });
+
+  it("loads secret from .env next to explicit config path", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+    fs.writeFileSync(envPath, "PAPERCLIP_AGENT_JWT_SECRET=test-secret\n", { mode: 0o600 });
+
+    const loaded = readAgentJwtSecretFromEnv(configPath);
+    expect(loaded).toBe("test-secret");
+    expect(process.env.PAPERCLIP_AGENT_JWT_SECRET).toBe("test-secret");
+  });
+
+  it("doctor check passes when secret exists in adjacent .env", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+    fs.writeFileSync(envPath, "PAPERCLIP_AGENT_JWT_SECRET=check-secret\n", { mode: 0o600 });
+
+    const result = agentJwtSecretCheck(configPath);
+    expect(result.status).toBe("pass");
+  });
+
+  it("quotes hash-prefixed env values so dotenv round-trips them", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+
+    mergePaperclipEnvEntries(
+      {
+        PAPERCLIP_WORKTREE_COLOR: "#439edb",
+      },
+      envPath,
+    );
+
+    const contents = fs.readFileSync(envPath, "utf-8");
+    expect(contents).toContain('PAPERCLIP_WORKTREE_COLOR="#439edb"');
+    expect(readPaperclipEnvEntries(envPath).PAPERCLIP_WORKTREE_COLOR).toBe("#439edb");
+  });
+});

cli/src/__tests__/allowed-hostname.test.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { PaperclipConfig } from "../config/schema.js";
+import { addAllowedHostname } from "../commands/allowed-hostname.js";
+
+function createTempConfigPath() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-allowed-hostname-"));
+  return path.join(dir, "config.json");
+}
+
+function writeBaseConfig(configPath: string) {
+  const base: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: "/tmp/paperclip-db",
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: "/tmp/paperclip-backups",
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: "/tmp/paperclip-logs",
+    },
+    server: {
+      deploymentMode: "authenticated",
+      exposure: "private",
+      host: "0.0.0.0",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: { baseDir: "/tmp/paperclip-storage" },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: { keyFilePath: "/tmp/paperclip-secrets/master.key" },
+    },
+  };
+  fs.writeFileSync(configPath, JSON.stringify(base, null, 2));
+}
+
+describe("allowed-hostname command", () => {
+  it("adds and normalizes hostnames", async () => {
+    const configPath = createTempConfigPath();
+    writeBaseConfig(configPath);
+
+    await addAllowedHostname("https://Dotta-MacBook-Pro:3100", { config: configPath });
+    await addAllowedHostname("dotta-macbook-pro", { config: configPath });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as PaperclipConfig;
+    expect(raw.server.allowedHostnames).toEqual(["dotta-macbook-pro"]);
+  });
+});

cli/src/__tests__/common.test.ts

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { writeContext } from "../client/context.js";
+import { resolveCommandContext } from "../commands/client/common.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function createTempPath(name: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-common-"));
+  return path.join(dir, name);
+}
+
+describe("resolveCommandContext", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_API_URL;
+    delete process.env.PAPERCLIP_API_KEY;
+    delete process.env.PAPERCLIP_COMPANY_ID;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("uses profile defaults when options/env are not provided", () => {
+    const contextPath = createTempPath("context.json");
+
+    writeContext(
+      {
+        version: 1,
+        currentProfile: "ops",
+        profiles: {
+          ops: {
+            apiBase: "http://127.0.0.1:9999",
+            companyId: "company-profile",
+            apiKeyEnvVarName: "AGENT_KEY",
+          },
+        },
+      },
+      contextPath,
+    );
+    process.env.AGENT_KEY = "key-from-env";
+
+    const resolved = resolveCommandContext({ context: contextPath }, { requireCompany: true });
+    expect(resolved.api.apiBase).toBe("http://127.0.0.1:9999");
+    expect(resolved.companyId).toBe("company-profile");
+    expect(resolved.api.apiKey).toBe("key-from-env");
+  });
+
+  it("prefers explicit options over profile values", () => {
+    const contextPath = createTempPath("context.json");
+    writeContext(
+      {
+        version: 1,
+        currentProfile: "default",
+        profiles: {
+          default: {
+            apiBase: "http://profile:3100",
+            companyId: "company-profile",
+          },
+        },
+      },
+      contextPath,
+    );
+
+    const resolved = resolveCommandContext(
+      {
+        context: contextPath,
+        apiBase: "http://override:3200",
+        apiKey: "direct-token",
+        companyId: "company-override",
+      },
+      { requireCompany: true },
+    );
+
+    expect(resolved.api.apiBase).toBe("http://override:3200");
+    expect(resolved.companyId).toBe("company-override");
+    expect(resolved.api.apiKey).toBe("direct-token");
+  });
+
+  it("throws when company is required but unresolved", () => {
+    const contextPath = createTempPath("context.json");
+    writeContext(
+      {
+        version: 1,
+        currentProfile: "default",
+        profiles: { default: {} },
+      },
+      contextPath,
+    );
+
+    expect(() =>
+      resolveCommandContext({ context: contextPath, apiBase: "http://localhost:3100" }, { requireCompany: true }),
+    ).toThrow(/Company ID is required/);
+  });
+});

cli/src/__tests__/company-delete.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import type { Company } from "@paperclipai/shared";
+import { assertDeleteConfirmation, resolveCompanyForDeletion } from "../commands/client/company.js";
+
+function makeCompany(overrides: Partial<Company>): Company {
+  return {
+    id: "11111111-1111-1111-1111-111111111111",
+    name: "Alpha",
+    description: null,
+    status: "active",
+    pauseReason: null,
+    pausedAt: null,
+    issuePrefix: "ALP",
+    issueCounter: 1,
+    budgetMonthlyCents: 0,
+    spentMonthlyCents: 0,
+    requireBoardApprovalForNewAgents: false,
+    brandColor: null,
+    logoAssetId: null,
+    logoUrl: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe("resolveCompanyForDeletion", () => {
+  const companies: Company[] = [
+    makeCompany({
+      id: "11111111-1111-1111-1111-111111111111",
+      name: "Alpha",
+      issuePrefix: "ALP",
+    }),
+    makeCompany({
+      id: "22222222-2222-2222-2222-222222222222",
+      name: "Paperclip",
+      issuePrefix: "PAP",
+    }),
+  ];
+
+  it("resolves by ID in auto mode", () => {
+    const result = resolveCompanyForDeletion(companies, "22222222-2222-2222-2222-222222222222", "auto");
+    expect(result.issuePrefix).toBe("PAP");
+  });
+
+  it("resolves by prefix in auto mode", () => {
+    const result = resolveCompanyForDeletion(companies, "pap", "auto");
+    expect(result.id).toBe("22222222-2222-2222-2222-222222222222");
+  });
+
+  it("throws when selector is not found", () => {
+    expect(() => resolveCompanyForDeletion(companies, "MISSING", "auto")).toThrow(/No company found/);
+  });
+
+  it("respects explicit id mode", () => {
+    expect(() => resolveCompanyForDeletion(companies, "PAP", "id")).toThrow(/No company found by ID/);
+  });
+
+  it("respects explicit prefix mode", () => {
+    expect(() => resolveCompanyForDeletion(companies, "22222222-2222-2222-2222-222222222222", "prefix"))
+      .toThrow(/No company found by shortname/);
+  });
+});
+
+describe("assertDeleteConfirmation", () => {
+  const company = makeCompany({
+    id: "22222222-2222-2222-2222-222222222222",
+    issuePrefix: "PAP",
+  });
+
+  it("requires --yes", () => {
+    expect(() => assertDeleteConfirmation(company, { confirm: "PAP" })).toThrow(/requires --yes/);
+  });
+
+  it("accepts matching prefix confirmation", () => {
+    expect(() => assertDeleteConfirmation(company, { yes: true, confirm: "pap" })).not.toThrow();
+  });
+
+  it("accepts matching id confirmation", () => {
+    expect(() =>
+      assertDeleteConfirmation(company, {
+        yes: true,
+        confirm: "22222222-2222-2222-2222-222222222222",
+      })).not.toThrow();
+  });
+
+  it("rejects mismatched confirmation", () => {
+    expect(() => assertDeleteConfirmation(company, { yes: true, confirm: "nope" }))
+      .toThrow(/does not match target company/);
+  });
+});

cli/src/__tests__/context.test.ts

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  defaultClientContext,
+  readContext,
+  setCurrentProfile,
+  upsertProfile,
+  writeContext,
+} from "../client/context.js";
+
+function createTempContextPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-context-"));
+  return path.join(dir, "context.json");
+}
+
+describe("client context store", () => {
+  it("returns default context when file does not exist", () => {
+    const contextPath = createTempContextPath();
+    const context = readContext(contextPath);
+    expect(context).toEqual(defaultClientContext());
+  });
+
+  it("upserts profile values and switches current profile", () => {
+    const contextPath = createTempContextPath();
+
+    upsertProfile(
+      "work",
+      {
+        apiBase: "http://localhost:3100",
+        companyId: "company-123",
+        apiKeyEnvVarName: "PAPERCLIP_AGENT_TOKEN",
+      },
+      contextPath,
+    );
+
+    setCurrentProfile("work", contextPath);
+    const context = readContext(contextPath);
+
+    expect(context.currentProfile).toBe("work");
+    expect(context.profiles.work).toEqual({
+      apiBase: "http://localhost:3100",
+      companyId: "company-123",
+      apiKeyEnvVarName: "PAPERCLIP_AGENT_TOKEN",
+    });
+  });
+
+  it("normalizes invalid file content to safe defaults", () => {
+    const contextPath = createTempContextPath();
+    writeContext(
+      {
+        version: 1,
+        currentProfile: "x",
+        profiles: {
+          x: {
+            apiBase: " ",
+            companyId: " ",
+            apiKeyEnvVarName: " ",
+          },
+        },
+      },
+      contextPath,
+    );
+
+    const context = readContext(contextPath);
+    expect(context.currentProfile).toBe("x");
+    expect(context.profiles.x).toEqual({});
+  });
+});

cli/src/__tests__/data-dir.test.ts

@@ -0,0 +1,79 @@
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { applyDataDirOverride } from "../config/data-dir.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+describe("applyDataDirOverride", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.PAPERCLIP_CONTEXT;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("sets PAPERCLIP_HOME and isolated default config/context paths", () => {
+    const home = applyDataDirOverride({
+      dataDir: "~/paperclip-data",
+      config: undefined,
+      context: undefined,
+    }, { hasConfigOption: true, hasContextOption: true });
+
+    const expectedHome = path.resolve(os.homedir(), "paperclip-data");
+    expect(home).toBe(expectedHome);
+    expect(process.env.PAPERCLIP_HOME).toBe(expectedHome);
+    expect(process.env.PAPERCLIP_CONFIG).toBe(
+      path.resolve(expectedHome, "instances", "default", "config.json"),
+    );
+    expect(process.env.PAPERCLIP_CONTEXT).toBe(path.resolve(expectedHome, "context.json"));
+    expect(process.env.PAPERCLIP_INSTANCE_ID).toBe("default");
+  });
+
+  it("uses the provided instance id when deriving default config path", () => {
+    const home = applyDataDirOverride({
+      dataDir: "/tmp/paperclip-alt",
+      instance: "dev_1",
+      config: undefined,
+      context: undefined,
+    }, { hasConfigOption: true, hasContextOption: true });
+
+    expect(home).toBe(path.resolve("/tmp/paperclip-alt"));
+    expect(process.env.PAPERCLIP_INSTANCE_ID).toBe("dev_1");
+    expect(process.env.PAPERCLIP_CONFIG).toBe(
+      path.resolve("/tmp/paperclip-alt", "instances", "dev_1", "config.json"),
+    );
+  });
+
+  it("does not override explicit config/context settings", () => {
+    process.env.PAPERCLIP_CONFIG = "/env/config.json";
+    process.env.PAPERCLIP_CONTEXT = "/env/context.json";
+
+    applyDataDirOverride({
+      dataDir: "/tmp/paperclip-alt",
+      config: "/flag/config.json",
+      context: "/flag/context.json",
+    }, { hasConfigOption: true, hasContextOption: true });
+
+    expect(process.env.PAPERCLIP_CONFIG).toBe("/env/config.json");
+    expect(process.env.PAPERCLIP_CONTEXT).toBe("/env/context.json");
+  });
+
+  it("only applies defaults for options supported by the command", () => {
+    applyDataDirOverride(
+      {
+        dataDir: "/tmp/paperclip-alt",
+      },
+      { hasConfigOption: false, hasContextOption: false },
+    );
+
+    expect(process.env.PAPERCLIP_HOME).toBe(path.resolve("/tmp/paperclip-alt"));
+    expect(process.env.PAPERCLIP_CONFIG).toBeUndefined();
+    expect(process.env.PAPERCLIP_CONTEXT).toBeUndefined();
+  });
+});

cli/src/__tests__/doctor.test.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { doctor } from "../commands/doctor.js";
+import { writeConfig } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function createTempConfig(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-doctor-"));
+  const configPath = path.join(root, ".paperclip", "config.json");
+  const runtimeRoot = path.join(root, "runtime");
+
+  const config: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-10T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(runtimeRoot, "db"),
+      embeddedPostgresPort: 55432,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(runtimeRoot, "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(runtimeRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3199,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(runtimeRoot, "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(runtimeRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  writeConfig(config, configPath);
+  return configPath;
+}
+
+describe("doctor", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("re-runs repairable checks so repaired failures do not remain blocking", async () => {
+    const configPath = createTempConfig();
+
+    const summary = await doctor({
+      config: configPath,
+      repair: true,
+      yes: true,
+    });
+
+    expect(summary.failed).toBe(0);
+    expect(summary.warned).toBe(0);
+    expect(process.env.PAPERCLIP_AGENT_JWT_SECRET).toBeTruthy();
+  });
+});

cli/src/__tests__/home-paths.test.ts

@@ -0,0 +1,44 @@
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  describeLocalInstancePaths,
+  expandHomePrefix,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+} from "../config/home.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+describe("home path resolution", () => {
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("defaults to ~/.paperclip and default instance", () => {
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+
+    const paths = describeLocalInstancePaths();
+    expect(paths.homeDir).toBe(path.resolve(os.homedir(), ".paperclip"));
+    expect(paths.instanceId).toBe("default");
+    expect(paths.configPath).toBe(path.resolve(os.homedir(), ".paperclip", "instances", "default", "config.json"));
+  });
+
+  it("supports PAPERCLIP_HOME and explicit instance ids", () => {
+    process.env.PAPERCLIP_HOME = "~/paperclip-home";
+
+    const home = resolvePaperclipHomeDir();
+    expect(home).toBe(path.resolve(os.homedir(), "paperclip-home"));
+    expect(resolvePaperclipInstanceId("dev_1")).toBe("dev_1");
+  });
+
+  it("rejects invalid instance ids", () => {
+    expect(() => resolvePaperclipInstanceId("bad/id")).toThrow(/Invalid instance id/);
+  });
+
+  it("expands ~ prefixes", () => {
+    expect(expandHomePrefix("~")).toBe(os.homedir());
+    expect(expandHomePrefix("~/x/y")).toBe(path.resolve(os.homedir(), "x/y"));
+  });
+});

cli/src/__tests__/http.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ApiRequestError, PaperclipApiClient } from "../client/http.js";
+
+describe("PaperclipApiClient", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("adds authorization and run-id headers", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new PaperclipApiClient({
+      apiBase: "http://localhost:3100",
+      apiKey: "token-123",
+      runId: "run-abc",
+    });
+
+    await client.post("/api/test", { hello: "world" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const call = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(call[0]).toContain("/api/test");
+
+    const headers = call[1].headers as Record<string, string>;
+    expect(headers.authorization).toBe("Bearer token-123");
+    expect(headers["x-paperclip-run-id"]).toBe("run-abc");
+    expect(headers["content-type"]).toBe("application/json");
+  });
+
+  it("returns null on ignoreNotFound", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ error: "Not found" }), { status: 404 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new PaperclipApiClient({ apiBase: "http://localhost:3100" });
+    const result = await client.get("/api/missing", { ignoreNotFound: true });
+    expect(result).toBeNull();
+  });
+
+  it("throws ApiRequestError with details", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({ error: "Issue checkout conflict", details: { issueId: "1" } }),
+        { status: 409 },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new PaperclipApiClient({ apiBase: "http://localhost:3100" });
+
+    await expect(client.post("/api/issues/1/checkout", {})).rejects.toMatchObject({
+      status: 409,
+      message: "Issue checkout conflict",
+      details: { issueId: "1" },
+    } satisfies Partial<ApiRequestError>);
+  });
+});

cli/src/__tests__/worktree.test.ts

@@ -0,0 +1,472 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  copyGitHooksToWorktreeGitDir,
+  copySeededSecretsKey,
+  rebindWorkspaceCwd,
+  resolveSourceConfigPath,
+  resolveGitWorktreeAddArgs,
+  resolveWorktreeMakeTargetPath,
+  worktreeInitCommand,
+  worktreeMakeCommand,
+} from "../commands/worktree.js";
+import {
+  buildWorktreeConfig,
+  buildWorktreeEnvEntries,
+  formatShellExports,
+  generateWorktreeColor,
+  resolveWorktreeSeedPlan,
+  resolveWorktreeLocalPaths,
+  rewriteLocalUrlPort,
+  sanitizeWorktreeInstanceId,
+} from "../commands/worktree-lib.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_CWD = process.cwd();
+const ORIGINAL_ENV = { ...process.env };
+
+afterEach(() => {
+  process.chdir(ORIGINAL_CWD);
+  for (const key of Object.keys(process.env)) {
+    if (!(key in ORIGINAL_ENV)) delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+function buildSourceConfig(): PaperclipConfig {
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-09T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: "/tmp/main/db",
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: "/tmp/main/backups",
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: "/tmp/main/logs",
+    },
+    server: {
+      deploymentMode: "authenticated",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: ["localhost"],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "explicit",
+      publicBaseUrl: "http://127.0.0.1:3100",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: "/tmp/main/storage",
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: "/tmp/main/secrets/master.key",
+      },
+    },
+  };
+}
+
+describe("worktree helpers", () => {
+  it("sanitizes instance ids", () => {
+    expect(sanitizeWorktreeInstanceId("feature/worktree-support")).toBe("feature-worktree-support");
+    expect(sanitizeWorktreeInstanceId("  ")).toBe("worktree");
+  });
+
+  it("resolves worktree:make target paths under the user home directory", () => {
+    expect(resolveWorktreeMakeTargetPath("paperclip-pr-432")).toBe(
+      path.resolve(os.homedir(), "paperclip-pr-432"),
+    );
+  });
+
+  it("rejects worktree:make names that are not safe directory/branch names", () => {
+    expect(() => resolveWorktreeMakeTargetPath("paperclip/pr-432")).toThrow(
+      "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",
+    );
+  });
+
+  it("builds git worktree add args for new and existing branches", () => {
+    expect(
+      resolveGitWorktreeAddArgs({
+        branchName: "feature-branch",
+        targetPath: "/tmp/feature-branch",
+        branchExists: false,
+      }),
+    ).toEqual(["worktree", "add", "-b", "feature-branch", "/tmp/feature-branch", "HEAD"]);
+
+    expect(
+      resolveGitWorktreeAddArgs({
+        branchName: "feature-branch",
+        targetPath: "/tmp/feature-branch",
+        branchExists: true,
+      }),
+    ).toEqual(["worktree", "add", "/tmp/feature-branch", "feature-branch"]);
+  });
+
+  it("builds git worktree add args with a start point", () => {
+    expect(
+      resolveGitWorktreeAddArgs({
+        branchName: "my-worktree",
+        targetPath: "/tmp/my-worktree",
+        branchExists: false,
+        startPoint: "public-gh/master",
+      }),
+    ).toEqual(["worktree", "add", "-b", "my-worktree", "/tmp/my-worktree", "public-gh/master"]);
+  });
+
+  it("uses start point even when a local branch with the same name exists", () => {
+    expect(
+      resolveGitWorktreeAddArgs({
+        branchName: "my-worktree",
+        targetPath: "/tmp/my-worktree",
+        branchExists: true,
+        startPoint: "origin/main",
+      }),
+    ).toEqual(["worktree", "add", "-b", "my-worktree", "/tmp/my-worktree", "origin/main"]);
+  });
+
+  it("rewrites loopback auth URLs to the new port only", () => {
+    expect(rewriteLocalUrlPort("http://127.0.0.1:3100", 3110)).toBe("http://127.0.0.1:3110/");
+    expect(rewriteLocalUrlPort("https://paperclip.example", 3110)).toBe("https://paperclip.example");
+  });
+
+  it("builds isolated config and env paths for a worktree", () => {
+    const paths = resolveWorktreeLocalPaths({
+      cwd: "/tmp/paperclip-feature",
+      homeDir: "/tmp/paperclip-worktrees",
+      instanceId: "feature-worktree-support",
+    });
+    const config = buildWorktreeConfig({
+      sourceConfig: buildSourceConfig(),
+      paths,
+      serverPort: 3110,
+      databasePort: 54339,
+      now: new Date("2026-03-09T12:00:00.000Z"),
+    });
+
+    expect(config.database.embeddedPostgresDataDir).toBe(
+      path.resolve("/tmp/paperclip-worktrees", "instances", "feature-worktree-support", "db"),
+    );
+    expect(config.database.embeddedPostgresPort).toBe(54339);
+    expect(config.server.port).toBe(3110);
+    expect(config.auth.publicBaseUrl).toBe("http://127.0.0.1:3110/");
+    expect(config.storage.localDisk.baseDir).toBe(
+      path.resolve("/tmp/paperclip-worktrees", "instances", "feature-worktree-support", "data", "storage"),
+    );
+
+    const env = buildWorktreeEnvEntries(paths, {
+      name: "feature-worktree-support",
+      color: "#3abf7a",
+    });
+    expect(env.PAPERCLIP_HOME).toBe(path.resolve("/tmp/paperclip-worktrees"));
+    expect(env.PAPERCLIP_INSTANCE_ID).toBe("feature-worktree-support");
+    expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
+    expect(env.PAPERCLIP_WORKTREE_NAME).toBe("feature-worktree-support");
+    expect(env.PAPERCLIP_WORKTREE_COLOR).toBe("#3abf7a");
+    expect(formatShellExports(env)).toContain("export PAPERCLIP_INSTANCE_ID='feature-worktree-support'");
+  });
+
+  it("generates vivid worktree colors as hex", () => {
+    expect(generateWorktreeColor()).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it("uses minimal seed mode to keep app state but drop heavy runtime history", () => {
+    const minimal = resolveWorktreeSeedPlan("minimal");
+    const full = resolveWorktreeSeedPlan("full");
+
+    expect(minimal.excludedTables).toContain("heartbeat_runs");
+    expect(minimal.excludedTables).toContain("heartbeat_run_events");
+    expect(minimal.excludedTables).toContain("workspace_runtime_services");
+    expect(minimal.excludedTables).toContain("agent_task_sessions");
+    expect(minimal.nullifyColumns.issues).toEqual(["checkout_run_id", "execution_run_id"]);
+
+    expect(full.excludedTables).toEqual([]);
+    expect(full.nullifyColumns).toEqual({});
+  });
+
+  it("copies the source local_encrypted secrets key into the seeded worktree instance", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
+    const originalInlineMasterKey = process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+    const originalKeyFile = process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+    try {
+      delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+      delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
+      const sourceKeyPath = path.join(tempRoot, "source", "secrets", "master.key");
+      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
+      fs.mkdirSync(path.dirname(sourceKeyPath), { recursive: true });
+      fs.writeFileSync(sourceKeyPath, "source-master-key", "utf8");
+
+      const sourceConfig = buildSourceConfig();
+      sourceConfig.secrets.localEncrypted.keyFilePath = sourceKeyPath;
+
+      copySeededSecretsKey({
+        sourceConfigPath,
+        sourceConfig,
+        sourceEnvEntries: {},
+        targetKeyFilePath: targetKeyPath,
+      });
+
+      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("source-master-key");
+    } finally {
+      if (originalInlineMasterKey === undefined) {
+        delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+      } else {
+        process.env.PAPERCLIP_SECRETS_MASTER_KEY = originalInlineMasterKey;
+      }
+      if (originalKeyFile === undefined) {
+        delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+      } else {
+        process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = originalKeyFile;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("writes the source inline secrets master key into the seeded worktree instance", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
+    try {
+      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
+      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
+
+      copySeededSecretsKey({
+        sourceConfigPath,
+        sourceConfig: buildSourceConfig(),
+        sourceEnvEntries: {
+          PAPERCLIP_SECRETS_MASTER_KEY: "inline-source-master-key",
+        },
+        targetKeyFilePath: targetKeyPath,
+      });
+
+      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("inline-source-master-key");
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("persists the current agent jwt secret into the worktree env file", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-jwt-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const originalCwd = process.cwd();
+    const originalJwtSecret = process.env.PAPERCLIP_AGENT_JWT_SECRET;
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      process.env.PAPERCLIP_AGENT_JWT_SECRET = "worktree-shared-secret";
+      process.chdir(repoRoot);
+
+      await worktreeInitCommand({
+        seed: false,
+        fromConfig: path.join(tempRoot, "missing", "config.json"),
+        home: path.join(tempRoot, ".paperclip-worktrees"),
+      });
+
+      const envPath = path.join(repoRoot, ".paperclip", ".env");
+      const envContents = fs.readFileSync(envPath, "utf8");
+      expect(envContents).toContain("PAPERCLIP_AGENT_JWT_SECRET=worktree-shared-secret");
+      expect(envContents).toContain("PAPERCLIP_WORKTREE_NAME=repo");
+      expect(envContents).toMatch(/PAPERCLIP_WORKTREE_COLOR=\"#[0-9a-f]{6}\"/);
+    } finally {
+      process.chdir(originalCwd);
+      if (originalJwtSecret === undefined) {
+        delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+      } else {
+        process.env.PAPERCLIP_AGENT_JWT_SECRET = originalJwtSecret;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("defaults the seed source config to the current repo-local Paperclip config", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-source-config-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const localConfigPath = path.join(repoRoot, ".paperclip", "config.json");
+    const originalCwd = process.cwd();
+    const originalPaperclipConfig = process.env.PAPERCLIP_CONFIG;
+
+    try {
+      fs.mkdirSync(path.dirname(localConfigPath), { recursive: true });
+      fs.writeFileSync(localConfigPath, JSON.stringify(buildSourceConfig()), "utf8");
+      delete process.env.PAPERCLIP_CONFIG;
+      process.chdir(repoRoot);
+
+      expect(fs.realpathSync(resolveSourceConfigPath({}))).toBe(fs.realpathSync(localConfigPath));
+    } finally {
+      process.chdir(originalCwd);
+      if (originalPaperclipConfig === undefined) {
+        delete process.env.PAPERCLIP_CONFIG;
+      } else {
+        process.env.PAPERCLIP_CONFIG = originalPaperclipConfig;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves the source config path across worktree:make cwd changes", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-source-override-"));
+    const sourceConfigPath = path.join(tempRoot, "source", "config.json");
+    const targetRoot = path.join(tempRoot, "target");
+    const originalCwd = process.cwd();
+    const originalPaperclipConfig = process.env.PAPERCLIP_CONFIG;
+
+    try {
+      fs.mkdirSync(path.dirname(sourceConfigPath), { recursive: true });
+      fs.mkdirSync(targetRoot, { recursive: true });
+      fs.writeFileSync(sourceConfigPath, JSON.stringify(buildSourceConfig()), "utf8");
+      delete process.env.PAPERCLIP_CONFIG;
+      process.chdir(targetRoot);
+
+      expect(resolveSourceConfigPath({ sourceConfigPathOverride: sourceConfigPath })).toBe(
+        path.resolve(sourceConfigPath),
+      );
+    } finally {
+      process.chdir(originalCwd);
+      if (originalPaperclipConfig === undefined) {
+        delete process.env.PAPERCLIP_CONFIG;
+      } else {
+        process.env.PAPERCLIP_CONFIG = originalPaperclipConfig;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("rebinds same-repo workspace paths onto the current worktree root", () => {
+    expect(
+      rebindWorkspaceCwd({
+        sourceRepoRoot: "/Users/example/paperclip",
+        targetRepoRoot: "/Users/example/paperclip-pr-432",
+        workspaceCwd: "/Users/example/paperclip",
+      }),
+    ).toBe("/Users/example/paperclip-pr-432");
+
+    expect(
+      rebindWorkspaceCwd({
+        sourceRepoRoot: "/Users/example/paperclip",
+        targetRepoRoot: "/Users/example/paperclip-pr-432",
+        workspaceCwd: "/Users/example/paperclip/packages/db",
+      }),
+    ).toBe("/Users/example/paperclip-pr-432/packages/db");
+  });
+
+  it("does not rebind paths outside the source repo root", () => {
+    expect(
+      rebindWorkspaceCwd({
+        sourceRepoRoot: "/Users/example/paperclip",
+        targetRepoRoot: "/Users/example/paperclip-pr-432",
+        workspaceCwd: "/Users/example/other-project",
+      }),
+    ).toBeNull();
+  });
+
+  it("copies shared git hooks into a linked worktree git dir", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-hooks-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const worktreePath = path.join(tempRoot, "repo-feature");
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
+      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
+
+      const sourceHooksDir = path.join(repoRoot, ".git", "hooks");
+      const sourceHookPath = path.join(sourceHooksDir, "pre-commit");
+      const sourceTokensPath = path.join(sourceHooksDir, "forbidden-tokens.txt");
+      fs.writeFileSync(sourceHookPath, "#!/usr/bin/env bash\nexit 0\n", { encoding: "utf8", mode: 0o755 });
+      fs.chmodSync(sourceHookPath, 0o755);
+      fs.writeFileSync(sourceTokensPath, "secret-token\n", "utf8");
+
+      execFileSync("git", ["worktree", "add", "--detach", worktreePath], { cwd: repoRoot, stdio: "ignore" });
+
+      const copied = copyGitHooksToWorktreeGitDir(worktreePath);
+      const worktreeGitDir = execFileSync("git", ["rev-parse", "--git-dir"], {
+        cwd: worktreePath,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+      const resolvedSourceHooksDir = fs.realpathSync(sourceHooksDir);
+      const resolvedTargetHooksDir = fs.realpathSync(path.resolve(worktreePath, worktreeGitDir, "hooks"));
+      const targetHookPath = path.join(resolvedTargetHooksDir, "pre-commit");
+      const targetTokensPath = path.join(resolvedTargetHooksDir, "forbidden-tokens.txt");
+
+      expect(copied).toMatchObject({
+        sourceHooksPath: resolvedSourceHooksDir,
+        targetHooksPath: resolvedTargetHooksDir,
+        copied: true,
+      });
+      expect(fs.readFileSync(targetHookPath, "utf8")).toBe("#!/usr/bin/env bash\nexit 0\n");
+      expect(fs.statSync(targetHookPath).mode & 0o111).not.toBe(0);
+      expect(fs.readFileSync(targetTokensPath, "utf8")).toBe("secret-token\n");
+    } finally {
+      execFileSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: repoRoot, stdio: "ignore" });
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("creates and initializes a worktree from the top-level worktree:make command", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-make-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const fakeHome = path.join(tempRoot, "home");
+    const worktreePath = path.join(fakeHome, "paperclip-make-test");
+    const originalCwd = process.cwd();
+    const homedirSpy = vi.spyOn(os, "homedir").mockReturnValue(fakeHome);
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      fs.mkdirSync(fakeHome, { recursive: true });
+      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
+      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
+
+      process.chdir(repoRoot);
+
+      await worktreeMakeCommand("paperclip-make-test", {
+        seed: false,
+        home: path.join(tempRoot, ".paperclip-worktrees"),
+      });
+
+      expect(fs.existsSync(path.join(worktreePath, ".git"))).toBe(true);
+      expect(fs.existsSync(path.join(worktreePath, ".paperclip", "config.json"))).toBe(true);
+      expect(fs.existsSync(path.join(worktreePath, ".paperclip", ".env"))).toBe(true);
+    } finally {
+      process.chdir(originalCwd);
+      homedirSpy.mockRestore();
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  }, 20_000);
+});

cli/src/adapters/http/format-event.ts

@@ -0,0 +1,4 @@
+export function printHttpStdoutEvent(raw: string, _debug: boolean): void {
+  const line = raw.trim();
+  if (line) console.log(line);
+}

cli/src/adapters/http/index.ts

@@ -0,0 +1,7 @@
+import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
+import { printHttpStdoutEvent } from "./format-event.js";
+
+export const httpCLIAdapter: CLIAdapterModule = {
+  type: "http",
+  formatStdoutEvent: printHttpStdoutEvent,
+};

cli/src/adapters/index.ts

@@ -0,0 +1,2 @@
+export { getCLIAdapter } from "./registry.js";
+export type { CLIAdapterModule } from "@paperclipai/adapter-utils";

cli/src/adapters/process/format-event.ts

@@ -0,0 +1,4 @@
+export function printProcessStdoutEvent(raw: string, _debug: boolean): void {
+  const line = raw.trim();
+  if (line) console.log(line);
+}

cli/src/adapters/process/index.ts

@@ -0,0 +1,7 @@
+import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
+import { printProcessStdoutEvent } from "./format-event.js";
+
+export const processCLIAdapter: CLIAdapterModule = {
+  type: "process",
+  formatStdoutEvent: printProcessStdoutEvent,
+};

cli/src/adapters/registry.ts

@@ -0,0 +1,63 @@
+import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
+import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
+import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
+import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
+import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
+import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
+import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
+import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";
+import { processCLIAdapter } from "./process/index.js";
+import { httpCLIAdapter } from "./http/index.js";
+
+const claudeLocalCLIAdapter: CLIAdapterModule = {
+  type: "claude_local",
+  formatStdoutEvent: printClaudeStreamEvent,
+};
+
+const codexLocalCLIAdapter: CLIAdapterModule = {
+  type: "codex_local",
+  formatStdoutEvent: printCodexStreamEvent,
+};
+
+const openCodeLocalCLIAdapter: CLIAdapterModule = {
+  type: "opencode_local",
+  formatStdoutEvent: printOpenCodeStreamEvent,
+};
+
+const piLocalCLIAdapter: CLIAdapterModule = {
+  type: "pi_local",
+  formatStdoutEvent: printPiStreamEvent,
+};
+
+const cursorLocalCLIAdapter: CLIAdapterModule = {
+  type: "cursor",
+  formatStdoutEvent: printCursorStreamEvent,
+};
+
+const geminiLocalCLIAdapter: CLIAdapterModule = {
+  type: "gemini_local",
+  formatStdoutEvent: printGeminiStreamEvent,
+};
+
+const openclawGatewayCLIAdapter: CLIAdapterModule = {
+  type: "openclaw_gateway",
+  formatStdoutEvent: printOpenClawGatewayStreamEvent,
+};
+
+const adaptersByType = new Map<string, CLIAdapterModule>(
+  [
+    claudeLocalCLIAdapter,
+    codexLocalCLIAdapter,
+    openCodeLocalCLIAdapter,
+    piLocalCLIAdapter,
+    cursorLocalCLIAdapter,
+    geminiLocalCLIAdapter,
+    openclawGatewayCLIAdapter,
+    processCLIAdapter,
+    httpCLIAdapter,
+  ].map((a) => [a.type, a]),
+);
+
+export function getCLIAdapter(type: string): CLIAdapterModule {
+  return adaptersByType.get(type) ?? processCLIAdapter;
+}

cli/src/checks/agent-jwt-secret-check.ts

@@ -0,0 +1,40 @@
+import {
+  ensureAgentJwtSecret,
+  readAgentJwtSecretFromEnv,
+  readAgentJwtSecretFromEnvFile,
+  resolveAgentJwtEnvFile,
+} from "../config/env.js";
+import type { CheckResult } from "./index.js";
+
+export function agentJwtSecretCheck(configPath?: string): CheckResult {
+  if (readAgentJwtSecretFromEnv(configPath)) {
+    return {
+      name: "Agent JWT secret",
+      status: "pass",
+      message: "PAPERCLIP_AGENT_JWT_SECRET is set in environment",
+    };
+  }
+
+  const envPath = resolveAgentJwtEnvFile(configPath);
+  const fileSecret = readAgentJwtSecretFromEnvFile(envPath);
+
+  if (fileSecret) {
+    return {
+      name: "Agent JWT secret",
+      status: "warn",
+      message: `PAPERCLIP_AGENT_JWT_SECRET is present in ${envPath} but not loaded into environment`,
+      repairHint: `Set the value from ${envPath} in your shell before starting the Paperclip server`,
+    };
+  }
+
+  return {
+    name: "Agent JWT secret",
+    status: "fail",
+    message: `PAPERCLIP_AGENT_JWT_SECRET missing from environment and ${envPath}`,
+    canRepair: true,
+    repair: () => {
+      ensureAgentJwtSecret(configPath);
+    },
+    repairHint: `Run with --repair to create ${envPath} containing PAPERCLIP_AGENT_JWT_SECRET`,
+  };
+}

cli/src/checks/config-check.ts

@@ -0,0 +1,33 @@
+import { readConfig, configExists, resolveConfigPath } from "../config/store.js";
+import type { CheckResult } from "./index.js";
+
+export function configCheck(configPath?: string): CheckResult {
+  const filePath = resolveConfigPath(configPath);
+
+  if (!configExists(configPath)) {
+    return {
+      name: "Config file",
+      status: "fail",
+      message: `Config file not found at ${filePath}`,
+      canRepair: false,
+      repairHint: "Run `paperclipai onboard` to create one",
+    };
+  }
+
+  try {
+    readConfig(configPath);
+    return {
+      name: "Config file",
+      status: "pass",
+      message: `Valid config at ${filePath}`,
+    };
+  } catch (err) {
+    return {
+      name: "Config file",
+      status: "fail",
+      message: `Invalid config: ${err instanceof Error ? err.message : String(err)}`,
+      canRepair: false,
+      repairHint: "Run `paperclipai configure --section database` (or `paperclipai onboard` to recreate)",
+    };
+  }
+}

cli/src/checks/database-check.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import type { PaperclipConfig } from "../config/schema.js";
+import type { CheckResult } from "./index.js";
+import { resolveRuntimeLikePath } from "./path-resolver.js";
+
+export async function databaseCheck(config: PaperclipConfig, configPath?: string): Promise<CheckResult> {
+  if (config.database.mode === "postgres") {
+    if (!config.database.connectionString) {
+      return {
+        name: "Database",
+        status: "fail",
+        message: "PostgreSQL mode selected but no connection string configured",
+        canRepair: false,
+        repairHint: "Run `paperclipai configure --section database`",
+      };
+    }
+
+    try {
+      const { createDb } = await import("@paperclipai/db");
+      const db = createDb(config.database.connectionString);
+      await db.execute("SELECT 1");
+      return {
+        name: "Database",
+        status: "pass",
+        message: "PostgreSQL connection successful",
+      };
+    } catch (err) {
+      return {
+        name: "Database",
+        status: "fail",
+        message: `Cannot connect to PostgreSQL: ${err instanceof Error ? err.message : String(err)}`,
+        canRepair: false,
+        repairHint: "Check your connection string and ensure PostgreSQL is running",
+      };
+    }
+  }
+
+  if (config.database.mode === "embedded-postgres") {
+    const dataDir = resolveRuntimeLikePath(config.database.embeddedPostgresDataDir, configPath);
+    const reportedPath = dataDir;
+    if (!fs.existsSync(dataDir)) {
+      fs.mkdirSync(reportedPath, { recursive: true });
+    }
+
+    return {
+      name: "Database",
+      status: "pass",
+      message: `Embedded PostgreSQL configured at ${dataDir} (port ${config.database.embeddedPostgresPort})`,
+    };
+  }
+
+  return {
+    name: "Database",
+    status: "fail",
+    message: `Unknown database mode: ${String(config.database.mode)}`,
+    canRepair: false,
+    repairHint: "Run `paperclipai configure --section database`",
+  };
+}

cli/src/checks/deployment-auth-check.ts

@@ -0,0 +1,91 @@
+import type { PaperclipConfig } from "../config/schema.js";
+import type { CheckResult } from "./index.js";
+
+function isLoopbackHost(host: string) {
+  const normalized = host.trim().toLowerCase();
+  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+
+export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {
+  const mode = config.server.deploymentMode;
+  const exposure = config.server.exposure;
+  const auth = config.auth;
+
+  if (mode === "local_trusted") {
+    if (!isLoopbackHost(config.server.host)) {
+      return {
+        name: "Deployment/auth mode",
+        status: "fail",
+        message: `local_trusted requires loopback host binding (found ${config.server.host})`,
+        canRepair: false,
+        repairHint: "Run `paperclipai configure --section server` and set host to 127.0.0.1",
+      };
+    }
+    return {
+      name: "Deployment/auth mode",
+      status: "pass",
+      message: "local_trusted mode is configured for loopback-only access",
+    };
+  }
+
+  const secret =
+    process.env.BETTER_AUTH_SECRET?.trim() ??
+    process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim();
+  if (!secret) {
+    return {
+      name: "Deployment/auth mode",
+      status: "fail",
+      message: "authenticated mode requires BETTER_AUTH_SECRET (or PAPERCLIP_AGENT_JWT_SECRET)",
+      canRepair: false,
+      repairHint: "Set BETTER_AUTH_SECRET before starting Paperclip",
+    };
+  }
+
+  if (auth.baseUrlMode === "explicit" && !auth.publicBaseUrl) {
+    return {
+      name: "Deployment/auth mode",
+      status: "fail",
+      message: "auth.baseUrlMode=explicit requires auth.publicBaseUrl",
+      canRepair: false,
+      repairHint: "Run `paperclipai configure --section server` and provide a base URL",
+    };
+  }
+
+  if (exposure === "public") {
+    if (auth.baseUrlMode !== "explicit" || !auth.publicBaseUrl) {
+      return {
+        name: "Deployment/auth mode",
+        status: "fail",
+        message: "authenticated/public requires explicit auth.publicBaseUrl",
+        canRepair: false,
+        repairHint: "Run `paperclipai configure --section server` and select public exposure",
+      };
+    }
+    try {
+      const url = new URL(auth.publicBaseUrl);
+      if (url.protocol !== "https:") {
+        return {
+          name: "Deployment/auth mode",
+          status: "warn",
+          message: "Public exposure should use an https:// auth.publicBaseUrl",
+          canRepair: false,
+          repairHint: "Use HTTPS in production for secure session cookies",
+        };
+      }
+    } catch {
+      return {
+        name: "Deployment/auth mode",
+        status: "fail",
+        message: "auth.publicBaseUrl is not a valid URL",
+        canRepair: false,
+        repairHint: "Run `paperclipai configure --section server` and provide a valid URL",
+      };
+    }
+  }
+
+  return {
+    name: "Deployment/auth mode",
+    status: "pass",
+    message: `Mode ${mode}/${exposure} with auth URL mode ${auth.baseUrlMode}`,
+  };
+}

cli/src/checks/index.ts

@@ -0,0 +1,18 @@
+export interface CheckResult {
+  name: string;
+  status: "pass" | "warn" | "fail";
+  message: string;
+  canRepair?: boolean;
+  repair?: () => void | Promise<void>;
+  repairHint?: string;
+}
+
+export { agentJwtSecretCheck } from "./agent-jwt-secret-check.js";
+export { configCheck } from "./config-check.js";
+export { deploymentAuthCheck } from "./deployment-auth-check.js";
+export { databaseCheck } from "./database-check.js";
+export { llmCheck } from "./llm-check.js";
+export { logCheck } from "./log-check.js";
+export { portCheck } from "./port-check.js";
+export { secretsCheck } from "./secrets-check.js";
+export { storageCheck } from "./storage-check.js";

cli/src/checks/llm-check.ts

@@ -0,0 +1,82 @@
+import type { PaperclipConfig } from "../config/schema.js";
+import type { CheckResult } from "./index.js";
+
+export async function llmCheck(config: PaperclipConfig): Promise<CheckResult> {
+  if (!config.llm) {
+    return {
+      name: "LLM provider",
+      status: "pass",
+      message: "No LLM provider configured (optional)",
+    };
+  }
+
+  if (!config.llm.apiKey) {
+    return {
+      name: "LLM provider",
+      status: "pass",
+      message: `${config.llm.provider} configured but no API key set (optional)`,
+    };
+  }
+
+  try {
+    if (config.llm.provider === "claude") {
+      const res = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+          "x-api-key": config.llm.apiKey,
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          model: "claude-sonnet-4-5-20250929",
+          max_tokens: 1,
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      });
+      if (res.ok || res.status === 400) {
+        return { name: "LLM provider", status: "pass", message: "Claude API key is valid" };
+      }
+      if (res.status === 401) {
+        return {
+          name: "LLM provider",
+          status: "fail",
+          message: "Claude API key is invalid (401)",
+          canRepair: false,
+          repairHint: "Run `paperclipai configure --section llm`",
+        };
+      }
+      return {
+        name: "LLM provider",
+        status: "warn",
+        message: `Claude API returned status ${res.status}`,
+      };
+    } else {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${config.llm.apiKey}` },
+      });
+      if (res.ok) {
+        return { name: "LLM provider", status: "pass", message: "OpenAI API key is valid" };
+      }
+      if (res.status === 401) {
+        return {
+          name: "LLM provider",
+          status: "fail",
+          message: "OpenAI API key is invalid (401)",
+          canRepair: false,
+          repairHint: "Run `paperclipai configure --section llm`",
+        };
+      }
+      return {
+        name: "LLM provider",
+        status: "warn",
+        message: `OpenAI API returned status ${res.status}`,
+      };
+    }
+  } catch {
+    return {
+      name: "LLM provider",
+      status: "warn",
+      message: "Could not reach API to validate key",
+    };
+  }
+}

cli/src/checks/log-check.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import type { PaperclipConfig } from "../config/schema.js";
+import type { CheckResult } from "./index.js";
+import { resolveRuntimeLikePath } from "./path-resolver.js";
+
+export function logCheck(config: PaperclipConfig, configPath?: string): CheckResult {
+  const logDir = resolveRuntimeLikePath(config.logging.logDir, configPath);
+  const reportedDir = logDir;
+
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(reportedDir, { recursive: true });
+  }
+
+  try {
+    fs.accessSync(reportedDir, fs.constants.W_OK);
+    return {
+      name: "Log directory",
+      status: "pass",
+      message: `Log directory is writable: ${reportedDir}`,
+    };
+  } catch {
+    return {
+      name: "Log directory",
+      status: "fail",
+      message: `Log directory is not writable: ${logDir}`,
+      canRepair: false,
+      repairHint: "Check file permissions on the log directory",
+    };
+  }
+}

cli/src/checks/path-resolver.ts

@@ -0,0 +1 @@
+export { resolveRuntimeLikePath } from "../utils/path-resolver.js";

cli/src/checks/port-check.ts

@@ -0,0 +1,24 @@
+import type { PaperclipConfig } from "../config/schema.js";
+import { checkPort } from "../utils/net.js";
+import type { CheckResult } from "./index.js";
+
+export async function portCheck(config: PaperclipConfig): Promise<CheckResult> {
+  const port = config.server.port;
+  const result = await checkPort(port);
+
+  if (result.available) {
+    return {
+      name: "Server port",
+      status: "pass",
+      message: `Port ${port} is available`,
+    };
+  }
+
+  return {
+    name: "Server port",
+    status: "warn",
+    message: result.error ?? `Port ${port} is not available`,
+    canRepair: false,
+    repairHint: `Check what's using port ${port} with: lsof -i :${port}`,
+  };
+}

cli/src/checks/secrets-check.ts

@@ -0,0 +1,146 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { PaperclipConfig } from "../config/schema.js";
+import type { CheckResult } from "./index.js";
+import { resolveRuntimeLikePath } from "./path-resolver.js";
+
+function decodeMasterKey(raw: string): Buffer | null {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  if (/^[A-Fa-f0-9]{64}$/.test(trimmed)) {
+    return Buffer.from(trimmed, "hex");
+  }
+
+  try {
+    const decoded = Buffer.from(trimmed, "base64");
+    if (decoded.length === 32) return decoded;
+  } catch {
+    // ignored
+  }
+
+  if (Buffer.byteLength(trimmed, "utf8") === 32) {
+    return Buffer.from(trimmed, "utf8");
+  }
+  return null;
+}
+
+function withStrictModeNote(
+  base: Pick<CheckResult, "name" | "status" | "message" | "canRepair" | "repair" | "repairHint">,
+  config: PaperclipConfig,
+): CheckResult {
+  const strictModeDisabledInDeployedSetup =
+    config.database.mode === "postgres" && config.secrets.strictMode === false;
+  if (!strictModeDisabledInDeployedSetup) return base;
+
+  if (base.status === "fail") return base;
+  return {
+    ...base,
+    status: "warn",
+    message: `${base.message}; strict secret mode is disabled for postgres deployment`,
+    repairHint: base.repairHint
+      ? `${base.repairHint}. Consider enabling secrets.strictMode`
+      : "Consider enabling secrets.strictMode",
+  };
+}
+
+export function secretsCheck(config: PaperclipConfig, configPath?: string): CheckResult {
+  const provider = config.secrets.provider;
+  if (provider !== "local_encrypted") {
+    return {
+      name: "Secrets adapter",
+      status: "fail",
+      message: `${provider} is configured, but this build only supports local_encrypted`,
+      canRepair: false,
+      repairHint: "Run `paperclipai configure --section secrets` and set provider to local_encrypted",
+    };
+  }
+
+  const envMasterKey = process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+  if (envMasterKey && envMasterKey.trim().length > 0) {
+    if (!decodeMasterKey(envMasterKey)) {
+      return {
+        name: "Secrets adapter",
+        status: "fail",
+        message:
+          "PAPERCLIP_SECRETS_MASTER_KEY is invalid (expected 32-byte base64, 64-char hex, or raw 32-char string)",
+        canRepair: false,
+        repairHint: "Set PAPERCLIP_SECRETS_MASTER_KEY to a valid key or unset it to use a key file",
+      };
+    }
+
+    return withStrictModeNote(
+      {
+        name: "Secrets adapter",
+        status: "pass",
+        message: "Local encrypted provider configured via PAPERCLIP_SECRETS_MASTER_KEY",
+      },
+      config,
+    );
+  }
+
+  const keyFileOverride = process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+  const configuredPath =
+    keyFileOverride && keyFileOverride.trim().length > 0
+      ? keyFileOverride.trim()
+      : config.secrets.localEncrypted.keyFilePath;
+  const keyFilePath = resolveRuntimeLikePath(configuredPath, configPath);
+
+  if (!fs.existsSync(keyFilePath)) {
+    return withStrictModeNote(
+      {
+        name: "Secrets adapter",
+        status: "warn",
+        message: `Secrets key file does not exist yet: ${keyFilePath}`,
+        canRepair: true,
+        repair: () => {
+          fs.mkdirSync(path.dirname(keyFilePath), { recursive: true });
+          fs.writeFileSync(keyFilePath, randomBytes(32).toString("base64"), {
+            encoding: "utf8",
+            mode: 0o600,
+          });
+          try {
+            fs.chmodSync(keyFilePath, 0o600);
+          } catch {
+            // best effort
+          }
+        },
+        repairHint: "Run with --repair to create a local encrypted secrets key file",
+      },
+      config,
+    );
+  }
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(keyFilePath, "utf8");
+  } catch (err) {
+    return {
+      name: "Secrets adapter",
+      status: "fail",
+      message: `Could not read secrets key file: ${err instanceof Error ? err.message : String(err)}`,
+      canRepair: false,
+      repairHint: "Check file permissions or set PAPERCLIP_SECRETS_MASTER_KEY",
+    };
+  }
+
+  if (!decodeMasterKey(raw)) {
+    return {
+      name: "Secrets adapter",
+      status: "fail",
+      message: `Invalid key material in ${keyFilePath}`,
+      canRepair: false,
+      repairHint: "Replace with valid key material or delete it and run doctor --repair",
+    };
+  }
+
+  return withStrictModeNote(
+    {
+      name: "Secrets adapter",
+      status: "pass",
+      message: `Local encrypted provider configured with key file ${keyFilePath}`,
+    },
+    config,
+  );
+}