Backlog

The backlog holds tasks that are not GitHub issues yet. Park an idea, attach supporting files, and promote it to an issue when it is ready — at which point the agent starts working it through the normal path.

Backlog items live only on the agent. They are not visible to GitHub until you promote them. The GUI Board’s Backlog column is this store.

Create and edit

Method	Path	Purpose
GET	/api/backlog	List items with attachment metadata
POST	/api/backlog	Create (title required, body optional)
PATCH	/api/backlog/{id}	Update title / body
DELETE	/api/backlog/{id}	Delete the item and its attachments

In the GUI, the item editor is a modal with a title, a Markdown body with a toolbar (H2, bold, code, list, checklist) and a preview toggle, and an attachment list.

Attachments

Attachments stay on the agent. Upload bytes as padded standard base64:

POST /api/backlog/{id}/attachments
{ "name": "log.txt", "content_type": "text/plain", "data": "<base64>" }

• Per-file cap: 10 MiB.
• Request body cap: 16 MiB (base64 expansion plus the JSON envelope).
• Filenames are reduced to a bounded basename; the content type is validated and falls back to application/octet-stream.
• Downloads: GET /api/backlog/{id}/attachments/{attachment_id}.
• Delete: DELETE /api/backlog/{id}/attachments/{attachment_id}.

Downloads are never rendered as active content on the agent origin. Only image/png, image/jpeg, image/gif, image/webp, application/pdf, and text/plain open inline; everything else (including SVG and HTML) is sent as an attachment with X-Content-Type-Options: nosniff.

Promote to an issue

POST /api/backlog/{id}/promote

Promotion:

1. Builds the issue body from the item body (or title, if the body is empty).
2. Appends an Attachments section with Markdown links to each attachment on the agent’s origin. The origin comes from X-Forwarded-Proto + Host, so links use the public URL behind a proxy.
3. Files the issue through the operator path with your pickup_labels (default steelframe:work-on-this) plus steelframe:from-tui.
4. Starts task_lifecycle immediately.
5. Deletes the backlog row but keeps the attachments, so the issue’s links keep resolving.

The response is the same as POST /api/operator/message: issue_number, issue_url, task_started, and workflow_run_id when a task started.

Tip

Promote from the GUI’s backlog editor with one action; the item is filed and the task starts in the same request.

Gotchas

• Attachment bytes live in the agent’s database and are served by the agent; the GitHub issue links only resolve for clients that can reach the agent (VPN, LAN, or the public URL).
• Promoting deletes the item row but not its attachments — a later manual delete of the item removes them.
• An empty title or an empty promote body is rejected.
• Filename characters that would break Markdown link syntax ([, ]) are escaped in the issue body.