CLI: `uploads staged` — first-class view of what's staged for a branch (+ binding state)

[zachdunn]

Problem

With #403, bare put on a branch stages automatically — so "what's currently staged for this branch?" becomes a question agents ask routinely (before opening a PR, before deciding whether to re-capture, when resuming a branch days later). The primitives exist but require insider knowledge:

• uploads list --prefix gh/<repo>/branch/<branch>/ — needs the key layout
• uploads find gh.branch=<name> — needs the metadata vocabulary (gh.staged-at gives recency)

Neither answers the adjacent question an agent actually cares about: will these auto-attach? (repo binding state, #398).

Proposal

A first-class read-only view: uploads staged [--branch <name>] [--repo <owner/name>].

• Defaults: current branch (same resolution stack as CLI: nudge bare put toward --pr/attach when a branch or PR context is detectable #393/CLI: bare put on a branch stages to the branch prefix (branch replaces date as the organizing unit) #403 — resolveCurrentBranch, worktree-safe), repo from the usual --repo/gh/git-remote chain.
• Output per file: key/filename, size, gh.staged-at, public URL. Human mode: compact table-ish lines; --format json: array plus a binding field.
• Folds in the binding tri-state from CLI: warn at stage time when the repo isn't bound (staged files won't auto-attach) #398's GET /github/repo-link and says what it means: self → "these auto-attach when this branch's PR opens"; none/other → the same advisory wording as the CLI: warn at stage time when the repo isn't bound (staged files won't auto-attach) #398 stage warning (one source of truth for those strings — reuse, don't duplicate).
• Ends with the promote affordance when relevant: once the PR exists: uploads attach --promote.
• files:read only; one list call against the staging prefix — no new server surface needed.

Considered and rejected: local history cache

A CLI-side cache of recent uploads was considered for performance and offline recall. Rejected for v1: the CLI is deliberately stateless across invocations (#393 explicitly avoided cross-invocation state), the server list is a single fast call, and a cache can lie after another machine/agent stages to the same branch — the server is the only truthful answer to "what's staged." Revisit only if listing latency actually shows up in practice.

MCP

• Hosted MCP: already covered by list/find_files with a documented prefix/metadata recipe — add that recipe to the tool descriptions or skill rather than a new tool.
• Local stdio MCP: expose staged as a tool mirroring the CLI command (shared implementation).

Sequencing

Blocked on #403 (same code area: commands.ts staging paths, skills). Implement after it merges; update skills/uploads-cli/SKILL.md in the same PR with the new command (and the find/list recipes for hosted-MCP agents).

Testing

Branch/repo resolution matrix (explicit flags, current-branch default, worktrees); empty staging → clean zero-state message (note: find --format json prints empty stdout on zero matches — this command must print []/empty-array JSON instead); binding states wire through; JSON schema; wording reuse from #398 verified by test.

Changeset: minor, @buildinternet/uploads only.

Related: #403, #398, #393.