Merge remote-tracking branch 'origin/dev' into release/2026-10-07

Co-authored-by: orchestrator-agent <20+orchestrator-agent@code.cubecraftcreations.com>

.gitignore

@@ -3,6 +3,8 @@ design/.DS_Store
 
 # Secrets and local environment
 .env*
+!deploy/.env.example
+deploy/.env
 deploy/secrets/
 
 # Build artifacts and dependencies

README.md

@@ -44,6 +44,9 @@ export MEALQUEST_OIDC_ALLOWED_GROUPS=mealquest-admin
 # X-Forwarded-For/-Proto headers are honoured (production: Traefik). Unset
 # trusts no peer, which is right for local development.
 # export MEALQUEST_TRUSTED_PROXY=10.60.1.33
+# Optional: a SearXNG instance the Settings screen suggests as the recipe
+# search URL until one is saved.
+# export MEALQUEST_SEARXNG_URL=http://localhost:8888
 export MEALQUEST_DEFAULT_TZ=America/New_York
 make dev
 ```
@@ -53,8 +56,9 @@ make dev
 http://localhost:5173. Configuration is environment-only and fails fast:
 every variable above is required except the commented-out session
 lifetimes (when set they must be positive, with MAX at least IDLE),
-trusted proxy list (every entry must be an IP or CIDR) and
-`MEALQUEST_DEFAULT_TZ`, and
+trusted proxy list (every entry must be an IP or CIDR), the SearXNG URL
+(an absolute `http://` or `https://` URL without credentials, a query or a
+fragment) and `MEALQUEST_DEFAULT_TZ`, and
 secrets are read only from files named by `*_FILE` variables. `MEALQUEST_PUBLIC_URL`, `MEALQUEST_OIDC_ISSUER` and the
 endpoints the issuer advertises must be `https://`; plain `http://` is
 accepted only for `localhost`, `127.0.0.1` and `[::1]`.

cmd/server/main.go

@@ -13,8 +13,12 @@ import (
 	"syscall"
 	"time"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
@@ -50,7 +54,8 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
-	if _, err := openSecretBox(cfg.SecretKey); err != nil {
+	box, err := openSecretBox(cfg.SecretKey)
+	if err != nil {
 		return err
 	}
 
@@ -73,7 +78,31 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	photos, err := recipes.NewPhotoCache(recipes.NewFetcher(), db, cfg.DataDir)
+	// One fetcher serves pages and photos, so its per-host spacing and
+	// page cache cover both.
+	fetcher := recipes.NewFetcher()
+	photos, err := recipes.NewPhotoCache(fetcher, db, cfg.DataDir)
+	if err != nil {
+		return err
+	}
+	search, err := recipes.NewSearchSettingsService(db, box, cfg.SearXNGURL)
+	if err != nil {
+		return fmt.Errorf("%s: %w", config.EnvSearXNGURL, err)
+	}
+
+	ai, err := aisettings.New(db, box, cfg.PublicURL.String())
+	if err != nil {
+		return err
+	}
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		return err
+	}
+	grounder, err := recipes.NewGrounder(db, search, fetcher, photos, normalizer(ai, guard))
+	if err != nil {
+		return err
+	}
+	dinnerSvc, err := dinners.NewService(db, grounder, runner, logger)
 	if err != nil {
 		return err
 	}
@@ -94,7 +123,7 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, runner, photos, frontend.Assets())
+	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, dinnerSvc, runner, photos, frontend.Assets())
 	if err != nil {
 		return err
 	}
@@ -110,6 +139,12 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	if err := runner.Start(jobsCtx); err != nil {
 		return err
 	}
+	// With those jobs failed, a dinner still pending with no grounding job
+	// queued or running is failed as interrupted, before any request can
+	// create one.
+	if _, err := dinnerSvc.FailInterruptedGroundings(ctx); err != nil {
+		return err
+	}
 	srv := &http.Server{
 		Addr:              cfg.HTTPAddr,
 		Handler:           router,
@@ -191,7 +226,7 @@ func seedDefaults(ctx context.Context, db *store.Store, defaultTZ string) error
 	return household.SeedNotificationPrefs(ctx, db)
 }
 
-// jobKinds enqueues every job kind the server runs.
+// jobKinds enqueues the framework's job kinds.
 type jobKinds struct {
 	builtins *jobs.Builtins
 }
@@ -210,8 +245,9 @@ func newJobRunner(db *store.Store, logger *slog.Logger) (*jobs.Runner, *jobKinds
 	return runner, kinds, nil
 }
 
-// registerJobKinds registers every job kind's handler on runner. Each
-// feature's job kinds are registered here.
+// registerJobKinds registers the framework's job kinds on runner. A feature
+// service registers its own kinds when it is built, before the runner
+// starts (dinners.NewService registers dinners.KindGroundDinner).
 func registerJobKinds(runner *jobs.Runner) (*jobKinds, error) {
 	builtins, err := jobs.RegisterBuiltins(runner)
 	if err != nil {
@@ -220,6 +256,18 @@ func registerJobKinds(runner *jobs.Runner) (*jobKinds, error) {
 	return &jobKinds{builtins: builtins}, nil
 }
 
+// normalizer runs normalize_recipe with the AI settings current at each
+// run, sharing guard.
+func normalizer(ai *aisettings.Service, guard *harness.Guard) recipes.Normalizer {
+	return func(ctx context.Context, scope string, in skills.RecipeText) (skills.NormalizedRecipe, error) {
+		cfg, err := ai.HarnessConfig(ctx, guard)
+		if err != nil {
+			return skills.NormalizedRecipe{}, err
+		}
+		return skills.NormalizeRecipe(ctx, cfg, scope, in)
+	}
+}
+
 // logListening logs the startup line. Only the public URL's origin is logged
 // so no credential-bearing URL component can reach the log.
 func logListening(logger *slog.Logger, cfg config.Config) {

deploy/.env.example

@@ -0,0 +1,87 @@
+# MealQuest production environment. Copy to deploy/.env (never committed)
+# and replace the placeholders. The service fails fast: a missing or invalid
+# required variable stops it at boot with the variable named.
+#
+# Secrets are never set here. They live in deploy/secrets/ (never committed),
+# one value per file, owned by the container user and readable only by it:
+#
+#   mkdir -p deploy/secrets && chmod 700 deploy/secrets
+#   head -c 32 /dev/urandom | base64 > deploy/secrets/secret_key
+#   printf '%s\n' '<Authentik client secret>' > deploy/secrets/oidc_client_secret
+#   sudo chown 10001:10001 deploy/secrets/* && sudo chmod 600 deploy/secrets/*
+#
+# SearXNG's secret key is the exception: compose reads it itself, so it
+# stays owned by you (mode 0600). Create it after the chown above:
+#
+#   (umask 077; printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > deploy/secrets/searxng.env)
+#
+# deploy/compose.yaml mounts them at /run/secrets/<name> and points the
+# *_FILE variables at them.
+
+# --- Compose -----------------------------------------------------------------
+
+# Host address the service is published on, as <address>:8090. Production
+# binds the LAN address 10.60.1.14 only; 127.0.0.1 suits a dev machine.
+MEALQUEST_BIND_ADDRESS=127.0.0.1
+
+# --- Service -----------------------------------------------------------------
+
+# Public origin the household opens. Fixes the OIDC redirect URI
+# (<url>/auth/callback) and the Secure cookies. Must be https:// (plain
+# http:// is accepted only for localhost, 127.0.0.1 and [::1]).
+MEALQUEST_PUBLIC_URL=https://mealquest.cubecraftlabs.com
+
+# How long a graceful shutdown may take before in-flight requests are cut.
+MEALQUEST_SHUTDOWN_TIMEOUT=10s
+
+# Optional. Comma-separated IPs/CIDRs of reverse proxies whose
+# X-Forwarded-For/-Proto headers are honoured. Production lists Traefik;
+# unset trusts no peer.
+MEALQUEST_TRUSTED_PROXY=10.60.1.33
+
+# IANA zone the household settings are created with on first boot. Required
+# until those settings exist; ignored afterwards (change the zone in
+# household settings instead). Confirm the household's zone before the first
+# deploy.
+MEALQUEST_DEFAULT_TZ=America/New_York
+
+# --- Authentik OIDC ----------------------------------------------------------
+
+# Issuer of the Authentik application "mealquest". Discovered at boot, so it
+# must be reachable from the container. Must be https://.
+MEALQUEST_OIDC_ISSUER=https://auth.cubecraftlabs.com/application/o/mealquest/
+MEALQUEST_OIDC_CLIENT_ID=mealquest
+# Comma-separated Authentik groups whose members may sign in.
+MEALQUEST_OIDC_ALLOWED_GROUPS=mealquest-admin
+
+# Optional session lifetimes. A session ends after IDLE unused and always MAX
+# after sign-in; MAX must be at least IDLE. Defaults: 720h and 4320h.
+MEALQUEST_SESSION_IDLE=720h
+MEALQUEST_SESSION_MAX=4320h
+
+# --- Set by deploy/compose.yaml; do not set here -----------------------------
+#
+# MEALQUEST_HTTP_ADDR=:8080
+# MEALQUEST_DATA_DIR=/data
+# MEALQUEST_SECRET_KEY_FILE=/run/secrets/secret_key
+#   Base64 of 32 random bytes; encrypts secrets at rest (AES-256-GCM).
+# MEALQUEST_OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret
+#   The Authentik provider's client secret.
+# MEALQUEST_SEARXNG_URL=http://searxng:8080
+#   The SearXNG recipe-search sidecar on the compose network. The Settings
+#   screen pre-fills it as the SearXNG URL until one is saved; the saved
+#   provider and base URL come from PATCH /api/v1/settings/recipe-search.
+#   See deploy/RUNBOOK.md "Recipe search (SearXNG)".
+
+# --- Planned; not read by the service yet -------------------------------------
+#
+# Added to deploy/compose.yaml and this file by the features that use them.
+#
+# Web Push (Feature 19). Generate the key pair with cmd/vapidgen.
+# MEALQUEST_VAPID_PUBLIC_KEY=<base64url VAPID public key>
+# MEALQUEST_VAPID_PRIVATE_KEY_FILE=/run/secrets/vapid_private_key
+# MEALQUEST_VAPID_SUBJECT=mailto:<owner address>
+#
+# Google Calendar OAuth web client (Feature 16).
+# MEALQUEST_GOOGLE_CLIENT_ID=<client id>.apps.googleusercontent.com
+# MEALQUEST_GOOGLE_CLIENT_SECRET_FILE=/run/secrets/google_client_secret

deploy/RUNBOOK.md

@@ -0,0 +1,982 @@
+# MealQuest deployment runbook
+
+How MealQuest is deployed on office-srvr (10.60.1.14), how it is reached
+through Authentik, Traefik and DNS, how it is updated and rolled back, how
+its data is backed up and restored, and how its secrets are rotated. Values
+are the ones in use on 2026-10-05. Secrets themselves are never written
+here.
+
+Paths used below:
+
+| Name | Path |
+| --- | --- |
+| Checkout on the host | `/home/overseer/mealquest` |
+| Data volume (`mealquest-data`) on the host | `/var/lib/docker/volumes/mealquest-data/_data` |
+| Same volume inside the containers | `/data` |
+| Database | `mealquest.db` (+ `mealquest.db-wal`, `mealquest.db-shm` while open) |
+| Media | `media/` in the data volume |
+| Backup target (NAS, over SSH) | `joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups` |
+| Same target over SFTP (Synology chroot) | `/homes/Joshua/mealquest-backups` |
+
+## Prerequisites
+
+On office-srvr (10.60.1.14), as recorded on 2026-10-05:
+
+| Item | Value |
+| --- | --- |
+| OS | Ubuntu 26.04.1 LTS |
+| Docker Engine / Compose plugin | 29.8.2 / 5.6.0 |
+| git, rsync, iptables | 2.53.0, 3.4.1, 1.8.11 (nf_tables) |
+| Account | `overseer`, with sudo |
+| Network | LAN reachability to Traefik (10.60.1.33), Authentik (`auth.cubecraftlabs.com`) and the NAS (10.60.1.50, SSH) |
+
+Elsewhere:
+
+- Admin access to Authentik at <https://auth.cubecraftlabs.com>.
+- SSH access to the Traefik host 10.60.1.33.
+- Cloudflare access for the `cubecraftlabs.com` zone, and admin access to
+  both Pi-holes (10.60.1.101 `dns.ccl`, 10.60.1.85 `dns2.ccl`).
+- A NAS account `joshua` on 10.60.1.50 with the backup directory
+  `/volume1/homes/Joshua/mealquest-backups` (see "Backups").
+- A Gitea token able to read `Maniacs_Mansion/MealQuest`, for the clone.
+
+## Stack and first deploy
+
+The compose stack is `deploy/compose.yaml`: the `mealquest` service (built
+from the repository `Dockerfile`, runs as uid/gid 10001, listens on 8080 in
+the container), the `litestream` service and the `searxng` recipe-search
+sidecar (see "Recipe search (SearXNG)"). Data lives in the named volume
+`mealquest-data`.
+
+### 1. Choose and check the port
+
+The container's 8080 is published on `10.60.1.14:8090`. Ports 8080 and 8081
+on this host belong to NestQuest, so 8090 was chosen. Before the first
+deploy it was checked free with:
+
+```sh
+ss -ltnp | grep 8090   # printed nothing
+```
+
+After the deploy the same host shows NestQuest on 8080/8081 and MealQuest
+on 8090:
+
+```
+LISTEN 0 4096 10.60.1.14:8080 0.0.0.0:*
+LISTEN 0 4096 10.60.1.14:8081 0.0.0.0:*
+LISTEN 0 4096 10.60.1.14:8090 0.0.0.0:*
+```
+
+The published host port is fixed in `deploy/compose.yaml`, in
+`deploy/systemd/mealquest-firewall.sh` and in the Traefik route; change all
+three together.
+
+### 2. Clone
+
+The checkout lives at `/home/overseer/mealquest`, next to NestQuest's
+`~/nestquest` (not `/opt/mealquest`). Clone over HTTPS with a Gitea token,
+then reset the remote to the clean URL so the token is not stored in
+`.git/config`:
+
+```sh
+cd /home/overseer
+git clone https://<user>:<token>@code.cubecraftlabs.com/Maniacs_Mansion/MealQuest.git mealquest
+cd mealquest
+git remote set-url origin https://code.cubecraftlabs.com/Maniacs_Mansion/MealQuest.git
+git remote -v   # must show no token
+git checkout main
+```
+
+### 3. Environment file
+
+`deploy/.env` (git-ignored) is copied from `deploy/.env.example` and is
+mode 0600, owned by `overseer`:
+
+```sh
+cp deploy/.env.example deploy/.env
+chmod 600 deploy/.env
+```
+
+Then edit `deploy/.env` to the values below. In particular
+**`MEALQUEST_BIND_ADDRESS` must be changed**: `.env.example` ships
+`127.0.0.1` (a dev machine), and left as is the service listens only on
+the host's loopback, which Traefik cannot reach. Set it to the LAN address
+and check:
+
+```sh
+sed -i 's/^MEALQUEST_BIND_ADDRESS=.*/MEALQUEST_BIND_ADDRESS=10.60.1.14/' deploy/.env
+grep '^MEALQUEST_BIND_ADDRESS=' deploy/.env      # MEALQUEST_BIND_ADDRESS=10.60.1.14
+docker compose -f deploy/compose.yaml config | grep -A4 'ports:'
+#   host_ip: 10.60.1.14, target: 8080, published: "8090"
+```
+
+After step 5 the listener is `10.60.1.14:8090` (container port 8080):
+
+```sh
+docker compose -f deploy/compose.yaml port mealquest 8080   # 10.60.1.14:8090
+sudo ss -ltnp 'sport = :8090'                               # 10.60.1.14:8090 only, no 0.0.0.0 or 127.0.0.1
+```
+
+Values in use:
+
+| Variable | Value |
+| --- | --- |
+| `MEALQUEST_BIND_ADDRESS` | `10.60.1.14` |
+| `MEALQUEST_PUBLIC_URL` | `https://mealquest.cubecraftlabs.com` |
+| `MEALQUEST_SHUTDOWN_TIMEOUT` | `10s` |
+| `MEALQUEST_TRUSTED_PROXY` | `10.60.1.33` |
+| `MEALQUEST_DEFAULT_TZ` | `America/New_York` |
+| `MEALQUEST_OIDC_ISSUER` | `https://auth.cubecraftlabs.com/application/o/mealquest/` |
+| `MEALQUEST_OIDC_CLIENT_ID` | `i6zraqmWsF552b8nmte070LXz0SI5pRdArBxFxeq` (not a secret) |
+| `MEALQUEST_OIDC_ALLOWED_GROUPS` | `mealquest-admin` |
+| `MEALQUEST_SESSION_IDLE` / `MEALQUEST_SESSION_MAX` | `720h` / `4320h` |
+
+`MEALQUEST_HTTP_ADDR`, `MEALQUEST_DATA_DIR` and the `*_FILE` variables are
+set by `deploy/compose.yaml` and must not appear in `deploy/.env`.
+
+### 4. Secrets
+
+`deploy/secrets/` (git-ignored) is mode 0700, owned by `overseer`. Each
+file holds one value, is owned by `10001:10001` (host user `mealquest`) and
+is mode 0600. Compose bind-mounts file secrets with their host owner and
+mode, so any other owner or mode stops the container reading them and the
+service refuses to start.
+
+| File | Content | Mounted at |
+| --- | --- | --- |
+| `secret_key` | base64 of 32 random bytes; encrypts stored secrets (AES-256-GCM) | `/run/secrets/secret_key` |
+| `oidc_client_secret` | Client Secret of the Authentik provider `mealquest` | `/run/secrets/oidc_client_secret` |
+| `litestream_key` | dedicated SSH private key for the NAS (see "Backups") | `/etc/litestream/sftp_key` |
+| `searxng.env` | `SEARXNG_SECRET=<64 hex characters>`; SearXNG's secret key | not mounted; compose passes it as an environment variable |
+
+`searxng.env` is the one exception to the owner rule: compose itself reads
+it (as `env_file`), so it is owned by `overseer`, mode 0600.
+
+```sh
+mkdir -p deploy/secrets && chmod 700 deploy/secrets
+head -c 32 /dev/urandom | base64 > deploy/secrets/secret_key
+printf '%s\n' '<Authentik client secret>' > deploy/secrets/oidc_client_secret
+# litestream_key: see "Backups" > "Database — Litestream"
+sudo chown 10001:10001 deploy/secrets/secret_key deploy/secrets/oidc_client_secret deploy/secrets/litestream_key
+sudo chmod 600 deploy/secrets/*
+(umask 077; printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > deploy/secrets/searxng.env)
+sudo ls -la deploy/secrets   # three files mealquest mealquest, searxng.env overseer overseer; all -rw-------
+```
+
+The `mealquest` host user (uid/gid 10001) is created in "Media — nightly
+rsync"; until it exists `ls` shows the numeric ids.
+
+### 5. Firewall, then the stack
+
+Install the firewall unit and the stack unit first (see "Host firewall"
+and "Stack unit"), so port 8090 is never open to the LAN. Create the media
+directory (see "Media — nightly rsync"), then build and start:
+
+```sh
+docker compose -f deploy/compose.yaml build
+sudo systemctl enable --now mealquest   # starts mealquest-firewall first
+docker compose -f deploy/compose.yaml ps   # mealquest healthy, litestream up, searxng healthy
+curl -fsS http://10.60.1.14:8090/health
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+```
+
+### Host checkout state on 2026-10-05
+
+The first deploy ran before Feature 07 reached `main`. The checkout is at
+`main` `9cddbbb` and the Feature 07 files under `deploy/` were copied in
+from the feature branch: `deploy/compose.yaml` and `deploy/.env.example`
+are listed in `.git/info/exclude`, the rest show as untracked. Before the
+first routine deploy of a `main` that contains `deploy/`, remove those
+`.git/info/exclude` lines and the copied files (keep `deploy/.env` and
+`deploy/secrets/`), or `git checkout` refuses to overwrite them:
+
+```sh
+cd /home/overseer/mealquest
+git status --porcelain --untracked-files=all deploy   # the copied files
+sed -i '/^deploy\/\(compose.yaml\|.env.example\)$/d' .git/info/exclude
+git clean -n deploy      # dry run: must not list .env or secrets/ (both git-ignored)
+git clean -f deploy
+```
+
+On 2026-10-06 `deploy/compose.yaml` was replaced and
+`deploy/compose.dev.yaml` and `deploy/searxng/settings.yml` were copied in
+from the Feature 10 branch (task 641f468b) to start the SearXNG sidecar;
+they too must go before that checkout (`git clean -n -d deploy` lists
+them).
+
+Then follow "Routine deploy"; the checkout brings the tracked copies back.
+
+## Authentik
+
+Sign-in is OpenID Connect against Authentik at
+<https://auth.cubecraftlabs.com>.
+
+| Object | Setting |
+| --- | --- |
+| Provider | OAuth2/OpenID provider `mealquest`, client type **Confidential** |
+| Redirect URI | `https://mealquest.cubecraftlabs.com/auth/callback` (strict) |
+| Signing | RS256, with the instance's signing key |
+| Scopes | MealQuest requests `openid profile email groups offline_access`; the provider's scope mappings include openid, profile, email and offline_access, and the `groups` claim is delivered by a property mapping (the default profile mapping carries `groups`) |
+| Application | name MealQuest, slug `mealquest`, provider `mealquest` |
+| Group | `mealquest-admin`, bound to the application; household members are added to it |
+| Client ID | `i6zraqmWsF552b8nmte070LXz0SI5pRdArBxFxeq` (not a secret; in `deploy/.env` as `MEALQUEST_OIDC_CLIENT_ID`) |
+| Client Secret | in `deploy/secrets/oidc_client_secret` only |
+
+MealQuest refuses a sign-in unless the user's `groups` claim (from the ID
+token, or from userinfo when the token has none) contains a group in
+`MEALQUEST_OIDC_ALLOWED_GROUPS`.
+
+Check discovery from the Docker host — the service discovers the issuer
+at boot and will not start if it cannot:
+
+```sh
+curl -s -o /dev/null -w "%{http_code}\n" \
+  https://auth.cubecraftlabs.com/application/o/mealquest/.well-known/openid-configuration   # 200
+```
+
+On 2026-10-05 discovery returned 200 with issuer
+`https://auth.cubecraftlabs.com/application/o/mealquest/` and
+`id_token_signing_alg_values_supported: ["RS256"]`.
+
+## Reverse proxy (Traefik)
+
+MealQuest is published at <https://mealquest.cubecraftlabs.com> by the
+shared Traefik instance on 10.60.1.33 (Feature 07, task 0c1dc172). The
+route is a dynamic-configuration file that lives on the Traefik host only,
+at `/home/overseer/Code/traefik/config/dynamic/mealquest-ccl.yml`. Its exact
+contents:
+
+```yaml
+# MealQuest - https://mealquest.cubecraftlabs.com
+#   Feature 07 task 0c1dc172. Single Go binary (API + embedded PWA) on
+#   office-srvr 10.60.1.14:8090. HTTP -> HTTPS is handled globally by
+#   http-conf.yml, so only a websecure router is defined here.
+#   This file lives on the Traefik host only; the repo copy is recorded in
+#   deploy/RUNBOOK.md by task 876134bc.
+http:
+  routers:
+    mealquest:
+      entryPoints:
+        - websecure
+      rule: "Host(`mealquest.cubecraftlabs.com`)"
+      priority: 100
+      middlewares:
+        - mealquest-headers
+      service: mealquest
+      tls:
+        certResolver: myresolver
+        domains:
+          - main: mealquest.cubecraftlabs.com
+
+  services:
+    mealquest:
+      loadBalancer:
+        servers:
+          - url: "http://10.60.1.14:8090"
+
+  middlewares:
+    mealquest-headers:
+      headers:
+        stsSeconds: 31536000
+        stsIncludeSubdomains: true
+        contentTypeNosniff: true
+        frameDeny: true
+```
+
+Traefik watches the dynamic directory, so saving the file loads the route;
+the certificate comes from `certResolver: myresolver` (Let's Encrypt,
+DNS-01 through Cloudflare). Check from the LAN:
+
+```sh
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+```
+
+## DNS
+
+| Where | Record |
+| --- | --- |
+| Cloudflare, zone `cubecraftlabs.com` | `CNAME mealquest.cubecraftlabs.com` → `cubecraftlabs.com`, **proxied = true** (orange cloud). Because it is proxied, public resolvers answer with Cloudflare's anycast addresses, A and AAAA (AAAA on 2026-10-05: `2606:4700:3032::6815:34ed`, `2606:4700:3035::ac43:cd75`), never the origin |
+| Pi-hole primary 10.60.1.101 (`dns.ccl`), Local DNS records | `A mealquest.cubecraftlabs.com` → `10.60.1.33` (Traefik) |
+| Pi-hole secondary 10.60.1.85 (`dns2.ccl`), Local DNS records | `A mealquest.cubecraftlabs.com` → `10.60.1.33` (Traefik) |
+
+The local record must be on **both** Pi-holes, or clients using the
+secondary go out through Cloudflare. Check:
+
+```sh
+for s in 10.60.1.101 10.60.1.85; do dig +short @$s mealquest.cubecraftlabs.com A; done
+# 10.60.1.33 from each
+```
+
+**AAAA caveat.** The Pi-hole local record is A only, so both Pi-holes still
+forward AAAA queries and return Cloudflare's IPv6 addresses
+(`2606:4700:3032::6815:34ed`, `2606:4700:3035::ac43:cd75` on 2026-10-05). An
+IPv6-capable LAN client may prefer those and reach MealQuest through
+Cloudflare instead of directly through Traefik. It still works (Cloudflare
+proxies to the public route), but it is not the LAN path. If that matters,
+add a local AAAA override or block AAAA for this name on both Pi-holes.
+
+## Host firewall
+
+Docker publishes `10.60.1.14:8090` past the host's INPUT rules, so the
+port is restricted in the `DOCKER-USER` chain instead: only Traefik
+(10.60.1.33) and the host itself (10.60.1.14) may connect; every other
+source is dropped.
+
+Docker DNATs the published port to the container address and port 8080
+**before** `DOCKER-USER`, so a plain `-p tcp --dport 8090` rule never
+matches. The rules match the original destination `10.60.1.14:8090` with
+conntrack (`--ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL`)
+and are tagged with the comment `mealquest-firewall`. The port is never
+open while the rules change: if the chain does not already start with
+exactly the three rules, the script first inserts the DROP at position 1,
+then deletes its other tagged rules and inserts the two RETURN rules above
+the DROP. A re-run on a correct chain changes nothing. NestQuest's
+8080/8081 rules below them are left untouched.
+
+| Repository file | Installed as |
+| --- | --- |
+| `deploy/systemd/mealquest-firewall.sh` | `/usr/local/sbin/mealquest-firewall` (root, 0755) |
+| `deploy/systemd/mealquest-firewall.service` | `/etc/systemd/system/mealquest-firewall.service` (root, 0644) |
+
+The unit is `Type=oneshot`, `RemainAfterExit=yes`, `Requires=` and
+`PartOf=docker.service`, and `WantedBy=multi-user.target docker.service`:
+it re-applies the rules whenever Docker starts or restarts (Docker
+recreates `DOCKER-USER` empty), and a failure fails this unit only.
+
+Install (done on 10.60.1.14 on 2026-10-05):
+
+```sh
+cd /home/overseer/mealquest
+sudo install -o root -g root -m 0755 deploy/systemd/mealquest-firewall.sh /usr/local/sbin/mealquest-firewall
+sudo install -o root -g root -m 0644 deploy/systemd/mealquest-firewall.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mealquest-firewall
+```
+
+Check:
+
+```sh
+systemctl is-enabled mealquest-firewall; systemctl is-active mealquest-firewall   # enabled, active
+sudo iptables -S DOCKER-USER
+```
+
+Expected head of the chain (recorded 2026-10-05; NestQuest's rules follow):
+
+```
+-A DOCKER-USER -s 10.60.1.33/32 -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j RETURN
+-A DOCKER-USER -s 10.60.1.14/32 -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j RETURN
+-A DOCKER-USER -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j DROP
+```
+
+From any other LAN machine, `curl -m 5 http://10.60.1.14:8090/health` must
+time out; from 10.60.1.33 and 10.60.1.14 it returns 200.
+
+## Stack unit
+
+`deploy/systemd/mealquest.service` owns the compose stack and is the only
+way it starts. Both compose services use `restart: "no"`, so Docker never
+starts them on its own; the unit has `Requires=` and
+`After=mealquest-firewall.service`, so the stack starts only after the
+firewall rules are applied, and not at all if that unit fails. It is
+`PartOf=docker.service`, so restarting Docker (which recreates
+`DOCKER-USER` empty) stops the stack, re-applies the firewall, then starts
+the stack again. `ExecStart` is `docker compose … up -d` and `ExecStop` is
+`docker compose … down`; neither builds, so build before starting.
+
+Containers no longer restart after a crash; `systemctl restart mealquest`
+brings them back.
+
+| Repository file | Installed as |
+| --- | --- |
+| `deploy/systemd/mealquest.service` | `/etc/systemd/system/mealquest.service` (root, 0644) |
+
+Install (done on 10.60.1.14 on 2026-10-05):
+
+```sh
+cd /home/overseer/mealquest
+sudo install -o root -g root -m 0644 deploy/systemd/mealquest.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mealquest
+```
+
+Check:
+
+```sh
+systemctl is-enabled mealquest; systemctl is-active mealquest   # enabled, active
+systemctl show mealquest -p Requires -p After                    # both list mealquest-firewall.service
+```
+
+Start, stop and restart the whole stack with `sudo systemctl start|stop|restart
+mealquest`, never with `docker compose up` or `down`. Per-service compose
+commands (`stop mealquest`, `up -d --force-recreate litestream`) are fine
+while the unit is active, because the firewall is already in place.
+
+## Recipe search (SearXNG)
+
+The `searxng` service in `deploy/compose.yaml` is a private SearXNG
+instance for recipe search. On the compose network it is reachable at
+`http://searxng:8080`; that is the address to configure in the app.
+
+Starting the sidecar does not connect the app to it. The recipe-search
+provider and base URL live in the `recipe_search_settings` row and are set
+through `GET`/`PATCH /api/v1/settings/recipe-search` (the API behind the
+recipe search card on Settings → AI assistant). Until that row exists,
+recipe search answers 409 `not_configured`.
+
+`deploy/compose.yaml` sets `MEALQUEST_SEARXNG_URL=http://searxng:8080`.
+The service only suggests it: `GET` returns it as `default_base_url`, and
+the recipe search card pre-fills the SearXNG URL with it while no URL is
+saved. Nothing is stored until the card is saved, and a saved `base_url`
+always wins. A set value must be an absolute `http://` or `https://` URL
+without credentials, a query or a fragment, or the service refuses to
+start; unset, `default_base_url` is `null`.
+
+To set it up, open Settings → AI assistant, check that the recipe search
+card shows SearXNG with `http://searxng:8080`, select **Save recipe search**
+and then **Test**. Or, from a signed-in session (every non-`GET` request
+needs the `X-MealQuest-CSRF` header set to `csrfToken` from
+`GET /api/v1/me`):
+
+1. `PATCH /api/v1/settings/recipe-search` with
+   `{"provider": "searxng", "base_url": "http://searxng:8080"}`.
+2. `GET /api/v1/settings/recipe-search` shows `"provider": "searxng"` and
+   `"base_url": "http://searxng:8080"`.
+3. `POST /api/v1/settings/recipe-search/test` searches
+   "chicken tikka masala" and must answer 200 with
+   `{"query": "chicken tikka masala", "count": <n>}`. A 502
+   `search_failed` carries SearXNG's error.
+
+| Item | Value |
+| --- | --- |
+| Image | `searxng/searxng:2026.10.4-d48c4b555`, pinned by digest `sha256:76b0bf285aca014c7191fc4d9234c4bfb358624ac33d8883833d496c059ec072` |
+| Settings | `deploy/searxng/settings.yml`, mounted read-only at `/etc/searxng/settings.yml` |
+| Secret | `deploy/secrets/searxng.env` (`SEARXNG_SECRET`), see "Secrets" |
+| Network | `mealquest` only; **no published port** |
+| Health | `wget http://127.0.0.1:8080/healthz` inside the container |
+
+The settings enable the `json` output format, turn off the public limiter
+and bot detection (the only client is the `mealquest` service), and keep
+only the general web search engines DuckDuckGo, Brave, Google, Bing,
+Mojeek and Startpage. Engines that block the host (CAPTCHA, "too many
+requests") are suspended by SearXNG for a while and listed under
+`unresponsive_engines` in the JSON; the others still answer.
+
+Check from inside the app container (the only place it is reachable):
+
+```sh
+docker compose -f deploy/compose.yaml exec mealquest \
+  wget -qO- 'http://searxng:8080/search?q=chicken+tikka+masala+recipe&format=json'
+docker compose -f deploy/compose.yaml port searxng 8080   # prints ":0": nothing published
+```
+
+On 2026-10-06 that query returned 17 results. From this host four of the
+six engines were blocked (Brave, DuckDuckGo, Google and Startpage were
+rate-limited or served a CAPTCHA), so the results came from Bing and
+Mojeek. SearXNG retries suspended engines after their suspension ends, so
+the set that answers can change. From 10.60.1.85 nothing on 10.60.1.14 answered as SearXNG:
+8888 refused the connection and 8080 is NestQuest's API.
+
+For development, `deploy/compose.dev.yaml` publishes SearXNG on the
+dev machine's loopback only (`127.0.0.1:8888`). It is never used on
+office-srvr.
+
+To move to a newer image, pull the new tag, take its digest from
+`docker image inspect --format '{{json .RepoDigests}}' searxng/searxng:<tag>`,
+update both in `deploy/compose.yaml`, then deploy as usual.
+
+## Routine deploy and rollback
+
+Production runs `main` (a release); only `overseer` merges `dev` → `main`.
+Every deploy builds the image on the host from the checked-out commit.
+
+### Deploy
+
+```sh
+cd /home/overseer/mealquest
+git fetch origin
+git rev-parse --short HEAD          # the SHA being replaced: note it for rollback
+git checkout --detach origin/main   # or a release tag
+docker compose -f deploy/compose.yaml build
+sudo systemctl restart mealquest    # applies the firewall, then down + up -d
+docker compose -f deploy/compose.yaml ps   # mealquest healthy, litestream up, searxng healthy
+curl -fsS http://10.60.1.14:8090/health
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+git rev-parse HEAD                  # the deployed SHA
+```
+
+Record the deployed SHA, the previous SHA and the date in the Maestro task
+for the release. Migrations run at start-up; the service refuses to start
+if the database has an applied migration it does not know.
+
+If `deploy/.env.example` gained a variable, add it to `deploy/.env` before
+the restart; the service fails fast at boot naming any missing required variable.
+
+### Rollback to a previous SHA
+
+```sh
+cd /home/overseer/mealquest
+git checkout --detach <previous SHA>
+docker compose -f deploy/compose.yaml build
+sudo systemctl restart mealquest
+docker compose -f deploy/compose.yaml ps
+curl -fsS http://10.60.1.14:8090/health
+```
+
+A rollback across a release that added a migration fails at start-up
+(the older binary refuses the newer schema). In that case restore the
+database to a point before the upgrade — "Restore the database" with
+`-timestamp` set just before the deploy — then start the older SHA.
+Changes made since that point are lost; say so to the household.
+
+## Backups
+
+### Database — Litestream
+
+The `litestream` compose service streams every committed change to
+`mealquest.db` to the NAS over SFTP (`deploy/litestream.yml`). It takes a
+full snapshot daily (compaction level 9) and keeps a week of snapshots
+plus the incremental LTX files between them.
+
+One-time setup (already done on 10.60.1.14):
+
+1. Generate the dedicated keypair, git-ignored, owned by the container
+   user:
+
+   ```sh
+   cd /home/overseer/mealquest
+   ssh-keygen -t ed25519 -N '' -C mealquest-litestream -f deploy/secrets/litestream_key
+   # append deploy/secrets/litestream_key.pub to joshua@10.60.1.50:~/.ssh/authorized_keys
+   rm deploy/secrets/litestream_key.pub
+   sudo chown 10001:10001 deploy/secrets/litestream_key
+   sudo chmod 0600 deploy/secrets/litestream_key
+   ```
+
+2. The NAS host key is pinned in `deploy/litestream.yml` (`host-key`).
+
+Check replication — list every LTX file at every level. Level 9 holds the
+full snapshots; the default listing (`-level 0`) shows only L0 files:
+
+```sh
+docker compose -f deploy/compose.yaml exec -T litestream \
+  litestream ltx -config /etc/litestream.yml -level all /data/mealquest.db
+```
+
+### Media — nightly rsync
+
+`mealquest-media-backup.timer` runs `mealquest-media-backup.service` at
+03:30 every night. The service runs `/usr/local/sbin/mealquest-media-backup`
+(`deploy/systemd/mealquest-media-backup.sh`) as the unprivileged host user
+`mealquest` (uid/gid 10001, the app's own user) with no capabilities.
+systemd bind-mounts the data volume read-only at `/run/mealquest-data` and
+passes the Litestream key in as the credential `nas_key`; uid 10001 cannot
+otherwise reach `/var/lib/docker` or `deploy/secrets/`. The script refuses a
+`media` path that is a symlink and fails (exit 1) if `media` is missing.
+
+One-time setup (already done on 10.60.1.14):
+
+```sh
+cd /home/overseer/mealquest
+# Host user for the backup; ssh needs a passwd entry for its uid.
+sudo groupadd --system --gid 10001 mealquest
+sudo useradd --system --uid 10001 --gid 10001 --no-create-home \
+  --home-dir /nonexistent --shell /usr/sbin/nologin mealquest
+# Pinned NAS host keys, root-owned and world-readable.
+sudo install -d -o root -g root -m 0755 /etc/mealquest
+sudo install -o root -g root -m 0644 deploy/known_hosts /etc/mealquest/known_hosts
+# The media directory; the backup fails if it is ever missing.
+sudo install -d -o 10001 -g 10001 -m 0755 /var/lib/docker/volumes/mealquest-data/_data/media
+# Script and units.
+sudo install -o root -g root -m 0755 deploy/systemd/mealquest-media-backup.sh /usr/local/sbin/mealquest-media-backup
+sudo install -o root -g root -m 0644 deploy/systemd/mealquest-media-backup.service \
+  deploy/systemd/mealquest-media-backup.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mealquest-media-backup.timer
+```
+
+Run it by hand and read the result:
+
+```sh
+sudo systemctl start mealquest-media-backup.service
+journalctl -u mealquest-media-backup --no-pager -n 30
+```
+
+To restore media, follow "Restore photos (media)" — never copy back while
+the timer or the service can still run.
+
+## Restore the database
+
+SQLite in WAL mode keeps recent commits in `mealquest.db-wal`, indexed by
+`mealquest.db-shm`. **A restored database must never sit beside an old WAL
+or shared-memory file**: on open, SQLite would replay the old WAL's pages
+onto the restored database and corrupt it or mix in state from the
+database it replaced. So all three files are moved aside together, with
+Litestream's local state directory `.mealquest.db-litestream`, before the
+restore — and the restore runs into an empty volume.
+
+Run from `/home/overseer/mealquest`:
+
+```sh
+D=/var/lib/docker/volumes/mealquest-data/_data
+A=/var/tmp/mealquest-restore-aside-$(date +%Y%m%d%H%M)
+
+# 1. Stop the whole stack (app and Litestream). Nothing may hold the
+#    database open; a clean close checkpoints the WAL into mealquest.db.
+sudo systemctl stop mealquest
+
+# 2. Move the database, its -wal and -shm files and Litestream's state
+#    aside — all of them, every time. Keep the directory until the
+#    restored stack is verified.
+sudo mkdir "$A"
+for f in mealquest.db mealquest.db-wal mealquest.db-shm .mealquest.db-litestream; do
+  if sudo test -e "$D/$f"; then sudo mv "$D/$f" "$A/"; fi
+done
+sudo ls -la "$D"   # must list only media/
+
+# 3. Restore from the NAS. --no-deps keeps the app stopped so it cannot
+#    create a fresh, empty database first.
+docker compose -f deploy/compose.yaml run --rm --no-deps litestream \
+  restore -config /etc/litestream.yml -o /data/mealquest.db /data/mealquest.db
+sudo ls -la "$D"   # mealquest.db only: no -wal, no -shm
+
+# 4. Check the restored file before starting the app (see "Count check").
+
+# 5. Start the stack and check health.
+sudo systemctl start mealquest
+docker compose -f deploy/compose.yaml ps
+curl -s -o /dev/null -w "health %{http_code}\n" http://10.60.1.14:8090/health
+```
+
+To restore to a point in time, add `-timestamp 2026-10-05T23:00:00Z` (or
+`-txid`) to the `restore` command.
+
+### Count check
+
+`/tmp/mqcount.py` prints row counts for key tables, the number of
+application tables, a SHA-256 over every application row (first 16 hex
+digits; Litestream's own `_litestream*` tables are excluded) and
+`PRAGMA integrity_check`. Run it on a **copy** of the database, never on the
+live file; copy `-wal`/`-shm` along with it when the app is running.
+
+```python
+import sqlite3, sys, hashlib
+c = sqlite3.connect(sys.argv[1])
+tabs = [r[0] for r in c.execute("select name from sqlite_master where type=\"table\" and name not like \"sqlite_%\" and name not like \"_litestream%\" order by name")]
+for t in ("dinners", "week_plans", "schema_migrations"):
+    print(t, c.execute(f"select count(*) from {t}").fetchone()[0])
+h = hashlib.sha256()
+for t in tabs:
+    for row in c.execute(f"select * from \"{t}\" order by rowid"):
+        h.update(repr(row).encode())
+print("tables", len(tabs), "content-sha256", h.hexdigest()[:16])
+print("integrity", c.execute("pragma integrity_check").fetchone()[0])
+```
+
+```sh
+rm -rf /tmp/mqcheck && mkdir /tmp/mqcheck
+sudo sh -c "cp -a $D/mealquest.db* /tmp/mqcheck/" && sudo chown -R "$USER" /tmp/mqcheck
+python3 /tmp/mqcount.py /tmp/mqcheck/mealquest.db
+```
+
+Before and after must match exactly.
+
+## Restore photos (media)
+
+Recipe and dinner photos live in `media/` in the data volume and are
+backed up nightly to `joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/`
+(see "Media — nightly rsync"). The backup service mirrors with
+`rsync --delete`. **An `rsync --delete` run must never see an empty or
+partial `media/`**: it would delete the NAS copy you are about to restore
+from. Stopping the timer is not enough — it does not stop a run that is
+already in flight, and the service can still be started by hand. So stop
+**both** the timer and the service, confirm no rsync is running, and do
+not start the service until the restore is verified.
+
+Run from `/home/overseer/mealquest`:
+
+```sh
+M=/var/lib/docker/volumes/mealquest-data/_data/media
+NAS=/volume1/homes/Joshua/mealquest-backups/media
+SSH="ssh -i deploy/secrets/litestream_key -o IdentitiesOnly=yes -o UserKnownHostsFile=/etc/mealquest/known_hosts -o StrictHostKeyChecking=yes"
+
+# 1. Stop the nightly mirror: the timer AND any run in flight.
+sudo systemctl stop mealquest-media-backup.timer mealquest-media-backup.service
+
+# 2. Pre-check — all three must hold before media/ is touched. If any
+#    fails, stop here and find out why.
+systemctl is-active mealquest-media-backup.timer     # inactive
+systemctl is-active mealquest-media-backup.service   # inactive (or failed)
+pgrep -a -u mealquest rsync || echo "no rsync"       # no rsync
+sudo $SSH joshua@10.60.1.50 "find $NAS -type f | wc -l"
+#    ^ note this NAS file count; it must be non-zero and is the target below.
+
+# 3. Stop the app (no writes into media/ meanwhile).
+docker compose -f deploy/compose.yaml stop mealquest
+
+# 4. Recreate the directory if it is gone, owned by the app user.
+sudo install -d -o 10001 -g 10001 -m 0755 "$M"
+
+# 5. Copy back from the NAS as uid 10001's files. No --delete in this
+#    direction: the NAS copy is the source and is only read.
+sudo rsync -a --stats --chown=10001:10001 -e "$SSH" "joshua@10.60.1.50:$NAS/" "$M/"
+
+# 6. Post-condition — before anything can mirror again:
+sudo find "$M" -type f | wc -l                            # >= the NAS count from step 2
+sudo $SSH joshua@10.60.1.50 "find $NAS -type f | wc -l"   # unchanged from step 2
+
+# 7. Start the app, then the timer again. Only now may the service run.
+docker compose -f deploy/compose.yaml up -d
+curl -fsS http://10.60.1.14:8090/health
+sudo systemctl start mealquest-media-backup.timer
+systemctl is-active mealquest-media-backup.timer          # active
+```
+
+The local count may exceed the NAS count only if `media/` still held
+files the NAS never received (photos added since the last nightly run);
+the next nightly run then copies them up. If the local count is lower,
+the copy did not complete: leave the timer stopped and re-run step 5.
+
+When the database is restored too, restore it first ("Restore the
+database"), then the media, so every photo the database refers to is
+present. This media restore has not been run against production yet; the
+backup direction was checked on 2026-10-05 (see "Media backup checks").
+
+## Restore drill record — 2026-10-05
+
+Drill on 10.60.1.14 against the live (pre-launch, empty-household)
+database, Litestream 0.5.17. Commands as in "Restore the database";
+output trimmed only of compose progress lines.
+
+Replica before the drill (`ltx -level all`; level 9 is the full snapshot):
+
+```
+level  min_txid          max_txid          size   created
+0      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
+1      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+1      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
+2      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+2      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
+3      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+9      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+```
+
+1. `docker compose -f deploy/compose.yaml down` — both containers stopped
+   and removed. The volume then held `mealquest.db`,
+   `.mealquest.db-litestream/` and `media/`; the clean close had
+   checkpointed and removed `-wal` and `-shm`.
+2. Before (copy of the stopped database):
+
+   ```
+   dinners 0
+   week_plans 0
+   schema_migrations 7
+   tables 26 content-sha256 836e230e16c58dc7
+   integrity ok
+   ```
+
+3. Moved aside to `/var/tmp/mealquest-restore-aside-20261005`:
+   `mealquest.db` and `.mealquest.db-litestream` (no `-wal`/`-shm` existed
+   after the clean stop; the loop moves them whenever they do). Volume
+   afterwards: `media/` only.
+4. `docker compose -f deploy/compose.yaml run --rm --no-deps litestream restore -config /etc/litestream.yml -o /data/mealquest.db /data/mealquest.db`
+   — volume afterwards: `mealquest.db` (258048 bytes) and `media/`; no
+   `-wal`, no `-shm`.
+5. After (copy of the restored file, before the app started):
+
+   ```
+   dinners 0
+   week_plans 0
+   schema_migrations 7
+   tables 26 content-sha256 836e230e16c58dc7
+   integrity ok
+   ```
+
+6. `docker compose -f deploy/compose.yaml up -d` — `mealquest-mealquest-1`
+   healthy, `mealquest-litestream-1` up; `GET /health` → `200`. Counts on a
+   copy of the running database (`mealquest.db`, `-wal`, `-shm`) were
+   identical to the above.
+7. Litestream resumed against the restored database:
+
+   ```
+   level=INFO msg="detected database behind replica" db=mealquest.db db_txid=0000000000000000 replica_txid=0000000000000003
+   level=INFO msg="fetched latest L0 file from replica" db=mealquest.db min_txid=0000000000000003 max_txid=0000000000000003
+   level=INFO msg="compaction complete" db=mealquest.db level=1 txid.min=0000000000000004 txid.max=0000000000000004 size=14110
+   ```
+
+   Replica after the drill (`ltx -level all`):
+
+   ```
+   level  min_txid          max_txid          size   created
+   0      0000000000000004  0000000000000004  14110  2026-10-05T23:27:21Z
+   1      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+   1      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
+   1      0000000000000004  0000000000000004  14110  2026-10-05T23:27:21Z
+   2      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+   2      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
+   3      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+   9      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
+   ```
+
+The first drill earlier the same day (before `-level all` was recorded)
+gave the same before/after result: checksum `836e230e16c58dc7`, 26 tables,
+integrity ok.
+
+### Media backup checks — 2026-10-05
+
+`sudo systemctl start mealquest-media-backup.service` on 10.60.1.14:
+
+| Case | Result |
+| --- | --- |
+| Normal run | `Result=success`; journal: `synced /run/mealquest-data/media to joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/ as uid 10001` |
+| A test file added | `Number of regular files transferred: 1`; removing it then gave `Number of deleted files: 1 (reg: 1)` |
+| `media` replaced by a symlink to `/etc` | `Result=exit-code`, status 1; `/run/mealquest-data/media is a symlink to /etc; refusing to back it up` |
+| `media` removed | `Result=exit-code`, status 1; `media directory /run/mealquest-data/media is missing` |
+| `sudo -u mealquest` writing into the volume via `/var/lib/docker/...` | `Permission denied` — uid 10001 cannot traverse `/var/lib/docker` (mode 0710 root) |
+
+## Secret rotation
+
+Rotate a secret when it may have leaked, when someone with access leaves,
+or on the owner's schedule. Never paste a secret into a ticket, chat or
+this file.
+
+### App key (`deploy/secrets/secret_key`)
+
+The app key encrypts every stored secret: the `_ct` columns
+`ai_settings.api_key_ct` (LLM API key), `recipe_search_settings.api_key_ct`
+(recipe-search API key), `integrations_google.refresh_token_ct` (Google
+Calendar refresh token) and `chat_settings.webhook_url_ct` (Google Chat
+webhook URL). **Rotating it re-encrypts nothing**: a value encrypted with
+the old key can no longer be read. A `mealquest rotate-key` helper that
+re-encrypts in place is planned but does not exist yet.
+
+**What is recoverable today.** The service currently exposes only
+household settings; no shipped flow writes or re-enters any of these four
+secrets. The re-entry flows are planned: the LLM key in Settings → AI
+assistant (the AI settings feature), the recipe-search key (Feature 10),
+Google Calendar reconnect (Feature 16) and the Google Chat webhook
+(Feature 19). So today the rotation is safe **only if no `_ct` value is
+stored**, which the pre-check below proves. If the pre-check finds a
+stored value, do not rotate: it could not be re-entered afterwards. Keep
+the current key and wait for the matching flow (or the `rotate-key`
+helper).
+
+**The pre-check and the key replacement run with the whole stack
+stopped**, from the pre-check until the new key is in place. A raw copy of
+`mealquest.db` and `mealquest.db-wal` taken while the stack runs is **not**
+a consistent snapshot: the two files are copied one after the other, and a
+checkpoint (by the app or by Litestream) between the two copies can move
+committed pages out of the WAL into `mealquest.db` after `mealquest.db` was
+already copied, then reset the WAL before it is copied. The copy then
+lacks those commits — possibly a stored `_ct` value — and the pre-check
+reports a false 0. A running app could also store a `_ct` value after a
+correct pre-check and before the key is replaced. Stopping both containers
+removes every writer (Litestream also writes and checkpoints), and the
+clean close checkpoints the WAL into `mealquest.db`, so the file alone is
+complete.
+
+Run from `/home/overseer/mealquest`:
+
+```sh
+D=/var/lib/docker/volumes/mealquest-data/_data
+
+# 1. Stop the whole stack (app and Litestream) and leave it stopped until
+#    step 4. Nothing may hold the database open.
+sudo systemctl stop mealquest
+sudo ls -la "$D"   # mealquest.db and media/ only: no -wal, no -shm; if
+                   # either exists, the close was not clean — stop here
+
+# 2. Pre-check, on a copy of the now-quiescent database.
+rm -rf /tmp/mqcheck && mkdir /tmp/mqcheck
+sudo cp -a "$D/mealquest.db" /tmp/mqcheck/ && sudo chown -R "$USER" /tmp/mqcheck
+python3 - /tmp/mqcheck/mealquest.db <<'PY'
+import sqlite3, sys
+c = sqlite3.connect(sys.argv[1])
+for t, col in (("ai_settings", "api_key_ct"), ("recipe_search_settings", "api_key_ct"),
+               ("integrations_google", "refresh_token_ct"), ("chat_settings", "webhook_url_ct")):
+    print(t, col, c.execute(f"select count(*) from {t} where {col} is not null").fetchone()[0])
+PY
+rm -rf /tmp/mqcheck
+# every count must be 0; otherwise start the stack again on the current
+# key (sudo systemctl start mealquest) and stop here
+
+# 3. Replace the key, still with the stack stopped.
+sudo cp -a deploy/secrets/secret_key /var/tmp/secret_key.old   # keep until verified, then shred
+head -c 32 /dev/urandom | base64 | sudo tee deploy/secrets/secret_key >/dev/null
+sudo chown 10001:10001 deploy/secrets/secret_key
+sudo chmod 600 deploy/secrets/secret_key
+
+# 4. Start the stack on the new key and check health.
+sudo systemctl start mealquest
+docker compose -f deploy/compose.yaml ps
+curl -fsS http://10.60.1.14:8090/health
+```
+
+Then sign in and open household settings to confirm the service runs on
+the new key. Finally `sudo shred -u /var/tmp/secret_key.old`. Once the
+planned flows ship, this section gains a step per secret to re-enter it
+and confirm it works.
+
+### OIDC client secret (`deploy/secrets/oidc_client_secret`)
+
+In Authentik, open the provider `mealquest` and regenerate the Client
+Secret. Write it to the file (same owner and mode as above) and recreate
+the service:
+
+```sh
+printf '%s\n' '<new Authentik client secret>' | sudo tee deploy/secrets/oidc_client_secret >/dev/null
+sudo chown 10001:10001 deploy/secrets/oidc_client_secret
+sudo chmod 600 deploy/secrets/oidc_client_secret
+docker compose -f deploy/compose.yaml up -d --force-recreate mealquest
+```
+
+Sign in at <https://mealquest.cubecraftlabs.com> to confirm; sign-ins
+fail between regenerating the secret in Authentik and recreating the
+service.
+
+### LLM API key
+
+Stored encrypted in the database, not in `deploy/`. In the app, open
+**Settings → AI assistant**, choose **Replace**, paste the new key and
+**Verify**, and check the verified state is shown. Then revoke the
+old key in the provider's console. (The AI assistant settings page is
+delivered by its own feature; until it ships there is no stored LLM key
+to rotate.)
+
+### VAPID keys (Web Push)
+
+Planned with Web Push (Feature 19): the public key goes in
+`deploy/.env` as `MEALQUEST_VAPID_PUBLIC_KEY`, the private key in
+`deploy/secrets/vapid_private_key` (owner `10001:10001`, mode 0600), and
+the pair is generated with `cmd/vapidgen`. **Changing the VAPID pair
+invalidates every push subscription**: each device must turn
+notifications on again (`/settings/notifications`) before it receives
+pushes. Rotate only when the private key may have leaked, write both
+halves, recreate the service with `--force-recreate mealquest`, and tell
+the household to re-enable notifications on each device.
+
+### SearXNG secret (`deploy/secrets/searxng.env`)
+
+Only signs SearXNG's own cookies and image-proxy links; nothing stored
+depends on it. Replace it and recreate the service:
+
+```sh
+(umask 077; printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > deploy/secrets/searxng.env)
+docker compose -f deploy/compose.yaml up -d --force-recreate searxng
+docker compose -f deploy/compose.yaml ps searxng   # healthy
+```
+
+### Litestream / NAS key (`deploy/secrets/litestream_key`)
+
+Generate a new keypair as in "Database — Litestream", add the new public
+key to `joshua@10.60.1.50:~/.ssh/authorized_keys`, replace the file
+(owner `10001:10001`, mode 0600), run
+`docker compose -f deploy/compose.yaml up -d --force-recreate litestream`
+and `sudo systemctl start mealquest-media-backup.service`, check both
+(`litestream ltx` and the journal), then remove the old public key from
+the NAS.
+
+## Context records
+
+The confirmed values in this runbook (port 8090, checkout path, Authentik
+group `mealquest-admin`, DNS, firewall, backup target) are also recorded in
+the CTXD project `mealquest`: `RUNBOOKS.MD` (deployment procedure) and the
+open questions in `CONTEXT.MD`, updated for Feature 07 task 876134bc.

deploy/compose.dev.yaml

@@ -0,0 +1,12 @@
+# Development override: publishes SearXNG on the dev machine's loopback so
+# it can be queried directly, e.g.
+#
+#   docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml up -d searxng
+#   curl 'http://127.0.0.1:8888/search?q=chicken+tikka+masala+recipe&format=json'
+#
+# Loopback only, never a LAN address. Never used in production: the
+# systemd unit starts deploy/compose.yaml alone.
+services:
+  searxng:
+    ports:
+      - "127.0.0.1:8888:8080"

deploy/compose.yaml

@@ -0,0 +1,138 @@
+# Production stack for MealQuest on 10.60.1.14 (D-018). Build on the host,
+# then start through systemd:
+#
+#   docker compose -f deploy/compose.yaml build
+#   sudo systemctl restart mealquest
+#
+# The services use restart: "no" on purpose: Docker must not start them
+# before the DOCKER-USER firewall is applied. deploy/systemd/mealquest.service
+# owns start and stop and requires mealquest-firewall.service first.
+#
+# Configuration comes from deploy/.env (copy deploy/.env.example) and secrets
+# from deploy/secrets/; neither is committed. Compose bind-mounts file secrets
+# with their host owner and mode, so each file in deploy/secrets/ must be
+# owned by the container user 10001:10001 with mode 0600 (except
+# searxng.env, read by compose itself; see the searxng service).
+name: mealquest
+
+services:
+  mealquest:
+    build:
+      context: ..
+      dockerfile: Dockerfile
+    user: "10001:10001"
+    restart: "no"
+    env_file:
+      - path: .env
+        required: true
+    # Fixed by this file's container shape (listen port, volume, secret
+    # mounts); deploy/.env must not set them.
+    environment:
+      MEALQUEST_HTTP_ADDR: ":8080"
+      MEALQUEST_DATA_DIR: /data
+      MEALQUEST_SECRET_KEY_FILE: /run/secrets/secret_key
+      MEALQUEST_OIDC_CLIENT_SECRET_FILE: /run/secrets/oidc_client_secret
+      MEALQUEST_SEARXNG_URL: http://searxng:8080
+    secrets:
+      - secret_key
+      - oidc_client_secret
+    volumes:
+      - mealquest-data:/data
+    ports:
+      - "${MEALQUEST_BIND_ADDRESS:?set MEALQUEST_BIND_ADDRESS in deploy/.env}:8090:8080"
+    networks:
+      - mealquest
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 10s
+      retries: 3
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+
+  # Litestream streams the database to the Synology NAS over SFTP
+  # (config: deploy/litestream.yml). The SFTP private key
+  # deploy/secrets/litestream_key is a dedicated keypair, owned by
+  # 10001:10001 with mode 0600 like the other secrets.
+  #
+  # The data volume is mounted read-write on purpose: Litestream writes its
+  # tracking tables into the database and checkpoints the WAL. It runs as
+  # the app's own user (owner of the volume) with a read-only root
+  # filesystem, no privilege escalation and no Linux capabilities.
+  #
+  # Restore: follow "Restore the database" in deploy/RUNBOOK.md (stop the
+  # stack, move the database with its -wal and -shm aside, restore, check).
+  litestream:
+    image: litestream/litestream:0.5.17
+    user: "10001:10001"
+    restart: "no"
+    command: ["replicate", "-config", "/etc/litestream.yml"]
+    depends_on:
+      mealquest:
+        condition: service_healthy
+    volumes:
+      - mealquest-data:/data
+      - ./litestream.yml:/etc/litestream.yml:ro
+      - ./secrets/litestream_key:/etc/litestream/sftp_key:ro
+    networks:
+      - mealquest
+    read_only: true
+    tmpfs:
+      - /tmp
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+
+  # SearXNG, the recipe-search sidecar (Feature 10; settings:
+  # deploy/searxng/settings.yml). It sits on the mealquest network only and
+  # publishes no port: the mealquest service reaches it at
+  # http://searxng:8080 and nothing outside the compose network can.
+  # deploy/compose.dev.yaml publishes it on 127.0.0.1 for development.
+  #
+  # The secret key comes from deploy/secrets/searxng.env as SEARXNG_SECRET.
+  # Compose itself reads that file (it is not mounted), so unlike the other
+  # secrets it is owned by overseer, mode 0600. It runs as the image's
+  # searxng user (977) with a read-only root filesystem.
+  searxng:
+    image: searxng/searxng:2026.10.4-d48c4b555@sha256:76b0bf285aca014c7191fc4d9234c4bfb358624ac33d8883833d496c059ec072
+    user: "977:977"
+    restart: "no"
+    env_file:
+      - path: ./secrets/searxng.env
+        required: true
+    volumes:
+      - ./searxng/settings.yml:/etc/searxng/settings.yml:ro
+    networks:
+      - mealquest
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 3s
+      start_period: 15s
+      retries: 3
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /var/cache/searxng:uid=977,gid=977
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+
+secrets:
+  secret_key:
+    file: ./secrets/secret_key
+  oidc_client_secret:
+    file: ./secrets/oidc_client_secret
+
+volumes:
+  mealquest-data:
+    name: mealquest-data
+
+networks:
+  mealquest:
+    name: mealquest

deploy/known_hosts

@@ -0,0 +1,6 @@
+# Host keys of the Synology NAS (10.60.1.50), the backup target. Installed
+# root-owned with mode 0644 as /etc/mealquest/known_hosts and pinned by the
+# media backup (UserKnownHostsFile, StrictHostKeyChecking=yes). The ECDSA
+# key is also pinned in deploy/litestream.yml (host-key).
+10.60.1.50 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHxIfgjavBABMRE5GW/EFY4C4gO6mo0sKbhkUW2NcAo
+10.60.1.50 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNujay9nYEiXuRQf4wDRDU1gp+CDvpeMdhuhC2XypIihzKGEtB654kwrUGfA2kDWAoSPGlmojeS3OIRtHPkj6GY=

deploy/litestream.yml

@@ -0,0 +1,31 @@
+# Litestream continuous backup of the MealQuest SQLite database (Feature
+# 07). The ``litestream`` compose service mounts the same named volume as
+# the app and streams every committed change to the Synology NAS over
+# SFTP, so the backup lives outside the Docker host.
+#
+# Nothing here is secret. The SFTP private key is a dedicated, git-ignored
+# keypair (deploy/secrets/litestream_key) mounted read-only by compose at
+# /etc/litestream/sftp_key; its public half is in
+# joshua@10.60.1.50:~/.ssh/authorized_keys. ``host-key`` pins the NAS's
+# ECDSA host key, the algorithm Litestream's SSH client negotiates with
+# this NAS.
+#
+# The Synology SFTP server is chrooted to the shared folders, so the
+# directory seen over SSH as /volume1/homes/Joshua/mealquest-backups is
+# /homes/Joshua/mealquest-backups over SFTP.
+
+# Take a full snapshot daily and keep a week of snapshots plus the
+# incremental changes between them (point-in-time restore window).
+snapshot:
+  interval: 24h
+  retention: 168h
+
+dbs:
+  - path: /data/mealquest.db
+    replicas:
+      - type: sftp
+        host: 10.60.1.50
+        user: joshua
+        path: /homes/Joshua/mealquest-backups
+        key-path: /etc/litestream/sftp_key
+        host-key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNujay9nYEiXuRQf4wDRDU1gp+CDvpeMdhuhC2XypIihzKGEtB654kwrUGfA2kDWAoSPGlmojeS3OIRtHPkj6GY=

deploy/searxng/settings.yml

@@ -0,0 +1,61 @@
+# SearXNG settings for the MealQuest recipe-search sidecar (Feature 10).
+# Mounted read-only at /etc/searxng/settings.yml by deploy/compose.yaml.
+#
+# Internal use only: SearXNG is reachable on the compose network
+# `mealquest` and nowhere else, and its only client is the mealquest
+# service. That is why the public limiter and bot detection are off.
+#
+# The secret key is not in this file. SearXNG reads it from SEARXNG_SECRET,
+# set from deploy/secrets/searxng.env (never committed). Without it the
+# default "ultrasecretkey" stays in place and SearXNG refuses to start.
+#
+# Settings reference: https://docs.searxng.org/admin/settings/
+
+use_default_settings:
+  engines:
+    # General web search engines only; every other default engine is
+    # dropped.
+    keep_only:
+      - duckduckgo
+      - brave
+      - google
+      - bing
+      - mojeek
+      - startpage
+
+general:
+  instance_name: MealQuest search
+
+server:
+  # Internal use: no public limiter and no bot detection.
+  limiter: false
+  public_instance: false
+  image_proxy: false
+
+search:
+  safe_search: 0
+  # No autocomplete: the mealquest service never asks for suggestions.
+  autocomplete: ""
+  # json is the format the mealquest service reads; html stays for
+  # debugging through deploy/compose.dev.yaml.
+  formats:
+    - html
+    - json
+
+# Some general web engines are disabled or inactive by default; enable all
+# of the kept ones.
+engines:
+  - name: duckduckgo
+    disabled: false
+  - name: brave
+    disabled: false
+  - name: google
+    disabled: false
+  - name: bing
+    disabled: false
+  - name: mojeek
+    disabled: false
+    inactive: false
+  - name: startpage
+    disabled: false
+    inactive: false

deploy/systemd/mealquest-firewall.service

@@ -0,0 +1,22 @@
+# Applies the MealQuest DOCKER-USER rules (/usr/local/sbin/mealquest-firewall).
+#
+# PartOf= re-runs this unit whenever docker.service is stopped or restarted,
+# and WantedBy=docker.service starts it whenever docker.service starts. Both
+# are one-way: a failure here fails this unit visibly and never fails
+# docker.service.
+#
+# Start MealQuest only after this unit has succeeded:
+#   systemctl start mealquest-firewall && docker compose up -d
+[Unit]
+Description=Restrict MealQuest port 8090 to Traefik (DOCKER-USER)
+After=docker.service
+Requires=docker.service
+PartOf=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/mealquest-firewall
+
+[Install]
+WantedBy=multi-user.target docker.service

deploy/systemd/mealquest-firewall.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Restrict the MealQuest published host port (10.60.1.14:8090) to Traefik
+# (10.60.1.33) and the Docker host itself (10.60.1.14); drop every other
+# source.
+#
+# DOCKER-USER runs after Docker's DNAT, so the destination there is the
+# container address and port, not the published ones. Match the original
+# destination address and port with conntrack instead of -d/--dport.
+#
+# The rules must sit at the top of DOCKER-USER, ahead of any other project's
+# rules (an earlier RETURN or DROP would decide MealQuest traffic first).
+# The port is never left open while the rules are updated:
+#
+#   1. If the chain already starts with exactly the three rules below and
+#      holds no other mealquest-firewall rule, change nothing.
+#   2. Otherwise insert the DROP at position 1 first, so the port is closed
+#      to every source (including Traefik, briefly) from here on.
+#   3. Delete every other rule tagged mealquest-firewall, by rule number,
+#      highest first.
+#   4. Insert the two RETURN rules above the DROP.
+#
+# Re-runs leave the same ordered rules at positions 1-3 and no duplicates.
+# Installed as /usr/local/sbin/mealquest-firewall.
+set -eu
+
+chain=DOCKER-USER
+tag="-m comment --comment mealquest-firewall"
+match="-m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL"
+
+# The three rules as iptables -S prints them, in their required order.
+want="-A $chain -s 10.60.1.33/32 $match $tag -j RETURN
+-A $chain -s 10.60.1.14/32 $match $tag -j RETURN
+-A $chain $match $tag -j DROP"
+
+rules=$(iptables -w -S "$chain" | grep -e '^-A ' || true)
+head=$(printf '%s\n' "$rules" | head -n 3)
+tagged=$(printf '%s\n' "$rules" | grep -c -e '--comment mealquest-firewall ' || true)
+if [ "$head" = "$want" ] && [ "$tagged" -eq 3 ]; then
+	exit 0
+fi
+
+iptables -w -I "$chain" 1 $match $tag -j DROP
+
+iptables -w -S "$chain" | grep -e '^-A ' |
+	awk '/--comment mealquest-firewall / { print NR }' |
+	sort -rn | while read -r num; do
+	if [ "$num" -ne 1 ]; then
+		iptables -w -D "$chain" "$num"
+	fi
+done
+
+iptables -w -I "$chain" 1 -s 10.60.1.14/32 $match $tag -j RETURN
+iptables -w -I "$chain" 1 -s 10.60.1.33/32 $match $tag -j RETURN

deploy/systemd/mealquest-media-backup.service

@@ -0,0 +1,29 @@
+# Runs the nightly MealQuest media backup (/usr/local/sbin/mealquest-media-backup).
+# Triggered by mealquest-media-backup.timer; run by hand with
+#   systemctl start mealquest-media-backup
+# and read the result with
+#   journalctl -u mealquest-media-backup
+#
+# The script runs as the app's user (10001, host user "mealquest") with no
+# capabilities. systemd, as root, only bind-mounts the data volume's root
+# (a root-owned path the app cannot replace) read-only at
+# /run/mealquest-data and copies the NAS key into the credentials directory.
+[Unit]
+Description=Back up MealQuest media to the Synology NAS
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/mealquest-media-backup
+User=mealquest
+Group=mealquest
+LoadCredential=nas_key:/home/overseer/mealquest/deploy/secrets/litestream_key
+BindReadOnlyPaths=/var/lib/docker/volumes/mealquest-data/_data:/run/mealquest-data
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+PrivateDevices=yes
+NoNewPrivileges=yes
+CapabilityBoundingSet=
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX

deploy/systemd/mealquest-media-backup.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+# Nightly copy of the MealQuest media directory (recipe and dinner photos)
+# to the Synology NAS. The database itself is replicated continuously by
+# Litestream; this covers the files beside it.
+#
+# Runs as the unprivileged app user (10001, host user "mealquest"), never
+# root: mealquest-media-backup.service bind-mounts the data volume
+# read-only at /run/mealquest-data and hands the NAS key in as a systemd
+# credential. Anything the app could plant in the volume is therefore read
+# with the app's own permissions only.
+#
+# The script changes into the media directory and checks that the physical
+# path is the expected one, so a media path that is a symlink is refused.
+# rsync then copies "./" — the directory the shell is already in — so
+# swapping the path afterwards cannot redirect it. Symlinks inside the
+# directory are copied as links (-a), never followed.
+#
+# The media directory is created at deploy time (deploy/RUNBOOK.md). If it
+# is missing the job fails; it is never treated as "nothing to back up".
+#
+# rsync mirrors into .../mealquest-backups/media/ only: the target ends in
+# a slash, so --delete removes files from that directory and nothing
+# outside it. Re-runs transfer only what changed. Output goes to the
+# journal via mealquest-media-backup.service.
+set -eu
+
+src=/run/mealquest-data/media
+dest=joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/
+key=$CREDENTIALS_DIRECTORY/nas_key
+known_hosts=/etc/mealquest/known_hosts
+
+if ! cd "$src"; then
+	echo "mealquest-media-backup: media directory $src is missing" >&2
+	exit 1
+fi
+if [ "$(pwd -P)" != "$src" ]; then
+	echo "mealquest-media-backup: $src is a symlink to $(pwd -P); refusing to back it up" >&2
+	exit 1
+fi
+
+rsync -a --delete --stats \
+	-e "ssh -F none -i $key -o IdentitiesOnly=yes -o BatchMode=yes -o UserKnownHostsFile=$known_hosts -o GlobalKnownHostsFile=/dev/null -o StrictHostKeyChecking=yes" \
+	./ "$dest"
+echo "mealquest-media-backup: synced $src to $dest as uid $(id -u)"

deploy/systemd/mealquest-media-backup.timer

@@ -0,0 +1,11 @@
+# Nightly trigger for mealquest-media-backup.service. Persistent= runs a
+# missed backup at the next boot.
+[Unit]
+Description=Nightly MealQuest media backup
+
+[Timer]
+OnCalendar=*-*-* 03:30:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target

deploy/systemd/mealquest.service

@@ -0,0 +1,22 @@
+# Owns the MealQuest compose stack (deploy/compose.yaml). The services use
+# restart: "no", so Docker never starts them on its own; this unit is the
+# only start path.
+#
+# Requires= and After=mealquest-firewall.service start the stack only after
+# the DOCKER-USER rules are applied, and not at all if that unit fails.
+# PartOf=docker.service propagates a Docker stop or restart here, so a
+# Docker restart re-applies the firewall before the stack comes back.
+[Unit]
+Description=MealQuest compose stack
+Requires=mealquest-firewall.service
+After=mealquest-firewall.service docker.service
+PartOf=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/bin/docker compose -f /home/overseer/mealquest/deploy/compose.yaml up -d
+ExecStop=/usr/bin/docker compose -f /home/overseer/mealquest/deploy/compose.yaml down
+
+[Install]
+WantedBy=multi-user.target

docs/ARCHITECTURE.md

@@ -92,11 +92,11 @@ Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
 | Table | Holds |
 | --- | --- |
 | `household_settings` | One row: timezone, dinner_time (17:30), reminder_time (16:30), review_time (09:00), plan_draft day/time (Fri 09:00), suggestions day/time (Sun 08:00), chat_autosend day/time (Sat 08:00), onboarding_completed_at, updates_seen_at. |
-| `recipes` | A real recipe page: source_url (unique), site_name, title, total/prep/cook minutes, yield, raw_jsonld, fetched_at. |
+| `recipes` | A real recipe page: source_url (unique), site_name, title, total/prep/cook minutes (the page's JSON-LD), yield, raw_jsonld, fetched_at; and its grounding: photo_id, method, difficulty, minutes_total (normalized prep to table). |
 | `recipe_ingredients` | recipe_id, position, raw_text, name, qty, unit, note. |
 | `recipe_steps` | recipe_id, position, text. |
 | `photos` | source_url, local_path, width, height, sha256, fetched_at. |
-| `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by. |
+| `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, recipe_url (a pasted recipe link awaiting grounding), photo_id, grounding_status (`pending` / `grounded` / `failed` / `manual`), grounding_error (why grounding failed), grounding_revision (raised whenever a dinner is renamed, so only the latest `ground_dinner` job may write it and no candidate offered before the rename grounds it), updated_by. |
 | `suggestion_batches` | trigger, status, ai_run_id. |
 | `suggestions` | dinner_id, batch_id, reason, cited_regular_ids (JSON), status, decided_at. |
 | `week_plans` | week_start (unique), status (`draft` / `synced` / `changed`), ai_note, ai_run_id, calendar_synced_at. |
@@ -105,7 +105,7 @@ Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
 | `shopping_lists` | week_start (unique), plan_id, title, status (`current` / `archived`), sent_to_chat_at, frozen_at. |
 | `shopping_groups` / `shopping_items` | One group per dinner/day; item name, qty, needed (bool), position. |
 | `ai_settings` | One row: provider, base_url, model, temperature, system_prompt, api_key_ct, api_key_last4, key_verified_at. |
-| `recipe_search_settings` | One row: provider (`searxng` / `brave`), base_url, api_key_ct. |
+| `recipe_search_settings` | One row: provider (`searxng` / `brave`), base_url (the SearXNG instance), api_key_ct and api_key_last4 (Brave). |
 | `integrations_google` | One row: refresh_token_ct, calendar_id, calendar_name, connected_at, last_sync_error. |
 | `chat_settings` | One row: webhook_url_ct, space_label, last_test_at, last_test_status. |
 | `notification_prefs` | event (`plan_ready` / `list_ready` / `day_of_reminder` / `new_suggestions` / `rotation_review`), push, chat. |
@@ -145,6 +145,132 @@ automatic** (D-021).
   with a `photos` row, with
   `Cache-Control: private, max-age=31536000, immutable`; anything else is
   404.
+- `GET`/`PATCH /api/v1/settings/recipe-search` — provider, base_url and
+  the Brave key (`api_key`, write-only: responses carry only
+  `api_key_set` and `api_key_last4`; an empty string removes it). The
+  result must be usable: SearXNG needs a base_url, Brave a key.
+  Responses also carry the read-only `default_base_url`, the deployment's
+  `MEALQUEST_SEARXNG_URL` (or null), which the client pre-fills while no
+  base_url is saved; only a PATCH of base_url stores a URL.
+  `POST /api/v1/settings/recipe-search/test` searches "chicken tikka
+  masala" and returns `{query, count}`, 409 `not_configured`, or 502
+  `search_failed` with the provider's error.
+- `GET`/`PATCH /api/v1/settings/ai` (`aisettings.Service`) — provider,
+  base_url, model, temperature, system_prompt, plus the read-only
+  `api_key_last4` and `key_verified_at`. PATCH requires a preset name as
+  provider, temperature 0–1 in 0.1 steps, a non-empty model and a
+  system_prompt of at most 8000 characters; a fixed-URL preset's base_url
+  must be empty or its own. Provider and base_url cannot change while a
+  key is stored (remove the key first), so a stored key is never sent to
+  an endpoint it was not stored for.
+  `PUT /api/v1/settings/ai/api-key` takes `{api_key}` (write-only, at least
+  8 characters, sealed with the secret box; an empty string removes it) and
+  clears `key_verified_at`; a preset without a fixed base_url takes a key
+  only when its base_url passes `secureurl.Check`. `POST /api/v1/settings/ai/verify` calls
+  `Provider.Verify` and records `key_verified_at`;
+  `GET /api/v1/settings/ai/models` returns `{models: [{id, display_name}]}`
+  live from the provider, with the key redacted from every id and
+  display_name. Both work before a model is chosen
+  (`presets.ForAccount`), answer 409 `not_configured` when the settings
+  cannot build a provider, and 502 with the provider's typed error
+  (`auth_failed`, `rate_limited`, `bad_output`, `provider_error`; 504
+  `timeout`) when the call fails. `POST /api/v1/settings/ai/reset-prompt`
+  restores `household.DefaultPersonaPrompt` (CTXD PROMPTS.MD §4). No
+  response holds the key. `Service.HarnessConfig` reads the settings for
+  each skill run, so a saved change applies to the next run.
+- Dinners (`dinners.Service`). `POST /api/v1/dinners` adds a Regular from
+  `{name}` or `{name, recipe_url}` (an https:// link, kept in
+  `recipe_url` for grounding and never returned in a dinner response, as
+  it may carry a personal token) with status and origin `regular` and
+  grounding_status `pending`, answering 201 with the dinner. The name is
+  always the household's: no part of a link is ever used as a dinner's
+  name, and a link without a name is 400. A name
+  is trimmed, at most 120 characters and must keep a word after
+  `harness.Normalize`, which sets `normalized_name`. A name
+  `harness.Similar` to an unarchived dinner's, or a link one already has
+  (the source_url of the recipe it is grounded in, else its pasted
+  `recipe_url`), is 409 `duplicate_dinner`; archived names may be added
+  again.
+  `GET /api/v1/dinners?status=regular|quest_log` returns
+  `{dinners: [...]}` ordered by normalized name, each with `photo_url`
+  (`/media/photos/{photo_id}-400.jpg`, or null) and `grounding_status`;
+  any other status is 400. `PATCH /api/v1/dinners/{id}` edits `name`
+  (deduplicated against the other unarchived dinners), `method`
+  (`stovetop` / `oven` / `crockpot` / `grill` / `other`), `minutes_total`
+  (1–1440) and `difficulty` (`easy` / `medium` / `hard`); invalid values
+  are 400 `invalid_dinner` and change nothing. `DELETE /api/v1/dinners/{id}`
+  sets status `archived` and keeps the row; `POST
+  /api/v1/dinners/{id}/favorite` toggles `is_favorite`. Every write records
+  the session's subject as `updated_by`; an unknown id is 404.
+- Dinner grounding. `POST /api/v1/dinners` also enqueues a `ground_dinner`
+  job and answers with its `grounding_job_id` without waiting for it
+  (`GET /api/v1/jobs/{id}` reports it); if the job cannot be enqueued it
+  still answers 201, with grounding_status `failed` (`grounding_error`)
+  and `grounding_job_id` null. The job grounds the dinner's
+  `recipe_url` directly with `GroundURL`, else its name with `Ground`
+  (see Recipe grounding), and sets grounding_status `grounded` with the
+  recipe's recipe_id, photo_id, method, minutes_total and difficulty,
+  clearing the pasted `recipe_url` (the recipe replaces it), or
+  `failed` with `grounding_error` — also the job's failure code — one of
+  `no_recipe_found`, `recipe_unusable` (the pasted link), `search_not_configured`,
+  `search_failed`, `ai_failed`, `interrupted` (the server stopped) or
+  `grounding_error`. Each job carries the dinner's `grounding_revision`
+  from when it was enqueued; renaming a dinner raises the revision, and
+  renaming a `pending` one enqueues a job for the new name, clearing its
+  `recipe_url` when the normalized name changes.
+  A job for a dinner archived, no longer `pending` or at another revision
+  does no work, and a job only writes a dinner still unarchived, `pending`
+  and at its revision, so a fix-up made meanwhile wins and an earlier job
+  for an old name — queued or running — never decides the outcome.
+  Archiving or renaming a dinner also stops its running job where it is,
+  so no further search, page fetch, photo download or model call is made
+  for it. A
+  method, minutes_total or difficulty a member saved while the dinner was
+  `pending` is kept; grounding fills only those left empty. At boot, after
+  the job runner fails the jobs a previous process left running, every
+  unarchived dinner still `pending` with no `ground_dinner` job for its revision
+  queued or running is set `failed` with `interrupted`, so no dinner stays
+  pending with nothing left to ground it.
+  `GET /api/v1/dinners/{id}/recipe-candidates`
+  searches for the dinner's name and returns `{candidates: [{candidate_id,
+  title, site_name, photo_url, minutes}]}`, at most 3, ranked as `Ground`
+  ranks them; it fetches pages but downloads no photo and runs no model,
+  so `photo_url` is set only for a page already stored. `candidate_id` is
+  an opaque id the server resolves to the page it last offered that dinner
+  (kept in memory, so a restart means fetching the candidates again) at
+  the `grounding_revision` it was searched at, so a candidate offered
+  before any rename is refused even if the name is changed back; the
+  page's URL, which may carry a token, is never returned or cached. An
+  unknown dinner is 404, recipe search not set up 409 `not_configured` and
+  a search failure 502 `search_failed`; any other failure, such as a
+  stored recipe that cannot be read, is 500, logged with a fixed reason
+  and the dinner id only — never a candidate's URL or dependency error
+  text.
+  `POST /api/v1/dinners/{id}/ground` takes exactly one of `{candidate_id}`,
+  `{recipe_url}` (both grounded with `GroundURL`, setting `grounded`) or `{manual: {ingredients[], steps[], minutes,
+  method}}` (1–100 ingredient lines, up to 100 steps, each non-blank and at
+  most 500 characters; minutes 1–1440). A manual recipe is stored as typed
+  — no model runs — as a `recipes` row whose source_url is
+  `mealquest:manual:{recipe_id}` and whose raw_jsonld is a schema.org
+  Recipe built from it, and sets `manual` with its method and minutes, no
+  photo and the dinner's difficulty unchanged. Either clears the dinner's
+  pasted `recipe_url`: the recipe chosen replaces it. It answers 200 with
+  the dinner; an invalid body is 400, an unknown dinner 404, a page that cannot
+  ground it 422 `ungroundable` (the dinner is unchanged), recipe search not
+  set up 409 `not_configured`, a search or model failure 502
+  `search_failed` / `ai_failed` (only the reason code is logged, never the
+  provider's text), and grounding a candidate or link that runs past 90
+  seconds (fetch, photo and `normalize_recipe`, all in the request) 504
+  `ground_timeout`, leaving the dinner unchanged. An archived dinner is 409
+  `dinner_archived`. A candidate or link is written only if the dinner is
+  still as it was before grounding began: one renamed or grounded some
+  other way meanwhile is 409 `ground_conflict`, and one archived meanwhile
+  409 `dinner_archived`, either leaving the dinner unchanged. A method,
+  minutes or difficulty a member edits meanwhile is kept over the recipe's.
+  Any other failure grounding a candidate or link, or recording it on the
+  dinner, is 500, logged with a fixed reason and the dinner id only —
+  never the link, which can carry a personal token, or dependency error
+  text.
 - `/health` — liveness.
 - Everything else serves the embedded PWA with SPA fallback.
 
@@ -246,7 +372,7 @@ automatic** (D-021).
 - Recipe search (`recipes.SearchProvider`: `Search(ctx, query, n)` →
   `[]Candidate{URL, Title, Snippet}`, n 1–20) appends " recipe" to a query
   without that word. SearXNG is called at
-  `{MEALQUEST_SEARXNG_URL}/search?q=…&format=json&categories=general` —
+  `{recipe_search_settings.base_url}/search?q=…&format=json&categories=general` —
   directly, not through the Fetcher, since this configured endpoint may be
   on the internal network; Brave calls the Brave Web Search API with the
   key decrypted from `recipe_search_settings.api_key_ct`
@@ -280,13 +406,45 @@ automatic** (D-021).
   hard over 10 steps or 90 minutes, easy at 5 steps or fewer and 45 minutes
   or less, else medium, a crockpot's minutes not counting.
 - Photos are cached locally (`photos`) and processed with
-  `golang.org/x/image`. `recipes.PhotoCache.CachePhoto` downloads through
+  `golang.org/x/image`. `recipes.PhotoCache.DownloadPhoto` downloads through
   the Fetcher's `FetchImage` (JPEG, PNG, WebP or GIF content types, 8 MB
-  cap, not cached), decodes the image (a GIF's first frame), refuses a
-  decoded image under 300 px on its short side, scales it so its long side is 1200 px and
-  400 px, and stores each as JPEG quality 82 at
-  `$MEALQUEST_DATA_DIR/media/photos/{id}-{size}.jpg`. Images are
-  deduplicated by the SHA-256 of the downloaded bytes.
+  cap, not cached), decodes the image (a GIF's first frame) and refuses a
+  decoded image under 300 px on its short side, recording nothing.
+  `CachePhoto` then records it in the caller's transaction: it scales the
+  image so its long side is 1200 px and 400 px, and stores each as JPEG
+  quality 82 at `$MEALQUEST_DATA_DIR/media/photos/{id}-{size}.jpg`. Images
+  are deduplicated by the SHA-256 of the downloaded bytes; the writer's
+  single connection serialises transactions, so one image is never
+  recorded twice. Files written for a transaction that rolls back are
+  removed by the caller (`RemovePhotoFiles`).
+- Grounding (`recipes.Grounder`) ties these together.
+  `Ground(ctx, dishName, query)` searches for the top 5 candidates and ranks
+  them all, stored and new alike: a candidate whose `source_url` is already
+  stored is scored on its stored recipe (title, ingredients, steps, times,
+  photo source) and its page is never refetched; every other candidate is
+  fetched and extracted. Ranking alone decides between them. It then tries
+  each ranked candidate best first. A stored one is returned as it is, so a
+  stored recipe is reused only when it ranks above every new candidate that
+  grounds. A new one is grounded in this order: (1) `DownloadPhoto` —
+  the download and validation step of photo caching — (2)
+  `normalize_recipe`, then (3) one **transaction** that runs `CachePhoto`
+  (scales and writes the photo files and records the `photos` row) and
+  stores the recipe, ingredients and steps (an existing `source_url` is
+  updated in place); files written for a rolled-back transaction are
+  removed. It returns `Grounded{recipe_id,
+  photo_id, method, minutes_total, difficulty, source_url, site_name}`. A
+  candidate whose photo fails or whose model output is unusable
+  (`llm.ErrBadOutput`) is passed over; when none grounds, the error is a
+  typed `*recipes.ErrUngroundable` listing every reason (no candidates,
+  Rank's per-candidate reasons, photo or normalize failures). Failures
+  that are not the candidates' — search, model provider, database — are
+  returned as they are. `GroundURL(ctx, url)` does the same for one pasted
+  URL. `Candidates(ctx, dishName, query, n)` returns the first n of the
+  candidates `Ground` would try, without grounding any. Search failures
+  wrap `recipes.ErrSearchFailed` and model provider failures
+  `recipes.ErrNormalizeFailed`. `GroundMany` grounds items 3 at a time and returns one result per
+  item, so one failure never affects its siblings. A recipe is usable only
+  with ingredients, an image and, if given, a positive total time.
 
 ## Scheduler
 
@@ -335,6 +493,9 @@ Runs are recorded in `schedule_runs` and executed through `jobs`.
   hard-coded hex. Self-hosted Bagel Fat One and Figtree.
 - Tests: Vitest, Testing Library, jsdom.
 - Offline cache for the current plan, shopping list and recipes.
+- Logout (`POST /auth/logout`) answers with `Clear-Site-Data: "storage",
+  "cache"`, wiping the offline marker, the service worker and its caches; the
+  worker leaves that request to the browser, as it does every network-only one.
 
 | Route | Screen |
 | --- | --- |
@@ -357,6 +518,48 @@ Runs are recorded in `schedule_runs` and executed through `jobs`.
 `/settings/household`, `/settings/regulars` and `/settings/calendar` come from
 CTXD; the other routes are defined in the UI handoff.
 
+First run: while `household_settings.onboarding_completed_at` (read from
+`GET /api/v1/settings/household`) is null, every route redirects to
+`/onboarding`. Onboarding is a full screen outside the app shell, in three
+steps: the welcome (`/onboarding`), the Regulars (`/onboarding/regulars`,
+mock 1h, adding and archiving through the dinners API optimistically; Next
+waits for three saved Regulars, and a common pick is not offered once a
+Regular has a name `harness.Similar` to it — the PWA's copy of the name
+rules in `web/src/dinners/names.ts` folds letters with
+`web/src/dinners/letterFolds.json`, which `gen_folds.py` writes from the
+same table as the server's, and runs the same cases,
+`web/src/dinners/testdata/dedupe_cases.json`, as the server's) and
+notifications (`/onboarding/notifications`: what MealQuest notifies about,
+the iOS install hint, "Turn on notifications" and "Maybe later"). "Maybe
+later", and "Turn on notifications" once notifications are enabled, send
+`PATCH /api/v1/settings/household` with `{"onboarding_completed": true}`; the server sets `onboarding_completed_at`
+to the time of that update (keeping the first time if it is already set;
+the field itself is read-only and `false` is refused) and the app goes Home.
+Completing needs at least three Regulars (`household.MinRegulars`); with
+fewer the server answers 400 `invalid_settings` naming
+`onboarding_completed` and changes nothing. Step 3 can be reached with
+fewer — by its URL, or after another member removes a Regular — so it then
+shows the server's reason with an "Add Regulars" button back to step 2.
+Notification permission is never asked for on page load; until Feature 19
+wires Web Push, "Turn on notifications" asks for nothing and says plainly
+that notifications are not on yet, offering "Finish setting up" (which
+completes onboarding as above) instead of a silent success. Offline on the
+saved pages the settings cannot be read (the service worker never caches `/api/v1/settings`),
+so the saved pages open as they are.
+
+Regular dinners (`/settings/regulars`) lists the Regulars from
+`GET /api/v1/dinners?status=regular`, each with its photo, "method ·
+minutes", favorite heart and grounding badge ("Finding recipe…" while
+`pending`, "Recipe found" when `grounded` or `manual`, "Needs a recipe" when
+`failed`). The add field takes a name or a pasted `https://` recipe link.
+Tapping a Regular opens an edit sheet (name, method, minutes, difficulty;
+remove archives it after a confirmation); tapping one that needs a recipe
+opens "Fix recipe" (pick one of the recipe candidates, paste a link or type
+the ingredients and steps in). Adds, removals and the heart show at once and
+are undone if the server refuses them. While any Regular is `pending`, the
+list is read again every 3 seconds (not while a change is in flight), and
+polling stops once none is.
+
 ## Boundaries and gotchas
 
 - **Secrets never reach the client** — API keys, OAuth tokens and the Chat

internal/ai/aisettings/aisettings.go

@@ -0,0 +1,478 @@
+// Package aisettings reads and changes the household's AI settings — the
+// ai_settings row seeded by household.SeedAISettings — and builds the
+// provider and harness.Config they describe. The API key is sealed with the
+// secret box and never leaves the package except to the provider.
+package aisettings
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"math"
+	"net/url"
+	"strings"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm/presets"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secureurl"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const (
+	// MaxSystemPromptChars is the longest system prompt accepted, in
+	// characters.
+	MaxSystemPromptChars = 8000
+	// MinKeyLength is the shortest API key accepted, so its last four
+	// characters never give away most of it.
+	MinKeyLength = 8
+)
+
+var (
+	// ErrNotConfigured is returned when the stored AI settings cannot
+	// build a provider, e.g. there is no API key yet. It is joined with
+	// the llm configuration error that says why.
+	ErrNotConfigured = errors.New("aisettings: AI provider is not configured")
+	// ErrProviderFailed is returned when a call to the provider fails. It
+	// is joined with the provider's error, so the llm typed error it
+	// matches says why.
+	ErrProviderFailed = errors.New("aisettings: AI provider call failed")
+	// ErrChanged is returned when the AI settings changed while
+	// their key was being verified, so the result applies to old settings.
+	ErrChanged = errors.New("aisettings: AI settings changed during verification")
+)
+
+// Settings is the household's AI configuration as the API shows it. The
+// API key is never part of it: only its last four characters.
+type Settings struct {
+	Provider    string  `json:"provider"`
+	BaseURL     string  `json:"base_url"`
+	Model       string  `json:"model"`
+	Temperature float64 `json:"temperature"`
+	// SystemPrompt is the admin persona, nil when none is stored.
+	SystemPrompt *string `json:"system_prompt"`
+	// APIKeyLast4 is nil when no key is stored.
+	APIKeyLast4 *string `json:"api_key_last4"`
+	// KeyVerifiedAt is when the stored key was last verified with these
+	// provider settings, nil when it has not been.
+	KeyVerifiedAt *string `json:"key_verified_at"`
+	UpdatedAt     string  `json:"updated_at"`
+}
+
+// Patch changes the settings. A nil field is left as it is.
+type Patch struct {
+	Provider     *string  `json:"provider"`
+	BaseURL      *string  `json:"base_url"`
+	Model        *string  `json:"model"`
+	Temperature  *float64 `json:"temperature"`
+	SystemPrompt *string  `json:"system_prompt"`
+}
+
+// Model is one model the provider offers.
+type Model struct {
+	ID          string `json:"id"`
+	DisplayName string `json:"display_name"`
+}
+
+// Problem is one invalid field, named by its JSON key.
+type Problem struct {
+	Field  string
+	Reason string
+}
+
+// ValidationError lists every problem with an Patch or API
+// key, or with the settings it would leave. No problem quotes the key.
+type ValidationError struct {
+	Problems []Problem
+}
+
+func (e *ValidationError) Error() string {
+	parts := make([]string, len(e.Problems))
+	for i, p := range e.Problems {
+		parts[i] = p.Field + ": " + p.Reason
+	}
+	return "invalid AI settings: " + strings.Join(parts, "; ")
+}
+
+// Service reads and changes the ai_settings row and builds the provider it
+// names. API keys are sealed with its secret box and never leave it except
+// to the provider.
+type Service struct {
+	st        *store.Store
+	box       *secretbox.Box
+	publicURL string
+	// newProvider and newAccount are presets.FromSettings and
+	// presets.ForAccount; tests substitute a fake provider.
+	newProvider harness.NewProvider
+	newAccount  func(llm.Settings, string) (presets.Account, error)
+}
+
+// New returns the service over st, sealing keys with box.
+// publicURL is MEALQUEST_PUBLIC_URL, which some presets send.
+func New(st *store.Store, box *secretbox.Box, publicURL string) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("aisettings: nil store")
+	case box == nil:
+		return nil, errors.New("aisettings: nil secret box")
+	case publicURL == "":
+		return nil, errors.New("aisettings: empty public URL")
+	}
+	return &Service{st: st, box: box, publicURL: publicURL, newProvider: presets.FromSettings, newAccount: presets.ForAccount}, nil
+}
+
+// Get returns the settings.
+func (s *Service) Get(ctx context.Context) (Settings, error) {
+	row, err := s.read(ctx, db.New(s.st.Reader))
+	if err != nil {
+		return Settings{}, err
+	}
+	return settingsFrom(row), nil
+}
+
+// Update applies patch and returns the settings it leaves. The provider
+// and base URL cannot change while an API key is stored, so the key never
+// reaches an endpoint it was not stored for. Every problem is reported in
+// a *ValidationError and nothing changes.
+func (s *Service) Update(ctx context.Context, patch Patch) (Settings, error) {
+	return s.change(ctx, func(row db.AiSetting) (db.AiSetting, error) {
+		return applyPatch(row, patch)
+	})
+}
+
+// SetAPIKey seals key and records its last four characters, clearing
+// key_verified_at. An empty key removes the stored one. A preset without
+// a fixed base URL takes a key only when its base URL is secure (see
+// secureurl.Check).
+func (s *Service) SetAPIKey(ctx context.Context, key string) (Settings, error) {
+	return s.change(ctx, func(row db.AiSetting) (db.AiSetting, error) {
+		row.ApiKeyCt, row.ApiKeyLast4, row.KeyVerifiedAt = nil, sql.NullString{}, sql.NullString{}
+		if key == "" {
+			return row, nil
+		}
+		p, _ := presets.Lookup(row.Provider)
+		var reason string
+		switch {
+		case p.Key == presets.KeyNone:
+			reason = row.Provider + " takes no API key"
+		case p.BaseURL == "" && !secureBaseURL(row.BaseUrl):
+			reason = "is sent only over https://, or http:// to localhost: set such a base_url first"
+		case !validHeaderValue(key):
+			reason = "has a character not allowed in a header"
+		case len(key) < MinKeyLength:
+			reason = fmt.Sprintf("must be at least %d characters", MinKeyLength)
+		}
+		if reason != "" {
+			return db.AiSetting{}, &ValidationError{Problems: []Problem{{Field: "api_key", Reason: reason}}}
+		}
+		ct, err := s.box.Encrypt([]byte(key))
+		if err != nil {
+			return db.AiSetting{}, fmt.Errorf("aisettings: seal AI API key: %w", err)
+		}
+		row.ApiKeyCt = ct
+		row.ApiKeyLast4 = sql.NullString{String: key[len(key)-4:], Valid: true}
+		return row, nil
+	})
+}
+
+// ResetPrompt restores household.DefaultPersonaPrompt as the system prompt.
+func (s *Service) ResetPrompt(ctx context.Context) (Settings, error) {
+	return s.change(ctx, func(row db.AiSetting) (db.AiSetting, error) {
+		row.SystemPrompt = sql.NullString{String: household.DefaultPersonaPrompt, Valid: true}
+		return row, nil
+	})
+}
+
+// Verify checks the stored key with the provider and, when it is
+// accepted, records key_verified_at. Settings that cannot build a
+// provider fail with ErrNotConfigured; a provider failure matches
+// ErrProviderFailed and the llm typed error the provider returned. If the
+// settings change while the provider is asked, nothing is recorded and the
+// error is ErrChanged.
+func (s *Service) Verify(ctx context.Context) (Settings, error) {
+	row, err := s.read(ctx, db.New(s.st.Reader))
+	if err != nil {
+		return Settings{}, err
+	}
+	acct, key, err := s.account(row)
+	if err != nil {
+		return Settings{}, err
+	}
+	if err := acct.Verify(ctx); err != nil {
+		return Settings{}, redact(fmt.Errorf("%w: verify: %w", ErrProviderFailed, err), key)
+	}
+	verified := store.Now().String()
+	return s.change(ctx, func(now db.AiSetting) (db.AiSetting, error) {
+		if now.Provider != row.Provider || now.BaseUrl != row.BaseUrl || !bytes.Equal(now.ApiKeyCt, row.ApiKeyCt) {
+			return db.AiSetting{}, ErrChanged
+		}
+		now.KeyVerifiedAt = sql.NullString{String: verified, Valid: true}
+		return now, nil
+	})
+}
+
+// Models returns the provider's live model list with the API key removed
+// from every model's ID and display name. Its errors are Verify's.
+func (s *Service) Models(ctx context.Context) ([]Model, error) {
+	row, err := s.read(ctx, db.New(s.st.Reader))
+	if err != nil {
+		return nil, err
+	}
+	acct, key, err := s.account(row)
+	if err != nil {
+		return nil, err
+	}
+	models, err := acct.ListModels(ctx)
+	if err != nil {
+		return nil, redact(fmt.Errorf("%w: list models: %w", ErrProviderFailed, err), key)
+	}
+	out := make([]Model, len(models))
+	for i, m := range models {
+		out[i] = Model{ID: llm.Redact(m.ID, key), DisplayName: llm.Redact(m.DisplayName, key)}
+	}
+	return out, nil
+}
+
+// HarnessConfig returns the harness.Config for a skill run with the
+// current settings, sharing guard. Read it for each run, so a run always
+// uses the latest saved provider, model, temperature and persona.
+func (s *Service) HarnessConfig(ctx context.Context, guard *harness.Guard) (harness.Config, error) {
+	row, err := s.read(ctx, db.New(s.st.Reader))
+	if err != nil {
+		return harness.Config{}, err
+	}
+	key, err := s.key(row)
+	if err != nil {
+		return harness.Config{}, err
+	}
+	return harness.Config{
+		Settings:    s.llmSettings(row),
+		APIKey:      key,
+		NewProvider: s.newProvider,
+		Persona:     row.SystemPrompt.String,
+		Store:       s.st,
+		Guard:       guard,
+	}, nil
+}
+
+// account builds the provider's Account from row, returning the key too
+// so the caller can redact it.
+func (s *Service) account(row db.AiSetting) (presets.Account, string, error) {
+	key, err := s.key(row)
+	if err != nil {
+		return nil, "", err
+	}
+	acct, err := s.newAccount(s.llmSettings(row), key)
+	if err != nil {
+		return nil, "", redact(fmt.Errorf("%w: %w", ErrNotConfigured, err), key)
+	}
+	return acct, key, nil
+}
+
+func (s *Service) llmSettings(row db.AiSetting) llm.Settings {
+	return llm.Settings{
+		Provider:    row.Provider,
+		BaseURL:     row.BaseUrl,
+		Model:       row.Model,
+		Temperature: row.Temperature,
+		PublicURL:   s.publicURL,
+	}
+}
+
+// key opens row's API key; "" when none is stored.
+func (s *Service) key(row db.AiSetting) (string, error) {
+	if len(row.ApiKeyCt) == 0 {
+		return "", nil
+	}
+	key, err := s.box.Decrypt(row.ApiKeyCt)
+	if err != nil {
+		return "", fmt.Errorf("aisettings: open AI API key: %w", err)
+	}
+	return string(key), nil
+}
+
+func (s *Service) read(ctx context.Context, q *db.Queries) (db.AiSetting, error) {
+	row, err := q.GetAISettings(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return db.AiSetting{}, errors.New("aisettings: AI settings are not seeded")
+	}
+	if err != nil {
+		return db.AiSetting{}, fmt.Errorf("aisettings: read AI settings: %w", err)
+	}
+	return row, nil
+}
+
+// change saves edit's result for the current row in one transaction.
+func (s *Service) change(ctx context.Context, edit func(db.AiSetting) (db.AiSetting, error)) (Settings, error) {
+	var saved db.AiSetting
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		row, err := s.read(ctx, q)
+		if err != nil {
+			return err
+		}
+		next, err := edit(row)
+		if err != nil {
+			return err
+		}
+		saved, err = q.UpsertAISettings(ctx, db.UpsertAISettingsParams{
+			Provider:      next.Provider,
+			BaseUrl:       next.BaseUrl,
+			Model:         next.Model,
+			Temperature:   next.Temperature,
+			SystemPrompt:  next.SystemPrompt,
+			ApiKeyCt:      next.ApiKeyCt,
+			ApiKeyLast4:   next.ApiKeyLast4,
+			KeyVerifiedAt: next.KeyVerifiedAt,
+			CreatedAt:     row.CreatedAt,
+			UpdatedAt:     store.Now().String(),
+		})
+		if err != nil {
+			return fmt.Errorf("aisettings: save AI settings: %w", err)
+		}
+		return nil
+	})
+	if err != nil {
+		return Settings{}, err
+	}
+	return settingsFrom(saved), nil
+}
+
+// applyPatch returns row with patch applied, validated.
+func applyPatch(row db.AiSetting, patch Patch) (db.AiSetting, error) {
+	var problems []Problem
+	fail := func(field, reason string) {
+		problems = append(problems, Problem{Field: field, Reason: reason})
+	}
+	if patch == (Patch{}) {
+		fail("settings", "no settings to change")
+	}
+	before := row
+	if patch.Provider != nil {
+		if _, ok := presets.Lookup(*patch.Provider); ok {
+			row.Provider = *patch.Provider
+		} else {
+			fail("provider", "must be one of "+strings.Join(presets.Names(), ", "))
+		}
+	}
+	if patch.BaseURL != nil {
+		row.BaseUrl = *patch.BaseURL
+	}
+	if patch.Model != nil {
+		switch m := *patch.Model; {
+		case strings.TrimSpace(m) == "":
+			fail("model", "must not be empty")
+		case !validHeaderValue(m):
+			fail("model", "must not contain control characters")
+		default:
+			row.Model = m
+		}
+	}
+	if patch.Temperature != nil {
+		t := *patch.Temperature
+		tenths := math.Round(t * 10)
+		if t < 0 || t > 1 || math.Abs(t*10-tenths) > 1e-9 {
+			fail("temperature", "must be between 0 and 1 in steps of 0.1")
+		} else {
+			row.Temperature = tenths / 10
+		}
+	}
+	if patch.SystemPrompt != nil {
+		if n := utf8.RuneCountInString(*patch.SystemPrompt); n > MaxSystemPromptChars {
+			fail("system_prompt", fmt.Sprintf("must be at most %d characters, got %d", MaxSystemPromptChars, n))
+		} else {
+			row.SystemPrompt = sql.NullString{String: *patch.SystemPrompt, Valid: true}
+		}
+	}
+	if p, ok := presets.Lookup(row.Provider); ok && len(problems) == 0 {
+		switch {
+		case p.BaseURL != "" && row.BaseUrl != "" && row.BaseUrl != p.BaseURL:
+			fail("base_url", fmt.Sprintf("is fixed for %s: must be empty or %s", p.Name, p.BaseURL))
+		case p.BaseURL == "" && row.BaseUrl != "":
+			// The preset's own check of the URL; its errors never quote it.
+			if _, err := presets.ForAccount(llm.Settings{Provider: p.Name, BaseURL: row.BaseUrl}, ""); err != nil {
+				fail("base_url", err.Error())
+			}
+		}
+	}
+	// The stored key is only ever sent where it was stored for: moving it
+	// to another provider or server would let a changed base URL receive
+	// it. Remove the key, change the endpoint, then store the new key.
+	if len(problems) == 0 && len(row.ApiKeyCt) > 0 {
+		if row.Provider != before.Provider {
+			fail("provider", "cannot change while an API key is stored: remove the key first")
+		}
+		if row.BaseUrl != before.BaseUrl {
+			fail("base_url", "cannot change while an API key is stored: remove the key first")
+		}
+	}
+	if len(problems) > 0 {
+		return db.AiSetting{}, &ValidationError{Problems: problems}
+	}
+	return row, nil
+}
+
+func settingsFrom(row db.AiSetting) Settings {
+	return Settings{
+		Provider:      row.Provider,
+		BaseURL:       row.BaseUrl,
+		Model:         row.Model,
+		Temperature:   row.Temperature,
+		SystemPrompt:  nullString(row.SystemPrompt),
+		APIKeyLast4:   nullString(row.ApiKeyLast4),
+		KeyVerifiedAt: nullString(row.KeyVerifiedAt),
+		UpdatedAt:     row.UpdatedAt,
+	}
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}
+
+// secureBaseURL reports whether base is a URL a key may be sent to.
+func secureBaseURL(base string) bool {
+	u, err := url.Parse(base)
+	return base != "" && err == nil && secureurl.Check(u) == nil
+}
+
+// validHeaderValue reports whether value has no control character other
+// than tab.
+func validHeaderValue(value string) bool {
+	for i := 0; i < len(value); i++ {
+		if c := value[i]; (c < 0x20 && c != '\t') || c == 0x7f {
+			return false
+		}
+	}
+	return true
+}
+
+// redactedError is an error with the API key removed from its text. It
+// does not unwrap, because the original may hold the key; Is still matches
+// the sentinels the original wraps.
+type redactedError struct {
+	text string
+	err  error
+}
+
+func (e *redactedError) Error() string { return e.text }
+
+// Is reports whether the original error matches target.
+func (e *redactedError) Is(target error) bool { return errors.Is(e.err, target) }
+
+// redact returns err with key removed from its text; an empty key returns
+// err unchanged.
+func redact(err error, key string) error {
+	if key == "" {
+		return err
+	}
+	return &redactedError{text: llm.Redact(err.Error(), key), err: err}
+}

internal/ai/aisettings/aisettings_test.go

@@ -0,0 +1,463 @@
+package aisettings
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm/presets"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+const testKey = "sk-ant-test-secret-key-41ab"
+
+// newService returns a Service over a migrated store with the seed AI
+// settings.
+func newService(t *testing.T) (*Service, *store.Store) {
+	t.Helper()
+	ctx := context.Background()
+	st, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedAISettings(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	raw := make([]byte, secretbox.KeySize)
+	rand.Read(raw)
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, err := New(st, box, "https://mealquest.example")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s, st
+}
+
+// useFake makes s build f for every run, verification and model list, and
+// returns a func reporting the settings and key each build was given.
+func useFake(s *Service, f *llm.Fake) func() ([]llm.Settings, []string) {
+	var mu sync.Mutex
+	var settings []llm.Settings
+	var keys []string
+	record := func(set llm.Settings, key string) {
+		mu.Lock()
+		defer mu.Unlock()
+		settings = append(settings, set)
+		keys = append(keys, key)
+	}
+	s.newProvider = func(set llm.Settings, key string) (llm.Provider, error) {
+		record(set, key)
+		return f, nil
+	}
+	s.newAccount = func(set llm.Settings, key string) (presets.Account, error) {
+		record(set, key)
+		return f, nil
+	}
+	return func() ([]llm.Settings, []string) {
+		mu.Lock()
+		defer mu.Unlock()
+		return settings, keys
+	}
+}
+
+func ptr[T any](v T) *T { return &v }
+
+// echoSkill asks the model to repeat a word; its prompt is the harness's
+// test template prompts/echo.v1.tmpl.
+type echoSkill struct{}
+
+type echoInput struct{ Word string }
+
+type echoOutput struct {
+	Echo string `json:"echo"`
+}
+
+func (echoSkill) Name() string { return "echo" }
+func (echoSkill) Version() int { return 1 }
+func (echoSkill) PromptInput(in echoInput) (harness.PromptInput, error) {
+	return harness.PromptInput{Data: in}, nil
+}
+func (echoSkill) Schema() llm.JSONSchema {
+	return llm.JSONSchema{Name: "echo", Schema: json.RawMessage(
+		`{"type":"object","properties":{"echo":{"type":"string"}},"required":["echo"],"additionalProperties":false}`)}
+}
+func (echoSkill) Validate(echoOutput) []string                   { return nil }
+func (echoSkill) PostProcess(out echoOutput) (echoOutput, error) { return out, nil }
+func (echoSkill) Timeout() time.Duration                         { return harness.DefaultTimeout }
+
+// A PATCHed model and temperature are what the next skill run uses: the
+// provider is built with them, the request carries the temperature and the
+// ai_runs row records both. A second PATCH changes the run after it.
+func TestPatchedModelAndTemperatureUsedByNextRun(t *testing.T) {
+	ctx := context.Background()
+	s, st := newService(t)
+	f := &llm.Fake{}
+	built := useFake(s, f)
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.SetAPIKey(ctx, testKey); err != nil {
+		t.Fatal(err)
+	}
+
+	for i, want := range []struct {
+		model string
+		temp  float64
+	}{{"claude-patched", 0.3}, {"claude-repatched", 1}} {
+		if _, err := s.Update(ctx, Patch{Model: ptr(want.model), Temperature: ptr(want.temp)}); err != nil {
+			t.Fatal(err)
+		}
+		cfg, err := s.HarnessConfig(ctx, guard)
+		if err != nil {
+			t.Fatal(err)
+		}
+		f.QueueGenerate(llm.GenerateResult{Response: llm.Response{JSON: json.RawMessage(`{"echo":"hi"}`)}})
+		if _, err := harness.Run(ctx, cfg, echoSkill{}, "test", echoInput{Word: "hi"}); err != nil {
+			t.Fatalf("run %d: %v", i, err)
+		}
+
+		settings, keys := built()
+		if got := settings[i]; got.Provider != "anthropic" || got.Model != want.model || got.Temperature != want.temp || keys[i] != testKey {
+			t.Errorf("run %d provider built with %+v, key ok %v; want model %s at %v", i, got, keys[i] == testKey, want.model, want.temp)
+		}
+		req := f.Requests()[i]
+		if req.Temperature == nil || *req.Temperature != want.temp {
+			t.Errorf("run %d request temperature = %v, want %v", i, req.Temperature, want.temp)
+		}
+		if !strings.HasPrefix(req.System, household.DefaultPersonaPrompt[:40]) {
+			t.Errorf("run %d system prompt does not start with the persona: %.80q", i, req.System)
+		}
+		var model string
+		var temp float64
+		err = st.Reader.QueryRowContext(ctx, `SELECT model, temperature FROM ai_runs ORDER BY created_at DESC, rowid DESC LIMIT 1`).Scan(&model, &temp)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if model != want.model || temp != want.temp {
+			t.Errorf("run %d ai_runs row = %s at %v, want %s at %v", i, model, temp, want.model, want.temp)
+		}
+	}
+}
+
+func TestUpdateValidates(t *testing.T) {
+	ctx := context.Background()
+	for _, c := range []struct {
+		name  string
+		patch Patch
+		field string
+	}{
+		{"empty", Patch{}, "settings"},
+		{"unknown provider", Patch{Provider: ptr("gemini")}, "provider"},
+		{"temperature above 1", Patch{Temperature: ptr(1.1)}, "temperature"},
+		{"negative temperature", Patch{Temperature: ptr(-0.1)}, "temperature"},
+		{"temperature between steps", Patch{Temperature: ptr(0.35)}, "temperature"},
+		{"empty model", Patch{Model: ptr(" ")}, "model"},
+		{"long system prompt", Patch{SystemPrompt: ptr(strings.Repeat("ü", MaxSystemPromptChars+1))}, "system_prompt"},
+		{"other base URL for a fixed preset", Patch{BaseURL: ptr("https://api.example/v1")}, "base_url"},
+		{"bad base URL", Patch{Provider: ptr("ollama"), BaseURL: ptr("ftp://ollama:11434")}, "base_url"},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			s, _ := newService(t)
+			before, err := s.Get(ctx)
+			if err != nil {
+				t.Fatal(err)
+			}
+			_, err = s.Update(ctx, c.patch)
+			var invalid *ValidationError
+			if !errors.As(err, &invalid) || len(invalid.Problems) != 1 || invalid.Problems[0].Field != c.field {
+				t.Fatalf("Update = %v, want one %s problem", err, c.field)
+			}
+			if after, err := s.Get(ctx); err != nil || !reflect.DeepEqual(after, before) {
+				t.Errorf("settings changed by a refused patch: %+v, %v", after, err)
+			}
+		})
+	}
+}
+
+func TestUpdateAccepts(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	for _, temp := range []float64{0, 0.1, 0.2, 0.3, 0.6, 0.7, 0.9, 1} {
+		got, err := s.Update(ctx, Patch{Temperature: ptr(temp)})
+		if err != nil || got.Temperature != temp {
+			t.Errorf("temperature %v = %v, %v", temp, got.Temperature, err)
+		}
+	}
+	prompt := strings.Repeat("ü", MaxSystemPromptChars)
+	if got, err := s.Update(ctx, Patch{SystemPrompt: &prompt}); err != nil || *got.SystemPrompt != prompt {
+		t.Errorf("system prompt of %d characters: %v", MaxSystemPromptChars, err)
+	}
+	for _, p := range presets.Names() {
+		patch := Patch{Provider: ptr(p), BaseURL: ptr("")}
+		if pr, _ := presets.Lookup(p); pr.BaseURL == "" {
+			patch.BaseURL = ptr("http://llm.local:11434")
+		}
+		if got, err := s.Update(ctx, patch); err != nil || got.Provider != p {
+			t.Errorf("provider %s: %+v, %v", p, got, err)
+		}
+	}
+}
+
+// While a key is stored the provider and base URL cannot change, so the
+// key never reaches an endpoint it was not stored for; the model,
+// temperature and system prompt can, keeping the verification.
+func TestEndpointLockedWhileKeyStored(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	f := &llm.Fake{}
+	useFake(s, f)
+	if _, err := s.Update(ctx, Patch{Provider: ptr("openai_compatible"), BaseURL: ptr("https://llm.example/v1")}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.SetAPIKey(ctx, testKey); err != nil {
+		t.Fatal(err)
+	}
+	f.QueueVerify(nil)
+	if got, err := s.Verify(ctx); err != nil || got.KeyVerifiedAt == nil {
+		t.Fatalf("Verify = %+v, %v", got, err)
+	}
+	got, err := s.Update(ctx, Patch{Model: ptr("m"), Temperature: ptr(0.5), SystemPrompt: ptr("p")})
+	if err != nil || got.KeyVerifiedAt == nil {
+		t.Errorf("model change = %+v, %v; want verification kept", got, err)
+	}
+	before, err := s.Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range []struct {
+		patch Patch
+		field string
+	}{
+		{Patch{BaseURL: ptr("https://attacker.example/v1")}, "base_url"},
+		{Patch{Provider: ptr("openai"), BaseURL: ptr("")}, "provider"},
+		{Patch{Provider: ptr("ollama"), BaseURL: ptr("http://localhost:11434")}, "provider"},
+	} {
+		var invalid *ValidationError
+		_, err := s.Update(ctx, c.patch)
+		if !errors.As(err, &invalid) || !slices.ContainsFunc(invalid.Problems, func(p Problem) bool { return p.Field == c.field }) {
+			t.Errorf("Update(%+v) with a key stored = %v, want a %s problem", c.patch, err, c.field)
+		}
+	}
+	if after, err := s.Get(ctx); err != nil || !reflect.DeepEqual(after, before) {
+		t.Errorf("refused endpoint change altered the settings: %+v, %v", after, err)
+	}
+
+	// Removing the key frees the endpoint; a new key is unverified.
+	if _, err := s.SetAPIKey(ctx, ""); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.Update(ctx, Patch{Provider: ptr("openai"), BaseURL: ptr("")}); err != nil {
+		t.Fatal(err)
+	}
+	got, err = s.SetAPIKey(ctx, "sk-another-key-9999")
+	if err != nil || got.KeyVerifiedAt != nil || *got.APIKeyLast4 != "9999" {
+		t.Errorf("new key = %+v, %v; want it unverified", got, err)
+	}
+}
+
+// A key is never stored for a base URL it would cross the network to in
+// plain text.
+func TestSetAPIKeyNeedsSecureBaseURL(t *testing.T) {
+	ctx := context.Background()
+	for _, c := range []struct {
+		base string
+		ok   bool
+	}{
+		{"", false},
+		{"http://llm.lan:8080/v1", false},
+		{"http://127.0.0.1:8080/v1", true},
+		{"https://llm.example/v1", true},
+	} {
+		s, _ := newService(t)
+		patch := Patch{Provider: ptr("openai_compatible")}
+		if c.base != "" {
+			patch.BaseURL = ptr(c.base)
+		}
+		if _, err := s.Update(ctx, patch); err != nil {
+			t.Fatal(err)
+		}
+		_, err := s.SetAPIKey(ctx, testKey)
+		var invalid *ValidationError
+		if c.ok != (err == nil) || (!c.ok && !errors.As(err, &invalid)) {
+			t.Errorf("SetAPIKey with base URL %q = %v, want ok %v", c.base, err, c.ok)
+		}
+	}
+}
+
+func TestVerifyReturnsProviderTypedError(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	f := &llm.Fake{}
+	useFake(s, f)
+	if _, err := s.SetAPIKey(ctx, testKey); err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []error{llm.ErrAuth, llm.NewRateLimitedError(time.Second, testKey), llm.NewProviderError(500, []byte("bad "+testKey), testKey)} {
+		f.QueueVerify(want)
+		_, err := s.Verify(ctx)
+		if !errors.Is(err, ErrProviderFailed) || !errors.Is(err, want) {
+			t.Errorf("Verify = %v, want ErrProviderFailed and %v", err, want)
+		}
+		if err != nil && strings.Contains(err.Error(), testKey) {
+			t.Errorf("Verify error holds the key: %v", err)
+		}
+	}
+	if got, err := s.Get(ctx); err != nil || got.KeyVerifiedAt != nil {
+		t.Errorf("failed verification recorded: %+v, %v", got, err)
+	}
+}
+
+// A key error that quotes the key, as a misbehaving adapter might, is
+// redacted by the service.
+func TestVerifyRedactsKey(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	f := &llm.Fake{}
+	useFake(s, f)
+	if _, err := s.SetAPIKey(ctx, testKey); err != nil {
+		t.Fatal(err)
+	}
+	f.QueueVerify(errors.Join(llm.ErrAuth, errors.New("rejected "+testKey)))
+	_, err := s.Verify(ctx)
+	if !errors.Is(err, llm.ErrAuth) || strings.Contains(err.Error(), testKey) {
+		t.Errorf("Verify = %v, want ErrAuth without the key", err)
+	}
+	f.QueueListModels(llm.ListModelsResult{Err: errors.New("rejected " + testKey)})
+	if _, err := s.Models(ctx); !errors.Is(err, ErrProviderFailed) || strings.Contains(err.Error(), testKey) {
+		t.Errorf("Models = %v, want ErrProviderFailed without the key", err)
+	}
+	f.QueueListModels(llm.ListModelsResult{Models: []llm.Model{{ID: "m-" + testKey, DisplayName: "Model " + testKey}}})
+	models, err := s.Models(ctx)
+	if err != nil || len(models) != 1 || models[0] != (Model{ID: "m-[REDACTED]", DisplayName: "Model [REDACTED]"}) {
+		t.Errorf("Models = %+v, %v, want the key redacted", models, err)
+	}
+}
+
+// Settings changed while the provider verifies the key are not marked
+// verified.
+func TestVerifyRefusesChangedSettings(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	if _, err := s.SetAPIKey(ctx, testKey); err != nil {
+		t.Fatal(err)
+	}
+	s.newAccount = func(llm.Settings, string) (presets.Account, error) {
+		return changingAccount{s: s}, nil
+	}
+	if _, err := s.Verify(ctx); !errors.Is(err, ErrChanged) {
+		t.Fatalf("Verify = %v, want ErrChanged", err)
+	}
+	if got, err := s.Get(ctx); err != nil || got.KeyVerifiedAt != nil || *got.APIKeyLast4 != "5678" {
+		t.Errorf("settings after a changed verification = %+v, %v", got, err)
+	}
+}
+
+// changingAccount replaces the stored key while it verifies.
+type changingAccount struct{ s *Service }
+
+func (a changingAccount) Verify(ctx context.Context) error {
+	_, err := a.s.SetAPIKey(ctx, "sk-replaced-5678")
+	return err
+}
+
+func (changingAccount) ListModels(context.Context) ([]llm.Model, error) { return nil, nil }
+
+func TestNotConfigured(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	// The seed is anthropic with no key; the real presets refuse it.
+	if _, err := s.Verify(ctx); !errors.Is(err, ErrNotConfigured) || !errors.Is(err, llm.ErrMissingKey) {
+		t.Errorf("Verify = %v, want ErrNotConfigured and ErrMissingKey", err)
+	}
+	if _, err := s.Models(ctx); !errors.Is(err, ErrNotConfigured) {
+		t.Errorf("Models = %v, want ErrNotConfigured", err)
+	}
+}
+
+func TestSetAPIKey(t *testing.T) {
+	ctx := context.Background()
+	s, st := newService(t)
+	got, err := s.SetAPIKey(ctx, testKey)
+	if err != nil || got.APIKeyLast4 == nil || *got.APIKeyLast4 != "41ab" {
+		t.Fatalf("SetAPIKey = %+v, %v", got, err)
+	}
+	var ct []byte
+	if err := st.Reader.QueryRowContext(ctx, `SELECT api_key_ct FROM ai_settings`).Scan(&ct); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(ct), testKey) {
+		t.Error("the key is stored in plain text")
+	}
+	if key, err := s.key(mustRow(t, s)); err != nil || key != testKey {
+		t.Errorf("stored key opens to %q, %v", key, err)
+	}
+
+	for _, bad := range []string{"short", "sk-bad\r\nkey"} {
+		var invalid *ValidationError
+		if _, err := s.SetAPIKey(ctx, bad); !errors.As(err, &invalid) {
+			t.Errorf("SetAPIKey(%q) = %v, want a ValidationError", bad, err)
+		}
+	}
+
+	// Ollama takes no key: neither storing one nor switching to it with one.
+	var invalid *ValidationError
+	if _, err := s.Update(ctx, Patch{Provider: ptr("ollama"), BaseURL: ptr("http://ollama:11434")}); !errors.As(err, &invalid) {
+		t.Errorf("switch to ollama with a key = %v, want a ValidationError", err)
+	}
+	if got, err := s.SetAPIKey(ctx, ""); err != nil || got.APIKeyLast4 != nil {
+		t.Fatalf("remove key = %+v, %v", got, err)
+	}
+	if _, err := s.Update(ctx, Patch{Provider: ptr("ollama"), BaseURL: ptr("http://ollama:11434")}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.SetAPIKey(ctx, testKey); !errors.As(err, &invalid) {
+		t.Errorf("SetAPIKey for ollama = %v, want a ValidationError", err)
+	}
+}
+
+func TestResetPrompt(t *testing.T) {
+	ctx := context.Background()
+	s, _ := newService(t)
+	if _, err := s.Update(ctx, Patch{SystemPrompt: ptr("")}); err != nil {
+		t.Fatal(err)
+	}
+	got, err := s.ResetPrompt(ctx)
+	if err != nil || got.SystemPrompt == nil || *got.SystemPrompt != household.DefaultPersonaPrompt {
+		t.Errorf("ResetPrompt = %+v, %v", got, err)
+	}
+}
+
+func mustRow(t *testing.T, s *Service) db.AiSetting {
+	t.Helper()
+	row, err := s.read(context.Background(), db.New(s.st.Reader))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return row
+}

internal/ai/harness/dedupe_test.go

@@ -1,10 +1,70 @@
 package harness
 
 import (
+	"encoding/json"
+	"os"
 	"testing"
 	"unicode"
+	"unicode/utf8"
 )
 
+// TestSharedDedupeCases runs web/src/dinners/testdata/dedupe_cases.json,
+// which the PWA's copy of Normalize and Similar (web/src/dinners/names.ts)
+// runs too, so the two cannot drift apart on these names.
+func TestSharedDedupeCases(t *testing.T) {
+	raw, err := os.ReadFile("../../../web/src/dinners/testdata/dedupe_cases.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases struct {
+		Normalize []struct{ Name, Want string }
+		Similar   []struct {
+			A, B string
+			Want bool
+		}
+	}
+	if err := json.Unmarshal(raw, &cases); err != nil {
+		t.Fatal(err)
+	}
+	if len(cases.Normalize) == 0 || len(cases.Similar) == 0 {
+		t.Fatal("dedupe_cases.json has no cases")
+	}
+	for _, c := range cases.Normalize {
+		if got := Normalize(c.Name); got != c.Want {
+			t.Errorf("Normalize(%q) = %q, want %q", c.Name, got, c.Want)
+		}
+	}
+	for _, c := range cases.Similar {
+		if got := Similar(c.A, c.B); got != c.Want {
+			t.Errorf("Similar(%q, %q) = %v, want %v", c.A, c.B, got, c.Want)
+		}
+	}
+}
+
+// TestLetterFoldsMatchPWA checks that the PWA's letter-fold table, which
+// gen_folds.py writes beside folds_table.go, is letterFolds exactly; run
+// go generate when it fails.
+func TestLetterFoldsMatchPWA(t *testing.T) {
+	raw, err := os.ReadFile("../../../web/src/dinners/letterFolds.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var pwa map[string]string
+	if err := json.Unmarshal(raw, &pwa); err != nil {
+		t.Fatal(err)
+	}
+	for r, want := range letterFolds {
+		if got, ok := pwa[string(r)]; !ok || got != want {
+			t.Errorf("PWA folds %U to %q (present %v), want %q", r, got, ok, want)
+		}
+	}
+	for k := range pwa {
+		if utf8.RuneCountInString(k) != 1 || letterFolds[[]rune(k)[0]] == "" {
+			t.Errorf("PWA folds %q, which letterFolds does not", k)
+		}
+	}
+}
+
 func TestNormalize(t *testing.T) {
 	tests := []struct {
 		name, want string

internal/ai/harness/gen_folds.py

@@ -1,5 +1,8 @@
 #!/usr/bin/env python3
-"""Generate folds_table.go, the letter-fold table used by harness.Normalize.
+"""Generate folds_table.go, the letter-fold table used by harness.Normalize,
+and its copy web/src/dinners/letterFolds.json, used by the PWA's
+normalizeName (web/src/dinners/names.ts). TestLetterFoldsMatchPWA fails when
+the two differ.
 
 Run from this directory with `go generate ./internal/ai/harness` (or
 `python3 gen_folds.py`; gofmt must be on PATH). It uses only the Python
@@ -28,11 +31,14 @@ Hangul syllables are left out: their decomposition is into conjoining jamo,
 not combining marks.
 """
 
+import json
 import re
 import subprocess
 import sys
 import unicodedata
 
+PWA_TABLE = "../../../web/src/dinners/letterFolds.json"
+
 EXTRA = {
     "ß": "ss", "ẞ": "ss", "æ": "ae", "Æ": "ae", "œ": "oe", "Œ": "oe",
     "þ": "th", "Þ": "th", "ð": "d", "Ð": "d", "ı": "i", "ʼn": "n",
@@ -110,6 +116,9 @@ def main():
     with open("folds_table.go", "w", encoding="utf-8") as f:
         f.write("\n".join(out) + "\n")
     subprocess.run(["gofmt", "-w", "folds_table.go"], check=True)
+    with open(PWA_TABLE, "w", encoding="ascii") as f:
+        json.dump({chr(cp): folded for cp, folded in entries}, f, indent=2)
+        f.write("\n")
 
 
 if __name__ == "__main__":

internal/ai/llm/presets/presets.go

@@ -15,6 +15,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"maps"
 	"math"
 	"regexp"
 	"slices"
@@ -115,6 +116,11 @@ func Lookup(name string) (Preset, bool) {
 	return p, ok
 }
 
+// Names returns every preset's name, sorted.
+func Names() []string {
+	return slices.Sorted(maps.Keys(all))
+}
+
 // all is every preset, by Settings.Provider name.
 var all = map[string]Preset{
 	"anthropic": {
@@ -181,19 +187,40 @@ var all = map[string]Preset{
 // preset's OmitTemperature matches. It is wrapped in llm.NewRetrying, so
 // Generate retries transient vendor failures and has the default timeout.
 func FromSettings(s llm.Settings, key string) (llm.Provider, error) {
-	cp, err := fromSettings(s, key)
+	cp, err := fromSettings(s, key, true)
 	if err != nil {
 		return nil, redact(err, key)
 	}
 	return llm.NewRetrying(cp), nil
 }
 
-func fromSettings(s llm.Settings, key string) (*configured, error) {
+// Account is what a provider offers before a model is chosen: the live
+// model list and a check of the credentials.
+type Account interface {
+	ListModels(ctx context.Context) ([]llm.Model, error)
+	Verify(ctx context.Context) error
+}
+
+// ForAccount returns the Account s describes, using key as its API key. It
+// checks s and key as FromSettings does except that s.Model may be empty,
+// so the household can verify its key and pick from the live model list
+// before it has chosen a model. Neither call is retried.
+func ForAccount(s llm.Settings, key string) (Account, error) {
+	cp, err := fromSettings(s, key, false)
+	if err != nil {
+		return nil, redact(err, key)
+	}
+	return cp, nil
+}
+
+// fromSettings builds the provider s describes; needModel is whether
+// s.Model is required.
+func fromSettings(s llm.Settings, key string, needModel bool) (*configured, error) {
 	p, ok := Lookup(s.Provider)
 	if !ok {
 		return nil, llm.ErrUnknownProvider
 	}
-	if err := check(p, s, key); err != nil {
+	if err := check(p, s, key, needModel); err != nil {
 		return nil, fmt.Errorf("%s: %w", p.Name, err)
 	}
 	base := p.BaseURL
@@ -233,8 +260,9 @@ func fromSettings(s llm.Settings, key string) (*configured, error) {
 	return cp, nil
 }
 
-// check validates s and key against p. Its errors never quote a value.
-func check(p Preset, s llm.Settings, key string) error {
+// check validates s and key against p, and that s names a model when
+// needModel is set. Its errors never quote a value.
+func check(p Preset, s llm.Settings, key string, needModel bool) error {
 	switch {
 	case p.Key == KeyRequired && key == "":
 		return llm.ErrMissingKey
@@ -249,7 +277,7 @@ func check(p Preset, s llm.Settings, key string) error {
 	case p.BaseURL != "" && s.BaseURL != "" && s.BaseURL != p.BaseURL:
 		return fmt.Errorf("%w: base URL is fixed by the preset", llm.ErrInvalidSetting)
 	}
-	if s.Model == "" {
+	if needModel && s.Model == "" {
 		return llm.ErrMissingModel
 	}
 	if p.RequiresPublicURL && s.PublicURL == "" {

internal/ai/llm/presets/presets_test.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"slices"
 	"strings"
 	"testing"
 
@@ -660,3 +661,35 @@ func TestFromSettingsRetriesTransportTimeout(t *testing.T) {
 		t.Errorf("sent %d requests, want 2", st.sent)
 	}
 }
+
+// ForAccount builds without a model, so a key can be verified and the
+// model list read before a model is chosen, but keeps every other check.
+func TestForAccount(t *testing.T) {
+	if _, err := ForAccount(llm.Settings{Provider: "openai"}, testKey); err != nil {
+		t.Errorf("ForAccount without a model = %v", err)
+	}
+	for _, c := range []struct {
+		s    llm.Settings
+		key  string
+		want error
+	}{
+		{llm.Settings{Provider: "gemini"}, testKey, llm.ErrUnknownProvider},
+		{llm.Settings{Provider: "openai"}, "", llm.ErrMissingKey},
+		{llm.Settings{Provider: "ollama"}, "", llm.ErrMissingBaseURL},
+		{llm.Settings{Provider: "openrouter"}, testKey, llm.ErrMissingPublicURL},
+	} {
+		if _, err := ForAccount(c.s, c.key); !errors.Is(err, c.want) {
+			t.Errorf("ForAccount(%s) = %v, want %v", c.s.Provider, err, c.want)
+		}
+	}
+	if _, err := FromSettings(llm.Settings{Provider: "openai"}, testKey); !errors.Is(err, llm.ErrMissingModel) {
+		t.Errorf("FromSettings without a model = %v, want ErrMissingModel", err)
+	}
+}
+
+func TestNames(t *testing.T) {
+	want := []string{"anthropic", "ollama", "openai", "openai_compatible", "openrouter", "xai"}
+	if got := Names(); !slices.Equal(got, want) {
+		t.Errorf("Names = %v, want %v", got, want)
+	}
+}

internal/auth/auth.go

@@ -327,8 +327,13 @@ func (a *Auth) callback(w http.ResponseWriter, r *http.Request) {
 
 // logout ends the session, clears the cookie and sends the browser to the
 // provider's end_session_endpoint to end the provider session as well.
+// Clear-Site-Data wipes this origin's storage and caches — the PWA's
+// verified-session marker in localStorage and the service worker's cached API
+// and media responses — so an offline visit after logout cannot reopen
+// household data.
 func (a *Auth) logout(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Clear-Site-Data", `"storage", "cache"`)
 	if err := a.sessions.EndSession(w, r); err != nil {
 		a.logger.ErrorContext(r.Context(), "end session", "error", err)
 		http.Error(w, "internal error", http.StatusInternalServerError)

internal/auth/session_test.go

@@ -440,6 +440,9 @@ func TestLogout(t *testing.T) {
 	if !strings.HasPrefix(raw, SessionCookieName+"=;") || !strings.Contains(raw, "Max-Age=0") {
 		t.Errorf("logout Set-Cookie = %q, want the cookie cleared", raw)
 	}
+	if got := resp.Header.Get("Clear-Site-Data"); got != `"storage", "cache"` {
+		t.Errorf("logout Clear-Site-Data = %q, want the PWA's storage and caches cleared", got)
+	}
 
 	rows := h.rows(t)
 	if len(rows) != 1 || rows[0].idHash != sha256Hex(other.Value) {
@@ -461,6 +464,9 @@ func TestLogoutWithoutSession(t *testing.T) {
 		t.Errorf("logout = %d to %q, want 303 to the end session endpoint", resp.StatusCode, resp.Header.Get("Location"))
 	}
 	assertSessionCookieAttributes(t, sessionSetCookie(t, resp))
+	if got := resp.Header.Get("Clear-Site-Data"); got != `"storage", "cache"` {
+		t.Errorf("logout Clear-Site-Data = %q, want the PWA's storage and caches cleared", got)
+	}
 }
 
 func TestLogoutIsPostOnly(t *testing.T) {

internal/config/config.go

@@ -35,6 +35,8 @@ const (
 	EnvTrustedProxy = "MEALQUEST_TRUSTED_PROXY"
 
 	EnvDefaultTZ = "MEALQUEST_DEFAULT_TZ"
+
+	EnvSearXNGURL = "MEALQUEST_SEARXNG_URL"
 )
 
 // Session lifetime defaults (D-004): long enough that the kitchen tablet
@@ -73,6 +75,13 @@ type Config struct {
 	// validates it only while the settings do not exist yet, and ignores it
 	// once they do. Empty when unset.
 	DefaultTZ string
+
+	// SearXNGURL is the deployment's SearXNG instance, which the Settings
+	// screen suggests while no recipe-search URL is saved. It is optional
+	// and validated by recipes.NewSearchSettingsService: the compose
+	// network's http://searxng:8080 is neither https nor loopback, so the
+	// secure-URL rule does not apply. Empty when unset.
+	SearXNGURL string
 }
 
 // PublicOrigin returns the scheme and host of PublicURL, the only parts of it
@@ -107,6 +116,8 @@ func load(lookup func(string) (string, bool)) (Config, error) {
 		TrustedProxy: r.trustedProxy(EnvTrustedProxy),
 
 		DefaultTZ: r.optional(EnvDefaultTZ),
+
+		SearXNGURL: r.optional(EnvSearXNGURL),
 	}
 	if cfg.SessionIdle > 0 && cfg.SessionMax > 0 && cfg.SessionMax < cfg.SessionIdle {
 		r.fail(EnvSessionMax, "must be at least %s (%s)", EnvSessionIdle, cfg.SessionIdle)

internal/config/config_test.go

@@ -422,6 +422,8 @@ func TestLoadValues(t *testing.T) {
 		EnvOIDCAllowedGroups:    " mealquest-admin ,family",
 
 		EnvDefaultTZ: "Europe/London",
+
+		EnvSearXNGURL: "http://searxng:8080",
 	}
 	cfg, err := load(func(k string) (string, bool) { v, ok := env[k]; return v, ok })
 	if err != nil {
@@ -480,6 +482,9 @@ func TestLoadValues(t *testing.T) {
 	if cfg.DefaultTZ != "Europe/London" {
 		t.Errorf("DefaultTZ = %q, want Europe/London", cfg.DefaultTZ)
 	}
+	if cfg.SearXNGURL != "http://searxng:8080" {
+		t.Errorf("SearXNGURL = %q, want http://searxng:8080", cfg.SearXNGURL)
+	}
 }
 
 func TestSecretRedacted(t *testing.T) {

internal/db/db_test.go

@@ -106,13 +106,22 @@ func TestDinners(t *testing.T) {
 		Cuisine:         str("Mexican"),
 		IsFavorite:      0,
 		RecipeID:        str(recipe.ID),
+		RecipeUrl:       str("https://example.com/tacos"),
 		PhotoID:         str(photo.ID),
 		GroundingStatus: "grounded",
 		UpdatedBy:       str("alex@example.com"),
 		CreatedAt:       created,
 		UpdatedAt:       created,
 	}
-	want := db.Dinner(create)
+	want := db.Dinner{
+		ID: create.ID, Name: create.Name, NormalizedName: create.NormalizedName,
+		Status: create.Status, Origin: create.Origin, Method: create.Method,
+		MinutesTotal: create.MinutesTotal, Difficulty: create.Difficulty,
+		Cuisine: create.Cuisine, IsFavorite: create.IsFavorite, RecipeID: create.RecipeID,
+		PhotoID: create.PhotoID, GroundingStatus: create.GroundingStatus,
+		UpdatedBy: create.UpdatedBy, CreatedAt: created, UpdatedAt: created,
+		RecipeUrl: create.RecipeUrl,
+	}
 	got, err := q.CreateDinner(ctx, create)
 	if err != nil {
 		t.Fatalf("CreateDinner: %v", err)
@@ -181,6 +190,7 @@ func TestDinners(t *testing.T) {
 		Difficulty:      str("medium"),
 		Cuisine:         sql.NullString{},
 		RecipeID:        sql.NullString{},
+		RecipeUrl:       str("https://example.com/tacos"),
 		PhotoID:         str(photo.ID),
 		GroundingStatus: "failed",
 		UpdatedBy:       str("sam@example.com"),
@@ -197,6 +207,7 @@ func TestDinners(t *testing.T) {
 		Cuisine: update.Cuisine, IsFavorite: 0, RecipeID: update.RecipeID,
 		PhotoID: update.PhotoID, GroundingStatus: update.GroundingStatus,
 		UpdatedBy: update.UpdatedBy, CreatedAt: created, UpdatedAt: updated,
+		RecipeUrl: create.RecipeUrl, // UpdateDinner leaves the recipe link
 	}
 	if got != want {
 		t.Fatalf("UpdateDinner returned %+v, want %+v", got, want)
@@ -227,6 +238,17 @@ func TestDinners(t *testing.T) {
 	_, err = q.SetDinnerFavorite(ctx, db.SetDinnerFavoriteParams{ID: "missing", IsFavorite: 1, UpdatedAt: updated})
 	mustNoRows(t, "SetDinnerFavorite missing", err)
 
+	for _, wantFav := range []int64{1, 0} {
+		got, err = q.ToggleDinnerFavorite(ctx, db.ToggleDinnerFavoriteParams{
+			ID: create.ID, UpdatedBy: str("alex@example.com"), UpdatedAt: updated,
+		})
+		if err != nil || got.IsFavorite != wantFav || got.UpdatedBy != str("alex@example.com") {
+			t.Fatalf("ToggleDinnerFavorite = %+v, %v; want is_favorite %d", got, err, wantFav)
+		}
+	}
+	_, err = q.ToggleDinnerFavorite(ctx, db.ToggleDinnerFavoriteParams{ID: "missing", UpdatedAt: updated})
+	mustNoRows(t, "ToggleDinnerFavorite missing", err)
+
 	const archivedAt = "2026-10-05T12:00:00.000Z"
 	got, err = q.ArchiveDinner(ctx, db.ArchiveDinnerParams{
 		ID: create.ID, UpdatedBy: str("alex@example.com"), UpdatedAt: archivedAt,
@@ -240,6 +262,15 @@ func TestDinners(t *testing.T) {
 	}
 	assertIDs(t, "archived", listIDs("archived"), create.ID)
 	assertIDs(t, "tried after archive", listIDs("tried"))
+	unarchived, err := q.ListUnarchivedDinners(ctx)
+	if err != nil {
+		t.Fatalf("ListUnarchivedDinners: %v", err)
+	}
+	var unarchivedIDs []string
+	for _, d := range unarchived {
+		unarchivedIDs = append(unarchivedIDs, d.Dinner.ID)
+	}
+	assertIDs(t, "unarchived", unarchivedIDs, other.ID, third.ID)
 	_, err = q.ArchiveDinner(ctx, db.ArchiveDinnerParams{ID: "missing", UpdatedAt: archivedAt})
 	mustNoRows(t, "ArchiveDinner missing", err)
 }

internal/db/dinners.sql.go

@@ -16,7 +16,7 @@ SET status = 'archived',
 	updated_by = ?,
 	updated_at = ?
 WHERE id = ?
-RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
 `
 
 type ArchiveDinnerParams struct {
@@ -46,21 +46,37 @@ func (q *Queries) ArchiveDinner(ctx context.Context, arg ArchiveDinnerParams) (D
 		&i.UpdatedBy,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
 	)
 	return i, err
 }
 
+const countRegularDinners = `-- name: CountRegularDinners :one
+SELECT COUNT(*) FROM dinners
+WHERE status = 'regular'
+`
+
+// How many Regulars the household has; archived dinners are not counted.
+func (q *Queries) CountRegularDinners(ctx context.Context) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countRegularDinners)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
 const createDinner = `-- name: CreateDinner :one
 INSERT INTO dinners (
 	id, name, normalized_name, status, origin, method, minutes_total,
-	difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status,
-	updated_by, created_at, updated_at
+	difficulty, cuisine, is_favorite, recipe_id, recipe_url, photo_id,
+	grounding_status, updated_by, created_at, updated_at
 ) VALUES (
 	?, ?, ?, ?, ?, ?, ?,
 	?, ?, ?, ?, ?, ?,
-	?, ?, ?
+	?, ?, ?, ?
 )
-RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
 `
 
 type CreateDinnerParams struct {
@@ -75,6 +91,7 @@ type CreateDinnerParams struct {
 	Cuisine         sql.NullString
 	IsFavorite      int64
 	RecipeID        sql.NullString
+	RecipeUrl       sql.NullString
 	PhotoID         sql.NullString
 	GroundingStatus string
 	UpdatedBy       sql.NullString
@@ -95,6 +112,7 @@ func (q *Queries) CreateDinner(ctx context.Context, arg CreateDinnerParams) (Din
 		arg.Cuisine,
 		arg.IsFavorite,
 		arg.RecipeID,
+		arg.RecipeUrl,
 		arg.PhotoID,
 		arg.GroundingStatus,
 		arg.UpdatedBy,
@@ -119,12 +137,85 @@ func (q *Queries) CreateDinner(ctx context.Context, arg CreateDinnerParams) (Din
 		&i.UpdatedBy,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
 	)
 	return i, err
 }
 
+const failOrphanedPendingDinnerGroundings = `-- name: FailOrphanedPendingDinnerGroundings :execrows
+UPDATE dinners
+SET grounding_status = 'failed',
+	grounding_error = ?1,
+	updated_at = ?2
+WHERE grounding_status = 'pending'
+	AND status <> 'archived'
+	AND NOT EXISTS (
+		SELECT 1 FROM jobs
+		WHERE jobs.kind = ?3
+			AND jobs.status IN ('queued', 'running')
+			AND json_extract(jobs.payload, '$.dinner_id') = dinners.id
+			AND json_extract(jobs.payload, '$.revision') = dinners.grounding_revision
+	)
+`
+
+type FailOrphanedPendingDinnerGroundingsParams struct {
+	GroundingError sql.NullString
+	UpdatedAt      string
+	Kind           string
+}
+
+// Fails every unarchived dinner still pending whose grounding job for its
+// current grounding_revision is no longer queued or running: the process
+// stopped before the job, or before its handler recorded a result. An
+// archived dinner is left as it is; archiving stopped its grounding. Run at
+// boot, after the job runner fails the jobs a previous process left running.
+func (q *Queries) FailOrphanedPendingDinnerGroundings(ctx context.Context, arg FailOrphanedPendingDinnerGroundingsParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failOrphanedPendingDinnerGroundings, arg.GroundingError, arg.UpdatedAt, arg.Kind)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const failPendingDinnerGrounding = `-- name: FailPendingDinnerGrounding :execrows
+UPDATE dinners
+SET grounding_status = 'failed',
+	grounding_error = ?,
+	updated_at = ?
+WHERE id = ?
+	AND status <> 'archived'
+	AND grounding_status = 'pending'
+	AND grounding_revision = ?
+`
+
+type FailPendingDinnerGroundingParams struct {
+	GroundingError    sql.NullString
+	UpdatedAt         string
+	ID                string
+	GroundingRevision int64
+}
+
+// Records why the background grounding of an unarchived dinner still
+// pending at the grounding_revision it was grounded for failed; a dinner
+// grounded some other way, renamed or archived meanwhile is left as it is
+// (0 rows).
+func (q *Queries) FailPendingDinnerGrounding(ctx context.Context, arg FailPendingDinnerGroundingParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failPendingDinnerGrounding,
+		arg.GroundingError,
+		arg.UpdatedAt,
+		arg.ID,
+		arg.GroundingRevision,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const getDinner = `-- name: GetDinner :one
-SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at FROM dinners
+SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision FROM dinners
 WHERE id = ?
 `
 
@@ -148,12 +239,164 @@ func (q *Queries) GetDinner(ctx context.Context, id string) (Dinner, error) {
 		&i.UpdatedBy,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
 	)
 	return i, err
 }
 
+const groundDinner = `-- name: GroundDinner :one
+UPDATE dinners
+SET recipe_id = ?1,
+	recipe_url = NULL,
+	photo_id = ?2,
+	method = CASE WHEN method IS ?3
+		THEN ?4 ELSE method END,
+	minutes_total = CASE WHEN minutes_total IS ?5
+		THEN ?6 ELSE minutes_total END,
+	difficulty = CASE WHEN difficulty IS ?7
+		THEN ?8 ELSE difficulty END,
+	grounding_status = ?9,
+	grounding_error = NULL,
+	updated_by = ?10,
+	updated_at = ?11
+WHERE id = ?12
+	AND status <> 'archived'
+	AND name = ?13
+	AND normalized_name = ?14
+	AND grounding_status = ?15
+	AND grounding_revision = ?16
+	AND recipe_id IS ?17
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
+`
+
+type GroundDinnerParams struct {
+	RecipeID                  sql.NullString
+	PhotoID                   sql.NullString
+	ObservedMethod            sql.NullString
+	Method                    sql.NullString
+	ObservedMinutesTotal      sql.NullInt64
+	MinutesTotal              sql.NullInt64
+	ObservedDifficulty        sql.NullString
+	Difficulty                sql.NullString
+	GroundingStatus           string
+	UpdatedBy                 sql.NullString
+	UpdatedAt                 string
+	ID                        string
+	ObservedName              string
+	ObservedNormalizedName    string
+	ObservedGroundingStatus   string
+	ObservedGroundingRevision int64
+	ObservedRecipeID          sql.NullString
+}
+
+// Records a dinner's grounding by hand (grounded or manual) and clears any
+// grounding_error and pasted recipe_url: the recipe chosen replaces the
+// link. It writes only an unarchived dinner still as it was observed
+// before grounding (same name, normalized_name, grounding_status,
+// grounding_revision and recipe_id), so a dinner renamed, archived or
+// grounded some other way meanwhile is left as it is. That dinner, or an
+// unknown id, returns sql.ErrNoRows. A method, minutes_total or difficulty
+// no longer as observed is kept: a member edited it while it was grounding.
+func (q *Queries) GroundDinner(ctx context.Context, arg GroundDinnerParams) (Dinner, error) {
+	row := q.db.QueryRowContext(ctx, groundDinner,
+		arg.RecipeID,
+		arg.PhotoID,
+		arg.ObservedMethod,
+		arg.Method,
+		arg.ObservedMinutesTotal,
+		arg.MinutesTotal,
+		arg.ObservedDifficulty,
+		arg.Difficulty,
+		arg.GroundingStatus,
+		arg.UpdatedBy,
+		arg.UpdatedAt,
+		arg.ID,
+		arg.ObservedName,
+		arg.ObservedNormalizedName,
+		arg.ObservedGroundingStatus,
+		arg.ObservedGroundingRevision,
+		arg.ObservedRecipeID,
+	)
+	var i Dinner
+	err := row.Scan(
+		&i.ID,
+		&i.Name,
+		&i.NormalizedName,
+		&i.Status,
+		&i.Origin,
+		&i.Method,
+		&i.MinutesTotal,
+		&i.Difficulty,
+		&i.Cuisine,
+		&i.IsFavorite,
+		&i.RecipeID,
+		&i.PhotoID,
+		&i.GroundingStatus,
+		&i.UpdatedBy,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
+	)
+	return i, err
+}
+
+const groundPendingDinner = `-- name: GroundPendingDinner :execrows
+UPDATE dinners
+SET recipe_id = ?1,
+	recipe_url = NULL,
+	photo_id = ?2,
+	method = COALESCE(method, ?3),
+	minutes_total = COALESCE(minutes_total, ?4),
+	difficulty = COALESCE(difficulty, ?5),
+	grounding_status = 'grounded',
+	grounding_error = NULL,
+	updated_at = ?6
+WHERE id = ?7
+	AND status <> 'archived'
+	AND grounding_status = 'pending'
+	AND grounding_revision = ?8
+`
+
+type GroundPendingDinnerParams struct {
+	RecipeID          sql.NullString
+	PhotoID           sql.NullString
+	Method            sql.NullString
+	MinutesTotal      sql.NullInt64
+	Difficulty        sql.NullString
+	UpdatedAt         string
+	ID                string
+	GroundingRevision int64
+}
+
+// Records the background grounding of an unarchived dinner still pending at
+// the grounding_revision it was grounded for; a dinner grounded some other
+// way, renamed or archived meanwhile is left as it is (0 rows). A method,
+// minutes_total or difficulty already set is kept: a pending dinner has
+// them only when a member edited them while it was grounding. Like
+// GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
+func (q *Queries) GroundPendingDinner(ctx context.Context, arg GroundPendingDinnerParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, groundPendingDinner,
+		arg.RecipeID,
+		arg.PhotoID,
+		arg.Method,
+		arg.MinutesTotal,
+		arg.Difficulty,
+		arg.UpdatedAt,
+		arg.ID,
+		arg.GroundingRevision,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const listDinnersByStatus = `-- name: ListDinnersByStatus :many
-SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at FROM dinners
+SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision FROM dinners
 WHERE status = ?
 ORDER BY normalized_name, id
 `
@@ -184,6 +427,68 @@ func (q *Queries) ListDinnersByStatus(ctx context.Context, status string) ([]Din
 			&i.UpdatedBy,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.RecipeUrl,
+			&i.GroundingError,
+			&i.GroundingRevision,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listUnarchivedDinners = `-- name: ListUnarchivedDinners :many
+SELECT dinners.id, dinners.name, dinners.normalized_name, dinners.status, dinners.origin, dinners.method, dinners.minutes_total, dinners.difficulty, dinners.cuisine, dinners.is_favorite, dinners.recipe_id, dinners.photo_id, dinners.grounding_status, dinners.updated_by, dinners.created_at, dinners.updated_at, dinners.recipe_url, dinners.grounding_error, dinners.grounding_revision, recipes.source_url AS recipe_source_url
+FROM dinners
+LEFT JOIN recipes ON recipes.id = dinners.recipe_id
+WHERE dinners.status <> 'archived'
+ORDER BY dinners.id
+`
+
+type ListUnarchivedDinnersRow struct {
+	Dinner          Dinner
+	RecipeSourceUrl sql.NullString
+}
+
+// Every dinner a new or renamed dinner must not repeat, with the
+// source_url of the recipe it is grounded in (NULL while it has none).
+func (q *Queries) ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDinnersRow, error) {
+	rows, err := q.db.QueryContext(ctx, listUnarchivedDinners)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListUnarchivedDinnersRow
+	for rows.Next() {
+		var i ListUnarchivedDinnersRow
+		if err := rows.Scan(
+			&i.Dinner.ID,
+			&i.Dinner.Name,
+			&i.Dinner.NormalizedName,
+			&i.Dinner.Status,
+			&i.Dinner.Origin,
+			&i.Dinner.Method,
+			&i.Dinner.MinutesTotal,
+			&i.Dinner.Difficulty,
+			&i.Dinner.Cuisine,
+			&i.Dinner.IsFavorite,
+			&i.Dinner.RecipeID,
+			&i.Dinner.PhotoID,
+			&i.Dinner.GroundingStatus,
+			&i.Dinner.UpdatedBy,
+			&i.Dinner.CreatedAt,
+			&i.Dinner.UpdatedAt,
+			&i.Dinner.RecipeUrl,
+			&i.Dinner.GroundingError,
+			&i.Dinner.GroundingRevision,
+			&i.RecipeSourceUrl,
 		); err != nil {
 			return nil, err
 		}
@@ -204,7 +509,7 @@ SET is_favorite = ?,
 	updated_by = ?,
 	updated_at = ?
 WHERE id = ?
-RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
 `
 
 type SetDinnerFavoriteParams struct {
@@ -240,6 +545,52 @@ func (q *Queries) SetDinnerFavorite(ctx context.Context, arg SetDinnerFavoritePa
 		&i.UpdatedBy,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
+	)
+	return i, err
+}
+
+const toggleDinnerFavorite = `-- name: ToggleDinnerFavorite :one
+UPDATE dinners
+SET is_favorite = 1 - is_favorite,
+	updated_by = ?,
+	updated_at = ?
+WHERE id = ?
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
+`
+
+type ToggleDinnerFavoriteParams struct {
+	UpdatedBy sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// An unknown id returns sql.ErrNoRows.
+func (q *Queries) ToggleDinnerFavorite(ctx context.Context, arg ToggleDinnerFavoriteParams) (Dinner, error) {
+	row := q.db.QueryRowContext(ctx, toggleDinnerFavorite, arg.UpdatedBy, arg.UpdatedAt, arg.ID)
+	var i Dinner
+	err := row.Scan(
+		&i.ID,
+		&i.Name,
+		&i.NormalizedName,
+		&i.Status,
+		&i.Origin,
+		&i.Method,
+		&i.MinutesTotal,
+		&i.Difficulty,
+		&i.Cuisine,
+		&i.IsFavorite,
+		&i.RecipeID,
+		&i.PhotoID,
+		&i.GroundingStatus,
+		&i.UpdatedBy,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
 	)
 	return i, err
 }
@@ -255,29 +606,33 @@ SET name = ?,
 	difficulty = ?,
 	cuisine = ?,
 	recipe_id = ?,
+	recipe_url = ?,
 	photo_id = ?,
 	grounding_status = ?,
+	grounding_revision = ?,
 	updated_by = ?,
 	updated_at = ?
 WHERE id = ?
-RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at
+RETURNING id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision
 `
 
 type UpdateDinnerParams struct {
-	Name            string
-	NormalizedName  string
-	Status          string
-	Origin          string
-	Method          sql.NullString
-	MinutesTotal    sql.NullInt64
-	Difficulty      sql.NullString
-	Cuisine         sql.NullString
-	RecipeID        sql.NullString
-	PhotoID         sql.NullString
-	GroundingStatus string
-	UpdatedBy       sql.NullString
-	UpdatedAt       string
-	ID              string
+	Name              string
+	NormalizedName    string
+	Status            string
+	Origin            string
+	Method            sql.NullString
+	MinutesTotal      sql.NullInt64
+	Difficulty        sql.NullString
+	Cuisine           sql.NullString
+	RecipeID          sql.NullString
+	RecipeUrl         sql.NullString
+	PhotoID           sql.NullString
+	GroundingStatus   string
+	GroundingRevision int64
+	UpdatedBy         sql.NullString
+	UpdatedAt         string
+	ID                string
 }
 
 // An unknown id returns sql.ErrNoRows.
@@ -292,8 +647,10 @@ func (q *Queries) UpdateDinner(ctx context.Context, arg UpdateDinnerParams) (Din
 		arg.Difficulty,
 		arg.Cuisine,
 		arg.RecipeID,
+		arg.RecipeUrl,
 		arg.PhotoID,
 		arg.GroundingStatus,
+		arg.GroundingRevision,
 		arg.UpdatedBy,
 		arg.UpdatedAt,
 		arg.ID,
@@ -316,6 +673,9 @@ func (q *Queries) UpdateDinner(ctx context.Context, arg UpdateDinnerParams) (Din
 		&i.UpdatedBy,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.RecipeUrl,
+		&i.GroundingError,
+		&i.GroundingRevision,
 	)
 	return i, err
 }

internal/db/models.go

@@ -51,22 +51,25 @@ type ChatSetting struct {
 }
 
 type Dinner struct {
-	ID              string
-	Name            string
-	NormalizedName  string
-	Status          string
-	Origin          string
-	Method          sql.NullString
-	MinutesTotal    sql.NullInt64
-	Difficulty      sql.NullString
-	Cuisine         sql.NullString
-	IsFavorite      int64
-	RecipeID        sql.NullString
-	PhotoID         sql.NullString
-	GroundingStatus string
-	UpdatedBy       sql.NullString
-	CreatedAt       string
-	UpdatedAt       string
+	ID                string
+	Name              string
+	NormalizedName    string
+	Status            string
+	Origin            string
+	Method            sql.NullString
+	MinutesTotal      sql.NullInt64
+	Difficulty        sql.NullString
+	Cuisine           sql.NullString
+	IsFavorite        int64
+	RecipeID          sql.NullString
+	PhotoID           sql.NullString
+	GroundingStatus   string
+	UpdatedBy         sql.NullString
+	CreatedAt         string
+	UpdatedAt         string
+	RecipeUrl         sql.NullString
+	GroundingError    sql.NullString
+	GroundingRevision int64
 }
 
 type HouseholdSetting struct {
@@ -181,6 +184,10 @@ type Recipe struct {
 	FetchedAt    string
 	CreatedAt    string
 	UpdatedAt    string
+	PhotoID      sql.NullString
+	Method       sql.NullString
+	Difficulty   sql.NullString
+	MinutesTotal sql.NullInt64
 }
 
 type RecipeIngredient struct {
@@ -197,12 +204,13 @@ type RecipeIngredient struct {
 }
 
 type RecipeSearchSetting struct {
-	ID        int64
-	Provider  string
-	BaseUrl   sql.NullString
-	ApiKeyCt  []byte
-	CreatedAt string
-	UpdatedAt string
+	ID          int64
+	Provider    string
+	BaseUrl     sql.NullString
+	ApiKeyCt    []byte
+	CreatedAt   string
+	UpdatedAt   string
+	ApiKeyLast4 sql.NullString
 }
 
 type RecipeStep struct {

internal/db/querier.go

@@ -21,9 +21,14 @@ type Querier interface {
 	// Drops references to the runs created before the cutoff, so the purge
 	// can delete them.
 	ClearWeekPlanAIRunsBefore(ctx context.Context, cutoff string) (int64, error)
+	// How many Regulars the household has; archived dinners are not counted.
+	CountRegularDinners(ctx context.Context) (int64, error)
 	CreateAIRun(ctx context.Context, arg CreateAIRunParams) error
 	CreateDinner(ctx context.Context, arg CreateDinnerParams) (Dinner, error)
 	CreateJob(ctx context.Context, arg CreateJobParams) error
+	// A recipe the household typed in. Its source_url is a mealquest:manual:
+	// URN rather than a page, so it never matches a fetched page.
+	CreateManualRecipe(ctx context.Context, arg CreateManualRecipeParams) (Recipe, error)
 	CreatePhoto(ctx context.Context, arg CreatePhotoParams) (Photo, error)
 	CreateRecipeIngredient(ctx context.Context, arg CreateRecipeIngredientParams) error
 	CreateRecipeStep(ctx context.Context, arg CreateRecipeStepParams) error
@@ -31,6 +36,17 @@ type Querier interface {
 	DeleteRecipeIngredients(ctx context.Context, recipeID string) error
 	DeleteRecipeSteps(ctx context.Context, recipeID string) error
 	FailJob(ctx context.Context, arg FailJobParams) (int64, error)
+	// Fails every unarchived dinner still pending whose grounding job for its
+	// current grounding_revision is no longer queued or running: the process
+	// stopped before the job, or before its handler recorded a result. An
+	// archived dinner is left as it is; archiving stopped its grounding. Run at
+	// boot, after the job runner fails the jobs a previous process left running.
+	FailOrphanedPendingDinnerGroundings(ctx context.Context, arg FailOrphanedPendingDinnerGroundingsParams) (int64, error)
+	// Records why the background grounding of an unarchived dinner still
+	// pending at the grounding_revision it was grounded for failed; a dinner
+	// grounded some other way, renamed or archived meanwhile is left as it is
+	// (0 rows).
+	FailPendingDinnerGrounding(ctx context.Context, arg FailPendingDinnerGroundingParams) (int64, error)
 	// Fails every job left running, at boot before any worker starts.
 	FailRunningJobs(ctx context.Context, arg FailRunningJobsParams) (int64, error)
 	// Returns sql.ErrNoRows until the row exists.
@@ -51,6 +67,22 @@ type Querier interface {
 	GetRecipeBySourceURL(ctx context.Context, sourceUrl string) (Recipe, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetRecipeSearchSettings(ctx context.Context) (RecipeSearchSetting, error)
+	// Records a dinner's grounding by hand (grounded or manual) and clears any
+	// grounding_error and pasted recipe_url: the recipe chosen replaces the
+	// link. It writes only an unarchived dinner still as it was observed
+	// before grounding (same name, normalized_name, grounding_status,
+	// grounding_revision and recipe_id), so a dinner renamed, archived or
+	// grounded some other way meanwhile is left as it is. That dinner, or an
+	// unknown id, returns sql.ErrNoRows. A method, minutes_total or difficulty
+	// no longer as observed is kept: a member edited it while it was grounding.
+	GroundDinner(ctx context.Context, arg GroundDinnerParams) (Dinner, error)
+	// Records the background grounding of an unarchived dinner still pending at
+	// the grounding_revision it was grounded for; a dinner grounded some other
+	// way, renamed or archived meanwhile is left as it is (0 rows). A method,
+	// minutes_total or difficulty already set is kept: a pending dinner has
+	// them only when a member edited them while it was grounding. Like
+	// GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
+	GroundPendingDinner(ctx context.Context, arg GroundPendingDinnerParams) (int64, error)
 	ListDinnersByStatus(ctx context.Context, status string) ([]Dinner, error)
 	// The planned dinners dated from from_date up to but not including
 	// to_date, oldest first. Days with no dinner are left out.
@@ -60,12 +92,17 @@ type Querier interface {
 	ListRecentDeclinedNames(ctx context.Context, limit int64) ([]string, error)
 	ListRecipeIngredients(ctx context.Context, recipeID string) ([]RecipeIngredient, error)
 	ListRecipeSteps(ctx context.Context, recipeID string) ([]RecipeStep, error)
+	// Every dinner a new or renamed dinner must not repeat, with the
+	// source_url of the recipe it is grounded in (NULL while it has none).
+	ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDinnersRow, error)
 	// Stores a partial result of a running job.
 	PublishJobResult(ctx context.Context, arg PublishJobResultParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	SetDinnerFavorite(ctx context.Context, arg SetDinnerFavoriteParams) (Dinner, error)
 	SucceedJob(ctx context.Context, arg SucceedJobParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
+	ToggleDinnerFavorite(ctx context.Context, arg ToggleDinnerFavoriteParams) (Dinner, error)
+	// An unknown id returns sql.ErrNoRows.
 	UpdateDinner(ctx context.Context, arg UpdateDinnerParams) (Dinner, error)
 	// Creates the single row (id 1) or replaces every column except id and
 	// created_at.

internal/db/recipes.sql.go

@@ -10,6 +10,67 @@ import (
 	"database/sql"
 )
 
+const createManualRecipe = `-- name: CreateManualRecipe :one
+INSERT INTO recipes (
+	id, source_url, title, total_minutes, raw_jsonld, method,
+	minutes_total, fetched_at, created_at, updated_at
+) VALUES (
+	?, ?, ?, ?, ?, ?,
+	?, ?, ?, ?
+)
+RETURNING id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at, photo_id, method, difficulty, minutes_total
+`
+
+type CreateManualRecipeParams struct {
+	ID           string
+	SourceUrl    string
+	Title        string
+	TotalMinutes sql.NullInt64
+	RawJsonld    string
+	Method       sql.NullString
+	MinutesTotal sql.NullInt64
+	FetchedAt    string
+	CreatedAt    string
+	UpdatedAt    string
+}
+
+// A recipe the household typed in. Its source_url is a mealquest:manual:
+// URN rather than a page, so it never matches a fetched page.
+func (q *Queries) CreateManualRecipe(ctx context.Context, arg CreateManualRecipeParams) (Recipe, error) {
+	row := q.db.QueryRowContext(ctx, createManualRecipe,
+		arg.ID,
+		arg.SourceUrl,
+		arg.Title,
+		arg.TotalMinutes,
+		arg.RawJsonld,
+		arg.Method,
+		arg.MinutesTotal,
+		arg.FetchedAt,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	var i Recipe
+	err := row.Scan(
+		&i.ID,
+		&i.SourceUrl,
+		&i.SiteName,
+		&i.Title,
+		&i.TotalMinutes,
+		&i.PrepMinutes,
+		&i.CookMinutes,
+		&i.Yield,
+		&i.RawJsonld,
+		&i.FetchedAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.PhotoID,
+		&i.Method,
+		&i.Difficulty,
+		&i.MinutesTotal,
+	)
+	return i, err
+}
+
 const createRecipeIngredient = `-- name: CreateRecipeIngredient :exec
 INSERT INTO recipe_ingredients (
 	id, recipe_id, position, raw_text, name, qty, unit, note,
@@ -99,7 +160,7 @@ func (q *Queries) DeleteRecipeSteps(ctx context.Context, recipeID string) error
 }
 
 const getRecipe = `-- name: GetRecipe :one
-SELECT id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at FROM recipes
+SELECT id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at, photo_id, method, difficulty, minutes_total FROM recipes
 WHERE id = ?
 `
 
@@ -119,12 +180,16 @@ func (q *Queries) GetRecipe(ctx context.Context, id string) (Recipe, error) {
 		&i.FetchedAt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.PhotoID,
+		&i.Method,
+		&i.Difficulty,
+		&i.MinutesTotal,
 	)
 	return i, err
 }
 
 const getRecipeBySourceURL = `-- name: GetRecipeBySourceURL :one
-SELECT id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at FROM recipes
+SELECT id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at, photo_id, method, difficulty, minutes_total FROM recipes
 WHERE source_url = ?
 `
 
@@ -144,6 +209,10 @@ func (q *Queries) GetRecipeBySourceURL(ctx context.Context, sourceUrl string) (R
 		&i.FetchedAt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.PhotoID,
+		&i.Method,
+		&i.Difficulty,
+		&i.MinutesTotal,
 	)
 	return i, err
 }
@@ -227,10 +296,12 @@ func (q *Queries) ListRecipeSteps(ctx context.Context, recipeID string) ([]Recip
 const upsertRecipe = `-- name: UpsertRecipe :one
 INSERT INTO recipes (
 	id, source_url, site_name, title, total_minutes, prep_minutes,
-	cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at
+	cook_minutes, yield, raw_jsonld, photo_id, method, difficulty,
+	minutes_total, fetched_at, created_at, updated_at
 ) VALUES (
 	?, ?, ?, ?, ?, ?,
-	?, ?, ?, ?, ?, ?
+	?, ?, ?, ?, ?, ?,
+	?, ?, ?, ?
 )
 ON CONFLICT (source_url) DO UPDATE SET
 	site_name = excluded.site_name,
@@ -240,9 +311,13 @@ ON CONFLICT (source_url) DO UPDATE SET
 	cook_minutes = excluded.cook_minutes,
 	yield = excluded.yield,
 	raw_jsonld = excluded.raw_jsonld,
+	photo_id = excluded.photo_id,
+	method = excluded.method,
+	difficulty = excluded.difficulty,
+	minutes_total = excluded.minutes_total,
 	fetched_at = excluded.fetched_at,
 	updated_at = excluded.updated_at
-RETURNING id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at
+RETURNING id, source_url, site_name, title, total_minutes, prep_minutes, cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at, photo_id, method, difficulty, minutes_total
 `
 
 type UpsertRecipeParams struct {
@@ -255,6 +330,10 @@ type UpsertRecipeParams struct {
 	CookMinutes  sql.NullInt64
 	Yield        sql.NullString
 	RawJsonld    string
+	PhotoID      sql.NullString
+	Method       sql.NullString
+	Difficulty   sql.NullString
+	MinutesTotal sql.NullInt64
 	FetchedAt    string
 	CreatedAt    string
 	UpdatedAt    string
@@ -275,6 +354,10 @@ func (q *Queries) UpsertRecipe(ctx context.Context, arg UpsertRecipeParams) (Rec
 		arg.CookMinutes,
 		arg.Yield,
 		arg.RawJsonld,
+		arg.PhotoID,
+		arg.Method,
+		arg.Difficulty,
+		arg.MinutesTotal,
 		arg.FetchedAt,
 		arg.CreatedAt,
 		arg.UpdatedAt,
@@ -293,6 +376,10 @@ func (q *Queries) UpsertRecipe(ctx context.Context, arg UpsertRecipeParams) (Rec
 		&i.FetchedAt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.PhotoID,
+		&i.Method,
+		&i.Difficulty,
+		&i.MinutesTotal,
 	)
 	return i, err
 }

internal/db/settings.sql.go

@@ -109,7 +109,7 @@ func (q *Queries) GetIntegrationsGoogle(ctx context.Context) (IntegrationsGoogle
 }
 
 const getRecipeSearchSettings = `-- name: GetRecipeSearchSettings :one
-SELECT id, provider, base_url, api_key_ct, created_at, updated_at FROM recipe_search_settings
+SELECT id, provider, base_url, api_key_ct, created_at, updated_at, api_key_last4 FROM recipe_search_settings
 WHERE id = 1
 `
 
@@ -124,6 +124,7 @@ func (q *Queries) GetRecipeSearchSettings(ctx context.Context) (RecipeSearchSett
 		&i.ApiKeyCt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.ApiKeyLast4,
 	)
 	return i, err
 }
@@ -390,24 +391,26 @@ func (q *Queries) UpsertIntegrationsGoogle(ctx context.Context, arg UpsertIntegr
 
 const upsertRecipeSearchSettings = `-- name: UpsertRecipeSearchSettings :one
 INSERT INTO recipe_search_settings (
-	id, provider, base_url, api_key_ct, created_at, updated_at
+	id, provider, base_url, api_key_ct, api_key_last4, created_at, updated_at
 ) VALUES (
-	1, ?, ?, ?, ?, ?
+	1, ?, ?, ?, ?, ?, ?
 )
 ON CONFLICT (id) DO UPDATE SET
 	provider = excluded.provider,
 	base_url = excluded.base_url,
 	api_key_ct = excluded.api_key_ct,
+	api_key_last4 = excluded.api_key_last4,
 	updated_at = excluded.updated_at
-RETURNING id, provider, base_url, api_key_ct, created_at, updated_at
+RETURNING id, provider, base_url, api_key_ct, created_at, updated_at, api_key_last4
 `
 
 type UpsertRecipeSearchSettingsParams struct {
-	Provider  string
-	BaseUrl   sql.NullString
-	ApiKeyCt  []byte
-	CreatedAt string
-	UpdatedAt string
+	Provider    string
+	BaseUrl     sql.NullString
+	ApiKeyCt    []byte
+	ApiKeyLast4 sql.NullString
+	CreatedAt   string
+	UpdatedAt   string
 }
 
 // Creates the single row (id 1) or replaces every column except id and
@@ -417,6 +420,7 @@ func (q *Queries) UpsertRecipeSearchSettings(ctx context.Context, arg UpsertReci
 		arg.Provider,
 		arg.BaseUrl,
 		arg.ApiKeyCt,
+		arg.ApiKeyLast4,
 		arg.CreatedAt,
 		arg.UpdatedAt,
 	)
@@ -428,6 +432,7 @@ func (q *Queries) UpsertRecipeSearchSettings(ctx context.Context, arg UpsertReci
 		&i.ApiKeyCt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.ApiKeyLast4,
 	)
 	return i, err
 }

internal/dinners/dinners.go

@@ -0,0 +1,577 @@
+// Package dinners keeps the household's dinners: adding Regulars by name or
+// recipe link, listing Regulars and the Quest log, editing, archiving and
+// favoriting, and grounding each dinner in a recipe. Names are deduplicated with the harness's dinner-name rules,
+// so the Regulars the household types and the Side quests the AI suggests
+// are compared the same way.
+package dinners
+
+import (
+	"context"
+	"crypto/rand"
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+	"math"
+	"net/url"
+	"slices"
+	"strings"
+	"sync"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Dinner statuses (the dinners.status column).
+const (
+	StatusSuggested = "suggested"
+	StatusQuestLog  = "quest_log"
+	StatusTried     = "tried"
+	StatusRegular   = "regular"
+	StatusArchived  = "archived"
+)
+
+// Limits on what a member may enter.
+const (
+	MaxNameChars   = 120
+	MaxRecipeURL   = 2048
+	MaxMinutes     = 1440 // a day; a crock-pot dinner fits
+	photoListWidth = 400  // the stored photo size lists show
+)
+
+// Methods and Difficulties are the values the dinners table allows.
+var (
+	Methods      = []string{"stovetop", "oven", "crockpot", "grill", "other"}
+	Difficulties = []string{"easy", "medium", "hard"}
+)
+
+// listable are the statuses List answers for.
+var listable = []string{StatusRegular, StatusQuestLog}
+
+// ErrNotFound is returned for an unknown dinner id.
+var ErrNotFound = errors.New("dinner not found")
+
+// Dinner is a dinner as the API shows it. It has no recipe_url: a pasted
+// link may carry a personal token, so it stays in the database for
+// grounding and never leaves the server.
+type Dinner struct {
+	ID              string  `json:"id"`
+	Name            string  `json:"name"`
+	Status          string  `json:"status"`
+	Origin          string  `json:"origin"`
+	Method          *string `json:"method"`
+	MinutesTotal    *int64  `json:"minutes_total"`
+	Difficulty      *string `json:"difficulty"`
+	Cuisine         *string `json:"cuisine"`
+	IsFavorite      bool    `json:"is_favorite"`
+	RecipeID        *string `json:"recipe_id"`
+	PhotoURL        *string `json:"photo_url"`
+	GroundingStatus string  `json:"grounding_status"`
+	// GroundingError is why grounding failed, one of the Reason codes;
+	// null unless GroundingStatus is failed.
+	GroundingError *string `json:"grounding_error"`
+	UpdatedBy      *string `json:"updated_by"`
+	CreatedAt      string  `json:"created_at"`
+	UpdatedAt      string  `json:"updated_at"`
+}
+
+// NewRegular is a Regular to add: its Name, which the household always
+// gives, and optionally the RecipeURL to ground it in. The name is never
+// taken from the link: a pasted link may carry a personal token anywhere in
+// it, and the name is shown in every dinner response.
+type NewRegular struct {
+	Name      *string
+	RecipeURL *string
+}
+
+// Patch edits a dinner. Nil fields are left as they are.
+type Patch struct {
+	Name         *string
+	Method       *string
+	MinutesTotal *int
+	Difficulty   *string
+}
+
+// Problem is one invalid field, named by its JSON key.
+type Problem struct {
+	Field  string
+	Reason string
+}
+
+// ValidationError lists every invalid field of a request.
+type ValidationError struct {
+	Problems []Problem
+}
+
+func (e *ValidationError) Error() string {
+	parts := make([]string, len(e.Problems))
+	for i, p := range e.Problems {
+		parts[i] = p.Field + ": " + p.Reason
+	}
+	return "invalid dinner: " + strings.Join(parts, "; ")
+}
+
+func invalid(field, reason string) *ValidationError {
+	return &ValidationError{Problems: []Problem{{Field: field, Reason: reason}}}
+}
+
+// DuplicateError is returned when a new or renamed dinner repeats an
+// unarchived one: its name is harness.Similar, or it has the same recipe
+// link.
+type DuplicateError struct {
+	Existing Dinner
+}
+
+func (e *DuplicateError) Error() string {
+	return fmt.Sprintf("%q is already a dinner (%s)", e.Existing.Name, e.Existing.Status)
+}
+
+// Service reads and changes dinners.
+type Service struct {
+	st        *store.Store
+	grounder  *recipes.Grounder
+	logger    *slog.Logger
+	groundJob *jobs.Kind[GroundJob]
+
+	// groundingsMu guards groundings: the KindGroundDinner jobs running,
+	// by dinner id, so archiving or renaming a dinner can stop them.
+	groundingsMu sync.Mutex
+	groundings   map[string]map[*runningGrounding]struct{}
+
+	// offerKey keys the candidate ids Candidates offers, so they are
+	// opaque and stable for this process.
+	offerKey []byte
+	// offersMu guards offers and offerSearches. offers holds, by dinner
+	// id, the candidates last offered by Candidates until they expire, so
+	// a candidate id is resolved here and its URL never leaves the server.
+	// offerSearches holds the Candidates searches running, by dinner id,
+	// so clearing a dinner's offers keeps them from storing stale ones.
+	offersMu      sync.Mutex
+	offers        map[string]*offerSet
+	offerSearches map[string]map[*offerSearch]struct{}
+}
+
+// NewService returns a service over st that grounds dinners with grounder
+// and registers the KindGroundDinner job on runner, which must not have
+// started yet.
+func NewService(st *store.Store, grounder *recipes.Grounder, runner *jobs.Runner, logger *slog.Logger) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("dinners: nil store")
+	case grounder == nil:
+		return nil, errors.New("dinners: nil grounder")
+	case runner == nil:
+		return nil, errors.New("dinners: nil job runner")
+	case logger == nil:
+		return nil, errors.New("dinners: nil logger")
+	}
+	s := &Service{st: st, grounder: grounder, logger: logger, groundings: make(map[string]map[*runningGrounding]struct{}), offerKey: make([]byte, 32), offers: make(map[string]*offerSet), offerSearches: make(map[string]map[*offerSearch]struct{})}
+	rand.Read(s.offerKey) // never fails: it crashes the program instead
+	kind, err := jobs.Register(runner, KindGroundDinner, s.runGroundJob, Reasons...)
+	if err != nil {
+		return nil, err
+	}
+	s.groundJob = kind
+	return s, nil
+}
+
+// Created is a new Regular with the id of the job grounding it, which is
+// nil when the job could not be enqueued and the dinner's grounding is
+// failed instead.
+type Created struct {
+	Dinner
+	GroundingJobID *string `json:"grounding_job_id"`
+}
+
+// CreateRegular adds a Regular named r.Name, keeping r.RecipeURL for
+// grounding when given, with status and origin regular and grounding_status
+// pending, recording updatedBy, and enqueues the KindGroundDinner job that grounds it. It returns without
+// waiting for the job. A name repeating an unarchived dinner is a
+// *DuplicateError. When the job cannot be enqueued, the stored dinner is
+// returned with grounding_status failed (ReasonGroundingError) and no job
+// id, so the household can fix its recipe by hand.
+func (s *Service) CreateRegular(ctx context.Context, r NewRegular, updatedBy string) (Created, error) {
+	d, err := s.createRegular(ctx, r, updatedBy)
+	if err != nil {
+		return Created{}, err
+	}
+	jobID, err := s.enqueueGrounding(ctx, d.ID, d.GroundingRevision)
+	if err != nil {
+		return Created{}, err
+	}
+	if jobID == nil {
+		row, err := db.New(s.st.Reader).GetDinner(context.WithoutCancel(ctx), d.ID)
+		if err != nil {
+			return Created{}, fmt.Errorf("dinners: read %s: %w", d.ID, err)
+		}
+		return Created{Dinner: fromRow(row)}, nil
+	}
+	return Created{Dinner: fromRow(d), GroundingJobID: jobID}, nil
+}
+
+// enqueueGrounding enqueues the KindGroundDinner job for pending dinner id
+// at grounding_revision revision and returns its id. When the job cannot be
+// enqueued, the dinner's grounding is failed with ReasonGroundingError, so
+// it is not left pending with no job, and the id is nil.
+func (s *Service) enqueueGrounding(ctx context.Context, id string, revision int64) (*string, error) {
+	jobID, err := s.groundJob.Enqueue(ctx, GroundJob{DinnerID: id, Revision: revision})
+	if err == nil {
+		return &jobID, nil
+	}
+	// The error is a database error, never a dependency's text.
+	s.logger.ErrorContext(ctx, "dinner grounding not enqueued", "dinner_id", id, "error", err)
+	if _, err := db.New(s.st.Writer).FailPendingDinnerGrounding(context.WithoutCancel(ctx), db.FailPendingDinnerGroundingParams{
+		GroundingError:    sql.NullString{String: ReasonGroundingError, Valid: true},
+		UpdatedAt:         store.Now().String(),
+		ID:                id,
+		GroundingRevision: revision,
+	}); err != nil {
+		return nil, fmt.Errorf("dinners: record failed grounding of %s: %w", id, err)
+	}
+	return nil, nil
+}
+
+func (s *Service) createRegular(ctx context.Context, r NewRegular, updatedBy string) (db.Dinner, error) {
+	if updatedBy == "" {
+		return db.Dinner{}, errors.New("dinners: create: no member to record as updated_by")
+	}
+	if r.Name == nil {
+		return db.Dinner{}, invalid("name", "give the dinner's name, with or without a recipe_url")
+	}
+	name, err := checkName(*r.Name)
+	if err != nil {
+		return db.Dinner{}, err
+	}
+	var recipeURL sql.NullString
+	if r.RecipeURL != nil {
+		u, err := checkRecipeURL(*r.RecipeURL)
+		if err != nil {
+			return db.Dinner{}, err
+		}
+		recipeURL = sql.NullString{String: u.String(), Valid: true}
+	}
+
+	var row db.Dinner
+	err = s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		if err := checkUnique(ctx, q, "", name, recipeURL); err != nil {
+			return err
+		}
+		now := store.Now().String()
+		var err error
+		row, err = q.CreateDinner(ctx, db.CreateDinnerParams{
+			ID:              store.NewID(),
+			Name:            name,
+			NormalizedName:  harness.Normalize(name),
+			Status:          StatusRegular,
+			Origin:          "regular",
+			RecipeUrl:       recipeURL,
+			GroundingStatus: "pending",
+			UpdatedBy:       sql.NullString{String: updatedBy, Valid: true},
+			CreatedAt:       now,
+			UpdatedAt:       now,
+		})
+		if err != nil {
+			return fmt.Errorf("dinners: create: %w", err)
+		}
+		return nil
+	})
+	if err != nil {
+		return db.Dinner{}, err
+	}
+	return row, nil
+}
+
+// List returns the dinners with status, which must be regular or
+// quest_log, ordered by normalized name.
+func (s *Service) List(ctx context.Context, status string) ([]Dinner, error) {
+	if !slices.Contains(listable, status) {
+		return nil, invalid("status", "must be one of "+strings.Join(listable, ", "))
+	}
+	rows, err := db.New(s.st.Reader).ListDinnersByStatus(ctx, status)
+	if err != nil {
+		return nil, fmt.Errorf("dinners: list %s: %w", status, err)
+	}
+	out := make([]Dinner, len(rows))
+	for i, row := range rows {
+		out[i] = fromRow(row)
+	}
+	return out, nil
+}
+
+// Update applies p to dinner id, recording updatedBy. An invalid patch is a
+// *ValidationError and a new name repeating another unarchived dinner a
+// *DuplicateError; either changes nothing. Renaming a dinner raises its
+// grounding_revision and drops the candidates offered for its old name:
+// each was offered at an earlier revision, so none of them grounds it.
+// Renaming a dinner still pending also enqueues a fresh KindGroundDinner
+// job that grounds the new name, and clears its recipe_url when the
+// normalized name changes: a job queued or running for the old name or
+// link carries the old revision, so it can no longer write the dinner, and
+// one running is stopped.
+func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy string) (Dinner, error) {
+	if updatedBy == "" {
+		return Dinner{}, errors.New("dinners: update: no member to record as updated_by")
+	}
+	name, err := p.validate()
+	if err != nil {
+		return Dinner{}, err
+	}
+
+	var row db.Dinner
+	var renamed, regrounding bool
+	err = s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetDinner(ctx, id)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("dinners: read %s: %w", id, err)
+		}
+		params := db.UpdateDinnerParams{
+			ID:                cur.ID,
+			Name:              cur.Name,
+			NormalizedName:    cur.NormalizedName,
+			Status:            cur.Status,
+			Origin:            cur.Origin,
+			Method:            cur.Method,
+			MinutesTotal:      cur.MinutesTotal,
+			Difficulty:        cur.Difficulty,
+			Cuisine:           cur.Cuisine,
+			RecipeID:          cur.RecipeID,
+			RecipeUrl:         cur.RecipeUrl,
+			PhotoID:           cur.PhotoID,
+			GroundingStatus:   cur.GroundingStatus,
+			GroundingRevision: cur.GroundingRevision,
+			UpdatedBy:         sql.NullString{String: updatedBy, Valid: true},
+			UpdatedAt:         store.Now().String(),
+		}
+		if p.Name != nil {
+			if err := checkUnique(ctx, q, cur.ID, name, sql.NullString{}); err != nil {
+				return err
+			}
+			params.Name = name
+			params.NormalizedName = harness.Normalize(name)
+			if name != cur.Name {
+				params.GroundingRevision++
+			}
+			if cur.GroundingStatus == GroundingPending && params.NormalizedName != cur.NormalizedName {
+				// The link was the old dinner's recipe; the new name is
+				// grounded by name, and a link can be given by hand.
+				params.RecipeUrl = sql.NullString{}
+			}
+		}
+		if p.Method != nil {
+			params.Method = sql.NullString{String: *p.Method, Valid: true}
+		}
+		if p.MinutesTotal != nil {
+			params.MinutesTotal = sql.NullInt64{Int64: int64(*p.MinutesTotal), Valid: true}
+		}
+		if p.Difficulty != nil {
+			params.Difficulty = sql.NullString{String: *p.Difficulty, Valid: true}
+		}
+		row, err = q.UpdateDinner(ctx, params)
+		if err != nil {
+			return fmt.Errorf("dinners: update %s: %w", id, err)
+		}
+		renamed = row.GroundingRevision != cur.GroundingRevision
+		regrounding = renamed && cur.GroundingStatus == GroundingPending
+		return nil
+	})
+	if err != nil {
+		return Dinner{}, err
+	}
+	if renamed {
+		updateCommitted()
+		s.clearOffers(row.ID, row.GroundingRevision)
+	}
+	if regrounding {
+		s.stopGroundings(row.ID, row.GroundingRevision)
+		jobID, err := s.enqueueGrounding(ctx, row.ID, row.GroundingRevision)
+		if err != nil {
+			return Dinner{}, err
+		}
+		if jobID == nil {
+			row, err = db.New(s.st.Reader).GetDinner(context.WithoutCancel(ctx), row.ID)
+			if err != nil {
+				return Dinner{}, fmt.Errorf("dinners: read %s: %w", id, err)
+			}
+		}
+	}
+	return fromRow(row), nil
+}
+
+// Archive sets dinner id's status to archived, recording updatedBy. The row
+// is kept, so its name still counts for Side quest dedupe. A
+// KindGroundDinner job running for it is stopped, and its candidates no
+// longer ground it.
+func (s *Service) Archive(ctx context.Context, id, updatedBy string) (Dinner, error) {
+	if updatedBy == "" {
+		return Dinner{}, errors.New("dinners: archive: no member to record as updated_by")
+	}
+	row, err := db.New(s.st.Writer).ArchiveDinner(ctx, db.ArchiveDinnerParams{
+		ID:        id,
+		UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+		UpdatedAt: store.Now().String(),
+	})
+	if errors.Is(err, sql.ErrNoRows) {
+		return Dinner{}, ErrNotFound
+	}
+	if err != nil {
+		return Dinner{}, fmt.Errorf("dinners: archive %s: %w", id, err)
+	}
+	s.stopGroundings(row.ID, math.MaxInt64)
+	s.clearOffers(row.ID, math.MaxInt64)
+	return fromRow(row), nil
+}
+
+// ToggleFavorite flips dinner id's is_favorite, recording updatedBy.
+func (s *Service) ToggleFavorite(ctx context.Context, id, updatedBy string) (Dinner, error) {
+	if updatedBy == "" {
+		return Dinner{}, errors.New("dinners: favorite: no member to record as updated_by")
+	}
+	row, err := db.New(s.st.Writer).ToggleDinnerFavorite(ctx, db.ToggleDinnerFavoriteParams{
+		ID:        id,
+		UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+		UpdatedAt: store.Now().String(),
+	})
+	if errors.Is(err, sql.ErrNoRows) {
+		return Dinner{}, ErrNotFound
+	}
+	if err != nil {
+		return Dinner{}, fmt.Errorf("dinners: favorite %s: %w", id, err)
+	}
+	return fromRow(row), nil
+}
+
+// validate checks every field of p and returns its trimmed name.
+func (p Patch) validate() (string, error) {
+	var problems []Problem
+	var name string
+	if p.Name == nil && p.Method == nil && p.MinutesTotal == nil && p.Difficulty == nil {
+		return "", invalid("patch", "no fields to change")
+	}
+	if p.Name != nil {
+		n, err := checkName(*p.Name)
+		var verr *ValidationError
+		if errors.As(err, &verr) {
+			problems = append(problems, verr.Problems...)
+		}
+		name = n
+	}
+	if p.Method != nil && !slices.Contains(Methods, *p.Method) {
+		problems = append(problems, Problem{"method", "must be one of " + strings.Join(Methods, ", ")})
+	}
+	if p.MinutesTotal != nil && (*p.MinutesTotal < 1 || *p.MinutesTotal > MaxMinutes) {
+		problems = append(problems, Problem{"minutes_total", fmt.Sprintf("must be 1 to %d", MaxMinutes)})
+	}
+	if p.Difficulty != nil && !slices.Contains(Difficulties, *p.Difficulty) {
+		problems = append(problems, Problem{"difficulty", "must be one of " + strings.Join(Difficulties, ", ")})
+	}
+	if problems != nil {
+		return "", &ValidationError{Problems: problems}
+	}
+	return name, nil
+}
+
+// checkName returns raw trimmed, refusing a name that is empty, too long or
+// has no words left once normalized (so it could not be deduplicated).
+func checkName(raw string) (string, error) {
+	name := strings.TrimSpace(raw)
+	switch {
+	case name == "":
+		return "", invalid("name", "must not be empty")
+	case utf8.RuneCountInString(name) > MaxNameChars:
+		return "", invalid("name", fmt.Sprintf("must be at most %d characters", MaxNameChars))
+	case harness.Normalize(name) == "":
+		return "", invalid("name", "must name a dish, not only filler words")
+	}
+	return name, nil
+}
+
+// checkRecipeURL parses raw as an absolute https:// link to a recipe page,
+// the only kind recipe grounding fetches.
+func checkRecipeURL(raw string) (*url.URL, error) {
+	raw = strings.TrimSpace(raw)
+	if len(raw) > MaxRecipeURL {
+		return nil, invalid("recipe_url", fmt.Sprintf("must be at most %d bytes", MaxRecipeURL))
+	}
+	u, err := url.Parse(raw)
+	switch {
+	case err != nil:
+		return nil, invalid("recipe_url", "is not a URL")
+	case u.Scheme != "https" || u.Hostname() == "":
+		return nil, invalid("recipe_url", "must be an https:// link")
+	case u.User != nil:
+		return nil, invalid("recipe_url", "must not carry a user name or password")
+	}
+	return u, nil
+}
+
+// checkUnique returns a *DuplicateError when name is harness.Similar to an
+// unarchived dinner other than self, or recipeURL is one's recipe link: the
+// source_url of the recipe it is grounded in, else the recipe_url still
+// awaiting grounding.
+func checkUnique(ctx context.Context, q *db.Queries, self, name string, recipeURL sql.NullString) error {
+	rows, err := q.ListUnarchivedDinners(ctx)
+	if err != nil {
+		return fmt.Errorf("dinners: list for dedupe: %w", err)
+	}
+	for _, row := range rows {
+		if row.Dinner.ID == self {
+			continue
+		}
+		link := row.Dinner.RecipeUrl
+		if row.RecipeSourceUrl.Valid {
+			link = row.RecipeSourceUrl
+		}
+		if harness.Similar(name, row.Dinner.Name) || (recipeURL.Valid && link == recipeURL) {
+			return &DuplicateError{Existing: fromRow(row.Dinner)}
+		}
+	}
+	return nil
+}
+
+// PhotoURL is where the API serves a list-sized copy of photo id.
+func PhotoURL(id string) string {
+	return fmt.Sprintf("/media/photos/%s-%d.jpg", id, photoListWidth)
+}
+
+func fromRow(r db.Dinner) Dinner {
+	d := Dinner{
+		ID:              r.ID,
+		Name:            r.Name,
+		Status:          r.Status,
+		Origin:          r.Origin,
+		Method:          nullString(r.Method),
+		Difficulty:      nullString(r.Difficulty),
+		Cuisine:         nullString(r.Cuisine),
+		IsFavorite:      r.IsFavorite == 1,
+		RecipeID:        nullString(r.RecipeID),
+		GroundingStatus: r.GroundingStatus,
+		GroundingError:  nullString(r.GroundingError),
+		UpdatedBy:       nullString(r.UpdatedBy),
+		CreatedAt:       r.CreatedAt,
+		UpdatedAt:       r.UpdatedAt,
+	}
+	if r.MinutesTotal.Valid {
+		d.MinutesTotal = &r.MinutesTotal.Int64
+	}
+	if r.PhotoID.Valid {
+		u := PhotoURL(r.PhotoID.String)
+		d.PhotoURL = &u
+	}
+	return d
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}

internal/dinners/dinners_test.go

@@ -0,0 +1,76 @@
+package dinners_test
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+)
+
+// TestCreateRegularNeverNamesFromLink: a Regular added with a recipe link
+// is named only by the household, so no part of the link — host, path,
+// query or fragment — is stored as its name or shown in a dinner or a
+// duplicate error, even a token of plain letters in the path.
+func TestCreateRegularNeverNamesFromLink(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	const link = "https://c.example/stew-key-abcdefghijklmno?sig=zyxwvut#lookup"
+	// Each leak holds a character no ULID has (Crockford base32 has no I, L,
+	// O, U, "-", "." or "/"), so a dinner's id never matches one.
+	leaks := []string{link, "c.example", "stew-key", "abcdefghijklmno", "sig", "zyxwvut", "lookup"}
+	check := func(what, text string) {
+		t.Helper()
+		lower := strings.ToLower(text)
+		for _, leak := range leaks {
+			if strings.Contains(lower, leak) {
+				t.Errorf("%s contains %q: %s", what, leak, text)
+			}
+		}
+	}
+
+	_, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{RecipeURL: ptr(link)}, member)
+	var verr *dinners.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("link without a name: err = %v, want a *ValidationError", err)
+	}
+	check("validation error", verr.Error())
+
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr(" Sunday stew "), RecipeURL: ptr(link)}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Name != "Sunday stew" {
+		t.Errorf("name = %q, want the household's %q", c.Name, "Sunday stew")
+	}
+	created, err := json.Marshal(c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	check("create response", string(created))
+	row := e.dinner(t, c.ID)
+	check("stored name", row.Name+" "+row.NormalizedName)
+	if row.RecipeUrl.String != link {
+		t.Errorf("stored recipe_url = %q, want %q kept for grounding", row.RecipeUrl.String, link)
+	}
+
+	list, err := e.svc.List(t.Context(), dinners.StatusRegular)
+	if err != nil {
+		t.Fatal(err)
+	}
+	listed, err := json.Marshal(list)
+	if err != nil {
+		t.Fatal(err)
+	}
+	check("list response", string(listed))
+
+	// The same link under another name is still a duplicate, and its error
+	// names the existing dinner by the household's name.
+	_, err = e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Weeknight chili"), RecipeURL: ptr(link)}, member)
+	var dup *dinners.DuplicateError
+	if !errors.As(err, &dup) || dup.Existing.ID != c.ID {
+		t.Fatalf("same link again: err = %v, want a duplicate of %s", err, c.ID)
+	}
+	check("duplicate error", dup.Error())
+}

internal/dinners/export_test.go

@@ -0,0 +1,73 @@
+package dinners
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// SetGroundTimeout sets the deadline of grounding by hand until t ends. A
+// test calling it must not run in parallel.
+func SetGroundTimeout(t *testing.T, d time.Duration) {
+	old := groundTimeout
+	groundTimeout = d
+	t.Cleanup(func() { groundTimeout = old })
+}
+
+// SetOfferLifetime sets how long candidates ground a dinner until t ends.
+// A test calling it must not run in parallel.
+func SetOfferLifetime(t *testing.T, d time.Duration) {
+	old := offerLifetime
+	offerLifetime = d
+	t.Cleanup(func() { offerLifetime = old })
+}
+
+// SetUpdateCommitted runs f in Update once a rename is committed, before
+// the dinner's offers are cleared, until t ends. A test calling it must
+// not run in parallel.
+func SetUpdateCommitted(t *testing.T, f func()) {
+	old := updateCommitted
+	updateCommitted = f
+	t.Cleanup(func() { updateCommitted = old })
+}
+
+// AdvanceClock moves the service's clock d ahead of real time until t
+// ends, without firing any timer. A test calling it must not run in
+// parallel.
+func AdvanceClock(t *testing.T, d time.Duration) {
+	old := now
+	now = func() time.Time { return old().Add(d) }
+	t.Cleanup(func() { now = old })
+}
+
+// HasOffers reports whether the service holds candidates offered for
+// dinner id.
+func (s *Service) HasOffers(id string) bool {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	_, ok := s.offers[id]
+	return ok
+}
+
+// StoreOffers stores urls as dinner id's offers, as a Candidates search
+// that read the dinner at grounding_revision revision would on finishing.
+func (s *Service) StoreOffers(id string, urls map[string]string, revision int64) {
+	keep, done := s.trackOffers(id)
+	defer done()
+	keep(urls, revision)
+}
+
+// OfferCount is the number of dinners whose candidates the service holds.
+func (s *Service) OfferCount() int {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	return len(s.offers)
+}
+
+// RunGroundJob runs the KindGroundDinner handler for p in the caller's
+// goroutine, as the job runner would, and returns the grounding status it
+// reports.
+func (s *Service) RunGroundJob(ctx context.Context, p GroundJob) (string, error) {
+	r, err := s.runGroundJob(ctx, p, nil)
+	return r.GroundingStatus, err
+}

internal/dinners/grounding.go

@@ -0,0 +1,804 @@
+package dinners
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"math"
+	"slices"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// KindGroundDinner is the job that grounds a new Regular in a recipe.
+const KindGroundDinner = "ground_dinner"
+
+// Grounding statuses (the dinners.grounding_status column).
+const (
+	GroundingPending  = "pending"
+	GroundingGrounded = "grounded"
+	GroundingFailed   = "failed"
+	GroundingManual   = "manual"
+)
+
+// Reasons a dinner's background grounding failed, stored in
+// dinners.grounding_error and as the KindGroundDinner job's failure code.
+const (
+	// ReasonNoRecipe: no page the search found holds a usable recipe.
+	ReasonNoRecipe = "no_recipe_found"
+	// ReasonRecipeUnusable: the dinner's recipe_url holds no usable recipe.
+	ReasonRecipeUnusable = "recipe_unusable"
+	// ReasonSearchNotConfigured: recipe search is not set up.
+	ReasonSearchNotConfigured = "search_not_configured"
+	// ReasonSearchFailed: the search provider failed.
+	ReasonSearchFailed = "search_failed"
+	// ReasonAIFailed: normalize_recipe's model provider could not be built
+	// or called.
+	ReasonAIFailed = "ai_failed"
+	// ReasonInterrupted: the server stopped while grounding.
+	ReasonInterrupted = "interrupted"
+	// ReasonGroundingError: any other failure, such as the database's.
+	ReasonGroundingError = "grounding_error"
+)
+
+// Reasons are every grounding failure reason.
+var Reasons = []string{
+	ReasonNoRecipe, ReasonRecipeUnusable, ReasonSearchNotConfigured, ReasonSearchFailed,
+	ReasonAIFailed, ReasonInterrupted, ReasonGroundingError,
+}
+
+// Limits on candidates and on a recipe entered by hand.
+const (
+	MaxCandidates     = 3
+	MaxManualLines    = 100
+	MaxManualLineChar = 500
+	// manualSourcePrefix starts the source_url of a recipe entered by hand,
+	// followed by the recipe's id; it is never a fetchable page.
+	manualSourcePrefix = "mealquest:manual:"
+)
+
+// GroundTimeout bounds grounding a candidate or link by hand, which runs in
+// the request: the page fetch (recipes.Timeout), its photo download and
+// normalize_recipe (harness.DefaultTimeout), with some slack.
+const GroundTimeout = 90 * time.Second
+
+// groundTimeout is GroundTimeout; tests shorten it.
+var groundTimeout = GroundTimeout
+
+// ErrGroundTimeout is returned by Ground when grounding a candidate or link
+// runs past GroundTimeout; the dinner is left as it was.
+var ErrGroundTimeout = errors.New("dinners: grounding the recipe took too long")
+
+// ErrGroundFailed wraps any unexpected failure grounding a dinner by hand.
+// Its text may quote the link and dependency errors, so it is never
+// logged.
+var ErrGroundFailed = errors.New("dinners: grounding the recipe failed")
+
+// ErrCandidatesFailed wraps any unexpected failure finding a dinner's
+// candidates. Its text may quote a candidate's URL and dependency errors,
+// so it is never logged.
+var ErrCandidatesFailed = errors.New("dinners: finding recipe candidates failed")
+
+// ErrArchived is grounding an archived dinner by hand.
+var ErrArchived = errors.New("dinner archived")
+
+// ErrGroundConflict is a candidate or link grounded for a dinner that was
+// renamed or grounded some other way while it was grounding.
+var ErrGroundConflict = errors.New("dinner changed while its recipe was grounding")
+
+// GroundJob is the KindGroundDinner payload: the dinner to ground and its
+// grounding_revision when the job was enqueued.
+type GroundJob struct {
+	DinnerID string `json:"dinner_id"`
+	Revision int64  `json:"revision"`
+}
+
+// groundResult is the KindGroundDinner result: the dinner's grounding
+// status once the job ends. It is not grounded by this job when the dinner
+// was grounded by hand before the job finished, renamed (a later job
+// grounds it) or archived; the job then reports the status it found.
+type groundResult struct {
+	DinnerID        string `json:"dinner_id"`
+	GroundingStatus string `json:"grounding_status"`
+}
+
+func (r groundResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// runGroundJob grounds a pending dinner as its creation asked: its
+// recipe_url with GroundURL, else its name with Ground. Success records
+// the recipe and photo with grounding_status grounded, and the recipe's
+// method, minutes and difficulty where a member has not set them; failure
+// records grounding_status failed with its Reason, which is also the job's
+// failure code. A dinner archived, no longer pending, or at a
+// grounding_revision other than p.Revision is not grounded at all, and
+// either result is recorded only while the dinner is still unarchived,
+// pending and at p.Revision: a dinner grounded by hand meanwhile is left as
+// it is, and one renamed or archived meanwhile is left pending — for the
+// job its rename enqueued, or for none. Archiving or renaming the dinner
+// stops the grounding where it is, so no further search, fetch, photo
+// download or model call is made for it.
+func (s *Service) runGroundJob(ctx context.Context, p GroundJob, _ func(groundResult) error) (groundResult, error) {
+	// Tracked before the dinner is read: an archive or rename committed
+	// after the read finds this job to stop.
+	groundCtx, done := s.trackGrounding(ctx, p.DinnerID, p.Revision)
+	defer done()
+	row, err := db.New(s.st.Reader).GetDinner(ctx, p.DinnerID)
+	if err != nil {
+		return groundResult{}, fmt.Errorf("dinners: ground: read %s: %w", p.DinnerID, err)
+	}
+	if row.Status == StatusArchived || row.GroundingStatus != GroundingPending || row.GroundingRevision != p.Revision {
+		return groundResult{DinnerID: row.ID, GroundingStatus: row.GroundingStatus}, nil
+	}
+
+	var gr recipes.Grounded
+	if row.RecipeUrl.Valid {
+		gr, err = s.grounder.GroundURL(groundCtx, row.RecipeUrl.String)
+	} else {
+		gr, err = s.grounder.Ground(groundCtx, row.Name, row.Name)
+	}
+	if err != nil && ctx.Err() == nil && errors.Is(context.Cause(groundCtx), errGroundingStopped) {
+		return s.currentGrounding(ctx, row.ID)
+	}
+	if err != nil {
+		reason := reasonFor(err, row.RecipeUrl.Valid)
+		if ctx.Err() != nil {
+			reason = ReasonInterrupted
+		}
+		// Only the reason is logged: the error may quote a dependency's
+		// response, which jobs never store, return or log.
+		s.logger.InfoContext(ctx, "dinner grounding failed", "dinner_id", row.ID, "reason", reason)
+		write := context.WithoutCancel(ctx)
+		if _, failErr := db.New(s.st.Writer).FailPendingDinnerGrounding(write, db.FailPendingDinnerGroundingParams{
+			GroundingError:    sql.NullString{String: reason, Valid: true},
+			UpdatedAt:         store.Now().String(),
+			ID:                row.ID,
+			GroundingRevision: p.Revision,
+		}); failErr != nil {
+			return groundResult{}, fmt.Errorf("dinners: ground: record failure of %s: %w", row.ID, failErr)
+		}
+		if ctx.Err() != nil {
+			return groundResult{}, ctx.Err()
+		}
+		return groundResult{}, &jobs.Failure{Code: reason}
+	}
+
+	n, err := db.New(s.st.Writer).GroundPendingDinner(ctx, db.GroundPendingDinnerParams{
+		RecipeID:          sql.NullString{String: gr.RecipeID, Valid: true},
+		PhotoID:           sql.NullString{String: gr.PhotoID, Valid: true},
+		Method:            sql.NullString{String: gr.Method, Valid: true},
+		MinutesTotal:      nullInt(gr.MinutesTotal),
+		Difficulty:        sql.NullString{String: gr.Difficulty, Valid: true},
+		UpdatedAt:         store.Now().String(),
+		ID:                row.ID,
+		GroundingRevision: p.Revision,
+	})
+	if err != nil {
+		return groundResult{}, fmt.Errorf("dinners: ground: record %s: %w", row.ID, err)
+	}
+	if n == 0 {
+		return s.currentGrounding(ctx, row.ID)
+	}
+	return groundResult{DinnerID: row.ID, GroundingStatus: GroundingGrounded}, nil
+}
+
+// currentGrounding is the KindGroundDinner result of a job that did not
+// ground dinner id: the grounding status the dinner has now.
+func (s *Service) currentGrounding(ctx context.Context, id string) (groundResult, error) {
+	cur, err := db.New(s.st.Reader).GetDinner(ctx, id)
+	if err != nil {
+		return groundResult{}, fmt.Errorf("dinners: ground: read %s: %w", id, err)
+	}
+	return groundResult{DinnerID: cur.ID, GroundingStatus: cur.GroundingStatus}, nil
+}
+
+// errGroundingStopped is the cause a running KindGroundDinner job's
+// grounding is cancelled with when its dinner is archived or renamed.
+var errGroundingStopped = errors.New("dinners: grounding stopped: dinner archived or renamed")
+
+// runningGrounding is a KindGroundDinner job running for a dinner at
+// revision, with the cancel of its grounding.
+type runningGrounding struct {
+	revision int64
+	cancel   context.CancelCauseFunc
+}
+
+// trackGrounding returns a context for grounding dinnerID at revision that
+// stopGroundings cancels, and the func to call when the job ends.
+func (s *Service) trackGrounding(ctx context.Context, dinnerID string, revision int64) (context.Context, func()) {
+	groundCtx, cancel := context.WithCancelCause(ctx)
+	r := &runningGrounding{revision: revision, cancel: cancel}
+	s.groundingsMu.Lock()
+	if s.groundings[dinnerID] == nil {
+		s.groundings[dinnerID] = make(map[*runningGrounding]struct{})
+	}
+	s.groundings[dinnerID][r] = struct{}{}
+	s.groundingsMu.Unlock()
+	return groundCtx, func() {
+		s.groundingsMu.Lock()
+		delete(s.groundings[dinnerID], r)
+		if len(s.groundings[dinnerID]) == 0 {
+			delete(s.groundings, dinnerID)
+		}
+		s.groundingsMu.Unlock()
+		cancel(nil)
+	}
+}
+
+// stopGroundings cancels, with errGroundingStopped, the grounding of every
+// KindGroundDinner job running for dinnerID at a revision below below. Call
+// it once the change that makes those jobs stale is committed.
+func (s *Service) stopGroundings(dinnerID string, below int64) {
+	s.groundingsMu.Lock()
+	defer s.groundingsMu.Unlock()
+	for r := range s.groundings[dinnerID] {
+		if r.revision < below {
+			r.cancel(errGroundingStopped)
+		}
+	}
+}
+
+// FailInterruptedGroundings fails, with ReasonInterrupted, every unarchived
+// dinner still pending whose KindGroundDinner job is no longer queued or
+// running: a previous process stopped before enqueuing the job or before
+// its handler recorded a result. An archived dinner is left pending, since
+// archiving, not a restart, stopped its grounding. Call it once at boot, after the job runner's
+// Start has failed the jobs that process left running, so no dinner stays
+// pending with nothing left to ground it. It returns how many it failed.
+func (s *Service) FailInterruptedGroundings(ctx context.Context) (int64, error) {
+	n, err := db.New(s.st.Writer).FailOrphanedPendingDinnerGroundings(ctx, db.FailOrphanedPendingDinnerGroundingsParams{
+		GroundingError: sql.NullString{String: ReasonInterrupted, Valid: true},
+		UpdatedAt:      store.Now().String(),
+		Kind:           KindGroundDinner,
+	})
+	if err != nil {
+		return 0, fmt.Errorf("dinners: fail interrupted groundings: %w", err)
+	}
+	if n > 0 {
+		s.logger.WarnContext(ctx, "failed dinner groundings interrupted by restart", "count", n)
+	}
+	return n, nil
+}
+
+// reasonFor is the Reason for a grounding error; fromURL says whether the
+// dinner's recipe_url was grounded rather than its name.
+func reasonFor(err error, fromURL bool) string {
+	var ungroundable *recipes.ErrUngroundable
+	switch {
+	case errors.As(err, &ungroundable) && fromURL:
+		return ReasonRecipeUnusable
+	case errors.As(err, &ungroundable):
+		return ReasonNoRecipe
+	case errors.Is(err, recipes.ErrSearchNotConfigured):
+		return ReasonSearchNotConfigured
+	case errors.Is(err, recipes.ErrSearchFailed):
+		return ReasonSearchFailed
+	case errors.Is(err, recipes.ErrNormalizeFailed):
+		return ReasonAIFailed
+	}
+	return ReasonGroundingError
+}
+
+// Candidate is a recipe page offered to ground a dinner in.
+type Candidate struct {
+	// CandidateID is an opaque id for the page, resolved by the server:
+	// Fix.CandidateID grounds it. The page's URL is never returned, as it
+	// may carry a token.
+	CandidateID string `json:"candidate_id"`
+	Title       string `json:"title"`
+	SiteName    string `json:"site_name"`
+	// PhotoURL is the cached photo of a page already grounded, else null.
+	PhotoURL *string `json:"photo_url"`
+	Minutes  *int    `json:"minutes"`
+}
+
+// offerLifetime is how long the candidates Candidates offers a dinner
+// ground it; tests shorten it.
+var offerLifetime = 30 * time.Minute
+
+// now is the clock offer lifetimes are measured on; tests advance it.
+var now = time.Now
+
+// updateCommitted runs in Update once a rename is committed, before the
+// dinner's offers are cleared; tests use it to act in between.
+var updateCommitted = func() {}
+
+// offerSet is the candidates last offered for a dinner: the page URL of
+// each candidate id, found by searching the dinner's name at its
+// grounding_revision revision. They ground the dinner until deadline, and
+// only while it is still at that revision, which every rename raises;
+// expiry drops the set from offers once deadline has passed.
+type offerSet struct {
+	urls     map[string]string
+	revision int64
+	deadline time.Time
+	expiry   *time.Timer
+}
+
+// offerSearch is a Candidates search running for a dinner. It stores no
+// offers found at a grounding_revision below below, which clearing the
+// dinner's offers raises.
+type offerSearch struct {
+	below int64
+}
+
+// Candidates searches for dinner id's name and returns up to MaxCandidates
+// recipe pages to ground it in, best first; the list may be empty. They
+// replace the dinner's earlier candidates: one not offered again no longer
+// grounds it. They ground it for offerLifetime, and not at all once it is
+// grounded by hand, renamed or archived, even while this search runs. A
+// missing dinner is ErrNotFound; any other failure wraps
+// ErrCandidatesFailed, and a search that fails also wraps
+// recipes.ErrSearchFailed.
+func (s *Service) Candidates(ctx context.Context, id string) ([]Candidate, error) {
+	// Tracked before the dinner is read: grounding, renaming or archiving
+	// it after the read keeps this search from storing what it found.
+	keep, done := s.trackOffers(id)
+	defer done()
+	row, err := s.get(ctx, id)
+	if errors.Is(err, ErrNotFound) {
+		return nil, err
+	}
+	if err != nil {
+		return nil, fmt.Errorf("%w: dinner %s: %w", ErrCandidatesFailed, id, err)
+	}
+	offers, err := s.grounder.Candidates(ctx, row.Name, row.Name, MaxCandidates)
+	if err != nil {
+		return nil, fmt.Errorf("%w: dinner %s: %w", ErrCandidatesFailed, id, err)
+	}
+	out := make([]Candidate, len(offers))
+	urls := make(map[string]string, len(offers))
+	for i, o := range offers {
+		cid := s.candidateID(row.ID, o.URL)
+		urls[cid] = o.URL
+		out[i] = Candidate{CandidateID: cid, Title: o.Title, SiteName: o.SiteName, Minutes: o.Minutes}
+		if o.PhotoID != "" {
+			u := PhotoURL(o.PhotoID)
+			out[i].PhotoURL = &u
+		}
+	}
+	if row.Status != StatusArchived {
+		keep(urls, row.GroundingRevision)
+	}
+	return out, nil
+}
+
+// trackOffers registers a Candidates search for dinner id. It returns keep,
+// which stores urls, found for the dinner at grounding_revision revision,
+// as its offers for offerLifetime unless clearOffers has run for it since
+// with a revision above that, or offers found at a later revision are
+// stored, and done, to call when the search ends.
+func (s *Service) trackOffers(id string) (keep func(urls map[string]string, revision int64), done func()) {
+	search := &offerSearch{}
+	s.offersMu.Lock()
+	if s.offerSearches[id] == nil {
+		s.offerSearches[id] = make(map[*offerSearch]struct{})
+	}
+	s.offerSearches[id][search] = struct{}{}
+	s.offersMu.Unlock()
+	keep = func(urls map[string]string, revision int64) {
+		s.offersMu.Lock()
+		defer s.offersMu.Unlock()
+		if revision < search.below {
+			return
+		}
+		if set := s.offers[id]; set != nil && set.revision > revision {
+			// Found at a later revision, so the earlier search's offers
+			// are already stale.
+			return
+		}
+		s.dropOffers(id)
+		set := &offerSet{urls: urls, revision: revision, deadline: now().Add(offerLifetime)}
+		// expiry waits for offersMu, so it finds set stored even when it
+		// fires at once, and drops set only, never offers stored later.
+		set.expiry = time.AfterFunc(offerLifetime, func() {
+			s.offersMu.Lock()
+			defer s.offersMu.Unlock()
+			if s.offers[id] == set {
+				delete(s.offers, id)
+			}
+		})
+		s.offers[id] = set
+	}
+	done = func() {
+		s.offersMu.Lock()
+		delete(s.offerSearches[id], search)
+		if len(s.offerSearches[id]) == 0 {
+			delete(s.offerSearches, id)
+		}
+		s.offersMu.Unlock()
+	}
+	return keep, done
+}
+
+// clearOffers drops dinner id's offers found at a grounding_revision below
+// below and keeps every Candidates search running for it from storing
+// such offers, so none of them grounds it. Offers found at below or above
+// are kept. Call it with math.MaxInt64 once the dinner is grounded by hand
+// or archived, and with its new revision once it is renamed: a search
+// that read the rename meanwhile keeps its offers.
+func (s *Service) clearOffers(id string, below int64) {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	if set := s.offers[id]; set != nil && set.revision < below {
+		s.dropOffers(id)
+	}
+	for search := range s.offerSearches[id] {
+		search.below = max(search.below, below)
+	}
+}
+
+// dropOffers drops dinner id's offers and stops their expiry. The caller
+// holds offersMu.
+func (s *Service) dropOffers(id string) {
+	if set := s.offers[id]; set != nil {
+		set.expiry.Stop()
+		delete(s.offers, id)
+	}
+}
+
+// candidateID is the opaque id of the page at rawURL as a candidate for
+// dinner id: the same page is offered under the same id until the service
+// restarts, and the id reveals nothing of the URL.
+func (s *Service) candidateID(id, rawURL string) string {
+	mac := hmac.New(sha256.New, s.offerKey)
+	mac.Write([]byte(id + "\x00" + rawURL))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil)[:16])
+}
+
+// candidateURL is the page URL of candidate cid last offered for dinner d.
+// A cid not among the dinner's live offers, or whose page is not a valid
+// recipe link, is a *ValidationError. Offers past their deadline, or found
+// at a grounding_revision other than d's, are not live, even before they
+// are dropped: d was renamed since they were found, if only to its name
+// then.
+func (s *Service) candidateURL(d db.Dinner, cid string) (string, error) {
+	var raw string
+	var ok bool
+	s.offersMu.Lock()
+	if set := s.offers[d.ID]; set != nil && set.revision == d.GroundingRevision && now().Before(set.deadline) {
+		raw, ok = set.urls[cid]
+	}
+	s.offersMu.Unlock()
+	if ok {
+		if u, err := checkRecipeURL(raw); err == nil {
+			return u.String(), nil
+		}
+	}
+	return "", invalid("candidate_id", "is not a candidate from recipe-candidates; reload the candidates")
+}
+
+// Fix grounds a dinner by hand: exactly one of a candidate from
+// Candidates, a pasted recipe link or a recipe typed in.
+type Fix struct {
+	CandidateID *string
+	RecipeURL   *string
+	Manual      *ManualRecipe
+}
+
+// ManualRecipe is a recipe typed in by the household.
+type ManualRecipe struct {
+	// Ingredients are the ingredient lines, at least one.
+	Ingredients []string
+	// Steps are the instructions, in order; there may be none.
+	Steps   []string
+	Minutes *int
+	Method  *string
+}
+
+// Ground grounds dinner id as f says, recording updatedBy. A candidate or
+// link is grounded with recipes.Grounder.GroundURL and sets
+// grounding_status grounded, with the recipe's photo, method, minutes and
+// difficulty; one a member changed while it was grounding is kept. A
+// manual recipe is stored as typed — no model runs — and sets
+// grounding_status manual with its method and minutes; it has no photo,
+// and the dinner keeps its difficulty. An invalid f is a *ValidationError
+// and an archived dinner ErrArchived. A failure grounding a candidate or
+// link, or recording it on the dinner, wraps ErrGroundFailed; a page that
+// cannot ground the dinner is also a *recipes.ErrUngroundable. A dinner
+// renamed, archived or grounded some other way while a candidate or link
+// was grounding is ErrGroundConflict or ErrArchived. A missing dinner is
+// ErrNotFound; any other failure, by candidate, link or manual recipe,
+// wraps ErrGroundFailed. None of these changes the dinner.
+func (s *Service) Ground(ctx context.Context, id string, f Fix, updatedBy string) (Dinner, error) {
+	if updatedBy == "" {
+		return Dinner{}, errors.New("dinners: ground: no member to record as updated_by")
+	}
+	link, manual, err := f.validate()
+	if err != nil {
+		return Dinner{}, err
+	}
+	if manual != nil {
+		return s.groundManual(ctx, id, *manual, updatedBy)
+	}
+	cur, err := s.get(ctx, id)
+	if errors.Is(err, ErrNotFound) {
+		return Dinner{}, err
+	}
+	if err != nil {
+		return Dinner{}, fmt.Errorf("%w: dinner %s: %w", ErrGroundFailed, id, err)
+	}
+	if cur.Status == StatusArchived {
+		return Dinner{}, ErrArchived
+	}
+	if f.CandidateID != nil {
+		if link, err = s.candidateURL(cur, *f.CandidateID); err != nil {
+			return Dinner{}, err
+		}
+	}
+	groundCtx, cancel := context.WithTimeout(ctx, groundTimeout)
+	defer cancel()
+	gr, err := s.grounder.GroundURL(groundCtx, link)
+	if err != nil {
+		if ctx.Err() == nil && errors.Is(groundCtx.Err(), context.DeadlineExceeded) {
+			return Dinner{}, ErrGroundTimeout
+		}
+		return Dinner{}, fmt.Errorf("%w: dinner %s: %w", ErrGroundFailed, id, err)
+	}
+	row, err := db.New(s.st.Writer).GroundDinner(ctx, db.GroundDinnerParams{
+		RecipeID:                  sql.NullString{String: gr.RecipeID, Valid: true},
+		PhotoID:                   sql.NullString{String: gr.PhotoID, Valid: true},
+		Method:                    sql.NullString{String: gr.Method, Valid: true},
+		MinutesTotal:              nullInt(gr.MinutesTotal),
+		Difficulty:                sql.NullString{String: gr.Difficulty, Valid: true},
+		GroundingStatus:           GroundingGrounded,
+		UpdatedBy:                 sql.NullString{String: updatedBy, Valid: true},
+		UpdatedAt:                 store.Now().String(),
+		ID:                        cur.ID,
+		ObservedName:              cur.Name,
+		ObservedNormalizedName:    cur.NormalizedName,
+		ObservedGroundingStatus:   cur.GroundingStatus,
+		ObservedGroundingRevision: cur.GroundingRevision,
+		ObservedRecipeID:          cur.RecipeID,
+		ObservedMethod:            cur.Method,
+		ObservedMinutesTotal:      cur.MinutesTotal,
+		ObservedDifficulty:        cur.Difficulty,
+	})
+	if errors.Is(err, sql.ErrNoRows) {
+		return Dinner{}, s.groundRejected(ctx, id)
+	}
+	if err != nil {
+		return Dinner{}, fmt.Errorf("%w: dinner %s: record: %w", ErrGroundFailed, id, err)
+	}
+	s.clearOffers(cur.ID, math.MaxInt64)
+	return fromRow(row), nil
+}
+
+// groundRejected is the error for dinner id when it was not as observed
+// before grounding: ErrNotFound, ErrArchived or ErrGroundConflict. Failing
+// to read it wraps ErrGroundFailed.
+func (s *Service) groundRejected(ctx context.Context, id string) error {
+	cur, err := s.get(ctx, id)
+	if errors.Is(err, ErrNotFound) {
+		return err
+	}
+	if err != nil {
+		return fmt.Errorf("%w: dinner %s: %w", ErrGroundFailed, id, err)
+	}
+	if cur.Status == StatusArchived {
+		return ErrArchived
+	}
+	return ErrGroundConflict
+}
+
+// groundManual stores m as dinner id's recipe, with its ingredients and
+// steps, and records it on the dinner, all in one transaction; the
+// dinner's candidates then no longer ground it. A missing or archived
+// dinner is ErrNotFound or ErrArchived; any other failure wraps
+// ErrGroundFailed.
+func (s *Service) groundManual(ctx context.Context, id string, m ManualRecipe, updatedBy string) (Dinner, error) {
+	var row db.Dinner
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetDinner(ctx, id)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("dinners: read %s: %w", id, err)
+		}
+		if cur.Status == StatusArchived {
+			return ErrArchived
+		}
+		ld, err := json.Marshal(manualJSONLD{
+			Context:      "https://schema.org",
+			Type:         "Recipe",
+			Name:         cur.Name,
+			Ingredients:  m.Ingredients,
+			Instructions: m.Steps,
+			TotalTime:    fmt.Sprintf("PT%dM", *m.Minutes),
+		})
+		if err != nil {
+			return fmt.Errorf("dinners: encode manual recipe: %w", err)
+		}
+		now := store.Now().String()
+		recipeID := store.NewID()
+		minutes := sql.NullInt64{Int64: int64(*m.Minutes), Valid: true}
+		method := sql.NullString{String: *m.Method, Valid: true}
+		rec, err := q.CreateManualRecipe(ctx, db.CreateManualRecipeParams{
+			ID:           recipeID,
+			SourceUrl:    manualSourcePrefix + recipeID,
+			Title:        cur.Name,
+			TotalMinutes: minutes,
+			RawJsonld:    string(ld),
+			Method:       method,
+			MinutesTotal: minutes,
+			FetchedAt:    now,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		})
+		if err != nil {
+			return fmt.Errorf("dinners: store manual recipe: %w", err)
+		}
+		for i, line := range m.Ingredients {
+			if err := q.CreateRecipeIngredient(ctx, db.CreateRecipeIngredientParams{
+				ID:        store.NewID(),
+				RecipeID:  rec.ID,
+				Position:  int64(i),
+				RawText:   line,
+				CreatedAt: now,
+				UpdatedAt: now,
+			}); err != nil {
+				return fmt.Errorf("dinners: store manual ingredient %d: %w", i+1, err)
+			}
+		}
+		for i, text := range m.Steps {
+			if err := q.CreateRecipeStep(ctx, db.CreateRecipeStepParams{
+				ID:        store.NewID(),
+				RecipeID:  rec.ID,
+				Position:  int64(i),
+				Text:      text,
+				CreatedAt: now,
+				UpdatedAt: now,
+			}); err != nil {
+				return fmt.Errorf("dinners: store manual step %d: %w", i+1, err)
+			}
+		}
+		row, err = q.GroundDinner(ctx, db.GroundDinnerParams{
+			RecipeID:                  sql.NullString{String: rec.ID, Valid: true},
+			Method:                    method,
+			MinutesTotal:              minutes,
+			Difficulty:                cur.Difficulty,
+			GroundingStatus:           GroundingManual,
+			UpdatedBy:                 sql.NullString{String: updatedBy, Valid: true},
+			UpdatedAt:                 now,
+			ID:                        cur.ID,
+			ObservedName:              cur.Name,
+			ObservedNormalizedName:    cur.NormalizedName,
+			ObservedGroundingStatus:   cur.GroundingStatus,
+			ObservedGroundingRevision: cur.GroundingRevision,
+			ObservedRecipeID:          cur.RecipeID,
+			ObservedMethod:            cur.Method,
+			ObservedMinutesTotal:      cur.MinutesTotal,
+			ObservedDifficulty:        cur.Difficulty,
+		})
+		if err != nil {
+			return fmt.Errorf("dinners: ground %s: %w", id, err)
+		}
+		return nil
+	})
+	if errors.Is(err, ErrNotFound) || errors.Is(err, ErrArchived) {
+		return Dinner{}, err
+	}
+	if err != nil {
+		return Dinner{}, fmt.Errorf("%w: dinner %s: %w", ErrGroundFailed, id, err)
+	}
+	s.clearOffers(row.ID, math.MaxInt64)
+	return fromRow(row), nil
+}
+
+// manualJSONLD is the schema.org Recipe stored as a manual recipe's
+// raw_jsonld, so it reads like a fetched page's.
+type manualJSONLD struct {
+	Context      string   `json:"@context"`
+	Type         string   `json:"@type"`
+	Name         string   `json:"name"`
+	Ingredients  []string `json:"recipeIngredient"`
+	Instructions []string `json:"recipeInstructions"`
+	TotalTime    string   `json:"totalTime"`
+}
+
+// validate checks f and returns the link to ground, or the manual recipe
+// with its lines trimmed.
+func (f Fix) validate() (link string, manual *ManualRecipe, err error) {
+	given := 0
+	for _, set := range []bool{f.CandidateID != nil, f.RecipeURL != nil, f.Manual != nil} {
+		if set {
+			given++
+		}
+	}
+	if given != 1 {
+		return "", nil, invalid("ground", "give exactly one of candidate_id, recipe_url and manual")
+	}
+	switch {
+	case f.CandidateID != nil:
+		// Ground resolves the candidate to its page.
+		return "", nil, nil
+	case f.RecipeURL != nil:
+		u, err := checkRecipeURL(*f.RecipeURL)
+		if err != nil {
+			return "", nil, err
+		}
+		return u.String(), nil, nil
+	}
+	m, err := f.Manual.validate()
+	if err != nil {
+		return "", nil, err
+	}
+	return "", &m, nil
+}
+
+// validate checks every field of m and returns it with its lines trimmed.
+func (m ManualRecipe) validate() (ManualRecipe, error) {
+	var problems []Problem
+	ings, ingProblem := checkLines(m.Ingredients, 1)
+	if ingProblem != "" {
+		problems = append(problems, Problem{"manual.ingredients", ingProblem})
+	}
+	steps, stepProblem := checkLines(m.Steps, 0)
+	if stepProblem != "" {
+		problems = append(problems, Problem{"manual.steps", stepProblem})
+	}
+	if m.Minutes == nil || *m.Minutes < 1 || *m.Minutes > MaxMinutes {
+		problems = append(problems, Problem{"manual.minutes", fmt.Sprintf("must be 1 to %d", MaxMinutes)})
+	}
+	if m.Method == nil || !slices.Contains(Methods, *m.Method) {
+		problems = append(problems, Problem{"manual.method", "must be one of " + strings.Join(Methods, ", ")})
+	}
+	if problems != nil {
+		return ManualRecipe{}, &ValidationError{Problems: problems}
+	}
+	return ManualRecipe{Ingredients: ings, Steps: steps, Minutes: m.Minutes, Method: m.Method}, nil
+}
+
+// checkLines returns lines trimmed, or why they are refused: fewer than
+// least, more than MaxManualLines, or one blank or over MaxManualLineChar.
+func checkLines(lines []string, least int) ([]string, string) {
+	if len(lines) < least {
+		return nil, fmt.Sprintf("must have at least %d line", least)
+	}
+	if len(lines) > MaxManualLines {
+		return nil, fmt.Sprintf("must have at most %d lines", MaxManualLines)
+	}
+	out := make([]string, len(lines))
+	for i, line := range lines {
+		line = strings.TrimSpace(line)
+		switch {
+		case line == "":
+			return nil, fmt.Sprintf("line %d is blank", i+1)
+		case utf8.RuneCountInString(line) > MaxManualLineChar:
+			return nil, fmt.Sprintf("line %d is over %d characters", i+1, MaxManualLineChar)
+		}
+		out[i] = line
+	}
+	return out, ""
+}
+
+// get reads dinner id, or ErrNotFound.
+func (s *Service) get(ctx context.Context, id string) (db.Dinner, error) {
+	row, err := db.New(s.st.Reader).GetDinner(ctx, id)
+	if errors.Is(err, sql.ErrNoRows) {
+		return db.Dinner{}, ErrNotFound
+	}
+	if err != nil {
+		return db.Dinner{}, fmt.Errorf("dinners: read %s: %w", id, err)
+	}
+	return row, nil
+}
+
+func nullInt(v *int) sql.NullInt64 {
+	if v == nil {
+		return sql.NullInt64{}
+	}
+	return sql.NullInt64{Int64: int64(*v), Valid: true}
+}

internal/household/defaults.go

@@ -11,7 +11,8 @@ import (
 )
 
 // DefaultPersonaPrompt is the default AI system prompt (CTXD PROMPTS.MD §4).
-// SeedAISettings stores it on first boot and the Admin reset restores it.
+// SeedAISettings stores it on first boot and aisettings.Service.ResetPrompt
+// restores it.
 const DefaultPersonaPrompt = `You are MealQuest, a dinner planning assistant for one household. Suggest dinners
 similar to their regular rotation, nudging them to try something a little new each
 week. Prefer weeknight-friendly recipes with common grocery-store ingredients.

internal/household/settings.go

@@ -68,8 +68,18 @@ type SettingsPatch struct {
 	SuggestionsTime  *string
 	ChatAutosendDow  *int
 	ChatAutosendTime *string
+	// OnboardingCompleted, when true, records that the household finished
+	// onboarding: onboarding_completed_at becomes the time of the update,
+	// unless it is already set, when the first time is kept. Onboarding is
+	// never undone, so false is invalid, and it cannot first be completed
+	// with fewer than MinRegulars Regulars.
+	OnboardingCompleted *bool
 }
 
+// MinRegulars is how many Regulars the household must have to complete
+// onboarding.
+const MinRegulars = 3
+
 // Problem is one invalid field of a SettingsPatch, named by its JSON key.
 type Problem struct {
 	Field  string
@@ -162,7 +172,8 @@ func (s *SettingsService) Get(ctx context.Context) (Settings, error) {
 // Update validates patch, applies it, records updatedBy (the signed-in
 // member's subject, which must not be empty) and publishes the new settings
 // to every subscriber. An invalid patch is a *ValidationError and changes
-// nothing.
+// nothing, as does completing onboarding with fewer than MinRegulars
+// Regulars.
 func (s *SettingsService) Update(ctx context.Context, patch SettingsPatch, updatedBy string) (Settings, error) {
 	if updatedBy == "" {
 		return Settings{}, errors.New("household: update settings: no member to record as updated_by")
@@ -208,6 +219,19 @@ func (s *SettingsService) Update(ctx context.Context, patch SettingsPatch, updat
 		setString(&p.SuggestionsTime, patch.SuggestionsTime)
 		setDow(&p.ChatAutosendDow, patch.ChatAutosendDow)
 		setString(&p.ChatAutosendTime, patch.ChatAutosendTime)
+		if patch.OnboardingCompleted != nil && !p.OnboardingCompletedAt.Valid {
+			n, err := q.CountRegularDinners(ctx)
+			if err != nil {
+				return fmt.Errorf("household: count Regulars: %w", err)
+			}
+			if n < MinRegulars {
+				return &ValidationError{Problems: []Problem{{
+					Field:  "onboarding_completed",
+					Reason: fmt.Sprintf("add at least %d Regulars first (have %d)", MinRegulars, n),
+				}}}
+			}
+			p.OnboardingCompletedAt = sql.NullString{String: p.UpdatedAt, Valid: true}
+		}
 		row, err = q.UpsertHouseholdSettings(ctx, p)
 		if err != nil {
 			return fmt.Errorf("household: update settings: %w", err)
@@ -291,6 +315,9 @@ func (p SettingsPatch) validate() error {
 			fail(d.field, fmt.Sprintf("invalid day of the week %d (want 0-6, Sunday = 0)", *d.value))
 		}
 	}
+	if p.OnboardingCompleted != nil && !*p.OnboardingCompleted {
+		fail("onboarding_completed", "onboarding cannot be undone (want true)")
+	}
 	if len(problems) > 0 {
 		return &ValidationError{Problems: problems}
 	}

internal/household/settings_test.go

@@ -3,10 +3,13 @@ package household
 import (
 	"context"
 	"errors"
+	"fmt"
 	"slices"
+	"strings"
 	"sync"
 	"testing"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
@@ -34,12 +37,34 @@ func migratedStore(t *testing.T, dir string) *store.Store {
 // seededService returns a settings service over a migrated temp database
 // seeded with zone America/New_York.
 func seededService(t *testing.T) *SettingsService {
+	t.Helper()
+	svc, _ := seededServiceStore(t)
+	return svc
+}
+
+// seededServiceStore is seededService with its store.
+func seededServiceStore(t *testing.T) (*SettingsService, *store.Store) {
 	t.Helper()
 	st := migratedStore(t, t.TempDir())
 	if err := SeedSettings(context.Background(), st, "America/New_York"); err != nil {
 		t.Fatal(err)
 	}
-	return NewSettingsService(st)
+	return NewSettingsService(st), st
+}
+
+// addDinners stores n dinners with status.
+func addDinners(t *testing.T, st *store.Store, status string, n int) {
+	t.Helper()
+	for range n {
+		id := store.NewID()
+		now := store.Now().String()
+		if _, err := db.New(st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+			ID: id, Name: "Dinner " + id, NormalizedName: "dinner " + strings.ToLower(id),
+			Status: status, Origin: "regular", GroundingStatus: "pending", CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
 }
 
 func ptr[T any](v T) *T { return &v }
@@ -217,6 +242,70 @@ func TestUpdateAppliesPatchAndRecordsUpdatedBy(t *testing.T) {
 	}
 }
 
+func TestUpdateCompletesOnboardingOnce(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	svc, st := seededServiceStore(t)
+	addDinners(t, st, "regular", MinRegulars)
+
+	got, err := svc.Update(ctx, SettingsPatch{OnboardingCompleted: ptr(true)}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.OnboardingCompletedAt == nil || *got.OnboardingCompletedAt != got.UpdatedAt {
+		t.Fatalf("onboarding_completed_at = %v, want the update time %s", got.OnboardingCompletedAt, got.UpdatedAt)
+	}
+	first := *got.OnboardingCompletedAt
+
+	// Completing again keeps the first time.
+	got, err = svc.Update(ctx, SettingsPatch{OnboardingCompleted: ptr(true)}, "alex")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.OnboardingCompletedAt == nil || *got.OnboardingCompletedAt != first {
+		t.Errorf("second completion: onboarding_completed_at = %v, want %s", got.OnboardingCompletedAt, first)
+	}
+
+	// Other changes leave it alone.
+	got, err = svc.Update(ctx, SettingsPatch{DinnerTime: ptr("18:00")}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.OnboardingCompletedAt == nil || *got.OnboardingCompletedAt != first {
+		t.Errorf("after another change: onboarding_completed_at = %v, want %s", got.OnboardingCompletedAt, first)
+	}
+}
+
+// TestUpdateOnboardingNeedsMinRegulars: onboarding cannot be completed
+// with fewer than MinRegulars Regulars; archived and Quest log dinners do
+// not count.
+func TestUpdateOnboardingNeedsMinRegulars(t *testing.T) {
+	t.Parallel()
+	for regulars := range MinRegulars {
+		t.Run(fmt.Sprintf("%d Regulars", regulars), func(t *testing.T) {
+			t.Parallel()
+			ctx := context.Background()
+			svc, st := seededServiceStore(t)
+			addDinners(t, st, "regular", regulars)
+			addDinners(t, st, "archived", MinRegulars)
+			addDinners(t, st, "quest_log", MinRegulars)
+
+			_, err := svc.Update(ctx, SettingsPatch{OnboardingCompleted: ptr(true)}, "sam")
+			var verr *ValidationError
+			if !errors.As(err, &verr) || len(verr.Problems) != 1 || verr.Problems[0].Field != "onboarding_completed" {
+				t.Fatalf("Update = %v, want a ValidationError on onboarding_completed", err)
+			}
+			got, err := svc.Get(ctx)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.OnboardingCompletedAt != nil {
+				t.Errorf("onboarding_completed_at = %s after a refused completion, want null", *got.OnboardingCompletedAt)
+			}
+		})
+	}
+}
+
 func TestUpdateRequiresMember(t *testing.T) {
 	t.Parallel()
 	ctx := context.Background()
@@ -259,6 +348,7 @@ func TestUpdateValidation(t *testing.T) {
 		{"dow 7", SettingsPatch{PlanDraftDow: ptr(7)}, []string{"plan_draft_dow"}},
 		{"dow -1", SettingsPatch{SuggestionsDow: ptr(-1)}, []string{"suggestions_dow"}},
 		{"dow 100", SettingsPatch{ChatAutosendDow: ptr(100)}, []string{"chat_autosend_dow"}},
+		{"onboarding undone", SettingsPatch{OnboardingCompleted: ptr(false)}, []string{"onboarding_completed"}},
 		{
 			"every problem is reported",
 			SettingsPatch{Timezone: ptr("Nowhere"), DinnerTime: ptr("5pm"), PlanDraftDow: ptr(9)},

internal/recipes/fetcher_test.go

@@ -564,9 +564,11 @@ func TestFetchCacheIsNotSharedWithCallers(t *testing.T) {
 	}
 }
 
-// TestFetchCanceledWaitHoldsNoSlot covers a burst of fetches whose
+// TestFetchCanceledWaitHoldsNoSlot covers a burst of requests whose
 // rate-limit waits end with their context: they must not push back the
-// next request that is allowed through.
+// next request that is allowed through. The burst calls waitTurn, the wait
+// turnConn's first Write makes, directly: through Fetch, net/http races the
+// failed write against its read loop, so the error it returns varies.
 func TestFetchCanceledWaitHoldsNoSlot(t *testing.T) {
 	t.Parallel()
 	env := newTestEnv(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -577,14 +579,24 @@ func TestFetchCanceledWaitHoldsNoSlot(t *testing.T) {
 	if _, err := env.f.Fetch(t.Context(), "https://example.com/first"); err != nil {
 		t.Fatalf("first Fetch: %v", err)
 	}
+	firstSent := clock.now()
 	env.f.sleep = func(context.Context, time.Duration) error { return context.DeadlineExceeded }
 	for i := range 5 {
-		if _, err := env.f.Fetch(t.Context(), fmt.Sprintf("https://example.com/burst/%d", i)); !errors.Is(err, context.DeadlineExceeded) {
-			t.Fatalf("burst Fetch %d error = %v, want context.DeadlineExceeded", i, err)
+		// Each request comes later in the interval, so a slot it took
+		// would delay the request after the burst.
+		clock.advance(HostInterval / 10)
+		if _, err := env.f.waitTurn(t.Context(), "example.com"); !errors.Is(err, context.DeadlineExceeded) {
+			t.Fatalf("burst waitTurn %d error = %v, want context.DeadlineExceeded", i, err)
 		}
 	}
+	env.f.mu.Lock()
+	last := env.f.lastSent["example.com"]
+	env.f.mu.Unlock()
+	if !last.Equal(firstSent) {
+		t.Errorf("host slot taken at %s after the burst, want the first send at %s", last, firstSent)
+	}
 	env.f.sleep = clock.sleep
-	clock.advance(HostInterval)
+	clock.advance(firstSent.Add(HostInterval).Sub(clock.now()))
 	if _, err := env.f.Fetch(t.Context(), "https://example.com/after"); err != nil {
 		t.Fatalf("Fetch after the burst: %v", err)
 	}

internal/recipes/ground.go

@@ -0,0 +1,541 @@
+package recipes
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// GroundConcurrency is how many items GroundMany grounds at once.
+const GroundConcurrency = 3
+
+var (
+	// ErrNoCandidates is a reason a dish is ungroundable: the search found
+	// no pages at all.
+	ErrNoCandidates = errors.New("recipes: search found no candidates")
+	// ErrTotalTimeNotPositive rejects a recipe whose page gives a total
+	// time of zero minutes, which normalize_recipe refuses.
+	ErrTotalTimeNotPositive = errors.New("recipes: recipe total time is not positive")
+	// ErrSearchFailed wraps every failure to search: the search provider
+	// could not be built (ErrSearchNotConfigured among them) or its search
+	// failed.
+	ErrSearchFailed = errors.New("recipes: recipe search failed")
+	// ErrNormalizeFailed wraps a normalize_recipe failure that is not the
+	// recipe's: the model provider could not be built or called.
+	ErrNormalizeFailed = errors.New("recipes: normalize_recipe failed")
+)
+
+// ErrUngroundable is returned when no recipe page could ground a dish or a
+// pasted URL. Reasons says why each page tried was rejected, or why there
+// were none; errors.Is matches any of them.
+type ErrUngroundable struct {
+	// Target is the dish name or the URL.
+	Target  string
+	Reasons []error
+}
+
+func (e *ErrUngroundable) Error() string {
+	parts := make([]string, len(e.Reasons))
+	for i, r := range e.Reasons {
+		parts[i] = r.Error()
+	}
+	return fmt.Sprintf("recipes: cannot ground %q: %s", e.Target, strings.Join(parts, "; "))
+}
+
+func (e *ErrUngroundable) Unwrap() []error { return e.Reasons }
+
+// Grounded is a recipe stored for a dish: the recipe and its cached photo,
+// with normalize_recipe's method, minutes and difficulty.
+type Grounded struct {
+	RecipeID string `json:"recipe_id"`
+	PhotoID  string `json:"photo_id"`
+	// Method is stovetop, oven, crockpot, grill or other.
+	Method string `json:"method"`
+	// MinutesTotal is prep to table, nil when unknown.
+	MinutesTotal *int `json:"minutes_total"`
+	// Difficulty is easy, medium or hard.
+	Difficulty string `json:"difficulty"`
+	SourceURL  string `json:"source_url"`
+	SiteName   string `json:"site_name"`
+}
+
+// SearchSource returns the household's current search provider;
+// *SearchSettingsService satisfies it.
+type SearchSource interface {
+	Provider(ctx context.Context) (SearchProvider, error)
+}
+
+// Normalizer runs normalize_recipe on a recipe; scope is its source URL. In
+// production it is skills.NormalizeRecipe with the household's
+// harness.Config.
+type Normalizer func(ctx context.Context, scope string, in skills.RecipeText) (skills.NormalizedRecipe, error)
+
+// Grounder grounds dishes in recipe pages: it searches, fetches, extracts
+// and ranks candidates, caches the best one's photo, normalizes its
+// ingredients and stores it all. It is safe for concurrent use.
+type Grounder struct {
+	st        *store.Store
+	search    SearchSource
+	pages     PageFetcher
+	photos    *PhotoCache
+	normalize Normalizer
+}
+
+// NewGrounder returns a Grounder storing recipes in st, searching with
+// search, fetching pages with pages, caching photos with photos and
+// normalizing with normalize.
+func NewGrounder(st *store.Store, search SearchSource, pages PageFetcher, photos *PhotoCache, normalize Normalizer) (*Grounder, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("recipes: nil store")
+	case search == nil:
+		return nil, errors.New("recipes: nil search source")
+	case pages == nil:
+		return nil, errors.New("recipes: nil page fetcher")
+	case photos == nil:
+		return nil, errors.New("recipes: nil photo cache")
+	case normalize == nil:
+		return nil, errors.New("recipes: nil normalizer")
+	}
+	return &Grounder{st: st, search: search, pages: pages, photos: photos, normalize: normalize}, nil
+}
+
+// Ground searches for query and grounds dishName in the best recipe found.
+// The candidates are ranked as Rank does, except that a candidate already
+// stored is scored on its stored recipe and never fetched. They are tried
+// best first: a stored candidate is returned as it is, and otherwise the
+// first whose photo can be cached and whose ingredients normalize is stored
+// — the recipe, its ingredients, steps and photo in one transaction — and
+// returned. A stored recipe is reused only when it ranks above every
+// candidate that grounds.
+//
+// When no candidate grounds the dish the error is an *ErrUngroundable with
+// each reason. A failure that is not the candidates' — the search, the
+// model provider, the database — is returned as it is.
+func (g *Grounder) Ground(ctx context.Context, dishName, query string) (Grounded, error) {
+	if strings.TrimSpace(dishName) == "" {
+		return Grounded{}, errors.New("recipes: ground: dish name is empty")
+	}
+	found, err := g.searchRanked(ctx, dishName, query)
+	if err != nil {
+		return Grounded{}, fmt.Errorf("recipes: ground %q: %w", dishName, err)
+	}
+	var reasons []error
+	if found.rankErr != nil {
+		reasons = append(reasons, found.rankErr)
+	}
+	for _, r := range found.ranked {
+		if sr, ok := found.stored[r.Candidate.URL]; ok {
+			return sr.grounded, nil
+		}
+		gr, reason, err := g.ground(ctx, r.Candidate.URL, r.Recipe)
+		if err != nil {
+			return Grounded{}, fmt.Errorf("recipes: ground %q: %w", dishName, err)
+		}
+		if reason == nil {
+			return gr, nil
+		}
+		reasons = append(reasons, fmt.Errorf("%s: %w", r.Candidate.URL, reason))
+	}
+	return Grounded{}, &ErrUngroundable{Target: dishName, Reasons: reasons}
+}
+
+// rankedSearch is a search's candidates ranked: the ranked ones best first,
+// those already stored by URL, and why any were not ranked.
+type rankedSearch struct {
+	ranked []Ranked
+	stored map[string]storedRecipe
+	// rankErr is Rank's error, or ErrNoCandidates when the search found
+	// nothing.
+	rankErr error
+}
+
+// searchRanked searches for query and ranks the top RankDepth candidates
+// for dishName as Ground describes. A search, database or context failure
+// is its error; candidates that do not rank are only rankErr's.
+func (g *Grounder) searchRanked(ctx context.Context, dishName, query string) (rankedSearch, error) {
+	provider, err := g.search.Provider(ctx)
+	if err != nil {
+		return rankedSearch{}, fmt.Errorf("%w: %w", ErrSearchFailed, err)
+	}
+	cands, err := provider.Search(ctx, query, RankDepth)
+	if err != nil {
+		return rankedSearch{}, fmt.Errorf("%w: %w", ErrSearchFailed, err)
+	}
+	if len(cands) == 0 {
+		return rankedSearch{rankErr: ErrNoCandidates}, nil
+	}
+	cands = cands[:min(len(cands), RankDepth)]
+	stored := make(map[string]storedRecipe)
+	for _, c := range cands {
+		sr, ok, err := g.storedRecipe(ctx, c.URL)
+		if err != nil {
+			return rankedSearch{}, err
+		}
+		if ok {
+			stored[c.URL] = sr
+		}
+	}
+	ranked, rankErr := rank(ctx, dishName, cands, func(ctx context.Context, c Candidate) (Recipe, error) {
+		if sr, ok := stored[c.URL]; ok {
+			return sr.recipe, nil
+		}
+		return fetchRecipe(ctx, g.pages, c.URL)
+	})
+	if err := ctx.Err(); err != nil {
+		return rankedSearch{}, err
+	}
+	return rankedSearch{ranked: ranked, stored: stored, rankErr: rankErr}, nil
+}
+
+// Offer is a ranked candidate offered for the household to ground a dish
+// in, with GroundURL on its URL.
+type Offer struct {
+	URL      string
+	Title    string
+	SiteName string
+	// PhotoID is the cached photo of a candidate already stored, "" for
+	// one that is not: a candidate's photo is cached only when it grounds.
+	PhotoID string
+	// Minutes is a stored candidate's normalized minutes_total, else its
+	// page's total time; nil when unknown.
+	Minutes *int
+}
+
+// Candidates searches for query and returns up to n of the candidates
+// Ground would try for dishName, best first. It fetches and extracts pages
+// but downloads no photo and runs no model. Candidates that hold no usable
+// recipe are not offered, so the list may be empty; a search that fails is
+// an error wrapping ErrSearchFailed.
+func (g *Grounder) Candidates(ctx context.Context, dishName, query string, n int) ([]Offer, error) {
+	if strings.TrimSpace(dishName) == "" {
+		return nil, errors.New("recipes: candidates: dish name is empty")
+	}
+	if n < 1 {
+		return nil, fmt.Errorf("recipes: candidates: n is %d, want at least 1", n)
+	}
+	found, err := g.searchRanked(ctx, dishName, query)
+	if err != nil {
+		return nil, fmt.Errorf("recipes: candidates for %q: %w", dishName, err)
+	}
+	offers := make([]Offer, 0, min(n, len(found.ranked)))
+	for _, r := range found.ranked[:min(n, len(found.ranked))] {
+		o := Offer{URL: r.Candidate.URL, Title: r.Recipe.Title, SiteName: r.Recipe.SiteName, Minutes: r.Recipe.TotalMinutes}
+		if sr, ok := found.stored[r.Candidate.URL]; ok {
+			o.PhotoID = sr.grounded.PhotoID
+			o.Minutes = sr.grounded.MinutesTotal
+		}
+		offers = append(offers, o)
+	}
+	return offers, nil
+}
+
+// GroundURL grounds the recipe on the page at rawURL, a pasted URL, as
+// Ground does a candidate. An already stored rawURL is returned without
+// fetching it. A page that cannot be fetched, holds no usable recipe, or
+// whose photo or ingredients fail is an *ErrUngroundable.
+func (g *Grounder) GroundURL(ctx context.Context, rawURL string) (Grounded, error) {
+	if gr, ok, err := g.stored(ctx, rawURL); err != nil || ok {
+		return gr, err
+	}
+	ungroundable := func(err error) (Grounded, error) {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return Grounded{}, ctxErr
+		}
+		return Grounded{}, &ErrUngroundable{Target: rawURL, Reasons: []error{err}}
+	}
+	page, err := g.pages.Fetch(ctx, rawURL)
+	if err != nil {
+		return ungroundable(err)
+	}
+	r, err := Extract(page.Body, page.URL)
+	if err != nil {
+		return ungroundable(err)
+	}
+	if err := usable(r); err != nil {
+		return ungroundable(err)
+	}
+	gr, reason, err := g.ground(ctx, rawURL, r)
+	if err != nil {
+		return Grounded{}, fmt.Errorf("recipes: ground pasted link: %w", err)
+	}
+	if reason != nil {
+		return ungroundable(reason)
+	}
+	return gr, nil
+}
+
+// GroundRequest is one dish for GroundMany.
+type GroundRequest struct {
+	DishName string
+	Query    string
+}
+
+// GroundResult is one GroundMany outcome: Grounded, or Err when the item
+// failed.
+type GroundResult struct {
+	Grounded Grounded
+	Err      error
+}
+
+// GroundMany grounds each request with Ground, GroundConcurrency at a time,
+// and returns their results in request order. One item's failure does not
+// affect the others.
+func (g *Grounder) GroundMany(ctx context.Context, reqs []GroundRequest) []GroundResult {
+	results := make([]GroundResult, len(reqs))
+	slots := make(chan struct{}, GroundConcurrency)
+	var wg sync.WaitGroup
+	for i, req := range reqs {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			select {
+			case slots <- struct{}{}:
+			case <-ctx.Done():
+				results[i] = GroundResult{Err: ctx.Err()}
+				return
+			}
+			defer func() { <-slots }()
+			gr, err := g.Ground(ctx, req.DishName, req.Query)
+			results[i] = GroundResult{Grounded: gr, Err: err}
+		}()
+	}
+	wg.Wait()
+	return results
+}
+
+// stored returns the grounding of the recipe stored for sourceURL, and
+// false when there is none.
+func (g *Grounder) stored(ctx context.Context, sourceURL string) (Grounded, bool, error) {
+	row, ok, err := g.storedRow(ctx, sourceURL)
+	if err != nil || !ok {
+		return Grounded{}, false, err
+	}
+	return groundedFrom(row), true, nil
+}
+
+// storedRow returns the recipe row stored for sourceURL, and false when
+// there is none.
+func (g *Grounder) storedRow(ctx context.Context, sourceURL string) (db.Recipe, bool, error) {
+	row, err := db.New(g.st.Reader).GetRecipeBySourceURL(ctx, sourceURL)
+	if errors.Is(err, sql.ErrNoRows) {
+		return db.Recipe{}, false, nil
+	}
+	if err != nil {
+		return db.Recipe{}, false, fmt.Errorf("recipes: look up recipe %s: %w", sourceURL, err)
+	}
+	if !row.PhotoID.Valid || !row.Method.Valid || !row.Difficulty.Valid {
+		return db.Recipe{}, false, fmt.Errorf("recipes: stored recipe %s for %s has no photo, method or difficulty", row.ID, sourceURL)
+	}
+	return row, true, nil
+}
+
+// storedRecipe is a recipe already stored: its grounding, and the recipe
+// rebuilt from what was stored so it can be ranked without its page.
+type storedRecipe struct {
+	grounded Grounded
+	recipe   Recipe
+}
+
+// storedRecipe returns the recipe stored for sourceURL with its photo,
+// ingredients and steps, and false when there is none.
+func (g *Grounder) storedRecipe(ctx context.Context, sourceURL string) (storedRecipe, bool, error) {
+	row, ok, err := g.storedRow(ctx, sourceURL)
+	if err != nil || !ok {
+		return storedRecipe{}, false, err
+	}
+	gr := groundedFrom(row)
+	q := db.New(g.st.Reader)
+	photo, err := q.GetPhoto(ctx, gr.PhotoID)
+	if err != nil {
+		return storedRecipe{}, false, fmt.Errorf("recipes: load photo %s of recipe %s: %w", gr.PhotoID, gr.RecipeID, err)
+	}
+	ings, err := q.ListRecipeIngredients(ctx, gr.RecipeID)
+	if err != nil {
+		return storedRecipe{}, false, fmt.Errorf("recipes: load ingredients of recipe %s: %w", gr.RecipeID, err)
+	}
+	steps, err := q.ListRecipeSteps(ctx, gr.RecipeID)
+	if err != nil {
+		return storedRecipe{}, false, fmt.Errorf("recipes: load steps of recipe %s: %w", gr.RecipeID, err)
+	}
+	r := Recipe{
+		Title:        row.Title,
+		SiteName:     row.SiteName.String,
+		ImageURL:     photo.SourceUrl,
+		PrepMinutes:  intFrom(row.PrepMinutes),
+		CookMinutes:  intFrom(row.CookMinutes),
+		TotalMinutes: intFrom(row.TotalMinutes),
+		Yield:        row.Yield.String,
+		JSONLD:       json.RawMessage(row.RawJsonld),
+	}
+	for _, ing := range ings {
+		r.Ingredients = append(r.Ingredients, ing.RawText)
+	}
+	for _, st := range steps {
+		r.Steps = append(r.Steps, st.Text)
+	}
+	return storedRecipe{grounded: gr, recipe: r}, true, nil
+}
+
+// ground downloads r's photo, normalizes it and stores it as sourceURL's
+// recipe. A problem with this recipe is returned as reason, so the caller
+// can try another; err is a failure that is not the recipe's.
+//
+// The order is fixed: the photo is downloaded and validated first, so a
+// recipe without a usable photo never costs a normalize_recipe call; then
+// normalize_recipe runs; then save records the photo (CachePhoto) and the
+// recipe in one transaction.
+func (g *Grounder) ground(ctx context.Context, sourceURL string, r Recipe) (gr Grounded, reason, err error) {
+	photo, err := g.photos.DownloadPhoto(ctx, r.ImageURL)
+	if err != nil {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return Grounded{}, nil, ctxErr
+		}
+		return Grounded{}, fmt.Errorf("photo: %w", err), nil
+	}
+	norm, err := g.normalize(ctx, sourceURL, skills.RecipeText{
+		Title:        r.Title,
+		Ingredients:  r.Ingredients,
+		Steps:        r.Steps,
+		PrepMinutes:  r.PrepMinutes,
+		CookMinutes:  r.CookMinutes,
+		TotalMinutes: r.TotalMinutes,
+	})
+	if errors.Is(err, llm.ErrBadOutput) {
+		return Grounded{}, fmt.Errorf("normalize: %w", err), nil
+	}
+	if err != nil {
+		return Grounded{}, nil, fmt.Errorf("%w: %w", ErrNormalizeFailed, err)
+	}
+	if len(norm.Ingredients) != len(r.Ingredients) {
+		return Grounded{}, nil, fmt.Errorf("normalize: %d ingredients for %d lines", len(norm.Ingredients), len(r.Ingredients))
+	}
+	gr, err = g.save(ctx, sourceURL, r, photo, norm)
+	return gr, nil, err
+}
+
+// save stores the recipe, its ingredients and steps and its photo in one
+// transaction. A photo's files written for a transaction that does not
+// commit are removed.
+func (g *Grounder) save(ctx context.Context, sourceURL string, r Recipe, p DownloadedPhoto, norm skills.NormalizedRecipe) (Grounded, error) {
+	var (
+		row     db.Recipe
+		photo   db.Photo
+		created bool
+	)
+	err := g.st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		photo, created, err = g.photos.CachePhoto(ctx, tx, p)
+		if err != nil {
+			return err
+		}
+		q := db.New(tx)
+		now := store.Now().String()
+		row, err = q.UpsertRecipe(ctx, db.UpsertRecipeParams{
+			ID:           store.NewID(),
+			SourceUrl:    sourceURL,
+			SiteName:     sql.NullString{String: r.SiteName, Valid: r.SiteName != ""},
+			Title:        r.Title,
+			TotalMinutes: nullInt(r.TotalMinutes),
+			PrepMinutes:  nullInt(r.PrepMinutes),
+			CookMinutes:  nullInt(r.CookMinutes),
+			Yield:        sql.NullString{String: r.Yield, Valid: r.Yield != ""},
+			RawJsonld:    string(r.JSONLD),
+			PhotoID:      sql.NullString{String: photo.ID, Valid: true},
+			Method:       sql.NullString{String: norm.Method, Valid: true},
+			Difficulty:   sql.NullString{String: norm.Difficulty, Valid: true},
+			MinutesTotal: nullInt(norm.MinutesTotal),
+			FetchedAt:    now,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		})
+		if err != nil {
+			return fmt.Errorf("recipes: store recipe: %w", err)
+		}
+		if err := q.DeleteRecipeIngredients(ctx, row.ID); err != nil {
+			return fmt.Errorf("recipes: replace ingredients: %w", err)
+		}
+		if err := q.DeleteRecipeSteps(ctx, row.ID); err != nil {
+			return fmt.Errorf("recipes: replace steps: %w", err)
+		}
+		for i, line := range r.Ingredients {
+			ing := norm.Ingredients[i]
+			err := q.CreateRecipeIngredient(ctx, db.CreateRecipeIngredientParams{
+				ID:        store.NewID(),
+				RecipeID:  row.ID,
+				Position:  int64(i),
+				RawText:   line,
+				Name:      sql.NullString{String: ing.Name, Valid: true},
+				Qty:       sql.NullString{String: ing.Qty, Valid: ing.Qty != ""},
+				Unit:      sql.NullString{String: ing.Unit, Valid: ing.Unit != ""},
+				Note:      sql.NullString{String: ing.Note, Valid: ing.Note != ""},
+				CreatedAt: now,
+				UpdatedAt: now,
+			})
+			if err != nil {
+				return fmt.Errorf("recipes: store ingredient %d: %w", i+1, err)
+			}
+		}
+		for i, text := range r.Steps {
+			err := q.CreateRecipeStep(ctx, db.CreateRecipeStepParams{
+				ID:        store.NewID(),
+				RecipeID:  row.ID,
+				Position:  int64(i),
+				Text:      text,
+				CreatedAt: now,
+				UpdatedAt: now,
+			})
+			if err != nil {
+				return fmt.Errorf("recipes: store step %d: %w", i+1, err)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		if created {
+			err = errors.Join(err, g.photos.RemovePhotoFiles(photo.ID))
+		}
+		return Grounded{}, err
+	}
+	return groundedFrom(row), nil
+}
+
+func groundedFrom(row db.Recipe) Grounded {
+	gr := Grounded{
+		RecipeID:   row.ID,
+		PhotoID:    row.PhotoID.String,
+		Method:     row.Method.String,
+		Difficulty: row.Difficulty.String,
+		SourceURL:  row.SourceUrl,
+		SiteName:   row.SiteName.String,
+	}
+	if row.MinutesTotal.Valid {
+		m := int(row.MinutesTotal.Int64)
+		gr.MinutesTotal = &m
+	}
+	return gr
+}
+
+func intFrom(v sql.NullInt64) *int {
+	if !v.Valid {
+		return nil
+	}
+	n := int(v.Int64)
+	return &n
+}
+
+func nullInt(v *int) sql.NullInt64 {
+	if v == nil {
+		return sql.NullInt64{}
+	}
+	return sql.NullInt64{Int64: int64(*v), Valid: true}
+}

internal/recipes/ground_test.go

@@ -0,0 +1,553 @@
+package recipes
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// fakeSearch is a SearchSource and SearchProvider answering each query
+// from results, and failing a query in errs. With gate set, every Search
+// reports its query on started and waits for gate to close.
+type fakeSearch struct {
+	results map[string][]Candidate
+	errs    map[string]error
+	started chan string
+	gate    chan struct{}
+
+	mu        sync.Mutex
+	calls     int
+	active    int
+	maxActive int
+}
+
+func (s *fakeSearch) Provider(context.Context) (SearchProvider, error) { return s, nil }
+
+func (s *fakeSearch) Search(_ context.Context, query string, n int) ([]Candidate, error) {
+	s.mu.Lock()
+	s.calls++
+	s.active++
+	s.maxActive = max(s.maxActive, s.active)
+	s.mu.Unlock()
+	defer func() {
+		s.mu.Lock()
+		s.active--
+		s.mu.Unlock()
+	}()
+	if s.gate != nil {
+		s.started <- query
+		<-s.gate
+	}
+	if err := s.errs[query]; err != nil {
+		return nil, err
+	}
+	c := s.results[query]
+	return c[:min(n, len(c))], nil
+}
+
+func (s *fakeSearch) callCount() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.calls
+}
+
+func (f *fakeFetcher) fetchCount() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.fetched)
+}
+
+// groundPage is a recipe page for name with two ingredients, two steps, a
+// 40-minute total and the image at https://example.com{imagePath}.
+func groundPage(name, imagePath string) []byte {
+	return page(`<meta property="og:site_name" content="Example Kitchen">`, fmt.Sprintf(`{
+		"@context": "https://schema.org",
+		"@type": "Recipe",
+		"name": %q,
+		"image": "https://example.com%s",
+		"recipeIngredient": ["1 onion", "2 cloves garlic, minced"],
+		"recipeInstructions": ["Chop the onion.", "Fry with the garlic."],
+		"totalTime": "PT40M",
+		"recipeYield": "4"
+	}`, name, imagePath))
+}
+
+// normalizedReply is a usable normalize_recipe reply for groundPage.
+func normalizedReply() llm.GenerateResult {
+	js := `{"ingredients":[
+		{"name":"onion","qty":"1","unit":"","note":""},
+		{"name":"garlic","qty":"2","unit":"cloves","note":"minced"}
+	],"method":"stovetop","difficulty":null,"minutes_total":40}`
+	return llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}}
+}
+
+// badReply is a normalize_recipe reply that fails validation.
+func badReply() llm.GenerateResult {
+	js := `{"ingredients":[],"method":"stovetop","difficulty":null,"minutes_total":40}`
+	return llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}}
+}
+
+type groundEnv struct {
+	g       *Grounder
+	st      *store.Store
+	dataDir string
+	images  *photoServer
+	pages   *fakeFetcher
+	search  *fakeSearch
+	llm     *llm.Fake
+}
+
+// newGroundEnv returns a Grounder over pages, images served at
+// https://example.com, search and a fake model, normalizing through the
+// real harness and normalize_recipe skill.
+func newGroundEnv(t *testing.T, pages map[string][]byte, images map[string]photoFile, search *fakeSearch) *groundEnv {
+	t.Helper()
+	photos, st, dataDir, imgSrv := newTestPhotoCache(t, images)
+	model := &llm.Fake{}
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := harness.Config{
+		Settings:    llm.Settings{Provider: "anthropic", Model: "claude-test"},
+		NewProvider: func(llm.Settings, string) (llm.Provider, error) { return model, nil },
+		Store:       st,
+		Guard:       guard,
+	}
+	normalize := func(ctx context.Context, scope string, in skills.RecipeText) (skills.NormalizedRecipe, error) {
+		return skills.NormalizeRecipe(ctx, cfg, scope, in)
+	}
+	fetcher := &fakeFetcher{pages: pages}
+	g, err := NewGrounder(st, search, fetcher, photos, normalize)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &groundEnv{g: g, st: st, dataDir: dataDir, images: imgSrv, pages: fetcher, search: search, llm: model}
+}
+
+func jpegFile(t *testing.T, w, h int) photoFile {
+	return photoFile{"image/jpeg", encodeJPEG(t, gradient(w, h))}
+}
+
+func countRows(t *testing.T, st *store.Store, table string) int {
+	t.Helper()
+	var n int
+	if err := st.Reader.QueryRowContext(context.Background(), "SELECT count(*) FROM "+table).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
+func TestGroundHappyPath(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{results: map[string][]Candidate{
+		"chicken curry": {
+			{URL: "https://a.example/missing"},
+			{URL: "https://b.example/curry"},
+		},
+	}}
+	env := newGroundEnv(t,
+		map[string][]byte{"https://b.example/curry": groundPage("Chicken Curry", "/img/curry.jpg")},
+		map[string]photoFile{"/img/curry.jpg": jpegFile(t, 800, 600)},
+		search)
+	env.llm.QueueGenerate(normalizedReply())
+
+	gr, err := env.g.Ground(t.Context(), "Chicken Curry", "chicken curry")
+	if err != nil {
+		t.Fatalf("Ground: %v", err)
+	}
+	if gr.RecipeID == "" || gr.PhotoID == "" {
+		t.Fatalf("Grounded = %+v, want recipe and photo ids", gr)
+	}
+	want := Grounded{
+		RecipeID: gr.RecipeID, PhotoID: gr.PhotoID, Method: "stovetop", MinutesTotal: gr.MinutesTotal,
+		Difficulty: "easy", SourceURL: "https://b.example/curry", SiteName: "Example Kitchen",
+	}
+	if gr != want || gr.MinutesTotal == nil || *gr.MinutesTotal != 40 {
+		t.Errorf("Grounded = %+v (minutes %v), want %+v with 40 minutes", gr, gr.MinutesTotal, want)
+	}
+
+	q := db.New(env.st.Reader)
+	rec, err := q.GetRecipe(t.Context(), gr.RecipeID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rec.Title != "Chicken Curry" || rec.PhotoID.String != gr.PhotoID || rec.Method.String != "stovetop" ||
+		rec.Difficulty.String != "easy" || rec.MinutesTotal.Int64 != 40 || rec.TotalMinutes.Int64 != 40 || rec.Yield.String != "4" {
+		t.Errorf("recipe row = %+v", rec)
+	}
+	ings, err := q.ListRecipeIngredients(t.Context(), gr.RecipeID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ings) != 2 || ings[1].RawText != "2 cloves garlic, minced" || ings[1].Name.String != "garlic" ||
+		ings[1].Qty.String != "2" || ings[1].Unit.String != "cloves" || ings[1].Note.String != "minced" || ings[0].Unit.Valid {
+		t.Errorf("ingredients = %+v", ings)
+	}
+	steps, err := q.ListRecipeSteps(t.Context(), gr.RecipeID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 2 || steps[0].Text != "Chop the onion." || steps[1].Position != 1 {
+		t.Errorf("steps = %+v", steps)
+	}
+	photo, err := q.GetPhoto(t.Context(), gr.PhotoID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if photo.SourceUrl != "https://example.com/img/curry.jpg" {
+		t.Errorf("photo row = %+v", photo)
+	}
+	if _, err := os.Stat(filepath.Join(env.dataDir, filepath.FromSlash(photo.LocalPath))); err != nil {
+		t.Errorf("photo file: %v", err)
+	}
+}
+
+func TestGroundUngroundable(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{results: map[string][]Candidate{
+		"mystery stew": {
+			{URL: "https://a.example/missing"},
+			{URL: "https://b.example/no-recipe"},
+			{URL: "https://c.example/tiny-photo"},
+		},
+	}}
+	env := newGroundEnv(t,
+		map[string][]byte{
+			"https://b.example/no-recipe":  page(""),
+			"https://c.example/tiny-photo": groundPage("Mystery Stew", "/img/tiny.jpg"),
+		},
+		map[string]photoFile{"/img/tiny.jpg": jpegFile(t, 200, 200)},
+		search)
+
+	_, err := env.g.Ground(t.Context(), "Mystery Stew", "mystery stew")
+	var ungroundable *ErrUngroundable
+	if !errors.As(err, &ungroundable) {
+		t.Fatalf("Ground error = %v, want *ErrUngroundable", err)
+	}
+	if ungroundable.Target != "Mystery Stew" {
+		t.Errorf("Target = %q", ungroundable.Target)
+	}
+	for _, reason := range []error{ErrCandidatesUnranked, ErrNoRecipe, ErrPhotoTooSmall} {
+		if !errors.Is(err, reason) {
+			t.Errorf("error %v does not report %v", err, reason)
+		}
+	}
+	if n := len(env.llm.Requests()); n != 0 {
+		t.Errorf("%d model calls, want none before a photo is cached", n)
+	}
+	for _, table := range []string{"recipes", "recipe_ingredients", "photos"} {
+		if n := countRows(t, env.st, table); n != 0 {
+			t.Errorf("%d %s rows for an ungroundable dish", n, table)
+		}
+	}
+	if names := photoFiles(t, env.dataDir); len(names) != 0 {
+		t.Errorf("photo files stored for an ungroundable dish: %v", names)
+	}
+
+	_, err = env.g.Ground(t.Context(), "Nothing At All", "nothing at all")
+	if !errors.As(err, &ungroundable) || !errors.Is(err, ErrNoCandidates) {
+		t.Errorf("Ground with no search results error = %v, want *ErrUngroundable with ErrNoCandidates", err)
+	}
+}
+
+func TestGroundTriesNextCandidateAfterBadOutput(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{results: map[string][]Candidate{
+		"curry": {{URL: "https://a.example/curry"}, {URL: "https://b.example/curry"}},
+	}}
+	env := newGroundEnv(t,
+		map[string][]byte{
+			"https://a.example/curry": groundPage("Curry", "/img/a.jpg"),
+			"https://b.example/curry": groundPage("Curry", "/img/b.jpg"),
+		},
+		map[string]photoFile{"/img/a.jpg": jpegFile(t, 640, 480), "/img/b.jpg": jpegFile(t, 480, 640)},
+		search)
+	// The first candidate's reply and repair are unusable; the second's is
+	// fine.
+	env.llm.QueueGenerate(badReply(), badReply(), normalizedReply())
+
+	gr, err := env.g.Ground(t.Context(), "Curry", "curry")
+	if err != nil {
+		t.Fatalf("Ground: %v", err)
+	}
+	if gr.SourceURL != "https://b.example/curry" {
+		t.Errorf("grounded in %s, want the second candidate", gr.SourceURL)
+	}
+	if n := countRows(t, env.st, "photos"); n != 1 {
+		t.Errorf("%d photos rows, want only the grounded recipe's", n)
+	}
+}
+
+func TestGroundSearchFailureIsNotUngroundable(t *testing.T) {
+	t.Parallel()
+	env := newGroundEnv(t, nil, nil, &fakeSearch{errs: map[string]error{"curry": ErrSearchRateLimited}})
+	_, err := env.g.Ground(t.Context(), "Curry", "curry")
+	var ungroundable *ErrUngroundable
+	if !errors.Is(err, ErrSearchRateLimited) || errors.As(err, &ungroundable) {
+		t.Errorf("Ground error = %v, want ErrSearchRateLimited and not *ErrUngroundable", err)
+	}
+}
+
+func TestGroundReusesStoredRecipe(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{results: map[string][]Candidate{
+		"curry":         {{URL: "https://b.example/curry"}},
+		"chicken curry": {{URL: "https://a.example/other"}, {URL: "https://b.example/curry"}},
+	}}
+	env := newGroundEnv(t,
+		map[string][]byte{"https://b.example/curry": groundPage("Curry", "/img/curry.jpg")},
+		map[string]photoFile{"/img/curry.jpg": jpegFile(t, 640, 480)},
+		search)
+	env.llm.QueueGenerate(normalizedReply())
+
+	first, err := env.g.Ground(t.Context(), "Curry", "curry")
+	if err != nil {
+		t.Fatalf("first Ground: %v", err)
+	}
+	pages, images, calls := env.pages.fetchCount(), env.images.requests.Load(), len(env.llm.Requests())
+
+	// The stored page is gone and the model has no reply left: only the
+	// stored recipe can ground the dish.
+	delete(env.pages.pages, "https://b.example/curry")
+	again, err := env.g.Ground(t.Context(), "Chicken Curry", "chicken curry")
+	if err != nil {
+		t.Fatalf("second Ground: %v", err)
+	}
+	if again.RecipeID != first.RecipeID || again.PhotoID != first.PhotoID || again.Method != first.Method ||
+		again.Difficulty != first.Difficulty || *again.MinutesTotal != *first.MinutesTotal || again.SiteName != first.SiteName {
+		t.Errorf("reused grounding = %+v, want %+v", again, first)
+	}
+	if env.images.requests.Load() != images || len(env.llm.Requests()) != calls {
+		t.Errorf("reuse fetched images %d→%d, model calls %d→%d; want none",
+			images, env.images.requests.Load(), calls, len(env.llm.Requests()))
+	}
+	// Ranking fetches only the candidate not stored; the stored one ranks
+	// on its stored recipe.
+	env.pages.mu.Lock()
+	fetched := append([]string(nil), env.pages.fetched[pages:]...)
+	env.pages.mu.Unlock()
+	if len(fetched) != 1 || fetched[0] != "https://a.example/other" {
+		t.Errorf("reuse fetched %v, want only https://a.example/other", fetched)
+	}
+	pages = env.pages.fetchCount()
+
+	byURL, err := env.g.GroundURL(t.Context(), "https://b.example/curry")
+	if err != nil || byURL.RecipeID != first.RecipeID {
+		t.Errorf("GroundURL of the stored page = %+v, %v; want the stored recipe", byURL, err)
+	}
+	if env.pages.fetchCount() != pages {
+		t.Error("GroundURL refetched a stored page")
+	}
+	if n := countRows(t, env.st, "recipes"); n != 1 {
+		t.Errorf("%d recipes rows, want 1", n)
+	}
+}
+
+func TestGroundStoredRecipeDoesNotOutrankRelevantOne(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{results: map[string][]Candidate{
+		"brownies":      {{URL: "https://b.example/brownies"}},
+		"chicken curry": {{URL: "https://b.example/brownies"}, {URL: "https://a.example/curry"}},
+	}}
+	env := newGroundEnv(t,
+		map[string][]byte{
+			"https://a.example/curry":    groundPage("Chicken Curry", "/img/curry.jpg"),
+			"https://b.example/brownies": groundPage("Fudgy Brownies", "/img/brownies.jpg"),
+		},
+		map[string]photoFile{
+			"/img/curry.jpg":    jpegFile(t, 640, 480),
+			"/img/brownies.jpg": jpegFile(t, 640, 480),
+		},
+		search)
+	env.llm.QueueGenerate(normalizedReply(), normalizedReply())
+
+	brownies, err := env.g.Ground(t.Context(), "Brownies", "brownies")
+	if err != nil {
+		t.Fatalf("Ground brownies: %v", err)
+	}
+
+	// Search lists the unrelated stored recipe first and the relevant new
+	// one second: ranking, not search order or storage, grounds the
+	// relevant one.
+	curry, err := env.g.Ground(t.Context(), "Chicken Curry", "chicken curry")
+	if err != nil {
+		t.Fatalf("Ground chicken curry: %v", err)
+	}
+	if curry.SourceURL != "https://a.example/curry" || curry.RecipeID == brownies.RecipeID {
+		t.Errorf("grounded Chicken Curry in %s (recipe %s), want https://a.example/curry, not the stored brownies %s",
+			curry.SourceURL, curry.RecipeID, brownies.RecipeID)
+	}
+	if n := countRows(t, env.st, "recipes"); n != 2 {
+		t.Errorf("%d recipes rows, want 2", n)
+	}
+}
+
+func TestGroundURL(t *testing.T) {
+	t.Parallel()
+	env := newGroundEnv(t,
+		map[string][]byte{
+			"https://b.example/pasted":   groundPage("Grandma's Slow Cooker Chili", "/img/chili.jpg"),
+			"https://b.example/no-image": recipePage("Chili", true, false, true, true),
+			"https://b.example/no-time": page("", `{"@type":"Recipe","name":"Chili","image":"https://example.com/img/chili.jpg",
+				"recipeIngredient":["1 onion"],"totalTime":"PT0M"}`),
+		},
+		map[string]photoFile{"/img/chili.jpg": jpegFile(t, 640, 480)},
+		&fakeSearch{})
+	env.llm.QueueGenerate(normalizedReply())
+
+	gr, err := env.g.GroundURL(t.Context(), "https://b.example/pasted")
+	if err != nil {
+		t.Fatalf("GroundURL: %v", err)
+	}
+	if gr.SourceURL != "https://b.example/pasted" || gr.Method != "crockpot" || gr.PhotoID == "" {
+		t.Errorf("Grounded = %+v, want the pasted URL, crockpot from the title", gr)
+	}
+	if env.search.callCount() != 0 {
+		t.Error("GroundURL searched")
+	}
+
+	for rawURL, reason := range map[string]error{
+		"https://b.example/no-image": ErrNoImage,
+		"https://b.example/no-time":  ErrTotalTimeNotPositive,
+		"https://b.example/missing":  nil,
+	} {
+		_, err := env.g.GroundURL(t.Context(), rawURL)
+		var ungroundable *ErrUngroundable
+		if !errors.As(err, &ungroundable) || ungroundable.Target != rawURL {
+			t.Errorf("GroundURL(%s) error = %v, want *ErrUngroundable", rawURL, err)
+		}
+		var status *StatusError
+		if reason != nil && !errors.Is(err, reason) || reason == nil && !errors.As(err, &status) {
+			t.Errorf("GroundURL(%s) error = %v, want reason %v", rawURL, err, reason)
+		}
+	}
+}
+
+func TestGroundManyIsolatesFailures(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{
+		results: map[string][]Candidate{
+			"curry":   {{URL: "https://a.example/curry"}},
+			"nothing": {{URL: "https://a.example/missing"}},
+			"chili":   {{URL: "https://b.example/chili"}},
+		},
+		errs: map[string]error{"broken": ErrSearchRefused},
+	}
+	env := newGroundEnv(t,
+		map[string][]byte{
+			"https://a.example/curry": groundPage("Curry", "/img/curry.jpg"),
+			"https://b.example/chili": groundPage("Chili", "/img/chili.jpg"),
+		},
+		map[string]photoFile{"/img/curry.jpg": jpegFile(t, 640, 480), "/img/chili.jpg": jpegFile(t, 480, 640)},
+		search)
+	env.llm.QueueGenerate(normalizedReply(), normalizedReply())
+
+	results := env.g.GroundMany(t.Context(), []GroundRequest{
+		{DishName: "Curry", Query: "curry"},
+		{DishName: "Nothing", Query: "nothing"},
+		{DishName: "Broken", Query: "broken"},
+		{DishName: "Chili", Query: "chili"},
+	})
+	if len(results) != 4 {
+		t.Fatalf("%d results, want 4", len(results))
+	}
+	if results[0].Err != nil || results[0].Grounded.SourceURL != "https://a.example/curry" {
+		t.Errorf("curry = %+v", results[0])
+	}
+	var ungroundable *ErrUngroundable
+	if !errors.As(results[1].Err, &ungroundable) {
+		t.Errorf("nothing error = %v, want *ErrUngroundable", results[1].Err)
+	}
+	if !errors.Is(results[2].Err, ErrSearchRefused) {
+		t.Errorf("broken error = %v, want ErrSearchRefused", results[2].Err)
+	}
+	if results[3].Err != nil || results[3].Grounded.SourceURL != "https://b.example/chili" {
+		t.Errorf("chili = %+v", results[3])
+	}
+	if n := countRows(t, env.st, "recipes"); n != 2 {
+		t.Errorf("%d recipes rows, want 2", n)
+	}
+}
+
+func TestGroundManyLimitsConcurrency(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{started: make(chan string, 5), gate: make(chan struct{})}
+	env := newGroundEnv(t, nil, nil, search)
+	reqs := make([]GroundRequest, 5)
+	for i := range reqs {
+		reqs[i] = GroundRequest{DishName: fmt.Sprintf("Dish %d", i), Query: fmt.Sprintf("dish %d", i)}
+	}
+	done := make(chan []GroundResult)
+	go func() { done <- env.g.GroundMany(t.Context(), reqs) }()
+
+	for range GroundConcurrency {
+		select {
+		case <-search.started:
+		case <-time.After(5 * time.Second):
+			t.Fatal("fewer than GroundConcurrency items started")
+		}
+	}
+	select {
+	case q := <-search.started:
+		t.Fatalf("%s started while %d were in flight", q, GroundConcurrency)
+	case <-time.After(100 * time.Millisecond):
+	}
+	close(search.gate)
+	results := <-done
+	for i, r := range results {
+		if !errors.Is(r.Err, ErrNoCandidates) {
+			t.Errorf("item %d error = %v, want ErrNoCandidates", i, r.Err)
+		}
+	}
+	if search.maxActive != GroundConcurrency || search.callCount() != 5 {
+		t.Errorf("max in flight %d of %d calls, want %d of 5", search.maxActive, search.callCount(), GroundConcurrency)
+	}
+}
+
+func TestCandidatesOffersBestFirstUpToN(t *testing.T) {
+	t.Parallel()
+	var cands []Candidate
+	pages := map[string][]byte{}
+	for i, title := range []string{"Fish Tacos", "Fish Taco Bowls", "Baja Fish Tacos", "Tacos"} {
+		u := fmt.Sprintf("https://site%d.example/tacos", i)
+		cands = append(cands, Candidate{URL: u})
+		pages[u] = groundPage(title, "/img/tacos.jpg")
+	}
+	search := &fakeSearch{results: map[string][]Candidate{"fish tacos": cands}}
+	env := newGroundEnv(t, pages, nil, search)
+
+	got, err := env.g.Candidates(t.Context(), "Fish Tacos", "fish tacos", 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 3 || got[0].URL != cands[0].URL || got[0].Title != "Fish Tacos" || got[0].SiteName != "Example Kitchen" ||
+		got[0].PhotoID != "" || got[0].Minutes == nil || *got[0].Minutes != 40 {
+		t.Fatalf("Candidates = %+v, want 3 with Fish Tacos first", got)
+	}
+	if env.images.requests.Load() != 0 || len(env.llm.Requests()) != 0 {
+		t.Errorf("Candidates downloaded a photo or ran the model")
+	}
+}
+
+func TestCandidatesSearchFailureWrapsErrSearchFailed(t *testing.T) {
+	t.Parallel()
+	search := &fakeSearch{errs: map[string]error{"stew": ErrSearchRateLimited}}
+	env := newGroundEnv(t, nil, nil, search)
+	_, err := env.g.Candidates(t.Context(), "Stew", "stew", 3)
+	if !errors.Is(err, ErrSearchFailed) || !errors.Is(err, ErrSearchRateLimited) {
+		t.Errorf("err = %v, want ErrSearchFailed wrapping ErrSearchRateLimited", err)
+	}
+}

internal/recipes/photo.go

@@ -19,7 +19,6 @@ import (
 	"path/filepath"
 	"slices"
 	"strconv"
-	"sync"
 
 	"github.com/oklog/ulid/v2"
 	"golang.org/x/image/draw"
@@ -66,26 +65,28 @@ var photoDecoders = map[string]func([]byte) (image.Image, error){
 	"webp": func(b []byte) (image.Image, error) { return webp.Decode(bytes.NewReader(b)) },
 }
 
-// PhotoCache downloads photos through a Fetcher and stores each at every
-// PhotoSizes length as {id}-{size}.jpg under PhotoDir, with a photos row.
-// Photos are deduplicated by the SHA-256 of the downloaded bytes. A
-// PhotoCache is safe for concurrent use; photos are processed one at a time.
-type PhotoCache struct {
-	fetcher *Fetcher
-	store   *store.Store
-	// dir is the absolute photo directory.
-	dir string
-
-	// mu serialises the dedupe lookup, processing and insert, so one image
-	// is never stored twice.
-	mu sync.Mutex
+// ImageFetcher fetches an image; *Fetcher satisfies it.
+type ImageFetcher interface {
+	FetchImage(ctx context.Context, rawURL string) (Page, error)
 }
 
-// NewPhotoCache returns a PhotoCache storing photos under dataDir, creating
-// the photo directory if it is absent.
-func NewPhotoCache(fetcher *Fetcher, st *store.Store, dataDir string) (*PhotoCache, error) {
-	if fetcher == nil {
-		return nil, errors.New("recipes: nil fetcher")
+// PhotoCache downloads photos through an ImageFetcher and stores each at every
+// PhotoSizes length as {id}-{size}.jpg under PhotoDir, with a photos row.
+// Photos are deduplicated by the SHA-256 of the downloaded bytes. A
+// PhotoCache is safe for concurrent use.
+type PhotoCache struct {
+	images ImageFetcher
+	store  *store.Store
+	// dir is the absolute photo directory.
+	dir string
+}
+
+// NewPhotoCache returns a PhotoCache downloading images with images and
+// storing photos under dataDir, creating the photo directory if it is
+// absent.
+func NewPhotoCache(images ImageFetcher, st *store.Store, dataDir string) (*PhotoCache, error) {
+	if images == nil {
+		return nil, errors.New("recipes: nil image fetcher")
 	}
 	if st == nil {
 		return nil, errors.New("recipes: nil store")
@@ -97,71 +98,91 @@ func NewPhotoCache(fetcher *Fetcher, st *store.Store, dataDir string) (*PhotoCac
 	if err := os.MkdirAll(dir, 0o750); err != nil {
 		return nil, fmt.Errorf("recipes: create photo directory: %w", err)
 	}
-	return &PhotoCache{fetcher: fetcher, store: st, dir: dir}, nil
+	return &PhotoCache{images: images, store: st, dir: dir}, nil
 }
 
-// CachePhoto downloads the image at rawURL and returns its photos row. An
-// image whose bytes are already cached returns the existing row. Otherwise
-// it is decoded, refused if its shorter side is under PhotoMinShortSide,
-// scaled so its long side is each of PhotoSizes, encoded as JPEG and
-// recorded. The row's width and height are the original image's, and its
-// local_path is the largest size's file relative to the data directory.
-func (c *PhotoCache) CachePhoto(ctx context.Context, rawURL string) (db.Photo, error) {
-	page, err := c.fetcher.FetchImage(ctx, rawURL)
+// DownloadedPhoto is an image DownloadPhoto has downloaded and decoded,
+// ready for CachePhoto.
+type DownloadedPhoto struct {
+	// url is the image's final URL, after redirects.
+	url    string
+	sha256 string
+	img    image.Image
+}
+
+// DownloadPhoto downloads the image at rawURL and decodes it, refusing one
+// whose shorter side is under PhotoMinShortSide. It records nothing, so a
+// caller can try another image before opening a transaction.
+func (c *PhotoCache) DownloadPhoto(ctx context.Context, rawURL string) (DownloadedPhoto, error) {
+	page, err := c.images.FetchImage(ctx, rawURL)
 	if err != nil {
-		return db.Photo{}, err
+		return DownloadedPhoto{}, err
 	}
-	digest := sha256.Sum256(page.Body)
-	sum := hex.EncodeToString(digest[:])
-
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	existing, err := db.New(c.store.Reader).GetPhotoBySHA256(ctx, sum)
-	if err == nil {
-		return existing, nil
-	}
-	if !errors.Is(err, sql.ErrNoRows) {
-		return db.Photo{}, fmt.Errorf("recipes: look up photo: %w", err)
-	}
-
 	img, err := decodePhoto(page.Body)
 	if err != nil {
-		return db.Photo{}, fmt.Errorf("%w: %s", err, page.URL)
+		return DownloadedPhoto{}, fmt.Errorf("%w: %s", err, page.URL)
 	}
+	digest := sha256.Sum256(page.Body)
+	return DownloadedPhoto{url: page.URL, sha256: hex.EncodeToString(digest[:]), img: img}, nil
+}
+
+// CachePhoto records p in tx, the caller's transaction, so its photos row
+// commits or rolls back with the rows that refer to it. An image whose
+// bytes are already recorded returns that row and created false. Otherwise
+// p is scaled so its long side is each of PhotoSizes, encoded as JPEG and
+// recorded, and created is true: if tx then does not commit, the caller
+// removes the files with RemovePhotoFiles. The row's width and height are
+// the original image's, and its local_path is the largest size's file
+// relative to the data directory.
+//
+// The store's writer has one connection, so transactions run one at a
+// time and an image is never recorded twice.
+func (c *PhotoCache) CachePhoto(ctx context.Context, tx *sql.Tx, p DownloadedPhoto) (photo db.Photo, created bool, err error) {
+	q := db.New(tx)
+	existing, err := q.GetPhotoBySHA256(ctx, p.sha256)
+	if err == nil {
+		return existing, false, nil
+	}
+	if !errors.Is(err, sql.ErrNoRows) {
+		return db.Photo{}, false, fmt.Errorf("recipes: look up photo: %w", err)
+	}
+
 	id := store.NewID()
-	var written []string
-	removeWritten := func() error {
-		var errs []error
-		for _, p := range written {
-			errs = append(errs, os.Remove(p))
-		}
-		return errors.Join(errs...)
-	}
 	for _, size := range PhotoSizes {
-		p := c.path(id, size)
-		if err := writeJPEG(p, scaleLongSide(img, size)); err != nil {
-			return db.Photo{}, errors.Join(err, removeWritten())
+		if err := writeJPEG(c.path(id, size), scaleLongSide(p.img, size)); err != nil {
+			return db.Photo{}, false, errors.Join(err, c.RemovePhotoFiles(id))
 		}
-		written = append(written, p)
 	}
 
 	now := store.Now().String()
-	bounds := img.Bounds()
-	photo, err := db.New(c.store.Writer).CreatePhoto(ctx, db.CreatePhotoParams{
+	bounds := p.img.Bounds()
+	photo, err = q.CreatePhoto(ctx, db.CreatePhotoParams{
 		ID:        id,
-		SourceUrl: page.URL,
+		SourceUrl: p.url,
 		LocalPath: path.Join(PhotoDir, photoFileName(id, PhotoSizes[0])),
 		Width:     int64(bounds.Dx()),
 		Height:    int64(bounds.Dy()),
-		Sha256:    sum,
+		Sha256:    p.sha256,
 		FetchedAt: now,
 		CreatedAt: now,
 		UpdatedAt: now,
 	})
 	if err != nil {
-		return db.Photo{}, errors.Join(fmt.Errorf("recipes: record photo: %w", err), removeWritten())
+		return db.Photo{}, false, errors.Join(fmt.Errorf("recipes: record photo: %w", err), c.RemovePhotoFiles(id))
 	}
-	return photo, nil
+	return photo, true, nil
+}
+
+// RemovePhotoFiles removes the files of photo id at every PhotoSizes
+// length; a file already absent is not an error.
+func (c *PhotoCache) RemovePhotoFiles(id string) error {
+	var errs []error
+	for _, size := range PhotoSizes {
+		if err := os.Remove(c.path(id, size)); err != nil && !errors.Is(err, fs.ErrNotExist) {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
 }
 
 // OpenPhoto opens the stored file of photo id at size. An id that is not a

internal/recipes/photo_test.go

@@ -3,6 +3,7 @@ package recipes
 import (
 	"bytes"
 	"context"
+	"database/sql"
 	"errors"
 	"image"
 	"image/color"
@@ -18,6 +19,7 @@ import (
 	"sync/atomic"
 	"testing"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
@@ -72,6 +74,22 @@ func newTestPhotoCache(t *testing.T, files map[string]photoFile) (*PhotoCache, *
 	return cache, st, dataDir, srv
 }
 
+// cachePhoto downloads the image at rawURL and records it in its own
+// transaction, as a caller of DownloadPhoto and CachePhoto does.
+func cachePhoto(t *testing.T, cache *PhotoCache, rawURL string) (db.Photo, error) {
+	t.Helper()
+	p, err := cache.DownloadPhoto(t.Context(), rawURL)
+	if err != nil {
+		return db.Photo{}, err
+	}
+	var photo db.Photo
+	err = cache.store.WithTx(t.Context(), func(tx *sql.Tx) error {
+		photo, _, err = cache.CachePhoto(t.Context(), tx, p)
+		return err
+	})
+	return photo, err
+}
+
 // gradient is a w×h opaque image.
 func gradient(w, h int) *image.RGBA {
 	img := image.NewRGBA(image.Rect(0, 0, w, h))
@@ -167,7 +185,7 @@ func TestCachePhotoFormatsAndSizes(t *testing.T) {
 		{"/square.png", 1500, 1500, map[int]image.Point{1200: {1200, 1200}, 400: {400, 400}}},
 	}
 	for _, tc := range tests {
-		photo, err := cache.CachePhoto(t.Context(), "https://example.com"+tc.path)
+		photo, err := cachePhoto(t, cache, "https://example.com"+tc.path)
 		if err != nil {
 			t.Fatalf("CachePhoto %s: %v", tc.path, err)
 		}
@@ -194,7 +212,7 @@ func TestCachePhotoGIFUsesFirstFrame(t *testing.T) {
 	cache, _, dataDir, _ := newTestPhotoCache(t, map[string]photoFile{
 		"/anim.gif": {"image/gif", twoFrameGIF(t, 400, 400)},
 	})
-	photo, err := cache.CachePhoto(t.Context(), "https://example.com/anim.gif")
+	photo, err := cachePhoto(t, cache, "https://example.com/anim.gif")
 	if err != nil {
 		t.Fatalf("CachePhoto: %v", err)
 	}
@@ -220,7 +238,7 @@ func TestCachePhotoRejectsSmallGIFFirstFrame(t *testing.T) {
 	cache, st, dataDir, _ := newTestPhotoCache(t, map[string]photoFile{
 		"/speck.gif": {"image/gif", b.Bytes()},
 	})
-	if _, err := cache.CachePhoto(t.Context(), "https://example.com/speck.gif"); !errors.Is(err, ErrPhotoTooSmall) {
+	if _, err := cachePhoto(t, cache, "https://example.com/speck.gif"); !errors.Is(err, ErrPhotoTooSmall) {
 		t.Errorf("CachePhoto error = %v, want ErrPhotoTooSmall", err)
 	}
 	if n := countPhotos(t, st); n != 0 {
@@ -236,7 +254,7 @@ func TestCachePhotoFillsTransparencyWhite(t *testing.T) {
 	cache, _, dataDir, _ := newTestPhotoCache(t, map[string]photoFile{
 		"/clear.png": {"image/png", encodePNG(t, image.NewNRGBA(image.Rect(0, 0, 400, 400)))},
 	})
-	photo, err := cache.CachePhoto(t.Context(), "https://example.com/clear.png")
+	photo, err := cachePhoto(t, cache, "https://example.com/clear.png")
 	if err != nil {
 		t.Fatalf("CachePhoto: %v", err)
 	}
@@ -276,7 +294,7 @@ func TestCachePhotoRejectsTooSmall(t *testing.T) {
 		"/edge.png":   {"image/png", encodePNG(t, gradient(300, 1000))},
 	})
 	for _, p := range []string{"/narrow.png", "/short.jpg"} {
-		if _, err := cache.CachePhoto(t.Context(), "https://example.com"+p); !errors.Is(err, ErrPhotoTooSmall) {
+		if _, err := cachePhoto(t, cache, "https://example.com"+p); !errors.Is(err, ErrPhotoTooSmall) {
 			t.Errorf("CachePhoto %s error = %v, want ErrPhotoTooSmall", p, err)
 		}
 	}
@@ -286,7 +304,7 @@ func TestCachePhotoRejectsTooSmall(t *testing.T) {
 	if names := photoFiles(t, dataDir); len(names) != 0 {
 		t.Errorf("files stored for refused images: %v", names)
 	}
-	if _, err := cache.CachePhoto(t.Context(), "https://example.com/edge.png"); err != nil {
+	if _, err := cachePhoto(t, cache, "https://example.com/edge.png"); err != nil {
 		t.Errorf("CachePhoto with a 300 px short side: %v", err)
 	}
 }
@@ -297,10 +315,10 @@ func TestCachePhotoRejectsNonImages(t *testing.T) {
 		"/page.html": {"text/html", encodePNG(t, gradient(400, 400))},
 		"/fake.jpg":  {"image/jpeg", []byte("<html>not a picture</html>")},
 	})
-	if _, err := cache.CachePhoto(t.Context(), "https://example.com/page.html"); !errors.Is(err, ErrNotImage) {
+	if _, err := cachePhoto(t, cache, "https://example.com/page.html"); !errors.Is(err, ErrNotImage) {
 		t.Errorf("text/html error = %v, want ErrNotImage", err)
 	}
-	if _, err := cache.CachePhoto(t.Context(), "https://example.com/fake.jpg"); !errors.Is(err, ErrPhotoFormat) {
+	if _, err := cachePhoto(t, cache, "https://example.com/fake.jpg"); !errors.Is(err, ErrPhotoFormat) {
 		t.Errorf("undecodable image error = %v, want ErrPhotoFormat", err)
 	}
 	if n := countPhotos(t, st); n != 0 {
@@ -316,11 +334,11 @@ func TestCachePhotoDeduplicatesBySHA256(t *testing.T) {
 		"/b.jpg":     {"image/jpeg", body},
 		"/other.jpg": {"image/jpeg", encodeJPEG(t, gradient(480, 640))},
 	})
-	first, err := cache.CachePhoto(t.Context(), "https://example.com/a.jpg")
+	first, err := cachePhoto(t, cache, "https://example.com/a.jpg")
 	if err != nil {
 		t.Fatalf("CachePhoto a: %v", err)
 	}
-	again, err := cache.CachePhoto(t.Context(), "https://example.com/b.jpg")
+	again, err := cachePhoto(t, cache, "https://example.com/b.jpg")
 	if err != nil {
 		t.Fatalf("CachePhoto b: %v", err)
 	}
@@ -330,7 +348,7 @@ func TestCachePhotoDeduplicatesBySHA256(t *testing.T) {
 	if n := srv.requests.Load(); n != 2 {
 		t.Errorf("%d downloads, want 2: each URL is fetched to hash it", n)
 	}
-	other, err := cache.CachePhoto(t.Context(), "https://example.com/other.jpg")
+	other, err := cachePhoto(t, cache, "https://example.com/other.jpg")
 	if err != nil {
 		t.Fatalf("CachePhoto other: %v", err)
 	}
@@ -350,7 +368,7 @@ func TestOpenPhoto(t *testing.T) {
 	cache, _, dataDir, _ := newTestPhotoCache(t, map[string]photoFile{
 		"/a.png": {"image/png", encodePNG(t, gradient(400, 300))},
 	})
-	photo, err := cache.CachePhoto(t.Context(), "https://example.com/a.png")
+	photo, err := cachePhoto(t, cache, "https://example.com/a.png")
 	if err != nil {
 		t.Fatalf("CachePhoto: %v", err)
 	}
@@ -436,3 +454,42 @@ func TestFetchImageContentTypes(t *testing.T) {
 		t.Errorf("Fetch: %v", err)
 	}
 }
+
+func TestCachePhotoRollsBackWithTransaction(t *testing.T) {
+	t.Parallel()
+	cache, st, dataDir, _ := newTestPhotoCache(t, map[string]photoFile{
+		"/a.jpg": {"image/jpeg", encodeJPEG(t, gradient(640, 480))},
+	})
+	p, err := cache.DownloadPhoto(t.Context(), "https://example.com/a.jpg")
+	if err != nil {
+		t.Fatal(err)
+	}
+	errAbort := errors.New("abort")
+	var photo db.Photo
+	var created bool
+	err = st.WithTx(t.Context(), func(tx *sql.Tx) error {
+		photo, created, err = cache.CachePhoto(t.Context(), tx, p)
+		if err != nil {
+			return err
+		}
+		return errAbort
+	})
+	if !errors.Is(err, errAbort) || !created {
+		t.Fatalf("WithTx error = %v, created = %v; want the abort after a new photo", err, created)
+	}
+	if n := countPhotos(t, st); n != 0 {
+		t.Errorf("%d photos rows after rollback", n)
+	}
+	if names := photoFiles(t, dataDir); len(names) != len(PhotoSizes) {
+		t.Errorf("files before removal = %v, want one per size", names)
+	}
+	if err := cache.RemovePhotoFiles(photo.ID); err != nil {
+		t.Fatal(err)
+	}
+	if names := photoFiles(t, dataDir); len(names) != 0 {
+		t.Errorf("files after RemovePhotoFiles = %v", names)
+	}
+	if err := cache.RemovePhotoFiles(photo.ID); err != nil {
+		t.Errorf("RemovePhotoFiles of absent files: %v", err)
+	}
+}

internal/recipes/rank.go

@@ -45,17 +45,26 @@ type Ranked struct {
 }
 
 // Rank fetches and extracts the first RankDepth candidates concurrently and
-// returns those whose recipe has ingredients and an image, highest Score
-// first; equal scores keep search order.
+// returns those whose recipe is usable — it has ingredients and an image,
+// and any total time it gives is positive — highest Score first; equal
+// scores keep search order.
 //
 // Every candidate that is not ranked — its fetch failed, its page holds no
-// valid recipe, or the recipe lacks ingredients or an image — is reported,
-// never dropped silently: when some are ranked the error is
+// valid recipe, or the recipe is not usable — is reported, never dropped
+// silently: when some are ranked the error is
 // ErrCandidatesUnranked, returned together with the ranked ones; when none
 // are it is ErrNoUsableRecipe with no results. Either is joined with each
 // unranked candidate's URL and reason. A cancelled ctx returns only its
 // error.
 func Rank(ctx context.Context, f PageFetcher, dish string, cands []Candidate) ([]Ranked, error) {
+	return rank(ctx, dish, cands, func(ctx context.Context, c Candidate) (Recipe, error) {
+		return fetchRecipe(ctx, f, c.URL)
+	})
+}
+
+// rank is Rank with each candidate's recipe got by load rather than always
+// fetched.
+func rank(ctx context.Context, dish string, cands []Candidate, load func(context.Context, Candidate) (Recipe, error)) ([]Ranked, error) {
 	if len(cands) > RankDepth {
 		cands = cands[:RankDepth]
 	}
@@ -69,7 +78,7 @@ func Rank(ctx context.Context, f PageFetcher, dish string, cands []Candidate) ([
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			r, err := rankOne(ctx, f, dish, c)
+			r, err := rankOne(ctx, load, dish, c)
 			outcomes[i] = outcome{r, err}
 		}()
 	}
@@ -97,26 +106,42 @@ func Rank(ctx context.Context, f PageFetcher, dish string, cands []Candidate) ([
 	return ranked, nil
 }
 
-// rankOne fetches, extracts and scores one candidate, or says why it is
+// rankOne loads and scores one candidate's recipe, or says why it is
 // rejected.
-func rankOne(ctx context.Context, f PageFetcher, dish string, c Candidate) (Ranked, error) {
-	page, err := f.Fetch(ctx, c.URL)
+func rankOne(ctx context.Context, load func(context.Context, Candidate) (Recipe, error), dish string, c Candidate) (Ranked, error) {
+	r, err := load(ctx, c)
 	if err != nil {
 		return Ranked{}, err
 	}
-	r, err := Extract(page.Body, page.URL)
-	if err != nil {
+	if err := usable(r); err != nil {
 		return Ranked{}, err
 	}
-	if len(r.Ingredients) == 0 {
-		return Ranked{}, ErrNoIngredients
-	}
-	if r.ImageURL == "" {
-		return Ranked{}, ErrNoImage
-	}
 	return Ranked{Candidate: c, Recipe: r, Score: harness.Similarity(r.Title, dish) + completeness(r)}, nil
 }
 
+// fetchRecipe fetches the page at rawURL and extracts its recipe.
+func fetchRecipe(ctx context.Context, f PageFetcher, rawURL string) (Recipe, error) {
+	page, err := f.Fetch(ctx, rawURL)
+	if err != nil {
+		return Recipe{}, err
+	}
+	return Extract(page.Body, page.URL)
+}
+
+// usable says why r cannot ground a dish: it has no ingredients or no
+// image, or a total time that is not positive.
+func usable(r Recipe) error {
+	switch {
+	case len(r.Ingredients) == 0:
+		return ErrNoIngredients
+	case r.ImageURL == "":
+		return ErrNoImage
+	case r.TotalMinutes != nil && *r.TotalMinutes <= 0:
+		return ErrTotalTimeNotPositive
+	}
+	return nil
+}
+
 // completeness is a quarter for each of ingredients, image, steps and total
 // minutes the recipe has.
 func completeness(r Recipe) float64 {

internal/recipes/recipestest/recipestest.go

@@ -0,0 +1,183 @@
+// Package recipestest provides fakes for tests that ground dinners outside
+// package recipes: a search, page and image fetchers serving fixtures, and
+// a Grounder over them that normalizes through the real harness and
+// normalize_recipe skill with a scripted model.
+package recipestest
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"sync"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Search is a recipes.SearchSource and recipes.SearchProvider answering
+// each query from Results. Err, when set, fails every search. Gate, when
+// set, makes every search wait for it to close.
+type Search struct {
+	Results map[string][]recipes.Candidate
+	Err     error
+	Gate    chan struct{}
+
+	mu      sync.Mutex
+	queries []string
+}
+
+func (s *Search) Provider(context.Context) (recipes.SearchProvider, error) { return s, nil }
+
+func (s *Search) Search(ctx context.Context, query string, n int) ([]recipes.Candidate, error) {
+	s.mu.Lock()
+	s.queries = append(s.queries, query)
+	s.mu.Unlock()
+	if s.Gate != nil {
+		select {
+		case <-s.Gate:
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		}
+	}
+	if s.Err != nil {
+		return nil, s.Err
+	}
+	c := s.Results[query]
+	return c[:min(n, len(c))], nil
+}
+
+// Queries returns every query searched, in order.
+func (s *Search) Queries() []string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return append([]string(nil), s.queries...)
+}
+
+// Pages is a recipes.PageFetcher serving Bodies by URL; any other URL is a
+// 404. Gate, when set, makes every fetch wait for it to close.
+type Pages struct {
+	Bodies map[string][]byte
+	Gate   chan struct{}
+
+	mu      sync.Mutex
+	fetched []string
+}
+
+func (p *Pages) Fetch(ctx context.Context, rawURL string) (recipes.Page, error) {
+	p.mu.Lock()
+	p.fetched = append(p.fetched, rawURL)
+	p.mu.Unlock()
+	if p.Gate != nil {
+		select {
+		case <-p.Gate:
+		case <-ctx.Done():
+			return recipes.Page{}, ctx.Err()
+		}
+	}
+	body, ok := p.Bodies[rawURL]
+	if !ok {
+		return recipes.Page{}, &recipes.StatusError{URL: rawURL, Status: 404}
+	}
+	return recipes.Page{URL: rawURL, ContentType: "text/html", Body: body}, nil
+}
+
+// Fetched returns every URL fetched, in order.
+func (p *Pages) Fetched() []string {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return append([]string(nil), p.fetched...)
+}
+
+// Images is a recipes.ImageFetcher serving JPEGs by URL; any other URL is
+// a 404.
+type Images struct {
+	JPEGs map[string][]byte
+}
+
+func (i *Images) FetchImage(_ context.Context, rawURL string) (recipes.Page, error) {
+	body, ok := i.JPEGs[rawURL]
+	if !ok {
+		return recipes.Page{}, &recipes.StatusError{URL: rawURL, Status: 404}
+	}
+	return recipes.Page{URL: rawURL, ContentType: "image/jpeg", Body: body}, nil
+}
+
+// JPEG is a w×h JPEG whose pixels depend on seed, so different seeds give
+// different photos.
+func JPEG(t testing.TB, w, h int, seed uint8) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, w, h))
+	for y := range h {
+		for x := range w {
+			img.Set(x, y, color.RGBA{uint8(x), uint8(y), seed, 255})
+		}
+	}
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, img, nil); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}
+
+// RecipePage is a page whose schema.org Recipe is title, from site, with
+// two ingredients, two steps, a total time of minutes and the image at
+// imageURL.
+func RecipePage(title, site, imageURL string, minutes int) []byte {
+	return fmt.Appendf(nil, `<!DOCTYPE html><html><head>
+<meta property="og:site_name" content=%q>
+<script type="application/ld+json">{
+	"@context": "https://schema.org",
+	"@type": "Recipe",
+	"name": %q,
+	"image": %q,
+	"recipeIngredient": ["1 onion", "2 cloves garlic, minced"],
+	"recipeInstructions": ["Chop the onion.", "Fry with the garlic."],
+	"totalTime": "PT%dM"
+}</script></head><body></body></html>`, site, title, imageURL, minutes)
+}
+
+// NormalizedReply is a usable normalize_recipe reply for a RecipePage with
+// method and minutes.
+func NormalizedReply(method string, minutes int) llm.GenerateResult {
+	js := fmt.Sprintf(`{"ingredients":[
+		{"name":"onion","qty":"1","unit":"","note":""},
+		{"name":"garlic","qty":"2","unit":"cloves","note":"minced"}
+	],"method":%q,"difficulty":null,"minutes_total":%d}`, method, minutes)
+	return llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}}
+}
+
+// NewGrounder returns a Grounder storing in st, with photos cached under
+// dataDir, normalizing through the real harness with model.
+func NewGrounder(t testing.TB, st *store.Store, dataDir string, search recipes.SearchSource, pages recipes.PageFetcher, images recipes.ImageFetcher, model llm.Provider) *recipes.Grounder {
+	t.Helper()
+	photos, err := recipes.NewPhotoCache(images, st, dataDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := harness.Config{
+		Settings:    llm.Settings{Provider: "anthropic", Model: "claude-test"},
+		NewProvider: func(llm.Settings, string) (llm.Provider, error) { return model, nil },
+		Store:       st,
+		Guard:       guard,
+	}
+	normalize := func(ctx context.Context, scope string, in skills.RecipeText) (skills.NormalizedRecipe, error) {
+		return skills.NormalizeRecipe(ctx, cfg, scope, in)
+	}
+	g, err := recipes.NewGrounder(st, search, pages, photos, normalize)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return g
+}

internal/recipes/search.go

@@ -71,12 +71,12 @@ type SearchProvider interface {
 }
 
 // NewSearchProvider returns the provider s names. SearXNG is called at
-// searxngURL, the configured MEALQUEST_SEARXNG_URL; Brave is called with the
-// API key in s.ApiKeyCt, decrypted by box.
-func NewSearchProvider(s db.RecipeSearchSetting, box *secretbox.Box, searxngURL string) (SearchProvider, error) {
+// s.BaseUrl; Brave is called with the API key in s.ApiKeyCt, decrypted by
+// box.
+func NewSearchProvider(s db.RecipeSearchSetting, box *secretbox.Box) (SearchProvider, error) {
 	switch s.Provider {
 	case "searxng":
-		return NewSearXNG(searxngURL)
+		return NewSearXNG(s.BaseUrl.String)
 	case "brave":
 		if len(s.ApiKeyCt) == 0 {
 			return nil, errors.New("recipes: Brave search has no API key")

internal/recipes/search_test.go

@@ -3,6 +3,7 @@ package recipes
 import (
 	"context"
 	"crypto/rand"
+	"database/sql"
 	"encoding/base64"
 	"errors"
 	"net/http"
@@ -262,7 +263,7 @@ func TestNewSearchProvider(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	p, err := NewSearchProvider(db.RecipeSearchSetting{Provider: "brave", ApiKeyCt: ct}, box, "")
+	p, err := NewSearchProvider(db.RecipeSearchSetting{Provider: "brave", ApiKeyCt: ct}, box)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -270,7 +271,7 @@ func TestNewSearchProvider(t *testing.T) {
 		t.Errorf("provider = %#v, want Brave with decrypted key", p)
 	}
 
-	p, err = NewSearchProvider(db.RecipeSearchSetting{Provider: "searxng"}, box, "http://searxng:8080")
+	p, err = NewSearchProvider(db.RecipeSearchSetting{Provider: "searxng", BaseUrl: sql.NullString{String: "http://searxng:8080", Valid: true}}, box)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -278,16 +279,13 @@ func TestNewSearchProvider(t *testing.T) {
 		t.Errorf("provider = %#v, want SearXNG at http://searxng:8080/search", p)
 	}
 
-	for name, tc := range map[string]struct {
-		s   db.RecipeSearchSetting
-		url string
-	}{
-		"brave without key":   {db.RecipeSearchSetting{Provider: "brave"}, ""},
-		"brave bad key":       {db.RecipeSearchSetting{Provider: "brave", ApiKeyCt: []byte("not a token at all, far too plain")}, ""},
-		"searxng without URL": {db.RecipeSearchSetting{Provider: "searxng"}, ""},
-		"unknown provider":    {db.RecipeSearchSetting{Provider: "google"}, ""},
+	for name, s := range map[string]db.RecipeSearchSetting{
+		"brave without key":   {Provider: "brave"},
+		"brave bad key":       {Provider: "brave", ApiKeyCt: []byte("not a token at all, far too plain")},
+		"searxng without URL": {Provider: "searxng"},
+		"unknown provider":    {Provider: "google"},
 	} {
-		if _, err := NewSearchProvider(tc.s, box, tc.url); err == nil {
+		if _, err := NewSearchProvider(s, box); err == nil {
 			t.Errorf("%s: succeeded, want error", name)
 		}
 	}

internal/recipes/searchsettings.go

@@ -0,0 +1,268 @@
+package recipes
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const (
+	// SearchTestQuery is what TestSearch searches for.
+	SearchTestQuery = "chicken tikka masala"
+	// MinBraveKeyLength is the shortest Brave API key accepted, so its last
+	// four characters never give away most of it.
+	MinBraveKeyLength = 8
+)
+
+// ErrSearchNotConfigured is returned when no recipe search provider has
+// been chosen yet.
+var ErrSearchNotConfigured = errors.New("recipes: recipe search is not configured")
+
+// SearchSettings is the household's recipe search configuration as the API
+// shows it. The Brave API key is never part of it: only whether one is
+// stored and its last four characters.
+type SearchSettings struct {
+	// Provider is "searxng" or "brave", nil until first chosen.
+	Provider *string `json:"provider"`
+	// BaseURL is the saved SearXNG instance's URL, nil when not set.
+	BaseURL *string `json:"base_url"`
+	// DefaultBaseURL is the deployment's SearXNG URL
+	// (MEALQUEST_SEARXNG_URL), for the client to suggest while BaseURL is
+	// not set. It is never saved by itself: only a PATCH of base_url saves
+	// a URL. Nil when the deployment names none.
+	DefaultBaseURL *string `json:"default_base_url"`
+	APIKeySet      bool    `json:"api_key_set"`
+	APIKeyLast4    *string `json:"api_key_last4"`
+	// UpdatedAt is nil until the settings are first saved.
+	UpdatedAt *string `json:"updated_at"`
+}
+
+// SearchSettingsPatch changes the settings. A nil field is left as it is;
+// an empty BaseURL or APIKey removes the stored one.
+type SearchSettingsPatch struct {
+	Provider *string `json:"provider"`
+	BaseURL  *string `json:"base_url"`
+	// APIKey is the Brave API key in plain text. It is stored encrypted
+	// and never returned.
+	APIKey *string `json:"api_key"`
+}
+
+// SearchSettingsProblem is one invalid field of a SearchSettingsPatch,
+// named by its JSON key.
+type SearchSettingsProblem struct {
+	Field  string
+	Reason string
+}
+
+// SearchSettingsError lists every problem with a SearchSettingsPatch, or
+// with the settings it would leave.
+type SearchSettingsError struct {
+	Problems []SearchSettingsProblem
+}
+
+func (e *SearchSettingsError) Error() string {
+	parts := make([]string, len(e.Problems))
+	for i, p := range e.Problems {
+		parts[i] = p.Field + ": " + p.Reason
+	}
+	return "invalid recipe search settings: " + strings.Join(parts, "; ")
+}
+
+// SearchSettingsService reads and changes the recipe_search_settings row
+// and builds the search provider it names. Brave API keys are sealed with
+// its secret box.
+type SearchSettingsService struct {
+	st  *store.Store
+	box *secretbox.Box
+	// defaultBaseURL is SearchSettings.DefaultBaseURL, "" for none.
+	defaultBaseURL string
+	// newProvider is NewSearchProvider; tests point Brave elsewhere.
+	newProvider func(db.RecipeSearchSetting, *secretbox.Box) (SearchProvider, error)
+}
+
+// NewSearchSettingsService returns the service over st, sealing keys with
+// box. defaultBaseURL is the deployment's SearXNG URL, "" for none; a set
+// one must be a valid SearXNG URL.
+func NewSearchSettingsService(st *store.Store, box *secretbox.Box, defaultBaseURL string) (*SearchSettingsService, error) {
+	if st == nil {
+		return nil, errors.New("recipes: nil store")
+	}
+	if box == nil {
+		return nil, errors.New("recipes: nil secret box")
+	}
+	if defaultBaseURL != "" {
+		if _, err := NewSearXNG(defaultBaseURL); err != nil {
+			return nil, fmt.Errorf("recipes: default SearXNG URL: %s", strings.TrimPrefix(err.Error(), "recipes: "))
+		}
+	}
+	return &SearchSettingsService{st: st, box: box, defaultBaseURL: defaultBaseURL, newProvider: NewSearchProvider}, nil
+}
+
+// Get returns the settings; before any are saved every field but
+// DefaultBaseURL is unset.
+func (s *SearchSettingsService) Get(ctx context.Context) (SearchSettings, error) {
+	row, err := db.New(s.st.Reader).GetRecipeSearchSettings(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return SearchSettings{DefaultBaseURL: s.defaultBase()}, nil
+	}
+	if err != nil {
+		return SearchSettings{}, fmt.Errorf("recipes: read recipe search settings: %w", err)
+	}
+	return s.settingsFrom(row), nil
+}
+
+func (s *SearchSettingsService) defaultBase() *string {
+	if s.defaultBaseURL == "" {
+		return nil
+	}
+	u := s.defaultBaseURL
+	return &u
+}
+
+// Update applies patch and returns the settings it leaves. The first update
+// must choose a provider. The result must be usable: SearXNG needs a base
+// URL and Brave an API key. Every problem is reported in a
+// *SearchSettingsError.
+func (s *SearchSettingsService) Update(ctx context.Context, patch SearchSettingsPatch) (SearchSettings, error) {
+	var saved db.RecipeSearchSetting
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		row, err := q.GetRecipeSearchSettings(ctx)
+		exists := err == nil
+		if err != nil && !errors.Is(err, sql.ErrNoRows) {
+			return fmt.Errorf("recipes: read recipe search settings: %w", err)
+		}
+		next, err := s.apply(row, exists, patch)
+		if err != nil {
+			return err
+		}
+		now := store.Now().String()
+		created := now
+		if exists {
+			created = row.CreatedAt
+		}
+		saved, err = q.UpsertRecipeSearchSettings(ctx, db.UpsertRecipeSearchSettingsParams{
+			Provider:    next.Provider,
+			BaseUrl:     next.BaseUrl,
+			ApiKeyCt:    next.ApiKeyCt,
+			ApiKeyLast4: next.ApiKeyLast4,
+			CreatedAt:   created,
+			UpdatedAt:   now,
+		})
+		if err != nil {
+			return fmt.Errorf("recipes: save recipe search settings: %w", err)
+		}
+		return nil
+	})
+	if err != nil {
+		return SearchSettings{}, err
+	}
+	return s.settingsFrom(saved), nil
+}
+
+// apply returns row with patch applied, validated.
+func (s *SearchSettingsService) apply(row db.RecipeSearchSetting, exists bool, patch SearchSettingsPatch) (db.RecipeSearchSetting, error) {
+	var problems []SearchSettingsProblem
+	if patch.Provider != nil {
+		switch *patch.Provider {
+		case "searxng", "brave":
+			row.Provider = *patch.Provider
+		default:
+			problems = append(problems, SearchSettingsProblem{"provider", `must be "searxng" or "brave"`})
+		}
+	} else if !exists {
+		problems = append(problems, SearchSettingsProblem{"provider", "is required until recipe search is configured"})
+	}
+	if patch.BaseURL != nil {
+		row.BaseUrl = sql.NullString{}
+		if u := *patch.BaseURL; u != "" {
+			if _, err := NewSearXNG(u); err != nil {
+				problems = append(problems, SearchSettingsProblem{"base_url", strings.TrimPrefix(err.Error(), "recipes: ")})
+			} else {
+				row.BaseUrl = sql.NullString{String: u, Valid: true}
+			}
+		}
+	}
+	if patch.APIKey != nil {
+		row.ApiKeyCt, row.ApiKeyLast4 = nil, sql.NullString{}
+		if key := *patch.APIKey; key != "" {
+			// The key is never echoed in a problem.
+			if _, err := NewBrave(key); err != nil {
+				problems = append(problems, SearchSettingsProblem{"api_key", "has a character not allowed in a header"})
+			} else if len(key) < MinBraveKeyLength {
+				problems = append(problems, SearchSettingsProblem{"api_key", fmt.Sprintf("must be at least %d characters", MinBraveKeyLength)})
+			} else {
+				ct, err := s.box.Encrypt([]byte(key))
+				if err != nil {
+					return db.RecipeSearchSetting{}, fmt.Errorf("recipes: seal Brave API key: %w", err)
+				}
+				row.ApiKeyCt = ct
+				row.ApiKeyLast4 = sql.NullString{String: key[len(key)-4:], Valid: true}
+			}
+		}
+	}
+	if len(problems) == 0 {
+		switch {
+		case row.Provider == "searxng" && !row.BaseUrl.Valid:
+			problems = append(problems, SearchSettingsProblem{"base_url", "is required for SearXNG"})
+		case row.Provider == "brave" && len(row.ApiKeyCt) == 0:
+			problems = append(problems, SearchSettingsProblem{"api_key", "is required for Brave"})
+		}
+	}
+	if len(problems) > 0 {
+		return db.RecipeSearchSetting{}, &SearchSettingsError{Problems: problems}
+	}
+	return row, nil
+}
+
+// Provider returns the search provider the settings name, or
+// ErrSearchNotConfigured.
+func (s *SearchSettingsService) Provider(ctx context.Context) (SearchProvider, error) {
+	row, err := db.New(s.st.Reader).GetRecipeSearchSettings(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrSearchNotConfigured
+	}
+	if err != nil {
+		return nil, fmt.Errorf("recipes: read recipe search settings: %w", err)
+	}
+	return s.newProvider(row, s.box)
+}
+
+// TestSearch searches for SearchTestQuery with the configured provider and
+// returns how many candidates it found, up to MaxSearchResults.
+func (s *SearchSettingsService) TestSearch(ctx context.Context) (int, error) {
+	p, err := s.Provider(ctx)
+	if err != nil {
+		return 0, err
+	}
+	cands, err := p.Search(ctx, SearchTestQuery, MaxSearchResults)
+	if err != nil {
+		return 0, err
+	}
+	return len(cands), nil
+}
+
+func (s *SearchSettingsService) settingsFrom(row db.RecipeSearchSetting) SearchSettings {
+	provider, updated := row.Provider, row.UpdatedAt
+	return SearchSettings{
+		Provider:       &provider,
+		BaseURL:        nullString(row.BaseUrl),
+		DefaultBaseURL: s.defaultBase(),
+		APIKeySet:      len(row.ApiKeyCt) > 0,
+		APIKeyLast4:    nullString(row.ApiKeyLast4),
+		UpdatedAt:      &updated,
+	}
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}

internal/recipes/searchsettings_test.go

@@ -0,0 +1,247 @@
+package recipes
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+const testBraveKey = "BSA-secret-brave-key-9f3c"
+
+func newTestSearchSettings(t *testing.T) *SearchSettingsService {
+	t.Helper()
+	return newTestSearchSettingsWithDefault(t, "")
+}
+
+// newTestSearchSettingsWithDefault is newTestSearchSettings with
+// defaultBaseURL as the deployment's SearXNG URL.
+func newTestSearchSettingsWithDefault(t *testing.T, defaultBaseURL string) *SearchSettingsService {
+	t.Helper()
+	st, err := store.Open(t.Context(), t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(t.Context(), st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	key := make([]byte, secretbox.KeySize)
+	rand.Read(key)
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatal(err)
+	}
+	svc, err := NewSearchSettingsService(st, box, defaultBaseURL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
+func ptr(s string) *string { return &s }
+
+// noKey fails the test when v, marshalled as the API would, holds the
+// Brave key.
+func noKey(t *testing.T, what string, v any) {
+	t.Helper()
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(b), testBraveKey) || strings.Contains(string(b), testBraveKey[:12]) {
+		t.Errorf("%s holds the Brave key: %s", what, b)
+	}
+}
+
+func TestSearchSettingsUpdate(t *testing.T) {
+	t.Parallel()
+	svc := newTestSearchSettings(t)
+	got, err := svc.Get(t.Context())
+	if err != nil || got != (SearchSettings{}) {
+		t.Fatalf("Get before any update = %+v, %v; want every field unset", got, err)
+	}
+	if _, err := svc.Provider(t.Context()); !errors.Is(err, ErrSearchNotConfigured) {
+		t.Errorf("Provider before any update error = %v, want ErrSearchNotConfigured", err)
+	}
+
+	for name, patch := range map[string]SearchSettingsPatch{
+		"no provider":         {BaseURL: ptr("http://searxng:8080")},
+		"unknown provider":    {Provider: ptr("google")},
+		"searxng without URL": {Provider: ptr("searxng")},
+		"bad URL":             {Provider: ptr("searxng"), BaseURL: ptr("ftp://searxng")},
+		"brave without key":   {Provider: ptr("brave")},
+		"short key":           {Provider: ptr("brave"), APIKey: ptr("abc12")},
+		"key with space":      {Provider: ptr("brave"), APIKey: ptr("abc 12345678")},
+	} {
+		var invalid *SearchSettingsError
+		if _, err := svc.Update(t.Context(), patch); !errors.As(err, &invalid) {
+			t.Errorf("%s: error = %v, want *SearchSettingsError", name, err)
+		}
+	}
+
+	got, err = svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("searxng"), BaseURL: ptr("http://searxng:8080")})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if *got.Provider != "searxng" || *got.BaseURL != "http://searxng:8080" || got.APIKeySet || got.APIKeyLast4 != nil || got.UpdatedAt == nil {
+		t.Errorf("SearXNG settings = %+v", got)
+	}
+
+	got, err = svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("brave"), APIKey: ptr(testBraveKey)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if *got.Provider != "brave" || !got.APIKeySet || *got.APIKeyLast4 != "9f3c" || *got.BaseURL != "http://searxng:8080" {
+		t.Errorf("Brave settings = %+v", got)
+	}
+	noKey(t, "Update result", got)
+	got, err = svc.Get(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	noKey(t, "Get result", got)
+	row, err := db.New(svc.st.Reader).GetRecipeSearchSettings(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(row.ApiKeyCt), testBraveKey) {
+		t.Error("Brave key stored in plain text")
+	}
+
+	if _, err := svc.Update(t.Context(), SearchSettingsPatch{APIKey: ptr("")}); err == nil {
+		t.Error("removing the key while Brave is chosen succeeded")
+	}
+	got, err = svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("searxng"), APIKey: ptr("")})
+	if err != nil || got.APIKeySet || got.APIKeyLast4 != nil {
+		t.Errorf("switch to SearXNG removing the key = %+v, %v", got, err)
+	}
+}
+
+func TestSearchSettingsDefaultBaseURL(t *testing.T) {
+	t.Parallel()
+	svc := newTestSearchSettingsWithDefault(t, "http://searxng:8080")
+	got, err := svc.Get(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.DefaultBaseURL == nil || *got.DefaultBaseURL != "http://searxng:8080" || got.BaseURL != nil || got.Provider != nil {
+		t.Errorf("Get before any update = %+v, want only default_base_url set", got)
+	}
+	if _, err := svc.Provider(t.Context()); !errors.Is(err, ErrSearchNotConfigured) {
+		t.Errorf("Provider with only a default error = %v, want ErrSearchNotConfigured", err)
+	}
+
+	// The default is a suggestion: SearXNG still needs a saved URL.
+	if _, err := svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("searxng")}); err == nil {
+		t.Error("choosing SearXNG without a URL succeeded with a default set")
+	}
+
+	got, err = svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("searxng"), BaseURL: ptr("https://search.example")})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if *got.BaseURL != "https://search.example" || got.DefaultBaseURL == nil || *got.DefaultBaseURL != "http://searxng:8080" {
+		t.Errorf("Update result = %+v, want the saved URL beside the default", got)
+	}
+	got, err = svc.Get(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if *got.BaseURL != "https://search.example" {
+		t.Errorf("Get base_url = %q, want the saved URL, not the default", *got.BaseURL)
+	}
+	row, err := db.New(svc.st.Reader).GetRecipeSearchSettings(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if row.BaseUrl.String != "https://search.example" {
+		t.Errorf("stored base_url = %q", row.BaseUrl.String)
+	}
+}
+
+func TestNewSearchSettingsServiceRejectsBadDefault(t *testing.T) {
+	t.Parallel()
+	st, err := store.Open(t.Context(), t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	key := make([]byte, secretbox.KeySize)
+	rand.Read(key)
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, u := range []string{"searxng:8080", "ftp://searxng", "http://user:pw@searxng:8080"} {
+		if _, err := NewSearchSettingsService(st, box, u); err == nil {
+			t.Errorf("NewSearchSettingsService(%q) succeeded", u)
+		} else if strings.Contains(err.Error(), "pw") {
+			t.Errorf("error for %q echoes the URL: %v", u, err)
+		}
+	}
+}
+
+func TestSearchSettingsTestSearch(t *testing.T) {
+	t.Parallel()
+	searx := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Query().Get("q") != SearchTestQuery+" recipe" {
+			t.Errorf("SearXNG query = %q", r.URL.Query().Get("q"))
+		}
+		w.Write([]byte(`{"results":[{"url":"https://a.example/1"},{"url":"https://b.example/2"}]}`))
+	}))
+	t.Cleanup(searx.Close)
+	svc := newTestSearchSettings(t)
+	if _, err := svc.TestSearch(t.Context()); !errors.Is(err, ErrSearchNotConfigured) {
+		t.Errorf("TestSearch unconfigured error = %v, want ErrSearchNotConfigured", err)
+	}
+	if _, err := svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("searxng"), BaseURL: ptr(searx.URL)}); err != nil {
+		t.Fatal(err)
+	}
+	if n, err := svc.TestSearch(t.Context()); err != nil || n != 2 {
+		t.Errorf("TestSearch = %d, %v; want 2", n, err)
+	}
+
+	// Brave refuses the key; the error must not carry it.
+	brave := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Subscription-Token") != testBraveKey {
+			t.Errorf("Brave token = %q", r.Header.Get("X-Subscription-Token"))
+		}
+		http.Error(w, "bad key "+testBraveKey, http.StatusUnauthorized)
+	}))
+	t.Cleanup(brave.Close)
+	svc.newProvider = func(s db.RecipeSearchSetting, box *secretbox.Box) (SearchProvider, error) {
+		p, err := NewSearchProvider(s, box)
+		if b, ok := p.(*Brave); ok {
+			b.endpoint = brave.URL
+		}
+		return p, err
+	}
+	if _, err := svc.Update(t.Context(), SearchSettingsPatch{Provider: ptr("brave"), APIKey: ptr(testBraveKey)}); err != nil {
+		t.Fatal(err)
+	}
+	_, err := svc.TestSearch(t.Context())
+	if !errors.Is(err, ErrSearchRefused) {
+		t.Fatalf("TestSearch error = %v, want ErrSearchRefused", err)
+	}
+	if strings.Contains(err.Error(), testBraveKey) {
+		t.Errorf("TestSearch error holds the Brave key: %v", err)
+	}
+}

internal/server/aisettings.go

@@ -0,0 +1,145 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+)
+
+// apiKeyBody is the PUT /settings/ai/api-key body. An empty api_key removes
+// the stored key.
+type apiKeyBody struct {
+	APIKey *string `json:"api_key"`
+}
+
+// modelsResponse is the GET /settings/ai/models body.
+type modelsResponse struct {
+	Models []aisettings.Model `json:"models"`
+}
+
+// No response from these handlers holds the API key: the settings carry
+// only its last four characters, and provider errors and model lists are
+// redacted by package aisettings.
+
+func getAISettings(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		settings, err := svc.Get(r.Context())
+		if err != nil {
+			logger.ErrorContext(r.Context(), "get AI settings", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+func patchAISettings(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		patch, err := decodePatch[aisettings.Patch](http.MaxBytesReader(w, r.Body, maxAISettingsBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		writeAISettings(w, r, logger, "update AI settings")(svc.Update(r.Context(), patch))
+	}
+}
+
+// putAIKey takes the API key in api_key; the response, like GET's, holds
+// only its last four characters.
+func putAIKey(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		body, err := decodePatch[apiKeyBody](http.MaxBytesReader(w, r.Body, maxSettingsBody))
+		if err == nil && body.APIKey == nil {
+			err = errors.New("api_key: is required")
+		}
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		writeAISettings(w, r, logger, "store AI API key")(svc.SetAPIKey(r.Context(), *body.APIKey))
+	}
+}
+
+func postAIResetPrompt(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		writeAISettings(w, r, logger, "reset AI system prompt")(svc.ResetPrompt(r.Context()))
+	}
+}
+
+// postAIVerify checks the stored key with the provider and returns the
+// settings with key_verified_at, or the failure (see writeAIFailure).
+func postAIVerify(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		settings, err := svc.Verify(r.Context())
+		if err != nil {
+			writeAIFailure(w, r, logger, "verify AI key", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+// getAIModels returns the provider's live model list, or the failure (see
+// writeAIFailure).
+func getAIModels(logger *slog.Logger, svc *aisettings.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		models, err := svc.Models(r.Context())
+		if err != nil {
+			writeAIFailure(w, r, logger, "list AI models", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, modelsResponse{Models: models})
+	}
+}
+
+// writeAISettings returns a func writing a Service result: the settings,
+// 400 invalid_settings for a *aisettings.ValidationError, or 500.
+func writeAISettings(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string) func(aisettings.Settings, error) {
+	return func(settings aisettings.Settings, err error) {
+		var invalid *aisettings.ValidationError
+		switch {
+		case errors.As(err, &invalid):
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_settings", invalid.Error())
+		case err != nil:
+			logger.ErrorContext(r.Context(), action, "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+		default:
+			writeJSON(w, r, logger, http.StatusOK, settings)
+		}
+	}
+}
+
+// writeAIFailure writes a Verify or Models error: 409 not_configured when
+// the settings cannot build a provider, 409 settings_changed when they
+// changed during verification, and for a failed provider call a 502 (504
+// for a timeout) whose code names the llm typed error: auth_failed,
+// rate_limited, timeout, bad_output or provider_error. Rate limits and
+// timeouts are retryable. Anything else is 500.
+func writeAIFailure(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	switch {
+	case errors.Is(err, aisettings.ErrNotConfigured):
+		writeError(w, r, logger, http.StatusConflict, "not_configured", err.Error())
+	case errors.Is(err, aisettings.ErrChanged):
+		writeError(w, r, logger, http.StatusConflict, "settings_changed", err.Error())
+	case errors.Is(err, aisettings.ErrProviderFailed):
+		logger.WarnContext(r.Context(), action+" failed", "error", err)
+		status, e := http.StatusBadGateway, apiError{Code: "provider_error", Message: err.Error()}
+		switch {
+		case errors.Is(err, llm.ErrAuth):
+			e.Code = "auth_failed"
+		case errors.Is(err, llm.ErrRateLimited):
+			e.Code, e.Retryable = "rate_limited", true
+		case errors.Is(err, llm.ErrTimeout):
+			status, e.Code, e.Retryable = http.StatusGatewayTimeout, "timeout", true
+		case errors.Is(err, llm.ErrBadOutput):
+			e.Code = "bad_output"
+		}
+		writeAPIError(w, r, logger, status, e)
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/aisettings_test.go

@@ -0,0 +1,261 @@
+package server
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"testing/fstest"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+)
+
+const (
+	aiPath            = "/api/v1/settings/ai"
+	aiKeyPath         = "/api/v1/settings/ai/api-key"
+	aiVerifyPath      = "/api/v1/settings/ai/verify"
+	aiModelsPath      = "/api/v1/settings/ai/models"
+	aiResetPromptPath = "/api/v1/settings/ai/reset-prompt"
+	testAIKey         = "sk-test-secret-ai-key-7d21"
+	testWrongAIKey    = "sk-test-wrong-ai-key-0b9e"
+)
+
+// newAIRouter returns a router with a fresh, seeded AI settings service.
+func newAIRouter(t *testing.T) http.Handler {
+	t.Helper()
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t),
+		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+// newModelsServer is an OpenAI-compatible server whose GET /models accepts
+// only testAIKey. While echo is set it answers 500 with a body quoting the
+// Authorization header it received, so a response that passed the vendor
+// body through unredacted would leak the key. Its model list holds a model
+// whose ID and name quote the key.
+func newModelsServer(t *testing.T, echo *atomic.Bool) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth := r.Header.Get("Authorization")
+		switch {
+		case r.URL.Path != "/v1/models":
+			http.NotFound(w, r)
+		case echo.Load():
+			w.WriteHeader(http.StatusInternalServerError)
+			io.WriteString(w, `{"error":{"message":"upstream failed for `+auth+`"}}`)
+		case auth != "Bearer "+testAIKey:
+			w.WriteHeader(http.StatusUnauthorized)
+			io.WriteString(w, `{"error":{"message":"invalid key `+auth+`"}}`)
+		default:
+			io.WriteString(w, `{"data":[{"id":"gpt-test"},{"id":"gpt-test-mini","name":"GPT Test Mini"},`+
+				`{"id":"gpt-`+testAIKey+`","name":"Leaky `+testAIKey+`"}]}`)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func errorCode(body map[string]any) any {
+	e, _ := body["error"].(map[string]any)
+	return e["code"]
+}
+
+// TestAISettingsAPI drives every /settings/ai route and scans every
+// response body for the API keys.
+func TestAISettingsAPI(t *testing.T) {
+	t.Parallel()
+	router := newAIRouter(t)
+	var echo atomic.Bool
+	vendor := newModelsServer(t, &echo)
+	var bodies []string
+	call := func(method, target, body string) (*httptest.ResponseRecorder, map[string]any) {
+		t.Helper()
+		var r io.Reader
+		if body != "" {
+			r = strings.NewReader(body)
+		}
+		rec, decoded := serve(t, router, signedIn(method, target, r))
+		bodies = append(bodies, rec.Body.String())
+		return rec, decoded
+	}
+
+	// The seed: anthropic, the default persona, no key.
+	rec, body := call(http.MethodGet, aiPath, "")
+	if rec.Code != http.StatusOK || body["provider"] != "anthropic" || body["system_prompt"] != household.DefaultPersonaPrompt ||
+		body["temperature"] != 0.7 || body["api_key_last4"] != nil || body["key_verified_at"] != nil {
+		t.Errorf("GET seed = %d %v", rec.Code, body)
+	}
+	for _, field := range []string{"provider", "base_url", "model", "temperature", "system_prompt", "api_key_last4", "key_verified_at"} {
+		if _, ok := body[field]; !ok {
+			t.Errorf("GET has no %s field: %v", field, body)
+		}
+	}
+	for _, path := range []string{aiVerifyPath, aiModelsPath} {
+		method := http.MethodPost
+		if path == aiModelsPath {
+			method = http.MethodGet
+		}
+		if rec, body := call(method, path, ""); rec.Code != http.StatusConflict || errorCode(body) != "not_configured" {
+			t.Errorf("%s %s without a key = %d %v, want 409 not_configured", method, path, rec.Code, body)
+		}
+	}
+
+	for _, bad := range []string{
+		`{}`,
+		`{"provider":"google"}`,
+		`{"provider":"openai_compatible","base_url":"not a url"}`,
+		`{"base_url":"https://evil.example"}`,
+		`{"temperature":1.1}`,
+		`{"temperature":-0.1}`,
+		`{"temperature":0.25}`,
+		`{"temperature":"0.5"}`,
+		`{"model":""}`,
+		`{"model":null}`,
+		`{"system_prompt":"` + strings.Repeat("é", 8001) + `"}`,
+		`{"system_prompt":"` + strings.Repeat("€", 8001) + `"}`,
+		`{"system_prompt":"` + strings.Repeat("a", maxAISettingsBody) + `"}`,
+		`{"api_key":"` + testAIKey + `"}`,
+	} {
+		if rec, body := call(http.MethodPatch, aiPath, bad); rec.Code != http.StatusBadRequest {
+			t.Errorf("PATCH %.80s = %d %v, want 400", bad, rec.Code, body)
+		}
+	}
+
+	// The longest prompt fits the body limit however its 8,000 characters
+	// are written: three-byte, four-byte, or as \u-escaped surrogate pairs.
+	for _, char := range []string{"€", "🍲", `\ud83c\udf72`} {
+		rec, body := call(http.MethodPatch, aiPath, `{"system_prompt":"`+strings.Repeat(char, 8000)+`"}`)
+		if prompt, _ := body["system_prompt"].(string); rec.Code != http.StatusOK || utf8.RuneCountInString(prompt) != 8000 {
+			t.Errorf("PATCH 8,000 × %s = %d, %d characters", char, rec.Code, utf8.RuneCountInString(prompt))
+		}
+	}
+
+	rec, body = call(http.MethodPatch, aiPath, `{"provider":"openai_compatible","base_url":"`+vendor.URL+`/v1","model":"gpt-test","temperature":0.3,"system_prompt":"`+strings.Repeat("é", 8000)+`"}`)
+	if rec.Code != http.StatusOK || body["provider"] != "openai_compatible" || body["base_url"] != vendor.URL+"/v1" ||
+		body["model"] != "gpt-test" || body["temperature"] != 0.3 {
+		t.Errorf("PATCH openai_compatible = %d %v", rec.Code, body)
+	}
+
+	for _, bad := range []string{`{}`, `{"api_key":"short"}`, `{"api_key":"sk-line\nbreak"}`, `{"api_key":null}`, `{"key":"` + testAIKey + `"}`} {
+		if rec, body := call(http.MethodPut, aiKeyPath, bad); rec.Code != http.StatusBadRequest {
+			t.Errorf("PUT api-key %s = %d %v, want 400", bad, rec.Code, body)
+		}
+	}
+
+	// A rejected key is a typed auth failure and records nothing.
+	rec, body = call(http.MethodPut, aiKeyPath, `{"api_key":"`+testWrongAIKey+`"}`)
+	if rec.Code != http.StatusOK || body["api_key_last4"] != "0b9e" || body["key_verified_at"] != nil {
+		t.Errorf("PUT wrong key = %d %v", rec.Code, body)
+	}
+	if rec, body := call(http.MethodPost, aiVerifyPath, ""); rec.Code != http.StatusBadGateway || errorCode(body) != "auth_failed" {
+		t.Errorf("POST verify with the wrong key = %d %v, want 502 auth_failed", rec.Code, body)
+	}
+	if rec, body := call(http.MethodGet, aiModelsPath, ""); rec.Code != http.StatusBadGateway || errorCode(body) != "auth_failed" {
+		t.Errorf("GET models with the wrong key = %d %v, want 502 auth_failed", rec.Code, body)
+	}
+
+	rec, body = call(http.MethodPut, aiKeyPath, `{"api_key":"`+testAIKey+`"}`)
+	if rec.Code != http.StatusOK || body["api_key_last4"] != "7d21" {
+		t.Errorf("PUT key = %d %v", rec.Code, body)
+	}
+	if _, ok := body["api_key"]; ok {
+		t.Errorf("PUT response has an api_key field: %v", body)
+	}
+
+	// The vendor quoting the key in an error body: the body excerpt
+	// reaches the response redacted.
+	echo.Store(true)
+	for _, c := range []struct{ method, path string }{{http.MethodPost, aiVerifyPath}, {http.MethodGet, aiModelsPath}} {
+		rec, body := call(c.method, c.path, "")
+		if rec.Code != http.StatusBadGateway || errorCode(body) != "provider_error" || !strings.Contains(rec.Body.String(), "upstream failed for Bearer [REDACTED]") {
+			t.Errorf("%s %s against an echoing vendor = %d %v, want 502 provider_error", c.method, c.path, rec.Code, body)
+		}
+	}
+	echo.Store(false)
+
+	rec, body = call(http.MethodPost, aiVerifyPath, "")
+	if rec.Code != http.StatusOK || body["key_verified_at"] == nil || body["api_key_last4"] != "7d21" {
+		t.Errorf("POST verify = %d %v", rec.Code, body)
+	}
+	rec, body = call(http.MethodGet, aiPath, "")
+	if rec.Code != http.StatusOK || body["key_verified_at"] == nil || body["model"] != "gpt-test" || body["temperature"] != 0.3 {
+		t.Errorf("GET after verify = %d %v", rec.Code, body)
+	}
+
+	rec, body = call(http.MethodGet, aiModelsPath, "")
+	models, _ := body["models"].([]any)
+	if rec.Code != http.StatusOK || len(models) != 3 {
+		t.Fatalf("GET models = %d %v", rec.Code, body)
+	}
+	if m := models[1].(map[string]any); m["id"] != "gpt-test-mini" || m["display_name"] != "GPT Test Mini" {
+		t.Errorf("GET models[1] = %v", m)
+	}
+	if m := models[2].(map[string]any); m["id"] != "gpt-[REDACTED]" || m["display_name"] != "Leaky [REDACTED]" {
+		t.Errorf("GET models[2] = %v, want the key redacted", m)
+	}
+
+	rec, body = call(http.MethodPatch, aiPath, `{"system_prompt":"Be brief."}`)
+	if rec.Code != http.StatusOK || body["system_prompt"] != "Be brief." || body["key_verified_at"] == nil {
+		t.Errorf("PATCH system_prompt = %d %v", rec.Code, body)
+	}
+	rec, body = call(http.MethodPost, aiResetPromptPath, "")
+	if rec.Code != http.StatusOK || body["system_prompt"] != household.DefaultPersonaPrompt {
+		t.Errorf("POST reset-prompt = %d %v", rec.Code, body)
+	}
+
+	// The stored key is never pointed at another server or provider.
+	for _, patch := range []string{`{"base_url":"https://attacker.example/v1"}`, `{"provider":"openai","base_url":""}`} {
+		if rec, body := call(http.MethodPatch, aiPath, patch); rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_settings" {
+			t.Errorf("PATCH %s with a key stored = %d %v, want 400 invalid_settings", patch, rec.Code, body)
+		}
+	}
+	if rec, body := call(http.MethodPut, aiKeyPath, `{"api_key":""}`); rec.Code != http.StatusOK || body["api_key_last4"] != nil || body["key_verified_at"] != nil {
+		t.Errorf("PUT empty key = %d %v", rec.Code, body)
+	}
+	rec, body = call(http.MethodPatch, aiPath, `{"base_url":"https://llm.example/v1"}`)
+	if rec.Code != http.StatusOK || body["base_url"] != "https://llm.example/v1" {
+		t.Errorf("PATCH base_url without a key = %d %v", rec.Code, body)
+	}
+
+	if len(bodies) < 30 {
+		t.Fatalf("scanned only %d response bodies", len(bodies))
+	}
+	for _, b := range bodies {
+		for _, key := range []string{testAIKey, testWrongAIKey} {
+			if strings.Contains(b, key) {
+				t.Errorf("response holds an API key: %s", b)
+			}
+		}
+	}
+}
+
+func TestAISettingsWritesNeedCSRF(t *testing.T) {
+	t.Parallel()
+	router := newAIRouter(t)
+	for _, c := range []struct{ method, path, body string }{
+		{http.MethodPatch, aiPath, `{"temperature":0.5}`},
+		{http.MethodPut, aiKeyPath, `{"api_key":"` + testAIKey + `"}`},
+		{http.MethodPost, aiVerifyPath, ""},
+		{http.MethodPost, aiResetPromptPath, ""},
+	} {
+		req := httptest.NewRequest(c.method, c.path, strings.NewReader(c.body))
+		req.AddCookie(validSessionCookie)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		if rec.Code != http.StatusForbidden {
+			t.Errorf("%s %s without the CSRF header = %d, want 403", c.method, c.path, rec.Code)
+		}
+	}
+	rec, body := serve(t, router, signedIn(http.MethodGet, aiPath, nil))
+	if rec.Code != http.StatusOK || body["api_key_last4"] != nil || body["temperature"] != 0.7 {
+		t.Errorf("GET after refused writes = %d %v, want the seed", rec.Code, body)
+	}
+}

internal/server/dinners.go

@@ -0,0 +1,258 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+)
+
+// maxDinnerBody bounds a POST or PATCH /dinners request body.
+const maxDinnerBody = 16 << 10
+
+// maxGroundBody bounds a POST /dinners/{id}/ground body, which may carry a
+// manual recipe of dinners.MaxManualLines lines of each kind.
+const maxGroundBody = 512 << 10
+
+// dinnerCreate is the POST /dinners body: a name, with or without a
+// recipe_url.
+type dinnerCreate struct {
+	Name      *string `json:"name"`
+	RecipeURL *string `json:"recipe_url"`
+}
+
+// dinnerPatch is the PATCH /dinners/{id} body. Every field is optional;
+// unknown fields and null values are refused.
+type dinnerPatch struct {
+	Name         *string `json:"name"`
+	Method       *string `json:"method"`
+	MinutesTotal *int    `json:"minutes_total"`
+	Difficulty   *string `json:"difficulty"`
+}
+
+type dinnerList struct {
+	Dinners []dinners.Dinner `json:"dinners"`
+}
+
+// dinnerGround is the POST /dinners/{id}/ground body: exactly one of
+// candidate_id, recipe_url and manual.
+type dinnerGround struct {
+	CandidateID *string             `json:"candidate_id"`
+	RecipeURL   *string             `json:"recipe_url"`
+	Manual      *dinnerManualRecipe `json:"manual"`
+}
+
+type dinnerManualRecipe struct {
+	Ingredients []string `json:"ingredients"`
+	Steps       []string `json:"steps"`
+	Minutes     *int     `json:"minutes"`
+	Method      *string  `json:"method"`
+}
+
+type candidateList struct {
+	Candidates []dinners.Candidate `json:"candidates"`
+}
+
+// getDinners answers GET /dinners?status=regular|quest_log.
+func getDinners(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		list, err := svc.List(r.Context(), r.URL.Query().Get("status"))
+		if err != nil {
+			writeDinnerError(w, r, logger, "list dinners", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, dinnerList{Dinners: list})
+	}
+}
+
+// postDinner adds a Regular, recording the session's actor as updated_by,
+// and answers 201 with it and its grounding_job_id without waiting for the
+// job. When the job cannot be enqueued it still answers 201, with the dinner
+// grounding_status failed and grounding_job_id null.
+func postDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[dinnerCreate](http.MaxBytesReader(w, r.Body, maxDinnerBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		d, err := svc.CreateRegular(r.Context(), dinners.NewRegular(body), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "create dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusCreated, d)
+	}
+}
+
+// patchDinner edits a dinner, recording the session's actor as updated_by.
+func patchDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		patch, err := decodePatch[dinnerPatch](http.MaxBytesReader(w, r.Body, maxDinnerBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		d, err := svc.Update(r.Context(), chi.URLParam(r, "id"), dinners.Patch(patch), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "update dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// getDinnerCandidates answers GET /dinners/{id}/recipe-candidates with up
+// to dinners.MaxCandidates recipe pages for the dinner's name.
+func getDinnerCandidates(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		list, err := svc.Candidates(r.Context(), chi.URLParam(r, "id"))
+		if err != nil {
+			writeDinnerError(w, r, logger, "list recipe candidates", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, candidateList{Candidates: list})
+	}
+}
+
+// postDinnerGround grounds a dinner by hand in a candidate, a pasted link
+// or a recipe typed in, recording the session's actor as updated_by.
+func postDinnerGround(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[dinnerGround](http.MaxBytesReader(w, r.Body, maxGroundBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		fix := dinners.Fix{CandidateID: body.CandidateID, RecipeURL: body.RecipeURL}
+		if body.Manual != nil {
+			m := dinners.ManualRecipe(*body.Manual)
+			fix.Manual = &m
+		}
+		d, err := svc.Ground(r.Context(), chi.URLParam(r, "id"), fix, actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "ground dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// deleteDinner archives a dinner; the row is never deleted.
+func deleteDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := svc.Archive(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "archive dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// postDinnerFavorite toggles a dinner's is_favorite.
+func postDinnerFavorite(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := svc.ToggleFavorite(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "toggle dinner favorite", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// actorOrFail returns the session's actor, or answers 500 when the request
+// has none, which behind requireSession is a wiring bug.
+func actorOrFail(w http.ResponseWriter, r *http.Request, logger *slog.Logger) (auth.Actor, bool) {
+	actor, ok := auth.ActorFrom(r.Context())
+	if !ok {
+		logger.ErrorContext(r.Context(), r.Method+" "+r.URL.Path+" without a session")
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+	return actor, ok
+}
+
+// writeDinnerError maps a dinners.Service error to its API error. A page
+// that cannot ground the dinner is 422 ungroundable; recipe search not set
+// up is 409 not_configured; a search or model failure is 502; grounding by
+// hand that runs past dinners.GroundTimeout is 504 ground_timeout; grounding
+// an archived dinner is 409 dinner_archived and one changed while grounding
+// 409 ground_conflict. Any other grounding failure, by candidate, link or
+// manual recipe, wraps dinners.ErrGroundFailed and is 500, logged by reason
+// and dinner id only, as is any other failure finding candidates, which
+// wraps dinners.ErrCandidatesFailed.
+func writeDinnerError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var invalid *dinners.ValidationError
+	var dup *dinners.DuplicateError
+	var ungroundable *recipes.ErrUngroundable
+	switch {
+	case errors.As(err, &ungroundable):
+		// The reasons quote dependency errors, so they are neither returned
+		// nor logged.
+		writeError(w, r, logger, http.StatusUnprocessableEntity, "ungroundable", "no usable recipe was found at that link")
+	case errors.Is(err, recipes.ErrSearchNotConfigured):
+		writeError(w, r, logger, http.StatusConflict, "not_configured", "recipe search is not configured")
+	case errors.Is(err, recipes.ErrSearchFailed):
+		// The error may quote the search provider's response, so only the
+		// reason is logged.
+		logger.WarnContext(r.Context(), action, "reason", "search_failed")
+		writeError(w, r, logger, http.StatusBadGateway, "search_failed", "recipe search failed")
+	case errors.Is(err, recipes.ErrNormalizeFailed):
+		logger.WarnContext(r.Context(), action, "reason", "normalize_recipe failed")
+		writeError(w, r, logger, http.StatusBadGateway, "ai_failed", "the AI provider failed to read the recipe")
+	case errors.Is(err, dinners.ErrGroundFailed):
+		// The error may quote the pasted link, which can carry a personal
+		// token, and dependency errors, so only the reason and dinner are
+		// logged.
+		logger.ErrorContext(r.Context(), action, "reason", "ground_failed", "dinner_id", chi.URLParam(r, "id"))
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	case errors.Is(err, dinners.ErrCandidatesFailed):
+		// The error may quote a candidate's URL, which can carry a
+		// personal token, and dependency errors, so only the reason and
+		// dinner are logged.
+		logger.ErrorContext(r.Context(), action, "reason", "candidates_failed", "dinner_id", chi.URLParam(r, "id"))
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	case errors.Is(err, dinners.ErrArchived):
+		writeError(w, r, logger, http.StatusConflict, "dinner_archived", "the dinner is archived")
+	case errors.Is(err, dinners.ErrGroundConflict):
+		writeError(w, r, logger, http.StatusConflict, "ground_conflict", "the dinner changed while its recipe was grounding; reload and try again")
+	case errors.Is(err, dinners.ErrGroundTimeout):
+		logger.WarnContext(r.Context(), action, "reason", "ground_timeout")
+		writeError(w, r, logger, http.StatusGatewayTimeout, "ground_timeout", "grounding the recipe took too long; try again")
+	case errors.As(err, &invalid):
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_dinner", invalid.Error())
+	case errors.As(err, &dup):
+		writeError(w, r, logger, http.StatusConflict, "duplicate_dinner", dup.Error())
+	case errors.Is(err, dinners.ErrNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "dinner not found")
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/dinners_test.go

@@ -0,0 +1,618 @@
+package server
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const dinnersPath = "/api/v1/dinners"
+
+// newDinnersRouter returns a router whose dinners service runs over the
+// returned store. Its job runner is not started, so grounding jobs stay
+// queued.
+func newDinnersRouter(t *testing.T) (http.Handler, *store.Store) {
+	t.Helper()
+	e := newDinnersEnv(t)
+	return e.h, e.st
+}
+
+// dinnersEnv is a router whose dinners service, job runner and grounder
+// share one store, grounding with fake search, pages, images and model.
+type dinnersEnv struct {
+	h      http.Handler
+	st     *store.Store
+	runner *jobs.Runner
+	search *recipestest.Search
+	pages  *recipestest.Pages
+	images *recipestest.Images
+	model  *llm.Fake
+	// logs holds everything the router and services log.
+	logs *logBuffer
+}
+
+// logBuffer is a bytes.Buffer safe for concurrent log writes.
+type logBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *logBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *logBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+func newDinnersEnv(t *testing.T) *dinnersEnv {
+	t.Helper()
+	st := newTestStore(t)
+	e := &dinnersEnv{
+		st:     st,
+		search: &recipestest.Search{Results: map[string][]recipes.Candidate{}},
+		pages:  &recipestest.Pages{Bodies: map[string][]byte{}},
+		images: &recipestest.Images{JPEGs: map[string][]byte{}},
+		model:  &llm.Fake{},
+		logs:   &logBuffer{},
+	}
+	logger := slog.New(slog.NewTextHandler(e.logs, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.runner = runner
+	g := recipestest.NewGrounder(t, st, t.TempDir(), e.search, e.pages, e.images, e.model)
+	svc, err := dinners.NewService(st, g, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+		svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return e
+}
+
+// start starts the env's job runner, stopping it when the test ends.
+func (e *dinnersEnv) start(t *testing.T) {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := e.runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		e.runner.Wait()
+	})
+}
+
+// callDinners sends a signed-in request with body (none when empty).
+func callDinners(t *testing.T, h http.Handler, method, target, body string) (*httptest.ResponseRecorder, map[string]any) {
+	t.Helper()
+	var r io.Reader
+	if body != "" {
+		r = strings.NewReader(body)
+	}
+	return serve(t, h, signedIn(method, target, r))
+}
+
+// createDinner adds a Regular and returns its id.
+func createDinner(t *testing.T, h http.Handler, body string) string {
+	t.Helper()
+	rec, got := callDinners(t, h, http.MethodPost, dinnersPath, body)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST %s = %d: %s", body, rec.Code, rec.Body)
+	}
+	return got["id"].(string)
+}
+
+// listNames returns the names GET /dinners?status=status lists, in order.
+func listNames(t *testing.T, h http.Handler, status string) []string {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"?status="+status, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=%s = %d: %s", status, rec.Code, rec.Body)
+	}
+	list, ok := body["dinners"].([]any)
+	if !ok {
+		t.Fatalf("GET status=%s has no dinners list: %v", status, body)
+	}
+	names := make([]string, len(list))
+	for i, d := range list {
+		names[i] = d.(map[string]any)["name"].(string)
+	}
+	return names
+}
+
+func TestCreateDinnerByName(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"  Chicken Tikka Masala "}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":             "Chicken Tikka Masala",
+		"status":           "regular",
+		"origin":           "regular",
+		"grounding_status": "pending",
+		"is_favorite":      false,
+		"photo_url":        nil,
+		"method":           nil,
+		"minutes_total":    nil,
+		"difficulty":       nil,
+		"updated_by":       testSession.Subject,
+	} {
+		if got, ok := body[k]; !ok || got != v {
+			t.Errorf("%s = %#v (present %v), want %#v", k, got, ok, v)
+		}
+	}
+	if got, ok := body["recipe_url"]; ok {
+		t.Errorf("recipe_url = %#v, want no recipe_url in a dinner response", got)
+	}
+	var normalized, updatedBy string
+	if err := st.Reader.QueryRow(`SELECT normalized_name, updated_by FROM dinners WHERE id = ?`, body["id"]).Scan(&normalized, &updatedBy); err != nil {
+		t.Fatal(err)
+	}
+	if normalized != "chicken tikka masala" || updatedBy != testSession.Subject {
+		t.Errorf("stored normalized_name, updated_by = %q, %q", normalized, updatedBy)
+	}
+}
+
+func TestCreateDinnerByURL(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+
+	link := "https://www.example.com/recipes/12345/beef-and-broccoli-stir-fry/"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Stir fry night","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":             "Stir fry night",
+		"status":           "regular",
+		"origin":           "regular",
+		"grounding_status": "pending",
+		"updated_by":       testSession.Subject,
+	} {
+		if body[k] != v {
+			t.Errorf("%s = %#v, want %#v", k, body[k], v)
+		}
+	}
+	// The link stays on the server for grounding; responses never carry it.
+	if got, ok := body["recipe_url"]; ok {
+		t.Errorf("recipe_url = %#v, want no recipe_url in a dinner response", got)
+	}
+
+	// The same link again is a duplicate even though its name would differ.
+	rec, body = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Something else entirely"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("unrelated name = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Beef and broccoli","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+		t.Errorf("same link again = %d %v, want 409 duplicate_dinner", rec.Code, body)
+	}
+
+	for _, tc := range []struct{ name, body string }{
+		{"plain http", `{"name":"Chili","recipe_url":"http://example.com/recipes/chili"}`},
+		{"not a URL", `{"name":"Chili","recipe_url":"chili"}`},
+		{"credentials", `{"name":"Chili","recipe_url":"https://me:pw@example.com/recipes/chili"}`},
+		{"link without a name", `{"recipe_url":"https://example.com/recipes/chili"}`},
+		{"filler name with a link", `{"name":"The Best Easy Recipe","recipe_url":"https://example.com/recipes/chili"}`},
+		{"neither field", `{}`},
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("%s: %d %v, want 400 invalid_dinner", tc.name, rec.Code, body)
+		}
+	}
+}
+
+// TestDinnerResponsesHideRecipeURL: a pasted link may carry a personal
+// token, so neither the create response nor a later list read shows any
+// part of it, while the stored link still awaits grounding.
+func TestDinnerResponsesHideRecipeURL(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+
+	const link = "https://c.example/recipes/stew?access_token=personal-token-abc123"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	created := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=regular = %d: %s", rec.Code, rec.Body)
+	}
+	for _, resp := range []struct{ name, body string }{{"create", created}, {"list", rec.Body.String()}} {
+		for _, secret := range []string{link, "c.example", "access_token", "personal-token-abc123", "recipe_url"} {
+			if strings.Contains(resp.body, secret) {
+				t.Errorf("%s response contains %q: %s", resp.name, secret, resp.body)
+			}
+		}
+	}
+
+	var stored string
+	if err := st.Reader.QueryRow(`SELECT recipe_url FROM dinners WHERE id = ?`, body["id"]).Scan(&stored); err != nil {
+		t.Fatal(err)
+	}
+	if stored != link {
+		t.Errorf("stored recipe_url = %q, want %q kept for grounding", stored, link)
+	}
+}
+
+// TestDinnerResponsesHideTokenInLinkPath: a personal token can sit
+// anywhere in a link's path, even as plain letters, so a dinner added from
+// a link is named only by the household and neither the create response, a
+// later list read nor the duplicate error for the same link shows any of
+// the link.
+func TestDinnerResponsesHideTokenInLinkPath(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+
+	const link = "https://c.example/recipes/stew-key-abcdefghijklmno"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Sunday stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	if body["name"] != "Sunday stew" {
+		t.Errorf("name = %v, want Sunday stew", body["name"])
+	}
+	created := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=regular = %d: %s", rec.Code, rec.Body)
+	}
+	listed := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Beef stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("same link again = %d, want 409: %s", rec.Code, rec.Body)
+	}
+	// Each secret holds a character no ULID has (Crockford base32 has no I,
+	// L, O, U, "-", "." or "/"), so the dinner's id never matches one.
+	for _, resp := range []struct{ name, body string }{{"create", created}, {"list", listed}, {"duplicate", rec.Body.String()}} {
+		lower := strings.ToLower(resp.body)
+		for _, secret := range []string{link, "c.example", "recipes/stew", "stew-key", "abcdefghijklmno"} {
+			if strings.Contains(lower, secret) {
+				t.Errorf("%s response contains %q: %s", resp.name, secret, resp.body)
+			}
+		}
+	}
+}
+
+func TestCreateDinnerDuplicate(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	createDinner(t, router, `{"name":"Chicken Tikka Masala"}`)
+
+	for _, name := range []string{
+		"chicken tikka masala",
+		"Easy Chicken Tikka-Masala!",
+		"The Best Homemade Chicken Tikka Masala Recipe",
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"`+name+`"}`)
+		if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+			t.Errorf("%q: %d %v, want 409 duplicate_dinner", name, rec.Code, body)
+		}
+	}
+	// A name repeating the dish is a duplicate with a link too.
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Chicken tikka masala","recipe_url":"https://example.com/other-curry.html"}`)
+	if rec.Code != http.StatusConflict {
+		t.Errorf("named duplicate with a link = %d %v, want 409", rec.Code, body)
+	}
+
+	var n int
+	if err := st.Reader.QueryRow(`SELECT count(*) FROM dinners`).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	if n != 1 {
+		t.Errorf("dinners rows = %d, want 1", n)
+	}
+
+	// A different dish sharing words is not a duplicate.
+	createDinner(t, router, `{"name":"Chicken Tikka Wraps"}`)
+}
+
+func TestCreateDinnerRejected(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+	for _, tc := range []struct{ name, body, code string }{
+		{"empty name", `{"name":"   "}`, "invalid_dinner"},
+		{"filler only", `{"name":"The Best Easy Recipe"}`, "invalid_dinner"},
+		{"too long", `{"name":"` + strings.Repeat("x", dinners.MaxNameChars+1) + `"}`, "invalid_dinner"},
+		{"null name", `{"name":null}`, "invalid_request"},
+		{"unknown field", `{"name":"Chili","status":"quest_log"}`, "invalid_request"},
+		{"not an object", `"Chili"`, "invalid_request"},
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code {
+			t.Errorf("%s: %d %v, want 400 %s", tc.name, rec.Code, body, tc.code)
+		}
+	}
+}
+
+func TestListDinnersFiltersByStatus(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	tacos := createDinner(t, router, `{"name":"Tacos"}`)
+	createDinner(t, router, `{"name":"Lasagna"}`)
+	pho := createDinner(t, router, `{"name":"Pho"}`)
+	gone := createDinner(t, router, `{"name":"Meatloaf"}`)
+
+	ctx := context.Background()
+	if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET status = 'quest_log', origin = 'side_quest' WHERE id = ?`, pho); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.Writer.ExecContext(ctx,
+		`INSERT INTO photos (id, source_url, local_path, width, height, sha256, fetched_at, created_at, updated_at)
+		 VALUES ('photo1', 'https://example.com/tacos.jpg', 'media/photos/photo1', 1200, 800, 'abc', 't', 't', 't')`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET photo_id = 'photo1', grounding_status = 'grounded' WHERE id = ?`, tacos); err != nil {
+		t.Fatal(err)
+	}
+	if rec, _ := callDinners(t, router, http.MethodDelete, dinnersPath+"/"+gone, ""); rec.Code != http.StatusOK {
+		t.Fatalf("DELETE = %d", rec.Code)
+	}
+
+	if got := strings.Join(listNames(t, router, "regular"), ","); got != "Lasagna,Tacos" {
+		t.Errorf("regular = %s, want Lasagna,Tacos", got)
+	}
+	if got := strings.Join(listNames(t, router, "quest_log"), ","); got != "Pho" {
+		t.Errorf("quest_log = %s, want Pho", got)
+	}
+
+	_, body := callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	for _, d := range body["dinners"].([]any) {
+		d := d.(map[string]any)
+		switch d["name"] {
+		case "Tacos":
+			if d["photo_url"] != "/media/photos/photo1-400.jpg" || d["grounding_status"] != "grounded" {
+				t.Errorf("Tacos photo_url, grounding_status = %v, %v", d["photo_url"], d["grounding_status"])
+			}
+		case "Lasagna":
+			if d["photo_url"] != nil || d["grounding_status"] != "pending" {
+				t.Errorf("Lasagna photo_url, grounding_status = %v, %v", d["photo_url"], d["grounding_status"])
+			}
+		}
+	}
+
+	// An empty list is [] rather than null.
+	empty, _ := newDinnersRouter(t)
+	rec, _ := callDinners(t, empty, http.MethodGet, dinnersPath+"?status=regular", "")
+	if got := rec.Body.String(); got != `{"dinners":[]}` {
+		t.Errorf("empty list = %s", got)
+	}
+
+	for _, q := range []string{"", "?status=archived", "?status=suggested", "?status=bogus"} {
+		rec, body := callDinners(t, router, http.MethodGet, dinnersPath+q, "")
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("GET %q = %d %v, want 400 invalid_dinner", q, rec.Code, body)
+		}
+	}
+}
+
+func TestPatchDinner(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+	createDinner(t, router, `{"name":"Pot Roast"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id,
+		`{"name":"White Chicken Chili","method":"crockpot","minutes_total":480,"difficulty":"easy"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":          "White Chicken Chili",
+		"method":        "crockpot",
+		"minutes_total": float64(480),
+		"difficulty":    "easy",
+		"status":        "regular",
+		"updated_by":    testSession.Subject,
+	} {
+		if body[k] != v {
+			t.Errorf("%s = %#v, want %#v", k, body[k], v)
+		}
+	}
+	var normalized string
+	if err := st.Reader.QueryRow(`SELECT normalized_name FROM dinners WHERE id = ?`, id).Scan(&normalized); err != nil {
+		t.Fatal(err)
+	}
+	if normalized != "white chicken chili" {
+		t.Errorf("normalized_name = %q", normalized)
+	}
+
+	// A partial patch leaves the other fields.
+	rec, body = callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"difficulty":"medium"}`)
+	if rec.Code != http.StatusOK || body["method"] != "crockpot" || body["difficulty"] != "medium" || body["name"] != "White Chicken Chili" {
+		t.Errorf("partial patch = %d %v", rec.Code, body)
+	}
+	// Renaming to its own name, respelled, is not a duplicate of itself.
+	if rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"name":"Easy white chicken chili"}`); rec.Code != http.StatusOK {
+		t.Errorf("self rename = %d %v", rec.Code, body)
+	}
+	// Renaming onto another dinner is.
+	rec, body = callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"name":"The Best Pot Roast"}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+		t.Errorf("rename onto Pot Roast = %d %v, want 409", rec.Code, body)
+	}
+}
+
+func TestPatchDinnerValidation(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+
+	for _, tc := range []struct {
+		name, body, code, in string
+	}{
+		{"bad method", `{"method":"microwave"}`, "invalid_dinner", "method"},
+		{"crock pot spelling", `{"method":"crock pot"}`, "invalid_dinner", "method"},
+		{"bad difficulty", `{"difficulty":"expert"}`, "invalid_dinner", "difficulty"},
+		{"zero minutes", `{"minutes_total":0}`, "invalid_dinner", "minutes_total"},
+		{"negative minutes", `{"minutes_total":-5}`, "invalid_dinner", "minutes_total"},
+		{"too many minutes", `{"minutes_total":1441}`, "invalid_dinner", "minutes_total"},
+		{"empty name", `{"name":""}`, "invalid_dinner", "name"},
+		{"every problem", `{"method":"x","difficulty":"y","minutes_total":0}`, "invalid_dinner", "method: must be one of stovetop, oven, crockpot, grill, other; minutes_total"},
+		{"empty patch", `{}`, "invalid_dinner", "no fields"},
+		{"fractional minutes", `{"minutes_total":30.5}`, "invalid_request", "minutes_total"},
+		{"string minutes", `{"minutes_total":"30"}`, "invalid_request", "minutes_total"},
+		{"null method", `{"method":null}`, "invalid_request", "method"},
+		{"read-only field", `{"status":"archived"}`, "invalid_request", "status"},
+		{"favorite field", `{"is_favorite":true}`, "invalid_request", "is_favorite"},
+	} {
+		rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, tc.body)
+		msg, _ := body["error"].(map[string]any)["message"].(string)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code || !strings.Contains(msg, tc.in) {
+			t.Errorf("%s: %d %v, want 400 %s containing %q", tc.name, rec.Code, body, tc.code, tc.in)
+		}
+	}
+
+	_, body := callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	d := body["dinners"].([]any)[0].(map[string]any)
+	if d["method"] != nil || d["difficulty"] != nil || d["minutes_total"] != nil || d["name"] != "Chili" {
+		t.Errorf("a rejected patch changed the dinner: %v", d)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/nope", `{"method":"oven"}`)
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestDeleteDinnerArchives(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Shepherd's Pie"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, router, http.MethodDelete, dinnersPath+"/"+id, "")
+	if rec.Code != http.StatusOK || body["status"] != "archived" || body["updated_by"] != testSession.Subject {
+		t.Fatalf("DELETE = %d %v", rec.Code, body)
+	}
+	var status, name, updatedBy string
+	if err := st.Reader.QueryRow(`SELECT status, name, updated_by FROM dinners WHERE id = ?`, id).Scan(&status, &name, &updatedBy); err != nil {
+		t.Fatalf("archived row is gone: %v", err)
+	}
+	if status != "archived" || name != "Shepherd's Pie" || updatedBy != testSession.Subject {
+		t.Errorf("row = %s %q %s", status, name, updatedBy)
+	}
+	if got := listNames(t, router, "regular"); len(got) != 0 {
+		t.Errorf("regular after archive = %v", got)
+	}
+	// An archived name may be added again.
+	createDinner(t, router, `{"name":"Shepherds Pie"}`)
+
+	rec, body = callDinners(t, router, http.MethodDelete, dinnersPath+"/nope", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestFavoriteDinnerToggles(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Fish Tacos"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, want := range []bool{true, false, true} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath+"/"+id+"/favorite", "")
+		if rec.Code != http.StatusOK || body["is_favorite"] != want || body["updated_by"] != testSession.Subject {
+			t.Fatalf("favorite = %d %v, want is_favorite %v", rec.Code, body, want)
+		}
+	}
+	var fav int
+	if err := st.Reader.QueryRow(`SELECT is_favorite FROM dinners WHERE id = ?`, id).Scan(&fav); err != nil {
+		t.Fatal(err)
+	}
+	if fav != 1 {
+		t.Errorf("stored is_favorite = %d, want 1", fav)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath+"/nope/favorite", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+// TestDinnerWritesRequireCSRF sends every dinners write without the CSRF
+// header and with a wrong one; each is refused and changes nothing.
+func TestDinnerWritesRequireCSRF(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+
+	var before string
+	snapshot := `SELECT group_concat(id || name || status || is_favorite || coalesce(method, '') || updated_at, '|') FROM dinners`
+	if err := st.Reader.QueryRow(snapshot).Scan(&before); err != nil {
+		t.Fatal(err)
+	}
+
+	writes := []struct{ method, target, body string }{
+		{http.MethodPost, dinnersPath, `{"name":"Lasagna"}`},
+		{http.MethodPatch, dinnersPath + "/" + id, `{"method":"oven"}`},
+		{http.MethodDelete, dinnersPath + "/" + id, ""},
+		{http.MethodPost, dinnersPath + "/" + id + "/favorite", ""},
+	}
+	for _, w := range writes {
+		for _, header := range []*string{nil, ptr("wrong-token")} {
+			req := httptest.NewRequest(w.method, w.target, strings.NewReader(w.body))
+			req.AddCookie(validSessionCookie)
+			if header != nil {
+				req.Header.Set(CSRFHeader, *header)
+			}
+			rec, body := serve(t, router, req)
+			if rec.Code != http.StatusForbidden || errorCode(body) != "csrf" {
+				t.Errorf("%s %s (header %v) = %d %v, want 403 csrf", w.method, w.target, header != nil, rec.Code, body)
+			}
+		}
+	}
+
+	var after string
+	if err := st.Reader.QueryRow(snapshot).Scan(&after); err != nil {
+		t.Fatal(err)
+	}
+	if after != before {
+		t.Errorf("refused writes changed dinners:\n before %s\n after  %s", before, after)
+	}
+
+	// Without a session, the list is 401 too.
+	req := httptest.NewRequest(http.MethodGet, dinnersPath+"?status=regular", nil)
+	if rec, body := serve(t, router, req); rec.Code != http.StatusUnauthorized || errorCode(body) != "unauthenticated" {
+		t.Errorf("GET without a session = %d %v, want 401", rec.Code, body)
+	}
+}
+
+func ptr[T any](v T) *T { return &v }

internal/server/grounding_test.go

@@ -0,0 +1,558 @@
+package server
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+)
+
+// Fixture pages: two curries found by searching "Chicken curry" and a stew
+// at a pasted link.
+const (
+	curryPage  = "https://a.example/chicken-curry"
+	curry2Page = "https://b.example/curry"
+	stewPage   = "https://c.example/recipes/beef-stew"
+)
+
+// withRecipes adds the fixture pages, their photos and the search for
+// "Chicken curry" to e.
+func (e *dinnersEnv) withRecipes(t *testing.T) *dinnersEnv {
+	t.Helper()
+	e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: curryPage}, {URL: curry2Page}}
+	e.pages.Bodies[curryPage] = recipestest.RecipePage("Chicken Curry", "Curry House", "https://a.example/curry.jpg", 40)
+	e.pages.Bodies[curry2Page] = recipestest.RecipePage("Weeknight Curry", "B Kitchen", "https://b.example/curry.jpg", 25)
+	e.pages.Bodies[stewPage] = recipestest.RecipePage("Beef Stew", "Stew Co", "https://c.example/stew.jpg", 150)
+	e.images.JPEGs["https://a.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 1)
+	e.images.JPEGs["https://b.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 2)
+	e.images.JPEGs["https://c.example/stew.jpg"] = recipestest.JPEG(t, 400, 320, 3)
+	return e
+}
+
+// waitJob polls GET /jobs/{id} until the job ends and returns its body.
+func waitJob(t *testing.T, h http.Handler, id string) map[string]any {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		rec, body := callDinners(t, h, http.MethodGet, "/api/v1/jobs/"+id, "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("GET job = %d: %s", rec.Code, rec.Body)
+		}
+		if s := body["status"]; s == "succeeded" || s == "failed" {
+			return body
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job %s never finished; last %v", id, body)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// listedDinner returns dinner id as GET /dinners?status=regular lists it.
+func listedDinner(t *testing.T, h http.Handler, id string) map[string]any {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET dinners = %d: %s", rec.Code, rec.Body)
+	}
+	for _, d := range body["dinners"].([]any) {
+		if d := d.(map[string]any); d["id"] == id {
+			return d
+		}
+	}
+	t.Fatalf("dinner %s not listed", id)
+	return nil
+}
+
+// candidateID returns the candidate_id GET recipe-candidates offers dinner
+// id for the page titled title.
+func candidateID(t *testing.T, h http.Handler, id, title string) string {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET candidates = %d: %s", rec.Code, rec.Body)
+	}
+	for _, c := range body["candidates"].([]any) {
+		if c := c.(map[string]any); c["title"] == title {
+			cid := c["candidate_id"].(string)
+			if strings.Contains(cid, "://") {
+				t.Fatalf("candidate_id = %q, want an opaque id, not the page URL", cid)
+			}
+			return cid
+		}
+	}
+	t.Fatalf("candidates = %v, want one titled %q", body, title)
+	return ""
+}
+
+func TestPostDinnerReturnsBeforeGroundingCompletes(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	e.search.Gate = make(chan struct{})
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	e.start(t)
+
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Chicken curry"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	jobID, _ := created["grounding_job_id"].(string)
+	if created["grounding_status"] != "pending" || created["grounding_error"] != nil || jobID == "" {
+		t.Fatalf("created = %v, want pending with a grounding_job_id", created)
+	}
+	// The search is held, so grounding cannot have completed.
+	_, job := callDinners(t, e.h, http.MethodGet, "/api/v1/jobs/"+jobID, "")
+	if s := job["status"]; s != "queued" && s != "running" {
+		t.Fatalf("job right after POST = %v, want queued or running", job)
+	}
+	if d := listedDinner(t, e.h, created["id"].(string)); d["grounding_status"] != "pending" {
+		t.Fatalf("dinner right after POST = %v, want pending", d)
+	}
+
+	close(e.search.Gate)
+	job = waitJob(t, e.h, jobID)
+	if job["status"] != "succeeded" || job["kind"] != "ground_dinner" {
+		t.Fatalf("job = %v, want ground_dinner succeeded", job)
+	}
+	d := listedDinner(t, e.h, created["id"].(string))
+	photo, _ := d["photo_url"].(string)
+	if d["grounding_status"] != "grounded" || d["recipe_id"] == nil || !strings.HasSuffix(photo, "-400.jpg") ||
+		d["method"] != "stovetop" || d["minutes_total"] != 40.0 || d["difficulty"] != "easy" || d["grounding_error"] != nil {
+		t.Errorf("dinner = %v, want grounded with recipe, photo, method, minutes and difficulty", d)
+	}
+}
+
+func TestPostDinnerGroundingFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	e.start(t)
+
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Nothing matches this"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	job := waitJob(t, e.h, created["grounding_job_id"].(string))
+	if job["status"] != "failed" || job["error"] != "no_recipe_found" {
+		t.Errorf("job = %v, want failed with no_recipe_found", job)
+	}
+	d := listedDinner(t, e.h, created["id"].(string))
+	if d["grounding_status"] != "failed" || d["grounding_error"] != "no_recipe_found" || d["recipe_id"] != nil {
+		t.Errorf("dinner = %v, want failed with no_recipe_found", d)
+	}
+}
+
+func TestGetRecipeCandidates(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	list, _ := body["candidates"].([]any)
+	if len(list) != 2 {
+		t.Fatalf("candidates = %v, want 2", body)
+	}
+	first := list[0].(map[string]any)
+	if cid, _ := first["candidate_id"].(string); cid == "" || strings.Contains(cid, "a.example") {
+		t.Errorf("candidate_id = %#v, want an opaque id", first["candidate_id"])
+	}
+	want := map[string]any{
+		"candidate_id": first["candidate_id"],
+		"title":        "Chicken Curry",
+		"site_name":    "Curry House",
+		"photo_url":    nil,
+		"minutes":      40.0,
+	}
+	if len(first) != len(want) {
+		t.Errorf("candidate keys = %v, want exactly %v", first, want)
+	}
+	for k, v := range want {
+		if got, ok := first[k]; !ok || got != v {
+			t.Errorf("%s = %#v (present %v), want %#v", k, got, ok, v)
+		}
+	}
+
+	rec, body = callDinners(t, e.h, http.MethodGet, dinnersPath+"/nope/recipe-candidates", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown dinner = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestGetRecipeCandidatesSearchFails(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	// The provider's text must reach neither the response nor the logs.
+	const leak = "provider-said-token-abc123"
+	e.search.Err = fmt.Errorf("%w: %s", recipes.ErrSearchRefused, leak)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusBadGateway || errorCode(body) != "search_failed" {
+		t.Errorf("GET = %d %v, want 502 search_failed", rec.Code, body)
+	}
+	if strings.Contains(rec.Body.String(), leak) {
+		t.Errorf("response quotes the provider: %s", rec.Body)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, leak) || !strings.Contains(logs, "reason=search_failed") {
+		t.Errorf("logs = %q, want reason=search_failed and no provider text", logs)
+	}
+}
+
+// TestGetRecipeCandidatesStoredLookupFailure: a candidate whose stored
+// recipe cannot be read, or is stored incomplete, is a 500 logged by reason
+// and dinner id, never with the candidate's URL, which can carry a personal
+// token, or the database error.
+func TestGetRecipeCandidatesStoredLookupFailure(t *testing.T) {
+	t.Parallel()
+	const (
+		token = "personal-token-abc123"
+		host  = "secret-candidate.example"
+		page  = "https://" + host + "/curry?access_token=" + token
+	)
+	for _, tc := range []struct {
+		name, sabotage string
+		leaks          []string
+	}{
+		// Renaming a column the lookup selects fails the read.
+		{"lookup", `ALTER TABLE recipes RENAME COLUMN yield TO yield_gone`, []string{"no such column", "yield"}},
+		// A recipe stored without its photo, method or difficulty is
+		// incomplete.
+		{"incomplete", `INSERT INTO recipes (id, source_url, title, raw_jsonld, fetched_at, created_at, updated_at)
+			VALUES ('r-incomplete', '` + page + `', 'Curry', '{}', 'now', 'now', 'now')`, []string{"r-incomplete", "no photo"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			e := newDinnersEnv(t)
+			e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: page}}
+			id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+			if _, err := e.st.Writer.ExecContext(t.Context(), tc.sabotage); err != nil {
+				t.Fatal(err)
+			}
+
+			rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+			if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+				t.Errorf("GET = %d %s, want 500 internal", rec.Code, rec.Body)
+			}
+			logs := e.logs.String()
+			for _, secret := range append([]string{page, host, token, "access_token"}, tc.leaks...) {
+				if strings.Contains(rec.Body.String(), secret) {
+					t.Errorf("response contains %q: %s", secret, rec.Body)
+				}
+				if strings.Contains(logs, secret) {
+					t.Errorf("logs contain %q: %s", secret, logs)
+				}
+			}
+			if !strings.Contains(logs, "reason=candidates_failed") || !strings.Contains(logs, "dinner_id="+id) {
+				t.Errorf("logs = %q, want reason=candidates_failed and the dinner id", logs)
+			}
+		})
+	}
+}
+
+func TestPostGroundViaCandidate(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
+
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+cid+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	photo, _ := d["photo_url"].(string)
+	if d["grounding_status"] != "grounded" || d["recipe_id"] == nil || photo == "" ||
+		d["method"] != "stovetop" || d["minutes_total"] != 25.0 || d["difficulty"] != "easy" || d["updated_by"] != testSession.Subject {
+		t.Errorf("dinner = %v", d)
+	}
+	// The candidate is now stored, so it is offered with its photo.
+	_, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	for _, c := range body["candidates"].([]any) {
+		if c := c.(map[string]any); c["candidate_id"] == cid && c["photo_url"] != photo {
+			t.Errorf("grounded candidate photo_url = %v, want %s", c["photo_url"], photo)
+		}
+	}
+}
+
+// TestRecipeCandidatesHideTokenURLs: a candidate page whose URL carries a
+// token in its path or query is offered by an opaque id alone, which
+// grounds the dinner in that page.
+func TestRecipeCandidatesHideTokenURLs(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	const (
+		pathToken  = "path-token-abc123"
+		queryToken = "query-token-def456"
+		pathPage   = "https://secret-path.example/u/" + pathToken + "/chicken-curry"
+		queryPage  = "https://secret-query.example/curry?access_token=" + queryToken
+	)
+	e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: pathPage}, {URL: queryPage}}
+	e.pages.Bodies[pathPage] = recipestest.RecipePage("Chicken Curry", "Curry House", "https://a.example/curry.jpg", 40)
+	e.pages.Bodies[queryPage] = recipestest.RecipePage("Weeknight Curry", "B Kitchen", "https://b.example/curry.jpg", 25)
+	e.images.JPEGs["https://b.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 2)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	if list, _ := body["candidates"].([]any); len(list) != 2 {
+		t.Fatalf("candidates = %v, want 2", body)
+	}
+	for _, secret := range []string{pathPage, queryPage, "secret-path.example", "secret-query.example", pathToken, queryToken, "access_token"} {
+		if strings.Contains(rec.Body.String(), secret) {
+			t.Errorf("candidates response contains %q: %s", secret, rec.Body)
+		}
+	}
+
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+cid+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if strings.Contains(rec.Body.String(), queryToken) {
+		t.Errorf("ground response contains the token: %s", rec.Body)
+	}
+	var source string
+	if err := e.st.Reader.QueryRow(`SELECT source_url FROM recipes WHERE id = ?`, d["recipe_id"]).Scan(&source); err != nil {
+		t.Fatal(err)
+	}
+	if d["grounding_status"] != "grounded" || source != queryPage {
+		t.Errorf("dinner = %v in recipe %s, want grounded in %s", d, source, queryPage)
+	}
+}
+
+// TestPostGroundRejectsCandidateNotOffered: a candidate_id is only one
+// offered for that dinner; a page URL, or another dinner's candidate, is
+// refused.
+func TestPostGroundRejectsCandidateNotOffered(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	other := createDinner(t, e.h, `{"name":"Pad thai"}`)
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	for _, tc := range []struct{ name, dinner, cid string }{
+		{"page URL", id, curry2Page},
+		{"another dinner's", other, cid},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+tc.dinner+"/ground", `{"candidate_id":"`+tc.cid+`"}`)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("%s: %d %v, want 400 invalid_dinner", tc.name, rec.Code, body)
+		}
+	}
+}
+
+func TestPostGroundViaRecipeURL(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+stewPage+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if d["grounding_status"] != "grounded" || d["photo_url"] == nil || d["method"] != "oven" || d["minutes_total"] != 150.0 {
+		t.Errorf("dinner = %v", d)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"https://gone.example/soup"}`)
+	if rec.Code != http.StatusUnprocessableEntity || errorCode(body) != "ungroundable" || strings.Contains(rec.Body.String(), "gone.example") {
+		t.Errorf("unusable link = %d %v, want 422 ungroundable", rec.Code, body)
+	}
+}
+
+// TestPostGroundViaRecipeURLStorageFailure: a pasted link that fails for a
+// reason other than its recipe is a 500 logged by reason and dinner id,
+// never with the link, which can carry a personal token, or the dependency
+// error.
+func TestPostGroundViaRecipeURLStorageFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	const token = "personal-token-abc123"
+	link := stewPage + "?access_token=" + token
+	e.pages.Bodies[link] = e.pages.Bodies[stewPage]
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_recipes BEFORE INSERT ON recipes BEGIN SELECT RAISE(ABORT, 'disk full'); END`); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" || strings.Contains(rec.Body.String(), token) {
+		t.Errorf("POST = %d %s, want 500 internal without the link", rec.Code, rec.Body)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, token) || strings.Contains(logs, "c.example") || strings.Contains(logs, "disk full") ||
+		!strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+		t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the link or dependency error", logs)
+	}
+}
+
+// TestPostGroundViaRecipeURLDinnerWriteFailure: a pasted link whose recipe
+// is stored but whose dinner cannot be written is a 500 logged by reason
+// and dinner id, never with the dependency error.
+func TestPostGroundViaRecipeURLDinnerWriteFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_grounding BEFORE UPDATE OF recipe_id ON dinners WHEN NEW.recipe_id IS NOT NULL BEGIN SELECT RAISE(ABORT, 'disk full'); END`); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+stewPage+`"}`)
+	if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+		t.Errorf("POST = %d %s, want 500 internal", rec.Code, rec.Body)
+	}
+	var stored int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM recipes WHERE source_url = ?`, stewPage).Scan(&stored); err != nil || stored != 1 {
+		t.Fatalf("recipes stored for the link = %d (%v), want 1: the failure must be the dinner write", stored, err)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, "disk full") || !strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+		t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the dependency error", logs)
+	}
+}
+
+// TestPostGroundUnexpectedFailures: grounding by hand that fails reading
+// the dinner, or storing a manual recipe, is a 500 logged by reason and
+// dinner id, never with the database error.
+func TestPostGroundUnexpectedFailures(t *testing.T) {
+	t.Parallel()
+	const (
+		// Renaming a column every dinner read selects fails the read.
+		breakRead = `ALTER TABLE dinners RENAME COLUMN cuisine TO cuisine_gone`
+		// The trigger's message stands in for the database error.
+		breakStore = `CREATE TRIGGER refuse_recipes BEFORE INSERT ON recipes BEGIN SELECT RAISE(ABORT, 'disk full'); END`
+		manual     = `{"manual":{"ingredients":["1 lb beef"],"steps":["Brown."],"minutes":240,"method":"crockpot"}}`
+	)
+	for _, tc := range []struct {
+		name, sabotage, fix, leak string
+	}{
+		{"link read", breakRead, `{"recipe_url":"` + stewPage + `"}`, "cuisine"},
+		{"manual read", breakRead, manual, "cuisine"},
+		{"manual store", breakStore, manual, "disk full"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			e := newDinnersEnv(t).withRecipes(t)
+			id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+			if _, err := e.st.Writer.ExecContext(t.Context(), tc.sabotage); err != nil {
+				t.Fatal(err)
+			}
+
+			rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", tc.fix)
+			if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+				t.Errorf("POST = %d %s, want 500 internal", rec.Code, rec.Body)
+			}
+			logs := e.logs.String()
+			if strings.Contains(logs, tc.leak) || !strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+				t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the database error", logs)
+			}
+		})
+	}
+}
+
+// TestPostGroundArchived: grounding an archived dinner by hand is a 409.
+func TestPostGroundArchived(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Family chili"}`)
+	if rec, _ := callDinners(t, e.h, http.MethodDelete, dinnersPath+"/"+id, ""); rec.Code != http.StatusOK {
+		t.Fatalf("DELETE = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground",
+		`{"manual":{"ingredients":["1 lb beef"],"minutes":240,"method":"crockpot"}}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "dinner_archived" {
+		t.Errorf("POST = %d %v, want 409 dinner_archived", rec.Code, body)
+	}
+}
+
+func TestPostGroundViaManual(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Family chili"}`)
+
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground",
+		`{"manual":{"ingredients":["1 lb beef","1 can beans"],"steps":["Brown.","Simmer."],"minutes":240,"method":"crockpot"}}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if d["grounding_status"] != "manual" || d["recipe_id"] == nil || d["photo_url"] != nil ||
+		d["method"] != "crockpot" || d["minutes_total"] != 240.0 || d["grounding_error"] != nil {
+		t.Errorf("dinner = %v", d)
+	}
+	var lines int
+	if err := e.st.Reader.QueryRow(`SELECT count(*) FROM recipe_ingredients WHERE recipe_id = ?`, d["recipe_id"]).Scan(&lines); err != nil {
+		t.Fatal(err)
+	}
+	if lines != 2 {
+		t.Errorf("stored %d ingredient lines, want 2", lines)
+	}
+}
+
+func TestPostGroundRejects(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Pad thai"}`)
+	path := dinnersPath + "/" + id + "/ground"
+
+	for _, tc := range []struct{ name, body, code string }{
+		{"empty", `{}`, "invalid_dinner"},
+		{"two kinds", `{"candidate_id":"https://a.example/x","recipe_url":"https://a.example/x"}`, "invalid_dinner"},
+		{"candidate not offered", `{"candidate_id":"c1"}`, "invalid_dinner"},
+		{"candidate a page URL", `{"candidate_id":"https://a.example/x"}`, "invalid_dinner"},
+		{"http link", `{"recipe_url":"http://a.example/x"}`, "invalid_dinner"},
+		{"null", `{"recipe_url":null}`, "invalid_request"},
+		{"unknown field", `{"url":"https://a.example/x"}`, "invalid_request"},
+		{"unknown manual field", `{"manual":{"ingredients":["x"],"minutes":5,"method":"oven","serves":4}}`, "invalid_request"},
+		{"manual without method", `{"manual":{"ingredients":["x"],"minutes":5}}`, "invalid_dinner"},
+		{"manual without ingredients", `{"manual":{"ingredients":[],"minutes":5,"method":"oven"}}`, "invalid_dinner"},
+		{"manual minutes too many", `{"manual":{"ingredients":["x"],"minutes":5000,"method":"oven"}}`, "invalid_dinner"},
+		{"not an object", `[]`, "invalid_request"},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPost, path, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code {
+			t.Errorf("%s: %d %v, want 400 %s", tc.name, rec.Code, body, tc.code)
+		}
+	}
+	if d := listedDinner(t, e.h, id); d["grounding_status"] != "pending" {
+		t.Errorf("dinner after rejected fixes = %v, want unchanged", d)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/nope/ground",
+		`{"manual":{"ingredients":["x"],"minutes":5,"method":"oven"}}`)
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown dinner = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestPostDinnerEnqueueFailureAnswersFailedDinner(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_jobs BEFORE INSERT ON jobs BEGIN SELECT RAISE(ABORT, 'no jobs'); END`); err != nil {
+		t.Fatal(err)
+	}
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Chicken curry"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	id, _ := created["id"].(string)
+	if id == "" || created["grounding_status"] != "failed" || created["grounding_error"] != "grounding_error" || created["grounding_job_id"] != nil {
+		t.Fatalf("created = %v, want its id, failed (grounding_error) and a null grounding_job_id", created)
+	}
+	if got := listedDinner(t, e.h, id); got["grounding_status"] != "failed" {
+		t.Errorf("listed = %v, want failed", got)
+	}
+}

internal/server/login_test.go

@@ -83,7 +83,7 @@ func newLoginRouter(t *testing.T, issuer string) http.Handler {
 		t.Fatal(err)
 	}
 	r, err := NewRouter(logger, "dev", trusted, flow, sessions, newTestSettings(t),
-		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/media_test.go

@@ -51,7 +51,7 @@ func newMediaRouter(t *testing.T) (r http.Handler, id, orphan string) {
 		t.Fatal(err)
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t),
 		photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/origin_test.go

@@ -45,7 +45,7 @@ func newOriginRouter(t *testing.T, logs io.Writer) http.Handler {
 	}
 	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(logs, nil)))
 	r, err := NewRouter(logger, "dev", trusted, probeAuth{}, stubSessions{}, newTestSettings(t),
-		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/recipesearch.go

@@ -0,0 +1,70 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+)
+
+// searchTestResponse is the POST /settings/recipe-search/test body.
+type searchTestResponse struct {
+	Query string `json:"query"`
+	Count int    `json:"count"`
+}
+
+func getRecipeSearchSettings(logger *slog.Logger, svc *recipes.SearchSettingsService) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		settings, err := svc.Get(r.Context())
+		if err != nil {
+			logger.ErrorContext(r.Context(), "get recipe search settings", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+// patchRecipeSearchSettings takes the Brave API key in api_key; the
+// response, like GET's, never holds it.
+func patchRecipeSearchSettings(logger *slog.Logger, svc *recipes.SearchSettingsService) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		patch, err := decodePatch[recipes.SearchSettingsPatch](http.MaxBytesReader(w, r.Body, maxSettingsBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		settings, err := svc.Update(r.Context(), patch)
+		var invalid *recipes.SearchSettingsError
+		if errors.As(err, &invalid) {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_settings", invalid.Error())
+			return
+		}
+		if err != nil {
+			logger.ErrorContext(r.Context(), "update recipe search settings", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+// postRecipeSearchTest searches for recipes.SearchTestQuery with the saved
+// settings. Recipe search not configured is 409; a search that fails is
+// 502 with the provider's error, which never holds the API key.
+func postRecipeSearchTest(logger *slog.Logger, svc *recipes.SearchSettingsService) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		count, err := svc.TestSearch(r.Context())
+		if errors.Is(err, recipes.ErrSearchNotConfigured) {
+			writeError(w, r, logger, http.StatusConflict, "not_configured", "recipe search is not configured")
+			return
+		}
+		if err != nil {
+			logger.WarnContext(r.Context(), "recipe search test failed", "error", err)
+			writeError(w, r, logger, http.StatusBadGateway, "search_failed", err.Error())
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, searchTestResponse{Query: recipes.SearchTestQuery, Count: count})
+	}
+}

internal/server/recipesearch_test.go

@@ -0,0 +1,124 @@
+package server
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+)
+
+const (
+	recipeSearchPath     = "/api/v1/settings/recipe-search"
+	recipeSearchTestPath = "/api/v1/settings/recipe-search/test"
+	testBraveKey         = "BSA-secret-brave-key-9f3c"
+)
+
+// newRecipeSearchRouter returns a router serving search.
+func newRecipeSearchRouter(t *testing.T, search *recipes.SearchSettingsService) http.Handler {
+	t.Helper()
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestDinners(t), newTestRunner(t),
+		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+func TestRecipeSearchSettingsAPI(t *testing.T) {
+	t.Parallel()
+	router := newRecipeSearchRouter(t, newTestSearch(t))
+	var bodies []string
+	call := func(method, target, body string) (*httptest.ResponseRecorder, map[string]any) {
+		t.Helper()
+		var r io.Reader
+		if body != "" {
+			r = strings.NewReader(body)
+		}
+		rec, decoded := serve(t, router, signedIn(method, target, r))
+		bodies = append(bodies, rec.Body.String())
+		return rec, decoded
+	}
+
+	rec, body := call(http.MethodGet, recipeSearchPath, "")
+	if def, ok := body["default_base_url"]; rec.Code != http.StatusOK || body["provider"] != nil || body["api_key_set"] != false || !ok || def != nil {
+		t.Errorf("GET unconfigured = %d %v", rec.Code, body)
+	}
+	rec, body = call(http.MethodPost, recipeSearchTestPath, "")
+	if rec.Code != http.StatusConflict || body["error"].(map[string]any)["code"] != "not_configured" {
+		t.Errorf("POST test unconfigured = %d %v", rec.Code, body)
+	}
+
+	for _, bad := range []string{
+		`{"provider":"google"}`,
+		`{"provider":"brave"}`,
+		`{"provider":"searxng","base_url":"not a url"}`,
+		`{"provider":"brave","api_key":null}`,
+		`{"provider":"brave","apikey":"x"}`,
+	} {
+		if rec, _ := call(http.MethodPatch, recipeSearchPath, bad); rec.Code != http.StatusBadRequest {
+			t.Errorf("PATCH %s = %d, want 400", bad, rec.Code)
+		}
+	}
+
+	rec, body = call(http.MethodPatch, recipeSearchPath, `{"provider":"brave","api_key":"`+testBraveKey+`"}`)
+	if rec.Code != http.StatusOK || body["provider"] != "brave" || body["api_key_set"] != true || body["api_key_last4"] != "9f3c" {
+		t.Errorf("PATCH Brave = %d %v", rec.Code, body)
+	}
+	if _, ok := body["api_key"]; ok {
+		t.Errorf("PATCH response has an api_key field: %v", body)
+	}
+	rec, body = call(http.MethodGet, recipeSearchPath, "")
+	if rec.Code != http.StatusOK || body["provider"] != "brave" || body["api_key_last4"] != "9f3c" {
+		t.Errorf("GET Brave = %d %v", rec.Code, body)
+	}
+
+	// SearXNG keeps the stored key; the test search goes to the instance.
+	searx := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`{"results":[{"url":"https://a.example/1"},{"url":"https://b.example/2"},{"url":"https://c.example/3"}]}`))
+	}))
+	t.Cleanup(searx.Close)
+	rec, body = call(http.MethodPatch, recipeSearchPath, `{"provider":"searxng","base_url":"`+searx.URL+`"}`)
+	if rec.Code != http.StatusOK || body["base_url"] != searx.URL || body["api_key_set"] != true {
+		t.Errorf("PATCH SearXNG = %d %v", rec.Code, body)
+	}
+	rec, body = call(http.MethodPost, recipeSearchTestPath, "")
+	if rec.Code != http.StatusOK || body["count"] != float64(3) || body["query"] != recipes.SearchTestQuery {
+		t.Errorf("POST test = %d %v, want count 3", rec.Code, body)
+	}
+
+	searx.Close()
+	rec, body = call(http.MethodPost, recipeSearchTestPath, "")
+	if rec.Code != http.StatusBadGateway || body["error"].(map[string]any)["code"] != "search_failed" {
+		t.Errorf("POST test against a stopped instance = %d %v, want 502 search_failed", rec.Code, body)
+	}
+
+	for _, b := range bodies {
+		if strings.Contains(b, testBraveKey) || strings.Contains(b, testBraveKey[:12]) {
+			t.Errorf("response holds the Brave key: %s", b)
+		}
+	}
+}
+
+func TestRecipeSearchSettingsNeedCSRF(t *testing.T) {
+	t.Parallel()
+	router := newRecipeSearchRouter(t, newTestSearch(t))
+	for _, method := range []string{http.MethodPatch, http.MethodPost} {
+		target := recipeSearchPath
+		if method == http.MethodPost {
+			target = recipeSearchTestPath
+		}
+		req := httptest.NewRequest(method, target, strings.NewReader(`{"provider":"brave","api_key":"`+testBraveKey+`"}`))
+		req.AddCookie(validSessionCookie)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		if rec.Code != http.StatusForbidden {
+			t.Errorf("%s %s without CSRF token = %d, want 403", method, target, rec.Code)
+		}
+	}
+}

internal/server/server.go

@@ -10,10 +10,13 @@ import (
 
 	"github.com/go-chi/chi/v5"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
 )
 
 // reservedPrefixes are owned by the API router and are never answered with the
@@ -29,15 +32,30 @@ type RouteMounter interface {
 // has its client address and scheme resolved, honouring forwarded headers
 // only from a peer in trusted (see resolveOrigin). version is reported by
 // GET /health; auth mounts the /auth routes; sessions guards /api/v1 and
-// /media; settings serves /api/v1/settings/household; runner serves
+// /media; settings serves /api/v1/settings/household; search serves
+// /api/v1/settings/recipe-search and its /test; ai serves
+// /api/v1/settings/ai, its /api-key, /verify, /models and /reset-prompt;
+// dinnerSvc serves GET and POST /api/v1/dinners, PATCH and DELETE
+// /api/v1/dinners/{id}, POST /api/v1/dinners/{id}/favorite, GET
+// /api/v1/dinners/{id}/recipe-candidates and POST /api/v1/dinners/{id}/ground;
+// runner serves
 // POST /api/v1/jobs and GET /api/v1/jobs/{id}; photos serves
 // GET /media/photos/{id}-{size}.jpg; assets is the web build
 // served for every other GET. /health, /auth and the web build are public.
 // Requests to /api/v1 other than GET also need the session's CSRF token in CSRFHeader.
-func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
+func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, dinnerSvc *dinners.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
 	if settings == nil {
 		return nil, errors.New("server: nil household settings service")
 	}
+	if search == nil {
+		return nil, errors.New("server: nil recipe search settings service")
+	}
+	if ai == nil {
+		return nil, errors.New("server: nil AI settings service")
+	}
+	if dinnerSvc == nil {
+		return nil, errors.New("server: nil dinners service")
+	}
 	if runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -72,6 +90,22 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	apiV1.Get("/me", me(logger))
 	apiV1.Get("/settings/household", getHouseholdSettings(logger, settings))
 	apiV1.Patch("/settings/household", patchHouseholdSettings(logger, settings))
+	apiV1.Get("/settings/recipe-search", getRecipeSearchSettings(logger, search))
+	apiV1.Patch("/settings/recipe-search", patchRecipeSearchSettings(logger, search))
+	apiV1.Post("/settings/recipe-search/test", postRecipeSearchTest(logger, search))
+	apiV1.Get("/settings/ai", getAISettings(logger, ai))
+	apiV1.Patch("/settings/ai", patchAISettings(logger, ai))
+	apiV1.Put("/settings/ai/api-key", putAIKey(logger, ai))
+	apiV1.Post("/settings/ai/verify", postAIVerify(logger, ai))
+	apiV1.Get("/settings/ai/models", getAIModels(logger, ai))
+	apiV1.Post("/settings/ai/reset-prompt", postAIResetPrompt(logger, ai))
+	apiV1.Get("/dinners", getDinners(logger, dinnerSvc))
+	apiV1.Post("/dinners", postDinner(logger, dinnerSvc))
+	apiV1.Patch("/dinners/{id}", patchDinner(logger, dinnerSvc))
+	apiV1.Delete("/dinners/{id}", deleteDinner(logger, dinnerSvc))
+	apiV1.Post("/dinners/{id}/favorite", postDinnerFavorite(logger, dinnerSvc))
+	apiV1.Get("/dinners/{id}/recipe-candidates", getDinnerCandidates(logger, dinnerSvc))
+	apiV1.Post("/dinners/{id}/ground", postDinnerGround(logger, dinnerSvc))
 	apiV1.Post("/jobs", postJob(logger, runner))
 	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	media.Get("/photos/{name}", getPhoto(logger, photos))

internal/server/server_test.go

@@ -2,6 +2,8 @@ package server
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/base64"
 	"encoding/json"
 	"io"
 	"log/slog"
@@ -14,9 +16,14 @@ import (
 
 	"github.com/go-chi/chi/v5"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
@@ -39,7 +46,7 @@ func newTestRouterWith(t *testing.T, version string, settings *household.Setting
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestDinners(t), runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -124,11 +131,85 @@ func newTestPhotos(t *testing.T) *recipes.PhotoCache {
 	return photos
 }
 
+// newTestSearch returns a recipe search settings service, with nothing
+// configured, over a migrated temp database and a random secret box.
+func newTestSearch(t *testing.T) *recipes.SearchSettingsService {
+	t.Helper()
+	search, err := recipes.NewSearchSettingsService(newTestStore(t), newTestBox(t), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return search
+}
+
+// newTestDinners returns a dinners service over a migrated temp database,
+// with its own unstarted job runner and a grounder that finds nothing.
+func newTestDinners(t *testing.T) *dinners.Service {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	svc, err := dinners.NewService(st, g, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
+// newTestBox returns a secret box under a random key.
+func newTestBox(t *testing.T) *secretbox.Box {
+	t.Helper()
+	key := make([]byte, secretbox.KeySize)
+	rand.Read(key)
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return box
+}
+
+// newTestAI returns an AI settings service over a migrated temp database
+// with the seed AI settings and a random secret box.
+func newTestAI(t *testing.T) *aisettings.Service {
+	t.Helper()
+	st := newTestStore(t)
+	if err := household.SeedAISettings(context.Background(), st); err != nil {
+		t.Fatal(err)
+	}
+	ai, err := aisettings.New(st, newTestBox(t), "https://mealquest.example")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return ai
+}
+
+func TestNewRouterRequiresAISettings(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil AI settings service")
+	}
+}
+
+func TestNewRouterRequiresSearchSettings(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil recipe search settings service")
+	}
+}
+
 func TestNewRouterRequiresPhotoFiles(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -137,16 +218,25 @@ func TestNewRouterRequiresSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
 
+func TestNewRouterRequiresDinners(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil dinners service")
+	}
+}
+
 func TestNewRouterRequiresJobRunner(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil job runner")
 	}
 }

internal/server/settings.go

@@ -9,13 +9,21 @@ import (
 	"log/slog"
 	"net/http"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 )
 
-// maxSettingsBody bounds a PATCH /settings/household request body.
+// maxSettingsBody bounds a PATCH /settings/household or
+// /settings/recipe-search, or PUT /settings/ai/api-key, request body.
 const maxSettingsBody = 16 << 10
 
+// maxAISettingsBody bounds a PATCH /settings/ai request body. It fits the
+// longest valid system prompt at 12 bytes of JSON per character (a
+// \u-escaped surrogate pair) on top of maxSettingsBody for the other
+// fields, so only aisettings.MaxSystemPromptChars limits the prompt.
+const maxAISettingsBody = maxSettingsBody + 12*aisettings.MaxSystemPromptChars
+
 // settingsPatch is the PATCH /settings/household body. Every field is
 // optional; unknown fields and null values are refused.
 type settingsPatch struct {
@@ -29,6 +37,9 @@ type settingsPatch struct {
 	SuggestionsTime  *string `json:"suggestions_time"`
 	ChatAutosendDow  *int    `json:"chat_autosend_dow"`
 	ChatAutosendTime *string `json:"chat_autosend_time"`
+	// OnboardingCompleted true sets onboarding_completed_at, which is
+	// itself read-only.
+	OnboardingCompleted *bool `json:"onboarding_completed"`
 }
 
 func getHouseholdSettings(logger *slog.Logger, svc *household.SettingsService) http.HandlerFunc {
@@ -52,7 +63,7 @@ func patchHouseholdSettings(logger *slog.Logger, svc *household.SettingsService)
 			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
 			return
 		}
-		patch, err := decodeSettingsPatch(http.MaxBytesReader(w, r.Body, maxSettingsBody))
+		patch, err := decodePatch[settingsPatch](http.MaxBytesReader(w, r.Body, maxSettingsBody))
 		if err != nil {
 			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
 			return
@@ -72,37 +83,37 @@ func patchHouseholdSettings(logger *slog.Logger, svc *household.SettingsService)
 	}
 }
 
-// decodeSettingsPatch reads a single JSON object, refusing unknown fields,
-// null values and trailing data.
-func decodeSettingsPatch(body io.Reader) (settingsPatch, error) {
+// decodePatch reads a single JSON object into a patch of type T, refusing
+// unknown fields, null values and trailing data.
+func decodePatch[T any](body io.Reader) (T, error) {
+	var patch T
 	data, err := io.ReadAll(body)
 	if err != nil {
 		var tooLarge *http.MaxBytesError
 		if errors.As(err, &tooLarge) {
-			return settingsPatch{}, fmt.Errorf("request body exceeds %d bytes", tooLarge.Limit)
+			return patch, fmt.Errorf("request body exceeds %d bytes", tooLarge.Limit)
 		}
-		return settingsPatch{}, errors.New("cannot read request body")
+		return patch, errors.New("cannot read request body")
 	}
 
 	var fields map[string]json.RawMessage
 	if err := json.Unmarshal(data, &fields); err != nil || fields == nil {
-		return settingsPatch{}, errors.New("request body must be a JSON object")
+		return patch, errors.New("request body must be a JSON object")
 	}
 	for name, raw := range fields {
 		if bytes.Equal(raw, []byte("null")) {
-			return settingsPatch{}, fmt.Errorf("%s: must not be null", name)
+			return patch, fmt.Errorf("%s: must not be null", name)
 		}
 	}
 
-	var patch settingsPatch
 	dec := json.NewDecoder(bytes.NewReader(data))
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&patch); err != nil {
 		var typeErr *json.UnmarshalTypeError
 		if errors.As(err, &typeErr) {
-			return settingsPatch{}, fmt.Errorf("%s: want a JSON %s", typeErr.Field, typeErr.Type)
+			return patch, fmt.Errorf("%s: want a JSON %s", typeErr.Field, typeErr.Type)
 		}
-		return settingsPatch{}, fmt.Errorf("invalid settings: %v", err)
+		return patch, fmt.Errorf("invalid request body: %v", err)
 	}
 	return patch, nil
 }
@@ -123,13 +134,18 @@ func writeJSON(w http.ResponseWriter, r *http.Request, logger *slog.Logger, stat
 
 // writeError responds with status and a non-retryable API error.
 func writeError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, status int, code, message string) {
-	body, err := json.Marshal(errorBody{Error: apiError{Code: code, Message: message}})
+	writeAPIError(w, r, logger, status, apiError{Code: code, Message: message})
+}
+
+// writeAPIError responds with status and e.
+func writeAPIError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, status int, e apiError) {
+	body, err := json.Marshal(errorBody{Error: e})
 	if err != nil {
 		panic(err) // string and bool fields cannot fail to marshal
 	}
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
 	if _, err := w.Write(body); err != nil {
-		logger.WarnContext(r.Context(), "write error response", "code", code, "error", err)
+		logger.WarnContext(r.Context(), "write error response", "code", e.Code, "error", err)
 	}
 }

internal/server/settings_test.go

@@ -3,6 +3,7 @@ package server
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"io"
 	"log/slog"
 	"net/http"
@@ -13,6 +14,7 @@ import (
 	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
@@ -115,6 +117,63 @@ func TestPatchHouseholdSettings(t *testing.T) {
 	}
 }
 
+// newOnboardingRouter returns a router whose settings store holds regulars
+// Regulars.
+func newOnboardingRouter(t *testing.T, regulars int) http.Handler {
+	t.Helper()
+	st := newTestStore(t)
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	for i := range regulars {
+		now := store.Now().String()
+		if _, err := db.New(st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+			ID: store.NewID(), Name: fmt.Sprintf("Dinner %d", i), NormalizedName: fmt.Sprintf("dinner %d", i),
+			Status: "regular", Origin: "regular", GroundingStatus: "pending", CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return newTestRouterWith(t, "dev", household.NewSettingsService(st), newTestRunner(t))
+}
+
+func TestPatchHouseholdSettingsCompletesOnboarding(t *testing.T) {
+	t.Parallel()
+
+	rec, body := serve(t, newOnboardingRouter(t, household.MinRegulars), signedIn(http.MethodPatch, settingsPath,
+		strings.NewReader(`{"onboarding_completed":true}`)))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body)
+	}
+	if at, ok := body["onboarding_completed_at"].(string); !ok || at != body["updated_at"] {
+		t.Errorf("onboarding_completed_at = %#v, want the update time %#v", body["onboarding_completed_at"], body["updated_at"])
+	}
+}
+
+// TestPatchHouseholdSettingsOnboardingNeedsRegulars: completing onboarding
+// with fewer than three Regulars is refused and leaves it incomplete.
+func TestPatchHouseholdSettingsOnboardingNeedsRegulars(t *testing.T) {
+	t.Parallel()
+
+	for regulars := range household.MinRegulars {
+		t.Run(fmt.Sprintf("%d Regulars", regulars), func(t *testing.T) {
+			t.Parallel()
+			router := newOnboardingRouter(t, regulars)
+			rec, _ := serve(t, router, signedIn(http.MethodPatch, settingsPath,
+				strings.NewReader(`{"onboarding_completed":true}`)))
+			if rec.Code != http.StatusBadRequest ||
+				!strings.Contains(rec.Body.String(), `"code":"invalid_settings"`) ||
+				!strings.Contains(rec.Body.String(), "onboarding_completed: add at least 3 Regulars first") {
+				t.Fatalf("PATCH = %d %s, want 400 invalid_settings on onboarding_completed", rec.Code, rec.Body)
+			}
+			_, body := serve(t, router, signedIn(http.MethodGet, settingsPath, nil))
+			if body["onboarding_completed_at"] != nil {
+				t.Errorf("onboarding_completed_at = %#v after a refused completion, want null", body["onboarding_completed_at"])
+			}
+		})
+	}
+}
+
 func TestPatchHouseholdSettingsRejected(t *testing.T) {
 	t.Parallel()
 
@@ -136,6 +195,8 @@ func TestPatchHouseholdSettingsRejected(t *testing.T) {
 		{"null value", `{"timezone":null}`, "invalid_request", "timezone"},
 		{"unknown field", `{"dinner":"17:30"}`, "invalid_request", "dinner"},
 		{"read-only field", `{"updated_by":"someone"}`, "invalid_request", "updated_by"},
+		{"read-only onboarding time", `{"onboarding_completed_at":"2026-10-06T12:00:00.000Z"}`, "invalid_request", "onboarding_completed_at"},
+		{"onboarding undone", `{"onboarding_completed":false}`, "invalid_settings", "onboarding_completed"},
 		{"not an object", `["timezone"]`, "invalid_request", "JSON object"},
 		{"null body", `null`, "invalid_request", "JSON object"},
 		{"trailing data", `{"dinner_time":"18:00"} {}`, "invalid_request", "JSON object"},
@@ -216,7 +277,7 @@ func TestHouseholdSettingsWithRealSession(t *testing.T) {
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	router, err := NewRouter(logger, "dev", nil, stubAuth{}, sessions, household.NewSettingsService(st),
-		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/store/migrate_test.go

@@ -175,8 +175,8 @@ func TestMigrateEmbeddedMigrations(t *testing.T) {
 	if err := Migrate(context.Background(), s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
 	}
 }
 
@@ -196,8 +196,8 @@ func TestMigrateBootstrapThenEmbeddedInitApplies(t *testing.T) {
 	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
 	}
 	if !tableExists(t, s, "dinners") {
 		t.Error("table from 0001_init was not created")

migrations/0007_recipe_grounding.sql

@@ -0,0 +1,18 @@
+-- 0007_recipe_grounding: a grounded recipe keeps what recipes.Ground
+-- returns, so a stored source_url is reused without fetching or normalizing
+-- it again: its cached photo, and normalize_recipe's method, difficulty and
+-- minutes_total (prep to table; total_minutes stays the page's own JSON-LD
+-- total). Nothing wrote recipes before Ground did, so the columns are added
+-- nullable rather than with a default no recipe has; Ground always sets
+-- photo_id, method and difficulty and refuses to reuse a row without them.
+--
+-- recipe_search_settings gains api_key_last4, the last four characters of
+-- the Brave API key, so the settings can show which key is stored without
+-- ever returning it.
+
+ALTER TABLE recipes ADD COLUMN photo_id TEXT REFERENCES photos (id);
+ALTER TABLE recipes ADD COLUMN method TEXT CHECK (method IN ('stovetop', 'oven', 'crockpot', 'grill', 'other'));
+ALTER TABLE recipes ADD COLUMN difficulty TEXT CHECK (difficulty IN ('easy', 'medium', 'hard'));
+ALTER TABLE recipes ADD COLUMN minutes_total INTEGER;
+
+ALTER TABLE recipe_search_settings ADD COLUMN api_key_last4 TEXT;

migrations/0008_dinner_recipe_url.sql

@@ -0,0 +1,5 @@
+-- 0008_dinner_recipe_url: a Regular added from a pasted recipe link keeps
+-- that link until grounding resolves it to a recipe (recipe_id). Nothing
+-- else records the link: recipes rows exist only for fetched pages.
+
+ALTER TABLE dinners ADD COLUMN recipe_url TEXT;

migrations/0009_dinner_grounding_error.sql

@@ -0,0 +1,7 @@
+-- 0009_dinner_grounding_error: a dinner whose grounding failed keeps why,
+-- as one of the reason codes package dinners defines (no_recipe_found,
+-- recipe_unusable, search_not_configured, search_failed, ai_failed,
+-- interrupted, grounding_error). It is NULL unless grounding_status is
+-- failed.
+
+ALTER TABLE dinners ADD COLUMN grounding_error TEXT;

migrations/0010_dinner_grounding_revision.sql

@@ -0,0 +1,7 @@
+-- 0010_dinner_grounding_revision: each ground_dinner job carries the
+-- dinner's grounding_revision when it was enqueued, and records its result
+-- only while the dinner still has that revision. Renaming a pending dinner
+-- raises the revision before enqueuing the job for the new name, so an
+-- earlier job — queued or running — can no longer write the dinner.
+
+ALTER TABLE dinners ADD COLUMN grounding_revision INTEGER NOT NULL DEFAULT 0;

migrations/0011_ground_dinner_job_revision.sql

@@ -0,0 +1,11 @@
+-- 0011_ground_dinner_job_revision: every dinner starts at grounding
+-- revision 0 (0010), so a ground_dinner job enqueued before 0010, whose
+-- payload has only dinner_id, is for revision 0. Recording it lets the boot
+-- cleanup, which matches a pending dinner to its job by revision, see a job
+-- still queued for its dinner. This is a migration of its own, not part of
+-- 0010, so it also runs on a database that has already applied 0010.
+
+UPDATE jobs
+SET payload = json_set(payload, '$.revision', 0)
+WHERE kind = 'ground_dinner'
+	AND json_type(payload, '$.revision') IS NULL;

migrations/queries/dinners.sql

@@ -1,12 +1,12 @@
 -- name: CreateDinner :one
 INSERT INTO dinners (
 	id, name, normalized_name, status, origin, method, minutes_total,
-	difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status,
-	updated_by, created_at, updated_at
+	difficulty, cuisine, is_favorite, recipe_id, recipe_url, photo_id,
+	grounding_status, updated_by, created_at, updated_at
 ) VALUES (
 	?, ?, ?, ?, ?, ?, ?,
 	?, ?, ?, ?, ?, ?,
-	?, ?, ?
+	?, ?, ?, ?
 )
 RETURNING *;
 
@@ -19,6 +19,20 @@ SELECT * FROM dinners
 WHERE status = ?
 ORDER BY normalized_name, id;
 
+-- name: CountRegularDinners :one
+-- How many Regulars the household has; archived dinners are not counted.
+SELECT COUNT(*) FROM dinners
+WHERE status = 'regular';
+
+-- name: ListUnarchivedDinners :many
+-- Every dinner a new or renamed dinner must not repeat, with the
+-- source_url of the recipe it is grounded in (NULL while it has none).
+SELECT sqlc.embed(dinners), recipes.source_url AS recipe_source_url
+FROM dinners
+LEFT JOIN recipes ON recipes.id = dinners.recipe_id
+WHERE dinners.status <> 'archived'
+ORDER BY dinners.id;
+
 -- name: UpdateDinner :one
 -- An unknown id returns sql.ErrNoRows.
 UPDATE dinners
@@ -31,8 +45,10 @@ SET name = ?,
 	difficulty = ?,
 	cuisine = ?,
 	recipe_id = ?,
+	recipe_url = ?,
 	photo_id = ?,
 	grounding_status = ?,
+	grounding_revision = ?,
 	updated_by = ?,
 	updated_at = ?
 WHERE id = ?
@@ -55,3 +71,100 @@ SET is_favorite = ?,
 	updated_at = ?
 WHERE id = ?
 RETURNING *;
+
+-- name: ToggleDinnerFavorite :one
+-- An unknown id returns sql.ErrNoRows.
+UPDATE dinners
+SET is_favorite = 1 - is_favorite,
+	updated_by = ?,
+	updated_at = ?
+WHERE id = ?
+RETURNING *;
+
+-- name: GroundDinner :one
+-- Records a dinner's grounding by hand (grounded or manual) and clears any
+-- grounding_error and pasted recipe_url: the recipe chosen replaces the
+-- link. It writes only an unarchived dinner still as it was observed
+-- before grounding (same name, normalized_name, grounding_status,
+-- grounding_revision and recipe_id), so a dinner renamed, archived or
+-- grounded some other way meanwhile is left as it is. That dinner, or an
+-- unknown id, returns sql.ErrNoRows. A method, minutes_total or difficulty
+-- no longer as observed is kept: a member edited it while it was grounding.
+UPDATE dinners
+SET recipe_id = sqlc.arg(recipe_id),
+	recipe_url = NULL,
+	photo_id = sqlc.arg(photo_id),
+	method = CASE WHEN method IS sqlc.narg(observed_method)
+		THEN sqlc.arg(method) ELSE method END,
+	minutes_total = CASE WHEN minutes_total IS sqlc.narg(observed_minutes_total)
+		THEN sqlc.arg(minutes_total) ELSE minutes_total END,
+	difficulty = CASE WHEN difficulty IS sqlc.narg(observed_difficulty)
+		THEN sqlc.arg(difficulty) ELSE difficulty END,
+	grounding_status = sqlc.arg(grounding_status),
+	grounding_error = NULL,
+	updated_by = sqlc.arg(updated_by),
+	updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id)
+	AND status <> 'archived'
+	AND name = sqlc.arg(observed_name)
+	AND normalized_name = sqlc.arg(observed_normalized_name)
+	AND grounding_status = sqlc.arg(observed_grounding_status)
+	AND grounding_revision = sqlc.arg(observed_grounding_revision)
+	AND recipe_id IS sqlc.narg(observed_recipe_id)
+RETURNING *;
+
+-- name: GroundPendingDinner :execrows
+-- Records the background grounding of an unarchived dinner still pending at
+-- the grounding_revision it was grounded for; a dinner grounded some other
+-- way, renamed or archived meanwhile is left as it is (0 rows). A method,
+-- minutes_total or difficulty already set is kept: a pending dinner has
+-- them only when a member edited them while it was grounding. Like
+-- GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
+UPDATE dinners
+SET recipe_id = sqlc.arg(recipe_id),
+	recipe_url = NULL,
+	photo_id = sqlc.arg(photo_id),
+	method = COALESCE(method, sqlc.arg(method)),
+	minutes_total = COALESCE(minutes_total, sqlc.arg(minutes_total)),
+	difficulty = COALESCE(difficulty, sqlc.arg(difficulty)),
+	grounding_status = 'grounded',
+	grounding_error = NULL,
+	updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id)
+	AND status <> 'archived'
+	AND grounding_status = 'pending'
+	AND grounding_revision = sqlc.arg(grounding_revision);
+
+-- name: FailPendingDinnerGrounding :execrows
+-- Records why the background grounding of an unarchived dinner still
+-- pending at the grounding_revision it was grounded for failed; a dinner
+-- grounded some other way, renamed or archived meanwhile is left as it is
+-- (0 rows).
+UPDATE dinners
+SET grounding_status = 'failed',
+	grounding_error = ?,
+	updated_at = ?
+WHERE id = ?
+	AND status <> 'archived'
+	AND grounding_status = 'pending'
+	AND grounding_revision = ?;
+
+-- name: FailOrphanedPendingDinnerGroundings :execrows
+-- Fails every unarchived dinner still pending whose grounding job for its
+-- current grounding_revision is no longer queued or running: the process
+-- stopped before the job, or before its handler recorded a result. An
+-- archived dinner is left as it is; archiving stopped its grounding. Run at
+-- boot, after the job runner fails the jobs a previous process left running.
+UPDATE dinners
+SET grounding_status = 'failed',
+	grounding_error = sqlc.arg(grounding_error),
+	updated_at = sqlc.arg(updated_at)
+WHERE grounding_status = 'pending'
+	AND status <> 'archived'
+	AND NOT EXISTS (
+		SELECT 1 FROM jobs
+		WHERE jobs.kind = sqlc.arg(kind)
+			AND jobs.status IN ('queued', 'running')
+			AND json_extract(jobs.payload, '$.dinner_id') = dinners.id
+			AND json_extract(jobs.payload, '$.revision') = dinners.grounding_revision
+	);

migrations/queries/recipes.sql

@@ -5,10 +5,12 @@
 -- DeleteRecipeIngredients/DeleteRecipeSteps then the Create queries.
 INSERT INTO recipes (
 	id, source_url, site_name, title, total_minutes, prep_minutes,
-	cook_minutes, yield, raw_jsonld, fetched_at, created_at, updated_at
+	cook_minutes, yield, raw_jsonld, photo_id, method, difficulty,
+	minutes_total, fetched_at, created_at, updated_at
 ) VALUES (
 	?, ?, ?, ?, ?, ?,
-	?, ?, ?, ?, ?, ?
+	?, ?, ?, ?, ?, ?,
+	?, ?, ?, ?
 )
 ON CONFLICT (source_url) DO UPDATE SET
 	site_name = excluded.site_name,
@@ -18,6 +20,10 @@ ON CONFLICT (source_url) DO UPDATE SET
 	cook_minutes = excluded.cook_minutes,
 	yield = excluded.yield,
 	raw_jsonld = excluded.raw_jsonld,
+	photo_id = excluded.photo_id,
+	method = excluded.method,
+	difficulty = excluded.difficulty,
+	minutes_total = excluded.minutes_total,
 	fetched_at = excluded.fetched_at,
 	updated_at = excluded.updated_at
 RETURNING *;
@@ -63,3 +69,15 @@ ORDER BY position, id;
 -- name: DeleteRecipeSteps :exec
 DELETE FROM recipe_steps
 WHERE recipe_id = ?;
+
+-- name: CreateManualRecipe :one
+-- A recipe the household typed in. Its source_url is a mealquest:manual:
+-- URN rather than a page, so it never matches a fetched page.
+INSERT INTO recipes (
+	id, source_url, title, total_minutes, raw_jsonld, method,
+	minutes_total, fetched_at, created_at, updated_at
+) VALUES (
+	?, ?, ?, ?, ?, ?,
+	?, ?, ?, ?
+)
+RETURNING *;

migrations/queries/settings.sql

@@ -70,14 +70,15 @@ WHERE id = 1;
 -- Creates the single row (id 1) or replaces every column except id and
 -- created_at.
 INSERT INTO recipe_search_settings (
-	id, provider, base_url, api_key_ct, created_at, updated_at
+	id, provider, base_url, api_key_ct, api_key_last4, created_at, updated_at
 ) VALUES (
-	1, ?, ?, ?, ?, ?
+	1, ?, ?, ?, ?, ?, ?
 )
 ON CONFLICT (id) DO UPDATE SET
 	provider = excluded.provider,
 	base_url = excluded.base_url,
 	api_key_ct = excluded.api_key_ct,
+	api_key_last4 = excluded.api_key_last4,
 	updated_at = excluded.updated_at
 RETURNING *;
 

web/index.html

@@ -3,6 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#5a358c" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <title>MealQuest</title>
   </head>
   <body>

web/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "MealQuest",
+  "short_name": "MealQuest",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "theme_color": "#5a358c",
+  "background_color": "#f9f6f1",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    {
+      "src": "/icons/icon-maskable-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

web/package.json

@@ -5,9 +5,9 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "npm run lint:colors && tsc --noEmit && vite build && npm run check:dist-fonts",
+    "build": "npm run lint:colors && npm run typecheck && vite build && npm run check:dist-fonts",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json",
     "test": "npm run lint:colors && vitest run",
     "lint:colors": "node scripts/lint-colors.mjs",
     "check:dist-fonts": "node scripts/check-dist-fonts.mjs"
@@ -29,6 +29,7 @@
     "jsdom": "^30.1.1",
     "typescript": "^7.0.2",
     "vite": "^8.3.2",
+    "vite-plugin-pwa": "^2.0.0",
     "vitest": "^5.0.3"
   }
 }

web/scripts/generate-icons/main.go

@@ -0,0 +1,186 @@
+// Command generate-icons writes the PWA icons in web/public from the
+// MealQuest logo. Run it from the repository root:
+//
+//	go run ./web/scripts/generate-icons
+//
+// The logo fills the regular icons edge to edge. The maskable icon shrinks it
+// onto the colour of its own parchment, so the banner stays inside the
+// circular safe zone (radius 40% of the icon) that launchers may crop to.
+package main
+
+import (
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"math"
+	"os"
+	"path/filepath"
+	"slices"
+
+	"golang.org/x/image/draw"
+)
+
+const (
+	source        = "design/logos/logo_v1_2Oct2026.jpg"
+	public        = "web/public"
+	maskableScale = 0.66
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, "generate-icons:", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	logo, err := load(source)
+	if err != nil {
+		return err
+	}
+	if b := logo.Bounds(); b.Dx() != b.Dy() {
+		return fmt.Errorf("%s is %dx%d; the logo must be square", source, b.Dx(), b.Dy())
+	}
+	outputs := []struct {
+		path  string
+		image *image.RGBA
+	}{
+		{"icons/icon-192.png", resized(logo, 192)},
+		{"icons/icon-512.png", resized(logo, 512)},
+		{"icons/icon-maskable-512.png", maskable(logo, 512)},
+		{"apple-touch-icon.png", resized(logo, 180)},
+	}
+	for _, out := range outputs {
+		path := filepath.Join(public, out.path)
+		if err := save(path, out.image); err != nil {
+			return err
+		}
+		fmt.Printf("wrote %s (%dx%d)\n", path, out.image.Rect.Dx(), out.image.Rect.Dy())
+	}
+	return nil
+}
+
+// load decodes the logo. The file is a PNG despite its .jpg name, so the
+// format is sniffed rather than taken from the extension.
+func load(path string) (image.Image, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	img, _, err := image.Decode(f)
+	if err != nil {
+		return nil, fmt.Errorf("decode %s: %w", path, err)
+	}
+	return img, nil
+}
+
+func save(path string, img image.Image) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	enc := png.Encoder{CompressionLevel: png.BestCompression}
+	if err := enc.Encode(f, img); err != nil {
+		f.Close()
+		return fmt.Errorf("encode %s: %w", path, err)
+	}
+	return f.Close()
+}
+
+func resized(logo image.Image, size int) *image.RGBA {
+	dst := image.NewRGBA(image.Rect(0, 0, size, size))
+	draw.CatmullRom.Scale(dst, dst.Rect, logo, logo.Bounds(), draw.Src, nil)
+	return dst
+}
+
+func maskable(logo image.Image, size int) *image.RGBA {
+	// The padding is the median colour of the logo's top edge, which is bare
+	// parchment; a feathered edge hides the seam.
+	b := logo.Bounds()
+	canvas := image.NewRGBA(image.Rect(0, 0, size, size))
+	draw.Draw(canvas, canvas.Rect, image.NewUniform(medianColour(logo, image.Rect(b.Min.X, b.Min.Y, b.Max.X, b.Min.Y+b.Dy()/40))), image.Point{}, draw.Src)
+	inner := int(math.Round(float64(size) * maskableScale))
+	offset := (size - inner) / 2
+	margin := inner / 24
+	at := image.Rect(offset, offset, offset+inner, offset+inner)
+	draw.DrawMask(canvas, at, resized(logo, inner), image.Point{}, feather(inner, margin), image.Point{}, draw.Over)
+	return canvas
+}
+
+// medianColour is the per-channel median of the pixels in r.
+func medianColour(img image.Image, r image.Rectangle) color.RGBA {
+	var channels [3][]uint8
+	for y := r.Min.Y; y < r.Max.Y; y++ {
+		for x := r.Min.X; x < r.Max.X; x++ {
+			c := color.RGBAModel.Convert(img.At(x, y)).(color.RGBA)
+			channels[0] = append(channels[0], c.R)
+			channels[1] = append(channels[1], c.G)
+			channels[2] = append(channels[2], c.B)
+		}
+	}
+	var median [3]uint8
+	for i, values := range channels {
+		slices.Sort(values)
+		median[i] = values[len(values)/2]
+	}
+	return color.RGBA{R: median[0], G: median[1], B: median[2], A: 0xff}
+}
+
+// feather is an opaque square inset by margin on a size×size mask, its edge
+// softened by a Gaussian blur with a standard deviation of margin/2.
+func feather(size, margin int) *image.Alpha {
+	values := make([]float64, size*size)
+	for y := margin; y <= size-margin && y < size; y++ {
+		for x := margin; x <= size-margin && x < size; x++ {
+			values[y*size+x] = 255
+		}
+	}
+	kernel := gaussian(float64(margin) / 2)
+	values = blur(values, size, kernel, 1, size)
+	values = blur(values, size, kernel, size, 1)
+	mask := image.NewAlpha(image.Rect(0, 0, size, size))
+	for i, v := range values {
+		mask.Pix[i] = uint8(math.Round(min(max(v, 0), 255)))
+	}
+	return mask
+}
+
+// gaussian is a normalised kernel reaching three standard deviations.
+func gaussian(sigma float64) []float64 {
+	radius := int(math.Ceil(3 * sigma))
+	kernel := make([]float64, 2*radius+1)
+	var sum float64
+	for i := range kernel {
+		d := float64(i - radius)
+		kernel[i] = math.Exp(-d * d / (2 * sigma * sigma))
+		sum += kernel[i]
+	}
+	for i := range kernel {
+		kernel[i] /= sum
+	}
+	return kernel
+}
+
+// blur convolves each line of a size×size grid with kernel: step is the
+// distance between neighbours along a line and stride between lines. Samples
+// beyond the edge repeat the edge.
+func blur(values []float64, size int, kernel []float64, step, stride int) []float64 {
+	radius := len(kernel) / 2
+	out := make([]float64, len(values))
+	for line := range size {
+		for i := range size {
+			var v float64
+			for k, w := range kernel {
+				j := min(max(i+k-radius, 0), size-1)
+				v += w * values[line*stride+j*step]
+			}
+			out[line*stride+i*step] = v
+		}
+	}
+	return out
+}

web/src/App.test.tsx

@@ -1,23 +1,46 @@
-import { render, screen } from '@testing-library/react'
-import { MemoryRouter } from 'react-router'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { createApiClient } from './api/index.ts'
+import { act, cleanup, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createApiClient, createVerifiedSession } from './api/index.ts'
+import { createNetworkStatus } from './pwa/networkStatus.ts'
 import { mockViewport } from './test/matchMedia.ts'
-import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch } from './test/fetchStub.ts'
+import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch, stubFetchByPath } from './test/fetchStub.ts'
 import App, { routes } from './App.tsx'
+import { AI_SETTINGS, HOUSEHOLD_SETTINGS, RECIPE_SEARCH_SETTINGS, SETTINGS_API } from './test/ApiProviders.tsx'
+import { InDataRouter } from './test/dataRouter.tsx'
+import { dinnerBody } from './test/dinners.ts'
 
 afterEach(() => {
   Reflect.deleteProperty(window, 'matchMedia')
+  vi.restoreAllMocks()
   vi.unstubAllGlobals()
 })
 
 function renderAt(path: string, location = fakeLocation(path)) {
-  render(
-    <MemoryRouter initialEntries={[path]}>
-      <App api={createApiClient(location)} />
-    </MemoryRouter>,
+  return { location, ...renderAppAt(path, location) }
+}
+
+function renderAppAt(path: string, location = fakeLocation(path)) {
+  return render(
+    <InDataRouter path={path}>
+      <App api={createApiClient(location, createNetworkStatus(window), createVerifiedSession(localStorage))} serviceWorker={undefined} />
+    </InDataRouter>,
   )
-  return location
+}
+
+// The routes that render a built screen rather than a placeholder page.
+const SCREENS = {
+  '/onboarding': true,
+  '/settings': true,
+  '/settings/ai': true,
+  '/settings/household': true,
+  '/settings/regulars': true,
+}
+
+// SIGNED_IN answers what every route reads first: the session, then the
+// household settings, onboarding finished.
+const SIGNED_IN = {
+  '/api/v1/me': () => jsonResponse(200, ME),
+  '/api/v1/settings/household': () => jsonResponse(200, HOUSEHOLD_SETTINGS),
 }
 
 describe('App routes', () => {
@@ -41,23 +64,113 @@ describe('App routes', () => {
     ])
   })
 
-  it.each(routes.map(({ path, title }) => [path.replace(':id', 'abc123'), title]))(
+  it.each(routes.filter(({ path }) => !Object.hasOwn(SCREENS, path)).map(({ path, title }) => [path.replace(':id', 'abc123'), title]))(
     '%s renders its placeholder page inside the shell',
     async (path, title) => {
       mockViewport(390)
-      stubFetch(jsonResponse(200, ME))
+      stubFetchByPath(SIGNED_IN)
       renderAt(path)
       const heading = await screen.findByRole('heading', { level: 1, name: title })
       expect(screen.getByRole('main')).toContainElement(heading)
       expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
     },
   )
+
+  it('/settings renders the settings home inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath({
+      '/api/v1/me': () => jsonResponse(200, ME),
+      ...SETTINGS_API,
+    })
+    renderAt('/settings')
+    const heading = await screen.findByRole('heading', { level: 1, name: 'Settings' })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByText('Anthropic · Claude Sonnet')).toBeInTheDocument()
+  })
+
+  it('/settings/ai renders the AI assistant screen inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath({
+      ...SIGNED_IN,
+      '/api/v1/settings/ai': () => jsonResponse(200, AI_SETTINGS),
+      '/api/v1/settings/ai/models': () => jsonResponse(200, { models: [] }),
+      '/api/v1/settings/recipe-search': () => jsonResponse(200, RECIPE_SEARCH_SETTINGS),
+    })
+    renderAt('/settings/ai')
+    const heading = await screen.findByRole('heading', { level: 1, name: 'AI assistant' })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByText('••••••••3f9a')).toBeInTheDocument()
+  })
+
+  it('/settings/household renders the household settings screen inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath(SIGNED_IN)
+    renderAt('/settings/household')
+    const heading = await screen.findByRole('heading', { level: 1, name: 'Household' })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByLabelText('Dinner time')).toHaveValue('17:30')
+  })
+
+  it('/settings/regulars renders the Regular dinners screen inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath({
+      ...SIGNED_IN,
+      '/api/v1/dinners?status=regular': () => jsonResponse(200, { dinners: [dinnerBody('d1', 'Beef tacos')] }),
+    })
+    renderAt('/settings/regulars')
+    const heading = await screen.findByRole('heading', { level: 1, name: 'Regular dinners' })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByText('Beef tacos')).toBeInTheDocument()
+  })
+})
+
+describe('App first-run redirect', () => {
+  const FIRST_RUN = {
+    '/api/v1/me': () => jsonResponse(200, ME),
+    '/api/v1/settings/household': () => jsonResponse(200, { ...HOUSEHOLD_SETTINGS, onboarding_completed_at: null }),
+  }
+
+  it.each(routes.filter(({ path }) => path !== '/onboarding').map(({ path }) => path.replace(':id', 'abc123')))(
+    '%s redirects to /onboarding while onboarding is not finished',
+    async (path) => {
+      mockViewport(390)
+      stubFetchByPath(FIRST_RUN)
+      renderAt(path)
+      expect(await screen.findByRole('heading', { level: 1, name: 'Welcome to MealQuest' })).toBeInTheDocument()
+      expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+    },
+  )
+
+  it('stays on an onboarding step', async () => {
+    mockViewport(390)
+    stubFetchByPath({ ...FIRST_RUN, '/api/v1/dinners?status=regular': () => jsonResponse(200, { dinners: [] }) })
+    renderAt('/onboarding/regulars')
+    expect(await screen.findByRole('heading', { level: 1, name: "What's on your usual rotation?" })).toBeInTheDocument()
+  })
+
+  it('opens the routes once onboarding is finished', async () => {
+    mockViewport(390)
+    stubFetchByPath(SIGNED_IN)
+    renderAt('/plan')
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+  })
+
+  it('reports a household settings failure with a retry instead of rendering the routes', async () => {
+    mockViewport(390)
+    stubFetch(jsonResponse(200, ME), errorResponse(500, 'internal'), jsonResponse(200, HOUSEHOLD_SETTINGS))
+    renderAt('/plan')
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: internal message')
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+    screen.getByRole('button', { name: 'Retry' }).click()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+  })
 })
 
 describe('App bootstrap', () => {
   it('shows the skeleton until /me loads, then the routes', async () => {
     mockViewport(390)
-    const fetchMock = stubFetch(jsonResponse(200, ME))
+    const fetchMock = stubFetch(jsonResponse(200, ME), jsonResponse(200, HOUSEHOLD_SETTINGS))
     renderAt('/plan')
 
     expect(screen.getByRole('main', { name: 'Loading MealQuest' })).toHaveAttribute('aria-busy', 'true')
@@ -70,7 +183,7 @@ describe('App bootstrap', () => {
 
   it('sends a signed-out visitor to sign-in and never renders the routes', async () => {
     const fetchMock = stubFetch(errorResponse(401, 'unauthenticated'))
-    const location = renderAt('/discover', fakeLocation('/discover', '?swipe=1'))
+    const { location } = renderAt('/discover', fakeLocation('/discover', '?swipe=1'))
 
     await vi.waitFor(() => expect(location.assign).toHaveBeenCalledWith('/auth/login?return=%2Fdiscover%3Fswipe%3D1'))
     expect(fetchMock).toHaveBeenCalledTimes(1)
@@ -80,7 +193,7 @@ describe('App bootstrap', () => {
 
   it('shows the not-in-this-household screen on a 403', async () => {
     const fetchMock = stubFetch(errorResponse(403, 'forbidden'))
-    const location = renderAt('/')
+    const { location } = renderAt('/')
 
     expect(await screen.findByText(/not in this household/)).toBeInTheDocument()
     expect(screen.getByRole('heading', { name: 'Not in this household' })).toBeInTheDocument()
@@ -91,7 +204,7 @@ describe('App bootstrap', () => {
 
   it('reports a /me failure with a retry instead of rendering the routes', async () => {
     mockViewport(390)
-    stubFetch(errorResponse(500, 'internal'), jsonResponse(200, ME))
+    stubFetch(errorResponse(500, 'internal'), jsonResponse(200, ME), jsonResponse(200, HOUSEHOLD_SETTINGS))
     renderAt('/')
 
     expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: internal message')
@@ -99,3 +212,130 @@ describe('App bootstrap', () => {
     expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
   })
 })
+
+describe('App offline bootstrap', () => {
+  let onLine: boolean
+
+  function goOffline() {
+    onLine = false
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+  }
+
+  // visitOnline is an earlier online visit on this device: /me answers with a
+  // member, then the app is closed.
+  async function visitOnline() {
+    stubFetchByPath(SIGNED_IN)
+    const { unmount } = renderAt('/')
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    unmount()
+  }
+
+  beforeEach(() => {
+    mockViewport(390)
+    onLine = true
+    vi.spyOn(navigator, 'onLine', 'get').mockImplementation(() => onLine)
+  })
+
+  // A test that emits an offline event leaves TanStack Query's online
+  // manager, shared by every test, offline until an online event.
+  afterEach(() => {
+    cleanup()
+    window.dispatchEvent(new Event('online'))
+  })
+
+  it.each([
+    ['/plan', 'Plan'],
+    ['/dinner/01J9ZK', 'Dinner'],
+  ])('an offline reload of %s after an online visit opens the saved page', async (path, title) => {
+    await visitOnline()
+    goOffline()
+    renderAt(path)
+
+    expect(await screen.findByRole('heading', { level: 1, name: title })).toBeInTheDocument()
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+    expect(screen.getByRole('status')).toHaveTextContent('Offline — showing saved data')
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('opens the saved page when the browser has emitted an offline event', async () => {
+    await visitOnline()
+    // /me is still loading, with the app mounted, when the browser emits
+    // its offline event; only then does /me fail.
+    let failMe!: () => void
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<typeof fetch>().mockImplementationOnce(
+        () => new Promise((_, reject) => (failMe = () => reject(new TypeError('Failed to fetch')))),
+      ).mockRejectedValue(new TypeError('Failed to fetch')),
+    )
+    renderAt('/plan')
+    await vi.waitFor(() => expect(failMe).toBeDefined())
+    onLine = false
+    act(() => {
+      window.dispatchEvent(new Event('offline'))
+    })
+    act(() => failMe())
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(screen.queryByRole('main', { name: 'Loading MealQuest' })).not.toBeInTheDocument()
+    expect(screen.getByRole('status')).toHaveTextContent('Offline — showing saved data')
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('opens the saved pages when the server is unreachable but the browser reports online', async () => {
+    await visitOnline()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    renderAt('/plan')
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(screen.getByRole('status')).toHaveTextContent('Offline — showing saved data')
+  })
+
+  it('reports the failure offline when this device never verified a session', async () => {
+    goOffline()
+    renderAt('/plan')
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: Failed to fetch')
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+  })
+
+  it('reports the failure offline after the session was refused', async () => {
+    await visitOnline()
+    stubFetch(errorResponse(401, 'unauthenticated'))
+    const { location, unmount } = renderAt('/plan')
+    await vi.waitFor(() => expect(location.assign).toHaveBeenCalled())
+    unmount()
+
+    goOffline()
+    renderAt('/plan')
+    expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: Failed to fetch')
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+  })
+
+  it('loads /me again on reconnect and refuses writes until it has', async () => {
+    await visitOnline()
+    goOffline()
+    const api = createApiClient(fakeLocation('/plan'), createNetworkStatus(window), createVerifiedSession(localStorage))
+    render(
+      <InDataRouter path="/plan">
+        <App api={api} serviceWorker={undefined} />
+      </InDataRouter>,
+    )
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    await expect(api.apiFetch('/api/v1/plans', { method: 'POST', body: {} })).rejects.toThrow(/no CSRF token/)
+
+    const fetchMock = stubFetchByPath(SIGNED_IN)
+    onLine = true
+    act(() => {
+      window.dispatchEvent(new Event('online'))
+    })
+    await vi.waitFor(() =>
+      expect(fetchMock.mock.calls.map(([input]) => String(input)).sort()).toEqual([
+        '/api/v1/me',
+        '/api/v1/settings/household',
+      ]),
+    )
+    await vi.waitFor(() => expect(screen.queryByRole('status')).toBeNull())
+    expect(screen.getByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+  })
+})

web/src/App.tsx

@@ -1,9 +1,17 @@
-import { useState } from 'react'
+import { useState, type ReactNode } from 'react'
 import { QueryClientProvider } from '@tanstack/react-query'
 import { Route, Routes } from 'react-router'
 import { ApiProvider, createQueryClient, type ApiClient } from './api/index.ts'
 import { AuthBootstrap } from './AuthBootstrap.tsx'
+import { ONBOARDING_PATH, OnboardingGate } from './onboarding/OnboardingGate.tsx'
+import { OnboardingPage } from './onboarding/OnboardingPage.tsx'
 import { PlaceholderPage } from './pages/PlaceholderPage.tsx'
+import { OfflinePill } from './pwa/OfflinePill.tsx'
+import { UpdatePrompt, type UpdateContainer } from './pwa/UpdatePrompt.tsx'
+import { AISettingsPage } from './settings/AISettingsPage.tsx'
+import { HouseholdSettingsPage } from './settings/HouseholdSettingsPage.tsx'
+import { RegularsSettingsPage } from './settings/RegularsSettingsPage.tsx'
+import { SettingsPage } from './settings/SettingsPage.tsx'
 import { AppShell } from './shell/AppShell.tsx'
 
 // Every route the app serves, with the heading its placeholder page shows.
@@ -25,14 +33,29 @@ export const routes = [
   { path: '/settings/calendar', title: 'Calendar' },
 ] as const
 
+// The screens built so far; every other route shows its placeholder page.
+const screens: Partial<Record<(typeof routes)[number]['path'], ReactNode>> = {
+  '/settings': <SettingsPage />,
+  '/settings/ai': <AISettingsPage />,
+  '/settings/household': <HouseholdSettingsPage />,
+  '/settings/regulars': <RegularsSettingsPage />,
+}
+
 // AppRoutes is the shell and its pages, shown once /api/v1/me has loaded.
+// Onboarding is a full screen of its own, outside the shell; until it is
+// finished, OnboardingGate sends every other route to it.
 export function AppRoutes() {
   return (
     <Routes>
-      <Route element={<AppShell />}>
-        {routes.map(({ path, title }) => (
-          <Route key={path} path={path} element={<PlaceholderPage title={title} />} />
-        ))}
+      <Route element={<OnboardingGate />}>
+        <Route path={`${ONBOARDING_PATH}/*`} element={<OnboardingPage />} />
+        <Route element={<AppShell />}>
+          {routes
+            .filter(({ path }) => path !== ONBOARDING_PATH)
+            .map(({ path, title }) => (
+              <Route key={path} path={path} element={screens[path] ?? <PlaceholderPage title={title} />} />
+            ))}
+        </Route>
       </Route>
     </Routes>
   )
@@ -40,11 +63,18 @@ export function AppRoutes() {
 
 export type AppProps = {
   api: ApiClient
+  // navigator.serviceWorker, or undefined where there is none (and in tests).
+  serviceWorker: UpdateContainer | undefined
 }
 
-// App expects to be rendered inside a router (BrowserRouter in main.tsx,
-// MemoryRouter in tests).
-export default function App({ api }: AppProps) {
+function reloadPage() {
+  window.location.reload()
+}
+
+// App expects to be rendered by a data router's splat route
+// (createBrowserRouter in main.tsx, createMemoryRouter in tests), so pages can
+// block navigation.
+export default function App({ api, serviceWorker }: AppProps) {
   const [queryClient] = useState(createQueryClient)
   return (
     <ApiProvider client={api}>
@@ -52,6 +82,8 @@ export default function App({ api }: AppProps) {
         <AuthBootstrap>
           <AppRoutes />
         </AuthBootstrap>
+        <OfflinePill />
+        <UpdatePrompt container={serviceWorker} reload={reloadPage} />
       </QueryClientProvider>
     </ApiProvider>
   )

web/src/AuthBootstrap.tsx

@@ -1,4 +1,4 @@
-import { useSyncExternalStore, type ReactNode } from 'react'
+import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
 import { useQuery } from '@tanstack/react-query'
 import { ApiError, ME_PATH, useApi } from './api/index.ts'
 import { NotInHouseholdPage } from './pages/NotInHouseholdPage.tsx'
@@ -11,13 +11,29 @@ export const meQueryKey = [ME_PATH] as const
 // AuthBootstrap loads GET /api/v1/me before rendering children. A 401 is
 // already navigating to sign-in, so the skeleton stays up; an account outside
 // the household sees only the "not in this household" screen.
+//
+// When /me cannot reach the server and it last answered with a member on this
+// device, the saved pages open read-only: the service worker answers their
+// reads from its cache, and every write is refused for want of a CSRF token.
+// /me runs even while the browser reports offline, so that case fails fast
+// instead of waiting, and it is fetched again when the browser is back online.
 export function AuthBootstrap({ children }: { children: ReactNode }) {
   const api = useApi()
   const forbidden = useSyncExternalStore(api.subscribe, api.forbidden)
-  const me = useQuery({ queryKey: meQueryKey, queryFn: api.loadMe, staleTime: Infinity })
+  const me = useQuery({ queryKey: meQueryKey, queryFn: api.loadMe, staleTime: Infinity, networkMode: 'always' })
+  // fetch rejects with a TypeError only when the network fails.
+  const savedPages = me.isError && me.error instanceof TypeError && api.session.verified()
+  const { refetch } = me
+
+  useEffect(() => {
+    if (!savedPages) return
+    return api.network.subscribe(() => {
+      if (!api.network.offline()) void refetch()
+    })
+  }, [savedPages, api, refetch])
 
   if (forbidden) return <NotInHouseholdPage />
-  if (me.isSuccess) return children
+  if (me.isSuccess || savedPages) return children
   if (me.isError && !(me.error instanceof ApiError && me.error.status === 401)) {
     return (
       <main className={styles.screen}>
@@ -25,6 +41,11 @@ export function AuthBootstrap({ children }: { children: ReactNode }) {
       </main>
     )
   }
+  return <LoadingScreen />
+}
+
+// LoadingScreen is the full-screen skeleton shown while MealQuest loads.
+export function LoadingScreen() {
   return (
     <main className={styles.screen} aria-busy="true" aria-label="Loading MealQuest">
       <div className={styles.loading}>

web/src/api/client.test.ts

@@ -1,15 +1,18 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch } from '../test/fetchStub.ts'
-import { ApiError, createApiClient, CSRF_HEADER } from './index.ts'
+import { ApiError, createApiClient, createVerifiedSession, CSRF_HEADER, VERIFIED_SESSION_KEY } from './index.ts'
+import { cacheFallbackHeader } from '../sw/routes.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
 
 afterEach(() => {
+  vi.restoreAllMocks()
   vi.unstubAllGlobals()
 })
 
 describe('apiFetch', () => {
   it('sends same-origin JSON and the cached CSRF token on non-GET requests only', async () => {
     const fetchMock = stubFetch(jsonResponse(200, ME), jsonResponse(200, { ok: 1 }), jsonResponse(200, { ok: 2 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await api.loadMe()
 
     await expect(api.apiFetch('/api/v1/settings/household')).resolves.toEqual({ ok: 1 })
@@ -29,7 +32,7 @@ describe('apiFetch', () => {
 
   it('refuses a non-GET request before /me has loaded', async () => {
     const fetchMock = stubFetch()
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toThrow(/no CSRF token/)
     expect(fetchMock).not.toHaveBeenCalled()
   })
@@ -47,7 +50,7 @@ describe('apiFetch', () => {
     'api/v1/me',
   ])('refuses %s without sending it or the CSRF token', async (path) => {
     const fetchMock = stubFetch(jsonResponse(200, ME))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await api.loadMe()
 
     await expect(api.apiFetch(path, { method: 'POST', body: {} })).rejects.toThrow(
@@ -60,7 +63,7 @@ describe('apiFetch', () => {
 
   it('rejects with a typed ApiError from the error body', async () => {
     stubFetch(errorResponse(503, 'unavailable', true))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     const error = await api.apiFetch('/api/v1/jobs/j1').catch((e: unknown) => e)
     expect(error).toBeInstanceOf(ApiError)
     expect(error).toMatchObject({ status: 503, code: 'unavailable', message: 'unavailable message', retryable: true })
@@ -68,14 +71,14 @@ describe('apiFetch', () => {
 
   it('rejects a response without the API error body', async () => {
     stubFetch(new Response('<html>bad gateway</html>', { status: 502 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await expect(api.apiFetch('/api/v1/jobs/j1')).rejects.toThrow('GET /api/v1/jobs/j1: 502 response is not JSON')
   })
 
   it('on 401 navigates to sign-in with the current path and search to return to', async () => {
     stubFetch(errorResponse(401, 'unauthenticated'))
     const location = fakeLocation('/plan/shopping', '?week=2026-10-05')
-    const api = createApiClient(location)
+    const api = createApiClient(location, createNetworkStatus(window), createVerifiedSession(localStorage))
 
     await expect(api.apiFetch('/api/v1/settings/household')).rejects.toMatchObject({ status: 401 })
     expect(location.assign).toHaveBeenCalledExactlyOnceWith(
@@ -90,7 +93,7 @@ describe('apiFetch', () => {
       jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
       jsonResponse(201, { id: 'j1' }),
     )
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await api.loadMe()
 
     await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: { kind: 'noop' } })).resolves.toEqual({
@@ -111,7 +114,7 @@ describe('apiFetch', () => {
       jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
       errorResponse(403, 'csrf'),
     )
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await api.loadMe()
 
     await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toMatchObject({
@@ -124,7 +127,7 @@ describe('apiFetch', () => {
 
   it('marks any other 403 as not in this household and notifies subscribers', async () => {
     const fetchMock = stubFetch(errorResponse(403, 'forbidden'))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     const listener = vi.fn()
     api.subscribe(listener)
 
@@ -136,14 +139,14 @@ describe('apiFetch', () => {
 
   it('does not take a 403 without the API error body as not in this household', async () => {
     stubFetch(new Response('<html>denied by proxy</html>', { status: 403 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await expect(api.apiFetch('/api/v1/me')).rejects.toThrow('GET /api/v1/me: 403 response is not JSON')
     expect(api.forbidden()).toBe(false)
   })
 
   it('does not refresh /me for a csrf 403 on a GET, which carries no token', async () => {
     const fetchMock = stubFetch(errorResponse(403, 'csrf'))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await expect(api.loadMe()).rejects.toMatchObject({ status: 403, code: 'csrf' })
     expect(fetchMock).toHaveBeenCalledTimes(1)
   })
@@ -152,7 +155,74 @@ describe('apiFetch', () => {
 describe('loadMe', () => {
   it('rejects a /me response without a CSRF token', async () => {
     stubFetch(jsonResponse(200, { ...ME, csrfToken: '' }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
     await expect(api.loadMe()).rejects.toThrow('response is not a member with a CSRF token')
   })
 })
+
+describe('verified session', () => {
+  it('is remembered when /me answers with a member', async () => {
+    stubFetch(jsonResponse(200, ME))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    expect(api.session.verified()).toBe(false)
+    await api.loadMe()
+    expect(api.session.verified()).toBe(true)
+    expect(localStorage.getItem(VERIFIED_SESSION_KEY)).toBe('1')
+  })
+
+  it('stores nothing from the /me response', async () => {
+    stubFetch(jsonResponse(200, ME))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    await api.loadMe()
+    expect(Object.keys(localStorage)).toEqual([VERIFIED_SESSION_KEY])
+    expect(JSON.stringify({ ...localStorage })).not.toContain(ME.csrfToken)
+  })
+
+  it('is not remembered for a /me response that is not a member', async () => {
+    stubFetch(jsonResponse(200, { ...ME, csrfToken: '' }))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    await expect(api.loadMe()).rejects.toThrow()
+    expect(api.session.verified()).toBe(false)
+  })
+
+  it('is forgotten on a 401', async () => {
+    stubFetch(jsonResponse(200, ME), errorResponse(401, 'unauthenticated'))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    await api.loadMe()
+    await expect(api.apiFetch('/api/v1/plans')).rejects.toMatchObject({ status: 401 })
+    expect(api.session.verified()).toBe(false)
+  })
+
+  it('is forgotten when the account is not in this household', async () => {
+    stubFetch(jsonResponse(200, ME), errorResponse(403, 'forbidden'))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    await api.loadMe()
+    await expect(api.apiFetch('/api/v1/plans')).rejects.toMatchObject({ status: 403 })
+    expect(api.session.verified()).toBe(false)
+  })
+
+  it('is kept when a request fails with a network error', async () => {
+    stubFetch(jsonResponse(200, ME))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    await api.loadMe()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await expect(api.loadMe()).rejects.toThrow(TypeError)
+    expect(api.session.verified()).toBe(true)
+  })
+})
+
+describe('network status', () => {
+  it('counts a response the service worker answered from its cache as offline', async () => {
+    vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true)
+    const cached = jsonResponse(200, { id: '01J9ZR' })
+    cached.headers.set(cacheFallbackHeader, '1')
+    stubFetch(cached, jsonResponse(200, { id: '01J9ZR' }))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+
+    await expect(api.apiFetch('/api/v1/recipes/01J9ZR')).resolves.toEqual({ id: '01J9ZR' })
+    expect(api.network.offline()).toBe(true)
+
+    await expect(api.apiFetch('/api/v1/recipes/01J9ZR')).resolves.toEqual({ id: '01J9ZR' })
+    expect(api.network.offline()).toBe(false)
+  })
+})

web/src/api/client.ts

@@ -1,4 +1,7 @@
+import type { NetworkStatus } from '../pwa/networkStatus.ts'
+import { cacheFallbackHeader } from '../sw/routes.ts'
 import { ApiError, isRecord, parseApiError } from './errors.ts'
+import type { VerifiedSession } from './verifiedSession.ts'
 
 // CSRF_HEADER carries the session's CSRF token on every non-GET request.
 export const CSRF_HEADER = 'X-MealQuest-CSRF'
@@ -36,7 +39,7 @@ export type ApiLocation = Pick<Location, 'origin' | 'pathname' | 'search' | 'ass
 
 export type ApiRequest = {
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-  // Sent as JSON.
+  // Sent as JSON. A GET must not have one.
   body?: unknown
 }
 
@@ -51,11 +54,18 @@ export type ApiClient = {
   // account is not in this household; subscribe is notified when it changes.
   forbidden(): boolean
   subscribe(listener: () => void): () => void
+  // network learns of every request that failed with a network error or was
+  // answered from the service worker's cache, and of every request the
+  // server answered.
+  network: NetworkStatus
+  // session remembers, on this device, whether /me last answered with a
+  // member; offline, AuthBootstrap opens the saved pages only if it did.
+  session: VerifiedSession
 }
 
 // createApiClient builds the app's API client. location is window.location in
 // the app: a 401 sends it to /auth/login with the current path to return to.
-export function createApiClient(location: ApiLocation): ApiClient {
+export function createApiClient(location: ApiLocation, network: NetworkStatus, session: VerifiedSession): ApiClient {
   let csrfToken: string | null = null
   let refreshing: Promise<Me> | null = null
   let forbidden = false
@@ -70,12 +80,28 @@ export function createApiClient(location: ApiLocation): ApiClient {
       }
       headers[CSRF_HEADER] = csrfToken
     }
-    return fetch(path, {
-      method,
-      headers,
-      credentials: 'same-origin',
-      body: body === undefined ? undefined : JSON.stringify(body),
-    })
+    // Serialize before fetching so a body that cannot be sent is its own error
+    // and never counts as a network failure.
+    let json: string | undefined
+    try {
+      json = body === undefined ? undefined : JSON.stringify(body)
+    } catch (error) {
+      throw new Error(`${method} ${path}: request body is not serializable as JSON`, { cause: error })
+    }
+    let response: Response
+    try {
+      response = await fetch(path, { method, headers, credentials: 'same-origin', body: json })
+    } catch (error) {
+      // fetch rejects with a TypeError when the network fails; an abort is a
+      // DOMException and says nothing about the network.
+      if (error instanceof TypeError) network.requestFailed()
+      throw error
+    }
+    // The service worker marks a response it answered from its cache because
+    // the server could not be reached in time.
+    if (response.headers.has(cacheFallbackHeader)) network.requestFailed()
+    else network.requestSucceeded()
+    return response
   }
 
   // refreshMe shares one in-flight /me request between every request that
@@ -90,6 +116,11 @@ export function createApiClient(location: ApiLocation): ApiClient {
   async function apiFetch<T>(path: string, request: ApiRequest = {}): Promise<T> {
     const method = request.method ?? 'GET'
     const url = apiURL(location.origin, method, path)
+    // fetch refuses a GET with a body by rejecting with a TypeError, the same
+    // error as a network failure, so refuse it here before anything is sent.
+    if (method === 'GET' && request.body !== undefined) {
+      throw new Error(`GET ${path}: a GET request cannot carry a body`)
+    }
     let response = await send(method, url, request.body)
     if (response.status === 403) {
       const error = await parseForbidden(method, path, response)
@@ -113,12 +144,14 @@ export function createApiClient(location: ApiLocation): ApiClient {
 
   function markForbidden() {
     if (forbidden) return
+    session.forget()
     forbidden = true
     listeners.forEach((listener) => listener())
   }
 
   async function decode<T>(method: string, path: string, response: Response): Promise<T> {
     if (response.status === 401) {
+      session.forget()
       location.assign(`/auth/login?return=${encodeURIComponent(location.pathname + location.search)}`)
     }
     if (!response.ok) throw await parseApiError(method, path, response)
@@ -140,6 +173,7 @@ export function createApiClient(location: ApiLocation): ApiClient {
       throw new Error(`GET ${ME_PATH}: response is not a member with a CSRF token`)
     }
     csrfToken = me.csrfToken
+    session.remember()
     return me as Me
   }
 
@@ -151,5 +185,7 @@ export function createApiClient(location: ApiLocation): ApiClient {
       listeners.add(listener)
       return () => listeners.delete(listener)
     },
+    network,
+    session,
   }
 }

web/src/api/index.ts

@@ -2,4 +2,5 @@ export { ApiProvider, useApi } from './ApiContext.tsx'
 export { createApiClient, CSRF_HEADER, ME_PATH, type ApiClient, type ApiLocation, type ApiRequest, type Me } from './client.ts'
 export { ApiError } from './errors.ts'
 export { createQueryClient, shouldRetry } from './queryClient.ts'
+export { createVerifiedSession, VERIFIED_SESSION_KEY, type VerifiedSession } from './verifiedSession.ts'
 export { useJob, type Job, type JobState, type JobStatus } from './useJob.ts'

web/src/api/useJob.test.tsx

@@ -2,7 +2,8 @@ import { act, renderHook } from '@testing-library/react'
 import type { ReactNode } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { errorResponse, fakeLocation, jsonResponse, request, stubFetch } from '../test/fetchStub.ts'
-import { ApiProvider, createApiClient, useJob } from './index.ts'
+import { ApiProvider, createApiClient, createVerifiedSession, useJob } from './index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
 
 type Draft = { dinners: string[] }
 
@@ -11,7 +12,7 @@ function job(status: string, result: Draft | null, error: string | null = null)
 }
 
 function renderJob(jobId: string | null) {
-  const api = createApiClient(fakeLocation())
+  const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
   const wrapper = ({ children }: { children: ReactNode }) => <ApiProvider client={api}>{children}</ApiProvider>
   return renderHook(({ id }) => useJob<Draft>(id), { wrapper, initialProps: { id: jobId } })
 }

web/src/api/verifiedSession.ts

@@ -0,0 +1,24 @@
+// VERIFIED_SESSION_KEY is the localStorage key marking that GET /api/v1/me
+// last answered with a household member on this device. It holds only "1" —
+// never the /me response, its CSRF token or anything from /auth.
+export const VERIFIED_SESSION_KEY = 'mealquest.verified-session'
+
+export type VerifiedSession = {
+  // verified reports whether /me last answered with a member on this device.
+  verified(): boolean
+  // remember records a /me that answered with a member.
+  remember(): void
+  // forget records that the server refused the session (401) or the account
+  // (not in this household).
+  forget(): void
+}
+
+// createVerifiedSession keeps the marker in storage (window.localStorage in
+// the app). A storage failure is thrown to the caller.
+export function createVerifiedSession(storage: Storage): VerifiedSession {
+  return {
+    verified: () => storage.getItem(VERIFIED_SESSION_KEY) === '1',
+    remember: () => storage.setItem(VERIFIED_SESSION_KEY, '1'),
+    forget: () => storage.removeItem(VERIFIED_SESSION_KEY),
+  }
+}

web/src/dinners/api.ts

@@ -0,0 +1,335 @@
+import { useIsMutating, useMutation, useQuery, useQueryClient, type QueryClient } from '@tanstack/react-query'
+import { useApi } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+
+export const DINNERS_PATH = '/api/v1/dinners'
+export const REGULARS_PATH = `${DINNERS_PATH}?status=regular`
+
+// GROUNDING_POLL_MS is how often the Regulars are read again while any of
+// them is still finding its recipe.
+export const GROUNDING_POLL_MS = 3000
+
+// Methods and Difficulties are the values the dinners API allows.
+export const METHODS = ['stovetop', 'oven', 'crockpot', 'grill', 'other'] as const
+export const DIFFICULTIES = ['easy', 'medium', 'hard'] as const
+const GROUNDING_STATUSES = ['pending', 'grounded', 'failed', 'manual'] as const
+
+export type Method = (typeof METHODS)[number]
+export type Difficulty = (typeof DIFFICULTIES)[number]
+export type GroundingStatus = (typeof GROUNDING_STATUSES)[number]
+
+// Regular is the part of a dinner the Regulars screens read. photo_id is
+// the stored photo's id, from photo_url. pending is true while an
+// optimistic add waits for the server; its id is not the server's.
+export type Regular = {
+  id: string
+  name: string
+  method: Method | null
+  minutes_total: number | null
+  difficulty: Difficulty | null
+  is_favorite: boolean
+  photo_id: string | undefined
+  grounding_status: GroundingStatus
+  pending?: true
+}
+
+// NewRegular is a POST /api/v1/dinners body: the household's name for the
+// dinner, with the recipe link to ground it in when one was pasted. A
+// dinner is never named from its link, which may carry private details.
+export type NewRegular = { name: string; recipe_url?: string }
+
+// RegularPatch is a PATCH /api/v1/dinners/{id} body; every field is optional.
+export type RegularPatch = Partial<{ name: string; method: Method; minutes_total: number; difficulty: Difficulty }>
+
+// ManualRecipe is a recipe the household types in; the server needs its
+// minutes and method.
+export type ManualRecipe = { ingredients: string[]; steps: string[]; minutes: number; method: Method }
+
+// RecipeFix is a POST /api/v1/dinners/{id}/ground body: exactly one way to
+// ground the dinner.
+export type RecipeFix = { candidate_id: string } | { recipe_url: string } | { manual: ManualRecipe }
+
+// RecipeCandidate is one recipe page a dinner could be grounded in.
+export type RecipeCandidate = {
+  candidate_id: string
+  title: string
+  site_name: string
+  photo_id: string | undefined
+  minutes: number | null
+}
+
+// CachedRegular is a Regular as the cache holds it. removing is true while
+// an optimistic removal waits for the server: the entry keeps its place, so
+// a refused removal returns exactly there whatever else changed meanwhile.
+type CachedRegular = Regular & { removing?: true }
+
+function shown(list: CachedRegular[]): Regular[] {
+  return list.filter((regular) => !regular.removing)
+}
+
+function restored(regular: CachedRegular): CachedRegular {
+  const copy = { ...regular }
+  delete copy.removing
+  return copy
+}
+
+// REGULARS_KEY prefixes every Regulars query, so a change refreshes them all
+// (the settings home's count included).
+export const REGULARS_KEY = ['dinners', 'regular'] as const
+const REGULARS_LIST_KEY = [...REGULARS_KEY, 'list'] as const
+const REGULARS_MUTATION_KEY = ['dinners', 'regular', 'change'] as const
+
+function oneOf<T extends string>(where: string, field: string, values: readonly T[], value: unknown): T {
+  if (typeof value !== 'string' || !(values as readonly string[]).includes(value)) {
+    throw new Error(`${where}: ${field} ${JSON.stringify(value)} is not one of ${values.join(', ')}`)
+  }
+  return value as T
+}
+
+function nullable<T>(value: unknown, parse: (value: unknown) => T): T | null {
+  return value === null ? null : parse(value)
+}
+
+function wholeNumber(where: string, field: string, value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) throw new Error(`${where}: ${field} is not a whole number`)
+  return value
+}
+
+const PHOTO_URL = /^\/media\/photos\/([^/]+)-400\.jpg$/
+
+// photoId reads the photo id out of a photo_url, which the server always
+// sends as /media/photos/{id}-400.jpg or null.
+function photoId(where: string, value: unknown): string | undefined {
+  if (value === null) return undefined
+  const match = typeof value === 'string' ? PHOTO_URL.exec(value) : null
+  if (!match?.[1]) throw new Error(`${where}: photo_url ${JSON.stringify(value)} is not a stored photo`)
+  return decodeURIComponent(match[1])
+}
+
+function parseDinner(where: string, body: unknown): Regular {
+  if (!isRecord(body) || typeof body.id !== 'string' || typeof body.name !== 'string') {
+    throw new Error(`${where}: response is not a dinner`)
+  }
+  if (typeof body.is_favorite !== 'boolean') throw new Error(`${where}: is_favorite is not a boolean`)
+  return {
+    id: body.id,
+    name: body.name,
+    method: nullable(body.method, (v) => oneOf(where, 'method', METHODS, v)),
+    minutes_total: nullable(body.minutes_total, (v) => wholeNumber(where, 'minutes_total', v)),
+    difficulty: nullable(body.difficulty, (v) => oneOf(where, 'difficulty', DIFFICULTIES, v)),
+    is_favorite: body.is_favorite,
+    photo_id: photoId(where, body.photo_url),
+    grounding_status: oneOf(where, 'grounding_status', GROUNDING_STATUSES, body.grounding_status),
+  }
+}
+
+function parseCandidate(where: string, body: unknown): RecipeCandidate {
+  if (
+    !isRecord(body) ||
+    typeof body.candidate_id !== 'string' ||
+    typeof body.title !== 'string' ||
+    typeof body.site_name !== 'string'
+  ) {
+    throw new Error(`${where}: response is not a recipe candidate`)
+  }
+  return {
+    candidate_id: body.candidate_id,
+    title: body.title,
+    site_name: body.site_name,
+    photo_id: photoId(where, body.photo_url),
+    minutes: nullable(body.minutes, (v) => wholeNumber(where, 'minutes', v)),
+  }
+}
+
+function dinnerPath(id: string): string {
+  return `${DINNERS_PATH}/${encodeURIComponent(id)}`
+}
+
+// useRegulars is the household's Regulars, in the server's order. While any
+// of them is still finding its recipe it is read again every
+// GROUNDING_POLL_MS, except while any change is in flight (whose settling
+// reads it again anyway), so a poll never overwrites a change being saved.
+// Watching the changes in flight re-renders the hook as each one starts and
+// settles, which pauses and resumes the poll.
+export function useRegulars() {
+  const { apiFetch } = useApi()
+  const changing = useIsMutating({ mutationKey: REGULARS_MUTATION_KEY }) > 0
+  return useQuery({
+    queryKey: REGULARS_LIST_KEY,
+    queryFn: async () => {
+      const where = `GET ${REGULARS_PATH}`
+      const body = await apiFetch<unknown>(REGULARS_PATH)
+      if (!isRecord(body) || !Array.isArray(body.dinners)) throw new Error(`${where}: response has no dinners list`)
+      return body.dinners.map((dinner): CachedRegular => parseDinner(where, dinner))
+    },
+    select: shown,
+    refetchInterval: (query) => {
+      const list = query.state.data
+      if (list === undefined || changing) return false
+      return list.some((regular) => regular.grounding_status === 'pending') ? GROUNDING_POLL_MS : false
+    },
+  })
+}
+
+// changeOptimistically stops Regulars reads in flight, so they cannot
+// overwrite the optimistic list, then applies change to it.
+async function changeOptimistically(queryClient: QueryClient, change: (list: CachedRegular[]) => CachedRegular[]) {
+  await queryClient.cancelQueries({ queryKey: REGULARS_LIST_KEY })
+  setRegulars(queryClient, change)
+}
+
+function setRegulars(queryClient: QueryClient, change: (list: CachedRegular[]) => CachedRegular[]) {
+  queryClient.setQueryData<CachedRegular[]>(REGULARS_LIST_KEY, (list) => change(list ?? []))
+}
+
+// replace puts the server's answer for a dinner in its place in the list.
+function replace(queryClient: QueryClient, dinner: Regular) {
+  setRegulars(queryClient, (list) => list.map((regular) => (regular.id === dinner.id ? dinner : regular)))
+}
+
+// settle refetches the Regulars once the last change in flight is done, so
+// an earlier change's refetch never drops a later change's optimistic entry.
+function settle(queryClient: QueryClient) {
+  if (queryClient.isMutating({ mutationKey: REGULARS_MUTATION_KEY }) === 1) {
+    void queryClient.invalidateQueries({ queryKey: REGULARS_KEY })
+  }
+}
+
+let pendingIds = 0
+
+// useAddRegular adds a Regular by name, with or without a recipe link (POST
+// /api/v1/dinners). It shows in the list at once under its name and is
+// taken out again if the server refuses it.
+export function useAddRegular() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationKey: REGULARS_MUTATION_KEY,
+    mutationFn: async (add: NewRegular) =>
+      parseDinner(`POST ${DINNERS_PATH}`, await apiFetch<unknown>(DINNERS_PATH, { method: 'POST', body: add })),
+    onMutate: async (add) => {
+      const id = `pending-${++pendingIds}`
+      const optimistic: CachedRegular = {
+        id,
+        name: add.name,
+        method: null,
+        minutes_total: null,
+        difficulty: null,
+        is_favorite: false,
+        photo_id: undefined,
+        grounding_status: 'pending',
+        pending: true,
+      }
+      await changeOptimistically(queryClient, (list) => [...list, optimistic])
+      return { id }
+    },
+    onSuccess: (dinner, _add, context) => {
+      setRegulars(queryClient, (list) => list.map((regular) => (regular.id === context.id ? dinner : regular)))
+    },
+    onError: (_error, _add, context) => {
+      if (context === undefined) return
+      setRegulars(queryClient, (list) => list.filter((regular) => regular.id !== context.id))
+    },
+    onSettled: () => settle(queryClient),
+  })
+}
+
+// useRemoveRegular archives a Regular (DELETE /api/v1/dinners/{id}). It
+// leaves the list at once and is put back in its place if the server
+// refuses.
+export function useRemoveRegular() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationKey: REGULARS_MUTATION_KEY,
+    mutationFn: async (regular: Regular) => {
+      await apiFetch<unknown>(dinnerPath(regular.id), { method: 'DELETE' })
+    },
+    onMutate: async (regular) => {
+      await changeOptimistically(queryClient, (list) =>
+        list.map((r): CachedRegular => (r.id === regular.id ? { ...r, removing: true } : r)),
+      )
+    },
+    onSuccess: (_data, regular) => {
+      setRegulars(queryClient, (list) => list.filter((r) => r.id !== regular.id))
+    },
+    onError: (_error, regular) => {
+      setRegulars(queryClient, (list) => list.map((r) => (r.id === regular.id ? restored(r) : r)))
+    },
+    onSettled: () => settle(queryClient),
+  })
+}
+
+// useEditRegular saves changes to a Regular (PATCH /api/v1/dinners/{id})
+// and shows the server's answer once it is saved.
+export function useEditRegular() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationKey: REGULARS_MUTATION_KEY,
+    mutationFn: async ({ id, patch }: { id: string; patch: RegularPatch }) =>
+      parseDinner(`PATCH ${DINNERS_PATH}/{id}`, await apiFetch<unknown>(dinnerPath(id), { method: 'PATCH', body: patch })),
+    onSuccess: (dinner) => replace(queryClient, dinner),
+    onSettled: () => settle(queryClient),
+  })
+}
+
+// useToggleFavorite toggles a Regular's favorite heart (POST
+// /api/v1/dinners/{id}/favorite). The heart changes at once and changes
+// back if the server refuses.
+export function useToggleFavorite() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  const set = (id: string, is_favorite: boolean) =>
+    setRegulars(queryClient, (list) => list.map((r) => (r.id === id ? { ...r, is_favorite } : r)))
+  return useMutation({
+    mutationKey: REGULARS_MUTATION_KEY,
+    mutationFn: async (regular: Regular) =>
+      parseDinner(
+        `POST ${DINNERS_PATH}/{id}/favorite`,
+        await apiFetch<unknown>(`${dinnerPath(regular.id)}/favorite`, { method: 'POST' }),
+      ),
+    onMutate: async (regular) => {
+      await changeOptimistically(queryClient, (list) =>
+        list.map((r) => (r.id === regular.id ? { ...r, is_favorite: !regular.is_favorite } : r)),
+      )
+    },
+    onSuccess: (dinner) => replace(queryClient, dinner),
+    onError: (_error, regular) => set(regular.id, regular.is_favorite),
+    onSettled: () => settle(queryClient),
+  })
+}
+
+// useGroundRegular fixes a Regular's recipe (POST /api/v1/dinners/{id}/ground)
+// with a candidate, a pasted link or a recipe typed in. A candidate or link
+// is read in the request, which can take up to a minute and a half.
+export function useGroundRegular() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationKey: REGULARS_MUTATION_KEY,
+    mutationFn: async ({ id, fix }: { id: string; fix: RecipeFix }) =>
+      parseDinner(
+        `POST ${DINNERS_PATH}/{id}/ground`,
+        await apiFetch<unknown>(`${dinnerPath(id)}/ground`, { method: 'POST', body: fix }),
+      ),
+    onSuccess: (dinner) => replace(queryClient, dinner),
+    onSettled: () => settle(queryClient),
+  })
+}
+
+// useRecipeCandidates is up to three recipe pages the dinner could be
+// grounded in, best first (GET /api/v1/dinners/{id}/recipe-candidates).
+export function useRecipeCandidates(id: string) {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: ['dinners', 'candidates', id],
+    queryFn: async () => {
+      const path = `${dinnerPath(id)}/recipe-candidates`
+      const where = `GET ${DINNERS_PATH}/{id}/recipe-candidates`
+      const body = await apiFetch<unknown>(path)
+      if (!isRecord(body) || !Array.isArray(body.candidates)) throw new Error(`${where}: response has no candidates list`)
+      return body.candidates.map((candidate) => parseCandidate(where, candidate))
+    },
+  })
+}

web/src/dinners/names.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import cases from './testdata/dedupe_cases.json'
+import { normalizeName, similarNames } from './names.ts'
+
+// The cases internal/ai/harness's tests run against Normalize and Similar.
+describe('dinner names, as the server compares them', () => {
+  it('has cases to run', () => {
+    expect(cases.normalize.length).toBeGreaterThan(0)
+    expect(cases.similar.length).toBeGreaterThan(0)
+  })
+
+  it.each(cases.normalize)('normalizes "$name" to "$want"', ({ name, want }) => {
+    expect(normalizeName(name)).toBe(want)
+  })
+
+  it.each(cases.similar)('"$a" and "$b" similar: $want', ({ a, b, want }) => {
+    expect(similarNames(a, b)).toBe(want)
+    expect(similarNames(b, a)).toBe(want)
+  })
+})

web/src/dinners/names.ts

@@ -0,0 +1,58 @@
+// The PWA's copy of the server's dinner-name rules (internal/ai/harness
+// Normalize and Similar), so a screen can tell beforehand that the dinners
+// API would refuse a name as a duplicate. The server still decides.
+// web/src/dinners/testdata/dedupe_cases.json is run against both.
+
+import folds from './letterFolds.json'
+
+// SIMILAR_THRESHOLD is harness.SimilarThreshold.
+const SIMILAR_THRESHOLD = 0.85
+
+// fillerWords is harness's fillerWords.
+const fillerWords = new Set(['easy', 'best', 'homemade', 'quick', 'simple', 'the', 'a', 'recipe', 'classic'])
+
+// letterFolds is harness's letterFolds: gen_folds.py writes both tables,
+// and harness's TestLetterFoldsMatchPWA fails when they differ.
+const letterFolds: Record<string, string> = folds
+
+const combiningMark = /\p{Mn}/u
+const wordChar = /[\p{L}\p{Nd}]/u
+
+// normalizeName is harness.Normalize: lowercased, accents dropped, letters
+// folded, apostrophes removed, other punctuation turned into spaces and
+// filler words dropped. "Easy Chicken Tikka-Masala!" is
+// "chicken tikka masala".
+export function normalizeName(name: string): string {
+  let out = ''
+  // Lowercased letter by letter, as Go's strings.ToLower does, so no
+  // letter is lowered by its context (a final Σ is σ, not ς).
+  for (const letter of name) {
+    for (const ch of letter.toLowerCase()) {
+      if (combiningMark.test(ch) || ch === "'" || ch === '’') continue
+      const fold = letterFolds[ch]
+      if (fold !== undefined) out += fold
+      else if (wordChar.test(ch)) out += ch
+      else out += ' '
+    }
+  }
+  return out
+    .split(' ')
+    .filter((word) => word !== '' && !fillerWords.has(word))
+    .join(' ')
+}
+
+function words(name: string): Set<string> {
+  const normalized = normalizeName(name)
+  return new Set(normalized === '' ? [] : normalized.split(' '))
+}
+
+// similarNames is harness.Similar: whether a and b name the same dinner, by
+// the share of the words of their normalized forms they have in common.
+export function similarNames(a: string, b: string): boolean {
+  const left = words(a)
+  const right = words(b)
+  if (left.size === 0 || right.size === 0) return false
+  let shared = 0
+  for (const word of left) if (right.has(word)) shared++
+  return shared / (left.size + right.size - shared) >= SIMILAR_THRESHOLD
+}

web/src/dinners/testdata/dedupe_cases.json

@@ -0,0 +1,136 @@
+{
+  "normalize": [
+    {
+      "name": "Easy Chicken Tikka-Masala!",
+      "want": "chicken tikka masala"
+    },
+    {
+      "name": "  Homemade   Chili ",
+      "want": "chili"
+    },
+    {
+      "name": "Grandma's Stew",
+      "want": "grandmas stew"
+    },
+    {
+      "name": "Grandma’s Stew",
+      "want": "grandmas stew"
+    },
+    {
+      "name": "İskender Kebab",
+      "want": "iskender kebab"
+    },
+    {
+      "name": "Paella à la Valenciana",
+      "want": "paella la valenciana"
+    },
+    {
+      "name": "Crème Brûlée",
+      "want": "creme brulee"
+    },
+    {
+      "name": "Crème Brûlée",
+      "want": "creme brulee"
+    },
+    {
+      "name": "Smørrebrød",
+      "want": "smorrebrod"
+    },
+    {
+      "name": "Pierogi z Łososiem",
+      "want": "pierogi z lososiem"
+    },
+    {
+      "name": "Straße Würstchen",
+      "want": "strasse wurstchen"
+    },
+    {
+      "name": "Œufs en Cocotte",
+      "want": "oeufs en cocotte"
+    },
+    {
+      "name": "Æbleskiver",
+      "want": "aebleskiver"
+    },
+    {
+      "name": "Phở Bò",
+      "want": "pho bo"
+    },
+    {
+      "name": "The Best Quick Recipe",
+      "want": ""
+    },
+    {
+      "name": "Chicken stir-fry",
+      "want": "chicken stir fry"
+    },
+    {
+      "name": "7-layer dip",
+      "want": "7 layer dip"
+    },
+    {
+      "name": "Ƈhili",
+      "want": "chili"
+    },
+    {
+      "name": "Ꞔarbanzo Stew",
+      "want": "carbanzo stew"
+    },
+    {
+      "name": "ΜΟΥΣΑΚΑΣ",
+      "want": "μουσακασ"
+    }
+  ],
+  "similar": [
+    {
+      "a": "Homemade chili",
+      "b": "Chili",
+      "want": true
+    },
+    {
+      "a": "Easy Spaghetti Bolognese",
+      "b": "spaghetti bolognese",
+      "want": true
+    },
+    {
+      "a": "Chicken stir fry",
+      "b": "Chicken stir-fry",
+      "want": true
+    },
+    {
+      "a": "Crème brûlée",
+      "b": "Creme brulee",
+      "want": true
+    },
+    {
+      "a": "Smørrebrød",
+      "b": "smorrebrod",
+      "want": true
+    },
+    {
+      "a": "Beef tacos",
+      "b": "Fish tacos",
+      "want": false
+    },
+    {
+      "a": "Chili",
+      "b": "White chicken chili",
+      "want": false
+    },
+    {
+      "a": "Pot roast",
+      "b": "Roast",
+      "want": false
+    },
+    {
+      "a": "The best",
+      "b": "Easy recipe",
+      "want": false
+    },
+    {
+      "a": "Ƈhili",
+      "b": "Chili",
+      "want": true
+    }
+  ]
+}

web/src/dinners/useRefusals.ts

@@ -0,0 +1,26 @@
+import { useRef, useState } from 'react'
+
+// Refusal is one change the server turned down. key is unique to that
+// attempt, so two attempts of the same change in flight each keep their own
+// refusal. change names what was tried, so trying it again once it has been
+// refused clears the earlier refusal and no other.
+export type Refusal = { key: number; change: string; text: string }
+
+// useRefusals keeps each change's own refusal: the mutation hooks only
+// report their latest change, which would hide a refusal while another
+// change is in flight. track(change, what, answer) clears change's earlier
+// refusal and records "Could not {what}: …" if answer rejects.
+export function useRefusals() {
+  const [refusals, setRefusals] = useState<Refusal[]>([])
+  const attempts = useRef(0)
+
+  function track(change: string, what: string, answer: Promise<unknown>) {
+    const key = ++attempts.current
+    setRefusals((all) => all.filter((refusal) => refusal.change !== change))
+    answer.catch((error: Error) => {
+      setRefusals((all) => [...all, { key, change, text: `Could not ${what}: ${error.message}` }])
+    })
+  }
+
+  return { refusals, track }
+}

web/src/main.tsx

@@ -1,22 +1,30 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
-import { BrowserRouter } from 'react-router'
+import { createBrowserRouter, RouterProvider } from 'react-router'
 import './styles/tokens.css'
 import './styles/base.css'
 import App from './App.tsx'
-import { createApiClient } from './api/index.ts'
+import { createApiClient, createVerifiedSession } from './api/index.ts'
+import { createNetworkStatus } from './pwa/networkStatus.ts'
 
 const root = document.getElementById('root')
 if (!root) {
   throw new Error('MealQuest: #root element missing from index.html')
 }
 
-const api = createApiClient(window.location)
+const api = createApiClient(window.location, createNetworkStatus(window), createVerifiedSession(window.localStorage))
+
+// A data router, so pages can block navigation (useBlocker); App's own
+// <Routes> match every path under its splat route.
+const router = createBrowserRouter([
+  {
+    path: '*',
+    element: <App api={api} serviceWorker={'serviceWorker' in navigator ? navigator.serviceWorker : undefined} />,
+  },
+])
 
 createRoot(root).render(
   <StrictMode>
-    <BrowserRouter>
-      <App api={api} />
-    </BrowserRouter>
+    <RouterProvider router={router} />
   </StrictMode>,
 )

web/src/onboarding/NotificationsStep.test.tsx

@@ -0,0 +1,326 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { Route, Routes } from 'react-router'
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { createApiClient, createVerifiedSession } from '../api/index.ts'
+import App from '../App.tsx'
+import { AuthBootstrap } from '../AuthBootstrap.tsx'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { ApiProviders, HOUSEHOLD_SETTINGS } from '../test/ApiProviders.tsx'
+import { declaredStyle } from '../test/cssRules.ts'
+import { InDataRouter } from '../test/dataRouter.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { mockViewport } from '../test/matchMedia.ts'
+import { NotificationsStep, notificationsUnavailable, type EnableNotifications } from './NotificationsStep.tsx'
+import styles from './Onboarding.module.css'
+
+const IPHONE_SAFARI =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1'
+
+const COMPLETED_AT = '2026-10-06T21:30:00.000Z'
+
+// requestPermission stands in for the browser's Notification API, which
+// jsdom lacks, so a test can prove nothing asks for permission.
+let requestPermission: Mock<() => Promise<NotificationPermission>>
+
+beforeEach(() => {
+  requestPermission = vi.fn<() => Promise<NotificationPermission>>(() => Promise.resolve('granted'))
+  vi.stubGlobal('Notification', { permission: 'default', requestPermission })
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(navigator, 'maxTouchPoints')
+  Reflect.deleteProperty(navigator, 'standalone')
+  localStorage.clear()
+})
+
+// A PATCH the fake server holds until the test answers it.
+type Held = { body: unknown; answer: (response: Response) => void }
+
+// stubFirstRunServer stands in for the server on first run: signed in,
+// onboarding not finished. Each PATCH of the household settings is held in
+// `held` until the test answers it.
+function stubFirstRunServer() {
+  const held: Held[] = []
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const path = String(input)
+    const method = init?.method ?? 'GET'
+    if (method === 'GET' && path === '/api/v1/me') return Promise.resolve(jsonResponse(200, ME))
+    if (method === 'GET' && path === '/api/v1/settings/household') {
+      return Promise.resolve(jsonResponse(200, { ...HOUSEHOLD_SETTINGS, onboarding_completed_at: null }))
+    }
+    if (method === 'PATCH' && path === '/api/v1/settings/household') {
+      return new Promise<Response>((resolve) => {
+        held.push({ body: JSON.parse(String(init?.body)), answer: resolve })
+      })
+    }
+    throw new Error(`unexpected fetch: ${method} ${path}`)
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return { fetchMock, held }
+}
+
+function completed(request: Held) {
+  request.answer(jsonResponse(200, { ...HOUSEHOLD_SETTINGS, onboarding_completed_at: COMPLETED_AT }))
+}
+
+// renderApp renders the whole app at step 3, so the first-run redirect is
+// what decides where finishing lands.
+async function renderApp() {
+  mockViewport(390)
+  const server = stubFirstRunServer()
+  const api = createApiClient(
+    fakeLocation('/onboarding/notifications'),
+    createNetworkStatus(window),
+    createVerifiedSession(localStorage),
+  )
+  render(
+    <InDataRouter path="/onboarding/notifications">
+      <App api={api} serviceWorker={undefined} />
+    </InDataRouter>,
+  )
+  await screen.findByRole('heading', { level: 1, name: 'Stay in the loop' })
+  return server
+}
+
+// renderStep renders step 3 alone with the given enableNotifications, and a
+// Home that says it was reached. AuthBootstrap reads /api/v1/me for the CSRF
+// token every write needs.
+async function renderStep(enableNotifications?: EnableNotifications) {
+  const server = stubFirstRunServer()
+  render(
+    <InDataRouter path="/onboarding/notifications">
+      <ApiProviders>
+        <AuthBootstrap>
+          <Routes>
+            <Route
+              path="/onboarding/notifications"
+              element={<NotificationsStep enableNotifications={enableNotifications} />}
+            />
+            <Route path="/" element={<h1>Home</h1>} />
+            <Route path="/onboarding/regulars" element={<h1>Regulars step</h1>} />
+          </Routes>
+        </AuthBootstrap>
+      </ApiProviders>
+    </InDataRouter>,
+  )
+  await screen.findByRole('heading', { level: 1, name: 'Stay in the loop' })
+  return server
+}
+
+function turnOn() {
+  return screen.getByRole('button', { name: 'Turn on notifications' })
+}
+
+function later() {
+  return screen.getByRole('button', { name: 'Maybe later' })
+}
+
+describe('onboarding step 3', () => {
+  it('explains what MealQuest notifies about, with all three progress pills filled', async () => {
+    await renderApp()
+
+    expect(screen.getByText('Step 3 of 3')).toBeInTheDocument()
+    const pills = Array.from(document.getElementsByClassName(styles.pill!))
+    expect(pills.map((pill) => pill.classList.contains(styles.filled!))).toEqual([true, true, true])
+    const topics = within(screen.getByRole('list')).getAllByRole('listitem')
+    expect(topics.map((topic) => topic.textContent)).toEqual([
+      expect.stringMatching(/^Plan ready/),
+      expect.stringMatching(/^Supply run ready/),
+      expect.stringMatching(/^Tonight's dinner/),
+      expect.stringMatching(/^New Side quests/),
+    ])
+    expect(turnOn()).toBeEnabled()
+    expect(later()).toBeEnabled()
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+  })
+
+  it('never asks for notification permission on render', async () => {
+    await renderApp()
+    expect(requestPermission).not.toHaveBeenCalled()
+  })
+
+  it('sizes both actions as tap targets and fixes them to the bottom', async () => {
+    await renderApp()
+    expectMinHitArea(turnOn())
+    expectMinHitArea(later())
+    expect(declaredStyle(turnOn()).height).toBe('52px')
+    expect(declaredStyle(later()).height).toBe('52px')
+    expect(declaredStyle(turnOn().parentElement!.parentElement!).position).toBe('fixed')
+  })
+
+  it('shows no install hint outside iOS Safari', async () => {
+    await renderApp()
+    expect(screen.queryByText('Tap Share, then Add to Home Screen to get notifications')).not.toBeInTheDocument()
+  })
+
+  it('shows the install hint in an iOS Safari tab', async () => {
+    vi.spyOn(navigator, 'userAgent', 'get').mockReturnValue(IPHONE_SAFARI)
+    Object.defineProperty(navigator, 'maxTouchPoints', { configurable: true, value: 5 })
+    Object.defineProperty(navigator, 'standalone', { configurable: true, value: false })
+    vi.stubGlobal('matchMedia', (query: string) => ({ matches: false, media: query }) as MediaQueryList)
+    await renderStep()
+    expect(screen.getByRole('note')).toHaveTextContent('Tap Share, then Add to Home Screen to get notifications')
+  })
+
+  it('"Maybe later" finishes onboarding and goes Home, ending the first-run redirect', async () => {
+    const server = await renderApp()
+    fireEvent.click(later())
+
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    expect(server.held[0]!.body).toEqual({ onboarding_completed: true })
+    expect(turnOn()).toBeDisabled()
+    expect(later()).toBeDisabled()
+    completed(server.held[0]!)
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+    expect(requestPermission).not.toHaveBeenCalled()
+  })
+
+  it('"Turn on notifications" says plainly that nothing was turned on while notifications are unavailable', async () => {
+    const server = await renderApp()
+    fireEvent.click(turnOn())
+
+    expect(await screen.findByRole('status')).toHaveTextContent(
+      "Notifications aren't on yet: MealQuest can't send them until the notification feature ships, so nothing was turned on.",
+    )
+    // Not a silent success: onboarding is not finished behind the household's back.
+    expect(server.held).toHaveLength(0)
+    expect(screen.getByRole('heading', { level: 1, name: 'Stay in the loop' })).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Turn on notifications' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Maybe later' })).not.toBeInTheDocument()
+
+    const finish = screen.getByRole('button', { name: 'Finish setting up' })
+    expectMinHitArea(finish)
+    fireEvent.click(finish)
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    expect(server.held[0]!.body).toEqual({ onboarding_completed: true })
+    completed(server.held[0]!)
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+    expect(requestPermission).not.toHaveBeenCalled()
+  })
+
+  it('"Turn on notifications" says the browser blocked them when denied, then finishes on request', async () => {
+    const server = await renderStep(() => Promise.resolve('denied'))
+    fireEvent.click(turnOn())
+
+    expect(await screen.findByRole('status')).toHaveTextContent("Notifications aren't on: this browser blocked them.")
+    expect(server.held).toHaveLength(0)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Finish setting up' }))
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    completed(server.held[0]!)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+  })
+
+  it('"Turn on notifications" asks the injected enableNotifications first, then finishes', async () => {
+    let answer: (result: 'enabled') => void = () => {}
+    const enable = vi.fn<EnableNotifications>(
+      () =>
+        new Promise((resolve) => {
+          answer = resolve
+        }),
+    )
+    const server = await renderStep(enable)
+    expect(enable).not.toHaveBeenCalled()
+
+    fireEvent.click(turnOn())
+    expect(enable).toHaveBeenCalledOnce()
+    expect(turnOn()).toBeDisabled()
+    expect(later()).toBeDisabled()
+    // Onboarding is not finished until enableNotifications has answered.
+    await Promise.resolve()
+    expect(server.held).toHaveLength(0)
+
+    answer('enabled')
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    expect(server.held[0]!.body).toEqual({ onboarding_completed: true })
+    completed(server.held[0]!)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+  })
+
+  it('"Maybe later" does not ask the injected enableNotifications', async () => {
+    const enable = vi.fn<EnableNotifications>(() => Promise.resolve('enabled'))
+    const server = await renderStep(enable)
+    fireEvent.click(later())
+
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    completed(server.held[0]!)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    expect(enable).not.toHaveBeenCalled()
+  })
+
+  it('says why and stays when enableNotifications fails', async () => {
+    const server = await renderStep(() => Promise.reject(new Error('push service down')))
+    fireEvent.click(turnOn())
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Could not turn on notifications: push service down')
+    expect(server.held).toHaveLength(0)
+    expect(turnOn()).toBeEnabled()
+    expect(screen.getByRole('heading', { level: 1, name: 'Stay in the loop' })).toBeInTheDocument()
+  })
+
+  it('says why and stays when the server refuses to finish onboarding, then finishes on retry', async () => {
+    const server = await renderApp()
+    fireEvent.click(later())
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    server.held[0]!.answer(errorResponse(500, 'internal'))
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Could not finish setting up: internal message')
+    expect(screen.getByRole('heading', { level: 1, name: 'Stay in the loop' })).toBeInTheDocument()
+    expect(later()).toBeEnabled()
+
+    fireEvent.click(later())
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+    await vi.waitFor(() => expect(server.held).toHaveLength(2))
+    completed(server.held[1]!)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+  })
+})
+
+describe('onboarding step 3 with too few Regulars', () => {
+  it('says why and offers a way back to add Regulars', async () => {
+    const server = await renderStep()
+    fireEvent.click(later())
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    server.held[0]!.answer(
+      jsonResponse(400, {
+        error: {
+          code: 'invalid_settings',
+          message: 'invalid household settings: onboarding_completed: add at least 3 Regulars first (have 2)',
+          retryable: false,
+        },
+      }),
+    )
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      'Could not finish setting up: invalid household settings: onboarding_completed: add at least 3 Regulars first (have 2)',
+    )
+    const addRegulars = screen.getByRole('button', { name: 'Add Regulars' })
+    expectMinHitArea(addRegulars)
+    fireEvent.click(addRegulars)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Regulars step' })).toBeInTheDocument()
+  })
+
+  it('offers no way back for any other refusal', async () => {
+    const server = await renderStep()
+    fireEvent.click(later())
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    server.held[0]!.answer(errorResponse(500, 'internal'))
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Could not finish setting up: internal message')
+    expect(screen.queryByRole('button', { name: 'Add Regulars' })).not.toBeInTheDocument()
+  })
+})
+
+describe('notificationsUnavailable', () => {
+  it('answers "unavailable" without asking for permission', async () => {
+    await expect(notificationsUnavailable()).resolves.toBe('unavailable')
+    expect(requestPermission).not.toHaveBeenCalled()
+  })
+})