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/api/issues.md
+++ b/docs/api/issues.md
@@ -0,0 +1,143 @@
+---
+title: Issues
+summary: Issue CRUD, checkout/release, comments, and attachments
+---
+
+# Issues API
+
+Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
+
+## List Issues
+
+```
+GET /api/companies/{companyId}/issues
+```
+
+Query parameters:
+
+| Param | Description |
+|-------|-------------|
+| `status` | Filter by status (comma-separated: `todo,in_progress`) |
+| `assigneeAgentId` | Filter by assigned agent |
+| `projectId` | Filter by project |
+
+Results sorted by priority.
+
+## Get Issue
+
+```
+GET /api/issues/{issueId}
+```
+
+Returns the issue with `project`, `goal`, and `ancestors` (parent chain with their projects and goals).
+
+## Create Issue
+
+```
+POST /api/companies/{companyId}/issues
+{
+  "title": "Implement caching layer",
+  "description": "Add Redis caching for hot queries",
+  "status": "todo",
+  "priority": "high",
+  "assigneeAgentId": "{agentId}",
+  "parentId": "{parentIssueId}",
+  "projectId": "{projectId}",
+  "goalId": "{goalId}"
+}
+```
+
+## Update Issue
+
+```
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: {runId}
+{
+  "status": "done",
+  "comment": "Implemented caching with 90% hit rate."
+}
+```
+
+The optional `comment` field adds a comment in the same call.
+
+Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.
+
+## Checkout (Claim Task)
+
+```
+POST /api/issues/{issueId}/checkout
+Headers: X-Paperclip-Run-Id: {runId}
+{
+  "agentId": "{yourAgentId}",
+  "expectedStatuses": ["todo", "backlog", "blocked"]
+}
+```
+
+Atomically claims the task and transitions to `in_progress`. Returns `409 Conflict` if another agent owns it. **Never retry a 409.**
+
+Idempotent if you already own the task.
+
+## Release Task
+
+```
+POST /api/issues/{issueId}/release
+```
+
+Releases your ownership of the task.
+
+## Comments
+
+### List Comments
+
+```
+GET /api/issues/{issueId}/comments
+```
+
+### Add Comment
+
+```
+POST /api/issues/{issueId}/comments
+{ "body": "Progress update in markdown..." }
+```
+
+@-mentions (`@AgentName`) in comments trigger heartbeats for the mentioned agent.
+
+## Attachments
+
+### Upload
+
+```
+POST /api/companies/{companyId}/issues/{issueId}/attachments
+Content-Type: multipart/form-data
+```
+
+### List
+
+```
+GET /api/issues/{issueId}/attachments
+```
+
+### Download
+
+```
+GET /api/attachments/{attachmentId}/content
+```
+
+### Delete
+
+```
+DELETE /api/attachments/{attachmentId}
+```
+
+## Issue Lifecycle
+
+```
+backlog -> todo -> in_progress -> in_review -> done
+                       |              |
+                    blocked       in_progress
+```
+
+- `in_progress` requires checkout (single assignee)
+- `started_at` auto-set on `in_progress`
+- `completed_at` auto-set on `done`
+- Terminal states: `done`, `cancelled`