From 63722b8764b8e5b6380d57e31a3ce1d928887dd2 Mon Sep 17 00:00:00 2001
From: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
Date: Mon, 15 Jun 2026 08:18:43 +0000
Subject: [PATCH] docs: document fields projection alias

Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com>
---
 .agents/skills/gog/SKILL.md | 4 ++++
 README.md                   | 3 +++
 docs/automation.md          | 4 ++++
 3 files changed, 11 insertions(+)

diff --git a/.agents/skills/gog/SKILL.md b/.agents/skills/gog/SKILL.md
index 9bb0254e6..ddfdddd55 100644
--- a/.agents/skills/gog/SKILL.md
+++ b/.agents/skills/gog/SKILL.md
@@ -23,6 +23,10 @@ stable exit codes, command guards, and untrusted-content wrapping apply across
 the CLI. Root help summarizes the human contract; `schema` exposes command
 syntax, stable exit codes, and effective safety state for automation.
 
+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.
+
 Pick the account explicitly for API work:
 
 ```bash
diff --git a/README.md b/README.md
index 803dbac21..4960ec83a 100644
--- a/README.md
+++ b/README.md
@@ -491,6 +491,9 @@ Useful global flags:
 - `--client <name>`: select a stored OAuth client
 - `--json`: JSON stdout
 - `--plain`: stable parseable text stdout
+- `--select <csv>`: in JSON mode, project output fields. `--fields` is
+  accepted as an alias on commands that do not define their own API field-mask
+  `--fields`.
 - `--wrap-untrusted`: in JSON/raw output, wrap fetched free-text fields with
   external untrusted-content markers for LLM/agent consumption
 - `--dry-run`: print intended actions where a command supports planning
diff --git a/docs/automation.md b/docs/automation.md
index ca744e16f..408c12f4a 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -45,6 +45,10 @@ being silently ignored. Explicit output flags override `GOG_JSON` and
 `GOG_PLAIN` environment defaults. `gog schema` always emits JSON and rejects
 `--plain`.
 
+`--fields` is accepted as an alias for `--select` output projection on commands
+that do not define their own API field-mask `--fields`; commands with a local
+field-mask flag keep that command-specific meaning.
+
 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.