diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..0a24ef7
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,40 @@
+# Copy to .env and fill in. Every value here is a placeholder, never a real key.
+#
+# Only the variables the app actually reads are listed. The Vercel Marketplace
+# integrations inject a larger block (PGHOST, POSTGRES_PASSWORD, KV_URL and so
+# on) that nothing in this codebase reads -- leave those as `vercel env pull`
+# writes them.
+#
+# Reference: docs/development.md > Environment Variables
+
+# --- Mapillary (required) ---------------------------------------------------
+# Without this every round fails: src/lib/mapillary.js throws on a missing token.
+# Also required by scripts/build-pano-index.mjs.
+# Create one at https://www.mapillary.com/dashboard/developers
+MAPILLARY_ACCESS_TOKEN=
+
+# --- Postgres (required) ----------------------------------------------------
+# Neon connection string holding the panorama index. Either name works;
+# `vercel env pull` writes both. Seed it with `npm run data:seed`.
+DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=require
+# POSTGRES_URL=
+
+# --- Redis (required) -------------------------------------------------------
+# Either the vanilla Upstash pair...
+# UPSTASH_REDIS_REST_URL=https://example.upstash.io
+# UPSTASH_REDIS_REST_TOKEN=
+# ...or the Vercel Marketplace alias for the same thing. Set one pair, not both.
+KV_REST_API_URL=https://example.upstash.io
+KV_REST_API_TOKEN=
+
+# Namespace for every physical Redis key, so this project can share an Upstash
+# database with others without collisions. Optional; defaults to 'vngeoguessr:'.
+# Do not set it empty -- src/lib/upstash.js treats that as unset on purpose.
+# KEY_PREFIX=vngeoguessr:
+
+# --- Map tiles (optional) ---------------------------------------------------
+# Read at BUILD time, not runtime. Unset, all Leaflet maps fall back to the OSM
+# public tile server: fine for dev and e2e, but its policy forbids commercial
+# use, so set this before any commercial deployment. The key is public by
+# design -- restrict it to the production domain in the Geoapify dashboard.
+# NEXT_PUBLIC_GEOAPIFY_KEY=
diff --git a/.gitignore b/.gitignore
index b4b75a4..e8d3d6b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,6 +42,8 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+# ...except the placeholder template, which carries names and comments only.
+!.env.example
 
 # vercel
 .vercel
diff --git a/docs/development.md b/docs/development.md
index 9835091..2456f36 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -40,6 +40,9 @@
 
 ### Environment Variables
 
+Copy `.env.example` to `.env` and fill it in; it lists every variable the app
+reads, with placeholders only. The sections below explain each one.
+
 **Redis (required)**:
 - Either `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` (vanilla Upstash)
 - Or `KV_REST_API_URL` + `KV_REST_API_TOKEN` (Vercel Marketplace)