Redact the AI key from model lists and fit the longest prompt

GET /settings/ai/models now removes the stored API key from every model
ID and display name the provider returns, so a provider that echoes the
key in a successful list cannot disclose it.

PATCH /settings/ai gets its own body limit, sized for 8,000 characters at
12 bytes of JSON each (a \u-escaped surrogate pair) plus the other
fields. A valid prompt of three- or four-byte characters was refused by
the shared 16 KiB limit; the 8,000-character rule stays the only limit
on the prompt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.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

cmd/server/main.go

@@ -13,6 +13,7 @@ import (
 	"syscall"
 	"time"
 
+	"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/config"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
@@ -83,6 +84,11 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
+	ai, err := aisettings.New(db, box, cfg.PublicURL.String())
+	if err != nil {
+		return err
+	}
+
 	sessions, err := auth.NewSessionManager(db, cfg.SessionIdle, cfg.SessionMax)
 	if err != nil {
 		return err
@@ -99,7 +105,7 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, runner, photos, frontend.Assets())
+	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, runner, photos, frontend.Assets())
 	if err != nil {
 		return err
 	}

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. Planned; not
+#   read by the service yet. The app takes its recipe-search provider and
+#   base URL 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,974 @@
+# 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 service does not
+read `MEALQUEST_SEARXNG_URL`: `deploy/compose.yaml` sets it for a future
+wiring, and today it does nothing. 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 Settings
+screen's recipe search; the screen itself is not built yet). Until that row
+exists, recipe search answers 409 `not_configured`.
+
+After the first deploy, 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

@@ -152,6 +152,29 @@ automatic** (D-021).
   `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.
 - `/health` — liveness.
 - Everything else serves the embedded PWA with SPA fallback.
 
@@ -371,6 +394,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 |
 | --- | --- |

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/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/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/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),
+		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/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),
-		newTestSearch(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(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), newTestSearch(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(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),
-		newTestSearch(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/recipesearch_test.go

@@ -22,7 +22,7 @@ const (
 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, newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/server.go

@@ -10,6 +10,7 @@ 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/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
@@ -31,18 +32,23 @@ type RouteMounter interface {
 // 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; search serves
-// /api/v1/settings/recipe-search and its /test; runner serves
+// /api/v1/settings/recipe-search and its /test; ai serves
+// /api/v1/settings/ai, its /api-key, /verify, /models and /reset-prompt;
+// 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, search *recipes.SearchSettingsService, 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, 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 runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -80,6 +86,12 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	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.Post("/jobs", postJob(logger, runner))
 	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	media.Get("/photos/{name}", getPhoto(logger, photos))

internal/server/server_test.go

@@ -16,6 +16,7 @@ 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/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
@@ -42,7 +43,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, newTestSearch(t), runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -131,24 +132,54 @@ func newTestPhotos(t *testing.T) *recipes.PhotoCache {
 // configured, over a migrated temp database and a random secret box.
 func newTestSearch(t *testing.T) *recipes.SearchSettingsService {
 	t.Helper()
-	key := make([]byte, secretbox.KeySize)
-	rand.Read(key)
-	box, err := secretbox.New(base64.StdEncoding.EncodeToString(key))
-	if err != nil {
-		t.Fatal(err)
-	}
-	search, err := recipes.NewSearchSettingsService(newTestStore(t), box)
+	search, err := recipes.NewSearchSettingsService(newTestStore(t), newTestBox(t))
 	if err != nil {
 		t.Fatal(err)
 	}
 	return search
 }
 
+// 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, 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, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil recipe search settings service")
 	}
 }
@@ -157,7 +188,7 @@ 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), newTestSearch(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -166,7 +197,7 @@ func TestNewRouterRequiresSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
@@ -175,7 +206,7 @@ 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), newTestSearch(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil job runner")
 	}
 }

internal/server/settings.go

@@ -9,14 +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 or
-// /settings/recipe-search request body.
+// /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 {
@@ -124,13 +131,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

@@ -216,7 +216,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),
-		newTestSearch(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

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,28 @@
-import { render, screen } from '@testing-library/react'
+import { act, 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 { 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 App, { routes } from './App.tsx'
 
 afterEach(() => {
   Reflect.deleteProperty(window, 'matchMedia')
+  vi.restoreAllMocks()
   vi.unstubAllGlobals()
 })
 
 function renderAt(path: string, location = fakeLocation(path)) {
-  render(
+  return { location, ...renderAppAt(path, location) }
+}
+
+function renderAppAt(path: string, location = fakeLocation(path)) {
+  return render(
     <MemoryRouter initialEntries={[path]}>
-      <App api={createApiClient(location)} />
+      <App api={createApiClient(location, createNetworkStatus(window), createVerifiedSession(localStorage))} serviceWorker={undefined} />
     </MemoryRouter>,
   )
-  return location
 }
 
 describe('App routes', () => {
@@ -70,7 +75,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 +85,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()
@@ -99,3 +104,93 @@ 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() {
+    stubFetch(jsonResponse(200, ME))
+    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)
+  })
+
+  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 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(
+      <MemoryRouter initialEntries={['/plan']}>
+        <App api={api} serviceWorker={undefined} />
+      </MemoryRouter>,
+    )
+    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 = stubFetch(jsonResponse(200, ME))
+    onLine = true
+    act(() => {
+      window.dispatchEvent(new Event('online'))
+    })
+    await vi.waitFor(() => expect(request(fetchMock, 0)).toMatchObject({ path: '/api/v1/me', method: 'GET' }))
+    await vi.waitFor(() => expect(screen.queryByRole('status')).toBeNull())
+    expect(screen.getByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+  })
+})

web/src/App.tsx

@@ -4,6 +4,8 @@ import { Route, Routes } from 'react-router'
 import { ApiProvider, createQueryClient, type ApiClient } from './api/index.ts'
 import { AuthBootstrap } from './AuthBootstrap.tsx'
 import { PlaceholderPage } from './pages/PlaceholderPage.tsx'
+import { OfflinePill } from './pwa/OfflinePill.tsx'
+import { UpdatePrompt, type UpdateContainer } from './pwa/UpdatePrompt.tsx'
 import { AppShell } from './shell/AppShell.tsx'
 
 // Every route the app serves, with the heading its placeholder page shows.
@@ -40,11 +42,17 @@ export function AppRoutes() {
 
 export type AppProps = {
   api: ApiClient
+  // navigator.serviceWorker, or undefined where there is none (and in tests).
+  serviceWorker: UpdateContainer | undefined
+}
+
+function reloadPage() {
+  window.location.reload()
 }
 
 // App expects to be rendered inside a router (BrowserRouter in main.tsx,
 // MemoryRouter in tests).
-export default function App({ api }: AppProps) {
+export default function App({ api, serviceWorker }: AppProps) {
   const [queryClient] = useState(createQueryClient)
   return (
     <ApiProvider client={api}>
@@ -52,6 +60,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}>

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/main.tsx

@@ -4,19 +4,20 @@ import { BrowserRouter } 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))
 
 createRoot(root).render(
   <StrictMode>
     <BrowserRouter>
-      <App api={api} />
+      <App api={api} serviceWorker={'serviceWorker' in navigator ? navigator.serviceWorker : undefined} />
     </BrowserRouter>
   </StrictMode>,
 )

web/src/pwa.test.ts

@@ -0,0 +1,157 @@
+// @vitest-environment node
+// Builds the app with the production config and serves the result, so the
+// assertions cover what ships in dist: the web manifest, the service worker,
+// every icon, and the service worker registration that only builds include.
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { build, createServer, preview, type PreviewServer, type ViteDevServer } from 'vite'
+import tokens from './styles/tokens.css?raw'
+
+const outDir = 'node_modules/.tmp/pwa-test-dist'
+
+const icons = [
+  { path: '/icons/icon-192.png', size: 192 },
+  { path: '/icons/icon-512.png', size: 512 },
+  { path: '/icons/icon-maskable-512.png', size: 512 },
+  { path: '/apple-touch-icon.png', size: 180 },
+]
+
+function token(name: string): string {
+  const value = tokens.match(new RegExp(`^\\s*${name}:\\s*([^;\\s]+);`, 'm'))?.[1]
+  if (!value) throw new Error(`${name} is not defined in tokens.css`)
+  return value
+}
+
+// Width and height from a PNG's IHDR chunk, which follows the 8-byte
+// signature, the chunk length and the chunk type.
+// The precache list vite-plugin-pwa injects into sw.js: a JSON array of
+// { revision, url } entries.
+function precacheEntries(sw: string): Array<{ revision: string | null; url: string }> {
+  const start = sw.indexOf('[{"revision":')
+  expect(start, 'injected precache list').toBeGreaterThanOrEqual(0)
+  return JSON.parse(sw.slice(start, sw.indexOf('}]', start) + 2))
+}
+
+function pngSize(bytes: Uint8Array): { width: number; height: number } {
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+  expect(Array.from(bytes.subarray(0, 8))).toEqual(signature)
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  return { width: view.getUint32(16), height: view.getUint32(20) }
+}
+
+describe('production build', () => {
+  let server: PreviewServer
+  let origin: string
+
+  async function get(path: string): Promise<Response> {
+    const response = await fetch(new URL(path, origin))
+    expect(response.status, path).toBe(200)
+    return response
+  }
+
+  beforeAll(async () => {
+    await build({ logLevel: 'error', build: { outDir, emptyOutDir: true } })
+    server = await preview({
+      logLevel: 'error',
+      build: { outDir },
+      preview: { port: 0, strictPort: false, host: '127.0.0.1' },
+    })
+    const url = server.resolvedUrls?.local[0]
+    if (!url) throw new Error('preview server did not report a URL')
+    origin = url
+  }, 60_000)
+
+  afterAll(async () => {
+    await server?.close()
+  })
+
+  it('emits manifest.webmanifest with the MealQuest identity', async () => {
+    const manifest = await (await get('/manifest.webmanifest')).json()
+    expect(manifest).toMatchObject({
+      name: 'MealQuest',
+      short_name: 'MealQuest',
+      start_url: '/',
+      scope: '/',
+      display: 'standalone',
+      // --color-accent and --color-bg hold the manifest colours; hex colours
+      // may not be written outside tokens.css.
+      theme_color: token('--color-accent'),
+      background_color: token('--color-bg'),
+    })
+    expect(manifest.icons).toEqual([
+      { 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',
+      },
+    ])
+  })
+
+  it.each(icons)('ships $path as a $size px square PNG', async ({ path, size }) => {
+    const bytes = new Uint8Array(await (await get(path)).arrayBuffer())
+    expect(pngSize(bytes)).toEqual({ width: size, height: size })
+  })
+
+  it('emits sw.js with the precache list injected', async () => {
+    const sw = await (await get('/sw.js')).text()
+    expect(sw).not.toContain('self.__WB_MANIFEST')
+    expect(sw).toContain('"url":"index.html"')
+    for (const { path } of icons.slice(0, 3)) {
+      expect(sw).toContain(`"url":"${path.slice(1)}"`)
+    }
+  })
+
+  it('precaches the shell, JS, CSS and every self-hosted font', async () => {
+    const entries = precacheEntries(await (await get('/sw.js')).text())
+    const urls = entries.map((entry) => entry.url)
+    // index.html keeps its URL across builds, so it carries a content
+    // revision; the other assets have content hashes in their names.
+    expect(entries.find((entry) => entry.url === 'index.html')?.revision).toMatch(/^[0-9a-f]{32}$/)
+    expect(urls.some((url) => url.endsWith('.js'))).toBe(true)
+    expect(urls.some((url) => url.endsWith('.css'))).toBe(true)
+    for (const font of [
+      'BagelFatOne-LatinExt',
+      'BagelFatOne-Latin',
+      'Figtree-Regular',
+      'Figtree-SemiBold',
+      'Figtree-Bold',
+    ]) {
+      expect(urls.some((url) => url.startsWith(`assets/${font}`) && url.endsWith('.woff2'))).toBe(true)
+    }
+  })
+
+  it('links the manifest, theme colour and apple-touch-icon from index.html', async () => {
+    const html = await (await get('/')).text()
+    expect(html.match(/<link rel="manifest" href="\/manifest\.webmanifest">/g)).toHaveLength(1)
+    expect(html).toContain(`<meta name="theme-color" content="${token('--color-accent')}" />`)
+    expect(html).toContain('<link rel="apple-touch-icon" href="/apple-touch-icon.png" />')
+  })
+
+  it('registers /sw.js at scope / from index.html', async () => {
+    const html = await (await get('/')).text()
+    expect(html).toContain('<script id="vite-plugin-pwa:register-sw" src="/registerSW.js"></script>')
+    const register = await (await get('/registerSW.js')).text()
+    expect(register).toContain("navigator.serviceWorker.register('/sw.js', { scope: '/' })")
+  })
+})
+
+describe('dev server', () => {
+  let server: ViteDevServer
+
+  beforeAll(async () => {
+    server = await createServer({ logLevel: 'error', server: { middlewareMode: true } })
+  })
+
+  afterAll(async () => {
+    await server?.close()
+  })
+
+  it('does not register a service worker', async () => {
+    const html = await server.transformIndexHtml('/', '<html><head></head><body></body></html>')
+    expect(html).not.toContain('registerSW')
+    expect(html).not.toContain('serviceWorker')
+    expect(html).not.toContain('rel="manifest"')
+  })
+})

web/src/pwa/InstallHint.module.css

@@ -0,0 +1,18 @@
+.hint {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.icon {
+  color: var(--color-accent);
+}
+
+.message {
+  flex: 1;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+}

web/src/pwa/InstallHint.test.tsx

@@ -0,0 +1,146 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { DISMISSED_KEY, InstallHint } from './InstallHint.tsx'
+
+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 IPAD_SAFARI =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Safari/605.1.15'
+const MAC_SAFARI = IPAD_SAFARI
+const IPHONE_CHROME =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/138.0.7204.119 Mobile/15E148 Safari/604.1'
+const IPHONE_FIREFOX =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/141.0 Mobile/15E148 Safari/605.1.15'
+const IPHONE_EDGE =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 EdgiOS/138.3351.83 Mobile/15E148 Safari/605.1.15'
+const IPHONE_OPERA =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1 OPT/5.4.0'
+const IPHONE_MQQBROWSER =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 MQQBrowser/11.3.5 Mobile/15E148 Safari/604.1'
+const ANDROID_CHROME =
+  'Mozilla/5.0 (Linux; Android 15; Pixel 9) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Mobile Safari/537.36'
+const DESKTOP_CHROME =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36'
+
+const copy = 'Tap Share, then Add to Home Screen to get notifications'
+
+type Device = {
+  userAgent: string
+  maxTouchPoints?: number
+  // display-mode: standalone
+  displayStandalone?: boolean
+  // navigator.standalone (Safari only; undefined elsewhere)
+  navigatorStandalone?: boolean
+}
+
+// mockDevice pretends to be a browser with the given user agent and
+// display mode; jsdom has no matchMedia, navigator.maxTouchPoints or
+// navigator.standalone.
+function mockDevice({ userAgent, maxTouchPoints = 0, displayStandalone = false, navigatorStandalone }: Device) {
+  vi.spyOn(navigator, 'userAgent', 'get').mockReturnValue(userAgent)
+  Object.defineProperty(navigator, 'maxTouchPoints', { configurable: true, value: maxTouchPoints })
+  Object.defineProperty(navigator, 'standalone', { configurable: true, value: navigatorStandalone })
+  vi.stubGlobal('matchMedia', (query: string) => {
+    if (query !== '(display-mode: standalone)') throw new Error(`unexpected media query ${query}`)
+    return { matches: displayStandalone, media: query } as MediaQueryList
+  })
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(navigator, 'maxTouchPoints')
+  Reflect.deleteProperty(navigator, 'standalone')
+  localStorage.clear()
+})
+
+describe('InstallHint', () => {
+  it('shows on iPhone Safari in a browser tab', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+  })
+
+  it('shows on iPadOS Safari, which reports itself as a Mac with a touch screen', () => {
+    mockDevice({ userAgent: IPAD_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+  })
+
+  it('is hidden when navigator.standalone is true', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: true })
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('is hidden when display-mode is standalone', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, displayStandalone: true })
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it.each([
+    ['Android Chrome', { userAgent: ANDROID_CHROME, maxTouchPoints: 5 }],
+    ['desktop Chrome', { userAgent: DESKTOP_CHROME }],
+    ['desktop Safari on a Mac', { userAgent: MAC_SAFARI }],
+    ['Chrome on iPhone', { userAgent: IPHONE_CHROME, maxTouchPoints: 5 }],
+    ['Firefox on iPhone', { userAgent: IPHONE_FIREFOX, maxTouchPoints: 5 }],
+    ['Edge on iPhone', { userAgent: IPHONE_EDGE, maxTouchPoints: 5 }],
+    ['Opera on iPhone', { userAgent: IPHONE_OPERA, maxTouchPoints: 5 }],
+    ['MQQBrowser on iPhone', { userAgent: IPHONE_MQQBROWSER, maxTouchPoints: 5 }],
+  ])('is hidden on %s', (_name, device: Device) => {
+    mockDevice(device)
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('stays dismissed on this device', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const first = render(<InstallHint />)
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(screen.queryByRole('note')).toBeNull()
+    expect(localStorage.getItem(DISMISSED_KEY)).toBe('1')
+
+    first.unmount()
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('stays up and reports the error when the dismissal cannot be saved', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const setItem = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('quota exceeded', 'QuotaExceededError')
+    })
+
+    render(<InstallHint />)
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      'Could not remember on this device that this hint was dismissed: QuotaExceededError: quota exceeded',
+    )
+
+    setItem.mockRestore()
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(screen.queryByRole('note')).toBeNull()
+    expect(screen.queryByRole('alert')).toBeNull()
+    expect(localStorage.getItem(DISMISSED_KEY)).toBe('1')
+  })
+
+  it('shows and reports the error when storage cannot be read', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const getItem = vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new DOMException('storage blocked', 'SecurityError')
+    })
+
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      'Could not check whether this hint was dismissed on this device: SecurityError: storage blocked',
+    )
+
+    getItem.mockRestore()
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+})

web/src/pwa/InstallHint.tsx

@@ -0,0 +1,97 @@
+import { useState } from 'react'
+import { Share, X } from 'lucide-react'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import styles from './InstallHint.module.css'
+
+// DISMISSED_KEY is the localStorage key remembering, on this device, that the
+// household dismissed the hint.
+export const DISMISSED_KEY = 'mealquest.installHint.dismissed'
+
+// Safari's user agent ends "(KHTML, like Gecko) Version/<v> Mobile/<build>
+// Safari/<v>" (iPadOS leaves out Mobile/). Every other iOS browser and in-app
+// web view adds its own token (CriOS, FxiOS, EdgiOS, OPiOS, MQQBrowser, GSA,
+// ...) or drops Version/ or Safari/, so only this exact tail is Safari.
+const SAFARI_TAIL = /\(KHTML, like Gecko\) Version\/[\d.]+ (?:Mobile\/\w+ )?Safari\/[\d.]+$/
+
+// isIosSafari reports whether the page is open in Safari on iPhone, iPod or
+// iPad. iPadOS 13+ asks for the desktop site and reports itself as a Mac, so
+// a "Macintosh" with a touch screen is an iPad.
+export function isIosSafari(nav: Pick<Navigator, 'userAgent' | 'maxTouchPoints'>): boolean {
+  const ua = nav.userAgent
+  const ios = /iPhone|iPod|iPad/.test(ua) || (/Macintosh/.test(ua) && nav.maxTouchPoints > 1)
+  return ios && SAFARI_TAIL.test(ua)
+}
+
+// isStandalone reports whether the app is running from the Home Screen.
+// Safari sets navigator.standalone; other browsers answer the display-mode
+// media query.
+export function isStandalone(): boolean {
+  const legacy = (navigator as Navigator & { standalone?: boolean }).standalone
+  return legacy === true || window.matchMedia('(display-mode: standalone)').matches
+}
+
+// HintState is whether the household dismissed the hint on this device, and
+// the storage failure, if any, that stopped us reading or saving that.
+type HintState = {
+  dismissed: boolean
+  failure: { action: 'read' | 'write'; message: string } | null
+}
+
+// Storage can be unavailable (blocked by the browser or privacy settings), in
+// which case using it throws. The failure is reported, never treated as a
+// remembered dismissal.
+function readDismissed(): HintState {
+  try {
+    return { dismissed: window.localStorage.getItem(DISMISSED_KEY) === '1', failure: null }
+  } catch (err) {
+    return { dismissed: false, failure: { action: 'read', message: String(err) } }
+  }
+}
+
+function writeDismissed(): HintState {
+  try {
+    window.localStorage.setItem(DISMISSED_KEY, '1')
+    return { dismissed: true, failure: null }
+  } catch (err) {
+    return { dismissed: false, failure: { action: 'write', message: String(err) } }
+  }
+}
+
+const failureText = {
+  read: 'Could not check whether this hint was dismissed on this device',
+  write: 'Could not remember on this device that this hint was dismissed',
+}
+
+// InstallHint tells iOS and iPadOS Safari users how to install the app, which
+// iOS requires before it delivers Web Push. It shows only in a Safari browser
+// tab, never once installed, and stays dismissed on this device. If storage
+// fails, the hint stays up with an error saying so. Used by onboarding step 3
+// and the Notifications screen.
+export function InstallHint() {
+  const [eligible] = useState(() => isIosSafari(navigator) && !isStandalone())
+  const [state, setState] = useState<HintState>(() =>
+    eligible ? readDismissed() : { dismissed: false, failure: null },
+  )
+  if (!eligible || state.dismissed) return null
+
+  const { failure } = state
+  return (
+    <>
+      <Card tone="muted" role="note" className={styles.hint}>
+        <Icon icon={Share} className={styles.icon} />
+        <p className={styles.message}>Tap Share, then Add to Home Screen to get notifications</p>
+        <IconButton label="Dismiss" onClick={() => setState(writeDismissed())}>
+          <Icon icon={X} />
+        </IconButton>
+      </Card>
+      {failure && (
+        <ErrorBanner onRetry={() => setState(failure.action === 'read' ? readDismissed() : writeDismissed())}>
+          {failureText[failure.action]}: {failure.message}
+        </ErrorBanner>
+      )}
+    </>
+  )
+}

web/src/pwa/OfflinePill.module.css

@@ -0,0 +1,22 @@
+.pill {
+  position: fixed;
+  top: calc(var(--space-3) + env(safe-area-inset-top));
+  left: 50%;
+  z-index: 20;
+  transform: translateX(-50%);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin: 0;
+  padding: 6px 14px;
+  border-radius: var(--radius-pill);
+  background: var(--color-neutral-800);
+  color: var(--on-accent);
+  box-shadow: var(--shadow-md);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+  line-height: 1.2;
+  white-space: nowrap;
+  pointer-events: none;
+}

web/src/pwa/OfflinePill.test.tsx

@@ -0,0 +1,150 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiProvider, createApiClient, createVerifiedSession, type ApiClient } from '../api/index.ts'
+import { fakeLocation, jsonResponse, ME, stubFetch } from '../test/fetchStub.ts'
+import { cacheFallbackHeader } from '../sw/routes.ts'
+import { createNetworkStatus } from './networkStatus.ts'
+import { OfflinePill } from './OfflinePill.tsx'
+
+const copy = 'Offline — showing saved data'
+
+let onLine: boolean
+
+beforeEach(() => {
+  onLine = true
+  vi.spyOn(navigator, 'onLine', 'get').mockImplementation(() => onLine)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+function goOffline() {
+  onLine = false
+  window.dispatchEvent(new Event('offline'))
+}
+
+function goOnline() {
+  onLine = true
+  window.dispatchEvent(new Event('online'))
+}
+
+function renderPill(): ApiClient {
+  const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+  render(
+    <ApiProvider client={api}>
+      <OfflinePill />
+    </ApiProvider>,
+  )
+  return api
+}
+
+describe('OfflinePill', () => {
+  it('is hidden while online', () => {
+    renderPill()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows while the browser is offline when it renders', () => {
+    onLine = false
+    renderPill()
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('appears on the offline event and disappears on the online event', () => {
+    renderPill()
+    act(goOffline)
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+    act(goOnline)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('appears when a request fails with a network error', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow(TypeError))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+
+    act(goOnline)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('disappears when a later request gets a response', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow(TypeError))
+    expect(screen.getByRole('status')).toBeInTheDocument()
+
+    stubFetch(jsonResponse(200, {}))
+    await act(() => api.apiFetch('/api/v1/plan'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows while online when the service worker answers from its cache', async () => {
+    const api = renderPill()
+    const cached = jsonResponse(200, { id: '01J9ZR' })
+    cached.headers.set(cacheFallbackHeader, '1')
+    stubFetch(cached, jsonResponse(200, { id: '01J9ZR' }))
+
+    await act(() => api.apiFetch('/api/v1/recipes/01J9ZR'))
+    expect(navigator.onLine).toBe(true)
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+
+    // The server answers again.
+    await act(() => api.apiFetch('/api/v1/recipes/01J9ZR'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores a request body that cannot be serialized', async () => {
+    const api = renderPill()
+    const fetchMock = stubFetch(jsonResponse(200, ME))
+    await act(() => api.loadMe())
+    const body: Record<string, unknown> = {}
+    body.self = body
+
+    await act(() =>
+      expect(api.apiFetch('/api/v1/plan', { method: 'PUT', body })).rejects.toThrow(
+        'PUT /api/v1/plan: request body is not serializable as JSON',
+      ),
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores a GET request with a body, which fetch would refuse to send', async () => {
+    const api = renderPill()
+    const fetchMock = stubFetch()
+
+    await act(() =>
+      expect(api.apiFetch('/api/v1/plan', { body: { week: 1 } })).rejects.toThrow(
+        'GET /api/v1/plan: a GET request cannot carry a body',
+      ),
+    )
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores an aborted request', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new DOMException('aborted', 'AbortError')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow('aborted'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('removes its online and offline listeners on unmount', () => {
+    const add = vi.spyOn(window, 'addEventListener')
+    const remove = vi.spyOn(window, 'removeEventListener')
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+    const { unmount } = render(
+      <ApiProvider client={api}>
+        <OfflinePill />
+      </ApiProvider>,
+    )
+    const added = add.mock.calls.filter(([type]) => type === 'online' || type === 'offline')
+    expect(added.map(([type]) => type).sort()).toEqual(['offline', 'online'])
+
+    unmount()
+    for (const [type, listener] of added) expect(remove).toHaveBeenCalledWith(type, listener)
+  })
+})

web/src/pwa/OfflinePill.tsx

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from 'react'
+import { WifiOff } from 'lucide-react'
+import { useApi } from '../api/index.ts'
+import { Icon } from '../ui/Icon.tsx'
+import styles from './OfflinePill.module.css'
+
+// OfflinePill tells the household that what they see came from the cache
+// while the browser is offline or the server cannot be reached.
+export function OfflinePill() {
+  const { network } = useApi()
+  const offline = useSyncExternalStore(network.subscribe, network.offline)
+  if (!offline) return null
+  return (
+    <p role="status" className={styles.pill}>
+      <Icon icon={WifiOff} />
+      Offline — showing saved data
+    </p>
+  )
+}

web/src/pwa/UpdatePrompt.module.css

@@ -0,0 +1,22 @@
+.toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(110px + env(safe-area-inset-bottom));
+  z-index: 20;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  width: max-content;
+  max-width: calc(100vw - 2 * var(--space-4));
+  padding: var(--space-2) var(--space-2) var(--space-2) var(--space-4);
+  box-shadow: var(--shadow-lg);
+}
+
+.message {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+}

web/src/pwa/UpdatePrompt.test.tsx

@@ -0,0 +1,165 @@
+import { act, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { SKIP_WAITING, UpdatePrompt, type UpdateContainer } from './UpdatePrompt.tsx'
+
+// FakeWorker is a ServiceWorker whose state the test moves along.
+class FakeWorker extends EventTarget {
+  state: ServiceWorkerState = 'installing'
+  postMessage = vi.fn()
+  setState(state: ServiceWorkerState) {
+    this.state = state
+    this.dispatchEvent(new Event('statechange'))
+  }
+}
+
+class FakeRegistration extends EventTarget {
+  installing: FakeWorker | null = null
+  waiting: FakeWorker | null = null
+  // install starts a new worker, as the browser does on finding an update.
+  install(): FakeWorker {
+    const worker = new FakeWorker()
+    this.installing = worker
+    this.dispatchEvent(new Event('updatefound'))
+    return worker
+  }
+  // finishInstall moves the installing worker to waiting.
+  finishInstall(worker: FakeWorker) {
+    this.installing = null
+    this.waiting = worker
+    worker.setState('installed')
+  }
+}
+
+class FakeContainer extends EventTarget {
+  controller: object | null = {}
+  registration = new FakeRegistration()
+  ready = Promise.resolve(this.registration)
+  // takeOver makes the waiting worker the controller.
+  takeOver() {
+    const worker = this.registration.waiting
+    this.registration.waiting = null
+    this.controller = worker
+    worker?.setState('activated')
+    this.dispatchEvent(new Event('controllerchange'))
+  }
+}
+
+async function renderPrompt(container: FakeContainer | undefined) {
+  const reload = vi.fn()
+  const view = render(<UpdatePrompt container={container as unknown as UpdateContainer} reload={reload} />)
+  await act(async () => {
+    await container?.ready
+  })
+  return { reload, ...view }
+}
+
+const copy = 'New version ready · Reload'
+
+describe('UpdatePrompt', () => {
+  it('shows nothing without a service worker', async () => {
+    await renderPrompt(undefined)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows nothing while no worker is waiting', async () => {
+    const container = new FakeContainer()
+    await renderPrompt(container)
+    act(() => {
+      container.registration.install()
+    })
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows nothing for a waiting worker when the page has no controller', async () => {
+    const container = new FakeContainer()
+    container.controller = null
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows the toast for a worker already waiting when the page loads', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('shows the toast when an update finishes installing', async () => {
+    const container = new FakeContainer()
+    await renderPrompt(container)
+    act(() => container.registration.finishInstall(container.registration.install()))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('sends SKIP_WAITING on Reload and reloads once the new worker controls the page', async () => {
+    const container = new FakeContainer()
+    const { reload } = await renderPrompt(container)
+    const worker = container.registration.install()
+    act(() => container.registration.finishInstall(worker))
+
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+    expect(worker.postMessage).toHaveBeenCalledExactlyOnceWith(SKIP_WAITING)
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(reload).not.toHaveBeenCalled()
+
+    act(() => container.takeOver())
+    expect(reload).toHaveBeenCalledOnce()
+    // A later controller change (another tab's update) does not reload again.
+    act(() => container.dispatchEvent(new Event('controllerchange')))
+    expect(reload).toHaveBeenCalledOnce()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('does not reappear for the worker the household chose to reload into', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+    // The worker reports another state change before it takes over.
+    act(() => container.registration.waiting?.setState('installed'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('hides when dismissed until the next update is waiting', async () => {
+    const container = new FakeContainer()
+    const { reload } = await renderPrompt(container)
+    const first = container.registration.install()
+    act(() => container.registration.finishInstall(first))
+
+    act(() => screen.getByRole('button', { name: 'Dismiss' }).click())
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(first.postMessage).not.toHaveBeenCalled()
+    act(() => first.setState('installed'))
+    expect(screen.queryByRole('status')).toBeNull()
+
+    act(() => container.registration.finishInstall(container.registration.install()))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+    expect(reload).not.toHaveBeenCalled()
+  })
+
+  it('hides when another tab activates the waiting worker', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    const { reload } = await renderPrompt(container)
+    act(() => container.takeOver())
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(reload).not.toHaveBeenCalled()
+  })
+
+  it('removes its listeners on unmount', async () => {
+    const container = new FakeContainer()
+    const worker = new FakeWorker()
+    container.registration.waiting = worker
+    const { reload, unmount } = await renderPrompt(container)
+    const removeRegistration = vi.spyOn(container.registration, 'removeEventListener')
+    const removeWorker = vi.spyOn(worker, 'removeEventListener')
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+
+    unmount()
+    expect(removeRegistration).toHaveBeenCalledWith('updatefound', expect.any(Function))
+    expect(removeWorker).toHaveBeenCalledWith('statechange', expect.any(Function))
+    container.takeOver()
+    expect(reload).not.toHaveBeenCalled()
+  })
+})

web/src/pwa/UpdatePrompt.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react'
+import { X } from 'lucide-react'
+import { Button } from '../ui/Button.tsx'
+import { Card } from '../ui/Card.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import styles from './UpdatePrompt.module.css'
+
+// UpdateContainer is the part of navigator.serviceWorker the prompt uses.
+export type UpdateContainer = Pick<ServiceWorkerContainer, 'ready' | 'controller' | 'addEventListener' | 'removeEventListener'>
+
+export type UpdatePromptProps = {
+  // navigator.serviceWorker, or undefined where the browser has none.
+  container: UpdateContainer | undefined
+  // Reloads the page once the new worker controls it.
+  reload: () => void
+}
+
+// SKIP_WAITING is the message src/sw.ts answers by activating the waiting
+// worker.
+export const SKIP_WAITING = { type: 'SKIP_WAITING' } as const
+
+// UpdatePrompt offers to reload when a new service worker is installed and
+// waiting to replace the one controlling the page. Reload asks the waiting
+// worker to activate and reloads once it controls the page; dismissing hides
+// the prompt until a different worker is waiting.
+export function UpdatePrompt({ container, reload }: UpdatePromptProps) {
+  const [waiting, setWaiting] = useState<ServiceWorker | null>(null)
+  const [dismissed, setDismissed] = useState<ServiceWorker | null>(null)
+  const [accepted, setAccepted] = useState<ServiceWorker | null>(null)
+  const reloadListener = useRef<(() => void) | null>(null)
+
+  useEffect(() => {
+    if (container === undefined) return
+    const sw = container
+    let registration: ServiceWorkerRegistration | null = null
+    let unmounted = false
+    const watched = new Set<ServiceWorker>()
+
+    // A waiting worker only replaces something when the page has a
+    // controller; without one there is no controllerchange to reload on.
+    function check() {
+      if (registration === null) return
+      setWaiting(sw.controller === null ? null : registration.waiting)
+    }
+    function watch(worker: ServiceWorker | null) {
+      if (worker === null || watched.has(worker)) return
+      watched.add(worker)
+      worker.addEventListener('statechange', check)
+    }
+    function updateFound() {
+      watch(registration?.installing ?? null)
+    }
+
+    void sw.ready.then((ready) => {
+      if (unmounted) return
+      registration = ready
+      ready.addEventListener('updatefound', updateFound)
+      watch(ready.installing)
+      watch(ready.waiting)
+      check()
+    })
+    return () => {
+      unmounted = true
+      registration?.removeEventListener('updatefound', updateFound)
+      watched.forEach((worker) => worker.removeEventListener('statechange', check))
+      if (reloadListener.current !== null) {
+        sw.removeEventListener('controllerchange', reloadListener.current)
+        reloadListener.current = null
+      }
+    }
+  }, [container])
+
+  if (container === undefined || waiting === null || waiting === dismissed || waiting === accepted) return null
+
+  function update() {
+    if (container === undefined || waiting === null || reloadListener.current !== null) return
+    const listener = () => {
+      reloadListener.current = null
+      reload()
+    }
+    reloadListener.current = listener
+    container.addEventListener('controllerchange', listener, { once: true })
+    setAccepted(waiting)
+    waiting.postMessage(SKIP_WAITING)
+  }
+
+  return (
+    <Card role="status" className={styles.toast}>
+      <p className={styles.message}>
+        New version ready <span aria-hidden="true">·</span>
+      </p>
+      {/* The space keeps the copy "New version ready · Reload" in the text;
+          a flex container does not render it. */}{' '}
+      <Button onClick={update}>Reload</Button>
+      <IconButton label="Dismiss" onClick={() => setDismissed(waiting)}>
+        <Icon icon={X} />
+      </IconButton>
+    </Card>
+  )
+}

web/src/pwa/networkStatus.ts

@@ -0,0 +1,51 @@
+// NetworkWindow is the part of window the network status reads: the browser's
+// online flag and its online/offline events.
+export type NetworkWindow = Pick<Window, 'navigator' | 'addEventListener' | 'removeEventListener'>
+
+export type NetworkStatus = {
+  // offline reports whether the browser says it is offline or the last API
+  // request failed with a network error or was answered from the cache.
+  offline(): boolean
+  // subscribe is notified when offline may have changed. It listens for the
+  // window's online/offline events until the returned function is called.
+  subscribe(listener: () => void): () => void
+  // requestFailed records a fetch that rejected with a network error or that
+  // the service worker answered from its cache.
+  requestFailed(): void
+  // requestSucceeded records a fetch the server answered.
+  requestSucceeded(): void
+}
+
+// createNetworkStatus tracks whether MealQuest can reach the server. A failed
+// request counts as offline until a later request gets a response or the
+// browser reports that it is back online.
+export function createNetworkStatus(win: NetworkWindow): NetworkStatus {
+  let failed = false
+  const listeners = new Set<() => void>()
+
+  function setFailed(value: boolean) {
+    if (failed === value) return
+    failed = value
+    listeners.forEach((listener) => listener())
+  }
+
+  return {
+    offline: () => !win.navigator.onLine || failed,
+    subscribe(listener) {
+      const online = () => {
+        failed = false
+        listener()
+      }
+      listeners.add(listener)
+      win.addEventListener('online', online)
+      win.addEventListener('offline', listener)
+      return () => {
+        listeners.delete(listener)
+        win.removeEventListener('online', online)
+        win.removeEventListener('offline', listener)
+      }
+    },
+    requestFailed: () => setFailed(true),
+    requestSucceeded: () => setFailed(false),
+  }
+}

web/src/sw.ts

@@ -0,0 +1,115 @@
+// MealQuest service worker. vite-plugin-pwa replaces self.__WB_MANIFEST with
+// the build's precache list (shell, JS, CSS and fonts, each with a revision).
+// Every other request goes through the route src/sw/routes.ts decides.
+// A network-only request is left to the browser: the worker never answers it,
+// so it reaches the network exactly as the page sent it. That matters for
+// POST /auth/logout, whose Clear-Site-Data header wipes the worker and its
+// caches — Chrome stalls that navigation when the worker answers it.
+// Fonts are precached too, but their route is registered ahead of the
+// precache route, so a font fetch goes through the expiring CacheFirst
+// strategy and falls back to the precached copy when the network fails.
+
+import { cacheNames as workboxCacheNames, setCacheNameDetails } from 'workbox-core'
+import type { RouteHandlerCallbackOptions } from 'workbox-core/types'
+import { ExpirationPlugin } from 'workbox-expiration'
+import { PrecacheFallbackPlugin, matchPrecache, precacheAndRoute } from 'workbox-precaching'
+import { registerRoute } from 'workbox-routing'
+import { CacheFirst, NetworkOnly, type Strategy } from 'workbox-strategies'
+import { createApiStrategy } from './sw/apiStrategy'
+import {
+  cacheNames,
+  cacheVersion,
+  routeFor,
+  staleCaches,
+  type Route,
+} from './sw/routes'
+
+declare const self: ServiceWorkerGlobalScope & {
+  __WB_MANIFEST: Array<{ url: string; revision: string | null }>
+}
+
+// The precache becomes mealquest-precache-v1.
+setCacheNameDetails({ prefix: 'mealquest', precache: 'precache', suffix: cacheVersion })
+
+const day = 24 * 60 * 60
+
+const strategies = {
+  [cacheNames.api]: createApiStrategy(),
+  [cacheNames.media]: new CacheFirst({
+    cacheName: cacheNames.media,
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 200, maxAgeSeconds: 30 * day, purgeOnQuotaError: true }),
+    ],
+  }),
+  [cacheNames.fonts]: new CacheFirst({
+    cacheName: cacheNames.fonts,
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 20, maxAgeSeconds: 365 * day, purgeOnQuotaError: true }),
+      // Offline with no runtime copy yet: the font from the precache.
+      { handlerDidError: async ({ request }) => matchPrecache(request.url) },
+    ],
+  }),
+}
+const navigation = new NetworkOnly({
+  plugins: [new PrecacheFallbackPlugin({ fallbackURL: 'index.html' })],
+})
+
+type AnsweredRoute = Exclude<Route, { strategy: 'network-only' }>
+
+function strategyFor(route: AnsweredRoute): Strategy {
+  switch (route.strategy) {
+    case 'network-first':
+    case 'cache-first':
+      return strategies[route.cacheName]
+    case 'navigation-fallback':
+      return navigation
+  }
+}
+
+function routeOf({ request, url }: { request: Request; url: URL }): Route {
+  return routeFor({ method: request.method, url, mode: request.mode }, self.location.origin)
+}
+
+// answered matches every request the worker answers: all but network-only.
+function answered(options: { request: Request; url: URL }): boolean {
+  return routeOf(options).strategy !== 'network-only'
+}
+
+function handle({ request, url, event }: RouteHandlerCallbackOptions): Promise<Response> {
+  const route = routeOf({ request, url })
+  if (route.strategy === 'network-only') {
+    throw new Error(`the worker never answers network-only ${request.method} ${url.href}`)
+  }
+  return strategyFor(route).handle({ request, event })
+}
+
+function isFont(options: { request: Request; url: URL }): boolean {
+  const route = routeOf(options)
+  return route.strategy === 'cache-first' && route.cacheName === cacheNames.fonts
+}
+
+// Workbox uses the first route that matches, so the font route comes before
+// the precache route, which would otherwise answer every precached font.
+registerRoute(isFont, handle, 'GET')
+precacheAndRoute(self.__WB_MANIFEST)
+
+// Workbox routes are per method; every method goes through routeFor, which
+// sends every non-GET to the network only, so only GETs are ever answered.
+for (const method of ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'] as const) {
+  registerRoute(answered, handle, method)
+}
+
+self.addEventListener('activate', (event) => {
+  const current = [workboxCacheNames.precache, ...Object.values(cacheNames)]
+  event.waitUntil(
+    caches
+      .keys()
+      .then((names) => Promise.all(staleCaches(names, current).map((name) => caches.delete(name)))),
+  )
+})
+
+// The update prompt (src/pwa/UpdatePrompt.tsx) asks a waiting worker to take
+// over when the household chooses Reload.
+self.addEventListener('message', (event) => {
+  if (event.data?.type === 'SKIP_WAITING') void self.skipWaiting()
+})

web/src/sw/apiStrategy.test.ts

@@ -0,0 +1,165 @@
+// Runs the real Workbox network-first strategy against an in-memory cache
+// storage: jsdom has none, and the worker itself needs service worker globals.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { RouteHandlerCallbackOptions } from 'workbox-core/types'
+import { createApiClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { fakeLocation, jsonResponse } from '../test/fetchStub.ts'
+import { createApiStrategy } from './apiStrategy'
+import { cacheFallbackHeader, cacheNames, routeFor } from './routes'
+
+const origin = 'https://mealquest.test'
+
+// FakeCache keys entries by URL, which is all the API cache needs.
+class FakeCache {
+  readonly entries = new Map<string, Response>()
+  async match(request: RequestInfo | URL): Promise<Response | undefined> {
+    return this.entries.get(new Request(request).url)?.clone()
+  }
+  async put(request: RequestInfo | URL, response: Response): Promise<void> {
+    this.entries.set(new Request(request).url, response)
+  }
+}
+
+// FakeExtendableEvent stands in for the worker-only ExtendableEvent,
+// collecting the promises the strategy waits on.
+class FakeExtendableEvent extends Event {
+  readonly pending: Promise<unknown>[] = []
+  waitUntil(promise: Promise<unknown>) {
+    this.pending.push(promise)
+  }
+}
+
+let cache: FakeCache
+
+beforeEach(() => {
+  cache = new FakeCache()
+  // Workbox checks its arguments against these worker-only globals.
+  vi.stubGlobal('FetchEvent', class FetchEvent {})
+  vi.stubGlobal('ExtendableEvent', FakeExtendableEvent)
+  const only = (name: string | undefined) => {
+    if (name !== cacheNames.api) throw new Error(`unexpected cache ${name}`)
+    return cache
+  }
+  vi.stubGlobal('caches', {
+    open: async (name: string) => only(name),
+    match: async (request: RequestInfo | URL, options?: MultiCacheQueryOptions) =>
+      only(options?.cacheName).match(request),
+  })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+// handle sends a GET through the API strategy, as src/sw.ts does for a
+// network-first route.
+async function handle(path: string): Promise<Response> {
+  return answer(new Request(new URL(path, origin)))
+}
+
+async function answer(request: Request): Promise<Response> {
+  expect(routeFor({ method: request.method, url: new URL(request.url), mode: 'cors' }, origin)).toEqual({
+    strategy: 'network-first',
+    cacheName: cacheNames.api,
+  })
+  const event = new FakeExtendableEvent('fetch')
+  const response = await createApiStrategy().handle({ request, event: event as unknown as RouteHandlerCallbackOptions['event'] })
+  await Promise.all(event.pending)
+  return response
+}
+
+function recipe(): Response {
+  return new Response(JSON.stringify({ id: '01J9ZR', name: 'Chicken tikka masala' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+describe('API strategy', () => {
+  it('answers from the network while the server is reachable, unmarked', async () => {
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(recipe()))
+    const response = await handle('/api/v1/recipes/01J9ZR')
+    expect(response.headers.has(cacheFallbackHeader)).toBe(false)
+    expect(await response.json()).toMatchObject({ id: '01J9ZR' })
+    expect(cache.entries.has(`${origin}/api/v1/recipes/01J9ZR`)).toBe(true)
+  })
+
+  it('opens a previously viewed recipe offline, marked as a cache fallback', async () => {
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(recipe()))
+    await handle('/api/v1/recipes/01J9ZR')
+
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    const response = await handle('/api/v1/recipes/01J9ZR')
+    expect(response.headers.get(cacheFallbackHeader)).toBe('1')
+    expect(await response.json()).toEqual({ id: '01J9ZR', name: 'Chicken tikka masala' })
+  })
+
+  it('fails offline for a recipe never viewed', async () => {
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await expect(handle('/api/v1/recipes/01J9ZS')).rejects.toThrow()
+  })
+})
+
+describe('previously viewed plan and recipe reads', () => {
+  const plan = { week: '2026-W40', days: [{ date: '2026-10-05', dinner: 'Chicken tikka masala' }] }
+  const recipe = { id: '01J9ZR', name: 'Chicken tikka masala', steps: ['Marinate', 'Simmer'] }
+  const server: Record<string, unknown> = { '/api/v1/plans/2026-W40': plan, '/api/v1/recipes/01J9ZR': recipe }
+  let reachable: boolean
+
+  // The page's fetch goes through the worker's API strategy; the strategy's
+  // own fetch (always a Request) is the network. The API client fetches a
+  // path string, so the two are told apart by the argument's type. As in a
+  // browser, a worker that cannot answer is a network error to the page.
+  beforeEach(() => {
+    reachable = true
+    vi.spyOn(navigator, 'onLine', 'get').mockImplementation(() => reachable)
+    vi.stubGlobal('fetch', async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (!(input instanceof Request)) {
+        return answer(new Request(new URL(String(input), origin), init)).catch((error: unknown) => {
+          throw new TypeError('Failed to fetch', { cause: error })
+        })
+      }
+      if (!reachable) throw new TypeError('Failed to fetch')
+      const body = server[new URL(input.url).pathname]
+      if (body === undefined) throw new Error(`unexpected network fetch: ${input.url}`)
+      return jsonResponse(200, body)
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  function client() {
+    return createApiClient(fakeLocation('/plan'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  }
+
+  it('serves the plan and recipe fetched online once the network is gone', async () => {
+    const online = client()
+    expect(await online.apiFetch('/api/v1/plans/2026-W40')).toEqual(plan)
+    expect(await online.apiFetch('/api/v1/recipes/01J9ZR')).toEqual(recipe)
+    expect(online.network.offline()).toBe(false)
+
+    reachable = false
+    const offline = client()
+    expect(await offline.apiFetch('/api/v1/plans/2026-W40')).toEqual(plan)
+    expect(await offline.apiFetch('/api/v1/recipes/01J9ZR')).toEqual(recipe)
+    expect(offline.network.offline()).toBe(true)
+  })
+
+  it('shows the offline indicator when the cached copy answers while the browser reports online', async () => {
+    await client().apiFetch('/api/v1/plans/2026-W40')
+
+    vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true)
+    reachable = false
+    const api = client()
+    expect(await api.apiFetch('/api/v1/plans/2026-W40')).toEqual(plan)
+    expect(api.network.offline()).toBe(true)
+  })
+
+  it('fails offline for a plan never fetched', async () => {
+    reachable = false
+    await expect(client().apiFetch('/api/v1/plans/2026-W41')).rejects.toThrow(TypeError)
+  })
+})

web/src/sw/apiStrategy.ts

@@ -0,0 +1,16 @@
+// The network-first strategy for API reads, kept apart from src/sw.ts so the
+// tests can run it without a service worker.
+import type { WorkboxPlugin } from 'workbox-core/types'
+import { NetworkFirst } from 'workbox-strategies'
+import { cacheNames, markCacheFallback, networkTimeoutSeconds } from './routes'
+
+// NetworkFirst reads its cache only when the network fails or times out, so
+// every cached response it uses is a fallback.
+const markFallback: WorkboxPlugin = {
+  cachedResponseWillBeUsed: async ({ cachedResponse }) =>
+    cachedResponse === undefined ? undefined : markCacheFallback(cachedResponse),
+}
+
+export function createApiStrategy(): NetworkFirst {
+  return new NetworkFirst({ cacheName: cacheNames.api, networkTimeoutSeconds, plugins: [markFallback] })
+}

web/src/sw/routes.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest'
+import { cacheFallbackHeader, cacheNames, markCacheFallback, routeFor, staleCaches, type Route } from './routes'
+
+const origin = 'https://mealquest.test'
+
+function route(path: string, method = 'GET', mode: RequestMode = 'cors'): Route {
+  return routeFor({ method, url: new URL(path, origin), mode }, origin)
+}
+
+const apiCache: Route = { strategy: 'network-first', cacheName: cacheNames.api }
+const networkOnly: Route = { strategy: 'network-only' }
+
+describe('routeFor', () => {
+  it.each([
+    '/api/v1/plans',
+    '/api/v1/plans/2026-W40',
+    '/api/v1/shopping/current',
+    '/api/v1/dinners',
+    '/api/v1/dinners/01J9ZK?include=recipe',
+    '/api/v1/recipes',
+    '/api/v1/recipes/01J9ZR',
+    '/api/v1/home',
+  ])('GET %s is network-first in the API cache', (path) => {
+    expect(route(path)).toEqual(apiCache)
+  })
+
+  it.each(['/media/photos/abc.jpg', '/media/thumbs/abc.webp'])(
+    'GET %s is cache-first in the media cache',
+    (path) => {
+      expect(route(path)).toEqual({ strategy: 'cache-first', cacheName: cacheNames.media })
+    },
+  )
+
+  it('GET of a font file is cache-first in the fonts cache', () => {
+    expect(route('/assets/Figtree-Bold-a1b2c3.woff2')).toEqual({
+      strategy: 'cache-first',
+      cacheName: cacheNames.fonts,
+    })
+  })
+
+  it.each([
+    '/auth/login',
+    '/auth/callback?code=x&state=y',
+    '/auth/logout',
+    '/auth/me',
+    '/api/v1/settings',
+    '/api/v1/settings/ai',
+    '/api/v1/jobs',
+    '/api/v1/jobs/01J9ZK',
+  ])('GET %s is network-only', (path) => {
+    expect(route(path)).toEqual(networkOnly)
+  })
+
+  it.each(['/auth/login', '/auth/callback?code=x&state=y', '/api/v1/settings/ai'])(
+    'a navigation to %s is network-only with no offline fallback',
+    (path) => {
+      expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+    },
+  )
+
+  it.each([
+    '/%61uth/login',
+    '/auth%2Fcallback?code=x&state=y',
+    '/%61pi/v1/settings/household',
+    '/api/v1/%73ettings/ai',
+    '/api/v1/settings%2Fai',
+    '/%61pi/v1/jobs/01J9ZK',
+    '/api/v1/j%6Fbs',
+    '/api/v1/plans%2F..%2Fsettings',
+    '/api/v1/recipes%2F..%2Fsettings%2Fai',
+    '/api/v1/recipes/..%2F..%2F..%2Fauth%2Flogin',
+    '/plan%2F..%2Fauth%2Flogin',
+  ])('an encoded reserved path %s is network-only, navigated or not', (path) => {
+    expect(route(path)).toEqual(networkOnly)
+    expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it.each(['/%E0%A4%A', '/auth%', '/plan/%zz', '/api/v1/plans/%C3'])(
+    'a malformed encoding in %s is network-only, navigated or not',
+    (path) => {
+      expect(route(path)).toEqual(networkOnly)
+      expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+    },
+  )
+
+  it('classifies other API paths by their decoded form', () => {
+    expect(route('/%61pi/v1/plans/2026-W40')).toEqual(apiCache)
+    expect(route('/%61pi/v1/recipes/01J9ZR')).toEqual(apiCache)
+    expect(route('/%61pi/v1/ideas', 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it.each(['POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])(
+    '%s is network-only on every URL class',
+    (method) => {
+      for (const path of [
+        '/api/v1/plans/2026-W40',
+        '/api/v1/shopping/current',
+        '/api/v1/dinners/01J9ZK',
+        '/api/v1/recipes/01J9ZR',
+        '/api/v1/home',
+        '/media/photos/abc.jpg',
+        '/assets/Figtree-Bold-a1b2c3.woff2',
+        '/auth/logout',
+        '/plan',
+      ]) {
+        expect(route(path, method), `${method} ${path}`).toEqual(networkOnly)
+        expect(route(path, method, 'navigate'), `${method} ${path}`).toEqual(networkOnly)
+      }
+    },
+  )
+
+  it('matches whole path segments only', () => {
+    expect(route('/api/v1/plansx')).toEqual(networkOnly)
+    expect(route('/api/v1/homepage')).toEqual(networkOnly)
+    expect(route('/api/v1/recipesx')).toEqual(networkOnly)
+    expect(route('/mediax/a.jpg')).toEqual(networkOnly)
+    expect(route('/authors')).toEqual(networkOnly)
+    expect(route('/api/v1/settingsx')).toEqual(networkOnly)
+  })
+
+  it('leaves other API calls network-only', () => {
+    expect(route('/api/v1/me')).toEqual(networkOnly)
+    expect(route('/api/v1/ideas', 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it('leaves cross-origin requests network-only', () => {
+    for (const path of ['/api/v1/plans', '/media/a.jpg', '/assets/a.woff2']) {
+      const url = new URL(path, 'https://cdn.example')
+      expect(routeFor({ method: 'GET', url, mode: 'no-cors' }, origin)).toEqual(networkOnly)
+    }
+  })
+
+  it.each(['/', '/plan', '/supply-run', '/dinners/01J9ZK'])(
+    'a navigation to the app at %s falls back to the precached index.html',
+    (path) => {
+      expect(route(path, 'GET', 'navigate')).toEqual({ strategy: 'navigation-fallback' })
+    },
+  )
+
+  it('leaves other same-origin GETs network-only', () => {
+    expect(route('/health')).toEqual(networkOnly)
+  })
+})
+
+describe('cache names', () => {
+  it('all start with mealquest-', () => {
+    for (const name of Object.values(cacheNames)) expect(name).toMatch(/^mealquest-/)
+  })
+})
+
+describe('staleCaches', () => {
+  it('deletes only MealQuest caches that are not current', () => {
+    const current = ['mealquest-precache-v1', ...Object.values(cacheNames)]
+    const names = [
+      ...current,
+      'mealquest-precache',
+      'mealquest-api-v0',
+      'workbox-precache-v2-https://mealquest.test/',
+      'other-app-cache',
+      'my-mealquest-cache',
+    ]
+    expect(staleCaches(names, current)).toEqual(['mealquest-precache', 'mealquest-api-v0'])
+  })
+})
+
+describe('markCacheFallback', () => {
+  it('copies the cached response with the cache fallback header set', async () => {
+    const cached = new Response('{"id":"01J9ZR"}', {
+      status: 200,
+      statusText: 'OK',
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const marked = markCacheFallback(cached)
+    expect(marked.status).toBe(200)
+    expect(marked.statusText).toBe('OK')
+    expect(marked.headers.get('Content-Type')).toBe('application/json')
+    expect(marked.headers.get(cacheFallbackHeader)).toBe('1')
+    expect(await marked.json()).toEqual({ id: '01J9ZR' })
+  })
+})

web/src/sw/routes.ts

@@ -0,0 +1,108 @@
+// Decides how the service worker handles each request. This module is pure —
+// no Workbox, no service worker globals — so the tests can assert every URL
+// class without a worker; src/sw.ts maps each route to a Workbox strategy.
+//
+// Security rule: /auth/*, /api/v1/settings/*, /api/v1/jobs/* and every
+// non-GET request are network-only and never reach a cache. Paths are matched
+// as the server sees them — percent-decoded, before and after dot segments are
+// resolved — so /%61uth/login is /auth/login; a malformed encoding is
+// network-only.
+
+export type Route =
+  // Network with a 3 s timeout, then the last cached response.
+  | { strategy: 'network-first'; cacheName: typeof cacheNames.api }
+  // Cached response when there is one, else the network; entries expire.
+  | { strategy: 'cache-first'; cacheName: typeof cacheNames.media | typeof cacheNames.fonts }
+  // Network only, nothing cached: the worker leaves the request to the browser.
+  | { strategy: 'network-only' }
+  // Network only, nothing cached; offline, the precached index.html.
+  | { strategy: 'navigation-fallback' }
+
+export interface RouteRequest {
+  method: string
+  url: URL
+  mode: RequestMode
+}
+
+// Bumping the version renames every cache; activate then deletes the old ones.
+export const cacheVersion = 'v1'
+export const cachePrefix = 'mealquest-'
+
+export const cacheNames = {
+  api: `${cachePrefix}api-${cacheVersion}`,
+  media: `${cachePrefix}media-${cacheVersion}`,
+  fonts: `${cachePrefix}fonts-${cacheVersion}`,
+} as const
+
+export const networkTimeoutSeconds = 3
+
+// cacheFallbackHeader marks a network-first response answered from the cache
+// because the server could not be reached in time, so the app can show the
+// offline indicator even while the browser reports that it is online.
+export const cacheFallbackHeader = 'X-MealQuest-Cache-Fallback'
+
+// markCacheFallback copies a cached response with cacheFallbackHeader set.
+export function markCacheFallback(cached: Response): Response {
+  const headers = new Headers(cached.headers)
+  headers.set(cacheFallbackHeader, '1')
+  return new Response(cached.body, { status: cached.status, statusText: cached.statusText, headers })
+}
+
+const neverCached = ['/auth', '/api/v1/settings', '/api/v1/jobs']
+const networkFirst = ['/api/v1/plans', '/api/v1/shopping', '/api/v1/dinners', '/api/v1/recipes', '/api/v1/home']
+
+// True when path is prefix itself or a path below it: /api/v1/plans matches
+// /api/v1/plans and /api/v1/plans/2026-W40, never /api/v1/plansx.
+function under(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`)
+}
+
+// The pathname percent-decoded, as the server's router sees it, or undefined
+// when the encoding is malformed.
+function decodePath(pathname: string): string | undefined {
+  try {
+    return decodeURIComponent(pathname)
+  } catch {
+    return undefined
+  }
+}
+
+// Resolves "." and ".." segments the way the server's path.Clean does, so a
+// decoded %2F cannot carry a request out of a reserved prefix:
+// /api/v1/plans/../settings cleans to /api/v1/settings.
+function cleanPath(path: string): string {
+  const segments: string[] = []
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') segments.pop()
+    else segments.push(segment)
+  }
+  return `/${segments.join('/')}`
+}
+
+const networkOnly: Route = { strategy: 'network-only' }
+
+export function routeFor(request: RouteRequest, origin: string): Route {
+  const { method, url, mode } = request
+  if (method !== 'GET') return networkOnly
+  if (url.origin !== origin) return networkOnly
+  const path = decodePath(url.pathname)
+  if (path === undefined) return networkOnly
+  const cleaned = cleanPath(path)
+  const reserved = (prefix: string) => under(path, prefix) || under(cleaned, prefix)
+  if (neverCached.some(reserved)) return networkOnly
+  if (networkFirst.some((prefix) => under(path, prefix))) {
+    return { strategy: 'network-first', cacheName: cacheNames.api }
+  }
+  if (under(path, '/media')) return { strategy: 'cache-first', cacheName: cacheNames.media }
+  if (path.endsWith('.woff2')) return { strategy: 'cache-first', cacheName: cacheNames.fonts }
+  if (reserved('/api')) return networkOnly
+  if (mode === 'navigate') return { strategy: 'navigation-fallback' }
+  return networkOnly
+}
+
+// The caches activate deletes: MealQuest caches that are no longer current.
+// Caches without the mealquest- prefix belong to someone else and are kept.
+export function staleCaches(names: readonly string[], current: readonly string[]): string[] {
+  return names.filter((name) => name.startsWith(cachePrefix) && !current.includes(name))
+}

web/src/sw/worker.test.ts

@@ -0,0 +1,45 @@
+// The service worker itself needs worker globals, so these tests read its
+// source: they pin the parts routes.ts cannot express — the API cache's
+// strategy, the font strategy's expiration, the font route's place ahead of
+// the precache route and network-only requests left to the browser.
+import { describe, expect, it } from 'vitest'
+import source from '../sw.ts?raw'
+
+describe('service worker source', () => {
+  it('serves the API cache with the strategy that marks cache fallbacks', () => {
+    expect(source).toContain('[cacheNames.api]: createApiStrategy(),')
+  })
+
+  it('gives the fonts cache a CacheFirst strategy with an expiration plugin', () => {
+    expect(source).toMatch(
+      /\[cacheNames\.fonts\]: new CacheFirst\(\{\s*cacheName: cacheNames\.fonts,\s*plugins: \[\s*new ExpirationPlugin\(\{ maxEntries: \d+, maxAgeSeconds: [^}]+\}\)/,
+    )
+  })
+
+  it('falls back to the precached font when the network fails', () => {
+    expect(source).toContain('handlerDidError: async ({ request }) => matchPrecache(request.url)')
+  })
+
+  it('registers the font route before the precache route', () => {
+    const fontRoute = source.indexOf("registerRoute(isFont, handle, 'GET')")
+    const precache = source.indexOf('precacheAndRoute(self.__WB_MANIFEST)')
+    expect(fontRoute).toBeGreaterThanOrEqual(0)
+    expect(precache).toBeGreaterThan(fontRoute)
+  })
+
+  it('leaves network-only requests to the browser instead of answering them', () => {
+    // Chrome stalls a navigation whose Clear-Site-Data response (POST
+    // /auth/logout) the worker answered, so the worker must not match it.
+    expect(source).toMatch(
+      /function answered\(options: \{ request: Request; url: URL \}\): boolean \{\s*return routeOf\(options\)\.strategy !== 'network-only'/,
+    )
+    expect(source).toContain('registerRoute(answered, handle, method)')
+    expect(source).not.toContain('registerRoute(() => true')
+  })
+
+  it('activates a waiting worker when the update prompt sends SKIP_WAITING', () => {
+    expect(source).toMatch(
+      /self\.addEventListener\('message', \(event\) => \{\s*if \(event\.data\?\.type === 'SKIP_WAITING'\) void self\.skipWaiting\(\)/,
+    )
+  })
+})

web/src/test/setup.ts

@@ -4,4 +4,7 @@ import { afterEach } from 'vitest'
 
 afterEach(() => {
   cleanup()
+  // The verified-session marker and other device state must not leak between
+  // tests. Tests in the node environment (src/pwa.test.ts) have no storage.
+  if (typeof localStorage !== 'undefined') localStorage.clear()
 })

web/tsconfig.json

@@ -13,9 +13,11 @@
     "noUncheckedIndexedAccess": true,
     "verbatimModuleSyntax": true,
     "isolatedModules": true,
+    "resolveJsonModule": true,
     "allowImportingTsExtensions": true,
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts", "manifest.json"],
+  "exclude": ["src/sw.ts"]
 }

web/tsconfig.sw.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "WebWorker"],
+    "types": []
+  },
+  "include": ["src/sw.ts"],
+  "exclude": []
+}

web/vite.config.ts

@@ -1,10 +1,30 @@
 import { defineConfig } from 'vitest/config'
 import react from '@vitejs/plugin-react'
+import { VitePWA, type ManifestOptions } from 'vite-plugin-pwa'
+import manifest from './manifest.json' with { type: 'json' }
 
 const backend = 'http://localhost:8080'
 
 export default defineConfig({
-  plugins: [react()],
+  plugins: [
+    react(),
+    // The plugin writes manifest.webmanifest and sw.js, links the manifest
+    // from index.html and adds the registerSW.js script. It does both only
+    // in production builds: dev options stay off, so neither `vite` nor
+    // Vitest registers a service worker.
+    VitePWA({
+      strategies: 'injectManifest',
+      srcDir: 'src',
+      filename: 'sw.ts',
+      injectRegister: 'script',
+      // Precache the shell, JS, CSS and the self-hosted fonts.
+      injectManifest: { globPatterns: ['**/*.{html,js,css,woff2}'] },
+      // The web manifest lives in manifest.json: its theme and background
+      // colours are --color-accent and --color-bg from src/styles/tokens.css,
+      // and hex colours may not be written in TypeScript.
+      manifest: manifest as Partial<ManifestOptions>,
+    }),
+  ],
   server: {
     proxy: {
       '/api': backend,