Skip to content

docs(fork): add service-config checklist + auth verification section#91

Merged
TortoiseWolfe merged 1 commit into
mainfrom
docs/fork-checklist
May 14, 2026
Merged

docs(fork): add service-config checklist + auth verification section#91
TortoiseWolfe merged 1 commit into
mainfrom
docs/fork-checklist

Conversation

@TortoiseWolfe
Copy link
Copy Markdown
Owner

Summary

Yesterday's #85 OAuth incident exposed a fork-onboarding gap: a brand-new forker had to hop between README, FORKING.md, AUTH-SETUP.md, PAYMENT-DEPLOYMENT.md, .env.example, and individual feature docs to figure out which services to set up. No single master checklist existed.

This PR adds three coordinated doc changes that close that gap.

Deliverables

1. docs/FORK-CHECKLIST.md (NEW, ~160 lines)

Single-page master walkthrough with three sections:

  • Setup order: numbered 1-9 (rebrand → Supabase → migration → auth → env → payments → email → analytics → verification)
  • Service matrix: every external service the template integrates with, in one table (16 rows covering Supabase, GitHub/Google OAuth, Stripe, PayPal, Web3Forms, EmailJS, Resend, GA4, PageSpeed, Calendar, Disqus, Cash App, Chime, author metadata, Docker config)
  • Common pitfalls: led with the OAuth providers misconfigured: Google + GitHub Client IDs are literal 'placeholder_*' strings #85 placeholder-OAuth-Client-ID footgun, plus production site_url / uri_allow_list, .env security, Supabase Vault for server secrets, Docker-first install rule

2. docs/AUTH-SETUP.md polish (+50 lines)

  • Cross-link callout at the top pointing first-time forkers to FORK-CHECKLIST.md so they don't land on this deep-dive doc cold
  • New "Verification via Management API" section with a copy-pasteable curl + jq command that prints current OAuth Client IDs in one line. This is the exact check that would have caught issue OAuth providers misconfigured: Google + GitHub Client IDs are literal 'placeholder_*' strings #85 weeks earlier. Includes red-flag patterns (literal placeholder_* strings, IDs that don't end in .apps.googleusercontent.com for Google, etc.).

3. README.md updates (+21 lines)

  • Quick Start callout (blockquote) pointing to FORK-CHECKLIST.md as the first thing a forker should read
  • New "🔐 Authentication Setup" section between Payment Integration and GitHub Actions Secrets, with a 5-step hyperlinked path through AUTH-SETUP.md and explicit mention of the Management API verification step

Verification

  • ✅ All 12 in-repo target files exist (spot-checked)
  • ✅ All FORKING.md heading anchors corrected (GitHub auto-slug includes parenthetical suffixes, e.g. quick-start-5-minutes, syncing-with-upstream-scripthammer)
  • ✅ README mentions FORK-CHECKLIST 2x, AUTH-SETUP 6x — discoverable
  • ✅ 27 distinct hyperlinks in FORK-CHECKLIST.md, all resolve to either real files or live URLs
  • ✅ Pre-push hooks (lint, type-check, build) all green

What this PR does NOT do

  • Does NOT add Discord / Microsoft / Okta OAuth sections — out of scope (Supabase supports them; the pattern from GitHub/Google translates)
  • Does NOT write new setup docs for Resend / Disqus / Sentry / Cash App / Chime — these are either trivial ("paste handle into .env") or stub services
  • Does NOT change .env.example — the vars were fine; the missing piece was discoverability
  • Does NOT close issue OAuth providers misconfigured: Google + GitHub Client IDs are literal 'placeholder_*' strings #85 — the OAuth dashboard repair still needs user-side work. This PR makes the same class of bug easier to catch next time.

🤖 Generated with Claude Code

Three coordinated doc changes to make first-time fork setup discoverable
end-to-end, prompted by yesterday's issue #85 OAuth incident:

1. docs/FORK-CHECKLIST.md (NEW): the missing master walkthrough. Single
   page with three sections:
   - Setup order (numbered, top-to-bottom): rebrand, Supabase, migration,
     auth providers, env vars, payments, email, analytics, verification
   - Service matrix: every external service the template integrates with
     (Supabase, GitHub/Google OAuth, Stripe, PayPal, Web3Forms, EmailJS,
     Resend, GA4, PageSpeed, Calendar, Disqus, Cash App, Chime, author
     metadata, Docker config) with Required? / env vars / setup link
     columns
   - Common pitfalls: the actual things that have bitten contributors,
     led with the #85 placeholder OAuth Client ID footgun

2. docs/AUTH-SETUP.md: two additions:
   - Cross-link callout at the top pointing first-time forkers to
     FORK-CHECKLIST.md so they don't land on this deep-dive doc cold
   - New "Verification via Management API" section after Part 6 with a
     copy-pasteable curl + jq command that prints current OAuth Client
     IDs in one line. This is the exact check that would have caught
     issue #85 weeks earlier — Google IDs end in .apps.googleusercontent.com,
     real GitHub IDs are 20-char hex or Iv1.-prefixed; anything else
     (especially literal "placeholder_*" strings) is a misconfig.

3. README.md: two additions:
   - Quick Start callout (one-line blockquote) pointing to FORK-CHECKLIST.md
     so brand-new forkers see the master walkthrough first
   - New "Authentication Setup" section between Payment Integration Setup
     and GitHub Actions Secrets, with hyperlinked 5-step path through
     AUTH-SETUP.md (Supabase signup -> migrations -> provider config ->
     env vars -> Management API verification)

Verification done:
- All in-repo target files exist (12 files spot-checked)
- All FORKING.md anchors corrected (slugs include trailing words like
  "5-minutes" and "scripthammer")
- README mentions FORK-CHECKLIST 2x and AUTH-SETUP 6x
- 27 distinct hyperlinks in FORK-CHECKLIST.md, all resolve

Does NOT close issue #85 (the OAuth dashboard repair still needs
user-side dashboard work). This PR makes #85's class of bug easier
to catch the next time, and gives forkers a single front door to
all the service setup they need.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@TortoiseWolfe TortoiseWolfe merged commit ac2e7f6 into main May 14, 2026
28 checks passed
@TortoiseWolfe TortoiseWolfe deleted the docs/fork-checklist branch May 14, 2026 00:52
TortoiseWolfe added a commit that referenced this pull request May 14, 2026
…ry (#93)

The PRP-STATUS.md dashboard was last fully refreshed 2026-04-25. Six PRs
have landed since then (2026-05-12 to 2026-05-14) closing the long-running
E2E flake pattern, the #31 GA4 ticket, and improving fork onboarding.

Three targeted updates:

1. Header — bump "Last Updated" to 2026-05-14, "Previous Update" to
   2026-04-25. Shipped count 17 -> 18 (019 GA moved from Mostly Shipped
   to Shipped after #31 close on 2026-05-13). Updated "Current Phase"
   line to reflect round 10 closure.

2. New "v0.4.x updates since 2026-04-25 audit" section between the
   header and the full feature table — one-paragraph summary of each
   merged PR (#86, #88, #89, #90, #91, #92) plus the issue closures
   (#31 GA4, #85 OAuth) with link to the closure comment for #85's
   outstanding dashboard work.

3. Stability hotspots note — added a callout indicating the E2E flake
   row in the hotspot table is resolved at round 10. Rounds 1-9
   attacked symptoms; round 10 found the underlying cause (concurrent
   CI runs racing against a shared Supabase project) and fixed it
   structurally via the concurrency mutex. Other 9 hotspots remain
   open.

Per-feature audit data in the lower sections is left untouched — the
2026-04-25 sweep is still the canonical detail. This refresh is purely
the top-of-document changes needed to reflect 19 days of activity.

Verification:
- grep "Last Updated" docs/prp-docs/PRP-STATUS.md -> "2026-05-14"
- Pre-commit hooks pass (prettier + gitleaks)

Co-authored-by: TurtleWolfe <TurtleWolfe@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants