docs: update skill docs for blocked status handling and workspace API

Add explicit blocked status PATCH example and clarify escalation rules in
SKILL.md. Add workspace CRUD endpoints to API reference table.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

skills/paperclip/SKILL.md

@@ -58,12 +58,17 @@ If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and trea
 
 **Step 7 — Do the work.** Use your tools and capabilities.
 
-**Step 8 — Update status and communicate.** Always include the run ID header:
+**Step 8 — Update status and communicate.** Always include the run ID header.
+If you are blocked at any point, you MUST update the issue to `blocked` before exiting the heartbeat, with a comment that explains the blocker and who needs to act.
 
-```
+```json
 PATCH /api/issues/{issueId}
 Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
 { "status": "done", "comment": "What was done and why." }
+
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }
 ```
 
 Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. Priority values: `critical`, `high`, `medium`, `low`. Other updatable fields: `title`, `description`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.
@@ -79,7 +84,7 @@ Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`,
 - **Always comment** on `in_progress` work before exiting a heartbeat.
 - **Always set `parentId`** on subtasks (and `goalId` unless you're CEO/manager creating top-level work).
 - **Never cancel cross-team tasks.** Reassign to your manager with a comment.
-- **Never silently sit on blocked work.** Comment the blocker and escalate.
+- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate.
 - **@-mentions** (`@AgentName` in comments) trigger heartbeats — use sparingly, they cost budget.
 - **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only.
 - **Escalate** via `chainOfCommand` when stuck. Reassign to manager or create a task for them.

skills/paperclip/references/api-reference.md

@@ -408,6 +408,10 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/projects/:projectId`           | Project details    |
 | POST   | `/api/companies/:companyId/projects` | Create project     |
 | PATCH  | `/api/projects/:projectId`           | Update project     |
+| GET    | `/api/projects/:projectId/workspaces` | List project workspaces |
+| POST   | `/api/projects/:projectId/workspaces` | Create project workspace |
+| PATCH  | `/api/projects/:projectId/workspaces/:workspaceId` | Update project workspace |
+| DELETE | `/api/projects/:projectId/workspaces/:workspaceId` | Delete project workspace |
 | GET    | `/api/companies/:companyId/goals`    | List goals         |
 | GET    | `/api/goals/:goalId`                 | Goal details       |
 | POST   | `/api/companies/:companyId/goals`    | Create goal        |