mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
nightly: issue artifacts — output playback, attachment streaming, skill upload
Cumulative window v2026.529.0 → parent master edeab22c (24h quarantine). One feature cluster: agent-produced issue artifacts (video/file deliverables) that reviewers — including cloud reviewers without workspace access — can view and play back on the board. - docs/reference/api/issues.md — attachment openPath/downloadPath, ?download=1 disposition, HTTP Range (206) streaming, video/zip allowed types + inference. - docs/reference/skills.md — bundled paperclip skill artifact-upload helper. - docs/guides/day-to-day/issues.md — Output section + inline video / open-vs-download. All 3 PR-tier edits verified against parent (verify-edit: 39/39 on api/issues, 0 unverified across all). docs:build + sync:check green. Drift: none. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
Aron PrinsandClaude Opus 4.8 committed
1 parent
9e7a098e6c
commit
5f08200d05
5 files changed
+85
-147
No files matched your search
+33
-34
@@ -2,57 +2,56 @@
|
||||
|
||||
> Regenerated by `/sync-docs` every nightly run. Cumulative from `base_release_tag`.
|
||||
|
||||
- **Base release tag:** `v2026.525.0`
|
||||
- **Parent window:** `v2026.525.0` → parent `master` HEAD `911a1e8`, effective cutoff `524e18b` (24h quarantine)
|
||||
- **Commits in window:** 9 effective (5 commits in quarantine, deferred to next run)
|
||||
- **Doc-relevant manifest entries:** 3 new this run (3 prior-run entries re-derived by cumulative diff, already applied)
|
||||
- **Base release tag:** `v2026.529.0`
|
||||
- **Parent window:** `v2026.529.0` → parent `master` HEAD `70b1a91`, effective cutoff `edeab22c` (24h quarantine)
|
||||
- **Commits in window:** 30 effective (3 commits in quarantine, deferred to next run)
|
||||
- **Doc-relevant manifest entries:** 3 new this run
|
||||
- **Drift candidates:** 0 (check-drift.mjs against master)
|
||||
- **Reconciliation candidates:** 0 (cumulative base is the release tag; all entries are net-new or already applied)
|
||||
- **Reconciliation candidates:** 0 (cumulative base is the release tag; nothing previously applied was reverted upstream)
|
||||
- **Genuine new dirs (rename-checked):** none
|
||||
|
||||
## Auto-merge
|
||||
|
||||
_None._ No `.env.example` / config / env-schema changes in the window — the env-vars watcher matched nothing.
|
||||
|
||||
## Already applied (prior run, commit `51b9fe3`)
|
||||
|
||||
These re-appear in the cumulative diff but are already documented; not re-edited this run.
|
||||
|
||||
1. Resource memberships — join/leave projects & agents (`#6677`)
|
||||
2. Document annotations & comments (`#6733`)
|
||||
3. Bundled plugins in plugin manager (`#6734`)
|
||||
|
||||
## PR-tier — applied this run
|
||||
|
||||
### 1. Skills CLI command group (`#6782`)
|
||||
All three entries belong to one feature cluster: **agent-produced issue artifacts** (videos and files) that reviewers can see and play back directly on the board, including cloud reviewers who don't have access to the agent workspace.
|
||||
|
||||
- **Watcher:** cli-commands
|
||||
- **Parent files:** `cli/src/index.ts` (`registerSkillsCommands(program)`); `cli/src/commands/client/skills.ts` (new).
|
||||
- **Change kind:** added — new `paperclipai skills` command tree.
|
||||
- **Surface:** `skills browse|search|inspect|install|list|show|file|import|create|scan-projects|check|update|audit|reset|remove` plus the `skills agent list|sync|clear` subgroup.
|
||||
- **Docs targets:** `docs/reference/cli/control-plane-commands.md` (new "Skills Commands" workflow section); `docs/reference/cli/commands.md` (full `skills` subcommand + flag reference).
|
||||
- **Evidence:** All command names, arguments, flags, and defaults (e.g. `--path` default `SKILL.md`, `--kind bundled|optional`) copied verbatim from `skills.ts`.
|
||||
### 1. Issue attachment streaming & artifact downloads
|
||||
|
||||
### 2. App-shipped skills catalog + lifecycle (`#6782`)
|
||||
- **Watcher:** rest-routes
|
||||
- **Parent files:** `server/src/routes/issues.ts`, `server/src/attachment-types.ts`
|
||||
- **Change kind:** modified.
|
||||
- **Surface:** Each attachment now exposes `openPath` and `downloadPath` alongside `contentPath`. The content route accepts `?download=1` to force a download disposition and supports HTTP **Range** requests (`206 Partial Content`, `Accept-Ranges`, `Content-Range`) so video can stream/seek. Default allowed upload types gain `application/zip`, `video/mp4`, `video/webm`, `video/quicktime`; generic `octet-stream` uploads get their video content-type inferred from the filename.
|
||||
- **Docs targets:** `docs/reference/api/issues.md` (Attachments section).
|
||||
|
||||
- **Watcher:** rest-routes, agent-skills, schemas, server-services
|
||||
- **Parent files:** `server/src/routes/company-skills.ts` (new catalog + lifecycle routes); `server/src/services/skills-catalog.ts` (new); `packages/skills-catalog/**` (new package: bundled + optional SKILL.md bundles).
|
||||
### 2. Paperclip skill artifact-upload workflow
|
||||
|
||||
- **Watcher:** agent-skills
|
||||
- **Parent files:** `skills/paperclip/references/artifacts.md` (new), `skills/paperclip/scripts/paperclip-upload-artifact.sh` (new), `skills/paperclip/SKILL.md` (modified).
|
||||
- **Change kind:** added.
|
||||
- **Docs targets:** `docs/reference/skills.md` (new "App-shipped catalog" section + corrected versioning row); `docs/guides/org/skills.md` (friendly "install a ready-made skill" subsection).
|
||||
- **Evidence:** Browse routes (auth-only, NOT company-scoped) `GET /api/skills/catalog`, `/api/skills/catalog/{catalogId}`, `/api/skills/catalog/{catalogId}/files`; lifecycle routes (company-scoped) `POST .../skills/install-catalog` (`{ catalogSkillId, slug?, force? }`), `.../skills/:skillId/audit`, `.../install-update`, `.../reset`. `CatalogSkillKind = bundled | optional`; `sourceKind: catalog`. Soft holds (local mods, `force`-overridable) vs hard-stop audit findings.
|
||||
- **Surface:** The bundled Paperclip skill now tells agents to upload user-inspectable output files to the current issue (as attachment-backed artifact work products) instead of leaving local workspace paths behind. A bundled `paperclip-upload-artifact.sh` helper does the upload and prints issue-safe markdown links.
|
||||
- **Docs targets:** `docs/reference/skills.md`.
|
||||
|
||||
### 3. Private browser first-admin claim (`#6755`)
|
||||
### 3. Issue Output section + rich attachment previews
|
||||
|
||||
- **Watcher:** rest-routes, server-services
|
||||
- **Parent files:** `server/src/routes/access.ts` (new `/bootstrap/claim` route); `server/src/first-admin-claim.ts` (new).
|
||||
- **Change kind:** added.
|
||||
- **Docs targets:** `docs/reference/api/instance-admin.md` ("Claim first instance admin" section); `docs/guides/getting-started/installation.md` (note under the private/Tailscale variation).
|
||||
- **Evidence:** `POST /api/bootstrap/claim` — gated to `deploymentMode = authenticated` + `deploymentExposure = private` (else 404); requires signed-in browser session (else 401); promotes first signed-in user to `instance_admin` atomically; 409 if already claimed; success `{ claimed: true, userId }`.
|
||||
- **Watcher:** web-ui
|
||||
- **Parent files:** `ui/src/pages/IssueDetail.tsx`, `ui/src/components/IssueAttachmentsSection.tsx`, `ui/src/components/issue-output/*`.
|
||||
- **Change kind:** modified.
|
||||
- **Surface:** The issue detail view gains an **Output** section that plays agent-produced video inline and renders rich previews for file deliverables; attachments expose distinct open vs. download actions.
|
||||
- **Docs targets:** `docs/guides/day-to-day/issues.md`.
|
||||
- **Screenshots:** 10 stale (see `SCREENSHOTS_PENDING.md`) — all entries tracking `ui/src/pages/IssueDetail.tsx`.
|
||||
|
||||
## Considered, not documented
|
||||
|
||||
- **Accepted-plan decomposition exact-once guards (`#6831`)** — internal reliability/correctness guard with UI state; no user-facing surface to document.
|
||||
- **CI runner Chrome for headless workflows (`#6967`, `524e18b0`)** — CI-only; not product-facing.
|
||||
- **`.github/**` commitperclip PR quality & security gates** — parent-repo CI infrastructure, not a Paperclip product surface.
|
||||
- **`scripts/dev-runner*` snapshot race fix** — dev tooling.
|
||||
- **`ui` StandaloneBrowserControls + pwa-display-mode** — PWA chrome for installed/cloud viewing; screenshot-adjacent only, folded into the Output narrative rather than given its own copy.
|
||||
|
||||
## ⚠ Anchor-map gap
|
||||
|
||||
- **`packages/skills-catalog/**` is unwatched.** A new bundled **wireframe** product skill landed in the skills catalog (`packages/skills-catalog/catalog/bundled/product/wireframe/**`), but no watcher globs `packages/skills-catalog/**` — the `agent-skills` watcher only globs `skills/**`. The prior run manually routed catalog changes to `docs/reference/skills.md` + `docs/guides/org/skills.md`, so the doc target exists; the map just doesn't auto-detect it. **Action:** add/extend a watcher so future catalog skills are caught.
|
||||
|
||||
## ⚠ Drift
|
||||
|
||||
@@ -64,4 +63,4 @@ _None._
|
||||
|
||||
## In quarantine (deferred to next run, <24h old at run time)
|
||||
|
||||
`1f70fd9a` workspace finalize gates + no-remote-git enforcement (PAPA-430) · `5153b01a` Claude model refresh · `8014445b` v2026.529.0 release changelog · `aea35fe6` exe.dev config UX · `911a1e8b` continuation recovery retry streaks
|
||||
`70b1a91` Improve CLI API parity coverage (#6626) — large CLI/API parity push (new `cli/src/commands/client/*` command groups + `server/src/routes/openapi.ts`) · `68401f8` Remove linked-issue gate from commitperclip (#7423) · `d58a862` fix(issues): coerce anchor.createdAt to Date before postgres binding (#5220)
|
||||
+5
-108
@@ -1,92 +1,15 @@
|
||||
# Screenshots — pending recapture
|
||||
|
||||
> Regenerated by `/sync-docs` (release mode, v2026.529.0). Entries whose `depends_on` parent paths changed in the v2026.525.0 → v2026.529.0 window.
|
||||
> Regenerated by `/sync-docs` (nightly mode). Entries whose `depends_on` parent paths changed in the cumulative window.
|
||||
|
||||
- **Window:** `v2026.525.0` → `v2026.529.0` (parent `911a1e8`)
|
||||
- **Stale entries:** 90 of 276
|
||||
- **Window:** `v2026.529.0` → parent `master` `70b1a91`, effective cutoff `edeab22c` (24h quarantine)
|
||||
- **Stale entries:** 10 of 276
|
||||
- **Recapture:** `npm run screenshots:refresh` (stale only) or `npm run screenshots:refresh:all` (full). Output PNGs land in a PR for human review — never auto-pushed.
|
||||
|
||||
## `ui/src/components/AgentConfigForm.tsx` — 20
|
||||
|
||||
- `dark/agents/adapter-type-dropdown.png`
|
||||
- `dark/agents/budget-and-heartbeat-fields.png`
|
||||
- `dark/agents/claude-local-config-filled.png`
|
||||
- `dark/agents/codex-local-config.png`
|
||||
- `dark/agents/heartbeat-toggle-disabled.png`
|
||||
- `dark/agents/heartbeat-toggle-enabled.png`
|
||||
- `dark/agents/http-adapter-config.png`
|
||||
- `dark/agents/test-environment-fail.png`
|
||||
- `dark/agents/test-environment-success.png`
|
||||
- `dark/org/reassign.png`
|
||||
- `light/agents/adapter-type-dropdown.png`
|
||||
- `light/agents/budget-and-heartbeat-fields.png`
|
||||
- `light/agents/claude-local-config-filled.png`
|
||||
- `light/agents/codex-local-config.png`
|
||||
- `light/agents/heartbeat-toggle-disabled.png`
|
||||
- `light/agents/heartbeat-toggle-enabled.png`
|
||||
- `light/agents/http-adapter-config.png`
|
||||
- `light/agents/test-environment-fail.png`
|
||||
- `light/agents/test-environment-success.png`
|
||||
- `light/org/reassign.png`
|
||||
|
||||
## `ui/src/pages/AgentDetail.tsx` — 24
|
||||
|
||||
- `dark/agents/agent-detail-idle.png`
|
||||
- `dark/agents/agent-detail-run-history.png`
|
||||
- `dark/agents/agent-status-running.png`
|
||||
- `dark/agents/budget.png`
|
||||
- `dark/agents/configuration.png`
|
||||
- `dark/agents/dashboard.png`
|
||||
- `dark/agents/instructions.png`
|
||||
- `dark/agents/run-history-in-progress.png`
|
||||
- `dark/agents/run-transcript-view.png`
|
||||
- `dark/agents/runs.png`
|
||||
- `dark/agents/skills.png`
|
||||
- `dark/costs/agent-budget-field.png`
|
||||
- `light/agents/agent-detail-idle.png`
|
||||
- `light/agents/agent-detail-run-history.png`
|
||||
- `light/agents/agent-status-running.png`
|
||||
- `light/agents/budget.png`
|
||||
- `light/agents/configuration.png`
|
||||
- `light/agents/dashboard.png`
|
||||
- `light/agents/instructions.png`
|
||||
- `light/agents/run-history-in-progress.png`
|
||||
- `light/agents/run-transcript-view.png`
|
||||
- `light/agents/runs.png`
|
||||
- `light/agents/skills.png`
|
||||
- `light/costs/agent-budget-field.png`
|
||||
|
||||
## `ui/src/pages/Agents.tsx` — 6
|
||||
|
||||
- `dark/agents/agents-list-empty.png`
|
||||
- `dark/agents/list.png`
|
||||
- `dark/agents/new.png`
|
||||
- `light/agents/agents-list-empty.png`
|
||||
- `light/agents/list.png`
|
||||
- `light/agents/new.png`
|
||||
|
||||
## `ui/src/pages/CompanySkills.tsx` — 12
|
||||
|
||||
- `dark/org/skills-list.png`
|
||||
- `dark/skills/add-skill-dialog-confirm.png`
|
||||
- `dark/skills/add-skill-dialog.png`
|
||||
- `dark/skills/assign-to-agent.png`
|
||||
- `dark/skills/file-inventory.png`
|
||||
- `dark/skills/list.png`
|
||||
- `light/org/skills-list.png`
|
||||
- `light/skills/add-skill-dialog-confirm.png`
|
||||
- `light/skills/add-skill-dialog.png`
|
||||
- `light/skills/assign-to-agent.png`
|
||||
- `light/skills/file-inventory.png`
|
||||
- `light/skills/list.png`
|
||||
|
||||
## `ui/src/pages/InstanceExperimentalSettings.tsx` — 2
|
||||
|
||||
- `dark/settings/experimental.png`
|
||||
- `light/settings/experimental.png`
|
||||
|
||||
## `ui/src/pages/IssueDetail.tsx` — 10
|
||||
|
||||
> The new **Output** section (inline video playback for agent artifacts) and the reworked attachment previews render inside `IssueDetail.tsx`. The new `IssueAttachmentsSection.tsx` and `issue-output/*` components are not yet tracked in `registry.json` — consider adding registry entries that capture an issue with a video/file artifact once these screenshots are recaptured.
|
||||
|
||||
- `dark/issues/detail-activity.png`
|
||||
- `dark/issues/detail-chat.png`
|
||||
- `dark/issues/detail-sidebar.png`
|
||||
@@ -97,29 +20,3 @@
|
||||
- `light/issues/detail-sidebar.png`
|
||||
- `light/issues/list.png`
|
||||
- `light/tasks/task-detail-with-comments.png`
|
||||
|
||||
## `ui/src/pages/PluginManager.tsx` — 4
|
||||
|
||||
- `dark/plugins/install.png`
|
||||
- `dark/plugins/list.png`
|
||||
- `light/plugins/install.png`
|
||||
- `light/plugins/list.png`
|
||||
|
||||
## `ui/src/pages/ProjectDetail.tsx` — 10
|
||||
|
||||
- `dark/projects/budget.png`
|
||||
- `dark/projects/configuration.png`
|
||||
- `dark/projects/issues.png`
|
||||
- `dark/projects/overview.png`
|
||||
- `dark/projects/workspaces.png`
|
||||
- `light/projects/budget.png`
|
||||
- `light/projects/configuration.png`
|
||||
- `light/projects/issues.png`
|
||||
- `light/projects/overview.png`
|
||||
- `light/projects/workspaces.png`
|
||||
|
||||
## `ui/src/pages/Projects.tsx` — 2
|
||||
|
||||
- `dark/projects/list.png`
|
||||
- `light/projects/list.png`
|
||||
|
||||
@@ -318,7 +318,16 @@ The sidebar exposes the following fields, in order:
|
||||
Above the tabs, separately from the Properties panel, the detail view also renders:
|
||||
|
||||
- An **Issue Workspace card** that summarises the issue's project and its execution workspace binding — the same underlying concept the Workspace / Branch / Folder rows describe, but surfaced as a single card so it is visible even when the sidebar is collapsed.
|
||||
- An **Attachments** section. Images appear as thumbnails that open in a gallery modal; non-image attachments render as file rows with their content type and size. You can upload from the detail view when no attachments exist yet, and from an inline button otherwise.
|
||||
- An **Attachments** section. Images appear as thumbnails that open in a gallery modal; video attachments play back inline in a built-in player; non-image attachments render as file rows with their content type and size. Each attachment offers two actions: **open** previews it inline (images in the gallery, video in the player), while **download** saves the file to disk. Supported media includes images, PDF, text, CSV, JSON, video (mp4, webm, mov/quicktime), and zip archives. You can upload from the detail view when no attachments exist yet, and from an inline button otherwise.
|
||||
|
||||
### Output
|
||||
|
||||
When an agent finishes a piece of work, it can hand back the result directly on the issue. The **Output** section surfaces those deliverables — the work products the agent produced — so you can inspect them right on the board without ever opening the agent's workspace.
|
||||
|
||||
- **Video deliverables play inline.** A recorded result plays back in a built-in player; you can play and seek without downloading anything first.
|
||||
- **File deliverables show as preview cards.** Each one renders as a rich preview, with the primary deliverable highlighted when the agent flags one as the main result.
|
||||
|
||||
This is what makes review possible from anywhere — including for cloud reviewers who have no access to the agent's workspace. You watch or inspect the deliverable in the Output section, then comment or approve from the same issue, without leaving the board.
|
||||
|
||||
### Keyed documents
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ Issue APIs are company-aware. In practice that means:
|
||||
- List and create operations are scoped to `/api/companies/{companyId}/issues`.
|
||||
- Single-issue routes use `/api/issues/{issueId}`.
|
||||
- Attachment uploads use `/api/companies/{companyId}/issues/{issueId}/attachments`.
|
||||
- Attachment downloads use `/api/attachments/{attachmentId}/content`.
|
||||
- Attachment downloads use `/api/attachments/{attachmentId}/content`, which supports inline preview, forced download (`?download=1`), and HTTP Range requests.
|
||||
|
||||
On issue-scoped routes, `{issueId}` can be either:
|
||||
|
||||
@@ -843,7 +843,11 @@ Attachments are file uploads linked to an issue, and optionally to a specific is
|
||||
GET /api/issues/{issueId}/attachments
|
||||
```
|
||||
|
||||
Return all attachments for an issue. Each item includes a `contentPath` that points to the binary download route.
|
||||
Return all attachments for an issue. Each item carries three path fields pointing at the binary content route:
|
||||
|
||||
- `contentPath` — `/api/attachments/{attachmentId}/content`. The raw content route.
|
||||
- `openPath` — same value as `contentPath`. Use it to open or preview the attachment inline.
|
||||
- `downloadPath` — `/api/attachments/{attachmentId}/content?download=1`. Use it to force a download.
|
||||
|
||||
### Upload Attachment
|
||||
|
||||
@@ -864,7 +868,12 @@ Upload rules:
|
||||
- Empty files are rejected.
|
||||
- Files larger than the server limit are rejected.
|
||||
- `issueCommentId` must belong to the same company and issue.
|
||||
- The stored response includes `contentPath` for download.
|
||||
- The content type must be in the allowed-uploads set.
|
||||
- The stored response includes `contentPath`, `openPath`, and `downloadPath`.
|
||||
|
||||
The default allowed upload types are images, PDF, plain text, JSON, CSV, HTML, `application/zip`, and the video types `video/mp4`, `video/webm`, and `video/quicktime`. Video types are also treated as inline-renderable. Override the allowlist with the `PAPERCLIP_ALLOWED_ATTACHMENT_TYPES` environment variable — a comma-separated list of MIME types or wildcard patterns.
|
||||
|
||||
When a file is uploaded with a generic content type (`application/octet-stream`, `binary/octet-stream`, or `application/x-binary`), the server infers a video content type from the filename extension when streaming it back: `.mp4`/`.m4v` → `video/mp4`, `.webm` → `video/webm`, and `.mov`/`.qt`/`.quicktime` → `video/quicktime`.
|
||||
|
||||
### Download Attachment Content
|
||||
|
||||
@@ -874,7 +883,17 @@ GET /api/attachments/{attachmentId}/content
|
||||
|
||||
Stream the attachment bytes.
|
||||
|
||||
The server sets the response headers for inline display or download depending on content type, and SVG content gets a sandboxed content security policy.
|
||||
By default the server sets `Content-Disposition` for inline display when the content type is inline-capable (images, PDF, video, and similar), and otherwise serves it as a download. SVG content gets a sandboxed content security policy.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- `download=1` — force `Content-Disposition: attachment` so the response is always saved as a download instead of rendered inline.
|
||||
|
||||
This route supports HTTP Range requests so large media such as video can stream and seek:
|
||||
|
||||
- The response sets `Accept-Ranges: bytes`.
|
||||
- A valid `Range: bytes=...` request returns `206 Partial Content` with a `Content-Range` header.
|
||||
- An unsatisfiable range returns `416 Range Not Satisfiable` with `Content-Range: bytes */{length}`.
|
||||
|
||||
### Delete Attachment
|
||||
|
||||
|
||||
@@ -105,6 +105,20 @@ Community examples in [`paperclipai/companies`](https://github.com/paperclipai/c
|
||||
|
||||
These are the canonical references for the file shape, frontmatter style, and supporting-file layout.
|
||||
|
||||
### Artifact upload in the bundled `paperclip` skill
|
||||
|
||||
The bundled `paperclip` skill ships an artifact-upload helper so that work products end up on the issue, not stranded in the agent's workspace. Its **Generated Artifacts and Work Products** section in `SKILL.md` tells the agent that whenever a run produces a user-inspectable file, it should upload that file to the current issue before final disposition — a local filesystem path is useless to board users, reviewers, and cloud operators who can't reach the agent workspace.
|
||||
|
||||
The skill bundles a helper script at `scripts/paperclip-upload-artifact.sh` (relative to the installed skill directory) and a reference doc at `references/artifacts.md`. The helper takes a file path plus `--title` and `--summary` flags:
|
||||
|
||||
```bash
|
||||
scripts/paperclip-upload-artifact.sh path/to/output.webm \
|
||||
--title "Walkthrough render" \
|
||||
--summary "Rendered walkthrough for review"
|
||||
```
|
||||
|
||||
It reads the run's environment — `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_TASK_ID`, and `PAPERCLIP_RUN_ID` — then uploads the file as an issue attachment, creates an attachment-backed artifact work product (the default), and prints issue-safe markdown links the agent can drop into its final comment. The underlying upload route is the attachment endpoint documented under [Issues API → Attachments](./api/issues.md#attachments).
|
||||
|
||||
---
|
||||
|
||||
## 2. Installation pipeline
|
||||
|
||||
Reference in new issue
Block a user