docs: rewrite README to house standard

[steipete]

Summary

Rewrites the README from an 861-line command catalog into a 193-line front door that follows the house structure: pitch and proof, smallest install path, quick start, progressive capability sections, development, and license. The banner, credits, generated OAuth scope table, and project boundaries remain intact.

Moved and removed

• Moved the service-by-service command examples into docs/examples.md and linked the generated command reference for exhaustive flags.
• Replaced duplicate install, OAuth, automation, safety, MCP, Workspace Admin, and evaluation prose with links to the existing canonical guides.
• Dropped no unique factual or current product content as obsolete or unverifiable; only duplicated README copies were removed.
• Added the one-line Unreleased docs entry, matching the changelog's docs precedent.

Verification

• go version → Go 1.26.5, matching go.mod.
• make build; built gog --version, root help, schema, and targeted schema/help commands all passed.
• The OAuth and live-service quick-start paths require user credentials, so their exact commands and flags were validated against the built binary's real --help and schema output instead of contacting Google.
• make ci passed: formatting, lint, deadcode, Go/Node tests, docs generation/coverage, and generated agent-skill checks.
• brew info --json=v2 openclaw/tap/gogcli and brew test openclaw/tap/gogcli passed; GitHub release assets and the public GHCR package page were also verified.
• All 49 relative links resolve. All 14 external link and badge targets returned HTTP 200. Every Shields SVG was checked for invalid and not found cards.
• Autoreview: /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode local ... returned autoreview clean: no accepted/actionable findings reported.

No library code samples were added, so the compile-sample gate is not applicable.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 2, 2026, 9:03 PM ET / August 3, 2026, 01:03 UTC.

ClawSweeper review

What this changes

The PR shortens the public README into an installation and onboarding front door, moves service-by-service examples to docs/examples.md, and adds an Unreleased documentation note.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep this collaborator-authored documentation PR open for explicit maintainer review. The current main branch still has the long README catalog, while this focused three-file patch moves detailed task examples into documentation and preserves the generated command-reference path; no concrete correctness or security defect was found in the reviewed change.

Priority: P3
Reviewed head: f1d4513cf1e127041b16bc1f0415eb9cc5ce978e
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	This is a focused, source-consistent documentation patch with a strong stated validation record and no actionable review finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: All changed files are documentation or release-note text, so external real-runtime behavior proof is not required for this PR.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All changed files are documentation or release-note text, so external real-runtime behavior proof is not required for this PR.
Evidence reviewed	4 items	Focused documentation diff: The branch changes only README.md, docs/examples.md, and CHANGELOG.md: 390 additions and 760 deletions. The central README restructuring is not already present on current main. Current-main comparison: Current main still presents the README as a broad command catalog with embedded install, Docker, Windows, source-build, and command examples, so the proposed concise front-door design remains a distinct contribution. Command examples match generated documentation: The quick-start commands used by the PR, including auth credentials set, auth add, auth doctor, auth alias set, Gmail search, Calendar events, Drive sharing audit, schema, and MCP, are documented by the current generated command reference.
Findings	None	None.
Security	None	None.

How this fits together

The README is gog’s primary entry point for people, scripts, and agents adopting the Google Workspace CLI. It directs users from installation, OAuth setup, and safety controls to the detailed examples and generated command reference that define the full CLI surface.

flowchart LR
  Users[People scripts and agents] --> Readme[README front door]
  Readme --> Install[Install and quick start]
  Readme --> Safety[Automation and safety guidance]
  Readme --> Examples[Service examples guide]
  Readme --> Reference[Generated command reference]
  Examples --> CLI[gog CLI]
  Reference --> CLI

Loading

Decision needed

Question	Recommendation
Should this collaborator-authored README information architecture become gog’s public onboarding front door?	Accept the documentation structure: Merge the focused README-to-guide split because current source checks show the cited commands and canonical documentation paths exist.

Why: Repository policy requires explicit maintainer handling for collaborator-authored items, and the remaining judgment is qualitative documentation direction rather than a mechanical defect.

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation footprint	3 files affected; 390 added, 760 removed	The branch is a focused information-architecture rewrite rather than a broad code or workflow change.

Technical review

Best possible solution:

Adopt the concise README only if the responsible reviewer agrees that the generated command reference and docs/examples.md are the intended long-form discovery paths for gog users.

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

Not applicable: this PR changes documentation structure, not a reported runtime behavior. Source review confirms that the prominent quick-start commands are represented in the generated command documentation.

Is this the best way to solve the issue?

Yes, subject to maintainer acceptance of the documentation structure: directing exhaustive examples to a dedicated guide and generated command reference avoids maintaining duplicate command catalogs in the README.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 71e40bfe7e22.

Labels

Label changes:

• add P3: This is a low-risk documentation and onboarding refinement with no reported runtime regression.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed files are documentation or release-note text, so external real-runtime behavior proof is not required for this PR.

Label justifications:

• P3: This is a low-risk documentation and onboarding refinement with no reported runtime regression.
• 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: All changed files are documentation or release-note text, so external real-runtime behavior proof is not required for this PR.

Evidence

What I checked:

• Focused documentation diff: The branch changes only README.md, docs/examples.md, and CHANGELOG.md: 390 additions and 760 deletions. The central README restructuring is not already present on current main. (README.md:1, f1d4513cf1e1)
• Current-main comparison: Current main still presents the README as a broad command catalog with embedded install, Docker, Windows, source-build, and command examples, so the proposed concise front-door design remains a distinct contribution. (README.md:1, 71e40bfe7e22)
• Command examples match generated documentation: The quick-start commands used by the PR, including auth credentials set, auth add, auth doctor, auth alias set, Gmail search, Calendar events, Drive sharing audit, schema, and MCP, are documented by the current generated command reference. (docs/commands/gog-auth-credentials-set.md:1, 71e40bfe7e22)
• Recent README provenance: README history shows recent surrounding documentation and release-workflow maintenance by Peter Steinberger, supporting steipete as the relevant current documentation-routing contact. (README.md:1, 1c5a1ec15fa8)

Likely related people:

• steipete: Current README history attributes the latest surrounding README work to Peter Steinberger, and the proposed branch is authored by the matching GitHub handle. (role: recent README and release-documentation contributor; confidence: high; commits: 1c5a1ec15fa8, 4814a57f0c55; files: README.md, CHANGELOG.md, docs/examples.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

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