diff --git a/GNUmakefile b/GNUmakefile
index 1bbea9112..78e489e41 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -155,15 +155,15 @@ CFG_DEV_OAUTH2_KEY = cfg/.dev-oauth2-signing-key.pem
 CFG_DEV_ENV       = cfg/dev.env
 
 .PHONY: dev-config
-dev-config: cfg/dev.yaml ## Generate cfg/dev.yaml via probod-bootstrap (rerun after deleting the file)
+dev-config: cfg/dev.yaml ## Generate cfg/dev.yaml via probod-bootstrap (picks up edits to cfg/dev.env)
 
 $(CFG_DEV_OAUTH2_KEY):
 	@$(MKDIR) $(@D)
 	$(OPENSSL) genrsa -out $@ 2048
 
-cfg/dev.yaml: bin/probod-bootstrap $(CFG_DEV_OAUTH2_KEY)
+cfg/dev.yaml: bin/probod-bootstrap $(CFG_DEV_OAUTH2_KEY) $(wildcard $(CFG_DEV_ENV))
 	@$(MKDIR) $(@D)
-	@set -a; \
+	set -a; \
 	PROBOD_ENCRYPTION_KEY="thisisnotasecretAAAAAAAAAAAAAAAAAAAAAAAAAAA="; \
 	AUTH_COOKIE_SECRET="this-is-a-secure-secret-for-cookie-signing-at-least-32-bytes"; \
 	AUTH_PASSWORD_PEPPER="this-is-a-secure-pepper-for-password-hashing-at-least-32-bytes"; \
diff --git a/cfg/dev.env.example b/cfg/dev.env.example
index 6ba15fcd0..d86500c82 100644
--- a/cfg/dev.env.example
+++ b/cfg/dev.env.example
@@ -1,10 +1,16 @@
 # Dev overrides for `make dev-config`.
 #
 # Copy this file to cfg/dev.env and uncomment any variable you want to
-# override. The file is sourced as a shell snippet, so quote values that
-# contain spaces. cfg/dev.env is gitignored; this .example file is the
+# override. cfg/dev.env is gitignored; this .example file is the
 # canonical list of overridable knobs.
 #
+# This is NOT a Docker-compose `.env` file. The Makefile sources it as
+# a POSIX shell snippet (`. cfg/dev.env`), so:
+#   - `KEY=value` works and is auto-exported.
+#   - Quote values containing spaces: `KEY="foo bar"`.
+#   - `#` starts a comment, `export KEY=value` is accepted.
+#   - Malformed assignments (e.g. unquoted spaces) abort `make dev-config`.
+#
 # See pkg/bootstrap/builder.go for the full env-var surface; the values
 # set below in the Makefile's `cfg/dev.yaml` recipe are the dev defaults
 # that this file can override.
@@ -16,6 +22,10 @@
 # TRUST_CENTER_HTTP_ADDR=:80
 # TRUST_CENTER_HTTPS_ADDR=:443
 
+# ── Observability ─────────────────────────────────────────────────────
+# METRICS_ADDR=localhost:8081
+# TRACING_ADDR=localhost:4317
+
 # ── Secrets (rotate before prod) ──────────────────────────────────────
 # PROBOD_ENCRYPTION_KEY=thisisnotasecretAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 # AUTH_COOKIE_SECRET=this-is-a-secure-secret-for-cookie-signing-at-least-32-bytes
@@ -24,6 +34,7 @@
 # ── Cookie ────────────────────────────────────────────────────────────
 # AUTH_COOKIE_DOMAIN=localhost
 # AUTH_COOKIE_SECURE=false
+# AUTH_COOKIE_DURATION=24
 
 # ── Postgres ──────────────────────────────────────────────────────────
 # PG_ADDR=localhost:5432
@@ -31,6 +42,7 @@
 # PG_PASSWORD=postgres
 # PG_DATABASE=probod
 # PG_POOL_SIZE=100
+# PG_DEBUG=false
 
 # ── Object storage (SeaweedFS via compose) ────────────────────────────
 # AWS_REGION=us-east-1
@@ -41,6 +53,9 @@
 
 # ── Mailer (Mailpit via compose) ──────────────────────────────────────
 # SMTP_ADDR=localhost:1025
+# SMTP_USER=
+# SMTP_PASSWORD=
+# SMTP_TLS_REQUIRED=false
 # MAILER_SENDER_EMAIL=no-reply@notification.getprobo.com
 # MAILER_SENDER_NAME=Probo
 
@@ -50,6 +65,12 @@
 # LLM_DEFAULT_PROVIDER=openai
 # LLM_DEFAULT_MODEL_NAME=gpt-4o
 
+# ── LLM-backed workers (inherit from LLM defaults when unset) ─────────
+# PROBO_AGENT_PROVIDER=anthropic
+# PROBO_AGENT_MODEL_NAME=claude-sonnet-4-6
+# EVIDENCE_DESCRIBER_PROVIDER=openai
+# EVIDENCE_DESCRIBER_MODEL_NAME=gpt-4o-mini
+
 # ── OIDC sign-in providers ────────────────────────────────────────────
 # AUTH_GOOGLE_CLIENT_ID=
 # AUTH_GOOGLE_CLIENT_SECRET=