@penclipai/server 2026.704.0 → 2026.714.0

package/skills/paperclip/references/api-reference.md

@@ -191,6 +191,137 @@ The response also includes `blockedBy` and `blocks` arrays showing first-class d
 
 Blocker wake semantics are strict: `issue_blockers_resolved` only fires when every blocker reaches `done`. A blocker moved to `cancelled` still requires manual re-triage or relation cleanup.
 
+### Blocker Diagnostics (`GET /api/issues/:issueId/diagnostics/blockers`)
+
+Use this read-only diagnostic when an issue appears stuck on dependencies, especially after an `issue_blockers_resolved` wake or when an issue looks blocked against a blocker that is already `done`.
+
+Read `diagnosis` first. It is a deterministic, nullable explanation derived only from fields included in the response. The endpoint also returns bounded structured blocker rows with status, readiness, and anomaly flags:
+
+```json
+{
+  "issue": { "id": "issue-99", "identifier": "PAP-99", "title": "Ship API", "status": "blocked", "priority": "medium", "assigneeAgentId": "agent-1", "assigneeUserId": null },
+  "diagnosis": "All blockers for PAP-99 are resolved, but the issue is still blocked; this is likely a stale blocker hold.",
+  "readiness": { "allBlockersDone": true, "isDependencyReady": true, "unresolvedBlockerCount": 0, "pendingFinalizeBlockerCount": 0 },
+  "blockers": [
+    {
+      "id": "issue-80",
+      "identifier": "PAP-80",
+      "title": "Design auth schema",
+      "status": "done",
+      "priority": "high",
+      "assigneeAgentId": "agent-55",
+      "assigneeUserId": null,
+      "isUnresolved": false,
+      "isDependencyReady": true,
+      "isPendingFinalize": false,
+      "flags": ["done_but_blocking"]
+    }
+  ],
+  "omittedUnauthorizedBlockerCount": 0,
+  "truncated": false,
+  "caps": { "maxBlockers": 100 }
+}
+```
+
+Security and bounds:
+
+- The root issue and every returned blocker are independently checked against `issue:read`; unauthorized blockers are omitted.
+- `omittedUnauthorizedBlockerCount` is a number only when the result is not truncated; it is `null` when `truncated` is `true` because blockers beyond the cap may also be unauthorized.
+- If blockers are omitted or the result is truncated, `readiness` is `null` and `diagnosis` does not mention hidden blocker ids, statuses, assignees, or reasons.
+- No raw wake payloads, activity details, errors, or trigger blobs are returned by this Slice-1 endpoint.
+
+### Wake Diagnostics (`GET /api/issues/:issueId/diagnostics/wakes`)
+
+Use this read-only diagnostic when you need to answer why an issue's assignee was or was not woken. Read `diagnosis` first; `likelyReason` is the same value for callers that prefer that name. The string is deterministic, nullable, and derived only from fields included in the response plus authorized blocker state.
+
+The endpoint returns bounded wake/activity events, newest-first across both event kinds:
+
+```json
+{
+  "issue": { "id": "issue-99", "identifier": "PAP-99", "title": "Ship API", "status": "blocked", "priority": "medium", "assigneeAgentId": "agent-1", "assigneeUserId": null },
+  "diagnosis": "No wake row exists for PAP-99 in the bounded window. PAP-99 is blocked by PAP-80, which is in_progress, so issue_blockers_resolved has not fired.",
+  "likelyReason": "No wake row exists for PAP-99 in the bounded window. PAP-99 is blocked by PAP-80, which is in_progress, so issue_blockers_resolved has not fired.",
+  "events": [
+    {
+      "kind": "wake_request",
+      "agentId": "agent-1",
+      "source": "automation",
+      "reason": "issue_blockers_resolved",
+      "status": "completed",
+      "coalescedCount": 0,
+      "runId": "run-1",
+      "requestedAt": "2026-07-07T00:00:00.000Z",
+      "claimedAt": "2026-07-07T00:00:01.000Z",
+      "finishedAt": "2026-07-07T00:00:10.000Z",
+      "failureClass": null
+    }
+  ],
+  "wakeRequestCount": 1,
+  "activityRecordCount": 0,
+  "truncated": false,
+  "truncatedSections": { "wakeRequests": false, "activityRecords": false },
+  "caps": { "maxWakeRequests": 50, "maxActivityRecords": 50, "lookbackDays": 14 }
+}
+```
+
+Security and bounds:
+
+- The root issue must pass normal issue-read authorization, and Case-B blocker inference uses the same per-blocker authorization rules as blocker diagnostics.
+- Wake rows are matched only through allowlisted issue/task id fields in the wake payload. Raw `payload`, raw activity `details`, raw `error`, and raw `triggerDetail` are never returned.
+- Low-trust or boundary-scoped callers that cannot read company scope receive `null` for wake `agentId`/`runId` and activity `agentId`/`runId`/`holdId`.
+- Wake `source`, `reason`, and `status` are projected through coarse allowlists; unknown producer text is returned as `other`.
+- Failure detail is exposed only as `failureClass` (`failed`, `cancelled`, or `skipped`), never raw error text.
+- Activity records are limited to wake defer/suppression actions and exact allowlisted fields such as `rootIssueId`, `holdId`, `source`, `requestedReason`, and `previousReason`.
+- Results are capped to 50 wake requests and 50 activity records within a 14-day lookback. If either cap is hit, `truncated` is `true` and the diagnosis states that it only covers returned records.
+
+### Subtree Diagnostics (`GET /api/issues/:issueId/diagnostics/subtree`)
+
+Use this read-only diagnostic when an issue has child work and you need the combined wake/dependency view for the subtree. Read top-level `diagnosis` first; `likelyReason` is the same value. The response omits unauthorized subtree nodes and hidden blocker nodes before deriving diagnosis text.
+
+```json
+{
+  "issue": { "id": "issue-99", "identifier": "PAP-99", "title": "Ship API", "status": "blocked", "priority": "medium", "assigneeAgentId": "agent-1", "assigneeUserId": null },
+  "diagnosis": "PAP-99 appears to be the subtree stall point: PAP-99 is blocked by PAP-80, which is in_progress.",
+  "likelyReason": "PAP-99 appears to be the subtree stall point: PAP-99 is blocked by PAP-80, which is in_progress.",
+  "nodes": [
+    {
+      "issue": { "id": "issue-99", "identifier": "PAP-99", "title": "Ship API", "status": "blocked", "priority": "medium", "assigneeAgentId": "agent-1", "assigneeUserId": null },
+      "parentId": null,
+      "depth": 0,
+      "diagnosis": "PAP-99 is blocked by PAP-80, which is in_progress.",
+      "likelyReason": "PAP-99 is blocked by PAP-80, which is in_progress.",
+      "blockers": [
+        { "id": "issue-80", "identifier": "PAP-80", "title": "Finish dependency", "status": "in_progress", "priority": "medium", "assigneeAgentId": "agent-2", "assigneeUserId": null, "isUnresolved": true, "isDependencyReady": false, "isPendingFinalize": false, "flags": [] }
+      ],
+      "blockerReadiness": { "allBlockersDone": false, "isDependencyReady": false, "unresolvedBlockerCount": 1, "pendingFinalizeBlockerCount": 0 },
+      "omittedUnauthorizedBlockerCount": 0,
+      "wakeEvents": [],
+      "wakeRequestCount": 0,
+      "activityRecordCount": 0,
+      "truncated": false,
+      "truncatedSections": { "blockers": false, "wakeRequests": false, "activityRecords": false }
+    }
+  ],
+  "edges": [
+    { "kind": "blocks", "fromIssueId": "issue-80", "toIssueId": "issue-99", "timestamp": "2026-07-07T00:00:00.000Z" },
+    { "kind": "wake_request", "issueId": "issue-99", "agentId": "agent-1", "reason": "issue_blockers_resolved", "status": "completed", "timestamp": "2026-07-07T00:01:00.000Z" }
+  ],
+  "nodeCount": 1,
+  "omittedUnauthorizedNodeCount": 0,
+  "truncated": false,
+  "truncatedSections": { "nodes": false, "depth": false, "blockers": false, "wakeRequests": false, "activityRecords": false },
+  "caps": { "maxDepth": 8, "maxNodes": 100, "maxBlockersPerNode": 20, "maxWakeRequestsPerNode": 5, "maxActivityRecordsPerNode": 5, "lookbackDays": 14 }
+}
+```
+
+Security and bounds:
+
+- The root issue must pass normal issue-read authorization. Every returned subtree node and blocker node is independently checked against `issue:read`; unauthorized nodes and blocker rows are omitted.
+- `diagnosis` and per-node `likelyReason` are deterministic and derived only from returned authorized node, blocker, wake, and activity projections.
+- Raw wake `payload`, activity `details`, raw `error`, and `triggerDetail` are never returned. Wake fields use the same coarse projections as wake diagnostics.
+- Low-trust or boundary-scoped callers that cannot read company scope receive `null` for internal wake `agentId`/`runId` and activity `agentId`/`runId`/`holdId`.
+- The subtree walk is capped to depth 8 and 100 nodes with a cycle guard. Per-node blockers, wake requests, and activity records are also capped. Any cap hit sets `truncated: true` and the relevant `truncatedSections` flag.
+
 ### Execution Policy Fields On An Issue
 
 When an issue has review or approval gates, `GET /api/issues/:issueId` can also include `executionPolicy` and `executionState`:
@@ -829,6 +960,116 @@ Best practice:
 - After creating a pending checkbox confirmation, move the source issue to `in_review` with a comment that names exactly what the board must decide. Pending interactions are an explicit waiting path, not a synonym for `done`.
 - When a `superseded_by_comment` or `stale_target` wake fires, address the new comment or rebuild the target, then create a fresh checkbox confirmation with an idempotency key that includes the new revision id.
 
+### Item verdict requests
+
+Use `request_item_verdicts` when the board must approve/reject/defer individual items from a known list, and partial responses should wake the assignee as durable progress. It is different from `request_checkbox_confirmation`: checkbox confirmation is one accept/reject decision with selected ids, while item verdicts store per-item terminal decisions over time.
+
+Create an item-verdict request:
+
+```json
+POST /api/issues/{issueId}/interactions
+{
+  "kind": "request_item_verdicts",
+  "idempotencyKey": "verdicts:{issueId}:generated-artifacts:{planRevisionId}",
+  "title": "Review generated artifacts",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "prompt": "Review each generated artifact.",
+    "detailsMarkdown": "Approve artifacts that are ready. Reject items that need another pass.",
+    "items": [
+      { "id": "api", "label": "API route", "description": "Partial verdict submit endpoint." },
+      { "id": "docs", "label": "Docs update", "previewMarkdown": "Documents the route and result shape." }
+    ],
+    "verdicts": ["approve", "reject", "defer"],
+    "requireReasonOn": ["reject"],
+    "reasonLabel": "What should change?",
+    "allowBulkApprove": true,
+    "supersedeOnUserComment": true,
+    "target": {
+      "type": "issue_document",
+      "issueId": "{issueId}",
+      "key": "plan",
+      "revisionId": "{latestPlanRevisionId}"
+    }
+  }
+}
+```
+
+Payload field reference (`RequestItemVerdictsPayload`):
+
+| Field                    | Type                                                     | Default                    | Notes                                                                                                                        |
+| ------------------------ | -------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `version`                | `1`                                                      | required                   | Versioned for forward compatibility.                                                                                         |
+| `prompt`                 | string (1–1000 chars)                                    | required                   | Headline rendered above the item list.                                                                                        |
+| `detailsMarkdown`        | string (≤ 20000 chars) \| `null`                         | `null`                     | Optional markdown context above the list.                                                                                     |
+| `items`                  | `[{ id, label, description?, previewMarkdown?, href?, attachmentId? }]` | required, 1–200 entries | Item `id` and `label` are 1–120 chars. Item ids must be unique. `href` must be safe: root-relative, fragment, or http(s). |
+| `verdicts`               | array of `"approve"`, `"reject"`, optional `"defer"`     | `["approve","reject"]`     | Must include `approve` and `reject`; `defer` is allowed only when listed.                                                     |
+| `requireReasonOn`        | verdict array                                            | `["reject"]`               | Each value must be enabled by `verdicts`. Pending submissions with those verdicts require a non-empty `reason`.              |
+| `reasonLabel`            | string (1–160) \| `null`                                 | `null`                     | Field label for the verdict reason.                                                                                           |
+| `allowBulkApprove`       | boolean                                                  | `true`                     | UI hint for bulk-approve affordances. Server still validates each submitted item id.                                          |
+| `supersedeOnUserComment` | boolean                                                  | `true` (set server-side)   | A later board/user comment expires the still-pending remainder with `outcome: "superseded_by_comment"`.                      |
+| `target`                 | `RequestConfirmationTarget` \| `null`                    | `null`                     | Same target schema as confirmations. Stale issue-document targets expire the still-pending remainder with `stale_target`.     |
+
+Submit item verdicts (board action, requires board/user role; agents creating the interaction cannot submit verdicts):
+
+```json
+POST /api/issues/{issueId}/interactions/{interactionId}/verdicts
+{
+  "verdicts": [
+    { "id": "api", "verdict": "approve" },
+    { "id": "docs", "verdict": "reject", "reason": "Needs install instructions." }
+  ]
+}
+```
+
+Server behavior:
+
+- Unknown item ids return 422.
+- A verdict not listed in `payload.verdicts` returns 422.
+- A pending item whose verdict is listed in `requireReasonOn` must include a non-empty `reason`.
+- Re-submitting an already resolved item id is a no-op and does not overwrite the stored verdict or reason.
+- Each submit that resolves at least one new item queues one assignee wake with `payload.newlyResolvedItemIds` and `payload.itemVerdicts.newlyResolvedItemIds`. Wake idempotency uses a two-second bucket per issue+interaction to coalesce rapid duplicate wake requests.
+
+Partial result (`RequestItemVerdictsResult`, interaction remains `pending`):
+
+```json
+{
+  "version": 1,
+  "outcome": "resolved",
+  "complete": false,
+  "items": [
+    {
+      "id": "docs",
+      "verdict": "reject",
+      "reason": "Needs install instructions.",
+      "resolvedByUserId": "local-board",
+      "resolvedAt": "2026-07-09T12:00:00.000Z"
+    }
+  ]
+}
+```
+
+Complete result (interaction becomes `answered`):
+
+```json
+{
+  "version": 1,
+  "outcome": "resolved",
+  "complete": true,
+  "items": [
+    { "id": "api", "verdict": "approve", "resolvedByUserId": "local-board", "resolvedAt": "2026-07-09T12:00:00.000Z" },
+    { "id": "docs", "verdict": "reject", "reason": "Needs install instructions.", "resolvedByUserId": "local-board", "resolvedAt": "2026-07-09T12:00:00.000Z" }
+  ]
+}
+```
+
+Expiration results preserve already resolved items and omit undecided items:
+
+- `superseded_by_comment` — `{ outcome: "superseded_by_comment", complete: false, items, commentId }`.
+- `stale_target` — `{ outcome: "stale_target", complete: false, items, staleTarget }`.
+- `cancelled` is reserved for future explicit cancellation flows.
+
 ### Checking approval status
 
 ```
@@ -927,6 +1168,9 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/companies/:companyId/issues` | List issues, sorted by priority. Filters: `?status=`, `?assigneeAgentId=`, `?assigneeUserId=`, `?projectId=`, `?labelId=`, `?q=` (full-text search across title, identifier, description, comments) |
 | GET    | `/api/issues/:issueId`             | Issue details + ancestors                                                                |
 | GET    | `/api/issues/:issueId/heartbeat-context` | Compact context for heartbeat: issue state, ancestor summaries, comment cursor  |
+| GET    | `/api/issues/:issueId/diagnostics/blockers` | Read-only blocker diagnostic with `diagnosis`, readiness, and bounded anomaly flags |
+| GET    | `/api/issues/:issueId/diagnostics/wakes` | Read-only wake-history diagnostic with `diagnosis`, bounded events, and Case-B inference |
+| GET    | `/api/issues/:issueId/diagnostics/subtree` | Read-only subtree diagnostic combining visible child, blocker, and wake edges with `diagnosis` |
 | POST   | `/api/companies/:companyId/issues` | Create issue (supports `blockedByIssueIds: string[]` for dependencies)                   |
 | PATCH  | `/api/issues/:issueId`             | Update issue (optional `comment` field; `blockedByIssueIds` replaces blocker set)        |
 | POST   | `/api/issues/:issueId/checkout`    | Atomic checkout (claim + start). Idempotent if you already own it.                       |
@@ -935,10 +1179,11 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/issues/:issueId/comments/:commentId` | Get a specific comment by ID                                                     |
 | POST   | `/api/issues/:issueId/comments`    | Add comment (@-mentions trigger wakeups)                                                 |
 | GET    | `/api/issues/:issueId/interactions` | List issue-thread interactions                                                          |
-| POST   | `/api/issues/:issueId/interactions` | Create issue-thread interaction (`suggest_tasks`, `ask_user_questions`, `request_confirmation`, `request_checkbox_confirmation`) |
+| POST   | `/api/issues/:issueId/interactions` | Create issue-thread interaction (`suggest_tasks`, `ask_user_questions`, `request_confirmation`, `request_checkbox_confirmation`, `request_item_verdicts`) |
 | POST   | `/api/issues/:issueId/interactions/:interactionId/accept` | Accept suggested tasks or confirmation (body: `selectedClientKeys` for `suggest_tasks`; `selectedOptionIds` for `request_checkbox_confirmation`) |
 | POST   | `/api/issues/:issueId/interactions/:interactionId/reject` | Reject suggested tasks or confirmation                                       |
 | POST   | `/api/issues/:issueId/interactions/:interactionId/respond` | Respond to structured questions                                             |
+| POST   | `/api/issues/:issueId/interactions/:interactionId/verdicts` | Submit partial item verdicts for `request_item_verdicts`                 |
 | GET    | `/api/issues/:issueId/documents`   | List issue documents                                                                     |
 | GET    | `/api/issues/:issueId/documents/:key` | Get issue document by key                                                            |
 | PUT    | `/api/issues/:issueId/documents/:key` | Create or update issue document (send `baseRevisionId` when updating)                |

package/skills/paperclip/references/cases.md

@@ -0,0 +1,295 @@
+# Cases
+
+Cases are agent-owned work records for durable outputs such as blog posts,
+research packets, release notes, incidents, QA runs, or generated asset sets.
+They are company-scoped and live beside issues: issues coordinate work, while
+cases preserve the structured object an agent is producing.
+
+Cases are experimental and must be enabled with `experimental.enableCases`.
+If a route returns `403 Cases are disabled`, stop and report that the operator
+must enable cases before the skill can use this surface.
+
+## Core Model
+
+A case has:
+
+- `identifier`: server-assigned display id such as `PAP-C42`
+- `caseType`: skill-owned type such as `blog_post`, `image_assets`, or `incident`
+- `key`: optional deterministic upsert key inside `(companyId, caseType)`
+- `title` and optional `summary`
+- `status`: `draft`, `in_progress`, `in_review`, `approved`, `done`, or `cancelled`
+- `fields`: JSON object owned by the skill using the case
+- `parentCaseId`: optional parent case for child work
+- documents, attachments, issue links, labels, and events
+
+Use deterministic `caseType` + `key` when a skill may be retried. Repeating
+`POST /api/companies/:companyId/cases` with the same `caseType` and `key`
+upserts the same case instead of creating a duplicate.
+
+## Upsert Semantics
+
+`POST /api/companies/:companyId/cases` creates or upserts a case.
+
+Request:
+
+```json
+{
+  "caseType": "blog_post",
+  "key": "launch-announcement",
+  "title": "Launch announcement",
+  "summary": "Draft launch post for operators.",
+  "status": "draft",
+  "fields": {
+    "slug": "launch-announcement",
+    "target_audience": "operators"
+  }
+}
+```
+
+Response:
+
+- `201` when a new case was created
+- `200` when an existing `(caseType, key)` case was updated
+
+Field behavior on upsert:
+
+- `title` is required and replaces the previous title.
+- `projectId`, `summary`, `status`, `fields`, and `parentCaseId` replace the
+  previous value when present.
+- Omitted optional values preserve the previous value during upsert.
+- `fields` is replaced as a whole object when provided. It is not deep-merged.
+  Send the complete desired JSON object each time.
+- Concurrent retries with the same `(caseType, key)` converge to one case.
+
+Do not use a random `key` for retryable skills. Use a stable content slug,
+external id, source URL hash, or parent-derived request key.
+
+## Read And Search
+
+Get a case by UUID or identifier:
+
+```http
+GET /api/cases/PAP-C42
+```
+
+List cases for a company:
+
+```http
+GET /api/companies/:companyId/cases?type=blog_post&status=active&q=launch
+```
+
+Useful filters:
+
+- `type`: exact `caseType`
+- `status`: exact lifecycle status, or `active` for non-terminal cases
+- `projectId` / `project`: project UUID
+- `labelId` / `label`: label UUID
+- `q`: identifier, title, summary, or key search
+- `limit`: 1-200, default 100
+
+## Documents
+
+Use case documents for rich bodies such as drafts, briefs, reports, or plans.
+
+```http
+PUT /api/cases/:caseIdOrIdentifier/documents/body
+Content-Type: application/json
+
+{
+  "title": "Launch announcement body",
+  "format": "markdown",
+  "body": "# Launch announcement\n\nDraft copy...",
+  "changeSummary": "Initial draft"
+}
+```
+
+Updating an existing case document requires `baseRevisionId`:
+
+```json
+{
+  "baseRevisionId": "latest-revision-uuid",
+  "body": "Updated body"
+}
+```
+
+If you get `409 stale_base_revision`, refetch the case detail, read the latest
+document revision id, merge intentionally, and retry with that `baseRevisionId`.
+
+## Fields
+
+Each skill owns the schema of `fields` for the `caseType` it creates. Keep fields
+small, typed, and stable enough for other agents to inspect.
+
+Examples:
+
+```json
+{
+  "slug": "launch-announcement",
+  "target_audience": "operators",
+  "publish_url": "https://example.com/blog/launch-announcement"
+}
+```
+
+Patch fields or status with:
+
+```http
+PATCH /api/cases/:caseIdOrIdentifier
+Content-Type: application/json
+
+{
+  "status": "in_review",
+  "fields": {
+    "slug": "launch-announcement",
+    "target_audience": "operators",
+    "publish_url": "https://example.com/blog/launch-announcement"
+  }
+}
+```
+
+Remember: `fields` replaces the whole object when present.
+
+## Issue Links
+
+Link cases to issues explicitly when needed:
+
+```http
+POST /api/cases/:caseIdOrIdentifier/links
+Content-Type: application/json
+
+{
+  "issueId": "issue-uuid",
+  "role": "reference"
+}
+```
+
+Roles:
+
+- `origin`: the issue/run that created the case
+- `work`: an issue/run that changed the case
+- `reference`: related issue context
+
+Agent run writes auto-link the run's issue when Paperclip can resolve it from
+the run JWT or `X-Paperclip-Run-Id`. Creation/upsert writes use `origin`; later
+document, patch, and attachment writes use `work` when no link already exists.
+You do not need to manually link the current issue before writing the case.
+
+## Child Cases
+
+Create child cases by setting `parentCaseId` to the parent case UUID.
+
+```json
+{
+  "caseType": "image_assets",
+  "key": "launch-announcement:hero-images",
+  "title": "Hero images for launch announcement",
+  "parentCaseId": "parent-case-uuid",
+  "fields": {
+    "required_assets": ["hero", "social-card"]
+  }
+}
+```
+
+Use child cases when the output has independently inspectable pieces or when
+another agent can work on a bounded part without editing the parent case body.
+
+## Attachments
+
+Attach generated files with multipart form data:
+
+```http
+POST /api/cases/:caseIdOrIdentifier/attachments
+Content-Type: multipart/form-data
+
+file=@hero.png
+```
+
+The server records an asset and adds an `attachment_added` case event.
+
+## Lifecycle
+
+Use the lifecycle consistently:
+
+- `draft`: case exists but useful work has not started
+- `in_progress`: an agent is actively producing or revising it
+- `in_review`: ready for reviewer, board, or downstream approval
+- `approved`: accepted but not finally shipped or archived
+- `done`: complete and no further action remains
+- `cancelled`: intentionally abandoned
+
+Terminal statuses are `done` and `cancelled`; setting either records
+`completedAt`. Moving back to a non-terminal status clears `completedAt`.
+
+## Worked Blog Post Example
+
+Create or upsert the parent blog post:
+
+```http
+POST /api/companies/:companyId/cases
+Content-Type: application/json
+
+{
+  "caseType": "blog_post",
+  "key": "paperclip-cases-launch",
+  "title": "Introducing Paperclip Cases",
+  "summary": "Blog post explaining the cases surface for agent outputs.",
+  "status": "in_progress",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "target_audience": "AI company operators",
+    "publish_url": null
+  }
+}
+```
+
+Write the body:
+
+```http
+PUT /api/cases/PAP-C42/documents/body
+Content-Type: application/json
+
+{
+  "title": "Introducing Paperclip Cases",
+  "format": "markdown",
+  "body": "# Introducing Paperclip Cases\n\n..."
+}
+```
+
+Create the child image-assets case:
+
+```http
+POST /api/companies/:companyId/cases
+Content-Type: application/json
+
+{
+  "caseType": "image_assets",
+  "key": "paperclip-cases-launch:image-assets",
+  "title": "Image assets for Introducing Paperclip Cases",
+  "parentCaseId": "parent-case-uuid",
+  "status": "in_progress",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "required_assets": ["hero", "social-card"],
+    "publish_url": null
+  }
+}
+```
+
+Attach generated assets to the child, then patch both cases as they move through
+review:
+
+```http
+PATCH /api/cases/PAP-C42
+Content-Type: application/json
+
+{
+  "status": "in_review",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "target_audience": "AI company operators",
+    "publish_url": "https://example.com/blog/paperclip-cases-launch"
+  }
+}
+```
+
+If the same skill retries the example with the same keys, it updates the parent
+and child cases rather than creating duplicates.

package/skills/paperclip/references/company-skills.md

@@ -4,7 +4,7 @@ Use this reference when a board user, CEO, or manager asks you to find a skill,
 
 ## What Exists
 
-- App-shipped catalog: a curated set of company skills in `@paperclipai/skills-catalog`, browseable and installable without leaving Paperclip.
+- App-shipped catalog: a curated set of company skills in `@penclipai/skills-catalog`, browseable and installable without leaving Paperclip.
 - Company skill library: install, inspect, update, audit, reset, and read company skills for the whole company.
 - Agent skill assignment: add or remove company skills on an existing agent.
 - Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.

package/skills/paperclip-board/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: paperclip-board
 description: >
-  Manage a Paperclip company as a board member via chat. Covers onboarding
-  (company creation, CEO setup, hiring plans), agent management, approvals,
-  task monitoring, cost oversight, and work product review. Use this skill
-  whenever the user wants to interact with their Paperclip control plane.
+  Manage a Paperclip company as a board member via chat. Use when the user wants
+  onboarding, company or agent management, approvals, task monitoring, cost
+  oversight, or work product review in the Paperclip control plane.
 ---
 
 # Paperclip Board Skill

package/skills/paperclip-converting-plans-to-tasks/SKILL.md

@@ -1,13 +1,9 @@
 ---
 name: paperclip-converting-plans-to-tasks
 description: >
-  The Paperclip way of converting a plan into executable tasks. Use whenever
-  you are asked to plan, scope, or break down work inside a Paperclip company.
-  Industry-agnostic guidance on how to translate a plan into assigned issues
-  with the right specialty, dependencies, and parallelization so Paperclip's
-  executor can pick up the work — it does not prescribe a plan format. Pair
-  with the `paperclip` skill, which covers the mechanics of writing the plan
-  document and reassigning the issue.
+  Convert Paperclip plans into executable issue graphs. Use when asked to plan,
+  scope, or break down Paperclip company work into assigned tasks with specialty
+  fit, dependencies, blockers, and parallelization.
 ---
 
 # Paperclip — Converting Plans to Tasks

package/skills/para-memory-files/SKILL.md

@@ -1,13 +1,9 @@
 ---
 name: para-memory-files
 description: >
-  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
-  you need to store, retrieve, update, or organize knowledge across sessions. Covers
-  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
-  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
-  handles planning files, memory decay, weekly synthesis, and recall via qmd.
-  Trigger on any memory operation: saving facts, writing daily notes, creating
-  entities, running weekly synthesis, recalling past context, or managing plans.
+  Use a file-based PARA memory system to store, retrieve, and organize durable
+  knowledge across sessions. Trigger on saving facts, daily notes, entity
+  records, weekly synthesis, recall, tacit user patterns, or plan memory.
 ---
 
 # PARA Memory Files

package/ui-dist/assets/{abnfDiagram-VRR7QNED-BsFz2IiG.js → abnfDiagram-VRR7QNED-Dtgfy1PK.js}

@@ -1 +1 @@
-import{g as p,r as u,d as a}from"./chunk-MOJQB5TN-Clfi83rK.js";import{p as f}from"./chunk-JWPE2WC7-CA07x4av.js";import{_ as n,l as o}from"./mermaid.core-DhvH8shK.js";import{M as c,b as d}from"./cynefin-VYW2F7L2-BQSQ1HKr.js";import"./index-D__fTsb2.js";var v=d().RailroadAbnf.parser.LangiumParser,i=n(e=>{const r=e.alternatives.map(g);return r.length===1?r[0]:{type:"choice",alternatives:r}},"transformAlternation"),g=n(e=>{const r=e.elements.map(y);return r.length===1?r[0]:{type:"sequence",elements:r}},"transformConcatenation"),b=n(e=>{if(e.includes("*")){const[t,s]=e.split("*"),l=t?parseInt(t,10):0,m=s?parseInt(s,10):1/0;return{min:l,max:m}}const r=parseInt(e,10);return{min:r,max:r}},"parseRepeat"),y=n(e=>{const r=A(e.primary);if(!e.repeat)return r;const{min:t,max:s}=b(e.repeat);return t===0&&s===1?{type:"optional",element:r}:{type:"repetition",element:r,min:t,max:s}},"transformElement"),A=n(e=>{switch(e.$type){case"AbnfStringLiteral":return{type:"terminal",value:e.value};case"AbnfNumVal":return{type:"terminal",value:e.value};case"AbnfRuleName":return{type:"nonterminal",name:e.name};case"AbnfGroup":return i(e.element);case"AbnfOptionalGroup":return{type:"optional",element:i(e.element)};default:throw new Error(`Unsupported ABNF primary node: ${e.$type}`)}},"transformPrimary"),P=n(e=>({name:e.name,definition:i(e.definition)}),"transformRule"),h=n(e=>{f(e,a),e.title&&a.setTitle(e.title),e.rules.map(r=>a.addRule(P(r)))},"populateDb"),R={parse:n(e=>{a.clear(),o.debug("[ABNF Parser] Starting Langium parse");const r=v.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new c(r);const t=r.value;o.debug("[ABNF Parser] Parsed rules:",t.rules.length),h(t),o.debug("[ABNF Parser] Parse complete")},"parse"),parser:{yy:a}},B={parser:R,db:a,renderer:u,styles:p};export{B as diagram};
+import{g as p,r as u,d as a}from"./chunk-MOJQB5TN-BEhQg0uD.js";import{p as f}from"./chunk-JWPE2WC7-DGo3MPmr.js";import{_ as n,l as o}from"./mermaid.core-DnsEVfbd.js";import{M as c,b as d}from"./cynefin-VYW2F7L2-DfZ8Hzqi.js";import"./index-DIKcgxCt.js";var v=d().RailroadAbnf.parser.LangiumParser,i=n(e=>{const r=e.alternatives.map(g);return r.length===1?r[0]:{type:"choice",alternatives:r}},"transformAlternation"),g=n(e=>{const r=e.elements.map(y);return r.length===1?r[0]:{type:"sequence",elements:r}},"transformConcatenation"),b=n(e=>{if(e.includes("*")){const[t,s]=e.split("*"),l=t?parseInt(t,10):0,m=s?parseInt(s,10):1/0;return{min:l,max:m}}const r=parseInt(e,10);return{min:r,max:r}},"parseRepeat"),y=n(e=>{const r=A(e.primary);if(!e.repeat)return r;const{min:t,max:s}=b(e.repeat);return t===0&&s===1?{type:"optional",element:r}:{type:"repetition",element:r,min:t,max:s}},"transformElement"),A=n(e=>{switch(e.$type){case"AbnfStringLiteral":return{type:"terminal",value:e.value};case"AbnfNumVal":return{type:"terminal",value:e.value};case"AbnfRuleName":return{type:"nonterminal",name:e.name};case"AbnfGroup":return i(e.element);case"AbnfOptionalGroup":return{type:"optional",element:i(e.element)};default:throw new Error(`Unsupported ABNF primary node: ${e.$type}`)}},"transformPrimary"),P=n(e=>({name:e.name,definition:i(e.definition)}),"transformRule"),h=n(e=>{f(e,a),e.title&&a.setTitle(e.title),e.rules.map(r=>a.addRule(P(r)))},"populateDb"),R={parse:n(e=>{a.clear(),o.debug("[ABNF Parser] Starting Langium parse");const r=v.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new c(r);const t=r.value;o.debug("[ABNF Parser] Parsed rules:",t.rules.length),h(t),o.debug("[ABNF Parser] Parse complete")},"parse"),parser:{yy:a}},B={parser:R,db:a,renderer:u,styles:p};export{B as diagram};