feat(WHE-28): add terraform baseline for cloud run and scheduler

docs/runbooks/dev-setup.md

@@ -4,6 +4,7 @@
 
 - Bun 1.3+
 - Node.js 22+
+- Terraform 1.8+ (for IaC checks/plans)
 
 ## First-time setup
 
@@ -21,6 +22,8 @@ bun run format:check
 bun run typecheck
 bun run test
 bun run build
+bun run infra:fmt:check
+bun run infra:validate
 ```
 
 ## App commands
@@ -47,8 +50,13 @@ bun run review:coderabbit
 
 - CI runs in parallel matrix jobs on push/PR to `main`:
   - `format:check`, `lint`, `typecheck`, `test`, `build`
+  - `terraform fmt -check`, `terraform validate`
 - CD deploys on successful `main` CI completion (or manual dispatch).
 - CD is enabled when GitHub secrets are configured:
   - `GCP_PROJECT_ID`
   - `GCP_WORKLOAD_IDENTITY_PROVIDER`
   - `GCP_SERVICE_ACCOUNT`
+
+## IaC Runbook
+
+- See `docs/runbooks/iac-terraform.md` for provisioning flow.

docs/runbooks/iac-terraform.md

@@ -0,0 +1,55 @@
+# Terraform IaC Runbook
+
+## Purpose
+
+Provision and maintain GCP infrastructure for bot API, mini app, scheduler, and runtime secrets.
+
+## Prerequisites
+
+- Terraform `>= 1.8`
+- GCP project with billing enabled
+- Local auth:
+
+```bash
+gcloud auth application-default login
+```
+
+## Bootstrap
+
+```bash
+cp infra/terraform/terraform.tfvars.example infra/terraform/terraform.tfvars
+terraform -chdir=infra/terraform init
+terraform -chdir=infra/terraform plan
+terraform -chdir=infra/terraform apply
+```
+
+## Quality checks
+
+```bash
+bun run infra:fmt:check
+bun run infra:validate
+```
+
+## Add secret values
+
+After first apply, add secret versions:
+
+```bash
+echo -n "<telegram-webhook-secret>" | gcloud secrets versions add telegram-webhook-secret --data-file=- --project <project_id>
+echo -n "<scheduler-shared-secret>" | gcloud secrets versions add scheduler-shared-secret --data-file=- --project <project_id>
+```
+
+## Environment strategy
+
+- Keep separate states for `dev` and `prod`.
+- Prefer separate GCP projects for stronger isolation.
+- Keep environment-specific variables in dedicated `*.tfvars` files.
+
+## Destructive operations
+
+Review plan output before apply/destroy:
+
+```bash
+terraform -chdir=infra/terraform plan -destroy
+terraform -chdir=infra/terraform destroy
+```

docs/specs/HOUSEBOT-007-terraform-iac-baseline.md

@@ -0,0 +1,77 @@
+# HOUSEBOT-007 Terraform IaC Baseline
+
+## Summary
+
+Define a reproducible GCP infrastructure baseline for deployment of the bot API and mini app, including scheduling and secrets.
+
+## Goals
+
+- Provision Cloud Run services for bot API and mini app.
+- Provision Cloud Scheduler reminder trigger.
+- Provision Secret Manager placeholders and runtime access bindings.
+- Provision Artifact Registry repository for container images.
+- Provide optional GitHub OIDC Workload Identity resources.
+
+## Non-goals
+
+- Business feature implementation.
+- Full observability stack (Grafana/Prometheus) in this ticket.
+- Multi-region failover.
+
+## Scope
+
+- In: Terraform scaffold, docs, CI validation.
+- Out: runtime deploy script rewrites, production dashboard configuration.
+
+## Interfaces and Contracts
+
+- Scheduler sends HTTP request to `POST /internal/scheduler/reminders`.
+- Bot runtime reads secret-backed env vars:
+  - `TELEGRAM_WEBHOOK_SECRET`
+  - `SCHEDULER_SHARED_SECRET`
+  - `SUPABASE_URL` (optional)
+  - `SUPABASE_PUBLISHABLE_KEY` (optional)
+
+## Domain Rules
+
+- N/A (infrastructure-only change).
+
+## Data Model Changes
+
+- None.
+
+## Security and Privacy
+
+- Runtime access to secrets is explicit via `roles/secretmanager.secretAccessor`.
+- Scheduler uses OIDC token with dedicated service account.
+- GitHub OIDC setup is optional and repository-scoped.
+
+## Observability
+
+- Out of scope for this ticket.
+
+## Edge Cases and Failure Modes
+
+- Missing secret versions causes runtime startup/read failures.
+- Scheduler remains paused by default to avoid accidental reminders.
+- Incorrect `bot_api_image` or `mini_app_image` tags causes deployment failures.
+
+## Test Plan
+
+- Unit: N/A
+- Integration: `terraform validate`
+- E2E: Apply in dev project and verify service URLs + scheduler job presence.
+
+## Acceptance Criteria
+
+- [ ] `terraform plan` succeeds with provided vars.
+- [ ] Two Cloud Run services and one Scheduler job are provisioned.
+- [ ] Runtime secret access is bound explicitly.
+- [ ] CI validates Terraform formatting and configuration.
+- [ ] Runbook documents local and CI workflow.
+
+## Rollout Plan
+
+- Apply to dev first with scheduler paused.
+- Add secret versions.
+- Unpause scheduler after reminder endpoint is implemented and verified.