Merge pull request 'Feature 01: Repository Scaffold and CI' (#8) from feature/19ad7feb-aba0-4b76-ab70-c47d71ed5e76-repository-scaffold-and-ci into dev

.dockerignore

@@ -0,0 +1,26 @@
+# Keep the build context small and free of secrets and local state.
+.git
+.gitignore
+.dockerignore
+Dockerfile
+.remember/
+.claude/
+design/
+**/.DS_Store
+node_modules
+web/node_modules
+web/dist
+# Generated embed output; the Go stage takes the PWA from the web stage.
+internal/frontend/dist/
+bin/
+*.db
+*.db-*
+.env*
+**/.env*
+deploy/secrets/
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/*.jks
+**/*.keystore

.gitea/workflows/ci.yml

@@ -0,0 +1,32 @@
+# Runs on every push and pull request (no branch filter) so feature branches,
+# their pull requests, and dev/main are all checked. Runs directly on the
+# self-hosted act_runner; no container: key.
+#
+# The Makefile is the single build definition: CI runs `make test` and
+# `make build` so it fails whenever either target would, and the binary
+# carries the Makefile's -trimpath and version-stamped -ldflags (the
+# `make build` log shows the -X main.version=... value).
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: make test
+        run: make test
+
+      - name: make build
+        run: make build

.gitignore

@@ -1,2 +1,18 @@
 .DS_Store
 design/.DS_Store
+
+# Secrets and local environment
+.env*
+deploy/secrets/
+
+# Build artifacts and dependencies
+node_modules
+dist
+bin/
+# Placeholder so the Go embed compiles on a fresh clone; built assets stay ignored.
+!internal/frontend/dist/
+internal/frontend/dist/*
+!internal/frontend/dist/index.html
+
+# Local databases
+*.db

AGENTS.md

@@ -0,0 +1,143 @@
+# AGENTS.md — MealQuest agent guide
+
+This is the authoritative guide for every agent (and human) working in this
+repository. `CLAUDE.md` only imports this file. Where this guide and a general
+habit disagree, this guide wins.
+
+MealQuest is a single Go service with an embedded React PWA for one
+household. The architecture of record is [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md);
+product requirements are in [design/MealQuest Requirements.md](design/MealQuest%20Requirements.md).
+
+## House rules
+
+1. **Fail fast.** Invalid configuration, input or state is an error reported
+   immediately and clearly — the service refuses to start on bad config.
+2. **No silent fallbacks.** Never substitute a default, retry quietly, or
+   swallow an error to "keep going". If something is missing, say so.
+3. **One way to do a thing.** No parallel code paths, alternative settings or
+   "just in case" options. Pick one approach and use it everywhere.
+4. **No new third-party dependency without owner approval.** Use only the
+   approved list below; anything else needs the owner's explicit yes first.
+5. **Never use `tea`.** The Gitea CLI on this host is authenticated as the
+   human owner. Agents act only through their own Gitea identities.
+
+## Approved dependencies (from CTXD)
+
+Backend:
+
+- Go 1.25, built with `CGO_ENABLED=0`.
+- `github.com/go-chi/chi/v5` — HTTP router.
+- `modernc.org/sqlite` — CGO-free SQLite driver.
+- `sqlc` — query code generation (dev tool only).
+- `github.com/coreos/go-oidc/v3` — OIDC (Authentik).
+- `golang.org/x/oauth2` and `golang.org/x/oauth2/google`.
+- `github.com/SherClockHolmes/webpush-go` — Web Push.
+- `golang.org/x/image` — photo processing.
+- `github.com/oklog/ulid/v2` — IDs.
+- Standard library `log/slog` and `net/http`.
+- **Not allowed:** LLM vendor SDKs, Google API SDKs (call the HTTP APIs
+  directly), goose, golang-migrate.
+
+Frontend:
+
+- React 19, TypeScript, Vite.
+- React Router 7, TanStack Query 5.
+- `vite-plugin-pwa`.
+- `lucide-react` icons at stroke width 2.75.
+- CSS Modules over the design tokens in
+  [tokens.css](design/MealQuest%20UI%20Designs/design_handoff_mealquest/tokens.css).
+  **No Tailwind, no Framer Motion, no hard-coded hex colours.**
+- Self-hosted fonts: Bagel Fat One and Figtree.
+- Tests: Vitest, Testing Library, jsdom.
+
+## Quality floor
+
+Every change must pass all of these before review (CI in
+[.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) enforces them):
+
+```sh
+gofmt -l .            # must print nothing
+go vet ./...
+go test -race ./...
+cd web && npm run typecheck && npm test && npm run build
+```
+
+And the build entry points in the [Makefile](Makefile) and [Dockerfile](Dockerfile):
+
+```sh
+make test
+make build
+docker build .
+```
+
+Lint proves code parses, not that it works: where a change has runtime
+behaviour, exercise it (hit the endpoint, render the page).
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `cmd/server` | Entry point. Wiring only — no business logic. |
+| `internal/config` | `MEALQUEST_*` environment config; secrets from `*_FILE`. |
+| `internal/server` | HTTP server, routes, `/health`. |
+| `internal/frontend` | `go:embed` of the built PWA with SPA fallback. |
+| `internal/*` (planned) | `auth`, `db`, `store`, `secretbox`, `household`, `dinners`, `recipes`, `ai/llm`, `ai/harness`, `ai/skills`, `suggest`, `plan`, `shopping`, `ideas`, `gcal`, `notify`, `push`, `chat`, `jobs`, `scheduler`. |
+| `migrations/` | SQL migrations (planned). |
+| `web/` | React PWA source. |
+| `deploy/` | Deployment files (planned). |
+| `docs/` | Project documentation, including [ARCHITECTURE.md](docs/ARCHITECTURE.md). |
+| `design/` | Requirements and UI handoff. **Read-only reference** — do not edit. |
+| `Dockerfile` | Multi-stage image build, at the repository root. |
+| `Makefile` | `dev`, `test`, `build`, `docker`. |
+| `.gitea/workflows/ci.yml` | CI quality floor. |
+
+Design references:
+
+- [design/MealQuest Requirements.md](design/MealQuest%20Requirements.md)
+- [design/MealQuest UI Designs/design_handoff_mealquest/README.md](design/MealQuest%20UI%20Designs/design_handoff_mealquest/README.md)
+- [design/MealQuest UI Designs/design_handoff_mealquest/tokens.css](design/MealQuest%20UI%20Designs/design_handoff_mealquest/tokens.css)
+
+## Branches, pull requests and merges
+
+- Integration branch is `dev`. `main` is the release branch.
+- **Feature branches:** `feature/<feature-uuid>-<slug>`, branched from `dev`.
+- **Task branches:** `task/<slug>_<task-uuid>`, branched from the feature branch.
+- Task pull requests **squash-merge into the feature branch**.
+- The feature pull request merges into `dev`.
+- **Only `overseer` merges `dev` → `main`** (a release).
+- Never push directly to `dev` or `main`.
+- Authors never review, approve, merge or close their own work.
+- Never store credentials in the repository; environment or ignored files only.
+
+## Where context lives and where work is tracked
+
+- **Context:** CTXD project `mealquest` — client guide at
+  <https://ctxd.cubecraftcreations.com>. Project documents: `CONTEXT.MD`
+  (architecture), `DECISIONS.MD` (decision log, e.g. D-021), `RUNBOOKS.MD`,
+  `PROMPTS.MD`, `GLOSSARY.MD`.
+- **Work tracking:** Maestro at <https://maestro.cubecraftlabs.com>,
+  workspace **Maniacs-Mansion** → project **MealQuest**. Every change has a
+  task with a verifiable done-condition.
+
+## Vocabulary (GLOSSARY)
+
+Use these product terms in code names, UI copy, docs and commit messages. Do
+not invent synonyms.
+
+| Term | Meaning |
+| --- | --- |
+| **Regulars** | Dinners the household makes routinely. |
+| **Side quest** | An AI-suggested new dinner to try. |
+| **Quest log** | The to-try pool of accepted Side quests, scheduled later. |
+| **Try it / Pass** | Accept (swipe right) / decline (swipe left) a suggestion. |
+| **Rotation check** / **"Keep it in rotation?"** | The prompt after a Quest-log dinner is tried, asking whether it becomes a Regular. Promotion is always the household's choice, never automatic. |
+| **Supply run** | The current week's shopping list, grouped by dinner. |
+| **Supply archive** | The blog-style history of past shopping lists (by week, month, year). |
+| **Draft board** | The mobile weekly plan layout the AI drafts for the household to adjust. |
+| **Rebuild week** | Ask the AI to redraft the week's plan. |
+| **Push to Calendar** | Push the plan one-way to Google Calendar. |
+| **Quick dinner** | Cooked in a crock pot **or** 30 minutes or less from prep to table. |
+| **Cook from what I have** | Ideas from a list of ingredients on hand. |
+| **Kitchen reading mode** | Tablet recipe view: large text, ingredient checkboxes, step-by-step. |
+| **"Why this?"** | The reason shown for a suggestion, referencing the household's Regulars. |
+| **Our kitchen / Shared household** | The single shared household identity; no per-person profiles. |

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Dockerfile

@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1
+# Base images are pinned by digest (multi-arch index); tags are for readability.
+
+FROM node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS web
+WORKDIR /src/web
+COPY web/package.json web/package-lock.json ./
+RUN npm ci
+COPY web/ ./
+RUN npm run build
+
+FROM golang:1.25-alpine@sha256:1ae0735f00daffa3aaf1363a5184c0d2dc55c78e3db4ec70241cdac97bf84b59 AS server
+ARG VERSION=dev
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+# Replace the placeholder with the built PWA; recreate the directory so no
+# stale file survives into the embed.
+RUN rm -rf internal/frontend/dist
+COPY --from=web /src/web/dist/ internal/frontend/dist/
+RUN CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=${VERSION}" \
+    -o /out/mealquest ./cmd/server
+
+# Alpine ships the CA bundle and busybox wget for the health check.
+FROM alpine:3.22@sha256:5291449c3df73caf6ed85e649dec1b9e818b39a5d8c871e97afc13e9cd5e8fa8
+RUN addgroup -S -g 10001 mealquest \
+    && adduser -S -D -H -u 10001 -G mealquest mealquest \
+    && mkdir /data && chown mealquest:mealquest /data
+COPY --from=server /out/mealquest /usr/local/bin/mealquest
+ENV MEALQUEST_HTTP_ADDR=:8080 \
+    MEALQUEST_DATA_DIR=/data
+VOLUME /data
+EXPOSE 8080
+USER 10001:10001
+# Probe the listener from MEALQUEST_HTTP_ADDR: host is everything before the
+# last colon (IPv6 keeps its brackets). Wildcard hosts map to loopback, as
+# does localhost: Go listens on its IPv4 address but wget would try ::1.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD host="${MEALQUEST_HTTP_ADDR%:*}"; \
+    case "$host" in ""|0.0.0.0|"[::]"|localhost) host=127.0.0.1 ;; esac; \
+    wget -q -O /dev/null "http://${host}:${MEALQUEST_HTTP_ADDR##*:}/health" || exit 1
+ENTRYPOINT ["/usr/local/bin/mealquest"]

Makefile

@@ -0,0 +1,60 @@
+# MealQuest build entry points.
+#
+#   make dev     Go server on :8080 plus Vite dev server on :5173 (proxies
+#                /api, /auth, /media to :8080). Needs the MEALQUEST_* env set.
+#   make test    gofmt check, go vet, go test -race, npm typecheck and test.
+#   make build   Build the PWA, embed it, build the static binary bin/mealquest.
+#   make docker  Build the container image from ./Dockerfile.
+
+FRONTEND_DIST := internal/frontend/dist
+# Dirty means a tracked change outside the generated embed output, which
+# `make embed` rewrites; plain `--dirty` would flag every rebuild.
+GIT_DIRTY := $(shell git status --porcelain --untracked-files=no -- . ':(exclude)$(FRONTEND_DIST)' 2>/dev/null)
+VERSION ?= $(shell git describe --tags --always 2>/dev/null || echo dev)$(if $(GIT_DIRTY),-dirty)
+IMAGE ?= mealquest:$(VERSION)
+LDFLAGS := -s -w -X main.version=$(VERSION)
+
+.PHONY: dev test go-test web-test build web embed check-embed-clean docker
+
+# Run both servers; Ctrl-C (or either exiting) stops both. The binary is built
+# first and run directly because `go run` would orphan its child on kill.
+dev: SHELL := /bin/bash
+dev:
+	go build -ldflags "$(LDFLAGS)" -o bin/mealquest-dev ./cmd/server
+	@trap 'kill $$(jobs -p) 2>/dev/null; wait' EXIT; \
+	bin/mealquest-dev & \
+	(cd web && exec npm run dev) & \
+	wait -n
+
+test: go-test web-test
+
+go-test:
+	@unformatted="$$(gofmt -l .)"; \
+	if [ -n "$$unformatted" ]; then echo "gofmt needed:"; echo "$$unformatted"; exit 1; fi
+	go vet ./...
+	go test -race ./...
+
+web-test:
+	cd web && npm ci && npm run typecheck && npm test
+
+build: embed
+	CGO_ENABLED=0 go build -trimpath -ldflags "$(LDFLAGS)" -o bin/mealquest ./cmd/server
+
+web:
+	cd web && npm ci && npm run build
+
+# Replace the committed placeholder with the built PWA so go:embed picks it up.
+# Recreate the whole directory: a glob would skip dotfiles, which all:dist embeds.
+embed: web
+	rm -rf $(FRONTEND_DIST)
+	mkdir -p $(FRONTEND_DIST)
+	cp -R web/dist/. $(FRONTEND_DIST)/
+
+# Regression check: a stale hidden file must not survive an embed.
+check-embed-clean:
+	touch $(FRONTEND_DIST)/.stale-embed-check
+	$(MAKE) embed
+	test ! -e $(FRONTEND_DIST)/.stale-embed-check
+
+docker:
+	docker build --build-arg VERSION=$(VERSION) -t $(IMAGE) .

README.md

@@ -0,0 +1,56 @@
+# MealQuest
+
+MealQuest is a mobile-first Progressive Web App for weekly dinner planning for
+one household. The household lists the dinners it makes regularly, an AI
+assistant suggests new dinners to try (swipe "Try it" or "Pass"), and the app
+builds a weekly plan, pushes it to Google Calendar, and generates a shopping
+list grouped by dinner, kept as a browsable weekly history. It ships as a
+single Go service with the React PWA embedded in the binary.
+
+> Status: this repository is the Feature 01 scaffold (Go service with
+> `/health`, embedded PWA skeleton, Makefile, Dockerfile, CI). The planned
+> application is described in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Quick start
+
+Requirements: Go 1.25 and Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` — that
+is, 22.22.2 or later on the 22 line, 24.15.0 or later on the 24 line, or 26.0.0
+or later. Node.js 23, 24.0–24.14 and 25 are not supported: this is the
+`engines` range of jsdom in the committed lockfile, the strictest of all the
+web dependencies.
+
+```sh
+(cd web && npm ci)
+mkdir -p ~/.mealquest-dev   # outside the repository: it holds a secret
+chmod 700 ~/.mealquest-dev
+head -c 32 /dev/urandom | base64 > ~/.mealquest-dev/secret_key
+chmod 600 ~/.mealquest-dev/secret_key
+export MEALQUEST_HTTP_ADDR=:8080
+export MEALQUEST_PUBLIC_URL=http://localhost:5173
+export MEALQUEST_DATA_DIR="$HOME/.mealquest-dev"
+export MEALQUEST_SHUTDOWN_TIMEOUT=10s
+export MEALQUEST_SECRET_KEY_FILE="$HOME/.mealquest-dev/secret_key"
+make dev
+```
+
+`make dev` runs the Go server on `:8080` and the Vite dev server on `:5173`
+(which proxies `/api`, `/auth` and `/media` to `:8080`). Open
+http://localhost:5173. Configuration is environment-only and fails fast:
+every variable above is required, and secrets are read only from files named
+by `*_FILE` variables.
+
+## Common commands
+
+| Command        | What it does                                                    |
+| -------------- | --------------------------------------------------------------- |
+| `make dev`     | Go server plus Vite dev server.                                 |
+| `make test`    | `gofmt` check, `go vet`, `go test -race`, web typecheck and tests. |
+| `make build`   | Build the PWA, embed it, build the static binary `bin/mealquest`. |
+| `make docker`  | Build the container image from the root `Dockerfile`.           |
+
+## Where to read next
+
+- [AGENTS.md](AGENTS.md) — house rules, approved dependencies, conventions.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture of record.
+- [design/MealQuest Requirements.md](design/MealQuest%20Requirements.md) — product requirements.
+- [design/MealQuest UI Designs/design_handoff_mealquest/README.md](design/MealQuest%20UI%20Designs/design_handoff_mealquest/README.md) — UI handoff.

cmd/server/main.go

@@ -0,0 +1,85 @@
+// Command server runs the MealQuest HTTP service.
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/server"
+)
+
+// version is set at build time with -ldflags "-X main.version=<version>".
+var version = "dev"
+
+func main() {
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	if err := run(cfg, logger); err != nil {
+		logger.Error("server stopped", "error", err)
+		os.Exit(1)
+	}
+}
+
+func run(cfg config.Config, logger *slog.Logger) error {
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	router, err := server.NewRouter(logger, version, frontend.Assets())
+	if err != nil {
+		return err
+	}
+	srv := &http.Server{
+		Addr:              cfg.HTTPAddr,
+		Handler:           router,
+		ReadHeaderTimeout: 10 * time.Second,
+		ErrorLog:          slog.NewLogLogger(logger.Handler(), slog.LevelError),
+	}
+
+	errc := make(chan error, 1)
+	go func() {
+		logListening(logger, cfg)
+		errc <- srv.ListenAndServe()
+	}()
+
+	select {
+	case err := <-errc:
+		return err
+	case <-ctx.Done():
+	}
+
+	logger.Info("shutting down", "timeout", cfg.ShutdownTimeout.String())
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
+	defer cancel()
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		return fmt.Errorf("shutdown: %w", err)
+	}
+	if err := <-errc; !errors.Is(err, http.ErrServerClosed) {
+		return err
+	}
+	return nil
+}
+
+// logListening logs the startup line. Only the public URL's origin is logged
+// so no credential-bearing URL component can reach the log.
+func logListening(logger *slog.Logger, cfg config.Config) {
+	logger.Info("listening",
+		"addr", cfg.HTTPAddr,
+		"public_origin", cfg.PublicOrigin(),
+		"data_dir", cfg.DataDir,
+		"version", version,
+	)
+}

cmd/server/main_test.go

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"bytes"
+	"log/slog"
+	"net/url"
+	"strings"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+)
+
+func TestLogListeningOmitsURLCredentials(t *testing.T) {
+	t.Parallel()
+
+	// Load rejects such URLs; this proves the log stays safe even if one
+	// reached the Config some other way.
+	u, err := url.Parse("https://alice:hunter2@meals.example.com/app?token=t0ken")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var buf bytes.Buffer
+	logListening(slog.New(slog.NewJSONHandler(&buf, nil)), config.Config{HTTPAddr: ":8080", PublicURL: u})
+
+	out := buf.String()
+	for _, leak := range []string{"alice", "hunter2", "t0ken"} {
+		if strings.Contains(out, leak) {
+			t.Errorf("startup log leaks %q: %s", leak, out)
+		}
+	}
+	if !strings.Contains(out, `"public_origin":"https://meals.example.com"`) {
+		t.Errorf("startup log missing public origin: %s", out)
+	}
+}

docs/ARCHITECTURE.md

@@ -0,0 +1,235 @@
+# MealQuest architecture
+
+This mirrors the architecture section of `CONTEXT.MD` in the CTXD project
+`mealquest`, which is the source of record; if the two disagree, CTXD wins and
+this file should be updated. It describes the **planned** application. The
+repository today is the Feature 01 scaffold: `cmd/server`, `internal/config`,
+`internal/server` (`/health`), `internal/frontend` (embedded PWA with SPA
+fallback), the `web/` skeleton, `Makefile`, `Dockerfile` and CI.
+
+Decision numbers (D-NNN) refer to `DECISIONS.MD` in CTXD.
+
+## Topology
+
+```
+PWA (phone / tablet / desktop)
+   │ HTTPS
+   ▼
+Traefik v3.6 — 10.60.1.33
+   file route: mealquest-ccl.yml
+   │
+   ▼
+docker compose project "mealquest" — 10.60.1.14
+   ├── mealquest   Go service + embedded PWA, host 8090 → container 8080
+   ├── searxng     sidecar for recipe search; internal compose network
+   │               only, no published port
+   └── Litestream  SQLite replication → Synology NAS 10.60.1.50
+```
+
+One Go service serves the API, the auth flow, media and the PWA. Its SQLite
+database is replicated by Litestream to the NAS.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `cmd/server` | Entry point; wiring only. |
+| `internal/config` | Env-only `MEALQUEST_*` config; secrets from `*_FILE`. |
+| `internal/server` | HTTP server, router, middleware. |
+| `internal/frontend` | Embedded PWA, SPA fallback. |
+| `internal/auth` | Authentik OIDC, sessions, CSRF. |
+| `internal/db`, `internal/store` | SQLite connections, sqlc queries. |
+| `internal/secretbox` | AES-256-GCM encryption for `_ct` columns. |
+| `internal/household`, `internal/dinners`, `internal/recipes` | Domain. |
+| `internal/ai/llm`, `internal/ai/harness`, `internal/ai/skills` | AI provider adapters, skill harness, skills. |
+| `internal/suggest`, `internal/plan`, `internal/shopping`, `internal/ideas` | Feature services. |
+| `internal/gcal`, `internal/notify`, `internal/push`, `internal/chat` | Integrations. |
+| `internal/jobs`, `internal/scheduler` | Background jobs and schedules. |
+| `migrations/` | SQL migrations (no goose or golang-migrate). |
+| `web/` | React PWA. |
+| `deploy/` | Deployment files. |
+| `docs/` | Documentation. |
+| `design/` | Requirements and UI handoff (read-only reference). |
+
+## Backend stack and conventions
+
+- Go 1.25, `CGO_ENABLED=0`, a single static binary.
+- Router: `go-chi/chi/v5`. Logging: `log/slog` JSON.
+- SQLite via `modernc.org/sqlite`, with `journal_mode=WAL`,
+  `foreign_keys=ON` and `busy_timeout`. **One writer connection plus a read
+  pool.** Queries generated by `sqlc`.
+- IDs are ULIDs (`oklog/ulid/v2`).
+- Timestamps are stored in UTC; local calendar dates are `YYYY-MM-DD` strings
+  in the household timezone.
+- Configuration is environment-only (`MEALQUEST_*`). Secrets come only from
+  files named by `*_FILE` variables. Missing or invalid config stops startup.
+- Error responses always have the body
+  `{"error":{"code":"…","message":"…","retryable":false}}`.
+
+## Authentication
+
+- Authentik OIDC; the backend is a **confidential client**
+  (`coreos/go-oidc/v3`, `golang.org/x/oauth2`).
+- Session cookie `__Host-mealquest_session` (HttpOnly, Secure,
+  SameSite=Lax). Sessions expire after 30 days idle or 180 days absolute.
+- Non-GET requests require the CSRF header `X-MealQuest-CSRF`.
+- Access requires membership of the Authentik group `mealquest-admin`.
+  There is a **single role**: one shared household, no per-person profiles.
+
+## Data model
+
+Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
+
+| Table | Holds |
+| --- | --- |
+| `household_settings` | One row: timezone, dinner_time (17:30), reminder_time (16:30), review_time (09:00), plan_draft day/time (Fri 09:00), suggestions day/time (Sun 08:00), chat_autosend day/time (Sat 08:00), onboarding_completed_at, updates_seen_at. |
+| `recipes` | A real recipe page: source_url (unique), site_name, title, total/prep/cook minutes, yield, raw_jsonld, fetched_at. |
+| `recipe_ingredients` | recipe_id, position, raw_text, name, qty, unit, note. |
+| `recipe_steps` | recipe_id, position, text. |
+| `photos` | source_url, local_path, width, height, sha256, fetched_at. |
+| `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by. |
+| `suggestion_batches` | trigger, status, ai_run_id. |
+| `suggestions` | dinner_id, batch_id, reason, cited_regular_ids (JSON), status, decided_at. |
+| `week_plans` | week_start (unique), status (`draft` / `synced` / `changed`), ai_note, ai_run_id, calendar_synced_at. |
+| `plan_days` | plan_id, date (unique per plan), dinner_id, is_new, calendar_event_id. |
+| `rotation_reviews` | dinner_id + plan_date (unique), status, decision (`keep` / `drop` / `not_made`), decided_at, updated_by. |
+| `shopping_lists` | week_start (unique), plan_id, title, status (`current` / `archived`), sent_to_chat_at, frozen_at. |
+| `shopping_groups` / `shopping_items` | One group per dinner/day; item name, qty, needed (bool), position. |
+| `ai_settings` | One row: provider, base_url, model, temperature, system_prompt, api_key_ct, api_key_last4, key_verified_at. |
+| `recipe_search_settings` | One row: provider (`searxng` / `brave`), base_url, api_key_ct. |
+| `integrations_google` | One row: refresh_token_ct, calendar_id, calendar_name, connected_at, last_sync_error. |
+| `chat_settings` | One row: webhook_url_ct, space_label, last_test_at, last_test_status. |
+| `notification_prefs` | event (`plan_ready` / `list_ready` / `day_of_reminder` / `new_suggestions` / `rotation_review`), push, chat. |
+| `push_subscriptions` | endpoint (unique), p256dh, auth, user_agent, failure_count, last_success_at. |
+| `notification_outbox` | event_key + channel (unique), payload, status, attempts, next_attempt_at, last_error. |
+| `jobs` | kind, status, payload, result (progressive), error, timestamps. |
+| `schedule_runs` | schedule, period_key (unique). |
+| `ai_runs` | skill, skill_version, provider, model, temperature, status, latency_ms, tokens_in/out, error, redacted request/response (30-day retention). |
+| `sessions` | id_hash, subject, email, name, groups, csrf_token, created/last_seen/expires. |
+
+`recipes` holds a fetched recipe page; `dinners` holds the household's meal
+record and its lifecycle, optionally linked to a recipe and a photo.
+
+## Dinner lifecycle
+
+```
+suggested (deck) ──Try it──▶ quest_log ──planned date passes──▶ tried
+    │                            ▲                                │
+    │                            └──────── explicit decision ─────┤
+    │                                                             ├──▶ regular
+    │                                                             └──▶ archived
+    └──Pass──▶ archived (name kept for dedupe)
+```
+
+From `tried`, an explicit decision moves the dinner to `regular`, to
+`archived`, or back to `quest_log`. Promotion to `regular` is **never
+automatic** (D-021).
+
+## API surface
+
+- JSON API under `/api/v1`, using the error body above for every failure.
+  It requires the session cookie and, for non-GET requests, the
+  `X-MealQuest-CSRF` header.
+- `/auth/*` — the OIDC flow.
+- `/media/*` — cached photos.
+- `/health` — liveness.
+- Everything else serves the embedded PWA with SPA fallback.
+
+## AI layer
+
+- **Provider interface** (`ai/llm`) with adapters for OpenAI-compatible,
+  Anthropic and Ollama endpoints, called over plain HTTP — no vendor SDKs.
+- **Skill harness** (`ai/harness`): prompt layering, validation of the
+  structured output, and **one repair retry**; if the repair also fails the
+  run fails — no silent fallback. Every call is recorded in `ai_runs`.
+
+## Recipe grounding
+
+- Dinners are grounded in real recipe pages found through recipe search
+  (`searxng` or `brave`, per `recipe_search_settings`).
+- Fetching is **SSRF-safe**.
+- Recipe data is parsed from schema.org `Recipe` JSON-LD.
+- Photos are cached locally (`photos`) and processed with
+  `golang.org/x/image`.
+
+## Scheduler
+
+Times are in the household timezone. The times of `day_of_reminder`
+(`reminder_time`) and `rotation_check` (`review_time`), and the day and time
+of `suggestions_weekly`, `plan_draft` and `shopping_chat_autosend`, are
+household settings in `household_settings` (`dinner_time` is also stored
+there); the table shows their defaults. `week_rollover` and the `ai_runs`
+purge are fixed and not configurable.
+
+| Schedule | When | Does |
+| --- | --- | --- |
+| `suggestions_weekly` | Sunday 08:00 | New batch of Side quests. |
+| `plan_draft` | Friday 09:00 | AI drafts next week's plan. |
+| `shopping_chat_autosend` | Saturday 08:00 | Sends the Supply run to Google Chat. |
+| `day_of_reminder` | Daily 16:30 | Tonight's dinner reminder. |
+| `rotation_check` | Daily 09:00 | Asks "Keep it in rotation?" for tried dinners. |
+| `week_rollover` | Monday 00:05 (fixed) | Freezes last week's Supply run into the Supply archive. |
+| `ai_runs` purge | Daily (fixed) | Deletes `ai_runs` rows past 30-day retention. |
+
+Runs are recorded in `schedule_runs` and executed through `jobs`.
+
+## Notifications
+
+- Events: `plan_ready`, `list_ready`, `day_of_reminder`, `new_suggestions`,
+  `rotation_review`; each can go to Web Push and/or Google Chat per
+  `notification_prefs`.
+- Delivery goes through `notification_outbox`.
+- Web Push uses VAPID (`webpush-go`). Google Chat uses the stored incoming
+  webhook.
+
+## Google Calendar
+
+- One-way push: the app is the source of truth; edits in Google Calendar do
+  not come back.
+- Connected once with Google OAuth in Settings; one event per planned
+  dinner.
+- **Deterministic event ids**; each plan day records its
+  `calendar_event_id`.
+
+## Frontend
+
+- React 19, TypeScript, Vite, React Router 7, TanStack Query 5,
+  `vite-plugin-pwa`, `lucide-react` (stroke 2.75).
+- CSS Modules over `tokens.css`; no Tailwind, no Framer Motion, no
+  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.
+
+| Route | Screen |
+| --- | --- |
+| `/` | Home |
+| `/onboarding` | Add regular dinners |
+| `/plan` | Weekly plan (Draft board) |
+| `/plan/shopping` | Shopping list (Supply run) |
+| `/plan/shopping/archive` | Supply archive |
+| `/discover` | Swipe suggestions (Side quests) |
+| `/quick` | Quick dinners |
+| `/cook-from-pantry` | Cook from what I have |
+| `/dinner/:id` | Recipe / dinner detail (Kitchen reading mode on tablet) |
+| `/settings` | Settings home |
+| `/settings/household` | Household settings |
+| `/settings/regulars` | Regular dinners |
+| `/settings/calendar` | Google Calendar connection |
+| `/settings/notifications` | Notifications and Google Chat |
+| `/settings/ai` | Admin · AI assistant |
+
+`/settings/household`, `/settings/regulars` and `/settings/calendar` come from
+CTXD; the other routes are defined in the UI handoff.
+
+## Boundaries and gotchas
+
+- **Secrets never reach the client** — API keys, OAuth tokens and the Chat
+  webhook stay server-side, encrypted at rest.
+- **The app is the source of truth for the plan**; Google Calendar is a
+  one-way mirror.
+- **Never auto-promote to Regular** (D-021).
+- **Quick** means cooked in a crock pot **or** ≤ 30 minutes prep to table.
+- **Weeks run Monday–Sunday** in the household timezone.
+- **No silent fallbacks** — fail fast and report.
+- **iOS Web Push requires the PWA to be installed to the Home Screen**; show
+  an install hint.

go.mod

@@ -0,0 +1,5 @@
+module code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest
+
+go 1.25
+
+require github.com/go-chi/chi/v5 v5.3.1

go.sum

@@ -0,0 +1,2 @@
+github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
+github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=

internal/config/config.go

@@ -0,0 +1,241 @@
+// Package config loads MealQuest configuration from MEALQUEST_* environment
+// variables. Secrets are read only from files named by *_FILE variables.
+package config
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Environment variable names.
+const (
+	EnvHTTPAddr        = "MEALQUEST_HTTP_ADDR"
+	EnvPublicURL       = "MEALQUEST_PUBLIC_URL"
+	EnvDataDir         = "MEALQUEST_DATA_DIR"
+	EnvShutdownTimeout = "MEALQUEST_SHUTDOWN_TIMEOUT"
+	EnvSecretKeyFile   = "MEALQUEST_SECRET_KEY_FILE"
+)
+
+// Config is the validated service configuration.
+type Config struct {
+	HTTPAddr        string
+	PublicURL       *url.URL
+	DataDir         string
+	ShutdownTimeout time.Duration
+	SecretKey       Secret
+}
+
+// PublicOrigin returns the scheme and host of PublicURL, the only parts of it
+// that are safe to log.
+func (c Config) PublicOrigin() string {
+	return c.PublicURL.Scheme + "://" + c.PublicURL.Host
+}
+
+// Load reads and validates configuration from the process environment.
+// It reports every missing or invalid variable in a single *Error.
+func Load() (Config, error) {
+	return load(os.LookupEnv)
+}
+
+func load(lookup func(string) (string, bool)) (Config, error) {
+	r := reader{lookup: lookup}
+	cfg := Config{
+		HTTPAddr:        r.listenAddr(EnvHTTPAddr),
+		PublicURL:       r.httpURL(EnvPublicURL),
+		DataDir:         r.dir(EnvDataDir),
+		ShutdownTimeout: r.duration(EnvShutdownTimeout),
+		SecretKey:       r.secretFile(EnvSecretKeyFile),
+	}
+	if len(r.problems) > 0 {
+		return Config{}, &Error{Problems: r.problems}
+	}
+	return cfg, nil
+}
+
+// Problem describes one missing or invalid variable.
+type Problem struct {
+	Var    string
+	Reason string
+}
+
+// Error lists every configuration problem found by Load.
+type Error struct {
+	Problems []Problem
+}
+
+func (e *Error) Error() string {
+	var b strings.Builder
+	b.WriteString("invalid configuration:")
+	for _, p := range e.Problems {
+		fmt.Fprintf(&b, "\n  %s: %s", p.Var, p.Reason)
+	}
+	return b.String()
+}
+
+// Secret holds a sensitive value. It never prints its contents.
+type Secret struct {
+	value string
+}
+
+// Reveal returns the secret value. Call it only where the value is used.
+func (s Secret) Reveal() string { return s.value }
+
+// String redacts the secret so it cannot leak through fmt or logs.
+func (s Secret) String() string { return "[REDACTED]" }
+
+// GoString redacts the secret for %#v.
+func (s Secret) GoString() string { return "[REDACTED]" }
+
+// reader reads variables and collects every problem instead of stopping at
+// the first one.
+type reader struct {
+	lookup   func(string) (string, bool)
+	problems []Problem
+}
+
+func (r *reader) fail(name, format string, args ...any) {
+	r.problems = append(r.problems, Problem{Var: name, Reason: fmt.Sprintf(format, args...)})
+}
+
+// required returns the variable's value, recording a problem when it is
+// unset or empty.
+func (r *reader) required(name string) (string, bool) {
+	v, ok := r.lookup(name)
+	if !ok || strings.TrimSpace(v) == "" {
+		r.fail(name, "required but not set")
+		return "", false
+	}
+	return v, true
+}
+
+func (r *reader) listenAddr(name string) string {
+	v, ok := r.required(name)
+	if !ok {
+		return ""
+	}
+	host, port, err := net.SplitHostPort(v)
+	if err != nil {
+		r.fail(name, "invalid listen address %q (want host:port or :port)", v)
+		return ""
+	}
+	// An empty host listens on all interfaces.
+	if host != "" && net.ParseIP(host) == nil && !validHostname(host) {
+		r.fail(name, "invalid host %q in listen address (want IP address or hostname)", host)
+		return ""
+	}
+	if _, err := strconv.ParseUint(port, 10, 16); err != nil {
+		r.fail(name, "invalid port %q in listen address (want 0-65535)", port)
+		return ""
+	}
+	return v
+}
+
+// validHostname reports whether h is a DNS hostname: dot-separated labels of
+// 1-63 letters, digits and hyphens, not starting or ending with a hyphen.
+func validHostname(h string) bool {
+	if len(h) > 253 {
+		return false
+	}
+	for _, label := range strings.Split(strings.TrimSuffix(h, "."), ".") {
+		if len(label) < 1 || len(label) > 63 || label[0] == '-' || label[len(label)-1] == '-' {
+			return false
+		}
+		for _, c := range label {
+			if !(c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' || c == '-') {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+func (r *reader) httpURL(name string) *url.URL {
+	v, ok := r.required(name)
+	if !ok {
+		return nil
+	}
+	// The value is never echoed: it may carry credentials.
+	u, err := url.Parse(v)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Hostname() == "" {
+		r.fail(name, "invalid URL (want absolute http:// or https:// URL)")
+		return nil
+	}
+	if u.User != nil {
+		r.fail(name, "URL must not contain user credentials")
+		return nil
+	}
+	return u
+}
+
+func (r *reader) dir(name string) string {
+	v, ok := r.required(name)
+	if !ok {
+		return ""
+	}
+	info, err := os.Stat(v)
+	if err != nil {
+		r.fail(name, "cannot access directory %q: %v", v, err)
+		return ""
+	}
+	if !info.IsDir() {
+		r.fail(name, "%q is not a directory", v)
+		return ""
+	}
+	return v
+}
+
+func (r *reader) duration(name string) time.Duration {
+	v, ok := r.required(name)
+	if !ok {
+		return 0
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil {
+		r.fail(name, "invalid duration %q (want e.g. 10s, 1m)", v)
+		return 0
+	}
+	if d <= 0 {
+		r.fail(name, "duration must be positive, got %q", v)
+		return 0
+	}
+	return d
+}
+
+// secretFile reads a secret from the file named by name, which must end in
+// _FILE. Setting the secret inline (name without _FILE) is rejected.
+func (r *reader) secretFile(name string) Secret {
+	inline := strings.TrimSuffix(name, "_FILE")
+	if _, set := r.lookup(inline); set {
+		r.fail(inline, "secrets must not be set inline; use %s", name)
+	}
+	path, ok := r.required(name)
+	if !ok {
+		return Secret{}
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		// Report the cause without echoing any file contents.
+		r.fail(name, "cannot read secret file %q: %v", path, unwrapPathError(err))
+		return Secret{}
+	}
+	value := strings.TrimRight(string(data), "\r\n")
+	if strings.TrimSpace(value) == "" {
+		r.fail(name, "secret file %q is empty", path)
+		return Secret{}
+	}
+	return Secret{value: value}
+}
+
+func unwrapPathError(err error) error {
+	var pe *os.PathError
+	if errors.As(err, &pe) {
+		return pe.Err
+	}
+	return err
+}

internal/config/config_test.go

@@ -0,0 +1,303 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestLoad(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	secretPath := filepath.Join(dir, "secret_key")
+	if err := os.WriteFile(secretPath, []byte("s3cret-value\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	unreadablePath := filepath.Join(dir, "missing_secret")
+	emptyPath := filepath.Join(dir, "empty_secret")
+	if err := os.WriteFile(emptyPath, []byte("\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	valid := func() map[string]string {
+		return map[string]string{
+			EnvHTTPAddr:        ":8080",
+			EnvPublicURL:       "https://meals.example.com",
+			EnvDataDir:         dir,
+			EnvShutdownTimeout: "15s",
+			EnvSecretKeyFile:   secretPath,
+		}
+	}
+	with := func(changes map[string]string, unset ...string) map[string]string {
+		env := valid()
+		for k, v := range changes {
+			env[k] = v
+		}
+		for _, k := range unset {
+			delete(env, k)
+		}
+		return env
+	}
+
+	tests := []struct {
+		name    string
+		env     map[string]string
+		badVars []string // variables the error must name; nil means success
+	}{
+		{
+			name: "all required vars present",
+			env:  valid(),
+		},
+		{
+			name:    "one missing",
+			env:     with(nil, EnvHTTPAddr),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "empty value counts as missing",
+			env:     with(map[string]string{EnvDataDir: ""}),
+			badVars: []string{EnvDataDir},
+		},
+		{
+			name: "all missing are collected",
+			env:  map[string]string{},
+			badVars: []string{
+				EnvHTTPAddr, EnvPublicURL, EnvDataDir, EnvShutdownTimeout, EnvSecretKeyFile,
+			},
+		},
+		{
+			name:    "invalid duration",
+			env:     with(map[string]string{EnvShutdownTimeout: "ten seconds"}),
+			badVars: []string{EnvShutdownTimeout},
+		},
+		{
+			name:    "non-positive duration",
+			env:     with(map[string]string{EnvShutdownTimeout: "0s"}),
+			badVars: []string{EnvShutdownTimeout},
+		},
+		{
+			name:    "invalid listen address",
+			env:     with(map[string]string{EnvHTTPAddr: "8080"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "non-numeric port",
+			env:     with(map[string]string{EnvHTTPAddr: ":notaport"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "empty port",
+			env:     with(map[string]string{EnvHTTPAddr: "127.0.0.1:"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "port out of range",
+			env:     with(map[string]string{EnvHTTPAddr: ":65536"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name: "listen address with IP host",
+			env:  with(map[string]string{EnvHTTPAddr: "127.0.0.1:8080"}),
+		},
+		{
+			name: "listen address with IPv6 host",
+			env:  with(map[string]string{EnvHTTPAddr: "[::1]:8080"}),
+		},
+		{
+			name: "listen address with hostname",
+			env:  with(map[string]string{EnvHTTPAddr: "localhost:8080"}),
+		},
+		{
+			name:    "listen host with space",
+			env:     with(map[string]string{EnvHTTPAddr: "bad host:8080"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "listen host with leading hyphen label",
+			env:     with(map[string]string{EnvHTTPAddr: "-bad.example.com:8080"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "listen host with empty label",
+			env:     with(map[string]string{EnvHTTPAddr: "bad..example.com:8080"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "listen host with label over 63 chars",
+			env:     with(map[string]string{EnvHTTPAddr: strings.Repeat("a", 64) + ".example.com:8080"}),
+			badVars: []string{EnvHTTPAddr},
+		},
+		{
+			name:    "public URL without hostname",
+			env:     with(map[string]string{EnvPublicURL: "http://:8080"}),
+			badVars: []string{EnvPublicURL},
+		},
+		{
+			name:    "relative public URL",
+			env:     with(map[string]string{EnvPublicURL: "meals.example.com"}),
+			badVars: []string{EnvPublicURL},
+		},
+		{
+			name:    "data dir does not exist",
+			env:     with(map[string]string{EnvDataDir: filepath.Join(dir, "nope")}),
+			badVars: []string{EnvDataDir},
+		},
+		{
+			name:    "unreadable secret file",
+			env:     with(map[string]string{EnvSecretKeyFile: unreadablePath}),
+			badVars: []string{EnvSecretKeyFile},
+		},
+		{
+			name:    "secret file path is a directory",
+			env:     with(map[string]string{EnvSecretKeyFile: dir}),
+			badVars: []string{EnvSecretKeyFile},
+		},
+		{
+			name:    "empty secret file",
+			env:     with(map[string]string{EnvSecretKeyFile: emptyPath}),
+			badVars: []string{EnvSecretKeyFile},
+		},
+		{
+			name:    "inline secret rejected",
+			env:     with(map[string]string{"MEALQUEST_SECRET_KEY": "inline"}),
+			badVars: []string{"MEALQUEST_SECRET_KEY"},
+		},
+		{
+			name: "several invalid values are all named",
+			env: with(map[string]string{
+				EnvShutdownTimeout: "soon",
+				EnvSecretKeyFile:   unreadablePath,
+			}, EnvPublicURL),
+			badVars: []string{EnvPublicURL, EnvShutdownTimeout, EnvSecretKeyFile},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			lookup := func(k string) (string, bool) {
+				v, ok := tc.env[k]
+				return v, ok
+			}
+			cfg, err := load(lookup)
+
+			if tc.badVars == nil {
+				if err != nil {
+					t.Fatalf("load() error = %v, want nil", err)
+				}
+				return
+			}
+
+			var cerr *Error
+			if !errors.As(err, &cerr) {
+				t.Fatalf("load() error = %v, want *Error", err)
+			}
+			var got []string
+			for _, p := range cerr.Problems {
+				got = append(got, p.Var)
+			}
+			if !slices.Equal(got, tc.badVars) {
+				t.Errorf("problem vars = %v, want %v", got, tc.badVars)
+			}
+			for _, v := range tc.badVars {
+				if !strings.Contains(err.Error(), v) {
+					t.Errorf("error message %q does not name %s", err.Error(), v)
+				}
+			}
+			if cfg != (Config{}) {
+				t.Errorf("load() returned non-zero Config alongside error: %+v", cfg)
+			}
+		})
+	}
+}
+
+func TestLoadValues(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	secretPath := filepath.Join(dir, "secret_key")
+	if err := os.WriteFile(secretPath, []byte("s3cret-value\r\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	env := map[string]string{
+		EnvHTTPAddr:        "127.0.0.1:9000",
+		EnvPublicURL:       "http://localhost:9000",
+		EnvDataDir:         dir,
+		EnvShutdownTimeout: "1m30s",
+		EnvSecretKeyFile:   secretPath,
+	}
+	cfg, err := load(func(k string) (string, bool) { v, ok := env[k]; return v, ok })
+	if err != nil {
+		t.Fatalf("load() error = %v", err)
+	}
+
+	if cfg.HTTPAddr != "127.0.0.1:9000" {
+		t.Errorf("HTTPAddr = %q", cfg.HTTPAddr)
+	}
+	if cfg.PublicURL.String() != "http://localhost:9000" {
+		t.Errorf("PublicURL = %q", cfg.PublicURL)
+	}
+	if cfg.DataDir != dir {
+		t.Errorf("DataDir = %q, want %q", cfg.DataDir, dir)
+	}
+	if cfg.ShutdownTimeout != 90*time.Second {
+		t.Errorf("ShutdownTimeout = %v, want 1m30s", cfg.ShutdownTimeout)
+	}
+	if cfg.SecretKey.Reveal() != "s3cret-value" {
+		t.Errorf("SecretKey.Reveal() = %q, want trailing newline trimmed", cfg.SecretKey.Reveal())
+	}
+}
+
+func TestSecretRedacted(t *testing.T) {
+	t.Parallel()
+
+	s := Secret{value: "s3cret-value"}
+	for _, format := range []string{"%v", "%s", "%+v", "%#v"} {
+		cfg := Config{SecretKey: s}
+		for _, out := range []string{fmt.Sprintf(format, s), fmt.Sprintf(format, cfg)} {
+			if strings.Contains(out, "s3cret-value") {
+				t.Errorf("format %s leaked secret: %s", format, out)
+			}
+		}
+	}
+}
+
+func TestPublicURLWithCredentialsRejected(t *testing.T) {
+	t.Parallel()
+
+	for _, raw := range []string{
+		"https://alice:hunter2@example.com",
+		"https://alice@example.com",
+		"https://alice:hunter2@[bad",
+	} {
+		env := map[string]string{EnvPublicURL: raw}
+		_, err := load(func(k string) (string, bool) { v, ok := env[k]; return v, ok })
+
+		var cerr *Error
+		if !errors.As(err, &cerr) || !slices.ContainsFunc(cerr.Problems, func(p Problem) bool { return p.Var == EnvPublicURL }) {
+			t.Errorf("load(%q) error = %v, want problem for %s", raw, err, EnvPublicURL)
+		}
+		if err != nil && (strings.Contains(err.Error(), "hunter2") || strings.Contains(err.Error(), "alice")) {
+			t.Errorf("load(%q) error leaks credentials: %v", raw, err)
+		}
+	}
+}
+
+func TestPublicOrigin(t *testing.T) {
+	t.Parallel()
+
+	u, err := url.Parse("https://alice:hunter2@meals.example.com:8443/app?token=x#frag")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := (Config{PublicURL: u}).PublicOrigin(), "https://meals.example.com:8443"; got != want {
+		t.Errorf("PublicOrigin() = %q, want %q", got, want)
+	}
+}

internal/frontend/dist/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>MealQuest</title>
+  </head>
+  <body>
+    <!-- Placeholder so the Go embed compiles. The build replaces this directory with web/dist. -->
+    <p>MealQuest web assets have not been built.</p>
+  </body>
+</html>

internal/frontend/frontend.go

@@ -0,0 +1,127 @@
+// Package frontend serves the embedded PWA build with an SPA fallback.
+package frontend
+
+import (
+	"embed"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"log/slog"
+	"net/http"
+	"path"
+	"strings"
+	"time"
+)
+
+// embedded holds the web build. The build copies web/dist over the committed
+// placeholder index.html.
+//
+//go:embed all:dist
+var embedded embed.FS
+
+const (
+	indexFile = "index.html"
+
+	cacheImmutable = "public, max-age=31536000, immutable"
+	cacheNoCache   = "no-cache"
+)
+
+// noCacheFiles must be revalidated on every load: they name the hashed assets
+// (or, for the service worker, control their caching), so a stale copy pins an
+// old release.
+var noCacheFiles = map[string]bool{
+	indexFile:              true,
+	"sw.js":                true,
+	"manifest.webmanifest": true,
+}
+
+// Assets returns the embedded web build rooted at its dist directory.
+func Assets() fs.FS {
+	sub, err := fs.Sub(embedded, "dist")
+	if err != nil {
+		panic(err) // "dist" is a valid path, so Sub cannot fail
+	}
+	return sub
+}
+
+// NewHandler returns a handler that serves files from fsys. A GET or HEAD for a
+// path that is not a file in fsys is answered with index.html so client-side
+// routes load the app. Paths equal to or under a reserved prefix (for example
+// "/api") are never answered with index.html, whether before or after the path
+// is cleaned; they are passed to notFound.
+// fsys must contain index.html.
+func NewHandler(fsys fs.FS, logger *slog.Logger, notFound http.Handler, reserved ...string) (http.Handler, error) {
+	if _, err := fs.Stat(fsys, indexFile); err != nil {
+		return nil, fmt.Errorf("frontend assets: %w", err)
+	}
+	return &handler{fsys: fsys, logger: logger, notFound: notFound, reserved: reserved}, nil
+}
+
+type handler struct {
+	fsys     fs.FS
+	logger   *slog.Logger
+	notFound http.Handler
+	reserved []string
+}
+
+func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	urlPath := path.Clean("/" + r.URL.Path)
+	// Check the uncleaned path too, so dot segments cannot escape a reserved
+	// prefix into the fallback ("/auth/../quests/42" cleans to "/quests/42").
+	if h.isReserved(r.URL.Path) || h.isReserved(urlPath) {
+		h.notFound.ServeHTTP(w, r)
+		return
+	}
+
+	name := strings.TrimPrefix(urlPath, "/")
+	if name == "" || !h.isFile(name) {
+		name = indexFile
+	}
+	h.serveFile(w, r, name)
+}
+
+func (h *handler) isReserved(urlPath string) bool {
+	for _, prefix := range h.reserved {
+		if urlPath == prefix || strings.HasPrefix(urlPath, prefix+"/") {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *handler) isFile(name string) bool {
+	info, err := fs.Stat(h.fsys, name)
+	return err == nil && info.Mode().IsRegular()
+}
+
+func (h *handler) serveFile(w http.ResponseWriter, r *http.Request, name string) {
+	f, err := h.fsys.Open(name)
+	if err != nil {
+		h.fail(w, r, name, err)
+		return
+	}
+	defer f.Close()
+	content, ok := f.(io.ReadSeeker)
+	if !ok {
+		h.fail(w, r, name, errors.New("file does not implement io.Seeker"))
+		return
+	}
+
+	if noCacheFiles[name] {
+		w.Header().Set("Cache-Control", cacheNoCache)
+	} else {
+		w.Header().Set("Cache-Control", cacheImmutable)
+	}
+	if path.Ext(name) == ".webmanifest" {
+		w.Header().Set("Content-Type", "application/manifest+json")
+	}
+	// Embedded files carry no modification time; ServeContent omits
+	// Last-Modified for the zero time.
+	http.ServeContent(w, r, name, time.Time{}, content)
+}
+
+func (h *handler) fail(w http.ResponseWriter, r *http.Request, name string, err error) {
+	h.logger.ErrorContext(r.Context(), "serve frontend asset", "file", name, "error", err)
+	http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
+}

internal/frontend/frontend_test.go

@@ -0,0 +1,137 @@
+package frontend
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+)
+
+const (
+	indexBody    = "<!doctype html><title>fixture index</title>"
+	assetBody    = "console.log('fixture asset')"
+	robotsBody   = "User-agent: *"
+	swBody       = "self.addEventListener('fetch', () => {})"
+	manifestBody = `{"name":"MealQuest"}`
+	notFoundBody = "reserved not found"
+)
+
+func fixture() fstest.MapFS {
+	return fstest.MapFS{
+		"index.html":             {Data: []byte(indexBody)},
+		"sw.js":                  {Data: []byte(swBody)},
+		"manifest.webmanifest":   {Data: []byte(manifestBody)},
+		"assets/index-AbC123.js": {Data: []byte(assetBody)},
+		"robots.txt":             {Data: []byte(robotsBody)},
+	}
+}
+
+func newTestHandler(t *testing.T) http.Handler {
+	t.Helper()
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	notFound := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, notFoundBody, http.StatusNotFound)
+	})
+	h, err := NewHandler(fixture(), logger, notFound, "/api", "/auth", "/media", "/health")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return h
+}
+
+func TestServe(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		method    string
+		path      string
+		wantBody  string
+		wantCache string
+	}{
+		{"hashed asset", http.MethodGet, "/assets/index-AbC123.js", assetBody, cacheImmutable},
+		{"unhashed asset", http.MethodGet, "/robots.txt", robotsBody, cacheImmutable},
+		{"root", http.MethodGet, "/", indexBody, cacheNoCache},
+		{"index.html", http.MethodGet, "/index.html", indexBody, cacheNoCache},
+		{"service worker", http.MethodGet, "/sw.js", swBody, cacheNoCache},
+		{"manifest", http.MethodGet, "/manifest.webmanifest", manifestBody, cacheNoCache},
+		{"client route", http.MethodGet, "/quests/42", indexBody, cacheNoCache},
+		{"missing asset", http.MethodGet, "/assets/missing.js", indexBody, cacheNoCache},
+		{"directory", http.MethodGet, "/assets", indexBody, cacheNoCache},
+		{"dot segments", http.MethodGet, "/x/../../sw.js", swBody, cacheNoCache},
+		{"prefix lookalike", http.MethodGet, "/apiary", indexBody, cacheNoCache},
+		{"head", http.MethodHead, "/assets/index-AbC123.js", "", cacheImmutable},
+	}
+	h := newTestHandler(t)
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, httptest.NewRequest(tt.method, tt.path, nil))
+
+			if rec.Code != http.StatusOK {
+				t.Errorf("status = %d, want 200", rec.Code)
+			}
+			if got := rec.Body.String(); got != tt.wantBody {
+				t.Errorf("body = %q, want %q", got, tt.wantBody)
+			}
+			if got := rec.Header().Get("Cache-Control"); got != tt.wantCache {
+				t.Errorf("Cache-Control = %q, want %q", got, tt.wantCache)
+			}
+		})
+	}
+}
+
+func TestManifestContentType(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	newTestHandler(t).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/manifest.webmanifest", nil))
+
+	if got := rec.Header().Get("Content-Type"); got != "application/manifest+json" {
+		t.Errorf("Content-Type = %q, want application/manifest+json", got)
+	}
+}
+
+func TestReservedPrefixesNotServed(t *testing.T) {
+	t.Parallel()
+
+	h := newTestHandler(t)
+	for _, path := range []string{"/api", "/api/unknown", "/auth/login", "/media/x.jpg", "/health", "/health/deep", "/x/../api/unknown", "/auth/../quests/42", "/api%2F..%2Fquests/42"} {
+		t.Run(path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+
+			if rec.Code != http.StatusNotFound {
+				t.Errorf("status = %d, want 404", rec.Code)
+			}
+			if got := rec.Body.String(); got != notFoundBody+"\n" {
+				t.Errorf("body = %q, want the notFound handler's body", got)
+			}
+		})
+	}
+}
+
+func TestNewHandlerRequiresIndex(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	fsys := fstest.MapFS{"sw.js": {Data: []byte(swBody)}}
+	if _, err := NewHandler(fsys, logger, http.NotFoundHandler()); err == nil {
+		t.Fatal("NewHandler without index.html: want error, got nil")
+	}
+}
+
+func TestAssetsContainsIndex(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewHandler(Assets(), logger, http.NotFoundHandler()); err != nil {
+		t.Fatalf("embedded assets: %v", err)
+	}
+}

internal/server/server.go

@@ -0,0 +1,91 @@
+// Package server builds the MealQuest HTTP router.
+package server
+
+import (
+	"encoding/json"
+	"io/fs"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
+)
+
+// reservedPrefixes are owned by the API router and are never answered with the
+// SPA's index.html.
+var reservedPrefixes = []string{"/api", "/auth", "/media", "/health"}
+
+// NewRouter returns the HTTP handler for the service. version is reported by
+// GET /health; assets is the web build served for every other GET.
+func NewRouter(logger *slog.Logger, version string, assets fs.FS) (http.Handler, error) {
+	notFound := apiErrorHandler(logger, http.StatusNotFound, "not_found", "not found")
+	methodNotAllowed := apiErrorHandler(logger, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
+
+	web, err := frontend.NewHandler(assets, logger, notFound, reservedPrefixes...)
+	if err != nil {
+		return nil, err
+	}
+
+	r := chi.NewRouter()
+	r.MethodNotAllowed(methodNotAllowed)
+	r.NotFound(notFound)
+
+	r.Get("/health", health(logger, version))
+	r.Route("/api", func(r chi.Router) {
+		r.MethodNotAllowed(methodNotAllowed)
+		r.NotFound(notFound)
+	})
+	// Catch-all for the PWA. /auth and /media have no routes yet; the frontend
+	// handler passes them to notFound rather than the SPA fallback.
+	r.Method(http.MethodGet, "/*", web)
+	r.Method(http.MethodHead, "/*", web)
+	return r, nil
+}
+
+type errorBody struct {
+	Error apiError `json:"error"`
+}
+
+type apiError struct {
+	Code      string `json:"code"`
+	Message   string `json:"message"`
+	Retryable bool   `json:"retryable"`
+}
+
+// apiErrorHandler responds with status and a fixed, non-retryable API error.
+func apiErrorHandler(logger *slog.Logger, status int, code, message string) http.HandlerFunc {
+	body, err := json.Marshal(errorBody{Error: apiError{
+		Code:    code,
+		Message: message,
+	}})
+	if err != nil {
+		panic(err) // fixed string and bool fields cannot fail to marshal
+	}
+	return func(w http.ResponseWriter, r *http.Request) {
+		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)
+		}
+	}
+}
+
+type healthResponse struct {
+	Status  string `json:"status"`
+	Version string `json:"version"`
+}
+
+func health(logger *slog.Logger, version string) http.HandlerFunc {
+	body, err := json.Marshal(healthResponse{Status: "ok", Version: version})
+	if err != nil {
+		panic(err) // two string fields cannot fail to marshal
+	}
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		if _, err := w.Write(body); err != nil {
+			logger.WarnContext(r.Context(), "write health response", "error", err)
+		}
+	}
+}

internal/server/server_test.go

@@ -0,0 +1,185 @@
+package server
+
+import (
+	"encoding/json"
+	"io"
+	"log/slog"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"testing/fstest"
+)
+
+const (
+	fixtureIndex = "<!doctype html><title>fixture index</title>"
+	fixtureAsset = "console.log('fixture asset')"
+	notFoundJSON = `{"error":{"code":"not_found","message":"not found","retryable":false}}`
+)
+
+func newTestRouter(t *testing.T, version string) http.Handler {
+	t.Helper()
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	assets := fstest.MapFS{
+		"index.html":             {Data: []byte(fixtureIndex)},
+		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
+	}
+	r, err := NewRouter(logger, version, assets)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+func TestHealth(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(newTestRouter(t, "1.2.3"))
+	t.Cleanup(srv.Close)
+
+	resp, err := http.Get(srv.URL + "/health")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("status = %d, want 200", resp.StatusCode)
+	}
+	if ct := resp.Header.Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+	var got map[string]string
+	if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]string{"status": "ok", "version": "1.2.3"}
+	if len(got) != len(want) || got["status"] != want["status"] || got["version"] != want["version"] {
+		t.Errorf("body = %v, want %v", got, want)
+	}
+}
+
+func TestHealthRejectsOtherMethods(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/health", nil))
+
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("status = %d, want 405", rec.Code)
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+	var got struct {
+		Error map[string]any `json:"error"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]any{
+		"code":      "method_not_allowed",
+		"message":   "method not allowed",
+		"retryable": false,
+	}
+	if !maps.Equal(got.Error, want) {
+		t.Errorf("error body = %v, want %v", got.Error, want)
+	}
+}
+
+func TestReservedPathsNotFound(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	tests := []struct {
+		method string
+		path   string
+	}{
+		{http.MethodGet, "/api"},
+		{http.MethodGet, "/api/unknown"},
+		{http.MethodPost, "/api/unknown"},
+		{http.MethodGet, "/auth/callback"},
+		{http.MethodGet, "/media/photo.jpg"},
+		{http.MethodGet, "/health/deep"},
+		{http.MethodGet, "/auth/../quests/42"},
+		{http.MethodGet, "/api%2F..%2Fquests/42"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.method+" "+tt.path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, httptest.NewRequest(tt.method, tt.path, nil))
+
+			if rec.Code != http.StatusNotFound {
+				t.Errorf("status = %d, want 404", rec.Code)
+			}
+			if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+				t.Errorf("Content-Type = %q, want application/json", ct)
+			}
+			if got := rec.Body.String(); got != notFoundJSON {
+				t.Errorf("body = %s, want %s", got, notFoundJSON)
+			}
+		})
+	}
+}
+
+func TestFrontend(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	tests := []struct {
+		path      string
+		wantBody  string
+		wantCache string
+	}{
+		{"/", fixtureIndex, "no-cache"},
+		{"/assets/index-AbC123.js", fixtureAsset, "public, max-age=31536000, immutable"},
+		{"/quests/42", fixtureIndex, "no-cache"},
+		{"/quests/42/edit", fixtureIndex, "no-cache"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, tt.path, nil))
+
+			if rec.Code != http.StatusOK {
+				t.Errorf("status = %d, want 200", rec.Code)
+			}
+			if got := rec.Body.String(); got != tt.wantBody {
+				t.Errorf("body = %q, want %q", got, tt.wantBody)
+			}
+			if got := rec.Header().Get("Cache-Control"); got != tt.wantCache {
+				t.Errorf("Cache-Control = %q, want %q", got, tt.wantCache)
+			}
+		})
+	}
+}
+
+func TestHealthNotShadowed(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/health", nil))
+
+	if body := rec.Body.String(); rec.Code != http.StatusOK || strings.Contains(body, fixtureIndex) {
+		t.Errorf("GET /health = %d %q, want 200 health JSON", rec.Code, body)
+	}
+}
+
+func TestFrontendRejectsOtherMethods(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/quests/42", nil))
+
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("status = %d, want 405", rec.Code)
+	}
+	if strings.Contains(rec.Body.String(), fixtureIndex) {
+		t.Errorf("body = %q, want no index.html", rec.Body.String())
+	}
+}

web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MealQuest</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "mealquest-web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.104.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-router": "^7.18.4"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "^30.1.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
+  }
+}

web/src/App.test.tsx

@@ -0,0 +1,15 @@
+import { render, screen } from '@testing-library/react'
+import { MemoryRouter } from 'react-router'
+import { describe, expect, it } from 'vitest'
+import App from './App.tsx'
+
+describe('App', () => {
+  it('renders the MealQuest shell', () => {
+    render(
+      <MemoryRouter>
+        <App />
+      </MemoryRouter>,
+    )
+    expect(screen.getByRole('heading', { name: 'MealQuest' })).toBeInTheDocument()
+  })
+})

web/src/App.tsx

@@ -0,0 +1,25 @@
+import { useState } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { Route, Routes } from 'react-router'
+
+// Placeholder shell only: no product UI, auth or API calls yet.
+function Shell() {
+  return (
+    <main>
+      <h1>MealQuest</h1>
+    </main>
+  )
+}
+
+// App expects to be rendered inside a router (BrowserRouter in main.tsx,
+// MemoryRouter in tests).
+export default function App() {
+  const [queryClient] = useState(() => new QueryClient())
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Routes>
+        <Route path="*" element={<Shell />} />
+      </Routes>
+    </QueryClientProvider>
+  )
+}

web/src/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router'
+import App from './App.tsx'
+
+const root = document.getElementById('root')
+if (!root) {
+  throw new Error('MealQuest: #root element missing from index.html')
+}
+
+createRoot(root).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+)

web/src/test/setup.ts

@@ -0,0 +1,7 @@
+import '@testing-library/jest-dom/vitest'
+import { cleanup } from '@testing-library/react'
+import { afterEach } from 'vitest'
+
+afterEach(() => {
+  cleanup()
+})

web/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

web/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+const backend = 'http://localhost:8080'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: {
+      '/api': backend,
+      '/auth': backend,
+      '/media': backend,
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+  },
+})