docs: clarify Gmail API ID web links

[zerone0x]

Summary

Fixes #858

Document that Gmail API message/thread IDs are not durable Gmail web permalinks and that #all/<hexId> is an unofficial alias that can fail from a cold browser load.

Changes

• Add a README note about Gmail API IDs, opaque Gmail web permalink IDs, and the rfc822msgid:<Message-ID> search fallback.
• Add the same guidance to the generated gws-gmail skill docs.
• Add a shorter tip to gws-gmail-read so agents know how to derive a browser-search URL from headers.

Test Plan

• python3 markdown fence balance check for changed Markdown files: passed
• cargo test: attempted, but the environment is missing linker cc (linker cc not found), so Rust tests could not run here

[changeset-bot]

⚠️ No Changeset found

Latest commit: e43b350

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request improves the documentation for the Gmail integration by clarifying the limitations of using Gmail API IDs for direct web navigation. It highlights that these IDs are not stable permalinks and provides actionable advice for developers to construct reliable search-based URLs using Message-ID headers.

Highlights

• Documentation Update: Added clear warnings across the documentation regarding the non-durability of Gmail API IDs as web permalinks.
• Best Practices: Provided guidance on using rfc822msgid search URLs as a reliable alternative for generating browser-accessible links from API data.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request updates the documentation in README.md, skills/gws-gmail-read/SKILL.md, and skills/gws-gmail/SKILL.md to clarify that Gmail API message and thread IDs are not durable web permalinks. It provides instructions on how to construct reliable browser links using the Message-ID header and a Gmail search URL instead. There are no review comments, so I have no feedback to provide.