diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..5e21bca
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,11 @@
+# Copy to .env and fill in. .env is gitignored — never commit real values.
+
+# BGG XML API application token (register at https://boardgamegeek.com/applications)
+BGG_API_TOKEN=
+
+# BGG website login for the upload stage (Playwright)
+BGG_USERNAME=
+BGG_PASSWORD=
+
+# Anthropic API key for the vision extract stage
+ANTHROPIC_API_KEY=
diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..7553c66
--- /dev/null
+++ b/.envrc
@@ -0,0 +1,3 @@
+# Loaded automatically by direnv when you cd into this directory.
+# Secrets live in .env (gitignored) — see .env.example for the template.
+dotenv_if_exists