docs(GRO-106): 10DLC pilot registration runbook

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

.gitea/workflows/helm-release.yml

@@ -1,54 +0,0 @@
-name: Release Helm Chart
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'charts/**'
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout groombook
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Checkout groombook.dev (Helm chart host)
-        uses: actions/checkout@v4
-        with:
-          repository: groombook/groombook.dev
-          path: gitea-pages
-          token: ${{ gitea.token }}
-
-      - name: Install Helm
-        uses: azure/setup-helm@v4
-
-      - name: Update Helm dependencies
-        run: helm dependency update charts/groombook
-
-      - name: Package chart
-        run: |
-          mkdir -p gitea-pages/charts
-          helm package charts/groombook -d gitea-pages/charts
-
-      - name: Update repo index
-        run: |
-          # TODO: update URL once Gitea Pages hosting is confirmed
-          CHART_URL="${HELM_CHART_URL:-https://groombook.farh.net/charts}"
-          if [ -f gitea-pages/charts/index.yaml ]; then
-            helm repo index gitea-pages/charts --merge gitea-pages/charts/index.yaml --url "$CHART_URL"
-          else
-            helm repo index gitea-pages/charts --url "$CHART_URL"
-          fi
-
-      - name: Push to groombook.dev
-        run: |
-          cd gitea-pages
-          git config user.name "groombook-engineer[bot]"
-          git config user.email "groombook-engineer[bot]@git.farh.net"
-          git add charts/
-          git diff --staged --quiet && echo 'No chart changes' && exit 0
-          git commit -m "Update Helm chart repository"
-          git push

.github/workflows/ci.yml

@@ -86,8 +86,6 @@ jobs:
 
       - name: Run E2E tests
         run: pnpm --filter @groombook/e2e test
-        env:
-          PLAYWRIGHT_BASE_URL: http://host.docker.internal:8080
 
       - name: Upload Playwright report
         if: failure()
@@ -129,12 +127,18 @@ jobs:
     needs: [build, e2e]
     outputs:
       tag: ${{ steps.version.outputs.tag }}
+    permissions:
+      contents: read
+      packages: write
     steps:
       - uses: actions/checkout@v4
 
       - name: Generate image tag
         id: version
         run: |
+          # Always include short SHA so each build is immutable and cache-from can never
+          # cross-contaminate between commits. For PRs the format is pr-N-sha7; for main
+          # it is YYYY.MM.DD-sha7.
           if [ "${{ github.event_name }}" = "pull_request" ]; then
             TAG="pr-${{ github.event.pull_request.number }}-${GITHUB_SHA::7}"
           else
@@ -146,12 +150,12 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Log in to Gitea Container Registry
+      - name: Log in to GitHub Container Registry
         uses: docker/login-action@v3
         with:
-          registry: git.farh.net
+          registry: ghcr.io
-          username: ${{ gitea.actor }}
+          username: ${{ github.actor }}
-          password: ${{ secrets.REGISTRY_TOKEN }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push API image
         uses: docker/build-push-action@v6
@@ -161,10 +165,10 @@ jobs:
           target: runner
           push: true
           tags: |
-            git.farh.net/groombook/api:${{ steps.version.outputs.tag }}
+            ghcr.io/groombook/api:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/api:latest' || '' }}
+            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/api:latest' || '' }}
-          cache-from: type=registry,ref=git.farh.net/groombook/cache:api
+          cache-from: type=gha
-          cache-to: type=registry,ref=git.farh.net/groombook/cache:api,mode=max
+          cache-to: type=gha,mode=max
 
       - name: Build and push Migrate image
         uses: docker/build-push-action@v6
@@ -174,10 +178,10 @@ jobs:
           target: migrate
           push: true
           tags: |
-            git.farh.net/groombook/migrate:${{ steps.version.outputs.tag }}
+            ghcr.io/groombook/migrate:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/migrate:latest' || '' }}
+            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/migrate:latest' || '' }}
-          cache-from: type=registry,ref=git.farh.net/groombook/cache:migrate
+          cache-from: type=gha
-          cache-to: type=registry,ref=git.farh.net/groombook/cache:migrate,mode=max
+          cache-to: type=gha,mode=max
 
       - name: Build and push Seed image
         uses: docker/build-push-action@v6
@@ -187,10 +191,10 @@ jobs:
           target: seed
           push: true
           tags: |
-            git.farh.net/groombook/seed:${{ steps.version.outputs.tag }}
+            ghcr.io/groombook/seed:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/seed:latest' || '' }}
+            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/seed:latest' || '' }}
-          cache-from: type=registry,ref=git.farh.net/groombook/cache:seed
+          cache-from: type=gha
-          cache-to: type=registry,ref=git.farh.net/groombook/cache:seed,mode=max
+          cache-to: type=gha,mode=max
 
       - name: Build and push Reset image
         uses: docker/build-push-action@v6
@@ -200,10 +204,10 @@ jobs:
           target: reset
           push: true
           tags: |
-            git.farh.net/groombook/reset:${{ steps.version.outputs.tag }}
+            ghcr.io/groombook/reset:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/reset:latest' || '' }}
+            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/reset:latest' || '' }}
-          cache-from: type=registry,ref=git.farh.net/groombook/cache:reset
+          cache-from: type=gha
-          cache-to: type=registry,ref=git.farh.net/groombook/cache:reset,mode=max
+          cache-to: type=gha,mode=max
 
       - name: Build and push Web image
         uses: docker/build-push-action@v6
@@ -212,16 +216,19 @@ jobs:
           file: apps/web/Dockerfile
           push: true
           tags: |
-            git.farh.net/groombook/web:${{ steps.version.outputs.tag }}
+            ghcr.io/groombook/web:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/web:latest' || '' }}
+            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/web:latest' || '' }}
-          cache-from: type=registry,ref=git.farh.net/groombook/cache:web
+          cache-from: type=gha
-          cache-to: type=registry,ref=git.farh.net/groombook/cache:web,mode=max
+          cache-to: type=gha,mode=max
 
   deploy-dev:
     name: Deploy PR to groombook-dev
-    runs-on: ubuntu-latest
+    runs-on: runners-groombook
     needs: [docker]
     if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - name: Install kubectl
         run: |
@@ -238,6 +245,7 @@ jobs:
           TAG="pr-$PR_NUM-${SHA::7}"
           echo "Deploying images tagged $TAG to groombook-dev..."
 
+          # Run migration with PR image
           kubectl delete job "migrate-pr-$PR_NUM" -n groombook-dev --ignore-not-found
           cat <<EOF | kubectl apply -n groombook-dev -f -
           apiVersion: batch/v1
@@ -252,7 +260,7 @@ jobs:
                 restartPolicy: Never
                 containers:
                 - name: migrate
-                  image: git.farh.net/groombook/migrate:$TAG
+                  image: ghcr.io/groombook/migrate:$TAG
                   env:
                   - name: DATABASE_URL
                     valueFrom:
@@ -263,25 +271,35 @@ jobs:
           kubectl wait --for=condition=complete "job/migrate-pr-$PR_NUM" \
             -n groombook-dev --timeout=120s
 
-          kubectl set image deployment/api api=git.farh.net/groombook/api:$TAG -n groombook-dev
+          # Update deployments
-          kubectl set image deployment/web web=git.farh.net/groombook/web:$TAG -n groombook-dev
+          kubectl set image deployment/api api=ghcr.io/groombook/api:$TAG -n groombook-dev
+          kubectl set image deployment/web web=ghcr.io/groombook/web:$TAG -n groombook-dev
 
+          # Wait for rollout
           kubectl rollout status deployment/api -n groombook-dev --timeout=300s
           kubectl rollout status deployment/web -n groombook-dev --timeout=300s
 
           echo "Deployment complete."
 
       - name: Comment on PR
-        env:
+        uses: actions/github-script@v7
-          PR_NUM: ${{ github.event.pull_request.number }}
+        with:
-          GITEA_TOKEN: ${{ gitea.token }}
+          script: |
-        run: |
+            const pr = context.issue.number;
-          TAG="pr-${PR_NUM}"
+            const tag = `pr-${pr}`;
-          curl -s -X POST \
+            await github.rest.issues.createComment({
-            -H "Authorization: token $GITEA_TOKEN" \
+              owner: context.repo.owner,
-            -H "Content-Type: application/json" \
+              repo: context.repo.repo,
-            "https://git.farh.net/api/v1/repos/groombook/app/issues/$PR_NUM/comments" \
+              issue_number: pr,
-            -d "{\"body\": \"## Deployed to groombook-dev\n\n**Images:** \`${TAG}\`\n**URL:** https://dev.groombook.farh.net\n\nReady for UAT validation.\"}"
+              body: [
+                '## Deployed to groombook-dev',
+                '',
+                `**Images:** \`${tag}\``,
+                '**URL:** https://dev.groombook.farh.net',
+                '',
+                'Ready for UAT validation.'
+              ].join('\n')
+            });
 
   web-e2e:
     name: Web E2E (Dev)
@@ -322,13 +340,21 @@ jobs:
     name: Update Infra Image Tags
     runs-on: ubuntu-latest
     needs: [docker]
-    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && github.event_name == 'push'
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
+      - name: Generate infra repo token
+        id: infra-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ vars.GH_APP_ID }}
+          private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
       - name: Clone groombook/infra
-        env:
-          GITEA_TOKEN: ${{ gitea.token }}
         run: |
-          git clone https://oauth2:$GITEA_TOKEN@git.farh.net/groombook/infra.git /tmp/infra
+          git clone https://x-access-token:${{ steps.infra-token.outputs.token }}@github.com/groombook/infra.git /tmp/infra
 
       - name: Install yq
         run: |
@@ -345,25 +371,30 @@ jobs:
           fi
           export SHORT_SHA="${SHA::7}"
           echo "Updating dev overlay image tags to: $TAG"
+          echo "Updating migration/seed Job names with SHA: $SHORT_SHA"
           cd /tmp/infra
           DEV_KUST="apps/groombook/overlays/dev/kustomization.yaml"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/api")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/api")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/web")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/web")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/migrate")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/migrate")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/seed")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/reset")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/reset")).newTag = env(TAG)' "$DEV_KUST"
 
+          # Update migrate Job name to include short SHA (immutable template fix)
           MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
+            # Ensure ttlSecondsAfterFinished is set for automatic cleanup
             yq -i '.spec.ttlSecondsAfterFinished = (.spec.ttlSecondsAfterFinished // 86400)' "$MIGRATE_JOB"
           fi
 
+          # Update seed Job name to include short SHA (immutable template fix)
           SEED_JOB="apps/groombook/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$SEED_JOB"
+            # Ensure ttlSecondsAfterFinished is set for automatic cleanup
             yq -i '.spec.ttlSecondsAfterFinished = (.spec.ttlSecondsAfterFinished // 86400)' "$SEED_JOB"
           fi
 
@@ -372,40 +403,32 @@ jobs:
       - name: Create PR on groombook/infra
         env:
           TAG: ${{ needs.docker.outputs.tag }}
-          GITEA_TOKEN: ${{ gitea.token }}
+          GH_TOKEN: ${{ steps.infra-token.outputs.token }}
         run: |
           if [ -z "$TAG" ]; then
             TAG="$(date -u +%Y.%m.%d)-${GITHUB_SHA::7}"
           fi
+
           cd /tmp/infra
           git config user.name "groombook-engineer[bot]"
-          git config user.email "groombook-engineer[bot]@git.farh.net"
+          git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "chore/update-image-tags-${TAG}"
           git add apps/groombook/overlays/dev/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
           git commit -m "chore: update image tags and migration/seed Job names to ${TAG}"
+
           git push -u origin "chore/update-image-tags-${TAG}"
 
-          EXISTING_PR=$(curl -s \
+          # Check if PR already exists for this branch
-            -H "Authorization: token $GITEA_TOKEN" \
+          EXISTING_PR=$(gh pr list --repo groombook/infra --head "chore/update-image-tags-${TAG}" --state open --json number -q '.[0].number' || true)
-            "https://git.farh.net/api/v1/repos/groombook/infra/pulls?state=open&limit=50" \
-            | jq -r ".[] | select(.head.label == \"chore/update-image-tags-${TAG}\") | .number" | head -1)
           if [ -n "$EXISTING_PR" ]; then
-            echo "PR #$EXISTING_PR already exists, merging"
+            echo "PR #$EXISTING_PR already exists for this tag, merging existing PR"
-            curl -s -X POST \
+            gh pr merge "$EXISTING_PR" --repo groombook/infra --merge
-              -H "Authorization: token $GITEA_TOKEN" \
-              -H "Content-Type: application/json" \
-              "https://git.farh.net/api/v1/repos/groombook/infra/pulls/$EXISTING_PR/merge" \
-              -d '{"Do":"merge"}'
           else
-            PR_NUM=$(curl -s -X POST \
+            PR_URL=$(gh pr create \
-              -H "Authorization: token $GITEA_TOKEN" \
+              --repo groombook/infra \
-              -H "Content-Type: application/json" \
+              --base main \
-              "https://git.farh.net/api/v1/repos/groombook/infra/pulls" \
+              --head "chore/update-image-tags-${TAG}" \
-              -d "{\"head\":\"chore/update-image-tags-${TAG}\",\"base\":\"main\",\"title\":\"chore: deploy ${TAG} to dev\",\"body\":\"[GRO-178](/GRO/issues/GRO-178) — automated image tag update from main merge\"}" \
+              --title "chore: deploy ${TAG} to dev" \
-              | jq '.number')
+              --body "[GRO-178](/GRO/issues/GRO-178) — automated image tag update from main merge")
-            curl -s -X POST \
+            gh pr merge "$PR_URL" --merge
-              -H "Authorization: token $GITEA_TOKEN" \
-              -H "Content-Type: application/json" \
-              "https://git.farh.net/api/v1/repos/groombook/infra/pulls/$PR_NUM/merge" \
-              -d '{"Do":"merge"}'
           fi

.github/workflows/helm-release.yml

@@ -0,0 +1,54 @@
+name: Release Helm Chart
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'charts/**'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout groombook
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Checkout groombook.github.io
+        uses: actions/checkout@v4
+        with:
+          repository: groombook/groombook.github.io
+          path: gh-pages
+          token: ${{ secrets.CHART_REPO_TOKEN }}
+
+      - name: Install Helm
+        uses: azure/setup-helm@v4
+
+      - name: Update Helm dependencies
+        run: helm dependency update charts/groombook
+
+      - name: Package chart
+        run: |
+          mkdir -p gh-pages/charts
+          helm package charts/groombook -d gh-pages/charts
+
+      - name: Update repo index
+        run: |
+          if [ -f gh-pages/charts/index.yaml ]; then
+            helm repo index gh-pages/charts --merge gh-pages/charts/index.yaml --url https://groombook.github.io/charts
+          else
+            helm repo index gh-pages/charts --url https://groombook.github.io/charts
+          fi
+
+      - name: Push to groombook.github.io
+        run: |
+          cd gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add charts/
+          git diff --staged --quiet && echo 'No chart changes' && exit 0
+          git commit -m "Update Helm chart repository"
+          git push

.github/workflows/promote-prod.yml

@@ -12,6 +12,9 @@ jobs:
   promote:
     name: Promote to Production
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
     steps:
       - name: Validate tag format
         run: |
@@ -22,25 +25,28 @@ jobs:
           fi
           echo "Tag format valid: $TAG"
 
-      - name: Verify image exists in Gitea Container Registry
+      - name: Verify image exists in GHCR
         env:
-          GITEA_TOKEN: ${{ gitea.token }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           TAG="${{ inputs.tag }}"
-          if ! curl -sf \
+          # Check that the API image exists — if API was pushed, web/migrate were too
-            -H "Authorization: token $GITEA_TOKEN" \
+          if ! gh api "/orgs/groombook/packages/container/api/versions" --jq ".[].metadata.container.tags[]" 2>/dev/null | grep -qF "$TAG"; then
-            "https://git.farh.net/api/v1/packages/groombook?type=container&limit=50" \
+            echo "::error::Image ghcr.io/groombook/api:$TAG not found in GHCR. Verify the tag was built and pushed."
-            | jq -e --arg t "$TAG" '[.[] | select(.name == "api" and .version == $t)] | length > 0' > /dev/null 2>&1; then
+            exit 1
-            echo "::warning::Could not verify git.farh.net/groombook/api:$TAG via package API — verify manually if needed."
-          else
-            echo "Image verified: git.farh.net/groombook/api:$TAG exists"
           fi
+          echo "Image verified: ghcr.io/groombook/api:$TAG exists"
+
+      - name: Generate infra repo token
+        id: infra-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ vars.GH_APP_ID }}
+          private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
       - name: Clone groombook/infra
-        env:
-          GITEA_TOKEN: ${{ gitea.token }}
         run: |
-          git clone https://oauth2:$GITEA_TOKEN@git.farh.net/groombook/infra.git /tmp/infra
+          git clone https://x-access-token:${{ steps.infra-token.outputs.token }}@github.com/groombook/infra.git /tmp/infra
 
       - name: Install yq
         run: |
@@ -58,17 +64,19 @@ jobs:
           export SHORT_SHA
           export TAG
 
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/api")).newTag = env(TAG)' "$PROD_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/api")).newTag = env(TAG)' "$PROD_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/web")).newTag = env(TAG)' "$PROD_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/web")).newTag = env(TAG)' "$PROD_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/migrate")).newTag = env(TAG)' "$PROD_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/migrate")).newTag = env(TAG)' "$PROD_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/seed")).newTag = env(TAG)' "$PROD_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$PROD_KUST"
 
+          # Update migrate Job name to include short SHA (immutable template fix)
           MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
           fi
 
+          # Update seed Job name to include short SHA (immutable template fix)
           SEED_JOB="apps/groombook/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
@@ -80,29 +88,30 @@ jobs:
       - name: Create PR on groombook/infra
         env:
           TAG: ${{ inputs.tag }}
-          GITEA_TOKEN: ${{ gitea.token }}
+          GH_TOKEN: ${{ steps.infra-token.outputs.token }}
         run: |
           cd /tmp/infra
           git config user.name "groombook-engineer[bot]"
-          git config user.email "groombook-engineer[bot]@git.farh.net"
+          git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "release/promote-prod-${TAG}"
           git add apps/groombook/overlays/prod/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
           git commit -m "release: promote ${TAG} to production"
           git push -u origin "release/promote-prod-${TAG}"
-          curl -s -X POST \
+          gh pr create \
-            -H "Authorization: token $GITEA_TOKEN" \
+            --repo groombook/infra \
-            -H "Content-Type: application/json" \
+            --base main \
-            "https://git.farh.net/api/v1/repos/groombook/infra/pulls" \
+            --head "release/promote-prod-${TAG}" \
-            -d "{\"head\":\"release/promote-prod-${TAG}\",\"base\":\"main\",\"title\":\"release: promote ${TAG} to production\",\"body\":\"Promote image tag ${TAG} to production after UAT sign-off. cc @cpfarhood\"}"
+            --title "release: promote ${TAG} to production" \
+            --body "Promote image tag ${TAG} to production after UAT sign-off. cc @cpfarhood"
 
       - name: Notify on failure
         if: failure()
-        env:
+        uses: actions/github-script@v7
-          GITEA_TOKEN: ${{ gitea.token }}
+        with:
-          RUN_ID: ${{ github.run_id }}
+          script: |
-        run: |
+            github.rest.issues.createComment({
-          curl -s -X POST \
+              owner: context.repo.owner,
-            -H "Authorization: token $GITEA_TOKEN" \
+              repo: context.repo.repo,
-            -H "Content-Type: application/json" \
+              issue_number: context.issue.number,
-            "https://git.farh.net/api/v1/repos/groombook/app/issues/$RUN_ID/comments" \
+              body: '## Production Promotion Failed\n\nThe `promote-prod` workflow failed. Check the workflow run logs for details.'
-            -d '{"body": "## Production Promotion Failed\n\nThe `promote-prod` workflow failed. Check the workflow run logs for details."}'
+            });

.github/workflows/promote-to-uat.yml

@@ -12,12 +12,20 @@ jobs:
   promote-to-uat:
     name: Promote to groombook-uat
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
+      - name: Generate infra repo token
+        id: infra-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ vars.GH_APP_ID }}
+          private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
       - name: Clone groombook/infra
-        env:
-          GITEA_TOKEN: ${{ gitea.token }}
         run: |
-          git clone https://oauth2:$GITEA_TOKEN@git.farh.net/groombook/infra.git /tmp/infra
+          git clone https://x-access-token:${{ steps.infra-token.outputs.token }}@github.com/groombook/infra.git /tmp/infra
 
       - name: Install yq
         run: |
@@ -41,17 +49,21 @@ jobs:
           export SHORT_SHA
           export TAG
 
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/api")).newTag = env(TAG)' "$UAT_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/api")).newTag = env(TAG)' "$UAT_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/web")).newTag = env(TAG)' "$UAT_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/web")).newTag = env(TAG)' "$UAT_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/migrate")).newTag = env(TAG)' "$UAT_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/migrate")).newTag = env(TAG)' "$UAT_KUST"
-          yq -i '(.images[] | select(.name == "git.farh.net/groombook/seed")).newTag = env(TAG)' "$UAT_KUST"
+          yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$UAT_KUST"
 
+          # Update migrate Job name to include short SHA (immutable template fix)
           MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
           fi
 
+          # Update seed Job name to include short SHA (immutable template fix)
+          # NOTE: Do NOT update the image tag here — let the Kustomize images transformer
+          # in the UAT overlay handle it via newTag. This avoids the immutable template issue.
           SEED_JOB="apps/groombook/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
@@ -63,36 +75,34 @@ jobs:
       - name: Create PR on groombook/infra
         env:
           TAG: ${{ inputs.image_tag }}
-          GITEA_TOKEN: ${{ gitea.token }}
+          GH_TOKEN: ${{ steps.infra-token.outputs.token }}
         run: |
           cd /tmp/infra
           git config user.name "groombook-engineer[bot]"
-          git config user.email "groombook-engineer[bot]@git.farh.net"
+          git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "chore/update-uat-image-tags-${TAG}"
           git add apps/groombook/overlays/uat/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
           git commit -m "chore: promote ${TAG} to UAT"
+
           git push -u origin "chore/update-uat-image-tags-${TAG}"
 
-          PR_NUM=$(curl -s -X POST \
+          # Create PR and merge immediately (no required checks on groombook/infra)
-            -H "Authorization: token $GITEA_TOKEN" \
+          PR_URL=$(gh pr create \
-            -H "Content-Type: application/json" \
+            --repo groombook/infra \
-            "https://git.farh.net/api/v1/repos/groombook/infra/pulls" \
+            --base main \
-            -d "{\"head\":\"chore/update-uat-image-tags-${TAG}\",\"base\":\"main\",\"title\":\"chore: promote ${TAG} to UAT\",\"body\":\"[GRO-429](/GRO/issues/GRO-429) — UAT promotion triggered by CTO\"}" \
+            --head "chore/update-uat-image-tags-${TAG}" \
-            | jq '.number')
+            --title "chore: promote ${TAG} to UAT" \
-          curl -s -X POST \
+            --body "[GRO-429](/GRO/issues/GRO-429) — UAT promotion triggered by CTO")
-            -H "Authorization: token $GITEA_TOKEN" \
+          gh pr merge "$PR_URL" --merge
-            -H "Content-Type: application/json" \
-            "https://git.farh.net/api/v1/repos/groombook/infra/pulls/$PR_NUM/merge" \
-            -d '{"Do":"merge"}'
 
       - name: Notify on failure
         if: failure()
-        env:
+        uses: actions/github-script@v7
-          GITEA_TOKEN: ${{ gitea.token }}
+        with:
-          RUN_ID: ${{ github.run_id }}
+          script: |
-        run: |
+            github.rest.issues.createComment({
-          curl -s -X POST \
+              owner: context.repo.owner,
-            -H "Authorization: token $GITEA_TOKEN" \
+              repo: context.repo.repo,
-            -H "Content-Type: application/json" \
+              issue_number: context.issue.number,
-            "https://git.farh.net/api/v1/repos/groombook/app/issues/$RUN_ID/comments" \
+              body: '## UAT Promotion Failed\n\nThe `promote-to-uat` workflow failed. Check the workflow run logs for details.\n\nCommon issues:\n- UAT overlay not found (ensure GRO-427 is complete)\n- Infra repo access token expired'
-            -d '{"body": "## UAT Promotion Failed\n\nThe `promote-to-uat` workflow failed. Check the workflow run logs for details.\n\nCommon issues:\n- UAT overlay not found (ensure GRO-427 is complete)\n- GITEA_TOKEN permissions"}'
+            });

.mcp.json

@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "gitea": {
-      "type": "http",
-      "url": "https://git-mcp.farh.net/mcp",
-      "headers": {
-        "Authorization": "Bearer ${GITEA_TOKEN}"
-      }
-    }
-  }
-}

README.md

@@ -1,43 +1,218 @@
-# GroomBook Monorepo — Archived
+# GroomBook
 
-> **This repository has been archived and replaced by standalone repositories.**
+> **The open-source scheduling and client management platform built specifically for independent pet groomers** — giving you the tools of enterprise software without the enterprise price tag or vendor lock-in.
 
-## Successor Repositories
+**Built for groomers, not corporations.**
-
-| Repository | Description |
-|---|---|
-| [groombook/api](https://github.com/groombook/api) | Hono REST API (TypeScript, Node.js) |
-| [groombook/web](https://github.com/groombook/web) | React PWA frontend |
-| [groombook/charts](https://github.com/groombook/charts) | Helm charts for Kubernetes deployment |
-
-## What Changed
-
-- **Monorepo split complete** — The former `apps/api`, `apps/web`, and `packages/*` are now standalone repos
-- **`@groombook/types`** — Inlined directly into `groombook/api` and `groombook/web`
-- **E2E testing** — Now via Playwright MCP, no standalone repo needed
-- **CI/CD** — Each repo has its own pipeline; see individual repos for status
-
-## Migration Notes
-
-If you were cloning `groombook/groombook` for local development:
-
-```bash
-# API
-git clone https://github.com/groombook/api.git
-cd api && pnpm install && pnpm dev
-
-# Web (in a new terminal)
-git clone https://github.com/groombook/web.git
-cd web && pnpm install && pnpm dev
-```
-
-For full Docker Compose setup, see each repo's README.
-
-## Archive Info
-
-This repository was archived on 2026-05-14 as part of the monorepo decommission ([GRO-1081]).
-The history is preserved but the repo is read-only.
 
 ---
 
-*For Kubernetes deployments, see [groombook/infra](https://github.com/groombook/infra) (private).*
+## Key Features
+
+**Stop chasing confirmations**
+- **Customer portal** — Clients confirm or cancel appointments on their own. Reduce no-shows with an automated waitlist.
+
+**Your calendar, your way**
+- **iCal calendar feed** — Push GroomBook appointments directly into Google Calendar or Apple Calendar. No app switching.
+
+**Know every pet at a glance**
+- **Client & pet records** — Detailed profiles with grooming history, preferences, and breed-specific notes. Full appointment notes for context on every regular.
+- **Quick-find search** — Find clients and pets instantly without digging through spreadsheets.
+
+**Staff access without stress**
+- **Role-based access control (RBAC)** — Front desk sees bookings; only you see financials. Right access for every role.
+
+**Everything else**
+- **Appointment scheduling** — Calendar management for single or multiple groomers
+- **Service management** — Pricing, duration, and service catalog
+- **POS & invoicing** — Payments, tips, and receipt generation
+- **Automated reminders** — SMS and email notifications
+- **Reporting dashboard** — Revenue, utilization, and trend analytics
+- **Staff impersonation** — Managers can view the customer portal as any client, with full audit logging and session controls
+- **PWA** — Installable on mobile devices, works offline
+
+---
+
+## 🚀 Try the Demo
+
+[**Live Demo**](https://demo.groombook.app) — explore GroomBook without installing anything.
+
+---
+
+## Quick Start
+
+### Docker Compose (recommended for indie groomers)
+
+Run GroomBook on your own hardware in minutes. Everything you need is in the box — no subscription, no vendor lock-in.
+
+```bash
+git clone https://github.com/groombook/groombook.git
+cd groombook
+
+# Start everything (Postgres + database migrations + API + web UI)
+docker compose up --build
+```
+
+- **Web UI**: http://localhost:8080
+- **API**: http://localhost:3000
+
+The default `docker-compose.yml` sets `AUTH_DISABLED=true` so you can explore the app without configuring an OIDC provider. **Important:** Disable this in any internet-facing deployment.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Backend | [Hono](https://hono.dev/) (TypeScript, Node.js) |
+| Frontend | React 19 + Vite + [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) |
+| Database | PostgreSQL via [CNPG](https://cloudnative-pg.io/) + [Drizzle ORM](https://orm.drizzle.team/) |
+| Auth | OIDC via [Authentik](https://goauthentik.io/) |
+| Infra | Kubernetes (namespace: `groombook`), Flux GitOps |
+| CI | GitHub Actions (self-hosted `groombook-runners`) |
+
+## Repository Structure
+
+```
+groombook/
+├── apps/
+│   ├── api/          # Hono REST API
+│   └── web/          # React PWA
+├── packages/
+│   ├── db/           # Drizzle schema + migrations
+│   └── types/        # Shared TypeScript types
+├── .github/
+│   └── workflows/    # CI/CD pipelines
+└── docker-compose.yml
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 20
+- pnpm >= 9 (`npm install -g pnpm`)
+- Docker & Docker Compose (for local Postgres)
+
+### Local Development
+
+```bash
+# Clone the repo
+git clone https://github.com/groombook/groombook.git
+cd groombook
+
+# Install dependencies
+pnpm install
+
+# Start local Postgres
+docker compose up postgres -d
+
+# Run database migrations
+DATABASE_URL=postgres://groombook:groombook@localhost:5432/groombook pnpm db:migrate
+
+# Start API and Web in parallel
+pnpm dev
+```
+
+API will be available at http://localhost:3000
+Web will be available at http://localhost:5173
+
+### Environment Variables
+
+#### API (`apps/api/.env`)
+
+```env
+DATABASE_URL=postgres://groombook:groombook@localhost:5432/groombook
+OIDC_ISSUER=https://authentik.example.com
+OIDC_AUDIENCE=groombook
+CORS_ORIGIN=http://localhost:5173
+PORT=3000
+```
+
+### Running Tests
+
+```bash
+# Unit tests (vitest)
+pnpm test
+
+# E2E tests (Playwright) — requires the full Docker Compose stack to be running
+docker compose up -d --wait
+pnpm --filter @groombook/e2e test
+
+# Open the Playwright UI (interactive test runner)
+pnpm --filter @groombook/e2e test:ui
+
+# View the last E2E test report
+pnpm --filter @groombook/e2e test:report
+```
+
+E2E tests target the Docker Compose stack (`http://localhost:8080`). They use API route mocking where needed so happy-path tests are deterministic without requiring seed data.
+
+### Building
+
+```bash
+pnpm build
+```
+
+## Self-Hosting
+
+### Production Configuration
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+Key variables to update for production:
+
+| Variable | Description |
+|---|---|
+| `DATABASE_URL` | PostgreSQL connection string |
+| `AUTH_DISABLED` | Set to `false` in production |
+| `OIDC_ISSUER` | Authentik issuer URL |
+| `OIDC_AUDIENCE` | OAuth2 audience (default: `groombook`) |
+| `CORS_ORIGIN` | Public URL of the web frontend |
+
+To use your `.env` file with Docker Compose:
+
+```bash
+docker compose --env-file .env up --build
+```
+
+### Kubernetes (production-grade deployments)
+
+See the [groombook/infra](https://github.com/groombook/infra) repository for Kubernetes manifests and Flux configuration.
+
+Groom Book is deployed in the `groombook` Kubernetes namespace using:
+- **CNPG** for PostgreSQL
+- **Authentik** for OIDC authentication
+- **Flux** for GitOps-managed deployments
+
+---
+
+## Contributing
+
+GroomBook thrives on contributions from the grooming community. Whether you're a groomer with a feature request, a developer fixing a bug, or someone improving docs — we'd love your help.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Open a pull request
+
+All PRs require CI to pass before merge. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+---
+
+## Why GroomBook?
+
+- **Open source** — You own your data. No vendor lock-in.
+- **Purpose-built** — Features designed for grooming workflows, not generic scheduling.
+- **Self-hosted or managed** — Run it yourself for free, or pay for hosted support (coming soon).
+- **Community-driven** — Used and built by actual groomers.
+
+---
+
+## License
+
+AGPL-3.0
+

docs/runbooks/10dlc-pilot-registration.md

@@ -0,0 +1,309 @@
+# 10DLC Pilot Tenant Registration Runbook
+
+Authored for [GRO-106](/GRO/issues/GRO-106) Phase 1.
+
+---
+
+## Pre-Flight Checklist
+
+Before starting Telnyx registration, collect the following:
+
+| Item | Details |
+|------|---------|
+| Legal business name | Exact name on EIN / business registration |
+| EIN (Employer Identification Number) | 9-digit IRS format: XX-XXXXXXX |
+| Business type | Sole Proprietor / LLC / Corporation |
+| Primary contact email | General contact address (postmaster@, info@, etc.) |
+| Primary contact phone | Direct line for carrier verification |
+| Website URL | Must be live and contain privacy policy |
+| Sample message templates | See [Sample Templates](#sample-message-templates) below |
+| Messaging use case | Customer Care / Account Notification |
+
+---
+
+## Step 1 — Telnyx Account Requirements
+
+- Active Telnyx account with billing configured.
+- Role required: **Admin** or **Super User** to register brands and campaigns.
+
+---
+
+## Step 2 — Brand Registration
+
+### Via Telnyx Console
+
+1. Log in to [Telnyx Portal](https://portal.telnyx.com).
+2. Navigate to **Messaging → A2P 10DLC → Brands**.
+3. Click **Register Brand**.
+4. Fill in:
+   - **Brand Name**: Legal business name
+   - **Legal Company Name**: Exact EIN name
+   - **Company Type**: Select from dropdown
+   - **EIN**: XX-XXXXXXX
+   - **Primary Contact**: Name, email, phone
+   - **Website**: Must be accessible
+   - **BusinessVertical**: Select appropriate vertical
+5. Acknowledge the **Terms of Service**.
+6. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/brands \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Your Legal Business Name",
+    "legal_company_name": "Your Legal Business Name",
+    "company_type": "llc",
+    "ein": "XX-XXXXXXX",
+    "primary_contact": {
+      "name": "Jane Doe",
+      "email": "compliance@example.com",
+      "phone": "+13125551000"
+    },
+    "website": "https://www.example.com",
+    "business_vertical": "FINANCE_INSURANCE_BANKING"
+  }'
+```
+
+**Response fields to record:**
+- `brand_id` — required for campaign registration
+- `brand_score` — affects campaign vetting speed
+
+### Expected Fees
+
+| Fee Type | Amount |
+|----------|--------|
+| Brand registration fee | ~$0 (no direct fee from Telnyx) |
+| Campaign registration fee | ~$15–$25 per campaign (Telnyx fee, subject to change) |
+| Carrier fees | Passed through from T-Mobile/AT&T/Verizon |
+
+### Expected Approval Window
+
+- **Vetting by Telnyx**: 1–3 business days after submission.
+- **Carrier (T-Mobile/AT&T/Verizon) review**: 2–5 business days after Telnyx approval.
+- Total end-to-end: **3–8 business days**.
+
+---
+
+## Step 3 — Campaign Registration
+
+### Use Case Selection
+
+- **Primary**: Customer Care
+- **Secondary**: Account Notification
+
+### Via Telnyx Console
+
+1. Navigate to **Messaging → A2P 10DLC → Campaigns**.
+2. Click **Register Campaign**.
+3. Select **Brand** (use the brand registered in Step 2).
+4. Fill in:
+   - **Campaign Name**: e.g., `groombook-pilot-customer-care`
+   - **Use Case**: Customer Care / Account Notification
+   - **Sample Messages**: Paste exactly the templates from [Sample Templates](#sample-message-templates) below.
+   - **Description**: Brief description of messaging program
+   - **Estimated Volume**: Enter monthly estimate (e.g., 500)
+5. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/campaigns \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "brand_id": "YOUR_BRAND_ID",
+    "name": "groombook-pilot-customer-care",
+    "use_case": "CUSTOMER_CARE",
+    "sample_messages": [
+      "Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out.",
+      "Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP or call us at {{phone}}."
+    ],
+    "description": "Appointment reminders and account notifications for grooming clients",
+    "estimated_monthly_volume": 500
+  }'
+```
+
+**Response fields to record:**
+- `campaign_id` — required for messaging profile
+- `status` — initially `PENDING`, transitions to `ACTIVE` after carrier approval
+
+### Campaign Vetting — STOP/HELP Language Requirements
+
+Every campaign **must** include compliant STOP/HELP messaging. The following must appear in your sample messages or be included in your terms of service:
+
+- **STOP**: Users can text `STOP` to opt out of all messages.
+- **HELP**: Users can text `HELP` to receive contact information.
+
+Example STOP/HELP block:
+
+```
+Text STOP to opt out. Text HELP for help. Msg & data rates may apply.
+```
+
+---
+
+## Step 4 — Messaging Profile + Phone Number Provisioning
+
+### Create Messaging Profile
+
+1. In Telnyx Portal, navigate to **Messaging → Messaging Profiles**.
+2. Click **Create Messaging Profile**.
+3. Name it (e.g., `groombook-pilot-prod`).
+4. Copy the **Messaging Profile ID** (`messaging_profile_id`) — record this in the DB.
+
+### Provision a 10DLC Phone Number
+
+1. Navigate to **Messaging → Phone Numbers**.
+2. Search for a number in your desired area code.
+3. Confirm the number is 10DLC-capable.
+4. Purchase the number.
+
+### Associate Number with Messaging Profile
+
+```bash
+# Assign number to messaging profile
+curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR_PHONE_NUMBER_ID \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
+  }'
+```
+
+---
+
+## Step 5 — Record in Database
+
+Once [GRO-981](/GRO/issues/GRO-981) lands, record the following against the business record:
+
+### SQL Path (when GRO-981 is complete)
+
+```sql
+UPDATE businesses
+SET
+  messaging_phone_number = '+13125551000',
+  telnyx_messaging_profile_id = 'YOUR_MESSAGING_PROFILE_ID',
+  telnyx_brand_id = 'YOUR_BRAND_ID',
+  telnyx_campaign_id = 'YOUR_CAMPAIGN_ID',
+  telnyx_brand_status = 'APPROVED',
+  telnyx_campaign_status = 'ACTIVE',
+  updated_at = NOW()
+WHERE id = 'pilot_business_id';
+```
+
+### Manual Admin Path (before GRO-981)
+
+Until GRO-981 is complete, use the Telnyx Portal to verify and record values manually in your internal ops sheet:
+
+| Field | Value |
+|-------|-------|
+| `messagingPhoneNumber` | +1XXXXXXXXXX |
+| `telnyxMessagingProfileId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxBrandId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxCampaignId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `brandStatus` | APPROVED / PENDING |
+| `campaignStatus` | ACTIVE / PENDING |
+
+---
+
+## Sample Message Templates
+
+These must match exactly what your system will send. Vetting reviewers compare templates against actual traffic.
+
+### Transactional Appointment Reminder
+
+```
+Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out. Msg & data rates may apply.
+```
+
+### Manual Staff Message
+
+```
+Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP for assistance or call us at {{phone}}. Msg & data rates may apply.
+```
+
+---
+
+## Failure Modes + Retry Guidance
+
+### Vetting Rejection — Brand
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Legal name mismatch with EIN | Ensure exact EIN name matches legal company name exactly |
+| Website not accessible / missing privacy policy | Add privacy policy page to website before resubmitting |
+| Incomplete primary contact | Provide direct phone and real email (no noreply) |
+| High-risk business vertical | Contact Telnyx support for pre-screening before resubmitting |
+
+### Campaign Rejection
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Sample messages do not match actual traffic | Update sample messages to match exactly what the system sends |
+| Missing STOP/HELP language | Add compliant STOP/HELP block to sample messages |
+| Volume estimate too low/high | Revise estimate to be realistic |
+| Use case mismatch | Re-select use case that matches actual messaging |
+
+### Re-submission
+
+After fixing the rejection reason, re-submit via the same API endpoint. Telnyx will re-run vetting (typically 24–48 hours).
+
+---
+
+## Cost Summary
+
+### Telnyx Fees (as of 2026)
+
+| Fee Type | Amount | Notes |
+|----------|--------|-------|
+| 10DLC number (monthly) | ~$1.00–$2.50/number | Varies by type and area code |
+| Outbound message | $0.005–$0.015/message | Depends on destination carrier |
+| Inbound message | Included | No charge for received messages |
+| Campaign registration | ~$15–$25 one-time | Per campaign, subject to change |
+
+### Carrier Fees (T-Mobile / AT&T / Verizon)
+
+| Carrier | Outbound Fee | Notes |
+|---------|-------------|-------|
+| T-Mobile | ~$0.005–$0.01/message | Varies by message size (segment) |
+| AT&T | ~$0.005–$0.015/message | Varies by message size (segment) |
+| Verizon | ~$0.005–$0.01/message | Varies by message size (segment) |
+
+**Note**: Carrier fees are subject to change. Check [Telnyx pricing page](https://telnyx.com/pricing) and carrier fee schedules for current rates.
+
+### Example Monthly Cost (Pilot — 500 messages/month)
+
+| Line Item | Cost |
+|-----------|------|
+| 1x 10DLC number | ~$2.00 |
+| 500 outbound messages | ~$5.00–$7.50 |
+| Carrier pass-through | ~$2.50–$7.50 |
+| **Estimated Monthly Total** | **~$9.50–$17.00** |
+
+---
+
+## Rollback / De-provisioning
+
+If the pilot tenant must be de-provisioned:
+
+1. Release the phone number: Telnyx Portal → Phone Numbers → Release.
+2. Archive the campaign: set status to `INACTIVE` via API or console.
+3. Remove DB record: clear `messagingPhoneNumber`, `telnyxMessagingProfileId`, `telnyxCampaignId` fields in the business record.
+4. Brand can remain registered (no harm) but will not be used.
+
+---
+
+## Contacts
+
+| Resource | Contact |
+|----------|---------|
+| Telnyx Support | support@telnyx.com |
+| Telnyx Dashboard | portal.telnyx.com |
+| Internal Engineering | Raise issue in [GRO-106](/GRO/issues/GRO-106) |
+
+---
+
+_Last updated: 2026-05-04_

docs/runbooks/README.md

@@ -0,0 +1,11 @@
+# GroomBook Runbooks
+
+Operational runbooks for GroomBook staff and operators.
+
+| Runbook | Description | Status |
+|---------|-------------|--------|
+| [10DLC Pilot Registration](./10dlc-pilot-registration.md) | Register a pilot grooming business as an A2P 10DLC brand + campaign on Telnyx | Active |
+
+---
+
+_To add a runbook, create a markdown file in this directory and update this table._

opencode.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": "allow",
+  "experimental": {
+    "snapshots": false
+  }
+}

packages/db/src/seed.ts

@@ -883,7 +883,6 @@ async function seed() {
   let appointmentCount = 0;
   let invoiceCount = 0;
   let visitLogCount = 0;
-  let paidInvoiceCounter = 0;
 
   // Process in batches per client to keep memory manageable
   const apptBatchSize = 100;
@@ -978,11 +977,8 @@ async function seed() {
 
         const invoiceStatus = rand() < 0.95 ? "paid" as const : "pending" as const;
         const paidAt = invoiceStatus === "paid" ? new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000) : null;
-        paidInvoiceCounter++;
-        const stripePaymentIntentId = invoiceStatus === "paid"
-          ? `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`
-          : null;
 
+        const stripePaymentIntentId = invoiceStatus === "paid" && rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
         invoiceBatch.push({
           id: invoiceId,
           appointmentId: apptId,
@@ -1098,16 +1094,14 @@ async function seed() {
       const taxCents = Math.round(effectivePrice * 0.08);
       const totalCents = effectivePrice + taxCents + tipCents;
       const paidAt = new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000);
-      paidInvoiceCounter++;
+      const stripePaymentIntentId = rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
 
       invoiceBatch.push({
         id: invoiceId, appointmentId: apptId, clientId,
         subtotalCents: effectivePrice, taxCents, tipCents, totalCents,
         status: "paid" as const,
         paymentMethod: pick(["cash", "card", "card", "card", "check"]) as "cash" | "card" | "check",
-        paidAt,
+        paidAt, stripePaymentIntentId, notes: null,
-        stripePaymentIntentId: `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`,
-        notes: null,
       });
       lineItemBatch.push({
         id: uuid(), invoiceId, description: svc.name, quantity: 1,