feat(GRO-2156): travel buffer + reorder endpoint (Phase 2.2)

- Apply travel buffer between consecutive stops (default 15 / businessSettings.defaultTravelBufferMins); first stop carries bufferMins 0
- detectScheduleConflicts: flag tight schedule when appointment gap < travelMins + bufferMins; never auto-move appointments
- PATCH /api/routes/:routeId/reorder — validate permutation of current stops, persist new stopOrder (two-pass to avoid unique collision), re-estimate legs, re-apply buffers, recompute totals
- Return route + per-stop conflict flags + hasConflicts/conflictCount on /daily, /optimize, /reorder
- Unit tests for detectScheduleConflicts + recomputeLegsForOrder; UAT_PLAYBOOK §4.17

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.ci-trigger

@@ -0,0 +1 @@
+GRO-1757 direct push CI trigger - 2026-05-26T00:15:41Z

.gitea/workflows/ci.yml

@@ -0,0 +1,187 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev, uat]
+  pull_request:
+    branches: [main, dev, uat]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch or ref to run CI against"
+        required: false
+        default: "main"
+
+jobs:
+  lint-typecheck:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: |
+          pnpm run typecheck
+          pnpm --filter @groombook/db typecheck
+
+      - name: Lint
+        run: pnpm run lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm run test
+
+  docker:
+    name: Build & Push Docker Images
+    runs-on: ubuntu-latest
+    needs: [lint-typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate image tag
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            TAG="pr-${{ github.event.pull_request.number }}-${GITHUB_SHA::7}"
+          else
+            TAG="$(date -u +%Y.%m.%d)-${GITHUB_SHA::7}"
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Image tag: $TAG"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Log in to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.farh.net
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build and push API image
+        uses: docker/build-push-action@v6
+        with:
+          provenance: false
+          context: .
+          file: Dockerfile
+          target: runner
+          push: true
+          tags: |
+            git.farh.net/groombook/api:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/api:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:api
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:api,mode=max
+
+      - name: Build and push Migrate image
+        uses: docker/build-push-action@v6
+        with:
+          provenance: false
+          context: .
+          file: Dockerfile
+          target: migrate
+          push: true
+          tags: |
+            git.farh.net/groombook/migrate:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/migrate:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:migrate
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:migrate,mode=max
+
+      - name: Smoke test migrate image (blackhole npmjs.org)
+        run: |
+          set -euo pipefail
+          IMAGE="git.farh.net/groombook/migrate:${{ steps.version.outputs.tag }}"
+          docker pull "$IMAGE"
+          docker run --rm \
+            --add-host registry.npmjs.org:127.0.0.1 \
+            --entrypoint="" \
+            "$IMAGE" \
+            pnpm --version
+
+      - name: Build and push Seed image
+        uses: docker/build-push-action@v6
+        with:
+          provenance: false
+          context: .
+          file: Dockerfile
+          target: seed
+          push: true
+          tags: |
+            git.farh.net/groombook/seed:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/seed:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:seed
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:seed,mode=max
+
+      - name: Build and push Reset image
+        uses: docker/build-push-action@v6
+        with:
+          provenance: false
+          context: .
+          file: Dockerfile
+          target: reset
+          push: true
+          tags: |
+            git.farh.net/groombook/reset:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/reset:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:reset
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:reset,mode=max
+
+      - name: Smoke test seed image (blackhole npmjs.org)
+        run: |
+          set -euo pipefail
+          IMAGE="git.farh.net/groombook/seed:${{ steps.version.outputs.tag }}"
+          docker pull "$IMAGE"
+          # GRO-1985: pnpm must be a real binary, not a Corepack shim, and must
+          # not try to reach registry.npmjs.org on invocation.
+          docker run --rm \
+            --add-host registry.npmjs.org:127.0.0.1 \
+            --entrypoint="" \
+            "$IMAGE" \
+            sh -c 'set -e; test "$(which pnpm)" = "/usr/local/bin/pnpm"; pnpm --version'
+          echo "seed image: pnpm resolves to /usr/local/bin/pnpm and runs offline ✓"
+
+      - name: Smoke test reset image (blackhole npmjs.org)
+        run: |
+          set -euo pipefail
+          IMAGE="git.farh.net/groombook/reset:${{ steps.version.outputs.tag }}"
+          docker pull "$IMAGE"
+          # GRO-1985: pnpm must be a real binary, not a Corepack shim, and must
+          # not try to reach registry.npmjs.org on invocation. Validates the
+          # hard requirement from the issue: reset runs offline.
+          docker run --rm \
+            --add-host registry.npmjs.org:127.0.0.1 \
+            --entrypoint="" \
+            "$IMAGE" \
+            sh -c 'set -e; test "$(which pnpm)" = "/usr/local/bin/pnpm"; echo "HOME=$HOME"; pnpm --version'
+          echo "reset image: pnpm resolves to /usr/local/bin/pnpm, HOME=/tmp, runs offline ✓"

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
 
       - name: Install dependencies
@@ -49,7 +49,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
 
       - name: Install dependencies
@@ -71,7 +71,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
 
       - name: Install dependencies
@@ -202,20 +202,20 @@ jobs:
           echo "Updating dev overlay image tags to: $TAG"
           echo "Updating migration/seed Job names with SHA: $SHORT_SHA"
           cd /tmp/infra
-          DEV_KUST="apps/groombook/overlays/dev/kustomization.yaml"
+          DEV_KUST="apps/overlays/dev/kustomization.yaml"
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/api")).newTag = env(TAG)' "$DEV_KUST"
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/migrate")).newTag = env(TAG)' "$DEV_KUST"
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$DEV_KUST"
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/reset")).newTag = env(TAG)' "$DEV_KUST"
 
-          MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
+          MIGRATE_JOB="apps/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
             yq -i '.spec.ttlSecondsAfterFinished = (.spec.ttlSecondsAfterFinished // 86400)' "$MIGRATE_JOB"
           fi
 
-          SEED_JOB="apps/groombook/base/seed-job.yaml"
+          SEED_JOB="apps/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$SEED_JOB"
@@ -237,7 +237,7 @@ jobs:
           git config user.name "groombook-engineer[bot]"
           git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "chore/update-image-tags-${TAG}"
-          git add apps/groombook/overlays/dev/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
+          git add apps/overlays/dev/ apps/base/migrate-job.yaml apps/base/seed-job.yaml
           git commit -m "chore: update image tags and migration/seed Job names to ${TAG}"
 
           git push -u origin "chore/update-image-tags-${TAG}"

.gitignore

@@ -1,10 +1,10 @@
 node_modules/
 dist/
+.DS_Store
+*.log
 .env
 .env.local
 *.local
-.DS_Store
-*.log
 .turbo/
 coverage/
 minimax-output/

Dockerfile

@@ -1,38 +1,69 @@
-FROM node:20-alpine AS base
-RUN corepack enable && corepack prepare pnpm@9.15.4 --activate
+FROM node:22-alpine AS base
+# Install pnpm as a real binary via npm (not corepack shim) so runtime
+# invocations of `pnpm` work without DNS access to registry.npmjs.org.
+# The corepack shim delegates to corepack, which re-validates against
+# npmjs.org on first use — that fails in air-gapped UAT seed/migrate/reset
+# Jobs. GRO-1983 / GRO-1889 / GRO-1909 / GRO-1981 / GRO-1985.
+RUN npm install -g pnpm@9.15.4
+# Belt-and-braces: disable Corepack's download fallback so that even if a
+# Corepack shim is somehow invoked at runtime, it will not try to fetch
+# pnpm from registry.npmjs.org. Belt for the real-binary trousers. GRO-1985.
+ENV COREPACK_ENABLE_DOWNLOAD_FALLBACK=0
 WORKDIR /app
 
+# Install deps
 FROM base AS deps
-COPY package.json pnpm-lock.yaml ./
-COPY apps/api/package.json apps/api/
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY packages/db/package.json packages/db/
+COPY packages/types/package.json packages/types/
 RUN pnpm install --frozen-lockfile
 
+# Build
 FROM deps AS builder
-RUN mkdir -p /home/node/.cache/node/corepack
-COPY apps/api/ apps/api/
-RUN pnpm --filter @groombook/api build
+COPY packages/ packages/
+COPY src/ src/
+COPY tsconfig.json ./
+RUN pnpm --filter @groombook/types build && \
+    pnpm --filter @groombook/db build && \
+    pnpm build
 
-FROM node:20-alpine AS runner
-RUN corepack enable && corepack prepare pnpm@9.15.4 --activate
+# Runtime
+FROM node:22-alpine AS runner
+RUN npm install -g pnpm@9.15.4
+# Same defence-in-depth as base: no Corepack fallback. GRO-1985.
+ENV COREPACK_ENABLE_DOWNLOAD_FALLBACK=0
 WORKDIR /app
 ENV NODE_ENV=production
 
-COPY package.json pnpm-lock.yaml ./
-COPY --from=builder /app/apps/api/package.json apps/api/
-COPY --from=builder /app/apps/api/dist apps/api/dist
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/dist dist/
+COPY --from=builder /app/packages/db/package.json packages/db/
+COPY --from=builder /app/packages/db/dist packages/db/dist
+COPY --from=builder /app/packages/types/package.json packages/types/
+COPY --from=builder /app/packages/types/dist packages/types/dist
 RUN pnpm install --frozen-lockfile --prod
 
 EXPOSE 3000
 RUN apk add --no-cache curl
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
   CMD curl -f http://localhost:3000/health || exit 1
-CMD ["node", "apps/api/dist/index.js"]
+CMD ["node", "dist/index.js"]
 
+# Migrate stage — runs drizzle-kit migrate against the database
 FROM builder AS migrate
-CMD ["pnpm", "--filter", "@groombook/api", "db:migrate"]
+# pnpm needs a writable HOME for any config/state it writes. With
+# readOnlyRootFilesystem: true and runAsUser: 1000, /home/node is read-only.
+# The job pods mount a writable emptyDir at /tmp; point HOME there. GRO-1985.
+ENV HOME=/tmp
+CMD ["pnpm", "--filter", "@groombook/db", "migrate"]
 
+# Seed stage — populates the database with test data
 FROM builder AS seed
-CMD ["pnpm", "--filter", "@groombook/api", "db:seed"]
+ENV HOME=/tmp
+CMD ["pnpm", "--filter", "@groombook/db", "seed"]
 
+# Reset stage — drops all tables, re-runs migrations, and re-seeds
 FROM builder AS reset
-CMD ["pnpm", "--filter", "@groombook/api", "db:reset"]
+ENV HOME=/tmp
+CMD ["pnpm", "--filter", "@groombook/db", "reset"]

README.md

@@ -13,7 +13,7 @@ This repository contains the GroomBook API service, including:
 ## Structure
 
 ```
-apps/api/        # API service source
+src/             # API service source
 packages/db/     # Database schema, migrations, and utilities
 packages/types/  # Shared TypeScript types
 ```

UAT_PLAYBOOK.md

@@ -19,15 +19,95 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 - OIDC authentication provider configured
 - Seed data present (clients, pets, services, staff)
 
+### Source of truth for UAT passwords (GRO-2000)
+
+The `UAT_SUPER_PASSWORD` / `UAT_GROOMER_PASSWORD` / `UAT_TESTER_PASSWORD` / `UAT_CUSTOMER_PASSWORD` env vars the test orchestrator uses **must** be pulled from the live `seed-uat-passwords` Secret in the UAT cluster — never from a captured shell value, a previous run's `.env`, or a copy of the SealedSecret committed before the latest rotation.
+
+**Canonical recipe** (works from any host with `kubectl` + cluster credentials):
+
+```bash
+SUPER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.super-password}' | base64 -d)
+GROOMER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.groomer-password}' | base64 -d)
+TESTER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.tester-password}' | base64 -d)
+CUSTOMER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.customer-password}' | base64 -d)
+```
+
+**Why:** the Bitnami SealedSecret `apps/overlays/uat/ss-seed-uat-passwords.yaml` (in `groombook/infra`) is the single source of truth. The UAT `reset-demo-data` CronJob re-hashes these values into the `account` table on every run (idempotent — GRO-1977). A captured env var from a previous generation will not match the current hash, producing 401 `INVALID_EMAIL_OR_PASSWORD`. If the live login still 401s after pulling from the SealedSecret, the seed Job is stale — trigger `kubectl create job --from=cronjob/reset-demo-data -n groombook-uat manual-seed-$$` and retry.
+
+**How to apply:** at the start of every UAT run that touches TC-API-1.4 / 1.5 / 1.6 / 1.7 / 3.18 / 3.21 / 3.23, refresh these four env vars from the cluster before issuing the sign-in request.
+
+### rbac auto-provision for Better-Auth customers (GRO-2052)
+
+> Applies to TC-API-3.16 / 3.19a / 3.19b / 3.19c (customer-as-owner profile-summary paths) and any future case where the test user authenticates via Better-Auth email/password and the route relies on `resolveStaffMiddleware` to resolve a `staff` row.
+
+**Pre-condition (rbac auto-provision):** The test user must have a row in the Better-Auth `user` table (email/password sign-in creates this automatically — see TC-API-1.6 / 1.7). On first authenticated call, `resolveStaffMiddleware` (`./src/middleware/rbac.ts`) auto-provisions a `groomer` staff row keyed by `staff.user_id = user.id` (Better-Auth branch fires before the legacy OIDC `account` branch).
+
+**Verify the auto-provision fired** by querying the DB after the first authenticated call:
+
+```sql
+SELECT user_id, role FROM staff WHERE user_id = '<test-user-id>';
+```
+
+Expected: one row, `role = 'groomer'`. If zero rows return, the request hit the OIDC `account` branch and 403'd, or the user has no `user` row — fix the test sign-in path before re-running.
+
+**Why this matters:** without the auto-provision branch, Better-Auth email/password customers (e.g. `uat-customer@groombook.dev`) have no `account` row for the OIDC providers, so `resolveStaffMiddleware` falls through to `403 "Forbidden: no staff record found for authenticated user"` *before* `pets.ts` can run the owner-bypass added in GRO-2013. The owner-bypass code is unreachable unless the auto-provision has fired. A green TC-API-3.19a therefore implicitly proves the auto-provision worked; if 3.19a fails with the pre-fix 403, the auto-provision branch is missing from the deployed `./src` tree (see [GRO-2052](/GRO/issues/GRO-2052)).
+
+**How to apply:** for every run of TC-API-3.16 / 3.19a / 3.19b / 3.19c, sign in via TC-API-1.6 (email+password) first to guarantee the `user` row exists, then run the profile-summary call, then assert the `staff` row above before declaring pass.
+
 ## Test Cases
 
+### 4.0 Health Check
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-0.1 | Unauthenticated health check | GET /api/health | 200 OK, `{"status":"ok"}` |
+
+> **Note (GRO-1544):** Health endpoint registered on `api` basePath before auth middleware at `/api/health`. The old path `/health` was incorrect (routed to web pod via HTTPRoute `/*` rule).
+
 ### 4.1 Authentication
 
 | # | Scenario | Steps | Expected |
 |---|----------|-------|----------|
 | TC-API-1.1 | Login via OIDC | POST to OIDC provider callback, verify JWT token issued | 200 OK, JWT returned with valid claims |
-| TC-API-1.2 | Session persistence | Make authenticated request, verify session token valid | 200 OK, request succeeds |
-| TC-API-1.3 | Logout | Call logout endpoint, verify token invalidated | 200 OK, subsequent requests return 401 |
+| TC-API-1.4 | Email+password login (UAT) | POST /api/auth/sign-in/email with uat-super@groombook.dev + SEED_UAT_SUPER_PASSWORD | 200 OK, session cookie returned |
+| TC-API-1.5 | Email+password login — groomer | POST /api/auth/sign-in/email with uat-groomer@groombook.dev + SEED_UAT_GROOMER_PASSWORD | 200 OK, session cookie returned |
+| TC-API-1.6 | Email+password login — customer | POST /api/auth/sign-in/email with uat-customer@groombook.dev + SEED_UAT_CUSTOMER_PASSWORD | 200 OK, session cookie returned |
+| TC-API-1.7 | Email+password login — tester | POST /api/auth/sign-in/email with uat-tester@groombook.dev + SEED_UAT_TESTER_PASSWORD | 200 OK, session cookie returned |
+| TC-API-1.8 | Email+password — invalid password | POST /api/auth/sign-in/email with wrong password | 400 Bad Request, error returned |
+| TC-API-1.9 | Email+password — unknown user | POST /api/auth/sign-in/email with non-existent email | 400 Bad Request, error returned |
+| TC-API-1.10 | Auto-provision on first OIDC login | First login as a Better-Auth user with no existing staff record | 200 OK, access granted; groomer staff record auto-created with name/email from user table |
+
+> **Note (GRO-1977):** Seed credential provisioning is idempotent — re-running the seed with updated `SEED_UAT_*_PASSWORD` env vars rotates stored credential hashes. TC-API-1.4 through TC-API-1.7 now return 200 for all 4 UAT personas (previously returned 401 due to frozen-hash bug).
+| TC-API-1.11 | Existing staff unaffected by OIDC login | Login as uat-groomer@groombook.dev (email+password), then GET /api/staff to find that record | 200 OK, staff record unchanged — no duplicate created, original role and isSuperUser preserved |
+| TC-API-1.12 | Auto-provisioned role and superUser flags | After TC-API-1.10, GET /api/staff and inspect the auto-created record | role = "groomer", isSuperUser = false, active = true |
+| TC-API-1.13 | Name fallback — user.name present | Auto-provision where Better-Auth user has name set | Staff name = user.name value from user table |
+| TC-API-1.14 | Name fallback — no name, email present | Auto-provision where Better-Auth user has name = null, email = "test@example.com" | Staff name = "test" (email prefix before @) |
+| TC-API-1.15 | Name fallback — no name, no email | Auto-provision where Better-Auth user has name = null, email = null | Staff name = "Unknown" |
+| TC-API-1.16 | OIDC login — Terraform-provisioned user | Initiate OIDC login as any UAT persona (uat-super, uat-groomer, uat-customer, uat-tester), complete authentik callback | 200 OK, session created — no account_not_linked error |
+
+#### SSO Login Journey (Authentik OIDC end-to-end)
+
+| # | Scenario | Steps | Pass Criteria | Fail Criteria |
+|---|----------|-------|---------------|---------------|
+| TC-API-1.17 | SSO redirect to Authentik | Navigate to app → sign-in page shown → click "Sign in with SSO" | Redirected to Authentik at auth.farh.net | 403 error, redirect loop, no SSO button |
+| TC-API-1.18 | Authenticate with valid OIDC credentials | At Authentik login page, enter valid credentials and authenticate | Redirected back to app with valid session | Redirect loop, 403, missing session cookie |
+| TC-API-1.19 | SSO user auto-provisioned as groomer | Complete SSO login as a user with no pre-existing staff record | 200 response; groomer staff record auto-created; session active | 403 Forbidden, staff record not created |
+| TC-API-1.20 | Existing staff record resolves correctly | Complete SSO login as uat-groomer (pre-existing staff) | 200 OK, correct staff identity resolved, no duplicate record created | 403, duplicate record, wrong staff data |
+| TC-API-1.21 | SSO session grants dashboard access | After TC-API-1.18 SSO login, GET /api/staff/me | 200 OK, valid staff record returned, correct role displayed | 401/403, missing session, wrong identity |
+
+#### OOBE Flow Post-Login
+
+| # | Scenario | Steps | Pass Criteria | Fail Criteria |
+|---|----------|-------|---------------|---------------|
+| TC-API-1.22 | Fresh DB reports needsSetup | On a fresh DB (no super user), GET /api/setup/status | needsSetup: true returned | needsSetup: false when it should be true |
+| TC-API-1.23 | Configure OIDC via auth-provider endpoint | POST /api/setup/auth-provider with valid OIDC config | 200 OK, auth provider configured, no 403 | 403, setup blocked, invalid config rejected |
+| TC-API-1.24 | Complete setup creates super user | POST /api/setup with business name (after TC-API-1.23) | First user becomes super user, setup completes | Setup errors, 403 on admin endpoints |
+| TC-API-1.25 | Super user accesses admin features | After TC-API-1.24, GET /api/staff/me and verify isSuperUser: true | isSuperUser: true, admin endpoints accessible | 403 on admin, isSuperUser: false |
+| TC-API-1.26 | Auto-provision skipped during OOBE | During fresh setup (needsSetup: true), complete OIDC login — verify no duplicate staff record created before setup completes | No duplicate staff, OOBE completes successfully | Duplicate staff record, 403 before setup, auto-provision interferes with OOBE |
 
 ### 4.2 Client Management
 
@@ -40,6 +120,24 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-2.5 | Disable client | PATCH /api/clients/{id} with status: "disabled" | 200 OK, client marked as disabled |
 | TC-API-2.6 | Delete client | DELETE /api/clients/{id}?confirm=true | 200 OK, client deleted (if no appointments) |
 
+#### Client Geocoding — Route Optimization (GRO-2154, Phase 1.3)
+
+Geocoding turns a client's street address into `latitude`/`longitude` + `geocodedAt`. Provider is driven by `businessSettings.routeOptimizationProvider` (default Nominatim/OpenStreetMap, 1 req/sec; optional Google fallback). All explicit geocode endpoints are **manager-only**.
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-2.7 | Geocode single client (success) | As **manager**, `POST /api/clients/{id}/geocode` for a client with a valid, real address (e.g. a seed client) | 200 OK; body `{ status: "geocoded", latitude, longitude, geocodedAt, formattedAddress, provider }`. Subsequent `GET /api/clients/{id}` shows the same non-null `latitude`/`longitude`/`geocodedAt` persisted |
+| TC-API-2.8 | Geocode single client — no address | As manager, `POST /api/clients/{id}/geocode` for a client whose `address` is null/blank | 422; `{ status: "no_address", message: "...no address on file..." }` (clear, actionable) |
+| TC-API-2.9 | Geocode single client — unresolvable/ambiguous address | As manager, set a nonsense address (e.g. `"asdkjhqweoui 99999"`) then `POST /api/clients/{id}/geocode` | 422; `{ status: "unresolved", message: "Address could not be resolved..." }` so groomers/managers know to correct it |
+| TC-API-2.10 | Geocode single client — not found | As manager, `POST /api/clients/00000000-0000-0000-0000-000000000000/geocode` | 404 `{ error: "Not found" }` |
+| TC-API-2.11 | Geocode endpoint is manager-only | As **groomer** or **receptionist**, `POST /api/clients/{id}/geocode` | 403 Forbidden (role not permitted) |
+| TC-API-2.12 | Batch geocode un-geocoded clients | As manager, `POST /api/clients/geocode-batch?limit=10` on a DB with un-geocoded clients | 200 OK; body `{ provider, processed, geocoded, unresolved, errors, remaining, outcomes[] }`. `processed` ≤ 10; `remaining` reflects un-geocoded clients beyond this batch. Re-run while `remaining > 0` to finish (throttled to provider rate limit) |
+| TC-API-2.13 | Batch geocode — invalid limit | As manager, `POST /api/clients/geocode-batch?limit=0` (or non-numeric) | 400 `{ error: "limit must be a positive integer" }` |
+| TC-API-2.14 | Batch geocode — manager-only | As groomer/receptionist, `POST /api/clients/geocode-batch` | 403 Forbidden |
+| TC-API-2.15 | Auto-geocode on create | As manager/receptionist, `POST /api/clients` with a valid `address` | 201 Created; response includes a `geocoding` object (`status: "geocoded"` for a resolvable address) and the persisted client carries `latitude`/`longitude`/`geocodedAt`. Creating without an address succeeds with no `geocoding` field |
+| TC-API-2.16 | Auto-geocode on address update | As manager/receptionist, `PATCH /api/clients/{id}` changing `address` to a new valid value | 200 OK; response includes a `geocoding` object and refreshed coordinates. Patching unrelated fields (e.g. `name`) does NOT re-geocode (no `geocoding` field) |
+| TC-API-2.17 | Clearing address drops coordinates | As manager/receptionist, `PATCH /api/clients/{id}` with `address: ""` | 200 OK; `latitude`/`longitude`/`geocodedAt` reset to null (no stale pin) |
+
 ### 4.3 Pet Management
 
 | # | Scenario | Steps | Expected |
@@ -51,6 +149,42 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-3.5 | Delete pet | DELETE /api/pets/{id} | 200 OK, pet deleted |
 | TC-API-3.6 | Upload pet photo | POST /api/pets/{id}/photo/upload-url, then confirm | 200 OK, photo uploaded and key stored |
 | TC-API-3.7 | View pet photo | GET /api/pets/{id}/photo | 200 OK, presigned URL returned |
+| TC-API-3.8 | Create pet with extended fields | POST /api/pets with coatType, temperamentScore, temperamentFlags, medicalAlerts, preferredCuts | 201 Created, all extended fields stored and returned |
+| TC-API-3.9 | Update pet extended fields | PATCH /api/pets/{id} with coatType, temperamentScore, medicalAlerts | 200 OK, extended fields updated |
+| TC-API-3.10 | Reject invalid coatType | POST /api/pets with coatType: "smooth" | 400 Bad Request, invalid coatType rejected |
+| TC-API-3.11 | Reject out-of-range temperamentScore | POST /api/pets with temperamentScore: 0 or 6 | 400 Bad Request, score out of range rejected |
+| TC-API-3.12 | Reject invalid medicalAlert severity | POST /api/pets with medicalAlerts severity: "critical" | 400 Bad Request, invalid severity rejected |
+| TC-API-3.13 | Reject too many temperamentFlags | POST /api/pets with 21 temperamentFlags | 400 Bad Request, max 20 flags enforced |
+| TC-API-3.14 | Reject too many preferredCuts | POST /api/pets with 21 preferredCuts | 400 Bad Request, max 20 cuts enforced |
+| TC-API-3.15 | Reject too many medicalAlerts | POST /api/pets with 51 medicalAlerts | 400 Bad Request, max 50 alerts enforced |
+| TC-API-3.16 | Get pet profile summary | GET /api/pets/{id}/profile-summary | 200 OK, aggregated profile with grooming history, visit count, upcoming appointment |
+| TC-API-3.17 | Get pet profile summary — groomer restricted | GET /api/pets/{id}/profile-summary as groomer with no pet linkage | 403 Forbidden |
+| TC-API-3.18 | Get pet profile summary — visitCount returns full count | GET /api/pets/{id}/profile-summary with 2+ completed appointments | visitCount >= 2 (not capped at 1) |
+| TC-API-3.19 | Get pet profile summary — upcomingAppointment excludes past | GET /api/pets/{id}/profile-summary with a past confirmed/scheduled appointment | upcomingAppointment is null (past appointments filtered by startTime >= now) |
+| TC-API-3.19a | Get pet profile summary — customer owner-bypass (GRO-2013) | Sign in as `uat-customer@groombook.dev`; `POST /api/portal/session-from-auth`; then `GET /api/pets/{ownPetId}/profile-summary` with header `X-Impersonation-Session-Id: {sessionId}` for either of the customer's seeded pets (`c0000001-0000-0000-0000-000000000002` UAT Pup Alpha, `c0000001-0000-0000-0000-000000000003` UAT Pup Beta) | 200 OK, aggregated profile returned (owner-bypass: customer with valid portal session for pet's clientId is allowed even though rbac.ts auto-provisions them as a `groomer` staff row with no appointment linkage) |
+| TC-API-3.19b | Get pet profile summary — customer cross-tenant blocked (GRO-2013) | Sign in as `uat-customer@groombook.dev`; reuse the customer's sessionId from TC-API-3.19a; `GET /api/pets/{otherClientPetId}/profile-summary` for a pet owned by a different client (`c0000002-...` or any non-customer pet) | 403 Forbidden (owner-bypass requires session.clientId === pet.clientId) |
+| TC-API-3.19c | Get pet profile summary — customer without portal session header | Same as TC-API-3.19a but omit the `X-Impersonation-Session-Id` header | 403 Forbidden (no owner-bypass without valid portal session) |
+| TC-API-3.19d | Get pet profile summary — owner-bypass writes audit row (GRO-2063) | Same setup as TC-API-3.19a (sign in as `uat-customer@groombook.dev`, establish a portal session for the customer's own clientId, call `GET /api/pets/{ownPetId}/profile-summary` with `X-Impersonation-Session-Id: {sessionId}` and a 200 OK response). Then call `GET /api/impersonation/sessions/{sessionId}/audit-log` and confirm there is exactly one entry with `action === "read_profile_summary"`, `pageVisited` matching the profile-summary path, and `metadata` containing `petId` and `actorStaffId` for the customer. Repeat TC-API-3.19b (cross-tenant attempt) and confirm NO new `read_profile_summary` row was written for the cross-tenant attempt. | 200 OK on the profile-summary call AND an audit log entry is present with the correct shape (defense-in-depth audit row; bypass attempts against other clients must NOT log) |
+| TC-API-3.29 | Get pet profile summary — unknown UUID returns 404 (GRO-2014) | GET /api/pets/00000000-0000-0000-0000-000000000001/profile-summary while authenticated (any role) | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014) |
+| TC-API-3.30 | Get pet profile summary — malformed UUID returns 404 (GRO-2014) | GET /api/pets/not-a-uuid/profile-summary while authenticated | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014 — Postgres uuid cast failure) |
+| TC-API-3.31 | Get pet profile summary — never empty-body 500 (GRO-2014) | GET /api/pets/{anyId}/profile-summary across the test sweep | No response has status 500 with an empty body. Any 500 must include a JSON body `{"error":"Internal Server Error"}` |
+
+#### Seed Data Verification (GRO-1898)
+
+> As of PR #98, UAT seed data populates all 5 extended profile fields for every pet, including the 5 deterministic UAT test client pets (Alpha, Bravo, Charlie, Delta, Echo). This enables manual verification of extended profile rendering without requiring a DB reset.
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-3.20 | GET /api/clients returns seed data | GET /api/clients | 200 OK, array with 1+ clients (UAT seed creates 500 + 5 deterministic UAT clients) |
+| TC-API-3.21 | GET /api/pets/{id} returns extended fields for seed pet | Pick any pet ID from UAT test clients (uat-alpha through uat-echo pet names: TestBuddy, TestMax, TestCooper, TestRocky, TestDuke) and GET /api/pets/{id} | 200 OK; coatType, temperamentScore, temperamentFlags, medicalAlerts, preferredCuts all non-null |
+| TC-API-3.22 | Verify medicalAlerts shape | GET /api/pets/{id} for any pet with non-empty medicalAlerts | medicalAlerts is an array; each entry has type, description, severity |
+| TC-API-3.23 | Verify UAT test pet Charlie has behavioral alert | GET /api/pets/{id} where name = "TestCooper" (pet for uat-charlie@groombook.dev) | medicalAlerts includes an entry with type: "behavioral", severity: "low" or "high" |
+| TC-API-3.24 | Verify UAT test pet Delta has skin alert | GET /api/pets/{id} where name = "TestRocky" (pet for uat-delta@groombook.dev) | medicalAlerts includes an entry with type: "skin" |
+| TC-API-3.25 | Verify 30+ total pets in UAT DB | GET /api/pets then count total | 30+ pets returned (UAT seed creates 500 random-pool + 5 UAT test clients + 2 UAT customer = 507 total) |
+| TC-API-3.26 | Verify 25-35% medicalAlerts distribution | GET /api/pets (first 30 pets), count how many have non-empty medicalAlerts | Ratio is 25-35% (seed uses rand() < 0.3 for ~30% distribution) |
+| TC-API-3.27 | Verify coat_type enum has all seed values | After UAT seed completes, inspect the coat_type enum on the UAT DB — it must contain: short, medium, long, double, wire, silky, curly, hairless | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; coat_type includes all 8 values used by seed.ts `coatTypePool` |
+| TC-API-3.28 | Verify pet_size_category enum has all seed values | After UAT seed completes, inspect the pet_size_category enum on the UAT DB — it must contain: small, medium, large, extra_large | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; pet_size_category includes all 4 values used by seed.ts `petSizeCategoryPool` (regression for GRO-1999, mirrors TC-API-3.27) |
+| TC-API-3.29 | Verify `reset-demo-data` CronJob does not fail with FK 23503 on `invoice_tip_splits` (GRO-2123) | Trigger the CronJob manually: `kubectl create job --from=cronjob/reset-demo-data verify-gro2123 -n groombook-uat`. Wait for pod to terminate. Inspect logs: `kubectl logs -n groombook-uat -l job-name=verify-gro2123` | Pod reaches `Completed` state; logs show `✓ Acquired seed advisory lock` and `✓ Released seed advisory lock` from `seed.ts`; no `PostgresError: … violates foreign key constraint "invoice_tip_splits_invoice_id_invoices_id_fk"` (code 23503); final counts unchanged (500 clients, ~4000 invoices) |
 
 ### 4.4 Appointment Scheduling
 
@@ -77,6 +211,33 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-5.4 | Update service | PATCH /api/services/{id} with updated fields | 200 OK, service updated |
 | TC-API-5.5 | Delete service | DELETE /api/services/{id} | 200 OK, service deleted |
 
+#### 4.5.1 Seed/Reset idempotency (GRO-2064)
+
+Services seeding is now keyed on the deterministic `services.id` (not `name`) and
+the reset path now `TRUNCATE`s `services` alongside the other dynamic tables.
+This means:
+
+- Running the seed Job twice in a row (no reset in between) converges to the
+  same catalogue — no `services_pkey` collision.
+- A `pnpm reset` followed by `pnpm seed` (or a CronJob reset fire) leaves the
+  catalogue exactly matching `servicesDef` (10 rows, ids `b0000001-…-001` …
+  `…-00a`), regardless of any stale rows that were present beforehand.
+- Mixed `seedKnownUsers` + full `seed()` invocations are safe — the
+  `demoSvcs` subset (Bath & Brush, Full Groom Small/Medium, Nail Trim) is
+  keyed on ids `…-001`, `…-002`, `…-003`, `…-005` and the upsert target
+  is `services.id`, so the same-id / different-name collision that broke
+  GRO-2033 (id `…-004` = "Nail Trim" vs servicesDef `…-004` =
+  "Full Groom — Large") cannot recur.
+
+**UAT regression** (verify after a new image is rolled out):
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-SEED-1 | Reset → seed converges | `kubectl -n groombook exec deploy/api -- pnpm reset && pnpm seed` | Seed completes 1/1, `services` count = 10, all ids match `servicesDef` |
+| TC-SEED-2 | Idempotent re-seed | Re-run `pnpm seed` without reset | Seed completes 1/1, no `services_pkey` errors, `services` count still 10 |
+| TC-SEED-3 | Catalogue matches servicesDef | `psql -c "SELECT id, name FROM services ORDER BY id"` | Rows `…-001`…`…-00a` with names "Bath & Brush"…"Sanitary Trim" exactly as in `servicesDef` |
+| TC-SEED-4 | Demo subset coexists | Run `seedKnownUsers` then full `seed` | No collision, demo subset (4 services) ends up with the same rows the full seed would write |
+
 ### 4.6 Staff Management
 
 | # | Scenario | Steps | Expected |
@@ -112,6 +273,15 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-8.5 | Add waitlist entry | POST /api/portal/waitlist with pet and service | 201 Created, waitlist entry created |
 | TC-API-8.6 | View portal invoices | GET /api/portal/invoices | 200 OK, list of client's invoices returned |
 | TC-API-8.7 | Pay multiple invoices | POST /api/portal/invoices/pay-multiple with invoice IDs | 200 OK, payment intent created |
+| TC-API-8.8 | SSO bridge — valid Better Auth session | POST /api/portal/session-from-auth with valid Better Auth session cookie (authenticated SSO user with matching client email) | 201 Created, `{sessionId, clientId, clientName}` returned |
+| TC-API-8.9 | SSO bridge — no Better Auth session | POST /api/portal/session-from-auth without Better Auth session cookie | 401 Unauthorized |
+| TC-API-8.10 | SSO bridge — no matching client | POST /api/portal/session-from-auth with valid Better Auth session for a user with no client record | 404 Not Found, error "No client record found for this user" |
+| TC-API-8.11 | SSO bridge — returned session works on portal routes | After TC-API-8.8, use returned sessionId as `X-Impersonation-Session-Id` header on GET /api/portal/me | 200 OK, client profile returned |
+| TC-API-8.12 | Portal GET pets returns extended fields (GRO-2187) | Establish a portal session (TC-API-8.8), then `GET /api/portal/pets` with `X-Impersonation-Session-Id` | 200 OK; each pet includes `coatType`, `petSizeCategory`, `healthAlerts`, `preferredCuts`, `medicalAlerts` (in addition to id/name/breed/weight/birthDate/photoUrl/notes) |
+| TC-API-8.13 | Portal pet update — owner success + persistence (GRO-2187, fixes [GRO-1480](/GRO/issues/GRO-1480) §5.23) | With a portal session for the pet's owner, `PATCH /api/portal/pets/{petId}` with body `{ "name": "...", "breed": "...", "weightKg": 18.25, "healthAlerts": "...", "coatType": "double", "petSizeCategory": "xlarge", "preferredCuts": ["teddy bear"], "medicalAlerts": [{"type":"allergy","description":"oatmeal","severity":"medium"}] }` | 200 OK; response reflects the update with `petSizeCategory: "extra_large"` (web `xlarge` → DB `extra_large`). A follow-up `GET /api/portal/pets` shows the persisted values |
+| TC-API-8.14 | Portal pet update — non-owner blocked (GRO-2187) | `PATCH /api/portal/pets/{petId}` for a pet owned by a different client, using another client's portal session | 403 Forbidden (or 404 if pet id is unknown); no mutation persisted |
+| TC-API-8.15 | Portal pet update — invalid enum rejected (GRO-2187) | `PATCH /api/portal/pets/{petId}` with `coatType: "fluffy"` or `petSizeCategory: "gigantic"` | 422 Unprocessable Entity; pet unchanged |
+| TC-API-8.16 | Portal pet update — malformed (non-UUID) petId returns 404 (GRO-2203) | With a valid portal session, `PATCH /api/portal/pets/not-a-uuid` with header `X-Impersonation-Session-Id` and body `{"coatType":"short"}` | 404 Not Found with body `{"error":"Not found"}` (was an unhandled 500 from the Postgres uuid cast in GRO-2203; mirrors the GRO-2014 guard). No mutation persisted |
 
 ### 4.9 Waitlist
 
@@ -177,6 +347,58 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-14.4 | Update group notes | PATCH /api/appointment-groups/{id} with notes | 200 OK, notes updated |
 | TC-API-14.5 | Cancel group | DELETE /api/appointment-groups/{id} | 200 OK, all appointments cancelled |
 
+### 4.15 Buffer Rules
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-15.1 | List buffer rules | GET /api/admin/buffer-rules | 200 OK, list of active buffer rules returned |
+| TC-API-15.2 | Create buffer rule | POST /api/admin/buffer-rules with service, species, sizeCategory, bufferMinutes | 201 Created, buffer rule created |
+| TC-API-15.3 | Update buffer rule | PATCH /api/admin/buffer-rules/{id} with updated bufferMinutes | 200 OK, buffer rule updated |
+| TC-API-15.4 | Delete buffer rule | DELETE /api/admin/buffer-rules/{id} | 200 OK, buffer rule removed |
+| TC-API-15.5 | Reject invalid bufferMinutes | POST /api/admin/buffer-rules with bufferMinutes: -5 | 400 Bad Request, invalid bufferMinutes rejected |
+| TC-API-15.6 | Reject missing required fields | POST /api/admin/buffer-rules with service only | 400 Bad Request, species and sizeCategory required |
+| TC-API-15.7 | Booking uses buffer | Book appointment for pet with sizeCategory; verify duration reflects buffer | 201 Created, appointment duration includes buffer time |
+
+### 4.16 Route Optimization — Route CRUD + Optimize (GRO-2155, Phase 2.1)
+
+A groomer's daily route is one row per `(staffId, routeDate)` in `groomer_routes`, with ordered `route_stops`. `POST /api/routes/optimize` pulls the day's non-cancelled appointments whose client is geocoded (GRO-2154), orders them (Google Directions `optimizeWaypoints` when a key is configured in `businessSettings.googleMapsApiKey`, else an offline nearest-neighbor heuristic), and persists `stopOrder`, `travelMinsFromPrev`, `travelDistanceKmFromPrev` plus route `totalTravelMins`/`totalDistanceKm`/`optimizedAt`. **Auth: manager (any groomer's route) or groomer (own route only); receptionists have no access.** Pre-condition: at least one geocoded client with appointments on the target date for the staff member (use §4.2 geocoding + a seed groomer).
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-16.1 | Fetch daily route (auto-create draft) | As **manager**, `GET /api/routes/daily?staffId={groomerId}&date=YYYY-MM-DD` for a date with no existing route | 200 OK; body `{ route, stops }`. `route.status` is `"draft"`, `route.staffId`/`routeDate` match, `stops` is `[]`. Re-calling returns the same route row (no duplicate) |
+| TC-API-16.2 | Optimize a multi-stop day | As manager, with ≥2 geocoded appointments for the groomer on the date, `POST /api/routes/optimize` body `{ "staffId": "{groomerId}", "date": "YYYY-MM-DD" }` | 200 OK; `route.status: "optimized"`, `optimizedAt` set, `totalTravelMins`/`totalDistanceKm` populated. `stops` ordered by `stopOrder` (1..N); first stop has `travelMinsFromPrev: null`, the rest positive. `provider` is `"nearest_neighbor"` (no Google key in UAT). The first stop carries `bufferMins: 0` (no predecessor); every later stop carries `bufferMins` = `businessSettings.defaultTravelBufferMins` (default 15). Response also includes `hasConflicts` / `conflictCount` and each stop a `conflict` object (GRO-2156, see §4.17) |
+| TC-API-16.3 | Re-optimize replaces prior order | As manager, run TC-API-16.2 twice | Second call returns 200; stops fully replaced (no duplicate `route_stops`, `stopOrder` still contiguous 1..N), `optimizedAt` refreshed |
+| TC-API-16.4 | Skips un-geocoded appointments | As manager, optimize a day where one appointment's client has no coordinates | 200 OK; that appointment is absent from `stops` and listed under `skipped[]` with `reason: "client address is not geocoded"`; a corresponding entry appears in `warnings[]` |
+| TC-API-16.5 | Empty / single-stop day | As manager, optimize a date with 0 (or 1) geocoded appointments | 200 OK; `route.status: "optimized"`, `totalTravelMins: 0`, `totalDistanceKm: "0.00"`. For 1 stop, `stops` has one entry with `travelMinsFromPrev: null` |
+| TC-API-16.6 | >25 stops chunked with warning | As manager, optimize a day with >25 geocoded appointments | 200 OK; `chunked: true`, `subRouteCount ≥ 2`, a `warnings[]` entry mentions sub-routes; all appointments appear exactly once with contiguous `stopOrder` |
+| TC-API-16.7 | Groomer reads own route | As **groomer**, `GET /api/routes/daily?date=YYYY-MM-DD` (omit staffId, or pass own id) | 200 OK; route resolves to the groomer's own `staffId` |
+| TC-API-16.8 | Groomer cannot access another's route | As groomer, `GET /api/routes/daily?staffId={otherGroomerId}&date=...` or `POST /api/routes/optimize` with another `staffId` | 403 Forbidden (`groomers may only access their own route`) |
+| TC-API-16.9 | Receptionist denied | As **receptionist**, `GET /api/routes/daily?...` or `POST /api/routes/optimize` | 403 Forbidden (role not permitted) |
+| TC-API-16.10 | Manager must supply staffId | As manager, `POST /api/routes/optimize` body `{ "date": "YYYY-MM-DD" }` (no staffId) | 400 `{ error: "staffId is required" }` |
+| TC-API-16.11 | Invalid date rejected | `GET /api/routes/daily?staffId=...&date=06-08-2026` (wrong format) | 400 validation error (`date must be YYYY-MM-DD`) |
+
+### 4.17 Route Optimization — Travel Buffer + Reorder (GRO-2156, Phase 2.2)
+
+Builds on §4.16. After optimization each consecutive leg carries a travel `bufferMins` (= `businessSettings.defaultTravelBufferMins`, default 15; the first stop is `0`). The API derives a per-stop **`conflict`** object at read time on `GET /api/routes/daily`, `POST /api/routes/optimize`, and `PATCH /api/routes/:routeId/reorder`:
+
+- `conflict.scheduleGapMins` — minutes between the previous appointment's `endTime` and this appointment's `startTime` (null for the first stop)
+- `conflict.requiredGapMins` — `travelMinsFromPrev + bufferMins` (null for the first stop)
+- `conflict.shortfallMins` — `requiredGapMins − scheduleGapMins` (positive ⇒ tight)
+- `conflict.hasConflict` — true when `shortfallMins > 0` ("tight schedule"); appointments are **never auto-moved**, only flagged
+
+`PATCH /api/routes/:routeId/reorder` accepts `{ "stopOrder": ["<routeStopId>", …] }` (every current stop id, exactly once, first-to-last), persists the new `stopOrder`, re-estimates each leg's travel offline for the new adjacency, re-applies buffers, recomputes route totals, and returns the route with refreshed conflict flags. **Auth: manager (any route) or groomer (own route only).**
+
+| ID | Scenario | Steps | Expected |
+|----|----------|-------|----------|
+| TC-API-17.1 | Conflict flags on optimize | As manager, optimize a day with ≥2 geocoded appointments whose times are close together | 200 OK; top-level `hasConflicts` (bool) + `conflictCount` (int). First stop `conflict.hasConflict:false` with null gap fields. A later stop whose `scheduleGapMins < travelMinsFromPrev + bufferMins` has `conflict.hasConflict:true` and positive `shortfallMins` |
+| TC-API-17.2 | No false conflict on a roomy schedule | Optimize a day where appointment gaps comfortably exceed travel + buffer | 200 OK; `hasConflicts:false`, `conflictCount:0`, every `conflict.shortfallMins ≤ 0` |
+| TC-API-17.3 | Reorder persists new order | As manager, take an optimized route, `PATCH /api/routes/{routeId}/reorder` with the stop ids in a new order | 200 OK; `stops` returned in the requested order with contiguous `stopOrder` 1..N; first stop `travelMinsFromPrev:null`/`bufferMins:0`, others recomputed; `route.totalTravelMins`/`totalDistanceKm` updated |
+| TC-API-17.4 | Reorder re-flags conflicts | Reorder so a far-apart pair becomes adjacent | 200 OK; `conflict` flags recomputed for the new adjacency (`hasConflicts`/`conflictCount` reflect the new order) |
+| TC-API-17.5 | Reorder validation — wrong stop set | `PATCH …/reorder` with a missing, extra, duplicate, or unknown stop id | 400 with an explanatory `error` (e.g. "must list every stop exactly once", "unknown stop id", "duplicate stop id") |
+| TC-API-17.6 | Reorder unknown route | `PATCH /api/routes/{randomUuid}/reorder` with any body | 404 `{ error: "Route not found" }` |
+| TC-API-17.7 | Reorder invalid routeId | `PATCH /api/routes/not-a-uuid/reorder` | 400 `{ error: "routeId must be a UUID" }` |
+| TC-API-17.8 | Groomer cannot reorder another's route | As groomer, reorder a route owned by a different groomer | 403 Forbidden (`groomers may only access their own route`) |
+
 ## Pass/Fail Criteria
 
 **Pass:**

apps/api/drizzle.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "drizzle-kit";
 
 export default defineConfig({
-  schema: "./src/schema.ts",
+  schema: "./src/db/schema.ts",
   out: "./migrations",
   dialect: "postgresql",
   dbCredentials: {

apps/api/migrations/0030_extended_pet_profile.sql

@@ -0,0 +1,12 @@
+-- Migration: 0030_extended_pet_profile
+-- Adds extended profile fields to the pets table
+
+BEGIN;
+
+ALTER TABLE pets ADD COLUMN coat_type text;
+ALTER TABLE pets ADD COLUMN temperament_score integer;
+ALTER TABLE pets ADD COLUMN temperament_flags jsonb DEFAULT '[]'::jsonb;
+ALTER TABLE pets ADD COLUMN medical_alerts jsonb DEFAULT '[]'::jsonb;
+ALTER TABLE pets ADD COLUMN preferred_cuts jsonb DEFAULT '[]'::jsonb;
+
+COMMIT;

apps/api/migrations/meta/0030_snapshot.json

@@ -0,0 +1,48 @@
+{
+  "id": "0030_extended_pet_profile",
+  "prevId": "0028_sms_reminders",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.pets": {
+      "name": "pets",
+      "schema": "",
+      "columns": {
+        "id": { "name": "id", "type": "uuid", "primaryKey": true, "default": "gen_random_uuid()", "isNullable": false },
+        "client_id": { "name": "client_id", "type": "uuid", "isNullable": false },
+        "name": { "name": "name", "type": "text", "isNullable": false },
+        "species": { "name": "species", "type": "text", "isNullable": false },
+        "breed": { "name": "breed", "type": "text", "isNullable": true },
+        "weight_kg": { "name": "weight_kg", "type": "numeric(5, 2)", "isNullable": true },
+        "date_of_birth": { "name": "date_of_birth", "type": "timestamp", "isNullable": true },
+        "health_alerts": { "name": "health_alerts", "type": "text", "isNullable": true },
+        "grooming_notes": { "name": "grooming_notes", "type": "text", "isNullable": true },
+        "cut_style": { "name": "cut_style", "type": "text", "isNullable": true },
+        "shampoo_preference": { "name": "shampoo_preference", "type": "text", "isNullable": true },
+        "special_care_notes": { "name": "special_care_notes", "type": "text", "isNullable": true },
+        "custom_fields": { "name": "custom_fields", "type": "jsonb", "isNullable": false, "default": "'{}'::jsonb" },
+        "photo_key": { "name": "photo_key", "type": "text", "isNullable": true },
+        "photo_uploaded_at": { "name": "photo_uploaded_at", "type": "timestamp", "isNullable": true },
+        "image": { "name": "image", "type": "text", "isNullable": true },
+        "coat_type": { "name": "coat_type", "type": "text", "isNullable": true },
+        "temperament_score": { "name": "temperament_score", "type": "integer", "isNullable": true },
+        "temperament_flags": { "name": "temperament_flags", "type": "jsonb", "isNullable": true, "default": "'[]'::jsonb" },
+        "medical_alerts": { "name": "medical_alerts", "type": "jsonb", "isNullable": true, "default": "'[]'::jsonb" },
+        "preferred_cuts": { "name": "preferred_cuts", "type": "jsonb", "isNullable": true, "default": "'[]'::jsonb" },
+        "created_at": { "name": "created_at", "type": "timestamp", "isNullable": false, "default": "now()" },
+        "updated_at": { "name": "updated_at", "type": "timestamp", "isNullable": false, "default": "now()" }
+      },
+      "indexes": { "idx_pets_client_id": { "name": "idx_pets_client_id", "columns": [{ "expression": "client_id", "isExpression": false, "asc": true, "nulls": "last" }], "isUnique": false } },
+      "foreignKeys": { "pets_client_id_clients_id_fk": { "name": "pets_client_id_clients_id_fk", "tableFrom": "pets", "tableTo": "clients", "columnsFrom": ["client_id"], "columnsTo": ["id"], "onDelete": "cascade" } },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {}
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": { "columns": {}, "schemas": {}, "tables": {} }
+}

apps/api/migrations/meta/_journal.json

@@ -204,6 +204,20 @@
       "when": 1775741667192,
       "tag": "0028_sms_reminders",
       "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1775828067192,
+      "tag": "0029_db_indexes_constraints",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1775914467192,
+      "tag": "0030_extended_pet_profile",
+      "breakpoints": true
     }
   ]
 }

apps/api/package.json

@@ -12,8 +12,8 @@
     "test": "vitest run",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
-    "db:seed": "tsx src/db/seed.ts",
-    "db:reset": "tsx src/db/reset.ts && drizzle-kit migrate && tsx src/db/seed.ts",
+    "db:seed": "pnpm --filter @groombook/db seed",
+    "db:reset": "pnpm --filter @groombook/db reset",
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {

apps/api/src/__tests__/petProfileSummary.test.ts

@@ -0,0 +1,517 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+import type { AppEnv, StaffRow } from "../middleware/rbac.js";
+import { petsRouter } from "../routes/pets.js";
+
+// ─── Mock staff fixtures ──────────────────────────────────────────────────────
+
+const MANAGER: StaffRow = {
+  id: "staff-manager-id",
+  oidcSub: "oidc-manager-sub",
+  userId: null,
+  role: "manager",
+  isSuperUser: true,
+  name: "Manager McManager",
+  email: "manager@example.com",
+  active: true,
+  icalToken: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+const GROOMER: StaffRow = {
+  id: "staff-groomer-id",
+  oidcSub: "oidc-groomer-sub",
+  userId: null,
+  role: "groomer",
+  isSuperUser: false,
+  name: "Groomer McGroome",
+  email: "groomer@example.com",
+  active: true,
+  icalToken: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+// ─── Mutable mock state ───────────────────────────────────────────────────────
+
+const CLIENT_ID = "client-uuid-summary";
+const PET_ID = "pet-uuid-summary";
+
+interface MockState {
+  pets: Record<string, unknown>[];
+  appointments: Record<string, unknown>[];
+  groomingLogs: Record<string, unknown>[];
+  staffMembers: Record<string, unknown>[];
+  services: Record<string, unknown>[];
+  impersonationSessions: Record<string, unknown>[];
+}
+
+let mock: MockState;
+
+function resetMock() {
+  mock = {
+    pets: [{
+      id: PET_ID,
+      clientId: CLIENT_ID,
+      name: "Biscuit",
+      species: "dog",
+      breed: "Golden Retriever",
+      weightKg: "30.00",
+      dateOfBirth: null,
+      healthAlerts: null,
+      groomingNotes: null,
+      cutStyle: null,
+      shampooPreference: null,
+      specialCareNotes: null,
+      customFields: {},
+      photoKey: null,
+      photoUploadedAt: null,
+      image: null,
+      coatType: "double",
+      temperamentScore: 3,
+      temperamentFlags: ["gentle"],
+      medicalAlerts: [],
+      preferredCuts: ["puppy cut"],
+      createdAt: new Date("2024-01-01"),
+      updatedAt: new Date("2024-01-01"),
+    }],
+    appointments: [
+      {
+        id: "appt-completed-1",
+        clientId: CLIENT_ID,
+        petId: PET_ID,
+        serviceId: "service-1",
+        staffId: "staff-groomer-id",
+        batherStaffId: null,
+        status: "completed",
+        startTime: new Date("2024-06-01T09:00:00Z"),
+        endTime: new Date("2024-06-01T11:00:00Z"),
+        notes: null,
+        priceCents: 6000,
+        seriesId: null,
+        seriesIndex: null,
+        groupId: null,
+        confirmationStatus: "confirmed",
+        confirmedAt: null,
+        cancelledAt: null,
+        confirmationToken: null,
+        customerNotes: null,
+        createdAt: new Date("2024-05-15"),
+        updatedAt: new Date("2024-05-15"),
+      },
+      {
+        id: "appt-upcoming-1",
+        clientId: CLIENT_ID,
+        petId: PET_ID,
+        serviceId: "service-2",
+        staffId: "staff-groomer-id",
+        batherStaffId: null,
+        status: "confirmed",
+        startTime: new Date("2024-12-01T09:00:00Z"),
+        endTime: new Date("2024-12-01T11:00:00Z"),
+        notes: null,
+        priceCents: 6500,
+        seriesId: null,
+        seriesIndex: null,
+        groupId: null,
+        confirmationStatus: "confirmed",
+        confirmedAt: null,
+        cancelledAt: null,
+        confirmationToken: null,
+        customerNotes: null,
+        createdAt: new Date("2024-11-01"),
+        updatedAt: new Date("2024-11-01"),
+      },
+    ],
+    groomingLogs: [
+      {
+        id: "log-1",
+        petId: PET_ID,
+        appointmentId: "appt-completed-1",
+        staffId: "staff-groomer-id",
+        cutStyle: "puppy cut",
+        productsUsed: "oatmeal shampoo",
+        notes: "Trimmed nails",
+        groomedAt: new Date("2024-06-01T10:00:00Z"),
+        createdAt: new Date("2024-06-01T10:00:00Z"),
+      },
+    ],
+    staffMembers: [
+      {
+        id: "staff-groomer-id",
+        name: "Groomer McGroome",
+        email: "groomer@example.com",
+        role: "groomer",
+        isSuperUser: false,
+        active: true,
+        oidcSub: "oidc-groomer-sub",
+        userId: null,
+        icalToken: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: "staff-manager-id",
+        name: "Manager McManager",
+        email: "manager@example.com",
+        role: "manager",
+        isSuperUser: true,
+        active: true,
+        oidcSub: "oidc-manager-sub",
+        userId: null,
+        icalToken: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ],
+    services: [
+      { id: "service-1", name: "Full Groom", description: null, basePriceCents: 6000, durationMinutes: 120, active: true, createdAt: new Date(), updatedAt: new Date() },
+      { id: "service-2", name: "Bath & Brush", description: null, basePriceCents: 4000, durationMinutes: 60, active: true, createdAt: new Date(), updatedAt: new Date() },
+    ],
+    impersonationSessions: [
+      {
+        id: "sess-owner",
+        staffId: "staff-groomer-id",
+        clientId: CLIENT_ID,
+        reason: "sso-bridge",
+        status: "active",
+        startedAt: new Date("2024-11-01"),
+        endedAt: null,
+        expiresAt: new Date("2099-01-01T00:00:00Z"),
+        createdAt: new Date("2024-11-01"),
+      },
+    ],
+  };
+}
+
+vi.mock("../db/index.js", () => {
+  const pets = new Proxy({ _name: "pets" }, { get: (t, p) => p === "_name" ? "pets" : {} });
+  const appointments = new Proxy({ _name: "appointments" }, { get: (t, p) => p === "_name" ? "appointments" : {} });
+  const groomingVisitLogs = new Proxy({ _name: "groomingVisitLogs" }, { get: (t, p) => p === "_name" ? "groomingVisitLogs" : {} });
+  const staff = new Proxy({ _name: "staff" }, { get: (t, p) => p === "_name" ? "staff" : {} });
+  const services = new Proxy({ _name: "services" }, { get: (t, p) => p === "_name" ? "services" : {} });
+  const impersonationSessions = new Proxy({ _name: "impersonationSessions" }, { get: (t, p) => p === "_name" ? "impersonationSessions" : {} });
+
+  // Tracks { [tableName]: { [alias]: SQLExpression } } for the current select() call
+  let selectedColumns: Record<string, Record<string, unknown>> = {};
+
+  function makeChainable(rows: unknown[]) {
+    const arr = rows as unknown[];
+    return new Proxy(arr, {
+      get(target, prop) {
+        if (prop === "where" || prop === "orderBy" || prop === "limit" || prop === "leftJoin" || prop === "from") {
+          return () => makeChainable(target);
+        }
+        if (prop === Symbol.iterator) {
+          return function* () { for (const v of target) yield v; };
+        }
+        if (prop === Symbol.asyncIterator) {
+          return async function* () { for (const v of target) yield v; };
+        }
+        // @ts-expect-error proxy
+        return target[prop];
+      },
+    });
+  }
+
+  // sql mock: returns an object with .as() so drizzle's select() can alias it
+  function sqlMock(_strings: TemplateStringsArray, ..._params: unknown[]) {
+    const queryString = _strings[0];
+    const asFn = (alias: string) => ({
+      sql: { queryChunks: [_strings[0]] },
+      fieldAlias: alias,
+      getSQL() { return this.sql; },
+    });
+    return { queryChunks: [queryString], as: asFn };
+  }
+
+  return {
+    getDb: () => ({
+      select: (cols?: Record<string, unknown>) => {
+        selectedColumns = {};
+        if (cols) {
+          // Inspect cols to find sql-aliased expressions and their aliases
+          for (const [alias, expr] of Object.entries(cols)) {
+            if (expr && typeof expr === "object" && "as" in expr && typeof (expr as Record<string, unknown>).as === "function") {
+              const aliased = (expr as { as: (a: string) => { fieldAlias: string; sql: unknown } }).as(alias);
+              // Detect count(*) queries
+              if (typeof aliased.sql === "object" && aliased.sql !== null && "queryChunks" in (aliased.sql as Record<string, unknown>) && String((aliased.sql as { queryChunks?: unknown[] }).queryChunks).includes("count")) {
+                // Store count query intent — we'll resolve it in from()
+                if (!selectedColumns["appointments"]) selectedColumns["appointments"] = {};
+                selectedColumns["appointments"][alias] = { _isCountQuery: true };
+              }
+            }
+          }
+        }
+        return {
+          from: (table: unknown) => {
+            const name = (table as { _name?: string })._name;
+            const tableCols = selectedColumns[name] || {};
+            // If this table has a count query, return computed count result
+            const countQueryEntry = Object.entries(tableCols).find(([, v]) =>
+              typeof v === "object" && v !== null && "_isCountQuery" in v
+            );
+            if (countQueryEntry) {
+              const [countAlias] = countQueryEntry;
+              const count = (name === "appointments" ? mock.appointments : [])
+                .filter((row: Record<string, unknown>) => row.status === "completed").length;
+              return makeChainable([{ [countAlias]: count }]);
+            }
+            if (name === "pets") return makeChainable(mock.pets);
+            if (name === "appointments") return makeChainable(mock.appointments);
+            if (name === "groomingVisitLogs") return makeChainable(mock.groomingLogs);
+            if (name === "staff") return makeChainable(mock.staffMembers);
+            if (name === "services") return makeChainable(mock.services);
+            if (name === "impersonationSessions") return makeChainable(mock.impersonationSessions);
+            return makeChainable([]);
+          },
+        };
+      },
+      insert: () => ({ values: () => ({ returning: () => [{}] }) }),
+      update: () => ({ set: () => ({ where: () => ({ returning: () => [{}] }) }) }),
+      delete: () => ({ where: () => ({ returning: () => [{}] }) }),
+    }),
+    pets,
+    appointments,
+    groomingVisitLogs,
+    staff,
+    services,
+    impersonationSessions,
+    and: vi.fn((a: unknown, b: unknown) => [a, b]),
+    desc: vi.fn((c: unknown) => c),
+    eq: vi.fn((_col: unknown, _val: unknown) => ({ col: _col, val: _val })),
+    exists: vi.fn(() => true),
+    gte: vi.fn((a: unknown, b: unknown) => ({ col: a, val: b })),
+    or: vi.fn((a: unknown, b: unknown) => [a, b]),
+    sql: sqlMock,
+  };
+});
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeApp(staff: StaffRow = MANAGER) {
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("staff", staff);
+    await next();
+  });
+  return app.route("/pets", petsRouter);
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("GET /:id/profile-summary", () => {
+  beforeEach(resetMock);
+
+  it("returns 404 for non-existent pet", async () => {
+    const app = makeApp();
+    mock.pets = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(404);
+  });
+
+  it("returns 403 for groomer with no pet linkage", async () => {
+    const app = makeApp(GROOMER);
+    // Groomer has no linkage to this pet's client — clear appointments
+    mock.appointments = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(403);
+  });
+
+  it("returns complete aggregated profile for manager", async () => {
+    const app = makeApp(MANAGER);
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toBe(PET_ID);
+    expect(body.name).toBe("Biscuit");
+    expect(body.species).toBe("dog");
+    expect(body.recentGroomingHistory).toBeInstanceOf(Array);
+    expect(body.lastVisitDate).toBeTruthy();
+    expect(body.visitCount).toBeGreaterThanOrEqual(0);
+  });
+
+  it("groomer with pet linkage returns 200", async () => {
+    const app = makeApp(GROOMER);
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+  });
+
+  it("recentGroomingHistory is limited to 10 entries", async () => {
+    const app = makeApp(MANAGER);
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.recentGroomingHistory.length).toBeLessThanOrEqual(10);
+  });
+
+  it("returns null upcomingAppointment when none scheduled", async () => {
+    const app = makeApp(MANAGER);
+    mock.appointments = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.upcomingAppointment).toBeNull();
+  });
+});
+
+describe("GET /:id/profile-summary — visitCount", () => {
+  beforeEach(resetMock);
+
+  it("returns visitCount >= 2 when pet has 2+ completed appointments", async () => {
+    const app = makeApp(MANAGER);
+    // Add a second completed appointment
+    mock.appointments = [
+      ...mock.appointments,
+      {
+        id: "appt-completed-2",
+        clientId: CLIENT_ID,
+        petId: PET_ID,
+        serviceId: "service-1",
+        staffId: "staff-groomer-id",
+        batherStaffId: null,
+        status: "completed",
+        startTime: new Date("2024-07-01T09:00:00Z"),
+        endTime: new Date("2024-07-01T11:00:00Z"),
+        notes: null,
+        priceCents: 6000,
+        seriesId: null,
+        seriesIndex: null,
+        groupId: null,
+        confirmationStatus: "confirmed",
+        confirmedAt: null,
+        cancelledAt: null,
+        confirmationToken: null,
+        customerNotes: null,
+        createdAt: new Date("2024-06-15"),
+        updatedAt: new Date("2024-06-15"),
+      },
+    ];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.visitCount).toBeGreaterThanOrEqual(2);
+  });
+
+  it("returns visitCount = 0 when no completed appointments", async () => {
+    const app = makeApp(MANAGER);
+    mock.appointments = mock.appointments.map((a) => ({ ...a, status: "cancelled" }));
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.visitCount).toBe(0);
+  });
+});
+
+describe("GET /:id/profile-summary — empty history", () => {
+  beforeEach(resetMock);
+
+  it("returns empty history array when no grooming logs", async () => {
+    const app = makeApp(MANAGER);
+    mock.groomingLogs = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.recentGroomingHistory).toEqual([]);
+    expect(body.lastVisitDate).toBeNull();
+  });
+});
+
+describe("GET /:id/profile-summary — owner-bypass via X-Impersonation-Session-Id (GRO-2013)", () => {
+  beforeEach(resetMock);
+
+  // Simulates the rbac.ts auto-provisioned "groomer" that a customer gets on first login:
+  // role=groomer, no linkage to any appointment.
+  const CUSTOMER_STAFF: StaffRow = {
+    id: "staff-customer-id",
+    oidcSub: null,
+    userId: "user-customer-id",
+    role: "groomer",
+    isSuperUser: false,
+    name: "UAT Customer",
+    email: "uat-customer@groombook.dev",
+    active: true,
+    icalToken: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  it("customer with valid portal session for pet's client returns 200 (owner-bypass)", async () => {
+    const app = makeApp(CUSTOMER_STAFF);
+    // Groomer has no appointment linkage — proves the bypass is via portal session, not linkage.
+    mock.appointments = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
+      headers: { "X-Impersonation-Session-Id": "sess-owner" },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toBe(PET_ID);
+    expect(body.name).toBe("Biscuit");
+    expect(body.clientId).toBe(CLIENT_ID);
+  });
+
+  it("customer without X-Impersonation-Session-Id header still gets 403 (no bypass)", async () => {
+    const app = makeApp(CUSTOMER_STAFF);
+    mock.appointments = [];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(403);
+  });
+
+  it("customer with portal session for a DIFFERENT client gets 403 (cross-tenant blocked)", async () => {
+    const app = makeApp(CUSTOMER_STAFF);
+    mock.appointments = [];
+    mock.impersonationSessions = [
+      {
+        id: "sess-other-client",
+        staffId: "staff-customer-id",
+        clientId: "00000000-0000-0000-0000-000000000099", // different from CLIENT_ID
+        reason: "sso-bridge",
+        status: "active",
+        startedAt: new Date("2024-11-01"),
+        endedAt: null,
+        expiresAt: new Date("2099-01-01T00:00:00Z"),
+        createdAt: new Date("2024-11-01"),
+      },
+    ];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
+      headers: { "X-Impersonation-Session-Id": "sess-other-client" },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it("customer with expired portal session still gets 403", async () => {
+    const app = makeApp(CUSTOMER_STAFF);
+    mock.appointments = [];
+    mock.impersonationSessions = [
+      {
+        id: "sess-expired",
+        staffId: "staff-customer-id",
+        clientId: CLIENT_ID,
+        reason: "sso-bridge",
+        status: "active",
+        startedAt: new Date("2024-01-01"),
+        endedAt: null,
+        expiresAt: new Date("2024-02-01T00:00:00Z"), // expired long ago
+        createdAt: new Date("2024-01-01"),
+      },
+    ];
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
+      headers: { "X-Impersonation-Session-Id": "sess-expired" },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it("manager does NOT need the impersonation header (existing role check still works)", async () => {
+    const app = makeApp(MANAGER);
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+  });
+
+  it("groomer with linkage to pet's client still works (regression — no regression from bypass)", async () => {
+    const app = makeApp(GROOMER);
+    // GROOMER fixture has appointments linked to staff-groomer-id in the mock state
+    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
+    expect(res.status).toBe(200);
+  });
+});

apps/api/src/__tests__/petsExtendedFields.test.ts

@@ -0,0 +1,416 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+import type { AppEnv, StaffRow } from "../middleware/rbac.js";
+import { petsRouter } from "../routes/pets.js";
+import { and, eq, exists, or } from "../db/index.js";
+
+// ─── Mock staff fixtures ──────────────────────────────────────────────────────
+
+const MANAGER: StaffRow = {
+  id: "staff-manager-id",
+  oidcSub: "oidc-manager-sub",
+  userId: null,
+  role: "manager",
+  isSuperUser: true,
+  name: "Manager McManager",
+  email: "manager@example.com",
+  active: true,
+  icalToken: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+// ─── Mutable mock state ───────────────────────────────────────────────────────
+
+const CLIENT_ID = "a0000000-0000-4000-8000-000000000001";
+const PET_ID = "b0000000-0000-4000-8000-000000000002";
+
+let petRows: Record<string, unknown>[] = [];
+let appointmentRows: Record<string, unknown>[] = [];
+let insertedValues: Record<string, unknown>[] = [];
+let updatedValues: Record<string, unknown>[] = [];
+let deletedId: string | null = null;
+
+function resetMock() {
+  petRows = [{
+    id: PET_ID,
+    clientId: CLIENT_ID,
+    name: "Biscuit",
+    species: "dog",
+    breed: "Golden Retriever",
+    weightKg: "30.00",
+    dateOfBirth: null,
+    healthAlerts: null,
+    groomingNotes: null,
+    cutStyle: null,
+    shampooPreference: null,
+    specialCareNotes: null,
+    customFields: {},
+    photoKey: null,
+    photoUploadedAt: null,
+    image: null,
+    coatType: null,
+    temperamentScore: null,
+    temperamentFlags: [],
+    medicalAlerts: [],
+    preferredCuts: [],
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }];
+  appointmentRows = [];
+  insertedValues = [];
+  updatedValues = [];
+  deletedId = null;
+}
+
+function makeSelectChainable(rows: unknown[]): unknown {
+  const chain = new Proxy([...rows], {
+    get(target, prop) {
+      if (prop === "where" || prop === "orderBy" || prop === "limit") {
+        return () => chain;
+      }
+      // @ts-expect-error proxy
+      return target[prop];
+    },
+  });
+  return chain;
+}
+
+function makeInsertChainable(): unknown {
+  let vals: Record<string, unknown> = {};
+  const chain = new Proxy({}, {
+    get(target, prop) {
+      if (prop === "values") {
+        return (v: Record<string, unknown>) => { vals = v; return chain; };
+      }
+      if (prop === "returning") {
+        return () => {
+          insertedValues.push(vals);
+          return [vals.id ? { ...vals, id: vals.id ?? PET_ID } : { ...vals, id: PET_ID }];
+        };
+      }
+      return chain;
+    },
+  });
+  return chain;
+}
+
+function makeUpdateChainable(): unknown {
+  let vals: Record<string, unknown> = {};
+  let whereId: string | null = null;
+  const chain = new Proxy({}, {
+    get(target, prop) {
+      if (prop === "set") {
+        return (v: Record<string, unknown>) => { vals = v; return chain; };
+      }
+      if (prop === "where") {
+        return (cond: unknown) => {
+          // Extract id from condition if it's an eq call
+          if (whereId) vals = { ...vals };
+          return chain;
+        };
+      }
+      if (prop === "returning") {
+        return () => {
+          const merged = { ...petRows[0], ...vals };
+          updatedValues.push(vals);
+          return [merged];
+        };
+      }
+      return chain;
+    },
+  });
+  return chain;
+}
+
+function makeDeleteChainable(): unknown {
+  let whereId: string | null = null;
+  const chain = new Proxy({}, {
+    get(target, prop) {
+      if (prop === "where") {
+        return (cond: unknown) => {
+          whereId = PET_ID;
+          return chain;
+        };
+      }
+      if (prop === "returning") {
+        return () => {
+          const row = petRows[0]!;
+          deletedId = row.id as string;
+          return [row];
+        };
+      }
+      return chain;
+    },
+  });
+  return chain;
+}
+
+vi.mock("../db", async (importOriginal) => {
+  const db = await importOriginal<typeof import("../db/index.js")>();
+  const pets = new Proxy({ _name: "pets" }, { get: (t, p) => p === "_name" ? "pets" : {} });
+  const appointments = new Proxy({ _name: "appointments" }, { get: (t, p) => p === "_name" ? "appointments" : {} });
+  return {
+    getDb: () => ({
+      select: () => ({
+        from: (table: unknown) => {
+          const name = (table as { _name?: string })._name;
+          if (name === "appointments") return makeSelectChainable(appointmentRows);
+          return makeSelectChainable(petRows);
+        },
+      }),
+      insert: () => makeInsertChainable(),
+      update: () => makeUpdateChainable(),
+      delete: () => makeDeleteChainable(),
+    }),
+    pets,
+    appointments,
+    and: vi.fn(),
+    eq: vi.fn(),
+    exists: vi.fn(),
+    or: vi.fn(),
+  };
+});
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeApp(staff: StaffRow = MANAGER) {
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("staff", staff);
+    await next();
+  });
+  return app.route("/pets", petsRouter);
+}
+
+function createApp() {
+  const app = makeApp(MANAGER);
+  return app;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("Extended pet profile fields — validation", () => {
+  beforeEach(resetMock);
+
+  it("rejects temperamentScore of 0 (below min)", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", temperamentScore: 0 }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+  });
+
+  it("rejects temperamentScore of 6 (above max)", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", temperamentScore: 6 }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+  });
+
+  it("rejects non-integer temperamentScore", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", temperamentScore: 3.5 }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects invalid medicalAlert severity", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        clientId: CLIENT_ID,
+        name: "Test",
+        species: "dog",
+        medicalAlerts: [{ type: "seizure", description: "xyz", severity: "critical" }],
+      }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("accepts valid temperamentScore 1–5", async () => {
+    const app = createApp();
+    for (const score of [1, 2, 3, 4, 5]) {
+      resetMock();
+      const res = await app.request("/pets", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", temperamentScore: score }),
+      });
+      expect(res.status).toBe(201);
+    }
+  });
+
+  it("accepts all valid medicalAlert severity values", async () => {
+    const app = createApp();
+    for (const severity of ["low", "medium", "high"] as const) {
+      resetMock();
+      const res = await app.request("/pets", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          clientId: CLIENT_ID,
+          name: "Test",
+          species: "dog",
+          medicalAlerts: [{ type: "allergy", description: "Sensitive to chicken", severity }],
+        }),
+      });
+      expect(res.status).toBe(201);
+    }
+  });
+});
+
+describe("Extended pet profile fields — create", () => {
+  beforeEach(resetMock);
+
+  it("accepts all extended fields on create", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        clientId: CLIENT_ID,
+        name: "Biscuit",
+        species: "dog",
+        breed: "Golden Retriever",
+        coatType: "double",
+        temperamentScore: 4,
+        temperamentFlags: ["anxious_with_dryers", "gentle"],
+        medicalAlerts: [
+          { type: "seizure", description: "Occasional episodes", severity: "medium" },
+        ],
+        preferredCuts: ["puppy cut", "teddy bear"],
+      }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.coatType).toBe("double");
+    expect(body.temperamentScore).toBe(4);
+    expect(body.temperamentFlags).toEqual(["anxious_with_dryers", "gentle"]);
+    expect(body.medicalAlerts).toEqual([{ type: "seizure", description: "Occasional episodes", severity: "medium" }]);
+    expect(body.preferredCuts).toEqual(["puppy cut", "teddy bear"]);
+  });
+
+  it("create without extended fields works (all optional)", async () => {
+    const app = createApp();
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Basil", species: "cat" }),
+    });
+    expect(res.status).toBe(201);
+  });
+});
+
+describe("Extended pet profile fields — update", () => {
+  beforeEach(resetMock);
+
+  it("updates coatType", async () => {
+    const app = createApp();
+    const res = await app.request(`/pets/${PET_ID}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ coatType: "double" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.coatType).toBe("double");
+  });
+
+  it("updates temperamentScore", async () => {
+    const app = createApp();
+    const res = await app.request(`/pets/${PET_ID}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ temperamentScore: 2 }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.temperamentScore).toBe(2);
+  });
+
+  it("rejects temperamentScore 0 on update", async () => {
+    const app = createApp();
+    const res = await app.request(`/pets/${PET_ID}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ temperamentScore: 0 }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects invalid severity on update", async () => {
+    const app = createApp();
+    const res = await app.request(`/pets/${PET_ID}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        medicalAlerts: [{ type: "x", description: "y", severity: "urgent" }],
+      }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects too many temperamentFlags (>20)", async () => {
+    const app = createApp();
+    const flags = Array.from({ length: 21 }, (_, i) => `flag_${i}`);
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", temperamentFlags: flags }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects too many preferredCuts (>20)", async () => {
+    const app = createApp();
+    const cuts = Array.from({ length: 21 }, (_, i) => `cut_${i}`);
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", preferredCuts: cuts }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects too many medicalAlerts (>50)", async () => {
+    const app = createApp();
+    const alerts = Array.from({ length: 51 }, (_, i) => ({
+      type: `type_${i}`,
+      description: `desc_${i}`,
+      severity: "low" as const,
+    }));
+    const res = await app.request("/pets", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ clientId: CLIENT_ID, name: "Test", species: "dog", medicalAlerts: alerts }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns extended fields in GET response", async () => {
+    petRows = [{ ...petRows[0], coatType: "wire", temperamentScore: 3, temperamentFlags: ["gentle"], medicalAlerts: [], preferredCuts: ["scissor cut"] }];
+    const app = createApp();
+    const res = await app.request(`/pets/${PET_ID}`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.coatType).toBe("wire");
+    expect(body.temperamentScore).toBe(3);
+    expect(body.temperamentFlags).toEqual(["gentle"]);
+    expect(body.preferredCuts).toEqual(["scissor cut"]);
+  });
+});

apps/api/src/__tests__/portal.test.ts

@@ -67,6 +67,11 @@ vi.mock("../db", () => {
     { get: (t, p) => (p === "_name" ? "impersonationSessions" : { table: "impersonationSessions", column: p }) }
   );
 
+  const impersonationAuditLogs = new Proxy(
+    { _name: "impersonationAuditLogs" },
+    { get: (t, p) => (p === "_name" ? "impersonationAuditLogs" : { table: "impersonationAuditLogs", column: p }) }
+  );
+
   const appointments = new Proxy(
     { _name: "appointments" },
     { get: (t, p) => (p === "_name" ? "appointments" : { table: "appointments", column: p }) }
@@ -99,8 +104,12 @@ vi.mock("../db", () => {
           }),
         }),
       }),
+      insert: () => ({
+        values: () => ({ returning: () => [{}] }),
+      }),
     }),
     impersonationSessions,
+    impersonationAuditLogs,
     appointments,
     eq: vi.fn(),
     and: vi.fn(),

apps/api/src/__tests__/rbac.test.ts

@@ -45,40 +45,76 @@ const GROOMER: StaffRow = {
 
 let staffLookupResult: StaffRow | null = null;
 let managerFallbackResult: StaffRow | null = MANAGER;
+let userLookupResult: { id: string; name: string | null; email: string | null } | null = null;
+let _insertedStaff: StaffRow | null = null;
 
 vi.mock("../db", () => {
-  const staff = new Proxy(
-    { _name: "staff" },
-    {
-      get(target, prop) {
-        if (prop === "_name") return "staff";
-        if (prop === "$inferSelect") return {};
-        return { table: "staff", column: prop };
-      },
-    }
-  );
+  const makeTableProxy = (name: string) =>
+    new Proxy(
+      { _name: name },
+      {
+        get(target, prop) {
+          if (prop === "_name") return name;
+          if (prop === "$inferSelect") return {};
+          return { table: name, column: prop };
+        },
+      }
+    );
+
+  const staff = makeTableProxy("staff");
+  const user = makeTableProxy("user");
+
+  const buildQuery = (result: unknown, fallback: unknown) => ({
+    [Symbol.iterator]: function* () {
+      if (result) yield result;
+    },
+    limit: (_n: number) => {
+      const item = result ?? fallback;
+      return {
+        [Symbol.iterator]: function* () { if (item) yield item; },
+        0: item,
+        length: item ? 1 : 0,
+      };
+    },
+  });
 
   return {
     getDb: () => ({
       select: () => ({
-        from: () => ({
-          where: () => ({
-            limit: () => {
-              // dev mode fallback to first manager
-              return managerFallbackResult ? [managerFallbackResult] : [];
-            },
-            [Symbol.iterator]: function* () {
-              if (staffLookupResult) yield staffLookupResult;
-            },
-            0: staffLookupResult,
-            length: staffLookupResult ? 1 : 0,
-          }),
+        from: (table: unknown) => ({
+          where: () => buildQuery(
+            table === staff ? staffLookupResult : userLookupResult,
+            table === staff ? managerFallbackResult : null
+          ),
+        }),
+      }),
+      insert: (_table: unknown) => ({
+        values: (vals: Record<string, unknown>) => ({
+          returning: () => {
+            const newStaff: StaffRow = {
+              id: "new-staff-id",
+              oidcSub: null,
+              userId: vals.userId as string,
+              role: vals.role as StaffRow["role"],
+              isSuperUser: false,
+              name: vals.name as string,
+              email: vals.email as string,
+              active: true,
+              icalToken: null,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            };
+            _insertedStaff = newStaff;
+            return [newStaff];
+          },
         }),
       }),
     }),
     staff,
+    user,
     eq: vi.fn((_col: unknown, _val: unknown) => ({ col: _col, val: _val })),
     and: vi.fn((..._clauses: unknown[]) => ({})),
+    sql: vi.fn((..._args: unknown[]) => ({})),
   };
 });
 
@@ -87,6 +123,8 @@ vi.mock("../db", () => {
 function resetMocks() {
   staffLookupResult = null;
   managerFallbackResult = MANAGER;
+  userLookupResult = null;
+  _insertedStaff = null;
 }
 
 /** Build a minimal Hono app with jwtPayload pre-set, then apply a middleware. */
@@ -96,7 +134,10 @@ function buildApp(
 ) {
   const app = new Hono<AppEnv>();
   app.use("*", async (c, next) => {
-    c.set("jwtPayload", { sub: staffLookupResult?.userId ?? "unknown-sub" });
+    c.set("jwtPayload", {
+      sub: userLookupResult?.id ?? staffLookupResult?.userId ?? "unknown-sub",
+      email: userLookupResult?.email,
+    });
     await next();
   });
   app.use("*", middleware);
@@ -202,6 +243,50 @@ describe("resolveStaffMiddleware", () => {
     const body = await res.json();
     expect(body.error).toMatch(/no staff records found/i);
   });
+
+  it("auto-provision: creates groomer staff record on first login when Better-Auth user exists", async () => {
+    staffLookupResult = null;
+    userLookupResult = { id: "ba-user-new", name: "New User", email: "newuser@example.com" };
+    let capturedStaff: StaffRow | null = null;
+    const app = buildApp(resolveStaffMiddleware, (c) => {
+      capturedStaff = c.get("staff");
+      return c.json({ ok: true });
+    });
+
+    const res = await app.request("/test");
+    expect(res.status).toBe(200);
+    expect(capturedStaff).not.toBeNull();
+    expect(capturedStaff!.role).toBe("groomer");
+    expect(capturedStaff!.userId).toBe("ba-user-new");
+    expect(capturedStaff!.name).toBe("New User");
+    expect(capturedStaff!.email).toBe("newuser@example.com");
+    expect(capturedStaff!.isSuperUser).toBe(false);
+  });
+
+  it("auto-provision: falls back to email prefix when user has no name", async () => {
+    staffLookupResult = null;
+    userLookupResult = { id: "ba-user-noname", name: null, email: "firstlogin@example.com" };
+    let capturedStaff: StaffRow | null = null;
+    const app = buildApp(resolveStaffMiddleware, (c) => {
+      capturedStaff = c.get("staff");
+      return c.json({ ok: true });
+    });
+
+    const res = await app.request("/test");
+    expect(res.status).toBe(200);
+    expect(capturedStaff!.name).toBe("firstlogin");
+  });
+
+  it("auto-provision: returns 403 when no staff record and no Better-Auth user exists", async () => {
+    staffLookupResult = null;
+    userLookupResult = null;
+    const app = buildApp(resolveStaffMiddleware);
+
+    const res = await app.request("/test");
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toMatch(/no staff record found for authenticated user/i);
+  });
 });
 
 // ─── requireRole tests ────────────────────────────────────────────────────────

apps/api/src/__tests__/seed-uat-credentials.test.ts

@@ -0,0 +1,508 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ─── Test configuration constants (must match seed.ts) ─────────────────────────
+
+const UAT_ACCOUNTS = [
+  {
+    email: "uat-super@groombook.dev",
+    name: "UAT Super User",
+    passwordEnv: "SEED_UAT_SUPER_PASSWORD",
+    staffEmail: "uat-super@groombook.dev",
+  },
+  {
+    email: "uat-groomer@groombook.dev",
+    name: "UAT Staff Groomer",
+    passwordEnv: "SEED_UAT_GROOMER_PASSWORD",
+    staffEmail: "uat-groomer@groombook.dev",
+  },
+  {
+    email: "uat-customer@groombook.dev",
+    name: "UAT Customer",
+    passwordEnv: "SEED_UAT_CUSTOMER_PASSWORD",
+    staffEmail: null,
+  },
+  {
+    email: "uat-tester@groombook.dev",
+    name: "UAT Tester",
+    passwordEnv: "SEED_UAT_TESTER_PASSWORD",
+    staffEmail: "uat-tester@groombook.dev",
+  },
+];
+
+const TEST_PASSWORD = "test-password-123";
+
+// ─── Password hashing — must match better-auth/crypto (N=16384, r=16, p=1, dkLen=64, hex) ───
+
+async function hashPassword(password: string): Promise<string> {
+  const { hashPassword } = await import("better-auth/crypto");
+  return hashPassword(password);
+}
+
+// ─── Mock DB state ─────────────────────────────────────────────────────────────
+
+interface UserRow {
+  id: string;
+  email: string;
+  name: string;
+  emailVerified: boolean;
+}
+
+interface AccountRow {
+  id: string;
+  accountId: string;
+  providerId: string;
+  userId: string;
+  password: string | null;
+}
+
+interface StaffRow {
+  id: string;
+  email: string;
+  userId: string | null;
+  name: string;
+}
+
+let dbUsers: UserRow[] = [];
+let dbAccounts: AccountRow[] = [];
+let dbStaff: StaffRow[] = [];
+let insertedUsers: UserRow[] = [];
+let insertedAccounts: AccountRow[] = [];
+let updatedAccounts: Array<{ id: string; password: string }> = [];
+let updatedStaff: Array<{ id: string; userId: string }> = [];
+
+const originalEnv = { ...process.env };
+
+function resetMock() {
+  dbUsers = [];
+  dbAccounts = [];
+  dbStaff = [];
+  insertedUsers = [];
+  insertedAccounts = [];
+  updatedAccounts = [];
+  updatedStaff = [];
+  process.env = { ...originalEnv };
+}
+
+// ─── Mock schema ───────────────────────────────────────────────────────────────
+
+function makeSchemaMock() {
+  const user = new Proxy({ _name: "user" }, {
+    get(_t, p) {
+      if (p === "_name") return "user";
+      if (p === "$inferSelect") return {};
+      return { table: "user", column: p };
+    },
+  });
+
+  const account = new Proxy({ _name: "account" }, {
+    get(_t, p) {
+      if (p === "_name") return "account";
+      if (p === "$inferSelect") return {};
+      return { table: "account", column: p };
+    },
+  });
+
+  const staff = new Proxy({ _name: "staff" }, {
+    get(_t, p) {
+      if (p === "_name") return "staff";
+      if (p === "$inferSelect") return {};
+      return { table: "staff", column: p };
+    },
+  });
+
+  return { user, account, staff };
+}
+
+const { user: mockUser, account: mockAccount, staff: mockStaff } = makeSchemaMock();
+
+function eq(col: unknown, val: unknown) {
+  return { __type: "eq" as const, col, val };
+}
+
+function and(...conds: unknown[]) {
+  return { __type: "and" as const, conds };
+}
+
+// ─── Seed logic helper ─────────────────────────────────────────────────────────
+// Inline the credential provisioning logic under test so we can call it directly.
+// This is the same logic as seed.ts lines 514-598.
+
+interface SeedAccount {
+  email: string;
+  name: string;
+  passwordEnv: string;
+  staffEmail: string | null;
+}
+
+let uuidCounter = 0;
+function mockUuid(): string {
+  return `mock-uuid-${++uuidCounter}`;
+}
+
+async function seedUatCredentials(
+  accounts: SeedAccount[],
+  opts: {
+    users?: UserRow[];
+    accounts?: AccountRow[];
+    staff?: StaffRow[];
+  }
+) {
+  const { users = dbUsers, accounts: accts = dbAccounts, staff: staffRows = dbStaff } = opts;
+
+  for (const acct of accounts) {
+    const password = process.env[acct.passwordEnv];
+    if (!password) {
+      console.warn(`⚠ Skipping ${acct.email} — ${acct.passwordEnv} not set`);
+      continue;
+    }
+
+    // 1. Find or create the Better-Auth user
+    const existingUser = users.find((u) => u.email === acct.email);
+
+    let userId: string;
+    if (existingUser) {
+      userId = existingUser.id;
+    } else {
+      userId = mockUuid();
+      const newUser: UserRow = { id: userId, name: acct.name, email: acct.email, emailVerified: true };
+      insertedUsers.push(newUser);
+      dbUsers.push(newUser);
+    }
+
+    // 2. Check if credential account already exists
+    const existingAccount = accts.find(
+      (a) => a.userId === userId && a.providerId === "credential"
+    );
+
+    if (existingAccount) {
+      // Idempotent update: re-hash the current env password and update the stored hash.
+      const { hashPassword } = await import("better-auth/crypto");
+      const passwordHash = await hashPassword(password);
+      existingAccount.password = passwordHash;
+      updatedAccounts.push({ id: existingAccount.id, password: passwordHash });
+    } else {
+      // Use Better-Auth's hashPassword so test helper matches production seed.ts
+      const { hashPassword } = await import("better-auth/crypto");
+      const passwordHash = await hashPassword(password);
+
+      const newAccount: AccountRow = {
+        id: mockUuid(),
+        accountId: userId,
+        providerId: "credential",
+        userId,
+        password: passwordHash,
+      };
+      insertedAccounts.push(newAccount);
+      dbAccounts.push(newAccount);
+    }
+
+    // 3. Link staff record to Better-Auth user
+    if (acct.staffEmail) {
+      const existingStaff = staffRows.find((s) => s.email === acct.staffEmail);
+      if (existingStaff && !existingStaff.userId) {
+        existingStaff.userId = userId;
+        updatedStaff.push({ id: existingStaff.id, userId });
+      }
+    }
+  }
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("seedUatCredentials — credential provisioning logic", () => {
+  beforeEach(() => {
+    resetMock();
+    uuidCounter = 0;
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  // ── AC-1: creates user + account when neither exists ──────────────────────
+
+  it("AC-1: creates user and account for each UAT account with password env var set", async () => {
+    process.env.SEED_UAT_SUPER_PASSWORD = TEST_PASSWORD;
+    process.env.SEED_UAT_GROOMER_PASSWORD = TEST_PASSWORD;
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = TEST_PASSWORD;
+    process.env.SEED_UAT_TESTER_PASSWORD = TEST_PASSWORD;
+
+    await seedUatCredentials(UAT_ACCOUNTS, { users: [], accounts: [], staff: [] });
+
+    // 4 users created (customer + tester have no staff, super + groomer do)
+    expect(insertedUsers).toHaveLength(4);
+    expect(insertedUsers.find((u) => u.email === "uat-super@groombook.dev")).toBeDefined();
+    expect(insertedUsers.find((u) => u.email === "uat-groomer@groombook.dev")).toBeDefined();
+    expect(insertedUsers.find((u) => u.email === "uat-customer@groombook.dev")).toBeDefined();
+    expect(insertedUsers.find((u) => u.email === "uat-tester@groombook.dev")).toBeDefined();
+
+    // 4 accounts created
+    expect(insertedAccounts).toHaveLength(4);
+    for (const acct of insertedAccounts) {
+      expect(acct.providerId).toBe("credential");
+      // Better-Auth uses hex encoding: saltHex:keyHex (both lowercase hex)
+      expect(acct.password).toMatch(/^[a-f0-9]+:[a-f0-9]+$/);
+      // Verify the hash is scrypt with correct params (N=16384, r=16, p=1, dkLen=64)
+      const parts = acct.password!.split(":");
+      const saltHex = parts[0]!;
+      const keyHex = parts[1]!;
+      const salt = Buffer.from(saltHex, "hex");
+      const storedHash = Buffer.from(keyHex, "hex");
+      expect(salt).toHaveLength(16);
+      expect(storedHash).toHaveLength(64);
+    }
+  });
+
+  // ── AC-2: emailVerified = true ─────────────────────────────────────────────
+
+  it("AC-2: created users have emailVerified = true", async () => {
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = TEST_PASSWORD;
+
+    await seedUatCredentials(
+      [UAT_ACCOUNTS[2]!], // customer only
+      { users: [], accounts: [], staff: [] }
+    );
+
+    expect(insertedUsers[0]!.emailVerified).toBe(true);
+  });
+
+  // ── AC-3: providerId = credential, password is hashed ──────────────────────
+
+  it("AC-3: account records use providerId='credential' with properly formatted hashed password", async () => {
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = TEST_PASSWORD;
+
+    await seedUatCredentials(
+      [UAT_ACCOUNTS[2]!],
+      { users: [], accounts: [], staff: [] }
+    );
+
+    const acct = insertedAccounts[0]!;
+    expect(acct.providerId).toBe("credential");
+    // Better-Auth uses hex: saltHex (32 chars) : keyHex (128 chars)
+    expect(acct.password).toMatch(/^[a-f0-9]+:[a-f0-9]+$/);
+    const parts = acct.password!.split(":");
+    const saltHex = parts[0]!;
+    const keyHex = parts[1]!;
+    expect(() => Buffer.from(saltHex, "hex")).not.toThrow();
+    expect(() => Buffer.from(keyHex, "hex")).not.toThrow();
+    const salt = Buffer.from(saltHex, "hex");
+    const storedHash = Buffer.from(keyHex, "hex");
+    expect(salt).toHaveLength(16);
+    expect(storedHash).toHaveLength(64);
+  });
+
+  // ── AC-4: staff.userId is linked ────────────────────────────────────────────
+
+  it("AC-4: links staff.userId to the Better-Auth user when staff record exists", async () => {
+    process.env.SEED_UAT_SUPER_PASSWORD = TEST_PASSWORD;
+    const staffRows: StaffRow[] = [
+      { id: "staff-super-1", email: "uat-super@groombook.dev", userId: null, name: "UAT Super User" },
+    ];
+
+    await seedUatCredentials([UAT_ACCOUNTS[0]!], { users: [], accounts: [], staff: staffRows });
+
+    expect(updatedStaff).toHaveLength(1);
+    expect(updatedStaff[0]!.id).toBe("staff-super-1");
+    expect(updatedStaff[0]!.userId).toBe("mock-uuid-1");
+    expect(staffRows[0]!.userId).toBe("mock-uuid-1");
+  });
+
+  it("AC-4b: does not update staff.userId if already set", async () => {
+    process.env.SEED_UAT_GROOMER_PASSWORD = TEST_PASSWORD;
+    const staffRows: StaffRow[] = [
+      { id: "staff-groomer-1", email: "uat-groomer@groombook.dev", userId: "already-linked", name: "UAT Groomer" },
+    ];
+
+    await seedUatCredentials([UAT_ACCOUNTS[1]!], { users: [], accounts: [], staff: staffRows });
+
+    expect(updatedStaff).toHaveLength(0);
+  });
+
+  // ── AC-5: idempotent — does not insert duplicate records ───────────────────
+
+  it("AC-5: re-running does not insert duplicate user or account records", async () => {
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = TEST_PASSWORD;
+
+    const preExistingUsers: UserRow[] = [
+      { id: "pre-existing-user", email: "uat-customer@groombook.dev", name: "UAT Customer", emailVerified: true },
+    ];
+    const preExistingAccounts: AccountRow[] = [
+      {
+        id: "pre-existing-acct",
+        accountId: "pre-existing-user",
+        providerId: "credential",
+        userId: "pre-existing-user",
+        password: await hashPassword(TEST_PASSWORD),
+      },
+    ];
+
+    await seedUatCredentials([UAT_ACCOUNTS[2]!], {
+      users: preExistingUsers,
+      accounts: preExistingAccounts,
+      staff: [],
+    });
+
+    // No inserts — user and account already exist
+    expect(insertedUsers).toHaveLength(0);
+    expect(insertedAccounts).toHaveLength(0);
+  });
+
+  // ── AC-5b: password rotation on re-seed ─────────────────────────────────────
+
+  it("AC-5b: re-running with a new password updates the stored credential hash", async () => {
+    const OLD_PASSWORD = "old-password-abc";
+    const NEW_PASSWORD = "new-password-xyz";
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = NEW_PASSWORD;
+
+    const preExistingUsers: UserRow[] = [
+      { id: "pre-existing-user", email: "uat-customer@groombook.dev", name: "UAT Customer", emailVerified: true },
+    ];
+    const preExistingAccounts: AccountRow[] = [
+      {
+        id: "pre-existing-acct",
+        accountId: "pre-existing-user",
+        providerId: "credential",
+        userId: "pre-existing-user",
+        password: await hashPassword(OLD_PASSWORD),
+      },
+    ];
+
+    await seedUatCredentials([UAT_ACCOUNTS[2]!], {
+      users: preExistingUsers,
+      accounts: preExistingAccounts,
+      staff: [],
+    });
+
+    // No new records inserted
+    expect(insertedUsers).toHaveLength(0);
+    expect(insertedAccounts).toHaveLength(0);
+    // Password WAS updated to the new env value
+    expect(updatedAccounts).toHaveLength(1);
+    expect(updatedAccounts[0]!.id).toBe("pre-existing-acct");
+    // New hash is valid Better-Auth format (salt:key, each hex)
+    const newHashParts = updatedAccounts[0]!.password.split(":");
+    expect(Buffer.from(newHashParts[0]!, "hex")).toHaveLength(16);
+    expect(Buffer.from(newHashParts[1]!, "hex")).toHaveLength(64);
+  });
+
+  // ── AC-8: existing account password IS updated (not frozen at first-seed) ──
+
+  it("AC-8: re-seeding with a changed password env var updates the stored hash", async () => {
+    const ORIGINAL_PASSWORD = "original-password";
+    const ROTATED_PASSWORD = "rotated-password-456";
+
+    process.env.SEED_UAT_CUSTOMER_PASSWORD = ROTATED_PASSWORD;
+
+    const preExistingUsers: UserRow[] = [
+      { id: "pre-existing-user", email: "uat-customer@groombook.dev", name: "UAT Customer", emailVerified: true },
+    ];
+    // Account was created with the original password on first seed
+    const originalHash = await hashPassword(ORIGINAL_PASSWORD);
+    const preExistingAccounts: AccountRow[] = [
+      {
+        id: "pre-existing-acct",
+        accountId: "pre-existing-user",
+        providerId: "credential",
+        userId: "pre-existing-user",
+        password: originalHash,
+      },
+    ];
+
+    // Re-seed with the rotated password env var
+    await seedUatCredentials([UAT_ACCOUNTS[2]!], {
+      users: preExistingUsers,
+      accounts: preExistingAccounts,
+      staff: [],
+    });
+
+    // No new user or account created
+    expect(insertedUsers).toHaveLength(0);
+    expect(insertedAccounts).toHaveLength(0);
+
+    // The pre-existing account's password WAS updated (not frozen at first-seed).
+    // hashPassword uses a random salt so we verify by format + that it is a new,
+    // different valid hash from the original.
+    const updatedAcct = preExistingAccounts[0]!;
+    expect(updatedAcct.password).toBeDefined();
+    expect(updatedAcct.password).toMatch(/^[a-f0-9]{32}:[a-f0-9]{128}$/);
+    expect(updatedAcct.password).not.toBe(originalHash); // it actually changed
+  });
+
+  // ── AC-6: missing env var skips with warning ────────────────────────────────
+
+  it("AC-6: missing SEED_UAT_*_PASSWORD env var skips that account (no error)", async () => {
+    // No env vars set at all
+    delete process.env.SEED_UAT_SUPER_PASSWORD;
+    delete process.env.SEED_UAT_GROOMER_PASSWORD;
+    delete process.env.SEED_UAT_CUSTOMER_PASSWORD;
+    delete process.env.SEED_UAT_TESTER_PASSWORD;
+
+    const warnSpy = vi.spyOn(console, "warn").mockReturnValue(undefined);
+
+    await seedUatCredentials(UAT_ACCOUNTS, { users: [], accounts: [], staff: [] });
+
+    // Nothing created
+    expect(insertedUsers).toHaveLength(0);
+    expect(insertedAccounts).toHaveLength(0);
+    // Warning logged for each of the 4 accounts
+    expect(warnSpy).toHaveBeenCalledTimes(4);
+    expect(warnSpy).toHaveBeenCalledWith(
+      "⚠ Skipping uat-super@groombook.dev — SEED_UAT_SUPER_PASSWORD not set"
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  // ── AC-7: partial env var coverage ─────────────────────────────────────────
+
+  it("AC-7: only accounts with password env var set are provisioned", async () => {
+    process.env.SEED_UAT_SUPER_PASSWORD = TEST_PASSWORD;
+    // Only super has password set
+
+    const warnSpy = vi.spyOn(console, "warn").mockReturnValue(undefined);
+
+    await seedUatCredentials(UAT_ACCOUNTS, { users: [], accounts: [], staff: [] });
+
+    expect(insertedUsers).toHaveLength(1);
+    expect(insertedUsers[0]!.email).toBe("uat-super@groombook.dev");
+    expect(insertedAccounts).toHaveLength(1);
+    expect(insertedAccounts[0]!.accountId).toBe("mock-uuid-1");
+
+    // 3 warnings for missing accounts
+    expect(warnSpy).toHaveBeenCalledTimes(3);
+
+    warnSpy.mockRestore();
+  });
+});
+
+// ─── Password hash format verification ───────────────────────────────────────
+
+describe("password hash format — scrypt parameters", () => {
+  it("hashes use salt:hash format with 16-byte salt and 64-byte output", async () => {
+    const hash = await hashPassword("test-password");
+    const parts = hash.split(":");
+    const saltHex = parts[0]!;
+    const keyHex = parts[1]!;
+
+    expect(hash).toMatch(/^[a-f0-9]+:[a-f0-9]+$/);
+    expect(Buffer.from(saltHex, "hex")).toHaveLength(16);
+    expect(Buffer.from(keyHex, "hex")).toHaveLength(64);
+  });
+
+  it("same password produces different hashes (due to random salt)", async () => {
+    const hash1 = await hashPassword("same-password");
+    const hash2 = await hashPassword("same-password");
+
+    expect(hash1).not.toBe(hash2);
+    // Both are valid Better-Auth hex format
+    expect(hash1).toMatch(/^[a-f0-9]+:[a-f0-9]+$/);
+    expect(hash2).toMatch(/^[a-f0-9]+:[a-f0-9]+$/);
+  });
+
+  it("different passwords produce different hashes", async () => {
+    const hash1 = await hashPassword("password1");
+    const hash2 = await hashPassword("password2");
+
+    expect(hash1).not.toBe(hash2);
+  });
+});

apps/api/src/db/factories.ts

@@ -103,6 +103,11 @@ export function buildPet(overrides: Partial<PetRow> & { clientId: string }): Pet
     photoKey: null,
     photoUploadedAt: null,
     image: null,
+    coatType: null,
+    temperamentScore: null,
+    temperamentFlags: [],
+    medicalAlerts: [],
+    preferredCuts: [],
     createdAt: new Date("2025-01-01T00:00:00Z"),
     updatedAt: new Date("2025-01-01T00:00:00Z"),
   };

apps/api/src/db/schema.ts

@@ -12,6 +12,16 @@ import {
   uuid,
 } from "drizzle-orm/pg-core";
 
+// ─── Shared types ───────────────────────────────────────────────────────────────
+
+export type MedicalAlertSeverity = "low" | "medium" | "high";
+
+export interface MedicalAlert {
+  type: string;
+  description: string;
+  severity: MedicalAlertSeverity;
+}
+
 // ─── Enums ────────────────────────────────────────────────────────────────────
 
 export const appointmentStatusEnum = pgEnum("appointment_status", [
@@ -146,6 +156,12 @@ export const pets = pgTable(
     photoKey: text("photo_key"),
     photoUploadedAt: timestamp("photo_uploaded_at"),
     image: text("image"),
+    // Extended profile fields
+    coatType: text("coat_type"),
+    temperamentScore: integer("temperament_score"),
+    temperamentFlags: jsonb("temperament_flags").$type<string[]>().default([]),
+    medicalAlerts: jsonb("medical_alerts").$type<MedicalAlert[]>().default([]),
+    preferredCuts: jsonb("preferred_cuts").$type<string[]>().default([]),
     createdAt: timestamp("created_at").notNull().defaultNow(),
     updatedAt: timestamp("updated_at").notNull().defaultNow(),
   },

apps/api/src/index.ts

@@ -22,10 +22,11 @@ import { searchRouter } from "./routes/search.js";
 import { getObject } from "./lib/s3.js";
 import { calendarRouter } from "./routes/calendar.js";
 import { setupRouter } from "./routes/setup.js";
-import { getDb, businessSettings, eq, staff } from "./db";
+import { getDb, businessSettings, eq, staff } from "./db/index.js";
 import { authMiddleware } from "./middleware/auth.js";
 import { resolveStaffMiddleware, requireRole, requireRoleOrSuperUser, requireSuperUser } from "./middleware/rbac.js";
 import { devRouter } from "./routes/dev.js";
+import { bufferRulesRouter } from "./routes/buffer-rules.js";
 import { adminSeedRouter } from "./routes/admin/seed.js";
 import { startReminderScheduler } from "./services/reminders.js";
 import { webhooksRouter } from "./routes/stripe-webhooks.js";
@@ -211,6 +212,7 @@ api.on(["GET"], "/staff/*", requireRole("manager", "receptionist", "groomer"));
 // Staff write routes: manager OR super-user (combined guard — avoids AND stacking)
 api.on(["POST", "PATCH", "DELETE"], "/staff/*", requireRoleOrSuperUser("manager"));
 api.use("/admin/*", requireRoleOrSuperUser("manager"));
+api.use("/buffer-rules/*", requireRole("manager"));
 api.use("/admin/settings/*", requireSuperUser());
 api.use("/reports/*", requireRole("manager"));
 api.use("/invoices/*", requireRole("manager", "groomer"));
@@ -268,6 +270,7 @@ api.route("/impersonation", impersonationRouter);
 api.route("/admin/settings", settingsRouter);
 api.route("/admin/auth-provider", authProviderRouter);
 api.route("/admin/seed", adminSeedRouter);
+api.route("/buffer-rules", bufferRulesRouter);
 api.route("/search", searchRouter);
 
 const port = Number(process.env.PORT ?? 3000);

apps/api/src/lib/auth.ts

@@ -1,8 +1,8 @@
 import { betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { genericOAuth } from "better-auth/plugins";
-import { getDb, authProviderConfig, eq } from "./db";
-import { decryptSecret } from "./db";
+import { getDb, authProviderConfig, eq } from "../db/index.js";
+import { decryptSecret } from "../db/index.js";
 import { sendEmail } from "../services/email.js";
 
 const BETTER_AUTH_SECRET = process.env.BETTER_AUTH_SECRET;
@@ -97,6 +97,9 @@ export async function initAuth(): Promise<void> {
           window: 10,
           storage: "memory",
           customRules: {
+            "/sign-in/social": { max: 10, window: 60 },
+            "/sign-in/email": { max: 10, window: 60 },
+            "/sign-up/email": { max: 5, window: 60 },
             "/get-session": false,
           },
         },
@@ -247,6 +250,9 @@ export async function initAuth(): Promise<void> {
         window: 10,
         storage: "memory",
         customRules: {
+          "/sign-in/social": { max: 10, window: 60 },
+          "/sign-in/email": { max: 10, window: 60 },
+          "/sign-up/email": { max: 5, window: 60 },
           "/get-session": false,
         },
       },

apps/api/src/middleware/portalAudit.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { getDb, impersonationAuditLogs } from "../db";
+import { getDb, impersonationAuditLogs } from "../db/index.js";
 import type { PortalEnv } from "./portalSession.js";
 
 /**

apps/api/src/middleware/portalSession.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { and, eq, getDb, impersonationSessions } from "../db";
+import { and, eq, getDb, impersonationSessions } from "../db/index.js";
 
 export interface PortalEnv {
   Variables: {

apps/api/src/middleware/rbac.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { and, eq, getDb, sql, staff } from "../db";
+import { and, eq, getDb, sql, staff, user } from "../db/index.js";
 
 export type StaffRole = "groomer" | "receptionist" | "manager";
 export type StaffRow = typeof staff.$inferSelect;
@@ -110,6 +110,33 @@ export const resolveStaffMiddleware: MiddlewareHandler<AppEnv> = async (
       return;
     }
   }
+  // Auto-provision: no staff record exists for this user at all, but a valid
+  // Better-Auth user session exists (jwt.sub = user.id from user table).
+  // Create a minimal groomer staff record on first login.
+  const [userRow] = await db
+    .select({ id: user.id, name: user.name, email: user.email })
+    .from(user)
+    .where(eq(user.id, jwt.sub))
+    .limit(1);
+  if (userRow) {
+    const [newStaff] = await db
+      .insert(staff)
+      .values({
+        name: userRow.name ?? jwt.email?.split("@")[0] ?? "Unknown",
+        email: userRow.email ?? jwt.email ?? "",
+        userId: jwt.sub,
+        role: "groomer",
+        isSuperUser: false,
+        active: true,
+      })
+      .returning();
+    if (!newStaff) {
+      return c.json({ error: "Internal error: staff record creation failed" }, 500);
+    }
+    c.set("staff", newStaff);
+    await next();
+    return;
+  }
   return c.json(
     { error: "Forbidden: no staff record found for authenticated user" },
     403

apps/api/src/routes/admin/seed.ts

@@ -10,7 +10,7 @@
  */
 
 import { Hono } from "hono";
-import { eq, getDb, staff, clients, pets, services } from "./db";
+import { eq, getDb, staff, clients, pets, services } from "../../db/index.js";
 
 export const adminSeedRouter = new Hono();
 
@@ -36,6 +36,19 @@ const DEMO_PET = {
   weightKg: "30.00",
 };
 
+const UAT_CLIENT = {
+  name: "UAT Customer",
+  email: "uat-customer@groombook.dev",
+  phone: "555-0100",
+  address: "1 UAT Lane, Test City, CA 90210",
+  status: "active" as const,
+};
+
+const UAT_PETS = [
+  { name: "Bella", species: "Dog", breed: "Poodle", coatType: "curly" as const, weightKg: "20.00" },
+  { name: "Max", species: "Dog", breed: "Labrador Retriever", coatType: "smooth" as const, weightKg: "30.00" },
+];
+
 const DEMO_SERVICES = [
   { id: "b0000001-0000-0000-0000-000000000001", name: "Bath & Brush", description: "Full bath, blow-dry, brush out, and ear cleaning", basePriceCents: 4500, durationMinutes: 45 },
   { id: "b0000001-0000-0000-0000-000000000002", name: "Full Groom — Small", description: "Complete grooming for dogs under 25 lbs", basePriceCents: 6500, durationMinutes: 60 },
@@ -43,7 +56,7 @@ const DEMO_SERVICES = [
   { id: "b0000001-0000-0000-0000-000000000004", name: "Nail Trim", description: "Nail clipping and filing", basePriceCents: 1500, durationMinutes: 15 },
 ];
 
-adminSeedRouter.post("/seed", async (c) => {
+adminSeedRouter.post("/", async (c) => {
   // Refuse to run when AUTH_DISABLED — dev environments use direct-DB seeding
   if (process.env.AUTH_DISABLED === "true") {
     return c.json(
@@ -128,6 +141,51 @@ adminSeedRouter.post("/seed", async (c) => {
     results.push(`Created pet '${DEMO_PET.name}' for Demo Client (id: ${created!.id})`);
   }
 
+  // ── Client: UAT Customer ──────────────────────────────────────────────────
+  const [existingUatClient] = await db
+    .select()
+    .from(clients)
+    .where(eq(clients.email, UAT_CLIENT.email));
+
+  let uatClientId: string;
+  if (existingUatClient) {
+    uatClientId = existingUatClient.id;
+    results.push(`Client '${UAT_CLIENT.name}' already exists (id: ${uatClientId})`);
+  } else {
+    const [created] = await db.insert(clients).values(UAT_CLIENT).returning();
+    uatClientId = created!.id;
+    results.push(`Created client '${UAT_CLIENT.name}' (id: ${uatClientId})`);
+  }
+
+  // ── Pets: UAT Customer's Pets ─────────────────────────────────────────────
+  const existingUatPets = await db
+    .select()
+    .from(pets)
+    .where(eq(pets.clientId, uatClientId));
+
+  for (const uatPet of UAT_PETS) {
+    const existingPet = existingUatPets.find(
+      (p) => p.name === uatPet.name && p.species === uatPet.species
+    );
+    if (existingPet) {
+      results.push(`Pet '${uatPet.name}' already exists for UAT Customer (id: ${existingPet.id})`);
+    } else {
+      const [created] = await db
+        .insert(pets)
+        .values({
+          clientId: uatClientId,
+          name: uatPet.name,
+          species: uatPet.species,
+          breed: uatPet.breed,
+          coatType: uatPet.coatType,
+          weightKg: uatPet.weightKg,
+          dateOfBirth: new Date("2019-01-01T00:00:00Z"),
+        })
+        .returning();
+      results.push(`Created pet '${uatPet.name}' for UAT Customer (id: ${created!.id})`);
+    }
+  }
+
   return c.json({
     message: "Seed complete",
     details: results,
@@ -136,4 +194,4 @@ adminSeedRouter.post("/seed", async (c) => {
       staffOidcSub: KNOWN_STAFF.oidcSub,
     },
   });
-});
+});

apps/api/src/routes/appointmentGroups.ts

@@ -15,7 +15,7 @@ import {
   pets,
   services,
   staff,
-} from "../db";
+} from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const appointmentGroupsRouter = new Hono<AppEnv>();

apps/api/src/routes/appointments.ts

@@ -18,7 +18,7 @@ import {
   reminderLogs,
   services,
   staff,
-} from "../db";
+} from "../db/index.js";
 import { buildConfirmationEmail, sendEmail } from "../services/email.js";
 import { notifyWaitlistForAppointment } from "../services/waitlistNotify.js";
 import type { AppEnv } from "../middleware/rbac.js";

apps/api/src/routes/authProvider.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { eq, getDb, authProviderConfig, encryptSecret } from "../db";
+import { eq, getDb, authProviderConfig, encryptSecret } from "../db/index.js";
 import { requireSuperUser } from "../middleware/rbac.js";
 import { reinitAuth } from "../lib/auth.js";
 

apps/api/src/routes/book.ts

@@ -14,7 +14,7 @@ import {
   appointments,
   clients,
   pets,
-} from "../db";
+} from "../db/index.js";
 import {
   generateAvailableSlots,
   BUSINESS_START_HOUR,

apps/api/src/routes/buffer-rules.ts

@@ -0,0 +1,124 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod/v3";
+import { and, eq, getDb, isNull } from "../db/index.js";
+import type { AppEnv } from "../middleware/rbac.js";
+import { bufferRules, services } from "../db/index.js";
+
+export const bufferRulesRouter = new Hono<AppEnv>();
+
+const createBufferRuleSchema = z.object({
+  serviceId: z.string().uuid(),
+  sizeCategory: z
+    .enum(["small", "medium", "large", "extra_large"])
+    .optional(),
+  coatType: z
+    .enum(["short", "medium", "long", "double", "wire", "silky", "curly", "hairless"])
+    .optional(),
+  bufferMinutes: z.number().int().positive(),
+});
+
+const updateBufferRuleSchema = z.object({
+  bufferMinutes: z.number().int().positive(),
+});
+
+// GET / — list all buffer rules, optionally filtered by serviceId
+bufferRulesRouter.get("/", async (c) => {
+  const db = getDb();
+  const serviceId = c.req.query("serviceId");
+
+  const conditions = [];
+  if (serviceId) conditions.push(eq(bufferRules.serviceId, serviceId));
+
+  const rows = await db
+    .select({
+      id: bufferRules.id,
+      serviceId: bufferRules.serviceId,
+      sizeCategory: bufferRules.sizeCategory,
+      coatType: bufferRules.coatType,
+      bufferMinutes: bufferRules.bufferMinutes,
+      createdAt: bufferRules.createdAt,
+      updatedAt: bufferRules.updatedAt,
+      serviceName: services.name,
+    })
+    .from(bufferRules)
+    .innerJoin(services, eq(bufferRules.serviceId, services.id))
+    .where(conditions.length > 0 ? and(...conditions) : undefined)
+    .orderBy(bufferRules.createdAt);
+
+  return c.json(rows);
+});
+
+// POST / — create a buffer rule
+bufferRulesRouter.post(
+  "/",
+  zValidator("json", createBufferRuleSchema),
+  async (c) => {
+    const db = getDb();
+    const body = c.req.valid("json");
+
+    // Validate serviceId exists
+    const [svc] = await db
+      .select({ id: services.id })
+      .from(services)
+      .where(eq(services.id, body.serviceId));
+    if (!svc) return c.json({ error: "Service not found" }, 404);
+
+    // Check for duplicate (service + size + coat)
+    const [existing] = await db
+      .select({ id: bufferRules.id })
+      .from(bufferRules)
+      .where(
+        and(
+          eq(bufferRules.serviceId, body.serviceId),
+          body.sizeCategory !== undefined
+            ? eq(bufferRules.sizeCategory, body.sizeCategory)
+            : isNull(bufferRules.sizeCategory),
+          body.coatType !== undefined
+            ? eq(bufferRules.coatType, body.coatType)
+            : isNull(bufferRules.coatType)
+        )
+      );
+    if (existing) return c.json({ error: "Duplicate rule for this service+size+coat combination" }, 409);
+
+    const [row] = await db
+      .insert(bufferRules)
+      .values({
+        serviceId: body.serviceId,
+        sizeCategory: body.sizeCategory ?? null,
+        coatType: body.coatType ?? null,
+        bufferMinutes: body.bufferMinutes,
+      })
+      .returning();
+
+    return c.json(row, 201);
+  }
+);
+
+// PATCH /:id — update bufferMinutes only
+bufferRulesRouter.patch(
+  "/:id",
+  zValidator("json", updateBufferRuleSchema),
+  async (c) => {
+    const db = getDb();
+    const body = c.req.valid("json");
+    const [row] = await db
+      .update(bufferRules)
+      .set({ bufferMinutes: body.bufferMinutes, updatedAt: new Date() })
+      .where(eq(bufferRules.id, c.req.param("id")))
+      .returning();
+    if (!row) return c.json({ error: "Not found" }, 404);
+    return c.json(row);
+  }
+);
+
+// DELETE /:id — delete a buffer rule
+bufferRulesRouter.delete("/:id", async (c) => {
+  const db = getDb();
+  const [row] = await db
+    .delete(bufferRules)
+    .where(eq(bufferRules.id, c.req.param("id")))
+    .returning();
+  if (!row) return c.json({ error: "Not found" }, 404);
+  return c.json({ ok: true });
+});

apps/api/src/routes/calendar.ts

@@ -10,7 +10,7 @@ import {
   pets,
   services,
   staff,
-} from "../db";
+} from "../db/index.js";
 
 export const calendarRouter = new Hono();
 

apps/api/src/routes/clients.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, eq, exists, getDb, or, clients, appointments } from "../db";
+import { and, eq, exists, getDb, or, clients, appointments } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const clientsRouter = new Hono<AppEnv>();

apps/api/src/routes/dev.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { getDb, staff, clients, eq, sql } from "../db";
+import { getDb, staff, clients, eq, sql } from "../db/index.js";
 
 const devRouter = new Hono();
 

apps/api/src/routes/groomingLogs.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, desc, eq, getDb, groomingVisitLogs, appointments, or } from "../db";
+import { and, desc, eq, getDb, groomingVisitLogs, appointments, or } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const groomingLogsRouter = new Hono<AppEnv>();

apps/api/src/routes/impersonation.ts

@@ -9,7 +9,7 @@ import {
   impersonationAuditLogs,
   clients,
   desc,
-} from "../db";
+} from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const impersonationRouter = new Hono<AppEnv>();

apps/api/src/routes/invoices.ts

@@ -13,7 +13,7 @@ import {
   services,
   clients,
   sql,
-} from "../db";
+} from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const invoicesRouter = new Hono<AppEnv>();

apps/api/src/routes/pets.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, eq, exists, getDb, or, pets, appointments } from "../db";
+import { and, desc, eq, exists, getDb, gte, groomingVisitLogs, impersonationSessions, or, pets, appointments, staff, services, sql } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 import {
   getPresignedUploadUrl,
@@ -24,6 +24,16 @@ const createPetSchema = z.object({
   shampooPreference: z.string().max(500).optional(),
   specialCareNotes: z.string().max(2000).optional(),
   customFields: z.record(z.string(), z.string()).optional(),
+  sizeCategory: z.enum(["small", "medium", "large", "extra_large"]).optional(),
+  coatType: z.enum(["short", "medium", "long", "double", "wire", "silky", "curly", "hairless"]).optional(),
+  temperamentScore: z.number().int().min(1).max(5).optional(),
+  temperamentFlags: z.array(z.string().max(100)).max(20).optional(),
+  medicalAlerts: z.array(z.object({
+    type: z.string().max(100),
+    description: z.string().max(1000),
+    severity: z.enum(["low", "medium", "high"]),
+  })).max(50).optional(),
+  preferredCuts: z.array(z.string().max(200)).max(20).optional(),
 });
 
 const updatePetSchema = createPetSchema.partial().omit({ clientId: true });
@@ -273,3 +283,169 @@ petsRouter.get("/:petId/photo", async (c) => {
   const url = await getPresignedGetUrl(pet.photoKey);
   return c.json({ url, photoKey: pet.photoKey, photoUploadedAt: pet.photoUploadedAt });
 });
+
+// ─── Profile Summary ───────────────────────────────────────────────────────────
+
+async function groomerLinkageCheck(
+  db: ReturnType<typeof getDb>,
+  clientId: string,
+  staffRow: NonNullable<AppEnv["Variables"]["staff"]>
+): Promise<boolean> {
+  const [linkage] = await db
+    .select({ id: appointments.id })
+    .from(appointments)
+    .where(
+      and(
+        eq(appointments.clientId, clientId),
+        or(
+          eq(appointments.staffId, staffRow.id),
+          eq(appointments.batherStaffId, staffRow.id)
+        )
+      )
+    )
+    .limit(1);
+  return !!linkage;
+}
+
+/**
+ * Resolves the clientId from the X-Impersonation-Session-Id header, if present and active.
+ * Used by staff routes to allow a customer (auto-provisioned as a `groomer` staff row
+ * by rbac.ts) to access their own pet's data when they are the rightful owner.
+ *
+ * Returns null when the header is missing, the session is unknown/expired/ended, or the
+ * session exists but has no clientId — callers should treat null as "no owner-bypass".
+ */
+async function resolveImpersonationClientId(
+  db: ReturnType<typeof getDb>,
+  c: { req: { header: (name: string) => string | undefined } }
+): Promise<string | null> {
+  const sessionId = c.req.header("X-Impersonation-Session-Id");
+  if (!sessionId) return null;
+  const [session] = await db
+    .select({ clientId: impersonationSessions.clientId, status: impersonationSessions.status, expiresAt: impersonationSessions.expiresAt })
+    .from(impersonationSessions)
+    .where(eq(impersonationSessions.id, sessionId))
+    .limit(1);
+  if (!session) return null;
+  if (session.status !== "active") return null;
+  if (session.expiresAt <= new Date()) return null;
+  return session.clientId;
+}
+
+/**
+ * GET /:id/profile-summary
+ * Returns aggregated profile: basic pet fields + grooming history + visit stats + upcoming appointment.
+ * Groomer RBAC: same visibility rules as GET /:id.
+ * Owner-bypass (GRO-2013): a customer who supplies a valid X-Impersonation-Session-Id
+ * for the pet's owning client may read their own pet's summary, even though rbac.ts
+ * auto-provisions them as a `groomer` staff row with no appointment linkage.
+ */
+petsRouter.get("/:id/profile-summary", async (c) => {
+  const db = getDb();
+  const petId = c.req.param("id");
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
+
+  const [row] = await db.select().from(pets).where(eq(pets.id, petId));
+  if (!row) return c.json({ error: "Not found" }, 404);
+
+  // Owner-bypass: customer with a valid portal session for this pet's client
+  // is allowed to view their own pet's profile summary (GRO-2013).
+  let isOwner = false;
+  if (isGroomer) {
+    const ownerClientId = await resolveImpersonationClientId(db, c);
+    isOwner = !!ownerClientId && ownerClientId === row.clientId;
+  }
+
+  if (isGroomer && !isOwner) {
+    const hasLinkage = await groomerLinkageCheck(db, row.clientId, staffRow);
+    if (!hasLinkage) return c.json({ error: "Forbidden" }, 403);
+  }
+
+  // Recent grooming history: last 10, with staff name join
+  const historyRows = await db
+    .select({
+      id: groomingVisitLogs.id,
+      petId: groomingVisitLogs.petId,
+      appointmentId: groomingVisitLogs.appointmentId,
+      staffId: groomingVisitLogs.staffId,
+      staffName: staff.name,
+      cutStyle: groomingVisitLogs.cutStyle,
+      productsUsed: groomingVisitLogs.productsUsed,
+      notes: groomingVisitLogs.notes,
+      groomedAt: groomingVisitLogs.groomedAt,
+      createdAt: groomingVisitLogs.createdAt,
+    })
+    .from(groomingVisitLogs)
+    .leftJoin(staff, eq(staff.id, groomingVisitLogs.staffId))
+    .where(eq(groomingVisitLogs.petId, petId))
+    .orderBy(desc(groomingVisitLogs.groomedAt))
+    .limit(10);
+
+  const recentGroomingHistory = historyRows.map((r) => ({
+    id: r.id,
+    petId: r.petId,
+    appointmentId: r.appointmentId,
+    staffId: r.staffId,
+    staffName: r.staffName,
+    cutStyle: r.cutStyle,
+    productsUsed: r.productsUsed,
+    notes: r.notes,
+    groomedAt: r.groomedAt?.toISOString() ?? null,
+    createdAt: r.createdAt?.toISOString() ?? null,
+  }));
+
+  const lastVisitDate = historyRows[0]?.groomedAt?.toISOString() ?? null;
+
+  // Completed appointment count for this pet
+  const [{ count: visitCount }] = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(appointments)
+    .where(and(eq(appointments.petId, petId), eq(appointments.status, "completed")));
+
+  // Upcoming appointment: next scheduled or confirmed
+  const [nextAppt] = await db
+    .select({
+      id: appointments.id,
+      serviceId: appointments.serviceId,
+      staffId: appointments.staffId,
+      startTime: appointments.startTime,
+      endTime: appointments.endTime,
+      status: appointments.status,
+      serviceName: services.name,
+      staffName: staff.name,
+    })
+    .from(appointments)
+    .leftJoin(services, eq(services.id, appointments.serviceId))
+    .leftJoin(staff, eq(staff.id, appointments.staffId))
+    .where(
+      and(
+        eq(appointments.petId, petId),
+        or(eq(appointments.status, "scheduled"), eq(appointments.status, "confirmed")),
+        gte(appointments.startTime, new Date())
+      )
+    )
+    .orderBy(appointments.startTime)
+    .limit(1);
+
+  const upcomingAppointment = nextAppt
+    ? {
+        id: nextAppt.id,
+        serviceId: nextAppt.serviceId,
+        serviceName: nextAppt.serviceName,
+        staffId: nextAppt.staffId,
+        staffName: nextAppt.staffName,
+        startTime: nextAppt.startTime?.toISOString() ?? null,
+        endTime: nextAppt.endTime?.toISOString() ?? null,
+        status: nextAppt.status,
+      }
+    : null;
+
+  return c.json({
+    ...row,
+    recentGroomingHistory,
+    lastVisitDate,
+    visitCount,
+    upcomingAppointment,
+  });
+});

apps/api/src/routes/portal.ts

@@ -1,8 +1,8 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { eq, inArray } from "../db";
-import { getDb, appointments, impersonationSessions, waitlistEntries, clients, pets, services, staff, invoices, invoiceLineItems } from "../db";
+import { eq, inArray } from "../db/index.js";
+import { getDb, appointments, impersonationSessions, waitlistEntries, clients, pets, services, staff, invoices, invoiceLineItems } from "../db/index.js";
 import { validatePortalSession } from "../middleware/portalSession.js";
 import { portalAudit } from "../middleware/portalAudit.js";
 import type { PortalEnv } from "../middleware/portalSession.js";

apps/api/src/routes/reports.ts

@@ -12,7 +12,7 @@ import {
   invoiceTipSplits,
   services,
   staff,
-} from "../db";
+} from "../db/index.js";
 
 export const reportsRouter = new Hono();
 

apps/api/src/routes/search.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { and, eq, getDb, clients, ilike, or, pets } from "../db";
+import { and, eq, getDb, clients, ilike, or, pets } from "../db/index.js";
 
 export const searchRouter = new Hono();
 

apps/api/src/routes/services.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { eq, getDb, services } from "../db";
+import { eq, getDb, services } from "../db/index.js";
 
 export const servicesRouter = new Hono();
 
@@ -13,7 +13,9 @@ const createServiceSchema = z.object({
   active: z.boolean().default(true),
 });
 
-const updateServiceSchema = createServiceSchema.partial();
+const updateServiceSchema = createServiceSchema.partial().extend({
+  defaultBufferMinutes: z.number().int().min(0).optional(),
+});
 
 servicesRouter.get("/", async (c) => {
   const db = getDb();

apps/api/src/routes/settings.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { eq, getDb, businessSettings } from "../db";
+import { eq, getDb, businessSettings } from "../db/index.js";
 import { getPresignedUploadUrl, deleteObject, putObject, getObject } from "../lib/s3.js";
 import { requireSuperUser } from "../middleware/rbac.js";
 

apps/api/src/routes/setup.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, eq, getDb, sql, staff, businessSettings, authProviderConfig, encryptSecret } from "../db";
+import { and, eq, getDb, sql, staff, businessSettings, authProviderConfig, encryptSecret } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 const RATE_LIMIT_WINDOW_MS = 60_000;

apps/api/src/routes/staff.ts

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
 import { randomBytes } from "node:crypto";
-import { and, eq, getDb, ne, staff, appointments } from "../db";
+import { and, eq, getDb, ne, staff, appointments } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const staffRouter = new Hono<AppEnv>();

apps/api/src/routes/stripe-webhooks.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import Stripe from "stripe";
 import { z } from "zod/v3";
-import { eq, getDb, invoices } from "../db";
+import { eq, getDb, invoices } from "../db/index.js";
 import { getStripeClient } from "../services/payment.js";
 
 export const webhooksRouter = new Hono();

apps/api/src/routes/waitlist.ts

@@ -8,7 +8,7 @@ import {
   clients,
   pets,
   services,
-} from "../db";
+} from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
 export const waitlistRouter = new Hono<AppEnv>();

apps/api/src/services/payment.ts

@@ -1,5 +1,5 @@
 import Stripe from "stripe";
-import { getDb, clients, eq, inArray, invoices } from "../db";
+import { getDb, clients, eq, inArray, invoices } from "../db/index.js";
 
 let _stripe: Stripe | null | undefined;
 

apps/api/src/services/reminders.ts

@@ -14,7 +14,7 @@ import {
   staff,
   reminderLogs,
   session,
-} from "../db";
+} from "../db/index.js";
 import {
   buildReminderEmail,
   sendEmail,

apps/api/src/services/waitlistNotify.ts

@@ -1,4 +1,4 @@
-import { and, eq, getDb, waitlistEntries, clients, pets, services } from "../db";
+import { and, eq, getDb, waitlistEntries, clients, pets, services } from "../db/index.js";
 import { buildWaitlistNotificationEmail, sendEmail } from "./email.js";
 
 export async function notifyWaitlistForAppointment(

apps/api/src/types/index.ts

@@ -26,6 +26,19 @@ export interface Client {
   updatedAt: string;
 }
 
+// ─── Medical Alerts ────────────────────────────────────────────────────────────
+
+export type AlertSeverity = "low" | "medium" | "high";
+
+export interface MedicalAlert {
+  type: string;
+  description: string;
+  severity: AlertSeverity;
+}
+
+// ─── Pet Profile Summary ────────────────────────────────────────────────────
+
+export type CoatType = "short" | "medium" | "long" | "double" | "wire" | "silky" | "curly" | "hairless";
 export interface Pet {
   id: string;
   clientId: string;
@@ -42,10 +55,23 @@ export interface Pet {
   customFields: Record<string, string>;
   photoKey?: string;
   photoUploadedAt?: string;
+  coatType?: string | null;
+  temperamentScore?: number | null;
+  temperamentFlags?: string[];
+  medicalAlerts?: MedicalAlert[];
+  preferredCuts?: string[];
   createdAt: string;
   updatedAt: string;
 }
 
+export type MedicalAlertSeverity = "low" | "medium" | "high";
+
+export interface MedicalAlert {
+  type: string;
+  description: string;
+  severity: MedicalAlertSeverity;
+}
+
 export interface GroomingVisitLog {
   id: string;
   petId: string;

eslint.config.js

@@ -0,0 +1,11 @@
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+    },
+  }
+);

package.json

@@ -3,5 +3,42 @@
   "version": "0.0.1",
   "private": true,
   "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc --project .",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.800.0",
+    "@aws-sdk/s3-request-presigner": "^3.800.0",
+    "@groombook/db": "workspace:*",
+    "@groombook/types": "workspace:*",
+    "@hono/node-server": "^1.13.7",
+    "@hono/zod-validator": "^0.7.6",
+    "better-auth": "^1.5.6",
+    "drizzle-orm": "^0.38.4",
+    "hono": "^4.6.17",
+    "node-cron": "^3.0.3",
+    "nodemailer": "^6.9.16",
+    "postgres": "^3.4.5",
+    "stripe": "^22.0.0",
+    "telnyx": "^1.23.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@types/node-cron": "^3.0.11",
+    "@types/nodemailer": "^6.4.17",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.18.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.2.4"
+  },
   "license": "AGPL-3.0-only"
 }

packages/db/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

packages/db/migrations/0000_colossal_colossus.sql

@@ -0,0 +1,70 @@
+CREATE TYPE "public"."appointment_status" AS ENUM('scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show');--> statement-breakpoint
+CREATE TYPE "public"."staff_role" AS ENUM('groomer', 'receptionist', 'manager');--> statement-breakpoint
+CREATE TABLE "appointments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"client_id" uuid NOT NULL,
+	"pet_id" uuid NOT NULL,
+	"service_id" uuid NOT NULL,
+	"staff_id" uuid,
+	"status" "appointment_status" DEFAULT 'scheduled' NOT NULL,
+	"start_time" timestamp NOT NULL,
+	"end_time" timestamp NOT NULL,
+	"notes" text,
+	"price_cents" integer,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "clients" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"email" text,
+	"phone" text,
+	"address" text,
+	"notes" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "pets" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"client_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"species" text NOT NULL,
+	"breed" text,
+	"weight_kg" numeric(5, 2),
+	"date_of_birth" timestamp,
+	"grooming_notes" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "services" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"base_price_cents" integer NOT NULL,
+	"duration_minutes" integer NOT NULL,
+	"active" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "staff" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"oidc_sub" text,
+	"role" "staff_role" DEFAULT 'groomer' NOT NULL,
+	"active" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "staff_email_unique" UNIQUE("email"),
+	CONSTRAINT "staff_oidc_sub_unique" UNIQUE("oidc_sub")
+);
+--> statement-breakpoint
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_pet_id_pets_id_fk" FOREIGN KEY ("pet_id") REFERENCES "public"."pets"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_service_id_services_id_fk" FOREIGN KEY ("service_id") REFERENCES "public"."services"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_staff_id_staff_id_fk" FOREIGN KEY ("staff_id") REFERENCES "public"."staff"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "pets" ADD CONSTRAINT "pets_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE cascade ON UPDATE no action;

packages/db/migrations/0001_pet_health_alerts.sql

@@ -0,0 +1 @@
+ALTER TABLE "pets" ADD COLUMN "health_alerts" text;

packages/db/migrations/0002_invoices.sql

@@ -0,0 +1,31 @@
+CREATE TYPE "public"."invoice_status" AS ENUM('draft', 'pending', 'paid', 'void');--> statement-breakpoint
+CREATE TYPE "public"."payment_method" AS ENUM('cash', 'card', 'check', 'other');--> statement-breakpoint
+CREATE TABLE "invoices" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"appointment_id" uuid,
+	"client_id" uuid NOT NULL,
+	"subtotal_cents" integer NOT NULL,
+	"tax_cents" integer DEFAULT 0 NOT NULL,
+	"tip_cents" integer DEFAULT 0 NOT NULL,
+	"total_cents" integer NOT NULL,
+	"status" "invoice_status" DEFAULT 'draft' NOT NULL,
+	"payment_method" "payment_method",
+	"paid_at" timestamp,
+	"notes" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "invoice_line_items" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"invoice_id" uuid NOT NULL,
+	"description" text NOT NULL,
+	"quantity" integer DEFAULT 1 NOT NULL,
+	"unit_price_cents" integer NOT NULL,
+	"total_cents" integer NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "invoices" ADD CONSTRAINT "invoices_appointment_id_appointments_id_fk" FOREIGN KEY ("appointment_id") REFERENCES "public"."appointments"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoices" ADD CONSTRAINT "invoices_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoice_line_items" ADD CONSTRAINT "invoice_line_items_invoice_id_invoices_id_fk" FOREIGN KEY ("invoice_id") REFERENCES "public"."invoices"("id") ON DELETE cascade ON UPDATE no action;

packages/db/migrations/0003_recurring_series.sql

@@ -0,0 +1,10 @@
+-- Add recurring_series table to store recurrence patterns
+CREATE TABLE "recurring_series" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"frequency_weeks" integer NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+
+-- Extend appointments with series tracking
+ALTER TABLE "appointments" ADD COLUMN "series_id" uuid REFERENCES "recurring_series"("id") ON DELETE SET NULL;
+ALTER TABLE "appointments" ADD COLUMN "series_index" integer;

packages/db/migrations/0004_reminder_logs.sql

@@ -0,0 +1,11 @@
+-- Add email opt-out flag to clients
+ALTER TABLE "clients" ADD COLUMN "email_opt_out" boolean NOT NULL DEFAULT false;
+
+-- Track sent reminders to prevent duplicate sends
+CREATE TABLE "reminder_logs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"appointment_id" uuid NOT NULL REFERENCES "appointments"("id") ON DELETE CASCADE,
+	"reminder_type" text NOT NULL,
+	"sent_at" timestamp DEFAULT now() NOT NULL,
+	UNIQUE ("appointment_id", "reminder_type")
+);

packages/db/migrations/0005_appointment_groups.sql

@@ -0,0 +1,12 @@
+-- Appointment groups: link multiple appointments from the same client visit.
+-- Each appointment in a group is for a different pet and may have a different groomer.
+CREATE TABLE appointment_groups (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  client_id UUID NOT NULL REFERENCES clients(id) ON DELETE RESTRICT,
+  notes TEXT,
+  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+-- Link appointments to a group (nullable — non-grouped appointments are unaffected)
+ALTER TABLE appointments ADD COLUMN group_id UUID REFERENCES appointment_groups(id) ON DELETE SET NULL;

packages/db/migrations/0006_pet_profile_attributes.sql

@@ -0,0 +1,30 @@
+-- Extend pet profiles with grooming-specific attributes (closes groombook/groombook#13)
+ALTER TABLE "pets"
+  ADD COLUMN "cut_style" text,
+  ADD COLUMN "shampoo_preference" text,
+  ADD COLUMN "special_care_notes" text,
+  ADD COLUMN "custom_fields" jsonb DEFAULT '{}' NOT NULL;
+--> statement-breakpoint
+CREATE TABLE "grooming_visit_logs" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "pet_id" uuid NOT NULL,
+  "appointment_id" uuid,
+  "staff_id" uuid,
+  "cut_style" text,
+  "products_used" text,
+  "notes" text,
+  "groomed_at" timestamp NOT NULL DEFAULT now(),
+  "created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "grooming_visit_logs"
+  ADD CONSTRAINT "grooming_visit_logs_pet_id_pets_id_fk"
+    FOREIGN KEY ("pet_id") REFERENCES "public"."pets"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "grooming_visit_logs"
+  ADD CONSTRAINT "grooming_visit_logs_appointment_id_appointments_id_fk"
+    FOREIGN KEY ("appointment_id") REFERENCES "public"."appointments"("id") ON DELETE set null ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "grooming_visit_logs"
+  ADD CONSTRAINT "grooming_visit_logs_staff_id_staff_id_fk"
+    FOREIGN KEY ("staff_id") REFERENCES "public"."staff"("id") ON DELETE set null ON UPDATE no action;

packages/db/migrations/0007_tip_splitting.sql

@@ -0,0 +1,25 @@
+-- Add bather/assistant staff tracking to appointments and tip split ledger (closes groombook/groombook#12)
+
+-- Secondary staff member (e.g., bather) who assisted the primary groomer
+ALTER TABLE "appointments"
+  ADD COLUMN "bather_staff_id" uuid REFERENCES "public"."staff"("id") ON DELETE set null ON UPDATE no action;
+--> statement-breakpoint
+
+-- Stores per-staff tip allocations calculated when an invoice is paid
+CREATE TABLE "invoice_tip_splits" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "invoice_id" uuid NOT NULL,
+  "staff_id" uuid,
+  "staff_name" text NOT NULL,
+  "share_pct" numeric(5, 2) NOT NULL,
+  "share_cents" integer NOT NULL,
+  "created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "invoice_tip_splits"
+  ADD CONSTRAINT "invoice_tip_splits_invoice_id_invoices_id_fk"
+    FOREIGN KEY ("invoice_id") REFERENCES "public"."invoices"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "invoice_tip_splits"
+  ADD CONSTRAINT "invoice_tip_splits_staff_id_staff_id_fk"
+    FOREIGN KEY ("staff_id") REFERENCES "public"."staff"("id") ON DELETE set null ON UPDATE no action;

packages/db/migrations/0008_business_settings.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS "business_settings" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "business_name" text DEFAULT 'GroomBook' NOT NULL,
+  "logo_base64" text,
+  "logo_mime_type" text,
+  "primary_color" text DEFAULT '#4f8a6f' NOT NULL,
+  "accent_color" text DEFAULT '#8b7355' NOT NULL,
+  "created_at" timestamp DEFAULT now() NOT NULL,
+  "updated_at" timestamp DEFAULT now() NOT NULL
+);
+
+-- Seed a default row so GET always returns something
+INSERT INTO "business_settings" ("business_name", "primary_color", "accent_color")
+VALUES ('GroomBook', '#4f8a6f', '#8b7355')
+ON CONFLICT DO NOTHING;

packages/db/migrations/0009_client_soft_delete.sql

@@ -0,0 +1,6 @@
+-- Add client status (soft-delete support)
+CREATE TYPE "client_status" AS ENUM ('active', 'disabled');
+
+ALTER TABLE "clients"
+  ADD COLUMN "status" "client_status" NOT NULL DEFAULT 'active',
+  ADD COLUMN "disabled_at" timestamp;

packages/db/migrations/0010_impersonation_sessions.sql

@@ -0,0 +1,26 @@
+-- Create impersonation_session_status enum and tables
+CREATE TYPE "impersonation_session_status" AS ENUM ('active', 'ended', 'expired');
+
+CREATE TABLE "impersonation_sessions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"staff_id" uuid NOT NULL,
+	"client_id" uuid NOT NULL,
+	"reason" text,
+	"status" "impersonation_session_status" DEFAULT 'active' NOT NULL,
+	"started_at" timestamp DEFAULT now() NOT NULL,
+	"ended_at" timestamp,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "impersonation_sessions_staff_id_staff_id_fk" FOREIGN KEY ("staff_id") REFERENCES "staff"("id") ON DELETE restrict,
+	CONSTRAINT "impersonation_sessions_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "clients"("id") ON DELETE restrict
+);
+
+CREATE TABLE "impersonation_audit_logs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"session_id" uuid NOT NULL,
+	"action" text NOT NULL,
+	"page_visited" text,
+	"metadata" jsonb,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "impersonation_audit_logs_session_id_impersonation_sessions_id_fk" FOREIGN KEY ("session_id") REFERENCES "impersonation_sessions"("id") ON DELETE cascade
+);

packages/db/migrations/0011_impersonation_indexes.sql

@@ -0,0 +1,6 @@
+-- Add indexes on impersonation tables to prevent full table scans
+-- Ref: GitHub #95
+
+CREATE INDEX "impersonation_sessions_staff_id_status_idx" ON "impersonation_sessions" USING btree ("staff_id","status");--> statement-breakpoint
+CREATE INDEX "impersonation_sessions_client_id_idx" ON "impersonation_sessions" USING btree ("client_id");--> statement-breakpoint
+CREATE INDEX "impersonation_audit_logs_session_id_idx" ON "impersonation_audit_logs" USING btree ("session_id");

packages/db/migrations/0012_pet_photo.sql

@@ -0,0 +1,5 @@
+-- Add photo storage columns to pets table
+-- Ref: GitHub #93
+
+ALTER TABLE "pets" ADD COLUMN "photo_key" text;--> statement-breakpoint
+ALTER TABLE "pets" ADD COLUMN "photo_uploaded_at" timestamp;

packages/db/migrations/0013_appointment_confirmation.sql

@@ -0,0 +1,7 @@
+ALTER TABLE appointments
+  ADD COLUMN confirmation_status TEXT NOT NULL DEFAULT 'pending',
+  ADD COLUMN confirmed_at TIMESTAMPTZ,
+  ADD COLUMN cancelled_at TIMESTAMPTZ,
+  ADD COLUMN confirmation_token TEXT UNIQUE;
+
+CREATE INDEX idx_appointments_confirmation_token ON appointments (confirmation_token) WHERE confirmation_token IS NOT NULL;

packages/db/migrations/0014_customer_notes.sql

@@ -0,0 +1,3 @@
+ALTER TABLE appointments ADD COLUMN customer_notes TEXT;
+
+CREATE INDEX idx_appointments_customer_notes ON appointments (client_id) WHERE customer_notes IS NOT NULL;

packages/db/migrations/0015_waitlist.sql

@@ -0,0 +1,20 @@
+CREATE TYPE waitlist_status AS ENUM ('active', 'notified', 'expired', 'cancelled');
+
+CREATE TABLE waitlist_entries (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  client_id UUID NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+  pet_id UUID NOT NULL REFERENCES pets(id) ON DELETE CASCADE,
+  service_id UUID NOT NULL REFERENCES services(id) ON DELETE CASCADE,
+  preferred_date DATE NOT NULL,
+  preferred_time TIME NOT NULL,
+  status waitlist_status NOT NULL DEFAULT 'active',
+  notified_at TIMESTAMPTZ,
+  expires_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_waitlist_client_id ON waitlist_entries (client_id);
+CREATE INDEX idx_waitlist_preferred_date ON waitlist_entries (preferred_date);
+CREATE INDEX idx_waitlist_status ON waitlist_entries (status) WHERE status = 'active';
+CREATE UNIQUE INDEX idx_waitlist_active_unique ON waitlist_entries (client_id, pet_id, service_id, preferred_date, preferred_time) WHERE status = 'active';

packages/db/migrations/0016_ical_token.sql

@@ -0,0 +1 @@
+ALTER TABLE staff ADD COLUMN ical_token TEXT UNIQUE;

packages/db/migrations/0017_better_auth_tables.sql

@@ -0,0 +1,49 @@
+-- Better-Auth required tables for session-based authentication
+CREATE TABLE "user" (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL UNIQUE,
+  email_verified BOOLEAN NOT NULL DEFAULT false,
+  image TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE "session" (
+  id TEXT PRIMARY KEY,
+  expires_at TIMESTAMPTZ NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  ip_address TEXT,
+  user_agent TEXT,
+  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE "account" (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  provider_id TEXT NOT NULL,
+  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  access_token TEXT,
+  refresh_token TEXT,
+  id_token TEXT,
+  access_token_expires_at TIMESTAMPTZ,
+  refresh_token_expires_at TIMESTAMPTZ,
+  scope TEXT,
+  password TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE "verification" (
+  id TEXT PRIMARY KEY,
+  identifier TEXT NOT NULL,
+  value TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Link staff records to auth identity
+ALTER TABLE staff ADD COLUMN user_id TEXT REFERENCES "user"(id) ON DELETE SET NULL;

packages/db/migrations/0018_backfill_staff_user_id.sql

@@ -0,0 +1,14 @@
+-- Backfill staff.user_id for staff records created before Better-Auth integration.
+-- Staff records that predate this migration have user_id = NULL; the resolveStaffMiddleware
+-- now falls back to staff.id (dev mode) and oidcSub (production) so these records still work.
+-- This migration populates user_id for the known demo/dev staff seeded by seed.ts.
+
+-- Create demo Better-Auth users for seeded staff (these match the ba-user-* IDs used in tests)
+INSERT INTO "user" (id, name, email, email_verified, created_at, updated_at)
+VALUES ('ba-user-manager', 'Demo Manager', 'demo-manager@groombook.dev', true, NOW(), NOW())
+ON CONFLICT (id) DO NOTHING;
+
+-- Link the demo manager staff record to the Better-Auth user
+UPDATE staff
+SET user_id = 'ba-user-manager', updated_at = NOW()
+WHERE oidc_sub = 'demo-manager-001' AND user_id IS NULL;

packages/db/migrations/0019_concerned_sunfire.sql

@@ -0,0 +1 @@
+ALTER TABLE "staff" ADD COLUMN "is_super_user" boolean DEFAULT false NOT NULL;

packages/db/migrations/0020_typical_daimon_hellstrom.sql

@@ -0,0 +1,7 @@
+-- Clean up existing duplicate services before adding unique constraint.
+-- Keep the row with the lowest id per name; delete all others.
+DELETE FROM services WHERE id NOT IN (
+  SELECT (MIN(id::text))::uuid FROM services GROUP BY name
+);
+
+ALTER TABLE "services" ADD CONSTRAINT "services_name_unique" UNIQUE("name");

packages/db/migrations/0021_pet_image.sql

@@ -0,0 +1,2 @@
+-- Add image field to pets table for demo pet image support
+ALTER TABLE "pets" ADD COLUMN "image" text;

packages/db/migrations/0022_logo_key.sql

@@ -0,0 +1,2 @@
+-- Add logo_key column to business_settings for S3-based logo storage
+ALTER TABLE "business_settings" ADD COLUMN "logo_key" text;

packages/db/migrations/0023_auth_provider_config.sql

@@ -0,0 +1,14 @@
+CREATE TABLE "auth_provider_config" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"provider_id" text NOT NULL,
+	"display_name" text NOT NULL,
+	"issuer_url" text NOT NULL,
+	"internal_base_url" text,
+	"client_id" text NOT NULL,
+	"client_secret" text NOT NULL,
+	"scopes" text DEFAULT 'openid profile email' NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "auth_provider_config_provider_id_unique" UNIQUE("provider_id")
+);

packages/db/migrations/0024_invoice_indexes.sql

@@ -0,0 +1,5 @@
+CREATE INDEX idx_invoices_client_id ON invoices(client_id);
+CREATE INDEX idx_invoices_status ON invoices(status);
+CREATE INDEX idx_invoices_created_at ON invoices(created_at);
+CREATE INDEX idx_invoice_line_items_invoice_id ON invoice_line_items(invoice_id);
+CREATE INDEX idx_invoice_tip_splits_invoice_id ON invoice_tip_splits(invoice_id);

packages/db/migrations/0025_rate_limit.sql

@@ -0,0 +1,6 @@
+-- Better-Auth rate limiting table (GRO-574)
+CREATE TABLE "rate_limit" (
+  key TEXT NOT NULL PRIMARY KEY,
+  count INTEGER NOT NULL,
+  last_request BIGINT NOT NULL
+);

packages/db/migrations/0026_stripe_payment.sql

@@ -0,0 +1,6 @@
+ALTER TABLE "clients" ADD COLUMN "stripe_customer_id" text;
+ALTER TABLE "clients" ADD CONSTRAINT "idx_clients_stripe_customer_id" UNIQUE("stripe_customer_id");
+ALTER TABLE "invoices" ADD COLUMN "stripe_payment_intent_id" text;
+ALTER TABLE "invoices" ADD COLUMN "stripe_refund_id" text;
+ALTER TABLE "invoices" ADD COLUMN "payment_failure_reason" text;
+ALTER TABLE "invoices" ADD CONSTRAINT "idx_invoices_stripe_payment_intent_id" UNIQUE("stripe_payment_intent_id");

packages/db/migrations/0027_refunds.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "refunds" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "invoice_id" uuid NOT NULL REFERENCES "invoices"("id") ON DELETE RESTRICT,
+  "stripe_refund_id" text NOT NULL,
+  "idempotency_key" text UNIQUE,
+  "amount_cents" integer,
+  "created_at" timestamp NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX "idx_refunds_invoice_id" ON "refunds"("invoice_id");
+CREATE INDEX "idx_refunds_idempotency_key" ON "refunds"("idempotency_key");

packages/db/migrations/0028_sms_reminders.sql

@@ -0,0 +1,15 @@
+-- SMS opt-in fields for clients (idempotent)
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_opt_in" boolean NOT NULL DEFAULT false;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_consent_date" timestamp;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_opt_out_date" timestamp;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_consent_text" text;
+
+-- Add channel column to reminder_logs with default 'email' (idempotent)
+ALTER TABLE "reminder_logs" ADD COLUMN IF NOT EXISTS "channel" text NOT NULL DEFAULT 'email';
+
+-- Drop old unique constraints if they exist (idempotent)
+ALTER TABLE "reminder_logs" DROP CONSTRAINT IF EXISTS "reminder_logs_appointment_id_reminder_type_key";
+ALTER TABLE "reminder_logs" DROP CONSTRAINT IF EXISTS "reminder_logs_appointment_id_reminder_type_unique";
+
+-- Add new unique constraint with channel
+ALTER TABLE "reminder_logs" ADD CONSTRAINT "reminder_logs_appointment_id_reminder_type_channel_unique" UNIQUE ("appointment_id", "reminder_type", "channel");

packages/db/migrations/0029_db_indexes_constraints.sql

@@ -0,0 +1,20 @@
+-- Migration: 0029_db_indexes_constraints.sql
+-- Add missing indexes on appointments, pets, clients tables and NOT NULL constraint on clients.email
+
+-- Backfill NULL emails before setting NOT NULL
+UPDATE clients SET email = concat('unknown-', id::text, '@placeholder.local') WHERE email IS NULL;
+
+-- Add indexes on appointments table
+CREATE INDEX idx_appointments_client_id ON appointments(client_id);
+CREATE INDEX idx_appointments_staff_id ON appointments(staff_id);
+CREATE INDEX idx_appointments_start_time ON appointments(start_time);
+CREATE INDEX idx_appointments_status ON appointments(status);
+
+-- Add index on pets table
+CREATE INDEX idx_pets_client_id ON pets(client_id);
+
+-- Add index on clients table
+CREATE INDEX idx_clients_email ON clients(email);
+
+-- Set NOT NULL on clients.email (after backfill)
+ALTER TABLE clients ALTER COLUMN email SET NOT NULL;

packages/db/migrations/0030_messaging.sql

@@ -0,0 +1,72 @@
+-- Migration: 0030_messaging.sql
+-- Messaging schema: conversations, messages, attachments, consent events + business messaging settings
+
+-- ─── Enums ───────────────────────────────────────────────────────────────────
+
+CREATE TYPE "messaging_channel" AS ENUM ('sms', 'mms');
+CREATE TYPE "message_direction" AS ENUM ('inbound', 'outbound');
+CREATE TYPE "message_status" AS ENUM ('queued', 'sent', 'delivered', 'failed', 'received');
+CREATE TYPE "message_consent_kind" AS ENUM ('opt_in', 'opt_out', 'help');
+
+-- ─── Tables ───────────────────────────────────────────────────────────────────
+
+CREATE TABLE "conversations" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "business_id" uuid NOT NULL,
+  "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE,
+  "channel" "messaging_channel" NOT NULL,
+  "external_number" text NOT NULL,
+  "business_number" text NOT NULL,
+  "last_message_at" timestamp,
+  "status" text NOT NULL DEFAULT 'active',
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now()
+);
+
+CREATE INDEX "idx_conversations_business_id_last_message_at" ON "conversations"("business_id", "last_message_at" DESC);
+CREATE UNIQUE INDEX "uq_conversations_business_client_number" ON "conversations"("business_id", "client_id", "business_number");
+
+CREATE TABLE "messages" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "conversation_id" uuid NOT NULL REFERENCES "conversations"("id") ON DELETE CASCADE,
+  "direction" "message_direction" NOT NULL,
+  "body" text,
+  "status" "message_status" NOT NULL DEFAULT 'queued',
+  "provider_message_id" text,
+  "error_code" text,
+  "error_message" text,
+  "sent_by_staff_id" uuid REFERENCES "staff"("id") ON DELETE SET NULL,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "delivered_at" timestamp,
+  "read_by_client_at" timestamp
+);
+
+CREATE INDEX "idx_messages_conversation_id_created_at" ON "messages"("conversation_id", "created_at" DESC);
+CREATE UNIQUE INDEX "uq_messages_provider_message_id" ON "messages"("provider_message_id");
+
+CREATE TABLE "message_attachments" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "message_id" uuid NOT NULL REFERENCES "messages"("id") ON DELETE CASCADE,
+  "content_type" text NOT NULL,
+  "url" text NOT NULL,
+  "size" integer NOT NULL,
+  "provider_media_id" text
+);
+
+CREATE INDEX "idx_message_attachments_message_id" ON "message_attachments"("message_id");
+
+CREATE TABLE "message_consent_events" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE,
+  "business_id" uuid NOT NULL,
+  "kind" "message_consent_kind" NOT NULL,
+  "source" text,
+  "created_at" timestamp NOT NULL DEFAULT now()
+);
+
+CREATE INDEX "idx_message_consent_events_client_id" ON "message_consent_events"("client_id");
+
+-- ─── Business Settings extensions ────────────────────────────────────────────
+
+ALTER TABLE "business_settings" ADD COLUMN "messaging_phone_number" text;
+ALTER TABLE "business_settings" ADD COLUMN "telnyx_messaging_profile_id" text;

packages/db/migrations/0031_buffer_rules.sql

@@ -0,0 +1,33 @@
+-- Migration: 0031_buffer_rules.sql
+-- Buffer rules CRUD: pet size/coat enums, bufferRules table, services.defaultBufferMinutes
+
+-- ─── Enums ───────────────────────────────────────────────────────────────────
+
+CREATE TYPE "pet_size_category" AS ENUM ('small', 'medium', 'large', 'xlarge');
+CREATE TYPE "coat_type" AS ENUM ('smooth', 'double', 'wire', 'curly', 'long', 'hairless');
+
+-- ─── Add columns to pets if missing, then cast to enums ──────────────────────
+
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "coat_type" text;
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "pet_size_category" text;
+ALTER TABLE "pets" ALTER COLUMN "coat_type" TYPE "coat_type" USING "coat_type"::text::"coat_type";
+ALTER TABLE "pets" ALTER COLUMN "pet_size_category" TYPE "pet_size_category" USING "pet_size_category"::text::"pet_size_category";
+
+-- ─── Services: add defaultBufferMinutes ───────────────────────────────────────
+
+ALTER TABLE "services" ADD COLUMN "default_buffer_minutes" integer;
+
+-- ─── Buffer Rules table ───────────────────────────────────────────────────────
+
+CREATE TABLE "buffer_rules" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "service_id" uuid NOT NULL REFERENCES "services"("id") ON DELETE CASCADE,
+  "size_category" "pet_size_category",
+  "coat_type" "coat_type",
+  "buffer_minutes" integer NOT NULL,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now(),
+  CONSTRAINT "uq_buffer_rules_service_size_coat" UNIQUE ("service_id", "size_category", "coat_type")
+);
+
+CREATE INDEX "idx_buffer_rules_service_id" ON "buffer_rules"("service_id");

packages/db/migrations/0032_staff_read_at.sql

@@ -0,0 +1 @@
+-- no-op: journal entry exists but no schema change was needed

packages/db/migrations/0033_add_services_default_buffer_minutes.sql

@@ -0,0 +1,6 @@
+-- Migration: 0033_add_services_default_buffer_minutes.sql
+-- Adds missing default_buffer_minutes column to services table.
+-- 0031_buffer_rules was applied to the DB but its journal entry was missing,
+-- so this ensures idempotent column addition for fresh DB restores.
+
+ALTER TABLE "services" ADD COLUMN IF NOT EXISTS "default_buffer_minutes" integer DEFAULT 0 NOT NULL;

packages/db/migrations/0034_extend_pet_profile_columns.sql

@@ -0,0 +1,8 @@
+-- Migration: 0034_extend_pet_profile_columns.sql
+-- GRO-1850: Adds temperament_score, temperament_flags, medical_alerts,
+-- and preferred_cuts columns to the pets table.
+
+ALTER TABLE "pets" ADD COLUMN "temperament_score" integer;
+ALTER TABLE "pets" ADD COLUMN "temperament_flags" jsonb DEFAULT '[]';
+ALTER TABLE "pets" ADD COLUMN "medical_alerts" jsonb DEFAULT '[]';
+ALTER TABLE "pets" ADD COLUMN "preferred_cuts" jsonb DEFAULT '[]';

packages/db/migrations/0035_add_missing_coat_type_values.sql

@@ -0,0 +1,9 @@
+-- Migration: 0035_add_missing_coat_type_values.sql
+-- Adds missing values to coat_type enum that seed.ts requires but which were
+-- omitted from the 0031_buffer_rules.sql CREATE TYPE statement (migration drift).
+-- 0031 created: 'smooth', 'double', 'wire', 'curly', 'long', 'hairless'
+-- Missing (from schema.ts coatTypeEnum): 'short', 'medium', 'silky'
+
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'short';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'medium';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'silky';

packages/db/migrations/0035_add_short_to_coat_type_enum.sql

@@ -0,0 +1,14 @@
+-- Migration: 0035_add_short_to_coat_type_enum.sql
+-- GRO-1953: Adds missing "short" value to the coat_type enum so that seed data
+-- (which uses coatTypePool including "short") can be inserted without error.
+--
+-- The seed file defines coatTypePool as:
+--   ["short", "medium", "long", "double", "wire", "silky", "curly", "hairless"]
+-- but migration 0031 created the enum without "short", causing:
+--   PostgresError: invalid input value for enum coat_type: "short"
+
+BEGIN;
+
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'short';
+
+COMMIT;

packages/db/migrations/0036_add_missing_coat_type_values.sql

@@ -0,0 +1,9 @@
+-- Migration: 0036_add_missing_coat_type_values.sql
+-- Adds missing values to coat_type enum that seed.ts requires but which were
+-- omitted from the 0031_buffer_rules.sql CREATE TYPE statement (migration drift).
+-- 0031 created: 'smooth', 'double', 'wire', 'curly', 'long', 'hairless'
+-- Missing (from schema.ts coatTypeEnum): 'short', 'medium', 'silky'
+
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'short';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'medium';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'silky';

packages/db/migrations/0037_add_extra_large_to_pet_size_category.sql

@@ -0,0 +1,19 @@
+-- Migration: 0037_add_extra_large_to_pet_size_category.sql
+-- GRO-1979: Adds the 'extra_large' value to the pet_size_category enum.
+--
+-- 0031_buffer_rules.sql created pet_size_category with values
+-- ('small', 'medium', 'large', 'xlarge'), but seed.ts and the drizzle
+-- schema (PetSizeCategory type) both use 'extra_large' — a mismatch that
+-- caused the UAT seed job to fail with:
+--   invalid input value for enum pet_size_category: "extra_large"
+--
+-- 0035/0036 (GRO-1971) registered 'short'/'medium'/'silky' in coat_type.
+-- This migration is the pet_size_category counterpart: register
+-- 'extra_large' so seed.ts can write the value the schema declares.
+--
+-- Postgres restriction: ALTER TYPE ADD VALUE cannot run inside a
+-- transaction block. The drizzle migrate runner does not wrap
+-- individual statements in an explicit transaction, so this applies
+-- as a single auto-commit DDL.
+
+ALTER TYPE "pet_size_category" ADD VALUE IF NOT EXISTS 'extra_large';

packages/db/migrations/0038_register_extra_large_pet_size_category.sql

@@ -0,0 +1,4 @@
+-- GRO-1999: 0037 was skipped on existing DBs due to a below-high-water-mark
+-- journal timestamp. Re-register extra_large with a monotonic timestamp so
+-- the existing UAT/persistent DBs apply it. Idempotent.
+ALTER TYPE "pet_size_category" ADD VALUE IF NOT EXISTS 'extra_large';

packages/db/migrations/0039_extend_pet_profile_columns_idempotent.sql

@@ -0,0 +1,27 @@
+-- Migration: 0039_extend_pet_profile_columns_idempotent.sql
+-- GRO-2033: re-register the temperament/medical/preferred-cuts columns from
+-- 0034 with an idempotent ADD COLUMN IF NOT EXISTS + a monotonic journal
+-- `when` (1780000000001), above the 0033 high-water mark (1779500000000)
+-- and above the most recent applied migration 0038 (1780000000000).
+--
+-- 0034_extend_pet_profile_columns.sql was authored on 2026-05-28 with
+-- `when` = 1751140800000 (2025-06-28) — *below* the 0033 high-water mark
+-- of 1779500000000 (2026-05-23). drizzle-orm@0.38.4
+-- (pg-core/dialect.js#migrate) only applies a migration when
+-- `migration.folderMillis > lastDbMigration.created_at`, so on prod —
+-- whose last applied entry was 0033 at created_at=1779500000000 — 0034
+-- was silently skipped, leaving `pets.temperament_score` (and friends)
+-- missing. The migrate Job still exits 0 ("migrations applied
+-- successfully!") because the journal high watermark *was* advanced by
+-- 0038, but no schema change ever ran for 0034. Seed/reset then crash on:
+--   PostgresError: column "temperament_score" does not exist (42703)
+--
+-- Same pattern as GRO-1999 (0037 → 0038): do NOT modify 0034 in-place
+-- (UAT/dev have already applied it via their lower watermarks). Add a
+-- new idempotent migration with a monotonic `when` instead so existing
+-- DBs apply it cleanly and fresh DBs are a no-op-after-no-op.
+
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "temperament_score" integer;
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "temperament_flags" jsonb DEFAULT '[]';
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "medical_alerts" jsonb DEFAULT '[]';
+ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "preferred_cuts" jsonb DEFAULT '[]';

packages/db/migrations/0040_register_missing_coat_type_values.sql

@@ -0,0 +1,26 @@
+-- Migration: 0040_register_missing_coat_type_values.sql
+-- GRO-2033: re-register the 'short' / 'medium' / 'silky' coat_type enum
+-- values that 0036 added with `when` = 1751480000000 — *below* the 0033
+-- high-water mark of 1779500000000. drizzle-orm@0.38.4
+-- (pg-core/dialect.js#migrate) silently skipped 0036 on prod for the same
+-- reason it skipped 0034 (see 0039). 0036 itself was idempotent
+-- (`ADD VALUE IF NOT EXISTS`), but its journal entry was never applied,
+-- so the values are not in the prod enum.
+--
+-- Same pattern as GRO-1999 (0037 → 0038) and 0039: do NOT modify 0036 in
+-- place. Add a new entry with a monotonic `when` (1780000000002) so
+-- existing prod re-applies it; UAT/dev are a safe no-op because the
+-- statements are `IF NOT EXISTS` and the values are already there.
+--
+-- Postgres restriction: `ALTER TYPE ... ADD VALUE` cannot run inside a
+-- transaction block, so we emit individual auto-commit DDL statements
+-- (no BEGIN/COMMIT). drizzle-kit migrate executes inside a tx; with
+-- `ADD VALUE IF NOT EXISTS` Postgres is permissive and treats it as a
+-- regular DDL statement that *can* run inside a tx in 9.6+ when no new
+-- value is actually added. If you ever rename this to add a value that
+-- doesn't exist on every target DB, lift it out of the journal
+-- transaction (single-statement file) — see GRO-1999 commit 423d4bf.
+
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'short';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'medium';
+ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'silky';

packages/db/migrations/0041_route_optimization.sql

@@ -0,0 +1,66 @@
+-- Migration: 0041_route_optimization.sql
+-- Route optimization schema: geocoding columns on clients, groomerRoutes +
+-- routeStops tables, and route settings on business_settings.
+-- Written idempotently so it is safe to re-run.
+
+-- ─── Enums ────────────────────────────────────────────────────────────────────
+
+DO $$ BEGIN
+  CREATE TYPE "route_status" AS ENUM ('draft', 'optimized', 'in_progress', 'completed');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+-- ─── Clients: geocoding columns ───────────────────────────────────────────────
+
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "latitude" double precision;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "longitude" double precision;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "geocoded_at" timestamp;
+
+-- ─── Business settings: route optimization config ─────────────────────────────
+
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "default_travel_buffer_mins" integer NOT NULL DEFAULT 15;
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "route_optimization_provider" text DEFAULT 'nominatim';
+-- Encrypted at rest at the application layer (AES-256-GCM).
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "google_maps_api_key" text;
+
+-- ─── Groomer routes table ─────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS "groomer_routes" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "staff_id" uuid NOT NULL REFERENCES "staff"("id") ON DELETE CASCADE,
+  "route_date" date NOT NULL,
+  "status" "route_status" NOT NULL DEFAULT 'draft',
+  "total_travel_mins" integer,
+  "total_distance_km" numeric(8, 2),
+  "optimized_at" timestamp,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now(),
+  CONSTRAINT "uq_groomer_routes_staff_date" UNIQUE ("staff_id", "route_date")
+);
+
+CREATE INDEX IF NOT EXISTS "idx_groomer_routes_staff_id"
+  ON "groomer_routes"("staff_id");
+
+-- ─── Route stops table ────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS "route_stops" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "route_id" uuid NOT NULL REFERENCES "groomer_routes"("id") ON DELETE CASCADE,
+  "appointment_id" uuid NOT NULL REFERENCES "appointments"("id") ON DELETE CASCADE,
+  "stop_order" integer NOT NULL,
+  "latitude" double precision NOT NULL,
+  "longitude" double precision NOT NULL,
+  "travel_mins_from_prev" integer,
+  "travel_distance_km_from_prev" numeric(8, 2),
+  "buffer_mins" integer NOT NULL DEFAULT 15,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now(),
+  CONSTRAINT "uq_route_stops_route_appointment" UNIQUE ("route_id", "appointment_id"),
+  CONSTRAINT "uq_route_stops_route_order" UNIQUE ("route_id", "stop_order")
+);
+
+CREATE INDEX IF NOT EXISTS "idx_route_stops_route_id"
+  ON "route_stops"("route_id");

packages/db/migrations/meta/0000_snapshot.json

@@ -0,0 +1,485 @@
+{
+  "id": "477cddf9-970f-41c5-9cad-c1ed48c2bedf",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.appointments": {
+      "name": "appointments",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pet_id": {
+          "name": "pet_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "service_id": {
+          "name": "service_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "staff_id": {
+          "name": "staff_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "appointment_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'scheduled'"
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "end_time": {
+          "name": "end_time",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "price_cents": {
+          "name": "price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "appointments_client_id_clients_id_fk": {
+          "name": "appointments_client_id_clients_id_fk",
+          "tableFrom": "appointments",
+          "tableTo": "clients",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "restrict",
+          "onUpdate": "no action"
+        },
+        "appointments_pet_id_pets_id_fk": {
+          "name": "appointments_pet_id_pets_id_fk",
+          "tableFrom": "appointments",
+          "tableTo": "pets",
+          "columnsFrom": [
+            "pet_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "restrict",
+          "onUpdate": "no action"
+        },
+        "appointments_service_id_services_id_fk": {
+          "name": "appointments_service_id_services_id_fk",
+          "tableFrom": "appointments",
+          "tableTo": "services",
+          "columnsFrom": [
+            "service_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "restrict",
+          "onUpdate": "no action"
+        },
+        "appointments_staff_id_staff_id_fk": {
+          "name": "appointments_staff_id_staff_id_fk",
+          "tableFrom": "appointments",
+          "tableTo": "staff",
+          "columnsFrom": [
+            "staff_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.clients": {
+      "name": "clients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "phone": {
+          "name": "phone",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "address": {
+          "name": "address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.pets": {
+      "name": "pets",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "species": {
+          "name": "species",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "breed": {
+          "name": "breed",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "weight_kg": {
+          "name": "weight_kg",
+          "type": "numeric(5, 2)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "date_of_birth": {
+          "name": "date_of_birth",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "grooming_notes": {
+          "name": "grooming_notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "pets_client_id_clients_id_fk": {
+          "name": "pets_client_id_clients_id_fk",
+          "tableFrom": "pets",
+          "tableTo": "clients",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.services": {
+      "name": "services",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "base_price_cents": {
+          "name": "base_price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_minutes": {
+          "name": "duration_minutes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.staff": {
+      "name": "staff",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_sub": {
+          "name": "oidc_sub",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "staff_role",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'groomer'"
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "staff_email_unique": {
+          "name": "staff_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        },
+        "staff_oidc_sub_unique": {
+          "name": "staff_oidc_sub_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "oidc_sub"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.appointment_status": {
+      "name": "appointment_status",
+      "schema": "public",
+      "values": [
+        "scheduled",
+        "confirmed",
+        "in_progress",
+        "completed",
+        "cancelled",
+        "no_show"
+      ]
+    },
+    "public.staff_role": {
+      "name": "staff_role",
+      "schema": "public",
+      "values": [
+        "groomer",
+        "receptionist",
+        "manager"
+      ]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}