fix(api): run Alembic migrations on startup to fix auth 500s

Co-Authored-By: Paperclip <noreply@paperclip.ing>
fix: change users.id and FK columns from uuid to text for Better-Auth (#88 )
2026-03-31 19:52:00 +00:00 · 2026-03-31 19:20:01 +00:00 · 2026-03-31 19:01:32 +00:00 · 2026-03-31 18:42:47 +00:00 · 2026-03-31 18:33:21 +00:00 · 2026-03-31 18:15:07 +00:00
76 changed files with 6421 additions and 1708 deletions
@@ -17,6 +17,9 @@ permissions:
 env:
  REGISTRY: ghcr.io
  IMAGE_NAME: cartsnitch/cartsnitch
+  AUTH_IMAGE_NAME: cartsnitch/auth
+  RECEIPTWITNESS_IMAGE_NAME: cartsnitch/receiptwitness
+  API_IMAGE_NAME: cartsnitch/api

 jobs:
  lint:
@@ -45,9 +48,61 @@ jobs:
      - name: Run tests
        run: npx vitest run

+  audit:
+    runs-on: runners-cartsnitch
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - name: Check for vulnerabilities
+        run: npm audit --audit-level=high
+
+  e2e:
+    runs-on: runners-cartsnitch
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npx playwright test
+
+  lighthouse:
+    runs-on: runners-cartsnitch
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Install Chromium for Lighthouse
+        run: |
+          npm install -g playwright
+          npx playwright install --with-deps chromium
+      - name: Start preview server
+        run: |
+          npm run preview &
+          npx wait-on http://localhost:4173/ --timeout 30000
+      - name: Run Lighthouse CI
+        run: |
+          CHROME_PATH=$(find /home/runner/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1)
+          npm install -g @lhci/cli
+          LHCI_CHROME_PATH="$CHROME_PATH" lhci autorun
+
  build-and-push:
    runs-on: runners-cartsnitch
-    needs: [lint, test]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test, e2e]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
    steps:
      - uses: actions/checkout@v4
        with:
@@ -70,6 +125,13 @@ jobs:
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          echo "CalVer tag: $VERSION"

+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
      - name: Log in to GHCR
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: docker/login-action@v3
@@ -104,3 +166,237 @@ jobs:
        run: |
          git tag "v${{ steps.calver.outputs.version }}"
          git push origin "v${{ steps.calver.outputs.version }}"
+
+  build-and-push-auth:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test, e2e]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then
+            VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
+            VERSION="${DATE_TAG}.2"
+          else
+            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
+            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (auth)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push auth Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./auth
+          file: ./auth/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-and-push-receiptwitness:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.RECEIPTWITNESS_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push receiptwitness image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./receiptwitness/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-and-push-api:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (API)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.API_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push API Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./api/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  deploy-dev:
+    runs-on: runners-cartsnitch
+    needs: [build-and-push, build-and-push-auth, build-and-push-receiptwitness, build-and-push-api]
+    if: always() && !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.CARTSNITCH_APP_ID }}
+          private-key: ${{ secrets.CARTSNITCH_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: infra
+
+      - name: Checkout infra repo
+        uses: actions/checkout@v4
+        with:
+          repository: cartsnitch/infra
+          token: ${{ steps.app-token.outputs.token }}
+          ref: main
+          path: infra
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+
+      - name: Install kustomize
+        uses: imranismail/setup-kustomize@v2
+
+      - name: Update frontend image tag
+        if: needs.build-and-push.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/cartsnitch:${{ needs.build-and-push.outputs.calver_tag }}
+
+      - name: Update auth image tag
+        if: needs.build-and-push-auth.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/auth:${{ needs.build-and-push-auth.outputs.calver_tag }}
+
+      - name: Update receiptwitness image tag
+        if: needs.build-and-push-receiptwitness.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness:${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}
+
+      - name: Update api image tag
+        if: needs.build-and-push-api.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/api:${{ needs.build-and-push-api.outputs.calver_tag }}
+
+      - name: Commit and push to infra
+        run: |
+          cd infra
+          git config user.name "cartsnitch-ci[bot]"
+          git config user.email "cartsnitch-ci[bot]@users.noreply.github.com"
+          git add apps/overlays/dev/kustomization.yaml
+          git commit -m "ci(dev): update cartsnitch, auth, receiptwitness, and api images"
+          git push origin main
@@ -11,6 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
+.env

 # Editor directories and files
 .vscode/*
@@ -12,6 +12,7 @@ CartSnitch is a self-hosted grocery price intelligence platform. This repo (`car
 | Directory | Service | Purpose |
 |-----------|---------|---------|
 | `/` (root) | Frontend | React PWA, mobile-first (this directory) |
+| `auth/` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) |
 | `api/` | API Gateway | Frontend-facing REST API |
 | `common/` | Common | Shared Python models, schemas, Alembic migrations |
 | `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
@@ -166,9 +167,13 @@ frontend/

 All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL configured via environment variable `VITE_API_URL`.

- JWT auth: store access token in memory (not localStorage), refresh token in httpOnly cookie if possible, or secure storage.
+- **Authentication via Better-Auth** (`auth/` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory.
+  - Auth service URL configured via `VITE_AUTH_URL` (default: `http://localhost:3001`)
+  - Frontend uses `better-auth/react` client for sign-in, sign-up, sign-out, and `useSession()` hook
+  - API gateway validates sessions by querying the shared `sessions` table in Postgres
+  - Both cookie-based and Bearer token auth are supported (cookies for web, Bearer for API clients)
 - TanStack Query handles caching, background refetching, and optimistic updates.
- API client should handle 401 responses by attempting token refresh before retrying.
+- API client sends `credentials: 'include'` on all requests to forward session cookies.

 ## Development Workflow

@@ -1,45 +1 @@
-# CartSnitch Monorepo
-
-CartSnitch is a self-hosted grocery price intelligence platform. This repo consolidates the core services and the flagship frontend PWA.
-
-## Services
-
-| Directory | Service | Purpose |
-|-----------|---------|---------|
-| `/` (root) | **Frontend** | React 18 PWA — mobile-first price intelligence UI |
-| `api/` | **API Gateway** | FastAPI — frontend-facing REST API |
-| `common/` | **Common** | Shared Python models, schemas, Alembic migrations |
-| `receiptwitness/` | **ReceiptWitness** | Purchase ingestion via retailer scrapers |
-
-## Quick Start
-
-### Frontend (root)
-
-```bash
-npm install
-npm run dev        # http://localhost:5173
-npm run build      # production build
-npm run test       # unit tests (Vitest)
-```
-
-### Python Services
-
-Each Python service uses [uv](https://github.com/astral-sh/uv) and has its own `pyproject.toml`:
-
-```bash
-cd api             # or common / receiptwitness
-uv sync
-uv run pytest
-```
-
-## Development Workflow
-
- **Never push directly to main.** Always open a PR from a feature branch.
- Branch naming: `feature/<description>` or `fix/<description>`
- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
-
-## Architecture
-
-For full details see [CLAUDE.md](./CLAUDE.md) or the per-service `CLAUDE.md` in each subdirectory.
-
-CartSnitch is a polyrepo-style monorepo: each service can be built and deployed independently, but sharing code between `common/` and the other Python services is done via local path dependencies in `pyproject.toml`.
+# CartSnitch
@@ -1,164 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/api
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - run: pip install ruff
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-
-  typecheck:
-    runs-on: runners-cartsnitch
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libpq-dev build-essential
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git"
-      - run: pip install -e ".[dev]" mypy
-      - name: Type check
-        run: mypy src/cartsnitch_api
-
-  test:
-    runs-on: runners-cartsnitch
-    services:
-      postgres:
-        image: postgres:15-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        env:
-          POSTGRES_USER: cartsnitch
-          POSTGRES_PASSWORD: cartsnitch_test
-          POSTGRES_DB: cartsnitch_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      CARTSNITCH_DATABASE_URL: postgresql+asyncpg://cartsnitch:cartsnitch_test@localhost:5432/cartsnitch_test
-      CARTSNITCH_REDIS_URL: redis://localhost:6379/0
-      CARTSNITCH_JWT_SECRET_KEY: test-secret-do-not-use-in-prod
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libpq-dev build-essential
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git"
-      - run: pip install -e ".[dev]"
-      - name: Run tests
-        run: pytest --tb=short -q
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"
@@ -1,3 +1,5 @@
+# Stage 1: Build dependencies
+# Build context is the repo root.  Paths below are relative to the root.
 FROM python:3.12-slim AS build

 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -6,16 +8,21 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

 WORKDIR /app
-COPY pyproject.toml ./
-COPY src/ ./src/
+COPY api/pyproject.toml ./
+COPY api/src/ ./src/
 RUN pip install --no-cache-dir --prefix=/install .

+# Stage 2: Production image
 FROM python:3.12-slim AS prod

+RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 RUN adduser --system --group --uid 1000 app
 COPY --from=build /install /usr/local
-COPY src/ ./src/
+COPY api/src/ ./src/
+COPY api/alembic.ini ./
+COPY api/alembic/ ./alembic/

 USER 1000
 EXPOSE 8000
@@ -23,4 +30,4 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=3s \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

-CMD ["uvicorn", "cartsnitch_api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["sh", "-c", "python -m alembic upgrade head && uvicorn cartsnitch_api.main:app --host 0.0.0.0 --port 8000"]
@@ -0,0 +1,101 @@
+"""Add Better-Auth tables and extend users table.
+
+Creates sessions, accounts, and verifications tables for Better-Auth.
+Adds email_verified and image columns to existing users table.
+Migrates password hashes from users.hashed_password to accounts.password.
+
+Revision ID: 002_better_auth_tables
+Revises: 001_encrypt_session_data
+Create Date: 2026-03-28
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "002_better_auth_tables"
+down_revision = "001_encrypt_session_data"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # --- Extend users table for Better-Auth compatibility ---
+    op.add_column("users", sa.Column("email_verified", sa.Boolean(), nullable=False, server_default="false"))
+    op.add_column("users", sa.Column("image", sa.Text(), nullable=True))
+
+    # --- Create sessions table ---
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("token", sa.Text(), nullable=False),
+        sa.Column("user_id", sa.Text(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("ip_address", sa.Text(), nullable=True),
+        sa.Column("user_agent", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_sessions_token", "sessions", ["token"], unique=True)
+    op.create_index("ix_sessions_user_id", "sessions", ["user_id"])
+
+    # --- Create accounts table ---
+    op.create_table(
+        "accounts",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("user_id", sa.Text(), nullable=False),
+        sa.Column("account_id", sa.Text(), nullable=False),
+        sa.Column("provider_id", sa.Text(), nullable=False),
+        sa.Column("access_token", sa.Text(), nullable=True),
+        sa.Column("refresh_token", sa.Text(), nullable=True),
+        sa.Column("access_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("refresh_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("scope", sa.Text(), nullable=True),
+        sa.Column("id_token", sa.Text(), nullable=True),
+        sa.Column("password", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_accounts_user_id", "accounts", ["user_id"])
+
+    # --- Create verifications table ---
+    op.create_table(
+        "verifications",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("identifier", sa.Text(), nullable=False),
+        sa.Column("value", sa.Text(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # --- Migrate existing password hashes to accounts table ---
+    # For each user with a hashed_password, create a 'credential' account row
+    conn = op.get_bind()
+    users = conn.execute(
+        text("SELECT id, hashed_password FROM users WHERE hashed_password IS NOT NULL")
+    ).fetchall()
+
+    for user_id, hashed_password in users:
+        user_id_str = str(user_id)
+        conn.execute(
+            text(
+                "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+                "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+            ),
+            {"user_id": user_id_str, "account_id": user_id_str, "password": hashed_password},
+        )
+
+
+def downgrade() -> None:
+    op.drop_table("verifications")
+    op.drop_table("accounts")
+    op.drop_index("ix_sessions_user_id", table_name="sessions")
+    op.drop_index("ix_sessions_token", table_name="sessions")
+    op.drop_table("sessions")
+    op.drop_column("users", "image")
+    op.drop_column("users", "email_verified")
@@ -0,0 +1,26 @@
+"""Make users.hashed_password nullable.
+
+Better-Auth inserts users without hashed_password (passwords live in the
+accounts table). This column is now purely optional.
+
+Revision ID: 003_make_users_hashed_password_nullable
+Revises: 002_better_auth_tables
+Create Date: 2026-03-30
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "003_make_users_hashed_password_nullable"
+down_revision = "002_better_auth_tables"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=True)
+
+
+def downgrade() -> None:
+    op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=False)
@@ -0,0 +1,122 @@
+"""Fix users.id UUID->text type mismatch for Better-Auth compatibility.
+
+Better-Auth generates nanoid-style text IDs (e.g. pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI),
+but the users table was using PostgreSQL uuid type. When Better-Auth tries to INSERT
+a new user, Postgres throws:
+  ERROR: invalid input syntax for type uuid: "pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI"
+
+The sessions, accounts, and verifications tables already use text IDs — only users,
+user_store_accounts.user_id, and purchases.user_id needed fixing.
+
+Revision ID: 004_fix_user_id_text
+Revises: 003_make_users_hashed_password_nullable
+Create Date: 2026-03-31
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "004_fix_user_id_text"
+down_revision = "003_make_users_hashed_password_nullable"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Step 1: Drop existing FK constraints
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Step 2: Alter users.id from uuid to text
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="id::text",
+    )
+
+    # Step 3: Alter user_store_accounts.user_id from uuid to text
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 4: Alter purchases.user_id from uuid to text
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 5: Re-add FK constraints
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+
+
+def downgrade() -> None:
+    # Drop FK constraints
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Revert users.id from text to uuid
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="id::uuid",
+    )
+
+    # Revert user_store_accounts.user_id from text to uuid
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Revert purchases.user_id from text to uuid
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Re-add FK constraints (PostgreSQL will auto-name them)
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
@@ -1,34 +1,88 @@
-"""FastAPI dependency injection for authentication."""
+"""FastAPI dependency injection for authentication.

+Validates Better-Auth session tokens from cookies or Bearer header.
+Sessions are verified by querying the shared sessions table directly.
+"""
+
+from datetime import UTC, datetime
 from uuid import UUID

-from fastapi import Depends, Header, HTTPException, status
+from fastapi import Cookie, Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession

-from cartsnitch_api.auth.jwt import decode_token
 from cartsnitch_api.config import settings
+from cartsnitch_api.database import get_db

-bearer_scheme = HTTPBearer()
+# Keep Bearer scheme as optional — Better-Auth primarily uses cookies,
+# but we support Bearer tokens for service-to-service or mobile clients.
+bearer_scheme = HTTPBearer(auto_error=False)
+
+# Better-Auth session cookie name
+SESSION_COOKIE_NAME = "better-auth.session_token"
+
+
+async def _validate_session_token(token: str, db: AsyncSession) -> UUID:
+    """Validate a Better-Auth session token against the sessions table.
+
+    Returns the user_id (as UUID) if the session is valid and not expired.
+    """
+    result = await db.execute(
+        text("SELECT user_id, expires_at FROM sessions WHERE token = :token"),
+        {"token": token},
+    )
+    row = result.first()
+
+    if not row:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid session token",
+        )
+
+    user_id, expires_at = row
+    if expires_at.tzinfo is None:
+        # Treat naive datetimes as UTC
+        expires_at = expires_at.replace(tzinfo=UTC)
+
+    if expires_at < datetime.now(UTC):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session expired",
+        )
+
+    return UUID(str(user_id))


 async def get_current_user(
-    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+    db: AsyncSession = Depends(get_db),
 ) -> UUID:
-    try:
-        payload = decode_token(credentials.credentials)
-    except ValueError:
+    """Extract and validate the session token from cookie or Authorization header.
+
+    Checks in order:
+    1. Better-Auth session cookie (primary — web clients)
+    2. Bearer token in Authorization header (fallback — API clients)
+    """
+    token: str | None = None
+
+    # 1. Check session cookie
+    cookie_token = request.cookies.get(SESSION_COOKIE_NAME)
+    if cookie_token:
+        token = cookie_token
+
+    # 2. Fall back to Bearer header
+    if not token and credentials:
+        token = credentials.credentials
+
+    if not token:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid or expired token",
-        ) from None
+            detail="Authentication required",
+        )

-    if payload.get("type") != "access":
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid token type",
-        ) from None
-
-    return UUID(payload["sub"])
+    return await _validate_session_token(token, db)


 async def verify_service_key(x_service_key: str = Header()) -> None:
@@ -1,4 +1,9 @@
-"""Auth routes: register, login, refresh, me, update, delete."""
+"""Auth routes: user profile management.
+
+Registration, login, refresh, and session management are handled by
+the Better-Auth service (auth/). This router provides user profile
+endpoints that query our own user data from the shared database.
+"""

 from uuid import UUID

@@ -8,10 +13,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from cartsnitch_api.auth.dependencies import get_current_user
 from cartsnitch_api.database import get_db
 from cartsnitch_api.schemas import (
-    LoginRequest,
-    RefreshRequest,
-    RegisterRequest,
-    TokenResponse,
    UpdateUserRequest,
    UserResponse,
 )
@@ -20,37 +21,6 @@ from cartsnitch_api.services.auth import AuthService
 router = APIRouter(prefix="/auth", tags=["auth"])


-@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
-async def register(body: RegisterRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.register(body.email, body.password, body.display_name)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) from e
-
-
-@router.post("/login", response_model=TokenResponse)
-async def login(body: LoginRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.login(body.email, body.password)
-    except ValueError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid email or password"
-        ) from None
-
-
-@router.post("/refresh", response_model=TokenResponse)
-async def refresh(body: RefreshRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.refresh(body.refresh_token)
-    except ValueError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token"
-        ) from None
-
-
@router.get("/me", response_model=UserResponse)
 async def get_me(
    user_id: UUID = Depends(get_current_user),
@@ -19,6 +19,8 @@ class Settings(BaseSettings):
    # Valid Fernet key for local dev — MUST be overridden in production
    fernet_key: str = "7reF42nmTwbdN21PBoubGp7h_FU8qSimstmlaMLoRK8="

+    auth_service_url: str = "http://auth:3001"
+
    cors_origins: list[str] = ["http://localhost:3000", "https://cartsnitch.com"]

    receiptwitness_url: str = "http://receiptwitness:8001"
@@ -32,7 +32,7 @@ class Purchase(UUIDPrimaryKeyMixin, TimestampMixin, Base):

    __tablename__ = "purchases"

-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
    store_location_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("store_locations.id"))
    receipt_id: Mapped[str] = mapped_column(String(200), nullable=False)
@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING

-from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy import DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship

 from cartsnitch_api.constants import AccountStatus
@@ -16,11 +16,12 @@ if TYPE_CHECKING:
    from cartsnitch_api.models.store import Store


-class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+class User(TimestampMixin, Base):
    """Application user."""

    __tablename__ = "users"

+    id: Mapped[str] = mapped_column(Text, primary_key=True)
    email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
    display_name: Mapped[str | None] = mapped_column(String(100))
@@ -36,7 +37,7 @@ class UserStoreAccount(UUIDPrimaryKeyMixin, TimestampMixin, Base):
    __tablename__ = "user_store_accounts"
    __table_args__ = (UniqueConstraint("user_id", "store_id", name="uq_user_store_account"),)

-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
    session_data: Mapped[dict | None] = mapped_column(EncryptedJSON)
    session_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
@@ -6,28 +6,8 @@ from uuid import UUID
 from pydantic import BaseModel, EmailStr, Field

 # ---------- Auth ----------
-
-
-class RegisterRequest(BaseModel):
-    email: EmailStr
-    password: str = Field(min_length=8, max_length=128)
-    display_name: str = Field(min_length=1, max_length=100)
-
-
-class LoginRequest(BaseModel):
-    email: EmailStr
-    password: str
-
-
-class RefreshRequest(BaseModel):
-    refresh_token: str
-
-
-class TokenResponse(BaseModel):
-    access_token: str
-    refresh_token: str
-    token_type: str = "bearer"
-    expires_in: int
+# Registration, login, and session management are handled by Better-Auth (auth/ service).
+# These schemas are for the profile management endpoints only.


 class UpdateUserRequest(BaseModel):
@@ -36,7 +16,7 @@ class UpdateUserRequest(BaseModel):


 class UserResponse(BaseModel):
-    id: UUID
+    id: str
    email: str
    display_name: str
    created_at: datetime
@@ -1,67 +1,20 @@
-"""Auth service — user registration, login, token management."""
+"""Auth service — user profile management.
+
+Registration, login, token management, and session handling are now
+handled by the Better-Auth service (auth/). This service provides
+user lookup and profile update operations for the API gateway.
+"""

 from uuid import UUID

 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession

-from cartsnitch_api.auth.jwt import create_access_token, create_refresh_token, decode_token
-from cartsnitch_api.auth.passwords import hash_password, verify_password
-from cartsnitch_api.config import settings
-

 class AuthService:
    def __init__(self, db: AsyncSession) -> None:
        self.db = db

-    async def register(self, email: str, password: str, display_name: str) -> dict:
-        from cartsnitch_api.models import User
-
-        existing = await self.db.execute(select(User).where(User.email == email))
-        if existing.scalar_one_or_none():
-            raise ValueError("Email already registered")
-
-        user = User(
-            email=email,
-            hashed_password=hash_password(password),
-            display_name=display_name,
-        )
-        self.db.add(user)
-        await self.db.commit()
-        await self.db.refresh(user)
-
-        return self._make_token_response(user.id)
-
-    async def login(self, email: str, password: str) -> dict:
-        from cartsnitch_api.models import User
-
-        result = await self.db.execute(select(User).where(User.email == email))
-        user = result.scalar_one_or_none()
-        if not user or not verify_password(password, user.hashed_password):
-            raise ValueError("Invalid email or password")
-
-        return self._make_token_response(user.id)
-
-    async def refresh(self, refresh_token: str) -> dict:
-        from cartsnitch_api.models import User
-
-        try:
-            payload = decode_token(refresh_token)
-        except ValueError:
-            raise ValueError("Invalid refresh token") from None
-
-        if payload.get("type") != "refresh":
-            raise ValueError("Invalid token type") from None
-
-        user_id = UUID(payload["sub"])
-
-        # Verify the user still exists before issuing new tokens
-        result = await self.db.execute(select(User).where(User.id == user_id))
-        if not result.scalar_one_or_none():
-            raise ValueError("User no longer exists")
-
-        return self._make_token_response(user_id)
-
    async def get_user(self, user_id: UUID) -> dict:
        from cartsnitch_api.models import User

@@ -115,11 +68,3 @@ class AuthService:

        await self.db.delete(user)
        await self.db.commit()
-
-    def _make_token_response(self, user_id: UUID) -> dict:
-        return {
-            "access_token": create_access_token(user_id),
-            "refresh_token": create_refresh_token(user_id),
-            "token_type": "bearer",
-            "expires_in": settings.jwt_access_token_expire_minutes * 60,
-        }
@@ -1,8 +1,16 @@
-"""Shared test fixtures with in-memory SQLite database."""
+"""Shared test fixtures with in-memory SQLite database.
+
+Session-based auth: tests create users and sessions directly in the DB,
+matching the Better-Auth session validation flow.
+"""
+
+import secrets
+import uuid
+from datetime import UTC, datetime, timedelta

 import pytest
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import create_engine, event
+from sqlalchemy import create_engine, event, text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import sessionmaker

@@ -51,6 +59,46 @@ async def db_engine():

    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
+        # Create Better-Auth tables (not managed by SQLAlchemy models)
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS sessions (
+                id TEXT PRIMARY KEY,
+                token TEXT NOT NULL UNIQUE,
+                user_id TEXT NOT NULL,
+                expires_at TIMESTAMP NOT NULL,
+                ip_address TEXT,
+                user_agent TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS accounts (
+                id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                account_id TEXT NOT NULL,
+                provider_id TEXT NOT NULL,
+                access_token TEXT,
+                refresh_token TEXT,
+                access_token_expires_at TIMESTAMP,
+                refresh_token_expires_at TIMESTAMP,
+                scope TEXT,
+                id_token TEXT,
+                password TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS verifications (
+                id TEXT PRIMARY KEY,
+                identifier TEXT NOT NULL,
+                value TEXT NOT NULL,
+                expires_at TIMESTAMP NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))

    yield engine

@@ -85,17 +133,55 @@ async def client(db_engine):
    app.dependency_overrides.clear()


+async def _create_test_user_and_session(client: AsyncClient, db_engine, **user_overrides) -> tuple[dict, str]:
+    """Create a test user and a valid session directly in the DB.
+
+    Returns (user_dict, session_token).
+    """
+    user_id = str(uuid.uuid4())
+    email = user_overrides.get("email", "test@example.com")
+    display_name = user_overrides.get("display_name", "Test User")
+    session_token = secrets.token_urlsafe(32)
+    session_id = str(uuid.uuid4())
+    now = datetime.now(UTC).isoformat()
+    expires = (datetime.now(UTC) + timedelta(days=7)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                "VALUES (:id, :email, :hashed_password, :display_name, :email_verified, :created_at, :updated_at)"
+            ),
+            {
+                "id": user_id,
+                "email": email,
+                "hashed_password": "not-used-with-better-auth",
+                "display_name": display_name,
+                "email_verified": False,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :user_id, :expires_at, :created_at, :updated_at)"
+            ),
+            {
+                "id": session_id,
+                "token": session_token,
+                "user_id": user_id,
+                "expires_at": expires,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+
+    return {"id": user_id, "email": email, "display_name": display_name}, session_token
+
+
@pytest.fixture
-async def auth_headers(client):
-    """Register a test user and return auth headers."""
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "test@example.com",
-            "password": "testpass123",
-            "display_name": "Test User",
-        },
-    )
-    assert resp.status_code == 201
-    token = resp.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
+async def auth_headers(client, db_engine):
+    """Create a test user with a valid session and return auth headers."""
+    _, session_token = await _create_test_user_and_session(client, db_engine)
+    return {"Cookie": f"better-auth.session_token={session_token}"}
@@ -1,146 +1,13 @@
-"""Integration tests for auth endpoints."""
+"""Integration tests for auth profile endpoints.
+
+Registration, login, and session management are handled by the Better-Auth
+service. These tests cover the profile endpoints (GET/PATCH/DELETE /auth/me)
+which validate sessions via the shared sessions table.
+"""

 import pytest


-@pytest.mark.asyncio
-async def test_register_success(client):
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "new@example.com",
-            "password": "securepass123",
-            "display_name": "New User",
-        },
-    )
-    assert resp.status_code == 201
-    data = resp.json()
-    assert "access_token" in data
-    assert "refresh_token" in data
-    assert data["token_type"] == "bearer"
-    assert data["expires_in"] == 900  # 15 min * 60
-
-
-@pytest.mark.asyncio
-async def test_register_duplicate_email(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "dupe@example.com",
-            "password": "securepass123",
-            "display_name": "User One",
-        },
-    )
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "dupe@example.com",
-            "password": "securepass456",
-            "display_name": "User Two",
-        },
-    )
-    assert resp.status_code == 409
-
-
-@pytest.mark.asyncio
-async def test_register_short_password(client):
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "short@example.com",
-            "password": "short",
-            "display_name": "Short Pass",
-        },
-    )
-    assert resp.status_code == 422
-
-
-@pytest.mark.asyncio
-async def test_login_success(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "login@example.com",
-            "password": "securepass123",
-            "display_name": "Login User",
-        },
-    )
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "login@example.com",
-            "password": "securepass123",
-        },
-    )
-    assert resp.status_code == 200
-    assert "access_token" in resp.json()
-
-
-@pytest.mark.asyncio
-async def test_login_wrong_password(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "wrong@example.com",
-            "password": "securepass123",
-            "display_name": "Wrong Pass",
-        },
-    )
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "wrong@example.com",
-            "password": "badpassword1",
-        },
-    )
-    assert resp.status_code == 401
-
-
-@pytest.mark.asyncio
-async def test_login_nonexistent_user(client):
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "ghost@example.com",
-            "password": "doesntmatter",
-        },
-    )
-    assert resp.status_code == 401
-
-
-@pytest.mark.asyncio
-async def test_refresh_token(client):
-    reg = await client.post(
-        "/auth/register",
-        json={
-            "email": "refresh@example.com",
-            "password": "securepass123",
-            "display_name": "Refresh User",
-        },
-    )
-    refresh_token = reg.json()["refresh_token"]
-
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": refresh_token,
-        },
-    )
-    assert resp.status_code == 200
-    assert "access_token" in resp.json()
-
-
-@pytest.mark.asyncio
-async def test_refresh_with_invalid_token(client):
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": "invalid.token.here",
-        },
-    )
-    assert resp.status_code == 401
-
-
@pytest.mark.asyncio
 async def test_get_me(client, auth_headers):
    resp = await client.get("/auth/me", headers=auth_headers)
@@ -155,7 +22,32 @@ async def test_get_me(client, auth_headers):
@pytest.mark.asyncio
 async def test_get_me_unauthorized(client):
    resp = await client.get("/auth/me")
-    assert resp.status_code in (401, 403)  # No auth header
+    assert resp.status_code in (401, 403)
+
+
+@pytest.mark.asyncio
+async def test_get_me_invalid_session(client):
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": "better-auth.session_token=invalid-token"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_me_with_bearer_token(client, db_engine):
+    """Session tokens can also be passed as Bearer tokens for API clients."""
+    from tests.conftest import _create_test_user_and_session
+
+    _, session_token = await _create_test_user_and_session(
+        client, db_engine, email="bearer@example.com", display_name="Bearer User"
+    )
+    resp = await client.get(
+        "/auth/me",
+        headers={"Authorization": f"Bearer {session_token}"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "bearer@example.com"


@pytest.mark.asyncio
@@ -163,9 +55,7 @@ async def test_update_me(client, auth_headers):
    resp = await client.patch(
        "/auth/me",
        headers=auth_headers,
-        json={
-            "display_name": "Updated Name",
-        },
+        json={"display_name": "Updated Name"},
    )
    assert resp.status_code == 200
    assert resp.json()["display_name"] == "Updated Name"
@@ -176,34 +66,58 @@ async def test_delete_me(client, auth_headers):
    resp = await client.delete("/auth/me", headers=auth_headers)
    assert resp.status_code == 204

-    # Verify user is gone (token still valid but user deleted)
+    # Session is still valid but user is gone
    resp = await client.get("/auth/me", headers=auth_headers)
    assert resp.status_code == 404


@pytest.mark.asyncio
-async def test_refresh_after_delete_fails(client):
-    """Refresh token for a deleted user must be rejected."""
-    reg = await client.post(
-        "/auth/register",
-        json={
-            "email": "ghost@example.com",
-            "password": "securepass123",
-            "display_name": "Ghost User",
-        },
-    )
-    tokens = reg.json()
-    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+async def test_expired_session_rejected(client, db_engine):
+    """Expired sessions must be rejected."""
+    import secrets
+    import uuid
+    from datetime import UTC, datetime, timedelta

-    # Delete the user
-    resp = await client.delete("/auth/me", headers=headers)
-    assert resp.status_code == 204
+    from sqlalchemy import text

-    # Refresh token should now fail
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": tokens["refresh_token"],
-        },
+    user_id = str(uuid.uuid4())
+    session_token = secrets.token_urlsafe(32)
+    now = datetime.now(UTC).isoformat()
+    expired = (datetime.now(UTC) - timedelta(hours=1)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                "VALUES (:id, :email, :hp, :dn, :ev, :ca, :ua)"
+            ),
+            {
+                "id": user_id,
+                "email": "expired@example.com",
+                "hp": "unused",
+                "dn": "Expired User",
+                "ev": False,
+                "ca": now,
+                "ua": now,
+            },
+        )
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :uid, :ea, :ca, :ua)"
+            ),
+            {
+                "id": str(uuid.uuid4()),
+                "token": session_token,
+                "uid": user_id,
+                "ea": expired,
+                "ca": now,
+                "ua": now,
+            },
+        )
+
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": f"better-auth.session_token={session_token}"},
    )
    assert resp.status_code == 401
@@ -10,9 +10,9 @@ from decimal import Decimal
 from uuid import UUID

 import pytest
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

-from cartsnitch_api.auth.jwt import decode_token
 from cartsnitch_api.models import (
    Coupon,
    NormalizedProduct,
@@ -126,10 +126,16 @@ async def seed_data(db_engine, auth_headers):
        session.add_all(prices)
        await session.flush()

-        # -- Purchases (need the user_id from the registered test user) --
-        token = auth_headers["Authorization"].split(" ")[1]
-        payload = decode_token(token)
-        user_id = UUID(payload["sub"])
+        # -- Get the user_id from the session token in auth_headers --
+        cookie_str = auth_headers.get("Cookie", "")
+        session_token = cookie_str.split("=", 1)[1] if "=" in cookie_str else ""
+
+        result = await session.execute(
+            text("SELECT user_id FROM sessions WHERE token = :token"),
+            {"token": session_token},
+        )
+        row = result.first()
+        user_id = UUID(row[0])

        purchase1 = Purchase(
            user_id=user_id,
@@ -1,132 +1,103 @@
-"""E2E: Auth and token validation flows."""
+"""E2E: Auth and session validation flows.

-import asyncio
+Registration and login are handled by the Better-Auth service.
+These tests validate session token handling at the API gateway level.
+"""

 import pytest

-
-@pytest.mark.asyncio
-class TestAuthRegistrationLogin:
-    """Full registration → login → token refresh → profile flow."""
-
-    async def test_full_auth_lifecycle(self, client, db_engine):
-        """Register → login → get profile → refresh → get profile again."""
-        # Register
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "lifecycle@example.com",
-                "password": "securepass123",
-                "display_name": "Lifecycle User",
-            },
-        )
-        assert reg.status_code == 201
-        tokens = reg.json()
-        assert "access_token" in tokens
-        assert "refresh_token" in tokens
-        assert tokens["token_type"] == "bearer"
-        assert tokens["expires_in"] > 0
-
-        headers = {"Authorization": f"Bearer {tokens['access_token']}"}
-
-        # Get profile with access token
-        me = await client.get("/auth/me", headers=headers)
-        assert me.status_code == 200
-        assert me.json()["email"] == "lifecycle@example.com"
-        assert me.json()["display_name"] == "Lifecycle User"
-
-        # Sleep 1s so the new token has a different exp than the registration token
-        await asyncio.sleep(1)
-
-        # Login with same credentials
-        login = await client.post(
-            "/auth/login",
-            json={"email": "lifecycle@example.com", "password": "securepass123"},
-        )
-        assert login.status_code == 200
-        login_tokens = login.json()
-        assert login_tokens["access_token"] != tokens["access_token"]
-
-        # Refresh token
-        refresh = await client.post(
-            "/auth/refresh",
-            json={"refresh_token": tokens["refresh_token"]},
-        )
-        assert refresh.status_code == 200
-        new_tokens = refresh.json()
-        assert new_tokens["access_token"] != tokens["access_token"]
-
-        # Use refreshed token to access profile
-        new_headers = {"Authorization": f"Bearer {new_tokens['access_token']}"}
-        me2 = await client.get("/auth/me", headers=new_headers)
-        assert me2.status_code == 200
-        assert me2.json()["email"] == "lifecycle@example.com"
+from tests.conftest import _create_test_user_and_session


@pytest.mark.asyncio
-class TestTokenValidation:
-    """Token edge cases and error responses."""
+class TestSessionValidation:
+    """Session edge cases and error responses."""

-    async def test_expired_token_rejected(self, client, db_engine):
-        """Manually craft an expired token and verify rejection."""
-        import uuid
-        from datetime import UTC, datetime, timedelta
-
-        from jose import jwt
-
-        from cartsnitch_api.config import settings
-
-        payload = {
-            "sub": str(uuid.uuid4()),
-            "exp": datetime.now(UTC) - timedelta(minutes=5),
-            "type": "access",
-        }
-        token = jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
-        resp = await client.get("/auth/me", headers={"Authorization": f"Bearer {token}"})
+    async def test_invalid_session_token_rejected(self, client, db_engine):
+        resp = await client.get(
+            "/auth/me",
+            headers={"Cookie": "better-auth.session_token=not-a-real-token"},
+        )
        assert resp.status_code == 401

-    async def test_invalid_token_rejected(self, client, db_engine):
-        resp = await client.get("/auth/me", headers={"Authorization": "Bearer not-a-real-token"})
-        assert resp.status_code == 401
-
-    async def test_missing_auth_header(self, client, db_engine):
+    async def test_missing_auth(self, client, db_engine):
        resp = await client.get("/auth/me")
        assert resp.status_code in (401, 403)

-    async def test_refresh_token_cannot_access_endpoints(self, client, db_engine):
-        """A refresh token should not work as an access token."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "refresh-test@example.com",
-                "password": "securepass123",
-                "display_name": "Refresh Test",
-            },
+    async def test_bearer_token_also_works(self, client, db_engine):
+        """Session tokens passed as Bearer tokens should also be accepted."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="bearer@e2e.com", display_name="Bearer E2E"
        )
-        refresh_token = reg.json()["refresh_token"]
-        resp = await client.get("/auth/me", headers={"Authorization": f"Bearer {refresh_token}"})
-        assert resp.status_code == 401
-
-    async def test_deleted_user_token_invalid(self, client, db_engine):
-        """After deleting an account, tokens should no longer work."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "delete-me@example.com",
-                "password": "securepass123",
-                "display_name": "Delete Me",
-            },
+        resp = await client.get(
+            "/auth/me",
+            headers={"Authorization": f"Bearer {session_token}"},
        )
-        tokens = reg.json()
-        headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+        assert resp.status_code == 200
+        assert resp.json()["email"] == "bearer@e2e.com"
+
+    async def test_deleted_user_session_returns_not_found(self, client, db_engine):
+        """After deleting a user, their session should result in 404 for profile."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="delete-me@e2e.com", display_name="Delete Me"
+        )
+        headers = {"Cookie": f"better-auth.session_token={session_token}"}

-        # Delete account
        delete_resp = await client.delete("/auth/me", headers=headers)
        assert delete_resp.status_code == 204

-        # Profile should fail
        me = await client.get("/auth/me", headers=headers)
-        assert me.status_code in (401, 404)
+        assert me.status_code == 404
+
+    async def test_expired_session_rejected(self, client, db_engine):
+        """Expired sessions must be rejected."""
+        import secrets
+        import uuid
+        from datetime import UTC, datetime, timedelta
+
+        from sqlalchemy import text
+
+        user_id = str(uuid.uuid4())
+        session_token = secrets.token_urlsafe(32)
+        now = datetime.now(UTC).isoformat()
+        expired = (datetime.now(UTC) - timedelta(hours=1)).isoformat()
+
+        async with db_engine.begin() as conn:
+            await conn.execute(
+                text(
+                    "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                    "VALUES (:id, :email, :hp, :dn, :ev, :ca, :ua)"
+                ),
+                {
+                    "id": user_id,
+                    "email": "expired@e2e.com",
+                    "hp": "unused",
+                    "dn": "Expired User",
+                    "ev": False,
+                    "ca": now,
+                    "ua": now,
+                },
+            )
+            await conn.execute(
+                text(
+                    "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                    "VALUES (:id, :token, :uid, :ea, :ca, :ua)"
+                ),
+                {
+                    "id": str(uuid.uuid4()),
+                    "token": session_token,
+                    "uid": user_id,
+                    "ea": expired,
+                    "ca": now,
+                    "ua": now,
+                },
+            )
+
+        resp = await client.get(
+            "/auth/me",
+            headers={"Cookie": f"better-auth.session_token={session_token}"},
+        )
+        assert resp.status_code == 401


@pytest.mark.asyncio
@@ -154,60 +125,38 @@ class TestAuthProtectedEndpoints:
 class TestCrossUserDataIsolation:
    """Verify that users cannot access other users' data."""

-    async def test_user_b_cannot_access_user_a_purchases(self, client, seed_data):
-        """Register a second user and verify they cannot see User A's purchases."""
-        # User A's purchase (from seed_data)
+    async def test_user_b_cannot_access_user_a_purchases(self, client, db_engine, seed_data):
+        """A second user cannot see User A's purchases."""
        purchase_id = str(seed_data["purchases"]["meijer_trip"].id)

-        # Register User B
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userb@example.com",
-                "password": "securepass123",
-                "display_name": "User B",
-            },
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userb@e2e.com", display_name="User B"
        )
-        assert reg.status_code == 201
-        user_b_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_b_headers = {"Cookie": f"better-auth.session_token={session_token}"}

-        # User B tries to access User A's specific purchase
        resp = await client.get(f"/purchases/{purchase_id}", headers=user_b_headers)
        assert resp.status_code in (403, 404), (
            "User B should not be able to access User A's purchase"
        )

-    async def test_user_b_purchase_list_is_empty(self, client, seed_data):
-        """A new user should see no purchases (not User A's purchases)."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userc@example.com",
-                "password": "securepass123",
-                "display_name": "User C",
-            },
+    async def test_user_b_purchase_list_is_empty(self, client, db_engine, seed_data):
+        """A new user should see no purchases."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userc@e2e.com", display_name="User C"
        )
-        assert reg.status_code == 201
-        user_c_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_c_headers = {"Cookie": f"better-auth.session_token={session_token}"}

        resp = await client.get("/purchases", headers=user_c_headers)
        assert resp.status_code == 200
        assert len(resp.json()) == 0, "New user should have no purchases"

-    async def test_user_b_stores_isolated(self, client, seed_data):
+    async def test_user_b_stores_isolated(self, client, db_engine, seed_data):
        """User B's connected stores should be independent from User A."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userd@example.com",
-                "password": "securepass123",
-                "display_name": "User D",
-            },
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userd@e2e.com", display_name="User D"
        )
-        assert reg.status_code == 201
-        user_d_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_d_headers = {"Cookie": f"better-auth.session_token={session_token}"}

-        # User D should have no connected stores
        resp = await client.get("/me/stores", headers=user_d_headers)
        assert resp.status_code == 200
        assert len(resp.json()) == 0, "New user should have no connected stores"
@@ -1,26 +1,25 @@
 """Integration tests for purchase endpoints."""

+import secrets
 import uuid
-from datetime import date
+from datetime import UTC, date, datetime, timedelta
 from decimal import Decimal

 import pytest
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

-from cartsnitch_api.auth.jwt import create_access_token
 from cartsnitch_api.models import Purchase, PurchaseItem, Store, User


@pytest.fixture
 async def purchase_data(db_engine):
-    """Seed a user, store, purchase, and items."""
+    """Seed a user, store, purchase, items, and a valid session."""
    factory = async_sessionmaker(db_engine, class_=AsyncSession, expire_on_commit=False)
    async with factory() as session:
-        from cartsnitch_api.auth.passwords import hash_password
-
        user = User(
            email="buyer@example.com",
-            hashed_password=hash_password("testpass123"),
+            hashed_password="not-used-with-better-auth",
            display_name="Buyer",
        )
        store = Store(name="Kroger", slug="kroger")
@@ -50,13 +49,33 @@ async def purchase_data(db_engine):
        session.add(item)
        await session.commit()

-        token = create_access_token(user.id)
-        return {
-            "user": user,
-            "store": store,
-            "purchase": purchase,
-            "headers": {"Authorization": f"Bearer {token}"},
-        }
+    # Create a session token directly in the sessions table
+    session_token = secrets.token_urlsafe(32)
+    now = datetime.now(UTC).isoformat()
+    expires = (datetime.now(UTC) + timedelta(days=7)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :user_id, :expires_at, :created_at, :updated_at)"
+            ),
+            {
+                "id": str(uuid.uuid4()),
+                "token": session_token,
+                "user_id": str(user.id),
+                "expires_at": expires,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+
+    return {
+        "user": user,
+        "store": store,
+        "purchase": purchase,
+        "headers": {"Cookie": f"better-auth.session_token={session_token}"},
+    }


@pytest.mark.asyncio
@@ -0,0 +1,11 @@
+# Required: Generate with `openssl rand -base64 32`
+BETTER_AUTH_SECRET=change-me-in-production-min-32-chars!!
+
+# Base URL of the auth service
+BETTER_AUTH_URL=http://localhost:3001
+
+# Shared PostgreSQL database
+DATABASE_URL=postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch
+
+# Port the auth service listens on
+PORT=3001
@@ -0,0 +1,17 @@
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src/ src/
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev
+COPY --from=builder /app/dist/ dist/
+USER 101
+EXPOSE 3001
+CMD ["node", "dist/index.js"]
@@ -0,0 +1,24 @@
+{
+  "name": "@cartsnitch/auth",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "generate": "npx @better-auth/cli generate"
+  },
+  "dependencies": {
+    "better-auth": "^1.2.0",
+    "pg": "^8.13.0",
+    "bcrypt": "^5.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "@types/bcrypt": "^5.0.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}
@@ -0,0 +1,99 @@
+import { betterAuth } from "better-auth";
+import bcrypt from "bcrypt";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const pool = new Pool({
+  connectionString:
+    process.env.DATABASE_URL ??
+    "postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+});
+
+const secret = process.env.BETTER_AUTH_SECRET;
+if (!secret) {
+  throw new Error("BETTER_AUTH_SECRET environment variable is required");
+}
+
+export const auth = betterAuth({
+  database: pool,
+  basePath: "/auth",
+  secret,
+  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3001",
+
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 8,
+    maxPasswordLength: 128,
+    password: {
+      hash: async (password: string) => {
+        return bcrypt.hash(password, 10);
+      },
+      verify: async (data: { hash: string; password: string }) => {
+        return bcrypt.compare(data.password, data.hash);
+      },
+    },
+  },
+
+  session: {
+    modelName: "sessions",
+    fields: {
+      userId: "user_id",
+      expiresAt: "expires_at",
+      ipAddress: "ip_address",
+      userAgent: "user_agent",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // refresh after 1 day
+    cookieCache: {
+      enabled: true,
+      maxAge: 5 * 60, // 5-minute cookie cache
+    },
+  },
+
+  user: {
+    modelName: "users",
+    fields: {
+      name: "display_name",
+      emailVerified: "email_verified",
+      image: "image",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  account: {
+    modelName: "accounts",
+    fields: {
+      userId: "user_id",
+      accountId: "account_id",
+      providerId: "provider_id",
+      accessToken: "access_token",
+      refreshToken: "refresh_token",
+      accessTokenExpiresAt: "access_token_expires_at",
+      refreshTokenExpiresAt: "refresh_token_expires_at",
+      idToken: "id_token",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  verification: {
+    modelName: "verifications",
+    fields: {
+      expiresAt: "expires_at",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  trustedOrigins: [
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "https://cartsnitch.com",
+    "https://cartsnitch.farh.net",
+    "https://cartsnitch.dev.farh.net",
+  ],
+});
@@ -0,0 +1,23 @@
+import { createServer } from "node:http";
+import { toNodeHandler } from "better-auth/node";
+import { auth } from "./auth.js";
+
+const port = parseInt(process.env.PORT ?? "3001", 10);
+
+const handler = toNodeHandler(auth);
+
+const server = createServer(async (req, res) => {
+  // Health check
+  if (req.url === "/health" && req.method === "GET") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok" }));
+    return;
+  }
+
+  // All /auth/* routes handled by Better-Auth
+  await handler(req, res);
+});
+
+server.listen(port, "0.0.0.0", () => {
+  console.log(`CartSnitch auth service listening on port ${port}`);
+});
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
@@ -0,0 +1,28 @@
+# CartSnitch Common
+
+Shared models, schemas, and utilities for CartSnitch services.
+
+## Test Users
+
+The following users are seeded by `cartsnitch-seed` and can be used for local development and UAT.
+
+| Email | Password | Display Name | Notes |
+|---|---|---|---|
+| `uat@cartsnitch.com` | `CartSnitch-UAT-2026!` | UAT Tester | Primary UAT account. Use for regression testing in the CartSnitch frontend. Created by the seed runner via Better-Auth's bcrypt path — credentials work against the live auth service. Idempotent; re-running the seed skips this user if it already exists. |
+
+### Running the Seed
+
+```bash
+# Install with seed dependencies
+pip install -e "cartsnitch-common[seed]"
+
+# Run (requires CARTSNITCH_DATABASE_URL_SYNC)
+CARTSNITCH_DATABASE_URL_SYNC=postgresql://user:pass@localhost:5432/cartsnitch \
+  cartsnitch-seed
+```
+
+### Architecture
+
+- **Models** live in `src/cartsnitch_common/models/`
+- **Alembic migrations** run via the `api` service (`api/alembic/`)
+- **Seed runner** runs via `cartsnitch-seed` (installed as a package entry point)
@@ -27,6 +27,7 @@ dev = [
 ]
 seed = [
    "faker>=33.0,<34.0",
+    "bcrypt>=4.0,<6.0",
 ]

 [project.scripts]
@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING

-from sqlalchemy import JSON, DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship

 from cartsnitch_common.constants import AccountStatus
@@ -21,8 +21,10 @@ class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
    __tablename__ = "users"

    email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
    display_name: Mapped[str | None] = mapped_column(String(100))
+    email_verified: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="false")
+    image: Mapped[str | None] = mapped_column(Text, nullable=True)

    # Relationships
    store_accounts: Mapped[list["UserStoreAccount"]] = relationship(back_populates="user")
@@ -2,8 +2,10 @@

 import random
 import time
+import uuid
 from typing import Any

+import bcrypt
 from faker import Faker
 from sqlalchemy import text
 from sqlalchemy.orm import Session
@@ -184,6 +186,65 @@ def run_seed(

        session.commit()

+        _seed_uat_user(session)
+
    elapsed = time.monotonic() - t0
    _log("")
    _log(f"Seed complete in {elapsed:.1f}s")
+
+
+# ---------------------------------------------------------------------------
+# UAT seed user
+# ---------------------------------------------------------------------------
+
+UAT_EMAIL = "uat@cartsnitch.com"
+UAT_PASSWORD = "CartSnitch-UAT-2026!"
+UAT_DISPLAY_NAME = "UAT Tester"
+UAT_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+
+
+def _seed_uat_user(session: Session) -> None:
+    """Insert or verify the dedicated UAT test user.
+
+    The user is created via Better-Auth's bcrypt hashing path so credentials
+    work against the live auth service. Idempotent — skips if the user already
+    exists.
+    """
+    existing = session.execute(
+        text("SELECT id FROM users WHERE email = :email"),
+        {"email": UAT_EMAIL},
+    ).fetchone()
+
+    if existing is not None:
+        _log(f"UAT user {UAT_EMAIL} already exists — skipping")
+        return
+
+    password_hash = bcrypt.hashpw(UAT_PASSWORD.encode(), bcrypt.gensalt()).decode()
+
+    session.execute(
+        text(
+            "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+            "VALUES (:id, :email, :hashed_password, :display_name, true, now(), now())"
+        ),
+        {
+            "id": str(UAT_USER_ID),
+            "email": UAT_EMAIL,
+            "hashed_password": password_hash,
+            "display_name": UAT_DISPLAY_NAME,
+        },
+    )
+
+    session.execute(
+        text(
+            "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+            "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+        ),
+        {
+            "user_id": str(UAT_USER_ID),
+            "account_id": str(UAT_USER_ID),
+            "password": password_hash,
+        },
+    )
+
+    session.commit()
+    _log(f"UAT user {UAT_EMAIL} created")
@@ -0,0 +1,72 @@
+# About CartSnitch
+
+## Our Mission
+
+We believe consumers deserve to know what they're really paying for at the grocery store.
+
+Grocery brands have been quietly reducing product sizes while keeping prices the same — a practice called shrinkflation. Most shoppers don't notice because the shelf price doesn't change. But the unit price goes up, and families end up paying more for less.
+
+CartSnitch exists to make that visible.
+
+---
+
+## The Problem We're Solving
+
+The average US family loses an estimated $300–$500 per year to shrinkflation. It's not dramatic. It happens slowly, product by product, category by category. A cereal box that's 10% smaller. A chip bag with 15% less in it. A detergent bottle that doesn't fill the dispenser the way it used to.
+
+These changes are legal. Manufacturers don't have to announce them. The only defense is tracking unit prices — and doing that manually, for every product, every week, is impractical for most people.
+
+So we built CartSnitch to do it automatically.
+
+---
+
+## What We Built
+
+CartSnitch is a grocery price tracking and shrinkflation detection app. When you connect your store account, we:
+- Track unit prices on the products you buy
+- Alert you when a product gets smaller or more expensive
+- Compare your total grocery bill across stores
+- Show you the biggest shrinkflation offenders we've found
+
+We're in beta. We're adding more products and stores every week.
+
+---
+
+## The Team
+
+**Penny Pincherton** — CEO and Co-founder
+Penny has spent her career in consumer finance and advocacy. She's watched grocery prices climb for years and got tired of not knowing whether she was getting a fair deal.
+
+**Savannah Savings** — CMO
+Savannah leads brand and communications at CartSnitch. She believes consumers deserve clear, honest information about what they're paying for — and that the grocery industry has been getting away with practices that harm families.
+
+**Chip Overstock** — CTO
+Chip has built data infrastructure at scale. He's responsible for the technical architecture that makes CartSnitch's price tracking possible.
+
+We're a small team. We care about this problem. We use the product ourselves.
+
+---
+
+## Our Approach
+
+- **Consumer-first.** Every decision starts with what helps the person using CartSnitch save money or understand their grocery bill.
+- **Data-backed.** Every claim we make is backed by numbers. We track unit prices, not shelf prices.
+- **Transparent.** We tell you exactly what data we access, what we store, and what we never do with it.
+- **Honest about scope.** CartSnitch focuses on shrinkflation detection. Price gouging monitoring is not currently in scope.
+
+---
+
+## The Data
+
+Our shrinkflation rankings and unit price calculations are based on publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. As we grow, we'll publish our methodology so anyone can verify our numbers.
+
+Production data will refine and validate our estimates. We will always note when statistics are directional versus based on real transaction data.
+
+---
+
+## Get In Touch
+
+- **General:** hello@cartsnitch.app
+- **Press:** press@cartsnitch.app
+- **Partnerships:** partners@cartsnitch.app
+- **Bug reports:** We use in-app feedback
@@ -0,0 +1,100 @@
+# App Store / PWA Listing Copy
+
+**Target:** April 24, 2026
+
+---
+
+## iOS App Store
+
+**App Name:** CartSnitch — Grocery Price Tracker
+
+**Subtitle:** Track prices. Catch shrinkflation.
+
+**Short description (170 characters max):**
+Know when your groceries get smaller or more expensive.
+
+**Full description (4000 characters max):**
+You go to the grocery store. You buy the same things you always buy. But lately, the cereal box feels lighter. The chips bag seems smaller. The detergent bottle doesn't fill up like it used to.
+
+You're not imagining it. It's called shrinkflation — and it's costing the average family hundreds of dollars a year.
+
+CartSnitch helps you catch it.
+
+**What CartSnitch does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy regularly gets smaller or more expensive
+- Compares your total grocery bill across stores so you always know where to shop cheapest
+
+**Why it matters:**
+Brands know you'll notice a price increase before you'll notice a smaller package. So instead of raising prices, they shrink products. The shelf price stays the same. You pay more per ounce without realizing it.
+
+CartSnitch tracks the unit price — price per ounce, price per use — so you see exactly what's happening.
+
+**Key features:**
+- Unit price tracking across grocery products
+- Personalized price alerts on products you buy regularly
+- Store comparison — see your total basket cost at different stores
+- Shrinkflation tracker — see which products have changed the most
+
+**This is beta.** We're adding more products and stores every week.
+
+---
+
+## Google Play Store
+
+**Tagline:** Track prices. Catch shrinkflation.
+
+**Short description (80 characters):**
+Know when your groceries get smaller or more expensive.
+
+**Full description:**
+You go to the grocery store. You buy the same things you always buy. But lately, the cereal box feels lighter. The chips bag seems smaller. The detergent bottle doesn't fill up like it used to.
+
+You're not imagining it. It's called shrinkflation — and it's costing the average family hundreds of dollars a year.
+
+CartSnitch helps you catch it.
+
+**What CartSnitch does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy regularly gets smaller or more expensive
+- Compares your total grocery bill across stores so you always know where to shop cheapest
+
+**Why it matters:**
+Brands know you'll notice a price increase before you'll notice a smaller package. So instead of raising prices, they shrink products. The shelf price stays the same. You pay more per ounce without realizing it.
+
+CartSnitch tracks the unit price — price per ounce, price per use — so you see exactly what's happening.
+
+**Key features:**
+- Unit price tracking across grocery products
+- Personalized price alerts on products you buy regularly
+- Store comparison — see your total basket cost at different stores
+- Shrinkflation tracker — see which products have changed the most
+
+**This is beta.** We're adding more products and stores every week.
+
+---
+
+## Feature Highlights (3 bullets, iOS)
+
+- **Unit price tracking** — See exactly what you're paying per ounce on every product
+- **Shrinkflation alerts** — Get notified when your regular products get smaller or more expensive
+- **Store comparison** — Compare your total grocery bill across stores in seconds
+
+## Feature Highlights (4 bullets, Google Play)
+
+- Track unit prices on grocery products
+- Personalized alerts when products you buy change
+- Compare grocery costs across stores
+- See the biggest shrinkflation offenders
+
+---
+
+## Keywords (iOS — 100 character limit)
+
+grocery, price tracker, savings, shrinkflation, unit price, grocery savings, price compare, food prices, grocery deals, price alert, grocery app
+
+---
+
+## Search Terms (Google Play)
+
+grocery price tracker, grocery savings app, price comparison grocery, shrinkflation app, unit price calculator, grocery deal app, grocery savings tracker
@@ -0,0 +1,53 @@
+---
+title: "CartSnitch vs Flipp: Which App Actually Helps You Save More on Groceries?"
+slug: cartsnitch-vs-flipp
+status: draft
+version: 1.1
+last_updated: 2026-03-22
+description: "Flipp shows you this week's sale prices. CartSnitch tracks unit prices over time and catches shrinkflation before you notice. Here's when each tool wins."
+tags: ["comparison", "flipp", "unit-price", "shrinkflation", "smart-shopping"]
+target_publish: "2026-05"
+---
+
+# CartSnitch vs Flipp: Which App Actually Helps You Save More on Groceries?
+
+Both CartSnitch and Flipp help you find deals on groceries, but they work differently. Here is how they compare on the features that matter most for saving money.
+
+## What Is Flipp?
+
+Flipp is a digital flyer app that lets you browse weekly grocery ads from multiple retailers in one place. You can clip coupons and create a shopping list from featured deals.
+
+## What Is CartSnitch?
+
+CartSnitch is a grocery price tracking and shrinkflation detection app. It monitors unit prices over time, alerts you when products you buy regularly change in size or price, and compares prices across stores.
+
+## Key Differences
+
+| Feature | CartSnitch | Flipp |
+|---------|-----------|-------|
+| **Price tracking over time** | ✅ Tracks unit prices continuously | ❌ Shows only current weekly ad prices |
+| **Shrinkflation detection** | ✅ Alerts when product sizes shrink | ❌ No shrinkflation monitoring |
+| **Unit price normalization** | ✅ Compares price-per-oz or price-per-unit across brands and stores | ❌ Compares only advertised sale prices |
+| **Store comparison** | ✅ Compares total basket cost across stores | ❌ Single-store flyer browsing |
+| **Price alerts** | ✅ Alerts on products you track | ❌ No personalized tracking |
+| **Receipt scanning** | Planned | ❌ No |
+
+## The Core Difference: Unit Price vs Sale Price
+
+Flipp shows you where items are on sale this week. CartSnitch shows you when brands are quietly shrinking products or when stores are charging more than competitors — even if neither is "on sale."
+
+**Example:** A cereal brand reduces its box from 18 oz to 15.5 oz. The shelf price stays the same. Flipp shows no deal. CartSnitch flags it as a 16.1% unit price increase.
+
+This is shrinkflation. A shopper buying the same cereal box at the same shelf price is now paying 16.1% more per ounce — without any price tag ever changing.
+
+## Which App Saves You More?
+
+**If you shop sales and clip coupons:** Flipp has a large catalog of weekly ad matchups.
+
+**If you want to track the actual cost of your grocery basket over time and catch every hidden price increase:** CartSnitch is built for this.
+
+Many users end up using both — Flipp for browsing weekly deals, CartSnitch for monitoring the real cost of their regular purchases.
+
+## Methodology
+
+CartSnitch tracks unit prices (price ÷ size) across product categories using manufacturer and retailer data. Shrinkflation percentage calculated as: `(new_price/new_size) / (old_price/old_size) - 1`. Comparisons are based on publicly available manufacturer packaging data.
@@ -0,0 +1,60 @@
+# Price Gouging vs Shrinkflation: What's the Difference?
+
+You hear both terms used when grocery prices feel unfair. But they are not the same thing — and understanding the difference helps you know what to do about each one.
+
+## What Is Price Gouging?
+
+Price gouging is when retailers or sellers dramatically raise prices during a crisis, shortage, or period of high demand. It is most commonly associated with:
+
+- Hurricanes and natural disasters (gas, water, generators)
+- Supply chain disruptions
+- Public health emergencies
+
+**Example:** A hardware store raising generator prices from $500 to $1,500 the day before a hurricane makes landfall.
+
+Price gouging is **illegal in many states** during declared emergencies. Most states have consumer protection laws that prohibit excessive price increases when a state of emergency has been declared.
+
+## What Is Shrinkflation?
+
+Shrinkflation is when manufacturers reduce the size or quantity of a product while keeping the price the same — or raising it. The per-unit cost increases without the packaging change being obvious at first glance.
+
+**Example:** A cereal brand reducing its box from 18 oz to 15.5 oz while keeping the price at $4.99. The shelf price did not change. The unit price went up 16%.
+
+Shrinkflation is **legal** in the US. Manufacturers are required to disclose net weight, but they do not need to announce when a product gets smaller.
+
+## Key Differences
+
+| | Price Gouging | Shrinkflation |
+|---|---|---|
+| **Who does it** | Retailers and sellers | Manufacturers |
+| **When it happens** | Crises, shortages, emergencies | Continuously, as a standard practice |
+| **How it works** | Raising prices sharply | Reducing product size |
+| **Legal status** | Illegal during declared emergencies in most states | Legal year-round |
+| **Consumer response** | Report to state attorney general | Track unit prices; switch products |
+| **Detection** | Obvious price increases | Requires unit price calculation |
+
+## How CartSnitch Handles Both
+
+**CartSnitch tracks shrinkflation automatically.** We monitor unit prices across our tracked products and alert you when a product you buy regularly gets smaller or more expensive.
+
+**Price gouging is different.** CartSnitch does not currently detect price gouging — it requires monitoring retail prices during specific time periods and comparing against pre-crisis baselines, which is outside our current scope.
+
+If you encounter what you believe is price gouging:
+- **Document the prices** — take screenshots
+- **Report it** — contact your state attorney general's office
+- **Shop elsewhere** — if possible
+
+## Can Both Happen at Once?
+
+Yes. A product could experience shrinkflation (getting smaller over time) AND be subject to price gouging during an emergency. For example:
+
+- A bottle of water that shrank from 24 oz to 16 oz over five years (shrinkflation)
+- The same product being sold for triple its normal price during a flood emergency (price gouging)
+
+Both are harmful to consumers. Only one is currently illegal.
+
+## The Common Ground
+
+Both price gouging and shrinkflation share a common feature: they exploit the fact that most consumers don't have access to real-time price data.
+
+CartSnitch was built to give that data to consumers. For shrinkflation today — and honest, transparent grocery pricing.
@@ -0,0 +1,110 @@
+---
+title: "Understanding Shrinkflation: A Consumer's FAQ"
+slug: shrinkflation-consumer-faq
+status: draft
+version: 1.0
+last_updated: 2026-03-22
+description: "Shrinkflation is how brands quietly raise prices by giving you less product for the same money. Here is what it is, why it is legal, and how to detect it."
+tags: ["shrinkflation", "consumer-faq", "grocery-prices", "price-transparency", "unit-price"]
+series: "The Shrinkflation Files"
+series_part: 0
+target_publish: 2026-04-01
+target_keywords: ["what is shrinkflation", "shrinkflation examples", "why did my product get smaller", "is shrinkflation legal"]
+---
+
+# Understanding Shrinkflation: A Consumer's FAQ
+
+You notice it at the grocery store: the cereal box looks smaller. The chip bag seems to have less air in it. The pasta salad you loved now fits less in the container. But the price is the same — or higher.
+
+That is shrinkflation. Here is what you need to know.
+
+---
+
+## What Is Shrinkflation?
+
+Shrinkflation is the practice of reducing the size or quantity of a product while keeping the price the same — or raising it. The per-unit cost increases without the packaging change being obvious at first glance.
+
+It is different from inflation. Inflation raises prices for the same product. Shrinkflation keeps the price the same for a smaller product. Both cost you more per ounce, per gram, or per use.
+
+---
+
+## Is Shrinkflation Legal?
+
+Yes. Shrinkflation is legal in the US and most markets. Manufacturers are required to state the net weight or count on the packaging, but they are not required to announce when a product gets smaller. There is no federal regulation specifically banning shrinkflation.
+
+Some regulators have begun studying the practice, and there have been proposals for mandatory price-per-unit labeling at the shelf level, but no binding rules exist as of 2026.
+
+---
+
+## What's an Example of Shrinkflation?
+
+Common examples from 2020–2025:
+
+- **Cereal:** Family-size boxes shrank from 20 oz to 18 oz to 16 oz while prices stayed at $4.99–$5.99
+- **Crackers:** Standard sleeve count dropped from 4 to 3 packs while shelf price remained constant
+- **Yogurt:** Multipacks reduced from 6 oz cups to 5.3 oz cups
+- **Paper towels:** Roll count dropped from 12 to 10 while price stayed the same
+- **Dish soap:** Bottle volumes shrank from 24 oz to 20 oz
+
+In every case, the per-unit cost increased even when the shelf price did not change — or changed less than the size reduction warranted.
+
+---
+
+## How Much Does Shrinkflation Cost the Average Family?
+
+Estimates vary by shopping habits and product categories. CartSnitch analysis of manufacturer packaging data suggests the average US household spends an additional $80–$120 per year on cereals alone due to shrinkflation. Across all categories — snacks, dairy, household goods, beverages — total hidden costs per household are estimated at $300–$500 per year.
+
+These figures are directional estimates based on publicly available manufacturer packaging data, not CartSnitch production data.
+
+---
+
+## Why Do Brands Use Shrinkflation?
+
+Brands use shrinkflation because consumers notice price increases more than package size decreases. A $5 cereal box going to $5.50 is visible and may cause consumers to switch to competitors. A $5 cereal box shrinking from 18 oz to 15 oz at the same price is rarely noticed until someone like CartSnitch tracks the unit price.
+
+Shrinkflation is most common in products where:
+- Brand loyalty is high (consumers repurchase without checking alternatives)
+- Unit prices are not prominently displayed
+- Size reductions are modest (5–15%)
+- The product is purchased regularly
+
+---
+
+## How Do I Detect Shrinkflation?
+
+Three ways to catch shrinkflation before you overpay:
+
+1. **Track unit prices** — Divide the shelf price by the size (oz, g, count). If the unit price goes up but the product looks the same, you are being shrunk.
+2. **Compare across brands** — A competing brand may offer more product for the same or lower price.
+3. **Use CartSnitch** — CartSnitch monitors unit prices on your tracked products and alerts you when a product you buy regularly gets smaller or more expensive.
+
+---
+
+## Does Shrinkflation Affect Store Brands Too?
+
+Yes. Store brands (private label) also engage in shrinkflation, though they tend to do so less aggressively than name brands. National brands rely more heavily on shrinkflation because they cannot compete on price as easily as store brands do.
+
+---
+
+## Is There a Campaign or Movement Against Shrinkflation?
+
+Consumer advocacy groups have lobbied for:
+- Mandatory unit price display at shelf level
+- Required advance notice when product sizes change
+- Clear "size changed" labels on packaging
+
+CartSnitch is built to give consumers the data they need to make informed decisions — even before regulation catches up.
+
+---
+
+## How Is Shrinkflation Different From Price Gouging?
+
+Shrinkflation is a gradual, product-level practice by manufacturers. Price gouging is typically a retailer or seller raising prices sharply during a supply crisis or emergency. Both harm consumers, but they are distinct practices.
+
+Price gouging is illegal in many states during declared emergencies. Shrinkflation is legal year-round.
+
+---
+
+## Summary
+
+Shrinkflation is how brands quietly raise prices by giving you less product for the same money. It is legal, common, and affects the average family by hundreds of dollars per year. The only defense is tracking unit prices — and CartSnitch does that automatically.
@@ -0,0 +1,83 @@
+# How CartSnitch Works
+
+## The Core Idea
+
+Every product at the grocery store has two prices:
+- **Shelf price** — what you pay at checkout
+- **Unit price** — what you pay per ounce, per gram, per sheet, per load
+
+Most people compare shelf prices. Smart shoppers compare unit prices.
+
+CartSnitch tracks unit prices automatically — so you don't have to do the math yourself.
+
+---
+
+## How We Track Prices
+
+CartSnitch pulls pricing data from:
+- **Store loyalty portals** — Meijer, Kroger, and Target — when you connect your account, CartSnitch uses an automated scraper to pull your purchase history from the store loyalty portal
+- **Public manufacturer data** — packaging changes, suggested retail prices
+- **USDA FoodData Central** — reference data for package sizing baselines (used for historical size comparison only — not part of our live tracking system)
+
+We calculate unit price for every product we track:
+
+`Unit Price = Shelf Price ÷ Package Size`
+
+When a brand reduces package size — or a store changes its price — we catch it.
+
+---
+
+## What Is Shrinkflation Detection?
+
+Shrinkflation happens when a brand reduces the size of a product without lowering the price. The shelf price stays the same. The unit price goes up.
+
+**Example:**
+- 2021: Cereal at $4.99 for 18 oz → $0.277 per oz
+- 2024: Same cereal at $4.99 for 15.5 oz → $0.322 per oz
+
+Same price. 16% more per ounce. That's shrinkflation.
+
+CartSnitch monitors unit prices over time. When we detect a statistically significant unit price increase — whether from a size reduction, a price increase, or both — we flag it.
+
+---
+
+## How Price Alerts Work
+
+1. **You add a product** — Search for any product you buy regularly and add it to your tracked list.
+2. **We monitor unit prices** — Every time we detect a price or size change, we recalculate the unit price.
+3. **You get an alert** — If the unit price increases beyond a threshold, we notify you — so you can decide whether to switch products, switch stores, or just be aware.
+
+You choose what counts as significant. Some users set alerts for any change. Others only want to know about large unit price jumps.
+
+---
+
+## Store Comparison
+
+CartSnitch compares your total grocery basket across stores.
+
+When you connect your store accounts, we can see what you bought and where. We calculate the total cost of your typical basket at each store we support — so you know where you're getting the best overall deal.
+
+This is different from just comparing the price of one item. Some stores are cheaper on produce, others on pantry staples. CartSnitch shows you the full picture.
+
+---
+
+## What We Don't Do
+
+- **We don't collect receipts** — Store account connections give us enough data to track prices and compare baskets. Receipt-based tracking is being evaluated.
+- **We don't have every product** — Beta is limited to supported stores and categories. We're adding more every week.
+- **We don't affect shelf prices** — We show you the data. What you do with it is up to you.
+
+---
+
+## How We Protect Your Data
+
+- We read price data from your connected store accounts — we never see your login credentials
+- We store only the minimum data needed to calculate unit prices and compare baskets
+- We don't sell your data to third parties
+- You can disconnect your store account at any time and delete your data
+
+---
+
+## Ready to Start?
+
+[Sign up for beta →]
@@ -0,0 +1,102 @@
+# How We Calculate Shrinkflation: Our Methodology
+
+We believe consumers deserve to verify our work. Here's exactly how we calculate shrinkflation percentages and where our data comes from.
+
+---
+
+## The Core Formula
+
+For every product we track, we calculate:
+
+**Unit Price = Shelf Price ÷ Package Size**
+
+Then we calculate the shrinkflation percentage:
+
+**Shrinkflation % = (New Unit Price ÷ Old Unit Price) − 1**
+
+This gives us the effective price increase — accounting for both size changes and price changes.
+
+**Example:**
+- 2021: Cereal at $4.99 for 18 oz → Unit price: $4.99 ÷ 18 oz = $0.277/oz
+- 2024: Same cereal at $4.99 for 15.5 oz → Unit price: $4.99 ÷ 15.5 oz = $0.322/oz
+
+Shrinkflation % = ($4.99 ÷ 15.5) ÷ ($4.99 ÷ 18) − 1 = 16.1%
+
+The shelf price is the same. The unit price went up 16.1%.
+
+---
+
+## Data Sources
+
+We use multiple data sources to build our shrinkflation rankings:
+
+### 1. Manufacturer Packaging Data
+We track documented changes in product sizes as reported by manufacturers. This includes:
+- Net weight changes on packaging
+- Count-per-package changes (e.g., 4 rolls → 3 rolls)
+- Volume changes in liquid products
+
+### 2. USDA FoodData Central
+The USDA FoodData Central database provides reference data on product sizes and nutrition, which we use as baselines for historical comparison.
+
+**URL:** https://fdc.nal.usda.gov/
+
+### 3. Public Retail Data
+When available, we cross-reference shelf prices from public retailer sources to validate price continuity.
+
+---
+
+## How We Rank Shrinkflation Offenders
+
+Our top shrinkflation offenders rankings are based on the calculated shrinkflation percentage for each product. We rank products by:
+
+1. **Highest shrinkflation percentage** — the largest effective unit price increase
+2. **Across consistent time periods** — comparing current sizes/prices to documented baselines from 2020–2024
+3. **By product category** — cereals, snacks, dairy, household goods, etc.
+
+We only include products where we have documented evidence of a size or price change. We do not estimate shrinkflation for products we cannot verify.
+
+---
+
+## Shrinkflation vs Regular Price Increases
+
+We distinguish between:
+
+- **Shrinkflation** — Package size decreases while shelf price stays the same or increases. Unit price goes up.
+- **Regular price increase** — Package size stays the same, shelf price goes up. Unit price goes up.
+- **Combined shrinkflation + price increase** — Package size decreases AND shelf price increases. Unit price goes up significantly.
+
+All three result in a higher unit price. Our percentages capture the total effective increase.
+
+---
+
+## What We Don't Do
+
+- We don't estimate shrinkflation without documented evidence
+- We don't include products we cannot verify
+- We don't adjust our calculations based on brand or retailer pressure
+- We don't publish specific rankings until we can verify the underlying data
+
+---
+
+## Production Data vs Estimates
+
+**Before launch (current):** Our shrinkflation percentages are based on publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. These are directional estimates — they tell you the pattern is real.
+
+**After production deployment:** Once we have a live product with real transaction data, we'll be able to run the numbers against actual purchase data. This will validate and refine our estimates.
+
+We will always note when statistics are directional estimates versus based on production data.
+
+---
+
+## Future: Publishing Our Queries
+
+Once production is live, we plan to publish the SQL queries behind our shrinkflation calculations — so anyone can run them against our data and verify our work.
+
+This is part of our commitment to transparency.
+
+---
+
+## Questions?
+
+If you have questions about our methodology or believe we've made an error, email us: hello@cartsnitch.app
@@ -0,0 +1,97 @@
+# CartSnitch Press/Media Kit
+
+**Timing:** Ready by April 24, 2026 (beta launch)
+
+---
+
+## About CartSnitch
+
+CartSnitch is a grocery price tracking and shrinkflation detection app that helps consumers see exactly how much they are paying per unit of product — and when brands shrink products without lowering prices.
+
+**Founded:** 2026
+**Mission:** Help consumers understand what they are really paying for at the grocery store, and expose the practices that cost families hundreds of dollars per year.
+
+---
+
+## Product Description
+
+CartSnitch tracks unit prices (price ÷ size) across grocery products. Users can:
+- Set alerts on products they buy regularly
+- See when a product gets smaller or more expensive
+- Compare total grocery costs across stores
+- Access data on which products have experienced the most shrinkflation
+
+**Status:** Beta (April 24, 2026)
+**Availability:** Web app / PWA
+**Supported stores:** Meijer, Kroger, and Target
+
+---
+
+## The Problem: Shrinkflation
+
+Shrinkflation is the practice of reducing product size while keeping prices the same or raising them. The average US family loses an estimated $300–$500 per year to shrinkflation across all grocery categories.
+
+**Examples (2020–2025):**
+- Family cereal boxes: 20 oz → 18 oz → 16 oz, same shelf price
+- Paper towels: 12 rolls → 10 rolls, same price
+- Yogurt cups: 6 oz → 5.3 oz, same price
+- Dish soap: 24 oz → 20 oz, same price
+
+Unlike price gouging, which is illegal during emergencies in many states, shrinkflation is legal year-round. The only defense is tracking unit prices.
+
+---
+
+## Key Messages
+
+1. **Unit prices reveal the truth.** The shelf price is misleading. Price per ounce or per unit is the honest measure of value.
+
+2. **Shrinkflation is real and costly.** Brands reduce product sizes while maintaining or raising prices. The average family loses $300–$500/year.
+
+3. **CartSnitch tracks it automatically.** We monitor unit prices across products and alert users when their regular purchases change.
+
+4. **Consumers deserve transparency.** Price-per-unit should be displayed prominently at shelf level. Until regulation catches up, CartSnitch gives consumers the data directly.
+
+---
+
+## Statistics (Directional — Based on CartSnitch Analysis of Manufacturer Packaging Data)
+
+- Average family loses **$300–$500/year** to shrinkflation across all grocery categories
+- Cereals specifically: **$80–$120/year** per family
+- Family cereal boxes shrank an average of **12–16%** in oz between 2020–2025
+- Top shrinkflation offenders in 2021–2025: Lay's (28%), Yoplait (27.5%), Cocoa Puffs (27%), Ruffles (23.6%), Cheerios (21.5%)
+
+*Note: Dollar figures are based on CartSnitch analysis of publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. Production data will refine these figures.*
+
+---
+
+## Quotes
+
+**Penny Pincherton, CEO and Co-founder:**
+> "We built CartSnitch because we were tired of going to the store and getting less for the same money. Shrinkflation is a quiet tax on families who don't have time to calculate price-per-ounce on every product, every week. We do that work automatically."
+
+**Savannah Savings, CMO:**
+> "The grocery industry has been shrinking products in plain sight for years because they know most shoppers won't notice. We think noticing should be easy."
+
+---
+
+## Leadership
+
+- **Penny Pincherton** — CEO and Co-founder
+- **Savannah Savings** — CMO
+- **Chip Overstock** — CTO
+
+---
+
+## Media Assets
+
+- **Screenshots:** Available once staging environment is live (CAR-60 in progress)
+- **Logo:** Available in brand assets folder
+- **Product demo:** TBD
+
+---
+
+## Contact
+
+For press inquiries: press@cartsnitch.app
+For partnerships: partners@cartsnitch.app
+Website: cartsnitch.app
@@ -0,0 +1,94 @@
+# Your Data Is Yours. Here's How We Keep It That Way.
+
+We know we're asking you to connect your grocery store account. That means trusting us with your purchase history — and we take that seriously.
+
+Here's exactly what we access, what we store, and what we never do.
+
+---
+
+## What We Access
+
+When you connect your store account, CartSnitch uses an automated scraper to pull your purchase history from the store loyalty portal. This means we can see:
+
+- **What you bought** — product names and quantities
+- **How much you paid** — shelf prices at time of purchase
+- **When you bought it** — purchase dates
+
+We **cannot** see:
+- Your store login credentials
+- Payment method information
+- Your physical location
+
+---
+
+## What We Store
+
+We store only the data we need to calculate unit prices and compare baskets:
+
+- Product identifiers (names, sizes, categories)
+- Shelf prices and unit prices
+- Purchase frequency
+- Your tracked products and alerts
+
+We **do not store**:
+- Your full purchase history indefinitely
+- Payment information
+- Personal identifying information beyond your email
+
+---
+
+## What We Never Do
+
+- **We never sell your data.** Your data is never a product. We don't license it, share it with third parties, or use it for advertising.
+- **We never see your login credentials.** CartSnitch accesses your store loyalty portal through an automated scraper — we never have access to your store password.
+- **We never post to your social accounts or profile.**
+- **We never use your purchase data for anything other than the CartSnitch service.**
+
+---
+
+## How We Use Your Data
+
+We use your purchase data to:
+
+1. **Calculate unit prices** — so you can compare products fairly
+2. **Detect shrinkflation** — by monitoring when products you buy change in size or price
+3. **Compare store prices** — to show you where your total basket costs less
+4. **Send you alerts** — when products you track change in price or size
+
+That's it.
+
+---
+
+## Data Retention
+
+- You can delete your account and all associated data at any time
+- When you disconnect a store account, we remove the connection and stop accessing new data
+- Historical data associated with your account can be deleted on request
+
+---
+
+## Security
+
+- All data is encrypted in transit and at rest
+- CartSnitch accesses store loyalty portals using an automated scraper — we never see your store password
+- Our team follows strict access controls — only the engineers who need your data to build the product can access it
+
+---
+
+## Want to Disconnect?
+
+You can disconnect your store account at any time:
+
+1. Go to Settings
+2. Select "Connected Accounts"
+3. Click "Disconnect" next to the store you want to remove
+
+Disconnecting immediately stops us from accessing new data from that store.
+
+---
+
+## Questions?
+
+We're happy to answer questions about how we handle data. Email us anytime: privacy@cartsnitch.app
+
+See our full [Terms of Service →]
@@ -0,0 +1,129 @@
+# April 24 Beta Launch Day Social Posts
+
+**Publish date:** April 24, 2026
+**Platforms:** Twitter/X, Reddit (r/Frugal, r/personalfinance)
+**Goal:** Announce beta launch, drive signups, first social proof
+
+---
+
+## Twitter/X — Main Launch Announcement
+
+**Tweet 1 (the big one):**
+🎉 CartSnitch is officially in beta.
+
+We built this because you deserve to know when brands shrink their products without lowering prices.
+
+Track unit prices. Catch shrinkflation. Compare stores.
+
+Join us: [link]
+
+**Tweet 2:**
+Grocery brands have been shrinking products in plain sight for years. Cereal boxes, chip bags, detergent bottles — all getting smaller while shelf prices stay the same.
+
+We track the unit price. You see the truth.
+
+[Link]
+
+**Tweet 3 (CTA thread):**
+How it works:
+1️⃣ Connect your store account
+2️⃣ We track unit prices on everything you buy
+3️⃣ Get alerts when products shrink or get more expensive
+4️⃣ Compare your total basket across stores
+
+Free to join: [link]
+
+**Tweet 4 (shrinkflation data hook):**
+We already found the biggest shrinkflation offenders. Lay's, Yoplait, Cocoa Puffs, Ruffles, Cheerios — all cutting sizes while keeping prices flat.
+
+See the full list: [link to top-10 article]
+
+**Tweet 5 (proof/activation):**
+Beta is live. Free to join.
+
+No commitment. No credit card. Just the data you need to stop overpaying at the grocery store.
+
+👉 [link]
+
+**Hashtags:** #Shrinkflation #GrocerySpending #PriceHiking #Frugal #Beta #CartSnitch
+
+---
+
+## Twitter/X — Reply Chain (engagement)
+
+**In reply to someone asking "what is shrinkflation":**
+When a brand reduces the size of a product but keeps the price the same — or raises it. The shelf price looks fine. The unit price goes up.
+
+Example: cereal at $4.99 for 18 oz → $4.99 for 15.5 oz. Same price. 16% more per ounce.
+
+We track it automatically. [link]
+
+**In reply to "why should I care":**
+The average family loses an estimated $300–$500/year to shrinkflation across all grocery categories. It's not dramatic. It happens slowly. But it adds up.
+
+CartSnitch shows you exactly when it happens to the products you buy.
+
+**In reply to "is this free":**
+Yes, beta is free. We're building the product and adding more stores every week.
+
+[link]
+
+---
+
+## Reddit Post — r/Frugal
+
+**Title:** [Launch] CartSnitch — we built a free tool to track shrinkflation and compare grocery prices across stores (beta)
+
+**Body:**
+Hey r/Frugal — been working on this for a while and finally ready to share.
+
+CartSnitch tracks unit prices (price ÷ size) on grocery products and alerts you when products you buy regularly get smaller or more expensive. It also compares your total grocery bill across stores.
+
+**What it does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy shrinks or gets more expensive
+- Compares your total basket cost across Meijer, Kroger, and Target
+- Shows you the biggest shrinkflation offenders we've found
+
+**Why we built it:**
+Shrinkflation costs the average family an estimated $300–$500/year. It's legal, it's common, and most people don't notice because the shelf price doesn't change.
+
+We're in beta — free to join, no credit card. Looking for feedback.
+
+[link]
+
+*(Mods: happy to answer questions. Not selling anything, just built this because we think consumers deserve this data.)*
+
+---
+
+## Reddit Post — r/personalfinance
+
+**Title:** [Launch] We built a free tool to track grocery shrinkflation and price changes — thinking about the data behind your grocery bill
+
+**Body:**
+I've been tracking grocery prices for about a year and the numbers are wild. Brands reduce product sizes constantly while maintaining or raising shelf prices. The average family loses an estimated $300–$500/year to this.
+
+We built CartSnitch to automate the tracking. It's in beta — free to join.
+
+**What it tracks:**
+- Unit prices (price per oz/g/sheet/load)
+- Product size changes (shrinkflation)
+- Price changes over time
+- Total basket comparison across stores
+
+We're not affiliated with any retailers. Just built this because I kept getting annoyed at the cereal aisle.
+
+Happy to answer questions about the data methodology.
+
+[link]
+
+---
+
+## Instagram / LinkedIn (if applicable)
+
+**Carousel idea:**
+Slide 1: "Your cereal box is lying to you."
+Slide 2: "Same price. Less product. Here's the math." [example with unit price calculation]
+Slide 3: "This is shrinkflation — and it's costing you hundreds a year."
+Slide 4: "CartSnitch tracks it automatically." [app screenshot]
+Slide 5: "Free beta — link in bio."
@@ -0,0 +1,93 @@
+# Stores Supported by CartSnitch
+
+CartSnitch currently supports the following stores for price tracking, shrinkflation detection, and store comparison.
+
+We're actively expanding coverage. If your store isn't listed, you can request it — we prioritize stores with the highest user demand.
+
+---
+
+## Currently Supported
+
+### Meijer
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Midwest (Meijer and Meijer Express)
+
+**Note:** Connect your Meijer account and CartSnitch will pull your purchase history from the Meijer loyalty portal using an automated scraper.
+
+---
+
+### Kroger
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Nationwide (Kroger, Kroger Marketplace, Kroger Pickup)
+
+**Note:** Connect your Kroger account and CartSnitch will pull your purchase history from the Kroger loyalty portal using an automated scraper.
+
+---
+
+### Target
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Nationwide
+
+**Note:** Connect your Target account and CartSnitch will pull your purchase history from the Target loyalty portal using an automated scraper.
+
+---
+
+## Evaluating Additional Stores
+
+We're always evaluating new retailers based on user demand. We can't commit to specific stores or timelines yet — but if there's a retailer you'd like us to prioritize, let us know.
+
+[Submit a store request →]
+
+---
+
+## How Store Coverage Works
+
+When you connect your store account, CartSnitch reads your purchase history and current pricing data from your loyalty account — without ever seeing your login credentials. We use read-only access to your loyalty account data.
+
+**What you get when your store is supported:**
+- Personalized price alerts on products you buy
+- Accurate basket cost comparison across your stores
+- Shrinkflation detection on your actual purchases
+
+**What this requires:**
+- An active loyalty account with the store
+- Willingness to connect the account (you can disconnect at any time)
+
+---
+
+## Privacy Note
+
+We never store your store login credentials. Our integration uses read-only access to your loyalty account data. We store only the minimum data needed to calculate unit prices and compare baskets.
+
+See our full [privacy policy →]
+
+---
+
+## Don't See Your Store?
+
+We're building CartSnitch's store coverage as fast as we can. The grocery market is fragmented and each integration requires technical work.
+
+**How to request a store:**
+1. Sign up for beta
+2. Go to Settings > Request a Store
+3. Submit your store name and location
+
+We review requests weekly and prioritize stores with the highest demand and broadest geographic coverage.
@@ -0,0 +1,151 @@
+# CartSnitch UAT Runbook v1
+
+**Version:** 1.0
+**Author:** Savannah Savings, CTO
+**Date:** 2026-03-30
+**Effective:** Immediately upon Phase 1 completion
+
+---
+
+## 1. Defect Severity Classification
+
+Every defect discovered during UAT **must** be classified by severity and priority before triage.
+
+### Severity Levels
+
+| Severity | Definition | Examples |
+|----------|-----------|----------|
+| **S1 — Critical** | Blocks all users from completing a core journey. System is down, data is lost, or security is breached. | Login page crashes for all users; purchase data deleted; auth tokens exposed in response |
+| **S2 — High** | Blocks a major user flow for a significant portion of users. Core feature is broken but workarounds may exist. | Registration fails for email addresses with `+` character; price alerts never trigger; store comparison shows wrong prices |
+| **S3 — Medium** | Feature is degraded but usable. User can complete the journey with friction. | Date formatting shows raw ISO string instead of friendly date; slow page load (>5s) on product detail; search results not sorted correctly |
+| **S4 — Low** | Cosmetic issue, minor UI inconsistency, or edge case with minimal user impact. | Button text truncated on narrow screens; extra whitespace in footer; tooltip shows on hover but not on focus |
+
+### Priority Levels
+
+Priority determines **when** the defect must be fixed. Priority is set by the CTO based on severity, business impact, and sprint capacity.
+
+| Priority | SLA | When to Use |
+|----------|-----|------------|
+| **P0 — Fix Now** | Triage within 1 hour, fix deployed within 4 hours | S1 defects, any security vulnerability, data integrity issues |
+| **P1 — Fix This Sprint** | Triage within 4 hours, fix in current sprint | S2 defects blocking upcoming release, S1 defects with viable workaround |
+| **P2 — Fix Next Sprint** | Triage within 24 hours, scheduled for next sprint | S3 defects, S2 defects with easy workarounds |
+| **P3 — Backlog** | Triage within 48 hours, prioritized against backlog | S4 defects, minor improvements, nice-to-haves |
+
+### Defect Report Template
+
+Every defect filed during UAT must include:
+
+```
+**Title:** [Short description]
+**Severity:** S1/S2/S3/S4
+**Priority:** P0/P1/P2/P3 (set by CTO at triage)
+**Journey:** [Which user journey — J1 through J10]
+**Environment:** [Dev / Prod, deployed image tag]
+**Steps to Reproduce:**
+1. Navigate to ...
+2. Click ...
+3. Enter ...
+**Expected Result:** ...
+**Actual Result:** ...
+**Screenshots/Logs:** [Attach or link]
+**Browser/Device:** [e.g., Chromium 124, mobile viewport 390x844]
+```
+
+---
+
+## 2. UAT Entry Criteria
+
+UAT **must not begin** until ALL of the following are satisfied. Checkout Charlie verifies these before opening the UAT gate.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| E1 | CI pipeline passes on the merged commit (lint, type-check, unit tests, build) | GitHub Actions (automated) |
+| E2 | Docker image is built and pushed to GHCR with a CalVer tag | GitHub Actions (automated) |
+| E3 | Dev environment is deployed and accessible at `cartsnitch.dev.farh.net` | Flux reconciliation + health check |
+| E4 | All Playwright E2E tests pass in CI | GitHub Actions (automated) |
+| E5 | No open S1/S2 defects from previous UAT cycle | Checkout Charlie (manual check) |
+| E6 | PR has been reviewed and approved by QA (Checkout Charlie) and CTO (Savannah Savings) | GitHub PR approvals |
+| E7 | PR has been merged to main by CEO (Coupon Carl) | GitHub merge event |
+| E8 | Acceptance criteria for the feature/change are documented in the Paperclip issue | Checkout Charlie (manual check) |
+
+**If any entry criterion is not met**, UAT is blocked. Checkout Charlie must comment on the Paperclip issue specifying which criteria failed and assign back to the responsible party.
+
+---
+
+## 3. UAT Exit Criteria
+
+UAT is **complete** only when ALL of the following are satisfied. Rollback Rhonda verifies these before signing off.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| X1 | All 10 critical user journeys (J1-J10) have been executed | Rollback Rhonda (full regression) |
+| X2 | Zero open S1 (Critical) defects | Defect tracker |
+| X3 | Zero open S2 (High) defects, OR CTO has granted a documented exception | Defect tracker + CTO sign-off |
+| X4 | All S3/S4 defects are logged and triaged (not necessarily fixed) | Defect tracker |
+| X5 | 100% test execution rate -- every test case was run, none skipped | Rollback Rhonda's UAT report |
+| X6 | Accessibility scan (axe-core) reports zero critical violations | Automated in E2E suite |
+| X7 | Lighthouse performance score >= 50, accessibility score >= 90 | Lighthouse CI |
+| X8 | Written sign-off from Rollback Rhonda confirming all criteria met | Paperclip comment on issue |
+
+**If any exit criterion is not met**, the release is blocked. Rollback Rhonda must:
+1. File defects for all failures using the Defect Report Template above.
+2. Comment on the Paperclip issue specifying which exit criteria failed.
+3. Assign back to CTO for triage and redistribution.
+
+---
+
+## 4. UAT Execution Procedure
+
+### 4.1 Pre-UAT (Checkout Charlie)
+
+1. Verify all entry criteria (E1-E8) are met.
+2. Comment on the Paperclip issue: "UAT gate open -- all entry criteria verified."
+3. Assign to Rollback Rhonda with status todo.
+
+### 4.2 UAT Execution (Rollback Rhonda)
+
+1. **Full regression run** -- execute ALL 10 user journeys against cartsnitch.dev.farh.net. No partial runs. No exceptions.
+2. For each journey, verify:
+   - All interactive elements respond correctly (buttons, forms, links, toggles)
+   - State transitions are correct (auth state, data mutations, navigation)
+   - Error states are handled gracefully (invalid input, network failures)
+   - Accessibility scan passes (axe-core integrated in Playwright)
+3. Log results for each journey: PASS / FAIL with details.
+4. File defects immediately for any failures.
+5. Complete the UAT report with execution results.
+
+### 4.3 Post-UAT Sign-Off
+
+1. If all exit criteria (X1-X8) are met:
+   - Rollback Rhonda posts sign-off comment: "UAT PASSED -- all exit criteria met."
+   - Production promotion is automated via Flux on UAT pass.
+2. If any exit criterion fails:
+   - Rollback Rhonda posts failure comment with specific failures.
+   - CTO triages defects and redistributes to engineers.
+   - After fixes are merged, UAT restarts from 4.1 (full cycle).
+
+---
+
+## 5. Critical User Journeys Reference
+
+| ID | Journey | Key Interactions |
+|----|---------|-----------------|
+| J1 | Registration -> Login -> Dashboard | Form submission, auth state, redirect |
+| J2 | Login -> Browse Products -> View Detail -> Price Chart | Search, navigation, data visualization |
+| J3 | Login -> Purchases -> Purchase Detail -> Product Link | List navigation, detail view, cross-linking |
+| J4 | Login -> Connect Store Account -> Verify Connection | OAuth flow, external integration |
+| J5 | Login -> Create Price Alert -> View -> Delete Alert | CRUD operations, confirmation dialogs |
+| J6 | Login -> Browse Coupons -> Copy Code | Clipboard interaction, toast feedback |
+| J7 | Login -> Settings -> Toggle Preferences -> Sign Out | Checkbox toggles, theme switch, session termination |
+| J8 | Login -> Store Comparison -> Compare Prices | Data comparison, sorting, price display |
+| J9 | Forgot Password Flow | Email input, validation, redirect |
+| J10 | Unauth Access -> Redirect to Login | Route protection, redirect behavior |
+
+---
+
+## 6. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-30 | Savannah Savings | Initial runbook -- defect taxonomy, entry/exit criteria, execution procedure |
+
@@ -0,0 +1,12 @@
+import { test as base, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+export const test = base.extend<{ axeCheck: void }>({
+  axeCheck: [async ({ page }, use) => {
+    await use();
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  }, { auto: true }],
+});
+
+export { expect } from "@playwright/test";
@@ -0,0 +1,56 @@
+import { test, expect } from '@playwright/test';
+
+const uniqueEmail = () => `betty+e2e-${Date.now()}@cartsnitch.test`;
+
+test.describe('J1: Registration and Login', () => {
+  test('can register a new account and lands on dashboard', async ({ page }) => {
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Betty Tester');
+    await page.fill('[placeholder="Email"]', uniqueEmail());
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    // With VITE_MOCK_AUTH=true the app navigates to "/" on success
+    await expect(page).toHaveURL('http://localhost:5173/');
+    await expect(page.getByRole('heading', { name: /cart/i })).toBeVisible();
+  });
+
+  test('shows validation error when registration fields are empty', async ({ page }) => {
+    await page.goto('/register');
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator('.bg-red-50')).toContainText('Please fill in all fields');
+  });
+
+  test('can navigate from register to login', async ({ page }) => {
+    await page.goto('/register');
+    await page.getByRole('link', { name: /sign in/i }).click();
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('can sign in with credentials and land on dashboard', async ({ page }) => {
+    // Register first so we have a real account
+    const email = uniqueEmail();
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Login Betty');
+    await page.fill('[placeholder="Email"]', email);
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('http://localhost:5173/');
+
+    // Sign out by clearing the mock session (reload with no session)
+    await page.goto('/');
+    await page.reload();
+
+    // Now sign in
+    await page.goto('/login');
+    await page.fill('[placeholder="Email"]', email);
+    await page.fill('[placeholder="Password"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL('http://localhost:5173/');
+  });
+
+});
@@ -0,0 +1,49 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('J8: Unauthenticated Access', () => {
+  test('redirects /dashboard (/) to /login when not authenticated', async ({ page }) => {
+    // No session cookie — start fresh
+    await page.context().clearCookies();
+    await page.goto('/');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /purchases to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/purchases');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /products to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/products');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /coupons to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/coupons');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('shows loading spinner while auth session is pending', async ({ page }) => {
+    // Intercept but don't respond — session stays pending
+    await page.context().clearCookies();
+    await page.request.fetch('/api/auth/session', {
+      method: 'GET',
+    });
+
+    // Just navigate to a protected route — ProtectedRoute will show spinner while session is pending
+    await page.goto('/purchases');
+    // Spinner is visible briefly; once resolved, should redirect to login
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+  });
+});
@@ -0,0 +1,8 @@
+import { test, expect } from './fixtures';
+
+test('app loads', async ({ page }) => {
+  await page.goto('/');
+  // Unauthenticated users are redirected to /login
+  await expect(page).toHaveURL(/\/login/);
+  await expect(page.getByRole('heading', { name: /CartSnitch/i })).toBeVisible();
+});
@@ -0,0 +1,19 @@
+{
+  "ci": {
+    "collect": {
+      "staticDistDir": "./dist",
+      "url": ["http://localhost:4173/"],
+      "numberOfRuns": 1
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.7 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.8 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}
@@ -9,10 +9,13 @@
    "lint": "eslint .",
    "preview": "vite preview",
    "test": "NODE_ENV=test vitest run",
-    "test:watch": "NODE_ENV=test vitest"
+    "test:watch": "NODE_ENV=test vitest",
+    "test:e2e": "npx playwright test"
  },
  "dependencies": {
    "@tanstack/react-query": "^5.0.0",
+    "better-auth": "^1.2.0",
+    "picomatch": "4.0.4",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^7.0.0",
@@ -20,24 +23,33 @@
    "zustand": "^5.0.0"
  },
  "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
    "@eslint/js": "^9.39.4",
+    "@playwright/test": "^1.58.2",
    "@tailwindcss/vite": "^4.0.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.3.2",
    "@types/node": "^24.12.0",
    "@types/react": "^18.3.28",
    "@types/react-dom": "^18.3.7",
-    "@vitejs/plugin-react": "^4.5.2",
+    "@vitejs/plugin-react": "^4.7.0",
    "eslint": "^9.39.4",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.5.2",
    "globals": "^17.4.0",
    "jsdom": "^25.0.1",
+    "msw": "^2.12.14",
+    "playwright": "^1.58.2",
    "tailwindcss": "^4.0.0",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.56.1",
    "vite": "^6.3.5",
    "vite-plugin-pwa": "^0.21.2",
    "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "@rollup/pluginutils": "5.3.0",
+    "flatted": "^3.4.2",
+    "serialize-javascript": "7.0.5"
  }
 }
@@ -0,0 +1,19 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'VITE_MOCK_AUTH=true npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:5173',
+  },
+});
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://cartsnitch.com/sitemap.xml
@@ -1,168 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/receiptwitness
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install ruff
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-
-  typecheck:
-    runs-on: runners-cartsnitch
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]" mypy
-      - name: Type check
-        run: mypy src/receiptwitness
-
-  test:
-    runs-on: runners-cartsnitch
-    services:
-      postgres:
-        image: postgres:15-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        env:
-          POSTGRES_USER: cartsnitch
-          POSTGRES_PASSWORD: cartsnitch_test
-          POSTGRES_DB: cartsnitch_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      DATABASE_URL: postgresql://cartsnitch:cartsnitch_test@localhost:5432/cartsnitch_test
-      REDIS_URL: redis://localhost:6379/0
-      ENCRYPTION_KEY: dGVzdC1lbmNyeXB0aW9uLWtleS0xMjM0NTY3ODk=
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]"
-      - name: Install Playwright browsers
-        run: playwright install chromium --with-deps
-      - name: Run tests
-        run: pytest --tb=short -q
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"
@@ -3,24 +3,21 @@ FROM python:3.12-slim AS build

 WORKDIR /app

-# git is required to install cartsnitch-common from GitHub; build-essential and
-# libpq-dev are needed to compile any C-extension wheels (e.g. psycopg2 fallback)
+# build-essential and libpq-dev are needed to compile any C-extension wheels
+# (e.g. psycopg2 fallback).  No git needed — common/ is copied from the repo root.
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    git \
    libpq-dev \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

-COPY pyproject.toml ./
-COPY src/ ./src/
+# Build context is the repo root.  These paths are relative to the root.
+COPY receiptwitness/pyproject.toml ./
+COPY receiptwitness/src/ ./src/
+COPY common/ ./common/

-# cartsnitch-common is not on PyPI — install it directly from GitHub, then
-# install the rest of the package dependencies in a single resolver pass so
-# pip can satisfy the cartsnitch-common>=0.1.0 constraint declared in
-# pyproject.toml without hitting PyPI for it.
-RUN pip install --no-cache-dir --prefix=/install \
-    "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b" \
-    .
+# Install from the local common/ (cartsnitch-common>=0.1.0 in pyproject.toml
+# will be satisfied by the local package) then install receiptwitness itself.
+RUN pip install --no-cache-dir --prefix=/install ./common/ .

 # Stage 2: Production image with Playwright + Chromium
 FROM python:3.12-slim AS prod
@@ -51,7 +48,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN adduser --system --group --uid 1000 app

 COPY --from=build /install /usr/local
-COPY src/ ./src/
+COPY receiptwitness/src/ ./src/

 # Install Playwright Chromium browser (runs as root; /opt/playwright is world-readable)
 RUN PLAYWRIGHT_BROWSERS_PATH=/opt/playwright playwright install chromium
@@ -1,17 +1,17 @@
-import { render, screen } from '@testing-library/react'
-import { describe, it, expect } from 'vitest'
-import App from './App.tsx'
-
-describe('App', () => {
-  it('renders the dashboard on the root route', () => {
-    render(<App />)
-    expect(screen.getByText('CartSnitch')).toBeInTheDocument()
-  })
-
-  it('renders the bottom navigation', () => {
-    render(<App />)
-    expect(screen.getByText('Home')).toBeInTheDocument()
-    expect(screen.getByText('Purchases')).toBeInTheDocument()
-    expect(screen.getByText('Products')).toBeInTheDocument()
-  })
-})
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import App from './App.tsx'
+
+vi.mock('./lib/auth-client.ts', () => ({
+  authClient: {
+    useSession: () => ({ data: null, isPending: false }),
+  },
+}))
+
+describe('App', () => {
+  it('redirects unauthenticated users to login', () => {
+    render(<App />)
+    expect(screen.getByText('CartSnitch')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument()
+  })
+})
@@ -31,8 +31,8 @@ export default function App() {
      <BrowserRouter>
        <Routes>
          <Route element={<Layout />}>
-            <Route index element={<Dashboard />} />
            <Route element={<ProtectedRoute />}>
+              <Route index element={<Dashboard />} />
              <Route path="purchases" element={<Purchases />} />
              <Route path="purchases/:id" element={<PurchaseDetail />} />
              <Route path="products" element={<Products />} />
@@ -1,10 +1,35 @@
+import { useEffect } from 'react'
 import { Navigate, Outlet } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
 import { useAuthStore } from '../stores/auth.ts'

 export function ProtectedRoute() {
+  const isMockAuth = import.meta.env.VITE_MOCK_AUTH === 'true'
+  const { data: session, isPending } = authClient.useSession()
  const isAuthenticated = useAuthStore((s) => s.isAuthenticated)
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)

-  if (!isAuthenticated) {
+  useEffect(() => {
+    if (!isMockAuth) {
+      setAuthenticated(!!session)
+    }
+  }, [session, setAuthenticated, isMockAuth])
+
+  // In mock auth mode, rely on Zustand store (set by Login/Register pages)
+  if (isMockAuth) {
+    if (!isAuthenticated) return <Navigate to="/login" replace />
+    return <Outlet />
+  }
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="h-8 w-8 animate-spin rounded-full border-2 border-brand-blue border-t-transparent" />
+      </div>
+    )
+  }
+
+  if (!session) {
    return <Navigate to="/login" replace />
  }

@@ -0,0 +1,45 @@
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { usePurchases } from '../useApi'
+import { http, HttpResponse } from 'msw'
+import { server } from '../../test/mocks/server'
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    )
+  }
+}
+
+describe('useApi hooks', () => {
+  describe('usePurchases', () => {
+    it('fetches and returns purchases', async () => {
+      const { result } = renderHook(() => usePurchases(), { wrapper: createWrapper() })
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+      expect(result.current.data).toHaveLength(1)
+      expect(result.current.data![0]).toMatchObject({
+        id: 'pur_1',
+        storeName: 'Kroger',
+        total: 42.5,
+      })
+    })
+
+    it('returns an error when the endpoint fails', async () => {
+      server.use(
+        http.get('/api/v1/purchases', () => HttpResponse.error()),
+      )
+
+      const { result } = renderHook(() => usePurchases(), { wrapper: createWrapper() })
+
+      await waitFor(() => expect(result.current.isError).toBe(true))
+    })
+  })
+})
@@ -1,100 +1,98 @@
-import { useAuthStore } from '../stores/auth.ts'
-import {
-  mockPurchases,
-  mockProducts,
-  mockCoupons,
-  mockAlerts,
-  getMockPriceHistory,
-} from './mock-data.ts'
-
-const API_BASE = import.meta.env.VITE_API_URL ?? '/api/v1'
-const USE_MOCK = import.meta.env.VITE_MOCK_API === 'true'
-
-// Mock response lookup table
-const mockRoutes: Record<string, (path: string) => unknown> = {
-  '/purchases': () => mockPurchases,
-  '/products': () => mockProducts,
-  '/coupons': () => mockCoupons,
-  '/price-alerts': () => mockAlerts,
-}
-
-function matchMockRoute<T>(path: string): T | null {
-  // Exact match
-  if (mockRoutes[path]) return mockRoutes[path](path) as T
-
-  // /purchases/:id
-  const purchaseMatch = path.match(/^\/purchases\/(.+)$/)
-  if (purchaseMatch) {
-    const purchase = mockPurchases.find((p) => p.id === purchaseMatch[1])
-    return (purchase ?? null) as T
-  }
-
-  // /products/:id/price-history
-  const priceHistoryMatch = path.match(/^\/products\/(.+)\/price-history$/)
-  if (priceHistoryMatch) {
-    return getMockPriceHistory(priceHistoryMatch[1]) as T
-  }
-
-  // /products?q=search or /products/:id
-  const productMatch = path.match(/^\/products\/(.+)$/)
-  if (productMatch) {
-    const product = mockProducts.find((p) => p.id === productMatch[1])
-    return (product ?? null) as T
-  }
-
-  const productsSearch = path.match(/^\/products\?q=(.+)$/)
-  if (productsSearch) {
-    const q = decodeURIComponent(productsSearch[1]).toLowerCase()
-    return mockProducts.filter(
-      (p) =>
-        p.name.toLowerCase().includes(q) ||
-        p.brand.toLowerCase().includes(q) ||
-        p.category.toLowerCase().includes(q),
-    ) as T
-  }
-
-  return null
-}
-
-async function apiFetch<T>(path: string, options?: RequestInit): Promise<T> {
-  // Mock interceptor: return mock data without hitting the network
-  if (USE_MOCK && (!options?.method || options.method === 'GET')) {
-    const mockResult = matchMockRoute<T>(path)
-    if (mockResult !== null) {
-      // Simulate network delay for realistic loading states
-      await new Promise((r) => setTimeout(r, 300))
-      return mockResult
-    }
-  }
-
-  const token = useAuthStore.getState().token
-
-  const res = await fetch(`${API_BASE}${path}`, {
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...(token ? { Authorization: `Bearer ${token}` } : {}),
-      ...options?.headers,
-    },
-  })
-
-  if (res.status === 401) {
-    useAuthStore.getState().logout()
-    throw new Error('Unauthorized')
-  }
-
-  if (!res.ok) {
-    throw new Error(`API error: ${res.status}`)
-  }
-
-  return res.json() as Promise<T>
-}
-
-export const api = {
-  get: <T>(path: string) => apiFetch<T>(path),
-  post: <T>(path: string, body: unknown) =>
-    apiFetch<T>(path, { method: 'POST', body: JSON.stringify(body) }),
-  put: <T>(path: string, body: unknown) =>
-    apiFetch<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
-  delete: <T>(path: string) => apiFetch<T>(path, { method: 'DELETE' }),
-}
+import { useAuthStore } from '../stores/auth.ts'
+import {
+  mockPurchases,
+  mockProducts,
+  mockCoupons,
+  mockAlerts,
+  getMockPriceHistory,
+} from './mock-data.ts'
+
+const API_BASE = import.meta.env.VITE_API_URL ?? '/api/v1'
+const USE_MOCK = import.meta.env.VITE_MOCK_API === 'true'
+
+// Mock response lookup table
+const mockRoutes: Record<string, (path: string) => unknown> = {
+  '/purchases': () => mockPurchases,
+  '/products': () => mockProducts,
+  '/coupons': () => mockCoupons,
+  '/price-alerts': () => mockAlerts,
+}
+
+function matchMockRoute<T>(path: string): T | null {
+  // Exact match
+  if (mockRoutes[path]) return mockRoutes[path](path) as T
+
+  // /purchases/:id
+  const purchaseMatch = path.match(/^\/purchases\/(.+)$/)
+  if (purchaseMatch) {
+    const purchase = mockPurchases.find((p) => p.id === purchaseMatch[1])
+    return (purchase ?? null) as T
+  }
+
+  // /products/:id/price-history
+  const priceHistoryMatch = path.match(/^\/products\/(.+)\/price-history$/)
+  if (priceHistoryMatch) {
+    return getMockPriceHistory(priceHistoryMatch[1]) as T
+  }
+
+  // /products/:id
+  const productMatch = path.match(/^\/products\/(.+)$/)
+  if (productMatch) {
+    const product = mockProducts.find((p) => p.id === productMatch[1])
+    return (product ?? null) as T
+  }
+
+  const productsSearch = path.match(/^\/products\?q=(.+)$/)
+  if (productsSearch) {
+    const q = decodeURIComponent(productsSearch[1]).toLowerCase()
+    return mockProducts.filter(
+      (p) =>
+        p.name.toLowerCase().includes(q) ||
+        p.brand.toLowerCase().includes(q) ||
+        p.category.toLowerCase().includes(q),
+    ) as T
+  }
+
+  return null
+}
+
+async function apiFetch<T>(path: string, options?: RequestInit): Promise<T> {
+  // Mock interceptor: return mock data without hitting the network
+  if (USE_MOCK && (!options?.method || options.method === 'GET')) {
+    const mockResult = matchMockRoute<T>(path)
+    if (mockResult !== null) {
+      // Simulate network delay for realistic loading states
+      await new Promise((r) => setTimeout(r, 300))
+      return mockResult
+    }
+  }
+
+  const res = await fetch(`${API_BASE}${path}`, {
+    ...options,
+    credentials: 'include', // Send Better-Auth session cookie
+    headers: {
+      'Content-Type': 'application/json',
+      ...options?.headers,
+    },
+  })
+
+  if (res.status === 401) {
+    useAuthStore.getState().setAuthenticated(false)
+    throw new Error('Unauthorized')
+  }
+
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status}`)
+  }
+
+  return res.json() as Promise<T>
+}
+
+export const api = {
+  get: <T>(path: string) => apiFetch<T>(path),
+  post: <T>(path: string, body: unknown) =>
+    apiFetch<T>(path, { method: 'POST', body: JSON.stringify(body) }),
+  put: <T>(path: string, body: unknown) =>
+    apiFetch<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
+  delete: <T>(path: string) => apiFetch<T>(path, { method: 'DELETE' }),
+}
@@ -0,0 +1,36 @@
+import { createAuthClient } from "better-auth/react"
+import type { BetterFetchPlugin } from "@better-fetch/fetch"
+
+/**
+ * Maps 'name' -> 'display_name' in register requests to match the API's RegisterRequest schema.
+ */
+const displayNameMapper: BetterFetchPlugin = {
+  id: "display-name-mapper",
+  name: "display-name-mapper",
+  hooks: {
+    onRequest: async (context) => {
+      const url = typeof context.url === "string" ? context.url : context.url.pathname
+      if (
+        url.endsWith("/auth/register") &&
+        context.method === "POST" &&
+        context.body &&
+        "name" in context.body
+      ) {
+        context.body = {
+          ...context.body,
+          display_name: context.body.name as string,
+          name: undefined,
+        }
+      }
+      return context
+    },
+  },
+}
+
+export const authClient = createAuthClient({
+  baseURL: import.meta.env.VITE_AUTH_URL || "",
+  basePath: "/auth",
+  fetchPlugins: [displayNameMapper],
+})
+
+export const { useSession, signIn, signUp, signOut } = authClient
@@ -1,197 +1,201 @@
-import React, { Suspense } from 'react'
-import { Link } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { usePurchases, usePriceAlerts, usePriceHistory } from '../hooks/useApi.ts'
-import { StoreIcon } from '../components/StoreIcon.tsx'
-
-const LazySparklineCard = React.lazy(() =>
-  import('../components/SparklineChart.tsx').then((mod) => ({ default: mod.SparklineCard }))
-)
-
-export function Dashboard() {
-  const user = useAuthStore((s) => s.user)
-  const isAuthenticated = useAuthStore((s) => s.isAuthenticated)
-
-  if (!isAuthenticated) {
-    return (
-      <div className="py-8 text-center">
-        <h1 className="text-2xl font-bold text-gray-900">CartSnitch</h1>
-        <p className="mt-2 text-sm text-gray-500">Track prices. Save money.</p>
-        <div className="mt-8 space-y-3">
-          <Link
-            to="/login"
-            className="block min-h-12 rounded-xl bg-brand-blue px-4 py-3 text-center text-base font-medium text-white active:bg-brand-blue/90"
-          >
-            Sign In
-          </Link>
-          <Link
-            to="/register"
-            className="block min-h-12 rounded-xl border border-gray-200 px-4 py-3 text-center text-base font-medium text-gray-700 active:bg-gray-50"
-          >
-            Create Account
-          </Link>
-        </div>
-      </div>
-    )
-  }
-
-  return <AuthenticatedDashboard userName={user?.name ?? 'there'} />
-}
-
-function AuthenticatedDashboard({ userName }: { userName: string }) {
-  const { data: purchases = [], isLoading: purchasesLoading } = usePurchases()
-  const { data: alerts = [], isLoading: alertsLoading } = usePriceAlerts()
-  const { data: eggHistory = [] } = usePriceHistory('prod10')
-  const { data: milkHistory = [] } = usePriceHistory('prod1')
-
-  const triggeredAlerts = alerts.filter((a) => a.triggered)
-  const watchingAlerts = alerts.filter((a) => !a.triggered)
-  const recentPurchases = purchases.slice(0, 3)
-
-  const sparklineData = eggHistory.filter((p) => p.storeId === 'meijer').slice(-8)
-  const milkSparkline = milkHistory.filter((p) => p.storeId === 'kroger').slice(-8)
-
-  const eggCurrent = sparklineData.length > 0 ? `$${sparklineData[sparklineData.length - 1].price.toFixed(2)}` : '—'
-  const milkCurrent = milkSparkline.length > 0 ? `$${milkSparkline[milkSparkline.length - 1].price.toFixed(2)}` : '—'
-
-  if (purchasesLoading || alertsLoading) {
-    return <DashboardSkeleton />
-  }
-
-  return (
-    <div>
-      <h1 className="text-2xl font-bold text-gray-900">
-        Hi, {userName.split(' ')[0]}
-      </h1>
-
-      {/* Triggered alerts banner */}
-      {triggeredAlerts.length > 0 && (
-        <Link
-          to="/alerts"
-          className="mt-4 flex items-center gap-3 rounded-xl bg-green-50 p-4"
-        >
-          <span className="flex h-10 w-10 items-center justify-center rounded-full bg-green-500 text-lg text-white">
-            &#x2713;
-          </span>
-          <div>
-            <p className="text-sm font-semibold text-green-800">
-              {triggeredAlerts.length} price {triggeredAlerts.length === 1 ? 'alert' : 'alerts'} triggered!
-            </p>
-            <p className="text-xs text-green-700">
-              {triggeredAlerts.map((a) => a.productName).join(', ')}
-            </p>
-          </div>
-        </Link>
-      )}
-
-      {/* Quick stats */}
-      <div className="mt-4 grid grid-cols-2 gap-3">
-        <div className="rounded-xl bg-white p-4 shadow-sm">
-          <p className="text-xs font-medium text-gray-500">Watching</p>
-          <p className="mt-1 text-2xl font-bold text-gray-900">{watchingAlerts.length}</p>
-          <p className="text-xs text-gray-400">price alerts</p>
-        </div>
-        <div className="rounded-xl bg-white p-4 shadow-sm">
-          <p className="text-xs font-medium text-gray-500">This Month</p>
-          <p className="mt-1 text-2xl font-bold text-gray-900">
-            ${recentPurchases.reduce((sum, p) => sum + p.total, 0).toFixed(0)}
-          </p>
-          <p className="text-xs text-gray-400">grocery spend</p>
-        </div>
-      </div>
-
-      {/* Price trend sparklines */}
-      <section className="mt-6">
-        <h2 className="mb-3 text-lg font-semibold text-gray-700">Price Trends</h2>
-        <div className="space-y-3">
-          <Suspense fallback={<SparklinePlaceholder />}>
-            <LazySparklineCard label="Eggs (dozen)" data={sparklineData} current={eggCurrent} />
-            <LazySparklineCard label="Whole Milk (1 gal)" data={milkSparkline} current={milkCurrent} />
-          </Suspense>
-        </div>
-      </section>
-
-      {/* Recent purchases */}
-      <section className="mt-6">
-        <div className="flex items-center justify-between">
-          <h2 className="text-lg font-semibold text-gray-700">Recent Purchases</h2>
-          <Link to="/purchases" className="text-sm text-brand-blue">
-            View all
-          </Link>
-        </div>
-        <div className="mt-3 space-y-3">
-          {recentPurchases.map((purchase) => (
-            <Link
-              key={purchase.id}
-              to={`/purchases/${purchase.id}`}
-              className="flex items-center gap-3 rounded-xl bg-white p-4 shadow-sm active:bg-gray-50"
-            >
-              <StoreIcon storeId={purchase.storeId} />
-              <div className="min-w-0 flex-1">
-                <p className="text-sm font-medium text-gray-900">{purchase.storeName}</p>
-                <p className="text-xs text-gray-500">
-                  {new Date(purchase.date).toLocaleDateString('en-US', {
-                    month: 'short',
-                    day: 'numeric',
-                  })}{' '}
-                  &middot; {purchase.items.length} items
-                </p>
-              </div>
-              <span className="text-sm font-semibold text-gray-900">
-                ${purchase.total.toFixed(2)}
-              </span>
-            </Link>
-          ))}
-        </div>
-      </section>
-
-      {/* Quick actions */}
-      <section className="mt-6 pb-4">
-        <h2 className="mb-3 text-lg font-semibold text-gray-700">Quick Actions</h2>
-        <div className="grid grid-cols-2 gap-3">
-          <Link
-            to="/products"
-            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
-          >
-            Compare Prices
-          </Link>
-          <Link
-            to="/settings"
-            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
-          >
-            Link a Store
-          </Link>
-        </div>
-      </section>
-    </div>
-  )
-}
-
-function DashboardSkeleton() {
-  return (
-    <div className="animate-pulse">
-      <div className="h-8 w-40 rounded bg-gray-200" />
-      <div className="mt-4 grid grid-cols-2 gap-3">
-        <div className="h-24 rounded-xl bg-gray-200" />
-        <div className="h-24 rounded-xl bg-gray-200" />
-      </div>
-      <div className="mt-6 h-5 w-28 rounded bg-gray-200" />
-      <div className="mt-3 space-y-3">
-        <div className="h-16 rounded-xl bg-gray-200" />
-        <div className="h-16 rounded-xl bg-gray-200" />
-      </div>
-    </div>
-  )
-}
-
-function SparklinePlaceholder() {
-  return (
-    <div className="flex items-center gap-4 rounded-xl bg-white p-4 shadow-sm animate-pulse">
-      <div className="min-w-0 flex-1">
-        <div className="h-4 w-24 rounded bg-gray-200" />
-        <div className="mt-2 h-6 w-16 rounded bg-gray-200" />
-      </div>
-      <div className="h-10 w-24 rounded bg-gray-100" />
-    </div>
-  )
-}
+import React, { Suspense } from 'react'
+import { Link } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { usePurchases, usePriceAlerts, usePriceHistory } from '../hooks/useApi.ts'
+import { StoreIcon } from '../components/StoreIcon.tsx'
+
+const LazySparklineCard = React.lazy(() =>
+  import('../components/SparklineChart.tsx').then((mod) => ({ default: mod.SparklineCard }))
+)
+
+export function Dashboard() {
+  const { data: session, isPending } = authClient.useSession()
+
+  if (isPending) {
+    return <DashboardSkeleton />
+  }
+
+  if (!session) {
+    return (
+      <div className="py-8 text-center">
+        <h1 className="text-2xl font-bold text-gray-900">CartSnitch</h1>
+        <p className="mt-2 text-sm text-gray-500">Track prices. Save money.</p>
+        <div className="mt-8 space-y-3">
+          <Link
+            to="/login"
+            className="block min-h-12 rounded-xl bg-brand-blue px-4 py-3 text-center text-base font-medium text-white active:bg-brand-blue/90"
+          >
+            Sign In
+          </Link>
+          <Link
+            to="/register"
+            className="block min-h-12 rounded-xl border border-gray-200 px-4 py-3 text-center text-base font-medium text-gray-700 active:bg-gray-50"
+          >
+            Create Account
+          </Link>
+        </div>
+      </div>
+    )
+  }
+
+  return <AuthenticatedDashboard userName={session.user?.name ?? 'there'} />
+}
+
+function AuthenticatedDashboard({ userName }: { userName: string }) {
+  const { data: purchases = [], isLoading: purchasesLoading } = usePurchases()
+  const { data: alerts = [], isLoading: alertsLoading } = usePriceAlerts()
+  const { data: eggHistory = [] } = usePriceHistory('prod10')
+  const { data: milkHistory = [] } = usePriceHistory('prod1')
+
+  const triggeredAlerts = alerts.filter((a) => a.triggered)
+  const watchingAlerts = alerts.filter((a) => !a.triggered)
+  const recentPurchases = purchases.slice(0, 3)
+
+  const sparklineData = eggHistory.filter((p) => p.storeId === 'meijer').slice(-8)
+  const milkSparkline = milkHistory.filter((p) => p.storeId === 'kroger').slice(-8)
+
+  const eggCurrent = sparklineData.length > 0 ? `$${sparklineData[sparklineData.length - 1].price.toFixed(2)}` : '—'
+  const milkCurrent = milkSparkline.length > 0 ? `$${milkSparkline[milkSparkline.length - 1].price.toFixed(2)}` : '—'
+
+  if (purchasesLoading || alertsLoading) {
+    return <DashboardSkeleton />
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold text-gray-900">
+        Hi, {userName.split(' ')[0]}
+      </h1>
+
+      {/* Triggered alerts banner */}
+      {triggeredAlerts.length > 0 && (
+        <Link
+          to="/alerts"
+          className="mt-4 flex items-center gap-3 rounded-xl bg-green-50 p-4"
+        >
+          <span className="flex h-10 w-10 items-center justify-center rounded-full bg-green-500 text-lg text-white">
+            &#x2713;
+          </span>
+          <div>
+            <p className="text-sm font-semibold text-green-800">
+              {triggeredAlerts.length} price {triggeredAlerts.length === 1 ? 'alert' : 'alerts'} triggered!
+            </p>
+            <p className="text-xs text-green-700">
+              {triggeredAlerts.map((a) => a.productName).join(', ')}
+            </p>
+          </div>
+        </Link>
+      )}
+
+      {/* Quick stats */}
+      <div className="mt-4 grid grid-cols-2 gap-3">
+        <div className="rounded-xl bg-white p-4 shadow-sm">
+          <p className="text-xs font-medium text-gray-500">Watching</p>
+          <p className="mt-1 text-2xl font-bold text-gray-900">{watchingAlerts.length}</p>
+          <p className="text-xs text-gray-400">price alerts</p>
+        </div>
+        <div className="rounded-xl bg-white p-4 shadow-sm">
+          <p className="text-xs font-medium text-gray-500">This Month</p>
+          <p className="mt-1 text-2xl font-bold text-gray-900">
+            ${recentPurchases.reduce((sum, p) => sum + p.total, 0).toFixed(0)}
+          </p>
+          <p className="text-xs text-gray-400">grocery spend</p>
+        </div>
+      </div>
+
+      {/* Price trend sparklines */}
+      <section className="mt-6">
+        <h2 className="mb-3 text-lg font-semibold text-gray-700">Price Trends</h2>
+        <div className="space-y-3">
+          <Suspense fallback={<SparklinePlaceholder />}>
+            <LazySparklineCard label="Eggs (dozen)" data={sparklineData} current={eggCurrent} />
+            <LazySparklineCard label="Whole Milk (1 gal)" data={milkSparkline} current={milkCurrent} />
+          </Suspense>
+        </div>
+      </section>
+
+      {/* Recent purchases */}
+      <section className="mt-6">
+        <div className="flex items-center justify-between">
+          <h2 className="text-lg font-semibold text-gray-700">Recent Purchases</h2>
+          <Link to="/purchases" className="text-sm text-brand-blue">
+            View all
+          </Link>
+        </div>
+        <div className="mt-3 space-y-3">
+          {recentPurchases.map((purchase) => (
+            <Link
+              key={purchase.id}
+              to={`/purchases/${purchase.id}`}
+              className="flex items-center gap-3 rounded-xl bg-white p-4 shadow-sm active:bg-gray-50"
+            >
+              <StoreIcon storeId={purchase.storeId} />
+              <div className="min-w-0 flex-1">
+                <p className="text-sm font-medium text-gray-900">{purchase.storeName}</p>
+                <p className="text-xs text-gray-500">
+                  {new Date(purchase.date).toLocaleDateString('en-US', {
+                    month: 'short',
+                    day: 'numeric',
+                  })}{' '}
+                  &middot; {purchase.items.length} items
+                </p>
+              </div>
+              <span className="text-sm font-semibold text-gray-900">
+                ${purchase.total.toFixed(2)}
+              </span>
+            </Link>
+          ))}
+        </div>
+      </section>
+
+      {/* Quick actions */}
+      <section className="mt-6 pb-4">
+        <h2 className="mb-3 text-lg font-semibold text-gray-700">Quick Actions</h2>
+        <div className="grid grid-cols-2 gap-3">
+          <Link
+            to="/products"
+            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
+          >
+            Compare Prices
+          </Link>
+          <Link
+            to="/settings"
+            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
+          >
+            Link a Store
+          </Link>
+        </div>
+      </section>
+    </div>
+  )
+}
+
+function DashboardSkeleton() {
+  return (
+    <div className="animate-pulse">
+      <h1 className="sr-only">Loading CartSnitch…</h1>
+      <div className="h-8 w-40 rounded bg-gray-200" />
+      <div className="mt-4 grid grid-cols-2 gap-3">
+        <div className="h-24 rounded-xl bg-gray-200" />
+        <div className="h-24 rounded-xl bg-gray-200" />
+      </div>
+      <div className="mt-6 h-5 w-28 rounded bg-gray-200" />
+      <div className="mt-3 space-y-3">
+        <div className="h-16 rounded-xl bg-gray-200" />
+        <div className="h-16 rounded-xl bg-gray-200" />
+      </div>
+    </div>
+  )
+}
+
+function SparklinePlaceholder() {
+  return (
+    <div className="flex items-center gap-4 rounded-xl bg-white p-4 shadow-sm animate-pulse">
+      <div className="min-w-0 flex-1">
+        <div className="h-4 w-24 rounded bg-gray-200" />
+        <div className="mt-2 h-6 w-16 rounded bg-gray-200" />
+      </div>
+      <div className="h-10 w-24 rounded bg-gray-100" />
+    </div>
+  )
+}
@@ -1,92 +1,97 @@
-import { useState } from 'react'
-import { Link, useNavigate } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { api } from '../lib/api.ts'
-import { mockUser } from '../lib/mock-data.ts'
-import type { User } from '../types/api.ts'
-
-export function Login() {
-  const [email, setEmail] = useState('')
-  const [password, setPassword] = useState('')
-  const [error, setError] = useState('')
-  const [loading, setLoading] = useState(false)
-  const navigate = useNavigate()
-  const setAuth = useAuthStore((s) => s.setAuth)
-
-  async function handleSubmit(e: React.FormEvent) {
-    e.preventDefault()
-    setError('')
-
-    if (!email || !password) {
-      setError('Please fill in all fields.')
-      return
-    }
-
-    setLoading(true)
-    try {
-      const res = await api.post<{ user: User; token: string }>('/auth/login', { email, password })
-      setAuth(res.user, res.token)
-      navigate('/')
-    } catch {
-      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
-        // Fallback to mock auth for demo
-        setAuth(mockUser, 'mock-jwt-token')
-        navigate('/')
-      } else {
-        setError('Invalid email or password. Please try again.')
-      }
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center px-4">
-      <h1 className="mb-2 text-3xl font-bold text-gray-900">CartSnitch</h1>
-      <p className="mb-8 text-sm text-gray-500">Track prices. Save money.</p>
-
-      {error && (
-        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
-          {error}
-        </div>
-      )}
-
-      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
-        <input
-          type="email"
-          placeholder="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          autoComplete="email"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="password"
-          placeholder="Password"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          autoComplete="current-password"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <button
-          type="submit"
-          disabled={loading}
-          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
-        >
-          {loading ? 'Signing in...' : 'Sign In'}
-        </button>
-      </form>
-
-      <Link to="/forgot-password" className="mt-4 text-sm text-brand-blue">
-        Forgot password?
-      </Link>
-
-      <p className="mt-6 text-sm text-gray-500">
-        Don't have an account?{' '}
-        <Link to="/register" className="text-brand-blue">
-          Sign up
-        </Link>
-      </p>
-    </div>
-  )
-}
+import { useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { useAuthStore } from '../stores/auth.ts'
+
+export function Login() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    if (!email || !password) {
+      setError('Please fill in all fields.')
+      return
+    }
+
+    setLoading(true)
+    try {
+      const { error: authError } = await authClient.signIn.email({
+        email,
+        password,
+      })
+
+      if (authError) {
+        throw new Error(authError.message ?? 'Sign in failed')
+      }
+
+      setAuthenticated(true)
+      navigate('/')
+    } catch {
+      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
+        setAuthenticated(true)
+        navigate('/')
+      } else {
+        setError('Invalid email or password. Please try again.')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center px-4">
+      <h1 className="mb-2 text-3xl font-bold text-gray-900">CartSnitch</h1>
+      <p className="mb-8 text-sm text-gray-500">Track prices. Save money.</p>
+
+      {error && (
+        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
+          {error}
+        </div>
+      )}
+
+      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          autoComplete="email"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          autoComplete="current-password"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
+        >
+          {loading ? 'Signing in...' : 'Sign In'}
+        </button>
+      </form>
+
+      <Link to="/forgot-password" className="mt-4 text-sm text-brand-blue">
+        Forgot password?
+      </Link>
+
+      <p className="mt-6 text-sm text-gray-500">
+        Don't have an account?{' '}
+        <Link to="/register" className="text-brand-blue underline">
+          Sign up
+        </Link>
+      </p>
+    </main>
+  )
+}
@@ -1,102 +1,108 @@
-import { useState } from 'react'
-import { Link, useNavigate } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { api } from '../lib/api.ts'
-import { mockUser } from '../lib/mock-data.ts'
-import type { User } from '../types/api.ts'
-
-export function Register() {
-  const [name, setName] = useState('')
-  const [email, setEmail] = useState('')
-  const [password, setPassword] = useState('')
-  const [error, setError] = useState('')
-  const [loading, setLoading] = useState(false)
-  const navigate = useNavigate()
-  const setAuth = useAuthStore((s) => s.setAuth)
-
-  async function handleSubmit(e: React.FormEvent) {
-    e.preventDefault()
-    setError('')
-
-    if (!name || !email || !password) {
-      setError('Please fill in all fields.')
-      return
-    }
-
-    if (password.length < 8) {
-      setError('Password must be at least 8 characters.')
-      return
-    }
-
-    setLoading(true)
-    try {
-      const res = await api.post<{ user: User; token: string }>('/auth/register', { name, email, password })
-      setAuth(res.user, res.token)
-      navigate('/')
-    } catch {
-      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
-        // Fallback to mock auth for demo
-        setAuth({ ...mockUser, name, email }, 'mock-jwt-token')
-        navigate('/')
-      } else {
-        setError('Registration failed. Please try again.')
-      }
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center px-4">
-      <h1 className="mb-2 text-3xl font-bold text-gray-900">Create Account</h1>
-      <p className="mb-8 text-sm text-gray-500">Start tracking your grocery prices.</p>
-
-      {error && (
-        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
-          {error}
-        </div>
-      )}
-
-      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
-        <input
-          type="text"
-          placeholder="Full Name"
-          value={name}
-          onChange={(e) => setName(e.target.value)}
-          autoComplete="name"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="email"
-          placeholder="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          autoComplete="email"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="password"
-          placeholder="Password (min. 8 characters)"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          autoComplete="new-password"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <button
-          type="submit"
-          disabled={loading}
-          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
-        >
-          {loading ? 'Creating account...' : 'Create Account'}
-        </button>
-      </form>
-
-      <p className="mt-6 text-sm text-gray-500">
-        Already have an account?{' '}
-        <Link to="/login" className="text-brand-blue">
-          Sign in
-        </Link>
-      </p>
-    </div>
-  )
-}
+import { useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { useAuthStore } from '../stores/auth.ts'
+
+export function Register() {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    if (!name || !email || !password) {
+      setError('Please fill in all fields.')
+      return
+    }
+
+    if (password.length < 8) {
+      setError('Password must be at least 8 characters.')
+      return
+    }
+
+    setLoading(true)
+    try {
+      const { error: authError } = await authClient.signUp.email({
+        name,
+        email,
+        password,
+      })
+
+      if (authError) {
+        throw new Error(authError.message ?? 'Registration failed')
+      }
+
+      setAuthenticated(true)
+      navigate('/')
+    } catch {
+      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
+        setAuthenticated(true)
+        navigate('/')
+      } else {
+        setError('Registration failed. Please try again.')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center px-4">
+      <h1 className="mb-2 text-3xl font-bold text-gray-900">Create Account</h1>
+      <p className="mb-8 text-sm text-gray-500">Start tracking your grocery prices.</p>
+
+      {error && (
+        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
+          {error}
+        </div>
+      )}
+
+      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
+        <input
+          type="text"
+          placeholder="Full Name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          autoComplete="name"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          autoComplete="email"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="password"
+          placeholder="Password (min. 8 characters)"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          autoComplete="new-password"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
+        >
+          {loading ? 'Creating account...' : 'Create Account'}
+        </button>
+      </form>
+
+      <p className="mt-6 text-sm text-gray-500">
+        Already have an account?{' '}
+        <Link to="/login" className="text-brand-blue">
+          Sign in
+        </Link>
+      </p>
+    </div>
+  )
+}
@@ -1,18 +1,21 @@
 import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
 import { useAuthStore } from '../stores/auth.ts'
 import { useThemeStore } from '../stores/theme.ts'
 import { StoreIcon } from '../components/StoreIcon.tsx'

 export function Settings() {
-  const user = useAuthStore((s) => s.user)
-  const logout = useAuthStore((s) => s.logout)
+  const { data: session } = authClient.useSession()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
  const navigate = useNavigate()
  const { theme, setTheme } = useThemeStore()

-  const connectedStores = user?.connectedStores ?? []
+  const user = session?.user
+  const connectedStores: string[] = []

-  function handleSignOut() {
-    logout()
+  async function handleSignOut() {
+    await authClient.signOut()
+    setAuthenticated(false)
    navigate('/login')
  }

@@ -1,27 +1,18 @@
-import { create } from 'zustand'
-import { persist } from 'zustand/middleware'
-import type { User } from '../types/api.ts'
-
-interface AuthState {
-  user: User | null
-  token: string | null
-  isAuthenticated: boolean
-  setAuth: (user: User, token: string) => void
-  logout: () => void
-}
-
-export const useAuthStore = create<AuthState>()(
-  persist(
-    (set) => ({
-      user: null,
-      token: null,
-      isAuthenticated: false,
-      setAuth: (user, token) => set({ user, token, isAuthenticated: true }),
-      logout: () => set({ user: null, token: null, isAuthenticated: false }),
-    }),
-    {
-      name: 'cartsnitch-auth',
-      partialize: (state) => ({ user: state.user, isAuthenticated: state.isAuthenticated }),
-    },
-  ),
-)
+import { create } from 'zustand'
+
+/**
+ * Minimal auth state for UI reactivity.
+ *
+ * Session management is handled by Better-Auth via httpOnly cookies.
+ * This store only tracks whether we have an active session for UI
+ * gating (protected routes, nav state). No tokens in memory or localStorage.
+ */
+interface AuthState {
+  isAuthenticated: boolean
+  setAuthenticated: (value: boolean) => void
+}
+
+export const useAuthStore = create<AuthState>()((set) => ({
+  isAuthenticated: false,
+  setAuthenticated: (value) => set({ isAuthenticated: value }),
+}))
@@ -0,0 +1,65 @@
+import { http, HttpResponse } from 'msw'
+import type { Purchase, Product, Coupon, PriceAlert } from '../../types/api.ts'
+
+const mockPurchases: Purchase[] = [
+  {
+    id: 'pur_1',
+    storeId: 'store_1',
+    storeName: 'Kroger',
+    date: '2024-01-15',
+    total: 42.5,
+    items: [
+      { id: 'item_1', productId: 'prod_1', name: 'Milk', quantity: 1, price: 3.99, unitPrice: 3.99 },
+      { id: 'item_2', productId: 'prod_2', name: 'Bread', quantity: 2, price: 5.98, unitPrice: 2.99 },
+    ],
+  },
+]
+
+const mockProducts: Product[] = [
+  {
+    id: 'prod_1',
+    name: 'Whole Milk',
+    brand: 'Kroger',
+    category: 'Dairy',
+    prices: [{ storeId: 'store_1', storeName: 'Kroger', price: 3.99, lastUpdated: '2024-01-15' }],
+  },
+  {
+    id: 'prod_2',
+    name: 'Whole Wheat Bread',
+    brand: 'Nature\'s Own',
+    category: 'Bakery',
+    prices: [{ storeId: 'store_1', storeName: 'Kroger', price: 2.99, lastUpdated: '2024-01-15' }],
+  },
+]
+
+const mockCoupons: Coupon[] = [
+  {
+    id: 'coupon_1',
+    productId: 'prod_1',
+    storeName: 'Kroger',
+    description: '$1 off milk',
+    discount: '$1.00',
+    expiresAt: '2024-12-31',
+    code: 'MILK1',
+  },
+]
+
+const mockAlerts: PriceAlert[] = [
+  {
+    id: 'alert_1',
+    productId: 'prod_1',
+    productName: 'Whole Milk',
+    targetPrice: 2.99,
+    currentPrice: 3.99,
+    triggered: false,
+  },
+]
+
+export const handlers = [
+  http.get('/api/v1/health', () => HttpResponse.json({ status: 'ok' })),
+  http.get('/api/v1/purchases', () => HttpResponse.json(mockPurchases)),
+  http.get('/api/v1/products', () => HttpResponse.json(mockProducts)),
+  http.get('/api/v1/products/prod_1', () => HttpResponse.json(mockProducts[0])),
+  http.get('/api/v1/coupons', () => HttpResponse.json(mockCoupons)),
+  http.get('/api/v1/price-alerts', () => HttpResponse.json(mockAlerts)),
+]
@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
@@ -1 +1,6 @@
 import '@testing-library/jest-dom/vitest'
+import { server } from './mocks/server'
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { formatCurrency } from '../formatCurrency';
+
+describe('formatCurrency', () => {
+  it('formats 0 cents as $0.00', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+
+  it('formats 199 cents as $1.99', () => {
+    expect(formatCurrency(199)).toBe('$1.99');
+  });
+
+  it('formats 10000 cents as $100.00', () => {
+    expect(formatCurrency(10000)).toBe('$100.00');
+  });
+
+  it('handles negative values', () => {
+    expect(formatCurrency(-500)).toBe('-$5.00');
+  });
+
+  it('handles large numbers', () => {
+    expect(formatCurrency(99999999)).toBe('$999,999.99');
+  });
+
+  it('supports custom locale', () => {
+    expect(formatCurrency(1999, 'de-DE', 'EUR')).toContain('19,99');
+  });
+
+  it('supports custom currency', () => {
+    const result = formatCurrency(1000, 'en-US', 'EUR');
+    expect(result).toContain('10.00');
+  });
+});
@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { formatDate } from '../formatDate';
+
+describe('formatDate', () => {
+  describe('short style', () => {
+    it('formats an ISO date string', () => {
+      const result = formatDate('2024-03-15', 'short');
+      expect(result).toMatch(/Mar 15, 2024/);
+    });
+
+    it('formats a Date object', () => {
+      const result = formatDate(new Date('2024-03-15'), 'short');
+      expect(result).toMatch(/Mar 15, 2024/);
+    });
+  });
+
+  describe('long style', () => {
+    it('formats with weekday and full month name', () => {
+      const result = formatDate('2024-03-15', 'long');
+      expect(result).toMatch(/Friday/);
+      expect(result).toMatch(/March/);
+    });
+  });
+
+  describe('relative style', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('returns "just now" for very recent dates', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T11:59:59Z'), 'relative');
+      expect(result).toBe('just now');
+    });
+
+    it('returns minutes ago', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T11:45:00Z'), 'relative');
+      expect(result).toBe('15m ago');
+    });
+
+    it('returns hours ago', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T09:00:00Z'), 'relative');
+      expect(result).toBe('3h ago');
+    });
+
+    it('returns days ago', () => {
+      const now = new Date('2024-01-05T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T12:00:00Z'), 'relative');
+      expect(result).toBe('4d ago');
+    });
+  });
+});
@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { getStore, getStoreName, STORE_SLUGS } from '../storeSlugs';
+
+describe('storeSlugs', () => {
+  describe('STORE_SLUGS constant', () => {
+    it('contains meijer, kroger, and target', () => {
+      expect(STORE_SLUGS).toHaveProperty('meijer');
+      expect(STORE_SLUGS).toHaveProperty('kroger');
+      expect(STORE_SLUGS).toHaveProperty('target');
+    });
+  });
+
+  describe('getStore', () => {
+    it('returns store data for known slug', () => {
+      const store = getStore('meijer');
+      expect(store).toEqual({
+        name: 'Meijer',
+        color: '#e31837',
+        icon: '/icons/stores/meijer.svg',
+      });
+    });
+
+    it('returns null for unknown slug', () => {
+      expect(getStore('unknown-store')).toBeNull();
+    });
+
+    it('is case insensitive', () => {
+      expect(getStore('KROGER')).toBeTruthy();
+      expect(getStore('Target')).toBeTruthy();
+    });
+  });
+
+  describe('getStoreName', () => {
+    it('returns store name for known slug', () => {
+      expect(getStoreName('kroger')).toBe('Kroger');
+    });
+
+    it('returns raw slug for unknown store', () => {
+      expect(getStoreName('unknown-store')).toBe('unknown-store');
+    });
+
+    it('is case insensitive', () => {
+      expect(getStoreName('TARGET')).toBe('Target');
+    });
+  });
+});
@@ -0,0 +1,10 @@
+export function formatCurrency(
+  cents: number,
+  locale = 'en-US',
+  currency = 'USD'
+): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  }).format(cents / 100);
+}
@@ -0,0 +1,34 @@
+export function formatDate(
+  date: string | Date,
+  style: 'short' | 'long' | 'relative' = 'short'
+): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+
+  if (style === 'short') {
+    return d.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  }
+
+  if (style === 'long') {
+    return d.toLocaleDateString('en-US', {
+      weekday: 'long',
+      month: 'long',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  }
+
+  // relative
+  const diff = Date.now() - d.getTime();
+  const seconds = Math.floor(diff / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
@@ -0,0 +1,13 @@
+export const STORE_SLUGS: Record<string, { name: string; color: string; icon: string }> = {
+  meijer: { name: 'Meijer', color: '#e31837', icon: '/icons/stores/meijer.svg' },
+  kroger: { name: 'Kroger', color: '#0033a0', icon: '/icons/stores/kroger.svg' },
+  target: { name: 'Target', color: '#cc0000', icon: '/icons/stores/target.svg' },
+};
+
+export function getStore(slug: string) {
+  return STORE_SLUGS[slug.toLowerCase()] ?? null;
+}
+
+export function getStoreName(slug: string): string {
+  return getStore(slug)?.name ?? slug;
+}
@@ -7,5 +7,6 @@ export default defineConfig({
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/test/setup.ts'],
+    exclude: ['e2e/**', 'node_modules/**'],
  },
 })