diff --git a/CLAUDE.md b/CLAUDE.md
index a02e5cf..05ed44f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,6 +21,28 @@ Rules, not preferences:
 If you find yourself editing that section, the only acceptable direction is
 clearer and more honest, never quieter.
 
+## Keep the docs true
+
+Docs rot silently and nobody notices until someone follows them and it doesn't
+work. Treat them as part of the change, not follow-up work:
+
+- **README.md** — update it in the *same commit* whenever you add or change an
+  environment variable, a route worth knowing about, a build or run command, or
+  anything in the Docker/Compose example. The env var table and the compose
+  snippet are the two things people copy, so they're the two that hurt most when
+  they're stale.
+- **DESIGN.md** — update it when the architecture actually changes: a new table,
+  a new package, a new API surface, a decision that supersedes one written there.
+  Not for every implementation detail.
+- **CLAUDE.md** — this file. Add a convention here the moment you find yourself
+  rediscovering it.
+- **Examples must run.** If you change something an example depends on, fix the
+  example. A snippet that references an issue number as "once #5 lands" after #5
+  has landed is a bug in the docs.
+
+When you touch a file, glance at whether the comments around your change are
+still true. Stale comments are worse than none — the next reader believes them.
+
 ## Build and test
 
 pansy is a standalone Go module inside a parent workspace, so **`GOWORK=off` is
diff --git a/README.md b/README.md
index 31e8e74..02dd889 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,13 @@ All configuration is via environment variables; every value has a default, so `.
 | `PANSY_OIDC_BUTTON_LABEL` | `Sign in with Authentik` | Label for the OIDC button on the login page.                |
 | `PANSY_TRUSTED_PROXIES`   | *(none)*           | Comma-separated proxy CIDRs/IPs to trust for client-IP resolution. |
 
+The garden assistant reads two more. Both are **read only once the assistant lands** ([#56](https://gitea.stevedudenhoeffer.com/steve/pansy/issues/56)); setting them earlier is harmless and setting neither leaves the assistant off.
+
+| Variable                | Default                       | Description                                                                 |
+| ----------------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| `OLLAMA_CLOUD_API_KEY`  | *(empty)*                     | Ollama Cloud API key. Without it the assistant is disabled, not broken.      |
+| `PANSY_AGENT_MODEL`     | `ollama-cloud/glm-5.2:cloud`  | Model spec, passed verbatim to `majordomo.Parse` — a comma-separated list is a failover chain. |
+
 Local email/password auth is live (`POST /api/v1/auth/register`, `/auth/login`, `/auth/logout`, `GET /auth/me`, `GET /auth/providers`); the session is an HttpOnly cookie (`Secure` when `PANSY_BASE_URL` is https). The first account registered becomes admin, and it may register even when `PANSY_REGISTRATION=closed` to bootstrap the instance.
 
 OIDC (Authentik-first) is live too: set `PANSY_OIDC_ISSUER`, `PANSY_OIDC_CLIENT_ID`, `PANSY_OIDC_CLIENT_SECRET`, and `PANSY_BASE_URL` (needed for the redirect URI). Register `PANSY_BASE_URL` + `/api/v1/auth/oidc/callback` as the redirect URI in your IdP. `GET /auth/oidc/login` starts an authorization-code + PKCE flow; first login provisions a user just-in-time (a matching *verified* email links to an existing local account instead of duplicating it). Provider discovery is lazy, so a briefly-unreachable IdP never blocks startup or local auth. Set `PANSY_LOCAL_AUTH=false` for pure-Authentik deployments (local register/login are then rejected and hidden from `/auth/providers`).
@@ -98,7 +105,10 @@ services:
       - pansy-data:/data
     environment:
       PANSY_BASE_URL: https://pansy.example.com
-      # PANSY_OIDC_ISSUER: ...   # once auth (#5) lands
+      # PANSY_OIDC_ISSUER: https://auth.example.com/application/o/pansy/
+      # PANSY_OIDC_CLIENT_ID: ...
+      # PANSY_OIDC_CLIENT_SECRET: ...
+      # OLLAMA_CLOUD_API_KEY: ...     # enables the garden assistant
     restart: unless-stopped
 volumes:
   pansy-data: