pansy/README.md

# pansy

Self-hostable garden planner: drag beds, bags, and containers onto a real-scale field, click into them to place freeform plops of plants, and zoom out to see what's planted where. Go backend + React frontend, one static binary.

> ### 🤖 This is a vibe-coded project
>
> **Essentially all of the code in pansy was written by an LLM** (Claude), with a human directing the work, reviewing it, and deciding what ships. Every pull request also gets an automated adversarial review before it lands.
>
> That's said up front because you deserve to know it before you trust pansy with anything: it hasn't been through the kind of scrutiny a hand-written, widely-used project has. Read the code before you self-host it. Back up your database. Bugs here are the ordinary kind of bugs, not a scandal — but so is the fact that nobody hand-wrote the thing.

See [DESIGN.md](DESIGN.md) for the architecture. Work is tracked in this repo's issues — start from the tracking epic.

## Quickstart

**Prerequisites:** Go 1.26+, Node 20+.

### Develop

Run the Go API and the Vite dev server together (Vite proxies `/api` → the API):

```sh
make dev
```

Then open http://localhost:5173. Or run the two halves in separate terminals for independent restarts:

```sh
make dev-api   # Go API on :8080
make dev-web   # Vite dev server on :5173
```

### Build & run

Produce the single static binary with the web build embedded, then run it:

```sh
make build
./pansy
```

Open http://localhost:8080 — one process serves both the JSON API and the app.

### Test

```sh
make test
```

## Configuration

All configuration is via environment variables; every value has a default, so `./pansy` runs with none set.

| Variable                  | Default            | Description                                                        |
| ------------------------- | ------------------ | ------------------------------------------------------------------ |
| `PANSY_PORT`              | `8080`             | TCP port the HTTP server listens on.                               |
| `PANSY_DB`                | `./pansy.db`       | SQLite database file path (created if absent).                     |
| `PANSY_BASE_URL`          | *(empty)*          | Externally-visible base URL; used to derive the OIDC redirect URI. |
| `PANSY_REGISTRATION`      | `open`             | `open` or `closed` — gates local self-service signup.              |
| `PANSY_LOCAL_AUTH`        | `true`             | Enable local password auth. Set `false` for pure-OIDC.            |
| `PANSY_OIDC_ISSUER`       | *(empty)*          | OIDC issuer/discovery URL (Authentik). Enables SSO when set.       |
| `PANSY_OIDC_CLIENT_ID`    | *(empty)*          | OIDC client ID.                                                    |
| `PANSY_OIDC_CLIENT_SECRET`| *(empty)*          | OIDC client secret.                                                |
| `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 three more. Setting none of them leaves the assistant off; the app runs exactly as it does without it.

| Variable                | Default                        | Description                                                                 |
| ----------------------- | ------------------------------ | --------------------------------------------------------------------------- |
| `OLLAMA_CLOUD_API_KEY`  | *(empty)*                      | Ollama Cloud API key. Without it the assistant is off, not broken. This is the one agent value that stays in the environment — it is **never** stored in the database or editable in Settings. |
| `PANSY_AGENT_MODEL`     | `ollama-cloud/glm-5.2:cloud`   | Default model spec, passed verbatim to `majordomo.Parse` — a comma-separated list is a failover chain, e.g. `ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud`. An admin can override this per-instance in **Settings** without a redeploy; a blank Settings value inherits this. |
| `PANSY_AGENT_ENABLED`   | on when a key is present       | Default on/off for the assistant. Also overridable in Settings (which can inherit this default). |
| `PANSY_VISION_MODEL`    | *(empty)*                      | Default model for **seed-packet capture** (photograph a packet → it fills in the plant + purchase). A *vision-capable* model (the chat model may not be). Empty = the feature isn't offered. Runs against the same `OLLAMA_CLOUD_API_KEY`, and is overridable in Settings. |

The agent model + enabled flag, and the vision model, can be changed at runtime by an admin under **Settings** (the gear appears in the nav for admins) — an agent change swaps the live assistant with no restart. The env vars above are the defaults an untouched instance uses, and the API key is intentionally not among the runtime-editable settings: a secret in the database would land in every backup. Precedence is **Settings value, if set → env var → built-in default**.

The assistant acts without asking first, which is only reasonable because every turn is one undoable change set — see the History panel in the editor.

**If you set the key and the assistant still doesn't appear**, check that the variable reaches the *container*, not just your orchestrator's stack config — Compose needs it listed under the service's `environment:`. pansy logs why the assistant is off at startup, and Settings shows the same status (a key present, the resolved model, and whether it's actually running).

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`).

## The UI

The frontend implements the design handoff in [`docs/design_handoff_pansy_ui/`](docs/design_handoff_pansy_ui/README.md) — read that README before changing how anything looks; the `.dc.html` files there are references, not shipped code.

- **Theme.** Light by default, with a `system | light | dark` preference (the monitor/sun/moon button in every nav, or Settings → Appearance) kept in `localStorage['pansy-theme']`. Dark mode is the same stylesheet with its tokens overridden on `<html>` by a small script in `web/index.html`, which runs before the first paint.
- **Fonts.** Caprasimo and Figtree are loaded from Google Fonts (`fonts.googleapis.com`). That is the app's only request to a third party; offline it falls back to system fonts and everything else works.
- **Phone vs desktop.** The editor picks its chrome by *container* width — below 760px it is the one-column phone layout (mode bar, tool strip, a peek panel that docks between the canvas and the bar); above it, the three-card workspace. Every other page is one responsive layout.
- **Season plans.** "Copy — plan a season from it" duplicates a garden (`POST /gardens/:id/copy`) under the name `<garden> — <year>`; the editor's season control and the `plan` tag on the gardens list read that name back. Rename the copy and it is just a garden again.
- **Settings → Who gets in** is read-only: `PANSY_REGISTRATION`, `PANSY_LOCAL_AUTH` and the OIDC issuer are reported there (the `auth` block of `GET /settings`) so an admin can see what is in force without shell access; they deploy with the environment.

## Docker & deployment

CI (`.gitea/workflows/build-image.yml`) builds the single-binary image and pushes it to the Gitea registry on every branch push:

| Ref | Tag |
| --- | --- |
| `main` | `gitea.stevedudenhoeffer.com/steve/pansy:latest` |
| any other branch | `gitea.stevedudenhoeffer.com/steve/pansy:<branch-name>` |
| every build | `gitea.stevedudenhoeffer.com/steve/pansy:sha-<short>` (immutable; use to pin) |

The image runs as a non-root user, serves on `:8080`, and stores the SQLite database on the `/data` volume. Run it directly:

```sh
docker run -d --name pansy \
  -p 8080:8080 \
  -v pansy-data:/data \
  gitea.stevedudenhoeffer.com/steve/pansy:latest
```

Or as a Komodo/Compose stack:

```yaml
services:
  pansy:
    image: gitea.stevedudenhoeffer.com/steve/pansy:${PANSY_TAG:-latest}
    ports:
      - "8080:8080"
    volumes:
      - pansy-data:/data
    environment:
      PANSY_BASE_URL: https://pansy.example.com
      # PANSY_OIDC_ISSUER: https://auth.example.com/application/o/pansy/
      # PANSY_OIDC_CLIENT_ID: ...
      # PANSY_OIDC_CLIENT_SECRET: ...
      # OLLAMA_CLOUD_API_KEY: ${OLLAMA_CLOUD_API_KEY}   # enables the garden assistant
      # PANSY_AGENT_MODEL: ollama-cloud/glm-5.2:cloud
    restart: unless-stopped
volumes:
  pansy-data:
```

Pin `PANSY_TAG` to a `sha-<short>` tag for reproducible deploys, or leave it at `latest` to track `main`.