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

.agents/skills/gog/SKILL.md

@@ -29,6 +29,13 @@ For JSON output projection, `--fields` is accepted as an alias for `--select` on
 commands that do not define their own API field-mask `--fields`; commands with a
 local field-mask flag keep that command-specific meaning.
 
+`--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 do not broadcast across the elements of a nested array, so an envelope
+path such as `--select items.id` selects nothing, and object paths that do not
+match are omitted rather than reported.
+
 Pick the account explicitly for API work:
 
 ```bash

docs/automation.md

@@ -49,6 +49,15 @@ being silently ignored. Explicit output flags override `GOG_JSON` and
 that do not define their own API field-mask `--fields`; commands with a local
 field-mask flag keep that command-specific meaning.
 
+`--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, so a projection in which no path
+matches yields an empty object.
+
 Use `--no-input` in CI and unattended processes. Use `--wrap-untrusted` when
 Google-hosted free text will be consumed by an LLM or another instruction-aware
 system.