PAP-10512 document browsable file completion guidance

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 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.
+When your task produces a user-inspectable deliverable 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. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path. See `doc/AGENT-ARTIFACTS.md` for details and `.mp4`/`.webm` examples.
 
 ## 6. Database Change Workflow
 

doc/AGENT-ARTIFACTS.md

@@ -1,9 +1,9 @@
 # Agent Artifact Upload Workflow
 
-Generated files that a board user or reviewer should inspect must be attached to
-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.
+Generated files that a board user or reviewer should inspect as deliverables
+must be attached to 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 bundled with the Paperclip skill from the repo root:
 
@@ -27,9 +27,43 @@ It uploads the file to
 artifact work product on `POST /api/issues/{issueId}/work-products` by default.
 The command prints issue-safe markdown links for the final task comment.
 
+## Uploaded Artifacts vs Workspace Files
+
+Use uploaded artifacts for deliverables: videos, PDFs, screenshots, archives,
+reports, rendered HTML, or any file the board should inspect without needing the
+agent's checkout. Attachment-backed artifact work products set `type` to
+`artifact` and `provider` to `paperclip`, with metadata canonicalized from the
+uploaded `attachmentId`.
+
+Use `workspace_file` metadata only for important files that intentionally remain
+in a project or execution workspace, such as source files, committed markdown
+plans, or generated files whose meaning depends on the checkout. Workspace-only
+references are useful signposts, but they are not durable uploads.
+
+Expected work product metadata shape:
+
+```json
+{
+  "resourceRef": {
+    "kind": "workspace_file",
+    "issueId": "<issue-id>",
+    "workspaceKind": "execution_workspace",
+    "workspaceId": "<execution-workspace-id>",
+    "relativePath": "doc/plans/example.md",
+    "line": 1,
+    "column": 1,
+    "displayPath": "doc/plans/example.md:1:1"
+  }
+}
+```
+
+`workspaceKind` is `execution_workspace` or `project_workspace`. `line` and
+`column` are optional. `relativePath` must be relative to that workspace root;
+do not store host-local absolute paths as workspace references.
+
 ## Completion Pattern
 
-When a task produces a user-inspectable file:
+When a task produces a user-inspectable deliverable file:
 
 1. Generate and verify the file locally.
 2. Upload it with `skills/paperclip/scripts/paperclip-upload-artifact.sh`.
@@ -38,9 +72,12 @@ When a task produces a user-inspectable file:
 4. Link the printed attachment URL in the final issue comment.
 5. Then set the final issue status.
 
-Final comments should name the uploaded artifact, not just the local filesystem
-path. Local paths can be included as diagnostic context, but they cannot be the
-only access path.
+Final comments should name and link the uploaded artifact or work product, not
+just the local filesystem path. For workspace-only files, include the work
+product title and recorded relative path. Local paths can be included as
+diagnostic context, but they cannot be the only access path. Browse/search is a
+fallback for recovering workspace files when the issue link or chip is not
+available, not the preferred way to deliver files to users.
 
 ## Video Examples
 

doc/DEVELOPING.md

@@ -214,9 +214,9 @@ pnpm paperclipai configure --section storage
 
 ## Agent Artifact Uploads
 
-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.
+When an agent generates a file that a board user or reviewer should inspect as
+a deliverable, 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 bundled with the Paperclip skill from the repo root:
 
@@ -237,6 +237,10 @@ skills/paperclip/scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
 The helper uploads the file as an issue attachment, creates an artifact work
 product by default, and prints markdown links for the final issue comment. See
 `doc/AGENT-ARTIFACTS.md` for the full completion pattern and direct API shape.
+If a file intentionally remains workspace-only, create a work product with
+`metadata.resourceRef.kind: "workspace_file"` and include the workspace-relative
+path in the final comment. Use browse/search only as the fallback for recovering
+that file, not as the main completion path for deliverables.
 
 ## Default Agent Workspaces
 

doc/SPEC-implementation.md

@@ -402,6 +402,7 @@ Operational policy:
   - Inline-safe responses use `Content-Disposition: inline`; unsafe types and explicit download requests use `attachment`.
   - Video attachments are inline-safe and support single `Range: bytes=start-end` requests with `206`, `Content-Range`, and `Accept-Ranges: bytes` for browser playback/seeking.
 - Attachment-backed artifact work products use `type: "artifact"`, `provider: "paperclip"`, and metadata with `attachmentId`, `contentType`, `byteSize`, `contentPath`, `openPath`, `downloadPath`, and optional `originalFilename`.
+- Workspace-only file references use work product `metadata.resourceRef` with `kind: "workspace_file"`, `issueId`, `workspaceKind` (`execution_workspace` or `project_workspace`), `workspaceId`, `relativePath`, optional `line`/`column`, and `displayPath`. These references point at files in a workspace; they do not replace attachment-backed artifacts for deliverables that must be inspectable without workspace access.
 
 ## 7.15 `documents` + `document_revisions` + `issue_documents`
 

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 `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.
+- When your work produces a user-inspectable deliverable 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. If an important file intentionally remains workspace-only, create/update a work product with `metadata.resourceRef.kind: "workspace_file"` and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable 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

@@ -100,7 +100,9 @@ If `currentParticipant` does not match you, do not try to advance the stage —
 
 ### Generated Artifacts and Work Products
 
-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.
+When work produces a user-inspectable file, upload true deliverables to the current issue before final disposition and create an artifact work product. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.
+
+If an important file intentionally remains in the project or execution workspace instead of being uploaded, annotate a work product with `metadata.resourceRef.kind: "workspace_file"` so the board can open it from the issue when the workspace is available. Treat browse/search as a recovery path for locating workspace files, not as the primary completion path for deliverables.
 
 For technical upload instructions, read `references/artifacts.md`.
 

skills/paperclip/references/artifacts.md

@@ -1,6 +1,6 @@
 # Generated Artifacts and Work Products
 
-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.
+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 the helper bundled with this skill. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
 
@@ -12,6 +12,54 @@ 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.
 
+## 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
@@ -41,4 +89,10 @@ curl -sS -X POST \
   }'
 ```
 
-In your final issue comment, link the uploaded attachment or work product and describe what it contains. Do not leave artifact-producing work `in_progress` with only a local path or a `Remaining` note.
+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.