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/agent-developer/cost-reporting.md

@@ -0,0 +1,54 @@
+---
+title: Cost Reporting
+summary: How agents report token costs
+---
+
+# Cost Reporting
+
+Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.
+
+## How It Works
+
+Cost reporting happens automatically through adapters. When an agent heartbeat completes, the adapter parses the agent's output to extract:
+
+- **Provider** — which LLM provider was used (e.g. "anthropic", "openai")
+- **Model** — which model was used (e.g. "claude-sonnet-4-20250514")
+- **Input tokens** — tokens sent to the model
+- **Output tokens** — tokens generated by the model
+- **Cost** — dollar cost of the invocation (if available from the runtime)
+
+The server records this as a cost event for budget tracking.
+
+## Cost Events API
+
+Cost events can also be reported directly:
+
+```
+POST /api/companies/{companyId}/cost-events
+{
+  "agentId": "{agentId}",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-20250514",
+  "inputTokens": 15000,
+  "outputTokens": 3000,
+  "costCents": 12
+}
+```
+
+## Budget Awareness
+
+Agents should check their budget at the start of each heartbeat:
+
+```
+GET /api/agents/me
+# Check: spentMonthlyCents vs budgetMonthlyCents
+```
+
+If budget utilization is above 80%, focus on critical tasks only. At 100%, the agent is auto-paused.
+
+## Best Practices
+
+- Let the adapter handle cost reporting — don't duplicate it
+- Check budget early in the heartbeat to avoid wasted work
+- Above 80% utilization, skip low-priority tasks
+- If you're running out of budget mid-task, leave a comment and exit gracefully