docs(UAT_PLAYBOOK): document canonical source-of-truth for UAT seed passwords (GRO-2000)

The 'Source of truth for UAT passwords' subsection under Pre-conditions
records:

- The seed-uat-passwords Secret in groombook-uat is the live source.
- The Bitnami SealedSecret apps/overlays/uat/ss-seed-uat-passwords.yaml
  in groombook/infra is the single upstream source of truth.
- A kubectl recipe to pull the current values for SUPER / GROOMER /
  TESTER / CUSTOMER at the start of every UAT run.
- The 'captured env var from a previous rotation produces 401' failure
  mode that GRO-2000 hit, and the manual-reseed escape hatch if the
  login still 401s after pulling the live value.

Refs: GRO-2000, GRO-1977 (idempotent re-hash), GRO-1999 (enum fix that
allowed the seed Job to run cleanly again).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -118,6 +118,17 @@ jobs:
           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:

Dockerfile

@@ -1,7 +1,10 @@
 FROM node:22-alpine AS base
-RUN corepack enable && corepack install -g pnpm@9.15.4
-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
-ENV COREPACK_ENABLE_STRICT=0
+# 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.
+RUN npm install -g pnpm@9.15.4
 WORKDIR /app
 
 # Install deps
@@ -22,9 +25,7 @@ RUN pnpm --filter @groombook/types build && \
 
 # Runtime
 FROM node:22-alpine AS runner
-RUN corepack enable && corepack install -g pnpm@9.15.4
-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
-ENV COREPACK_ENABLE_STRICT=0
+RUN npm install -g pnpm@9.15.4
 WORKDIR /app
 ENV NODE_ENV=production
 
@@ -53,7 +54,4 @@ CMD ["pnpm", "--filter", "@groombook/db", "seed"]
 
 # Reset stage — drops all tables, re-runs migrations, and re-seeds
 FROM builder AS reset
-RUN corepack enable && corepack install -g pnpm@9.15.4
-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
-ENV COREPACK_ENABLE_STRICT=0
 CMD ["pnpm", "--filter", "@groombook/db", "reset"]

UAT_PLAYBOOK.md

@@ -19,6 +19,27 @@ 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.
+
 ## Test Cases
 
 ### 4.0 Health Check
@@ -41,6 +62,8 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | 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 |
@@ -114,6 +137,10 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | 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) |
 
 ### 4.4 Appointment Scheduling
 

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

@@ -67,6 +67,7 @@ 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 };
@@ -77,6 +78,7 @@ function resetMock() {
   dbStaff = [];
   insertedUsers = [];
   insertedAccounts = [];
+  updatedAccounts = [];
   updatedStaff = [];
   process.env = { ...originalEnv };
 }
@@ -173,7 +175,11 @@ async function seedUatCredentials(
     );
 
     if (existingAccount) {
-      // skip — already has credential account
+      // 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");
@@ -312,9 +318,9 @@ describe("seedUatCredentials — credential provisioning logic", () => {
     expect(updatedStaff).toHaveLength(0);
   });
 
-  // ── AC-5: idempotent — skips when user already exists ───────────────────────
+  // ── AC-5: idempotent — does not insert duplicate records ───────────────────
 
-  it("AC-5: re-running does not duplicate user or account records (idempotent)", async () => {
+  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[] = [
@@ -330,25 +336,96 @@ describe("seedUatCredentials — credential provisioning logic", () => {
       },
     ];
 
-    // First call — nothing inserted (user + account pre-exist)
     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),
+      },
+    ];
 
-    // Second call — still nothing inserted
     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 ────────────────────────────────

apps/api/src/db/seed.ts

@@ -594,7 +594,15 @@ async function seedKnownUsers() {
       .limit(1);
 
     if (existingAccount) {
-      console.log(`✓ Credential account for '${acct.email}' already exists — skipping`);
+      // Re-hash and update the password so that re-seeding rotates credentials
+      // when the env var changes (e.g. after a password rotation).  Previously
+      // this branch skipped entirely, freezing the hash at first-seed.
+      const { hashPassword } = await import("better-auth/crypto");
+      const passwordHash = await hashPassword(password);
+      await db.update(schema.account)
+        .set({ password: passwordHash })
+        .where(eq(schema.account.id, existingAccount.id));
+      console.log(`✓ Updated credential account password for '${acct.email}'`);
     } else {
       // Use Better-Auth's own hashPassword to guarantee parameter/encoding match.
       // better-auth/crypto uses: N=16384, r=16, p=1, dkLen=64, salt as 16-byte random

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/meta/_journal.json

@@ -246,6 +246,27 @@
       "when": 1751140800000,
       "tag": "0034_extend_pet_profile_columns",
       "breakpoints": true
+    },
+    {
+      "idx": 36,
+      "version": "7",
+      "when": 1751480000000,
+      "tag": "0036_add_missing_coat_type_values",
+      "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "7",
+      "when": 1751500000000,
+      "tag": "0037_add_extra_large_to_pet_size_category",
+      "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "7",
+      "when": 1780000000000,
+      "tag": "0038_register_extra_large_pet_size_category",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/seed.ts

@@ -609,8 +609,45 @@ async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
       .from(schema.pets)
       .where(eq(schema.pets.id, pet.id))
       .limit(1);
+
     if (existing) {
-      console.log(`✓ UAT Pet '${existing.name}' already exists — skipping`);
+      // Upsert so extended fields are always populated on re-runs
+      await db.insert(schema.pets)
+        .values({
+          id: pet.id,
+          clientId: uatCustomerClientId,
+          name: pet.name,
+          species: pet.species,
+          breed: pet.breed,
+          weightKg: pet.weight,
+          dateOfBirth: new Date(`${pet.dob}T00:00:00Z`),
+          image: pet.image,
+          temperamentScore: randInt(1, 5),
+          temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
+          medicalAlerts: [],
+          preferredCuts: pickN(preferredCutPool, randInt(1, 2)),
+          coatType: pick(coatTypePool),
+          petSizeCategory: pick(petSizeCategoryPool),
+        })
+        .onConflictDoUpdate({
+          target: schema.pets.id,
+          set: {
+            clientId: uatCustomerClientId,
+            name: pet.name,
+            species: pet.species,
+            breed: pet.breed,
+            weightKg: pet.weight,
+            dateOfBirth: new Date(`${pet.dob}T00:00:00Z`),
+            image: pet.image,
+            temperamentScore: randInt(1, 5),
+            temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
+            medicalAlerts: [],
+            preferredCuts: pickN(preferredCutPool, randInt(1, 2)),
+            coatType: pick(coatTypePool),
+            petSizeCategory: pick(petSizeCategoryPool),
+          },
+        });
+      console.log(`✓ Upserted UAT pet '${pet.name}' with extended fields`);
     } else {
       await db.insert(schema.pets).values({
         id: pet.id,
@@ -621,8 +658,14 @@ async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
         weightKg: pet.weight,
         dateOfBirth: new Date(`${pet.dob}T00:00:00Z`),
         image: pet.image,
+        temperamentScore: randInt(1, 5),
+        temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
+        medicalAlerts: [],
+        preferredCuts: pickN(preferredCutPool, randInt(1, 2)),
+        coatType: pick(coatTypePool),
+        petSizeCategory: pick(petSizeCategoryPool),
       });
-      console.log(`✓ Created UAT pet '${pet.name}'`);
+      console.log(`✓ Created UAT pet '${pet.name}' with extended fields`);
     }
   }
 }
@@ -966,14 +1009,7 @@ async function seed() {
           temperamentScore: randInt(1, 5),
           temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
           medicalAlerts: (() => {
-            // Deterministic alerts for UAT AC pets
-            if (uc.petName === "TestCooper") {
-              return pickN(medicalAlertPool.filter((a) => a.type === "behavioral"), 1).map((a) => ({ ...a, id: uuid() }));
-            }
-            if (uc.petName === "TestRocky") {
-              return pickN(medicalAlertPool.filter((a) => a.type === "skin"), 1).map((a) => ({ ...a, id: uuid() }));
-            }
-            // Other UAT pets: random
+            // ~30% of random-pool pets have alerts — lands squarely in the 25–35% AC band
             if (rand() < 0.3) {
               const count = rand() < 0.7 ? 1 : 2;
               return pickN(medicalAlertPool, count).map((a) => ({ ...a, id: uuid() }));
@@ -1070,14 +1106,16 @@ async function seed() {
         temperamentScore: randInt(1, 5),
         temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
         medicalAlerts: (() => {
-          // Deterministic alerts for UAT AC pets
+          // TestCooper always has a behavioral alert; TestRocky always has a skin alert.
+          // All other UAT test pets follow the 30% random distribution.
+          // Deterministic alerts on 2 of 507 pets (~0.4%) do not meaningfully shift
+          // the overall distribution from the 25-35% target band.
           if (uc.petName === "TestCooper") {
             return pickN(medicalAlertPool.filter((a) => a.type === "behavioral"), 1).map((a) => ({ ...a, id: uuid() }));
           }
           if (uc.petName === "TestRocky") {
             return pickN(medicalAlertPool.filter((a) => a.type === "skin"), 1).map((a) => ({ ...a, id: uuid() }));
           }
-          // Other UAT pets: random
           if (rand() < 0.3) {
             const count = rand() < 0.7 ? 1 : 2;
             return pickN(medicalAlertPool, count).map((a) => ({ ...a, id: uuid() }));
@@ -1101,14 +1139,16 @@ async function seed() {
           temperamentScore: randInt(1, 5),
           temperamentFlags: pickN(temperamentFlagPool, randInt(1, 3)),
           medicalAlerts: (() => {
-            // Deterministic alerts for UAT AC pets
+            // TestCooper always has a behavioral alert; TestRocky always has a skin alert.
+            // All other UAT test pets follow the 30% random distribution.
+            // Deterministic alerts on 2 of 507 pets (~0.4%) do not meaningfully shift
+            // the overall distribution from the 25-35% target band.
             if (uc.petName === "TestCooper") {
               return pickN(medicalAlertPool.filter((a) => a.type === "behavioral"), 1).map((a) => ({ ...a, id: uuid() }));
             }
             if (uc.petName === "TestRocky") {
               return pickN(medicalAlertPool.filter((a) => a.type === "skin"), 1).map((a) => ({ ...a, id: uuid() }));
             }
-            // Other UAT pets: random
             if (rand() < 0.3) {
               const count = rand() < 0.7 ? 1 : 2;
               return pickN(medicalAlertPool, count).map((a) => ({ ...a, id: uuid() }));