docs: document fields projection alias

[clawsweeper]

Summary

• Document that --fields is accepted as an alias for --select output projection on commands without a local API field-mask --fields.
• Keep the API field-mask exception explicit for commands such as Drive and Calendar calls that define their own --fields flag.
• Update README automation guidance, docs/automation.md, and the bundled gog agent skill only.

Source issue: #814

Fixes #814

Validation

• make test TEST_PKGS=./internal/cmd
• make docs-check
• make ci

[clawsweeper]

Codex review: passed. Reviewed June 15, 2026, 4:28 AM ET / 08:28 UTC.

Summary
The PR adds documentation in the README, automation guide, and bundled gog skill for the existing --fields/--select projection alias and API field-mask exception.

Reproducibility: not applicable. this is a documentation discoverability request. Source inspection of internal/cmd/arg_rewrite.go and internal/cmd/desire_paths_test.go confirms the described behavior already exists; current docs lacked the explanatory note.

Review metrics: 1 noteworthy metric.

• Docs scope: 3 files changed, 11 additions, 0 deletions. The measured diff confirms this is limited to documentation and agent guidance, not runtime behavior.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Next step before merge

• [P2] No repair lane is needed; this PR already contains the narrow docs change and normal CI/review is the remaining gate.

Security
Cleared: The diff changes only documentation and bundled skill guidance; it does not add code execution, dependencies, secrets handling, or workflow changes.

Review details

Best possible solution:

Land the narrow docs update after normal CI/review so the existing alias is discoverable in README, automation docs, and bundled agent guidance.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a documentation discoverability request. Source inspection of internal/cmd/arg_rewrite.go and internal/cmd/desire_paths_test.go confirms the described behavior already exists; current docs lacked the explanatory note.

Is this the best way to solve the issue?

Yes. A docs-only update is the narrowest maintainable solution because the CLI behavior and tests already match the requested contract.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 09d02e809672.

Label changes

Label changes:

• add P3: This is a low-risk documentation discoverability improvement for existing CLI behavior.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The proof gate does not apply because this is a ClawSweeper bot PR with documentation/skill text only and no runtime behavior change.

Label justifications:

• P3: This is a low-risk documentation discoverability improvement for existing CLI behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The proof gate does not apply because this is a ClawSweeper bot PR with documentation/skill text only and no runtime behavior change.

Evidence reviewed

What I checked:

• Repository policy applied: AGENTS.md was read fully, and its PR review guidance was applied by inspecting the PR with gh pr view / gh pr diff without switching branches. (AGENTS.md:36, 09d02e809672)
• PR diff is narrowly scoped: The PR adds 11 documentation lines across .agents/skills/gog/SKILL.md, README.md, and docs/automation.md, with no runtime code, workflow, dependency, or generated-file changes. (README.md:491, 63722b8764b8)
• Runtime behavior already exists: rewriteDesirePathArgs rewrites --fields and --fields= to --select unless the active command has its own local fields flag, matching the PR's documented exception. (internal/cmd/arg_rewrite.go:9, 09d02e809672)
• Behavior is covered by tests: The desire-path tests cover rewriting --fields to --select for ordinary commands and preserving API field-mask --fields for commands such as Drive, Calendar, Sites, and Drive Labels. (internal/cmd/desire_paths_test.go:134, 09d02e809672)
• Current docs gap remains on main: Current main's useful global flags list has --json and --plain but no --select or --fields projection guidance, which the PR adds. (README.md:488, 22d197c5c40e)
• Source issue is paired with this PR: The linked source issue requests a docs-only note for the existing alias behavior, and its automation comment records this PR as the implementation PR.

Likely related people:

• Peter Steinberger: git blame attributes the current alias rewrite, select help text, README automation section, automation docs, and bundled gog skill text to the v0.27.1 release commit by Peter Steinberger. (role: current line owner / recent area contributor; confidence: medium; commits: 22d197c5c40e; files: internal/cmd/arg_rewrite.go, internal/cmd/root.go, internal/cmd/desire_paths_test.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.