From 5421bdc088b0c925e57bfa05bd3f7317e7738d6a Mon Sep 17 00:00:00 2001 From: postoso Date: Thu, 20 Aug 2026 05:45:11 -0400 Subject: [PATCH 1/2] docs: document projection order for --results-only and --select The two global flags are documented separately, so nothing states that --results-only is applied first, or how to project one field from every element of a list response. Adds a short paragraph to the two prose locations that describe these flags. --- .agents/skills/gog/SKILL.md | 7 +++++++ docs/automation.md | 9 +++++++++ 2 files changed, 16 insertions(+) diff --git a/.agents/skills/gog/SKILL.md b/.agents/skills/gog/SKILL.md index 912b4db6f..bbe2c9ecb 100644 --- a/.agents/skills/gog/SKILL.md +++ b/.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 diff --git a/docs/automation.md b/docs/automation.md index 1c79fcd31..16f8b680f 100644 --- a/docs/automation.md +++ b/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. From dad14fa6d3c2a4a3c836b304cf44028139db2fe9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 25 Aug 2026 01:21:16 -0700 Subject: [PATCH 2/2] docs: tighten JSON projection-order guidance Co-authored-by: postoso --- .agents/skills/gog/SKILL.md | 10 ++++------ docs/automation.md | 13 +++++-------- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/.agents/skills/gog/SKILL.md b/.agents/skills/gog/SKILL.md index bbe2c9ecb..3084ce975 100644 --- a/.agents/skills/gog/SKILL.md +++ b/.agents/skills/gog/SKILL.md @@ -29,12 +29,10 @@ 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. +`--results-only` unwraps the primary result before `--select` projects it. For +lists, select item-relative fields: `--results-only --select id`. Dot paths do +not broadcast through nested arrays (`--select items.id` selects nothing). +Unmatched object fields are omitted. Pick the account explicitly for API work: diff --git a/docs/automation.md b/docs/automation.md index 16f8b680f..52877382d 100644 --- a/docs/automation.md +++ b/docs/automation.md @@ -49,14 +49,11 @@ 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. +`--results-only` unwraps the primary result before `--select` projects it. For +lists, select item-relative fields: `--results-only --select id`. Dot paths +traverse object keys or numeric array indexes; they do not broadcast through +nested arrays (`--select items.id` selects nothing). Unmatched object fields +are omitted. 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