feat(docs): add a reviewed revision-bound text patch example

[ratovarius]

Description

Add a standalone Python standard-library workflow for reviewing one literal text change before applying it. A versioned plan records the exact revision, tab, diff, UTF-16 target, and digest. Apply reconstructs that plan from a fresh read, submits once with requiredRevisionId, then verifies the result. The original plan remains unchanged.

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

Fixes ratovarius#3.

Scope and dependencies

This is an optional standalone example, not a new built-in CLI subcommand. It uses existing raw gws docs documents methods and does not require #931, #932, #934, #935, #936, or #937. It intentionally handles only the narrow, documented literal-replacement workflow.

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 36 synthetic Python subprocess tests and Python 3.10 syntax checks passed, along with full Rust workspace tests, formatting, and strict Clippy. Tests cover changed revisions, Unicode, repeated text, tampered plans, malformed structures, post-write uncertainty, and output failures.

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):

{
  "diff": "--- before\n+++ after\n@@ -1 +1 @@\n-world\n+reader\n",
  "digest": "5acdf427dea06f6133919aef045d326c0dc66369ce32c3188476add8535a654c",
  "request": {
    "requests": [
      {
        "replaceAllText": {
          "containsText": {
            "matchCase": true,
            "searchByRegex": false,
            "text": "world"
          },
          "replaceText": "reader",
          "tabsCriteria": {
            "tabIds": [
              "t.main"
            ]
          }
        }
      }
    ],
    "writeControl": {
      "requiredRevisionId": "rev-1"
    }
  },
  "status": "preview"
}

Limits

Python 3.10+, Linux/macOS. Deliberately limited to a unique literal replacement in one top-level body paragraph; unsupported structures or suggestions are refused. No live writes were made. A plan digest detects changes but is not an authorization signature. Post-submission failures require inspection rather than automatic retry.

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: e6088ec

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