feat(docs): add a visual review bundle example

[ratovarius]

Description

Add a standalone Python standard-library companion that collects native Docs JSON plus Drive PDF, DOCX, and Markdown exports into a local review bundle. Its HTML index combines an outline, optional rendered pages, DOCX image occurrences and nearby text, and separate native image metadata. A manifest records artifact hashes, optional failures, revision observations, and mapping limits.

The example uses existing gws authentication and commands and includes an independent Linux/macOS Python CI job.

Fixes ratovarius#4.

Scope and dependencies

This is an optional standalone example, not a built-in reader or patch command. It uses existing raw Docs/Drive methods and does not require #931, #932, #933, #935, #936, or #937. The bundle remains read-only against Google; optional PDF rendering requires a separately installed trusted renderer.

The only common code included from another contribution is the two-file Clippy fix proposed separately in #930. This PR contains its own copy, so it is self-contained against the current upstream base; it is not a zero-overlap diff. Prefer merging #930 first, then refreshing this branch to remove the duplicate. Each feature has its own changeset.

Validation

All 50 synthetic Python tests and Python 3.10 syntax checks passed, plus full Rust workspace tests, formatting, and strict Clippy. Tests cover archive/path/XML handling, nested image occurrences, revision changes, export receipts, optional comments, and renderer failure. A complete bundle export also passed through actual standalone and combined gws binaries against a loopback server; CI builds gws and always enables that regression. Real pdftoppm rendered a synthetic PDF, whose page image was visually inspected.

Local independent agent review found no outstanding findings; upstream maintainer approval is still pending. Combined validation with the other contributions passed 859 Rust tests, 86 Python tests, 20 CLI acceptance checks, formatting, strict Clippy, and build.

Dry-run output: not applicable to this change.

Limits

Python 3.10+, Linux/macOS; optional rendering requires trusted pdftoppm. Sequential exports are not an atomic snapshot. Page-preview coverage and native-tab/DOCX-image mappings remain explicitly unverified. Content URLs are not fetched. Interactive HTML browser inspection was unavailable in this environment; HTML references and escaping have synthetic regression coverage. No live document was accessed.

Checklist

• Follows AGENTS.md; no generated Google client crates.
• Formatting check passed.
• Required strict Clippy check passed.
• Added regression tests for accepted and rejected cases.
• Includes a changeset.

The companion CI runs in a dedicated workflow with read-only repository permissions and verified action pins; the existing shared CI workflow is unchanged.

[changeset-bot]

🦋 Changeset detected

Latest commit: 52e47c9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

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

[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.

[googleworkspace-bot]

/gemini review

[ratovarius]

Closing this proposal by author request to focus the initial upstream contribution on #937 (preserve saved credentials after authentication failures).

This work remains implemented and maintained in the public fork, https://github.com/ratovarius/cli, with tracking in ratovarius#4 and integration in ratovarius#10. Further development of this item will continue in the fork. This closure does not indicate rejection by upstream maintainers.