[AJCJ1]

Adds a way to report a bad render straight from the CLI, plus a shortcut to the support page (as a precursor to reporting an issue with the CLI itself).

urlbox report <renderId> files a render report with the Urlbox team (a category and a short comment).

• Agents and scripts pass --category and --comment and get no prompts.
• In an interactive terminal without those flags, it prompts: a category picker, then a one-line description.
• JSON output returns the full report and quiet output returns the report id only

A post-render hint. After a render, the CLI prints one muted line naming the render id and the ready-to-run report command:

✓ Rendered: https://renders.urlbox.com/…png
  Something wrong with this render? Report it: urlbox report 01a0…_ps

It only appears in a real terminal in text mode. Piped, JSON, and quiet output aren't changed.

urlbox support opens the contact page in the browser (prints the URL instead when there's no browser, and never launches one in JSON/quiet mode) — the same shape as urlbox dashboard.

Notes

• The render id for the hint comes from the API's response header (and the error body on failures); it's held in memory only, so no response shape changes. - this avoids requiring an API change
• Reports are limited to a category and a comment for now — no region/area highlighting.

[cjroebuck]

Really nice work on this, Arnold. urlbox report feels at home in the CLI: support mirrors dashboard exactly, the report reuses the session plumbing, and the hint gating (text + TTY only, JSON/quiet envelopes byte-identical) is exactly the right call for agents. Capturing the render id from the header in-memory, so no API change is needed, is a neat solution too. The tests cover every output mode, which made this easy to review.

I checked it out locally: go build, go vet and go test ./... are all green. I also checked it against the render-reports contract on mono main. The path, the six categories and the 2000-char comment cap all line up.

A few things I'd like us to close before merging:

1. The report hint also appears on errors that aren't render failures

The API attaches requestId to every presentable error body: invalid API key, validation errors, rate limits, quota exhausted. do() in internal/api/http_client.go wraps any error carrying a requestId in RenderIDError, so e.g. a render with a bad secret prints:

Error: …invalid API key…
Something wrong with this render? Report it: urlbox report <id>

No render doc exists for that id, so following the hint would most likely 404 (exit 5). Could we only attach the hint for genuine render outcomes, i.e. 5xx / engine failure codes, and skip auth/usage/validation/rate-limit? appendReportHint looks like the natural place for that check since it already has the CLIError code.

2. Planning docs: happy for them to go in, with internal details kept out

Keeping the spec/plan/handoff in docs/superpowers/ is fine by me. This repo is public though, so let's adopt a rule for these docs: no mentions of internal infrastructure, setup, configs or services. In this PR that means taking out things like the mono repo and its internal file paths, Crisp/Slack side effects, "renders are free on his staff account", the in-flight worktree notes and the author email/commit-process instructions. It would be great to add that rule to CLAUDE.md too, so the agents writing these docs follow it automatically. (Ironically the same commit does a great job scrubbing exactly this kind of thing from the code comments 🙂)

Smaller things (nice-to-haves, not blockers)

• Session-less users: someone rendering with only an API secret still sees the hint, then gets exit 3 from urlbox report. Maybe skip the hint when there's no session, or mention urlbox login in it?
• Cancelling a prompt: pressing Esc/Ctrl-C in the category picker or the comment prompt currently returns "missing --category / --comment" (usage, exit 1). A plain "cancelled" would read more naturally.
• Comment length: len(comment) counts bytes, while the server's zod max(2000) counts UTF-16 units. So the CLI rejects non-ASCII comments the API would accept. utf8.RuneCountInString would bring them in line.
• Commit shape: the comment clean-up across ~50 files is a welcome change! As a separate commit it would make the feature diff much easier to follow.

One open question

For sync renders the id comes from x-urlbox-request-id. On a cache HIT, that header is the current request's id. The report service does Render.findOne({ reqId }), so do cache hits get a Render doc of their own? If not, reports on cached renders would 404. A quick live check on your staff account would settle it.

Great feature overall. Once #1 and the docs tweak are in, I'm very happy to approve. Shout if you'd like to pair on the hint gating.

[AJCJ1]

Here is what has been addressed in the force-pushed commit (CI green):

Blockers

1. Hint only on real render failures. appendReportHint now gates on ErrServer, so auth, validation, rate-limit and usage rejections never carry the report hint. Tests cover each case.
2. Planning docs. Removed entirely rather than scrubbed. CLAUDE.md now has a "planning docs are public" rule so this doesn't recur.

Nice-to-haves

• Comment cap counts characters (utf8.RuneCountInString), not bytes, matching the API's 2000 limit for non-ASCII text.
• Esc / Ctrl-C in the category picker or comment prompt now returns "report cancelled" instead of the missing-flags usage error.
• The hint is withheld when the active profile has no session, since urlbox report would fail with exit 3.
• Kept as a single commit, which is how we've done things in this repo.

Cache hits, tested live

• Cache HIT → urlbox report 404s. A MISS on the same URL and a sync POST render both save fine. So cached renders get no render record, as you suspected.
• The CLI now reads x-urlbox-cache-status and withholds the hint on HIT.
• For what it's worth, the sync POST path never returned a HIT for me, even with an explicit ttl, so the ids the CLI's hint produces were already reportable in practice.