docs: sharpen gog launch story

[steipete]

Summary

Rewrites the README opening and docs overview around a clearer product story:

One binary. Task-first commands. Predictable automation.

The old introduction led with a long service inventory. The new version leads with real tasks, then explains the operational contracts that differentiate gog once a one-off API call becomes maintained automation.

What changed

• New descriptive title: “gog — Google Workspace from the terminal.”
• Immediate, copyable Gmail/Calendar/Drive examples using runtime --readonly,
  plus non-interactive no-send protection.
• A five-point “Why gog” explanation:
  • task-first workflows;
  • composable stdout/stderr and exit-code contracts;
  • multi-account and multi-client identity routing;
  • layered agent safety, including runtime read-only enforcement;
  • schema-generated command discovery, docs, and service skills.
• Shorter route from the opening to Install, Quickstart, Auth, Command Index,
  Automation, Agent Skills, and MCP.
• Explicit open-source/non-affiliation statement near the first screen.
• New docs/why-gog.md with design tradeoffs, intended users, honest non-goals, and a safe first proof sequence.
• Overview links the design story into the existing task-oriented docs navigation.

Accuracy work

Every featured command was checked against the branch binary and generated schema/help. That caught and fixed a stale example shape: Drive audits require gog drive audit sharing, not the parent gog drive audit command.

Validation

• live read-only E2E using an authenticated test account:
  • Gmail search example: exit 0, valid JSON
  • Calendar today example: exit 0, valid JSON
  • Drive sharing audit example: exit 0, valid JSON
• gog schema gmail search --json command-shape verification
• make docs-check: 699 command pages, docs site build, links, anchors, and coverage
• final autoreview: clean, no accepted/actionable findings

Scope

Docs only. No CLI behavior, auth state, or Google data changed. The live proof used read-only commands and retained no fetched content in the repository.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 22, 2026, 3:15 PM ET / 19:15 UTC.

Summary
The branch rewrites the README opening and docs overview, adds docs/why-gog.md, and adds an unreleased changelog note around a task-first gog launch story.

Reproducibility: not applicable. this is a documentation-positioning PR, not a bug report. I inspected the PR diff, current main docs, and generated command docs instead of attempting a runtime reproduction.

Review metrics: 1 noteworthy metric.

• Changed surface: 4 files; +148/-31; 0 runtime files. The diff is documentation and release-note text, so review should focus on public wording, links, and command-example accuracy.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Have a maintainer decide whether this first-screen launch positioning is the desired public story.
• [P2] Let the current-head test and windows checks finish before merge.

Risk before merge

• [P1] The main remaining uncertainty is editorial/product positioning: the PR changes the public first-screen story and should be accepted by a maintainer before merge.
• [P1] GitHub still reports the current head as UNSTABLE with test and windows checks pending, so merge should wait for current-head checks to finish.

Maintainer options:

1. Decide the mitigation before merge
   Have a maintainer accept or adjust the docs story, then merge after current-head checks complete.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] Manual review is the right lane because the PR is collaborator-authored and changes public launch positioning; there is no narrow code repair to queue.

Security
Cleared: The diff changes documentation and changelog text only, with no code execution, dependency, credential, OAuth, CI, or release-script surface.

Review details

Best possible solution:

Have a maintainer accept or adjust the docs story, then merge after current-head checks complete.

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

Not applicable; this is a documentation-positioning PR, not a bug report. I inspected the PR diff, current main docs, and generated command docs instead of attempting a runtime reproduction.

Is this the best way to solve the issue?

Yes, if maintainers want this launch story; the change is scoped to README/docs/changelog and its featured command examples match generated command docs. The remaining decision is editorial/product acceptance, not implementation mechanics.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is low-risk documentation and launch-story polish 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: The external contributor proof gate does not apply to this collaborator-authored PR; the body still includes live read-only E2E and docs-check validation context.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR review-mode guidance applies because this was reviewed through GitHub PR metadata and diff without switching branches or editing files. (AGENTS.md:1, 4ddec67538e6)
• Protected author association: GitHub REST metadata reports author_association COLLABORATOR, so this workflow should not auto-close the PR even if the diff is straightforward. (e1d66a09ec87)
• PR diff scope: The PR changes four documentation/release-note files: README.md, docs/index.md, new docs/why-gog.md, and CHANGELOG.md, with +148/-31 and no runtime code changes. (docs/why-gog.md:1, e1d66a09ec87)
• Current main lacks central README rewrite: Current main still opens with # gogcli and the older service-inventory introduction, so the central README launch-story change is not already implemented. (README.md:1, 4ddec67538e6)
• Current main lacks new story page: docs/why-gog.md is absent on current main, so the new design-story page is unique PR work rather than already-merged content. (docs/why-gog.md, 4ddec67538e6)
• Featured command examples checked against generated docs: Generated docs on main confirm the PR's highlighted gog drive audit sharing --parent ... --json shape and the global safety flags used in the examples. (docs/commands/gog-drive-audit-sharing.md:1, 4ddec67538e6)

Likely related people:

• steipete: The current README/docs overview blame and recent path history are dominated by Peter Steinberger, including the v0.30.0 docs baseline plus recent generated-skills, runtime-readonly, and eval documentation updates. (role: recent docs area contributor; confidence: high; commits: 48db48b4f61f, 4ddec67538e6, 4cac149d75a7; files: README.md, docs/index.md, CHANGELOG.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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

[steipete]

Landed as fc13b4147e2000cb52ff1e4fce0305b4f7370ccb.

Proof:

• make docs-check passed: 699 command pages generated; docs site, links, anchors, tests, and coverage passed.
• Live read-only Gmail search, Calendar events, and Drive sharing-audit smoke tests passed with valid JSON; fetched output was discarded.
• Final autoreview: clean, no accepted/actionable findings.
• GitHub CI: 8/8 checks passed across Linux, macOS, Windows, and worker jobs. The first Windows lint attempts stopped making progress; both complete workflows were rerun and passed.

The rebased copy also incorporates the newly landed runtime --readonly control and schema-generated agent skills. Thanks.