Add restore command

[code-monger-givenall]

What changed

Adds hey restore <thread-id>... for restoring one or more email threads from Trash.

• accepts positive topic_id values and deduplicates repeated IDs
• calls SDK Topics().Restore once per thread and stops on the first failure
• states clearly that restore is Trash-only and does not take a box item ID
• points to hey search --in trash --json as the current ID source and to hey thread list --in trash --json once List system views through thread list #161 lands

The earlier mark-spam command and its supporting surface have been removed.

Validation

• GOWORK=off TMPDIR=/tmp mise exec -- make check
• focused unit and race tests pass
• the smoke-test module compiles
• no live mailbox mutation was run

[Copilot]

Pull request overview

Adds SDK-backed mailbox controls for restoring trashed topics and marking individual entries as spam.

Changes:

• Adds and registers both commands with validation and output handling.
• Adds request, validation, help, and command-surface tests.
• Updates user and agent documentation.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/hey/SKILL.md	Adds agent guidance and examples.
README.md	Documents both commands and ID types.
internal/cmd/topic_controls.go	Implements both mailbox controls.
internal/cmd/topic_controls_test.go	Tests requests and validation.
internal/cmd/root.go	Registers the commands.
internal/cmd/help.go	Adds commands to curated help.
internal/cmd/help_test.go	Updates the help snapshot.
API-COVERAGE.md	Records SDK endpoint coverage.
.surface	Updates the CLI surface baseline.

Suppressed comments (1)

internal/cmd/topic_controls.go:65

• The user-facing hey mark-spam --help output only shows Short, so it omits the PR's promised warning to confirm the exact entry ID before changing mailbox state; the annotation is limited to agent help. Add the warning to a Long description.

		Use:     "mark-spam <entry-id>",
		Short:   "Mark an email entry as spam",
		Example: "  hey mark-spam 12345",

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[jeremy]

Thanks for keeping this one refreshed. Read against current main, half of it is a clear gap and half is already covered, so here's what I'd like to take.

Keep hey restore. Nothing on main brings a thread back from Trash; the SDK's Topics().Restore (PUT /topics/{id}/status/active.json) has been sitting unused. Three adjustments:

• Accept one or more IDs, like hey trash and its siblings, and loop the per-topic call.
• Name the ID kind in Use and in agent_notes: this takes a thread ID, not the box item ID the other verbs take, because a trashed thread has no box item any more. Say where the ID comes from: the topic_id column of hey search --in trash today, and the trash listing from List system views through thread list #161 once that lands.
• Say in the help that this restores from Trash only. The SDK also has MarkHam for Spam; leave that out of scope rather than guessing which state the thread is in.

Drop hey mark-spam. main already has hey spam <box-item-id>..., which marks threads as spam through the bulk posting route, so a second verb at entry granularity with a near-identical name adds surface without adding a capability people are asking for. If an entry-level spam mark turns out to have a use, it can come on its own.

Rebase notes: main has moved. internal/cmd/trash.go is the shape to copy (requireAuth, parseIntArgs, usageMinOneArg, writeMutation), the shared topic_controls.go helpers are no longer needed with mark-spam gone, and hey box is now hey box view in the docs and examples.

[code-monger-givenall]

Rebased onto current main and narrowed to restore-only in c790ad7.

hey restore <thread-id>... now accepts one or more positive topic_id values, deduplicates repeats, calls Topics().Restore for each ID, and stops on the first failure. Help and agent guidance state that this is Trash-only and uses thread IDs from hey search --in trash --json today; #161 adds the direct Trash thread listing. The earlier mark-spam surface is fully removed.

Validation: focused unit/race coverage and GOWORK=off TMPDIR=/tmp mise exec -- make check pass; the separate smoke module compiles. No live mailbox mutation was run.