docs(gmail): clarify that drafts delete is permanent

chrischall · claude · steipete · commit 822f293d4599 · 2026-05-30T18:37:33.000+01:00
The Gmail Drafts API only supports an irreversible delete — drafts are not
moved to Trash and there is no untrash path — but `gog gmail drafts delete`
advertised a generic "Delete a draft" and confirmed with "delete gmail draft
&lt;id&gt;", reading like a recoverable operation.

Surface the permanence in the command help, the destructive-confirmation
prompt, and a doc comment on the command type, and regenerate the command
reference (make docs-commands) so the published docs match.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/docs/commands.generated.md b/docs/commands.generated.md
@@ -335,7 +335,7 @@ Generated from `gog schema --json`.
       - [`gog gmail (mail,email) batch modify (update,edit,set) <messageId> ... [flags]`](commands/gog-gmail-batch-modify.md) - Modify labels on multiple messages
     - [`gog gmail (mail,email) drafts (draft) <command>`](commands/gog-gmail-drafts.md) - Draft operations
       - [`gog gmail (mail,email) drafts (draft) create (add,new) [flags]`](commands/gog-gmail-drafts-create.md) - Create a draft
-      - [`gog gmail (mail,email) drafts (draft) delete (rm,del,remove) <draftId>`](commands/gog-gmail-drafts-delete.md) - Delete a draft
+      - [`gog gmail (mail,email) drafts (draft) delete (rm,del,remove) <draftId>`](commands/gog-gmail-drafts-delete.md) - Permanently delete a draft (not recoverable; drafts are not moved to Trash)
       - [`gog gmail (mail,email) drafts (draft) get (info,show) <draftId> [flags]`](commands/gog-gmail-drafts-get.md) - Get draft details
       - [`gog gmail (mail,email) drafts (draft) list (ls) [flags]`](commands/gog-gmail-drafts-list.md) - List drafts
       - [`gog gmail (mail,email) drafts (draft) send (post) <draftId>`](commands/gog-gmail-drafts-send.md) - Send a draft
diff --git a/docs/commands/README.md b/docs/commands/README.md
@@ -386,7 +386,7 @@ Generated pages: 572.
       - [gog gmail batch modify](gog-gmail-batch-modify.md) - Modify labels on multiple messages
     - [gog gmail drafts](gog-gmail-drafts.md) - Draft operations
       - [gog gmail drafts create](gog-gmail-drafts-create.md) - Create a draft
-      - [gog gmail drafts delete](gog-gmail-drafts-delete.md) - Delete a draft
+      - [gog gmail drafts delete](gog-gmail-drafts-delete.md) - Permanently delete a draft (not recoverable; drafts are not moved to Trash)
       - [gog gmail drafts get](gog-gmail-drafts-get.md) - Get draft details
       - [gog gmail drafts list](gog-gmail-drafts-list.md) - List drafts
       - [gog gmail drafts send](gog-gmail-drafts-send.md) - Send a draft
diff --git a/docs/commands/gog-gmail-drafts-delete.md b/docs/commands/gog-gmail-drafts-delete.md
@@ -2,7 +2,7 @@
 
 > Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
 
-Delete a draft
+Permanently delete a draft (not recoverable; drafts are not moved to Trash)
 
 ## Usage
 
diff --git a/docs/commands/gog-gmail-drafts.md b/docs/commands/gog-gmail-drafts.md
@@ -17,7 +17,7 @@ gog gmail (mail,email) drafts (draft) <command>
 ## Subcommands
 
 - [gog gmail drafts create](gog-gmail-drafts-create.md) - Create a draft
-- [gog gmail drafts delete](gog-gmail-drafts-delete.md) - Delete a draft
+- [gog gmail drafts delete](gog-gmail-drafts-delete.md) - Permanently delete a draft (not recoverable; drafts are not moved to Trash)
 - [gog gmail drafts get](gog-gmail-drafts-get.md) - Get draft details
 - [gog gmail drafts list](gog-gmail-drafts-list.md) - List drafts
 - [gog gmail drafts send](gog-gmail-drafts-send.md) - Send a draft
diff --git a/internal/cmd/gmail_drafts.go b/internal/cmd/gmail_drafts.go
@@ -16,7 +16,7 @@ import (
 type GmailDraftsCmd struct {
 	List   GmailDraftsListCmd   `cmd:"" name:"list" aliases:"ls" help:"List drafts"`
 	Get    GmailDraftsGetCmd    `cmd:"" name:"get" aliases:"info,show" help:"Get draft details"`
-	Delete GmailDraftsDeleteCmd `cmd:"" name:"delete" aliases:"rm,del,remove" help:"Delete a draft"`
+	Delete GmailDraftsDeleteCmd `cmd:"" name:"delete" aliases:"rm,del,remove" help:"Permanently delete a draft (not recoverable; drafts are not moved to Trash)"`
 	Send   GmailDraftsSendCmd   `cmd:"" name:"send" aliases:"post" help:"Send a draft"`
 	Create GmailDraftsCreateCmd `cmd:"" name:"create" aliases:"add,new" help:"Create a draft"`
 	Update GmailDraftsUpdateCmd `cmd:"" name:"update" aliases:"edit,set" help:"Update a draft"`
@@ -178,6 +178,9 @@ func (c *GmailDraftsGetCmd) Run(ctx context.Context, flags *RootFlags) error {
 	return nil
 }
 
+// GmailDraftsDeleteCmd permanently deletes a draft. The Gmail API's
+// users.drafts.delete is irreversible — drafts are not moved to Trash and have
+// no untrash path — so this cannot be undone.
 type GmailDraftsDeleteCmd struct {
 	DraftID string `arg:"" name:"draftId" help:"Draft ID"`
 }
@@ -191,7 +194,7 @@ func (c *GmailDraftsDeleteCmd) Run(ctx context.Context, flags *RootFlags) error
 
 	if confirmErr := dryRunAndConfirmDestructive(ctx, flags, "gmail.drafts.delete", map[string]any{
 		"draft_id": draftID,
-	}, fmt.Sprintf("delete gmail draft %s", draftID)); confirmErr != nil {
+	}, fmt.Sprintf("permanently delete gmail draft %s (not recoverable; drafts are not moved to Trash)", draftID)); confirmErr != nil {
 		return confirmErr
 	}
 
