release: promote develop to main

[ratovarius]

Summary

Promote the verified develop branch to the release baseline on main.

Included work:

• guided Google Docs suggestion workflow
• opt-in comment reading with referenced text resolution
• anchored comment creation without manually passing --allow-unknown-fields
• replacement concurrency, child-tab, overlapping-match, and OAuth-scope hardening
• associated changesets and documentation

Verification

• Full Rust test suites passed on the feature branches
• Rust formatting and Clippy passed
• Live Google Docs smoke tests passed for suggestions, comment creation, comment reading, and referenced text
• Temporary live test documents were deleted

Release policy: this PR targets main from develop and should be merged with a merge commit.

[Copilot]

🟡 Changes recommended

Release preparation is incomplete, and file-root and OAuth-scope regressions remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Promotes develop to the release branch with new Docs workflows, safer credential handling, file-root controls, and request validation improvements.

Changes:

• Adds structured Docs reading, comments, suggestions, and review workflows.
• Adds credential-free dry runs and unknown Discovery-field support.
• Hardens credentials, file paths, OAuth scopes, and YAML formatting.

File summaries

File	Description
README.md	Documents new commands, dry runs, credentials, and file roots.
examples/docs-review/README.md	Documents the text-review workflow.
examples/docs-review/docs_review.py	Implements revision-bound text replacement.
examples/docs-review-bundle/README.md	Documents visual review bundles.
docs/docs-read.md	Documents structured Docs reading.
crates/google-workspace/src/validate.rs	Adds configurable file-root validation.
crates/google-workspace-cli/tests/file_roots.rs	Tests file-root CLI behavior.
crates/google-workspace-cli/tests/dry_run.rs	Tests credential-free dry runs.
crates/google-workspace-cli/src/main.rs	Integrates dry-run and validation policies.
crates/google-workspace-cli/src/helpers/gmail/mod.rs	Isolates attachment tests from file-root state.
crates/google-workspace-cli/src/helpers/docs/suggest.rs	Adds suggestion management.
crates/google-workspace-cli/src/helpers/docs/read.rs	Adds structured reading and comment resolution.
crates/google-workspace-cli/src/helpers/docs/read_tests.rs	Tests Docs normalization and comments.
crates/google-workspace-cli/src/helpers/docs/comment.rs	Adds anchored comment creation.
crates/google-workspace-cli/src/helpers/docs.rs	Registers and dispatches Docs helpers.
crates/google-workspace-cli/src/formatter.rs	Fixes empty YAML collection formatting.
crates/google-workspace-cli/src/executor.rs	Adds unknown-field validation policy.
crates/google-workspace-cli/src/commands.rs	Adds --allow-unknown-fields.
crates/google-workspace-cli/src/auth.rs	Preserves credentials after loading failures.
AGENTS.md	Documents file-root policy.
.changeset/yaml-empty-collections.md	Records YAML fix.
.changeset/scoped-file-roots.md	Records file-root support.
.changeset/preserve-credentials.md	Records credential preservation.
.changeset/offline-dry-run.md	Records offline dry runs.
.changeset/docs-suggest-workflow.md	Records suggestion workflow.
.changeset/docs-structured-read.md	Records structured reading.
.changeset/docs-review-workflow.md	Records review workflow.
.changeset/docs-review-bundle.md	Records review bundles.
.changeset/docs-read-comments.md	Records comment reading.
.changeset/docs-comment-create.md	Records comment creation.
.changeset/allow-unknown-fields.md	Records unknown-field support.

Review details

• Files reviewed: 34/34 changed files
• Comments generated: 5
• Review effort level: Balanced

---

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

[ratovarius]

Release preparation is now available in PR #21: #21

The release-review code fixes are included on the preparation branch. After #21 merges into develop, please refresh this release PR so the new 0.23.0 version/provenance metadata is evaluated.

[Copilot]

Copilot review overview

🟡 Changes recommended

Credential fallback can still occur for inaccessible encrypted paths, and comment anchors can lose tab context in multi-tab documents.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Distinguish missing credentials from inaccessible paths · New
• Preserve enclosing tab IDs when resolving comment anchors · New

Resolved since last review (5)

• This release still contains pending changesets while every synchronized package/crate version…
• The root override is now applied to every caller of this shared validator, including Gmail…
• Discovery scopes are alternatives, but this requests every scope for comment creation. The raw…
• The helper cannot validate that these indices align to UTF-16 boundaries or identify a valid range…
• This text will be published on main by this release PR, so saying the command exists “On…

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[ratovarius]

Reviewed 1fc496b. No critical/P1 issues found; two important P2 fixes are recommended before merging:

1. [P2] Preserve comment text when a zero start index is omitted. read.rs:404–408 skips text runs without an explicit startIndex. A header comment reproduced referencedText: [null] instead of ["Header"] when the zero index was omitted. Recommendation: default an absent paragraph-element start index to zero, retain rejection of malformed explicit values, and add segment regression coverage.

2. [P2] Keep optional revision-read failures from aborting the bundle. docs_review_bundle.py:658–663 propagates a failed final revision read after all required exports succeed, preventing index.html generation. Recommendation: record revision status as unknown and continue; cover failed and timed-out reads while preserving required-export failures.

Both issues were reproduced locally. Existing validation passed: 879 Rust tests, 99 Python tests, formatting, Clippy, and build. Live Google API behavior was not retested.