From 653f381c4bf62e61d1bcf2a02fc7614f3db97a9c Mon Sep 17 00:00:00 2001 From: Steve Dudenhoeffer Date: Tue, 21 Jul 2026 00:55:01 -0400 Subject: [PATCH] Document the agent env vars; make keeping docs true a standing rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README's config table gained OLLAMA_CLOUD_API_KEY and PANSY_AGENT_MODEL, marked as read once the assistant lands (#56) so the table describes what the binary does rather than what it will do. Both are already set in Komodo. Also fixed the Compose example, which still said "# PANSY_OIDC_ISSUER: ... once auth (#5) lands" — auth landed a long time ago. That is exactly the kind of rot this commit is trying to prevent, so it seemed worth fixing in the same breath: the snippet now shows the OIDC vars people actually need to set. CLAUDE.md now carries the rule explicitly. README updates go in the SAME commit as the change that needs them — the env var table and the compose snippet are the two things people copy, so they hurt most when stale. DESIGN.md tracks real architecture changes. Examples must run. And when you touch a file, check the comments around your change are still true, because a stale comment is worse than none: the next reader believes it. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ --- CLAUDE.md | 22 ++++++++++++++++++++++ README.md | 12 +++++++++++- 2 files changed, 33 insertions(+), 1 deletion(-) 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: