diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index a0aaad66..65b130b1 100644
--- a/skills/paperclip/SKILL.md
+++ b/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.
diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md
index 44f6ada0..4a562ddd 100644
--- a/skills/paperclip/references/api-reference.md
+++ b/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        |