diff --git a/.env.example b/.env.example
index 0629fc8..ca68d5e 100644
--- a/.env.example
+++ b/.env.example
@@ -35,6 +35,13 @@ CHAT_DEPLOYMENT=                  # flagship — final prose only
 CHEAP_DEPLOYMENT=                 # nano/mini — classifier, entities, tool selection
 EMBED_DEPLOYMENT=                 # text-embedding-3-small
 
+# --- no-LLM stub mode --------------------------------------------------------
+# OFF for anything real. With it on, no model is called: the class comes from
+# the caller instead of the classifier and the prose is a fixed placeholder.
+# Every answer carries stub_mode: true and a banner. See api/stub.py for what
+# it proves and what it does not.
+NO_LLM_STUB=false
+
 # --- behaviour ---------------------------------------------------------------
 CLASSIFIER_CONFIDENCE_THRESHOLD=0.7
 SITE_TIMEZONE=Australia/Sydney    # storage UTC; convert once, in Cube
@@ -46,7 +53,38 @@ MAX_OUTPUT_TOKENS=1200
 CUBEJS_API_SECRET=
 CUBEJS_API_URL=http://cube:4000/cubejs-api/v1
 
+# The upstream source Cube reads. ai-compose.yml says these come from this
+# file, and this file did not list them - so the first person to deploy Cube
+# had to work out from the compose comments and db/003_roles.sql what the
+# service actually needed. While USE_FIXTURES=true the fixtures live in pg-ai,
+# so this points at pg-ai with the cube_rw credentials from pg-ai.env.
+# At Phase 4 the whole block becomes CUBEJS_DB_TYPE=mssql against imh.
+CUBEJS_DB_TYPE=postgres
+CUBEJS_DB_HOST=pg-ai
+CUBEJS_DB_PORT=5432
+CUBEJS_DB_NAME=plant
+CUBEJS_DB_USER=cube_rw            # CUBE_DB_USER in pg-ai.env
+CUBEJS_DB_PASS=                   # CUBE_DB_PASSWORD in pg-ai.env
+
+# NOT CUBEJS_EXT_DB_*. Cube v1 will not use Postgres as an external
+# pre-aggregation store; cubestore does that job and needs no keys here.
+# See the note above the cube service in compose/ai-compose.yml.
+
 # --- Langfuse ----------------------------------------------------------------
+# PROJECT keys, created in the Langfuse UI - not the server's own secrets
+# (SALT, NEXTAUTH_SECRET), which live in langfuse.env and are a different
+# thing. The two must be a MATCHED PAIR from the same key: a public key from
+# one pair with a secret from another authenticates as neither.
+#
+# Langfuse shows the secret ONCE, at creation, and stores only a hash - the
+# database keeps a masked form (sk-lf-...abcd) and nothing can recover it. If
+# it is lost, generate a new pair; there is no way to read the old one back.
+#
+# Getting this wrong is silent in both directions. Keys absent -> _langfuse()
+# returns None and every question is simply untraced. Keys present but wrong ->
+# a client is built, Langfuse rejects it, and main.py swallows the exception on
+# purpose, because observability must never break the answer path. Neither case
+# logs anything. Confirm traces are ARRIVING; do not infer it from config.
 LANGFUSE_HOST=http://langfuse:3000
 LANGFUSE_PUBLIC_KEY=
 LANGFUSE_SECRET_KEY=