Follow-up to #367, which documents how to put a screenshot in an issue or PR by POSTing to uploads.github.com/user-attachments/assets. Documenting it was the right first step — it stops the reinvention — but the guide now carries a five-line curl incantation with a repo-id lookup, and that has two problems.
It is undocumented and unversioned. No REST docs, no gh subcommand (cli/cli#12960, cli/cli#13256 are open feature requests). If GitHub changes or withdraws it, the fix has to land in the shipped guide and reach every deployment through a box update, and until then every agent copies a recipe that silently fails.
The failure mode is a trap. The uploaded URL 404s until a comment references it, and only goes live seconds later. An agent that verifies its own work — which is the good instinct — sees a 404 and concludes the upload failed. That is precisely how we ended up with four assets/* branches and a side repo.
Both get better behind one command, e.g. agent-box-attach shot.png --repo OWNER/REPO printing the markdown line, or the URL, ready to paste into a body:
- one place to fix when the endpoint moves, instead of N transcripts;
- it can swallow the activation race — upload, and either say plainly "this 404s until you reference it" or offer
--verify that polls after the caller posts;
- it can refuse obvious footguns (uploading against a public repo something read out of
~/.config/agent-box/env);
- the guide shrinks to one line, which is what a guide should be.
Worth weighing against just leaving the recipe: a new shipped payload means modules/src/bin/, PATH wiring, a runtime-profile entry and golden churn, for something that is four lines of curl. My recommendation is to wait until either the endpoint actually breaks or a second use case appears (video for a demo, PDF for a report), and keep the documented recipe until then — filing this so that decision is recorded rather than re-derived.
Verified behaviors backing the above are in #367.
Follow-up to #367, which documents how to put a screenshot in an issue or PR by POSTing to
uploads.github.com/user-attachments/assets. Documenting it was the right first step — it stops the reinvention — but the guide now carries a five-linecurlincantation with a repo-id lookup, and that has two problems.It is undocumented and unversioned. No REST docs, no
ghsubcommand (cli/cli#12960, cli/cli#13256 are open feature requests). If GitHub changes or withdraws it, the fix has to land in the shipped guide and reach every deployment through a box update, and until then every agent copies a recipe that silently fails.The failure mode is a trap. The uploaded URL 404s until a comment references it, and only goes live seconds later. An agent that verifies its own work — which is the good instinct — sees a 404 and concludes the upload failed. That is precisely how we ended up with four
assets/*branches and a side repo.Both get better behind one command, e.g.
agent-box-attach shot.png --repo OWNER/REPOprinting the markdown line, or the URL, ready to paste into a body:--verifythat polls after the caller posts;~/.config/agent-box/env);Worth weighing against just leaving the recipe: a new shipped payload means
modules/src/bin/, PATH wiring, a runtime-profile entry and golden churn, for something that is four lines of curl. My recommendation is to wait until either the endpoint actually breaks or a second use case appears (video for a demo, PDF for a report), and keep the documented recipe until then — filing this so that decision is recorded rather than re-derived.Verified behaviors backing the above are in #367.