diff --git a/docs/runbooks/first-deploy.md b/docs/runbooks/first-deploy.md
index 31aaeab..778de31 100644
--- a/docs/runbooks/first-deploy.md
+++ b/docs/runbooks/first-deploy.md
@@ -31,6 +31,10 @@ Required in your environment `*.tfvars`:
 
 Recommended:
 
+- `database_url_secret_id = "database-url"`
+- `openai_api_key_secret_id = "openai-api-key"`
+- optional `supabase_url_secret_id = "supabase-url"`
+- optional `supabase_publishable_key_secret_id = "supabase-publishable-key"`
 - `bot_feedback_topic_id`
 - `bot_mini_app_allowed_origins`
 - `scheduler_timezone`
@@ -132,6 +136,11 @@ echo -n "<database-url>" | gcloud secrets versions add database-url --data-file=
 
 Add optional secret versions only if those integrations are enabled.
 
+For a functional household dev deployment, set `database_url_secret_id = "database-url"` in
+`dev.tfvars` before the apply that creates the Cloud Run services. Otherwise the bot deploys
+without `DATABASE_URL`, and finance commands, reminders, mini app auth/dashboard, and anonymous
+feedback remain disabled.
+
 ## Phase 4: Configure GitHub CD
 
 Populate GitHub repository secrets with the Terraform outputs:
diff --git a/docs/runbooks/iac-terraform.md b/docs/runbooks/iac-terraform.md
index 7b2316c..b3dfc9d 100644
--- a/docs/runbooks/iac-terraform.md
+++ b/docs/runbooks/iac-terraform.md
@@ -43,6 +43,11 @@ echo -n "<scheduler-shared-secret>" | gcloud secrets versions add scheduler-shar
 If you set optional secret IDs such as `database_url_secret_id` or
 `openai_api_key_secret_id`, add versions for those secrets too.
 
+For a functional dev bot, set at least:
+
+- `database_url_secret_id = "database-url"`
+- optional `openai_api_key_secret_id = "openai-api-key"`
+
 Keep bot runtime config that is not secret in your `*.tfvars` file:
 
 - `bot_household_id`
diff --git a/infra/terraform/terraform.tfvars.example b/infra/terraform/terraform.tfvars.example
index 5a7ae5b..5393cd2 100644
--- a/infra/terraform/terraform.tfvars.example
+++ b/infra/terraform/terraform.tfvars.example
@@ -8,6 +8,11 @@ artifact_repository_id = "household-bot"
 bot_api_image   = "europe-west1-docker.pkg.dev/my-gcp-project/household-bot/bot:latest"
 mini_app_image  = "europe-west1-docker.pkg.dev/my-gcp-project/household-bot/miniapp:latest"
 
+database_url_secret_id   = "database-url"
+openai_api_key_secret_id = "openai-api-key"
+# supabase_url_secret_id             = "supabase-url"
+# supabase_publishable_key_secret_id = "supabase-publishable-key"
+
 bot_household_id       = "11111111-1111-4111-8111-111111111111"
 bot_household_chat_id  = "-1001234567890"
 bot_purchase_topic_id  = 777