From 7d0080f76a24ed37d0f35d93e10325a87694fb18 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 02:48:01 +0100
Subject: [PATCH] docs(readme): add generated auth services table

---
 README.md                       | 18 +++++++++---
 scripts/gen-auth-services-md.go | 52 +++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 4 deletions(-)
 create mode 100644 scripts/gen-auth-services-md.go

diff --git a/README.md b/README.md
index cc05548..a4b2806 100644
--- a/README.md
+++ b/README.md
@@ -143,11 +143,21 @@ gog auth add you@gmail.com --services sheets --force-consent
 
 Docs commands are implemented via the Drive API, and `docs` requests both Drive and Docs API scopes.
 
-To render a Markdown table of services and scopes:
+Service scope matrix (auto-generated; run `go run scripts/gen-auth-services-md.go`):
 
-```bash
-gog auth services --markdown
-```
+<!-- auth-services:start -->
+| Service | User | APIs | Scopes | Notes |
+| --- | --- | --- | --- | --- |
+| gmail | yes | Gmail API | `https://mail.google.com/` |  |
+| calendar | yes | Calendar API | `https://www.googleapis.com/auth/calendar` |  |
+| drive | yes | Drive API | `https://www.googleapis.com/auth/drive` |  |
+| docs | yes | Docs API, Drive API | `https://www.googleapis.com/auth/drive`<br>`https://www.googleapis.com/auth/documents` | Export/copy/create via Drive |
+| contacts | yes | People API | `https://www.googleapis.com/auth/contacts`<br>`https://www.googleapis.com/auth/contacts.other.readonly`<br>`https://www.googleapis.com/auth/directory.readonly` | Contacts + other contacts + directory |
+| tasks | yes | Tasks API | `https://www.googleapis.com/auth/tasks` |  |
+| sheets | yes | Sheets API, Drive API | `https://www.googleapis.com/auth/spreadsheets` | Export via Drive |
+| people | yes | People API | `profile` | OIDC profile scope |
+| keep | no | Keep API | `https://www.googleapis.com/auth/keep` | Workspace only; service account |
+<!-- auth-services:end -->
 
 ### Google Keep (Workspace only)
 
diff --git a/scripts/gen-auth-services-md.go b/scripts/gen-auth-services-md.go
new file mode 100644
index 0000000..fabaffd
--- /dev/null
+++ b/scripts/gen-auth-services-md.go
@@ -0,0 +1,52 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/steipete/gogcli/internal/googleauth"
+)
+
+const (
+	readmePath  = "README.md"
+	startMarker = "<!-- auth-services:start -->"
+	endMarker   = "<!-- auth-services:end -->"
+)
+
+func main() {
+	data, err := os.ReadFile(readmePath)
+	if err != nil {
+		fatalf("read README: %v", err)
+	}
+
+	content := string(data)
+	start := strings.Index(content, startMarker)
+	end := strings.Index(content, endMarker)
+
+	if start == -1 || end == -1 || end < start {
+		fatalf("missing markers %q ... %q in %s", startMarker, endMarker, readmePath)
+	}
+
+	table := googleauth.ServicesMarkdown(googleauth.ServicesInfo())
+	if table == "" {
+		fatalf("empty services table")
+	}
+	table = strings.TrimRight(table, "\n")
+
+	replacement := startMarker + "\n" + table + "\n" + endMarker
+	updated := content[:start] + replacement + content[end+len(endMarker):]
+
+	if updated == content {
+		return
+	}
+
+	if err := os.WriteFile(readmePath, []byte(updated), 0o600); err != nil {
+		fatalf("write README: %v", err)
+	}
+}
+
+func fatalf(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	os.Exit(1)
+}