Add restore and mark-spam commands

[code-monger-givenall]

What changed

This adds two mailbox controls already exposed by the current SDK:

• hey restore <topic-id> returns a trashed topic to active mail
• hey mark-spam <entry-id> marks one email entry as spam

They are separate from the existing posting actions because the APIs use different IDs. hey trash and hey spam take box item IDs, while these commands take a topic ID and an entry ID respectively.

Both commands validate positive IDs and reject list-only output formats before authentication or any HTTP request. Their help and agent guidance call out that they change mailbox state and require confirmation of the exact ID.

Tests

• make check
• command surface validation
• request method and path coverage for both operations
• invalid IDs and incompatible output formats make no request

No live mailbox mutations were used to test this change.

---

Summary by cubic

Adds two mailbox controls: hey restore <topic-id> returns a trashed topic to active mail, and hey mark-spam <entry-id> marks a single email entry as spam. Previously only hey trash/hey spam existed and used box item IDs; these use topic and entry IDs to target the correct objects.

• Hooks commands to SDK methods (Topics().Restore, Entries().MarkSpam) and adds API coverage for the corresponding PUT endpoints.
• Validates positive IDs and rejects --ids-only/--count before auth or any HTTP request; both commands change mailbox state and require the exact ID.
• Registers commands in root.go; adds shared helpers in topic_controls.go for ID parsing, list-format rejection, and summarized output.
• Updates help, .surface, README examples, and skills/hey/SKILL.md.
• Tests cover method/path, help warnings, early validation with no request on invalid input, and smoke flows for restore and mark-spam.

^{Written for commit 3c4c687. Summary will update on new commits.}

[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.