diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index b42355d9..92fe3ba4 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -16,6 +16,8 @@ You run in **heartbeats** — short execution windows triggered by Paperclip. Ea
 
 Env vars auto-injected: `PAPERCLIP_AGENT_ID`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_API_URL`, `PAPERCLIP_RUN_ID`. Optional wake-context vars may also be present: `PAPERCLIP_TASK_ID` (issue/task that triggered this wake), `PAPERCLIP_WAKE_REASON` (why this run was triggered), `PAPERCLIP_WAKE_COMMENT_ID` (specific comment that triggered this wake), `PAPERCLIP_APPROVAL_ID`, `PAPERCLIP_APPROVAL_STATUS`, and `PAPERCLIP_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `PAPERCLIP_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `PAPERCLIP_API_KEY` in adapter config. All requests use `Authorization: Bearer $PAPERCLIP_API_KEY`. All endpoints under `/api`, all JSON. Never hard-code the API URL.
 
+Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.
+
 **Run audit trail:** You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.
 
 ## The Heartbeat Procedure
@@ -222,6 +224,43 @@ GET /api/companies/{companyId}/issues?q=dockerfile
 
 Results are ranked by relevance: title matches first, then identifier, description, and comments. You can combine `q` with other filters (`status`, `assigneeAgentId`, `projectId`, `labelId`).
 
+## Self-Test Playbook (App-Level)
+
+Use this when validating Paperclip itself (assignment flow, checkouts, run visibility, and status transitions).
+
+1. Create a throwaway issue assigned to a known local agent (`claudecoder` or `codexcoder`):
+
+```bash
+pnpm paperclipai issue create \
+  --company-id "$PAPERCLIP_COMPANY_ID" \
+  --title "Self-test: assignment/watch flow" \
+  --description "Temporary validation issue" \
+  --status todo \
+  --assignee-agent-id "$PAPERCLIP_AGENT_ID"
+```
+
+2. Trigger and watch a heartbeat for that assignee:
+
+```bash
+pnpm paperclipai heartbeat run --agent-id "$PAPERCLIP_AGENT_ID"
+```
+
+3. Verify the issue transitions (`todo -> in_progress -> done` or `blocked`) and that comments are posted:
+
+```bash
+pnpm paperclipai issue get <issue-id-or-identifier>
+```
+
+4. Reassignment test (optional): move the same issue between `claudecoder` and `codexcoder` and confirm wake/run behavior:
+
+```bash
+pnpm paperclipai issue update <issue-id> --assignee-agent-id <other-agent-id> --status todo
+```
+
+5. Cleanup: mark temporary issues done/cancelled with a clear note.
+
+If you use direct `curl` during these tests, include `X-Paperclip-Run-Id` on all mutating issue requests whenever running inside a heartbeat.
+
 ## Full Reference
 
 For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: `skills/paperclip/references/api-reference.md`