docs: sharpen gog launch story (#869)

steipete · web-flow · commit fc13b4147e20 · 2026-06-22T12:51:39.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - API: add Discovery-backed `api list`, `api describe`, and scoped `api call` access for Google methods outside the first-class command surface, with dry-run plans and explicit write opt-in.
 - Safety: add global `--readonly` / `GOG_READONLY=1` runtime enforcement that blocks mutating Google and Zoom API requests before dispatch while preserving read-only query POSTs and least-privilege OAuth setup.
 - Add schema-generated service skills and curated agent workflows for inbox triage, meeting prep, attachment archival, Drive audits, weekly digests, and contact cleanup.
+- Docs: sharpen the README and overview around task-first workflows, predictable automation, identity routing, layered agent safety, and honest product boundaries.
 
 ## 0.30.0 - 2026-06-21
 
diff --git a/README.md b/README.md
@@ -1,34 +1,49 @@
-# gogcli
+# gog — Google Workspace from the terminal
 
 ![gogcli banner](docs/assets/readme-banner.jpg)
 
-`gog` is a script-friendly Google CLI for Gmail, Calendar, Drive, Docs, Sheets,
-Sites, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts,
-Tasks, People, Classroom, Chat, YouTube, and Workspace admin flows.
-
-It is built for terminals, shell scripts, CI, and coding agents:
-
-- predictable `--json` and `--plain` output on stdout
-- human hints and progress on stderr
-- multiple Google accounts and OAuth clients
-- OAuth, direct access tokens, ADC, and Workspace service accounts
-- runtime command allowlists/denylists and baked safety-profile binaries
-- typed [MCP server](docs/mcp.md) for agent clients, read-only by default and
-  without a generic command runner
-- read-only audit/reporting commands for risky surfaces like Drive and Contacts
-- [generated docs](docs/commands/README.md) for every command
-
-Rendered docs: <https://gogcli.sh/>
-
-Start here:
-
-- [Install](docs/install.md)
-- [Quickstart](docs/quickstart.md)
-- [Auth clients and service accounts](docs/auth-clients.md)
-- [MCP server](docs/mcp.md)
-- [Agent skills](docs/agent-skills.md)
-- [Command index](docs/commands/README.md)
-- [Gmail watch / Pub/Sub push](docs/watch.md) (<https://gogcli.sh/watch.html>)
+One binary. Task-first commands. Predictable automation.
+
+`gog` gives people, scripts, CI, and coding agents one CLI for Gmail, Calendar,
+Drive, Docs, Sheets, Slides, Forms, Meet, Apps Script, Analytics, Search
+Console, Contacts, Tasks, Classroom, Chat, YouTube, and Workspace admin.
+
+```bash
+# Find mail, inspect today's calendar, and audit a Drive folder.
+gog --account you@gmail.com --readonly gmail search 'is:unread newer_than:7d' --max 10
+gog --account you@gmail.com --readonly calendar events --today
+gog --account you@gmail.com --readonly drive audit sharing --parent <folderId> --json
+
+# Make automation parseable, non-interactive, read-only, and unable to send Gmail.
+gog --readonly --gmail-no-send --no-input --json gmail search 'label:inbox'
+```
+
+## Why gog
+
+Google APIs expose resources and methods. Real work crosses them. `gog` keeps
+the raw capability, then adds the workflow and operational contracts a durable
+CLI needs:
+
+- **Task-first workflows:** search and sanitize mail, resolve calendar names,
+  audit Drive sharing, edit Docs, append Sheet tables, build Slides, manage
+  Workspace users, and back up accounts.
+- **Automation that composes:** stable `--json` and `--plain` stdout; prompts,
+  progress, and warnings on stderr; documented exit codes; `--no-input` for CI.
+- **Many identities, one install:** account aliases, named OAuth clients, direct
+  access tokens, ADC, OS/encrypted-file keyrings, and Workspace service accounts.
+- **Agent safety with explicit boundaries:** runtime `--readonly`, command
+  allow/deny rules, `--gmail-no-send`, untrusted-content wrapping, dry-run plans,
+  baked safety-profile binaries, and a typed MCP server that is read-only by default.
+- **A discoverable contract:** `gog schema --json`, generated reference pages
+  for every command, and schema-generated service skills for agent workflows.
+
+Read [Why gog](docs/why-gog.md) for the design tradeoffs, or go straight to:
+[Install](docs/install.md) · [Quickstart](docs/quickstart.md) · [Auth](docs/auth-clients.md) ·
+[Command index](docs/commands/README.md) · [Automation](docs/automation.md) ·
+[Agent skills](docs/agent-skills.md) · [MCP](docs/mcp.md).
+
+Rendered docs: <https://gogcli.sh/>. `gog` is open source and not affiliated
+with Google.
 
 ## Install
 
diff --git a/docs/index.md b/docs/index.md
@@ -39,14 +39,19 @@ gog slides create-from-markdown "Weekly update" --content-file slides.md
 - **Stable output.** `--json` for scripts, `--plain` TSV for `awk`, human output on stderr.
 - **Runtime discovery.** `gog schema --json` exposes command shape, stable exit codes, output modes, and effective safety state.
 - **Multi-account, multi-client.** Many Google accounts and OAuth client projects in one config; OAuth, direct access tokens, ADC, and Workspace service accounts all supported.
-- **One automation contract.** Humans, scripts, CI, and agents use the same commands, with JSON/TSV output, non-interactive operation, stable exit codes, untrusted-content wrapping, runtime command guards, and baked safety profiles.
+- **One automation contract.** Humans, scripts, CI, and agents use the same commands, with JSON/TSV output, non-interactive operation, stable exit codes, runtime read-only enforcement, untrusted-content wrapping, command guards, and baked safety profiles.
 - **Preview-first audits.** Drive `tree`, `du`, `inventory`; Contacts `dedupe` previews by default and requires explicit `--apply` for guarded merges; raw API JSON dumps never mutate remote state.
-- **Generated reference.** Every command has a docs page produced from `gog schema --json`.
+- **Generated reference.** Every command has a docs page, and service-level agent skills are generated from the same `gog schema --json` contract.
+
+The short version is in [Why gog](why-gog.md): workflow-first commands, stdout
+as an API, identity routing, layered safety, and a contract generated from the
+live binary.
 
 ## Pick your path
 
 - **Trying it.** [Install](install.md) → [Quickstart](quickstart.md). Five minutes from `brew install` to your first authenticated query.
-- **Wiring up automation.** [Automation](automation.md), [Safety Profiles](safety-profiles.md), and the bundled [`gog` skill](https://github.com/openclaw/gogcli/blob/main/.agents/skills/gog/SKILL.md). Discover the active contract and lock the binary down before handing it to an untrusted caller.
+- **Understanding the design.** [Why gog](why-gog.md) explains what the project optimizes for and where its boundaries are.
+- **Wiring up automation.** [Automation](automation.md), [Safety Profiles](safety-profiles.md), and [Agent skills](agent-skills.md). Discover the active contract and lock the binary down before handing it to an untrusted caller.
 - **Serving MCP tools.** [MCP server](mcp.md) exposes typed, allowlisted tools for agent clients without a generic command bridge.
 - **Discovering runtime contracts.** [Automation](automation.md) explains root help, schema metadata, safety controls, and stable exit codes.
 - **Polling local events.** [Drive and Docs polling](polling.md) persists cursors and optionally invokes trusted shell hooks.
diff --git a/docs/why-gog.md b/docs/why-gog.md
@@ -0,0 +1,96 @@
+---
+title: Why gog
+description: "Why gog combines task-first Google Workspace workflows with stable automation and explicit agent safety."
+---
+
+# Why gog
+
+Google Workspace automation usually starts simple: list messages, fetch an
+event, update a cell. It becomes operational software as soon as it must choose
+an account, preserve machine-readable output, recover from expired auth, avoid
+an accidental send, or hand fetched content to an agent.
+
+`gog` is built for that second stage.
+
+## The product idea
+
+Use one command surface everywhere:
+
+```text
+person at a terminal → shell script / CI → coding agent / MCP client
+                         same gog commands
+```
+
+The interface does not fork into a human CLI and an agent API. Commands expose
+the same arguments and behavior; global contracts make them safe to compose.
+
+## Five design choices
+
+### 1. Workflows before endpoint spelling
+
+First-class commands encode the parts that raw API calls leave to every user:
+calendar-name resolution, pagination, time parsing, Gmail content sanitation,
+Drive audit projections, Docs revision controls, dry-run plans, and stable
+output shapes.
+
+### 2. Stdout is an API
+
+`--json` and `--plain` keep stdout parseable. Human guidance, warnings,
+prompts, and progress use stderr. Stable exit codes let automation branch on
+auth, permission, quota, empty-result, not-found, and retryable failures without
+matching prose.
+
+### 3. Auth is a routing problem
+
+One installation can hold several Google accounts and several OAuth client
+projects. Aliases, domain mappings, direct access tokens, ADC, and Workspace
+service accounts all resolve through the same command layer.
+
+### 4. Safety is layered
+
+No single switch covers every caller. gog combines:
+
+- preview/dry-run behavior for mutations;
+- confirmation for destructive operations;
+- runtime `--readonly` enforcement before API requests are dispatched;
+- Gmail no-send policy at flag, config, and account level;
+- runtime command allowlists and denylists;
+- baked binaries whose blocked commands disappear from help and schema;
+- untrusted-content markers for fetched Google text;
+- a typed MCP tool surface with writes disabled by default.
+
+### 5. The live CLI generates its contract
+
+`gog schema --json` is the source for the command reference and generated agent
+skills. Documentation, agent discovery, and runtime policy inspection therefore
+describe the binary that is actually running, including build-time safety
+filtering.
+
+## Who it is for
+
+- People who manage more than one Google account from a terminal.
+- Teams that need auditable Workspace automation in shell or CI.
+- Maintainers who want high-level workflows without hiding the underlying IDs,
+  scopes, and API errors.
+- Agent builders who need constrained tools and machine-readable contracts.
+
+It is not a hosted integration platform, a replacement for Google Cloud Console
+administration, or a promise that every Google API feature has a curated command.
+The [command index](commands/) is the exact current surface.
+
+## A useful first proof
+
+After [Quickstart](quickstart.md), run a read-only loop before enabling any
+mutation workflow:
+
+```bash
+gog auth doctor --check
+gog --account you@gmail.com --readonly gmail search 'newer_than:7d' --max 5 --json
+gog --account you@gmail.com --readonly calendar events --today --json
+gog --account you@gmail.com --readonly drive audit sharing --parent <folderId> --json
+gog schema gmail search --json
+```
+
+Then choose the narrowest next boundary: keep runtime read-only enforcement,
+add an exact command allowlist or no-send policy, use a dedicated OAuth client
+or service account, or bake a safety profile into the binary.
