docs(gmail): clarify that drafts delete is permanent

[chrischall]

Fixes #656.

Problem

gog gmail drafts delete is permanent and irreversible — the Gmail API's users.drafts.delete deletes the draft outright; drafts are not moved to Trash and there's no untrash path (gog gmail trash operates on message IDs only). But the command's help ("Delete a draft") and confirmation prompt ("delete gmail draft <id>") read like an ordinary, recoverable delete, so the irreversibility wasn't surfaced before confirming.

Change

• Command help → Permanently delete a draft (not recoverable; drafts are not moved to Trash).
• Destructive-confirmation/refusal wording → permanently delete gmail draft <id> (not recoverable; drafts are not moved to Trash).
• Doc comment on GmailDraftsDeleteCmd explaining why it's irreversible.
• Regenerated the command reference (make docs-commands) so the published docs match.

No behavioural change — same API call, same dryRunAndConfirmDestructive guard; only the wording is clarified.

Real-behavior proof (built from this branch)

gog gmail drafts --help (parent listing):

  delete (rm,del,remove) <draftId>
    Permanently delete a draft (not recoverable; drafts are not moved to Trash)

gog gmail drafts delete --help:

Usage: gog gmail (mail,email) drafts (draft) delete (rm,del,remove) <draftId>

Permanently delete a draft (not recoverable; drafts are not moved to Trash)

Destructive confirmation/refusal (gog gmail drafts delete <id>, no --force):

refusing to permanently delete gmail draft demo-draft-id-12345 (not recoverable; drafts are not moved to Trash) without --force (non-interactive)

--dry-run intended action:

{ "dry_run": true, "op": "gmail.drafts.delete", "request": { "draft_id": "demo-draft-id-12345" } }

Review follow-ups addressed

• [P1] proof — added above (redacted terminal output of the updated help + confirmation prompt).
• [P2] generated docs — ran make docs-commands; docs/commands/gog-gmail-drafts-delete.md, gog-gmail-drafts.md, commands.generated.md, and commands/README.md now carry the permanent-delete wording (no stale Delete a draft).
• [P3] CHANGELOG — dropped the contributor CHANGELOG edit; release notes are release-owned.

make fmt + go test ./internal/cmd/ green.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 30, 2026, 1:43 PM ET / 17:43 UTC.

Summary
This PR updates Gmail drafts delete help and destructive-confirmation wording, regenerates command docs, and adds an unreleased changelog entry.

Reproducibility: not applicable. for this docs/help PR as a runtime bug reproduction. Current main source confirms the old generic wording, and the PR body provides branch terminal output for the updated help and refusal path.

Review metrics: 1 noteworthy metric.

• Touched surface: 6 files changed; 10 additions, 6 deletions. The diff is small but spans the CLI help source, generated docs, and changelog, so alignment matters before merge.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• [P2] No repair lane is needed; this clean open PR only needs normal maintainer merge review.

Security
Cleared: The diff only changes CLI/help wording, generated docs, and changelog text; it adds no dependencies, scripts, credentials handling, or execution paths.

Review details

Best possible solution:

Land this wording-only PR if maintainers accept documentation as the path for #656, keeping CLI help and generated docs aligned.

Do we have a high-confidence way to reproduce the issue?

Not applicable for this docs/help PR as a runtime bug reproduction. Current main source confirms the old generic wording, and the PR body provides branch terminal output for the updated help and refusal path.

Is this the best way to solve the issue?

Yes. For the documentation path requested by the linked issue, updating the command help, destructive confirmation text, and generated command reference is the narrowest maintainable fix without changing Gmail API behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 32ad20a0306e.

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P2: The PR addresses a normal-priority Gmail safety/documentation gap around irreversible draft deletion with limited code surface.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-change terminal output for the updated help text, refusal wording, and dry-run JSON.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-change terminal output for the updated help text, refusal wording, and dry-run JSON.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully and its PR review guidance was applied by keeping the checkout on main and using read-only inspection. (AGENTS.md:1, 32ad20a0306e)
• Current main still has generic wording: Current main advertises Gmail drafts delete as "Delete a draft" and confirms the action as "delete gmail draft", so this PR is not obsolete on main. (internal/cmd/gmail_drafts.go:19, 32ad20a0306e)
• PR source changes are narrow: The contributor commit updates one Go command file and four generated command-doc files to warn that drafts are permanently deleted and not moved to Trash. (internal/cmd/gmail_drafts.go:19, 822f293d4599)
• Merge result keeps behavior aligned: The merge ref shows the updated help string, doc comment, confirmation text, generated docs, and changelog together in a six-file diff. (internal/cmd/gmail_drafts.go:19, e2157c2ff9b5)
• Real behavior proof is present: The PR body includes after-change terminal output for parent help, command help, non-interactive refusal text, and dry-run JSON from the branch. (89827b10e223)
• Relevant history: Blame shows the Gmail drafts command and generated command pages currently on main trace back to the v0.19.0 release commit, before this clarification. (internal/cmd/gmail_drafts.go:19, b25a3c029b37)

Likely related people:

• steipete: The current Gmail drafts command and generated command docs blame to the v0.19.0 release commit authored by Peter Steinberger, and the latest PR head includes a separate changelog commit by the same account. (role: introduced behavior and recent area contributor; confidence: high; commits: b25a3c029b37, 89827b10e223; files: internal/cmd/gmail_drafts.go, docs/commands/gog-gmail-drafts-delete.md, CHANGELOG.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[chrischall]

@clawsweeper re-review — added real-behavior proof (help + confirmation prompt terminal output) to the PR body, regenerated the command docs via make docs-commands, and dropped the CHANGELOG edit.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26686353069
• Updated: 2026-05-30T14:35:27.817Z