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/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