Document retry/idempotency characteristics and add pagination hints

[scottlovegrove]

Priority: Low

Context

Based on 7 Principles for Agent-Friendly CLIs:

• Principle 4 (Safe Retries): "Agents retry, resume, and replay commands more frequently than humans. For append/send/trigger operations where exact idempotence proves impossible, mutation boundaries should remain explicit with identifiers letting agents determine if work repeated."
• Principle 7 (Bounded, High-Signal Responses): "When truncating, CLIs should teach agents how to narrow queries."

Part 1: Document retry/idempotency in skill content

Problem

Agents don't know which commands are safe to retry. Creating a thread twice makes two threads. Archiving an already-archived thread is a no-op. An agent has no way to know this without experimenting.

Proposed solution

Add a section to SKILL_CONTENT in src/lib/skills/content.ts documenting retry behaviour:

## Retry Safety

Commands that are safe to retry (idempotent):
- `thread done`, `conversation done` — archiving an already-archived item is a no-op
- `thread mute`, `thread unmute` — setting the same mute state is a no-op
- `conversation mute`, `conversation unmute` — same

Commands that produce duplicates on retry:
- `thread create` — creates a new thread each time
- `thread reply` — posts a new comment each time
- `conversation reply` — sends a new message each time

Use `--dry-run` to preview mutations before executing. All create/send commands return the created object's `id` in `--json` mode, which can be used to detect unintended duplicates.

Part 2: Add pagination hints to human-readable output

Problem

When results are paginated, the JSON/NDJSON output includes nextCursor metadata, but the human-readable output doesn't tell the user (or agent) that there are more results or how to get them. An agent falling back to human output won't know results were truncated.

Proposed solution

Add a footer line to paginated human-readable output when there are more results:

── 25 threads shown. More results available — use --limit, --since, or --until to adjust. ──

or when a cursor is available:

── Showing first 50 results. Use --json or --ndjson for cursor-based pagination. ──

This applies to:

• tw inbox
• tw thread view (comments list)
• tw conversation view (messages list)
• tw conversation list
• tw search

Implementation would go in the output formatting section of each command, after the main results are printed, checking if nextCursor is non-null.