diff --git a/ai/ai.env.template b/ai/ai.env.template
new file mode 100644
index 0000000..cc55720
--- /dev/null
+++ b/ai/ai.env.template
@@ -0,0 +1,54 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# ai.env.template — AUTHORITATIVE template for ai/ai.env (rendered by
+# deploy/provision-stack.py per secrets/secrets-map.yaml).
+#
+#   - This file IS the complete key list for ai.env. The whole file is
+#     rendered on every provisioning run — no line surgery, so a key can
+#     never silently go missing again (root cause of the 2026-09-03 outage).
+#   - Non-secret config lives here as LITERAL values (visible, reviewable).
+#   - Secret values are dollar-brace placeholders resolved from Woodpecker
+#     secrets at provisioning time. provision-stack.py FAILS HARD if any
+#     placeholder is missing/empty — a broken render can never ship.
+#   - The rendered ai/ai.env exists only on the host (gitignored).
+#   - NOTE: this template is rendered by provision-stack.py, NOT by
+#     Woodpecker's yaml preprocessor — single-dollar placeholders here are
+#     safe and correct (the deploy.yml double-dollar rule does NOT apply to
+#     this file).
+#
+# Consumed by ai/ai.yaml. DOMAIN_NAME comes from deploy/global.env, not here.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── LiteLLM (non-secret config) ──────────────────────────────────────────────
+AWS_REGION_NAME=us-east-2
+LITELLM_MODIFY_PARAMS=False
+LITELLM_DATABASE_MIGRATIONS=True
+
+# ── LiteLLM (secrets) ────────────────────────────────────────────────────────
+AI_AWS_ACCESS_KEY_ID=${AI_AWS_ACCESS_KEY_ID}
+AI_AWS_SECRET_ACCESS_KEY=${AI_AWS_SECRET_ACCESS_KEY}
+LITELLM_MASTER_KEY=${AI_LITELLM_MASTER_KEY}
+LITELLM_SALT_KEY=${AI_LITELLM_SALT_KEY}
+# Full connection URL is itself a secret (ai_litellm_database_url) — the
+# URL structure never appears in git.
+DATABASE_URL=${AI_LITELLM_DATABASE_URL}
+POSTGRES_PASSWORD=${AI_LITELLM_POSTGRES_PASSWORD}
+
+# ── Open WebUI (non-secret config) ───────────────────────────────────────────
+WEBUI_URL=https://ai.bryanmail.net
+ENABLE_OAUTH_SIGNUP=true
+OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true
+OAUTH_PROVIDER_NAME=Authentik
+OPENID_PROVIDER_URL=https://auth.bryanmail.net/application/o/open-web-ui/.well-known/openid-configuration
+# OAuth client ID is a public identifier by OAuth2 design (it is sent to the
+# browser); the client SECRET below is the protected credential.
+OAUTH_CLIENT_ID=hVmhi1dS3TnG2cUw5QwLOx5FDLSWtnQUdZyeB5zK
+OAUTH_SCOPES=openid email profile
+OPENID_REDIRECT_URI=https://ai.bryanmail.net/oauth/oidc/callback
+
+# ── Open WebUI (secrets) ─────────────────────────────────────────────────────
+WEBUI_SECRET_KEY=${AI_WEBUI_SECRET_KEY}
+OPEN_WEBUI_DATABASE_URL=${AI_OPEN_WEBUI_DATABASE_URL}
+OAUTH_CLIENT_SECRET=${AI_OPEN_WEB_UI_OAUTH_CLIENT_SECRET}
+
+# ── mcpo / mcpo-critical (secrets) ───────────────────────────────────────────
+MCPO_API_KEY=${AI_MCPO_API_KEY}