diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c948c0..2f11272 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,32 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.51.0] - 2026-10-29
+
+### Added
+
+- **API v2** (`/api/v2`), the groundwork for 2.0: every endpoint is declared once with zod
+  schemas (`src/v2/route.ts`). The declaration validates the request, strips the response to what
+  the schema lists, and generates the **OpenAPI 3.1** document (`GET /api/v2/openapi.json`, admin)
+  shown at **`/docs/v2`** (Swagger UI, served locally). One error shape
+  `{ error: { code, message, fields? } }` with stable codes, and one list shape
+  `{ data, meta: { page, limit, total, pages } }`. First endpoints (read-only): `GET /events`,
+  `GET /events/:id`, `GET /me`, `GET /me/registrations`. v1 (`/api/…`) is unchanged.
+- **TypeScript in the backend:** `tsconfig.json` (`allowJs`; `.ts` strict), `npm run build` →
+  `dist/`, `npm run typecheck`, `npm run dev` through tsx, Jest runs `.ts` via ts-jest. Typed
+  doors into JS modules in `src/v2/legacy.ts`.
+- Tests: `tests/v2.test.ts`, e2e `e2e/api-v2.spec.ts`.
+
+### Changed
+
+- The server moved from `backend/src/index.js` to `backend/src/app.js`. `src/index.js` is now a
+  launcher that runs the matching build in `dist/` (or compiles on the fly with tsx when there is
+  none), so existing PM2 configs keep working unchanged.
+- `scripts/deploy.sh` and `scripts/install.sh` build the backend (`npm ci --include=dev`, then
+  `npm run build`); a rollback to a release before 1.51.0 skips the build. The first update to
+  1.51.0 by an older deploy script still starts (it compiles at start-up); the next update builds.
+- e2e starts the backend with tsx.
+
 ## [1.50.2] - 2026-10-29
 
 ### Added
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index cd347e3..228e0cf 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -305,7 +305,8 @@ cd /opt/hope-events
 sudo -u hopeevents -H bash scripts/deploy.sh v1.41.2     # or no tag for the latest main
 ```
 
-It backs up the database, checks out the release, installs, migrates, builds and reloads PM2,
+It backs up the database, checks out the release, installs, migrates, builds (the backend too,
+since 1.51.0) and reloads PM2,
 and goes back to the previous version if anything fails first. `backend/.env`,
 `frontend/.env.production`, `ecosystem.config.js` and the nginx/frpc configs are not in git, so
 updates keep your changes from this guide.
diff --git a/FEATURES.md b/FEATURES.md
index 967fa56..2a77f02 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -889,7 +889,10 @@ can't start, the same jobs run on in-process timers.
 - **Sentry** error monitoring when `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` are
   set.
 - Unhandled promise rejections are logged and don't crash the server.
-- Backend status page (`/`) and built-in API docs page (`/docs`).
+- Backend status page (`/`) and built-in API docs page (`/docs`); **API v2** (`/api/v2`, 1.51.0)
+  with one error shape, paged lists and an OpenAPI 3.1 reference at `/docs/v2` (admins).
+- **TypeScript backend** (1.51.0): `.ts` files are checked strictly, `.js` compiles as it is;
+  deploys build `dist/`, which `src/index.js` runs.
 - **Tests** — Jest unit tests in `backend/tests` (`npm test`), and Playwright
   end-to-end tests in `e2e/` (`npm run test:e2e`) that start their own backend and
   frontend against a separate, freshly seeded database: public pages, free and paid
diff --git a/WHATS-NEW.md b/WHATS-NEW.md
index 3cf206e..2e973ed 100644
--- a/WHATS-NEW.md
+++ b/WHATS-NEW.md
@@ -12,6 +12,12 @@ Write for church admins, not developers: no environment variables, endpoints or
 developer log is CHANGELOG.md. A tagged version without a section here shows "No details given".
 -->
 
+## 1.51.0
+
+- **Groundwork for Cross Events 2.0.** Behind the scenes, the server is moving to a newer, safer
+  way of talking to the app, ready for the AI helpers in 2.0. Nothing changes in how you use
+  Cross Events.
+
 ## 1.50.2
 
 - **Finding an event quickly.** Wherever staff and supervisors choose an event (the scanner, at
diff --git a/backend/API_DOCUMENTATION.md b/backend/API_DOCUMENTATION.md
index 5616a32..1093c3b 100644
--- a/backend/API_DOCUMENTATION.md
+++ b/backend/API_DOCUMENTATION.md
@@ -2,6 +2,12 @@
 
 Full interactive docs (with request/response examples) are available at `GET /docs?token=<admin-jwt>` on the running backend.
 
+> **API v2 (1.51.0 on):** `/api/v2` is described by OpenAPI 3.1. The reference is at `/docs/v2`
+> (admin token), the document at `GET /api/v2/openapi.json` (admin). It is generated from the route
+> declarations, so it is not repeated here. v2 responses are `{ data }` (lists add
+> `meta: { page, limit, total, pages }`, `?page=&limit=` up to 100) and errors
+> `{ error: { code, message, fields? } }`. This file documents v1 (`/api/…`), which stays until 2.0.
+
 All authenticated requests require:
 ```
 Authorization: Bearer <jwt>
diff --git a/backend/README.md b/backend/README.md
index 4cf19d4..4b1baf2 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -152,14 +152,22 @@ npm run prisma:generate
 ## Running the Server
 
 ```bash
-# Development (auto-reload)
+# Development (auto-reload; runs the TypeScript in src/ through tsx)
 npm run dev
 
-# Production
+# Production: build once per update, then start (src/index.js runs the build in dist/)
+npm run build
 npm start
+
+# Type-check only
+npm run typecheck
 ```
 
-Visit `/` for the status page. Visit `/docs?token=<admin-jwt>` for full API documentation (admin only).
+Since 1.51.0 the backend is partly TypeScript (`allowJs`: `.js` compiles as it is, `.ts` is checked
+strictly). `src/index.js` is a small launcher: with plain Node it runs `dist/` when `dist/build.json`
+matches this version, otherwise it compiles on the fly with tsx. The server itself is `src/app.js`.
+
+Visit `/` for the status page. Visit `/docs?token=<admin-jwt>` for the v1 API documentation and `/docs/v2` for the v2 (OpenAPI) reference — both admin only.
 
 ---
 
@@ -532,6 +540,7 @@ Setup: Admin → Site Settings → **Yoco**. Paste the secret key (checked with
 ### PM2 (recommended)
 ```bash
 npm install -g pm2
+npm run build
 pm2 start src/index.js --name hope-events-api
 pm2 save && pm2 startup
 ```
diff --git a/backend/jest.config.js b/backend/jest.config.js
index dc0a5df..568035d 100644
--- a/backend/jest.config.js
+++ b/backend/jest.config.js
@@ -1,4 +1,8 @@
 module.exports = {
   testEnvironment: 'node',
-  testMatch: ['**/tests/**/*.test.js'],
+  testMatch: ['**/tests/**/*.test.js', '**/tests/**/*.test.ts'],
+  // TypeScript (src/**/*.ts and tests) runs through ts-jest; plain JS is left as it is.
+  transform: { '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.json' }] },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
 };
diff --git a/backend/package-lock.json b/backend/package-lock.json
index 0ca566b..08fa20f 100644
--- a/backend/package-lock.json
+++ b/backend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "event-management-backend",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "event-management-backend",
-      "version": "1.50.2",
+      "version": "1.51.0",
       "hasInstallScript": true,
       "dependencies": {
         "@prisma/adapter-pg": "^7.10.1",
@@ -29,11 +29,23 @@
         "pg-boss": "^10.4.2",
         "qrcode": "^1.5.4",
         "raw-body": "^3.0.0",
-        "uuid": "^11.1.1"
+        "swagger-ui-dist": "^5.34.0",
+        "tsx": "^4.23.15",
+        "typescript": "^5.9.3",
+        "uuid": "^11.1.1",
+        "zod": "^4.4.3"
       },
       "devDependencies": {
+        "@types/express": "^4.17.25",
+        "@types/jest": "^30.0.0",
+        "@types/jsonwebtoken": "^9.0.10",
+        "@types/node": "^20.19.43",
+        "@types/supertest": "^7.2.1",
+        "@types/swagger-ui-dist": "^3.30.6",
         "jest": "^30.4.2",
-        "prisma": "^7.10.1"
+        "prisma": "^7.10.1",
+        "supertest": "^7.3.1",
+        "ts-jest": "^29.4.15"
       }
     },
     "node_modules/@apm-js-collab/code-transformer": {
@@ -732,6 +744,422 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+      "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+      "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+      "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+      "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+      "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+      "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+      "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+      "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+      "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+      "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+      "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+      "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+      "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+      "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+      "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+      "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+      "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+      "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+      "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+      "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+      "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@fast-csv/format": {
       "version": "4.3.5",
       "resolved": "https://registry.npmjs.org/@fast-csv/format/-/format-4.3.5.tgz",
@@ -746,6 +1174,12 @@
         "lodash.isnil": "^4.0.0"
       }
     },
+    "node_modules/@fast-csv/format/node_modules/@types/node": {
+      "version": "14.18.63",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.63.tgz",
+      "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==",
+      "license": "MIT"
+    },
     "node_modules/@fast-csv/parse": {
       "version": "4.3.6",
       "resolved": "https://registry.npmjs.org/@fast-csv/parse/-/parse-4.3.6.tgz",
@@ -761,6 +1195,12 @@
         "lodash.uniq": "^4.5.0"
       }
     },
+    "node_modules/@fast-csv/parse/node_modules/@types/node": {
+      "version": "14.18.63",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.63.tgz",
+      "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==",
+      "license": "MIT"
+    },
     "node_modules/@isaacs/cliui": {
       "version": "8.0.2",
       "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
@@ -1377,6 +1817,19 @@
         "@emnapi/runtime": "^1.7.1 || ^2.0.0-alpha.4"
       }
     },
+    "node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@opentelemetry/api": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.1.tgz",
@@ -1490,6 +1943,16 @@
         "node": ">=14"
       }
     },
+    "node_modules/@paralleldrive/cuid2": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
+      "integrity": "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "^1.1.5"
+      }
+    },
     "node_modules/@parcel/watcher": {
       "version": "2.6.0",
       "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.6.0.tgz",
@@ -2178,6 +2641,13 @@
         }
       }
     },
+    "node_modules/@scarf/scarf": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",
+      "integrity": "sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0"
+    },
     "node_modules/@sentry/conventions": {
       "version": "0.16.0",
       "resolved": "https://registry.npmjs.org/@sentry/conventions/-/conventions-0.16.0.tgz",
@@ -2391,6 +2861,34 @@
         "@babel/types": "^7.28.2"
       }
     },
+    "node_modules/@types/body-parser": {
+      "version": "1.19.6",
+      "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
+      "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/connect": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/connect": {
+      "version": "3.4.38",
+      "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
+      "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/cookiejar": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@types/cookiejar/-/cookiejar-2.1.5.tgz",
+      "integrity": "sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/d3-array": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.0.3.tgz",
@@ -2486,6 +2984,32 @@
       "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
       "license": "MIT"
     },
+    "node_modules/@types/express": {
+      "version": "4.17.25",
+      "resolved": "https://registry.npmjs.org/@types/express/-/express-4.17.25.tgz",
+      "integrity": "sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/body-parser": "*",
+        "@types/express-serve-static-core": "^4.17.33",
+        "@types/qs": "*",
+        "@types/serve-static": "^1"
+      }
+    },
+    "node_modules/@types/express-serve-static-core": {
+      "version": "4.19.9",
+      "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-4.19.9.tgz",
+      "integrity": "sha512-QP2ESEe/ImWY0HDwNAnK9PvEffUyhLTnWkk7KXzHfyeWAnlrDe1fN77bXl6ia8KT3wPlmA7t9/VPRpnf4Ex9sg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "@types/qs": "*",
+        "@types/range-parser": "*",
+        "@types/send": "*"
+      }
+    },
     "node_modules/@types/geojson": {
       "version": "7946.0.16",
       "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
@@ -2493,6 +3017,13 @@
       "devOptional": true,
       "license": "MIT"
     },
+    "node_modules/@types/http-errors": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
+      "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/istanbul-lib-coverage": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz",
@@ -2520,6 +3051,28 @@
         "@types/istanbul-lib-report": "*"
       }
     },
+    "node_modules/@types/jest": {
+      "version": "30.0.0",
+      "resolved": "https://registry.npmjs.org/@types/jest/-/jest-30.0.0.tgz",
+      "integrity": "sha512-XTYugzhuwqWjws0CVz8QpM36+T+Dz5mTEBKhNs/esGLnCIlGdRy+Dq78NRjd7ls7r8BC8ZRMOrKlkO1hU0JOwA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "expect": "^30.0.0",
+        "pretty-format": "^30.0.0"
+      }
+    },
+    "node_modules/@types/jsonwebtoken": {
+      "version": "9.0.10",
+      "resolved": "https://registry.npmjs.org/@types/jsonwebtoken/-/jsonwebtoken-9.0.10.tgz",
+      "integrity": "sha512-asx5hIG9Qmf/1oStypjanR7iKTv0gXQ1Ov/jfrX6kS/EO0OFni8orbmGCn0672NHR3kXHwpAwR+B368ZGN/2rA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/ms": "*",
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/lodash": {
       "version": "4.17.26",
       "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.17.26.tgz",
@@ -2527,12 +3080,36 @@
       "devOptional": true,
       "license": "MIT"
     },
-    "node_modules/@types/node": {
-      "version": "14.18.63",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.63.tgz",
-      "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==",
+    "node_modules/@types/methods": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
+      "integrity": "sha512-ymXWVrDiCxTBE3+RIrrP533E70eA+9qu7zdWoHuOmGujkYtzf4HQF96b8nwHLqhuf4ykX61IGRIB38CC6/sImQ==",
+      "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/mime": {
+      "version": "1.3.5",
+      "resolved": "https://registry.npmjs.org/@types/mime/-/mime-1.3.5.tgz",
+      "integrity": "sha512-/pyBZWSLD2n0dcHE3hq8s8ZvcETHtEuF+3E7XVt0Ig2nvsVQXdghHVcEkIWjy9A0wKfTn97a/PSDYohKIlnP/w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
     "node_modules/@types/pg": {
       "version": "8.23.1",
       "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.23.1.tgz",
@@ -2544,6 +3121,20 @@
         "pg-types": "^2.2.0"
       }
     },
+    "node_modules/@types/qs": {
+      "version": "6.15.1",
+      "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.1.tgz",
+      "integrity": "sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/range-parser": {
+      "version": "1.2.7",
+      "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
+      "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/react": {
       "version": "19.3.0",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
@@ -2554,6 +3145,39 @@
         "csstype": "^3.2.2"
       }
     },
+    "node_modules/@types/send": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
+      "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/serve-static": {
+      "version": "1.15.10",
+      "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-1.15.10.tgz",
+      "integrity": "sha512-tRs1dB+g8Itk72rlSI2ZrW6vZg0YrLI81iQSTkMmOqnqCaNr/8Ek4VwWcN5vZgCYWbg/JJSGBlUaYGAOP73qBw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/http-errors": "*",
+        "@types/node": "*",
+        "@types/send": "<1"
+      }
+    },
+    "node_modules/@types/serve-static/node_modules/@types/send": {
+      "version": "0.17.6",
+      "resolved": "https://registry.npmjs.org/@types/send/-/send-0.17.6.tgz",
+      "integrity": "sha512-Uqt8rPBE8SY0RK8JB1EzVOIZ32uqy8HwdxCnoCOsYrvnswqmFZ/k+9Ikidlk/ImhsdvBsloHbAlewb2IEBV/Og==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/mime": "^1",
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/stack-utils": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",
@@ -2561,6 +3185,37 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/superagent": {
+      "version": "8.1.11",
+      "resolved": "https://registry.npmjs.org/@types/superagent/-/superagent-8.1.11.tgz",
+      "integrity": "sha512-KA7srSW/HENDtOw9DOqaFLgWuMqN9WgjEw62lh9dpvRaZDkhdOkazASd7X7i2eMUYLHa1U37ZttnePsH5zTDHw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cookiejar": "^2.1.5",
+        "@types/methods": "^1.1.4",
+        "@types/node": "*",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@types/supertest": {
+      "version": "7.2.1",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-7.2.1.tgz",
+      "integrity": "sha512-4CbBvoYVLHL7+yhbYrZET0vsvuyXTC05aRe7dNQkwMzm56auceoy6Yu3K50uZmwfHna1os3CMSgM/3QVkUtPTw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
+    "node_modules/@types/swagger-ui-dist": {
+      "version": "3.30.6",
+      "resolved": "https://registry.npmjs.org/@types/swagger-ui-dist/-/swagger-ui-dist-3.30.6.tgz",
+      "integrity": "sha512-FVxN7wjLYRtJsZBscOcOcf8oR++m38vbUFjT33Mr9HBuasX9bRDrJsp7iwixcOtKSHEEa2B7o2+4wEiXqC+Ebw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/yargs": {
       "version": "17.0.35",
       "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.35.tgz",
@@ -3256,6 +3911,13 @@
       "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
       "license": "MIT"
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/astring": {
       "version": "1.9.0",
       "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz",
@@ -3610,6 +4272,19 @@
         "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
       }
     },
+    "node_modules/bs-logger": {
+      "version": "0.2.6",
+      "resolved": "https://registry.npmjs.org/bs-logger/-/bs-logger-0.2.6.tgz",
+      "integrity": "sha512-pd8DCoxmbgc7hyPKOvxtqNcjYoOsABPQdcCUjGp3d42VR2CX1ORhk2A87oqqu5R1kk+76nsxZupkmyd+MVtCog==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-json-stable-stringify": "2.x"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/bser": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/bser/-/bser-2.1.1.tgz",
@@ -3982,6 +4657,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/compress-commons": {
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/compress-commons/-/compress-commons-4.1.2.tgz",
@@ -4053,6 +4738,13 @@
       "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
       "license": "MIT"
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/core-util-is": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
@@ -4417,6 +5109,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/dezalgo": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/dezalgo/-/dezalgo-1.0.4.tgz",
+      "integrity": "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "asap": "^2.0.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/dfa": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/dfa/-/dfa-1.2.0.tgz",
@@ -4662,6 +5365,47 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/esbuild": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+      "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.2",
+        "@esbuild/android-arm": "0.28.2",
+        "@esbuild/android-arm64": "0.28.2",
+        "@esbuild/android-x64": "0.28.2",
+        "@esbuild/darwin-arm64": "0.28.2",
+        "@esbuild/darwin-x64": "0.28.2",
+        "@esbuild/freebsd-arm64": "0.28.2",
+        "@esbuild/freebsd-x64": "0.28.2",
+        "@esbuild/linux-arm": "0.28.2",
+        "@esbuild/linux-arm64": "0.28.2",
+        "@esbuild/linux-ia32": "0.28.2",
+        "@esbuild/linux-loong64": "0.28.2",
+        "@esbuild/linux-mips64el": "0.28.2",
+        "@esbuild/linux-ppc64": "0.28.2",
+        "@esbuild/linux-riscv64": "0.28.2",
+        "@esbuild/linux-s390x": "0.28.2",
+        "@esbuild/linux-x64": "0.28.2",
+        "@esbuild/netbsd-arm64": "0.28.2",
+        "@esbuild/netbsd-x64": "0.28.2",
+        "@esbuild/openbsd-arm64": "0.28.2",
+        "@esbuild/openbsd-x64": "0.28.2",
+        "@esbuild/openharmony-arm64": "0.28.2",
+        "@esbuild/sunos-x64": "0.28.2",
+        "@esbuild/win32-arm64": "0.28.2",
+        "@esbuild/win32-ia32": "0.28.2",
+        "@esbuild/win32-x64": "0.28.2"
+      }
+    },
     "node_modules/escalade": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -4968,6 +5712,13 @@
         "fast-decode-uri-component": "^1.0.1"
       }
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fast-uri": {
       "version": "3.1.9",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz",
@@ -5124,6 +5875,24 @@
         "node": ">= 6"
       }
     },
+    "node_modules/formidable": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-3.5.4.tgz",
+      "integrity": "sha512-YikH+7CUTOtP44ZTnUhR7Ic2UASBPOqmaRkRKxRbywPTe5VxF7RRCck4af9wutiZ/QKM5nME9Bie2fFaPz5Gug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "dezalgo": "^1.0.4",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -5154,6 +5923,20 @@
       "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
       "license": "ISC"
     },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/fstream": {
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/fstream/-/fstream-1.0.12.tgz",
@@ -5338,6 +6121,28 @@
       "devOptional": true,
       "license": "MIT"
     },
+    "node_modules/handlebars": {
+      "version": "4.7.10",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.10.tgz",
+      "integrity": "sha512-P5VJMVM7qgBn6vjXMw8WG9uVI+ncf2pi72j4de4yz5ZULLj2RGqLYaKOYGsgyrViQ0tePOVlN1tDCCXXtFqXKg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "minimist": "^1.2.8",
+        "neo-async": "^2.6.2",
+        "source-map": "^0.6.1",
+        "wordwrap": "^1.0.0"
+      },
+      "bin": {
+        "handlebars": "bin/handlebars"
+      },
+      "engines": {
+        "node": ">=0.4.7"
+      },
+      "optionalDependencies": {
+        "uglify-js": "^3.1.4"
+      }
+    },
     "node_modules/has-symbols": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
@@ -7050,6 +7855,13 @@
       "integrity": "sha512-MXB1is3s899/cD8jheYYE2V9qTHwKvt+npCwpD+1Sxm3Q3cECXCiYHjeHWXNwr6Q0SOBPrYUDxendrO6goVTEA==",
       "license": "MIT"
     },
+    "node_modules/lodash.memoize": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz",
+      "integrity": "sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/lodash.once": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/lodash.once/-/lodash.once-4.1.1.tgz",
@@ -7135,6 +7947,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/make-error": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
+      "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -7405,6 +8224,13 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/neo-async": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz",
+      "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/node-addon-api": {
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
@@ -8466,9 +9292,9 @@
       "license": "Apache-2.0"
     },
     "node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
@@ -8871,6 +9697,99 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/superagent": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.4.1.tgz",
+      "integrity": "sha512-PVMkMrhKrSTtFhUU8jiWuGh/gyRMKiyCTCmm0+qVzRNxlfntmRKJkDhlEXN62x3HIb33sQ4kmL8lcSdccWAchQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/superagent/node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/superagent/node_modules/mime": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
+      "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/superagent/node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/supertest": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.3.1.tgz",
+      "integrity": "sha512-vNaNCFoCR/edDbErQZp5KLNT8R4dSPHX7rlDLoE8hWLAm/878j6ShMbe8HK/E6RwwuhlSXVelXAIg9AxR5WWPw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/supertest/node_modules/cookie-signature": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
+      "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.6.0"
+      }
+    },
+    "node_modules/swagger-ui-dist": {
+      "version": "5.34.0",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.34.0.tgz",
+      "integrity": "sha512-H6tAIjr3XqE31PbkZl0OFya1ziRLDfTwh3J6OHdumPtPCLfjTnyLeagl/55kFNZcTOz9a9QI9WP0FXldwiGJag==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@scarf/scarf": "=1.4.0"
+      }
+    },
     "node_modules/synckit": {
       "version": "0.11.13",
       "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.11.13.tgz",
@@ -9087,12 +10006,106 @@
         "node": "*"
       }
     },
+    "node_modules/ts-jest": {
+      "version": "29.4.15",
+      "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-29.4.15.tgz",
+      "integrity": "sha512-s2qmEUYFRqbjz1wv0EmccNPVOb45HOFpFuhzQJLKShYVisuTbCFPIIAIV2EuK5rIxb4BejLDbH7dnBZfYjybUQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bs-logger": "^0.2.6",
+        "fast-json-stable-stringify": "^2.1.0",
+        "handlebars": "^4.7.10",
+        "json5": "^2.2.3",
+        "lodash.memoize": "^4.1.2",
+        "make-error": "^1.3.6",
+        "semver": "^7.8.5",
+        "type-fest": "^4.41.0",
+        "yargs-parser": "^21.1.1"
+      },
+      "bin": {
+        "ts-jest": "cli.js"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || ^18.0.0 || >=20.0.0"
+      },
+      "peerDependencies": {
+        "@babel/core": ">=7.0.0-beta.0 <9",
+        "@jest/transform": "^29.0.0 || ^30.0.0",
+        "@jest/types": "^29.0.0 || ^30.0.0",
+        "babel-jest": "^29.0.0 || ^30.0.0",
+        "jest": "^29.0.0 || ^30.0.0",
+        "jest-util": "^29.0.0 || ^30.0.0",
+        "typescript": ">=4.3 <7"
+      },
+      "peerDependenciesMeta": {
+        "@babel/core": {
+          "optional": true
+        },
+        "@jest/transform": {
+          "optional": true
+        },
+        "@jest/types": {
+          "optional": true
+        },
+        "babel-jest": {
+          "optional": true
+        },
+        "esbuild": {
+          "optional": true
+        },
+        "jest-util": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ts-jest/node_modules/type-fest": {
+      "version": "4.41.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
+      "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
+      "dev": true,
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ts-jest/node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
       "license": "0BSD"
     },
+    "node_modules/tsx": {
+      "version": "4.23.15",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.15.tgz",
+      "integrity": "sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==",
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
     "node_modules/type-detect": {
       "version": "4.0.8",
       "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz",
@@ -9129,6 +10142,39 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/uglify-js": {
+      "version": "3.19.3",
+      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz",
+      "integrity": "sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "bin": {
+        "uglifyjs": "bin/uglifyjs"
+      },
+      "engines": {
+        "node": ">=0.8.0"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "license": "MIT"
+    },
     "node_modules/unicode-properties": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/unicode-properties/-/unicode-properties-1.4.1.tgz",
@@ -9380,6 +10426,13 @@
       "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==",
       "license": "ISC"
     },
+    "node_modules/wordwrap": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz",
+      "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/wrap-ansi": {
       "version": "6.2.0",
       "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
@@ -9591,6 +10644,15 @@
       "engines": {
         "node": ">= 10"
       }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
     }
   }
 }
diff --git a/backend/package.json b/backend/package.json
index ed1ec27..98f5cbe 100644
--- a/backend/package.json
+++ b/backend/package.json
@@ -1,11 +1,11 @@
 {
   "name": "event-management-backend",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "description": "Event Management System Backend",
   "main": "src/index.js",
   "scripts": {
     "start": "node src/index.js",
-    "dev": "node --watch src/index.js",
+    "dev": "tsx watch src/index.js",
     "test": "jest",
     "postinstall": "prisma generate",
     "prisma:generate": "prisma generate",
@@ -14,7 +14,9 @@
     "prisma:reset": "prisma migrate reset --force",
     "migrate:env-to-db": "node scripts/migrate-env-to-db.js",
     "migrate:env-to-db:dry": "node scripts/migrate-env-to-db.js --dry-run",
-    "set-demo": "node scripts/set-demo.js"
+    "set-demo": "node scripts/set-demo.js",
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').writeFileSync('dist/build.json', JSON.stringify({ version: require('./package.json').version, builtAt: new Date().toISOString() }))\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@prisma/adapter-pg": "^7.10.1",
@@ -37,11 +39,23 @@
     "pg-boss": "^10.4.2",
     "qrcode": "^1.5.4",
     "raw-body": "^3.0.0",
-    "uuid": "^11.1.1"
+    "swagger-ui-dist": "^5.34.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "uuid": "^11.1.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/jest": "^30.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^20.19.43",
+    "@types/supertest": "^7.2.1",
+    "@types/swagger-ui-dist": "^3.30.6",
     "jest": "^30.4.2",
-    "prisma": "^7.10.1"
+    "prisma": "^7.10.1",
+    "supertest": "^7.3.1",
+    "ts-jest": "^29.4.15"
   },
   "overrides": {
     "uuid": "^11.1.1",
@@ -54,6 +68,8 @@
     "prisma@7.10.1": true,
     "@prisma/engines@7.10.1": true,
     "unrs-resolver@1.12.2": true,
-    "@parcel/watcher": false
+    "@parcel/watcher": false,
+    "@scarf/scarf": false,
+    "esbuild": false
   }
 }
diff --git a/backend/src/app.js b/backend/src/app.js
new file mode 100644
index 0000000..e3695e9
--- /dev/null
+++ b/backend/src/app.js
@@ -0,0 +1,1812 @@
+const path = require('path');
+const dotenv = require('dotenv');
+
+// Load environment variables
+dotenv.config();
+
+// Error monitoring — a no-op if SENTRY_DSN isn't set, so this is safe in every
+// environment (dev, a fresh deploy that hasn't configured Sentry yet, etc.).
+// Must run before express/@prisma/client are required below — Sentry's
+// auto-instrumentation patches those modules via a require hook, which only
+// works if Sentry.init() runs before they're first required into the cache.
+if (process.env.SENTRY_DSN) {
+  const Sentry = require('@sentry/node');
+  Sentry.init({
+    dsn: process.env.SENTRY_DSN,
+    environment: process.env.NODE_ENV || 'development',
+    // Small single-VM deployment, not high-traffic — start conservative and raise
+    // this once real usage is visible in Sentry, rather than sampling every request.
+    tracesSampleRate: 0.1,
+  });
+}
+
+const express = require('express');
+const { version: API_VERSION } = require('../package.json');
+const cors = require('cors');
+const rateLimit = require('express-rate-limit');
+const prisma = require('./config/db');
+const { notFound, errorHandler } = require('./middleware/errorMiddleware');
+const getRawBody = require('raw-body');
+
+// Initialize Express app
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Trust proxy — required when running behind a reverse proxy (e.g. nginx on a
+// separate server) so req.ip / X-Forwarded-For are read correctly by
+// express-rate-limit and friends. Accepts a hop count ("1"), "true"/"false",
+// or a comma-separated list of trusted proxy IPs/CIDRs.
+if (process.env.TRUST_PROXY) {
+  const raw = process.env.TRUST_PROXY.trim();
+  let trustProxyValue;
+  if (raw === 'true') trustProxyValue = true;
+  else if (raw === 'false') trustProxyValue = false;
+  else if (/^\d+$/.test(raw)) trustProxyValue = parseInt(raw, 10);
+  else if (raw.includes(',')) trustProxyValue = raw.split(',').map((s) => s.trim());
+  else trustProxyValue = raw;
+  app.set('trust proxy', trustProxyValue);
+  console.log(`[startup] trust proxy set to: ${JSON.stringify(trustProxyValue)}`);
+}
+
+// CORS — allow only the configured frontend origin
+const allowedOrigins = (process.env.FRONTEND_URL || 'http://localhost:3000')
+  .split(',')
+  .map((o) => o.trim());
+
+const isDev = process.env.NODE_ENV === 'development' || !process.env.NODE_ENV;
+const isTesting = process.env.NODE_ENV === 'testing';
+const isProd = process.env.NODE_ENV === 'production';
+const modeLabel = isProd ? 'production' : isTesting ? 'testing' : 'development';
+console.log(`Running in ${modeLabel} mode.`);
+
+// In testing or production, require all critical env vars to be set at startup
+if (isTesting || isProd) {
+  const required = ['DATABASE_URL', 'JWT_SECRET'];
+  const missing = required.filter(k => !process.env[k]);
+  if (missing.length > 0) {
+    console.error(`[startup] Missing required environment variables for ${modeLabel} mode: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+}
+
+app.use(cors({
+  origin: (origin, callback) => {
+    // Allow requests with no origin (e.g. mobile apps, curl, Postman)
+    if (!origin) return callback(null, true);
+    // Always allow configured origins
+    if (allowedOrigins.includes(origin)) return callback(null, true);
+    // In dev or testing, also allow any LAN origin on the same port (e.g. phone on 192.168.x.x:3000)
+    if (isDev || isTesting) {
+      try {
+        const u = new URL(origin);
+        const isLan = /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(u.hostname);
+        if (isLan) return callback(null, true);
+      } catch {}
+    }
+    callback(new Error(`CORS: origin '${origin}' not allowed`));
+  },
+  credentials: true,
+}));
+
+// Global rate limiter — 5000 requests per 5 minutes per IP
+// Webhooks are excluded because they come from Yoco's servers and are already HMAC-verified
+const globalLimiter = rateLimit({
+  windowMs: 5 * 60 * 1000,
+  max: 5000,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { message: 'Too many requests, please try again later.' },
+  skip: (req) => req.path.startsWith('/api/webhooks'),
+});
+app.use(globalLimiter);
+
+// Impersonation is strictly read-only: refuse every write made with an impersonation
+// token before it can reach any route (see utils/impersonation.js).
+app.use(require('./utils/impersonation').readOnlyGuard);
+
+// Raw body parsing middleware for webhooks
+app.use((req, res, next) => {
+  if (req.path.startsWith('/api/webhooks')) {
+    getRawBody(req, {
+      length: req.headers['content-length'],
+      encoding: 'utf-8'
+    }, (err, rawBody) => {
+      if (err) return next(err);
+      req.rawBody = rawBody;
+      next();
+    });
+  } else {
+    next();
+  }
+});
+
+
+// Import routes
+const userRoutes = require('./routes/userRoutes');
+const eventRoutes = require('./routes/eventRoutes');
+const registrationRoutes = require('./routes/registrationRoutes');
+const paymentRoutes = require('./routes/paymentRoutes');
+const ticketRoutes = require('./routes/ticketRoutes');
+const webhookRoutes = require('./routes/webhookRoutes');
+const uploadRoutes = require('./routes/uploadRoutes');
+const reportRoutes = require('./routes/reportRoutes');
+const formRoutes = require('./routes/formRoutes');
+const providerTransactionRoutes = require('./routes/providerTransactionRoutes');
+const automationRoutes = require('./routes/automationRoutes');
+const broadcastRoutes = require('./routes/broadcastRoutes');
+const whatsappBroadcastRoutes = require('./routes/whatsappBroadcastRoutes');
+const scheduledEmailRoutes = require('./routes/scheduledEmailRoutes');
+const sectionRoutes = require('./routes/sectionRoutes');
+const bannerRoutes    = require('./routes/bannerRoutes');
+const whatsappRoutes  = require('./routes/whatsappRoutes');
+const settingsRoutes  = require('./routes/settingsRoutes');
+const setupRoutes     = require('./routes/setupRoutes');
+const costRoutes      = require('./routes/costRoutes');
+const cashupRoutes    = require('./routes/cashupRoutes');
+const statsRoutes     = require('./routes/statsRoutes');
+const adminRoutes     = require('./routes/adminRoutes');
+const backupRoutes    = require('./routes/backupRoutes');
+const yocoRoutes      = require('./routes/yocoRoutes');
+const payfastRoutes   = require('./routes/payfastRoutes');
+const privacyRoutes   = require('./routes/privacyRoutes');
+
+// Mount webhook routes BEFORE JSON body parser to avoid double-reading the stream
+app.use('/api/webhooks', webhookRoutes);
+
+// Apply JSON body parser for all non-webhook routes
+app.use(express.json());
+
+// Count server errors (any 5xx response) for the Hub heartbeat.
+app.use((req, res, next) => {
+  res.on('finish', () => { if (res.statusCode >= 500) require('./utils/errorCounter').recordError(); });
+  next();
+});
+
+// Licence suspended, revoked or missing: no new or edited events, registrations or payments (src/hub/readOnly.js).
+app.use(require('./hub/readOnly').licenceReadOnly);
+
+// Health for monitoring (and the Hub): no secrets, no personal information.
+app.get('/health', async (req, res) => {
+  const report = require('./hub/report');
+  let db = true;
+  try { await prisma.$queryRaw`SELECT 1`; } catch { db = false; }
+  const health = db ? await report.health().catch(() => null) : null;
+  res.status(db ? 200 : 503).json({
+    status: db ? 'ok' : 'error',
+    version: report.APP_VERSION,
+    db,
+    jobs: health?.jobs || null,
+    lastBackupAt: health?.lastBackupAt || null,
+  });
+});
+
+// Use routes
+// /api/v2 (1.51.0, TypeScript): consistent errors and paging, described by OpenAPI at /docs/v2.
+app.use('/api/v2', require('./v2').v2Router());
+app.use('/docs/v2', require('./v2').v2DocsRouter());
+app.use('/api/hub', require('./routes/hubRoutes'));
+app.use('/api/campuses', require('./routes/campusRoutes'));
+app.use('/api/kids', require('./routes/kidsRoutes'));
+app.use('/api/volunteers', require('./routes/volunteerRoutes'));
+app.use('/api/series', require('./routes/seriesRoutes'));
+app.use('/api/season-passes', require('./routes/seasonPassRoutes'));
+app.use('/api/outbound-webhooks', require('./routes/outboundWebhookRoutes'));
+app.use('/api/dashboard', require('./routes/dashboardRoutes'));
+app.use('/api/saved-filters', require('./routes/savedFilterRoutes'));
+app.use('/api/users', userRoutes);
+app.use('/api/events', eventRoutes);
+app.use('/api/registrations', registrationRoutes);
+app.use('/api/payments', paymentRoutes);
+app.use('/api/tickets', ticketRoutes);
+app.use('/api/uploads', uploadRoutes);
+app.use('/api/reports', reportRoutes);
+app.use('/api/forms', formRoutes);
+app.use('/api/provider-transactions', providerTransactionRoutes);
+app.use('/api/yoco-transactions', providerTransactionRoutes); // older name
+app.use('/api/automations', automationRoutes);
+app.use('/api/broadcasts', broadcastRoutes);
+app.use('/api/whatsapp-broadcasts', whatsappBroadcastRoutes);
+app.use('/api/scheduled-emails', scheduledEmailRoutes);
+app.use('/api/sections', sectionRoutes);
+app.use('/api/banner',    bannerRoutes);
+app.use('/api/whatsapp', whatsappRoutes);
+app.use('/api/privacy',  privacyRoutes);
+app.use('/api/settings', settingsRoutes);
+app.use('/api/setup',    setupRoutes);
+app.use('/api/stats',    statsRoutes);
+app.use('/api', costRoutes);
+app.use('/api/cashups', cashupRoutes);
+app.use('/api/admin', adminRoutes);
+app.use('/api/coupons', require('./routes/couponRoutes'));
+app.use('/api/bundles', require('./routes/bundleRoutes'));
+app.use('/api/consent', require('./routes/consentRoutes'));
+app.use('/api/waitlist', require('./routes/waitlistRoutes'));
+app.use('/api/scan-locks', require('./routes/scanLockRoutes'));
+app.use('/api/allocations', require('./routes/allocationRoutes'));
+app.use('/api/sponsorships', require('./routes/sponsorshipRoutes'));
+app.use('/api/feedback', require('./routes/feedbackRoutes'));
+app.use('/api/attendance', require('./routes/attendanceRoutes'));
+app.use('/api/analytics', require('./routes/analyticsRoutes'));
+app.use('/api/backups', backupRoutes);
+app.use('/api/yoco', yocoRoutes);
+app.use('/api/payfast', payfastRoutes);
+
+// Pre-warm the settings cache so synchronous helpers have DB values from startup
+const { getSettingSync, warmCache } = require('./utils/settingsCache');
+warmCache().catch(() => {});
+// Uploaded branding assets can include SVGs, which may embed <script>/event
+// handlers. Serving them inline lets a compromised/malicious upload run script
+// in the site's origin if opened directly, so pin the safe response headers
+// (no inline execution, no MIME-sniffing to HTML/script) on every asset here.
+app.use('/uploads', express.static('public/uploads', {
+  setHeaders: (res) => {
+    res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+  },
+}));
+
+// ── Shared page helpers ────────────────────────────────────────────────────────
+const jwt = require('jsonwebtoken');
+
+function pageShell(title, accentColor, bodyHtml) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <style>
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f3f4f6;color:#1f2937;min-height:100vh;padding:24px 16px}
+    .wrap{max-width:960px;margin:0 auto}
+    h1{font-size:1.5rem;font-weight:700;color:#111827;margin-bottom:4px}
+    h2{font-size:1.1rem;font-weight:600;color:#111827;margin:24px 0 10px}
+    .subtitle{font-size:.85rem;color:#6b7280;margin-bottom:24px}
+    .card{background:#fff;border:1px solid #e5e7eb;border-radius:10px;padding:20px;margin-bottom:16px}
+    .stat-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:12px;margin-bottom:16px}
+    .stat{background:#fff;border:1px solid #e5e7eb;border-radius:8px;padding:14px 16px}
+    .stat-label{font-size:.72rem;text-transform:uppercase;letter-spacing:.05em;color:#6b7280;margin-bottom:4px}
+    .stat-value{font-size:1.1rem;font-weight:600;color:#111827}
+    .badge{display:inline-block;padding:2px 8px;border-radius:999px;font-size:.75rem;font-weight:600}
+    .badge-ok{background:#d1fae5;color:#065f46}
+    .badge-warn{background:#fef3c7;color:#92400e}
+    .badge-err{background:#fee2e2;color:#991b1b}
+    table{width:100%;border-collapse:collapse;font-size:.82rem}
+    th{text-align:left;padding:6px 10px;background:#f9fafb;border-bottom:1px solid #e5e7eb;font-weight:600;color:#374151}
+    td{padding:6px 10px;border-bottom:1px solid #f3f4f6;color:#374151;vertical-align:top}
+    tr:last-child td{border-bottom:none}
+    .method{display:inline-block;padding:1px 7px;border-radius:4px;font-size:.7rem;font-weight:700;font-family:monospace}
+    .get{background:#dbeafe;color:#1e40af}
+    .post{background:#d1fae5;color:#065f46}
+    .put{background:#fef3c7;color:#92400e}
+    .patch{background:#ede9fe;color:#5b21b6}
+    .del{background:#fee2e2;color:#991b1b}
+    .auth-badge{font-size:.68rem;padding:1px 6px;border-radius:4px;background:#f3f4f6;color:#374151;font-family:monospace}
+    code{background:#f3f4f6;padding:1px 5px;border-radius:4px;font-family:monospace;font-size:.82rem}
+    .note{background:#eff6ff;border:1px solid #bfdbfe;border-radius:8px;padding:12px 16px;font-size:.82rem;color:#1e40af;margin-bottom:16px}
+    .accent{color:${accentColor}}
+    a{color:${accentColor};text-decoration:none}
+    a:hover{text-decoration:underline}
+  </style>
+</head>
+<body>
+<div class="wrap">
+${bodyHtml}
+</div>
+</body>
+</html>`;
+}
+
+function formatUptime(seconds) {
+  const d = Math.floor(seconds / 86400);
+  const h = Math.floor((seconds % 86400) / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  if (d > 0) return `${d}d ${h}h ${m}m`;
+  if (h > 0) return `${h}h ${m}m ${s}s`;
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1048576).toFixed(1)} MB`;
+}
+
+// ── Favicon ──────────────────────────────────────────────────────────────────
+app.get('/favicon.ico', (req, res) => {
+  // From src/ either way (the build in dist/ copies only code).
+  res.sendFile(path.join(__dirname, '..', 'src', 'favicon.ico'));
+});
+
+// ── Root route — status page ────────────────────────────────────────────────
+app.get('/', async (req, res) => {
+  const mem = process.memoryUsage();
+  const uptimeSec = process.uptime();
+  const now = new Date().toISOString();
+
+  // Database health check
+  let dbStatus = 'ok';
+  let dbMsg = 'Connected';
+  try {
+    await prisma.$queryRaw`SELECT 1`;
+  } catch (e) {
+    dbStatus = 'error';
+    dbMsg = 'Unreachable';
+  }
+
+  const dbBadge = dbStatus === 'ok'
+    ? `<span class="badge badge-ok">&#10003; ${dbMsg}</span>`
+    : `<span class="badge badge-err">&#10007; ${dbMsg}</span>`;
+
+  const envBadge = isProd
+    ? `<span class="badge badge-ok">production</span>`
+    : isTesting
+      ? `<span class="badge badge-warn">testing</span>`
+      : `<span class="badge badge-warn">development</span>`;
+
+  const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
+  const html = pageShell(`${orgName} Events API — Status`, '#2563eb', `
+    <h1>${orgName} Events API</h1>
+    <p class="subtitle">v${API_VERSION} &mdash; ${now}</p>
+
+    <div class="stat-grid">
+      <div class="stat">
+        <div class="stat-label">Status</div>
+        <div class="stat-value"><span class="badge badge-ok">&#10003; Online</span></div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Environment</div>
+        <div class="stat-value">${envBadge}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Database</div>
+        <div class="stat-value">${dbBadge}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Uptime</div>
+        <div class="stat-value">${formatUptime(uptimeSec)}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Heap Used</div>
+        <div class="stat-value">${formatBytes(mem.heapUsed)}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Heap Total</div>
+        <div class="stat-value">${formatBytes(mem.heapTotal)}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">RSS</div>
+        <div class="stat-value">${formatBytes(mem.rss)}</div>
+      </div>
+      <div class="stat">
+        <div class="stat-label">Node</div>
+        <div class="stat-value">${process.version}</div>
+      </div>
+    </div>
+
+    <div class="note">
+      API documentation is available at <a href="/docs">/docs</a> (v1) and <a href="/docs/v2">/docs/v2</a> (v2, OpenAPI) — both need an admin account token.
+    </div>
+  `);
+
+  res.send(html);
+});
+
+// ── /docs route — interactive API reference, admin only ─────────────────────
+app.get('/docs', async (req, res) => {
+  const tokenFromQuery = req.query.token;
+  const tokenFromHeader = req.headers.authorization?.startsWith('Bearer ')
+    ? req.headers.authorization.split(' ')[1] : null;
+  const token = tokenFromQuery || tokenFromHeader;
+
+  if (!token) {
+    return res.status(401).send(pageShell('API Docs — Login Required', '#2563eb', `
+      <h1>API Documentation</h1>
+      <p class="subtitle">Admin access required</p>
+      <div class="card">
+        <p style="margin-bottom:12px;font-size:.9rem;">Pass your admin JWT to view the docs:</p>
+        <code style="display:block;padding:10px;background:#f3f4f6;border-radius:6px;font-size:.8rem;word-break:break-all;">/docs?token=&lt;your-admin-jwt&gt;</code>
+        <p style="margin-top:12px;font-size:.8rem;color:#6b7280;">Copy your token from the browser's localStorage key <code>token</code> after logging in as admin.</p>
+      </div>`));
+  }
+
+  let user;
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
+    user = await prisma.user.findUnique({
+      where: { id: decoded.id },
+      select: { id: true, name: true, email: true, role: true, isActive: true, tokenVersion: true },
+    });
+    if (!user || !user.isActive) throw new Error('User not found or inactive');
+    if ((decoded.tokenVersion ?? 0) !== user.tokenVersion) throw new Error('Token revoked');
+    if (user.role !== 'admin') throw new Error('Admin role required');
+  } catch (e) {
+    return res.status(403).send(pageShell('API Docs — Access Denied', '#dc2626', `
+      <h1>Access Denied</h1>
+      <p class="subtitle">Admin role required</p>
+      <div class="card">
+        <p style="font-size:.9rem;color:#dc2626;">${e.message}</p>
+        <p style="margin-top:10px;font-size:.82rem;color:#6b7280;">Make sure you are logged in as an admin and using a valid, non-expired token.</p>
+      </div>`));
+  }
+
+  // ── Endpoint data ────────────────────────────────────────────────────────
+  const GROUPS = [
+    { title: 'Users', base: '/api/users', endpoints: [
+      { method:'GET', path:'/api/users/activity', auth:'Bearer', desc:'Recent account activity (logins, password changes) for the current user' },
+      { method:'POST', path:'/api/users', auth:'public', desc:'Register a new account',
+        request:{ body:{ name:'Jane Doe', email:'jane@example.com', password:'secret123', phoneNumber:'+27821234567' }},
+        responses:[
+          { status:201, desc:'Created', body:{ id:'a1b2c3d4-0000-0000-0000-000000000001', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...' }},
+          { status:400, desc:'Validation error', body:{ message:'Email already in use' }},
+        ]},
+      { method:'POST', path:'/api/users/login', auth:'public', desc:'Login — returns a signed JWT',
+        notes:'Rate-limited to 15 requests/min per IP.',
+        request:{ body:{ email:'jane@example.com', password:'secret123' }},
+        responses:[
+          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...' }},
+          { status:200, desc:'Two-factor code sent (account has 2FA on) — no token yet', body:{ twoFactorRequired:true, challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
+          { status:200, desc:'Admin/supervisor without 2FA — code sent; verifying it turns 2FA on', body:{ twoFactorRequired:true, enrolling:true, challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
+          { status:401, desc:'Wrong credentials', body:{ message:'Invalid email or password' }},
+        ]},
+      { method:'POST', path:'/api/users/login/2fa', auth:'public', desc:'Second login step — exchange the emailed/WhatsApp code for a JWT',
+        notes:'Codes expire after 10 minutes and allow 5 attempts. With rememberDevice, the response includes a deviceToken; send it with later logins to skip the code for 30 days.',
+        request:{ body:{ challengeId:'c0ffee00-...', code:'123456', rememberDevice:true }},
+        responses:[
+          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...', deviceToken:'9f2c...' }},
+          { status:400, desc:'Wrong or expired code', body:{ message:'Incorrect code. 4 attempts left.' }},
+        ]},
+      { method:'POST', path:'/api/users/login/2fa/resend', auth:'public', desc:'Send a new code for a pending login challenge',
+        notes:'At most one send per 60 seconds.',
+        request:{ body:{ challengeId:'c0ffee00-...' }},
+        responses:[
+          { status:200, desc:'Sent', body:{ challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
+          { status:429, desc:'Too soon', body:{ message:'Please wait 42 seconds before requesting another code.' }},
+        ]},
+      { method:'POST', path:'/api/users/forgot', auth:'public', desc:'Request a password reset email',
+        request:{ body:{ email:'jane@example.com' }},
+        responses:[
+          { status:200, desc:'Always succeeds (no user enumeration)', body:{ message:'If that email exists, a reset link has been sent.' }},
+        ]},
+      { method:'POST', path:'/api/users/reset', auth:'public', desc:'Reset password using token from email',
+        request:{ body:{ token:'reset-token-from-email', password:'newPassword123' }},
+        responses:[
+          { status:200, desc:'Success', body:{ message:'Password reset successful.' }},
+          { status:400, desc:'Invalid or expired token', body:{ message:'Reset token is invalid or has expired.' }},
+        ]},
+      { method:'POST', path:'/api/users/activate', auth:'public', desc:'Activate a new account via email link',
+        request:{ body:{ token:'activation-token-from-email' }},
+        responses:[
+          { status:200, desc:'Success', body:{ message:'Account activated.' }},
+          { status:400, desc:'Invalid token', body:{ message:'Invalid or expired activation token.' }},
+        ]},
+      { method:'GET', path:'/api/users/profile', auth:'user+', desc:'Get own profile',
+        responses:[
+          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', phoneNumber:'+27821234567', notificationPreference:'email', createdAt:'2024-01-15T08:00:00.000Z' }},
+          { status:401, desc:'Unauthorized', body:{ message:'Not authorized, no token' }},
+        ]},
+      { method:'PUT', path:'/api/users/profile', auth:'user+', desc:'Update own profile',
+        request:{ body:{ name:'Jane Smith', phoneNumber:'+27821234567', notificationPreference:'both' }},
+        responses:[
+          { status:200, desc:'Updated', body:{ id:'a1b2c3d4-...', name:'Jane Smith', email:'jane@example.com', notificationPreference:'both' }},
+        ]},
+      { method:'POST', path:'/api/users/revoke-sessions', auth:'user+', desc:'Invalidate all own sessions by incrementing tokenVersion',
+        responses:[{ status:200, desc:'Success', body:{ message:'All sessions revoked.' }}]},
+      { method:'POST', path:'/api/users/close-account', auth:'user+', desc:'Deactivate own account',
+        responses:[{ status:200, desc:'Success', body:{ message:'Account deactivated.' }}]},
+      { method:'POST', path:'/api/users/2fa/enable', auth:'user+', desc:'Start turning on two-factor authentication — sends a code to the chosen channel',
+        notes:'WhatsApp needs a valid phone number on the account and a connected WhatsApp session.',
+        request:{ body:{ method:'email', password:'secret123' }},
+        responses:[
+          { status:200, desc:'Code sent', body:{ challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
+          { status:400, desc:'Wrong password or unavailable channel', body:{ message:'Incorrect password' }},
+        ]},
+      { method:'POST', path:'/api/users/2fa/confirm', auth:'user+', desc:'Finish turning on two-factor authentication with the code that was sent',
+        request:{ body:{ challengeId:'c0ffee00-...', code:'123456' }},
+        responses:[{ status:200, desc:'Enabled', body:{ twoFactorEnabled:true, twoFactorMethod:'email' }}]},
+      { method:'POST', path:'/api/users/2fa/disable', auth:'user+', desc:'Turn off two-factor authentication',
+        request:{ body:{ password:'secret123' }},
+        notes:'Admins and supervisors must keep two-factor on — 403 for them.',
+        responses:[
+          { status:200, desc:'Disabled', body:{ twoFactorEnabled:false, twoFactorMethod:null }},
+          { status:403, desc:'Required for this role', body:{ message:"Two-factor authentication is required for your role and can't be turned off." }},
+        ]},
+      { method:'POST', path:'/api/users/verify-password', auth:'user+', desc:'Re-confirm own password without starting a new session',
+        request:{ body:{ password:'secret123' }},
+        responses:[
+          { status:200, desc:'Correct', body:{ ok:true }},
+          { status:401, desc:'Wrong password', body:{ message:'Incorrect password' }},
+        ]},
+      { method:'GET', path:'/api/users', auth:'supervisor+', desc:'List all users (paginated). All filters are applied server-side.',
+        queryParams:{ page:'Page number (default 1)', limit:'Items per page (max 200, default 100)', search:'Search by name, email, or phone number (case-insensitive substring)', role:'Filter by role: admin|supervisor|staff|user', isActive:'Filter by active status: true|false (omit for both)' },
+        responses:[
+          { status:200, desc:'Success', body:{ data:[{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, createdAt:'2024-01-15T08:00:00.000Z' }], total:1, page:1, limit:20 }},
+        ]},
+      { method:'GET', path:'/api/users/check-exists', auth:'supervisor+', desc:'Check whether an account already exists for a given email and/or phone number (used by the self-service kiosk and manual registration screens to avoid duplicate accounts)',
+        queryParams:{ email:'Email to look up (optional)', phone:'Phone number to look up (optional; SA formats normalized)' },
+        responses:[
+          { status:200, desc:'Success', body:{ exists:true, hasEmail:true, hasPhone:false }},
+        ]},
+      { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID (with scopedCampuses)',
+        pathParams:{ ':id':'User UUID' },
+        responses:[
+          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, phoneNumber:'+27821234567', notificationPreference:'email' }},
+          { status:404, desc:'Not found', body:{ message:'User not found' }},
+        ]},
+      { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role). scopedCampusIds limits a supervisor/staff member to those campuses (empty = every campus; audited)',
+        pathParams:{ ':id':'User UUID' },
+        request:{ body:{ role:'supervisor', isActive:true, name:'Jane Doe' }},
+        responses:[
+          { status:200, desc:'Updated', body:{ id:'a1b2c3d4-...', name:'Jane Doe', role:'supervisor' }},
+        ]},
+      { method:'DELETE', path:'/api/users/:id', auth:'admin', desc:'Deactivate a user account (sets isActive: false; does not erase data)',
+        pathParams:{ ':id':'User UUID' },
+        responses:[
+          { status:200, desc:'Deactivated', body:{ message:'User deactivated' }},
+          { status:404, desc:'Not found', body:{ message:'User not found' }},
+        ]},
+      { method:'POST', path:'/api/users/:id/revoke-sessions', auth:'admin', desc:'Revoke all sessions for another user',
+        pathParams:{ ':id':'User UUID' },
+        responses:[{ status:200, desc:'Success', body:{ message:'Sessions revoked for user.' }}]},
+      { method:'POST', path:'/api/users/:id/anonymize', auth:'admin', desc:'Erase personal data for a user (POPIA) — the account, the people they registered, form answers, consent details, sponsor names, login history and payer details in provider payloads; payments, registrations and tickets stay as "Deleted User". Refused (409) while they have a registration for an upcoming event. Completes an open deletion request. Irreversible; audited as user_anonymised.',
+        pathParams:{ ':id':'User UUID' },
+        responses:[
+          { status:200, desc:'Anonymised', body:{ message:'User data deleted' }},
+          { status:404, desc:'Not found', body:{ message:'User not found' }},
+        ]},
+    ]},
+
+    { title: 'Events', base: '/api/events', endpoints: [
+      { method:'GET', path:'/api/events/admin/all', auth:'admin', desc:'All events, including inactive ones' },
+      { method:'GET', path:'/api/events/:id/ics', auth:'Public (optional login)', desc:'Download an .ics calendar file for an event' },
+      { method:'GET', path:'/api/events/:id/attachments', auth:'Public', desc:'List the downloadable attachments of an event' },
+      { method:'POST', path:'/api/events/:id/attachments', auth:'supervisor+', desc:'Upload an attachment (multipart, field "file")' },
+      { method:'DELETE', path:'/api/events/:eventId/attachments/:attachmentId', auth:'supervisor+', desc:'Delete an attachment' },
+      { method:'GET', path:'/api/events/attachments/status', auth:'admin', desc:'Diagnostics for the attachments pipeline' },
+      { method:'POST', path:'/api/events/attachments/sync', auth:'admin', desc:'Re-sync attachment records with the files on disk' },
+      { method:'POST', path:'/api/events/options/:id/variants', auth:'supervisor+', desc:'Add a variant (e.g. a size) to an event option' },
+      { method:'GET', path:'/api/events', auth:'public', desc:'List active, public, upcoming events. Each event includes isSoldOut:boolean — true when every option with a stockLimit > 0 is fully booked.',
+        queryParams:{ limit:'Max results (default 20)' },
+        responses:[
+          { status:200, desc:'Success', body:[{ id:'ev-uuid-...', title:'Camp 2025', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', price:450, picture:'/uploads/camp.jpg', isActive:true, isSoldOut:false }]},
+        ]},
+      { method:'GET', path:'/api/events/all', auth:'staff+', desc:'All events including hidden and past',
+        queryParams:{ includePast:'Include past events (true|false, default false)' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'ev-uuid-...', title:'Camp 2025', isHidden:false, isActive:true }]}]},
+      { method:'GET', path:'/api/events/:id', auth:'public', desc:'Get full event detail by ID. When called by staff/supervisor/admin, the response also includes createdBy and notifyRecipients (who the event\'s notifications go to).',
+        pathParams:{ ':id':'Event UUID' },
+        responses:[
+          { status:200, desc:'Success', body:{ id:'ev-uuid-...', title:'Camp 2025', description:'Annual family camp.', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', price:450, requiresAuth:true, eventOptions:[{ id:'opt-uuid-...', name:'Adult', price:450, isMainTicket:true }], createdBy:{ id:'user-uuid-...', name:'Jane Supervisor', email:'jane@example.com' }, notifyRecipients:[]}},
+          { status:404, desc:'Not found', body:{ message:'Event not found' }},
+        ]},
+      { method:'GET', path:'/api/events/by-alias/:redirectUrl', auth:'public', desc:'Get event by its URL alias',
+        pathParams:{ ':redirectUrl':'URL alias string (e.g. camp-2025)' },
+        responses:[{ status:200, desc:'Success', body:{ id:'ev-uuid-...', title:'Camp 2025', redirectUrl:'camp-2025' }}]},
+      { method:'POST', path:'/api/events', auth:'supervisor+', desc:'Create a new event',
+        request:{ body:{ title:'Camp 2025', description:'Annual family camp', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', registrationDeadline:'2025-07-01T00:00:00.000Z', price:450, isActive:true, isHidden:false, requiresAuth:true }},
+        responses:[
+          { status:201, desc:'Created', body:{ id:'ev-uuid-new', title:'Camp 2025', createdAt:'2024-11-01T09:00:00.000Z' }},
+        ]},
+      { method:'PUT', path:'/api/events/:id', auth:'supervisor+', desc:'Update an event. Multi-day events send scheduleType:"sessions" with the full sessions list (rows left out are deleted; ones with check-ins must be cancelled instead), plus lateJoinEnabled, lateJoinUntilSessionIndex, latePricing, lateFixedPrice, checkInWindow, sessionReminders, certificatesEnabled and certificateConfig. The response includes sessionChanges.',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ title:'Camp 2025 Updated', price:500 }},
+        responses:[{ status:200, desc:'Updated', body:{ id:'ev-uuid-...', title:'Camp 2025 Updated', price:500 }}]},
+      { method:'POST', path:'/api/events/:id/copy-from', auth:'supervisor+', desc:'Copying an event (1.47.0): after the copy is created from the event form, copy the source event\'s allocation sets and groups (not the kids rooms) and, for admins, its planned costs (matched to options by name). Only into an event with no registrations or allocation sets yet. POST /api/events takes clonedFromId to note the source in the audit log.',
+        pathParams:{ ':id':'The new event' },
+        request:{ body:{ fromEventId:'ev-uuid-source' }},
+        responses:[{ status:200, desc:'Copied', body:{ sets:2, groups:9, costs:3 }}, { status:409, desc:'The event already has registrations or groups' }]},
+      { method:'GET', path:'/api/events/:id/notify-recipients', auth:'supervisor+', desc:'Get which users receive registration/payment/daily-summary notifications for this event. Lightweight — skips the option/stock computation that GET /api/events/:id does.',
+        pathParams:{ ':id':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'user-uuid-1', name:'Jane Supervisor', email:'jane@example.com', role:'supervisor' }]}]},
+      { method:'PUT', path:'/api/events/:id/notify-recipients', auth:'supervisor+', desc:'Set which users receive registration/payment/daily-summary notifications for this event. Pass an empty array to fall back to the event creator.',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ userIds:['user-uuid-1','user-uuid-2'] }},
+        responses:[
+          { status:200, desc:'Saved', body:[{ id:'user-uuid-1', name:'Jane Supervisor', email:'jane@example.com', role:'supervisor' },{ id:'user-uuid-2', name:'John Admin', email:'john@example.com', role:'admin' }]},
+          { status:400, desc:'Bad input', body:{ message:'userIds must be an array' }},
+        ]},
+      { method:'DELETE', path:'/api/events/:id', auth:'admin', desc:'Permanently delete an event',
+        pathParams:{ ':id':'Event UUID' },
+        responses:[{ status:200, desc:'Deleted', body:{ message:'Event deleted.' }}]},
+      { method:'POST', path:'/api/events/:id/email-attendees', auth:'supervisor+', desc:'Send a bulk email to event attendees. Use dryRun:true to preview recipients without sending.',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ subject:'Payment reminder: Camp 2025', text:'Hi {{name}}, you have an outstanding balance of {{balance}}.', filter:{ status:'unpaid', attendeeIds:['user-uuid-1','user-uuid-2'] }, dryRun:false, template:'custom' }},
+        responses:[
+          { status:200, desc:'Sent', body:{ matched:15, sent:14, failed:1 }},
+          { status:200, desc:'Dry run', body:{ matched:15, dryRun:true, recipients:[{ email:'jane@example.com', name:'Jane Doe' }]}},
+        ]},
+      { method:'POST', path:'/api/events/:id/email-attendees/schedule', auth:'supervisor+', desc:'Schedule a bulk email to run at a future time',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ subject:'Reminder: Camp 2025', text:'Hi {{name}}, see you soon!', scheduledAt:'2025-07-03T09:00:00.000Z', filter:{ status:'paid' }}},
+        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', scheduledAt:'2025-07-03T09:00:00.000Z', status:'queued' }}}]},
+      { method:'POST', path:'/api/events/:id/whatsapp-attendees', auth:'supervisor+', desc:'Send a bulk WhatsApp message to attendees with a phone number. Supports dryRun.',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ message:'Hi {{name}}, camp starts in 3 days! 🏕️', filter:{ status:'paid' }, dryRun:false }},
+        responses:[
+          { status:200, desc:'Sent', body:{ matched:12, sent:11 }},
+        ]},
+      { method:'POST', path:'/api/events/:id/whatsapp-attendees/schedule', auth:'supervisor+', desc:'Schedule a bulk WhatsApp message',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ message:'Hi {{name}}, final reminder for camp tomorrow! 🎉', scheduledAt:'2025-07-09T08:00:00.000Z', filter:{ status:'paid' }}},
+        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued' }}}]},
+      { method:'POST', path:'/api/events/:id/options', auth:'supervisor+', desc:'Add a ticket option to an event',
+        pathParams:{ ':id':'Event UUID' },
+        request:{ body:{ name:'Child (under 12)', price:250, isMainTicket:false }},
+        responses:[{ status:201, desc:'Created', body:{ id:'opt-uuid-new', name:'Child (under 12)', price:250, isMainTicket:false }}]},
+      { method:'PUT', path:'/api/events/options/:id', auth:'supervisor+', desc:'Update a ticket option',
+        pathParams:{ ':id':'EventOption UUID' },
+        request:{ body:{ price:300 }},
+        responses:[{ status:200, desc:'Updated', body:{ id:'opt-uuid-...', price:300 }}]},
+      { method:'DELETE', path:'/api/events/options/:id', auth:'admin', desc:'Delete a ticket option (fails if registrations exist)',
+        pathParams:{ ':id':'EventOption UUID' },
+        responses:[
+          { status:200, desc:'Deleted', body:{ message:'Option deleted.' }},
+          { status:400, desc:'In use', body:{ message:'Cannot delete option with existing registrations.' }},
+        ]},
+    ]},
+
+    { title: 'Registrations', base: '/api/registrations', endpoints: [
+      { method:'PUT', path:'/api/registrations/:id/options', auth:'Bearer (owner or staff)', desc:'Change the items on a registration (add/remove), within stock and paid-ticket limits' },
+      { method:'POST', path:'/api/registrations/:id/coupon', auth:'Bearer (owner or staff)', desc:'Apply a coupon code to an existing registration', request:{ body:{ code:'STAFF50' }}},
+      { method:'DELETE', path:'/api/registrations/:id/coupon', auth:'staff+', desc:'Remove the coupon from a registration (frees the use)' },
+      { method:'GET', path:'/api/registrations/:id/forms/draft', auth:'Owner or staff', desc:'Saved draft of the attendee forms' },
+      { method:'PUT', path:'/api/registrations/:id/forms/draft', auth:'Owner or staff', desc:'Save a draft of the attendee forms (not submitted)' },
+      { method:'PUT', path:'/api/registrations/:id/forms/responses', auth:'supervisor+', desc:'Replace (edit) the submitted form responses of a registration' },
+      { method:'POST', path:'/api/registrations', auth:'optional', desc:'Create a registration. Auth optional — guests are allowed when event does not require auth.',
+        request:{ body:{ eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-uuid-...', quantity:2 }] }},
+        responses:[
+          { status:201, desc:'Created', body:{ id:'reg-uuid-...', eventId:'ev-uuid-...', status:'pending', checkoutId:null, createdAt:'2025-06-01T10:00:00.000Z' }},
+          { status:400, desc:'Deadline passed', body:{ message:'Registration deadline has passed.' }},
+        ]},
+      { method:'GET', path:'/api/registrations/myregistrations', auth:'user+', desc:'Get all registrations for the authenticated user',
+        responses:[{ status:200, desc:'Success', body:[{ id:'reg-uuid-...', event:{ id:'ev-uuid-...', title:'Camp 2025' }, status:'paid', createdAt:'2025-06-01T10:00:00.000Z' }]}]},
+      { method:'GET', path:'/api/registrations/:id', auth:'optional', desc:'Get registration detail by ID',
+        pathParams:{ ':id':'Registration UUID' },
+        responses:[{ status:200, desc:'Success', body:{ id:'reg-uuid-...', status:'paid', event:{ title:'Camp 2025' }, registrationOptions:[{ eventOption:{ name:'Adult' }, quantity:1 }], payments:[{ amount:450, method:'card', status:'succeeded' }] }}]},
+      { method:'PUT', path:'/api/registrations/:id', auth:'staff+', desc:'Update registration status. If set to "paid", generates tickets and emails them fire-and-forget. If downgraded from "paid", deletes unused tickets (blocks if any ticket has been scanned).',
+        pathParams:{ ':id':'Registration UUID' },
+        request:{ body:{ status:'paid' }},
+        responses:[{ status:200, desc:'Updated', body:{ id:'reg-uuid-...', status:'paid' }}]},
+      { method:'DELETE', path:'/api/registrations/:id', auth:'user+', desc:'Cancel registration. Users: only allowed when no positive payments exist (returns 403 otherwise). Admins: always allowed.',
+        pathParams:{ ':id':'Registration UUID' },
+        responses:[
+          { status:200, desc:'Cancelled', body:{ message:'Registration cancelled', registration:{ id:'reg-uuid-...', status:'cancelled' }}},
+          { status:400, desc:'Already cancelled', body:{ message:'Registration is already cancelled' }},
+          { status:403, desc:'Payments exist — non-admin cannot cancel', body:{ message:'This registration has payments recorded against it and cannot be self-cancelled. Please contact the organisation for assistance.' }},
+          { status:403, desc:'Not the owner (and not admin)', body:{ message:'Not authorized to cancel this registration' }},
+        ]},
+      { method:'GET', path:'/api/registrations', auth:'staff+', desc:'List all registrations across all events',
+        queryParams:{ page:'Page (default 1)', limit:'Per page (default 20)', eventId:'Filter by event', status:'Filter by status', search:'Search by name/email' },
+        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'reg-uuid-...', user:{ name:'Jane Doe' }, event:{ title:'Camp 2025' }, status:'paid' }], total:1, page:1 }}]},
+      { method:'GET', path:'/api/registrations/event/:eventId', auth:'staff+', desc:'Get all registrations for a specific event',
+        pathParams:{ ':eventId':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'reg-uuid-...', user:{ id:'user-uuid-...', name:'Jane Doe', email:'jane@example.com', phoneNumber:'+27821234567' }, status:'paid' }]}]},
+      { method:'PUT', path:'/api/registrations/:id/attendees', auth:'user+', desc:'Replace the named attendees on a registration (group tickets) and choose ticket delivery (payer | each). Owner or staff. Removing an attendee whose ticket was scanned is refused.',
+        request:{ body:{ attendees:[{ id:'att-uuid-...', eventOptionId:'opt-uuid-...', name:'Sam Smith', email:'sam@example.com' },{ eventOptionId:'opt-uuid-...', name:'Alex Smith' }], ticketDelivery:'each' }},
+        responses:[{ status:200, desc:'Saved', body:{ id:'reg-uuid-...', ticketDelivery:'each', attendees:[{ id:'att-uuid-...', name:'Sam Smith', ticket:{ id:'tkt-uuid-...', isUsed:false }}] }}]},
+      { method:'POST', path:'/api/registrations/:id/attendees/:attendeeId/send-form-link', auth:'user+', desc:'Email/WhatsApp a named attendee the link to fill in their own attendee form' },
+      { method:'POST', path:'/api/registrations/bulk', auth:'supervisor+', desc:'Bulk actions on ticked registrations (up to 500), each run through the same code as doing it one at a time: action "markPaid" { method: cash|eft|card|other, paidAt? } records the balance; "cancel"; "moveOption" { fromOptionId, toOptionId } (same event); "allocate" { setId, groupId } places their named people; "message" { channel: email|whatsapp, subject?, text } sends an event update. Answers { action, done, skipped, failed, results: [{ id, ok, skipped?, message }] }. Campus-checked for every id; payments and ticket changes refused in licence read-only mode. Audited as registrations_bulk',
+        request:{ body:{ action:'markPaid', registrationIds:['reg-uuid-1','reg-uuid-2'], method:'cash' } } },
+      { method:'POST', path:'/api/registrations/manual', auth:'supervisor+', desc:'Manually create a registration (at-the-door / walk-in). Resolves early-bird tier pricing (including per-variant tiers) and stores priceSnapshot + appliedTierId on each option. Creates or finds a matching user by email/phone. If a matching user is found, updates their notificationPreference and backfills a missing phone number or guest placeholder email with the newly supplied value (without overwriting existing contact info). Generates a Yoco checkout link for unpaid registrations to include in the self-service notification email.',
+        request:{ body:{ eventId:'ev-uuid-...', user:{ name:'Jane Doe', email:'jane@example.com', phoneNumber:'0821234567' }, options:[{ eventOptionId:'opt-uuid-...', quantity:1, variantId:'var-uuid-...' }], notificationPreference:'email' }},
+        responses:[{ status:201, desc:'Created', body:{ id:'reg-uuid-new', status:'pending' }}]},
+      { method:'POST', path:'/api/registrations/:id/forms/responses', auth:'optional', desc:'Submit form responses for a registration',
+        pathParams:{ ':id':'Registration UUID' },
+        request:{ body:{ answers:[{ fieldId:'field-uuid-...', value:'Yes' }, { fieldId:'field-uuid-2', value:'Vegetarian' }] }},
+        responses:[{ status:201, desc:'Submitted', body:{ id:'response-uuid-...', createdAt:'2025-06-01T10:05:00.000Z' }}]},
+      { method:'POST', path:'/api/registrations/:id/send-invoice', auth:'user+', desc:'(Re)generate the invoice PDF for one of the caller\'s own registrations and send it on the requested channel — email or WhatsApp. Works regardless of balance (shows "Paid in full" when nothing is owed); fails only if there is no valid email/phone on file for the chosen channel.',
+        notes:'The PDF\'s invoiceNo is derived, not sequential: INV-<year of registration.createdAt>-<last 6 hex chars of the registration id, uppercased>. When there is an outstanding balance, generates a fresh Yoco checkout link for the invoice\'s QR code/pay-now link on each call.',
+        pathParams:{ ':id':'Registration UUID' },
+        request:{ body:{ channel:'email' }},
+        responses:[
+          { status:200, desc:'Sent', body:{ message:'Invoice emailed.' }},
+          { status:400, desc:'No valid contact for channel', body:{ message:'No valid email address on file. Add one in your profile.' }},
+          { status:403, desc:'Not the owner', body:{ message:'Not authorized to access this registration' }},
+        ]},
+    ]},
+
+    { title: 'Impersonation', base: '/api/admin', endpoints: [
+      { method:'GET', path:'/api/admin/audit-log', auth:'admin', desc:'Paginated admin/supervisor audit trail (?page, limit, actorId, action, role, from, to, search)' },
+      { method:'GET', path:'/api/admin/jobs', auth:'admin', desc:'Background jobs: queue mode, timezone, and each job schedule, next run and last 10 runs' },
+      { method:'POST', path:'/api/admin/jobs/:name/run', auth:'admin', desc:'Run a background job now (queued for a worker); audit-logged' },
+      { method:'POST', path:'/api/admin/impersonate/:userId', auth:'admin (2FA)', desc:'View the site as a user — read-only token, 30 minutes, audited', request:{ body:{ reason:'Ticket not showing in My Events' }}, responses:[{ status:201, desc:'Started', body:{ token:'jwt…', session:{ id:'sess-uuid', expiresAt:'2025-07-10T08:45:00.000Z' }}}, { status:403, desc:'Not allowed', body:{ message:"Admins can't be impersonated." }}]},
+      { method:'POST', path:'/api/admin/impersonate/end', auth:'impersonation token', desc:'End the impersonation session' },
+      { method:'POST', path:'/api/admin/impersonate/log', auth:'impersonation token', desc:'Record a page viewed during the session' },
+      { method:'GET', path:'/api/admin/impersonate/current', auth:'impersonation token', desc:'The live impersonation session' },
+      { method:'GET', path:'/api/admin/impersonation-sessions', auth:'admin', desc:'Impersonation sessions with their request trail' },
+    ]},
+    { title: 'Registration funnel', base: '/api/analytics', endpoints: [
+      { method:'POST', path:'/api/analytics/track', auth:'Public (rate-limited)', desc:'Record a funnel step from a cookie-consented browser (always 204)',
+        request:{ body:{ sessionId:'random-uuid', eventId:'ev-uuid-...', stage:'view', source:'camp-2025' }}},
+      { method:'GET', path:'/api/analytics/funnel', auth:'supervisor+', desc:'Funnel for ?eventIds=a,b&from=&to= — totals, conversion, daily trend, by source/device/option' },
+    ]},
+    { title: 'Post-event feedback', base: '/api/feedback', endpoints: [
+      { method:'GET', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'An event\'s feedback form, with invite and response counts' },
+      { method:'PUT', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'Create/update the feedback form (questions lock once answered)',
+        request:{ body:{ sendAt:'2025-07-13T09:00:00.000Z', audience:'checked_in', anonymous:false, intro:'Thanks for coming!', fields:[{ type:'rating', label:'Overall?', isRequired:true }, { type:'multiple_choice', label:'Best part', options:['Worship','Talks'] }] }}},
+      { method:'DELETE', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'Remove the feedback form' },
+      { method:'POST', path:'/api/feedback/event/:eventId/send-now', auth:'supervisor+', desc:'Send the feedback form now' },
+      { method:'GET', path:'/api/feedback/public/:token', auth:'Link holder', desc:'The form behind a personal feedback link' },
+      { method:'POST', path:'/api/feedback/public/:token', auth:'Link holder', desc:'Submit feedback once', request:{ body:{ answers:{ 'field-uuid':'5' } }}},
+      { method:'GET', path:'/api/feedback/summary', auth:'supervisor+', desc:'Feedback summary for ?eventIds=a,b (response rate, averages, breakdowns, comments)' },
+    ]},
+    { title: 'Sponsor a spot', base: '/api/sponsorships', endpoints: [
+      { method:'GET', path:'/api/sponsorships/event/:eventId', auth:'Public', desc:'Sponsorship progress for an event (spots funded, goal) — never who was helped',
+        responses:[{ status:200, desc:'Progress', body:{ enabled:true, open:true, spotPrice:450, showProgress:true, goalSpots:20, spotsFunded:12, sponsors:9 }}]},
+      { method:'POST', path:'/api/sponsorships/checkout', auth:'Public (optional login)', desc:'Start a Yoco checkout to sponsor spots or a custom amount; the money lands in the event sponsorship pool',
+        request:{ body:{ eventId:'ev-uuid-...', spots:2, anonymous:false, sponsorName:'The Smith family', message:'Have a great camp!', name:'Sam Smith', email:'sam@example.com' }},
+        responses:[{ status:200, desc:'Checkout created', body:{ redirectUrl:'https://pay.yoco.com/...', amount:900 }}]},
+      { method:'GET', path:'/api/sponsorships/event/:eventId/pool', auth:'supervisor+', desc:'Sponsorship pool totals: received, assigned, remaining' },
+    ]},
+    { title: 'Rooms & groups', base: '/api/allocations', endpoints: [
+      { method:'GET', path:'/api/allocations/event/:eventId', auth:'supervisor+', desc:'Allocation board: sets with groups and assignments, named attendees, possible leaders' },
+      { method:'POST', path:'/api/allocations/sets', auth:'supervisor+', desc:'Create an allocation set', request:{ body:{ eventId:'ev-uuid-...', name:'Rooms', showOnTicket:true }}},
+      { method:'PUT', path:'/api/allocations/sets/:id', auth:'supervisor+', desc:'Rename a set or show it on tickets' },
+      { method:'DELETE', path:'/api/allocations/sets/:id', auth:'supervisor+', desc:'Delete a set and its groups' },
+      { method:'POST', path:'/api/allocations/sets/:id/groups', auth:'supervisor+', desc:'Add a group', request:{ body:{ name:'Cabin 1', capacity:8, gender:'female', leaderUserId:'user-uuid-...' }}},
+      { method:'PUT', path:'/api/allocations/groups/:id', auth:'supervisor+', desc:'Edit a group' },
+      { method:'DELETE', path:'/api/allocations/groups/:id', auth:'supervisor+', desc:'Delete a group (its people become unassigned)' },
+      { method:'PUT', path:'/api/allocations/sets/:id/assignments', auth:'supervisor+', desc:'Place (or with groupId null, unplace) an attendee; enforces capacity and gender', request:{ body:{ attendeeId:'att-uuid-...', groupId:'grp-uuid-...' }}},
+      { method:'DELETE', path:'/api/allocations/sets/:id/assignments', auth:'supervisor+', desc:'Clear every assignment in a set' },
+      { method:'POST', path:'/api/allocations/sets/:id/auto', auth:'supervisor+', desc:'Auto-allocate everyone not yet placed', request:{ body:{ mode:'together' }}, responses:[{ status:200, desc:'Done', body:{ placed:12, unplaced:1 }}]},
+      { method:'GET', path:'/api/allocations/sets/:id/lists', auth:'supervisor+', desc:'Per-group lists for printing (?medical=true adds medical details; audited)' },
+      { method:'GET', path:'/api/allocations/my-groups', auth:'staff+', desc:'Groups the signed-in leader leads, with their people' },
+    ]},
+    { title: 'Ticket transfer', base: '/api/tickets', endpoints: [
+      { method:'DELETE', path:'/api/tickets/:id/transfer', auth:'payer, holder or supervisor+', desc:'Withdraw a transfer offer that has not been accepted yet' },
+      { method:'GET', path:'/api/tickets/transfer-offer/:token', auth:'Link holder', desc:'The ticket offered behind a transfer link (status, event, ticket type, sender first name)' },
+      { method:'POST', path:'/api/tickets/transfer-offer/:token/accept', auth:'Link holder', desc:'Accept the ticket — the transfer happens now (new QR code, ticket sent to the new holder)' },
+      { method:'POST', path:'/api/tickets/transfer-offer/:token/decline', auth:'Link holder', desc:'Decline the ticket offer' },
+      { method:'POST', path:'/api/tickets/:id/transfer', auth:'payer, holder or supervisor+', desc:'Give a ticket to someone else before the event (new QR code; the old one stops working; billing stays with the payer)',
+        request:{ body:{ name:'Nia New', email:'nia@example.com', phone:'0821234567' }},
+        responses:[{ status:200, desc:'Transferred', body:{ message:'Ticket transferred to Nia New…', ticketId:'ticket-uuid-...' }}, { status:400, desc:'Not allowed', body:{ message:'This ticket has already been used (or partly used), so it can’t be transferred.' }}]},
+      { method:'GET', path:'/api/tickets/:id/transfers', auth:'payer, holder or staff+', desc:'Transfer history of a ticket' },
+    ]},
+    { title: 'Offline scanning', base: '/api/scan-locks', endpoints: [
+      { method:'GET', path:'/api/scan-locks', auth:'staff+', desc:'Active offline locks for an event (?eventId=)' },
+      { method:'POST', path:'/api/scan-locks', auth:'staff+', desc:'Lock a section (or the whole event) to this device for offline scanning',
+        request:{ body:{ eventId:'ev-uuid-...', sectionId:'sec-uuid-...', deviceId:'device-uuid', deviceName:'Chrome on Android' }},
+        responses:[{ status:201, desc:'Locked', body:{ id:'lock-uuid-...', sectionName:'Main hall' }}, { status:409, desc:'Held elsewhere', body:{ message:'"Main hall" is offline-locked by Ann on Chrome on Android.' }}]},
+      { method:'GET', path:'/api/scan-locks/:id/snapshot', auth:'staff+', desc:'Tickets valid in the lock scope, for the device to keep offline (lock holder, ?deviceId=)' },
+      { method:'POST', path:'/api/scan-locks/:id/sync', auth:'staff+', desc:'Upload offline scans (idempotent by clientScanId; capped at what is left on each ticket)',
+        request:{ body:{ deviceId:'device-uuid', scans:[{ clientScanId:'scan-uuid', qrCode:'qr-uuid', qty:1, scannedAt:'2025-07-10T08:15:00.000Z' }] }},
+        responses:[{ status:200, desc:'Synced', body:{ accepted:1, duplicates:0, conflicts:[] }}]},
+      { method:'DELETE', path:'/api/scan-locks/:id', auth:'staff+', desc:'End offline mode (lock holder)' },
+      { method:'POST', path:'/api/scan-locks/:id/force-release', auth:'supervisor+', desc:'Release a lost device\'s lock' },
+      { method:'GET', path:'/api/scan-locks/reports', auth:'supervisor+', desc:'Offline sync reports for an event' },
+      { method:'POST', path:'/api/scan-locks/reports/:id/review', auth:'supervisor+', desc:'Mark a sync report reviewed' },
+    ]},
+    { title: 'Waitlist', base: '/api/waitlist', endpoints: [
+      { method:'POST', path:'/api/waitlist', auth:'public', desc:'Join the waitlist for a sold-out line (login needed when the event requires it)',
+        request:{ body:{ eventId:'ev-uuid-...', eventOptionId:'opt-uuid-...', quantity:2 }},
+        responses:[{ status:201, desc:'Joined', body:{ id:'wl-uuid-...', status:'waiting', ahead:3 }}, { status:400, desc:'Places available', body:{ message:'There are places available — you can register now.' }}]},
+      { method:'GET', path:'/api/waitlist/mine', auth:'user+', desc:'My active waitlist entries' },
+      { method:'DELETE', path:'/api/waitlist/:id', auth:'user+', desc:'Leave the waitlist' },
+      { method:'GET', path:'/api/waitlist/claim/:token', auth:'public', desc:'What a claim link offers (rate-limited)' },
+      { method:'GET', path:'/api/waitlist/events/:eventId', auth:'staff+', desc:'The queue for an event' },
+      { method:'POST', path:'/api/waitlist/:id/offer', auth:'supervisor+', desc:'Offer places now, even over the stock limit' },
+      { method:'POST', path:'/api/waitlist/:id/move', auth:'supervisor+', desc:'Move up or down the queue', request:{ body:{ direction:'up' }} },
+      { method:'POST', path:'/api/waitlist/:id/remove', auth:'supervisor+', desc:'Take someone off the waitlist' },
+    ]},
+    { title: 'Attendance & certificates', base: '/api/attendance', endpoints: [
+      { method:'GET', path:'/api/attendance/:eventId', auth:'staff+', desc:'Attendance register: sessions (columns), one row per main ticket with check-ins per session, completion and certificate',
+        responses:[{ status:200, desc:'Register', body:{ event:{ id:'ev-uuid-...', scheduleType:'sessions' }, columns:[{ id:'ses-uuid-...', label:'Week 1', startsAt:'2026-11-04T16:30:00.000Z', cancelled:false }], rows:[{ ticketId:'t-uuid-...', name:'Thandi', checkIns:{ 'ses-uuid-...':1 }, attended:1, total:5, completed:false, certificate:null }], totals:{ 'ses-uuid-...':12 } }}]},
+      { method:'GET', path:'/api/attendance/:eventId/export?format=xlsx|pdf', auth:'staff+', desc:'Download the register as Excel or PDF' },
+      { method:'POST', path:'/api/attendance/:eventId/mark', auth:'supervisor+', desc:'Mark a ticket present/absent for a session (single-date events use sessionId "event")', request:{ body:{ ticketId:'t-uuid-...', sessionId:'ses-uuid-...', present:true }} },
+      { method:'POST', path:'/api/attendance/:eventId/certificates', auth:'supervisor+', desc:'Issue certificates now to everyone eligible, or to one ticket (even if not eligible)', request:{ body:{ ticketId:'t-uuid-... (optional)' }} },
+      { method:'POST', path:'/api/attendance/:eventId/certificates/send', auth:'supervisor+', desc:'Email/WhatsApp unsent certificates, or one again', request:{ body:{ certificateId:'(optional)' }} },
+      { method:'GET', path:'/api/attendance/:eventId/certificates.pdf', auth:'supervisor+', desc:'All of an event\'s certificates in one PDF' },
+      { method:'POST', path:'/api/attendance/certificates/preview', auth:'supervisor+', desc:'Sample certificate PDF with unsaved settings', request:{ body:{ title:'Alpha Course', config:{ template:'classic' } }} },
+      { method:'POST', path:'/api/attendance/certificates/:id/revoke', auth:'supervisor+', desc:'Revoke a certificate (never re-issued automatically)' },
+      { method:'GET', path:'/api/attendance/certificates/mine', auth:'user+', desc:'My certificates' },
+      { method:'GET', path:'/api/attendance/certificates/:id/pdf', auth:'user+', desc:'Download a certificate (its person, the booker, or a supervisor)' },
+      { method:'GET', path:'/api/attendance/certificates/verify/:code', auth:'public', desc:'Check a certificate code — name, event and dates only', responses:[{ status:200, desc:'Result', body:{ valid:true, name:'Thandi Mokoena', event:'Alpha Course', completedOn:'2026-12-02T18:30:00.000Z' }}] },
+    ]},
+    { title: 'Parental consent', base: '/api/consent', endpoints: [
+      { method:'GET', path:'/api/consent/:token', auth:'public', desc:'Consent page data for a parent/guardian (the link token is the credential; rate-limited)',
+        responses:[{ status:200, desc:'Success', body:{ status:'pending', attendeeName:'Sam Smith', consentText:'I give permission…', event:{ title:'Youth Camp' }, collect:{ medical:true, emergency:true, photo:true } }}, { status:404, desc:'Unknown or replaced link', body:{ message:'This consent link is not valid.' }}]},
+      { method:'POST', path:'/api/consent/:token', auth:'public', desc:'Give or decline consent. Records name, time, IP, device and the consent text version; medical/emergency details are stored encrypted.',
+        request:{ body:{ decision:'give', signedName:'Pat Smith', isGuardian:true, medical:{ allergies:'Peanuts' }, emergency:{ name:'Gran', phone:'0821234567' }, photoConsent:true }},
+        responses:[{ status:200, desc:'Answered', body:{ status:'given' }}, { status:409, desc:'Already answered', body:{ message:'Consent has already been given.' }}]},
+      { method:'GET', path:'/api/consent/events/:eventId', auth:'staff+', desc:'Consent status for every attendee on an event' },
+      { method:'POST', path:'/api/consent/requests/:id/resend', auth:'user+', desc:'Re-send a pending request with a fresh link (registrant or staff)' },
+      { method:'POST', path:'/api/consent/events/:eventId/resend-pending', auth:'supervisor+', desc:'Re-send every pending request on an event' },
+      { method:'POST', path:'/api/consent/events/:eventId/rerequest', auth:'supervisor+', desc:'Ask again where consent was given on an older version of the text, or never requested' },
+      { method:'GET', path:'/api/consent/events/:eventId/medical', auth:'supervisor+', desc:'Decrypted medical & emergency list; every view is written to the admin audit log' },
+    ]},
+    { title: 'Coupons', base: '/api/coupons', endpoints: [
+      { method:'POST', path:'/api/coupons/validate', auth:'public', desc:'Check a code against a basket before registering; returns the discount. Login needed for restricted codes; staff can pass forUserId (or null for a walk-in).',
+        request:{ body:{ code:'STAFF50', eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-uuid-...', quantity:2 }] }},
+        responses:[
+          { status:200, desc:'Valid (bundle deals come off first, then the code)', body:{ valid:true, code:'STAFF50', type:'percent', value:50, summary:'50% off', discount:450, bundleDiscount:0, bundles:[], subtotal:900, total:450 }},
+          { status:400, desc:'Not usable', body:{ valid:false, message:'This code has expired.' }},
+        ]},
+      { method:'GET', path:'/api/coupons', auth:'supervisor+', desc:'List codes with use counts and total discount given',
+        responses:[{ status:200, desc:'Success', body:[{ id:'cpn-uuid-...', code:'STAFF50', type:'percent', value:50, summary:'50% off', active:true, uses:3, totalDiscount:1350 }]}]},
+      { method:'POST', path:'/api/coupons', auth:'supervisor+', desc:'Create a code. type: percent | fixed | comp. eventIds/options/userIds/restrictRoles/restrictDomain are optional.',
+        request:{ body:{ code:'STAFF50', type:'percent', value:50, eventIds:['ev-uuid-...'], restrictRoles:['staff','supervisor','admin'], maxUsesPerUser:1, stackEarlyBird:false }},
+        responses:[{ status:201, desc:'Created', body:{ id:'cpn-uuid-...', code:'STAFF50' }}, { status:409, desc:'Code exists', body:{ message:'The code STAFF50 already exists' }}]},
+      { method:'GET', path:'/api/coupons/:id', auth:'supervisor+', desc:'One code with every use (redemption)' },
+      { method:'PUT', path:'/api/coupons/:id', auth:'supervisor+', desc:'Edit a code or turn it off ({ active:false }). Discounts already given keep their amount; a used code can\'t be renamed.' },
+      { method:'GET', path:'/api/coupons/redemptions', auth:'supervisor+', desc:'Active uses for the Discounts report. Query: eventIds (comma-separated), from, to' },
+    ]},
+    { title: 'Bundle deals', base: '/api/bundles', endpoints: [
+      { method:'POST', path:'/api/bundles/quote', auth:'public', desc:'The bundle deals a basket gets, applied automatically as many times as they fit and only when cheaper. Staff can pass forUserId (or null for a walk-in).',
+        request:{ body:{ eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-adult', quantity:5 }, { eventOptionId:'opt-child', quantity:3 }] }},
+        responses:[{ status:200, desc:'Success', body:{ subtotal:550, bundleDiscount:50, bundles:[{ bundleId:'bnd-uuid-...', name:'Family deal', count:1, discount:50 }], total:500 }}]},
+      { method:'GET', path:'/api/bundles/event/:eventId', auth:'supervisor+', desc:'An event\'s bundles with uses and total discount given' },
+      { method:'POST', path:'/api/bundles/event/:eventId', auth:'supervisor+', desc:'Create a bundle. kind: exact (items with quantities, price for the set) | mix (any setSize of the items for price) | free (any setSize, cheapest freeCount free) | group (setSize or more of the items: groupPricing per_ticket price each, or percent off). items: [{ eventOptionId, variantId?, quantity }] (variantId left out = any variant; quantity only for exact).',
+        request:{ body:{ name:'Family deal', price:500, items:[{ eventOptionId:'opt-adult', quantity:5 }, { eventOptionId:'opt-child', quantity:3 }], validUntil:null }}},
+      { method:'PUT', path:'/api/bundles/:id', auth:'supervisor+', desc:'Edit a bundle or switch it off ({ isActive:false }). Registrations keep a bundle they already have.' },
+      { method:'DELETE', path:'/api/bundles/:id', auth:'supervisor+', desc:'Delete a bundle; one that has been used is switched off instead' },
+    ]},
+    { title: 'Payments', base: '/api/payments', endpoints: [
+      { method:'GET', path:'/api/payments/:id', auth:'Bearer', desc:'A payment by id' },
+      { method:'GET', path:'/api/payments/registration/:registrationId', auth:'Bearer', desc:'Payments of a registration' },
+      { method:'POST', path:'/api/payments/checkout/send', auth:'supervisor+', desc:'Send a generated payment link to the registrant by email or WhatsApp (also at /api/payments/yoco-checkout/send)', request:{ body:{ registrationId:'reg-uuid-...', redirectUrl:'https://pay.yoco.com/...', channel:'whatsapp' }}},
+      { method:'GET', path:'/api/payments/providers', auth:'—', desc:'Payment providers people can pay with now (enabled in Site settings → Payments and set up), in display order, plus the online minimum (R15)',
+        responses:[{ status:200, desc:'Success', body:{ providers:[{ id:'yoco', label:'Yoco' }], minimumAmount:15 }}]},
+      { method:'GET', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'The payer\'s page for a checkout: amount, description, providers to choose from, or the PayFast form to post' },
+      { method:'POST', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'Start the checkout with the provider the payer picked: { provider } → { redirectUrl } or { form }' },
+      { method:'GET', path:'/api/payments/checkouts/open', auth:'supervisor+', desc:'Online checkouts from the last 14 days with no payment yet, and whether their provider can be asked (canCheck)' },
+      { method:'POST', path:'/api/payments/checkouts/check', auth:'supervisor+', desc:'Ask providers whether checkouts were paid ({ ids? }, default all open) and record what they received. PayFast: transaction history; Yoco: cant_check' },
+      { method:'GET', path:'/api/payments/providers/settings', auth:'admin', desc:'Every provider with enabled, configured and capabilities ({ refund, getTransaction, listTransactions }), in display order' },
+      { method:'PUT', path:'/api/payments/providers/settings', auth:'admin', desc:'Turn providers on/off and set their order (the list order). Audit logged.',
+        request:{ body:{ providers:[{ id:'yoco', enabled:true }] }}},
+      { method:'POST', path:'/api/payments/unassign-donation', auth:'supervisor+', desc:'Reverse a donation assignment (removes the leg and reverts the registration status)' },
+      { method:'POST', path:'/api/payments/checkout', auth:'user+', desc:'Start an online checkout (also at /api/payments/yoco-checkout) with body.provider, or the first enabled provider. At least R15 (all providers). Before creating the checkout, re-evaluates early-bird tier eligibility (deadline + stock). If any price changed since registration, returns priceUpdated:true instead of creating a checkout — the client must inform the user and retry.',
+        request:{ body:{ registrationId:'reg-uuid-...', amount:450, provider:'yoco', successUrl:'https://events.example.com/payment/success', cancelUrl:'https://events.example.com/payment/cancel', failureUrl:'https://events.example.com/payment/failure' }},
+        responses:[
+          { status:200, desc:'Checkout created — send the payer to redirectUrl', body:{ redirectUrl:'https://pay.yoco.com/checkout/abc123', checkoutId:'yoco-checkout-id', provider:'yoco', amount:450 }},
+          { status:200, desc:'Early-bird price changed — checkout NOT created. Frontend must show warning and let user confirm before retrying.', body:{ priceUpdated:true, newTotal:500, message:'One or more early-bird prices have changed since your registration was created. Please review the updated total before proceeding.' }},
+        ]},
+      { method:'POST', path:'/api/payments', auth:'supervisor+', desc:'Record a manual payment (cash, EFT, etc.)',
+        request:{ body:{ registrationId:'reg-uuid-...', amount:450, method:'cash', userId:'user-uuid-...' }},
+        responses:[
+          { status:201, desc:'Recorded', body:{ id:'pay-uuid-...', amount:450, method:'cash', status:'succeeded', createdAt:'2025-06-10T09:00:00.000Z' }},
+        ]},
+      { method:'GET', path:'/api/payments/mypayments', auth:'user+', desc:'Get own payment history (paginated, excludes donations). Returned method is normalized to cash|card|eft|voucher|other — apple_pay/google_pay report as "card", any other gateway-reported value reports as "other"',
+        queryParams:{ page:'Page (default 1)', limit:'Per page (default 25, max 25)', startDate:'ISO date, filters createdAt >=', endDate:'ISO date, filters createdAt <=', method:'Filter by normalized method: cash|card|eft|voucher|other', kind:'payment|refund — filters by amount sign' },
+        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'pay-uuid-...', amount:450, method:'card', status:'succeeded', createdAt:'2025-06-01T11:00:00.000Z' }], total:1, page:1, limit:25, pages:1 }}]},
+      { method:'POST', path:'/api/payments/:id/send-receipt', auth:'user+', desc:'Regenerate the receipt PDF for one of the caller\'s own payments and send it on the requested channel — email or WhatsApp. Fails if there is no valid email/phone on file for the chosen channel.',
+        notes:'The PDF\'s receiptNo is derived, not sequential: RCPT-<year of payment.createdAt>-<last 6 hex chars of the payment id, uppercased>.',
+        pathParams:{ ':id':'Payment UUID' },
+        request:{ body:{ channel:'whatsapp' }},
+        responses:[
+          { status:200, desc:'Sent', body:{ message:'Receipt sent to WhatsApp.' }},
+          { status:403, desc:'Not the owner', body:{ message:'Not authorized to access this payment' }},
+        ]},
+      { method:'GET', path:'/api/payments', auth:'supervisor+', desc:'List all payments',
+        queryParams:{ page:'Page (default 1)', limit:'Per page (default 20)', eventId:'Filter by event', userId:'Filter by user', method:'Filter by method (cash|card|eft|donation)', startDate:'ISO date', endDate:'ISO date' },
+        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'pay-uuid-...', amount:450, method:'card', user:{ name:'Jane Doe' }, registration:{ event:{ title:'Camp 2025' }}}], total:1 }}]},
+      { method:'GET', path:'/api/payments/event/:eventId', auth:'staff+', desc:'All payments for an event',
+        pathParams:{ ':eventId':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'pay-uuid-...', amount:450, user:{ name:'Jane Doe' }, method:'card' }]}]},
+      { method:'POST', path:'/api/payments/refund', auth:'supervisor+', desc:'Create a refund payment (negative amount)',
+        request:{ body:{ originalPaymentId:'pay-uuid-...', amount:450, reason:'Cancelled registration' }},
+        responses:[{ status:201, desc:'Refund recorded', body:{ id:'pay-uuid-refund', amount:-450, method:'refund' }}]},
+      { method:'PUT', path:'/api/payments/assign-donation', auth:'supervisor+', desc:'Link an unassigned donation payment to a specific registration',
+        request:{ body:{ paymentId:'pay-uuid-...', registrationId:'reg-uuid-...' }},
+        responses:[{ status:200, desc:'Assigned', body:{ id:'pay-uuid-...', registrationId:'reg-uuid-...', isDonation:false }}]},
+      { method:'GET', path:'/api/payments/admin/stats', auth:'admin', desc:'Aggregated payment statistics',
+        responses:[{ status:200, desc:'Success', body:{ totalRevenue:98500, totalPayments:215, byMethod:{ card:180, cash:30, eft:5 }, byEvent:[{ eventId:'ev-uuid-...', title:'Camp 2025', total:45000 }] }}]},
+    ]},
+
+    { title: 'Tickets', base: '/api/tickets', endpoints: [
+      { method:'GET', path:'/api/tickets', auth:'supervisor+', desc:'All tickets' },
+      { method:'GET', path:'/api/tickets/:id', auth:'Bearer (owner or staff)', desc:'A ticket by id' },
+      { method:'GET', path:'/api/tickets/qr/:qrCode', auth:'staff+', desc:'A ticket by QR code' },
+      { method:'PUT', path:'/api/tickets/email-sent', auth:'admin', desc:'Mark tickets as emailed' },
+      { method:'GET', path:'/api/tickets/mytickets', auth:'user+', desc:'Get own tickets',
+        responses:[{ status:200, desc:'Success', body:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', event:{ title:'Camp 2025' }, registrationOption:{ eventOption:{ name:'Adult' }}, quantity:1, isUsed:false }]}]},
+      { method:'POST', path:'/api/tickets/generate', auth:'supervisor+', desc:'Generate tickets for a registration (idempotent — skips already-generated options)',
+        request:{ body:{ registrationId:'reg-uuid-...' }},
+        responses:[{ status:201, desc:'Generated', body:{ created:2, skipped:0, tickets:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123' }] }}]},
+      { method:'POST', path:'/api/tickets/scan/:qrCode', auth:'staff+', desc:'Scan and redeem a ticket',
+        pathParams:{ ':qrCode':'QR code string from ticket' },
+        request:{ body:{ quantity:1 }},
+        responses:[
+          { status:200, desc:'Scanned', body:{ ticket:{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', isUsed:true }, event:{ title:'Camp 2025' }, user:{ name:'Jane Doe' }, quantityRedeemed:1, remainingUses:0 }},
+          { status:400, desc:'Already used', body:{ message:'Ticket has already been fully redeemed.' }},
+          { status:404, desc:'Not found', body:{ message:'Ticket not found.' }},
+        ]},
+      { method:'GET', path:'/api/tickets/scan-preview/:qrCode', auth:'staff+', desc:'Preview a ticket scan without marking it used',
+        pathParams:{ ':qrCode':'QR code string' },
+        responses:[{ status:200, desc:'Preview', body:{ ticket:{ qrCode:'TKT-ABC123', quantity:2, isUsed:false }, event:{ title:'Camp 2025' }, user:{ name:'Jane Doe', phoneNumber:'+27821234567' }, totalRedeemed:0 }}]},
+      { method:'POST', path:'/api/tickets/email', auth:'user+', desc:'Email own tickets as PDF attachments',
+        responses:[{ status:200, desc:'Sent', body:{ message:'Tickets emailed.', count:2 }}]},
+      { method:'POST', path:'/api/tickets/send-to', auth:'staff+', desc:'Send tickets to a specific user by email or WhatsApp',
+        request:{ body:{ userId:'user-uuid-...', eventId:'ev-uuid-...', channel:'email' }},
+        responses:[{ status:200, desc:'Sent', body:{ sent:2 }}]},
+      { method:'GET', path:'/api/tickets/event/:eventId', auth:'staff+', desc:'All tickets for an event',
+        pathParams:{ ':eventId':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', user:{ name:'Jane Doe' }, isUsed:false, quantity:1 }]}]},
+      { method:'GET', path:'/api/tickets/scans/recent', auth:'staff+', desc:'Last 50 scan events across all events',
+        responses:[{ status:200, desc:'Success', body:[{ ticketId:'tkt-uuid-...', scannedAt:'2025-07-10T09:05:00.000Z', quantityRedeemed:1, ticket:{ user:{ name:'Jane Doe' }, event:{ title:'Camp 2025' }}, scannedBy:{ name:'Staff Member' }}]}]},
+      { method:'GET', path:'/api/tickets/scans/stats', auth:'staff+', desc:'Scan statistics grouped by event',
+        responses:[{ status:200, desc:'Success', body:[{ eventId:'ev-uuid-...', title:'Camp 2025', totalTickets:50, scanned:38, remaining:12 }]}]},
+    ]},
+
+    { title: 'Hub and licence', base: '/api/hub', endpoints: [
+      { method:'GET', path:'/health', auth:'public', desc:'Status, version, database, background jobs and last backup (503 if the database is down)',
+        responses:[{ status:200, desc:'Healthy', body:{ status:'ok', version:'1.41.0', db:true, jobs:{ mode:'queue', failedLast24h:0 }, lastBackupAt:'2026-10-26T00:00:12.000Z' }}]},
+      { method:'GET', path:'/api/hub/status', auth:'admin', desc:'Licence state (active, grace, suspended, revoked, unlicensed), Hub connection, version and update',
+        responses:[{ status:200, desc:'Success', body:{ state:'grace', readOnly:false, daysLeft:9, connected:true, version:'1.41.0', latestVersion:'1.42.0', updateAvailable:true }}]},
+      { method:'POST', path:'/api/hub/connect', auth:'admin', desc:'Connect to the Cross Events Hub with a licence key (also the /setup licence step)',
+        request:{ body:{ licenceKey:'CEH-7K2M-9QXA-P4RT-WD8C' } },
+        responses:[{ status:200, desc:'Connected (status as above)' }, { status:404, desc:'Unknown key', body:{ code:'LICENCE_NOT_FOUND', message:'That licence key was not found.' }}]},
+      { method:'POST', path:'/api/hub/heartbeat', auth:'admin', desc:'Check in with the Hub now (picks up licence changes)',
+        responses:[{ status:200, desc:'Status' }, { status:502, desc:'Hub unreachable' }]},
+      { method:'POST', path:'/api/hub/update-request', auth:'admin', desc:'Ask the Hub for this site to be updated to the latest version (the provider is told; the site never updates itself)',
+        responses:[{ status:200, desc:'Status, with updateRequest', body:{ updateAvailable:true, updateRequest:{ requestedAt:'2026-10-27T09:00:00.000Z', version:'1.42.0' } }}, { status:409, desc:'Already on the latest version', body:{ code:'UP_TO_DATE', message:'This site already runs the latest version.' }}, { status:502, desc:'Hub unreachable' }]},
+      { method:'POST', path:'/api/hub/update-request/cancel', auth:'admin', desc:'Withdraw the update request (the provider is told not to update after all)',
+        responses:[{ status:200, desc:'Status, updateRequest null' }, { status:502, desc:'Hub unreachable, or a Hub too old to withdraw requests (NOT_SUPPORTED)' }]},
+      { method:'POST', path:'/api/hub/update-snooze', auth:'admin', desc:'"Not now": no update reminders until a newer version is out. { snooze: false } turns them back on',
+        request:{ body:{ snooze:true } },
+        responses:[{ status:200, desc:'Status', body:{ updateAvailable:true, updateSnoozed:true } }, { status:400, desc:'No update, or an urgent one (can\'t be put off)' }]},
+      { method:'GET', path:'/api/hub/notices', auth:'supervisor', desc:'The provider\'s notices showing now (the dashboard banner for site admins and supervisors)',
+        responses:[{ status:200, desc:'Success', body:[{ id:'…', level:'maintenance', title:'Planned maintenance', message:'The site will be down for 30 minutes.', startsAt:'2026-11-01T16:00:00.000Z', endsAt:'2026-11-01T16:30:00.000Z' }] }]},
+    ]},
+
+    { title: 'Campuses', base: '/api/campuses', endpoints: [
+      { method:'GET', path:'/api/campuses', auth:'Public', desc:'Whether campuses are on, and the active campuses in order (empty while off)',
+        responses:[{ status:200, desc:'Success', body:{ enabled:true, campuses:[{ id:'c_1', name:'Henley Campus', slug:'henley-campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall', order:0 }] }}]},
+      { method:'GET', path:'/api/campuses/by-slug/:slug', auth:'Public', desc:'One active campus, for its /campus/<slug> page (404 when archived or campuses are off)' },
+      { method:'GET', path:'/api/campuses/admin', auth:'admin', desc:'All campuses with archived ones, event and home-campus counts, and daily-summary recipients' },
+      { method:'PUT', path:'/api/campuses/settings', auth:'admin', desc:'Turn campuses on or off (off hides campus fields and filters; nothing is deleted). Audited as campuses_toggled',
+        request:{ body:{ enabled:true } }},
+      { method:'POST', path:'/api/campuses', auth:'admin', desc:'Add a campus (slug made from the name unless given). 409 if the slug is taken',
+        request:{ body:{ name:'Henley Campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall' } }},
+      { method:'PUT', path:'/api/campuses/:id', auth:'admin', desc:'Change a campus, its daily-summary recipients (staff only) and archived state',
+        request:{ body:{ name:'Henley Campus', notifyRecipientIds:['u_1'], archived:false } }},
+      { method:'PUT', path:'/api/campuses/order', auth:'admin', desc:'Put the campuses in this order', request:{ body:{ ids:['c_2','c_1'] } }},
+      { method:'DELETE', path:'/api/campuses/:id', auth:'admin', desc:'Delete a campus with no events (409 CAMPUS_HAS_EVENTS otherwise — archive it)' },
+      { method:'GET', path:'/api/campuses/:id/audience', auth:'supervisor+', desc:'"Everyone at campus X" for broadcasts: home campus X, plus with ?registrants=true people registered for its events in the last 12 months' },
+    ]},
+
+    { title: 'Kids check-in', base: '/api/kids', endpoints: [
+      { method:'GET', path:'/api/kids/me', auth:'user', desc:'My family (children, authorised adults, parents), the family QR token, live pickup codes and pages from the last 24 hours' },
+      { method:'POST', path:'/api/kids/me', auth:'user', desc:'Start my family', request:{ body:{ name:'The Smith family' } } },
+      { method:'PUT', path:'/api/kids/me', auth:'user', desc:'Rename my family' },
+      { method:'DELETE', path:'/api/kids/me', auth:'user', desc:'Leave my family (the last parent leaving deletes it with its children)' },
+      { method:'POST', path:'/api/kids/me/children', auth:'user', desc:'Add a child (allergies, medical and custody notes are stored encrypted)',
+        request:{ body:{ firstName:'Mia', lastName:'Smith', dateOfBirth:'2021-03-04', allergies:'Peanuts', medicalNotes:'', custodyNotes:'' } } },
+      { method:'PUT', path:'/api/kids/me/children/:id', auth:'user', desc:'Change a child (custody note changes are audited)' },
+      { method:'DELETE', path:'/api/kids/me/children/:id', auth:'user', desc:'Remove a child' },
+      { method:'POST', path:'/api/kids/me/adults', auth:'user', desc:'Add an authorised adult (no account needed; up to 10)', request:{ body:{ name:'Mary Smith', phone:'0821234567', relationship:'Gran' } } },
+      { method:'PUT', path:'/api/kids/me/adults/:id', auth:'user', desc:'Change an authorised adult' },
+      { method:'DELETE', path:'/api/kids/me/adults/:id', auth:'user', desc:'Remove an authorised adult' },
+      { method:'GET', path:'/api/kids/setup-events', auth:'supervisor+', desc:'Upcoming events to set kids check-in up for (campus-scoped)' },
+      { method:'GET', path:'/api/kids/events/:eventId/settings', auth:'supervisor+', desc:'Kids check-in settings, the main tickets that can be the kids ticket and the allocation sets' },
+      { method:'PUT', path:'/api/kids/events/:eventId/settings', auth:'supervisor+', desc:'Switch kids check-in on/off and choose the kids ticket and rooms ("new" makes a free "Kids check-in" ticket or a "Kids rooms" set). Audited as kids_settings_updated',
+        request:{ body:{ enabled:true, optionId:'new', roomSetId:'new' } } },
+      { method:'GET', path:'/api/kids/events', auth:'staff+', desc:'Events with kids check-in from the last week on' },
+      { method:'GET', path:'/api/kids/events/:eventId/board', auth:'staff+', desc:'Rooms (counts, leaders on duty, full/over ratio), check-ins with allergies, medical and custody notes, and alerts for today\'s occasion. ?log=1 writes the access log' },
+      { method:'GET', path:'/api/kids/events/:eventId/families?q=', auth:'staff+', desc:'Find families by family, child or parent name, email or phone' },
+      { method:'POST', path:'/api/kids/events/:eventId/families', auth:'staff+', desc:'New family at the desk: the parent\'s account is matched by email/phone or created inactive',
+        request:{ body:{ name:'The Smith family', parent:{ name:'Anna Smith', phone:'0821234567', email:'' }, children:[{ firstName:'Mia', dateOfBirth:'2021-03-04' }] } } },
+      { method:'GET', path:'/api/kids/events/:eventId/families/qr/:token', auth:'staff+', desc:'The family for a scanned family QR code' },
+      { method:'GET', path:'/api/kids/events/:eventId/families/:familyId', auth:'staff+', desc:'One family' },
+      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/parents', auth:'staff+', desc:'Add a parent to a family' },
+      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/children', auth:'staff+', desc:'Add a child (custody notes: supervisors only)' },
+      { method:'PUT', path:'/api/kids/events/:eventId/families/:familyId/children/:childId', auth:'staff+', desc:'Change a child' },
+      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/adults', auth:'staff+', desc:'Add an authorised adult' },
+      { method:'POST', path:'/api/kids/events/:eventId/check-in', auth:'staff+', desc:'Check children in: one pickup code per family per occasion, a free place on the kids ticket the first time, a ticket usage each time. Sends the code to the parents (and optionally an authorised adult)',
+        request:{ body:{ familyId:'f_1', children:[{ childId:'c_1', roomId:'g_1' }], sendToAdultId:null } },
+        responses:[{ status:201, desc:'Checked in', body:{ code:'K7P2', qr:'KIDS-K7P2', checkIns:[{ id:'k_1', name:'Mia Smith', room:{ id:'g_1', name:'Toddlers' }, sticker:'ALLERGY: PEANUTS' }] } }] },
+      { method:'GET', path:'/api/kids/events/:eventId/code/:code', auth:'staff+', desc:'The children on a pickup code (for confirming who is collected)' },
+      { method:'POST', path:'/api/kids/events/:eventId/check-out', auth:'staff+', desc:'Check out with the pickup code. 404 WRONG_CODE raises a room alert (audited as kids_wrong_code)',
+        request:{ body:{ code:'K7P2', collectedBy:'Anna Smith', checkInIds:['k_1'] } } },
+      { method:'POST', path:'/api/kids/check-ins/:id/override', auth:'staff+', desc:'Check one child out without the code; reason and who collected required. Audited as kids_checkout_override' },
+      { method:'POST', path:'/api/kids/check-ins/:id/page', auth:'staff+', desc:'Ask the parents to come to the room (WhatsApp/email; shows on their Kids page)' },
+      { method:'PUT', path:'/api/kids/check-ins/:id/room', auth:'staff+', desc:'Move a child to another room' },
+      { method:'POST', path:'/api/kids/events/:eventId/duty', auth:'staff+', desc:'"I\'m on duty" in a room (on:false to go off), for the ratio' },
+      { method:'POST', path:'/api/kids/alerts/:id/resolve', auth:'staff+', desc:'Mark an alert as dealt with' },
+      { method:'GET', path:'/api/kids/events/:eventId/offline?deviceId=', auth:'staff+', desc:'Offline list for a desk: families, rooms, who is in, and 20 pickup codes reserved for the device' },
+      { method:'POST', path:'/api/kids/events/:eventId/sync', auth:'staff+', desc:'Sync an offline desk\'s check-ins and check-outs (idempotent by clientId). Audited as kids_offline_sync' },
+    ]},
+
+    { title: 'Event series', base: '/api/series', endpoints: [
+      { method:'GET', path:'/api/series', auth:'supervisor+', desc:'Every series with followers, eventCount and its events (campus-scoped staff see only their campuses\' events in each)' },
+      { method:'POST', path:'/api/series', auth:'supervisor+', desc:'Create a series (slug made from the name when not given). Audited as series_created',
+        request:{ body:{ name:'Family Camp', slug:'family-camp', description:'Every year in March', picture:null } } },
+      { method:'PUT', path:'/api/series/:id', auth:'supervisor+', desc:'Change a series. Audited as series_updated' },
+      { method:'DELETE', path:'/api/series/:id', auth:'admin', desc:'Delete a series; its events stay without a series and followers are dropped. Audited as series_deleted' },
+      { method:'GET', path:'/api/series/by-slug/:slug', auth:'public', desc:'The series page: details, upcoming and past public events, and following (signed in)' },
+      { method:'POST', path:'/api/series/:id/follow', auth:'user', desc:'Follow a series: an email (News & announcements) when a new event in it goes live' },
+      { method:'DELETE', path:'/api/series/:id/follow', auth:'user', desc:'Unfollow a series' },
+      { method:'GET', path:'/api/series/:id/compare', auth:'supervisor+', desc:'Year on year: registrations, tickets, income (as on the dashboard), checked in (average per session on multi-session events) and attendance rate per event in the series, oldest first, with the % change from the one before. Campus-scoped staff: their campuses\x27 events only' },
+    ]},
+
+    { title: 'Saved filters', base: '/api/saved-filters', endpoints: [
+      { method:'GET', path:'/api/saved-filters?page=', auth:'staff+', desc:'My saved filters for a list page (registrations, users, events, reports), default first' },
+      { method:'POST', path:'/api/saved-filters', auth:'staff+', desc:'Save (or replace by name) a filter: { page, name, params, isDefault? }. Up to 30 per page; making one the default clears the old default',
+        request:{ body:{ page:'registrations', name:'Camp — unpaid', params:{ event:'ev-uuid', status:'pending' }, isDefault:false } } },
+      { method:'PUT', path:'/api/saved-filters/:id', auth:'staff+', desc:'Rename it, or make it (or stop it being) my default — my own only' },
+      { method:'DELETE', path:'/api/saved-filters/:id', auth:'staff+', desc:'Delete one of my saved filters' },
+    ]},
+
+    { title: 'Dashboard and command palette', base: '/api/dashboard', endpoints: [
+      { method:'GET', path:'/api/dashboard/today', auth:'staff+', desc:'Events on today (or with a session today): places, people checked in today, children in now, volunteers rostered/checked in. Supervisors and admins also get money in (today, last 7 days) and "waiting" items: unpaid registrations for the next two weeks, parental consent, waitlist, cover requests, roster gaps, and for admins cashups due, provider payments to reconcile, privacy requests, failed webhooks. Campus-scoped' },
+      { method:'GET', path:'/api/dashboard/search?q=', auth:'staff+', desc:'Command palette search: events; supervisors also payments by amount ("R450"); admins also people and registrations by reference. { results: [{ type, id, title, subtitle, href }] }' },
+    ]},
+
+    { title: 'Outbound webhooks', base: '/api/outbound-webhooks', endpoints: [
+      { method:'GET', path:'/api/outbound-webhooks', auth:'admin', desc:'Endpoints (with last-week delivery counts per status) and the event types: registration.created, registration.paid, registration.cancelled, payment.received, payment.refunded, ticket.checked_in, user.created, event.published' },
+      { method:'POST', path:'/api/outbound-webhooks', auth:'admin', desc:'Add an endpoint (https, public address). The answer holds the signing secret — shown only now. Also added to the POPIA operator register. Audited as webhook_endpoint_changed',
+        request:{ body:{ name:'ChurchSuite sync', url:'https://example.com/hooks/cross-events', events:['registration.paid','ticket.checked_in'] } } },
+      { method:'PUT', path:'/api/outbound-webhooks/:id', auth:'admin', desc:'Change name, url, events or isActive' },
+      { method:'DELETE', path:'/api/outbound-webhooks/:id', auth:'admin', desc:'Delete an endpoint and its deliveries (its operator entry is marked inactive)' },
+      { method:'POST', path:'/api/outbound-webhooks/:id/rotate-secret', auth:'admin', desc:'A new signing secret (the old one stops at once)' },
+      { method:'POST', path:'/api/outbound-webhooks/:id/test', auth:'admin', desc:'Send a webhook.test now; answers { status, statusCode, error }' },
+      { method:'GET', path:'/api/outbound-webhooks/:id/deliveries?status=&limit=', auth:'admin', desc:'Delivery log, newest first, with payloads (kept 30 days)' },
+      { method:'POST', path:'/api/outbound-webhooks/deliveries/:id/resend', auth:'admin', desc:'Send a delivery again now' },
+    ]},
+
+    { title: 'Season passes', base: '/api/season-passes', endpoints: [
+      { method:'GET', path:'/api/season-passes?seriesId=', auth:'supervisor+', desc:'A series\x27 passes: events, normal prices, each event\x27s share, sold and unpaid counts' },
+      { method:'POST', path:'/api/season-passes', auth:'supervisor+', desc:'Create a pass. Events must be in the series; not youth (consent) events, staff-only or per-session tickets. Campus-scoped supervisors: only their campuses\x27 events. Audited as season_pass_changed',
+        request:{ body:{ seriesId:'series-uuid', name:'2027 breakfasts', price:400, saleEndsAt:null, items:[{ eventId:'ev-uuid', eventOptionId:'opt-uuid', variantId:null }] } } },
+      { method:'PUT', path:'/api/season-passes/:id', auth:'supervisor+', desc:'Change a pass (events and price only while nobody has bought it; 409 otherwise)' },
+      { method:'DELETE', path:'/api/season-passes/:id', auth:'supervisor+', desc:'Delete a pass nobody has bought' },
+      { method:'POST', path:'/api/season-passes/:id/buy', auth:'user', desc:'Buy passes: a registration at every event (lines priced at each event\x27s share), then one checkout for the total (redirectUrl), or tickets straight away when free. 409 when not on sale or an event has too few places',
+        request:{ body:{ quantity:2 } }, responses:[{ status:201, desc:'Bought', body:{ purchaseId:'uuid', total:800, paid:false, redirectUrl:'https://…', provider:'yoco', message:null } }] },
+      { method:'POST', path:'/api/season-passes/purchases/:id/checkout', auth:'user', desc:'Pay what is still owed on my purchase (a new checkout)' },
+      { method:'GET', path:'/api/season-passes/mine', auth:'user', desc:'My pass purchases with their registrations' },
+    ]},
+
+    { title: 'Volunteer rosters', base: '/api/volunteers', endpoints: [
+      { method:'GET', path:'/api/volunteers/me', auth:'user', desc:'My shifts (upcoming and the last week), cover requests I could take, and events looking for volunteers' },
+      { method:'GET', path:'/api/volunteers/events/:eventId', auth:'user', desc:'An event\'s serving roles: shift, how many are needed and signed up, whether I\'m in it, open cover requests' },
+      { method:'POST', path:'/api/volunteers/roles/:id/sign-up', auth:'user', desc:'Sign up for a role. 409 ROLE_FULL when it\'s full, 409 SHIFT_CLASH when I serve elsewhere at the same time. Gives a free volunteer place when the event has one',
+        responses:[{ status:201, desc:'Signed up', body:{ slotId:'s_1', ticket:true } }] },
+      { method:'DELETE', path:'/api/volunteers/slots/:id', auth:'user', desc:'Withdraw from a shift (not after checking in or once it\'s over). The event\'s notify recipients are emailed' },
+      { method:'POST', path:'/api/volunteers/slots/:id/swap', auth:'user', desc:'"Can\'t make it": ask for cover. The event\'s other volunteers are told; the request shows on everyone\'s Serving page', request:{ body:{ note:'Away that weekend' } } },
+      { method:'DELETE', path:'/api/volunteers/swaps/:id', auth:'user', desc:'Cancel my cover request' },
+      { method:'POST', path:'/api/volunteers/swaps/:id/accept', auth:'user', desc:'Take over someone\'s place. Happens at once (409 SWAP_CLOSED if someone was first); both volunteers and the event\'s notify recipients are told' },
+      { method:'POST', path:'/api/volunteers/check-in', auth:'user', desc:'Check in by scanning the event\'s volunteer QR code: every shift of mine on today is checked in; kids-room roles put me on duty in that room',
+        request:{ body:{ qr:'SERVE-3f2a…' } }, responses:[{ status:200, desc:'Checked in', body:{ event:{ id:'e_1', title:'Sunday service' }, checkedIn:[{ role:'Kids', kidsRoom:'Toddlers' }], already:[] } }] },
+      { method:'GET', path:'/api/volunteers/manage/events', auth:'staff+', desc:'Events with serving roles from the last 30 days on (?all=1, supervisors: every upcoming event). Campus-scoped' },
+      { method:'GET', path:'/api/volunteers/manage/events/:eventId', auth:'staff+', desc:'The roster sheet: roles with volunteers, contact details, check-ins and fill rate. ?log=1 writes the access log' },
+      { method:'GET', path:'/api/volunteers/manage/events/:eventId/qr', auth:'staff+', desc:'The volunteer check-in QR code value for the event (made the first time)' },
+      { method:'POST', path:'/api/volunteers/manage/slots/:id/check-in', auth:'staff+', desc:'Check a volunteer in by hand (undo:true to undo). Audited as volunteer_checked_in_manual' },
+      { method:'GET', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'The volunteer ticket setting, the main tickets that can be it and the event\'s kids rooms' },
+      { method:'PUT', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'Free volunteer place: optionId of a main ticket, "new" for a free "Volunteer" ticket, null for off (the default). Audited as volunteer_settings_updated', request:{ body:{ optionId:'new' } } },
+      { method:'POST', path:'/api/volunteers/manage/events/:eventId/roles', auth:'supervisor+', desc:'Add a serving role (sessionId required on multi-session events; shift times optional). Audited as volunteer_roles_changed',
+        request:{ body:{ name:'Welcome', needed:4, sessionId:null, startsAt:'2026-11-08T07:30:00.000Z', endsAt:'2026-11-08T09:30:00.000Z', description:'Front doors', kidsRoomId:null } } },
+      { method:'PUT', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Change a role' },
+      { method:'DELETE', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Delete a role (refused once someone checked in for it); its volunteers are told' },
+      { method:'POST', path:'/api/volunteers/manage/roles/:id/assign', auth:'supervisor+', desc:'Put someone on a role (allowed beyond the number needed); they\'re told. Audited as volunteer_assigned', request:{ body:{ userId:'u_1' } } },
+      { method:'DELETE', path:'/api/volunteers/manage/slots/:id', auth:'supervisor+', desc:'Take someone off a role (not after check-in); they\'re told. Audited as volunteer_removed' },
+      { method:'GET', path:'/api/volunteers/manage/hours?eventId=&from=&to=', auth:'supervisor+', desc:'Hours served per person (checked-in shifts × shift length), most first. Campus-scoped' },
+    ]},
+
+    { title: 'Privacy (POPIA)', base: '/api/privacy', endpoints: [
+      { method:'GET', path:'/api/privacy/me', auth:'user', desc:'My news opt-in, its history, and my privacy requests',
+        responses:[{ status:200, desc:'Success', body:{ news:{ email:true, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z', canWhatsApp:false, notificationPreference:'email', history:[{ channel:'email', granted:true, source:'signup', createdAt:'2026-10-23T08:00:00.000Z' }], requests:[] }}]},
+      { method:'PUT', path:'/api/privacy/me/news', auth:'user', desc:'Change the News & announcements opt-in per channel (source "prompt" for the one-time question after login)',
+        request:{ body:{ email:false, whatsapp:false } },
+        responses:[{ status:200, desc:'Saved', body:{ news:{ email:false, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z' }}]},
+      { method:'GET', path:'/api/privacy/me/export', auth:'user', desc:'Download my data — JSON, or ?format=pdf for a readable PDF. Blocked while impersonating',
+        responses:[{ status:200, desc:'File download' }]},
+      { method:'POST', path:'/api/privacy/me/requests', auth:'user', desc:'Correction request ({ type:"correction", details }) or delete my account ({ type:"deletion", password }) — deletion closes the account at once',
+        request:{ body:{ type:'correction', details:'My son\'s date of birth on the Camp registration is wrong — it should be 3 May 2012.' } },
+        responses:[{ status:201, desc:'Created', body:{ request:{ id:'req-uuid-...', type:'correction', status:'open', dueAt:'2026-11-22T08:00:00.000Z' }, message:'Your request was sent.' }}, { status:409, desc:'Already open', body:{ message:'You already have an open correction request.' }}]},
+      { method:'GET', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'What an unsubscribe link (signed token) is for',
+        responses:[{ status:200, desc:'Success', body:{ kind:'account', email:'jo***@example.com', hasPhone:true, news:{ email:true, whatsapp:true } }}]},
+      { method:'POST', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'Unsubscribe from news ({ channels?: ["email","whatsapp"] }, default both)',
+        responses:[{ status:200, desc:'Done', body:{ message:'You have been unsubscribed.' }}]},
+      { method:'POST', path:'/api/privacy/unsubscribe/:token/one-click', auth:'public', desc:'RFC 8058 one-click unsubscribe from the List-Unsubscribe email header (email news off)',
+        responses:[{ status:200, desc:'Done' }]},
+      { method:'GET', path:'/api/privacy/requests', auth:'admin', desc:'Data requests inbox (?status=open|closed|all), with due dates and, for deletions, the registrations still blocking it',
+        responses:[{ status:200, desc:'Success', body:{ requests:[{ id:'req-uuid-...', type:'deletion', status:'open', name:'Jane Doe', email:'jane@example.com', dueAt:'2026-11-22T08:00:00.000Z', overdue:false, blockers:[] }], openCount:1 }}]},
+      { method:'POST', path:'/api/privacy/requests/:id/complete', auth:'admin', desc:'Complete a request (emailed to the person). Deletion anonymises the account; 409 while it has a registration for an upcoming event',
+        request:{ body:{ response:'Corrected the date of birth on the Camp 2026 registration.' } },
+        responses:[{ status:200, desc:'Completed', body:{ request:{ status:'completed' }, anonymised:null }}]},
+      { method:'POST', path:'/api/privacy/requests/:id/reject', auth:'admin', desc:'Reject a request, or mark it withdrawn (cancelled:true); a deletion request reopens the account',
+        request:{ body:{ response:'We could not find a registration with that name.', cancelled:false } },
+        responses:[{ status:200, desc:'Closed', body:{ request:{ status:'rejected' } }}]},
+      { method:'GET', path:'/api/privacy/notice', auth:'public', desc:'The privacy notice (current, or ?version=N) with org details and the operator list filled in. Version 0 = built-in, until one is published',
+        responses:[{ status:200, desc:'Success', body:{ version:2, builtIn:false, current:true, effectiveDate:'23 October 2026', changeSummary:'We added WhatsApp news.', sections:[{ id:'introduction', title:'1. Introduction', body:'Hope Church values your privacy…' }], versions:[{ version:2, publishedAt:'2026-10-23T10:00:00.000Z', requiresAcceptance:true }] }}]},
+      { method:'POST', path:'/api/privacy/me/notice/accept', auth:'user', desc:'Accept the current privacy notice version',
+        responses:[{ status:200, desc:'Accepted', body:{ version:2 }}]},
+      { method:'GET', path:'/api/privacy/notice/draft', auth:'admin', desc:'Notice editor: draft (or current) sections, rendered preview, published versions with acceptance counts, built-in text',
+        responses:[{ status:200, desc:'Success', body:{ sections:[], rendered:[], isDraft:false, savedAt:null, versions:[{ version:1, acceptances:12 }] }}]},
+      { method:'PUT', path:'/api/privacy/notice/draft', auth:'admin', desc:'Save the draft ({ sections: [{ id?, title, body }] })',
+        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }] } },
+        responses:[{ status:200, desc:'Saved', body:{ isDraft:true }}]},
+      { method:'DELETE', path:'/api/privacy/notice/draft', auth:'admin', desc:'Discard the draft',
+        responses:[{ status:200, desc:'Discarded', body:{ message:'Draft discarded.' }}]},
+      { method:'POST', path:'/api/privacy/notice/publish', auth:'admin', desc:'Publish the next version; requiresAcceptance asks everyone to accept it after their next login (needs changeSummary)',
+        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }], changeSummary:'We added WhatsApp news.', requiresAcceptance:true } },
+        responses:[{ status:201, desc:'Published', body:{ version:2, requiresAcceptance:true }}]},
+      { method:'GET', path:'/api/privacy/operators', auth:'admin', desc:'The operator register (third parties that process personal information)',
+        responses:[{ status:200, desc:'Success', body:[{ id:'op-uuid-...', name:'PayFast', purpose:'Online payments', dataShared:'Name, email address, payment amount and reference', location:'South Africa', website:'https://payfast.io', active:true }] }]},
+      { method:'POST', path:'/api/privacy/operators', auth:'admin', desc:'Add an operator (PUT/DELETE /api/privacy/operators/:id to change or remove)',
+        request:{ body:{ name:'Mailgun', purpose:'Sending emails', dataShared:'Name, email address, message content', location:'EU' } },
+        responses:[{ status:201, desc:'Created' }]},
+      { method:'GET', path:'/api/privacy/consent-log', auth:'admin', desc:'Consent records: ?type=news|notice|parental, ?q= name/email, ?page=',
+        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', name:'Jane Doe', email:'jane@example.com', channel:'email', granted:false, source:'unsubscribe_link' }] }}]},
+      { method:'GET', path:'/api/privacy/readiness', auth:'admin', desc:'POPIA readiness checklist with a score; each open item has a link to fix it',
+        responses:[{ status:200, desc:'Success', body:{ score:77, passed:10, total:13, checks:[{ key:'notice', label:'Privacy notice published', ok:true, detail:'2 versions published', href:'/dashboard/admin/privacy?tab=notice', applies:true }] }}]},
+      { method:'GET', path:'/api/privacy/retention', auth:'admin', desc:'Retention policies, what the next run would affect, and the last run',
+        responses:[{ status:200, desc:'Success', body:{ policies:{ inactive_accounts:{ enabled:true, months:60 } }, preview:{ inactive_accounts:{ toWarn:3, toAnonymise:0 } }, reviewedAt:null }}]},
+      { method:'PUT', path:'/api/privacy/retention', auth:'admin', desc:'Save the retention policies (all five)',
+        request:{ body:{ policies:{ inactive_accounts:{ enabled:true, months:60 }, form_answers:{ enabled:true, months:12 }, login_history:{ enabled:true, months:24 }, payment_details:{ enabled:true, months:24 }, audit_logs:{ enabled:true, months:60 } } } },
+        responses:[{ status:200, desc:'Saved' }]},
+      { method:'POST', path:'/api/privacy/retention/run', auth:'admin', desc:'Run the retention job now (warn/anonymise inactive accounts, delete expired data)',
+        responses:[{ status:200, desc:'Done', body:{ result:{ inactive_accounts:{ warned:3, anonymised:0, waiting:0 }, login_history:{ deleted:120 } } }}]},
+      { method:'GET', path:'/api/privacy/breaches', auth:'admin', desc:'The breach register (security compromises); POST to record one, PUT /:id to update or mark the Regulator/people told',
+        responses:[{ status:200, desc:'Success', body:[{ id:'br-uuid-...', title:'Phone with the attendee list lost', status:'open', discoveredAt:'2026-10-23T08:00:00.000Z', regulatorNotifiedAt:null }] }]},
+      { method:'GET', path:'/api/privacy/access-log', auth:'admin', desc:'Bulk exports/views of personal information: ?action=, ?actorId=, ?sensitive=true, ?from=, ?to=, ?page=',
+        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', actor:'Sam Supervisor', action:'report_pdf', what:'Camp 2026 attendees', records:48 }] }}]},
+    ]},
+
+    { title: 'Broadcasts (Email)', base: '/api/broadcasts', endpoints: [
+      { method:'POST', path:'/api/broadcasts/preview', auth:'supervisor+', desc:'Dry-run a broadcast — returns resolved recipient list without sending',
+        request:{ body:{ userIds:['user-uuid-1','user-uuid-2'], emails:'extra@example.com\nJohn <john@example.com>', eventId:'ev-uuid-...' }},
+        responses:[{ status:200, desc:'Preview', body:{ matched:3, recipients:[{ email:'jane@example.com', name:'Jane Doe' },{ email:'extra@example.com', name:null }] }}]},
+      { method:'POST', path:'/api/broadcasts/send', auth:'supervisor+', desc:'Send an email broadcast to users and/or ad-hoc addresses',
+        request:{ body:{ subject:'Important update', text:'Hi {{name}}, here is a message for you.', userIds:['user-uuid-1'], emails:'extra@example.com', eventId:'ev-uuid-...' }},
+        responses:[{ status:200, desc:'Sent', body:{ matched:2, sent:2 }}]},
+      { method:'POST', path:'/api/broadcasts/schedule', auth:'supervisor+', desc:'Schedule an email broadcast for a future time',
+        request:{ body:{ subject:'Save the date!', text:'Hi {{name}}, mark your calendar for {{event.title}}.', userIds:['user-uuid-1'], scheduledAt:'2025-06-01T09:00:00.000Z', eventId:'ev-uuid-...' }},
+        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued', scheduledAt:'2025-06-01T09:00:00.000Z' }}}]},
+    ]},
+
+    { title: 'Broadcasts (WhatsApp)', base: '/api/whatsapp-broadcasts', endpoints: [
+      { method:'POST', path:'/api/whatsapp-broadcasts/preview', auth:'supervisor+', desc:'Dry-run — resolve phone list without sending',
+        request:{ body:{ userIds:['user-uuid-1'], phones:'0821234567\nJane <0721234567>', eventId:'ev-uuid-...' }},
+        responses:[{ status:200, desc:'Preview', body:{ matched:2, recipients:[{ phone:'+27821234567', name:'Jane Doe' }] }}]},
+      { method:'POST', path:'/api/whatsapp-broadcasts/send', auth:'supervisor+', desc:'Send a WhatsApp broadcast',
+        request:{ body:{ message:'Hi {{name}}, please check your tickets for {{event.title}}.', userIds:['user-uuid-1'], phones:'0821234567', eventId:'ev-uuid-...' }},
+        responses:[{ status:200, desc:'Sent', body:{ matched:2, sent:2 }}]},
+      { method:'POST', path:'/api/whatsapp-broadcasts/schedule', auth:'supervisor+', desc:'Schedule a WhatsApp broadcast',
+        request:{ body:{ message:'Hi {{name}}! {{event.title}} is tomorrow. See you there 🙌', userIds:['user-uuid-1'], scheduledAt:'2025-07-09T08:00:00.000Z' }},
+        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued' }}}]},
+    ]},
+
+    { title: 'Scheduled Messages', base: '/api/scheduled-emails', endpoints: [
+      { method:'GET', path:'/api/scheduled-emails', auth:'supervisor+', desc:'List all scheduled jobs — email and WhatsApp. Jobs sent more than 7 days ago are hidden.',
+        responses:[{ status:200, desc:'Success', body:{ jobs:[{ id:'job-uuid-...', channel:'email', broadcast:false, eventId:'ev-uuid-...', status:'queued', scheduledAt:'2025-07-03T09:00:00.000Z', attempts:0, payload:{ subject:'Camp reminder' }}]}}]},
+      { method:'PATCH', path:'/api/scheduled-emails/:id', auth:'supervisor+', desc:'Edit a queued job — reschedule or update its message content',
+        pathParams:{ ':id':'Scheduled job UUID' },
+        request:{ body:{ scheduledAt:'2025-07-04T09:00:00.000Z', subject:'Updated subject', text:'Hi {{name}}, updated message.' }},
+        responses:[
+          { status:200, desc:'Updated', body:{ id:'job-uuid-...', scheduledAt:'2025-07-04T09:00:00.000Z', status:'queued' }},
+          { status:400, desc:'Already sent', body:{ message:'Cannot edit a job that has already been sent.' }},
+        ]},
+      { method:'DELETE', path:'/api/scheduled-emails/:id', auth:'supervisor+', desc:'Cancel and remove a queued job',
+        pathParams:{ ':id':'Scheduled job UUID' },
+        responses:[{ status:200, desc:'Deleted', body:{ message:'Scheduled job removed.' }}]},
+    ]},
+
+    { title: 'Automations', base: '/api/automations', endpoints: [
+      { method:'POST', path:'/api/automations/schedule', auth:'supervisor+', desc:'Schedule multiple lifecycle email automations for an event in one call (pre-event, final reminder, thank-you, promo).',
+        request:{ body:{ eventId:'ev-uuid-...', jobs:[
+          { subject:'1 Week to Go: Camp 2025!', text:'Hi {{name}}, camp is one week away!\n\nDetails: {{event.link}}', scheduledAt:'2025-07-03T09:00:00.000Z' },
+          { subject:"We'll See You Tomorrow!", text:'Hi {{name}}, final reminder for {{event.title}}. Please have your QR code ready.', scheduledAt:'2025-07-09T09:00:00.000Z' },
+        ]}},
+        responses:[{ status:201, desc:'Scheduled', body:{ message:'2 automation(s) scheduled.', jobs:[{ id:'job-uuid-1', status:'queued' },{ id:'job-uuid-2', status:'queued' }] }}]},
+    ]},
+
+    { title: 'Reports', base: '/api/reports', endpoints: [
+      { method:'POST', path:'/api/reports/excel', auth:'Bearer', desc:'Build an Excel file from a report payload' },
+      { method:'POST', path:'/api/reports/whatsapp', auth:'Bearer', desc:'Send a report PDF by WhatsApp' },
+      { method:'POST', path:'/api/reports/pdf', auth:'user+', desc:'Generate a PDF report of own registrations and tickets and return it as a binary download',
+        responses:[{ status:200, desc:'PDF file (application/pdf)', body:'<binary PDF>' }]},
+      { method:'POST', path:'/api/reports/email', auth:'user+', desc:'Generate PDF report and email it to the authenticated user',
+        responses:[{ status:200, desc:'Sent', body:{ message:'Report emailed.' }}]},
+    ]},
+
+    { title: 'Costs', base: '/api/events/:eventId/costs', endpoints: [
+      { method:'GET', path:'/api/events/:eventId/costs', auth:'supervisor+', desc:'List costs (once-off or per-item) for an event',
+        pathParams:{ ':eventId':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:[{ id:'cost-uuid-...', label:'Venue hire', costType:'once_off', amount:2500 },{ id:'cost-uuid-2', label:'Catering', costType:'per_item', amount:75, eventOptionId:'opt-uuid-...' }]}]},
+      { method:'POST', path:'/api/events/:eventId/costs', auth:'admin', desc:'Create a cost for an event. eventOptionId is required when costType is per_item. paidFromMethod (cash/card/eft/other) optionally tags which float it was paid out of. Rejected once the event is closed.',
+        pathParams:{ ':eventId':'Event UUID' },
+        request:{ body:{ label:'Catering', costType:'per_item', amount:75, eventOptionId:'opt-uuid-...', paidFromMethod:'cash' }},
+        responses:[{ status:201, desc:'Created', body:{ id:'cost-uuid-new', label:'Catering', costType:'per_item', amount:75, paidFromMethod:'cash' }}]},
+      { method:'PUT', path:'/api/costs/:id', auth:'admin', desc:'Update a cost. Rejected once the event is closed.',
+        pathParams:{ ':id':'EventCost UUID' },
+        request:{ body:{ amount:80 }},
+        responses:[{ status:200, desc:'Updated', body:{ id:'cost-uuid-...', amount:80 }}]},
+      { method:'DELETE', path:'/api/costs/:id', auth:'admin', desc:'Delete a cost. Rejected once the event is closed.',
+        pathParams:{ ':id':'EventCost UUID' },
+        responses:[{ status:200, desc:'Deleted', body:{ message:'Cost deleted' }}]},
+    ]},
+
+    { title: 'Cashups', base: '/api/cashups', endpoints: [
+      { method:'GET', path:'/api/cashups/event/:eventId/cash-by-user', auth:'supervisor+', desc:'Payments recorded for an event, by staff member and method' },
+      { method:'PUT', path:'/api/cashups/event/:eventId/person-cash/:userId', auth:'supervisor+', desc:'Enter one staff member\'s physical cash count for an event' },
+      { method:'GET', path:'/api/cashups/event/:eventId', auth:'supervisor+', desc:'Live cashup preview for an event: system income vs. reconciled actual per method, method-tagged costs, unallocated donations, net profit, and the full close/reopen history',
+        pathParams:{ ':eventId':'Event UUID' },
+        responses:[{ status:200, desc:'Success', body:{ event:{ id:'ev-uuid-...', title:'Camp 2025', cashupStatus:'open' }, paymentsByMethod:{ cash:1200, card:4500, eft:600, other:0 }, expectedCashByMethod:{ cash:1150, card:4500, eft:600, other:0 }, unallocatedDonationsTotal:150, totalCosts:900, netProfit:6450, history:[] }}]},
+      { method:'PUT', path:'/api/cashups/event/:eventId/draft', auth:'admin', desc:'Save in-progress reconciliation entries (actual counted amounts, and cash denomination counts, per method) without closing the event',
+        pathParams:{ ':eventId':'Event UUID' },
+        request:{ body:{ lines:[{ method:'cash', denominations:[{ value:100, count:5 },{ value:50, count:2 }] },{ method:'card', actualAmount:4500 }] }},
+        responses:[{ status:200, desc:'Saved', body:{ message:'Draft saved' }}]},
+      { method:'POST', path:'/api/cashups/event/:eventId/close', auth:'admin', desc:'Close the event. Pass "lines" for a full per-method cashup (variances computed against expected cash, i.e. income minus any method-tagged costs) — for the cash line, pass "denominations" and the actual amount is computed from the note/coin counts server-side. Omit "lines" for a quick close that accepts system numbers as-is. Either way, unallocated donations are counted as profit and the event is fully locked (no new registrations, payments, refunds, checkouts, or donations) until an admin reopens it. Creates a permanent EventCashup audit row.',
+        pathParams:{ ':eventId':'Event UUID' },
+        request:{ body:{ lines:[{ method:'cash', denominations:[{ value:100, count:5 },{ value:50, count:2 }], notes:'R20 short' }], notes:'Closed after evening service' }},
+        responses:[{ status:201, desc:'Closed', body:{ id:'cashup-uuid-...', action:'closed', unallocatedDonationsTotal:150, totalCosts:900, totalExpectedRevenue:6300, totalActualRevenue:6280 }}]},
+      { method:'POST', path:'/api/cashups/event/:eventId/reopen', auth:'admin', desc:'Reopen a closed event, unlocking registrations/payments/donations again. Admin-only. Creates a permanent "reopened" EventCashup audit row.',
+        pathParams:{ ':eventId':'Event UUID' },
+        request:{ body:{ notes:'Reopening to correct a miscounted cash drawer' }},
+        responses:[{ status:201, desc:'Reopened', body:{ id:'cashup-uuid-...', action:'reopened' }}]},
+      { method:'GET', path:'/api/cashups/audit', auth:'supervisor+', desc:'Flat audit log of every close/quick-close/reopen across events, optionally filtered by eventId and/or from/to dates',
+        request:{ query:{ eventId:'ev-uuid-... (optional)', from:'2026-01-01 (optional)', to:'2026-12-31 (optional)' }},
+        responses:[{ status:200, desc:'Success', body:[{ id:'cashup-uuid-...', action:'closed', event:{ id:'ev-uuid-...', title:'Camp 2025' }, performedBy:{ name:'Jane Supervisor' }, createdAt:'2026-07-20T18:00:00.000Z' }]}]},
+    ]},
+
+    { title: 'Uploads', base: '/api/uploads', endpoints: [
+      { method:'POST', path:'/api/uploads/logo', auth:'admin (open during first-run setup)', desc:'Upload the site logo (multipart, field "image")' },
+      { method:'POST', path:'/api/uploads/favicon', auth:'admin (open during first-run setup)', desc:'Upload the site favicon (multipart, field "image")' },
+      { method:'POST', path:'/api/uploads/event-image', auth:'supervisor+', desc:'Upload an event cover image. Send as multipart/form-data with field name "image". Returns the public URL.',
+        notes:'Content-Type must be multipart/form-data. Max size is typically 5 MB.',
+        responses:[
+          { status:200, desc:'Uploaded', body:{ url:'/uploads/event-images/camp-2025-abc123.jpg' }},
+          { status:400, desc:'No file', body:{ message:'No image file provided.' }},
+        ]},
+    ]},
+
+    { title: 'Sections', base: '/api/sections', endpoints: [
+      { method:'GET', path:'/api/sections', auth:'staff+', desc:'List all sections with their allowed options',
+        responses:[{ status:200, desc:'Success', body:[{ id:'sec-uuid-...', eventId:'ev-uuid-...', name:'Adults', allowedOptions:[{ eventOptionId:'opt-uuid-...', eventOption:{ name:'Adult', price:450 }}] }]}]},
+      { method:'POST', path:'/api/sections', auth:'supervisor+', desc:'Create a section for an event',
+        request:{ body:{ eventId:'ev-uuid-...', name:'Adults', optionIds:['opt-uuid-1','opt-uuid-2'] }},
+        responses:[{ status:201, desc:'Created', body:{ id:'sec-uuid-new', name:'Adults', eventId:'ev-uuid-...' }}]},
+      { method:'PUT', path:'/api/sections/:id', auth:'supervisor+', desc:'Update a section',
+        pathParams:{ ':id':'Section UUID' },
+        request:{ body:{ name:'Adults & Teens', optionIds:['opt-uuid-1','opt-uuid-2','opt-uuid-3'] }},
+        responses:[{ status:200, desc:'Updated', body:{ id:'sec-uuid-...', name:'Adults & Teens' }}]},
+      { method:'DELETE', path:'/api/sections/:id', auth:'admin', desc:'Delete a section',
+        pathParams:{ ':id':'Section UUID' },
+        responses:[{ status:200, desc:'Deleted', body:{ message:'Section deleted.' }}]},
+    ]},
+
+    { title: 'Banner', base: '/api/banner', endpoints: [
+      { method:'GET', path:'/api/banner', auth:'public', desc:'Get the current site-wide announcement banner',
+        responses:[
+          { status:200, desc:'Banner set', body:{ message:'Registration for Camp 2025 is now open!', type:'info', active:true }},
+          { status:200, desc:'No banner', body:{ message:null, active:false }},
+        ]},
+      { method:'POST', path:'/api/banner', auth:'supervisor+', desc:'Set or update the site banner',
+        request:{ body:{ message:'Registration is now closed.', type:'warning', active:true }},
+        responses:[{ status:200, desc:'Saved', body:{ message:'Registration is now closed.', type:'warning', active:true }}]},
+    ]},
+
+    { title: 'Forms', base: '/api/forms', endpoints: [
+      { method:'GET', path:'/api/forms/responses', auth:'staff+', desc:'List all submitted form responses across all events',
+        queryParams:{ eventId:'Filter by event UUID', page:'Page (default 1)', limit:'Per page (default 20)' },
+        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'resp-uuid-...', registrationId:'reg-uuid-...', createdAt:'2025-06-01T10:05:00.000Z', answers:[{ field:{ label:'Dietary requirements' }, value:'Vegetarian' }] }], total:1 }}]},
+    ]},
+
+    { title: 'Provider Transactions', base: '/api/provider-transactions', endpoints: [
+      { method:'GET', path:'/api/provider-transactions', auth:'supervisor+', desc:'Transactions payment providers sent by webhook (also at /api/yoco-transactions)',
+        queryParams:{ provider:'yoco', reconciled:'true|false', ignored:'true|false' },
+        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_abc', amount:45000, currency:'ZAR', reconciled:true, paymentId:'pay-uuid-...', createdDate:'2025-06-01T11:00:00.000Z' }] }}]},
+      { method:'GET', path:'/api/provider-transactions/unreconciled', auth:'supervisor+', desc:'Transactions not yet matched to a payment record',
+        queryParams:{ provider:'yoco' },
+        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_xyz', amount:45000, currency:'ZAR', reconciled:false }] }}]},
+      { method:'POST', path:'/api/provider-transactions/:id/reconcile', auth:'supervisor+', desc:'Record the transaction as a payment on a registration, or as a donation to an event',
+        pathParams:{ ':id':'ProviderTransaction UUID' },
+        request:{ body:{ registrationId:'reg-uuid-...', eventId:'(donation) event-uuid-...', userId:'(donation, optional) user-uuid-...' }},
+        responses:[{ status:200, desc:'Reconciled', body:{ success:true, data:{ transaction:{ id:'ptx-uuid-...', reconciled:true, paymentId:'pay-uuid-...' }, payment:{ id:'pay-uuid-...', provider:'yoco' } } }}]},
+      { method:'POST', path:'/api/provider-transactions/:id/ignore', auth:'supervisor+', desc:'Mark a transaction as intentionally ignored',
+        pathParams:{ ':id':'ProviderTransaction UUID' },
+        responses:[{ status:200, desc:'Ignored', body:{ success:true, data:{ id:'ptx-uuid-...', ignored:true } }}]},
+    ]},
+
+    { title: 'WhatsApp Admin', base: '/api/whatsapp', endpoints: [
+      { method:'POST', path:'/api/whatsapp/start', auth:'admin', desc:'Start (or restart) the WAWP WhatsApp instance' },
+      { method:'POST', path:'/api/whatsapp/request-code', auth:'admin', desc:'Request a pairing code to link a WhatsApp number' },
+      { method:'POST', path:'/api/whatsapp/delete-instance', auth:'admin', desc:'Delete the WAWP instance' },
+      { method:'POST', path:'/api/whatsapp/webhook', auth:'—', desc:'WAWP event webhook (alias of /api/webhooks/whatsapp)' },
+      { method:'GET', path:'/api/whatsapp/config', auth:'admin', desc:'Get the currently stored WAWP credentials from DB (tokens are partially masked)',
+        responses:[{ status:200, desc:'Success', body:{ instanceId:'wawp-instance-abc', accessToken:'eyJ...****', source:'db' }}]},
+      { method:'POST', path:'/api/whatsapp/config', auth:'admin', desc:'Save WAWP credentials to the database (AppSetting). Takes effect immediately; no restart needed.',
+        request:{ body:{ accessToken:'eyJhbGciOiJSUzI1...', instanceId:'wawp-instance-abc' }},
+        responses:[{ status:200, desc:'Saved', body:{ message:'WhatsApp config saved.' }}]},
+      { method:'GET', path:'/api/whatsapp/status', auth:'admin', desc:'Get the current WAWP session status',
+        responses:[
+          { status:200, desc:'Connected', body:{ status:'open', phoneNumber:'+27821234567', pushName:'Cross Code' }},
+          { status:200, desc:'Not connected', body:{ status:'close' }},
+        ]},
+      { method:'GET', path:'/api/whatsapp/qr', auth:'admin', desc:'Get a QR code image/string to link a WhatsApp account',
+        responses:[{ status:200, desc:'Success', body:{ qr:'data:image/png;base64,...', qrString:'2@abc123...' }}]},
+      { method:'POST', path:'/api/whatsapp/create-instance', auth:'admin', desc:'Create a new WAWP session instance',
+        responses:[{ status:200, desc:'Created', body:{ instanceId:'wawp-instance-new', message:'Instance created.' }}]},
+      { method:'POST', path:'/api/whatsapp/restart', auth:'admin', desc:'Restart the current WAWP instance',
+        responses:[{ status:200, desc:'Restarted', body:{ message:'Instance restarted.' }}]},
+      { method:'POST', path:'/api/whatsapp/logout', auth:'admin', desc:'Log out the current WhatsApp session',
+        responses:[{ status:200, desc:'Logged out', body:{ message:'Logged out.' }}]},
+    ]},
+
+    { title: 'Dashboard stats', base: '/api/stats', endpoints: [
+      { method:'GET', path:'/api/stats/staff', auth:'staff+', desc:'Everything the staff dashboard needs, in one call' },
+      { method:'GET', path:'/api/stats/supervisor', auth:'supervisor+', desc:'Everything the supervisor dashboard needs, in one call' },
+      { method:'GET', path:'/api/stats/admin', auth:'admin', desc:'Everything the admin dashboard needs, in one call' },
+      { method:'GET', path:'/api/stats/overview', auth:'supervisor+', desc:'Trailing-month KPIs (registrations, tickets, revenue, donations), revenue trend, top events, funnel conversion. ?campus=<id|slug|all> for one campus or church-wide events only' },
+    ]},
+    { title: 'Backups', base: '/api/backups', endpoints: [
+      { method:'GET', path:'/api/backups', auth:'admin', desc:'Local database backups, newest first' },
+      { method:'POST', path:'/api/backups/run', auth:'admin', desc:'Run a backup now' },
+      { method:'GET', path:'/api/backups/:filename/download', auth:'admin', desc:'Download a backup file' },
+    ]},
+    { title: 'Webhooks', base: '/api/webhooks', endpoints: [
+      { method:'POST', path:'/api/webhooks/payfast', auth:'PayFast ITN', desc:'PayFast payment notification (form-encoded). Checked as PayFast requires: signature, PayFast host, VALID from /eng/query/validate, and amount_gross equal to the checkout (otherwise held for review). COMPLETE records the payment.' },
+      { method:'POST', path:'/api/webhooks/yoco', auth:'HMAC', desc:'Yoco payment event webhook. Called by Yoco servers. Verified via HMAC-SHA256 signature in the X-Yoco-Signature header.',
+        notes:'This endpoint bypasses the global rate limiter. Raw body is parsed before JSON middleware. Refreshes early-bird pricing before computing totalDue to ensure accurate paid/partial status.',
+        request:{ body:{ id:'evt_yoco_abc', type:'payment.succeeded', payload:{ metadata:{ checkoutId:'checkout-id-...' }, amount:45000, currency:'ZAR' }}},
+        responses:[{ status:200, desc:'Acknowledged', body:{ received:true }}]},
+      { method:'POST', path:'/api/webhooks/whatsapp', auth:'—', desc:'WAWP inbound message event. Called by WAWP servers when a message arrives on the linked number.',
+        responses:[{ status:200, desc:'Acknowledged', body:{ received:true }}]},
+    ]},
+
+    { title: 'PayFast', base: '/api/payfast', endpoints: [
+      { method:'GET', path:'/api/payfast/config', auth:'admin', desc:'PayFast settings (passphrase masked), mode and the ITN notify URL (with a warning when PayFast can\'t reach it).' },
+      { method:'PUT', path:'/api/payfast/config', auth:'admin', desc:'Save merchantId, merchantKey, passphrase (encrypted) and/or mode (sandbox|live). Audit logged.' },
+      { method:'POST', path:'/api/payfast/test', auth:'admin', desc:'Check the saved merchant ID and passphrase with PayFast (signed API ping).' },
+    ]},
+    { title: 'Yoco', base: '/api/yoco', endpoints: [
+      { method:'GET', path:'/api/yoco/config', auth:'admin', desc:'Yoco settings with secrets masked (prefix + last 3 characters), where each comes from (db, env or none), test/live mode and the default webhook URL.',
+        responses:[{ status:200, desc:'Success', body:{ secretKeyMasked:'sk_test_***************aba', secretKeySource:'db', mode:'test', webhookSecretMasked:'whsec_*****************1Xz', webhookSecretSource:'db', webhookId:'sub_123', webhookUrl:'https://api.example.com/api/webhooks/yoco', configured:true }}]},
+      { method:'PUT', path:'/api/yoco/config', auth:'admin', desc:'Save the secret key and/or webhook secret (stored AES-256-GCM encrypted). A new secret key is checked against Yoco first. An empty string clears the value (the .env fallback then applies).',
+        request:{ body:{ secretKey:'sk_test_...', webhookSecret:'whsec_...' }},
+        responses:[{ status:200, desc:'Saved', body:{ message:'Yoco settings saved' }}]},
+      { method:'GET', path:'/api/yoco/webhooks', auth:'admin', desc:'Webhooks registered on the Yoco account, flagged isActive (its secret is the stored one) and pointsHere (URL is this server).',
+        responses:[{ status:200, desc:'Success', body:{ webhooks:[{ id:'sub_123', name:'hope-events', url:'https://api.example.com/api/webhooks/yoco', mode:'test', isActive:true, pointsHere:true }], defaultUrl:'https://api.example.com/api/webhooks/yoco' }}]},
+      { method:'POST', path:'/api/yoco/webhooks', auth:'admin', desc:'Register a webhook at Yoco (defaults: name "hope-events", URL = BACKEND_URL/api/webhooks/yoco) and store the secret Yoco returns. The URL must be public https.',
+        request:{ body:{ name:'hope-events', url:'https://api.example.com/api/webhooks/yoco' }},
+        responses:[{ status:201, desc:'Registered', body:{ message:'Webhook registered and its secret saved', webhook:{ id:'sub_123', name:'hope-events', url:'https://api.example.com/api/webhooks/yoco', mode:'test' }, webhookSecretMasked:'whsec_*****************1Xz' }}]},
+      { method:'DELETE', path:'/api/yoco/webhooks/:id', auth:'admin', desc:'Delete a webhook at Yoco. If it was the active one, the stored webhook secret is cleared too.',
+        responses:[{ status:200, desc:'Deleted', body:{ message:'Webhook deleted', clearedSecret:false }}]},
+    ]},
+
+    { title: 'Settings', base: '/api/settings', endpoints: [
+      { method:'GET', path:'/api/settings', auth:'public', desc:'Public settings — org name, brand colours (primary/secondary/accent), logo URL, favicon URL, legal page slugs, registration notification email (no secrets)',
+        responses:[{ status:200, desc:'Success', body:{ org_name:'Cross Code', org_tagline:'Event management, made simple', primary_color:'#4F46E5', secondary_color:'#8B5CF6', accent_color:'#EC4899', logo_url:'/uploads/branding/logo-123.png', favicon_url:'/uploads/branding/favicon-123.png' }}]},
+      { method:'GET', path:'/api/settings/all', auth:'admin', desc:'All settings including SMTP config. smtp_pass is returned masked (••••••••); smtp_user is returned decrypted.',
+        responses:[{ status:200, desc:'Success', body:[{ key:'smtp_host', value:'smtp.example.com' },{ key:'smtp_user', value:'user@example.com' },{ key:'smtp_pass', value:'••••••••' }]}]},
+      { method:'GET', path:'/api/settings/needs-setup', auth:'public', desc:'Returns true until the setup wizard has been completed (setup_complete flag is set).',
+        responses:[{ status:200, desc:'Success', body:{ needsSetup:true }}]},
+      { method:'PUT', path:'/api/settings', auth:'admin', desc:'Upsert one or more settings. smtp_user and smtp_pass are AES-256-GCM encrypted before storage. Sending •••••••• for smtp_pass is a no-op.',
+        request:{ body:{ org_name:'Cross Code', smtp_host:'smtp.gmail.com', smtp_port:'587', smtp_user:'user@gmail.com', smtp_pass:'app-password' }},
+        responses:[{ status:200, desc:'Saved', body:{ message:'Settings saved.' }}]},
+      { method:'POST', path:'/api/settings/test-smtp', auth:'admin (or setup token)', desc:'Test the SMTP connection with provided credentials. On success, sends a real test email to the authenticated admin and returns a friendly message. On failure, returns a human-readable message plus a raw field containing the original SMTP error for debugging. Error code 530 (Microsoft "Client not authenticated") maps to the authentication-failure message.',
+        request:{ body:{ host:'smtp.gmail.com', port:587, secure:false, user:'me@gmail.com', pass:'app-password', from:'me@gmail.com' }},
+        responses:[
+          { status:200, desc:'Connection OK — test email sent', body:{ message:'SMTP connection verified — a test email has been sent to admin@example.com' }},
+          { status:400, desc:'Connection failed', body:{ message:'Authentication failed — check your SMTP username and password.', raw:'535 5.7.8 Error: authentication failed' }},
+        ]},
+    ]},
+
+    { title: 'Setup', base: '/api/setup', endpoints: [
+      { method:'POST', path:'/api/setup/register', auth:'public (one-time)', desc:'Step 2 of the first-time setup wizard. Creates the admin account and returns a short-lived JWT. Blocked once any user exists.',
+        request:{ body:{ name:'Admin User', email:'admin@example.com', password:'strong-password' }},
+        responses:[
+          { status:201, desc:'Created', body:{ token:'eyJhbGciOiJIUzI1NiJ9...', user:{ id:'uuid-...', name:'Admin User', role:'admin' }}},
+          { status:400, desc:'Already exists', body:{ message:'Setup already completed — users exist.' }},
+        ]},
+      { method:'POST', path:'/api/setup', auth:'setup token or admin', desc:'Final step of the setup wizard. Saves initial site settings. Requires the JWT returned by POST /api/setup/register.',
+        request:{ body:{ settings:{ org_name:'Cross Code', smtp_host:'smtp.gmail.com', smtp_port:'587', smtp_user:'user@gmail.com', smtp_pass:'app-password', mail_from:'noreply@example.com' }}},
+        responses:[{ status:200, desc:'Setup complete', body:{ message:'Setup complete.' }}]},
+    ]},
+  ];
+
+  // ── Rendering helpers ─────────────────────────────────────────────────────
+  function hl(json) {
+    // Simple JSON syntax highlighting — server-side
+    const s = JSON.stringify(json, null, 2);
+    return s
+      .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
+      .replace(/("(\\u[a-zA-Z0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?)/g, (m) => {
+        if (/^"/.test(m)) {
+          if (/:$/.test(m)) return `<span style="color:#6366f1">${m}</span>`; // key
+          return `<span style="color:#059669">${m}</span>`; // string value
+        }
+        if (/true|false/.test(m)) return `<span style="color:#d97706">${m}</span>`;
+        if (/null/.test(m)) return `<span style="color:#9ca3af">${m}</span>`;
+        return `<span style="color:#2563eb">${m}</span>`; // number
+      });
+  }
+
+  function codeBlock(content, lang) {
+    return `<pre style="background:#0f172a;color:#e2e8f0;padding:12px 14px;border-radius:6px;font-size:.75rem;overflow-x:auto;margin:0;line-height:1.6">${content}</pre>`;
+  }
+
+  function headerLine(key, val) {
+    return `<span style="color:#6366f1">${key}</span>: <span style="color:#059669">${val}</span>`;
+  }
+
+  function renderEndpoint(ep, idx) {
+    const id = `ep${idx}`;
+    const methodCls = { GET:'get', POST:'post', PUT:'put', PATCH:'patch', DELETE:'del' }[ep.method] || 'get';
+    const hasDetail = ep.notes || ep.pathParams || ep.queryParams || ep.request || ep.responses;
+
+    // Build HTTP request example
+    let reqLines = [];
+    const needsAuth = ep.auth !== 'public' && ep.auth !== 'HMAC' && ep.auth !== '—';
+    const isMultipart = ep.notes && ep.notes.includes('multipart');
+
+    reqLines.push(`<span style="color:#f59e0b;font-weight:600">${ep.method}</span> <span style="color:#e2e8f0">${ep.path}</span> <span style="color:#64748b">HTTP/1.1</span>`);
+    if (needsAuth) reqLines.push(headerLine('Authorization','Bearer &lt;your-jwt&gt;'));
+    if (ep.request?.body && !isMultipart) reqLines.push(headerLine('Content-Type','application/json'));
+    if (isMultipart) reqLines.push(headerLine('Content-Type','multipart/form-data'));
+    if (ep.request?.body && !isMultipart) {
+      reqLines.push('');
+      reqLines.push(hl(ep.request.body));
+    } else if (isMultipart) {
+      reqLines.push('');
+      reqLines.push(`<span style="color:#9ca3af">-- form field: image (binary file) --</span>`);
+    }
+
+    const reqHtml = codeBlock(reqLines.join('\n'));
+
+    // Build response examples
+    const resHtml = (ep.responses || []).map(r => {
+      const statusColor = r.status < 300 ? '#22c55e' : r.status < 500 ? '#f59e0b' : '#ef4444';
+      const body = typeof r.body === 'string' ? `<span style="color:#9ca3af">${r.body}</span>` : hl(r.body);
+      return `<div style="margin-bottom:8px">
+        <div style="font-size:.72rem;color:#64748b;margin-bottom:4px">
+          <span style="color:${statusColor};font-weight:600">HTTP ${r.status}</span>
+          <span style="margin-left:8px">${r.desc}</span>
+        </div>
+        ${codeBlock(body)}
+      </div>`;
+    }).join('');
+
+    // Path params table
+    let paramsHtml = '';
+    if (ep.pathParams && Object.keys(ep.pathParams).length) {
+      const rows = Object.entries(ep.pathParams).map(([k,v]) =>
+        `<tr><td style="padding:3px 10px;font-family:monospace;color:#6366f1;white-space:nowrap">${k}</td><td style="padding:3px 10px;color:#374151">${v}</td></tr>`).join('');
+      paramsHtml += `<div style="margin-bottom:10px"><div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:4px;text-transform:uppercase;letter-spacing:.05em">Path parameters</div><table style="width:100%;font-size:.8rem;border-collapse:collapse"><tbody>${rows}</tbody></table></div>`;
+    }
+    if (ep.queryParams && Object.keys(ep.queryParams).length) {
+      const rows = Object.entries(ep.queryParams).map(([k,v]) =>
+        `<tr><td style="padding:3px 10px;font-family:monospace;color:#6366f1;white-space:nowrap">${k}</td><td style="padding:3px 10px;color:#374151">${v}</td></tr>`).join('');
+      paramsHtml += `<div style="margin-bottom:10px"><div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:4px;text-transform:uppercase;letter-spacing:.05em">Query parameters</div><table style="width:100%;font-size:.8rem;border-collapse:collapse"><tbody>${rows}</tbody></table></div>`;
+    }
+
+    const notesHtml = ep.notes
+      ? `<div style="margin-bottom:10px;padding:8px 12px;background:#fefce8;border:1px solid #fde68a;border-radius:6px;font-size:.78rem;color:#92400e">${ep.notes}</div>`
+      : '';
+
+    const detailHtml = hasDetail ? `
+      <tr id="${id}-detail" style="display:none">
+        <td colspan="4" style="padding:0;border-bottom:2px solid #e5e7eb">
+          <div style="padding:16px;background:#f8fafc">
+            ${notesHtml}
+            ${paramsHtml}
+            <div style="display:grid;grid-template-columns:1fr 1fr;gap:16px">
+              <div>
+                <div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:6px;text-transform:uppercase;letter-spacing:.05em">Request</div>
+                ${reqHtml}
+              </div>
+              <div>
+                <div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:6px;text-transform:uppercase;letter-spacing:.05em">Responses</div>
+                ${resHtml}
+              </div>
+            </div>
+          </div>
+        </td>
+      </tr>` : '';
+
+    const cursor = hasDetail ? 'cursor:pointer' : '';
+    const chevron = hasDetail
+      ? `<svg id="${id}-chevron" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" style="display:inline;vertical-align:middle;transition:transform .15s;flex-shrink:0"><polyline points="9 18 15 12 9 6"/></svg>`
+      : '';
+
+    const onclick = hasDetail ? `onclick="toggle('${id}')"` : '';
+
+    return `
+      <tr ${onclick} style="${cursor};${hasDetail?'':''}">
+        <td style="padding:7px 10px"><span class="method ${methodCls}">${ep.method}</span></td>
+        <td style="padding:7px 10px;font-family:monospace;font-size:.8rem;word-break:break-all">${ep.path}</td>
+        <td style="padding:7px 10px"><span class="auth-badge">${ep.auth}</span></td>
+        <td style="padding:7px 10px;font-size:.82rem;display:flex;align-items:center;justify-content:space-between;gap:6px">
+          <span>${ep.desc}</span>
+          <span style="color:#9ca3af;flex-shrink:0">${chevron}</span>
+        </td>
+      </tr>
+      ${detailHtml}`;
+  }
+
+  function renderGroup(group) {
+    const rows = group.endpoints.map((ep, i) => renderEndpoint(ep, `${group.title.replace(/\W+/g,'')}-${i}`)).join('');
+    return `
+      <h2 style="font-size:1rem;font-weight:600;color:#111827;margin:24px 0 8px">${group.title} <span style="font-size:.78rem;font-weight:400;color:#6b7280;font-family:monospace">${group.base}</span></h2>
+      <div style="border:1px solid #e5e7eb;border-radius:10px;overflow:hidden;margin-bottom:4px">
+        <table style="width:100%;border-collapse:collapse">
+          <thead><tr style="background:#f9fafb;border-bottom:1px solid #e5e7eb">
+            <th style="padding:7px 10px;width:75px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Method</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Path</th>
+            <th style="padding:7px 10px;width:100px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Auth</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Description</th>
+          </tr></thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </div>`;
+  }
+
+  const groupsHtml = GROUPS.map(renderGroup).join('');
+
+  // ── Notifications reference — every automatic email/WhatsApp message the system sends ──
+  const NOTIFICATIONS = [
+    { category: 'Registration', items: [
+      { trigger: 'New registration — self-service (attendee registers via the public website)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration confirmed – {event}', content: 'Selections table, total due / paid / balance, payment options (website or at the door), and an account login / create-account prompt.' },
+      { trigger: 'New registration — self-service', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator when none are set)', subject: 'New registration: {event} — {name}', content: 'Registrant name, email, phone, status, items table, total due / paid / balance, registration ID.' },
+      { trigger: 'New registration — staff/at-door (manual registration, self-service kiosk)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration confirmed – {event}', content: 'Same as above, plus a Yoco pay-now link when a balance is owing.' },
+      { trigger: 'New registration — staff/at-door', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'New registration: {event} — {name}', content: 'Same layout as the self-service admin notice.' },
+      { trigger: 'Registration updated (options changed by staff, or a free registration completes)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration updated – {event}', content: 'Updated selections/total, same payment & account sections as the confirmation email.' },
+      { trigger: 'Registration updated', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Registration updated: {event} — {name}', content: 'Same layout as the new-registration admin notice.' },
+    ]},
+    { category: 'Payments', items: [
+      { trigger: 'Payment recorded (Yoco webhook success, manual cash/EFT entry, or a donation assigned to a registration)', channels: ['Email', 'WhatsApp'], recipients: 'Payer', subject: 'Payment received – {event} (or "Donation received – {event}" for unassigned donations)', content: 'Amount, method, date, full payment history table, updated balance.' },
+      { trigger: 'Payment recorded', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Payment recorded: {amount} — {payer} ({event})', content: 'Amount, type (registration payment / donation), payer, event, method, date, payment ID, external (Yoco) ID.' },
+      { trigger: 'Refund processed (negative payment created against an original payment)', channels: ['Email'], recipients: 'Payer', subject: 'Refund processed – {amount} for {event}', content: 'Refund amount, method, date, reason (when supplied).' },
+      { trigger: 'Refund processed', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Refund: Payment recorded: {amount} — {payer} ({event})', content: 'Same payment admin notice content, subject prefixed "Refund:".' },
+    ]},
+    { category: 'Tickets', items: [
+      { trigger: 'Tickets generated — fires whenever a registration becomes fully paid or is free (webhook, manual payment, staff status change, or free/no-cost registration)', channels: ['Email (PDF attached)', 'WhatsApp (PDF)'], recipients: 'Registrant (or a specific user when sent manually via "Send to")', subject: 'Your tickets for {event}', content: 'QR-coded ticket PDF, one per registered option/quantity; WhatsApp caption names the event and date.' },
+    ]},
+    { category: 'Daily digest', items: [
+      { trigger: 'Scheduled — every day at 07:00 local server time, once per active event that has gone live and has not yet started', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Daily summary: {event} — {date}', content: 'Stat tiles (registrations, paid, awaiting payment, revenue), full registrations table with balances, full payments & donations table.' },
+    ]},
+    { category: 'Account & security', items: [
+      { trigger: 'New account registered', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'New user', subject: 'Welcome to {org}!', content: 'Welcome message plus a list of upcoming events.' },
+      { trigger: 'Login attempt on an account that is not yet active', channels: ['Email (if a real address is on file)', 'WhatsApp (fallback when there is no usable email)'], recipients: 'User', subject: 'Activate your {org} account', content: 'One-time activation link; expires after 24 hours.' },
+      { trigger: 'Successful login', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'New login to your {org} account', content: 'Login time, approximate location, device/user agent. Security alert — always emailed regardless of the user\'s notification preference.' },
+      { trigger: 'Password changed via profile update', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'Your {org} password was changed', content: 'Confirms the change and gives a support contact to use if it wasn\'t them.' },
+      { trigger: 'Forgot-password request', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'Reset your password', content: 'Password reset link.' },
+      { trigger: 'Account closed (self-service — "Deactivate" or "Delete my data")', channels: ['Email', 'WhatsApp (if preferred)'], recipients: 'User (sent to their last-known address/number just before data is wiped)', subject: 'Your {org} account has been closed', content: 'Confirms closure; wording differs slightly when personal data was also erased.' },
+    ]},
+    { category: 'Admin-triggered broadcasts', items: [
+      { trigger: 'Bulk email to event attendees, or an ad-hoc email broadcast — sent immediately or on a schedule', channels: ['Email'], recipients: 'Selected attendees / users / ad-hoc addresses chosen by the sender', subject: 'Admin-authored', content: 'Free-form subject & body written by the sender, supporting {{name}}, {{event.title}}, {{event.link}} placeholders. Used for reminders, thank-yous, promos, and multi-step automations.' },
+      { trigger: 'Bulk WhatsApp to event attendees, or an ad-hoc WhatsApp broadcast — sent immediately or on a schedule', channels: ['WhatsApp'], recipients: 'Selected attendees / users / ad-hoc phone numbers chosen by the sender', subject: '—', content: 'Free-form message written by the sender, same placeholder support as email broadcasts.' },
+    ]},
+  ];
+
+  function notifChannelBadges(channels) {
+    return channels.map(c => {
+      const isWa = /whatsapp/i.test(c);
+      return `<span style="display:inline-block;margin:1px 4px 2px 0;padding:1px 7px;border-radius:4px;font-size:.68rem;font-weight:700;white-space:nowrap;background:${isWa ? '#d1fae5' : '#dbeafe'};color:${isWa ? '#065f46' : '#1e40af'}">${c}</span>`;
+    }).join('');
+  }
+
+  function renderNotificationRow(n) {
+    return `<tr>
+      <td style="padding:8px 10px;font-size:.8rem;color:#374151;vertical-align:top">${n.trigger}</td>
+      <td style="padding:8px 10px;vertical-align:top">${notifChannelBadges(n.channels)}</td>
+      <td style="padding:8px 10px;font-size:.78rem;color:#374151;vertical-align:top">${n.recipients}</td>
+      <td style="padding:8px 10px;font-size:.78rem;font-family:monospace;color:#111827;vertical-align:top">${n.subject}</td>
+      <td style="padding:8px 10px;font-size:.76rem;color:#6b7280;vertical-align:top">${n.content}</td>
+    </tr>`;
+  }
+
+  function renderNotificationCategory(cat) {
+    const rows = cat.items.map(renderNotificationRow).join('');
+    return `
+      <h3 style="font-size:.88rem;font-weight:600;color:#111827;margin:16px 0 8px">${cat.category}</h3>
+      <div style="border:1px solid #e5e7eb;border-radius:10px;overflow:hidden;margin-bottom:4px">
+        <table style="width:100%;border-collapse:collapse">
+          <thead><tr style="background:#f9fafb;border-bottom:1px solid #e5e7eb">
+            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:26%">Trigger — when it's sent</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:11%">Channel</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:19%">Recipients</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:17%">Subject</th>
+            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Content</th>
+          </tr></thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </div>`;
+  }
+
+  const notificationsHtml = NOTIFICATIONS.map(renderNotificationCategory).join('');
+  const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${orgName} Events — API Docs</title>
+  <style>
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f3f4f6;color:#1f2937;min-height:100vh;padding:24px 16px}
+    .wrap{max-width:1100px;margin:0 auto}
+    .method{display:inline-block;padding:1px 7px;border-radius:4px;font-size:.7rem;font-weight:700;font-family:monospace}
+    .get{background:#dbeafe;color:#1e40af}
+    .post{background:#d1fae5;color:#065f46}
+    .put{background:#fef3c7;color:#92400e}
+    .patch{background:#ede9fe;color:#5b21b6}
+    .del{background:#fee2e2;color:#991b1b}
+    .auth-badge{font-size:.68rem;padding:1px 6px;border-radius:4px;background:#f3f4f6;color:#374151;font-family:monospace}
+    code{background:#f3f4f6;padding:1px 5px;border-radius:4px;font-family:monospace;font-size:.82rem}
+    tr.ep-open{background:#f0f9ff}
+    tbody tr:hover{background:#f8fafc}
+    tbody tr[onclick]:hover{background:#f0f9ff}
+    td{border-bottom:1px solid #f3f4f6}
+    a{color:#2563eb;text-decoration:none}
+    a:hover{text-decoration:underline}
+  </style>
+</head>
+<body>
+<div class="wrap">
+  <div style="display:flex;align-items:baseline;justify-content:space-between;flex-wrap:wrap;gap:8px;margin-bottom:6px">
+    <h1 style="font-size:1.4rem;font-weight:700;color:#111827">${orgName} Events — API Reference</h1>
+    <a href="/" style="font-size:.82rem;color:#6b7280">&#8592; Status page</a>
+  </div>
+  <p style="font-size:.82rem;color:#6b7280;margin-bottom:20px">
+    Logged in as <strong>${user.name || user.email}</strong> (${user.role}) &mdash;
+    Click any row to expand request &amp; response examples.
+  </p>
+
+  <div style="background:#eff6ff;border:1px solid #bfdbfe;border-radius:8px;padding:10px 14px;font-size:.8rem;color:#1e40af;margin-bottom:20px">
+    Protected routes require <code>Authorization: Bearer &lt;jwt&gt;</code> &nbsp;|&nbsp;
+    Roles: <code>admin</code> &gt; <code>supervisor</code> &gt; <code>staff</code> &gt; <code>user</code> &nbsp;|&nbsp;
+    Base URL: <code>${process.env.APP_BASE_URL || 'http://localhost:' + PORT}</code>
+  </div>
+
+  ${groupsHtml}
+
+  <h1 style="font-size:1.2rem;font-weight:700;color:#111827;margin:36px 0 4px">Notifications sent by the system</h1>
+  <p style="font-size:.8rem;color:#6b7280;margin-bottom:16px">
+    Every automatic email and WhatsApp message the platform sends, what triggers it, who receives it, and what it contains.
+    Admin-facing registration/payment/daily-summary notices go to the <code>reg_notification_emails</code> setting plus each
+    event's configured notify recipients (Admin &rarr; Events &rarr; edit event &rarr; Notifications step) &mdash;
+    falling back to that event's creator when no recipients have been chosen.
+  </p>
+
+  ${notificationsHtml}
+
+  <p style="font-size:.72rem;color:#9ca3af;margin-top:28px;text-align:center">
+    ${orgName} Events API v${API_VERSION} &mdash; ${new Date().toISOString()}
+  </p>
+</div>
+<script>
+function toggle(id) {
+  const detail = document.getElementById(id + '-detail');
+  const chevron = document.getElementById(id + '-chevron');
+  if (!detail) return;
+  const open = detail.style.display !== 'none';
+  detail.style.display = open ? 'none' : 'table-row';
+  if (chevron) chevron.style.transform = open ? 'rotate(0deg)' : 'rotate(90deg)';
+  // highlight parent row
+  const rows = detail.parentElement.querySelectorAll('tr[onclick]');
+  rows.forEach(r => {
+    if (r.getAttribute('onclick') === "toggle('" + id + "')") {
+      r.classList.toggle('ep-open', !open);
+    }
+  });
+}
+</script>
+</body>
+</html>`;
+
+  res.send(html);
+});
+
+// Error middleware
+app.use(notFound);
+
+// Sentry captures the error here, then passes it through unchanged — errorHandler
+// below remains the sole source of what's actually sent back to the client.
+if (process.env.SENTRY_DSN) {
+  const Sentry = require('@sentry/node');
+  Sentry.setupExpressErrorHandler(app);
+}
+
+app.use(errorHandler);
+
+// Start server
+app.listen(PORT, () => {
+  console.log(`Server is running at http://localhost:${PORT}`);
+  // Attempt a one-time background sync of attachment manifests into DB
+  try {
+    const { syncManifestsToDb } = require('./utils/attachmentsSync');
+    const prismaShared = require('./config/db');
+    setTimeout(async () => {
+      try {
+        const summary = await syncManifestsToDb(prismaShared, { dryRun: false });
+        if ((summary.imported || 0) > 0) {
+          console.log(`[attachments sync] Imported ${summary.imported} attachments from manifests (skipped ${summary.skipped}).`);
+        } else {
+          console.log('[attachments sync] No attachments imported (either none found or already in DB).');
+        }
+      } catch (e) {
+        console.warn('[attachments sync] Failed:', e?.message || e);
+      }
+    }, 1000);
+  } catch (e) {
+    console.warn('[attachments sync] Not scheduled:', e?.message || e);
+  }
+
+  // Timed background jobs (daily summary, waitlist, feedback, sessions, consent, analytics,
+  // backup, temp cleanup) run on the pg-boss job queue — see src/jobs/index.js.
+  require('./jobs').startJobs().catch(e => console.warn('[jobs] Not started:', e?.message || e));
+
+  // Check in with the Hub 30 s after starting, so the licence is fresh without waiting 15 minutes.
+  require('./hub/client').heartbeatSoon();
+
+  // Scheduled emails worker (polling)
+  try {
+    const enabled = String(process.env.SCHEDULED_EMAILS_ENABLED || 'true').toLowerCase() !== 'false';
+    if (enabled) {
+      const { getDueJobs, updateJob, purgeSentJobs } = require('./utils/scheduledEmails');
+      const { emailEventAttendees, whatsappEventAttendees } = require('./controllers/eventController');
+      const { sendBroadcast } = require('./controllers/broadcastController');
+      const { sendWhatsAppBroadcast } = require('./controllers/whatsappBroadcastController');
+      const intervalMs = parseInt(process.env.SCHEDULED_EMAILS_INTERVAL_MS || '30000', 10);
+      setInterval(async () => {
+        try {
+          try { purgeSentJobs(24 * 60 * 60 * 1000); } catch (e) { console.warn('[scheduled emails] purge failed:', e?.message || e); }
+          const due = getDueJobs(new Date());
+          if (!due || due.length === 0) return;
+          for (const job of due) {
+            try {
+              updateJob(job.id, { status: 'sending', attempts: (job.attempts || 0) + 1, lastError: null });
+              let responseBody = null; let code = 200;
+              const mockRes = {
+                status: (c) => { code = c; return mockRes; },
+                json: (b) => { responseBody = b; return mockRes; }
+              };
+              if (job.broadcast && job.channel === 'whatsapp') {
+                const mockReq = { body: job.payload };
+                await sendWhatsAppBroadcast(mockReq, mockRes);
+              } else if (job.broadcast) {
+                const mockReq = { body: job.payload };
+                await sendBroadcast(mockReq, mockRes);
+              } else if (job.channel === 'whatsapp') {
+                const mockReq = { params: { id: job.eventId }, body: job.payload };
+                await whatsappEventAttendees(mockReq, mockRes);
+              } else {
+                const mockReq = { params: { id: job.eventId }, body: job.payload };
+                await emailEventAttendees(mockReq, mockRes);
+              }
+              if (code >= 200 && code < 300) {
+                updateJob(job.id, { status: 'sent', sentAt: new Date().toISOString(), lastResult: responseBody || null });
+              } else {
+                updateJob(job.id, { status: 'error', lastError: (responseBody && responseBody.message) ? responseBody.message : `HTTP ${code}` });
+              }
+            } catch (e) {
+              updateJob(job.id, { status: 'error', lastError: String(e?.message || e) });
+            }
+          }
+        } catch (e) {
+          console.warn('[scheduled emails] poll failed:', e?.message || e);
+        }
+      }, isNaN(intervalMs) ? 30000 : intervalMs);
+      console.log('[scheduled emails] Worker initialized. Set SCHEDULED_EMAILS_ENABLED=false to disable.');
+    } else {
+      console.log('[scheduled emails] Worker disabled by env SCHEDULED_EMAILS_ENABLED=false');
+    }
+  } catch (e) {
+    console.warn('[scheduled emails] Worker not started:', e?.message || e);
+  }
+});
+
+// Log unhandled promise rejections without killing the server, since a single
+// missed .catch() on fire-and-forget notification code (email/WhatsApp sends)
+// would otherwise take the whole app down.
+// On restart/stop (PM2 sends SIGINT), let a running background job finish first.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.once(signal, async () => {
+    try { await require('./jobs').stopJobs(); } catch { /* exiting anyway */ }
+    process.exit(0);
+  });
+}
+
+process.on('unhandledRejection', (err) => {
+  console.error('UNHANDLED REJECTION!', err?.name, err?.message);
+  console.error(err?.stack || err);
+  if (process.env.SENTRY_DSN) {
+    try { require('@sentry/node').captureException(err); } catch {}
+  }
+});
+
+module.exports = { app, prisma };
\ No newline at end of file
diff --git a/backend/src/index.js b/backend/src/index.js
index 01203a6..1ca4ee2 100644
--- a/backend/src/index.js
+++ b/backend/src/index.js
@@ -1,1808 +1,34 @@
+// Starts the backend (the server itself is app.js).
+//
+// Since 1.51.0 part of the backend is TypeScript. Production runs the compiled build in dist/
+// (`npm run build`, done by scripts/deploy.sh), but every install's PM2 config points here, at
+// src/index.js — so with plain Node this hands over to dist/ when its build matches this
+// version, and otherwise compiles the TypeScript on the fly with tsx (e.g. right after an
+// update made by an older deploy script, which didn't build). Under tsx or Jest, which load
+// .ts files themselves, and when this file is the one in dist/, it just loads app.js.
+const fs = require('fs');
 const path = require('path');
-const dotenv = require('dotenv');
 
-// Load environment variables
-dotenv.config();
-
-// Error monitoring — a no-op if SENTRY_DSN isn't set, so this is safe in every
-// environment (dev, a fresh deploy that hasn't configured Sentry yet, etc.).
-// Must run before express/@prisma/client are required below — Sentry's
-// auto-instrumentation patches those modules via a require hook, which only
-// works if Sentry.init() runs before they're first required into the cache.
-if (process.env.SENTRY_DSN) {
-  const Sentry = require('@sentry/node');
-  Sentry.init({
-    dsn: process.env.SENTRY_DSN,
-    environment: process.env.NODE_ENV || 'development',
-    // Small single-VM deployment, not high-traffic — start conservative and raise
-    // this once real usage is visible in Sentry, rather than sampling every request.
-    tracesSampleRate: 0.1,
-  });
-}
-
-const express = require('express');
-const { version: API_VERSION } = require('../package.json');
-const cors = require('cors');
-const rateLimit = require('express-rate-limit');
-const prisma = require('./config/db');
-const { notFound, errorHandler } = require('./middleware/errorMiddleware');
-const getRawBody = require('raw-body');
-
-// Initialize Express app
-const app = express();
-const PORT = process.env.PORT || 3000;
-
-// Trust proxy — required when running behind a reverse proxy (e.g. nginx on a
-// separate server) so req.ip / X-Forwarded-For are read correctly by
-// express-rate-limit and friends. Accepts a hop count ("1"), "true"/"false",
-// or a comma-separated list of trusted proxy IPs/CIDRs.
-if (process.env.TRUST_PROXY) {
-  const raw = process.env.TRUST_PROXY.trim();
-  let trustProxyValue;
-  if (raw === 'true') trustProxyValue = true;
-  else if (raw === 'false') trustProxyValue = false;
-  else if (/^\d+$/.test(raw)) trustProxyValue = parseInt(raw, 10);
-  else if (raw.includes(',')) trustProxyValue = raw.split(',').map((s) => s.trim());
-  else trustProxyValue = raw;
-  app.set('trust proxy', trustProxyValue);
-  console.log(`[startup] trust proxy set to: ${JSON.stringify(trustProxyValue)}`);
-}
-
-// CORS — allow only the configured frontend origin
-const allowedOrigins = (process.env.FRONTEND_URL || 'http://localhost:3000')
-  .split(',')
-  .map((o) => o.trim());
-
-const isDev = process.env.NODE_ENV === 'development' || !process.env.NODE_ENV;
-const isTesting = process.env.NODE_ENV === 'testing';
-const isProd = process.env.NODE_ENV === 'production';
-const modeLabel = isProd ? 'production' : isTesting ? 'testing' : 'development';
-console.log(`Running in ${modeLabel} mode.`);
-
-// In testing or production, require all critical env vars to be set at startup
-if (isTesting || isProd) {
-  const required = ['DATABASE_URL', 'JWT_SECRET'];
-  const missing = required.filter(k => !process.env[k]);
-  if (missing.length > 0) {
-    console.error(`[startup] Missing required environment variables for ${modeLabel} mode: ${missing.join(', ')}`);
-    process.exit(1);
+function builtApp() {
+  const dist = path.join(__dirname, '..', 'dist');
+  try {
+    const built = JSON.parse(fs.readFileSync(path.join(dist, 'build.json'), 'utf8'));
+    if (built.version === require('../package.json').version) return path.join(dist, 'app.js');
+  } catch {
+    // no build yet
   }
+  return null;
 }
 
-app.use(cors({
-  origin: (origin, callback) => {
-    // Allow requests with no origin (e.g. mobile apps, curl, Postman)
-    if (!origin) return callback(null, true);
-    // Always allow configured origins
-    if (allowedOrigins.includes(origin)) return callback(null, true);
-    // In dev or testing, also allow any LAN origin on the same port (e.g. phone on 192.168.x.x:3000)
-    if (isDev || isTesting) {
-      try {
-        const u = new URL(origin);
-        const isLan = /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(u.hostname);
-        if (isLan) return callback(null, true);
-      } catch {}
-    }
-    callback(new Error(`CORS: origin '${origin}' not allowed`));
-  },
-  credentials: true,
-}));
-
-// Global rate limiter — 5000 requests per 5 minutes per IP
-// Webhooks are excluded because they come from Yoco's servers and are already HMAC-verified
-const globalLimiter = rateLimit({
-  windowMs: 5 * 60 * 1000,
-  max: 5000,
-  standardHeaders: true,
-  legacyHeaders: false,
-  message: { message: 'Too many requests, please try again later.' },
-  skip: (req) => req.path.startsWith('/api/webhooks'),
-});
-app.use(globalLimiter);
-
-// Impersonation is strictly read-only: refuse every write made with an impersonation
-// token before it can reach any route (see utils/impersonation.js).
-app.use(require('./utils/impersonation').readOnlyGuard);
-
-// Raw body parsing middleware for webhooks
-app.use((req, res, next) => {
-  if (req.path.startsWith('/api/webhooks')) {
-    getRawBody(req, {
-      length: req.headers['content-length'],
-      encoding: 'utf-8'
-    }, (err, rawBody) => {
-      if (err) return next(err);
-      req.rawBody = rawBody;
-      next();
-    });
+if (path.basename(__dirname) === 'src' && !require.extensions['.ts']) {
+  const built = builtApp();
+  if (built) {
+    module.exports = require(built);
   } else {
-    next();
+    console.warn('[startup] No build for this version in dist/ — compiling TypeScript as it loads (run `npm run build`).');
+    require('tsx/cjs');
+    module.exports = require('./app');
   }
-});
-
-
-// Import routes
-const userRoutes = require('./routes/userRoutes');
-const eventRoutes = require('./routes/eventRoutes');
-const registrationRoutes = require('./routes/registrationRoutes');
-const paymentRoutes = require('./routes/paymentRoutes');
-const ticketRoutes = require('./routes/ticketRoutes');
-const webhookRoutes = require('./routes/webhookRoutes');
-const uploadRoutes = require('./routes/uploadRoutes');
-const reportRoutes = require('./routes/reportRoutes');
-const formRoutes = require('./routes/formRoutes');
-const providerTransactionRoutes = require('./routes/providerTransactionRoutes');
-const automationRoutes = require('./routes/automationRoutes');
-const broadcastRoutes = require('./routes/broadcastRoutes');
-const whatsappBroadcastRoutes = require('./routes/whatsappBroadcastRoutes');
-const scheduledEmailRoutes = require('./routes/scheduledEmailRoutes');
-const sectionRoutes = require('./routes/sectionRoutes');
-const bannerRoutes    = require('./routes/bannerRoutes');
-const whatsappRoutes  = require('./routes/whatsappRoutes');
-const settingsRoutes  = require('./routes/settingsRoutes');
-const setupRoutes     = require('./routes/setupRoutes');
-const costRoutes      = require('./routes/costRoutes');
-const cashupRoutes    = require('./routes/cashupRoutes');
-const statsRoutes     = require('./routes/statsRoutes');
-const adminRoutes     = require('./routes/adminRoutes');
-const backupRoutes    = require('./routes/backupRoutes');
-const yocoRoutes      = require('./routes/yocoRoutes');
-const payfastRoutes   = require('./routes/payfastRoutes');
-const privacyRoutes   = require('./routes/privacyRoutes');
-
-// Mount webhook routes BEFORE JSON body parser to avoid double-reading the stream
-app.use('/api/webhooks', webhookRoutes);
-
-// Apply JSON body parser for all non-webhook routes
-app.use(express.json());
-
-// Count server errors (any 5xx response) for the Hub heartbeat.
-app.use((req, res, next) => {
-  res.on('finish', () => { if (res.statusCode >= 500) require('./utils/errorCounter').recordError(); });
-  next();
-});
-
-// Licence suspended, revoked or missing: no new or edited events, registrations or payments (src/hub/readOnly.js).
-app.use(require('./hub/readOnly').licenceReadOnly);
-
-// Health for monitoring (and the Hub): no secrets, no personal information.
-app.get('/health', async (req, res) => {
-  const report = require('./hub/report');
-  let db = true;
-  try { await prisma.$queryRaw`SELECT 1`; } catch { db = false; }
-  const health = db ? await report.health().catch(() => null) : null;
-  res.status(db ? 200 : 503).json({
-    status: db ? 'ok' : 'error',
-    version: report.APP_VERSION,
-    db,
-    jobs: health?.jobs || null,
-    lastBackupAt: health?.lastBackupAt || null,
-  });
-});
-
-// Use routes
-app.use('/api/hub', require('./routes/hubRoutes'));
-app.use('/api/campuses', require('./routes/campusRoutes'));
-app.use('/api/kids', require('./routes/kidsRoutes'));
-app.use('/api/volunteers', require('./routes/volunteerRoutes'));
-app.use('/api/series', require('./routes/seriesRoutes'));
-app.use('/api/season-passes', require('./routes/seasonPassRoutes'));
-app.use('/api/outbound-webhooks', require('./routes/outboundWebhookRoutes'));
-app.use('/api/dashboard', require('./routes/dashboardRoutes'));
-app.use('/api/saved-filters', require('./routes/savedFilterRoutes'));
-app.use('/api/users', userRoutes);
-app.use('/api/events', eventRoutes);
-app.use('/api/registrations', registrationRoutes);
-app.use('/api/payments', paymentRoutes);
-app.use('/api/tickets', ticketRoutes);
-app.use('/api/uploads', uploadRoutes);
-app.use('/api/reports', reportRoutes);
-app.use('/api/forms', formRoutes);
-app.use('/api/provider-transactions', providerTransactionRoutes);
-app.use('/api/yoco-transactions', providerTransactionRoutes); // older name
-app.use('/api/automations', automationRoutes);
-app.use('/api/broadcasts', broadcastRoutes);
-app.use('/api/whatsapp-broadcasts', whatsappBroadcastRoutes);
-app.use('/api/scheduled-emails', scheduledEmailRoutes);
-app.use('/api/sections', sectionRoutes);
-app.use('/api/banner',    bannerRoutes);
-app.use('/api/whatsapp', whatsappRoutes);
-app.use('/api/privacy',  privacyRoutes);
-app.use('/api/settings', settingsRoutes);
-app.use('/api/setup',    setupRoutes);
-app.use('/api/stats',    statsRoutes);
-app.use('/api', costRoutes);
-app.use('/api/cashups', cashupRoutes);
-app.use('/api/admin', adminRoutes);
-app.use('/api/coupons', require('./routes/couponRoutes'));
-app.use('/api/bundles', require('./routes/bundleRoutes'));
-app.use('/api/consent', require('./routes/consentRoutes'));
-app.use('/api/waitlist', require('./routes/waitlistRoutes'));
-app.use('/api/scan-locks', require('./routes/scanLockRoutes'));
-app.use('/api/allocations', require('./routes/allocationRoutes'));
-app.use('/api/sponsorships', require('./routes/sponsorshipRoutes'));
-app.use('/api/feedback', require('./routes/feedbackRoutes'));
-app.use('/api/attendance', require('./routes/attendanceRoutes'));
-app.use('/api/analytics', require('./routes/analyticsRoutes'));
-app.use('/api/backups', backupRoutes);
-app.use('/api/yoco', yocoRoutes);
-app.use('/api/payfast', payfastRoutes);
-
-// Pre-warm the settings cache so synchronous helpers have DB values from startup
-const { getSettingSync, warmCache } = require('./utils/settingsCache');
-warmCache().catch(() => {});
-// Uploaded branding assets can include SVGs, which may embed <script>/event
-// handlers. Serving them inline lets a compromised/malicious upload run script
-// in the site's origin if opened directly, so pin the safe response headers
-// (no inline execution, no MIME-sniffing to HTML/script) on every asset here.
-app.use('/uploads', express.static('public/uploads', {
-  setHeaders: (res) => {
-    res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox");
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-  },
-}));
-
-// ── Shared page helpers ────────────────────────────────────────────────────────
-const jwt = require('jsonwebtoken');
-
-function pageShell(title, accentColor, bodyHtml) {
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
-  <style>
-    *{box-sizing:border-box;margin:0;padding:0}
-    body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f3f4f6;color:#1f2937;min-height:100vh;padding:24px 16px}
-    .wrap{max-width:960px;margin:0 auto}
-    h1{font-size:1.5rem;font-weight:700;color:#111827;margin-bottom:4px}
-    h2{font-size:1.1rem;font-weight:600;color:#111827;margin:24px 0 10px}
-    .subtitle{font-size:.85rem;color:#6b7280;margin-bottom:24px}
-    .card{background:#fff;border:1px solid #e5e7eb;border-radius:10px;padding:20px;margin-bottom:16px}
-    .stat-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:12px;margin-bottom:16px}
-    .stat{background:#fff;border:1px solid #e5e7eb;border-radius:8px;padding:14px 16px}
-    .stat-label{font-size:.72rem;text-transform:uppercase;letter-spacing:.05em;color:#6b7280;margin-bottom:4px}
-    .stat-value{font-size:1.1rem;font-weight:600;color:#111827}
-    .badge{display:inline-block;padding:2px 8px;border-radius:999px;font-size:.75rem;font-weight:600}
-    .badge-ok{background:#d1fae5;color:#065f46}
-    .badge-warn{background:#fef3c7;color:#92400e}
-    .badge-err{background:#fee2e2;color:#991b1b}
-    table{width:100%;border-collapse:collapse;font-size:.82rem}
-    th{text-align:left;padding:6px 10px;background:#f9fafb;border-bottom:1px solid #e5e7eb;font-weight:600;color:#374151}
-    td{padding:6px 10px;border-bottom:1px solid #f3f4f6;color:#374151;vertical-align:top}
-    tr:last-child td{border-bottom:none}
-    .method{display:inline-block;padding:1px 7px;border-radius:4px;font-size:.7rem;font-weight:700;font-family:monospace}
-    .get{background:#dbeafe;color:#1e40af}
-    .post{background:#d1fae5;color:#065f46}
-    .put{background:#fef3c7;color:#92400e}
-    .patch{background:#ede9fe;color:#5b21b6}
-    .del{background:#fee2e2;color:#991b1b}
-    .auth-badge{font-size:.68rem;padding:1px 6px;border-radius:4px;background:#f3f4f6;color:#374151;font-family:monospace}
-    code{background:#f3f4f6;padding:1px 5px;border-radius:4px;font-family:monospace;font-size:.82rem}
-    .note{background:#eff6ff;border:1px solid #bfdbfe;border-radius:8px;padding:12px 16px;font-size:.82rem;color:#1e40af;margin-bottom:16px}
-    .accent{color:${accentColor}}
-    a{color:${accentColor};text-decoration:none}
-    a:hover{text-decoration:underline}
-  </style>
-</head>
-<body>
-<div class="wrap">
-${bodyHtml}
-</div>
-</body>
-</html>`;
+} else {
+  module.exports = require('./app');
 }
-
-function formatUptime(seconds) {
-  const d = Math.floor(seconds / 86400);
-  const h = Math.floor((seconds % 86400) / 3600);
-  const m = Math.floor((seconds % 3600) / 60);
-  const s = Math.floor(seconds % 60);
-  if (d > 0) return `${d}d ${h}h ${m}m`;
-  if (h > 0) return `${h}h ${m}m ${s}s`;
-  if (m > 0) return `${m}m ${s}s`;
-  return `${s}s`;
-}
-
-function formatBytes(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / 1048576).toFixed(1)} MB`;
-}
-
-// ── Favicon ──────────────────────────────────────────────────────────────────
-app.get('/favicon.ico', (req, res) => {
-  res.sendFile(path.join(__dirname, 'favicon.ico'));
-});
-
-// ── Root route — status page ────────────────────────────────────────────────
-app.get('/', async (req, res) => {
-  const mem = process.memoryUsage();
-  const uptimeSec = process.uptime();
-  const now = new Date().toISOString();
-
-  // Database health check
-  let dbStatus = 'ok';
-  let dbMsg = 'Connected';
-  try {
-    await prisma.$queryRaw`SELECT 1`;
-  } catch (e) {
-    dbStatus = 'error';
-    dbMsg = 'Unreachable';
-  }
-
-  const dbBadge = dbStatus === 'ok'
-    ? `<span class="badge badge-ok">&#10003; ${dbMsg}</span>`
-    : `<span class="badge badge-err">&#10007; ${dbMsg}</span>`;
-
-  const envBadge = isProd
-    ? `<span class="badge badge-ok">production</span>`
-    : isTesting
-      ? `<span class="badge badge-warn">testing</span>`
-      : `<span class="badge badge-warn">development</span>`;
-
-  const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
-  const html = pageShell(`${orgName} Events API — Status`, '#2563eb', `
-    <h1>${orgName} Events API</h1>
-    <p class="subtitle">v${API_VERSION} &mdash; ${now}</p>
-
-    <div class="stat-grid">
-      <div class="stat">
-        <div class="stat-label">Status</div>
-        <div class="stat-value"><span class="badge badge-ok">&#10003; Online</span></div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Environment</div>
-        <div class="stat-value">${envBadge}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Database</div>
-        <div class="stat-value">${dbBadge}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Uptime</div>
-        <div class="stat-value">${formatUptime(uptimeSec)}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Heap Used</div>
-        <div class="stat-value">${formatBytes(mem.heapUsed)}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Heap Total</div>
-        <div class="stat-value">${formatBytes(mem.heapTotal)}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">RSS</div>
-        <div class="stat-value">${formatBytes(mem.rss)}</div>
-      </div>
-      <div class="stat">
-        <div class="stat-label">Node</div>
-        <div class="stat-value">${process.version}</div>
-      </div>
-    </div>
-
-    <div class="note">
-      API documentation is available at <a href="/docs">/docs</a> — requires an admin account token.
-    </div>
-  `);
-
-  res.send(html);
-});
-
-// ── /docs route — interactive API reference, admin only ─────────────────────
-app.get('/docs', async (req, res) => {
-  const tokenFromQuery = req.query.token;
-  const tokenFromHeader = req.headers.authorization?.startsWith('Bearer ')
-    ? req.headers.authorization.split(' ')[1] : null;
-  const token = tokenFromQuery || tokenFromHeader;
-
-  if (!token) {
-    return res.status(401).send(pageShell('API Docs — Login Required', '#2563eb', `
-      <h1>API Documentation</h1>
-      <p class="subtitle">Admin access required</p>
-      <div class="card">
-        <p style="margin-bottom:12px;font-size:.9rem;">Pass your admin JWT to view the docs:</p>
-        <code style="display:block;padding:10px;background:#f3f4f6;border-radius:6px;font-size:.8rem;word-break:break-all;">/docs?token=&lt;your-admin-jwt&gt;</code>
-        <p style="margin-top:12px;font-size:.8rem;color:#6b7280;">Copy your token from the browser's localStorage key <code>token</code> after logging in as admin.</p>
-      </div>`));
-  }
-
-  let user;
-  try {
-    const decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
-    user = await prisma.user.findUnique({
-      where: { id: decoded.id },
-      select: { id: true, name: true, email: true, role: true, isActive: true, tokenVersion: true },
-    });
-    if (!user || !user.isActive) throw new Error('User not found or inactive');
-    if ((decoded.tokenVersion ?? 0) !== user.tokenVersion) throw new Error('Token revoked');
-    if (user.role !== 'admin') throw new Error('Admin role required');
-  } catch (e) {
-    return res.status(403).send(pageShell('API Docs — Access Denied', '#dc2626', `
-      <h1>Access Denied</h1>
-      <p class="subtitle">Admin role required</p>
-      <div class="card">
-        <p style="font-size:.9rem;color:#dc2626;">${e.message}</p>
-        <p style="margin-top:10px;font-size:.82rem;color:#6b7280;">Make sure you are logged in as an admin and using a valid, non-expired token.</p>
-      </div>`));
-  }
-
-  // ── Endpoint data ────────────────────────────────────────────────────────
-  const GROUPS = [
-    { title: 'Users', base: '/api/users', endpoints: [
-      { method:'GET', path:'/api/users/activity', auth:'Bearer', desc:'Recent account activity (logins, password changes) for the current user' },
-      { method:'POST', path:'/api/users', auth:'public', desc:'Register a new account',
-        request:{ body:{ name:'Jane Doe', email:'jane@example.com', password:'secret123', phoneNumber:'+27821234567' }},
-        responses:[
-          { status:201, desc:'Created', body:{ id:'a1b2c3d4-0000-0000-0000-000000000001', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...' }},
-          { status:400, desc:'Validation error', body:{ message:'Email already in use' }},
-        ]},
-      { method:'POST', path:'/api/users/login', auth:'public', desc:'Login — returns a signed JWT',
-        notes:'Rate-limited to 15 requests/min per IP.',
-        request:{ body:{ email:'jane@example.com', password:'secret123' }},
-        responses:[
-          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...' }},
-          { status:200, desc:'Two-factor code sent (account has 2FA on) — no token yet', body:{ twoFactorRequired:true, challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
-          { status:200, desc:'Admin/supervisor without 2FA — code sent; verifying it turns 2FA on', body:{ twoFactorRequired:true, enrolling:true, challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
-          { status:401, desc:'Wrong credentials', body:{ message:'Invalid email or password' }},
-        ]},
-      { method:'POST', path:'/api/users/login/2fa', auth:'public', desc:'Second login step — exchange the emailed/WhatsApp code for a JWT',
-        notes:'Codes expire after 10 minutes and allow 5 attempts. With rememberDevice, the response includes a deviceToken; send it with later logins to skip the code for 30 days.',
-        request:{ body:{ challengeId:'c0ffee00-...', code:'123456', rememberDevice:true }},
-        responses:[
-          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', token:'eyJhbGciOiJIUzI1NiJ9...', deviceToken:'9f2c...' }},
-          { status:400, desc:'Wrong or expired code', body:{ message:'Incorrect code. 4 attempts left.' }},
-        ]},
-      { method:'POST', path:'/api/users/login/2fa/resend', auth:'public', desc:'Send a new code for a pending login challenge',
-        notes:'At most one send per 60 seconds.',
-        request:{ body:{ challengeId:'c0ffee00-...' }},
-        responses:[
-          { status:200, desc:'Sent', body:{ challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
-          { status:429, desc:'Too soon', body:{ message:'Please wait 42 seconds before requesting another code.' }},
-        ]},
-      { method:'POST', path:'/api/users/forgot', auth:'public', desc:'Request a password reset email',
-        request:{ body:{ email:'jane@example.com' }},
-        responses:[
-          { status:200, desc:'Always succeeds (no user enumeration)', body:{ message:'If that email exists, a reset link has been sent.' }},
-        ]},
-      { method:'POST', path:'/api/users/reset', auth:'public', desc:'Reset password using token from email',
-        request:{ body:{ token:'reset-token-from-email', password:'newPassword123' }},
-        responses:[
-          { status:200, desc:'Success', body:{ message:'Password reset successful.' }},
-          { status:400, desc:'Invalid or expired token', body:{ message:'Reset token is invalid or has expired.' }},
-        ]},
-      { method:'POST', path:'/api/users/activate', auth:'public', desc:'Activate a new account via email link',
-        request:{ body:{ token:'activation-token-from-email' }},
-        responses:[
-          { status:200, desc:'Success', body:{ message:'Account activated.' }},
-          { status:400, desc:'Invalid token', body:{ message:'Invalid or expired activation token.' }},
-        ]},
-      { method:'GET', path:'/api/users/profile', auth:'user+', desc:'Get own profile',
-        responses:[
-          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', phoneNumber:'+27821234567', notificationPreference:'email', createdAt:'2024-01-15T08:00:00.000Z' }},
-          { status:401, desc:'Unauthorized', body:{ message:'Not authorized, no token' }},
-        ]},
-      { method:'PUT', path:'/api/users/profile', auth:'user+', desc:'Update own profile',
-        request:{ body:{ name:'Jane Smith', phoneNumber:'+27821234567', notificationPreference:'both' }},
-        responses:[
-          { status:200, desc:'Updated', body:{ id:'a1b2c3d4-...', name:'Jane Smith', email:'jane@example.com', notificationPreference:'both' }},
-        ]},
-      { method:'POST', path:'/api/users/revoke-sessions', auth:'user+', desc:'Invalidate all own sessions by incrementing tokenVersion',
-        responses:[{ status:200, desc:'Success', body:{ message:'All sessions revoked.' }}]},
-      { method:'POST', path:'/api/users/close-account', auth:'user+', desc:'Deactivate own account',
-        responses:[{ status:200, desc:'Success', body:{ message:'Account deactivated.' }}]},
-      { method:'POST', path:'/api/users/2fa/enable', auth:'user+', desc:'Start turning on two-factor authentication — sends a code to the chosen channel',
-        notes:'WhatsApp needs a valid phone number on the account and a connected WhatsApp session.',
-        request:{ body:{ method:'email', password:'secret123' }},
-        responses:[
-          { status:200, desc:'Code sent', body:{ challengeId:'c0ffee00-...', method:'email', destination:'j•••@example.com' }},
-          { status:400, desc:'Wrong password or unavailable channel', body:{ message:'Incorrect password' }},
-        ]},
-      { method:'POST', path:'/api/users/2fa/confirm', auth:'user+', desc:'Finish turning on two-factor authentication with the code that was sent',
-        request:{ body:{ challengeId:'c0ffee00-...', code:'123456' }},
-        responses:[{ status:200, desc:'Enabled', body:{ twoFactorEnabled:true, twoFactorMethod:'email' }}]},
-      { method:'POST', path:'/api/users/2fa/disable', auth:'user+', desc:'Turn off two-factor authentication',
-        request:{ body:{ password:'secret123' }},
-        notes:'Admins and supervisors must keep two-factor on — 403 for them.',
-        responses:[
-          { status:200, desc:'Disabled', body:{ twoFactorEnabled:false, twoFactorMethod:null }},
-          { status:403, desc:'Required for this role', body:{ message:"Two-factor authentication is required for your role and can't be turned off." }},
-        ]},
-      { method:'POST', path:'/api/users/verify-password', auth:'user+', desc:'Re-confirm own password without starting a new session',
-        request:{ body:{ password:'secret123' }},
-        responses:[
-          { status:200, desc:'Correct', body:{ ok:true }},
-          { status:401, desc:'Wrong password', body:{ message:'Incorrect password' }},
-        ]},
-      { method:'GET', path:'/api/users', auth:'supervisor+', desc:'List all users (paginated). All filters are applied server-side.',
-        queryParams:{ page:'Page number (default 1)', limit:'Items per page (max 200, default 100)', search:'Search by name, email, or phone number (case-insensitive substring)', role:'Filter by role: admin|supervisor|staff|user', isActive:'Filter by active status: true|false (omit for both)' },
-        responses:[
-          { status:200, desc:'Success', body:{ data:[{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, createdAt:'2024-01-15T08:00:00.000Z' }], total:1, page:1, limit:20 }},
-        ]},
-      { method:'GET', path:'/api/users/check-exists', auth:'supervisor+', desc:'Check whether an account already exists for a given email and/or phone number (used by the self-service kiosk and manual registration screens to avoid duplicate accounts)',
-        queryParams:{ email:'Email to look up (optional)', phone:'Phone number to look up (optional; SA formats normalized)' },
-        responses:[
-          { status:200, desc:'Success', body:{ exists:true, hasEmail:true, hasPhone:false }},
-        ]},
-      { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID (with scopedCampuses)',
-        pathParams:{ ':id':'User UUID' },
-        responses:[
-          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, phoneNumber:'+27821234567', notificationPreference:'email' }},
-          { status:404, desc:'Not found', body:{ message:'User not found' }},
-        ]},
-      { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role). scopedCampusIds limits a supervisor/staff member to those campuses (empty = every campus; audited)',
-        pathParams:{ ':id':'User UUID' },
-        request:{ body:{ role:'supervisor', isActive:true, name:'Jane Doe' }},
-        responses:[
-          { status:200, desc:'Updated', body:{ id:'a1b2c3d4-...', name:'Jane Doe', role:'supervisor' }},
-        ]},
-      { method:'DELETE', path:'/api/users/:id', auth:'admin', desc:'Deactivate a user account (sets isActive: false; does not erase data)',
-        pathParams:{ ':id':'User UUID' },
-        responses:[
-          { status:200, desc:'Deactivated', body:{ message:'User deactivated' }},
-          { status:404, desc:'Not found', body:{ message:'User not found' }},
-        ]},
-      { method:'POST', path:'/api/users/:id/revoke-sessions', auth:'admin', desc:'Revoke all sessions for another user',
-        pathParams:{ ':id':'User UUID' },
-        responses:[{ status:200, desc:'Success', body:{ message:'Sessions revoked for user.' }}]},
-      { method:'POST', path:'/api/users/:id/anonymize', auth:'admin', desc:'Erase personal data for a user (POPIA) — the account, the people they registered, form answers, consent details, sponsor names, login history and payer details in provider payloads; payments, registrations and tickets stay as "Deleted User". Refused (409) while they have a registration for an upcoming event. Completes an open deletion request. Irreversible; audited as user_anonymised.',
-        pathParams:{ ':id':'User UUID' },
-        responses:[
-          { status:200, desc:'Anonymised', body:{ message:'User data deleted' }},
-          { status:404, desc:'Not found', body:{ message:'User not found' }},
-        ]},
-    ]},
-
-    { title: 'Events', base: '/api/events', endpoints: [
-      { method:'GET', path:'/api/events/admin/all', auth:'admin', desc:'All events, including inactive ones' },
-      { method:'GET', path:'/api/events/:id/ics', auth:'Public (optional login)', desc:'Download an .ics calendar file for an event' },
-      { method:'GET', path:'/api/events/:id/attachments', auth:'Public', desc:'List the downloadable attachments of an event' },
-      { method:'POST', path:'/api/events/:id/attachments', auth:'supervisor+', desc:'Upload an attachment (multipart, field "file")' },
-      { method:'DELETE', path:'/api/events/:eventId/attachments/:attachmentId', auth:'supervisor+', desc:'Delete an attachment' },
-      { method:'GET', path:'/api/events/attachments/status', auth:'admin', desc:'Diagnostics for the attachments pipeline' },
-      { method:'POST', path:'/api/events/attachments/sync', auth:'admin', desc:'Re-sync attachment records with the files on disk' },
-      { method:'POST', path:'/api/events/options/:id/variants', auth:'supervisor+', desc:'Add a variant (e.g. a size) to an event option' },
-      { method:'GET', path:'/api/events', auth:'public', desc:'List active, public, upcoming events. Each event includes isSoldOut:boolean — true when every option with a stockLimit > 0 is fully booked.',
-        queryParams:{ limit:'Max results (default 20)' },
-        responses:[
-          { status:200, desc:'Success', body:[{ id:'ev-uuid-...', title:'Camp 2025', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', price:450, picture:'/uploads/camp.jpg', isActive:true, isSoldOut:false }]},
-        ]},
-      { method:'GET', path:'/api/events/all', auth:'staff+', desc:'All events including hidden and past',
-        queryParams:{ includePast:'Include past events (true|false, default false)' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'ev-uuid-...', title:'Camp 2025', isHidden:false, isActive:true }]}]},
-      { method:'GET', path:'/api/events/:id', auth:'public', desc:'Get full event detail by ID. When called by staff/supervisor/admin, the response also includes createdBy and notifyRecipients (who the event\'s notifications go to).',
-        pathParams:{ ':id':'Event UUID' },
-        responses:[
-          { status:200, desc:'Success', body:{ id:'ev-uuid-...', title:'Camp 2025', description:'Annual family camp.', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', price:450, requiresAuth:true, eventOptions:[{ id:'opt-uuid-...', name:'Adult', price:450, isMainTicket:true }], createdBy:{ id:'user-uuid-...', name:'Jane Supervisor', email:'jane@example.com' }, notifyRecipients:[]}},
-          { status:404, desc:'Not found', body:{ message:'Event not found' }},
-        ]},
-      { method:'GET', path:'/api/events/by-alias/:redirectUrl', auth:'public', desc:'Get event by its URL alias',
-        pathParams:{ ':redirectUrl':'URL alias string (e.g. camp-2025)' },
-        responses:[{ status:200, desc:'Success', body:{ id:'ev-uuid-...', title:'Camp 2025', redirectUrl:'camp-2025' }}]},
-      { method:'POST', path:'/api/events', auth:'supervisor+', desc:'Create a new event',
-        request:{ body:{ title:'Camp 2025', description:'Annual family camp', startDate:'2025-07-10T08:00:00.000Z', endDate:'2025-07-14T17:00:00.000Z', registrationDeadline:'2025-07-01T00:00:00.000Z', price:450, isActive:true, isHidden:false, requiresAuth:true }},
-        responses:[
-          { status:201, desc:'Created', body:{ id:'ev-uuid-new', title:'Camp 2025', createdAt:'2024-11-01T09:00:00.000Z' }},
-        ]},
-      { method:'PUT', path:'/api/events/:id', auth:'supervisor+', desc:'Update an event. Multi-day events send scheduleType:"sessions" with the full sessions list (rows left out are deleted; ones with check-ins must be cancelled instead), plus lateJoinEnabled, lateJoinUntilSessionIndex, latePricing, lateFixedPrice, checkInWindow, sessionReminders, certificatesEnabled and certificateConfig. The response includes sessionChanges.',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ title:'Camp 2025 Updated', price:500 }},
-        responses:[{ status:200, desc:'Updated', body:{ id:'ev-uuid-...', title:'Camp 2025 Updated', price:500 }}]},
-      { method:'POST', path:'/api/events/:id/copy-from', auth:'supervisor+', desc:'Copying an event (1.47.0): after the copy is created from the event form, copy the source event\'s allocation sets and groups (not the kids rooms) and, for admins, its planned costs (matched to options by name). Only into an event with no registrations or allocation sets yet. POST /api/events takes clonedFromId to note the source in the audit log.',
-        pathParams:{ ':id':'The new event' },
-        request:{ body:{ fromEventId:'ev-uuid-source' }},
-        responses:[{ status:200, desc:'Copied', body:{ sets:2, groups:9, costs:3 }}, { status:409, desc:'The event already has registrations or groups' }]},
-      { method:'GET', path:'/api/events/:id/notify-recipients', auth:'supervisor+', desc:'Get which users receive registration/payment/daily-summary notifications for this event. Lightweight — skips the option/stock computation that GET /api/events/:id does.',
-        pathParams:{ ':id':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'user-uuid-1', name:'Jane Supervisor', email:'jane@example.com', role:'supervisor' }]}]},
-      { method:'PUT', path:'/api/events/:id/notify-recipients', auth:'supervisor+', desc:'Set which users receive registration/payment/daily-summary notifications for this event. Pass an empty array to fall back to the event creator.',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ userIds:['user-uuid-1','user-uuid-2'] }},
-        responses:[
-          { status:200, desc:'Saved', body:[{ id:'user-uuid-1', name:'Jane Supervisor', email:'jane@example.com', role:'supervisor' },{ id:'user-uuid-2', name:'John Admin', email:'john@example.com', role:'admin' }]},
-          { status:400, desc:'Bad input', body:{ message:'userIds must be an array' }},
-        ]},
-      { method:'DELETE', path:'/api/events/:id', auth:'admin', desc:'Permanently delete an event',
-        pathParams:{ ':id':'Event UUID' },
-        responses:[{ status:200, desc:'Deleted', body:{ message:'Event deleted.' }}]},
-      { method:'POST', path:'/api/events/:id/email-attendees', auth:'supervisor+', desc:'Send a bulk email to event attendees. Use dryRun:true to preview recipients without sending.',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ subject:'Payment reminder: Camp 2025', text:'Hi {{name}}, you have an outstanding balance of {{balance}}.', filter:{ status:'unpaid', attendeeIds:['user-uuid-1','user-uuid-2'] }, dryRun:false, template:'custom' }},
-        responses:[
-          { status:200, desc:'Sent', body:{ matched:15, sent:14, failed:1 }},
-          { status:200, desc:'Dry run', body:{ matched:15, dryRun:true, recipients:[{ email:'jane@example.com', name:'Jane Doe' }]}},
-        ]},
-      { method:'POST', path:'/api/events/:id/email-attendees/schedule', auth:'supervisor+', desc:'Schedule a bulk email to run at a future time',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ subject:'Reminder: Camp 2025', text:'Hi {{name}}, see you soon!', scheduledAt:'2025-07-03T09:00:00.000Z', filter:{ status:'paid' }}},
-        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', scheduledAt:'2025-07-03T09:00:00.000Z', status:'queued' }}}]},
-      { method:'POST', path:'/api/events/:id/whatsapp-attendees', auth:'supervisor+', desc:'Send a bulk WhatsApp message to attendees with a phone number. Supports dryRun.',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ message:'Hi {{name}}, camp starts in 3 days! 🏕️', filter:{ status:'paid' }, dryRun:false }},
-        responses:[
-          { status:200, desc:'Sent', body:{ matched:12, sent:11 }},
-        ]},
-      { method:'POST', path:'/api/events/:id/whatsapp-attendees/schedule', auth:'supervisor+', desc:'Schedule a bulk WhatsApp message',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ message:'Hi {{name}}, final reminder for camp tomorrow! 🎉', scheduledAt:'2025-07-09T08:00:00.000Z', filter:{ status:'paid' }}},
-        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued' }}}]},
-      { method:'POST', path:'/api/events/:id/options', auth:'supervisor+', desc:'Add a ticket option to an event',
-        pathParams:{ ':id':'Event UUID' },
-        request:{ body:{ name:'Child (under 12)', price:250, isMainTicket:false }},
-        responses:[{ status:201, desc:'Created', body:{ id:'opt-uuid-new', name:'Child (under 12)', price:250, isMainTicket:false }}]},
-      { method:'PUT', path:'/api/events/options/:id', auth:'supervisor+', desc:'Update a ticket option',
-        pathParams:{ ':id':'EventOption UUID' },
-        request:{ body:{ price:300 }},
-        responses:[{ status:200, desc:'Updated', body:{ id:'opt-uuid-...', price:300 }}]},
-      { method:'DELETE', path:'/api/events/options/:id', auth:'admin', desc:'Delete a ticket option (fails if registrations exist)',
-        pathParams:{ ':id':'EventOption UUID' },
-        responses:[
-          { status:200, desc:'Deleted', body:{ message:'Option deleted.' }},
-          { status:400, desc:'In use', body:{ message:'Cannot delete option with existing registrations.' }},
-        ]},
-    ]},
-
-    { title: 'Registrations', base: '/api/registrations', endpoints: [
-      { method:'PUT', path:'/api/registrations/:id/options', auth:'Bearer (owner or staff)', desc:'Change the items on a registration (add/remove), within stock and paid-ticket limits' },
-      { method:'POST', path:'/api/registrations/:id/coupon', auth:'Bearer (owner or staff)', desc:'Apply a coupon code to an existing registration', request:{ body:{ code:'STAFF50' }}},
-      { method:'DELETE', path:'/api/registrations/:id/coupon', auth:'staff+', desc:'Remove the coupon from a registration (frees the use)' },
-      { method:'GET', path:'/api/registrations/:id/forms/draft', auth:'Owner or staff', desc:'Saved draft of the attendee forms' },
-      { method:'PUT', path:'/api/registrations/:id/forms/draft', auth:'Owner or staff', desc:'Save a draft of the attendee forms (not submitted)' },
-      { method:'PUT', path:'/api/registrations/:id/forms/responses', auth:'supervisor+', desc:'Replace (edit) the submitted form responses of a registration' },
-      { method:'POST', path:'/api/registrations', auth:'optional', desc:'Create a registration. Auth optional — guests are allowed when event does not require auth.',
-        request:{ body:{ eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-uuid-...', quantity:2 }] }},
-        responses:[
-          { status:201, desc:'Created', body:{ id:'reg-uuid-...', eventId:'ev-uuid-...', status:'pending', checkoutId:null, createdAt:'2025-06-01T10:00:00.000Z' }},
-          { status:400, desc:'Deadline passed', body:{ message:'Registration deadline has passed.' }},
-        ]},
-      { method:'GET', path:'/api/registrations/myregistrations', auth:'user+', desc:'Get all registrations for the authenticated user',
-        responses:[{ status:200, desc:'Success', body:[{ id:'reg-uuid-...', event:{ id:'ev-uuid-...', title:'Camp 2025' }, status:'paid', createdAt:'2025-06-01T10:00:00.000Z' }]}]},
-      { method:'GET', path:'/api/registrations/:id', auth:'optional', desc:'Get registration detail by ID',
-        pathParams:{ ':id':'Registration UUID' },
-        responses:[{ status:200, desc:'Success', body:{ id:'reg-uuid-...', status:'paid', event:{ title:'Camp 2025' }, registrationOptions:[{ eventOption:{ name:'Adult' }, quantity:1 }], payments:[{ amount:450, method:'card', status:'succeeded' }] }}]},
-      { method:'PUT', path:'/api/registrations/:id', auth:'staff+', desc:'Update registration status. If set to "paid", generates tickets and emails them fire-and-forget. If downgraded from "paid", deletes unused tickets (blocks if any ticket has been scanned).',
-        pathParams:{ ':id':'Registration UUID' },
-        request:{ body:{ status:'paid' }},
-        responses:[{ status:200, desc:'Updated', body:{ id:'reg-uuid-...', status:'paid' }}]},
-      { method:'DELETE', path:'/api/registrations/:id', auth:'user+', desc:'Cancel registration. Users: only allowed when no positive payments exist (returns 403 otherwise). Admins: always allowed.',
-        pathParams:{ ':id':'Registration UUID' },
-        responses:[
-          { status:200, desc:'Cancelled', body:{ message:'Registration cancelled', registration:{ id:'reg-uuid-...', status:'cancelled' }}},
-          { status:400, desc:'Already cancelled', body:{ message:'Registration is already cancelled' }},
-          { status:403, desc:'Payments exist — non-admin cannot cancel', body:{ message:'This registration has payments recorded against it and cannot be self-cancelled. Please contact the organisation for assistance.' }},
-          { status:403, desc:'Not the owner (and not admin)', body:{ message:'Not authorized to cancel this registration' }},
-        ]},
-      { method:'GET', path:'/api/registrations', auth:'staff+', desc:'List all registrations across all events',
-        queryParams:{ page:'Page (default 1)', limit:'Per page (default 20)', eventId:'Filter by event', status:'Filter by status', search:'Search by name/email' },
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'reg-uuid-...', user:{ name:'Jane Doe' }, event:{ title:'Camp 2025' }, status:'paid' }], total:1, page:1 }}]},
-      { method:'GET', path:'/api/registrations/event/:eventId', auth:'staff+', desc:'Get all registrations for a specific event',
-        pathParams:{ ':eventId':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'reg-uuid-...', user:{ id:'user-uuid-...', name:'Jane Doe', email:'jane@example.com', phoneNumber:'+27821234567' }, status:'paid' }]}]},
-      { method:'PUT', path:'/api/registrations/:id/attendees', auth:'user+', desc:'Replace the named attendees on a registration (group tickets) and choose ticket delivery (payer | each). Owner or staff. Removing an attendee whose ticket was scanned is refused.',
-        request:{ body:{ attendees:[{ id:'att-uuid-...', eventOptionId:'opt-uuid-...', name:'Sam Smith', email:'sam@example.com' },{ eventOptionId:'opt-uuid-...', name:'Alex Smith' }], ticketDelivery:'each' }},
-        responses:[{ status:200, desc:'Saved', body:{ id:'reg-uuid-...', ticketDelivery:'each', attendees:[{ id:'att-uuid-...', name:'Sam Smith', ticket:{ id:'tkt-uuid-...', isUsed:false }}] }}]},
-      { method:'POST', path:'/api/registrations/:id/attendees/:attendeeId/send-form-link', auth:'user+', desc:'Email/WhatsApp a named attendee the link to fill in their own attendee form' },
-      { method:'POST', path:'/api/registrations/bulk', auth:'supervisor+', desc:'Bulk actions on ticked registrations (up to 500), each run through the same code as doing it one at a time: action "markPaid" { method: cash|eft|card|other, paidAt? } records the balance; "cancel"; "moveOption" { fromOptionId, toOptionId } (same event); "allocate" { setId, groupId } places their named people; "message" { channel: email|whatsapp, subject?, text } sends an event update. Answers { action, done, skipped, failed, results: [{ id, ok, skipped?, message }] }. Campus-checked for every id; payments and ticket changes refused in licence read-only mode. Audited as registrations_bulk',
-        request:{ body:{ action:'markPaid', registrationIds:['reg-uuid-1','reg-uuid-2'], method:'cash' } } },
-      { method:'POST', path:'/api/registrations/manual', auth:'supervisor+', desc:'Manually create a registration (at-the-door / walk-in). Resolves early-bird tier pricing (including per-variant tiers) and stores priceSnapshot + appliedTierId on each option. Creates or finds a matching user by email/phone. If a matching user is found, updates their notificationPreference and backfills a missing phone number or guest placeholder email with the newly supplied value (without overwriting existing contact info). Generates a Yoco checkout link for unpaid registrations to include in the self-service notification email.',
-        request:{ body:{ eventId:'ev-uuid-...', user:{ name:'Jane Doe', email:'jane@example.com', phoneNumber:'0821234567' }, options:[{ eventOptionId:'opt-uuid-...', quantity:1, variantId:'var-uuid-...' }], notificationPreference:'email' }},
-        responses:[{ status:201, desc:'Created', body:{ id:'reg-uuid-new', status:'pending' }}]},
-      { method:'POST', path:'/api/registrations/:id/forms/responses', auth:'optional', desc:'Submit form responses for a registration',
-        pathParams:{ ':id':'Registration UUID' },
-        request:{ body:{ answers:[{ fieldId:'field-uuid-...', value:'Yes' }, { fieldId:'field-uuid-2', value:'Vegetarian' }] }},
-        responses:[{ status:201, desc:'Submitted', body:{ id:'response-uuid-...', createdAt:'2025-06-01T10:05:00.000Z' }}]},
-      { method:'POST', path:'/api/registrations/:id/send-invoice', auth:'user+', desc:'(Re)generate the invoice PDF for one of the caller\'s own registrations and send it on the requested channel — email or WhatsApp. Works regardless of balance (shows "Paid in full" when nothing is owed); fails only if there is no valid email/phone on file for the chosen channel.',
-        notes:'The PDF\'s invoiceNo is derived, not sequential: INV-<year of registration.createdAt>-<last 6 hex chars of the registration id, uppercased>. When there is an outstanding balance, generates a fresh Yoco checkout link for the invoice\'s QR code/pay-now link on each call.',
-        pathParams:{ ':id':'Registration UUID' },
-        request:{ body:{ channel:'email' }},
-        responses:[
-          { status:200, desc:'Sent', body:{ message:'Invoice emailed.' }},
-          { status:400, desc:'No valid contact for channel', body:{ message:'No valid email address on file. Add one in your profile.' }},
-          { status:403, desc:'Not the owner', body:{ message:'Not authorized to access this registration' }},
-        ]},
-    ]},
-
-    { title: 'Impersonation', base: '/api/admin', endpoints: [
-      { method:'GET', path:'/api/admin/audit-log', auth:'admin', desc:'Paginated admin/supervisor audit trail (?page, limit, actorId, action, role, from, to, search)' },
-      { method:'GET', path:'/api/admin/jobs', auth:'admin', desc:'Background jobs: queue mode, timezone, and each job schedule, next run and last 10 runs' },
-      { method:'POST', path:'/api/admin/jobs/:name/run', auth:'admin', desc:'Run a background job now (queued for a worker); audit-logged' },
-      { method:'POST', path:'/api/admin/impersonate/:userId', auth:'admin (2FA)', desc:'View the site as a user — read-only token, 30 minutes, audited', request:{ body:{ reason:'Ticket not showing in My Events' }}, responses:[{ status:201, desc:'Started', body:{ token:'jwt…', session:{ id:'sess-uuid', expiresAt:'2025-07-10T08:45:00.000Z' }}}, { status:403, desc:'Not allowed', body:{ message:"Admins can't be impersonated." }}]},
-      { method:'POST', path:'/api/admin/impersonate/end', auth:'impersonation token', desc:'End the impersonation session' },
-      { method:'POST', path:'/api/admin/impersonate/log', auth:'impersonation token', desc:'Record a page viewed during the session' },
-      { method:'GET', path:'/api/admin/impersonate/current', auth:'impersonation token', desc:'The live impersonation session' },
-      { method:'GET', path:'/api/admin/impersonation-sessions', auth:'admin', desc:'Impersonation sessions with their request trail' },
-    ]},
-    { title: 'Registration funnel', base: '/api/analytics', endpoints: [
-      { method:'POST', path:'/api/analytics/track', auth:'Public (rate-limited)', desc:'Record a funnel step from a cookie-consented browser (always 204)',
-        request:{ body:{ sessionId:'random-uuid', eventId:'ev-uuid-...', stage:'view', source:'camp-2025' }}},
-      { method:'GET', path:'/api/analytics/funnel', auth:'supervisor+', desc:'Funnel for ?eventIds=a,b&from=&to= — totals, conversion, daily trend, by source/device/option' },
-    ]},
-    { title: 'Post-event feedback', base: '/api/feedback', endpoints: [
-      { method:'GET', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'An event\'s feedback form, with invite and response counts' },
-      { method:'PUT', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'Create/update the feedback form (questions lock once answered)',
-        request:{ body:{ sendAt:'2025-07-13T09:00:00.000Z', audience:'checked_in', anonymous:false, intro:'Thanks for coming!', fields:[{ type:'rating', label:'Overall?', isRequired:true }, { type:'multiple_choice', label:'Best part', options:['Worship','Talks'] }] }}},
-      { method:'DELETE', path:'/api/feedback/event/:eventId', auth:'supervisor+', desc:'Remove the feedback form' },
-      { method:'POST', path:'/api/feedback/event/:eventId/send-now', auth:'supervisor+', desc:'Send the feedback form now' },
-      { method:'GET', path:'/api/feedback/public/:token', auth:'Link holder', desc:'The form behind a personal feedback link' },
-      { method:'POST', path:'/api/feedback/public/:token', auth:'Link holder', desc:'Submit feedback once', request:{ body:{ answers:{ 'field-uuid':'5' } }}},
-      { method:'GET', path:'/api/feedback/summary', auth:'supervisor+', desc:'Feedback summary for ?eventIds=a,b (response rate, averages, breakdowns, comments)' },
-    ]},
-    { title: 'Sponsor a spot', base: '/api/sponsorships', endpoints: [
-      { method:'GET', path:'/api/sponsorships/event/:eventId', auth:'Public', desc:'Sponsorship progress for an event (spots funded, goal) — never who was helped',
-        responses:[{ status:200, desc:'Progress', body:{ enabled:true, open:true, spotPrice:450, showProgress:true, goalSpots:20, spotsFunded:12, sponsors:9 }}]},
-      { method:'POST', path:'/api/sponsorships/checkout', auth:'Public (optional login)', desc:'Start a Yoco checkout to sponsor spots or a custom amount; the money lands in the event sponsorship pool',
-        request:{ body:{ eventId:'ev-uuid-...', spots:2, anonymous:false, sponsorName:'The Smith family', message:'Have a great camp!', name:'Sam Smith', email:'sam@example.com' }},
-        responses:[{ status:200, desc:'Checkout created', body:{ redirectUrl:'https://pay.yoco.com/...', amount:900 }}]},
-      { method:'GET', path:'/api/sponsorships/event/:eventId/pool', auth:'supervisor+', desc:'Sponsorship pool totals: received, assigned, remaining' },
-    ]},
-    { title: 'Rooms & groups', base: '/api/allocations', endpoints: [
-      { method:'GET', path:'/api/allocations/event/:eventId', auth:'supervisor+', desc:'Allocation board: sets with groups and assignments, named attendees, possible leaders' },
-      { method:'POST', path:'/api/allocations/sets', auth:'supervisor+', desc:'Create an allocation set', request:{ body:{ eventId:'ev-uuid-...', name:'Rooms', showOnTicket:true }}},
-      { method:'PUT', path:'/api/allocations/sets/:id', auth:'supervisor+', desc:'Rename a set or show it on tickets' },
-      { method:'DELETE', path:'/api/allocations/sets/:id', auth:'supervisor+', desc:'Delete a set and its groups' },
-      { method:'POST', path:'/api/allocations/sets/:id/groups', auth:'supervisor+', desc:'Add a group', request:{ body:{ name:'Cabin 1', capacity:8, gender:'female', leaderUserId:'user-uuid-...' }}},
-      { method:'PUT', path:'/api/allocations/groups/:id', auth:'supervisor+', desc:'Edit a group' },
-      { method:'DELETE', path:'/api/allocations/groups/:id', auth:'supervisor+', desc:'Delete a group (its people become unassigned)' },
-      { method:'PUT', path:'/api/allocations/sets/:id/assignments', auth:'supervisor+', desc:'Place (or with groupId null, unplace) an attendee; enforces capacity and gender', request:{ body:{ attendeeId:'att-uuid-...', groupId:'grp-uuid-...' }}},
-      { method:'DELETE', path:'/api/allocations/sets/:id/assignments', auth:'supervisor+', desc:'Clear every assignment in a set' },
-      { method:'POST', path:'/api/allocations/sets/:id/auto', auth:'supervisor+', desc:'Auto-allocate everyone not yet placed', request:{ body:{ mode:'together' }}, responses:[{ status:200, desc:'Done', body:{ placed:12, unplaced:1 }}]},
-      { method:'GET', path:'/api/allocations/sets/:id/lists', auth:'supervisor+', desc:'Per-group lists for printing (?medical=true adds medical details; audited)' },
-      { method:'GET', path:'/api/allocations/my-groups', auth:'staff+', desc:'Groups the signed-in leader leads, with their people' },
-    ]},
-    { title: 'Ticket transfer', base: '/api/tickets', endpoints: [
-      { method:'DELETE', path:'/api/tickets/:id/transfer', auth:'payer, holder or supervisor+', desc:'Withdraw a transfer offer that has not been accepted yet' },
-      { method:'GET', path:'/api/tickets/transfer-offer/:token', auth:'Link holder', desc:'The ticket offered behind a transfer link (status, event, ticket type, sender first name)' },
-      { method:'POST', path:'/api/tickets/transfer-offer/:token/accept', auth:'Link holder', desc:'Accept the ticket — the transfer happens now (new QR code, ticket sent to the new holder)' },
-      { method:'POST', path:'/api/tickets/transfer-offer/:token/decline', auth:'Link holder', desc:'Decline the ticket offer' },
-      { method:'POST', path:'/api/tickets/:id/transfer', auth:'payer, holder or supervisor+', desc:'Give a ticket to someone else before the event (new QR code; the old one stops working; billing stays with the payer)',
-        request:{ body:{ name:'Nia New', email:'nia@example.com', phone:'0821234567' }},
-        responses:[{ status:200, desc:'Transferred', body:{ message:'Ticket transferred to Nia New…', ticketId:'ticket-uuid-...' }}, { status:400, desc:'Not allowed', body:{ message:'This ticket has already been used (or partly used), so it can’t be transferred.' }}]},
-      { method:'GET', path:'/api/tickets/:id/transfers', auth:'payer, holder or staff+', desc:'Transfer history of a ticket' },
-    ]},
-    { title: 'Offline scanning', base: '/api/scan-locks', endpoints: [
-      { method:'GET', path:'/api/scan-locks', auth:'staff+', desc:'Active offline locks for an event (?eventId=)' },
-      { method:'POST', path:'/api/scan-locks', auth:'staff+', desc:'Lock a section (or the whole event) to this device for offline scanning',
-        request:{ body:{ eventId:'ev-uuid-...', sectionId:'sec-uuid-...', deviceId:'device-uuid', deviceName:'Chrome on Android' }},
-        responses:[{ status:201, desc:'Locked', body:{ id:'lock-uuid-...', sectionName:'Main hall' }}, { status:409, desc:'Held elsewhere', body:{ message:'"Main hall" is offline-locked by Ann on Chrome on Android.' }}]},
-      { method:'GET', path:'/api/scan-locks/:id/snapshot', auth:'staff+', desc:'Tickets valid in the lock scope, for the device to keep offline (lock holder, ?deviceId=)' },
-      { method:'POST', path:'/api/scan-locks/:id/sync', auth:'staff+', desc:'Upload offline scans (idempotent by clientScanId; capped at what is left on each ticket)',
-        request:{ body:{ deviceId:'device-uuid', scans:[{ clientScanId:'scan-uuid', qrCode:'qr-uuid', qty:1, scannedAt:'2025-07-10T08:15:00.000Z' }] }},
-        responses:[{ status:200, desc:'Synced', body:{ accepted:1, duplicates:0, conflicts:[] }}]},
-      { method:'DELETE', path:'/api/scan-locks/:id', auth:'staff+', desc:'End offline mode (lock holder)' },
-      { method:'POST', path:'/api/scan-locks/:id/force-release', auth:'supervisor+', desc:'Release a lost device\'s lock' },
-      { method:'GET', path:'/api/scan-locks/reports', auth:'supervisor+', desc:'Offline sync reports for an event' },
-      { method:'POST', path:'/api/scan-locks/reports/:id/review', auth:'supervisor+', desc:'Mark a sync report reviewed' },
-    ]},
-    { title: 'Waitlist', base: '/api/waitlist', endpoints: [
-      { method:'POST', path:'/api/waitlist', auth:'public', desc:'Join the waitlist for a sold-out line (login needed when the event requires it)',
-        request:{ body:{ eventId:'ev-uuid-...', eventOptionId:'opt-uuid-...', quantity:2 }},
-        responses:[{ status:201, desc:'Joined', body:{ id:'wl-uuid-...', status:'waiting', ahead:3 }}, { status:400, desc:'Places available', body:{ message:'There are places available — you can register now.' }}]},
-      { method:'GET', path:'/api/waitlist/mine', auth:'user+', desc:'My active waitlist entries' },
-      { method:'DELETE', path:'/api/waitlist/:id', auth:'user+', desc:'Leave the waitlist' },
-      { method:'GET', path:'/api/waitlist/claim/:token', auth:'public', desc:'What a claim link offers (rate-limited)' },
-      { method:'GET', path:'/api/waitlist/events/:eventId', auth:'staff+', desc:'The queue for an event' },
-      { method:'POST', path:'/api/waitlist/:id/offer', auth:'supervisor+', desc:'Offer places now, even over the stock limit' },
-      { method:'POST', path:'/api/waitlist/:id/move', auth:'supervisor+', desc:'Move up or down the queue', request:{ body:{ direction:'up' }} },
-      { method:'POST', path:'/api/waitlist/:id/remove', auth:'supervisor+', desc:'Take someone off the waitlist' },
-    ]},
-    { title: 'Attendance & certificates', base: '/api/attendance', endpoints: [
-      { method:'GET', path:'/api/attendance/:eventId', auth:'staff+', desc:'Attendance register: sessions (columns), one row per main ticket with check-ins per session, completion and certificate',
-        responses:[{ status:200, desc:'Register', body:{ event:{ id:'ev-uuid-...', scheduleType:'sessions' }, columns:[{ id:'ses-uuid-...', label:'Week 1', startsAt:'2026-11-04T16:30:00.000Z', cancelled:false }], rows:[{ ticketId:'t-uuid-...', name:'Thandi', checkIns:{ 'ses-uuid-...':1 }, attended:1, total:5, completed:false, certificate:null }], totals:{ 'ses-uuid-...':12 } }}]},
-      { method:'GET', path:'/api/attendance/:eventId/export?format=xlsx|pdf', auth:'staff+', desc:'Download the register as Excel or PDF' },
-      { method:'POST', path:'/api/attendance/:eventId/mark', auth:'supervisor+', desc:'Mark a ticket present/absent for a session (single-date events use sessionId "event")', request:{ body:{ ticketId:'t-uuid-...', sessionId:'ses-uuid-...', present:true }} },
-      { method:'POST', path:'/api/attendance/:eventId/certificates', auth:'supervisor+', desc:'Issue certificates now to everyone eligible, or to one ticket (even if not eligible)', request:{ body:{ ticketId:'t-uuid-... (optional)' }} },
-      { method:'POST', path:'/api/attendance/:eventId/certificates/send', auth:'supervisor+', desc:'Email/WhatsApp unsent certificates, or one again', request:{ body:{ certificateId:'(optional)' }} },
-      { method:'GET', path:'/api/attendance/:eventId/certificates.pdf', auth:'supervisor+', desc:'All of an event\'s certificates in one PDF' },
-      { method:'POST', path:'/api/attendance/certificates/preview', auth:'supervisor+', desc:'Sample certificate PDF with unsaved settings', request:{ body:{ title:'Alpha Course', config:{ template:'classic' } }} },
-      { method:'POST', path:'/api/attendance/certificates/:id/revoke', auth:'supervisor+', desc:'Revoke a certificate (never re-issued automatically)' },
-      { method:'GET', path:'/api/attendance/certificates/mine', auth:'user+', desc:'My certificates' },
-      { method:'GET', path:'/api/attendance/certificates/:id/pdf', auth:'user+', desc:'Download a certificate (its person, the booker, or a supervisor)' },
-      { method:'GET', path:'/api/attendance/certificates/verify/:code', auth:'public', desc:'Check a certificate code — name, event and dates only', responses:[{ status:200, desc:'Result', body:{ valid:true, name:'Thandi Mokoena', event:'Alpha Course', completedOn:'2026-12-02T18:30:00.000Z' }}] },
-    ]},
-    { title: 'Parental consent', base: '/api/consent', endpoints: [
-      { method:'GET', path:'/api/consent/:token', auth:'public', desc:'Consent page data for a parent/guardian (the link token is the credential; rate-limited)',
-        responses:[{ status:200, desc:'Success', body:{ status:'pending', attendeeName:'Sam Smith', consentText:'I give permission…', event:{ title:'Youth Camp' }, collect:{ medical:true, emergency:true, photo:true } }}, { status:404, desc:'Unknown or replaced link', body:{ message:'This consent link is not valid.' }}]},
-      { method:'POST', path:'/api/consent/:token', auth:'public', desc:'Give or decline consent. Records name, time, IP, device and the consent text version; medical/emergency details are stored encrypted.',
-        request:{ body:{ decision:'give', signedName:'Pat Smith', isGuardian:true, medical:{ allergies:'Peanuts' }, emergency:{ name:'Gran', phone:'0821234567' }, photoConsent:true }},
-        responses:[{ status:200, desc:'Answered', body:{ status:'given' }}, { status:409, desc:'Already answered', body:{ message:'Consent has already been given.' }}]},
-      { method:'GET', path:'/api/consent/events/:eventId', auth:'staff+', desc:'Consent status for every attendee on an event' },
-      { method:'POST', path:'/api/consent/requests/:id/resend', auth:'user+', desc:'Re-send a pending request with a fresh link (registrant or staff)' },
-      { method:'POST', path:'/api/consent/events/:eventId/resend-pending', auth:'supervisor+', desc:'Re-send every pending request on an event' },
-      { method:'POST', path:'/api/consent/events/:eventId/rerequest', auth:'supervisor+', desc:'Ask again where consent was given on an older version of the text, or never requested' },
-      { method:'GET', path:'/api/consent/events/:eventId/medical', auth:'supervisor+', desc:'Decrypted medical & emergency list; every view is written to the admin audit log' },
-    ]},
-    { title: 'Coupons', base: '/api/coupons', endpoints: [
-      { method:'POST', path:'/api/coupons/validate', auth:'public', desc:'Check a code against a basket before registering; returns the discount. Login needed for restricted codes; staff can pass forUserId (or null for a walk-in).',
-        request:{ body:{ code:'STAFF50', eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-uuid-...', quantity:2 }] }},
-        responses:[
-          { status:200, desc:'Valid (bundle deals come off first, then the code)', body:{ valid:true, code:'STAFF50', type:'percent', value:50, summary:'50% off', discount:450, bundleDiscount:0, bundles:[], subtotal:900, total:450 }},
-          { status:400, desc:'Not usable', body:{ valid:false, message:'This code has expired.' }},
-        ]},
-      { method:'GET', path:'/api/coupons', auth:'supervisor+', desc:'List codes with use counts and total discount given',
-        responses:[{ status:200, desc:'Success', body:[{ id:'cpn-uuid-...', code:'STAFF50', type:'percent', value:50, summary:'50% off', active:true, uses:3, totalDiscount:1350 }]}]},
-      { method:'POST', path:'/api/coupons', auth:'supervisor+', desc:'Create a code. type: percent | fixed | comp. eventIds/options/userIds/restrictRoles/restrictDomain are optional.',
-        request:{ body:{ code:'STAFF50', type:'percent', value:50, eventIds:['ev-uuid-...'], restrictRoles:['staff','supervisor','admin'], maxUsesPerUser:1, stackEarlyBird:false }},
-        responses:[{ status:201, desc:'Created', body:{ id:'cpn-uuid-...', code:'STAFF50' }}, { status:409, desc:'Code exists', body:{ message:'The code STAFF50 already exists' }}]},
-      { method:'GET', path:'/api/coupons/:id', auth:'supervisor+', desc:'One code with every use (redemption)' },
-      { method:'PUT', path:'/api/coupons/:id', auth:'supervisor+', desc:'Edit a code or turn it off ({ active:false }). Discounts already given keep their amount; a used code can\'t be renamed.' },
-      { method:'GET', path:'/api/coupons/redemptions', auth:'supervisor+', desc:'Active uses for the Discounts report. Query: eventIds (comma-separated), from, to' },
-    ]},
-    { title: 'Bundle deals', base: '/api/bundles', endpoints: [
-      { method:'POST', path:'/api/bundles/quote', auth:'public', desc:'The bundle deals a basket gets, applied automatically as many times as they fit and only when cheaper. Staff can pass forUserId (or null for a walk-in).',
-        request:{ body:{ eventId:'ev-uuid-...', options:[{ eventOptionId:'opt-adult', quantity:5 }, { eventOptionId:'opt-child', quantity:3 }] }},
-        responses:[{ status:200, desc:'Success', body:{ subtotal:550, bundleDiscount:50, bundles:[{ bundleId:'bnd-uuid-...', name:'Family deal', count:1, discount:50 }], total:500 }}]},
-      { method:'GET', path:'/api/bundles/event/:eventId', auth:'supervisor+', desc:'An event\'s bundles with uses and total discount given' },
-      { method:'POST', path:'/api/bundles/event/:eventId', auth:'supervisor+', desc:'Create a bundle. kind: exact (items with quantities, price for the set) | mix (any setSize of the items for price) | free (any setSize, cheapest freeCount free) | group (setSize or more of the items: groupPricing per_ticket price each, or percent off). items: [{ eventOptionId, variantId?, quantity }] (variantId left out = any variant; quantity only for exact).',
-        request:{ body:{ name:'Family deal', price:500, items:[{ eventOptionId:'opt-adult', quantity:5 }, { eventOptionId:'opt-child', quantity:3 }], validUntil:null }}},
-      { method:'PUT', path:'/api/bundles/:id', auth:'supervisor+', desc:'Edit a bundle or switch it off ({ isActive:false }). Registrations keep a bundle they already have.' },
-      { method:'DELETE', path:'/api/bundles/:id', auth:'supervisor+', desc:'Delete a bundle; one that has been used is switched off instead' },
-    ]},
-    { title: 'Payments', base: '/api/payments', endpoints: [
-      { method:'GET', path:'/api/payments/:id', auth:'Bearer', desc:'A payment by id' },
-      { method:'GET', path:'/api/payments/registration/:registrationId', auth:'Bearer', desc:'Payments of a registration' },
-      { method:'POST', path:'/api/payments/checkout/send', auth:'supervisor+', desc:'Send a generated payment link to the registrant by email or WhatsApp (also at /api/payments/yoco-checkout/send)', request:{ body:{ registrationId:'reg-uuid-...', redirectUrl:'https://pay.yoco.com/...', channel:'whatsapp' }}},
-      { method:'GET', path:'/api/payments/providers', auth:'—', desc:'Payment providers people can pay with now (enabled in Site settings → Payments and set up), in display order, plus the online minimum (R15)',
-        responses:[{ status:200, desc:'Success', body:{ providers:[{ id:'yoco', label:'Yoco' }], minimumAmount:15 }}]},
-      { method:'GET', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'The payer\'s page for a checkout: amount, description, providers to choose from, or the PayFast form to post' },
-      { method:'POST', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'Start the checkout with the provider the payer picked: { provider } → { redirectUrl } or { form }' },
-      { method:'GET', path:'/api/payments/checkouts/open', auth:'supervisor+', desc:'Online checkouts from the last 14 days with no payment yet, and whether their provider can be asked (canCheck)' },
-      { method:'POST', path:'/api/payments/checkouts/check', auth:'supervisor+', desc:'Ask providers whether checkouts were paid ({ ids? }, default all open) and record what they received. PayFast: transaction history; Yoco: cant_check' },
-      { method:'GET', path:'/api/payments/providers/settings', auth:'admin', desc:'Every provider with enabled, configured and capabilities ({ refund, getTransaction, listTransactions }), in display order' },
-      { method:'PUT', path:'/api/payments/providers/settings', auth:'admin', desc:'Turn providers on/off and set their order (the list order). Audit logged.',
-        request:{ body:{ providers:[{ id:'yoco', enabled:true }] }}},
-      { method:'POST', path:'/api/payments/unassign-donation', auth:'supervisor+', desc:'Reverse a donation assignment (removes the leg and reverts the registration status)' },
-      { method:'POST', path:'/api/payments/checkout', auth:'user+', desc:'Start an online checkout (also at /api/payments/yoco-checkout) with body.provider, or the first enabled provider. At least R15 (all providers). Before creating the checkout, re-evaluates early-bird tier eligibility (deadline + stock). If any price changed since registration, returns priceUpdated:true instead of creating a checkout — the client must inform the user and retry.',
-        request:{ body:{ registrationId:'reg-uuid-...', amount:450, provider:'yoco', successUrl:'https://events.example.com/payment/success', cancelUrl:'https://events.example.com/payment/cancel', failureUrl:'https://events.example.com/payment/failure' }},
-        responses:[
-          { status:200, desc:'Checkout created — send the payer to redirectUrl', body:{ redirectUrl:'https://pay.yoco.com/checkout/abc123', checkoutId:'yoco-checkout-id', provider:'yoco', amount:450 }},
-          { status:200, desc:'Early-bird price changed — checkout NOT created. Frontend must show warning and let user confirm before retrying.', body:{ priceUpdated:true, newTotal:500, message:'One or more early-bird prices have changed since your registration was created. Please review the updated total before proceeding.' }},
-        ]},
-      { method:'POST', path:'/api/payments', auth:'supervisor+', desc:'Record a manual payment (cash, EFT, etc.)',
-        request:{ body:{ registrationId:'reg-uuid-...', amount:450, method:'cash', userId:'user-uuid-...' }},
-        responses:[
-          { status:201, desc:'Recorded', body:{ id:'pay-uuid-...', amount:450, method:'cash', status:'succeeded', createdAt:'2025-06-10T09:00:00.000Z' }},
-        ]},
-      { method:'GET', path:'/api/payments/mypayments', auth:'user+', desc:'Get own payment history (paginated, excludes donations). Returned method is normalized to cash|card|eft|voucher|other — apple_pay/google_pay report as "card", any other gateway-reported value reports as "other"',
-        queryParams:{ page:'Page (default 1)', limit:'Per page (default 25, max 25)', startDate:'ISO date, filters createdAt >=', endDate:'ISO date, filters createdAt <=', method:'Filter by normalized method: cash|card|eft|voucher|other', kind:'payment|refund — filters by amount sign' },
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'pay-uuid-...', amount:450, method:'card', status:'succeeded', createdAt:'2025-06-01T11:00:00.000Z' }], total:1, page:1, limit:25, pages:1 }}]},
-      { method:'POST', path:'/api/payments/:id/send-receipt', auth:'user+', desc:'Regenerate the receipt PDF for one of the caller\'s own payments and send it on the requested channel — email or WhatsApp. Fails if there is no valid email/phone on file for the chosen channel.',
-        notes:'The PDF\'s receiptNo is derived, not sequential: RCPT-<year of payment.createdAt>-<last 6 hex chars of the payment id, uppercased>.',
-        pathParams:{ ':id':'Payment UUID' },
-        request:{ body:{ channel:'whatsapp' }},
-        responses:[
-          { status:200, desc:'Sent', body:{ message:'Receipt sent to WhatsApp.' }},
-          { status:403, desc:'Not the owner', body:{ message:'Not authorized to access this payment' }},
-        ]},
-      { method:'GET', path:'/api/payments', auth:'supervisor+', desc:'List all payments',
-        queryParams:{ page:'Page (default 1)', limit:'Per page (default 20)', eventId:'Filter by event', userId:'Filter by user', method:'Filter by method (cash|card|eft|donation)', startDate:'ISO date', endDate:'ISO date' },
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'pay-uuid-...', amount:450, method:'card', user:{ name:'Jane Doe' }, registration:{ event:{ title:'Camp 2025' }}}], total:1 }}]},
-      { method:'GET', path:'/api/payments/event/:eventId', auth:'staff+', desc:'All payments for an event',
-        pathParams:{ ':eventId':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'pay-uuid-...', amount:450, user:{ name:'Jane Doe' }, method:'card' }]}]},
-      { method:'POST', path:'/api/payments/refund', auth:'supervisor+', desc:'Create a refund payment (negative amount)',
-        request:{ body:{ originalPaymentId:'pay-uuid-...', amount:450, reason:'Cancelled registration' }},
-        responses:[{ status:201, desc:'Refund recorded', body:{ id:'pay-uuid-refund', amount:-450, method:'refund' }}]},
-      { method:'PUT', path:'/api/payments/assign-donation', auth:'supervisor+', desc:'Link an unassigned donation payment to a specific registration',
-        request:{ body:{ paymentId:'pay-uuid-...', registrationId:'reg-uuid-...' }},
-        responses:[{ status:200, desc:'Assigned', body:{ id:'pay-uuid-...', registrationId:'reg-uuid-...', isDonation:false }}]},
-      { method:'GET', path:'/api/payments/admin/stats', auth:'admin', desc:'Aggregated payment statistics',
-        responses:[{ status:200, desc:'Success', body:{ totalRevenue:98500, totalPayments:215, byMethod:{ card:180, cash:30, eft:5 }, byEvent:[{ eventId:'ev-uuid-...', title:'Camp 2025', total:45000 }] }}]},
-    ]},
-
-    { title: 'Tickets', base: '/api/tickets', endpoints: [
-      { method:'GET', path:'/api/tickets', auth:'supervisor+', desc:'All tickets' },
-      { method:'GET', path:'/api/tickets/:id', auth:'Bearer (owner or staff)', desc:'A ticket by id' },
-      { method:'GET', path:'/api/tickets/qr/:qrCode', auth:'staff+', desc:'A ticket by QR code' },
-      { method:'PUT', path:'/api/tickets/email-sent', auth:'admin', desc:'Mark tickets as emailed' },
-      { method:'GET', path:'/api/tickets/mytickets', auth:'user+', desc:'Get own tickets',
-        responses:[{ status:200, desc:'Success', body:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', event:{ title:'Camp 2025' }, registrationOption:{ eventOption:{ name:'Adult' }}, quantity:1, isUsed:false }]}]},
-      { method:'POST', path:'/api/tickets/generate', auth:'supervisor+', desc:'Generate tickets for a registration (idempotent — skips already-generated options)',
-        request:{ body:{ registrationId:'reg-uuid-...' }},
-        responses:[{ status:201, desc:'Generated', body:{ created:2, skipped:0, tickets:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123' }] }}]},
-      { method:'POST', path:'/api/tickets/scan/:qrCode', auth:'staff+', desc:'Scan and redeem a ticket',
-        pathParams:{ ':qrCode':'QR code string from ticket' },
-        request:{ body:{ quantity:1 }},
-        responses:[
-          { status:200, desc:'Scanned', body:{ ticket:{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', isUsed:true }, event:{ title:'Camp 2025' }, user:{ name:'Jane Doe' }, quantityRedeemed:1, remainingUses:0 }},
-          { status:400, desc:'Already used', body:{ message:'Ticket has already been fully redeemed.' }},
-          { status:404, desc:'Not found', body:{ message:'Ticket not found.' }},
-        ]},
-      { method:'GET', path:'/api/tickets/scan-preview/:qrCode', auth:'staff+', desc:'Preview a ticket scan without marking it used',
-        pathParams:{ ':qrCode':'QR code string' },
-        responses:[{ status:200, desc:'Preview', body:{ ticket:{ qrCode:'TKT-ABC123', quantity:2, isUsed:false }, event:{ title:'Camp 2025' }, user:{ name:'Jane Doe', phoneNumber:'+27821234567' }, totalRedeemed:0 }}]},
-      { method:'POST', path:'/api/tickets/email', auth:'user+', desc:'Email own tickets as PDF attachments',
-        responses:[{ status:200, desc:'Sent', body:{ message:'Tickets emailed.', count:2 }}]},
-      { method:'POST', path:'/api/tickets/send-to', auth:'staff+', desc:'Send tickets to a specific user by email or WhatsApp',
-        request:{ body:{ userId:'user-uuid-...', eventId:'ev-uuid-...', channel:'email' }},
-        responses:[{ status:200, desc:'Sent', body:{ sent:2 }}]},
-      { method:'GET', path:'/api/tickets/event/:eventId', auth:'staff+', desc:'All tickets for an event',
-        pathParams:{ ':eventId':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'tkt-uuid-...', qrCode:'TKT-ABC123', user:{ name:'Jane Doe' }, isUsed:false, quantity:1 }]}]},
-      { method:'GET', path:'/api/tickets/scans/recent', auth:'staff+', desc:'Last 50 scan events across all events',
-        responses:[{ status:200, desc:'Success', body:[{ ticketId:'tkt-uuid-...', scannedAt:'2025-07-10T09:05:00.000Z', quantityRedeemed:1, ticket:{ user:{ name:'Jane Doe' }, event:{ title:'Camp 2025' }}, scannedBy:{ name:'Staff Member' }}]}]},
-      { method:'GET', path:'/api/tickets/scans/stats', auth:'staff+', desc:'Scan statistics grouped by event',
-        responses:[{ status:200, desc:'Success', body:[{ eventId:'ev-uuid-...', title:'Camp 2025', totalTickets:50, scanned:38, remaining:12 }]}]},
-    ]},
-
-    { title: 'Hub and licence', base: '/api/hub', endpoints: [
-      { method:'GET', path:'/health', auth:'public', desc:'Status, version, database, background jobs and last backup (503 if the database is down)',
-        responses:[{ status:200, desc:'Healthy', body:{ status:'ok', version:'1.41.0', db:true, jobs:{ mode:'queue', failedLast24h:0 }, lastBackupAt:'2026-10-26T00:00:12.000Z' }}]},
-      { method:'GET', path:'/api/hub/status', auth:'admin', desc:'Licence state (active, grace, suspended, revoked, unlicensed), Hub connection, version and update',
-        responses:[{ status:200, desc:'Success', body:{ state:'grace', readOnly:false, daysLeft:9, connected:true, version:'1.41.0', latestVersion:'1.42.0', updateAvailable:true }}]},
-      { method:'POST', path:'/api/hub/connect', auth:'admin', desc:'Connect to the Cross Events Hub with a licence key (also the /setup licence step)',
-        request:{ body:{ licenceKey:'CEH-7K2M-9QXA-P4RT-WD8C' } },
-        responses:[{ status:200, desc:'Connected (status as above)' }, { status:404, desc:'Unknown key', body:{ code:'LICENCE_NOT_FOUND', message:'That licence key was not found.' }}]},
-      { method:'POST', path:'/api/hub/heartbeat', auth:'admin', desc:'Check in with the Hub now (picks up licence changes)',
-        responses:[{ status:200, desc:'Status' }, { status:502, desc:'Hub unreachable' }]},
-      { method:'POST', path:'/api/hub/update-request', auth:'admin', desc:'Ask the Hub for this site to be updated to the latest version (the provider is told; the site never updates itself)',
-        responses:[{ status:200, desc:'Status, with updateRequest', body:{ updateAvailable:true, updateRequest:{ requestedAt:'2026-10-27T09:00:00.000Z', version:'1.42.0' } }}, { status:409, desc:'Already on the latest version', body:{ code:'UP_TO_DATE', message:'This site already runs the latest version.' }}, { status:502, desc:'Hub unreachable' }]},
-      { method:'POST', path:'/api/hub/update-request/cancel', auth:'admin', desc:'Withdraw the update request (the provider is told not to update after all)',
-        responses:[{ status:200, desc:'Status, updateRequest null' }, { status:502, desc:'Hub unreachable, or a Hub too old to withdraw requests (NOT_SUPPORTED)' }]},
-      { method:'POST', path:'/api/hub/update-snooze', auth:'admin', desc:'"Not now": no update reminders until a newer version is out. { snooze: false } turns them back on',
-        request:{ body:{ snooze:true } },
-        responses:[{ status:200, desc:'Status', body:{ updateAvailable:true, updateSnoozed:true } }, { status:400, desc:'No update, or an urgent one (can\'t be put off)' }]},
-      { method:'GET', path:'/api/hub/notices', auth:'supervisor', desc:'The provider\'s notices showing now (the dashboard banner for site admins and supervisors)',
-        responses:[{ status:200, desc:'Success', body:[{ id:'…', level:'maintenance', title:'Planned maintenance', message:'The site will be down for 30 minutes.', startsAt:'2026-11-01T16:00:00.000Z', endsAt:'2026-11-01T16:30:00.000Z' }] }]},
-    ]},
-
-    { title: 'Campuses', base: '/api/campuses', endpoints: [
-      { method:'GET', path:'/api/campuses', auth:'Public', desc:'Whether campuses are on, and the active campuses in order (empty while off)',
-        responses:[{ status:200, desc:'Success', body:{ enabled:true, campuses:[{ id:'c_1', name:'Henley Campus', slug:'henley-campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall', order:0 }] }}]},
-      { method:'GET', path:'/api/campuses/by-slug/:slug', auth:'Public', desc:'One active campus, for its /campus/<slug> page (404 when archived or campuses are off)' },
-      { method:'GET', path:'/api/campuses/admin', auth:'admin', desc:'All campuses with archived ones, event and home-campus counts, and daily-summary recipients' },
-      { method:'PUT', path:'/api/campuses/settings', auth:'admin', desc:'Turn campuses on or off (off hides campus fields and filters; nothing is deleted). Audited as campuses_toggled',
-        request:{ body:{ enabled:true } }},
-      { method:'POST', path:'/api/campuses', auth:'admin', desc:'Add a campus (slug made from the name unless given). 409 if the slug is taken',
-        request:{ body:{ name:'Henley Campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall' } }},
-      { method:'PUT', path:'/api/campuses/:id', auth:'admin', desc:'Change a campus, its daily-summary recipients (staff only) and archived state',
-        request:{ body:{ name:'Henley Campus', notifyRecipientIds:['u_1'], archived:false } }},
-      { method:'PUT', path:'/api/campuses/order', auth:'admin', desc:'Put the campuses in this order', request:{ body:{ ids:['c_2','c_1'] } }},
-      { method:'DELETE', path:'/api/campuses/:id', auth:'admin', desc:'Delete a campus with no events (409 CAMPUS_HAS_EVENTS otherwise — archive it)' },
-      { method:'GET', path:'/api/campuses/:id/audience', auth:'supervisor+', desc:'"Everyone at campus X" for broadcasts: home campus X, plus with ?registrants=true people registered for its events in the last 12 months' },
-    ]},
-
-    { title: 'Kids check-in', base: '/api/kids', endpoints: [
-      { method:'GET', path:'/api/kids/me', auth:'user', desc:'My family (children, authorised adults, parents), the family QR token, live pickup codes and pages from the last 24 hours' },
-      { method:'POST', path:'/api/kids/me', auth:'user', desc:'Start my family', request:{ body:{ name:'The Smith family' } } },
-      { method:'PUT', path:'/api/kids/me', auth:'user', desc:'Rename my family' },
-      { method:'DELETE', path:'/api/kids/me', auth:'user', desc:'Leave my family (the last parent leaving deletes it with its children)' },
-      { method:'POST', path:'/api/kids/me/children', auth:'user', desc:'Add a child (allergies, medical and custody notes are stored encrypted)',
-        request:{ body:{ firstName:'Mia', lastName:'Smith', dateOfBirth:'2021-03-04', allergies:'Peanuts', medicalNotes:'', custodyNotes:'' } } },
-      { method:'PUT', path:'/api/kids/me/children/:id', auth:'user', desc:'Change a child (custody note changes are audited)' },
-      { method:'DELETE', path:'/api/kids/me/children/:id', auth:'user', desc:'Remove a child' },
-      { method:'POST', path:'/api/kids/me/adults', auth:'user', desc:'Add an authorised adult (no account needed; up to 10)', request:{ body:{ name:'Mary Smith', phone:'0821234567', relationship:'Gran' } } },
-      { method:'PUT', path:'/api/kids/me/adults/:id', auth:'user', desc:'Change an authorised adult' },
-      { method:'DELETE', path:'/api/kids/me/adults/:id', auth:'user', desc:'Remove an authorised adult' },
-      { method:'GET', path:'/api/kids/setup-events', auth:'supervisor+', desc:'Upcoming events to set kids check-in up for (campus-scoped)' },
-      { method:'GET', path:'/api/kids/events/:eventId/settings', auth:'supervisor+', desc:'Kids check-in settings, the main tickets that can be the kids ticket and the allocation sets' },
-      { method:'PUT', path:'/api/kids/events/:eventId/settings', auth:'supervisor+', desc:'Switch kids check-in on/off and choose the kids ticket and rooms ("new" makes a free "Kids check-in" ticket or a "Kids rooms" set). Audited as kids_settings_updated',
-        request:{ body:{ enabled:true, optionId:'new', roomSetId:'new' } } },
-      { method:'GET', path:'/api/kids/events', auth:'staff+', desc:'Events with kids check-in from the last week on' },
-      { method:'GET', path:'/api/kids/events/:eventId/board', auth:'staff+', desc:'Rooms (counts, leaders on duty, full/over ratio), check-ins with allergies, medical and custody notes, and alerts for today\'s occasion. ?log=1 writes the access log' },
-      { method:'GET', path:'/api/kids/events/:eventId/families?q=', auth:'staff+', desc:'Find families by family, child or parent name, email or phone' },
-      { method:'POST', path:'/api/kids/events/:eventId/families', auth:'staff+', desc:'New family at the desk: the parent\'s account is matched by email/phone or created inactive',
-        request:{ body:{ name:'The Smith family', parent:{ name:'Anna Smith', phone:'0821234567', email:'' }, children:[{ firstName:'Mia', dateOfBirth:'2021-03-04' }] } } },
-      { method:'GET', path:'/api/kids/events/:eventId/families/qr/:token', auth:'staff+', desc:'The family for a scanned family QR code' },
-      { method:'GET', path:'/api/kids/events/:eventId/families/:familyId', auth:'staff+', desc:'One family' },
-      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/parents', auth:'staff+', desc:'Add a parent to a family' },
-      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/children', auth:'staff+', desc:'Add a child (custody notes: supervisors only)' },
-      { method:'PUT', path:'/api/kids/events/:eventId/families/:familyId/children/:childId', auth:'staff+', desc:'Change a child' },
-      { method:'POST', path:'/api/kids/events/:eventId/families/:familyId/adults', auth:'staff+', desc:'Add an authorised adult' },
-      { method:'POST', path:'/api/kids/events/:eventId/check-in', auth:'staff+', desc:'Check children in: one pickup code per family per occasion, a free place on the kids ticket the first time, a ticket usage each time. Sends the code to the parents (and optionally an authorised adult)',
-        request:{ body:{ familyId:'f_1', children:[{ childId:'c_1', roomId:'g_1' }], sendToAdultId:null } },
-        responses:[{ status:201, desc:'Checked in', body:{ code:'K7P2', qr:'KIDS-K7P2', checkIns:[{ id:'k_1', name:'Mia Smith', room:{ id:'g_1', name:'Toddlers' }, sticker:'ALLERGY: PEANUTS' }] } }] },
-      { method:'GET', path:'/api/kids/events/:eventId/code/:code', auth:'staff+', desc:'The children on a pickup code (for confirming who is collected)' },
-      { method:'POST', path:'/api/kids/events/:eventId/check-out', auth:'staff+', desc:'Check out with the pickup code. 404 WRONG_CODE raises a room alert (audited as kids_wrong_code)',
-        request:{ body:{ code:'K7P2', collectedBy:'Anna Smith', checkInIds:['k_1'] } } },
-      { method:'POST', path:'/api/kids/check-ins/:id/override', auth:'staff+', desc:'Check one child out without the code; reason and who collected required. Audited as kids_checkout_override' },
-      { method:'POST', path:'/api/kids/check-ins/:id/page', auth:'staff+', desc:'Ask the parents to come to the room (WhatsApp/email; shows on their Kids page)' },
-      { method:'PUT', path:'/api/kids/check-ins/:id/room', auth:'staff+', desc:'Move a child to another room' },
-      { method:'POST', path:'/api/kids/events/:eventId/duty', auth:'staff+', desc:'"I\'m on duty" in a room (on:false to go off), for the ratio' },
-      { method:'POST', path:'/api/kids/alerts/:id/resolve', auth:'staff+', desc:'Mark an alert as dealt with' },
-      { method:'GET', path:'/api/kids/events/:eventId/offline?deviceId=', auth:'staff+', desc:'Offline list for a desk: families, rooms, who is in, and 20 pickup codes reserved for the device' },
-      { method:'POST', path:'/api/kids/events/:eventId/sync', auth:'staff+', desc:'Sync an offline desk\'s check-ins and check-outs (idempotent by clientId). Audited as kids_offline_sync' },
-    ]},
-
-    { title: 'Event series', base: '/api/series', endpoints: [
-      { method:'GET', path:'/api/series', auth:'supervisor+', desc:'Every series with followers, eventCount and its events (campus-scoped staff see only their campuses\' events in each)' },
-      { method:'POST', path:'/api/series', auth:'supervisor+', desc:'Create a series (slug made from the name when not given). Audited as series_created',
-        request:{ body:{ name:'Family Camp', slug:'family-camp', description:'Every year in March', picture:null } } },
-      { method:'PUT', path:'/api/series/:id', auth:'supervisor+', desc:'Change a series. Audited as series_updated' },
-      { method:'DELETE', path:'/api/series/:id', auth:'admin', desc:'Delete a series; its events stay without a series and followers are dropped. Audited as series_deleted' },
-      { method:'GET', path:'/api/series/by-slug/:slug', auth:'public', desc:'The series page: details, upcoming and past public events, and following (signed in)' },
-      { method:'POST', path:'/api/series/:id/follow', auth:'user', desc:'Follow a series: an email (News & announcements) when a new event in it goes live' },
-      { method:'DELETE', path:'/api/series/:id/follow', auth:'user', desc:'Unfollow a series' },
-      { method:'GET', path:'/api/series/:id/compare', auth:'supervisor+', desc:'Year on year: registrations, tickets, income (as on the dashboard), checked in (average per session on multi-session events) and attendance rate per event in the series, oldest first, with the % change from the one before. Campus-scoped staff: their campuses\x27 events only' },
-    ]},
-
-    { title: 'Saved filters', base: '/api/saved-filters', endpoints: [
-      { method:'GET', path:'/api/saved-filters?page=', auth:'staff+', desc:'My saved filters for a list page (registrations, users, events, reports), default first' },
-      { method:'POST', path:'/api/saved-filters', auth:'staff+', desc:'Save (or replace by name) a filter: { page, name, params, isDefault? }. Up to 30 per page; making one the default clears the old default',
-        request:{ body:{ page:'registrations', name:'Camp — unpaid', params:{ event:'ev-uuid', status:'pending' }, isDefault:false } } },
-      { method:'PUT', path:'/api/saved-filters/:id', auth:'staff+', desc:'Rename it, or make it (or stop it being) my default — my own only' },
-      { method:'DELETE', path:'/api/saved-filters/:id', auth:'staff+', desc:'Delete one of my saved filters' },
-    ]},
-
-    { title: 'Dashboard and command palette', base: '/api/dashboard', endpoints: [
-      { method:'GET', path:'/api/dashboard/today', auth:'staff+', desc:'Events on today (or with a session today): places, people checked in today, children in now, volunteers rostered/checked in. Supervisors and admins also get money in (today, last 7 days) and "waiting" items: unpaid registrations for the next two weeks, parental consent, waitlist, cover requests, roster gaps, and for admins cashups due, provider payments to reconcile, privacy requests, failed webhooks. Campus-scoped' },
-      { method:'GET', path:'/api/dashboard/search?q=', auth:'staff+', desc:'Command palette search: events; supervisors also payments by amount ("R450"); admins also people and registrations by reference. { results: [{ type, id, title, subtitle, href }] }' },
-    ]},
-
-    { title: 'Outbound webhooks', base: '/api/outbound-webhooks', endpoints: [
-      { method:'GET', path:'/api/outbound-webhooks', auth:'admin', desc:'Endpoints (with last-week delivery counts per status) and the event types: registration.created, registration.paid, registration.cancelled, payment.received, payment.refunded, ticket.checked_in, user.created, event.published' },
-      { method:'POST', path:'/api/outbound-webhooks', auth:'admin', desc:'Add an endpoint (https, public address). The answer holds the signing secret — shown only now. Also added to the POPIA operator register. Audited as webhook_endpoint_changed',
-        request:{ body:{ name:'ChurchSuite sync', url:'https://example.com/hooks/cross-events', events:['registration.paid','ticket.checked_in'] } } },
-      { method:'PUT', path:'/api/outbound-webhooks/:id', auth:'admin', desc:'Change name, url, events or isActive' },
-      { method:'DELETE', path:'/api/outbound-webhooks/:id', auth:'admin', desc:'Delete an endpoint and its deliveries (its operator entry is marked inactive)' },
-      { method:'POST', path:'/api/outbound-webhooks/:id/rotate-secret', auth:'admin', desc:'A new signing secret (the old one stops at once)' },
-      { method:'POST', path:'/api/outbound-webhooks/:id/test', auth:'admin', desc:'Send a webhook.test now; answers { status, statusCode, error }' },
-      { method:'GET', path:'/api/outbound-webhooks/:id/deliveries?status=&limit=', auth:'admin', desc:'Delivery log, newest first, with payloads (kept 30 days)' },
-      { method:'POST', path:'/api/outbound-webhooks/deliveries/:id/resend', auth:'admin', desc:'Send a delivery again now' },
-    ]},
-
-    { title: 'Season passes', base: '/api/season-passes', endpoints: [
-      { method:'GET', path:'/api/season-passes?seriesId=', auth:'supervisor+', desc:'A series\x27 passes: events, normal prices, each event\x27s share, sold and unpaid counts' },
-      { method:'POST', path:'/api/season-passes', auth:'supervisor+', desc:'Create a pass. Events must be in the series; not youth (consent) events, staff-only or per-session tickets. Campus-scoped supervisors: only their campuses\x27 events. Audited as season_pass_changed',
-        request:{ body:{ seriesId:'series-uuid', name:'2027 breakfasts', price:400, saleEndsAt:null, items:[{ eventId:'ev-uuid', eventOptionId:'opt-uuid', variantId:null }] } } },
-      { method:'PUT', path:'/api/season-passes/:id', auth:'supervisor+', desc:'Change a pass (events and price only while nobody has bought it; 409 otherwise)' },
-      { method:'DELETE', path:'/api/season-passes/:id', auth:'supervisor+', desc:'Delete a pass nobody has bought' },
-      { method:'POST', path:'/api/season-passes/:id/buy', auth:'user', desc:'Buy passes: a registration at every event (lines priced at each event\x27s share), then one checkout for the total (redirectUrl), or tickets straight away when free. 409 when not on sale or an event has too few places',
-        request:{ body:{ quantity:2 } }, responses:[{ status:201, desc:'Bought', body:{ purchaseId:'uuid', total:800, paid:false, redirectUrl:'https://…', provider:'yoco', message:null } }] },
-      { method:'POST', path:'/api/season-passes/purchases/:id/checkout', auth:'user', desc:'Pay what is still owed on my purchase (a new checkout)' },
-      { method:'GET', path:'/api/season-passes/mine', auth:'user', desc:'My pass purchases with their registrations' },
-    ]},
-
-    { title: 'Volunteer rosters', base: '/api/volunteers', endpoints: [
-      { method:'GET', path:'/api/volunteers/me', auth:'user', desc:'My shifts (upcoming and the last week), cover requests I could take, and events looking for volunteers' },
-      { method:'GET', path:'/api/volunteers/events/:eventId', auth:'user', desc:'An event\'s serving roles: shift, how many are needed and signed up, whether I\'m in it, open cover requests' },
-      { method:'POST', path:'/api/volunteers/roles/:id/sign-up', auth:'user', desc:'Sign up for a role. 409 ROLE_FULL when it\'s full, 409 SHIFT_CLASH when I serve elsewhere at the same time. Gives a free volunteer place when the event has one',
-        responses:[{ status:201, desc:'Signed up', body:{ slotId:'s_1', ticket:true } }] },
-      { method:'DELETE', path:'/api/volunteers/slots/:id', auth:'user', desc:'Withdraw from a shift (not after checking in or once it\'s over). The event\'s notify recipients are emailed' },
-      { method:'POST', path:'/api/volunteers/slots/:id/swap', auth:'user', desc:'"Can\'t make it": ask for cover. The event\'s other volunteers are told; the request shows on everyone\'s Serving page', request:{ body:{ note:'Away that weekend' } } },
-      { method:'DELETE', path:'/api/volunteers/swaps/:id', auth:'user', desc:'Cancel my cover request' },
-      { method:'POST', path:'/api/volunteers/swaps/:id/accept', auth:'user', desc:'Take over someone\'s place. Happens at once (409 SWAP_CLOSED if someone was first); both volunteers and the event\'s notify recipients are told' },
-      { method:'POST', path:'/api/volunteers/check-in', auth:'user', desc:'Check in by scanning the event\'s volunteer QR code: every shift of mine on today is checked in; kids-room roles put me on duty in that room',
-        request:{ body:{ qr:'SERVE-3f2a…' } }, responses:[{ status:200, desc:'Checked in', body:{ event:{ id:'e_1', title:'Sunday service' }, checkedIn:[{ role:'Kids', kidsRoom:'Toddlers' }], already:[] } }] },
-      { method:'GET', path:'/api/volunteers/manage/events', auth:'staff+', desc:'Events with serving roles from the last 30 days on (?all=1, supervisors: every upcoming event). Campus-scoped' },
-      { method:'GET', path:'/api/volunteers/manage/events/:eventId', auth:'staff+', desc:'The roster sheet: roles with volunteers, contact details, check-ins and fill rate. ?log=1 writes the access log' },
-      { method:'GET', path:'/api/volunteers/manage/events/:eventId/qr', auth:'staff+', desc:'The volunteer check-in QR code value for the event (made the first time)' },
-      { method:'POST', path:'/api/volunteers/manage/slots/:id/check-in', auth:'staff+', desc:'Check a volunteer in by hand (undo:true to undo). Audited as volunteer_checked_in_manual' },
-      { method:'GET', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'The volunteer ticket setting, the main tickets that can be it and the event\'s kids rooms' },
-      { method:'PUT', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'Free volunteer place: optionId of a main ticket, "new" for a free "Volunteer" ticket, null for off (the default). Audited as volunteer_settings_updated', request:{ body:{ optionId:'new' } } },
-      { method:'POST', path:'/api/volunteers/manage/events/:eventId/roles', auth:'supervisor+', desc:'Add a serving role (sessionId required on multi-session events; shift times optional). Audited as volunteer_roles_changed',
-        request:{ body:{ name:'Welcome', needed:4, sessionId:null, startsAt:'2026-11-08T07:30:00.000Z', endsAt:'2026-11-08T09:30:00.000Z', description:'Front doors', kidsRoomId:null } } },
-      { method:'PUT', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Change a role' },
-      { method:'DELETE', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Delete a role (refused once someone checked in for it); its volunteers are told' },
-      { method:'POST', path:'/api/volunteers/manage/roles/:id/assign', auth:'supervisor+', desc:'Put someone on a role (allowed beyond the number needed); they\'re told. Audited as volunteer_assigned', request:{ body:{ userId:'u_1' } } },
-      { method:'DELETE', path:'/api/volunteers/manage/slots/:id', auth:'supervisor+', desc:'Take someone off a role (not after check-in); they\'re told. Audited as volunteer_removed' },
-      { method:'GET', path:'/api/volunteers/manage/hours?eventId=&from=&to=', auth:'supervisor+', desc:'Hours served per person (checked-in shifts × shift length), most first. Campus-scoped' },
-    ]},
-
-    { title: 'Privacy (POPIA)', base: '/api/privacy', endpoints: [
-      { method:'GET', path:'/api/privacy/me', auth:'user', desc:'My news opt-in, its history, and my privacy requests',
-        responses:[{ status:200, desc:'Success', body:{ news:{ email:true, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z', canWhatsApp:false, notificationPreference:'email', history:[{ channel:'email', granted:true, source:'signup', createdAt:'2026-10-23T08:00:00.000Z' }], requests:[] }}]},
-      { method:'PUT', path:'/api/privacy/me/news', auth:'user', desc:'Change the News & announcements opt-in per channel (source "prompt" for the one-time question after login)',
-        request:{ body:{ email:false, whatsapp:false } },
-        responses:[{ status:200, desc:'Saved', body:{ news:{ email:false, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z' }}]},
-      { method:'GET', path:'/api/privacy/me/export', auth:'user', desc:'Download my data — JSON, or ?format=pdf for a readable PDF. Blocked while impersonating',
-        responses:[{ status:200, desc:'File download' }]},
-      { method:'POST', path:'/api/privacy/me/requests', auth:'user', desc:'Correction request ({ type:"correction", details }) or delete my account ({ type:"deletion", password }) — deletion closes the account at once',
-        request:{ body:{ type:'correction', details:'My son\'s date of birth on the Camp registration is wrong — it should be 3 May 2012.' } },
-        responses:[{ status:201, desc:'Created', body:{ request:{ id:'req-uuid-...', type:'correction', status:'open', dueAt:'2026-11-22T08:00:00.000Z' }, message:'Your request was sent.' }}, { status:409, desc:'Already open', body:{ message:'You already have an open correction request.' }}]},
-      { method:'GET', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'What an unsubscribe link (signed token) is for',
-        responses:[{ status:200, desc:'Success', body:{ kind:'account', email:'jo***@example.com', hasPhone:true, news:{ email:true, whatsapp:true } }}]},
-      { method:'POST', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'Unsubscribe from news ({ channels?: ["email","whatsapp"] }, default both)',
-        responses:[{ status:200, desc:'Done', body:{ message:'You have been unsubscribed.' }}]},
-      { method:'POST', path:'/api/privacy/unsubscribe/:token/one-click', auth:'public', desc:'RFC 8058 one-click unsubscribe from the List-Unsubscribe email header (email news off)',
-        responses:[{ status:200, desc:'Done' }]},
-      { method:'GET', path:'/api/privacy/requests', auth:'admin', desc:'Data requests inbox (?status=open|closed|all), with due dates and, for deletions, the registrations still blocking it',
-        responses:[{ status:200, desc:'Success', body:{ requests:[{ id:'req-uuid-...', type:'deletion', status:'open', name:'Jane Doe', email:'jane@example.com', dueAt:'2026-11-22T08:00:00.000Z', overdue:false, blockers:[] }], openCount:1 }}]},
-      { method:'POST', path:'/api/privacy/requests/:id/complete', auth:'admin', desc:'Complete a request (emailed to the person). Deletion anonymises the account; 409 while it has a registration for an upcoming event',
-        request:{ body:{ response:'Corrected the date of birth on the Camp 2026 registration.' } },
-        responses:[{ status:200, desc:'Completed', body:{ request:{ status:'completed' }, anonymised:null }}]},
-      { method:'POST', path:'/api/privacy/requests/:id/reject', auth:'admin', desc:'Reject a request, or mark it withdrawn (cancelled:true); a deletion request reopens the account',
-        request:{ body:{ response:'We could not find a registration with that name.', cancelled:false } },
-        responses:[{ status:200, desc:'Closed', body:{ request:{ status:'rejected' } }}]},
-      { method:'GET', path:'/api/privacy/notice', auth:'public', desc:'The privacy notice (current, or ?version=N) with org details and the operator list filled in. Version 0 = built-in, until one is published',
-        responses:[{ status:200, desc:'Success', body:{ version:2, builtIn:false, current:true, effectiveDate:'23 October 2026', changeSummary:'We added WhatsApp news.', sections:[{ id:'introduction', title:'1. Introduction', body:'Hope Church values your privacy…' }], versions:[{ version:2, publishedAt:'2026-10-23T10:00:00.000Z', requiresAcceptance:true }] }}]},
-      { method:'POST', path:'/api/privacy/me/notice/accept', auth:'user', desc:'Accept the current privacy notice version',
-        responses:[{ status:200, desc:'Accepted', body:{ version:2 }}]},
-      { method:'GET', path:'/api/privacy/notice/draft', auth:'admin', desc:'Notice editor: draft (or current) sections, rendered preview, published versions with acceptance counts, built-in text',
-        responses:[{ status:200, desc:'Success', body:{ sections:[], rendered:[], isDraft:false, savedAt:null, versions:[{ version:1, acceptances:12 }] }}]},
-      { method:'PUT', path:'/api/privacy/notice/draft', auth:'admin', desc:'Save the draft ({ sections: [{ id?, title, body }] })',
-        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }] } },
-        responses:[{ status:200, desc:'Saved', body:{ isDraft:true }}]},
-      { method:'DELETE', path:'/api/privacy/notice/draft', auth:'admin', desc:'Discard the draft',
-        responses:[{ status:200, desc:'Discarded', body:{ message:'Draft discarded.' }}]},
-      { method:'POST', path:'/api/privacy/notice/publish', auth:'admin', desc:'Publish the next version; requiresAcceptance asks everyone to accept it after their next login (needs changeSummary)',
-        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }], changeSummary:'We added WhatsApp news.', requiresAcceptance:true } },
-        responses:[{ status:201, desc:'Published', body:{ version:2, requiresAcceptance:true }}]},
-      { method:'GET', path:'/api/privacy/operators', auth:'admin', desc:'The operator register (third parties that process personal information)',
-        responses:[{ status:200, desc:'Success', body:[{ id:'op-uuid-...', name:'PayFast', purpose:'Online payments', dataShared:'Name, email address, payment amount and reference', location:'South Africa', website:'https://payfast.io', active:true }] }]},
-      { method:'POST', path:'/api/privacy/operators', auth:'admin', desc:'Add an operator (PUT/DELETE /api/privacy/operators/:id to change or remove)',
-        request:{ body:{ name:'Mailgun', purpose:'Sending emails', dataShared:'Name, email address, message content', location:'EU' } },
-        responses:[{ status:201, desc:'Created' }]},
-      { method:'GET', path:'/api/privacy/consent-log', auth:'admin', desc:'Consent records: ?type=news|notice|parental, ?q= name/email, ?page=',
-        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', name:'Jane Doe', email:'jane@example.com', channel:'email', granted:false, source:'unsubscribe_link' }] }}]},
-      { method:'GET', path:'/api/privacy/readiness', auth:'admin', desc:'POPIA readiness checklist with a score; each open item has a link to fix it',
-        responses:[{ status:200, desc:'Success', body:{ score:77, passed:10, total:13, checks:[{ key:'notice', label:'Privacy notice published', ok:true, detail:'2 versions published', href:'/dashboard/admin/privacy?tab=notice', applies:true }] }}]},
-      { method:'GET', path:'/api/privacy/retention', auth:'admin', desc:'Retention policies, what the next run would affect, and the last run',
-        responses:[{ status:200, desc:'Success', body:{ policies:{ inactive_accounts:{ enabled:true, months:60 } }, preview:{ inactive_accounts:{ toWarn:3, toAnonymise:0 } }, reviewedAt:null }}]},
-      { method:'PUT', path:'/api/privacy/retention', auth:'admin', desc:'Save the retention policies (all five)',
-        request:{ body:{ policies:{ inactive_accounts:{ enabled:true, months:60 }, form_answers:{ enabled:true, months:12 }, login_history:{ enabled:true, months:24 }, payment_details:{ enabled:true, months:24 }, audit_logs:{ enabled:true, months:60 } } } },
-        responses:[{ status:200, desc:'Saved' }]},
-      { method:'POST', path:'/api/privacy/retention/run', auth:'admin', desc:'Run the retention job now (warn/anonymise inactive accounts, delete expired data)',
-        responses:[{ status:200, desc:'Done', body:{ result:{ inactive_accounts:{ warned:3, anonymised:0, waiting:0 }, login_history:{ deleted:120 } } }}]},
-      { method:'GET', path:'/api/privacy/breaches', auth:'admin', desc:'The breach register (security compromises); POST to record one, PUT /:id to update or mark the Regulator/people told',
-        responses:[{ status:200, desc:'Success', body:[{ id:'br-uuid-...', title:'Phone with the attendee list lost', status:'open', discoveredAt:'2026-10-23T08:00:00.000Z', regulatorNotifiedAt:null }] }]},
-      { method:'GET', path:'/api/privacy/access-log', auth:'admin', desc:'Bulk exports/views of personal information: ?action=, ?actorId=, ?sensitive=true, ?from=, ?to=, ?page=',
-        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', actor:'Sam Supervisor', action:'report_pdf', what:'Camp 2026 attendees', records:48 }] }}]},
-    ]},
-
-    { title: 'Broadcasts (Email)', base: '/api/broadcasts', endpoints: [
-      { method:'POST', path:'/api/broadcasts/preview', auth:'supervisor+', desc:'Dry-run a broadcast — returns resolved recipient list without sending',
-        request:{ body:{ userIds:['user-uuid-1','user-uuid-2'], emails:'extra@example.com\nJohn <john@example.com>', eventId:'ev-uuid-...' }},
-        responses:[{ status:200, desc:'Preview', body:{ matched:3, recipients:[{ email:'jane@example.com', name:'Jane Doe' },{ email:'extra@example.com', name:null }] }}]},
-      { method:'POST', path:'/api/broadcasts/send', auth:'supervisor+', desc:'Send an email broadcast to users and/or ad-hoc addresses',
-        request:{ body:{ subject:'Important update', text:'Hi {{name}}, here is a message for you.', userIds:['user-uuid-1'], emails:'extra@example.com', eventId:'ev-uuid-...' }},
-        responses:[{ status:200, desc:'Sent', body:{ matched:2, sent:2 }}]},
-      { method:'POST', path:'/api/broadcasts/schedule', auth:'supervisor+', desc:'Schedule an email broadcast for a future time',
-        request:{ body:{ subject:'Save the date!', text:'Hi {{name}}, mark your calendar for {{event.title}}.', userIds:['user-uuid-1'], scheduledAt:'2025-06-01T09:00:00.000Z', eventId:'ev-uuid-...' }},
-        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued', scheduledAt:'2025-06-01T09:00:00.000Z' }}}]},
-    ]},
-
-    { title: 'Broadcasts (WhatsApp)', base: '/api/whatsapp-broadcasts', endpoints: [
-      { method:'POST', path:'/api/whatsapp-broadcasts/preview', auth:'supervisor+', desc:'Dry-run — resolve phone list without sending',
-        request:{ body:{ userIds:['user-uuid-1'], phones:'0821234567\nJane <0721234567>', eventId:'ev-uuid-...' }},
-        responses:[{ status:200, desc:'Preview', body:{ matched:2, recipients:[{ phone:'+27821234567', name:'Jane Doe' }] }}]},
-      { method:'POST', path:'/api/whatsapp-broadcasts/send', auth:'supervisor+', desc:'Send a WhatsApp broadcast',
-        request:{ body:{ message:'Hi {{name}}, please check your tickets for {{event.title}}.', userIds:['user-uuid-1'], phones:'0821234567', eventId:'ev-uuid-...' }},
-        responses:[{ status:200, desc:'Sent', body:{ matched:2, sent:2 }}]},
-      { method:'POST', path:'/api/whatsapp-broadcasts/schedule', auth:'supervisor+', desc:'Schedule a WhatsApp broadcast',
-        request:{ body:{ message:'Hi {{name}}! {{event.title}} is tomorrow. See you there 🙌', userIds:['user-uuid-1'], scheduledAt:'2025-07-09T08:00:00.000Z' }},
-        responses:[{ status:201, desc:'Scheduled', body:{ job:{ id:'job-uuid-...', status:'queued' }}}]},
-    ]},
-
-    { title: 'Scheduled Messages', base: '/api/scheduled-emails', endpoints: [
-      { method:'GET', path:'/api/scheduled-emails', auth:'supervisor+', desc:'List all scheduled jobs — email and WhatsApp. Jobs sent more than 7 days ago are hidden.',
-        responses:[{ status:200, desc:'Success', body:{ jobs:[{ id:'job-uuid-...', channel:'email', broadcast:false, eventId:'ev-uuid-...', status:'queued', scheduledAt:'2025-07-03T09:00:00.000Z', attempts:0, payload:{ subject:'Camp reminder' }}]}}]},
-      { method:'PATCH', path:'/api/scheduled-emails/:id', auth:'supervisor+', desc:'Edit a queued job — reschedule or update its message content',
-        pathParams:{ ':id':'Scheduled job UUID' },
-        request:{ body:{ scheduledAt:'2025-07-04T09:00:00.000Z', subject:'Updated subject', text:'Hi {{name}}, updated message.' }},
-        responses:[
-          { status:200, desc:'Updated', body:{ id:'job-uuid-...', scheduledAt:'2025-07-04T09:00:00.000Z', status:'queued' }},
-          { status:400, desc:'Already sent', body:{ message:'Cannot edit a job that has already been sent.' }},
-        ]},
-      { method:'DELETE', path:'/api/scheduled-emails/:id', auth:'supervisor+', desc:'Cancel and remove a queued job',
-        pathParams:{ ':id':'Scheduled job UUID' },
-        responses:[{ status:200, desc:'Deleted', body:{ message:'Scheduled job removed.' }}]},
-    ]},
-
-    { title: 'Automations', base: '/api/automations', endpoints: [
-      { method:'POST', path:'/api/automations/schedule', auth:'supervisor+', desc:'Schedule multiple lifecycle email automations for an event in one call (pre-event, final reminder, thank-you, promo).',
-        request:{ body:{ eventId:'ev-uuid-...', jobs:[
-          { subject:'1 Week to Go: Camp 2025!', text:'Hi {{name}}, camp is one week away!\n\nDetails: {{event.link}}', scheduledAt:'2025-07-03T09:00:00.000Z' },
-          { subject:"We'll See You Tomorrow!", text:'Hi {{name}}, final reminder for {{event.title}}. Please have your QR code ready.', scheduledAt:'2025-07-09T09:00:00.000Z' },
-        ]}},
-        responses:[{ status:201, desc:'Scheduled', body:{ message:'2 automation(s) scheduled.', jobs:[{ id:'job-uuid-1', status:'queued' },{ id:'job-uuid-2', status:'queued' }] }}]},
-    ]},
-
-    { title: 'Reports', base: '/api/reports', endpoints: [
-      { method:'POST', path:'/api/reports/excel', auth:'Bearer', desc:'Build an Excel file from a report payload' },
-      { method:'POST', path:'/api/reports/whatsapp', auth:'Bearer', desc:'Send a report PDF by WhatsApp' },
-      { method:'POST', path:'/api/reports/pdf', auth:'user+', desc:'Generate a PDF report of own registrations and tickets and return it as a binary download',
-        responses:[{ status:200, desc:'PDF file (application/pdf)', body:'<binary PDF>' }]},
-      { method:'POST', path:'/api/reports/email', auth:'user+', desc:'Generate PDF report and email it to the authenticated user',
-        responses:[{ status:200, desc:'Sent', body:{ message:'Report emailed.' }}]},
-    ]},
-
-    { title: 'Costs', base: '/api/events/:eventId/costs', endpoints: [
-      { method:'GET', path:'/api/events/:eventId/costs', auth:'supervisor+', desc:'List costs (once-off or per-item) for an event',
-        pathParams:{ ':eventId':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:[{ id:'cost-uuid-...', label:'Venue hire', costType:'once_off', amount:2500 },{ id:'cost-uuid-2', label:'Catering', costType:'per_item', amount:75, eventOptionId:'opt-uuid-...' }]}]},
-      { method:'POST', path:'/api/events/:eventId/costs', auth:'admin', desc:'Create a cost for an event. eventOptionId is required when costType is per_item. paidFromMethod (cash/card/eft/other) optionally tags which float it was paid out of. Rejected once the event is closed.',
-        pathParams:{ ':eventId':'Event UUID' },
-        request:{ body:{ label:'Catering', costType:'per_item', amount:75, eventOptionId:'opt-uuid-...', paidFromMethod:'cash' }},
-        responses:[{ status:201, desc:'Created', body:{ id:'cost-uuid-new', label:'Catering', costType:'per_item', amount:75, paidFromMethod:'cash' }}]},
-      { method:'PUT', path:'/api/costs/:id', auth:'admin', desc:'Update a cost. Rejected once the event is closed.',
-        pathParams:{ ':id':'EventCost UUID' },
-        request:{ body:{ amount:80 }},
-        responses:[{ status:200, desc:'Updated', body:{ id:'cost-uuid-...', amount:80 }}]},
-      { method:'DELETE', path:'/api/costs/:id', auth:'admin', desc:'Delete a cost. Rejected once the event is closed.',
-        pathParams:{ ':id':'EventCost UUID' },
-        responses:[{ status:200, desc:'Deleted', body:{ message:'Cost deleted' }}]},
-    ]},
-
-    { title: 'Cashups', base: '/api/cashups', endpoints: [
-      { method:'GET', path:'/api/cashups/event/:eventId/cash-by-user', auth:'supervisor+', desc:'Payments recorded for an event, by staff member and method' },
-      { method:'PUT', path:'/api/cashups/event/:eventId/person-cash/:userId', auth:'supervisor+', desc:'Enter one staff member\'s physical cash count for an event' },
-      { method:'GET', path:'/api/cashups/event/:eventId', auth:'supervisor+', desc:'Live cashup preview for an event: system income vs. reconciled actual per method, method-tagged costs, unallocated donations, net profit, and the full close/reopen history',
-        pathParams:{ ':eventId':'Event UUID' },
-        responses:[{ status:200, desc:'Success', body:{ event:{ id:'ev-uuid-...', title:'Camp 2025', cashupStatus:'open' }, paymentsByMethod:{ cash:1200, card:4500, eft:600, other:0 }, expectedCashByMethod:{ cash:1150, card:4500, eft:600, other:0 }, unallocatedDonationsTotal:150, totalCosts:900, netProfit:6450, history:[] }}]},
-      { method:'PUT', path:'/api/cashups/event/:eventId/draft', auth:'admin', desc:'Save in-progress reconciliation entries (actual counted amounts, and cash denomination counts, per method) without closing the event',
-        pathParams:{ ':eventId':'Event UUID' },
-        request:{ body:{ lines:[{ method:'cash', denominations:[{ value:100, count:5 },{ value:50, count:2 }] },{ method:'card', actualAmount:4500 }] }},
-        responses:[{ status:200, desc:'Saved', body:{ message:'Draft saved' }}]},
-      { method:'POST', path:'/api/cashups/event/:eventId/close', auth:'admin', desc:'Close the event. Pass "lines" for a full per-method cashup (variances computed against expected cash, i.e. income minus any method-tagged costs) — for the cash line, pass "denominations" and the actual amount is computed from the note/coin counts server-side. Omit "lines" for a quick close that accepts system numbers as-is. Either way, unallocated donations are counted as profit and the event is fully locked (no new registrations, payments, refunds, checkouts, or donations) until an admin reopens it. Creates a permanent EventCashup audit row.',
-        pathParams:{ ':eventId':'Event UUID' },
-        request:{ body:{ lines:[{ method:'cash', denominations:[{ value:100, count:5 },{ value:50, count:2 }], notes:'R20 short' }], notes:'Closed after evening service' }},
-        responses:[{ status:201, desc:'Closed', body:{ id:'cashup-uuid-...', action:'closed', unallocatedDonationsTotal:150, totalCosts:900, totalExpectedRevenue:6300, totalActualRevenue:6280 }}]},
-      { method:'POST', path:'/api/cashups/event/:eventId/reopen', auth:'admin', desc:'Reopen a closed event, unlocking registrations/payments/donations again. Admin-only. Creates a permanent "reopened" EventCashup audit row.',
-        pathParams:{ ':eventId':'Event UUID' },
-        request:{ body:{ notes:'Reopening to correct a miscounted cash drawer' }},
-        responses:[{ status:201, desc:'Reopened', body:{ id:'cashup-uuid-...', action:'reopened' }}]},
-      { method:'GET', path:'/api/cashups/audit', auth:'supervisor+', desc:'Flat audit log of every close/quick-close/reopen across events, optionally filtered by eventId and/or from/to dates',
-        request:{ query:{ eventId:'ev-uuid-... (optional)', from:'2026-01-01 (optional)', to:'2026-12-31 (optional)' }},
-        responses:[{ status:200, desc:'Success', body:[{ id:'cashup-uuid-...', action:'closed', event:{ id:'ev-uuid-...', title:'Camp 2025' }, performedBy:{ name:'Jane Supervisor' }, createdAt:'2026-07-20T18:00:00.000Z' }]}]},
-    ]},
-
-    { title: 'Uploads', base: '/api/uploads', endpoints: [
-      { method:'POST', path:'/api/uploads/logo', auth:'admin (open during first-run setup)', desc:'Upload the site logo (multipart, field "image")' },
-      { method:'POST', path:'/api/uploads/favicon', auth:'admin (open during first-run setup)', desc:'Upload the site favicon (multipart, field "image")' },
-      { method:'POST', path:'/api/uploads/event-image', auth:'supervisor+', desc:'Upload an event cover image. Send as multipart/form-data with field name "image". Returns the public URL.',
-        notes:'Content-Type must be multipart/form-data. Max size is typically 5 MB.',
-        responses:[
-          { status:200, desc:'Uploaded', body:{ url:'/uploads/event-images/camp-2025-abc123.jpg' }},
-          { status:400, desc:'No file', body:{ message:'No image file provided.' }},
-        ]},
-    ]},
-
-    { title: 'Sections', base: '/api/sections', endpoints: [
-      { method:'GET', path:'/api/sections', auth:'staff+', desc:'List all sections with their allowed options',
-        responses:[{ status:200, desc:'Success', body:[{ id:'sec-uuid-...', eventId:'ev-uuid-...', name:'Adults', allowedOptions:[{ eventOptionId:'opt-uuid-...', eventOption:{ name:'Adult', price:450 }}] }]}]},
-      { method:'POST', path:'/api/sections', auth:'supervisor+', desc:'Create a section for an event',
-        request:{ body:{ eventId:'ev-uuid-...', name:'Adults', optionIds:['opt-uuid-1','opt-uuid-2'] }},
-        responses:[{ status:201, desc:'Created', body:{ id:'sec-uuid-new', name:'Adults', eventId:'ev-uuid-...' }}]},
-      { method:'PUT', path:'/api/sections/:id', auth:'supervisor+', desc:'Update a section',
-        pathParams:{ ':id':'Section UUID' },
-        request:{ body:{ name:'Adults & Teens', optionIds:['opt-uuid-1','opt-uuid-2','opt-uuid-3'] }},
-        responses:[{ status:200, desc:'Updated', body:{ id:'sec-uuid-...', name:'Adults & Teens' }}]},
-      { method:'DELETE', path:'/api/sections/:id', auth:'admin', desc:'Delete a section',
-        pathParams:{ ':id':'Section UUID' },
-        responses:[{ status:200, desc:'Deleted', body:{ message:'Section deleted.' }}]},
-    ]},
-
-    { title: 'Banner', base: '/api/banner', endpoints: [
-      { method:'GET', path:'/api/banner', auth:'public', desc:'Get the current site-wide announcement banner',
-        responses:[
-          { status:200, desc:'Banner set', body:{ message:'Registration for Camp 2025 is now open!', type:'info', active:true }},
-          { status:200, desc:'No banner', body:{ message:null, active:false }},
-        ]},
-      { method:'POST', path:'/api/banner', auth:'supervisor+', desc:'Set or update the site banner',
-        request:{ body:{ message:'Registration is now closed.', type:'warning', active:true }},
-        responses:[{ status:200, desc:'Saved', body:{ message:'Registration is now closed.', type:'warning', active:true }}]},
-    ]},
-
-    { title: 'Forms', base: '/api/forms', endpoints: [
-      { method:'GET', path:'/api/forms/responses', auth:'staff+', desc:'List all submitted form responses across all events',
-        queryParams:{ eventId:'Filter by event UUID', page:'Page (default 1)', limit:'Per page (default 20)' },
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'resp-uuid-...', registrationId:'reg-uuid-...', createdAt:'2025-06-01T10:05:00.000Z', answers:[{ field:{ label:'Dietary requirements' }, value:'Vegetarian' }] }], total:1 }}]},
-    ]},
-
-    { title: 'Provider Transactions', base: '/api/provider-transactions', endpoints: [
-      { method:'GET', path:'/api/provider-transactions', auth:'supervisor+', desc:'Transactions payment providers sent by webhook (also at /api/yoco-transactions)',
-        queryParams:{ provider:'yoco', reconciled:'true|false', ignored:'true|false' },
-        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_abc', amount:45000, currency:'ZAR', reconciled:true, paymentId:'pay-uuid-...', createdDate:'2025-06-01T11:00:00.000Z' }] }}]},
-      { method:'GET', path:'/api/provider-transactions/unreconciled', auth:'supervisor+', desc:'Transactions not yet matched to a payment record',
-        queryParams:{ provider:'yoco' },
-        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_xyz', amount:45000, currency:'ZAR', reconciled:false }] }}]},
-      { method:'POST', path:'/api/provider-transactions/:id/reconcile', auth:'supervisor+', desc:'Record the transaction as a payment on a registration, or as a donation to an event',
-        pathParams:{ ':id':'ProviderTransaction UUID' },
-        request:{ body:{ registrationId:'reg-uuid-...', eventId:'(donation) event-uuid-...', userId:'(donation, optional) user-uuid-...' }},
-        responses:[{ status:200, desc:'Reconciled', body:{ success:true, data:{ transaction:{ id:'ptx-uuid-...', reconciled:true, paymentId:'pay-uuid-...' }, payment:{ id:'pay-uuid-...', provider:'yoco' } } }}]},
-      { method:'POST', path:'/api/provider-transactions/:id/ignore', auth:'supervisor+', desc:'Mark a transaction as intentionally ignored',
-        pathParams:{ ':id':'ProviderTransaction UUID' },
-        responses:[{ status:200, desc:'Ignored', body:{ success:true, data:{ id:'ptx-uuid-...', ignored:true } }}]},
-    ]},
-
-    { title: 'WhatsApp Admin', base: '/api/whatsapp', endpoints: [
-      { method:'POST', path:'/api/whatsapp/start', auth:'admin', desc:'Start (or restart) the WAWP WhatsApp instance' },
-      { method:'POST', path:'/api/whatsapp/request-code', auth:'admin', desc:'Request a pairing code to link a WhatsApp number' },
-      { method:'POST', path:'/api/whatsapp/delete-instance', auth:'admin', desc:'Delete the WAWP instance' },
-      { method:'POST', path:'/api/whatsapp/webhook', auth:'—', desc:'WAWP event webhook (alias of /api/webhooks/whatsapp)' },
-      { method:'GET', path:'/api/whatsapp/config', auth:'admin', desc:'Get the currently stored WAWP credentials from DB (tokens are partially masked)',
-        responses:[{ status:200, desc:'Success', body:{ instanceId:'wawp-instance-abc', accessToken:'eyJ...****', source:'db' }}]},
-      { method:'POST', path:'/api/whatsapp/config', auth:'admin', desc:'Save WAWP credentials to the database (AppSetting). Takes effect immediately; no restart needed.',
-        request:{ body:{ accessToken:'eyJhbGciOiJSUzI1...', instanceId:'wawp-instance-abc' }},
-        responses:[{ status:200, desc:'Saved', body:{ message:'WhatsApp config saved.' }}]},
-      { method:'GET', path:'/api/whatsapp/status', auth:'admin', desc:'Get the current WAWP session status',
-        responses:[
-          { status:200, desc:'Connected', body:{ status:'open', phoneNumber:'+27821234567', pushName:'Cross Code' }},
-          { status:200, desc:'Not connected', body:{ status:'close' }},
-        ]},
-      { method:'GET', path:'/api/whatsapp/qr', auth:'admin', desc:'Get a QR code image/string to link a WhatsApp account',
-        responses:[{ status:200, desc:'Success', body:{ qr:'data:image/png;base64,...', qrString:'2@abc123...' }}]},
-      { method:'POST', path:'/api/whatsapp/create-instance', auth:'admin', desc:'Create a new WAWP session instance',
-        responses:[{ status:200, desc:'Created', body:{ instanceId:'wawp-instance-new', message:'Instance created.' }}]},
-      { method:'POST', path:'/api/whatsapp/restart', auth:'admin', desc:'Restart the current WAWP instance',
-        responses:[{ status:200, desc:'Restarted', body:{ message:'Instance restarted.' }}]},
-      { method:'POST', path:'/api/whatsapp/logout', auth:'admin', desc:'Log out the current WhatsApp session',
-        responses:[{ status:200, desc:'Logged out', body:{ message:'Logged out.' }}]},
-    ]},
-
-    { title: 'Dashboard stats', base: '/api/stats', endpoints: [
-      { method:'GET', path:'/api/stats/staff', auth:'staff+', desc:'Everything the staff dashboard needs, in one call' },
-      { method:'GET', path:'/api/stats/supervisor', auth:'supervisor+', desc:'Everything the supervisor dashboard needs, in one call' },
-      { method:'GET', path:'/api/stats/admin', auth:'admin', desc:'Everything the admin dashboard needs, in one call' },
-      { method:'GET', path:'/api/stats/overview', auth:'supervisor+', desc:'Trailing-month KPIs (registrations, tickets, revenue, donations), revenue trend, top events, funnel conversion. ?campus=<id|slug|all> for one campus or church-wide events only' },
-    ]},
-    { title: 'Backups', base: '/api/backups', endpoints: [
-      { method:'GET', path:'/api/backups', auth:'admin', desc:'Local database backups, newest first' },
-      { method:'POST', path:'/api/backups/run', auth:'admin', desc:'Run a backup now' },
-      { method:'GET', path:'/api/backups/:filename/download', auth:'admin', desc:'Download a backup file' },
-    ]},
-    { title: 'Webhooks', base: '/api/webhooks', endpoints: [
-      { method:'POST', path:'/api/webhooks/payfast', auth:'PayFast ITN', desc:'PayFast payment notification (form-encoded). Checked as PayFast requires: signature, PayFast host, VALID from /eng/query/validate, and amount_gross equal to the checkout (otherwise held for review). COMPLETE records the payment.' },
-      { method:'POST', path:'/api/webhooks/yoco', auth:'HMAC', desc:'Yoco payment event webhook. Called by Yoco servers. Verified via HMAC-SHA256 signature in the X-Yoco-Signature header.',
-        notes:'This endpoint bypasses the global rate limiter. Raw body is parsed before JSON middleware. Refreshes early-bird pricing before computing totalDue to ensure accurate paid/partial status.',
-        request:{ body:{ id:'evt_yoco_abc', type:'payment.succeeded', payload:{ metadata:{ checkoutId:'checkout-id-...' }, amount:45000, currency:'ZAR' }}},
-        responses:[{ status:200, desc:'Acknowledged', body:{ received:true }}]},
-      { method:'POST', path:'/api/webhooks/whatsapp', auth:'—', desc:'WAWP inbound message event. Called by WAWP servers when a message arrives on the linked number.',
-        responses:[{ status:200, desc:'Acknowledged', body:{ received:true }}]},
-    ]},
-
-    { title: 'PayFast', base: '/api/payfast', endpoints: [
-      { method:'GET', path:'/api/payfast/config', auth:'admin', desc:'PayFast settings (passphrase masked), mode and the ITN notify URL (with a warning when PayFast can\'t reach it).' },
-      { method:'PUT', path:'/api/payfast/config', auth:'admin', desc:'Save merchantId, merchantKey, passphrase (encrypted) and/or mode (sandbox|live). Audit logged.' },
-      { method:'POST', path:'/api/payfast/test', auth:'admin', desc:'Check the saved merchant ID and passphrase with PayFast (signed API ping).' },
-    ]},
-    { title: 'Yoco', base: '/api/yoco', endpoints: [
-      { method:'GET', path:'/api/yoco/config', auth:'admin', desc:'Yoco settings with secrets masked (prefix + last 3 characters), where each comes from (db, env or none), test/live mode and the default webhook URL.',
-        responses:[{ status:200, desc:'Success', body:{ secretKeyMasked:'sk_test_***************aba', secretKeySource:'db', mode:'test', webhookSecretMasked:'whsec_*****************1Xz', webhookSecretSource:'db', webhookId:'sub_123', webhookUrl:'https://api.example.com/api/webhooks/yoco', configured:true }}]},
-      { method:'PUT', path:'/api/yoco/config', auth:'admin', desc:'Save the secret key and/or webhook secret (stored AES-256-GCM encrypted). A new secret key is checked against Yoco first. An empty string clears the value (the .env fallback then applies).',
-        request:{ body:{ secretKey:'sk_test_...', webhookSecret:'whsec_...' }},
-        responses:[{ status:200, desc:'Saved', body:{ message:'Yoco settings saved' }}]},
-      { method:'GET', path:'/api/yoco/webhooks', auth:'admin', desc:'Webhooks registered on the Yoco account, flagged isActive (its secret is the stored one) and pointsHere (URL is this server).',
-        responses:[{ status:200, desc:'Success', body:{ webhooks:[{ id:'sub_123', name:'hope-events', url:'https://api.example.com/api/webhooks/yoco', mode:'test', isActive:true, pointsHere:true }], defaultUrl:'https://api.example.com/api/webhooks/yoco' }}]},
-      { method:'POST', path:'/api/yoco/webhooks', auth:'admin', desc:'Register a webhook at Yoco (defaults: name "hope-events", URL = BACKEND_URL/api/webhooks/yoco) and store the secret Yoco returns. The URL must be public https.',
-        request:{ body:{ name:'hope-events', url:'https://api.example.com/api/webhooks/yoco' }},
-        responses:[{ status:201, desc:'Registered', body:{ message:'Webhook registered and its secret saved', webhook:{ id:'sub_123', name:'hope-events', url:'https://api.example.com/api/webhooks/yoco', mode:'test' }, webhookSecretMasked:'whsec_*****************1Xz' }}]},
-      { method:'DELETE', path:'/api/yoco/webhooks/:id', auth:'admin', desc:'Delete a webhook at Yoco. If it was the active one, the stored webhook secret is cleared too.',
-        responses:[{ status:200, desc:'Deleted', body:{ message:'Webhook deleted', clearedSecret:false }}]},
-    ]},
-
-    { title: 'Settings', base: '/api/settings', endpoints: [
-      { method:'GET', path:'/api/settings', auth:'public', desc:'Public settings — org name, brand colours (primary/secondary/accent), logo URL, favicon URL, legal page slugs, registration notification email (no secrets)',
-        responses:[{ status:200, desc:'Success', body:{ org_name:'Cross Code', org_tagline:'Event management, made simple', primary_color:'#4F46E5', secondary_color:'#8B5CF6', accent_color:'#EC4899', logo_url:'/uploads/branding/logo-123.png', favicon_url:'/uploads/branding/favicon-123.png' }}]},
-      { method:'GET', path:'/api/settings/all', auth:'admin', desc:'All settings including SMTP config. smtp_pass is returned masked (••••••••); smtp_user is returned decrypted.',
-        responses:[{ status:200, desc:'Success', body:[{ key:'smtp_host', value:'smtp.example.com' },{ key:'smtp_user', value:'user@example.com' },{ key:'smtp_pass', value:'••••••••' }]}]},
-      { method:'GET', path:'/api/settings/needs-setup', auth:'public', desc:'Returns true until the setup wizard has been completed (setup_complete flag is set).',
-        responses:[{ status:200, desc:'Success', body:{ needsSetup:true }}]},
-      { method:'PUT', path:'/api/settings', auth:'admin', desc:'Upsert one or more settings. smtp_user and smtp_pass are AES-256-GCM encrypted before storage. Sending •••••••• for smtp_pass is a no-op.',
-        request:{ body:{ org_name:'Cross Code', smtp_host:'smtp.gmail.com', smtp_port:'587', smtp_user:'user@gmail.com', smtp_pass:'app-password' }},
-        responses:[{ status:200, desc:'Saved', body:{ message:'Settings saved.' }}]},
-      { method:'POST', path:'/api/settings/test-smtp', auth:'admin (or setup token)', desc:'Test the SMTP connection with provided credentials. On success, sends a real test email to the authenticated admin and returns a friendly message. On failure, returns a human-readable message plus a raw field containing the original SMTP error for debugging. Error code 530 (Microsoft "Client not authenticated") maps to the authentication-failure message.',
-        request:{ body:{ host:'smtp.gmail.com', port:587, secure:false, user:'me@gmail.com', pass:'app-password', from:'me@gmail.com' }},
-        responses:[
-          { status:200, desc:'Connection OK — test email sent', body:{ message:'SMTP connection verified — a test email has been sent to admin@example.com' }},
-          { status:400, desc:'Connection failed', body:{ message:'Authentication failed — check your SMTP username and password.', raw:'535 5.7.8 Error: authentication failed' }},
-        ]},
-    ]},
-
-    { title: 'Setup', base: '/api/setup', endpoints: [
-      { method:'POST', path:'/api/setup/register', auth:'public (one-time)', desc:'Step 2 of the first-time setup wizard. Creates the admin account and returns a short-lived JWT. Blocked once any user exists.',
-        request:{ body:{ name:'Admin User', email:'admin@example.com', password:'strong-password' }},
-        responses:[
-          { status:201, desc:'Created', body:{ token:'eyJhbGciOiJIUzI1NiJ9...', user:{ id:'uuid-...', name:'Admin User', role:'admin' }}},
-          { status:400, desc:'Already exists', body:{ message:'Setup already completed — users exist.' }},
-        ]},
-      { method:'POST', path:'/api/setup', auth:'setup token or admin', desc:'Final step of the setup wizard. Saves initial site settings. Requires the JWT returned by POST /api/setup/register.',
-        request:{ body:{ settings:{ org_name:'Cross Code', smtp_host:'smtp.gmail.com', smtp_port:'587', smtp_user:'user@gmail.com', smtp_pass:'app-password', mail_from:'noreply@example.com' }}},
-        responses:[{ status:200, desc:'Setup complete', body:{ message:'Setup complete.' }}]},
-    ]},
-  ];
-
-  // ── Rendering helpers ─────────────────────────────────────────────────────
-  function hl(json) {
-    // Simple JSON syntax highlighting — server-side
-    const s = JSON.stringify(json, null, 2);
-    return s
-      .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
-      .replace(/("(\\u[a-zA-Z0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?)/g, (m) => {
-        if (/^"/.test(m)) {
-          if (/:$/.test(m)) return `<span style="color:#6366f1">${m}</span>`; // key
-          return `<span style="color:#059669">${m}</span>`; // string value
-        }
-        if (/true|false/.test(m)) return `<span style="color:#d97706">${m}</span>`;
-        if (/null/.test(m)) return `<span style="color:#9ca3af">${m}</span>`;
-        return `<span style="color:#2563eb">${m}</span>`; // number
-      });
-  }
-
-  function codeBlock(content, lang) {
-    return `<pre style="background:#0f172a;color:#e2e8f0;padding:12px 14px;border-radius:6px;font-size:.75rem;overflow-x:auto;margin:0;line-height:1.6">${content}</pre>`;
-  }
-
-  function headerLine(key, val) {
-    return `<span style="color:#6366f1">${key}</span>: <span style="color:#059669">${val}</span>`;
-  }
-
-  function renderEndpoint(ep, idx) {
-    const id = `ep${idx}`;
-    const methodCls = { GET:'get', POST:'post', PUT:'put', PATCH:'patch', DELETE:'del' }[ep.method] || 'get';
-    const hasDetail = ep.notes || ep.pathParams || ep.queryParams || ep.request || ep.responses;
-
-    // Build HTTP request example
-    let reqLines = [];
-    const needsAuth = ep.auth !== 'public' && ep.auth !== 'HMAC' && ep.auth !== '—';
-    const isMultipart = ep.notes && ep.notes.includes('multipart');
-
-    reqLines.push(`<span style="color:#f59e0b;font-weight:600">${ep.method}</span> <span style="color:#e2e8f0">${ep.path}</span> <span style="color:#64748b">HTTP/1.1</span>`);
-    if (needsAuth) reqLines.push(headerLine('Authorization','Bearer &lt;your-jwt&gt;'));
-    if (ep.request?.body && !isMultipart) reqLines.push(headerLine('Content-Type','application/json'));
-    if (isMultipart) reqLines.push(headerLine('Content-Type','multipart/form-data'));
-    if (ep.request?.body && !isMultipart) {
-      reqLines.push('');
-      reqLines.push(hl(ep.request.body));
-    } else if (isMultipart) {
-      reqLines.push('');
-      reqLines.push(`<span style="color:#9ca3af">-- form field: image (binary file) --</span>`);
-    }
-
-    const reqHtml = codeBlock(reqLines.join('\n'));
-
-    // Build response examples
-    const resHtml = (ep.responses || []).map(r => {
-      const statusColor = r.status < 300 ? '#22c55e' : r.status < 500 ? '#f59e0b' : '#ef4444';
-      const body = typeof r.body === 'string' ? `<span style="color:#9ca3af">${r.body}</span>` : hl(r.body);
-      return `<div style="margin-bottom:8px">
-        <div style="font-size:.72rem;color:#64748b;margin-bottom:4px">
-          <span style="color:${statusColor};font-weight:600">HTTP ${r.status}</span>
-          <span style="margin-left:8px">${r.desc}</span>
-        </div>
-        ${codeBlock(body)}
-      </div>`;
-    }).join('');
-
-    // Path params table
-    let paramsHtml = '';
-    if (ep.pathParams && Object.keys(ep.pathParams).length) {
-      const rows = Object.entries(ep.pathParams).map(([k,v]) =>
-        `<tr><td style="padding:3px 10px;font-family:monospace;color:#6366f1;white-space:nowrap">${k}</td><td style="padding:3px 10px;color:#374151">${v}</td></tr>`).join('');
-      paramsHtml += `<div style="margin-bottom:10px"><div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:4px;text-transform:uppercase;letter-spacing:.05em">Path parameters</div><table style="width:100%;font-size:.8rem;border-collapse:collapse"><tbody>${rows}</tbody></table></div>`;
-    }
-    if (ep.queryParams && Object.keys(ep.queryParams).length) {
-      const rows = Object.entries(ep.queryParams).map(([k,v]) =>
-        `<tr><td style="padding:3px 10px;font-family:monospace;color:#6366f1;white-space:nowrap">${k}</td><td style="padding:3px 10px;color:#374151">${v}</td></tr>`).join('');
-      paramsHtml += `<div style="margin-bottom:10px"><div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:4px;text-transform:uppercase;letter-spacing:.05em">Query parameters</div><table style="width:100%;font-size:.8rem;border-collapse:collapse"><tbody>${rows}</tbody></table></div>`;
-    }
-
-    const notesHtml = ep.notes
-      ? `<div style="margin-bottom:10px;padding:8px 12px;background:#fefce8;border:1px solid #fde68a;border-radius:6px;font-size:.78rem;color:#92400e">${ep.notes}</div>`
-      : '';
-
-    const detailHtml = hasDetail ? `
-      <tr id="${id}-detail" style="display:none">
-        <td colspan="4" style="padding:0;border-bottom:2px solid #e5e7eb">
-          <div style="padding:16px;background:#f8fafc">
-            ${notesHtml}
-            ${paramsHtml}
-            <div style="display:grid;grid-template-columns:1fr 1fr;gap:16px">
-              <div>
-                <div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:6px;text-transform:uppercase;letter-spacing:.05em">Request</div>
-                ${reqHtml}
-              </div>
-              <div>
-                <div style="font-size:.72rem;font-weight:600;color:#374151;margin-bottom:6px;text-transform:uppercase;letter-spacing:.05em">Responses</div>
-                ${resHtml}
-              </div>
-            </div>
-          </div>
-        </td>
-      </tr>` : '';
-
-    const cursor = hasDetail ? 'cursor:pointer' : '';
-    const chevron = hasDetail
-      ? `<svg id="${id}-chevron" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" style="display:inline;vertical-align:middle;transition:transform .15s;flex-shrink:0"><polyline points="9 18 15 12 9 6"/></svg>`
-      : '';
-
-    const onclick = hasDetail ? `onclick="toggle('${id}')"` : '';
-
-    return `
-      <tr ${onclick} style="${cursor};${hasDetail?'':''}">
-        <td style="padding:7px 10px"><span class="method ${methodCls}">${ep.method}</span></td>
-        <td style="padding:7px 10px;font-family:monospace;font-size:.8rem;word-break:break-all">${ep.path}</td>
-        <td style="padding:7px 10px"><span class="auth-badge">${ep.auth}</span></td>
-        <td style="padding:7px 10px;font-size:.82rem;display:flex;align-items:center;justify-content:space-between;gap:6px">
-          <span>${ep.desc}</span>
-          <span style="color:#9ca3af;flex-shrink:0">${chevron}</span>
-        </td>
-      </tr>
-      ${detailHtml}`;
-  }
-
-  function renderGroup(group) {
-    const rows = group.endpoints.map((ep, i) => renderEndpoint(ep, `${group.title.replace(/\W+/g,'')}-${i}`)).join('');
-    return `
-      <h2 style="font-size:1rem;font-weight:600;color:#111827;margin:24px 0 8px">${group.title} <span style="font-size:.78rem;font-weight:400;color:#6b7280;font-family:monospace">${group.base}</span></h2>
-      <div style="border:1px solid #e5e7eb;border-radius:10px;overflow:hidden;margin-bottom:4px">
-        <table style="width:100%;border-collapse:collapse">
-          <thead><tr style="background:#f9fafb;border-bottom:1px solid #e5e7eb">
-            <th style="padding:7px 10px;width:75px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Method</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Path</th>
-            <th style="padding:7px 10px;width:100px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Auth</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.75rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Description</th>
-          </tr></thead>
-          <tbody>${rows}</tbody>
-        </table>
-      </div>`;
-  }
-
-  const groupsHtml = GROUPS.map(renderGroup).join('');
-
-  // ── Notifications reference — every automatic email/WhatsApp message the system sends ──
-  const NOTIFICATIONS = [
-    { category: 'Registration', items: [
-      { trigger: 'New registration — self-service (attendee registers via the public website)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration confirmed – {event}', content: 'Selections table, total due / paid / balance, payment options (website or at the door), and an account login / create-account prompt.' },
-      { trigger: 'New registration — self-service', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator when none are set)', subject: 'New registration: {event} — {name}', content: 'Registrant name, email, phone, status, items table, total due / paid / balance, registration ID.' },
-      { trigger: 'New registration — staff/at-door (manual registration, self-service kiosk)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration confirmed – {event}', content: 'Same as above, plus a Yoco pay-now link when a balance is owing.' },
-      { trigger: 'New registration — staff/at-door', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'New registration: {event} — {name}', content: 'Same layout as the self-service admin notice.' },
-      { trigger: 'Registration updated (options changed by staff, or a free registration completes)', channels: ['Email', 'WhatsApp'], recipients: 'Registrant', subject: 'Registration updated – {event}', content: 'Updated selections/total, same payment & account sections as the confirmation email.' },
-      { trigger: 'Registration updated', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Registration updated: {event} — {name}', content: 'Same layout as the new-registration admin notice.' },
-    ]},
-    { category: 'Payments', items: [
-      { trigger: 'Payment recorded (Yoco webhook success, manual cash/EFT entry, or a donation assigned to a registration)', channels: ['Email', 'WhatsApp'], recipients: 'Payer', subject: 'Payment received – {event} (or "Donation received – {event}" for unassigned donations)', content: 'Amount, method, date, full payment history table, updated balance.' },
-      { trigger: 'Payment recorded', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Payment recorded: {amount} — {payer} ({event})', content: 'Amount, type (registration payment / donation), payer, event, method, date, payment ID, external (Yoco) ID.' },
-      { trigger: 'Refund processed (negative payment created against an original payment)', channels: ['Email'], recipients: 'Payer', subject: 'Refund processed – {amount} for {event}', content: 'Refund amount, method, date, reason (when supplied).' },
-      { trigger: 'Refund processed', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Refund: Payment recorded: {amount} — {payer} ({event})', content: 'Same payment admin notice content, subject prefixed "Refund:".' },
-    ]},
-    { category: 'Tickets', items: [
-      { trigger: 'Tickets generated — fires whenever a registration becomes fully paid or is free (webhook, manual payment, staff status change, or free/no-cost registration)', channels: ['Email (PDF attached)', 'WhatsApp (PDF)'], recipients: 'Registrant (or a specific user when sent manually via "Send to")', subject: 'Your tickets for {event}', content: 'QR-coded ticket PDF, one per registered option/quantity; WhatsApp caption names the event and date.' },
-    ]},
-    { category: 'Daily digest', items: [
-      { trigger: 'Scheduled — every day at 07:00 local server time, once per active event that has gone live and has not yet started', channels: ['Email'], recipients: 'Admin — registrations inbox + event notify recipients (falls back to the event creator)', subject: 'Daily summary: {event} — {date}', content: 'Stat tiles (registrations, paid, awaiting payment, revenue), full registrations table with balances, full payments & donations table.' },
-    ]},
-    { category: 'Account & security', items: [
-      { trigger: 'New account registered', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'New user', subject: 'Welcome to {org}!', content: 'Welcome message plus a list of upcoming events.' },
-      { trigger: 'Login attempt on an account that is not yet active', channels: ['Email (if a real address is on file)', 'WhatsApp (fallback when there is no usable email)'], recipients: 'User', subject: 'Activate your {org} account', content: 'One-time activation link; expires after 24 hours.' },
-      { trigger: 'Successful login', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'New login to your {org} account', content: 'Login time, approximate location, device/user agent. Security alert — always emailed regardless of the user\'s notification preference.' },
-      { trigger: 'Password changed via profile update', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'Your {org} password was changed', content: 'Confirms the change and gives a support contact to use if it wasn\'t them.' },
-      { trigger: 'Forgot-password request', channels: ['Email (always)', 'WhatsApp (if preferred)'], recipients: 'User', subject: 'Reset your password', content: 'Password reset link.' },
-      { trigger: 'Account closed (self-service — "Deactivate" or "Delete my data")', channels: ['Email', 'WhatsApp (if preferred)'], recipients: 'User (sent to their last-known address/number just before data is wiped)', subject: 'Your {org} account has been closed', content: 'Confirms closure; wording differs slightly when personal data was also erased.' },
-    ]},
-    { category: 'Admin-triggered broadcasts', items: [
-      { trigger: 'Bulk email to event attendees, or an ad-hoc email broadcast — sent immediately or on a schedule', channels: ['Email'], recipients: 'Selected attendees / users / ad-hoc addresses chosen by the sender', subject: 'Admin-authored', content: 'Free-form subject & body written by the sender, supporting {{name}}, {{event.title}}, {{event.link}} placeholders. Used for reminders, thank-yous, promos, and multi-step automations.' },
-      { trigger: 'Bulk WhatsApp to event attendees, or an ad-hoc WhatsApp broadcast — sent immediately or on a schedule', channels: ['WhatsApp'], recipients: 'Selected attendees / users / ad-hoc phone numbers chosen by the sender', subject: '—', content: 'Free-form message written by the sender, same placeholder support as email broadcasts.' },
-    ]},
-  ];
-
-  function notifChannelBadges(channels) {
-    return channels.map(c => {
-      const isWa = /whatsapp/i.test(c);
-      return `<span style="display:inline-block;margin:1px 4px 2px 0;padding:1px 7px;border-radius:4px;font-size:.68rem;font-weight:700;white-space:nowrap;background:${isWa ? '#d1fae5' : '#dbeafe'};color:${isWa ? '#065f46' : '#1e40af'}">${c}</span>`;
-    }).join('');
-  }
-
-  function renderNotificationRow(n) {
-    return `<tr>
-      <td style="padding:8px 10px;font-size:.8rem;color:#374151;vertical-align:top">${n.trigger}</td>
-      <td style="padding:8px 10px;vertical-align:top">${notifChannelBadges(n.channels)}</td>
-      <td style="padding:8px 10px;font-size:.78rem;color:#374151;vertical-align:top">${n.recipients}</td>
-      <td style="padding:8px 10px;font-size:.78rem;font-family:monospace;color:#111827;vertical-align:top">${n.subject}</td>
-      <td style="padding:8px 10px;font-size:.76rem;color:#6b7280;vertical-align:top">${n.content}</td>
-    </tr>`;
-  }
-
-  function renderNotificationCategory(cat) {
-    const rows = cat.items.map(renderNotificationRow).join('');
-    return `
-      <h3 style="font-size:.88rem;font-weight:600;color:#111827;margin:16px 0 8px">${cat.category}</h3>
-      <div style="border:1px solid #e5e7eb;border-radius:10px;overflow:hidden;margin-bottom:4px">
-        <table style="width:100%;border-collapse:collapse">
-          <thead><tr style="background:#f9fafb;border-bottom:1px solid #e5e7eb">
-            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:26%">Trigger — when it's sent</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:11%">Channel</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:19%">Recipients</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em;width:17%">Subject</th>
-            <th style="padding:7px 10px;text-align:left;font-size:.7rem;color:#6b7280;font-weight:600;text-transform:uppercase;letter-spacing:.04em">Content</th>
-          </tr></thead>
-          <tbody>${rows}</tbody>
-        </table>
-      </div>`;
-  }
-
-  const notificationsHtml = NOTIFICATIONS.map(renderNotificationCategory).join('');
-  const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
-
-  const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${orgName} Events — API Docs</title>
-  <style>
-    *{box-sizing:border-box;margin:0;padding:0}
-    body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f3f4f6;color:#1f2937;min-height:100vh;padding:24px 16px}
-    .wrap{max-width:1100px;margin:0 auto}
-    .method{display:inline-block;padding:1px 7px;border-radius:4px;font-size:.7rem;font-weight:700;font-family:monospace}
-    .get{background:#dbeafe;color:#1e40af}
-    .post{background:#d1fae5;color:#065f46}
-    .put{background:#fef3c7;color:#92400e}
-    .patch{background:#ede9fe;color:#5b21b6}
-    .del{background:#fee2e2;color:#991b1b}
-    .auth-badge{font-size:.68rem;padding:1px 6px;border-radius:4px;background:#f3f4f6;color:#374151;font-family:monospace}
-    code{background:#f3f4f6;padding:1px 5px;border-radius:4px;font-family:monospace;font-size:.82rem}
-    tr.ep-open{background:#f0f9ff}
-    tbody tr:hover{background:#f8fafc}
-    tbody tr[onclick]:hover{background:#f0f9ff}
-    td{border-bottom:1px solid #f3f4f6}
-    a{color:#2563eb;text-decoration:none}
-    a:hover{text-decoration:underline}
-  </style>
-</head>
-<body>
-<div class="wrap">
-  <div style="display:flex;align-items:baseline;justify-content:space-between;flex-wrap:wrap;gap:8px;margin-bottom:6px">
-    <h1 style="font-size:1.4rem;font-weight:700;color:#111827">${orgName} Events — API Reference</h1>
-    <a href="/" style="font-size:.82rem;color:#6b7280">&#8592; Status page</a>
-  </div>
-  <p style="font-size:.82rem;color:#6b7280;margin-bottom:20px">
-    Logged in as <strong>${user.name || user.email}</strong> (${user.role}) &mdash;
-    Click any row to expand request &amp; response examples.
-  </p>
-
-  <div style="background:#eff6ff;border:1px solid #bfdbfe;border-radius:8px;padding:10px 14px;font-size:.8rem;color:#1e40af;margin-bottom:20px">
-    Protected routes require <code>Authorization: Bearer &lt;jwt&gt;</code> &nbsp;|&nbsp;
-    Roles: <code>admin</code> &gt; <code>supervisor</code> &gt; <code>staff</code> &gt; <code>user</code> &nbsp;|&nbsp;
-    Base URL: <code>${process.env.APP_BASE_URL || 'http://localhost:' + PORT}</code>
-  </div>
-
-  ${groupsHtml}
-
-  <h1 style="font-size:1.2rem;font-weight:700;color:#111827;margin:36px 0 4px">Notifications sent by the system</h1>
-  <p style="font-size:.8rem;color:#6b7280;margin-bottom:16px">
-    Every automatic email and WhatsApp message the platform sends, what triggers it, who receives it, and what it contains.
-    Admin-facing registration/payment/daily-summary notices go to the <code>reg_notification_emails</code> setting plus each
-    event's configured notify recipients (Admin &rarr; Events &rarr; edit event &rarr; Notifications step) &mdash;
-    falling back to that event's creator when no recipients have been chosen.
-  </p>
-
-  ${notificationsHtml}
-
-  <p style="font-size:.72rem;color:#9ca3af;margin-top:28px;text-align:center">
-    ${orgName} Events API v${API_VERSION} &mdash; ${new Date().toISOString()}
-  </p>
-</div>
-<script>
-function toggle(id) {
-  const detail = document.getElementById(id + '-detail');
-  const chevron = document.getElementById(id + '-chevron');
-  if (!detail) return;
-  const open = detail.style.display !== 'none';
-  detail.style.display = open ? 'none' : 'table-row';
-  if (chevron) chevron.style.transform = open ? 'rotate(0deg)' : 'rotate(90deg)';
-  // highlight parent row
-  const rows = detail.parentElement.querySelectorAll('tr[onclick]');
-  rows.forEach(r => {
-    if (r.getAttribute('onclick') === "toggle('" + id + "')") {
-      r.classList.toggle('ep-open', !open);
-    }
-  });
-}
-</script>
-</body>
-</html>`;
-
-  res.send(html);
-});
-
-// Error middleware
-app.use(notFound);
-
-// Sentry captures the error here, then passes it through unchanged — errorHandler
-// below remains the sole source of what's actually sent back to the client.
-if (process.env.SENTRY_DSN) {
-  const Sentry = require('@sentry/node');
-  Sentry.setupExpressErrorHandler(app);
-}
-
-app.use(errorHandler);
-
-// Start server
-app.listen(PORT, () => {
-  console.log(`Server is running at http://localhost:${PORT}`);
-  // Attempt a one-time background sync of attachment manifests into DB
-  try {
-    const { syncManifestsToDb } = require('./utils/attachmentsSync');
-    const prismaShared = require('./config/db');
-    setTimeout(async () => {
-      try {
-        const summary = await syncManifestsToDb(prismaShared, { dryRun: false });
-        if ((summary.imported || 0) > 0) {
-          console.log(`[attachments sync] Imported ${summary.imported} attachments from manifests (skipped ${summary.skipped}).`);
-        } else {
-          console.log('[attachments sync] No attachments imported (either none found or already in DB).');
-        }
-      } catch (e) {
-        console.warn('[attachments sync] Failed:', e?.message || e);
-      }
-    }, 1000);
-  } catch (e) {
-    console.warn('[attachments sync] Not scheduled:', e?.message || e);
-  }
-
-  // Timed background jobs (daily summary, waitlist, feedback, sessions, consent, analytics,
-  // backup, temp cleanup) run on the pg-boss job queue — see src/jobs/index.js.
-  require('./jobs').startJobs().catch(e => console.warn('[jobs] Not started:', e?.message || e));
-
-  // Check in with the Hub 30 s after starting, so the licence is fresh without waiting 15 minutes.
-  require('./hub/client').heartbeatSoon();
-
-  // Scheduled emails worker (polling)
-  try {
-    const enabled = String(process.env.SCHEDULED_EMAILS_ENABLED || 'true').toLowerCase() !== 'false';
-    if (enabled) {
-      const { getDueJobs, updateJob, purgeSentJobs } = require('./utils/scheduledEmails');
-      const { emailEventAttendees, whatsappEventAttendees } = require('./controllers/eventController');
-      const { sendBroadcast } = require('./controllers/broadcastController');
-      const { sendWhatsAppBroadcast } = require('./controllers/whatsappBroadcastController');
-      const intervalMs = parseInt(process.env.SCHEDULED_EMAILS_INTERVAL_MS || '30000', 10);
-      setInterval(async () => {
-        try {
-          try { purgeSentJobs(24 * 60 * 60 * 1000); } catch (e) { console.warn('[scheduled emails] purge failed:', e?.message || e); }
-          const due = getDueJobs(new Date());
-          if (!due || due.length === 0) return;
-          for (const job of due) {
-            try {
-              updateJob(job.id, { status: 'sending', attempts: (job.attempts || 0) + 1, lastError: null });
-              let responseBody = null; let code = 200;
-              const mockRes = {
-                status: (c) => { code = c; return mockRes; },
-                json: (b) => { responseBody = b; return mockRes; }
-              };
-              if (job.broadcast && job.channel === 'whatsapp') {
-                const mockReq = { body: job.payload };
-                await sendWhatsAppBroadcast(mockReq, mockRes);
-              } else if (job.broadcast) {
-                const mockReq = { body: job.payload };
-                await sendBroadcast(mockReq, mockRes);
-              } else if (job.channel === 'whatsapp') {
-                const mockReq = { params: { id: job.eventId }, body: job.payload };
-                await whatsappEventAttendees(mockReq, mockRes);
-              } else {
-                const mockReq = { params: { id: job.eventId }, body: job.payload };
-                await emailEventAttendees(mockReq, mockRes);
-              }
-              if (code >= 200 && code < 300) {
-                updateJob(job.id, { status: 'sent', sentAt: new Date().toISOString(), lastResult: responseBody || null });
-              } else {
-                updateJob(job.id, { status: 'error', lastError: (responseBody && responseBody.message) ? responseBody.message : `HTTP ${code}` });
-              }
-            } catch (e) {
-              updateJob(job.id, { status: 'error', lastError: String(e?.message || e) });
-            }
-          }
-        } catch (e) {
-          console.warn('[scheduled emails] poll failed:', e?.message || e);
-        }
-      }, isNaN(intervalMs) ? 30000 : intervalMs);
-      console.log('[scheduled emails] Worker initialized. Set SCHEDULED_EMAILS_ENABLED=false to disable.');
-    } else {
-      console.log('[scheduled emails] Worker disabled by env SCHEDULED_EMAILS_ENABLED=false');
-    }
-  } catch (e) {
-    console.warn('[scheduled emails] Worker not started:', e?.message || e);
-  }
-});
-
-// Log unhandled promise rejections without killing the server, since a single
-// missed .catch() on fire-and-forget notification code (email/WhatsApp sends)
-// would otherwise take the whole app down.
-// On restart/stop (PM2 sends SIGINT), let a running background job finish first.
-for (const signal of ['SIGINT', 'SIGTERM']) {
-  process.once(signal, async () => {
-    try { await require('./jobs').stopJobs(); } catch { /* exiting anyway */ }
-    process.exit(0);
-  });
-}
-
-process.on('unhandledRejection', (err) => {
-  console.error('UNHANDLED REJECTION!', err?.name, err?.message);
-  console.error(err?.stack || err);
-  if (process.env.SENTRY_DSN) {
-    try { require('@sentry/node').captureException(err); } catch {}
-  }
-});
-
-module.exports = { app, prisma };
\ No newline at end of file
diff --git a/backend/src/v2/errors.ts b/backend/src/v2/errors.ts
new file mode 100644
index 0000000..78409bd
--- /dev/null
+++ b/backend/src/v2/errors.ts
@@ -0,0 +1,82 @@
+import type { ErrorRequestHandler, RequestHandler } from 'express';
+import { ZodError } from 'zod';
+
+/**
+ * /api/v2 errors all look the same:
+ *   { "error": { "code": "VALIDATION_FAILED", "message": "…", "fields": { "limit": "…" } } }
+ * `code` is stable (clients switch on it), `message` is for people, `fields` only on validation.
+ */
+export type ErrorCode =
+  | 'VALIDATION_FAILED'
+  | 'UNAUTHENTICATED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'RATE_LIMITED'
+  | 'READ_ONLY'
+  | 'INTERNAL';
+
+export const ERROR_STATUS: Record<ErrorCode, number> = {
+  VALIDATION_FAILED: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  READ_ONLY: 423,
+  INTERNAL: 500,
+};
+
+export class ApiError extends Error {
+  readonly code: ErrorCode;
+  readonly status: number;
+  readonly fields?: Record<string, string>;
+
+  constructor(code: ErrorCode, message: string, fields?: Record<string, string>) {
+    super(message);
+    this.code = code;
+    this.status = ERROR_STATUS[code];
+    this.fields = fields;
+  }
+}
+
+export const notFound = (what = 'That'): ApiError => new ApiError('NOT_FOUND', `${what} wasn't found.`);
+
+/** "limit" or "items.0.quantity" → the first problem with it. */
+export function zodFields(err: ZodError): Record<string, string> {
+  const fields: Record<string, string> = {};
+  for (const issue of err.issues) {
+    const key = issue.path.length ? issue.path.join('.') : '_';
+    if (!fields[key]) fields[key] = issue.message;
+  }
+  return fields;
+}
+
+const STATUS_CODE: Record<number, ErrorCode> = { 400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 409: 'CONFLICT', 423: 'READ_ONLY', 429: 'RATE_LIMITED' };
+const PRISMA_CODE: Record<string, ErrorCode> = { P2002: 'CONFLICT', P2025: 'NOT_FOUND', P2003: 'CONFLICT' };
+
+type LegacyError = Error & { statusCode?: number; status?: number; code?: string };
+
+/** Turns anything thrown (ApiError, zod, Prisma, the v1 auth middleware's errors) into the v2 shape. */
+export function toApiError(err: unknown, responseStatus: number): ApiError {
+  if (err instanceof ApiError) return err;
+  if (err instanceof ZodError) return new ApiError('VALIDATION_FAILED', 'Some of what was sent is not valid.', zodFields(err));
+  const e = (err || {}) as LegacyError;
+  if (typeof e.code === 'string' && PRISMA_CODE[e.code]) {
+    return new ApiError(PRISMA_CODE[e.code], e.code === 'P2002' ? 'A record with that value already exists.' : e.code === 'P2025' ? 'Record not found.' : 'A related record prevents this.');
+  }
+  // The shared v1 middleware (protect, staff…) sets res.status() and passes an Error;
+  // utils throw errors with statusCode. Those messages are written for people already.
+  const status = e.statusCode || e.status || (responseStatus >= 400 ? responseStatus : 500);
+  const code = STATUS_CODE[status];
+  if (code) return new ApiError(code, e.message || 'Request failed.');
+  return new ApiError('INTERNAL', 'Something went wrong on the server.');
+}
+
+export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
+  const apiErr = toApiError(err, res.statusCode);
+  if (apiErr.code === 'INTERNAL') console.error('[api/v2]', req.method, req.originalUrl, err);
+  res.status(apiErr.status).json({ error: { code: apiErr.code, message: apiErr.message, ...(apiErr.fields ? { fields: apiErr.fields } : {}) } });
+};
+
+export const notFoundHandler: RequestHandler = (_req, _res, next) => next(new ApiError('NOT_FOUND', 'There is no such API endpoint.'));
diff --git a/backend/src/v2/index.ts b/backend/src/v2/index.ts
new file mode 100644
index 0000000..3bc6fba
--- /dev/null
+++ b/backend/src/v2/index.ts
@@ -0,0 +1,92 @@
+import express, { Router } from 'express';
+import path from 'path';
+import { mount, routes } from './route';
+import { buildOpenApi } from './openapi';
+import { errorHandler, notFoundHandler } from './errors';
+import auth from '../middleware/authMiddleware';
+// Resources: importing one registers its routes.
+import './resources/events';
+import './resources/me';
+
+const pkg = require('../../package.json') as { version: string };
+
+/** /api/v2 — see route.ts for how endpoints are declared, openapi.ts for the docs. */
+export function v2Router(): Router {
+  const router = express.Router();
+
+  // The API description is for the people building on it (admins), like /docs.
+  router.get('/openapi.json', auth.protect, auth.admin, (_req, res) => {
+    res.json(buildOpenApi({ version: pkg.version }));
+  });
+
+  mount(router, routes);
+  router.use(notFoundHandler);
+  router.use(errorHandler);
+  return router;
+}
+
+/**
+ * /docs/v2: Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is
+ * public; it asks for an admin token and uses it to load openapi.json and to try requests.
+ */
+export function v2DocsRouter(): Router {
+  const router = express.Router();
+  const assets = path.dirname(require.resolve('swagger-ui-dist/package.json'));
+  router.use('/assets', express.static(assets, { index: false, maxAge: '1d' }));
+  router.get('/', (_req, res) => {
+    res.type('html').send(DOCS_HTML);
+  });
+  return router;
+}
+
+const DOCS_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cross Events API v2</title>
+  <link rel="stylesheet" href="/docs/v2/assets/swagger-ui.css">
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; }
+    #login { max-width: 40rem; margin: 3rem auto; padding: 0 1rem; }
+    #login input { width: 100%; padding: .5rem; font: inherit; border: 1px solid #9ca3af; border-radius: 6px; box-sizing: border-box; }
+    #login button { margin-top: .75rem; padding: .5rem 1rem; font: inherit; background: #1d4ed8; color: #fff; border: 0; border-radius: 6px; cursor: pointer; }
+    #login .err { color: #b91c1c; margin-top: .5rem; }
+  </style>
+</head>
+<body>
+  <main id="login" hidden>
+    <h1>Cross Events API v2</h1>
+    <p>The API reference is for admins. Paste your admin token (after signing in, it's under <code>hope_events_token</code> in the browser's local storage).</p>
+    <label for="token">Admin token</label>
+    <input id="token" autocomplete="off">
+    <button id="go" type="button">Show the API</button>
+    <p class="err" id="err" role="alert"></p>
+  </main>
+  <div id="ui"></div>
+  <script src="/docs/v2/assets/swagger-ui-bundle.js"></script>
+  <script>
+  (function () {
+    var params = new URLSearchParams(location.search);
+    var token = params.get('token') || sessionStorage.getItem('v2docs_token') || localStorage.getItem('hope_events_token') || '';
+    function show(t) {
+      fetch('/api/v2/openapi.json', { headers: { Authorization: 'Bearer ' + t } }).then(function (r) {
+        if (!r.ok) return r.json().then(function (b) { throw new Error((b.error && b.error.message) || r.statusText); });
+        return r.json();
+      }).then(function (spec) {
+        sessionStorage.setItem('v2docs_token', t);
+        if (params.has('token')) history.replaceState(null, '', location.pathname);
+        document.getElementById('login').hidden = true;
+        var ui = SwaggerUIBundle({ spec: spec, dom_id: '#ui', deepLinking: true, persistAuthorization: false });
+        ui.preauthorizeApiKey('bearerAuth', t);
+      }).catch(function (e) {
+        document.getElementById('login').hidden = false;
+        document.getElementById('err').textContent = t ? 'That token did not work: ' + e.message : '';
+      });
+    }
+    document.getElementById('go').addEventListener('click', function () { show(document.getElementById('token').value.trim()); });
+    show(token);
+  })();
+  </script>
+</body>
+</html>`;
diff --git a/backend/src/v2/legacy.ts b/backend/src/v2/legacy.ts
new file mode 100644
index 0000000..74cfe65
--- /dev/null
+++ b/backend/src/v2/legacy.ts
@@ -0,0 +1,32 @@
+/**
+ * Typed doors into the JavaScript side of the backend. TypeScript infers loose types from the
+ * .js files (the Prisma client is built by a function, helpers have defaulted options), so v2
+ * code imports them from here instead. When a module is converted to TypeScript, its line here
+ * goes and callers import it directly.
+ */
+import type { PrismaClient } from '@prisma/client';
+
+// The client in config/db.js only adds query hooks (webhooks), so its models are PrismaClient's.
+export const prisma = require('../config/db') as PrismaClient;
+
+type CampusFilter = '' | 'all' | string;
+const campuses = require('../utils/campuses') as {
+  campusesEnabled(): Promise<boolean>;
+  resolveCampusFilter(value: string | undefined): Promise<CampusFilter>;
+  campusWhere(filter: CampusFilter, opts: { enabled: boolean; withAllCampuses?: boolean }): object;
+};
+export const { campusesEnabled, resolveCampusFilter, campusWhere } = campuses;
+
+export const { publicEventWhere } = require('../utils/series') as {
+  publicEventWhere(now?: Date): { isActive: true; isHidden: false; goLiveAt: { lte: Date } };
+};
+
+type OptionLike = { id: string; price: number; earlyBirdTiers?: unknown[] };
+export const { publicOptions } = require('../utils/volunteers') as {
+  publicOptions<O extends { id: string }>(event: { eventOptions?: O[]; kidsOptionId?: string | null; volunteerOptionId?: string | null }): O[];
+};
+
+export const { getEffectiveUnitPrice, computeRegistrationTotalDue } = require('../utils/pricing') as {
+  getEffectiveUnitPrice(option: OptionLike, referenceTime: Date | null, atTime: Date): number;
+  computeRegistrationTotalDue(registration: object, atTime: Date): number;
+};
diff --git a/backend/src/v2/openapi.ts b/backend/src/v2/openapi.ts
new file mode 100644
index 0000000..8a16f6a
--- /dev/null
+++ b/backend/src/v2/openapi.ts
@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { routes as allRoutes, type AnyRoute, type Access } from './route';
+import { ERROR_STATUS } from './errors';
+
+/**
+ * The OpenAPI 3.1 document for /api/v2, built from the route declarations (route.ts), so it is
+ * always what the code does. Served at /api/v2/openapi.json, shown at /docs/v2.
+ */
+
+type JsonSchema = Record<string, unknown>;
+
+const toSchema = (schema: z.ZodType, io: 'input' | 'output'): JsonSchema => {
+  const { $schema: _drop, ...rest } = z.toJSONSchema(schema, { io, unrepresentable: 'any' }) as JsonSchema;
+  return rest;
+};
+
+const ACCESS_TEXT: Record<Access, string> = {
+  public: 'Anyone.',
+  optional: 'Anyone; signed-in staff may see more.',
+  user: 'Any signed-in person.',
+  staff: 'Staff, supervisors and admins.',
+  supervisor: 'Supervisors and admins.',
+  admin: 'Admins only.',
+};
+
+const errorSchema = {
+  type: 'object',
+  required: ['error'],
+  properties: {
+    error: {
+      type: 'object',
+      required: ['code', 'message'],
+      properties: {
+        code: { type: 'string', enum: Object.keys(ERROR_STATUS) },
+        message: { type: 'string' },
+        fields: { type: 'object', additionalProperties: { type: 'string' }, description: 'Per-field problems (VALIDATION_FAILED only)' },
+      },
+    },
+  },
+};
+
+const errorResponse = (description: string) => ({ description, content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } });
+
+function parameters(def: AnyRoute) {
+  const out: JsonSchema[] = [];
+  const add = (schema: z.ZodType | undefined, where: 'path' | 'query') => {
+    if (!schema) return;
+    const json = toSchema(schema, 'input') as { properties?: Record<string, JsonSchema>; required?: string[] };
+    for (const [name, prop] of Object.entries(json.properties || {})) {
+      const { description, ...propSchema } = prop as JsonSchema & { description?: string };
+      out.push({ name, in: where, required: where === 'path' || (json.required || []).includes(name), ...(description ? { description } : {}), schema: propSchema });
+    }
+  };
+  add(def.params, 'path');
+  add(def.query, 'query');
+  return out;
+}
+
+export function buildOpenApi(opts: { version: string; serverUrl?: string; list?: AnyRoute[] }) {
+  const list = opts.list ?? allRoutes;
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const def of list) {
+    const path = def.path.replace(/:(\w+)/g, '{$1}');
+    const secured = def.access !== 'public' && def.access !== 'optional';
+    paths[path] ||= {};
+    paths[path][def.method] = {
+      tags: [def.tag],
+      summary: def.summary,
+      description: [def.description, `**Who:** ${ACCESS_TEXT[def.access]}`].filter(Boolean).join('\n\n'),
+      operationId: `${def.method}${path.replace(/[{}]/g, '').split('/').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('')}`,
+      ...(secured ? { security: [{ bearerAuth: [] }] } : def.access === 'optional' ? { security: [{}, { bearerAuth: [] }] } : {}),
+      parameters: parameters(def),
+      ...(def.body ? { requestBody: { required: true, content: { 'application/json': { schema: toSchema(def.body, 'input') } } } } : {}),
+      responses: {
+        [String(def.status ?? 200)]: { description: 'OK', content: { 'application/json': { schema: toSchema(def.response, 'output') } } },
+        ...(def.params || def.query || def.body ? { 400: errorResponse('Validation failed (VALIDATION_FAILED)') } : {}),
+        ...(secured ? { 401: errorResponse('Not signed in (UNAUTHENTICATED)') } : {}),
+        ...(secured && def.access !== 'user' ? { 403: errorResponse('Not allowed for this role (FORBIDDEN)') } : {}),
+        ...(def.params ? { 404: errorResponse('Not found (NOT_FOUND)') } : {}),
+      },
+    };
+  }
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'Cross Events API',
+      version: opts.version,
+      description: [
+        'Version 2 of the Cross Events API. Every response is JSON:',
+        '- a single item is `{ "data": { … } }`;',
+        '- a list is `{ "data": [ … ], "meta": { "page", "limit", "total", "pages" } }`, paged with `?page=` and `?limit=` (at most 100);',
+        '- an error is `{ "error": { "code", "message", "fields"? } }` with a stable `code`.',
+        '',
+        'Dates are ISO 8601 in UTC; amounts are in rand. Sign in through the app and send the token as `Authorization: Bearer <token>`.',
+        'Version 1 (`/api/…`) keeps working while the app moves over; it will be removed in 2.0.',
+      ].join('\n'),
+    },
+    servers: [{ url: opts.serverUrl ?? '/api/v2' }],
+    tags: Array.from(new Set(list.map(r => r.tag))).map(name => ({ name })),
+    paths,
+    components: {
+      securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } },
+      schemas: { Error: errorSchema },
+    },
+  };
+}
diff --git a/backend/src/v2/paging.ts b/backend/src/v2/paging.ts
new file mode 100644
index 0000000..dfcd5ec
--- /dev/null
+++ b/backend/src/v2/paging.ts
@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/** `?page=2&limit=25` on every v2 list (limit 1–100, default 25). */
+export const pageQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1).describe('Page number, from 1'),
+  limit: z.coerce.number().int().min(1).max(100).default(25).describe('Items per page (at most 100)'),
+});
+export type PageQuery = z.infer<typeof pageQuery>;
+
+export const pageMeta = z.object({
+  page: z.number().int(),
+  limit: z.number().int(),
+  total: z.number().int().describe('Items across all pages'),
+  pages: z.number().int().describe('Number of pages (at least 1)'),
+});
+
+/** The response shape of a v2 list: `{ data: [...], meta: { page, limit, total, pages } }`. */
+export const paged = <T extends z.ZodType>(item: T) => z.object({ data: z.array(item), meta: pageMeta });
+
+/** The response shape of a single v2 resource: `{ data: {...} }`. */
+export const single = <T extends z.ZodType>(item: T) => z.object({ data: item });
+
+/** Prisma's skip/take for a page. */
+export const skipTake = ({ page, limit }: PageQuery) => ({ skip: (page - 1) * limit, take: limit });
+
+export function pageOf<T>(data: T[], total: number, { page, limit }: PageQuery) {
+  return { data, meta: { page, limit, total, pages: Math.max(1, Math.ceil(total / limit)) } };
+}
diff --git a/backend/src/v2/resources/events.ts b/backend/src/v2/resources/events.ts
new file mode 100644
index 0000000..4b05c2b
--- /dev/null
+++ b/backend/src/v2/resources/events.ts
@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { defineRoute } from '../route';
+import { notFound } from '../errors';
+import { pageQuery, paged, single, skipTake, pageOf } from '../paging';
+import { absoluteUrl, campusRef, id, idParams, iso, isoDate, seriesRef } from '../schemas';
+import { prisma, campusesEnabled, campusWhere, resolveCampusFilter, publicEventWhere, publicOptions, getEffectiveUnitPrice } from '../legacy';
+
+const eventSummary = z.object({
+  id,
+  title: z.string(),
+  startDate: isoDate,
+  endDate: isoDate,
+  location: z.string().nullable(),
+  price: z.number().describe('The headline price in rand (0 = free)'),
+  pictureUrl: z.string().nullable(),
+  requiresRegistration: z.boolean(),
+  scheduleType: z.enum(['single', 'sessions']),
+  campus: campusRef.nullable().describe('null = for all campuses (or campuses are off)'),
+  series: seriesRef.nullable(),
+});
+
+const ticketOption = z.object({
+  id,
+  name: z.string(),
+  price: z.number().describe('The normal price in rand'),
+  currentPrice: z.number().describe('What it costs now (an early-bird price while one runs)'),
+  isMainTicket: z.boolean(),
+  sessionMode: z.enum(['all', 'pick']).describe('"pick" = the buyer chooses sessions'),
+});
+
+const session = z.object({
+  id,
+  label: z.string().nullable(),
+  startsAt: isoDate,
+  endsAt: isoDate,
+  location: z.string().nullable(),
+  cancelled: z.boolean(),
+});
+
+const eventDetail = eventSummary.extend({
+  description: z.string().nullable(),
+  registrationDeadline: isoDate.nullable(),
+  ticketOptions: z.array(ticketOption),
+  sessions: z.array(session).describe('Multi-day events only; empty otherwise'),
+});
+
+const SUMMARY_SELECT = {
+  id: true, title: true, startDate: true, endDate: true, location: true, price: true, picture: true,
+  requiresRegistration: true, scheduleType: true,
+  campus: { select: { id: true, name: true, slug: true } },
+  series: { select: { id: true, name: true, slug: true } },
+} as const;
+
+type SummaryRow = {
+  id: string; title: string; startDate: Date; endDate: Date; location: string | null; price: number; picture: string | null;
+  requiresRegistration: boolean; scheduleType: 'single' | 'sessions';
+  campus: { id: string; name: string; slug: string } | null; series: { id: string; name: string; slug: string } | null;
+};
+
+const toSummary = (req: Parameters<typeof absoluteUrl>[0], e: SummaryRow): z.input<typeof eventSummary> => ({
+  id: e.id, title: e.title, startDate: iso(e.startDate), endDate: iso(e.endDate), location: e.location ?? null,
+  price: e.price, pictureUrl: absoluteUrl(req, e.picture), requiresRegistration: e.requiresRegistration,
+  scheduleType: e.scheduleType, campus: e.campus ?? null, series: e.series ?? null,
+});
+
+export const listEvents = defineRoute({
+  method: 'get',
+  path: '/events',
+  tag: 'Events',
+  summary: 'Upcoming public events',
+  description: 'Events anyone can see (active, not hidden, live) that have not ended, soonest first.',
+  access: 'public',
+  query: pageQuery.extend({
+    q: z.string().trim().max(100).optional().describe('Search the title'),
+    campus: z.string().max(64).optional().describe("A campus id or slug (its events plus church-wide ones), or 'all' for church-wide events only"),
+    series: z.string().max(120).optional().describe('A series slug'),
+  }),
+  response: paged(eventSummary),
+  async handler({ query, req }) {
+    const now = new Date();
+    const enabled = await campusesEnabled();
+    const and: object[] = [publicEventWhere(now), { endDate: { gte: now } }];
+    if (query.campus) and.push(campusWhere(await resolveCampusFilter(query.campus), { enabled, withAllCampuses: true }));
+    if (query.series) and.push({ series: { slug: query.series } });
+    if (query.q) and.push({ title: { contains: query.q, mode: 'insensitive' } });
+    const where = { AND: and };
+    const [rows, total] = await Promise.all([
+      prisma.event.findMany({ where, select: SUMMARY_SELECT, orderBy: [{ startDate: 'asc' }, { id: 'asc' }], ...skipTake(query) }),
+      prisma.event.count({ where }),
+    ]);
+    return pageOf((rows as SummaryRow[]).map(e => toSummary(req, e)), total, query);
+  },
+});
+
+export const getEvent = defineRoute({
+  method: 'get',
+  path: '/events/:id',
+  tag: 'Events',
+  summary: 'One public event',
+  description: 'With its ticket options (internal kids check-in and volunteer tickets left out) and sessions. Hidden events can be fetched by id (they are unlisted, not private).',
+  access: 'public',
+  params: idParams,
+  response: single(eventDetail),
+  async handler({ params, req }) {
+    const now = new Date();
+    const { isHidden: _hiddenOk, ...visible } = publicEventWhere(now);
+    const e = await prisma.event.findFirst({
+      where: { id: params.id, ...visible },
+      select: {
+        ...SUMMARY_SELECT, description: true, registrationDeadline: true, kidsOptionId: true, volunteerOptionId: true,
+        eventOptions: { include: { earlyBirdTiers: true }, orderBy: [{ isMainTicket: 'desc' }, { name: 'asc' }] },
+        sessions: { orderBy: { startsAt: 'asc' } },
+      },
+    });
+    if (!e) throw notFound('That event');
+    const options = publicOptions(e);
+    return {
+      data: {
+        ...toSummary(req, e as unknown as SummaryRow),
+        description: e.description ?? null,
+        registrationDeadline: iso(e.registrationDeadline),
+        ticketOptions: options.map(o => ({
+          id: o.id, name: o.name, price: o.price, currentPrice: getEffectiveUnitPrice(o, null, now),
+          isMainTicket: o.isMainTicket, sessionMode: o.sessionMode,
+        })),
+        sessions: e.sessions.map(s => ({ id: s.id, label: s.label, startsAt: iso(s.startsAt), endsAt: iso(s.endsAt), location: s.location, cancelled: !!s.cancelledAt })),
+      },
+    };
+  },
+});
diff --git a/backend/src/v2/resources/me.ts b/backend/src/v2/resources/me.ts
new file mode 100644
index 0000000..5d62983
--- /dev/null
+++ b/backend/src/v2/resources/me.ts
@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { defineRoute } from '../route';
+import { ApiError } from '../errors';
+import { pageQuery, paged, single, skipTake, pageOf } from '../paging';
+import { eventRef, id, iso, isoDate } from '../schemas';
+import { prisma, computeRegistrationTotalDue } from '../legacy';
+
+const me = z.object({
+  id,
+  name: z.string(),
+  email: z.string(),
+  phone: z.string().nullable(),
+  role: z.enum(['admin', 'supervisor', 'staff', 'user']),
+  twoFactorEnabled: z.boolean(),
+  createdAt: isoDate,
+});
+
+export const getMe = defineRoute({
+  method: 'get',
+  path: '/me',
+  tag: 'Me',
+  summary: 'The signed-in person',
+  access: 'user',
+  response: single(me),
+  async handler({ user }) {
+    const u = await prisma.user.findUnique({
+      where: { id: user!.id },
+      select: { id: true, name: true, email: true, phoneNumber: true, role: true, twoFactorEnabled: true, createdAt: true },
+    });
+    if (!u) throw new ApiError('UNAUTHENTICATED', 'User not found');
+    return { data: { id: u.id, name: u.name, email: u.email, phone: u.phoneNumber ?? null, role: u.role, twoFactorEnabled: !!u.twoFactorEnabled, createdAt: iso(u.createdAt) } };
+  },
+});
+
+const STATUSES = ['pending', 'confirmed', 'partial_paid', 'paid', 'cancelled'] as const;
+
+const myRegistration = z.object({
+  id,
+  status: z.enum(STATUSES),
+  createdAt: isoDate,
+  event: eventRef,
+  items: z.array(z.object({
+    ticket: z.string(),
+    variant: z.string().nullable(),
+    quantity: z.number().int(),
+    unitPrice: z.number(),
+  })),
+  totalDue: z.number().describe('In rand, after discounts'),
+  amountPaid: z.number().describe('In rand (refunds subtracted)'),
+  balance: z.number().describe('totalDue − amountPaid; 0 or less = nothing owing'),
+});
+
+const r2 = (n: number) => Math.round(n * 100) / 100;
+
+export const listMyRegistrations = defineRoute({
+  method: 'get',
+  path: '/me/registrations',
+  tag: 'Me',
+  summary: 'My registrations',
+  description: 'Newest first. By default only ones for events that have not ended, and not cancelled; `past=true` lists everything.',
+  access: 'user',
+  query: pageQuery.extend({
+    past: z.enum(['true', 'false']).default('false').transform(v => v === 'true').describe('Include past and cancelled registrations'),
+  }),
+  response: paged(myRegistration),
+  async handler({ query, user }) {
+    const now = new Date();
+    const where = query.past
+      ? { userId: user!.id }
+      : { userId: user!.id, status: { not: 'cancelled' as const }, event: { endDate: { gte: now } } };
+    const [rows, total] = await Promise.all([
+      prisma.registration.findMany({
+        where,
+        include: {
+          event: { select: { id: true, title: true, startDate: true, endDate: true } },
+          registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, variant: { select: { name: true, price: true } }, tranches: true } },
+          payments: { select: { amount: true, createdAt: true } },
+        },
+        orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+        ...skipTake(query),
+      }),
+      prisma.registration.count({ where }),
+    ]);
+    return pageOf(rows.map(r => {
+      const totalDue = r2(computeRegistrationTotalDue(r, now));
+      const amountPaid = r2(r.payments.reduce((s, p) => s + p.amount, 0));
+      return {
+        id: r.id,
+        status: r.status,
+        createdAt: iso(r.createdAt),
+        event: { id: r.event.id, title: r.event.title, startDate: iso(r.event.startDate), endDate: iso(r.event.endDate) },
+        items: r.registrationOptions.map(o => ({ ticket: o.eventOption?.name ?? '', variant: o.variant?.name ?? null, quantity: o.quantity, unitPrice: o.priceSnapshot ?? o.eventOption?.price ?? 0 })),
+        totalDue,
+        amountPaid,
+        balance: r2(totalDue - amountPaid),
+      };
+    }), total, query);
+  },
+});
diff --git a/backend/src/v2/route.ts b/backend/src/v2/route.ts
new file mode 100644
index 0000000..83522dc
--- /dev/null
+++ b/backend/src/v2/route.ts
@@ -0,0 +1,105 @@
+import type { Request, RequestHandler, Response, Router } from 'express';
+import { z } from 'zod';
+import { ApiError } from './errors';
+import auth from '../middleware/authMiddleware';
+
+/**
+ * Every /api/v2 endpoint is declared with `defineRoute`: method, path, who may call it, and zod
+ * schemas for the params, query, body and response. The same declaration
+ *   - validates the request (400 VALIDATION_FAILED with per-field messages),
+ *   - checks the response against its schema and strips anything it doesn't list (so a field
+ *     can't leak by being added to a Prisma include), and
+ *   - becomes the OpenAPI document (openapi.ts) — the docs can't drift from the code.
+ */
+
+export type Access = 'public' | 'optional' | 'user' | 'staff' | 'supervisor' | 'admin';
+
+/** The signed-in person, as the auth middleware puts it on the request. */
+export type ApiUser = { id: string; name: string; email: string; role: 'admin' | 'supervisor' | 'staff' | 'user' };
+
+export type Ctx<P, Q, B> = {
+  params: P;
+  query: Q;
+  body: B;
+  user: ApiUser | null;
+  req: Request;
+  res: Response;
+};
+
+type Schema = z.ZodType;
+type Infer<S> = S extends z.ZodType ? z.infer<S> : undefined;
+
+export type RouteDef<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema> = {
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  /** Express-style, relative to /api/v2: "/events/:id". */
+  path: string;
+  summary: string;
+  description?: string;
+  tag: string;
+  access: Access;
+  /**
+   * Staff and supervisor routes must say how they treat campus-scoped staff (see
+   * utils/campusScope.js and tests/campusScopeRoutes.test.js) — e.g. "scopeEvent(params.id)".
+   */
+  campusScope?: string;
+  params?: P;
+  query?: Q;
+  body?: B;
+  response: R;
+  /** HTTP status on success (default 200). */
+  status?: number;
+  handler: (ctx: Ctx<Infer<P>, Infer<Q>, Infer<B>>) => Promise<z.input<R>> | z.input<R>;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyRoute = RouteDef<any, any, any, any>;
+
+export const routes: AnyRoute[] = [];
+
+const ACCESS: Record<Access, RequestHandler[]> = {
+  public: [],
+  optional: [auth.optionalAuth],
+  user: [auth.protect],
+  staff: [auth.protect, auth.staff],
+  supervisor: [auth.protect, auth.supervisor],
+  admin: [auth.protect, auth.admin],
+};
+
+export function defineRoute<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema>(def: RouteDef<P, Q, B, R>): RouteDef<P, Q, B, R> {
+  if ((def.access === 'staff' || def.access === 'supervisor') && !def.campusScope) {
+    throw new Error(`${def.method.toUpperCase()} /api/v2${def.path}: staff and supervisor routes must declare campusScope`);
+  }
+  routes.push(def as AnyRoute);
+  return def;
+}
+
+const parse = <S extends Schema | undefined>(schema: S, value: unknown): Infer<S> =>
+  (schema ? schema.parse(value) : undefined) as Infer<S>;
+
+/** Adds every defined route to the router. */
+export function mount(router: Router, list: AnyRoute[] = routes): void {
+  for (const def of list) {
+    const run: RequestHandler = async (req, res, next) => {
+      try {
+        const ctx = {
+          params: parse(def.params, req.params),
+          query: parse(def.query, req.query),
+          body: parse(def.body, req.body ?? {}),
+          user: (req as Request & { user?: ApiUser }).user ?? null,
+          req,
+          res,
+        };
+        const result = await def.handler(ctx);
+        const checked = def.response.safeParse(result);
+        if (!checked.success) {
+          console.error(`[api/v2] ${def.method.toUpperCase()} ${def.path}: response doesn't match its schema`, checked.error.issues);
+          throw new ApiError('INTERNAL', 'Something went wrong on the server.');
+        }
+        res.status(def.status ?? 200).json(checked.data);
+      } catch (err) {
+        next(err);
+      }
+    };
+    router[def.method](def.path, ...ACCESS[def.access], run);
+  }
+}
diff --git a/backend/src/v2/schemas.ts b/backend/src/v2/schemas.ts
new file mode 100644
index 0000000..3c3a1ae
--- /dev/null
+++ b/backend/src/v2/schemas.ts
@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+
+/** Shared pieces of v2 schemas. Dates go out as ISO 8601 strings (UTC). */
+
+export const isoDate = z.iso.datetime();
+export const id = z.string().min(1).max(64);
+export const idParams = z.object({ id: id.describe('The id') });
+
+/** A Date (or date string) as ISO 8601, for building responses. */
+export function iso(d: Date | string): string;
+export function iso(d: Date | string | null | undefined): string | null;
+export function iso(d: Date | string | null | undefined): string | null {
+  return d == null ? null : new Date(d).toISOString();
+}
+
+/** A stored picture path ("/uploads/…") as an absolute URL on the host the request came to. */
+export function absoluteUrl(req: Request, url: string | null | undefined): string | null {
+  const raw = String(url || '').trim();
+  if (!raw) return null;
+  if (/^https?:\/\//.test(raw)) return raw;
+  return `${req.protocol}://${req.get('host')}${raw.startsWith('/') ? '' : '/'}${raw}`;
+}
+
+export const campusRef = z.object({ id, name: z.string(), slug: z.string() });
+export const seriesRef = z.object({ id, name: z.string(), slug: z.string() });
+export const eventRef = z.object({ id, title: z.string(), startDate: isoDate, endDate: isoDate });
diff --git a/backend/tests/v2.test.ts b/backend/tests/v2.test.ts
new file mode 100644
index 0000000..9fe7694
--- /dev/null
+++ b/backend/tests/v2.test.ts
@@ -0,0 +1,152 @@
+import express from 'express';
+import request from 'supertest';
+
+// /api/v2 (1.51.0): the route declarations validate requests, shape responses and errors the same
+// way everywhere, and produce the OpenAPI document.
+
+const mockDb = {
+  event: { findMany: jest.fn(), count: jest.fn(), findFirst: jest.fn() },
+  user: { findUnique: jest.fn() },
+  registration: { findMany: jest.fn(), count: jest.fn() },
+};
+jest.mock('../src/config/db', () => mockDb);
+jest.mock('../src/utils/campuses', () => ({
+  campusesEnabled: jest.fn().mockResolvedValue(false),
+  resolveCampusFilter: jest.fn(async (v: string) => v),
+  campusWhere: jest.fn(() => ({})),
+}));
+
+// Signed in as whoever the test says (the real middleware checks JWTs against the database).
+let signedIn: { id: string; role: string } | null = null;
+jest.mock('../src/middleware/authMiddleware', () => {
+  const deny = (status: number, message: string) => (_req: unknown, res: { status(n: number): void }, next: (e: Error) => void) => { res.status(status); next(new Error(message)); };
+  return {
+    protect: (req: { user?: unknown }, res: { status(n: number): void }, next: (e?: Error) => void) => (signedIn ? ((req.user = signedIn), next()) : deny(401, 'Not authorized, no token')(req, res, next as (e: Error) => void)),
+    optionalAuth: (req: { user?: unknown }, _res: unknown, next: () => void) => { if (signedIn) req.user = signedIn; next(); },
+    admin: (req: { user?: { role: string } }, res: { status(n: number): void }, next: (e?: Error) => void) => (req.user?.role === 'admin' ? next() : deny(403, 'Not authorized as an admin')(req, res, next as (e: Error) => void)),
+    staff: jest.fn(), supervisor: jest.fn(),
+  };
+});
+
+import { v2Router } from '../src/v2';
+import { routes } from '../src/v2/route';
+import { buildOpenApi } from '../src/v2/openapi';
+
+const app = express();
+app.use(express.json());
+app.use('/api/v2', v2Router());
+
+const event = (over: Record<string, unknown> = {}) => ({
+  id: 'e1', title: 'Youth Camp', startDate: new Date('2026-12-04T16:00:00Z'), endDate: new Date('2026-12-06T12:00:00Z'),
+  location: 'Camp Joy', price: 600, picture: '/uploads/events/camp.jpg', requiresRegistration: true, scheduleType: 'single',
+  campus: null, series: { id: 's1', name: 'Camps', slug: 'camps' }, ...over,
+});
+
+beforeEach(() => { signedIn = null; jest.clearAllMocks(); });
+
+describe('GET /api/v2/events', () => {
+  test('a page of public events, with meta and ISO dates', async () => {
+    mockDb.event.findMany.mockResolvedValue([event()]);
+    mockDb.event.count.mockResolvedValue(31);
+    const res = await request(app).get('/api/v2/events?page=2&limit=10&q=camp');
+    expect(res.status).toBe(200);
+    expect(res.body.meta).toEqual({ page: 2, limit: 10, total: 31, pages: 4 });
+    expect(res.body.data[0]).toMatchObject({ id: 'e1', startDate: '2026-12-04T16:00:00.000Z', series: { slug: 'camps' } });
+    expect(res.body.data[0].pictureUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/uploads\/events\/camp\.jpg$/);
+    const args = mockDb.event.findMany.mock.calls[0][0];
+    expect(args).toMatchObject({ skip: 10, take: 10 });
+    expect(args.where.AND).toEqual(expect.arrayContaining([{ isActive: true, isHidden: false, goLiveAt: { lte: expect.any(Date) } }, { title: { contains: 'camp', mode: 'insensitive' } }]));
+  });
+
+  test('fields the schema does not list are never sent', async () => {
+    mockDb.event.findMany.mockResolvedValue([event({ cashupStatus: 'closed', createdById: 'u9' })]);
+    mockDb.event.count.mockResolvedValue(1);
+    const res = await request(app).get('/api/v2/events');
+    expect(Object.keys(res.body.data[0]).sort()).toEqual(['campus', 'endDate', 'id', 'location', 'pictureUrl', 'price', 'requiresRegistration', 'scheduleType', 'series', 'startDate', 'title']);
+  });
+
+  test('a bad query is a VALIDATION_FAILED error naming the field', async () => {
+    const res = await request(app).get('/api/v2/events?limit=500&page=0');
+    expect(res.status).toBe(400);
+    expect(res.body.error.code).toBe('VALIDATION_FAILED');
+    expect(Object.keys(res.body.error.fields).sort()).toEqual(['limit', 'page']);
+    expect(mockDb.event.findMany).not.toHaveBeenCalled();
+  });
+});
+
+describe('GET /api/v2/events/:id', () => {
+  test('leaves out kids and volunteer tickets and shows the early-bird price now', async () => {
+    mockDb.event.findFirst.mockResolvedValue({
+      ...event(), description: 'A weekend away', registrationDeadline: null, kidsOptionId: 'kids', volunteerOptionId: null,
+      eventOptions: [
+        { id: 'o1', name: 'Camper', price: 600, isMainTicket: true, sessionMode: 'all', earlyBirdTiers: [{ id: 't', price: 500, deadline: new Date(Date.now() + 864e5), stockLimit: 0 }] },
+        { id: 'kids', name: 'Kids check-in', price: 0, isMainTicket: false, sessionMode: 'all', earlyBirdTiers: [] },
+      ],
+      sessions: [],
+    });
+    const res = await request(app).get('/api/v2/events/e1');
+    expect(res.status).toBe(200);
+    expect(res.body.data.ticketOptions).toEqual([{ id: 'o1', name: 'Camper', price: 600, currentPrice: 500, isMainTicket: true, sessionMode: 'all' }]);
+  });
+
+  test('an unknown or private event is NOT_FOUND', async () => {
+    mockDb.event.findFirst.mockResolvedValue(null);
+    const res = await request(app).get('/api/v2/events/nope');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ error: { code: 'NOT_FOUND', message: "That event wasn't found." } });
+  });
+});
+
+describe('me', () => {
+  test('signed out is UNAUTHENTICATED in the v2 shape', async () => {
+    const res = await request(app).get('/api/v2/me');
+    expect(res.status).toBe(401);
+    expect(res.body.error.code).toBe('UNAUTHENTICATED');
+  });
+
+  test('my registrations with totals and what is owing', async () => {
+    signedIn = { id: 'u1', role: 'user' };
+    mockDb.registration.findMany.mockResolvedValue([{
+      id: 'r1', status: 'partial_paid', createdAt: new Date('2026-10-01T10:00:00Z'), discountTotal: 0,
+      event: { id: 'e1', title: 'Youth Camp', startDate: new Date('2026-12-04T16:00:00Z'), endDate: new Date('2026-12-06T12:00:00Z') },
+      registrationOptions: [{ quantity: 2, priceSnapshot: 600, eventOption: { name: 'Camper', price: 600, earlyBirdTiers: [] }, variant: null, tranches: [] }],
+      payments: [{ amount: 500, createdAt: new Date() }],
+    }]);
+    mockDb.registration.count.mockResolvedValue(1);
+    const res = await request(app).get('/api/v2/me/registrations');
+    expect(res.status).toBe(200);
+    expect(res.body.data[0]).toMatchObject({ id: 'r1', totalDue: 1200, amountPaid: 500, balance: 700, items: [{ ticket: 'Camper', variant: null, quantity: 2, unitPrice: 600 }] });
+    expect(mockDb.registration.findMany.mock.calls[0][0].where).toMatchObject({ userId: 'u1', status: { not: 'cancelled' } });
+  });
+});
+
+describe('the API description', () => {
+  test('openapi.json is for admins', async () => {
+    signedIn = { id: 'u1', role: 'user' };
+    expect((await request(app).get('/api/v2/openapi.json')).body.error.code).toBe('FORBIDDEN');
+    signedIn = { id: 'a1', role: 'admin' };
+    const res = await request(app).get('/api/v2/openapi.json');
+    expect(res.status).toBe(200);
+    expect(res.body.openapi).toBe('3.1.0');
+  });
+
+  test('every route is described, with its parameters, auth and response', () => {
+    const doc = buildOpenApi({ version: 'test' });
+    for (const r of routes) {
+      const op = (doc.paths as Record<string, Record<string, Record<string, unknown>>>)[r.path.replace(/:(\w+)/g, '{$1}')][r.method];
+      expect(op).toBeDefined();
+      expect(op.responses).toHaveProperty(String(r.status ?? 200));
+    }
+    const list = doc.paths['/events'].get as { parameters: { name: string; in: string }[]; security?: unknown };
+    expect(list.parameters.map(p => p.name)).toEqual(['page', 'limit', 'q', 'campus', 'series']);
+    expect(list.security).toBeUndefined();
+    expect((doc.paths['/me'].get as { security: unknown }).security).toEqual([{ bearerAuth: [] }]);
+    expect((doc.paths['/events/{id}'].get as { parameters: { name: string; in: string; required: boolean }[] }).parameters[0]).toMatchObject({ name: 'id', in: 'path', required: true });
+  });
+
+  test('an unknown v2 path is a v2 NOT_FOUND', async () => {
+    const res = await request(app).get('/api/v2/nothing-here');
+    expect(res.status).toBe(404);
+    expect(res.body.error.code).toBe('NOT_FOUND');
+  });
+});
diff --git a/backend/tsconfig.json b/backend/tsconfig.json
new file mode 100644
index 0000000..fb96420
--- /dev/null
+++ b/backend/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  // The backend is moving to TypeScript a file at a time (1.51.0): .js files are compiled as they
+  // are (not type-checked), .ts files are checked strictly. `npm run build` writes dist/, which is
+  // what production runs (dist/index.js); dev and the e2e tests run src/ through tsx.
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2023"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "allowJs": true,
+    "checkJs": false,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "sourceMap": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src"]
+}
diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md
index 64df75d..306b9ce 100644
--- a/docs/HANDOVER.md
+++ b/docs/HANDOVER.md
@@ -1,6 +1,6 @@
 # Handover — where things stand and how to carry on
 
-Last updated: 2026-10-29, after **1.50.2** (and Hub 1.5.0). The plan itself is in
+Last updated: 2026-10-29, after **1.51.0** (and Hub 1.5.0). The plan itself is in
 [ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
 features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 
@@ -14,6 +14,7 @@ encrypted settings unreadable or break existing installs.
 
 | Version | What |
 |---------|------|
+| 1.51.0 | **TypeScript backend + `/api/v2` foundations** (§14): tsconfig (`allowJs`), build to `dist/`, launcher `src/index.js` → `src/app.js`; v2 route declarations with zod → validation, response stripping and OpenAPI 3.1 at `/docs/v2`; first endpoints events, event, me, my registrations. Tests `tests/v2.test.ts`, e2e `e2e/api-v2.spec.ts` |
 | 1.50.2 | Searchable **event picker** (`components/shared/EventPicker.tsx`) on staff/supervisor pages and the kiosk; searchable reports events list; **How webhooks work** guide on Site settings → Webhooks (examples from `EVENT_TYPES[].example`). e2e `e2e/event-picker.spec.ts` |
 | 1.50.1 | Long lists: audit-log search/role filter/all actions and inclusive To date, data-request search and paging, webhook-delivery status filter and Load older, supervisor Payments loads only what it needs (`unpaid`, `userId`, `from`, `donations` filters). `components/shared/Pager.tsx`; e2e `e2e/long-lists.spec.ts` |
 | 1.50.0 | **Accessibility pass** (§11, WCAG 2.2 AA) on public pages, auth, registration, payment, My Events and the kiosk: skip link, focus ring, labelled fields, named quantity buttons, announced errors, `ModalOverlay` popups (focus trap, Escape), contrast and underlined in-text links, reduce-motion; Branding warns about a too-light primary colour. axe + keyboard e2e in `e2e/accessibility.spec.ts` |
@@ -61,7 +62,9 @@ encrypted settings unreadable or break existing installs.
 Hub 1.1.0 is deployed with update requests rolled out, and `scripts/install.sh` has been tried on
 a test server (both done 2026-10-28).
 
-1. **1.51.0 — TypeScript backend, OpenAPI and `/api/v2`** (§14), then **2.0.0 — AI helpers** (§15).
+1. **1.51.1 — v2 write endpoints** (register, pay, check-in, users; split `registrationController`
+   and `eventController` into TS services as they move; typed frontend calls from the schemas), then
+   **1.51.2 — the rest of v2, Express 5, v1 deprecation headers**, then **2.0.0 — AI helpers** (§15).
    Languages (Afrikaans, §10) are removed from scope (2026-10-28).
 2. AI rules decided 2026-10-29 (see §15 in the roadmap): the AI buttons show only when the
    licence's monthly cap is above R0, and are disabled (not hidden) once it's reached. The Hub
@@ -82,7 +85,7 @@ a test server (both done 2026-10-28).
   full log; WHATS-NEW.md is what churches see before updating (the Hub reads it from main every
   15 minutes, for tagged versions only and sets the latest version from the tags — nothing to do in the Hub).
 - **Docs to keep in step:** CHANGELOG.md, FEATURES.md, README.md, SETTINGS.md,
-  backend/API_DOCUMENTATION.md, the `/docs` route list in `backend/src/index.js`, and
+  backend/API_DOCUMENTATION.md, the `/docs` route list in `backend/src/app.js` (v2 documents itself), and
   in-app help in `frontend/src/content/help/` (register new pages in `registry.ts`).
 - **Prisma migrations:** `npx prisma migrate dev --create-only --name x` against a local
   DB. Prisma 7 keeps adding an unrelated `_EventNotifyRecipients` primary-key/index
@@ -450,6 +453,27 @@ a test server (both done 2026-10-28).
   `fetchAllUsers` (Payments, Email/WhatsApp attendees, Forms, Manual) — a server-side search
   picker would replace them; the coupons list; `GET /api/registrations` without `page` (other callers still use the plain array).
 
+## TypeScript and API v2 (1.51.0)
+
+- **Starting the backend:** PM2 runs `src/index.js`, a launcher. With plain Node it runs
+  `dist/app.js` when `dist/build.json` has this version; otherwise tsx compiles on the fly (with a
+  warning). tsx and typescript are runtime dependencies for that fallback. `npm run dev` and e2e
+  use tsx, so they never pick up a stale `dist/`. The server is `src/app.js`.
+- **Paths:** `dist/` mirrors `src/`, so `path.join(__dirname, '..', '..', 'public')` works from
+  both. Non-code files in `src/` aren't copied (the favicon is read from `src/`).
+- **New code in TypeScript.** Convert a JS module when a release touches it; until then import it
+  through `src/v2/legacy.ts` with a typed signature. TypeScript infers loose types from JS (the
+  Prisma client especially), so v2 code takes `prisma` from there, typed as `PrismaClient`.
+- **A v2 endpoint** is `defineRoute({ method, path, tag, summary, access, params?, query?, body?,
+  response, handler })` in `src/v2/resources/<area>.ts`, imported in `src/v2/index.ts`. Lists use
+  `pageQuery`, `paged()` and `pageOf()`; single items `single()`. Dates go out as ISO strings
+  (`iso()`), so response schemas use `isoDate`. Throw `ApiError(code, message)` or `notFound()`.
+  The response is parsed by its schema: unknown fields are dropped, and a mismatch is a 500 plus a
+  log line (tests catch it). Staff/supervisor routes must declare `campusScope` (start-up fails
+  otherwise).
+- Not yet v2-shaped: the global middleware in front of every route (rate limit, impersonation
+  read-only guard, licence read-only) still answers `{ message }`. Do that with 1.51.2.
+
 ## Event picker and webhook guide (1.50.2)
 
 - **Choosing an event:** use `EventPicker` (`components/shared/EventPicker.tsx`), not a `<select>`.
diff --git a/docs/ROADMAP-v2.md b/docs/ROADMAP-v2.md
index d7f1871..c343d61 100644
--- a/docs/ROADMAP-v2.md
+++ b/docs/ROADMAP-v2.md
@@ -38,8 +38,8 @@ Event series and cloning ships as 1.47.0–1.47.3 (2026-10-28); 1.47.0 **copy an
 report** and 1.47.3 **season passes** shipped — §6 is done. 1.48.0 **outbound webhooks** shipped. 1.49.0 **dashboard (Today, Waiting for you) and Ctrl+K palette**
 shipped; 1.49.1 **bulk actions** and 1.49.2 **saved filters** shipped — §9 is done. Languages
 (Afrikaans) are removed from scope (2026-10-28), so everything after moves up by one. 1.50.0 **accessibility
-pass** shipped. 1.50.1 **pagination and search on long lists** and 1.50.2 **event picker and webhook guide** shipped. **Next: 1.51.0 TypeScript
-backend / `/api/v2`.**
+pass** shipped. 1.50.1 **pagination and search on long lists** and 1.50.2 **event picker and webhook guide** shipped. 1.51.0 **TypeScript backend and `/api/v2`
+foundations** shipped. **Next: 1.51.1 v2 write endpoints, then 1.51.2.**
 
 **Repositories:**
 
@@ -1007,7 +1007,7 @@ income justify the hardware:
 | 8 | 1.45.0 ✅ – 1.46.0 ✅ | Kids check-in, Volunteer rosters | Depend on sessions and campuses |
 | 9 | 1.47.0 ✅ – 1.47.3 ✅, 1.48.0 ✅ | Event series & cloning (1.47.0 clone, 1.47.1 series, 1.47.2 year-on-year reports, 1.47.3 season pass), Outbound webhooks (Wallet passes removed from scope) | Smaller, independent wins |
 | 10 | 1.49.0 ✅ – 1.49.2 ✅, 1.50.0 ✅, 1.50.1 ✅, 1.50.2 ✅ | Admin dashboard/Ctrl+K/bulk actions/saved filters, Accessibility pass, pagination and search on long lists, event picker and webhook guide (Afrikaans removed from scope) | Polish before the big release |
-| 11 | 1.51.0 | TypeScript backend + OpenAPI + `/api/v2` alongside v1 | The breaking-change groundwork |
+| 11 | 1.51.0 ✅, 1.51.1, 1.51.2 | TypeScript backend + OpenAPI + `/api/v2` alongside v1: 1.51.0 foundations (build, launcher, route declarations, errors, paging, OpenAPI at `/docs/v2`, first read endpoints); 1.51.1 write endpoints and services, typed frontend calls; 1.51.2 the rest, Express 5, v1 deprecation headers | The breaking-change groundwork |
 | 12 | **2.0.0** | **AI helpers** (§15 — headline feature: draft an event, summarise reports and feedback, draft messages, improve text; through the Hub with a rand cap per licence), v1 API removed, migration guide, marketing site/docs for selling | The release. AI needs the Hub (phase 6) for the key, metering and caps |
 
 Each phase should add matching help content (`frontend/src/content/help/`),
diff --git a/e2e/api-v2.spec.ts b/e2e/api-v2.spec.ts
new file mode 100644
index 0000000..42117e2
--- /dev/null
+++ b/e2e/api-v2.spec.ts
@@ -0,0 +1,48 @@
+import { test, expect, seed, API } from "./fixtures";
+
+// /api/v2 (1.51.0) against the real server and database: paged public events, the v2 error
+// shape, the signed-in person, and the OpenAPI reference at /docs/v2.
+test.describe("API v2", () => {
+  test("public events come a page at a time; errors have a code", async ({ request }) => {
+    const res = await request.get(`${API}/api/v2/events?limit=2`);
+    expect(res.ok()).toBe(true);
+    const body = await res.json();
+    expect(body.data).toHaveLength(2);
+    expect(body.meta).toMatchObject({ page: 1, limit: 2 });
+    expect(body.meta.total).toBeGreaterThan(2);
+
+    const search = await (await request.get(`${API}/api/v2/events?q=free%20evening`)).json();
+    expect(search.data.map((e: { title: string }) => e.title)).toEqual(["E2E Free Evening"]);
+
+    const one = await (await request.get(`${API}/api/v2/events/${seed().events.paid}`)).json();
+    expect(one.data.ticketOptions.length).toBeGreaterThan(0);
+
+    const bad = await request.get(`${API}/api/v2/events?limit=1000`);
+    expect(bad.status()).toBe(400);
+    expect((await bad.json()).error).toMatchObject({ code: "VALIDATION_FAILED", fields: { limit: expect.any(String) } });
+
+    const missing = await request.get(`${API}/api/v2/events/00000000-0000-4000-8000-000000000000`);
+    expect((await missing.json()).error.code).toBe("NOT_FOUND");
+  });
+
+  test("me and my registrations need a token", async ({ request }) => {
+    expect((await request.get(`${API}/api/v2/me`)).status()).toBe(401);
+    const headers = { Authorization: `Bearer ${seed().users.user.token}` };
+    const me = await (await request.get(`${API}/api/v2/me`, { headers })).json();
+    expect(me.data).toMatchObject({ id: seed().users.user.id, role: "user" });
+    const regs = await (await request.get(`${API}/api/v2/me/registrations?past=true`, { headers })).json();
+    expect(regs.meta).toMatchObject({ page: 1, limit: 25 });
+    expect(regs.data.length).toBe(Math.min(25, regs.meta.total));
+  });
+
+  test("an admin can read the OpenAPI reference at /docs/v2", async ({ page, request }) => {
+    const headers = { Authorization: `Bearer ${seed().users.user.token}` };
+    expect((await request.get(`${API}/api/v2/openapi.json`, { headers })).status()).toBe(403);
+
+    await page.goto(`${API}/docs/v2?token=${seed().users.admin.token}`);
+    await expect(page.getByRole("heading", { name: /Cross Events API/ })).toBeVisible();
+    await expect(page.locator(".opblock-summary-path", { hasText: "/events/{id}" })).toBeVisible();
+    // The token isn't left in the address bar.
+    expect(page.url()).not.toContain("token=");
+  });
+});
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 0b53abc..2a910df 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hope-events-frontend",
-      "version": "1.50.2",
+      "version": "1.51.0",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",
         "@hookform/resolvers": "^5.2.1",
diff --git a/frontend/package.json b/frontend/package.json
index eb6ed98..41e6d14 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "private": true,
   "scripts": {
     "dev": "next dev --turbopack",
diff --git a/package-lock.json b/package-lock.json
index d70aef6..de0d678 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "hope-events",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hope-events",
-      "version": "1.50.2",
+      "version": "1.51.0",
       "license": "ISC",
       "devDependencies": {
         "@axe-core/playwright": "^4.14.0",
diff --git a/package.json b/package.json
index 6c92b63..f1ea3dc 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hope-events",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "main": "index.js",
   "scripts": {
     "dev:backend": "cd backend && npm run dev",
diff --git a/playwright.config.ts b/playwright.config.ts
index 3d622ba..d1e1759 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -32,7 +32,8 @@ export default defineConfig({
   projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
   webServer: [
     {
-      command: "node ../e2e/support/prepare-db.js && node src/index.js",
+      // tsx runs the TypeScript straight from src/ (never a stale dist/ build).
+      command: "node ../e2e/support/prepare-db.js && npx tsx src/index.js",
       cwd: "backend",
       url: `http://localhost:${API_PORT}/api/settings/needs-setup`,
       timeout: 180_000,
diff --git a/scripts/deploy.sh b/scripts/deploy.sh
index a54b6af..ddc6788 100644
--- a/scripts/deploy.sh
+++ b/scripts/deploy.sh
@@ -63,7 +63,8 @@ rollback() {
   clear_pm2_config
   git checkout -q "$PREVIOUS"
   restore_pm2_config
-  (cd backend && npm ci --silent) || true
+  # Releases from 1.51.0 on have a TypeScript build; older ones run src/ as it is.
+  (cd backend && npm ci --include=dev --silent && { ! grep -q '"build":' package.json || npm run build --silent; }) || true
   (cd frontend && npm ci --silent && npm run build --silent) || true
 }
 trap rollback ERR
@@ -76,8 +77,9 @@ if [ ! -f "$PM2_CONFIG" ]; then
   echo "    Created $PM2_CONFIG from the example — check its app names and port."
 fi
 
-echo "==> Backend: install and migrate"
-(cd backend && npm ci && npm run prisma:deploy)
+echo "==> Backend: install, migrate and build"
+# --include=dev: the TypeScript build needs the type packages even where NODE_ENV=production.
+(cd backend && npm ci --include=dev && npm run prisma:deploy && npm run build)
 
 echo "==> Frontend: install and build"
 (cd frontend && npm ci && npm run build)
diff --git a/scripts/install.sh b/scripts/install.sh
index 1d34fbb..e5a1b0f 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -125,7 +125,7 @@ chown "$APP_USER:$APP_USER" "$DIR/backend/.env" "$DIR/frontend/.env.production"
 chmod 600 "$DIR/backend/.env"
 
 step "Install, migrate, build"
-as_app "cd '$DIR/backend' && npm ci --no-audit --no-fund && npx prisma migrate deploy && npx prisma generate"
+as_app "cd '$DIR/backend' && npm ci --include=dev --no-audit --no-fund && npx prisma migrate deploy && npx prisma generate && npm run build"
 as_app "cd '$DIR/frontend' && npm ci --no-audit --no-fund && npm run build"
 
 step "Start with PM2"