@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0 → 2026.925.2

package/skills/paperclip/references/artifacts.md

@@ -2,6 +2,8 @@
 
 When work produces a user-inspectable file, upload true deliverables to the current issue before final disposition. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.
 
+Attachment upload is a multipart upload and has no MCP tool, so it keeps its own helper. Everything else on this page — listing and deleting attachments, and recording work products — is done with the `core` toolset tools named below.
+
 Use Bash to run the helper bundled with this skill; installed skill files may not retain executable permissions. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
 
 ```bash
@@ -12,6 +14,37 @@ bash scripts/paperclip-upload-artifact.sh path/to/output.webm \
 
 The helper uses `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_TASK_ID`, and `PAPERCLIP_RUN_ID`. It uploads the file as an issue attachment, creates an attachment-backed artifact work product by default, and prints issue-safe markdown links for your final comment.
 
+## Inspect What Is Already On The Issue
+
+- `paperclipListIssueAttachments` with `{ "id": "<issue-id>" }` lists the files attached to the issue, including each `attachmentId`.
+- `paperclipListIssueWorkProducts` with `{ "id": "<issue-id>" }` lists the recorded work products. Add `"refreshPullRequests": "true"` when you need pull request state refreshed first.
+- `paperclipDeleteAttachment` with `{ "attachmentId": "<attachment-id>" }` removes an attachment you uploaded by mistake. It is destructive; do not delete attachments you did not create.
+
+## Record The Work Product
+
+When the uploaded file is the deliverable, record it with `paperclipCreateIssueWorkProduct`. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
+
+```json
+{
+  "id": "<issue-id>",
+  "type": "artifact",
+  "provider": "paperclip",
+  "title": "Walkthrough render",
+  "status": "ready_for_review",
+  "reviewState": "needs_board_review",
+  "isPrimary": true,
+  "metadata": { "attachmentId": "<uploaded-attachment-id>" }
+}
+```
+
+Read the returned work product record before you report the deliverable. If the tool returns an error instead of a record, the work product does not exist — fix the cause and retry rather than describing it as recorded.
+
+When a recorded work product changes later, for example when its pull request merges, patch it with `paperclipUpdateWorkProduct` using the work product id:
+
+```json
+{ "id": "<work-product-id>", "status": "done" }
+```
+
 ## Workspace-Only File References
 
 Use a workspace-only reference only when the file should stay in the project or
@@ -20,10 +53,12 @@ or other file whose value is tied to the checkout. This is not a substitute for
 uploading a deliverable file that a board user should be able to inspect outside
 the workspace.
 
-Annotate the work product with `metadata.resourceRef`:
+Annotate the work product with `metadata.resourceRef`, again through
+`paperclipCreateIssueWorkProduct`:
 
 ```json
 {
+  "id": "<issue-id>",
   "type": "document",
   "provider": "workspace",
   "title": "Regression test plan",
@@ -49,46 +84,6 @@ Annotate the work product with `metadata.resourceRef`:
 optional positive integers. `relativePath` must be relative to the selected
 workspace root; do not use host-local absolute paths in `resourceRef`.
 
-Create the work product with:
-
-```bash
-curl -sS -X POST \
-  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  --data-binary @workspace-file-work-product.json
-```
-
-If the helper is unavailable, use the Paperclip API directly:
-
-```bash
-curl -sS -X POST \
-  "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -F 'file=@"path/to/output.webm";type=video/webm'
-```
-
-Then create a work product when the file is the deliverable. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
-
-```bash
-curl -sS -X POST \
-  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  --data-binary '{
-    "type": "artifact",
-    "provider": "paperclip",
-    "title": "Walkthrough render",
-    "status": "ready_for_review",
-    "reviewState": "needs_board_review",
-    "isPrimary": true,
-    "metadata": { "attachmentId": "<uploaded-attachment-id>" }
-  }'
-```
-
 In your final issue comment, link the uploaded attachment or work product and
 describe what it contains. If the output is workspace-only, name the work
 product and the relative path that was recorded in `metadata.resourceRef`.
@@ -97,6 +92,8 @@ chip or link cannot open it; it is not the preferred deliverable path. Do not
 leave artifact-producing work `in_progress` with only a local path or a
 `Remaining` note.
 
+## External Chat Responses
+
 When the current run was started by an external chat request and the file is
 part of the response intended for that external conversation, have the upload
 helper bind that specific file to an explicit response comment:
@@ -107,21 +104,20 @@ bash scripts/paperclip-upload-artifact.sh path/to/result.png \
   --chat-comment "Here is the requested image."
 ```
 
-`--chat-comment` uses the current run-scoped API directly, so it does not depend
-on a separately installed CLI version. It first uploads the file and creates
-the same-run artifact work product, then binds that exact attachment to the
-comment. Concurrent matching invocations on one host serialize by API, company,
-task, run, filename, content hash, and media type. On retry, the helper reuses
-the server's immutable same-run attachment record instead of uploading a second
-copy. A retry from a different host is still subject to server-side attachment
-admission and should not be run concurrently.
-
-If the upload connection ends without an HTTP response, the helper records that
-ambiguous outcome locally. The same command polls briefly for Paperclip's
-immutable attachment record and otherwise stops instead of blindly creating a
-duplicate. Retry later. Use `--retry-unknown-upload` only after establishing
-that the first upload did not commit; this explicit override accepts the risk of
-creating a duplicate file.
+It first uploads the file and creates the same-run artifact work product, then
+binds that exact attachment to the comment. Concurrent matching invocations on
+one host serialize by API, company, task, run, filename, content hash, and media
+type. On retry, the helper reuses the server's immutable same-run attachment
+record instead of uploading a second copy. A retry from a different host is
+still subject to server-side attachment admission and should not be run
+concurrently.
+
+If the upload ends without a response, the helper records that ambiguous outcome
+locally. The same command polls briefly for Paperclip's immutable attachment
+record and otherwise stops instead of blindly creating a duplicate. Retry later.
+Use `--retry-unknown-upload` only after establishing that the first upload did
+not commit; this explicit override accepts the risk of creating a duplicate
+file.
 
 The binding is durable Paperclip state, but it is not proof of external
 delivery—or even proof that the current run has an active external-chat origin.
@@ -147,7 +143,8 @@ When `register_deliverable` is available, use it for files in the bound local or
 remote workspace. Supply a workspace-relative `contentRef`, basename `filename`,
 `contentType`, exact `byteSize` and SHA-256, `title`, and a stable `idempotencyKey`.
 The tool verifies the file, stores an attachment and artifact work product, and
-binds it to the response. Generic API tools and a legacy API key are unnecessary.
+binds it to the response. Do not also record the same file with
+`paperclipCreateIssueWorkProduct`; the receipt already covers it.
 
 Wait for the receipt. It includes `attachmentId`, `contentPath`, and
 `downloadPath`, along with the existing command, revision, entity references,

package/skills/paperclip/references/cases.md

@@ -6,9 +6,14 @@ 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
+If a case tool reports `Cases are disabled`, stop and report that the operator
 must enable cases before the skill can use this surface.
 
+The case tools are in the `extended` toolset: they are available when the
+operator enables `PAPERCLIP_MCP_TOOLSETS=core,extended`. When they are not
+loaded, use `paperclipApiRequest` for the same operations. Every tool below
+takes `companyId` only where noted; it defaults to the agent's company.
+
 ## Core Model
 
 A case has:
@@ -23,14 +28,12 @@ A case has:
 - 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.
+`paperclipCreateCase` 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:
+`paperclipCreateCase` creates or upserts a case:
 
 ```json
 {
@@ -46,10 +49,9 @@ Request:
 }
 ```
 
-Response:
-
-- `201` when a new case was created
-- `200` when an existing `(caseType, key)` case was updated
+The result is the case record, whether it was newly created or an existing
+`(caseType, key)` case that was updated. Read `identifier` and `id` from it for
+the follow-up calls.
 
 Field behavior on upsert:
 
@@ -66,36 +68,37 @@ external id, source URL hash, or parent-derived request key.
 
 ## Read And Search
 
-Get a case by UUID or identifier:
+Get a case by UUID or identifier with `paperclipGetCase`:
 
-```http
-GET /api/cases/PAP-C42
+```json
+{ "caseId": "PAP-C42" }
 ```
 
-List cases for a company:
+List cases for a company with `paperclipListCases`:
 
-```http
-GET /api/companies/:companyId/cases?type=blog_post&status=active&q=launch
+```json
+{ "type": "blog_post", "status": "active", "q": "launch" }
 ```
 
-Useful filters:
+Useful arguments:
 
-- `type`: exact `caseType`
-- `status`: exact lifecycle status, or `active` for non-terminal cases
+- `type` / `types`: exact `caseType`
+- `status` / `statuses`: exact lifecycle status, or `active` for non-terminal cases
 - `projectId` / `project`: project UUID
 - `labelId` / `label`: label UUID
+- `parent`: parent case filter
 - `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.
+`paperclipSetCaseDocument` takes the case, the document `key`, and the body:
 
-```http
-PUT /api/cases/:caseIdOrIdentifier/documents/body
-Content-Type: application/json
-
+```json
 {
+  "caseId": "PAP-C42",
+  "key": "body",
   "title": "Launch announcement body",
   "format": "markdown",
   "body": "# Launch announcement\n\nDraft copy...",
@@ -107,13 +110,16 @@ Updating an existing case document requires `baseRevisionId`:
 
 ```json
 {
+  "caseId": "PAP-C42",
+  "key": "body",
   "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`.
+If the tool reports `stale_base_revision`, refetch the case detail, read the
+latest document revision id, merge intentionally, and retry with that
+`baseRevisionId`. A failed call wrote nothing — do not treat it as saved.
 
 ## Fields
 
@@ -130,13 +136,11 @@ Examples:
 }
 ```
 
-Patch fields or status with:
-
-```http
-PATCH /api/cases/:caseIdOrIdentifier
-Content-Type: application/json
+Patch fields or status with `paperclipUpdateCase`:
 
+```json
 {
+  "caseId": "PAP-C42",
   "status": "in_review",
   "fields": {
     "slug": "launch-announcement",
@@ -150,13 +154,11 @@ 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
+Link cases to issues explicitly when needed with `paperclipCreateCaseLink`:
 
+```json
 {
+  "id": "PAP-C42",
   "issueId": "issue-uuid",
   "role": "reference"
 }
@@ -169,13 +171,14 @@ Roles:
 - `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
+the run context the tools carry. 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.
+Create child cases with `paperclipCreateCase` by setting `parentCaseId` to the
+parent case UUID.
 
 ```json
 {
@@ -194,16 +197,11 @@ 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.
+Case attachments are a multipart file upload, and multipart has no MCP tool.
+Upload generated files as issue attachments with the upload helper described in
+`artifacts.md`, then connect them to the case with `paperclipCreateCaseLink`
+using the issue that holds the files. The case then carries the link, and the
+issue carries the inspectable file.
 
 ## Lifecycle
 
@@ -221,12 +219,9 @@ Terminal statuses are `done` and `cancelled`; setting either records
 
 ## Worked Blog Post Example
 
-Create or upsert the parent blog post:
-
-```http
-POST /api/companies/:companyId/cases
-Content-Type: application/json
+Create or upsert the parent blog post with `paperclipCreateCase`:
 
+```json
 {
   "caseType": "blog_post",
   "key": "paperclip-cases-launch",
@@ -241,25 +236,21 @@ Content-Type: application/json
 }
 ```
 
-Write the body:
-
-```http
-PUT /api/cases/PAP-C42/documents/body
-Content-Type: application/json
+Write the body with `paperclipSetCaseDocument`:
 
+```json
 {
+  "caseId": "PAP-C42",
+  "key": "body",
   "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
+Create the child image-assets case with `paperclipCreateCase`:
 
+```json
 {
   "caseType": "image_assets",
   "key": "paperclip-cases-launch:image-assets",
@@ -274,14 +265,12 @@ Content-Type: application/json
 }
 ```
 
-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
+Attach the generated assets to the child's linked issue, then patch both cases
+as they move through review with `paperclipUpdateCase`:
 
+```json
 {
+  "caseId": "PAP-C42",
   "status": "in_review",
   "fields": {
     "slug": "paperclip-cases-launch",