From 41a4324b82d944324b82328b3885827e54ce8acd Mon Sep 17 00:00:00 2001
From: MeGaurav4 <gauravyadavwork07@gmail.com>
Date: Sun, 12 Jul 2026 11:52:02 +0530
Subject: [PATCH 1/2] docs: document Gmail web link vs API ID mismatch (#858)

The API returns hex IDs that cannot be converted into durable Gmail web
URLs. The '#all/<hexId>' alias is unofficial and breaks on cold loads.
Document this gap and cross-reference #790.
---
 README.md                 | 2 ++
 skills/gws-gmail/SKILL.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 04c532d0..c34eaa48 100644
--- a/README.md
+++ b/README.md
@@ -332,6 +332,8 @@ gws drive --help      # shows +upload …
 | `modelarmor` | `+sanitize-response` | Sanitize a model response through a Model Armor template |
 | `modelarmor` | `+create-template` | Create a new Model Armor template |
 
+> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. For the inverse problem (web URL IDs not accepted by the API), see [#790](https://github.com/googleworkspace/cli/issues/790).
+
 **Examples:**
 
 ```bash
diff --git a/skills/gws-gmail/SKILL.md b/skills/gws-gmail/SKILL.md
index 3423770e..baa9bf85 100644
--- a/skills/gws-gmail/SKILL.md
+++ b/skills/gws-gmail/SKILL.md
@@ -45,6 +45,8 @@ gws gmail <resource> <method> [flags]
   - `settings` — Operations on the 'settings' resource
   - `threads` — Operations on the 'threads' resource
 
+> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. For the inverse problem, see [#790](https://github.com/googleworkspace/cli/issues/790).
+
 ## Discovering Commands
 
 Before calling any API method, inspect it:

From 422b5e8d4d0c97b5fa13b6b11b8bc299b4c98290 Mon Sep 17 00:00:00 2001
From: MeGaurav4 <gauravyadavwork07@gmail.com>
Date: Sun, 12 Jul 2026 11:54:37 +0530
Subject: [PATCH 2/2] docs: add rfc822msgid workaround to Gmail web link docs

---
 README.md                 | 2 +-
 skills/gws-gmail/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c34eaa48..c1536850 100644
--- a/README.md
+++ b/README.md
@@ -332,7 +332,7 @@ gws drive --help      # shows +upload …
 | `modelarmor` | `+sanitize-response` | Sanitize a model response through a Model Armor template |
 | `modelarmor` | `+create-template` | Create a new Model Armor template |
 
-> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. For the inverse problem (web URL IDs not accepted by the API), see [#790](https://github.com/googleworkspace/cli/issues/790).
+> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. The closest option is `#search/rfc822msgid:<Message-ID>`, though it is a search URL, not a direct permalink. For the inverse problem (web URL IDs not accepted by the API), see [#790](https://github.com/googleworkspace/cli/issues/790).
 
 **Examples:**
 
diff --git a/skills/gws-gmail/SKILL.md b/skills/gws-gmail/SKILL.md
index baa9bf85..9d41931d 100644
--- a/skills/gws-gmail/SKILL.md
+++ b/skills/gws-gmail/SKILL.md
@@ -45,7 +45,7 @@ gws gmail <resource> <method> [flags]
   - `settings` — Operations on the 'settings' resource
   - `threads` — Operations on the 'threads' resource
 
-> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. For the inverse problem, see [#790](https://github.com/googleworkspace/cli/issues/790).
+> **Gmail web links vs API IDs:** The API returns hex thread/message IDs (e.g. `19e1acd465710c93`). There is no supported way to turn these into durable Gmail web URLs. `#all/<hexId>` is unofficial and unreliable on cold loads. The closest option is `#search/rfc822msgid:<Message-ID>`, though it is a search URL, not a direct permalink. For the inverse problem, see [#790](https://github.com/googleworkspace/cli/issues/790).
 
 ## Discovering Commands