diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..6a6290e
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,35 @@
+# ampelos-dashboard
+#
+# Copy to .env.local and fill in. Next.js loads .env.local automatically from
+# the working directory, which is what ampelos.service sets. Never commit it.
+
+# --- database -------------------------------------------------------------
+# This repository owns the schema. ampelos-agent reads the same database with
+# raw SQL and holds no copy of it, so a rename here needs `npm run check:schema`
+# run over there.
+DATABASE_URL=postgres://user:password@mimir/ampelos
+
+# --- sign-in --------------------------------------------------------------
+AUTH_URL=https://ampelos.sticknife.com
+AUTHENTIK_ISSUER=
+AUTHENTIK_CLIENT_ID=
+AUTHENTIK_CLIENT_SECRET=
+
+# --- ampelos-agent --------------------------------------------------------
+# Where the indexer listens, for the manual search and grab panel. The
+# automatic acquisition loop does not go through here.
+AMPELOS_INDEXER_URL=http://127.0.0.1:8081
+AMPELOS_AGENT_TIMEOUT_SECONDS=30
+# Shared with ampelos-agent, in both directions: the satellites POST to
+# /api/agents/* with it, and this app sends it to the indexer. Same value in
+# both repositories' environments, in neither's history.
+AMPELOS_AGENT_TOKEN=
+
+# --- external services ----------------------------------------------------
+MOVIEDB_API=
+PLEX_URL=
+PLEX_PORT=32400
+PLEX_AUTH_TOKEN=
+PLEX_MACHINE_IDENTIFIER=
+# Read-only here: the dashboard shows queue state, the agent does the grabbing.
+QBT_URL=http://localhost:8080
diff --git a/.gitignore b/.gitignore
index 5ef6a52..8c1acc6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,8 +30,10 @@ yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
 
-# env files (can opt-in for committing if needed)
+# env files. The real ones hold DATABASE_URL, the Authentik client secret and
+# the agent token; the example is the documentation and must be committed.
 .env*
+!.env.example
 
 # vercel
 .vercel