docs(gmail): clarify that drafts delete is permanent

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Fixed
 
 - Gmail: keep label IDs case-sensitive during label resolution and duplicate-name checks while still matching label names case-insensitively.
+- Gmail: clarify that `gmail drafts delete` permanently deletes drafts and cannot be recovered. (#656, #659) — thanks @chrischall.
 - Docs: update the bundled `gog` agent skill to preserve broad user OAuth scopes during reauth and rely on command guards for scoped execution.
 
 ## 0.19.0 - 2026-05-22

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

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

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
 

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

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
 	}