docs: surface that --fields is accepted as an alias for --select on most commands

[privatenumber]

Summary

The global --fields is accepted as an alias for --select (JSON output projection) on every
command that doesn't define its own API field-mask --fields. This is intentional and helpful
(agents often guess --fields for output projection), but it is only surfaced on the --select
flag help, so someone reaching for --fields directly won't discover it. A one-line note in the
agent / global-flags docs would close the discoverability gap.

Details (v0.22.0, 197992a)

• The rewrite happens in internal/cmd/root.go:251-274 (see the explanatory comment at :251-255);
  commands with a real field-mask --fields are exempted via commandHasLocalFieldsFlagBefore
  (root.go:308).
• Currently documented only on the --select help text (root.go:44: "Desire path: use --fields
  for most commands").

Suggested change (docs only, behavior is correct)

Add a line to the agent-patterns / global-flags documentation, e.g.: "--fields is accepted as an
alias for --select (output field projection) on commands that don't take an API field mask."

Environment

gog v0.22.0 (confirmed by reading source at 197992a). Working as designed; this is a
discoverability/docs request, not a bug.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 15, 2026, 4:05 AM ET / 08:05 UTC.

Summary
Keep open: current main implements the --fields to --select rewrite, but the requested discoverability note is still missing from the automation/global-flag and bundled agent guidance.

Reproducibility: not applicable. for a documentation request. Source inspection confirms the behavior exists, while README, automation docs, and the bundled agent skill do not yet document the alias.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
This is a narrow docs-only gap with clear files and no behavior change needed.

Review details

Best possible solution:

Add a short docs-only note to the automation/global-flag and agent-facing guidance that describes the existing alias and its local-field-mask exception.

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

Not applicable for a documentation request. Source inspection confirms the behavior exists, while README, automation docs, and the bundled agent skill do not yet document the alias.

Is this the best way to solve the issue?

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

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The docs wording must preserve the exception for commands whose local --fields is an API field mask, such as Drive, raw API, labels, and Sites commands.

Codex review notes: model internal, reasoning high; reviewed against 8af7d1a9a281.

Label changes

Label changes:

• add P3: This is a low-risk documentation discoverability improvement for an existing CLI behavior.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk documentation discoverability improvement for an existing CLI behavior.

Evidence reviewed

Acceptance criteria:

• rg -n -- '--fields|--select' README.md docs/automation.md .agents/skills/gog/SKILL.md
• go test ./internal/cmd

What I checked:

• Alias rewrite exists: rewriteDesirePathArgs rewrites --fields and --fields= to --select unless the active command owns a local fields flag, preserving API field-mask commands. (internal/cmd/arg_rewrite.go:9, 8af7d1a9a281)
• Behavior is covered by tests: The desire-path tests cover rewriting --fields to --select for ordinary commands and preserving local API field-mask --fields flags. (internal/cmd/desire_paths_test.go:134, 8af7d1a9a281)
• Automation docs still omit the alias: The automation docs mention --results-only and --select JSON transforms but do not surface the --fields alias. (docs/automation.md:42, 8af7d1a9a281)
• README global flags still omit the alias: The README useful global flags list does not mention --select or the preferred --fields output-projection alias. (README.md:488, 8af7d1a9a281)
• Bundled agent skill lacks projection guidance: The bundled gog skill tells agents to prefer JSON and wrapping, but the inspected skill text has no --fields or --select projection guidance. (.agents/skills/gog/SKILL.md:21, 8af7d1a9a281)
• History points to current area owner: Local blame attributes the current arg rewrite and adjacent docs surfaces to v0.27.0 release commit 274a2a6 by Peter Steinberger. (internal/cmd/arg_rewrite.go:9, 274a2a61da98)

Likely related people:

• Peter Steinberger: git blame and local history attribute the current --fields rewrite, select help, README global-flags section, automation docs, and bundled gog skill text to the v0.27.0 release commit by Peter Steinberger. (role: current line owner / recent area contributor; confidence: medium; commits: 274a2a61da98, 8af7d1a9a281; files: internal/cmd/arg_rewrite.go, internal/cmd/root.go, docs/automation.md)

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.

[clawsweeper]

🦞✅
Implementation merged: #816
Worker: https://github.com/openclaw/clawsweeper/actions/runs/27532683938