docs: document projection order for --results-only and --select

[postoso]

Scope

Documents the existing interaction between --results-only and --select. No behavior change.

The two global flags are documented separately today, so nothing states that --results-only is applied first, or how to project one field from every element of a list response. Reaching for the envelope path --select items.id returns {}, which is consistent with the best-effort projection contract but is not discoverable from the flag help.

Adds a short paragraph to the two places that describe these flags in prose:

• docs/automation.md, next to the existing --fields alias note
• .agents/skills/gog/SKILL.md, same

Content:

--results-only is applied before --select, so a projection runs against the unwrapped primary result. To project each element of a list response, select fields relative to a single element, such as --results-only --select id. Dot paths descend through object keys and numeric array indexes; they do not broadcast across every element of a nested array, so an envelope path such as --select items.id selects nothing. Object paths that do not match are omitted from the projection rather than reported.

This follows #816, which documented the --fields alias in the same two files after #814. #816 also touched README.md, but the global-flags list it edited is no longer in the README, and the current "Automate safely" section defers to docs/automation.md for output contracts, so I left the README alone.

Why not a help-string change

--select and --results-only help text lives in internal/cmd/root.go, and editing either regenerates 719 of the 720 pages under docs/commands/. That seemed like the wrong trade for a clarification, so this stays in the hand-maintained prose. Happy to move it if you would rather it live in the flag help.

Testing

• make docs-check and make agent-skills-check
• Behavior claims verified against v0.37.0 and a source build of main at eb85a993, using gog api list against the public Discovery directory:

command	result
--select 'items.name'	{}
--select 'items.0.name'	{"items.0.name": "..."}
--results-only --select 'name'	one {"name": ...} per item
--select 'kind,nope'	{"kind": "..."}, unmatched path omitted

User-facing changes

Documentation only. No new flags, no behavior change.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 20, 2026, 5:48 AM ET / 09:48 UTC.

ClawSweeper review

What this changes

This PR adds matching automation and agent-skill documentation explaining that --results-only unwraps output before --select projects fields, including non-broadcast dot-path behavior.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open: the documentation-only patch accurately describes the current JSON transformation order and path semantics, with no correctness finding. Likely related people: Peter Steinberger (current-source and frequent output-format contributor, medium confidence) and Yannick (recent adjacent output-format contributor, medium confidence).

Priority: P3
Reviewed head: 5421bdc088b0c925e57bfa05bd3f7317e7738d6a

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The focused documentation patch is accurate against current source and existing regression coverage.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only documentation, so external real-behavior proof is not required.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only documentation, so external real-behavior proof is not required.
Evidence reviewed	6 items	Transformation order on current main: The formatter unwraps the primary result when ResultsOnly is set, then applies field selection afterward. List and dot-path semantics on current main: Selection iterates over each list element; path traversal accepts object keys and numeric array indexes only, so an array segment such as items.id does not broadcast and an unmatched path is omitted. Existing regression coverage: Current-main coverage asserts that --results-only unwraps a list and --select id emits only each element’s ID.
Findings	None	None.
Security	None	None.

How this fits together

Global CLI output flags configure JSON transformation after a Google API command returns its response. The formatter unwraps a command’s primary result when requested, projects selected paths, and writes parseable JSON to stdout.

flowchart LR
A[CLI global flags] --> B[JSON transform settings]
B --> C[Output formatter]
C --> D[Unwrap primary result]
D --> E[Project selected JSON paths]
E --> F[Parseable JSON stdout]

Loading

Before merge

• Add real behavior proof - Not applicable: This PR changes only documentation, so external real-behavior proof is not required.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	2 files changed; 16 added, 0 removed	The clarification updates both maintained prose surfaces without changing generated command reference pages or runtime behavior.

Technical review

Best possible solution:

Merge the narrowly scoped clarification in both maintained output-contract documents so automation users can choose paths relative to the unwrapped list element.

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

Not applicable: this is documentation for an existing contract, independently verified by current source and its focused formatter test.

Is this the best way to solve the issue?

Yes: keeping the clarification in the hand-maintained automation guide and bundled agent skill documents the existing behavior without triggering generated command-reference churn.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is a small documentation clarification with no runtime behavior change.
• 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: This PR changes only documentation, so external real-behavior proof is not required.

Label justifications:

• P3: This is a small documentation clarification with no runtime behavior change.
• 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: This PR changes only documentation, so external real-behavior proof is not required.

Evidence

What I checked:

• Transformation order on current main: The formatter unwraps the primary result when ResultsOnly is set, then applies field selection afterward. (internal/outfmt/outfmt.go:155, 45b5d766e137)
• List and dot-path semantics on current main: Selection iterates over each list element; path traversal accepts object keys and numeric array indexes only, so an array segment such as items.id does not broadcast and an unmatched path is omitted. (internal/outfmt/outfmt.go:259, 45b5d766e137)
• Existing regression coverage: Current-main coverage asserts that --results-only unwraps a list and --select id emits only each element’s ID. (internal/outfmt/outfmt_test.go:50, eb85a99366eb)
• Narrow documentation diff: The branch adds 16 lines across the two maintained prose surfaces and has no whitespace errors. (docs/automation.md:52, 5421bdc088b0)
• Release baseline checked: The behavior existed in the latest release baseline v0.37.0; the new explanatory prose is not already present there. (docs/automation.md:48, 45b5d766e137)
• Area history: Blame ties the current transform implementation to the v0.37.0 source boundary; history also shows Yannick’s recent envelope-preservation change in the same implementation and tests. (internal/outfmt/outfmt.go:140, 455caec23623)

Likely related people:

• Peter Steinberger: Current-main blame assigns the transform and path-selection lines to the v0.37.0 source boundary, and local shortlog shows the most contributions in this formatter area. (role: current-source and frequent output-format contributor; confidence: medium; commits: 45b5d766e137; files: internal/outfmt/outfmt.go, internal/outfmt/outfmt_test.go)
• Yannick: Recent commit fix(outfmt): preserve Gmail attachment result envelopes (#943) modified both the formatter and its tests. (role: recent adjacent output-format contributor; confidence: medium; commits: 455caec23623; files: internal/outfmt/outfmt.go, internal/outfmt/outfmt_test.go)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.