Bundle artifact upload helper with Paperclip skill

Co-Authored-By: Paperclip <noreply@paperclip.ing>

AGENTS.md

@@ -85,7 +85,7 @@ Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` ali
 When you are creating a plan file in the repository itself, new plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issue `plan` document per the `paperclip` skill instead of creating a repo markdown file.
 
 6. Attach inspectable generated artifacts.
-When your task produces a user-inspectable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. In this repo, prefer `scripts/paperclip-upload-artifact.sh` so the file is available through the Paperclip API, create/update an artifact work product when the file is the deliverable, link the uploaded artifact in the final issue comment, and then set status. Do not rely on local filesystem paths as the only access path. See `doc/AGENT-ARTIFACTS.md` for `.mp4` and `.webm` examples.
+When your task produces a user-inspectable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. In this repo, prefer the self-contained skill helper at `skills/paperclip/scripts/paperclip-upload-artifact.sh` so the file is available through the Paperclip API, create/update an artifact work product when the file is the deliverable, link the uploaded artifact in the final issue comment, and then set status. Do not rely on local filesystem paths as the only access path. See `doc/AGENT-ARTIFACTS.md` for `.mp4` and `.webm` examples.
 
 ## 6. Database Change Workflow
 

doc/AGENT-ARTIFACTS.md

@@ -5,10 +5,10 @@ the Paperclip issue before the agent chooses a final disposition. A local
 workspace path is not enough, because cloud users and reviewers often cannot
 access the agent's disk.
 
-Use the helper from the repo root:
+Use the helper bundled with the Paperclip skill from the repo root:
 
 ```sh
-scripts/paperclip-upload-artifact.sh path/to/output.webm \
+skills/paperclip/scripts/paperclip-upload-artifact.sh path/to/output.webm \
   --title "Walkthrough render" \
   --summary "Rendered walkthrough for review"
 ```
@@ -32,7 +32,7 @@ The command prints issue-safe markdown links for the final task comment.
 When a task produces a user-inspectable file:
 
 1. Generate and verify the file locally.
-2. Upload it with `scripts/paperclip-upload-artifact.sh`.
+2. Upload it with `skills/paperclip/scripts/paperclip-upload-artifact.sh`.
 3. Keep the artifact work product unless the file is incidental; pass
    `--no-work-product` only for supporting files that should not be promoted.
 4. Link the printed attachment URL in the final issue comment.
@@ -47,7 +47,7 @@ only access path.
 Upload an `.mp4` render:
 
 ```sh
-scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
+skills/paperclip/scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
   --title "Demo video render" \
   --summary "MP4 render for board review"
 ```
@@ -55,7 +55,7 @@ scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
 Upload a `.webm` render:
 
 ```sh
-scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
+skills/paperclip/scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
   --title "Walkthrough video" \
   --summary "WebM walkthrough render"
 ```
@@ -64,7 +64,7 @@ The helper detects `.mp4`, `.webm`, and `.mov` content types. If a renderer uses
 an unusual extension, pass the MIME type explicitly:
 
 ```sh
-scripts/paperclip-upload-artifact.sh render.bin \
+skills/paperclip/scripts/paperclip-upload-artifact.sh render.bin \
   --title "Demo video render" \
   --content-type video/mp4
 ```

doc/DEVELOPING.md

@@ -218,10 +218,10 @@ When an agent generates a file that a board user or reviewer should inspect,
 attach it to the issue before marking the task complete. Do not rely on a local
 workspace path as the only access path.
 
-Use the helper from the repo root:
+Use the helper bundled with the Paperclip skill from the repo root:
 
 ```sh
-scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
+skills/paperclip/scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
   --title "Demo video render" \
   --summary "MP4 render for board review"
 ```
@@ -229,7 +229,7 @@ scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
 For WebM output:
 
 ```sh
-scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
+skills/paperclip/scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
   --title "Walkthrough video" \
   --summary "WebM walkthrough render"
 ```

server/src/__tests__/agent-skills-routes.test.ts

@@ -702,7 +702,7 @@ describe.sequential("agent skill routes", () => {
       expect(mockAgentInstructionsService.materializeManagedBundle).toHaveBeenCalledWith(
         expect.any(Object),
         expect.objectContaining({
-          "AGENTS.md": expect.stringContaining("scripts/paperclip-upload-artifact.sh"),
+          "AGENTS.md": expect.stringContaining("skills/paperclip/scripts/paperclip-upload-artifact.sh"),
         }),
         expect.any(Object),
       );

server/src/__tests__/paperclip-skill-utils.test.ts

@@ -51,6 +51,10 @@ describe("paperclip skill utils", () => {
     expect(skillBody).toContain("POST");
     expect(skillBody).toContain("/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments");
     expect(skillBody).toContain("/api/issues/$PAPERCLIP_TASK_ID/work-products");
+    await expect(
+      fs.access(path.resolve("skills/paperclip/scripts/paperclip-upload-artifact.sh")),
+    ).resolves.toBeUndefined();
+    await expect(fs.access(path.resolve("scripts/paperclip-upload-artifact.sh"))).rejects.toThrow();
   });
 
   it("marks skills with required: false in SKILL.md frontmatter as optional", async () => {

server/src/onboarding-assets/default/AGENTS.md

@@ -5,7 +5,7 @@ You are an agent at Paperclip company.
 - Start actionable work in the same heartbeat. Do not stop at a plan unless the issue explicitly asks for planning.
 - Keep the work moving until it is done. If you need QA to review it, ask them. If you need your boss to review it, ask them.
 - Leave durable progress in task comments, documents, or work products, then update the issue to a clear final disposition before you exit.
-- When your work produces a user-inspectable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. Use `scripts/paperclip-upload-artifact.sh` when working in this repo, create/update an artifact work product when the file is the deliverable, and link the uploaded attachment in the final comment. Do not rely on local filesystem paths as the only access path.
+- When your work produces a user-inspectable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. Use `skills/paperclip/scripts/paperclip-upload-artifact.sh` when working in this repo, create/update an artifact work product when the file is the deliverable, and link the uploaded attachment in the final comment. Do not rely on local filesystem paths as the only access path.
 - Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.
 - Final disposition checklist: mark `done` when complete and verified; use `in_review` only with a real reviewer, approval, interaction, or monitor path; use `blocked` only with first-class blockers or a named unblock owner/action; create delegated follow-up issues with blockers when another agent owns the next step; keep `in_progress` only when a live continuation path exists.
 - Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.

skills/paperclip/SKILL.md

@@ -98,7 +98,7 @@ If `currentParticipant` does not match you, do not try to advance the stage —
 
 When work produces a user-inspectable file, upload it 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 the repo helper when it exists in the active workspace:
+Use the helper bundled with this skill. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
 
 ```bash
 scripts/paperclip-upload-artifact.sh path/to/output.webm \

skills/paperclip/scripts/paperclip-upload-artifact.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 Usage:
-  scripts/paperclip-upload-artifact.sh FILE [options]
+  paperclip-upload-artifact.sh FILE [options]
 
 Uploads a generated file from the current workspace to the current Paperclip
 issue, then creates an attachment-backed artifact work product by default.