feat(docs): add a structured document reader

[ratovarius]

Description

Raw Docs responses require callers to reconstruct tabs, content order, styled runs, tables, image references, and an outline. Add gws docs +read to produce a compact structured view while retaining returned indices, suggestions, and explicit unknown-content markers. It uses the existing executor, authentication, sanitization, and output formatter.

Also fix the shared YAML formatter for empty collection values, required for ordinary reader output. Related to #726.

Fixes ratovarius#2.

Scope and dependencies

This built-in reader does not require either Python companion or the preview-field flag. Its separate YAML-formatting fix is included because empty arrays and objects are ordinary reader output. The view preserves document content structure; it does not render pages.

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

Focused reader and shared-formatter regressions, all 802 Rust workspace tests, formatting, and strict Clippy passed. Synthetic tests exercise nested tabs, non-BMP text, tables, image metadata, auto-text subtypes, sanitization, dry-run, and rejection paths. Reader YAML is checked for valid round-trip structure.

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 (synthetic fixture and placeholder IDs; no API request sent):

{
  "body": null,
  "dry_run": true,
  "is_multipart_upload": false,
  "method": "GET",
  "query_params": [
    [
      "includeTabsContent",
      "true"
    ],
    [
      "suggestionsViewMode",
      "SUGGESTIONS_INLINE"
    ]
  ],
  "url": "https://example.invalid/v1/documents/example%2Ddocument"
}

Limits

This is a content view, not rendered page layout. Table/CSV output is a summary; JSON/YAML retain structure. No live Google 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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3df0cdc

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.

[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#2 and integration in ratovarius#10. Further development of this item will continue in the fork. This closure does not indicate rejection by upstream maintainers.