docs: document env vars and local setup

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.env.example

@@ -1,10 +1,22 @@
-BETTER_AUTH_API_KEY=
-BETTER_AUTH_SECRET=
+# --- required to build ---
+NEXT_PUBLIC_BASE_URL=http://localhost:3000
+NEXT_PUBLIC_SITE_LOCALE=en-US
+# GitHub "owner/repo" for "Improve This Post" links, and the username shown on /projects
+NEXT_PUBLIC_GITHUB_REPO=
+NEXT_PUBLIC_GITHUB_USERNAME=
+
+# --- views & comments (Postgres) ---
 DATABASE_URL=
+
+# --- sign-in for comments (GitHub OAuth app via Better Auth) ---
+BETTER_AUTH_SECRET=
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
+# optional: Better Auth infra dashboard
+BETTER_AUTH_API_KEY=
+
+# --- optional ---
+# GitHub token for /projects (the page 404s without it)
 GITHUB_TOKEN=
-NEXT_PUBLIC_BASE_URL=
-NEXT_PUBLIC_GITHUB_REPO=
+# Tor mirror hostname, adds an onion-location header
 NEXT_PUBLIC_ONION_DOMAIN=
-NEXT_PUBLIC_SITE_LOCALE=

README.md

@@ -14,7 +14,12 @@ My humble abode on the World Wide Web, created with [Next.js](https://nextjs.org
 
 I highly recommend spinning up a [Codespace](https://github.com/features/codespaces) with the button above to start inside of a preconfigured and tested environment.
 
-**Be sure to populate the required environment variables!**
+Or, to run it locally (Node 24+ with Corepack enabled):
+
+1. `cp .env.example .env.local` and fill in the values. Only the "required to build" ones are needed to run the site; the rest enable views, comments, sign-in and `/projects`.
+2. `pnpm install`
+3. `pnpm db:migrate` (needs `DATABASE_URL`)
+4. `pnpm dev`
 
 ## Related