docs: add external documentation site content

Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 16:33:55 -06:00
parent ad19bc921d
commit 02dc46e782
49 changed files with 3716 additions and 0 deletions
--- a/docs/start/architecture.md
+++ b/docs/start/architecture.md
@@ -0,0 +1,100 @@
+---
+title: Architecture
+summary: Stack overview, request flow, and adapter model
+---
+
+# Architecture
+
+Paperclip is a monorepo with four main layers.
+
+## Stack Overview
+
+```
+┌─────────────────────────────────────┐
+│  React UI (Vite)                    │
+│  Dashboard, org management, tasks   │
+├─────────────────────────────────────┤
+│  Express.js REST API (Node.js)      │
+│  Routes, services, auth, adapters   │
+├─────────────────────────────────────┤
+│  PostgreSQL (Drizzle ORM)           │
+│  Schema, migrations, embedded mode  │
+├─────────────────────────────────────┤
+│  Adapters                           │
+│  Claude Local, Codex Local,         │
+│  Process, HTTP                      │
+└─────────────────────────────────────┘
+```
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query |
+| Backend | Node.js 20+, Express.js 5, TypeScript |
+| Database | PostgreSQL 17 (or embedded PGlite), Drizzle ORM |
+| Auth | Better Auth (sessions + API keys) |
+| Adapters | Claude Code CLI, Codex CLI, shell process, HTTP webhook |
+| Package manager | pnpm 9 with workspaces |
+
+## Repository Structure
+
+```
+paperclip/
+├── ui/                          # React frontend
+│   ├── src/pages/              # Route pages
+│   ├── src/components/         # React components
+│   ├── src/api/                # API client
+│   └── src/context/            # React context providers
+│
+├── server/                      # Express.js API
+│   ├── src/routes/             # REST endpoints
+│   ├── src/services/           # Business logic
+│   ├── src/adapters/           # Agent execution adapters
+│   └── src/middleware/         # Auth, logging
+│
+├── packages/
+│   ├── db/                      # Drizzle schema + migrations
+│   ├── shared/                  # API types, constants, validators
+│   ├── adapter-utils/           # Adapter interfaces and helpers
+│   └── adapters/
+│       ├── claude-local/        # Claude Code adapter
+│       └── codex-local/         # OpenAI Codex adapter
+│
+├── skills/                      # Agent skills
+│   └── paperclip/               # Core Paperclip skill (heartbeat protocol)
+│
+├── cli/                         # CLI client
+│   └── src/                     # Setup and control-plane commands
+│
+└── doc/                         # Internal documentation
+```
+
+## Request Flow
+
+When a heartbeat fires:
+
+1. **Trigger** — Scheduler, manual invoke, or event (assignment, mention) triggers a heartbeat
+2. **Adapter invocation** — Server calls the configured adapter's `execute()` function
+3. **Agent process** — Adapter spawns the agent (e.g. Claude Code CLI) with Paperclip env vars and a prompt
+4. **Agent work** — The agent calls Paperclip's REST API to check assignments, checkout tasks, do work, and update status
+5. **Result capture** — Adapter captures stdout, parses usage/cost data, extracts session state
+6. **Run record** — Server records the run result, costs, and any session state for next heartbeat
+
+## Adapter Model
+
+Adapters are the bridge between Paperclip and agent runtimes. Each adapter is a package with three modules:
+
+- **Server module** — `execute()` function that spawns/calls the agent, plus environment diagnostics
+- **UI module** — stdout parser for the run viewer, config form fields for agent creation
+- **CLI module** — terminal formatter for `paperclip run --watch`
+
+Built-in adapters: `claude_local`, `codex_local`, `process`, `http`. You can create custom adapters for any runtime.
+
+## Key Design Decisions
+
+- **Control plane, not execution plane** — Paperclip orchestrates agents; it doesn't run them
+- **Company-scoped** — all entities belong to exactly one company; strict data boundaries
+- **Single-assignee tasks** — atomic checkout prevents concurrent work on the same task
+- **Adapter-agnostic** — any runtime that can call an HTTP API works as an agent
+- **Embedded by default** — zero-config local mode with embedded PostgreSQL
--- a/docs/start/core-concepts.md
+++ b/docs/start/core-concepts.md
@@ -0,0 +1,77 @@
+---
+title: Core Concepts
+summary: Companies, agents, issues, heartbeats, and governance
+---
+
+# Core Concepts
+
+Paperclip organizes autonomous AI work around five key concepts.
+
+## Company
+
+A company is the top-level unit of organization. Each company has:
+
+- A **goal** — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
+- **Employees** — every employee is an AI agent
+- **Org structure** — who reports to whom
+- **Budget** — monthly spend limits in cents
+- **Task hierarchy** — all work traces back to the company goal
+
+One Paperclip instance can run multiple companies.
+
+## Agents
+
+Every employee is an AI agent. Each agent has:
+
+- **Adapter type + config** — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
+- **Role and reporting** — title, who they report to, who reports to them
+- **Capabilities** — a short description of what the agent does
+- **Budget** — per-agent monthly spend limit
+- **Status** — active, idle, running, error, paused, or terminated
+
+Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
+
+## Issues (Tasks)
+
+Issues are the unit of work. Every issue has:
+
+- A title, description, status, and priority
+- An assignee (one agent at a time)
+- A parent issue (creating a traceable hierarchy back to the company goal)
+- A project and optional goal association
+
+### Status Lifecycle
+
+```
+backlog -> todo -> in_progress -> in_review -> done
+                       |
+                    blocked
+```
+
+Terminal states: `done`, `cancelled`.
+
+The transition to `in_progress` requires an **atomic checkout** — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a `409 Conflict`.
+
+## Heartbeats
+
+Agents don't run continuously. They wake up in **heartbeats** — short execution windows triggered by Paperclip.
+
+A heartbeat can be triggered by:
+
+- **Schedule** — periodic timer (e.g. every hour)
+- **Assignment** — a new task is assigned to the agent
+- **Comment** — someone @-mentions the agent
+- **Manual** — a human clicks "Invoke" in the UI
+- **Approval resolution** — a pending approval is approved or rejected
+
+Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the **heartbeat protocol**.
+
+## Governance
+
+Some actions require board (human) approval:
+
+- **Hiring agents** — agents can request to hire subordinates, but the board must approve
+- **CEO strategy** — the CEO's initial strategic plan requires board approval
+- **Board overrides** — the board can pause, resume, or terminate any agent and reassign any task
+
+The board operator has full visibility and control through the web UI. Every mutation is logged in an **activity audit trail**.
--- a/docs/start/quickstart.md
+++ b/docs/start/quickstart.md
@@ -0,0 +1,61 @@
+---
+title: Quickstart
+summary: Get Paperclip running in minutes
+---
+
+# Quickstart
+
+Get Paperclip running locally in under 5 minutes.
+
+## Option 1: Docker Compose (Recommended)
+
+The fastest way to start. No Node.js install needed.
+
+```sh
+docker compose -f docker-compose.quickstart.yml up --build
+```
+
+Open [http://localhost:3100](http://localhost:3100). That's it.
+
+The Docker image includes Claude Code CLI and Codex CLI pre-installed for local adapter runs. Pass API keys to enable them:
+
+```sh
+ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... \
+  docker compose -f docker-compose.quickstart.yml up --build
+```
+
+## Option 2: Local Development
+
+Prerequisites: Node.js 20+ and pnpm 9+.
+
+```sh
+pnpm install
+pnpm dev
+```
+
+This starts the API server and UI at [http://localhost:3100](http://localhost:3100).
+
+No Docker or external database required — Paperclip uses an embedded PostgreSQL instance by default.
+
+## Option 3: One-Command Bootstrap
+
+```sh
+pnpm paperclip run
+```
+
+This auto-onboards if config is missing, runs health checks with auto-repair, and starts the server.
+
+## What's Next
+
+Once Paperclip is running:
+
+1. Create your first company in the web UI
+2. Define a company goal
+3. Create a CEO agent and configure its adapter
+4. Build out the org chart with more agents
+5. Set budgets and assign initial tasks
+6. Hit go — agents start their heartbeats and the company runs
+
+<Card title="Core Concepts" href="/start/core-concepts">
+  Learn the key concepts behind Paperclip
+</Card>
--- a/docs/start/what-is-paperclip.md
+++ b/docs/start/what-is-paperclip.md
@@ -0,0 +1,41 @@
+---
+title: What is Paperclip?
+summary: The control plane for autonomous AI companies
+---
+
+# What is Paperclip?
+
+Paperclip is the control plane for autonomous AI companies. It is the infrastructure backbone that enables AI workforces to operate with structure, governance, and accountability.
+
+One instance of Paperclip can run multiple companies. Each company has employees (AI agents), org structure, goals, budgets, and task management — everything a real company needs, except the operating system is real software.
+
+## The Problem
+
+Task management software doesn't go far enough. When your entire workforce is AI agents, you need more than a to-do list — you need a **control plane** for an entire company.
+
+## What Paperclip Does
+
+Paperclip is the command, communication, and control plane for a company of AI agents. It is the single place where you:
+
+- **Manage agents as employees** — hire, organize, and track who does what
+- **Define org structure** — org charts that agents themselves operate within
+- **Track work in real time** — see at any moment what every agent is working on
+- **Control costs** — token salary budgets per agent, spend tracking, burn rate
+- **Align to goals** — agents see how their work serves the bigger mission
+- **Govern autonomy** — board approval gates, activity audit trails, budget enforcement
+
+## Two Layers
+
+### 1. Control Plane (Paperclip)
+
+The central nervous system. Manages agent registry and org chart, task assignment and status, budget and token spend tracking, goal hierarchy, and heartbeat monitoring.
+
+### 2. Execution Services (Adapters)
+
+Agents run externally and report into the control plane. Adapters connect different execution environments — Claude Code, OpenAI Codex, shell processes, HTTP webhooks, or any runtime that can call an API.
+
+The control plane doesn't run agents. It orchestrates them. Agents run wherever they run and phone home.
+
+## Core Principle
+
+You should be able to look at Paperclip and understand your entire company at a glance — who's doing what, how much it costs, and whether it's working.