docs: add Shedward Scissorhands UAT agent instructions (GRO-1502)

Mandates groombook-playwright MCP for all browser interaction during UAT.
Documents available MCP tools, execution workflow, and environment URLs.

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

.github/workflows/ci.yml

@@ -53,41 +53,6 @@ jobs:
       - name: Run tests
         run: pnpm test
 
-  e2e:
-    name: E2E Tests
-    runs-on: ubuntu-latest
-    needs: [lint-typecheck, test]
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: '9.15.4'
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Install Playwright browsers
-        run: pnpm --filter @groombook/e2e exec playwright install --with-deps chromium
-
-      - name: Start Docker Compose stack
-        run: docker compose up -d --wait
-        timeout-minutes: 5
-
-      - name: Run E2E tests
-        run: pnpm --filter @groombook/e2e test
-        env:
-          PLAYWRIGHT_BASE_URL: http://host.docker.internal:8080
-
-      - name: Stop Docker Compose stack
-        if: always()
-        run: docker compose down
-
   build:
     name: Build
     runs-on: ubuntu-latest
@@ -115,7 +80,7 @@ jobs:
   docker:
     name: Build & Push Docker Images
     runs-on: ubuntu-latest
-    needs: [build, e2e]
+    needs: [build]
     outputs:
       tag: ${{ steps.version.outputs.tag }}
     steps:

SHEDWARD_INSTRUCTIONS.md

@@ -0,0 +1,50 @@
+# Shedward Scissorhands — UAT Agent Instructions
+
+You are the GroomBook User Acceptance Tester. Your sole job is to execute UAT playbooks against deployed environments and report results.
+
+## Mandatory Tooling
+
+You MUST use the **groombook-playwright MCP server** (`mcp__playwright-groombook__*` tools) for ALL browser interaction. Do not:
+
+- Run scripted Playwright suites (`npx playwright test`, `pnpm test:e2e`, etc.)
+- Use manual browser commands or shell-based browser automation
+- Open browsers outside the MCP server
+
+Every page navigation, click, form fill, and verification MUST go through MCP tools.
+
+## Available MCP Tools
+
+| Tool | When to use |
+|------|-------------|
+| `browser_navigate` | Open a URL |
+| `browser_snapshot` | Read page state (preferred over screenshot for assertions) |
+| `browser_take_screenshot` | Capture visual evidence |
+| `browser_click` | Click an element (use ref from snapshot) |
+| `browser_fill_form` | Fill form fields |
+| `browser_type` | Type text into focused element |
+| `browser_press_key` | Press keyboard keys |
+| `browser_select_option` | Select dropdown options |
+| `browser_hover` | Hover over elements |
+| `browser_wait_for` | Wait for elements or navigation |
+| `browser_console_messages` | Check for JS errors |
+| `browser_network_requests` | Inspect API calls |
+| `browser_evaluate` | Run JS in page context |
+| `browser_resize` | Test responsive layouts |
+| `browser_close` | Close browser session |
+
+## Execution Workflow
+
+1. Read the `UAT_PLAYBOOK.md` in the repo being tested.
+2. For each test case, translate the human-readable steps into MCP tool calls.
+3. Capture evidence: use `browser_snapshot` for assertions, `browser_take_screenshot` for visual proof.
+4. Report pass/fail per test case with evidence.
+5. If a test fails, document: severity, steps to reproduce, actual vs expected, and attach screenshots.
+
+## Environments
+
+| Environment | URL | Auth |
+|-------------|-----|------|
+| Dev | `https://dev.groombook.dev` | Dev login selector (no OIDC) |
+| UAT | `https://uat.groombook.dev` | Authentik OIDC at `https://auth.farh.net` |
+| Production | `https://demo.groombook.dev` | Authentik OIDC |
+| Site | `https://groombook.farh.net` | No auth required |

UAT_PLAYBOOK.md

@@ -4,7 +4,49 @@
 
 GroomBook is an open-source, self-hostable pet grooming business management & CRM platform. The monorepo contains the Hono API (`apps/api`), React PWA web app (`apps/web`), E2E tests (`apps/e2e`), and shared packages (`packages/db`, `packages/types`). Tech stack: Hono + React 19 + Vite + PostgreSQL + Drizzle ORM + Authentik OIDC.
 
-## 2. Environments
+## 2. Execution Method
+
+All UAT is executed by **Shedward Scissorhands** via the **groombook-playwright MCP server**. No manual browser checks or scripted Playwright suites are used for UAT.
+
+### MCP Tools
+
+Shedward uses the `mcp__playwright-groombook__*` tool family:
+
+| Tool | Purpose |
+|------|---------|
+| `browser_navigate` | Navigate to a URL |
+| `browser_snapshot` | Capture accessibility snapshot (preferred over screenshot) |
+| `browser_take_screenshot` | Capture visual screenshot when needed |
+| `browser_click` | Click an element by ref or selector |
+| `browser_fill_form` | Fill form fields |
+| `browser_type` | Type text into focused element |
+| `browser_press_key` | Press keyboard keys (Enter, Tab, etc.) |
+| `browser_select_option` | Select dropdown options |
+| `browser_hover` | Hover over elements |
+| `browser_wait_for` | Wait for elements or conditions |
+| `browser_console_messages` | Check console for errors |
+| `browser_network_requests` | Inspect network traffic |
+| `browser_evaluate` | Run JavaScript in page context |
+| `browser_tabs` | Manage browser tabs |
+| `browser_close` | Close browser |
+
+### How Test Cases Map to MCP Calls
+
+Each test case in Section 4 describes steps like "Navigate to X" or "Click Y". Shedward translates these to MCP tool calls:
+
+- **"Navigate to [URL]"** → `browser_navigate` with the environment URL
+- **"Click [element]"** → `browser_snapshot` to find the element ref, then `browser_click`
+- **"Fill in [field]"** → `browser_fill_form` or `browser_click` + `browser_type`
+- **"Verify [state]"** → `browser_snapshot` and inspect the accessibility tree
+- **"Check for errors"** → `browser_console_messages` + `browser_snapshot`
+
+Shedward reads this playbook, executes each test case via MCP tools, captures evidence (snapshots/screenshots), and reports pass/fail per test case.
+
+### Legacy CI Tests
+
+The scripted Playwright suites in `apps/e2e/` and `apps/web/e2e/` are retained for CI regression testing only. They are **not** the primary UAT mechanism. UAT is exclusively MCP-driven by Shedward.
+
+## 3. Environments
 
 | Environment | URL | Notes |
 |-------------|-----|-------|
@@ -14,7 +56,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
 
 **Local Development:** Run `docker compose up --build` at repository root. Web app available at `localhost:8080`, API at `localhost:3000`.
 
-## 3. Pre-conditions
+## 4. Pre-conditions
 
 - UAT environment is accessible at `https://uat.groombook.dev`
 - Test accounts are seeded with the following personas:
@@ -29,7 +71,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
 - Stripe test keys are configured for payment flow testing
 - Email/SMS providers (Telnyx, etc.) are configured for notification testing
 
-## 4. Test Cases
+## 5. Test Cases
 
 ### 4.1 Authentication
 
@@ -235,7 +277,24 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
 | TC-APP-4.20.5 | Unread indicator | 1. Client sends a new message | Thread marked unread until staff views it |
 | TC-APP-4.20.6 | Cross-tenant isolation | 1. Staff from Business A attempts to read Business B conversations | 403 or empty response returned |
 
-## 5. Pass/Fail Criteria
+
+### 4.21 SMS Consent (STOP/HELP Keyword Handler)
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-APP-4.21.1 | STOP → unsubscribe + auto-reply | 1. Send `STOP` (case-insensitive, with whitespace) from a subscribed client's phone number | Client is opted out (`smsOptIn=false`, `smsOptOutDate` set), event is logged, user receives auto-reply: "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe." |
+| TC-APP-4.21.2 | START → resubscribe + auto-reply | 1. Send `START` (case-insensitive) from an opted-out client's phone number | Client is opted back in (`smsOptIn=true`, `smsConsentDate` updated, `smsOptOutDate` cleared), event is logged, user receives auto-reply: "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply." |
+| TC-APP-4.21.3 | HELP → no opt-in change + default reply | 1. Send `HELP` (case-insensitive) from any client's phone number | No change to opt-in state, no database update, event is logged, user receives auto-reply: "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly." |
+| TC-APP-4.21.4 | STOPALL / UNSUBSCRIBE / CANCEL / END / QUIT → opt-out | 1. Send each alias from a subscribed client's phone | Same behaviour as STOP: opt-out applied, correct reply sent |
+| TC-APP-4.21.5 | UNSTOP / YES / SUBSCRIBE → opt-in | 1. Send each alias from an opted-out client's phone | Same behaviour as START: opt-in applied, correct reply sent |
+| TC-APP-4.21.6 | INFO → help reply | 1. Send `INFO` from any client's phone | Same behaviour as HELP: no state change, help reply returned |
+| TC-APP-4.21.7 | Double STOP (idempotency) | 1. Send `STOP` from an already-opted-out client | Event is logged, no update call made, idempotent — no duplicate update |
+| TC-APP-4.21.8 | Double START (idempotency) | 1. Send `START` from an already-subscribed client | Event is logged, no update call made, idempotent — no duplicate update |
+| TC-APP-4.21.9 | Case insensitivity | 1. Send `stop`, `Stop`, `sToP`, ` stop ` from subscribed client | All variants are detected and handled as opt-out |
+| TC-APP-4.21.10 | Whitespace trimming | 1. Send `  START  ` or `\tSTOP\n` | Keywords are trimmed before matching |
+| TC-APP-4.21.11 | Non-keyword messages ignored | 1. Send `STOP IT`, `help me`, `hello` | Returns null from `detectKeyword`, no consent event inserted, no reply sent |
+| TC-APP-4.21.12 | Consent event audit log | 1. After any keyword, query `messageConsentEvents` table | Record exists with correct `clientId`, `businessId`, `kind`, and `source: "sms_keyword"` |
+## 6. Pass/Fail Criteria
 
 **Pass:** All test cases execute without errors. Expected results match actual results. No regressions are observed. All functionality works as documented.
 
@@ -248,7 +307,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
 
 **Regressions:** If a previously working feature fails during this UAT run, it is considered a regression and must be addressed before the release can proceed.
 
-## 6. Update Policy
+## 7. Update Policy
 
 **Any PR that changes user-facing behaviour MUST update this file.**
 
@@ -258,4 +317,4 @@ When modifying features that affect:
 - Configuration (settings, integrations)
 - Data visibility (reports, search, filtering)
 
-The corresponding test case(s) in Section 4 must be updated to reflect the new behaviour. The PR description must reference which playbook section was updated (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group scheduling feature").
+The corresponding test case(s) in Section 5 must be updated to reflect the new behaviour. The PR description must reference which playbook section was updated (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group scheduling feature").

apps/api/src/lib/cascade.ts

@@ -1,4 +1,4 @@
-import { eq, and, gt, gte, lt, ne, or, asc } from "@groombook/db";
+import { eq, and, gt, or, asc } from "@groombook/db";
 import { appointments, clients, pets, services, staff, type Db } from "@groombook/db";
 import { resolveBufferMinutes } from "./buffer.js";
 import { sendEmail, buildRescheduleNotificationEmail } from "../services/email.js";
@@ -53,12 +53,12 @@ export async function detectAndCascadeOverrun({
   db,
   overrunningAppointmentId,
   newEndTime,
-  originalEndTime,
+  _originalEndTime,
 }: {
   db: Db;
   overrunningAppointmentId: string;
   newEndTime: Date;
-  originalEndTime: Date;
+  _originalEndTime: Date;
 }): Promise<CascadeResult> {
   const result: CascadeResult = { shifted: [], flaggedForReview: [] };
 
@@ -178,16 +178,16 @@ export async function detectAndCascadeOverrun({
 export function isOverrun({
   originalEndTime,
   newEndTime,
-  originalStartTime,
-  newStartTime,
+  _originalStartTime,
+  _newStartTime,
   status,
   currentTime,
   bufferMinutes,
 }: {
   originalEndTime: Date;
   newEndTime: Date;
-  originalStartTime: Date;
-  newStartTime?: Date;
+  _originalStartTime: Date;
+  _newStartTime?: Date;
   status: string;
   currentTime: Date;
   bufferMinutes: number;

apps/api/src/routes/appointments.ts

@@ -700,7 +700,7 @@ appointmentsRouter.patch(
         isOverrun({
           originalEndTime,
           newEndTime: new Date(updateFields.endTime),
-          originalStartTime: row.startTime,
+          _originalStartTime: row.startTime,
           status: row.status,
           currentTime: new Date(),
           bufferMinutes: row.bufferMinutes ?? 0,
@@ -710,7 +710,7 @@ appointmentsRouter.patch(
           db,
           overrunningAppointmentId: id,
           newEndTime: new Date(updateFields.endTime),
-          originalEndTime,
+          _originalEndTime: originalEndTime,
         });
         return c.json({ ...row, cascade: cascadeResult });
       }

apps/api/src/routes/book.ts

@@ -44,7 +44,6 @@ bookRouter.get("/availability", async (c) => {
   const serviceId = c.req.query("serviceId");
   const dateStr = c.req.query("date");
   const petSizeCategory = c.req.query("petSizeCategory") ?? undefined;
-  const petCoatType = c.req.query("petCoatType") ?? undefined;
 
   if (!serviceId || !dateStr) {
     return c.json({ error: "serviceId and date are required" }, 400);
@@ -61,7 +60,7 @@ bookRouter.get("/availability", async (c) => {
   if (!service) return c.json({ error: "Service not found" }, 404);
 
   // Buffer-aware duration: extra time for large/x-large or complex coats
-  const extraBuffer = (petSizeCategory === "large" || petSizeCategory === "x-large")
+  const extraBuffer = (petSizeCategory === "large" || petSizeCategory === "xlarge")
     ? (service.defaultBufferMinutes ?? 0)
     : 0;
   const durationMinutes = service.durationMinutes + extraBuffer;
@@ -121,7 +120,7 @@ const bookingSchema = z.object({
   petSpecies: z.string().min(1).max(100),
   petBreed: z.string().max(100).optional(),
   petSizeCategory: z
-    .enum(["small", "medium", "large", "x-large"])
+    .enum(["small", "medium", "large", "xlarge"])
     .optional(),
   petCoatType: z
     .enum(["smooth", "double", "curly", "wire", "long", "hairless"])
@@ -213,7 +212,7 @@ bookRouter.post(
     if (!pet) return c.json({ error: "Failed to create pet" }, 500);
 
     // Buffer-aware end time: large/x-large pets add service bufferMinutes
-    if (body.petSizeCategory === "large" || body.petSizeCategory === "x-large") {
+    if (body.petSizeCategory === "large" || body.petSizeCategory === "xlarge") {
       end = new Date(start.getTime() + (service.durationMinutes + (service.defaultBufferMinutes ?? 0)) * 60_000);
     }
 

apps/api/src/services/messaging/__tests__/consent.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { detectKeyword } from "../consent.js";
+
+const mockDb = {
+  insert: vi.fn(),
+  update: vi.fn(),
+  select: vi.fn(),
+};
+
+vi.mock("@groombook/db", () => ({
+  getDb: () => mockDb,
+  clients: {},
+  messageConsentEvents: {},
+  businessSettings: {},
+  eq: vi.fn(),
+}));
+
+const { handleConsentKeyword } = await import("../consent.js");
+
+describe("detectKeyword", () => {
+  it.each([
+    ["STOP", "opt_out"],
+    ["STOPALL", "opt_out"],
+    ["UNSUBSCRIBE", "opt_out"],
+    ["CANCEL", "opt_out"],
+    ["END", "opt_out"],
+    ["QUIT", "opt_out"],
+  ])("opt-out keyword %s → opt_out", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it.each([
+    ["START", "opt_in"],
+    ["UNSTOP", "opt_in"],
+    ["YES", "opt_in"],
+    ["SUBSCRIBE", "opt_in"],
+  ])("opt-in keyword %s → opt_in", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it.each([
+    ["HELP", "help"],
+    ["INFO", "help"],
+  ])("help keyword %s → help", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it("is case insensitive", () => {
+    expect(detectKeyword("stop")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("Stop")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("sToP")).toEqual({ kind: "opt_out" });
+  });
+
+  it("trims whitespace", () => {
+    expect(detectKeyword("  STOP  ")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("\tSTART\n")).toEqual({ kind: "opt_in" });
+  });
+
+  it("returns null for non-keyword messages", () => {
+    expect(detectKeyword("hello")).toBeNull();
+    expect(detectKeyword("STOP IT")).toBeNull();
+    expect(detectKeyword("help me")).toBeNull();
+  });
+});
+
+describe("handleConsentKeyword", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockResolvedValue([{ id: "event-1" }]),
+    } as any);
+    mockDb.update.mockReturnValue({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockResolvedValue([]),
+      }),
+    } as any);
+  });
+
+  const baseOpts = {
+    clientId: "client-1",
+    businessId: "biz-1",
+    db: mockDb as unknown as ReturnType<typeof import("@groombook/db").getDb>,
+  };
+
+  describe("opt_out", () => {
+    it("inserts consent event with sms_keyword source", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.insert).toHaveBeenCalledOnce();
+    });
+
+    it("sets smsOptIn=false and smsOptOutDate when currently opted in", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("is idempotent — second opt-out logs event but skips client update", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+    });
+
+    it("returns unsubscribe reply text", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+      expect(result.replyText).toBe(
+        "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe."
+      );
+    });
+  });
+
+  describe("opt_in", () => {
+    it("sets smsOptIn=true and smsConsentDate when currently opted out", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false, smsConsentDate: null }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("clears smsOptOutDate on opt-in after opt-out", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("is idempotent — second opt-in skips client update", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+    });
+
+    it("returns resubscribe reply text", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+      expect(result.replyText).toBe(
+        "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply."
+      );
+    });
+  });
+
+  describe("help", () => {
+    it("returns default help reply without querying businessSettings", async () => {
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "help" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+      expect(mockDb.select).not.toHaveBeenCalled();
+      expect(result.replyText).toBe(
+        "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly."
+      );
+    });
+  });
+});

apps/api/src/services/messaging/consent.ts

@@ -0,0 +1,77 @@
+import { clients, messageConsentEvents, eq } from "@groombook/db";
+import type { Db } from "@groombook/db";
+
+export type KeywordKind = "opt_in" | "opt_out" | "help";
+
+const OPT_OUT_KEYWORDS = new Set(["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"]);
+const OPT_IN_KEYWORDS = new Set(["START", "UNSTOP", "YES", "SUBSCRIBE"]);
+const HELP_KEYWORDS = new Set(["HELP", "INFO"]);
+
+export function detectKeyword(body: string): { kind: KeywordKind } | null {
+  const normalized = body.trim().toUpperCase();
+  if (OPT_OUT_KEYWORDS.has(normalized)) return { kind: "opt_out" };
+  if (OPT_IN_KEYWORDS.has(normalized)) return { kind: "opt_in" };
+  if (HELP_KEYWORDS.has(normalized)) return { kind: "help" };
+  return null;
+}
+
+export async function handleConsentKeyword(opts: {
+  clientId: string;
+  businessId: string;
+  kind: KeywordKind;
+  db: Db;
+}): Promise<{ replyText: string }> {
+  const { clientId, businessId, kind, db: database } = opts;
+
+  await database.insert(messageConsentEvents).values({
+    clientId,
+    businessId,
+    kind,
+    source: "sms_keyword",
+  });
+
+  if (kind === "opt_out") {
+    const [existing] = await database
+      .select({ smsOptIn: clients.smsOptIn })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+
+    if (existing?.smsOptIn !== false) {
+      await database
+        .update(clients)
+        .set({ smsOptIn: false, smsOptOutDate: new Date() })
+        .where(eq(clients.id, clientId));
+    }
+
+    return {
+      replyText: "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe.",
+    };
+  }
+
+  if (kind === "opt_in") {
+    const [existing] = await database
+      .select({ smsOptIn: clients.smsOptIn, smsConsentDate: clients.smsConsentDate })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+
+    if (existing?.smsOptIn !== true) {
+      await database
+        .update(clients)
+        .set({ smsOptIn: true, smsConsentDate: new Date(), smsOptOutDate: null })
+        .where(eq(clients.id, clientId));
+    }
+
+    return {
+      replyText:
+        "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply.",
+    };
+  }
+
+  // kind === "help"
+  const replyText =
+    "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly.";
+
+  return { replyText };
+}

apps/api/src/services/messaging/inbound.ts

@@ -1,5 +1,7 @@
 import { getDb, conversations, messages, businessSettings, clients, eq, and } from "@groombook/db";
 import { v4 as uuidv4 } from "uuid";
+import { detectKeyword, handleConsentKeyword } from "./consent.js";
+import { sendMessage } from "./outbound.js";
 
 export interface TelnyxMessageReceivedPayload {
   data: {
@@ -152,7 +154,7 @@ export async function handleMessageReceived(payload: TelnyxMessageReceivedPayloa
     throw new Error(`No business owns messaging number: ${toPhone}`);
   }
 
-  const { id: conversationId } = await findOrCreateConversation(businessId, fromPhone, toPhone);
+  const { id: conversationId, clientId } = await findOrCreateConversation(businessId, fromPhone, toPhone);
 
   await getDb()
     .update(conversations)
@@ -167,6 +169,22 @@ export async function handleMessageReceived(payload: TelnyxMessageReceivedPayloa
     "received"
   );
 
+  const keyword = detectKeyword(message.body ?? "");
+  if (keyword) {
+    const { replyText } = await handleConsentKeyword({
+      clientId,
+      businessId,
+      kind: keyword.kind,
+      db: getDb(),
+    });
+    await sendMessage({
+      businessId,
+      clientId,
+      body: replyText,
+      sentByStaffId: undefined,
+    });
+  }
+
   return { conversationId, messageId };
 }
 

apps/e2e/playwright.config.ts

@@ -19,7 +19,7 @@ export default defineConfig({
   reporter: process.env.CI ? "github" : "list",
 
   use: {
-    baseURL: "http://localhost:8080",
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:8080",
     trace: "on-first-retry",
     screenshot: "only-on-failure",
     serviceWorkers: "block",

apps/web/src/pages/Book.tsx

@@ -515,7 +515,7 @@ export function BookPage() {
                     <option value="small">Small (under 15 lbs)</option>
                     <option value="medium">Medium (15–40 lbs)</option>
                     <option value="large">Large (40–80 lbs)</option>
-                    <option value="x-large">X-Large (over 80 lbs)</option>
+                    <option value="xlarge">X-Large (over 80 lbs)</option>
                   </select>
                 </div>
                 <div>
@@ -568,7 +568,7 @@ export function BookPage() {
               <div>
                 <div style={{ color: "#9ca3af", fontSize: 12, fontWeight: 600, textTransform: "uppercase" }}>Service</div>
                 <div style={{ fontWeight: 600 }}>{selectedService.name}</div>
-                <div style={{ color: "#6b7280" }}>{fmtPrice(selectedService.basePriceCents)} · {fmtDuration(selectedService.durationMinutes + ((form.petSizeCategory === "large" || form.petSizeCategory === "x-large") ? (selectedService.defaultBufferMinutes ?? 0) : 0))}</div>
+                <div style={{ color: "#6b7280" }}>{fmtPrice(selectedService.basePriceCents)} · {fmtDuration(selectedService.durationMinutes + ((form.petSizeCategory === "large" || form.petSizeCategory === "xlarge") ? (selectedService.defaultBufferMinutes ?? 0) : 0))}</div>
               </div>
               <div>
                 <div style={{ color: "#9ca3af", fontSize: 12, fontWeight: 600, textTransform: "uppercase" }}>Date & Time</div>

docker-compose.yml

@@ -43,6 +43,12 @@ services:
         condition: service_healthy
       migrate:
         condition: service_completed_successfully
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 10s
 
   web:
     build:
@@ -50,8 +56,17 @@ services:
       dockerfile: apps/web/Dockerfile
     ports:
       - "8080:80"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     depends_on:
-      - api
+      api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:80 || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 10s
 
 volumes:
   postgres_data:

packages/types/src/index.ts

@@ -32,6 +32,8 @@ export interface Pet {
   name: string;
   species: string;
   breed: string | null;
+  sizeCategory: string | null;
+  coatType: string | null;
   weightKg: number | null;
   dateOfBirth: string | null;
   healthAlerts: string | null;
@@ -115,6 +117,7 @@ export interface Appointment {
   cancelledAt: string | null;
   confirmationToken: string | null;
   customerNotes: string | null;
+  bufferMinutes: number;
   createdAt: string;
   updatedAt: string;
 }