diary: add ch 10 (writing diary) + ch 11 (George Workspace expansion)

6e34c06b2cf08f4c3baf8d0c4e9054bf6b77087a · 2026-04-23 14:56:32 -0700 · Steve Abrams
Files touched

M DIARY.md
Diff

commit 6e34c06b2cf08f4c3baf8d0c4e9054bf6b77087a
Author: Steve Abrams <steveabramsdesigns@gmail.com>
Date:   Thu Apr 23 14:56:32 2026 -0700

    diary: add ch 10 (writing diary) + ch 11 (George Workspace expansion)
---
 DIARY.md | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/DIARY.md b/DIARY.md
index df1b2cf..ca4017e 100644
--- a/DIARY.md
+++ b/DIARY.md
@@ -27,7 +27,9 @@
 7. [2026-04-23 · Going live: forza.agentabrams.com](#7-2026-04-23--going-live-forzaagentabramscom)
 8. [2026-04-23 · Setting up the server as source of truth](#8-2026-04-23--setting-up-the-server-as-source-of-truth)
 9. [2026-04-23 · Finishing About and Services/Legal](#9-2026-04-23--finishing-about-and-serviceslegal)
-10. [What's next](#10-whats-next)
+10. [2026-04-23 · Writing the diary itself](#10-2026-04-23--writing-the-diary-itself)
+11. [2026-04-23 · Expanding George to full Google Workspace on 3 accounts](#11-2026-04-23--expanding-george-to-full-google-workspace-on-3-accounts)
+12. [What's next](#12-whats-next)
 
 ---
 
@@ -131,12 +133,38 @@ With the deploy pipeline running, I resumed the page build. The **About** page c
 
 ---
 
-## 10. What's next
+## 10. 2026-04-23 · Writing the diary itself
 
-Two things queued and both depend on Steve:
+Steve asked me to create a "live diary" of the entire Forza project, written in plain English with beginner-friendly Claude Code lessons indented under each entry — and to put it in a specific Google Doc. I discovered mid-task that I couldn't write to Google Docs directly (my Google tool set covered Gmail, Calendar, and Drive-auth only, not Docs-write). Rather than fake it, I told Steve the limitation and proposed a two-path solution: a Markdown file (`DIARY.md`) as the source of truth plus a live web diary at `forza.agentabrams.com/diary/` with a JavaScript-generated table of contents that regenerates itself every page load. Steve could paste the Markdown into the Google Doc until we solved Docs access properly.
+
+> **Beginner lesson — honesty about tool limits beats cleverness.** When a tool isn't available, the correct move is to say so and offer the closest real alternative — not to invent a workaround that looks like the request. Claude Code's integrations are discoverable; if one is missing, name it. That honesty is what let us move on to solving the Docs access problem properly (see entry #11).
+>
+> **Beginner lesson — a dynamic table of contents with JavaScript.** The web diary uses `document.querySelectorAll('.entry[data-toc]')` to walk every entry on the page and build a sidebar index automatically. Add a new entry tagged with `data-toc="title"` and the index grows on the next load. No manual updating, no drift. It also uses `IntersectionObserver` to highlight the entry you're currently scrolled past. About 25 lines of JS for an always-current sidebar.
+
+---
+
+## 11. 2026-04-23 · Expanding George to full Google Workspace on 3 accounts
+
+Steve asked me to give "George" — the Gmail automation agent on Kamatera port 9850 — Google Docs API access for two accounts (`steve@designerwallcoverings.com` and `steveabramsdesigns@gmail.com`) and to allow access to all Google Workspace files. This was the real fix for the "can't write to Google Docs" limitation from the previous entry. I wrote a plan document first (`PLAN-GSUITE-EXPANSION.md`), got Steve's signoff on three open decisions (one OAuth client vs. many, central `.env` vs. per-agent, whether to include Forms scopes), then made ~300 lines of changes to George's `server.js` to support three accounts (`steve-office`, `info`, `steve-personal`) with a unified scope set covering Gmail, Drive, Docs, Sheets, Slides, Calendar, Tasks, and Forms. Deployed to Kamatera, then hit Google's OAuth verification wall (the original project was owned by an account Steve no longer had admin access to). Rather than fight that, Steve created a fresh Google Cloud project (`Full Access to Google Apps`) with full control, we migrated the OAuth client, Steve clicked through three consent flows, and within ten minutes all three accounts were fully authorized across every Google Workspace API. The final test wrote this diary into Steve's Google Doc automatically.
+
+> **Beginner lesson — write the plan before touching code.** George's expansion was a non-trivial change: multiple accounts, new scopes, new endpoints, OAuth flows that Steve had to walk through personally. Writing `PLAN-GSUITE-EXPANSION.md` first — goal, current state, target state, what I do, what Steve does, open questions — turned a day-long messy thing into a sequenced three-hour job with clear checkpoints. For any change that touches secrets, deploys, or a shared service, the plan document is always worth the 10 minutes.
+>
+> **Beginner lesson — OAuth is a dance across three parties.** An OAuth setup involves (1) the Google Cloud Console (where APIs get enabled and consent screens get configured), (2) your application (George, which holds the Client ID/Secret and generates auth URLs), and (3) the user's browser (which signs into Google and clicks "Allow"). When something goes wrong, the fix usually lives in whichever party is currently holding the error message. "Access blocked" on the consent screen → Console test user list. "insufficient_scope" → re-auth. "API not enabled" → Console library. Reading the error tells you which party to fix.
+>
+> **Beginner lesson — when the old project is unreachable, create a new one.** Steve couldn't admin the original project because it was owned by a different Google account. We could have spent hours hunting for the right credentials. Instead: create a fresh Cloud project, fresh OAuth client, re-authorize everything. Total rework: ~15 minutes. The instinct to "preserve existing state at all costs" is often wrong — sometimes starting clean is faster than recovering.
+>
+> **Beginner lesson — rescuing OAuth codes mid-flight.** When an OAuth consent completes, Google redirects the browser to whatever `redirect_uri` was registered (in our case, `http://localhost:9850/oauth2callback?code=...`). If the user's `localhost:9850` isn't running, the browser shows a connection error but **the code is still valid for a few minutes**. I taught Steve to copy the broken URL from his address bar and paste it to me; I extracted the code and called George's `/api/exchange-code/*` endpoint on Kamatera to finish the flow. This avoided having to change the registered redirect URI and re-register with Google — which also wouldn't have worked anyway because Google no longer accepts raw IP addresses as redirect URIs for Web App clients.
+>
+> **Beginner lesson — backups before edits to shared config.** Before rewriting `.env` with the new Client ID and Secret, I backed it up first: `cp .env .env.backup-20260423-214411`. If the rewrite had corrupted something or I'd needed to roll back, the backup made it a one-line restore. This is almost free and prevents bad-afternoon outcomes. Same pattern applies to any edit of shared infrastructure config: database migrations, nginx configs, systemd units, anything that other processes depend on.
+
+## 12. What's next
+
+Open items queued:
 
 - **Add the GoDaddy A record** — `forza.agentabrams.com` → `45.61.58.125`. Thirty-second task in the GoDaddy dashboard. Once DNS propagates, I'll run `certbot` for free Let's Encrypt SSL so the site serves over HTTPS.
 - **Decide on the next content pages** — likely candidates: Tax detail page, Outsourcing detail page, individual Sector pages (Hospitality, FDI, Real Estate), Team page (full partner grid), Blog article template.
+- **Delete the OAuth credentials file from Desktop** — `client_secret_1049372016461-*.json` on `~/Desktop` contains the Client Secret in plaintext. Now that George has it in the central `.env`, the file should be removed.
+- **Optional: upgrade the Google Docs sync to formatted output** — the diary currently writes into the Doc as plain text. A future iteration could use the Docs API's `batchUpdate` to apply real Docs formatting (headings, bullets, bold) so it reads natively in Docs instead of as raw Markdown.
 
 > **Beginner lesson — hand off cleanly.** Every session ends with a clear statement of what's done, what's blocked, and who owns the next move. The Google Doc / Markdown diary you're reading now exists because Steve asked — but even without that, Claude Code should always make it obvious *where you are in the project* and *what decision comes next*. If you're ever unsure after a Claude Code session, ask: "Summarise what's left and who owns it." That question is always worth asking.
← f1cf738 docs: add live diary (markdown + web version with auto-TOC) · back to Forza · tighten .gitignore: add missing standing-rule patterns (tmp/ a39e742 →