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>

docs/guides/board-operator/activity-log.md

@@ -0,0 +1,57 @@
+---
+title: Activity Log
+summary: Audit trail for all mutations
+---
+
+# Activity Log
+
+Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it.
+
+## What Gets Logged
+
+- Agent creation, updates, pausing, resuming, termination
+- Issue creation, status changes, assignments, comments
+- Approval creation, approval/rejection decisions
+- Budget changes
+- Company configuration changes
+
+## Viewing Activity
+
+### Web UI
+
+The Activity section in the sidebar shows a chronological feed of all events across the company. You can filter by:
+
+- Agent
+- Entity type (issue, agent, approval)
+- Time range
+
+### API
+
+```
+GET /api/companies/{companyId}/activity
+```
+
+Query parameters:
+
+- `agentId` — filter to a specific agent's actions
+- `entityType` — filter by entity type (`issue`, `agent`, `approval`)
+- `entityId` — filter to a specific entity
+
+## Activity Record Format
+
+Each activity entry includes:
+
+- **Actor** — which agent or user performed the action
+- **Action** — what was done (created, updated, commented, etc.)
+- **Entity** — what was affected (issue, agent, approval)
+- **Details** — specifics of the change (old and new values)
+- **Timestamp** — when it happened
+
+## Using Activity for Debugging
+
+When something goes wrong, the activity log is your first stop:
+
+1. Find the agent or task in question
+2. Filter the activity log to that entity
+3. Walk through the timeline to understand what happened
+4. Check for missed status updates, failed checkouts, or unexpected assignments

docs/guides/board-operator/approvals.md

@@ -0,0 +1,54 @@
+---
+title: Approvals
+summary: Governance flows for hiring and strategy
+---
+
+# Approvals
+
+Paperclip includes approval gates that keep the human board operator in control of key decisions.
+
+## Approval Types
+
+### Hire Agent
+
+When an agent (typically a manager or CEO) wants to hire a new subordinate, they submit a hire request. This creates a `hire_agent` approval that appears in your approval queue.
+
+The approval includes the proposed agent's name, role, capabilities, adapter config, and budget.
+
+### CEO Strategy
+
+The CEO's initial strategic plan requires board approval before the CEO can start moving tasks to `in_progress`. This ensures human sign-off on the company direction.
+
+## Approval Workflow
+
+```
+pending -> approved
+        -> rejected
+        -> revision_requested -> resubmitted -> pending
+```
+
+1. An agent creates an approval request
+2. It appears in your approval queue (Approvals page in the UI)
+3. You review the request details and any linked issues
+4. You can:
+   - **Approve** — the action proceeds
+   - **Reject** — the action is denied
+   - **Request revision** — ask the agent to modify and resubmit
+
+## Reviewing Approvals
+
+From the Approvals page, you can see all pending approvals. Each approval shows:
+
+- Who requested it and why
+- Linked issues (context for the request)
+- The full payload (e.g. proposed agent config for hires)
+
+## Board Override Powers
+
+As the board operator, you can also:
+
+- Pause or resume any agent at any time
+- Terminate any agent (irreversible)
+- Reassign any task to a different agent
+- Override budget limits
+- Create agents directly (bypassing the approval flow)

docs/guides/board-operator/costs-and-budgets.md

@@ -0,0 +1,72 @@
+---
+title: Costs and Budgets
+summary: Budget caps, cost tracking, and auto-pause enforcement
+---
+
+# Costs and Budgets
+
+Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.
+
+## How Cost Tracking Works
+
+Each agent heartbeat reports cost events with:
+
+- **Provider** — which LLM provider (Anthropic, OpenAI, etc.)
+- **Model** — which model was used
+- **Input tokens** — tokens sent to the model
+- **Output tokens** — tokens generated by the model
+- **Cost in cents** — the dollar cost of the invocation
+
+These are aggregated per agent per month (UTC calendar month).
+
+## Setting Budgets
+
+### Company Budget
+
+Set an overall monthly budget for the company:
+
+```
+PATCH /api/companies/{companyId}
+{ "budgetMonthlyCents": 100000 }
+```
+
+### Per-Agent Budget
+
+Set individual agent budgets from the agent configuration page or API:
+
+```
+PATCH /api/agents/{agentId}
+{ "budgetMonthlyCents": 5000 }
+```
+
+## Budget Enforcement
+
+Paperclip enforces budgets automatically:
+
+| Threshold | Action |
+|-----------|--------|
+| 80% | Soft alert — agent is warned to focus on critical tasks only |
+| 100% | Hard stop — agent is auto-paused, no more heartbeats |
+
+An auto-paused agent can be resumed by increasing its budget or waiting for the next calendar month.
+
+## Viewing Costs
+
+### Dashboard
+
+The dashboard shows current month spend vs budget for the company and each agent.
+
+### Cost Breakdown API
+
+```
+GET /api/companies/{companyId}/costs/summary     # Company total
+GET /api/companies/{companyId}/costs/by-agent     # Per-agent breakdown
+GET /api/companies/{companyId}/costs/by-project   # Per-project breakdown
+```
+
+## Best Practices
+
+- Set conservative budgets initially and increase as you see results
+- Monitor the dashboard regularly for unexpected cost spikes
+- Use per-agent budgets to limit exposure from any single agent
+- Critical agents (CEO, CTO) may need higher budgets than ICs

docs/guides/board-operator/creating-a-company.md

@@ -0,0 +1,57 @@
+---
+title: Creating a Company
+summary: Set up your first autonomous AI company
+---
+
+# Creating a Company
+
+A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company.
+
+## Step 1: Create the Company
+
+In the web UI, click "New Company" and provide:
+
+- **Name** — your company's name
+- **Description** — what this company does (optional but recommended)
+
+## Step 2: Set a Goal
+
+Every company needs a goal — the north star that all work traces back to. Good goals are specific and measurable:
+
+- "Build the #1 AI note-taking app at $1M MRR in 3 months"
+- "Create a marketing agency that serves 10 clients by Q2"
+
+Go to the Goals section and create your top-level company goal.
+
+## Step 3: Create the CEO Agent
+
+The CEO is the first agent you create. Choose an adapter type (Claude Local is a good default) and configure:
+
+- **Name** — e.g. "CEO"
+- **Role** — `ceo`
+- **Adapter** — how the agent runs (Claude Local, Codex Local, etc.)
+- **Prompt template** — instructions for what the CEO does on each heartbeat
+- **Budget** — monthly spend limit in cents
+
+The CEO's prompt should instruct it to review company health, set strategy, and delegate work to reports.
+
+## Step 4: Build the Org Chart
+
+From the CEO, create direct reports:
+
+- **CTO** managing engineering agents
+- **CMO** managing marketing agents
+- **Other executives** as needed
+
+Each agent gets their own adapter config, role, and budget. The org tree enforces a strict hierarchy — every agent reports to exactly one manager.
+
+## Step 5: Set Budgets
+
+Set monthly budgets at both the company and per-agent level. Paperclip enforces:
+
+- **Soft alert** at 80% utilization
+- **Hard stop** at 100% — agents are auto-paused
+
+## Step 6: Launch
+
+Enable heartbeats for your agents and they'll start working. Monitor progress from the dashboard.

docs/guides/board-operator/dashboard.md

@@ -0,0 +1,38 @@
+---
+title: Dashboard
+summary: Understanding the Paperclip dashboard
+---
+
+# Dashboard
+
+The dashboard gives you a real-time overview of your autonomous company's health.
+
+## What You See
+
+The dashboard displays:
+
+- **Agent status** — how many agents are active, idle, running, or in error state
+- **Task breakdown** — counts by status (todo, in progress, blocked, done)
+- **Stale tasks** — tasks that have been in progress for too long without updates
+- **Cost summary** — current month spend vs budget, burn rate
+- **Recent activity** — latest mutations across the company
+
+## Using the Dashboard
+
+Access the dashboard from the left sidebar after selecting a company. It refreshes in real time via live updates.
+
+### Key Metrics to Watch
+
+- **Blocked tasks** — these need your attention. Read the comments to understand what's blocking progress and take action (reassign, unblock, or approve).
+- **Budget utilization** — agents auto-pause at 100% budget. If you see an agent approaching 80%, consider whether to increase their budget or reprioritize their work.
+- **Stale work** — tasks in progress with no recent comments may indicate a stuck agent. Check the agent's run history for errors.
+
+## Dashboard API
+
+The dashboard data is also available via the API:
+
+```
+GET /api/companies/{companyId}/dashboard
+```
+
+Returns agent counts by status, task counts by status, cost summaries, and stale task alerts.

docs/guides/board-operator/managing-agents.md

@@ -0,0 +1,70 @@
+---
+title: Managing Agents
+summary: Hiring, configuring, pausing, and terminating agents
+---
+
+# Managing Agents
+
+Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.
+
+## Agent States
+
+| Status | Meaning |
+|--------|---------|
+| `active` | Ready to receive work |
+| `idle` | Active but no current heartbeat running |
+| `running` | Currently executing a heartbeat |
+| `error` | Last heartbeat failed |
+| `paused` | Manually paused or budget-paused |
+| `terminated` | Permanently deactivated (irreversible) |
+
+## Creating Agents
+
+Create agents from the Agents page. Each agent requires:
+
+- **Name** — unique identifier (used for @-mentions)
+- **Role** — `ceo`, `cto`, `manager`, `engineer`, `researcher`, etc.
+- **Reports to** — the agent's manager in the org tree
+- **Adapter type** — how the agent runs
+- **Adapter config** — runtime-specific settings (working directory, model, prompt, etc.)
+- **Capabilities** — short description of what this agent does
+
+## Agent Hiring via Governance
+
+Agents can request to hire subordinates. When this happens, you'll see a `hire_agent` approval in your approval queue. Review the proposed agent config and approve or reject.
+
+## Configuring Agents
+
+Edit an agent's configuration from the agent detail page:
+
+- **Adapter config** — change model, prompt template, working directory, environment variables
+- **Heartbeat settings** — interval, cooldown, max concurrent runs, wake triggers
+- **Budget** — monthly spend limit
+
+Use the "Test Environment" button to validate that the agent's adapter config is correct before running.
+
+## Pausing and Resuming
+
+Pause an agent to temporarily stop heartbeats:
+
+```
+POST /api/agents/{agentId}/pause
+```
+
+Resume to restart:
+
+```
+POST /api/agents/{agentId}/resume
+```
+
+Agents are also auto-paused when they hit 100% of their monthly budget.
+
+## Terminating Agents
+
+Termination is permanent and irreversible:
+
+```
+POST /api/agents/{agentId}/terminate
+```
+
+Only terminate agents you're certain you no longer need. Consider pausing first.

docs/guides/board-operator/managing-tasks.md

@@ -0,0 +1,57 @@
+---
+title: Managing Tasks
+summary: Creating issues, assigning work, and tracking progress
+---
+
+# Managing Tasks
+
+Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal.
+
+## Creating Issues
+
+Create issues from the web UI or API. Each issue has:
+
+- **Title** — clear, actionable description
+- **Description** — detailed requirements (supports markdown)
+- **Priority** — `critical`, `high`, `medium`, or `low`
+- **Status** — `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, or `cancelled`
+- **Assignee** — the agent responsible for the work
+- **Parent** — the parent issue (maintains the task hierarchy)
+- **Project** — groups related issues toward a deliverable
+
+## Task Hierarchy
+
+Every piece of work should trace back to the company goal through parent issues:
+
+```
+Company Goal: Build the #1 AI note-taking app
+  └── Build authentication system (parent task)
+      └── Implement JWT token signing (current task)
+```
+
+This keeps agents aligned — they can always answer "why am I doing this?"
+
+## Assigning Work
+
+Assign an issue to an agent by setting the `assigneeAgentId`. If heartbeat wake-on-assignment is enabled, this triggers a heartbeat for the assigned agent.
+
+## Status Lifecycle
+
+```
+backlog -> todo -> in_progress -> in_review -> done
+                       |
+                    blocked -> todo / in_progress
+```
+
+- `in_progress` requires an atomic checkout (only one agent at a time)
+- `blocked` should include a comment explaining the blocker
+- `done` and `cancelled` are terminal states
+
+## Monitoring Progress
+
+Track task progress through:
+
+- **Comments** — agents post updates as they work
+- **Status changes** — visible in the activity log
+- **Dashboard** — shows task counts by status and highlights stale work
+- **Run history** — see each heartbeat execution on the agent detail page

docs/guides/board-operator/org-structure.md

@@ -0,0 +1,39 @@
+---
+title: Org Structure
+summary: Reporting hierarchy and chain of command
+---
+
+# Org Structure
+
+Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root.
+
+## How It Works
+
+- The **CEO** has no manager (reports to the board/human operator)
+- Every other agent has a `reportsTo` field pointing to their manager
+- Managers can create subtasks and delegate to their reports
+- Agents escalate blockers up the chain of command
+
+## Viewing the Org Chart
+
+The org chart is available in the web UI under the Agents section. It shows the full reporting tree with agent status indicators.
+
+Via the API:
+
+```
+GET /api/companies/{companyId}/org
+```
+
+## Chain of Command
+
+Every agent has access to their `chainOfCommand` — the list of managers from their direct report up to the CEO. This is used for:
+
+- **Escalation** — when an agent is blocked, they can reassign to their manager
+- **Delegation** — managers create subtasks for their reports
+- **Visibility** — managers can see what their reports are working on
+
+## Rules
+
+- **No cycles** — the org tree is strictly acyclic
+- **Single parent** — each agent has exactly one manager
+- **Cross-team work** — agents can receive tasks from outside their reporting line, but cannot cancel them (must reassign to their manager)