A staged plan for merging, testing, and deploying the open PRs

[kcarnold]

Adds docs/pr-merge-and-deploy-plan.md. Docs only — no code changes.

The finding that reframes the question

Nothing conflicts textually. Every open branch merges clean into main @ c16d6ba, and the full pairwise matrix between them is clean too. The only shared files are frontend/CLAUDE.md (four PRs, different sections), backend/CLAUDE.md/docker-compose.yml (#574, #594), and backend/src/app.ts + AccountPage.tsx (#566, #594) — all disjoint hunks. The collisions that matter are semantic, and there are four.

Four things to fix, not just merge

1. Google Docs staging is untestable today, which blocks the whole test plan. vite.config.ts:57 compiles GDOCS_BACKEND_URL to the prod origin in every non-dev build, but sidebar.html:200 offers a staging source and the image is built once per commit for both hosts. Picking "staging" in Docs loads the staging bundle against the prod backend — prod auth, prod consent records, prod logs. That makes Feat/503 consent pr2 #566, Handle document-read errors (e.g., Google Docs authorization timeout) #585, and Serialize Google Docs documents to Markdown #581 untestable on Docs without touching production data. Fix is ~5 lines: let resolveServerUrl() derive the origin from the bundle's own script URL, which it already knows how to do.

2. Handle document-read errors (e.g., Google Docs authorization timeout) #585 ships the bug its own description names. The new requestSuggestion catch sets the error outside getSuggestion, so lastRequestRef is never updated and retryLastRequest re-runs the last successful request with its stale docContext. Chat and Revise re-enter from the top and are correct; draft is the odd one out.

3. Serialize Google Docs documents to Markdown #581 makes paragraph coordinates host-dependent. It filters blank lines out of getParagraphs() on Docs; Word and the standalone editor both keep empty paragraphs. Paragraph index N stops meaning the same thing across hosts — and that's the coordinate system view and insert-after use.

4. Serialize Google Docs documents to Markdown #581 and My Words: tolerate typography when matching the writer's words #587 point in different directions on text matching. Serialize Google Docs documents to Markdown #581 makes the model read ## Introduction while the host document contains Introduction; My Words: tolerate typography when matching the writer's words #587 tolerates typography but not Markdown. Inert today (gdocs applyEdit is unimplemented, Google Docs: My Words edits are unimplemented (applyEdit rejects) #590), but it means Google Docs: My Words edits are unimplemented (applyEdit rejects) #590 must be written against Markdown-serialized text, and it strengthens Send hosts ranges, not needles: one text-matching implementation across editors #589 — a range is immune to both problems at once.

The stages

• 0 — unblock testing: Keep PostHog off the request path; point backend at PostHog US #574 (plus removing the explicit POSTHOG_HOST from the k8s deployment, or its new default does nothing), Render Word manifests from one template per environment #595, the gdocs-origin fix. Exit criteria: staging reachable in both Word and Docs, with Docs demonstrably hitting the staging backend.
• 1 — free merges: Design explorations: discernment in community, and writing to learn #596 now, Add draft Terms of Service for Google add-on #519 when the store listing is prepared.
• 2 — Docs correctness chain: Serialize Google Docs documents to Markdown #581 (needs clasp push, so it isn't done when it's merged), then Handle document-read errors (e.g., Google Docs authorization timeout) #585 with the retry fix.
• 3 — consent (Feat/503 consent pr2 #566): rebase, regenerate snapshots, verify consentUpdatedAt round-trips for a fresh real user, then live-test both hosts. Highest blast radius in the set — a required first-run gate locks everyone out if it misbehaves.
• 4 — My Words (My Words: tolerate typography when matching the writer's words #587): merge, then test voice edits in Word specifically, since Word's autocorrect is the only place the bug reproduces.
• 5 — brief proposals (Let the writer draft their brief from the document #598): merge, then watch brief_proposal_resolved.

#594 stays draft — it is the tool-launch rearchitecture, and nothing else in the open set depends on the answer, so it doesn't block stages 0–5.

The doc also carries per-PR verdicts, live-test checklists for Word and Docs, and four decisions that need a human: the #585 retry approach, whether to normalize paragraph coordinates across hosts, the #594 direction, and what to do with #449/#446/#435 (2+ months stale).

---

Generated by Claude Code