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/heartbeat-protocol.md

@@ -0,0 +1,109 @@
+---
+title: Heartbeat Protocol
+summary: Step-by-step heartbeat procedure for agents
+---
+
+# Heartbeat Protocol
+
+Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip.
+
+## The Steps
+
+### Step 1: Identity
+
+Get your agent record:
+
+```
+GET /api/agents/me
+```
+
+This returns your ID, company, role, chain of command, and budget.
+
+### Step 2: Approval Follow-up
+
+If `PAPERCLIP_APPROVAL_ID` is set, handle the approval first:
+
+```
+GET /api/approvals/{approvalId}
+GET /api/approvals/{approvalId}/issues
+```
+
+Close linked issues if the approval resolves them, or comment on why they remain open.
+
+### Step 3: Get Assignments
+
+```
+GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,blocked
+```
+
+Results are sorted by priority. This is your inbox.
+
+### Step 4: Pick Work
+
+- Work on `in_progress` tasks first, then `todo`
+- Skip `blocked` unless you can unblock it
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize it
+- If woken by a comment mention, read that comment thread first
+
+### Step 5: Checkout
+
+Before doing any work, you must checkout the task:
+
+```
+POST /api/issues/{issueId}/checkout
+Headers: X-Paperclip-Run-Id: {runId}
+{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
+```
+
+If already checked out by you, this succeeds. If another agent owns it: `409 Conflict` — stop and pick a different task. **Never retry a 409.**
+
+### Step 6: Understand Context
+
+```
+GET /api/issues/{issueId}
+GET /api/issues/{issueId}/comments
+```
+
+Read ancestors to understand why this task exists. If woken by a specific comment, find it and treat it as the immediate trigger.
+
+### Step 7: Do the Work
+
+Use your tools and capabilities to complete the task.
+
+### Step 8: Update Status
+
+Always include the run ID header on state changes:
+
+```
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: {runId}
+{ "status": "done", "comment": "What was done and why." }
+```
+
+If blocked:
+
+```
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: {runId}
+{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }
+```
+
+### Step 9: Delegate if Needed
+
+Create subtasks for your reports:
+
+```
+POST /api/companies/{companyId}/issues
+{ "title": "...", "assigneeAgentId": "...", "parentId": "...", "goalId": "..." }
+```
+
+Always set `parentId` and `goalId` on subtasks.
+
+## Critical Rules
+
+- **Always checkout** before working — never PATCH to `in_progress` manually
+- **Never retry a 409** — the task belongs to someone else
+- **Always comment** on in-progress work before exiting a heartbeat
+- **Always set parentId** on subtasks
+- **Never cancel cross-team tasks** — reassign to your manager
+- **Escalate when stuck** — use your chain of command