feat(docs): read and create comments

[ratovarius]

Summary

• add opt-in gws docs +read --include-comments with per-anchor referencedText
• add gws docs +comment create with UTF-16 range validation and internal preview-field opt-in
• add documentation, tests, and changesets

Verification

• cargo test -p google-workspace-cli --quiet (747 unit, 22 integration, 4 file-root tests)
• cargo fmt --all -- --check
• cargo clippy -p google-workspace-cli -- -D warnings
• live Google Docs test: created a temporary document, created a comment without --allow-unknown-fields, read it back with referencedText, and deleted the temporary document

This PR is based on the suggestion workflow branch and includes its commits.

[Copilot]

🟡 Changes recommended

Comment-free documents can fail reading, and repeated matches within one text run can be replaced ambiguously.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Extends the Docs helpers with suggestion workflows, comment retrieval, and anchored comment creation.

Changes:

• Adds +suggest operations and documentation.
• Adds opt-in comment inclusion with referencedText.
• Adds +comment create with range validation and preview support.

File summaries

File	Description
README.md	Documents Docs suggestions and comments
crates/google-workspace-cli/src/helpers/docs/suggest.rs	Implements suggestion workflows
crates/google-workspace-cli/src/helpers/docs/read.rs	Adds comment retrieval and anchor resolution
crates/google-workspace-cli/src/helpers/docs/read_tests.rs	Tests comment parameters and text resolution
crates/google-workspace-cli/src/helpers/docs/comment.rs	Implements anchored comment creation
crates/google-workspace-cli/src/helpers/docs.rs	Registers new Docs helpers
.changeset/docs-suggest-workflow.md	Adds suggestion feature changeset
.changeset/docs-read-comments.md	Adds comment-reading changeset
.changeset/docs-comment-create.md	Adds comment-creation changeset

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ratovarius]

Addressed all three Copilot review findings in commit 92ff044:

• comment-free documents now return comments: [] instead of failing
• replacement duplicate detection is synced with PR feat(docs): add guided suggestion workflow #18’s hardened implementation
• +comment is listed in the README full helper reference

Validation: 751 unit tests, 22 integration tests, 4 file-root tests, rustfmt, Clippy, and diff checks all pass.

[Copilot]

🟡 Changes recommended

Suggestion replacement omits child tabs, and comment anchor resolution conflates separate document segments.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/google-workspace-cli/src/helpers/docs/read.rs:346

• collect_text_runs walks the entire normalized document, including each tab's headers, footers, and footnotes, but TextRun carries only the tab ID. Docs indices are scoped by tab/segment, so a body comment range can incorrectly match same-numbered text in a header/footer/footnote (and ranges with segmentId are ignored), producing a concatenated or unrelated referencedText. Preserve the segment identity while collecting runs and require it to match the anchor range, treating an absent/empty segment as the body.

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

[ratovarius]

Addressed the latest Copilot findings in commit f941a79:

• replacement traversal now includes nested child tabs (the PR feat(docs): add guided suggestion workflow #18 hardening is synced)
• comment referenced-text resolution now preserves tab and segment identity, so body/header/footer/footnote anchors cannot collide on equal indexes
• added regression tests for child-tab replacement and body/header segment separation

Validation: 754 unit tests, 22 integration tests, 4 file-root tests, rustfmt, Clippy, and diff checks pass.