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

package/skills/paperclip/references/artifacts.md

@@ -0,0 +1,158 @@
+# Generated Artifacts and Work Products
+
+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.
+
+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
+bash scripts/paperclip-upload-artifact.sh path/to/output.webm \
+  --title "Walkthrough render" \
+  --summary "Rendered walkthrough for review"
+```
+
+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.
+
+## Workspace-Only File References
+
+Use a workspace-only reference only when the file should stay in the project or
+execution workspace, such as a source file, committed report, generated index,
+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`:
+
+```json
+{
+  "type": "document",
+  "provider": "workspace",
+  "title": "Regression test plan",
+  "status": "ready_for_review",
+  "reviewState": "needs_board_review",
+  "summary": "Markdown plan committed in the execution workspace.",
+  "metadata": {
+    "resourceRef": {
+      "kind": "workspace_file",
+      "issueId": "<issue-id>",
+      "workspaceKind": "execution_workspace",
+      "workspaceId": "<execution-workspace-id>",
+      "relativePath": "doc/plans/regression-test-plan.md",
+      "line": 1,
+      "displayPath": "doc/plans/regression-test-plan.md"
+    }
+  }
+}
+```
+
+`workspaceKind` is `execution_workspace` for the current issue checkout or
+`project_workspace` for a shared project workspace. `line` and `column` are
+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`.
+Browse/search is the fallback for recovering a workspace file when the issue
+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.
+
+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:
+
+```bash
+bash scripts/paperclip-upload-artifact.sh path/to/result.png \
+  --title "Requested image" \
+  --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.
+
+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.
+For an authorized active chat-origin run, Paperclip keeps this selection
+internal until it selects the run's final response, then attempts the provider
+publication. The final assistant response may use different prose from
+`--chat-comment`.
+
+Treat the helper's exit status as confirmation that the Paperclip attachment,
+work product, and requested comment binding were saved. Use neutral final prose
+such as “I prepared the requested image.” Do not claim the file is shown above,
+attached, queued, or delivered. If the bind step fails after upload, say that
+the artifact was saved to the Paperclip task but was **not** bound to the
+response comment; never also claim that it appears above or is attached.
+
+Do not infer sharing intent from other files on the task or bind every
+attachment from a run. Only the file passed with `--chat-comment` is eligible
+for external publication; unbound artifacts remain Paperclip-only.
+
+**Native runner**
+
+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.
+
+Wait for the receipt. It includes `attachmentId`, `contentPath`, and
+`downloadPath`, along with the existing command, revision, entity references,
+and disposition. Reuse the original key after an ambiguous result. A receipt
+confirms storage and response binding in Paperclip; it does not confirm delivery
+to an external chat provider. If registration fails, use the returned error to
+resolve the failure or explain the limitation; do not describe a workspace path
+as an uploaded file.

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.