Docs: 2.0 progress, marketing site plan, AI tested

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

CHANGELOG.md

@@ -7,6 +7,43 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **AI helpers — the plumbing** (2.0, roadmap §15). The site calls AI through the Cross Events Hub
+  (protocol §3b, Hub 1.6.0), which holds the Claude API key and a monthly allowance in rand per
+  licence; no key is ever stored on the site. `GET /api/v2/ai/status` says whether to show the AI
+  buttons: hidden when the licence has no AI (worked out from the licence token, without asking the
+  Hub), disabled with the reason once the month's allowance is used up or the Hub can't be reached.
+  The answer is cached for a minute and refreshed by every AI call. `<AiButton>` and
+  `useAiStatus()` on the frontend; only supervisors and admins see AI.
+- **Site settings → AI** (admins): this month's use against the allowance, use per person, per
+  helper and per day, a switch per helper, and an optional most-uses-per-person-per-day. Admins are
+  emailed once a month when 80% is used. Changes are audited (`ai_settings_changed`).
+- Each AI call is logged in `AiCall` (person, helper, outcome, cost — never the prompt or answer);
+  anonymising an account unlinks its calls, and calls go after 13 months. Anthropic is added to the
+  operator register, switched off until a site uses AI. Migration `20261030120000_ai_helpers`.
+- v2 errors have a new code, `UNAVAILABLE` (503), for when the Hub or the AI service can't be
+  reached.
+
+## [1.51.17] - 2026-10-30 — security release
+
+### Security
+
+- **Forgot password no longer reveals whether an account exists.** It answered "Email not found"
+  (404) for an unknown address, so anyone could check which emails have accounts. It now gives
+  the same answer and status for every address, sent before any work that only happens for a
+  real account (so the response time doesn't tell either); the reset link is made and sent
+  afterwards. Applies to `POST /api/users/forgot` and `POST /api/v2/auth/password/forgot`.
+- **Sign-in no longer reveals it either.** An unknown email answered "User does not exist" (with a
+  different status on v1); it now gets exactly the answer a wrong password gets, after a password
+  check against a stand-in hash so it takes as long.
+- Forgot password is rate-limited like sign-in, so it can't be used to flood someone's inbox with
+  reset emails.
+
+### Upgrading
+
+- Update as soon as you can. Nothing else changes; the forgot-password page shows the new message.
+
 ## [1.51.16] - 2026-10-30
 
 ### Added

WHATS-NEW.md

@@ -12,6 +12,11 @@ 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.17 — security update
+
+- **Better protection for people's accounts.** The forgot-password and sign-in pages no longer
+  let anyone find out whether an email address has an account here.
+
 ## 1.51.16
 
 - **The move to the new server connection is complete.** Payment confirmations from Yoco and

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "event-management-backend",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "event-management-backend",
-      "version": "1.51.16",
+      "version": "1.51.17",
       "hasInstallScript": true,
       "dependencies": {
         "@cj-tech-master/excelts": "^10.2.0",

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "event-management-backend",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "description": "Event Management System Backend",
   "main": "src/index.js",
   "scripts": {

backend/prisma/migrations/20261030120000_ai_helpers/migration.sql

@@ -0,0 +1,28 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'ai_settings_changed';
+
+-- CreateTable
+CREATE TABLE "AiCall" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT,
+    "helper" TEXT NOT NULL,
+    "outcome" TEXT NOT NULL,
+    "chargedCents" DOUBLE PRECISION NOT NULL DEFAULT 0,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "AiCall_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "AiCall_createdAt_idx" ON "AiCall"("createdAt");
+
+-- CreateIndex
+CREATE INDEX "AiCall_userId_createdAt_idx" ON "AiCall"("userId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "AiCall" ADD CONSTRAINT "AiCall_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+
+-- 2.0 AI helpers: Anthropic in the operator register, off until the site uses AI.
+INSERT INTO "Operator" ("id", "name", "purpose", "dataShared", "location", "website", "active", "order", "updatedAt") VALUES
+  (gen_random_uuid()::text, 'Anthropic (Claude), through the software provider''s Hub', 'AI helpers for staff: drafting events and messages, improving text, summarising reports and feedback', 'The text a staff member asks to draft or improve, report figures, and feedback comments with names and contact details removed. Not kept by the software provider; Anthropic''s commercial terms apply', 'United States', 'https://www.anthropic.com/legal/privacy', false, 9, CURRENT_TIMESTAMP);

backend/prisma/schema.prisma

@@ -165,6 +165,7 @@ model User {
   seriesFollows       SeriesFollow[]
   seasonPassPurchases SeasonPassPurchase[]
   savedFilters        SavedFilter[]
+  aiCalls             AiCall[]
   swapsAsked          VolunteerSwap[] @relation("VolunteerSwapFrom")
   swapsTaken          VolunteerSwap[] @relation("VolunteerSwapTo")
 
@@ -820,6 +821,7 @@ enum AdminAuditAction {
   season_pass_changed
   webhook_endpoint_changed
   registrations_bulk
+  ai_settings_changed
 }
 
 // Append-only audit trail for admin/supervisor-initiated actions with money or
@@ -2315,3 +2317,21 @@ model SavedFilter {
   @@unique([userId, page, name])
   @@index([userId, page])
 }
+
+/// One AI helper call (2.0). The Hub meters the money; this copy is for Site settings → AI (use
+/// per person, per helper and per day) and per-person daily limits. No prompt or answer text is
+/// kept. `userId` is cleared when the account is anonymised; rows go after 13 months.
+model AiCall {
+  id           String   @id @default(uuid())
+  userId       String?
+  helper       String
+  // ok, refused, incomplete, failed, cap_reached, unavailable
+  outcome      String
+  // What the church was charged, in cents (fractions of a cent).
+  chargedCents Float    @default(0)
+  createdAt    DateTime @default(now())
+  user         User?    @relation(fields: [userId], references: [id], onDelete: SetNull)
+
+  @@index([createdAt])
+  @@index([userId, createdAt])
+}

backend/src/ai/index.ts

@@ -0,0 +1,263 @@
+/**
+ * AI helpers (2.0, roadmap §15). The site never holds a Claude API key: every call goes through
+ * the Cross Events Hub (docs/hub-protocol.md §3b), which checks the licence's monthly cap in rand,
+ * calls Claude and meters the call. This module:
+ *   - works out what the AI buttons do (`aiStatus`): hidden, working, or disabled until the
+ *     allowance renews — from the licence token first, then the Hub (cached for a minute);
+ *   - runs one helper call (`runHelper`), with this site's own switches per helper and an optional
+ *     daily limit per person, and logs it in `AiCall` (no prompt or answer text);
+ *   - emails the site admins once a month when 80% of the allowance is used.
+ * The helpers themselves (prompts, schemas, what they send) are in ./helpers.ts.
+ */
+
+import { ApiError } from '../v2/errors';
+import { prisma } from '../v2/legacy';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS Hub client and helpers aren't typed */
+const hub = require('../hub/client') as {
+  PROTOCOL_VERSION: number;
+  signedPost(path: string, body: object, opts?: { timeoutMs?: number }): Promise<any>;
+  HubError: new (...args: any[]) => Error & { code: string; statusCode: number; data: any };
+};
+const { licenceStatus } = require('../hub/licence') as {
+  licenceStatus(): Promise<{ connected: boolean; claims: { limits?: { aiMonthlyCapCents?: number } } | null; state: string; readOnly: boolean }>;
+};
+const email = require('../utils/email') as {
+  sendMail(m: { to: string; subject: string; html: string; text: string }): Promise<unknown>;
+  emailWrapper(body: string): string;
+  isSmtpConfigured(): boolean;
+};
+const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise<unknown> };
+
+export const HELPERS = ['draft_event', 'summarise_report', 'draft_message', 'summarise_feedback', 'improve_text'] as const;
+export type HelperName = (typeof HELPERS)[number];
+
+/** What the Hub says (§3b). Cents are charged rand, with fractions. */
+export type HubAiStatus = { enabled: boolean; capReached: boolean; capCents: number; usedCents: number; usedPercent: number; renewsOn: string | null };
+/** What the buttons need: the Hub's answer, whether it could be reached, and this site's switches. */
+export type AiStatus = HubAiStatus & { available: boolean; helpers: Record<HelperName, boolean> };
+
+export type AiSettings = { helpers: Record<HelperName, boolean>; dailyLimitPerPerson: number };
+const SETTINGS_KEY = 'ai_settings';
+const WARNED_KEY = 'ai_warned_month';
+const STATUS_TTL_MS = 60 * 1000;
+const CALL_TIMEOUT_MS = 90 * 1000;
+const KEEP_CALLS_DAYS = 400;
+
+const OFF: HubAiStatus = { enabled: false, capReached: false, capCents: 0, usedCents: 0, usedPercent: 0, renewsOn: null };
+
+// ─── This site's settings ─────────────────────────────────────────────────────
+
+export const DEFAULT_SETTINGS: AiSettings = { helpers: Object.fromEntries(HELPERS.map(h => [h, true])) as Record<HelperName, boolean>, dailyLimitPerPerson: 0 };
+
+export async function getAiSettings(): Promise<AiSettings> {
+  const row = await prisma.appSetting.findUnique({ where: { key: SETTINGS_KEY } });
+  let saved: Partial<AiSettings> = {};
+  try { saved = row ? JSON.parse(row.value) : {}; } catch { /* keep the defaults */ }
+  return {
+    helpers: { ...DEFAULT_SETTINGS.helpers, ...Object.fromEntries(HELPERS.filter(h => typeof saved.helpers?.[h] === 'boolean').map(h => [h, saved.helpers![h]])) },
+    dailyLimitPerPerson: Number.isInteger(saved.dailyLimitPerPerson) && saved.dailyLimitPerPerson! >= 0 ? saved.dailyLimitPerPerson! : 0,
+  };
+}
+
+export async function saveAiSettings(next: { helpers?: Partial<Record<HelperName, boolean | undefined>>; dailyLimitPerPerson?: number }, actor: { id: string; role: string }, ip?: string): Promise<AiSettings> {
+  const current = await getAiSettings();
+  const changed = Object.fromEntries(HELPERS.filter(h => typeof next.helpers?.[h] === 'boolean').map(h => [h, next.helpers![h]]));
+  const value: AiSettings = {
+    helpers: { ...current.helpers, ...changed },
+    dailyLimitPerPerson: next.dailyLimitPerPerson ?? current.dailyLimitPerPerson,
+  };
+  await prisma.appSetting.upsert({ where: { key: SETTINGS_KEY }, update: { value: JSON.stringify(value) }, create: { key: SETTINGS_KEY, value: JSON.stringify(value) } });
+  await logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'ai_settings_changed', targetType: 'setting', targetId: SETTINGS_KEY, metadata: value, ip });
+  return value;
+}
+
+// ─── Status ───────────────────────────────────────────────────────────────────
+
+let cached: { at: number; value: HubAiStatus; available: boolean } | null = null;
+
+/** Keep what the Hub just said (every AI reply and error carries it). */
+function remember(value: unknown, available = true): void {
+  const v = value as Partial<HubAiStatus> | null;
+  if (v && typeof v.enabled === 'boolean') cached = { at: Date.now(), value: { ...OFF, ...v } as HubAiStatus, available };
+}
+
+export function clearAiStatusCache(): void {
+  cached = null;
+}
+
+/**
+ * The cap from the licence token (refreshed by every heartbeat): no Hub call is needed to know AI
+ * is off, which is most sites.
+ */
+async function licenceCap(): Promise<number> {
+  const l = await licenceStatus();
+  if (!l.connected || !l.claims || l.readOnly) return 0;
+  return Number(l.claims.limits?.aiMonthlyCapCents) || 0;
+}
+
+async function hubStatus(fresh = false): Promise<{ value: HubAiStatus; available: boolean }> {
+  if (!fresh && cached && Date.now() - cached.at < STATUS_TTL_MS) return cached;
+  try {
+    remember(await hub.signedPost('/api/installs/ai/status', { protocolVersion: hub.PROTOCOL_VERSION }));
+  } catch (e) {
+    const err = e as { code?: string; statusCode?: number };
+    // A Hub before 1.6.0 has no AI; a released install has no licence: both mean off.
+    if (err.statusCode === 404) cached = { at: Date.now(), value: OFF, available: true };
+    else {
+      console.warn('[ai] could not ask the Hub for the AI status:', (e as Error).message);
+      // Unreachable: keep showing the buttons (they say AI is unavailable when pressed).
+      cached = { at: Date.now(), value: { ...(cached?.value || OFF), enabled: true }, available: false };
+    }
+  }
+  return cached!;
+}
+
+export async function aiStatus({ fresh = false } = {}): Promise<AiStatus> {
+  const settings = await getAiSettings();
+  if ((await licenceCap()) <= 0) return { ...OFF, available: true, helpers: settings.helpers };
+  const { value, available } = await hubStatus(fresh);
+  return { ...value, available, helpers: settings.helpers };
+}
+
+// ─── Running a helper ─────────────────────────────────────────────────────────
+
+export type HelperRequest = {
+  /** The helper's fixed instructions (the Hub has Claude cache them). */
+  system: string;
+  /** This request's text. Never names, contact details, medical or children's information. */
+  input: string;
+  /** A JSON schema: the answer comes back as JSON in this shape. */
+  schema?: object;
+  maxTokens: number;
+  effort?: 'low' | 'medium' | 'high';
+};
+
+const failure = (code: 'FORBIDDEN' | 'RATE_LIMITED' | 'UNAVAILABLE', reason: string, message: string) => Object.assign(new ApiError(code, message), { reason });
+
+function renewsText(renewsOn: string | null): string {
+  if (!renewsOn) return 'next month';
+  return new Date(`${renewsOn}T12:00:00Z`).toLocaleDateString('en-ZA', { day: 'numeric', month: 'long', timeZone: 'Africa/Johannesburg' });
+}
+
+/** The Hub's errors (§3b) as v2 errors, and what to log. */
+function fromHubError(e: { code?: string; statusCode?: number; message: string; data?: any }): { error: ApiError; outcome: string } {
+  remember(e.data?.status);
+  switch (e.code) {
+    case 'AI_CAP_REACHED':
+      return { outcome: 'cap_reached', error: failure('FORBIDDEN', 'AI_CAP_REACHED', `This month's AI allowance is used up — it renews on ${renewsText(e.data?.status?.renewsOn ?? null)}.`) };
+    case 'AI_OFF': case 'LICENCE_INACTIVE': case 'AI_NOT_CONFIGURED':
+      return { outcome: 'unavailable', error: failure('FORBIDDEN', 'AI_OFF', 'AI helpers are not available on this site.') };
+    case 'AI_REFUSED':
+      return { outcome: 'refused', error: failure('UNAVAILABLE', 'AI_REFUSED', "The AI couldn't help with this one. Try wording it differently.") };
+    case 'AI_INCOMPLETE':
+      return { outcome: 'incomplete', error: failure('UNAVAILABLE', 'AI_INCOMPLETE', 'The answer was too long and got cut off. Try asking for less.') };
+    case 'AI_INPUT_TOO_LARGE':
+      return { outcome: 'failed', error: failure('UNAVAILABLE', 'AI_INPUT_TOO_LARGE', 'There is too much here to send in one go.') };
+    case 'AI_FAILED':
+      return { outcome: 'failed', error: failure('UNAVAILABLE', 'AI_FAILED', "The AI's answer couldn't be used. Try again.") };
+    default:
+      return { outcome: 'unavailable', error: failure('UNAVAILABLE', 'AI_UNAVAILABLE', 'AI is unavailable right now. Try again in a few minutes.') };
+  }
+}
+
+/** Starts of today in South African time, for the per-person daily limit. */
+function startOfToday(now = new Date()): Date {
+  const sast = new Date(now.getTime() + 2 * 3600 * 1000);
+  return new Date(Date.UTC(sast.getUTCFullYear(), sast.getUTCMonth(), sast.getUTCDate()) - 2 * 3600 * 1000);
+}
+
+let prunedOn = '';
+/** Calls older than about 13 months go (once a day, on the first call). */
+async function pruneOldCalls(now = new Date()): Promise<void> {
+  const today = now.toISOString().slice(0, 10);
+  if (prunedOn === today) return;
+  prunedOn = today;
+  await prisma.aiCall.deleteMany({ where: { createdAt: { lt: new Date(now.getTime() - KEEP_CALLS_DAYS * 86400000) } } }).catch(() => {});
+}
+
+/** At 80% of the allowance, the site's admins get one email a month. */
+async function warnAt80(status: HubAiStatus): Promise<void> {
+  if (!status.enabled || status.usedPercent < 80 || !status.renewsOn) return;
+  const row = await prisma.appSetting.findUnique({ where: { key: WARNED_KEY } });
+  if (row?.value === status.renewsOn) return;
+  await prisma.appSetting.upsert({ where: { key: WARNED_KEY }, update: { value: status.renewsOn }, create: { key: WARNED_KEY, value: status.renewsOn } });
+  if (!email.isSmtpConfigured()) return;
+  const admins = await prisma.user.findMany({ where: { role: 'admin', isActive: true }, select: { email: true } });
+  const when = renewsText(status.renewsOn);
+  const text = `This site has used ${status.usedPercent}% of this month's AI allowance (R${(status.usedCents / 100).toFixed(2)} of R${(status.capCents / 100).toFixed(2)}). The AI buttons stop working when it runs out, until it renews on ${when}. Site settings → AI shows who used it and for what.`;
+  for (const a of admins) {
+    await email.sendMail({ to: a.email, subject: `AI allowance ${status.usedPercent}% used`, text, html: email.emailWrapper(`<p>${text}</p>`) })
+      .catch(e => console.warn('[ai] 80% warning email failed:', (e as Error).message));
+  }
+}
+
+/**
+ * Run one helper call for a person. Resolves to the answer (text, or JSON when a schema was
+ * given) and the new status; throws an ApiError with a `reason` (AI_OFF, AI_HELPER_OFF,
+ * AI_CAP_REACHED, AI_DAILY_LIMIT, AI_REFUSED, AI_INCOMPLETE, AI_UNAVAILABLE…).
+ */
+export async function runHelper(helper: HelperName, userId: string, req: HelperRequest): Promise<{ output: unknown; status: AiStatus }> {
+  const status = await aiStatus();
+  if (!status.enabled) throw failure('FORBIDDEN', 'AI_OFF', 'AI helpers are not available on this site.');
+  if (!status.helpers[helper]) throw failure('FORBIDDEN', 'AI_HELPER_OFF', 'This AI helper is switched off in Site settings → AI.');
+  if (status.capReached) throw failure('FORBIDDEN', 'AI_CAP_REACHED', `This month's AI allowance is used up — it renews on ${renewsText(status.renewsOn)}.`);
+  const { dailyLimitPerPerson } = await getAiSettings();
+  if (dailyLimitPerPerson > 0) {
+    const today = await prisma.aiCall.count({ where: { userId, createdAt: { gte: startOfToday() }, outcome: { in: ['ok', 'refused', 'incomplete'] } } });
+    if (today >= dailyLimitPerPerson) throw failure('RATE_LIMITED', 'AI_DAILY_LIMIT', `You've used the AI helpers ${dailyLimitPerPerson} times today, the most this site allows. Try again tomorrow.`);
+  }
+
+  let outcome = 'ok';
+  let chargedCents = 0;
+  try {
+    const reply = await hub.signedPost('/api/installs/ai/complete', { protocolVersion: hub.PROTOCOL_VERSION, helper, ...req }, { timeoutMs: CALL_TIMEOUT_MS });
+    chargedCents = Number(reply.chargedCents) || 0;
+    remember(reply.status);
+    await warnAt80(reply.status).catch(e => console.warn('[ai] 80% check failed:', (e as Error).message));
+    return { output: reply.output, status: { ...(cached?.value || OFF), available: true, helpers: status.helpers } };
+  } catch (e) {
+    if (e instanceof ApiError) throw e;
+    const mapped = fromHubError(e as Error & { code?: string; data?: any });
+    outcome = mapped.outcome;
+    if ((e as { code?: string }).code === 'HUB_UNREACHABLE') remember(cached?.value || { ...OFF, enabled: true }, false);
+    throw mapped.error;
+  } finally {
+    await prisma.aiCall.create({ data: { userId, helper, outcome, chargedCents } }).catch(err => console.warn('[ai] could not log the call:', (err as Error).message));
+    await pruneOldCalls();
+  }
+}
+
+// ─── Usage (Site settings → AI) ───────────────────────────────────────────────
+
+/** This month's use on this site: per person, per helper and per day (South African time). */
+export async function usageThisMonth(now = new Date()) {
+  const sast = new Date(now.getTime() + 2 * 3600 * 1000);
+  const from = new Date(Date.UTC(sast.getUTCFullYear(), sast.getUTCMonth(), 1) - 2 * 3600 * 1000);
+  const calls = await prisma.aiCall.findMany({ where: { createdAt: { gte: from } }, select: { userId: true, helper: true, outcome: true, chargedCents: true, createdAt: true } });
+  const add = (m: Map<string, { uses: number; chargedCents: number }>, key: string, cents: number) => {
+    const v = m.get(key) || { uses: 0, chargedCents: 0 };
+    v.uses++;
+    v.chargedCents += cents;
+    m.set(key, v);
+  };
+  const byPerson = new Map<string, { uses: number; chargedCents: number }>();
+  const byHelper = new Map<string, { uses: number; chargedCents: number }>();
+  const byDay = new Map<string, { uses: number; chargedCents: number }>();
+  for (const c of calls) {
+    if (c.outcome === 'cap_reached' || c.outcome === 'unavailable') continue;
+    add(byPerson, c.userId || '', c.chargedCents);
+    add(byHelper, c.helper, c.chargedCents);
+    add(byDay, new Date(c.createdAt.getTime() + 2 * 3600 * 1000).toISOString().slice(0, 10), c.chargedCents);
+  }
+  const people = await prisma.user.findMany({ where: { id: { in: [...byPerson.keys()].filter(Boolean) } }, select: { id: true, name: true } });
+  const names = new Map(people.map(p => [p.id, p.name]));
+  return {
+    people: [...byPerson.entries()].map(([id, v]) => ({ userId: id || null, name: id ? names.get(id) || 'Unknown' : 'Removed account', ...v })).sort((a, b) => b.chargedCents - a.chargedCents),
+    helpers: [...byHelper.entries()].map(([helper, v]) => ({ helper, ...v })).sort((a, b) => b.chargedCents - a.chargedCents),
+    days: [...byDay.entries()].map(([day, v]) => ({ day, ...v })).sort((a, b) => a.day.localeCompare(b.day)),
+  };
+}
+
+// For tests.
+export const _internal = { fromHubError, startOfToday, renewsText };

backend/src/controllers/userController.js

@@ -539,55 +539,52 @@ const requestPasswordReset = async (req, res) => {
 
     const user = await prisma.user.findUnique({ where: { email } });
 
-    // Explicitly check existence as requested
-    if (!user) {
-      return res.status(404).json({ message: 'Email not found' });
-    }
-
-    // Create token valid for 1 hour
-    const token = uuidv4();
-    const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
-
-    // If PasswordReset model isn't available (migration not run), return clear error
-    if (!prisma.passwordReset || typeof prisma.passwordReset.create !== 'function' || typeof prisma.passwordReset.updateMany !== 'function') {
-      console.warn('[PasswordReset] Prisma model not available. Run Prisma migrations to enable password reset tokens.');
-      return res.status(500).json({ message: 'Password reset is not available. Please contact support.' });
-    }
-
-    // Invalidate previous tokens (optional)
-    await prisma.passwordReset.updateMany({
-      where: { userId: user.id, used: false, expiresAt: { gt: new Date() } },
-      data: { used: true }
-    });
-
-    await prisma.passwordReset.create({
-      data: {
-        id: uuidv4(),
-        userId: user.id,
-        token,
-        expiresAt,
-        used: false
-      }
-    });
-
-    const baseUrl = process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001';
-    const resetUrl = `${baseUrl.replace(/\/$/, '')}/reset-password?token=${encodeURIComponent(token)}`;
-
-    const { sendMail, buildPasswordResetEmail } = require('../utils/email');
-    const emailContent = buildPasswordResetEmail({ name: user.name, resetUrl });
-    // Security: always email
-    sendMail({ to: user.email, subject: 'Reset your password', ...emailContent })
-      .catch(e => console.warn('[password reset email] Failed:', e?.message || e));
-    // Also WhatsApp if preferred (security message — sent in addition to email)
-    const { waText } = require('../utils/notify');
-    waText(user, emailContent.text).catch(() => {});
-
-    return res.json({ message: 'If that email exists, a password reset link has been sent.' });
+    // Security (1.51.17): the same answer, with the same status, whether or not an account has
+    // this email — and it's sent before any work that only happens for real accounts, so the
+    // response time doesn't tell either. The link is made and sent afterwards.
+    res.json({ message: GENERIC_RESET_MESSAGE });
+    if (user) sendPasswordResetLink(user).catch(e => console.warn('[password reset] Failed:', e?.message || e));
   } catch (error) {
     res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
   }
 };
 
+const GENERIC_RESET_MESSAGE = 'If an account uses that email, we\'ve sent it a link to reset the password.';
+
+/** A one-hour reset link for this account, by email (and WhatsApp when they prefer it). */
+async function sendPasswordResetLink(user) {
+  const token = uuidv4();
+  const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
+
+  // Invalidate previous tokens (optional)
+  await prisma.passwordReset.updateMany({
+    where: { userId: user.id, used: false, expiresAt: { gt: new Date() } },
+    data: { used: true }
+  });
+
+  await prisma.passwordReset.create({
+    data: {
+      id: uuidv4(),
+      userId: user.id,
+      token,
+      expiresAt,
+      used: false
+    }
+  });
+
+  const baseUrl = process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001';
+  const resetUrl = `${baseUrl.replace(/\/$/, '')}/reset-password?token=${encodeURIComponent(token)}`;
+
+  const { sendMail, buildPasswordResetEmail } = require('../utils/email');
+  const emailContent = buildPasswordResetEmail({ name: user.name, resetUrl });
+  // Security: always email
+  sendMail({ to: user.email, subject: 'Reset your password', ...emailContent })
+    .catch(e => console.warn('[password reset email] Failed:', e?.message || e));
+  // Also WhatsApp if preferred (security message — sent in addition to email)
+  const { waText } = require('../utils/notify');
+  waText(user, emailContent.text).catch(() => {});
+}
+
 // @desc    Reset password using token
 // @route   POST /api/users/reset
 // @access  Public

backend/src/hub/client.js

@@ -25,10 +25,12 @@ function hubUrl() {
 }
 
 class HubError extends Error {
-  constructor(message, code, status) {
+  constructor(message, code, status, data = null) {
     super(message);
     this.code = code;
     this.statusCode = status;
+    // The Hub's whole error body (AI errors carry the new AI status, protocol §3b).
+    this.data = data;
   }
 }
 
@@ -53,7 +55,7 @@ async function read(keys) {
   return Object.fromEntries(rows.map(r => [r.key, r.value]));
 }
 
-async function post(path, body, headers = {}) {
+async function post(path, body, headers = {}, timeoutMs = TIMEOUT_MS) {
   const raw = JSON.stringify(body);
   let res;
   try {
@@ -61,18 +63,21 @@ async function post(path, body, headers = {}) {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...(typeof headers === 'function' ? headers(raw) : headers) },
       body: raw,
-      signal: AbortSignal.timeout(TIMEOUT_MS),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (e) {
     throw new HubError(`The Hub (${hubUrl()}) could not be reached: ${e?.message || e}`, 'HUB_UNREACHABLE', 502);
   }
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status);
+  if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status, data);
   return data;
 }
 
-/** POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection. */
-async function signedPost(path, body) {
+/**
+ * POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection.
+ * AI calls wait longer than the default (Claude can take a while to write).
+ */
+async function signedPost(path, body, { timeoutMs = TIMEOUT_MS } = {}) {
   const s = await read(['hub_install_id', 'hub_install_secret']);
   if (!s.hub_install_id || !s.hub_install_secret) throw new HubError('This site isn\'t connected to the Hub yet.', 'NOT_CONNECTED', 400);
   const secret = decrypt(s.hub_install_secret);
@@ -83,7 +88,7 @@ async function signedPost(path, body) {
       'X-Hub-Timestamp': timestamp,
       'X-Hub-Signature': crypto.createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex'),
     };
-  });
+  }, timeoutMs);
 }
 
 /** Register this install with a licence key. Returns the licence claims. */
@@ -211,4 +216,4 @@ function heartbeatSoon(delayMs = 30 * 1000) {
   soonTimer.unref?.();
 }
 
-module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };
+module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, signedPost, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };

backend/src/routes/userRoutes.js

@@ -33,7 +33,7 @@ router.post('/', registerUser);
 router.post('/login', loginLimiter, loginUser);
 router.post('/login/2fa', loginLimiter, verifyLoginTwoFactor);
 router.post('/login/2fa/resend', loginLimiter, resendLoginTwoFactor);
-router.post('/forgot', requestPasswordReset);
+router.post('/forgot', loginLimiter, requestPasswordReset);
 router.post('/reset', resetPassword);
 router.post('/activate', activateAccount);
 

backend/src/services/auth.ts

@@ -207,6 +207,10 @@ export type LoginResult =
   | { status: 'signed_in'; session: Session }
   | { status: 'code_required'; challenge: { challengeId: string; method: string; destination: string | null }; enrolling: boolean };
 
+let standIn: Promise<string> | null = null;
+/** A hash nobody's password matches, so a sign-in with an unknown email does the same work. */
+const standInHash = () => (standIn ??= auth.hashPassword(uuidv4()));
+
 const MAX_ATTEMPTS = 5;
 const LOCK_TIME = 5 * 60 * 1000;
 
@@ -219,7 +223,12 @@ export async function logIn(input: { identifier: string; password: string; devic
   // SA local format (0xx) → international (27xx)
   const normalizedPhone = whatsapp().normalizeZAPhone(rawInput) || rawInput.replace(/\D/g, '');
   const user = await prisma.user.findFirst({ where: { OR: [{ email: rawInput }, ...(normalizedPhone ? [{ phoneNumber: normalizedPhone }] : [])] } });
-  if (!user) return fail(401, 'User does not exist');
+  // Security (1.51.17): an unknown email answers like a wrong password — same message and
+  // status, and a password check against a stand-in hash so it takes as long.
+  if (!user) {
+    await auth.comparePassword(input.password, await standInHash());
+    return fail(401, 'Invalid email or password', undefined, { v1Status: 400 });
+  }
 
   if (!user.isActive) {
     // Resend the activation link on each attempt, in case the earlier one expired.

backend/src/utils/privacy.js

@@ -469,6 +469,8 @@ async function anonymiseUser(userId, db = prisma) {
     await tx.webhookDelivery.deleteMany({ where: { userId } });
     // Their saved list filters (can hold search text, such as names).
     await tx.savedFilter.deleteMany({ where: { userId } });
+    // AI helper calls (2.0): kept for the site's monthly totals, no longer linked to them.
+    await tx.aiCall.updateMany({ where: { userId }, data: { userId: null } });
 
     return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted, shiftsGivenUp };
   });

backend/src/v2/errors.ts

@@ -14,6 +14,7 @@ export type ErrorCode =
   | 'CONFLICT'
   | 'RATE_LIMITED'
   | 'READ_ONLY'
+  | 'UNAVAILABLE'
   | 'INTERNAL';
 
 export const ERROR_STATUS: Record<ErrorCode, number> = {
@@ -24,6 +25,8 @@ export const ERROR_STATUS: Record<ErrorCode, number> = {
   CONFLICT: 409,
   RATE_LIMITED: 429,
   READ_ONLY: 403,
+  // Something this depends on (the Hub, the AI service) can't be reached right now.
+  UNAVAILABLE: 503,
   INTERNAL: 500,
 };
 
@@ -54,7 +57,7 @@ export function zodFields(err: ZodError): Record<string, string> {
   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 STATUS_CODE: Record<number, ErrorCode> = { 400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 409: 'CONFLICT', 423: 'READ_ONLY', 429: 'RATE_LIMITED', 503: 'UNAVAILABLE' };
 const PRISMA_CODE: Record<string, ErrorCode> = { P2002: 'CONFLICT', P2025: 'NOT_FOUND', P2003: 'CONFLICT' };
 
 type LegacyError = Error & { statusCode?: number; status?: number; code?: string };

backend/src/v2/index.ts

@@ -21,6 +21,7 @@ import './resources/peopleMessaging';
 import './resources/adminPrivacy';
 import './resources/checkin';
 import './resources/auth';
+import './resources/ai';
 
 const pkg = require('../../package.json') as { version: string };
 

backend/src/v2/resources/ai.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { defineRoute } from '../route';
+import { single } from '../paging';
+import { aiStatus, getAiSettings, saveAiSettings, usageThisMonth, HELPERS, clearAiStatusCache } from '../../ai';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const { campusIndependent } = require('../../utils/campusScope') as { campusIndependent(reason: string): any };
+const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+
+const helperFlags = z.object(Object.fromEntries(HELPERS.map(h => [h, z.boolean()])) as Record<(typeof HELPERS)[number], z.ZodBoolean>);
+
+const status = z.object({
+  enabled: z.boolean().describe('false: hide the AI buttons (the licence has no AI, or the site isn\'t connected to the Hub)'),
+  capReached: z.boolean().describe('true: show the buttons disabled until `renewsOn`'),
+  available: z.boolean().describe('false: the Hub couldn\'t be reached just now'),
+  capCents: z.number().describe('The monthly allowance, in cents'),
+  usedCents: z.number().describe('Used this month, in cents (fractions of a cent)'),
+  usedPercent: z.number(),
+  renewsOn: z.string().nullable().describe('YYYY-MM-DD'),
+  helpers: helperFlags.describe('Each helper switched on or off in Site settings → AI'),
+});
+
+const settings = z.object({
+  helpers: helperFlags,
+  dailyLimitPerPerson: z.number().int().min(0).max(1000).describe('0 = no limit'),
+});
+
+const use = z.object({ uses: z.number().int(), chargedCents: z.number() });
+
+export const getAiStatus = defineRoute({
+  method: 'get',
+  path: '/ai/status',
+  tag: 'AI',
+  summary: 'Whether to show the AI buttons',
+  description: 'Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it.',
+  access: 'supervisor',
+  campusScope: 'campusIndependent (the site\'s AI allowance)',
+  middleware: [campusIndependent('the site\'s AI allowance')],
+  response: single(status),
+  async handler() {
+    return { data: await aiStatus() };
+  },
+});
+
+export const getAiUsage = defineRoute({
+  method: 'get',
+  path: '/ai/usage',
+  tag: 'AI',
+  summary: 'AI use this month',
+  description: 'For Site settings → AI: the allowance, this site\'s switches, and this month\'s use per person, per helper and per day.',
+  access: 'admin',
+  response: single(z.object({
+    status,
+    settings,
+    people: z.array(use.extend({ userId: z.string().nullable(), name: z.string() })),
+    helpers: z.array(use.extend({ helper: z.string() })),
+    days: z.array(use.extend({ day: z.string() })),
+  })),
+  async handler() {
+    clearAiStatusCache();
+    const [s, settingsNow, usage] = await Promise.all([aiStatus({ fresh: true }), getAiSettings(), usageThisMonth()]);
+    return { data: { status: s, settings: settingsNow, ...usage } };
+  },
+});
+
+export const updateAiSettings = defineRoute({
+  method: 'put',
+  path: '/ai/settings',
+  tag: 'AI',
+  summary: 'Switch helpers on or off, and set a daily limit',
+  access: 'admin',
+  body: z.object({ helpers: helperFlags.partial().optional(), dailyLimitPerPerson: z.number().int().min(0).max(1000).optional() }),
+  response: single(settings),
+  async handler({ body, user, req }) {
+    return { data: await saveAiSettings(body, user!, getClientIp(req)) };
+  },
+});

backend/src/v2/resources/peopleMessaging.ts

@@ -44,7 +44,7 @@ const qs = (req: Request) => (req.originalUrl.includes('?') ? req.originalUrl.sl
 // ─── Accounts ────────────────────────────────────────────────────────────────
 
 v1Route({ method: 'post', path: '/auth/login/code/resend', tag: 'Accounts', summary: 'Send the sign-in code again', access: 'public', middleware: [loginLimiter], body: loose, v1: users.resendLoginTwoFactor });
-v1Route({ method: 'post', path: '/auth/password/forgot', tag: 'Accounts', summary: 'Email me a link to reset my password', description: 'NOT_FOUND when no account has that email (as v1 does).', access: 'public', body: z.looseObject({ email: z.string().max(200) }), v1: users.requestPasswordReset });
+v1Route({ method: 'post', path: '/auth/password/forgot', tag: 'Accounts', summary: 'Email me a link to reset my password', description: 'Always the same answer, so it doesn\'t say whether an account has that email. Rate-limited like sign-in.', access: 'public', middleware: [loginLimiter], body: z.looseObject({ email: z.string().max(200) }), v1: users.requestPasswordReset });
 v1Route({ method: 'post', path: '/auth/password/reset', tag: 'Accounts', summary: 'Set a new password with a reset link', access: 'public', body: loose, v1: users.resetPassword });
 v1Route({ method: 'post', path: '/auth/activate', tag: 'Accounts', summary: 'Activate an account with its link', access: 'public', body: loose, v1: users.activateAccount });
 v1Route({ method: 'post', path: '/me/sessions/revoke', tag: 'Me', summary: 'Sign out everywhere else', access: 'user', body: loose, v1: users.revokeMySession });

backend/tests/accountEnumeration.test.ts

@@ -0,0 +1,83 @@
+/**
+ * 1.51.17 security fix: nothing public says whether an account exists. Forgot-password answers
+ * the same for every email (before doing any per-account work), and sign-in with an unknown email
+ * answers exactly like a wrong password.
+ */
+const mockDb = {
+  user: { findUnique: jest.fn(), findFirst: jest.fn(), update: jest.fn() },
+  passwordReset: { updateMany: jest.fn(), create: jest.fn() },
+};
+jest.mock('../src/config/db', () => mockDb);
+const mockCompare = jest.fn(async () => false);
+jest.mock('../src/config/auth', () => ({ comparePassword: (...a: unknown[]) => (mockCompare as jest.Mock)(...a), hashPassword: async () => 'stand-in-hash', generateToken: () => 't' }));
+const mockSendMail = jest.fn(async () => undefined);
+jest.mock('../src/utils/email', () => ({ sendMail: (...a: unknown[]) => (mockSendMail as jest.Mock)(...a), buildPasswordResetEmail: () => ({ html: '', text: 'reset' }) }));
+jest.mock('../src/utils/notify', () => ({ waText: async () => undefined }));
+jest.mock('../src/utils/securityEvents', () => ({ logSecurityEvent: async () => undefined, getRecentSecurityEvents: async () => [] }));
+jest.mock('../src/utils/whatsapp', () => ({ normalizeZAPhone: () => null, isValidZAPhone: () => false }));
+
+import { logIn } from '../src/services/auth';
+import { ServiceError } from '../src/services/errors';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { requestPasswordReset } = require('../src/controllers/userController');
+
+type Answer = { status: number; body: unknown };
+function call(handler: (req: unknown, res: unknown) => Promise<void>, body: object): Promise<Answer> {
+  return new Promise(resolve => {
+    let status = 200;
+    const res = {
+      statusCode: 200,
+      status(n: number) { status = n; this.statusCode = n; return this; },
+      json(b: unknown) { resolve({ status, body: b }); return this; },
+    };
+    handler({ body, headers: {}, ip: '127.0.0.1' }, res);
+  });
+}
+
+const realUser = { id: 'u1', name: 'Thandi', email: 'thandi@example.org', isActive: true, password: 'real-hash', failedAttempts: 0, lockUntil: null, role: 'user' };
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('forgot password', () => {
+  test('answers the same, with the same status, for an email with and without an account', async () => {
+    mockDb.user.findUnique.mockResolvedValueOnce(null);
+    const unknown = await call(requestPasswordReset, { email: 'nobody@example.org' });
+    mockDb.user.findUnique.mockResolvedValueOnce(realUser);
+    const known = await call(requestPasswordReset, { email: realUser.email });
+    expect(unknown).toEqual(known);
+    expect(known.status).toBe(200);
+  });
+
+  test('only a real account gets a link, made after the answer is sent', async () => {
+    mockDb.user.findUnique.mockResolvedValueOnce(null);
+    await call(requestPasswordReset, { email: 'nobody@example.org' });
+    await new Promise(r => setImmediate(r));
+    expect(mockDb.passwordReset.create).not.toHaveBeenCalled();
+    expect(mockSendMail).not.toHaveBeenCalled();
+
+    mockDb.user.findUnique.mockResolvedValueOnce(realUser);
+    const answered = call(requestPasswordReset, { email: realUser.email });
+    await answered;
+    await new Promise(r => setImmediate(r));
+    expect(mockDb.passwordReset.create).toHaveBeenCalledTimes(1);
+    expect(mockSendMail).toHaveBeenCalledWith(expect.objectContaining({ to: realUser.email }));
+  });
+});
+
+describe('sign-in', () => {
+  const failure = async (p: Promise<unknown>) => { try { await p; } catch (e) { return e as ServiceError; } throw new Error('expected a refusal'); };
+
+  test('an unknown email is refused exactly like a wrong password', async () => {
+    mockDb.user.findFirst.mockResolvedValueOnce(null);
+    const unknown = await failure(logIn({ identifier: 'nobody@example.org', password: 'x' }, { ip: '1', userAgent: 'jest' }));
+    mockDb.user.findFirst.mockResolvedValueOnce(realUser);
+    const wrong = await failure(logIn({ identifier: realUser.email, password: 'x' }, { ip: '1', userAgent: 'jest' }));
+    expect({ message: unknown.message, status: unknown.statusCode, v1: unknown.v1Status }).toEqual({ message: wrong.message, status: wrong.statusCode, v1: wrong.v1Status });
+  });
+
+  test('an unknown email still does a password check, so it takes as long', async () => {
+    mockDb.user.findFirst.mockResolvedValueOnce(null);
+    await failure(logIn({ identifier: 'nobody@example.org', password: 'guess' }, { ip: '1', userAgent: 'jest' }));
+    expect(mockCompare).toHaveBeenCalledWith('guess', 'stand-in-hash');
+  });
+});

backend/tests/ai.test.ts

@@ -0,0 +1,134 @@
+// AI helpers (2.0): what the buttons do, and how a helper call goes through the Hub (§3b).
+
+const mockCalls: Array<Record<string, unknown>> = [];
+const mockSettings = new Map<string, string>();
+const mockDb = {
+  appSetting: {
+    findUnique: jest.fn(async ({ where }: { where: { key: string } }) => (mockSettings.has(where.key) ? { key: where.key, value: mockSettings.get(where.key) } : null)),
+    upsert: jest.fn(async ({ where, update }: { where: { key: string }; update: { value: string } }) => { mockSettings.set(where.key, update.value); }),
+  },
+  aiCall: {
+    count: jest.fn(async () => mockCalls.filter(c => c.outcome === 'ok').length),
+    create: jest.fn(async ({ data }: { data: Record<string, unknown> }) => { mockCalls.push(data); return data; }),
+    deleteMany: jest.fn(async () => ({ count: 0 })),
+  },
+  user: { findMany: jest.fn(async () => [{ email: 'admin@test.local' }]) },
+};
+jest.mock('../src/config/db', () => mockDb);
+
+const mockLicence = { connected: true, readOnly: false, state: 'active', claims: { limits: { aiMonthlyCapCents: 5000 } } as { limits: { aiMonthlyCapCents: number } } | null };
+jest.mock('../src/hub/licence', () => ({ licenceStatus: jest.fn(async () => mockLicence) }));
+
+class MockHubError extends Error {
+  constructor(message: string, public code: string, public statusCode: number, public data: unknown = null) { super(message); }
+}
+const mockPost = jest.fn();
+jest.mock('../src/hub/client', () => ({ PROTOCOL_VERSION: 1, HubError: MockHubError, signedPost: (...a: unknown[]) => mockPost(...a) }));
+const mockMail = jest.fn(async (_m: unknown) => undefined);
+jest.mock('../src/utils/email', () => ({ sendMail: (m: unknown) => mockMail(m), emailWrapper: (s: string) => s, isSmtpConfigured: () => true }));
+jest.mock('../src/utils/adminAudit', () => ({ logAdminAction: jest.fn(async () => undefined) }));
+
+import { aiStatus, runHelper, saveAiSettings, clearAiStatusCache, _internal } from '../src/ai';
+
+const hubStatus = (over = {}) => ({ enabled: true, capReached: false, capCents: 5000, usedCents: 100, usedPercent: 2, renewsOn: '2026-12-01', ...over });
+const req = { system: 'Write a friendly message.', input: 'Bring a sleeping bag.', maxTokens: 500 };
+
+beforeEach(() => {
+  mockCalls.length = 0;
+  mockSettings.clear();
+  mockPost.mockReset();
+  mockMail.mockClear();
+  mockLicence.connected = true;
+  mockLicence.readOnly = false;
+  mockLicence.claims = { limits: { aiMonthlyCapCents: 5000 } };
+  clearAiStatusCache();
+});
+
+describe('status', () => {
+  test('a licence without AI never asks the Hub', async () => {
+    mockLicence.claims = { limits: { aiMonthlyCapCents: 0 } };
+    expect(await aiStatus()).toMatchObject({ enabled: false, capReached: false });
+    mockLicence.connected = false;
+    expect((await aiStatus()).enabled).toBe(false);
+    expect(mockPost).not.toHaveBeenCalled();
+  });
+
+  test('asks the Hub and caches its answer for a minute', async () => {
+    mockPost.mockResolvedValue(hubStatus());
+    expect(await aiStatus()).toMatchObject({ enabled: true, available: true, usedCents: 100, helpers: { draft_event: true } });
+    await aiStatus();
+    expect(mockPost).toHaveBeenCalledTimes(1);
+    expect(mockPost).toHaveBeenCalledWith('/api/installs/ai/status', { protocolVersion: 1 });
+  });
+
+  test('a Hub without AI (404) means off; an unreachable Hub keeps the buttons, marked unavailable', async () => {
+    mockPost.mockRejectedValueOnce(new MockHubError('Not found', 'NOT_FOUND', 404));
+    expect((await aiStatus()).enabled).toBe(false);
+    clearAiStatusCache();
+    mockPost.mockRejectedValueOnce(new MockHubError('down', 'HUB_UNREACHABLE', 502));
+    expect(await aiStatus()).toMatchObject({ enabled: true, available: false });
+  });
+});
+
+describe('running a helper', () => {
+  test('sends the request to the Hub, logs the call, returns the answer', async () => {
+    mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValueOnce({ output: 'Hi all!', chargedCents: 0.31, status: hubStatus({ usedCents: 100.31 }) });
+    const r = await runHelper('draft_message', 'u1', req);
+    expect(r.output).toBe('Hi all!');
+    expect(r.status.usedCents).toBe(100.31);
+    expect(mockPost).toHaveBeenLastCalledWith('/api/installs/ai/complete', { protocolVersion: 1, helper: 'draft_message', ...req }, { timeoutMs: 90000 });
+    expect(mockCalls).toEqual([{ userId: 'u1', helper: 'draft_message', outcome: 'ok', chargedCents: 0.31 }]);
+  });
+
+  test('a helper switched off, or the cap reached, never reaches the Hub', async () => {
+    mockPost.mockResolvedValue(hubStatus({ capReached: true }));
+    await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ code: 'FORBIDDEN', reason: 'AI_CAP_REACHED' });
+    clearAiStatusCache();
+    mockPost.mockResolvedValue(hubStatus());
+    await saveAiSettings({ helpers: { draft_message: false } }, { id: 'a1', role: 'admin' });
+    await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ reason: 'AI_HELPER_OFF' });
+    expect(mockPost).not.toHaveBeenCalledWith('/api/installs/ai/complete', expect.anything(), expect.anything());
+  });
+
+  test('the per-person daily limit', async () => {
+    await saveAiSettings({ dailyLimitPerPerson: 1 }, { id: 'a1', role: 'admin' });
+    mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValueOnce({ output: 'x', chargedCents: 0.1, status: hubStatus() });
+    await runHelper('draft_message', 'u1', req);
+    await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ code: 'RATE_LIMITED', reason: 'AI_DAILY_LIMIT' });
+  });
+
+  test('the Hub refusing at the cap updates the status, so the buttons disable at once', async () => {
+    mockPost.mockResolvedValueOnce(hubStatus())
+      .mockRejectedValueOnce(new MockHubError('used up', 'AI_CAP_REACHED', 402, { code: 'AI_CAP_REACHED', status: hubStatus({ capReached: true }) }));
+    await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ reason: 'AI_CAP_REACHED', message: expect.stringContaining('1 December') });
+    expect((await aiStatus()).capReached).toBe(true);
+    expect(mockCalls[0]).toMatchObject({ outcome: 'cap_reached', chargedCents: 0 });
+  });
+
+  test('admins are emailed once a month at 80%', async () => {
+    const at80 = hubStatus({ usedPercent: 81, usedCents: 4050 });
+    mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValue({ output: 'x', chargedCents: 1, status: at80 });
+    await runHelper('draft_message', 'u1', req);
+    await runHelper('draft_message', 'u1', req);
+    expect(mockMail).toHaveBeenCalledTimes(1);
+    expect(mockMail.mock.calls[0]).toEqual([expect.objectContaining({ to: 'admin@test.local', subject: 'AI allowance 81% used' })]);
+  });
+});
+
+describe('Hub errors', () => {
+  test.each([
+    ['AI_REFUSED', 'UNAVAILABLE', 'refused'],
+    ['AI_INCOMPLETE', 'UNAVAILABLE', 'incomplete'],
+    ['AI_OFF', 'FORBIDDEN', 'unavailable'],
+    ['HUB_UNREACHABLE', 'UNAVAILABLE', 'unavailable'],
+  ])('%s → %s, logged as %s', (hubCode, code, outcome) => {
+    const r = _internal.fromHubError({ code: hubCode, message: 'x' });
+    expect(r.error.code).toBe(code);
+    expect(r.outcome).toBe(outcome);
+  });
+
+  test('today starts at midnight South African time', () => {
+    expect(_internal.startOfToday(new Date('2026-11-10T22:30:00Z')).toISOString()).toBe('2026-11-10T22:00:00.000Z');
+    expect(_internal.startOfToday(new Date('2026-11-10T10:00:00Z')).toISOString()).toBe('2026-11-09T22:00:00.000Z');
+  });
+});

docs/HANDOVER.md

@@ -1,6 +1,6 @@
 # Handover — where things stand and how to carry on
 
-Last updated: 2026-10-30, after **1.51.16** (and Hub 1.5.0). The plan itself is in
+Last updated: 2026-10-30, after **1.51.17** and Hub **1.6.0**; 2.0.0 in progress on `release/2.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,9 +14,7 @@ encrypted settings unreadable or break existing installs.
 
 | Version | What |
 |---------|------|
-| 1.51.3 | **Express 5** (qs query parser and `req.body = {}` kept); scanner and at-the-door on v2 check-in; shared middleware answers v2-shaped on `/api/v2` (`legacyErrorsToV2`, `reason`); v1 `Deprecation` + `successor-version` headers (`src/v2/deprecation.ts`) |
-| 1.51.2 | **v2 accounts and check-in**: signup, login (+ code step), `PATCH /me`; check-in look-up and scan with `outcome`s. `src/services/auth.ts` (from userController) and `src/services/checkin.ts` (from ticketController); login/signup/profile pages on v2 |
-| 1.51.1 | **v2 registrations and payments**: register, get, cancel, checkout; create/cancel moved to `src/services/registrations.ts`, online checkout to `src/services/payments.ts` (v1 uses them too); typed frontend calls (`apiV2`, `npm run api:types`); register page, Pay now and My Events cancel on v2 |
+| 1.51.17 | **Security:** forgot-password and sign-in don't reveal whether an account exists (same answer, status and timing); forgot-password rate-limited |
 | 1.51.16 | **Incoming webhooks and message links on v2** — `src/v2/links.ts` (`/api/v2/webhooks/…`, one-click unsubscribe, 308s for old links); provider URLs and email links point at v2 |
 | 1.51.15 | **Privacy and admin on v2** — `resources/adminPrivacy.ts`; every frontend call on v2; impersonation end/log allowed on v2 while read-only |
 | 1.51.14 | **People and messaging on v2** — `resources/peopleMessaging.ts`; `/event-listing` for the public pages; `defineRoute` refuses duplicates |
@@ -28,6 +26,11 @@ encrypted settings unreadable or break existing installs.
 | 1.51.8 | **Rest of event set-up on v2**: event in full, calendar, alias, ticket options and variants, attachments, sections, costs, image uploads — `src/services/eventDetails.ts`, `src/services/setup.ts`; frontend `fetchEvent()` and `lib/eventSetup.ts`; v2 `file` and `upload` routes |
 | 1.51.7 | **Setting events up on v2** (`/events/manage`, create, `PATCH`, deactivate, copy-from, notify-recipients) via `src/services/events.ts`; `fetchManagedEvents()` for every picker; **pg-boss 11** in schema `pgboss_v11` |
 | 1.51.6 | Command palette lists every report (from `ReportCatalog`) and every dashboard page (e2e drift check); exceljs → ExcelTS 10 (`@cj-tech-master/excelts`, no dependencies; e2e `e2e/excel.spec.ts`); backend `engines.node` >= 22 |
+| 1.51.5 | **Next.js 16** and React 19.3 (Turbopack), **ESLint 10** with Next 16's flat configs (`npm run lint` = `eslint src`); React Compiler-era rules as warnings for now; empty `middleware.ts` removed |
+| 1.51.4 | **Security and dependency updates**: Next.js 15.5.28, @sentry/nextjs, zod, multer, nodemailer and others for published advisories; minimum versions raised in package.json; cron-parser 5 |
+| 1.51.3 | **Express 5** (qs query parser and `req.body = {}` kept); scanner and at-the-door on v2 check-in; shared middleware answers v2-shaped on `/api/v2` (`legacyErrorsToV2`, `reason`); v1 `Deprecation` + `successor-version` headers (`src/v2/deprecation.ts`) |
+| 1.51.2 | **v2 accounts and check-in**: signup, login (+ code step), `PATCH /me`; check-in look-up and scan with `outcome`s. `src/services/auth.ts` (from userController) and `src/services/checkin.ts` (from ticketController); login/signup/profile pages on v2 |
+| 1.51.1 | **v2 registrations and payments**: register, get, cancel, checkout; create/cancel moved to `src/services/registrations.ts`, online checkout to `src/services/payments.ts` (v1 uses them too); typed frontend calls (`apiV2`, `npm run api:types`); register page, Pay now and My Events cancel on v2 |
 | 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` |
@@ -43,9 +46,9 @@ encrypted settings unreadable or break existing installs.
 | 1.47.2 | **Series: year on year** report (§6 part 3): `GET /api/series/:id/compare` (`compareSeries` in `utils/series.js`), report `seriesComparison` in `ReportsV2`, "Compare" on the Event series page |
 | 1.47.1 | **Event series** (§6 part 2): Event series page, Series box on events, public `/series/<slug>`, "Next in this series", follow (News & announcements email from the `series` job when a new event goes live). Migration `20261028140000_event_series` |
 | 1.47.0 | **Copy an event** (§6 part 1): "Copy" opens the event editor filled in from the source (campus, sessions, options, tiers, sections, form, recipients, feedback, certificates); "New start" moves every date; allocation groups and (admins) costs copied by `POST /api/events/:id/copy-from`. No registrations, coupons, attachments, kids check-in or volunteer roles |
-| 1.46.0 | **Volunteer rosters** (§5): serving roles per event or session, anyone signs up (or supervisors assign), day-before reminders, "can't make it" swaps that happen on accept (notify recipients emailed), self check-in with the event's QR code or by staff, kids-room roles count as leaders on duty, free volunteer ticket off by default, roster sheet and hours served. Also fixes the 1.45.0 kids ticket being offered publicly |
-| 1.46.1 | Removed the Gitea CI workflow (no runner): test, lint and deploy by hand |
 | 1.46.2 | Licence page: what's new (from WHATS-NEW.md via the Hub), withdraw update request, "Not now", urgent updates, provider notices banner (Hub 1.4.0: releases from git tags, Notices page) |
+| 1.46.1 | Removed the Gitea CI workflow (no runner): test, lint and deploy by hand |
+| 1.46.0 | **Volunteer rosters** (§5): serving roles per event or session, anyone signs up (or supervisors assign), day-before reminders, "can't make it" swaps that happen on accept (notify recipients emailed), self check-in with the event's QR code or by staff, kids-room roles count as leaders on duty, free volunteer ticket off by default, roster sheet and hours served. Also fixes the 1.45.0 kids ticket being offered publicly |
 | 1.45.1 | Privacy notice (built-in text) and terms of use brought up to date with kids check-in, sessions, certificates, campuses, the Hub heartbeat and where data is stored. Installs with a published notice must publish a new version themselves |
 | 1.45.0 | **Kids check-in** (§4), fully digital: families/children/authorised adults kept between events (My account → Kids), staff desk with pickup codes and a "write on the sticker" panel, rooms with age ranges and ratios, room screen (on duty, call parent, alerts), check-out by code (wrong code alerts, override with reason), offline desk with reserved codes, attendance through a free kids ticket; 6-month retention rule for children |
 | 1.44.0 | **Campus-scoped staff** (§12 part 2): Admin → Users "Limit to campuses"; `utils/campusScope.js` on every staff/supervisor route (and owner-or-staff routes), lists filtered, scanner names the other campus, church-wide events view/scan/door-only for scoped staff; route test `tests/campusScopeRoutes.test.js` |
@@ -59,10 +62,6 @@ encrypted settings unreadable or break existing installs.
 | 1.40.0 | POPIA toolkit part 3 — readiness checklist with score, retention policies + nightly `retention` job (inactive accounts anonymised after 5 years with a 30-day warning, on by default), breach register with notification drafts, children's/medical flag in the access log, `{retention}` in the notice |
 | 1.39.0 | POPIA toolkit part 2 — Admin → Privacy: privacy notice editor (built-in text as the start, placeholders, drafts, numbered versions, re-acceptance after login), operator register, consent log, access log; Information Officer on the contact page |
 | 1.38.0 | POPIA toolkit part 1 — Privacy page (news opt-in + history, download my data, correction and deletion requests), Event update vs News & announcements on every bulk send, unsubscribe links + one-click headers, WhatsApp STOP, one-time news question, Admin → Data requests, thorough anonymising |
-| 1.32.0 | Early-bird ribbon on event cards |
-| 1.33.0 | Multi-day events phase A — sessions, late joining + late pricing, per-session check-in, attendance register, session reminders, certificates (4 templates, verify page) |
-| 1.34.0 | Background jobs on pg-boss (admin Background jobs page), Playwright e2e tests, Gitea CI workflow, `scripts/deploy.sh` |
-| 1.35.0 | Multi-day events phase B — "pick sessions" (per-session tickets and prices, session capacity) |
 | 1.37.4 | Deploy script: no tag = latest main; per-install `ecosystem.config.js` out of git (`ecosystem.config.example.js`) |
 | 1.37.3 | Fix: the production build failed on unescaped quotes in a help text |
 | 1.37.2 | Payment status checks (PayFast transaction history; job every 15 min; Payments → Reconcile → Waiting for payment), PayFast Test connection |
@@ -70,24 +69,48 @@ encrypted settings unreadable or break existing installs.
 | 1.37.0 | PayFast (signed form, ITN checks), `ProviderCheckout` with amount checks, the "Pay online" page (`/pay/<id>`) where payers choose a provider |
 | 1.36.0 | Payment provider interface (`backend/src/payments`) with Yoco behind it, `ProviderTransaction`, `Payment.provider`, Site settings → Payments (on/off and order per provider), R15 minimum |
 | 1.35.1 | Waitlist per session, session picker at the door, "All sessions" tickets let people tick sessions at one price; fixes (per-session stock limits, offline service worker serving stale scripts) |
+| 1.35.0 | Multi-day events phase B — "pick sessions" (per-session tickets and prices, session capacity) |
+| 1.34.0 | Background jobs on pg-boss (admin Background jobs page), Playwright e2e tests, Gitea CI workflow (removed in 1.46.1), `scripts/deploy.sh` |
+| 1.33.0 | Multi-day events phase A — sessions, late joining + late pricing, per-session check-in, attendance register, session reminders, certificates (4 templates, verify page) |
+| 1.32.0 | Early-bird ribbon on event cards |
 
 ## Next up
 
 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. **2.0.0** — AI helpers, and v1 removed. Every endpoint is on v2 since 1.51.16. Keep
-   answering the v1 webhook paths and the old links in sent messages (`src/v2/links.ts`) after
-   v1 goes: providers and old emails still use them.
-2. **Servers run Node 24** (Joshua, 2026-10-29), so the backend may need Node 22+. Still to do:
-   move from ExcelTS — deprecated in favour of `documonster` by the same author (pre-1.0 in Oct
-   2026) — once documonster is stable. After 1.51.7 has run everywhere, the old `pgboss` schema
-   can be dropped (`DROP SCHEMA pgboss CASCADE;`).
-   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
-   charges the real cost plus a markup % (a default and a per-licence override) and counts the cap
-   in charged rand. AI endpoints are `/api/v2` only.
+1. **2.0.0 — in progress on `release/2.0`** (WIP commit per part; tag 2.0.0 only when all of it
+   is in). The parts and their state are in the roadmap's Status table:
+   - ✅ **Hub 1.6.0** — the AI proxy (tagged, pushed). Real Claude calls tested 2026-10-30 through
+     a local Hub with Joshua's key: fine, and a fraction of a cent each.
+   - ✅ **AI plumbing** on Cross Events (`backend/src/ai/`, `/api/v2/ai/*`, Site settings → AI,
+     `<AiButton>`, `useAiStatus()`; roadmap §15 "Progress").
+   - **Next: the five helpers** (`backend/src/ai/helpers.ts`, their routes and buttons, an eval set,
+     privacy notice text).
+   - Then **v1 removed** — keep answering the v1 webhook paths and the old links in sent messages
+     (`src/v2/links.ts`): providers and old emails still use them. Then the **migration guide**.
+   - **Marketing site** (roadmap §17): a simple static HTML site — Cross Code as the main site,
+     with a Cross Events page; room for a church app and a full church website later. Repo,
+     domain and hosting to decide first.
+   - Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a
+     test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`.
+2. **AI rules** (decided 2026-10-29, roadmap §15): 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 charges the
+   real cost plus a markup % (a default and a per-licence override) and counts the cap in charged
+   rand. AI endpoints are `/api/v2` only. Check Claude Haiku 5.5's current prices before setting
+   the markup and caps.
+3. **Clean-ups before or with 2.0:**
+   - Turn the React Compiler lint rules back to errors (see [Next.js 16](#nextjs-16-1515)) — every
+     screen is on v2 now, but they're still `warn` in `frontend/eslint.config.mjs`.
+   - `node-fetch` is still listed in `backend/package.json` though nothing in `src/` uses it —
+     remove it.
+   - Password hashing upgrade with rehash-on-login (roadmap §14) isn't done: still `bcryptjs`.
+     Decide whether it's in 2.0.
+4. **Later:** move from ExcelTS — deprecated in favour of `documonster` by the same author
+   (pre-1.0 in Oct 2026) — once documonster is stable. After 1.51.7 has run everywhere, the old
+   `pgboss` schema can be dropped (`DROP SCHEMA pgboss CASCADE;`).
+
+Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026-10-28).
 
 ## Working on this repo
 
@@ -175,8 +198,8 @@ a test server (both done 2026-10-28).
   up in its transaction history (`findPayments`); Yoco's Checkout API documents no lookup, so
   Yoco checkouts are "can't check". Tests: `backend/tests/paymentStatus.test.js`.
 - **Adding a provider:** write `providers/<id>.js` with the same interface, add it to
-  `PROVIDERS` in `index.js`, mount `handleProviderWebhook('<id>')` at `/api/v2/webhooks/<id>` (in `src/v2/links.ts`; add the v1 path in `routes/webhookRoutes.js` only for providers already registered there)
-  (`routes/webhookRoutes.js`), and give it a settings card in
+  `PROVIDERS` in `index.js`, mount `handleProviderWebhook('<id>')` at `/api/v2/webhooks/<id>` (in `src/v2/links.ts`; add the v1 path in `routes/webhookRoutes.js` only for providers already registered there),
+  and give it a settings card in
   `frontend/src/components/admin/PaymentsTab.tsx`. New providers start switched off.
 - `Payment.method` stays the wallet type (card, apple_pay…) because cashups bucket on it;
   the provider is `Payment.provider`.
@@ -193,7 +216,8 @@ a test server (both done 2026-10-28).
 - Bulk sends: `broadcastController`, `whatsappBroadcastController`, and `emailEventAttendees` /
   `whatsappEventAttendees` in `eventController` take `kind`; scheduled payloads carry it.
 - WhatsApp STOP: `handleIncomingMessage` in `whatsappController.js` (WAWP `message` event on
-  `/api/v2/webhooks/whatsapp?secret=…` — older set-ups use `/api/whatsapp/webhook`, which still works; secret in AppSetting `WAWP_WEBHOOK_SECRET`).
+  `/api/v2/webhooks/whatsapp?secret=…` — older set-ups use `/api/whatsapp/webhook` or `/api/webhooks/whatsapp`, which run the same handler
+  since 1.51.16; secret in AppSetting `WAWP_WEBHOOK_SECRET`).
 - Frontend: `app/dashboard/user/privacy`, `app/unsubscribe`, `app/dashboard/admin/data-requests`,
   `components/shared/NewsPrompt.tsx` (dashboard layout), `MessageKindPicker.tsx`.
 - **Anything new that stores personal data** must be added to `anonymiseUser` and
@@ -466,7 +490,8 @@ a test server (both done 2026-10-28).
 - A list that grows for ever must page on the server (`page`/`limit`, `total`, `pages`) or load
   older items with a `before` cursor, and offer a search. `components/shared/Pager.tsx` renders
   "21–40 of 312 · Prev · Next". Already paged: users, registrations (Manage registrations), events,
-  payments, audit log, consent/access logs, data requests, My payments.
+  payments, audit log, consent/access logs, data requests, My payments. (Paths below are the v1
+  names; each has a v2 successor in `SUCCESSORS`, `src/v2/deprecation.ts`.)
 - **Audit-log actions:** a new `AdminAuditAction` needs a label in `ACTION_LABELS`
   (`app/dashboard/admin/audit-log/page.tsx`) — the filter is built from that list.
 - **Still loading everything (fine for now, watch as installs grow):** user pickers that call
@@ -547,8 +572,9 @@ a test server (both done 2026-10-28).
 - Turbopack for dev and build (the default). Lint with `npm run lint` / `npx eslint src` (`next lint`
   is gone). There's no middleware/proxy file — add `src/proxy.ts` (Next 16's name) only if needed.
 - **React Compiler lint rules are warnings, not errors** (`eslint.config.mjs`): 181 existing places,
-  mostly `useEffect(() => { load(); }, [...])`. Fix them in a screen when it's moved onto v2
-  (1.51.6 – 1.51.11), then turn the rules back to errors. Don't add new ones.
+  mostly `useEffect(() => { load(); }, [...])`. The plan was to fix them as each screen moved onto
+  v2; every screen is on v2 now (1.51.15) but the rules are still `warn` — fix what's left and turn
+  them back to errors before or with 2.0. Don't add new ones.
 - `eslint-config-next` 16's bundled plugins (react, import, jsx-a11y) don't list ESLint 10 as a peer
   yet; they work, and npm notes the override. Revisit when they publish ESLint 10 support.
 
@@ -593,13 +619,14 @@ a test server (both done 2026-10-28).
 ## Event picker and webhook guide (1.50.2)
 
 - **Choosing an event:** use `EventPicker` (`components/shared/EventPicker.tsx`), not a `<select>`.
-  Give it the whole list (`/api/events/all?includePast=true`); it opens on upcoming events, keeps
+  Give it the whole list (`fetchManagedEvents(token, { past: true })`, v2 `GET /events/manage`
+  since 1.51.7); it opens on upcoming events, keeps
   past ones behind "Show past events", and searches all of them. `emptyLabel` adds a clearable
   choice ("All events"), `graceHours` keeps just-ended events current (the scanner uses 12),
   `describe` adds detail per row, and `defaultEventId(events)` picks the next upcoming one. In e2e,
   `pickEvent(page, title)` from `e2e/fixtures.ts`.
-- `/api/events/all` still returns full events (options, form, sessions) — fine for a few hundred;
-  a slim `?fields=` mode would help if a church gets into the thousands.
+- The managed events list still returns full events (options, form, sessions) — fine for a few
+  hundred; a slim `?fields=` mode would help if a church gets into the thousands.
 - **Webhook examples:** a new webhook event type needs an entry in `EXAMPLES` in
   `utils/webhooks.js`; `tests/webhooks.test.js` fails if an example and `buildPayload` differ in
   shape.
@@ -610,7 +637,6 @@ a test server (both done 2026-10-28).
   into WAWP (events `message` + `session.status`), and only for senders WhatsApp identifies by
   phone number — a sender known only by a "LID" is logged and ignored (they can still use the
   link in the message).
-- `/api/webhooks/whatsapp` runs the real WAWP handler since 1.51.16 (it was an empty stub).
 - There's no log of individual messages sent, so "Download my data" can't include "messages
   sent to you" yet.
 

docs/ROADMAP-v2.md

@@ -11,41 +11,46 @@ sold — trustworthy (POPIA), flexible (multi-day events, several payment
 providers), maintainable (tests, CI, typed backend, versioned API), and with
 **AI helpers** as the headline feature (§15).
 
-**Status (2026-10-27):** all features in this document are approved. Shipped
-so far: 1.32.0 early-bird ribbon on event cards; 1.33.0 multi-day events
-phase A (sessions, late joining, per-session check-in, attendance register,
-reminders, certificates); 1.34.0 job queue (pg-boss), Playwright E2E tests, Gitea CI
-workflow (waiting for a runner) and deploy script; 1.35.0 multi-day events phase B
-(pick sessions, per-session capacity), with 1.35.1 adding the per-session waitlist, the session
-picker at the door and session choice on "All sessions" tickets; 1.36.0 payment provider interface
-(Yoco moved behind it, Site settings → Payments); 1.37.0 PayFast and the "Pay online" page;
-1.37.1 "Pay online" hidden when it can't be used; 1.37.2 payment status checks for missing
-notifications. SnapScan and Zapper are dropped — Yoco and PayFast are enough (2026-10-23);
-1.38.0 POPIA toolkit part 1 (privacy page, unsubscribe, WhatsApp STOP, data requests); 1.39.0 part 2 (privacy notice editor and versions, operator register, consent and access logs); 1.40.0 part 3 (retention policies and job, breach register, children’s-data flags, readiness page).
-1.41.0 the Hub connection (licence, heartbeat, read-only mode, `/health`, install script) with Hub 1.0.0 (`joshua/events-hub`);
-1.41.1–1.41.2 licence and job-time fixes; 1.41.3 renamed **Hope Events → Cross Events** (Hub 1.0.1:
-Cross Events Hub); 1.42.0 **Request update** button instead of the deploy command, with Hub 1.1.0
-(update requests); 1.42.1 the production Hub key built in. Later versions moved up by one
-(2026-10-27). Multi-campus is split in two — 1.43.0 campuses, 1.44.0 campus-scoped staff — so
-everything after moves up by one more (2026-10-27). 1.43.0 **campuses** shipped (settings, events
-per campus, public filter and campus pages, home campus, filters, campus broadcasts and summaries);
-1.44.0 **campus-scoped staff** shipped (Admin → Users "Limit to campuses", every staff route checked).
-Wallet passes are removed from scope (2026-10-28), so everything after volunteer rosters moves
-up by one. 1.45.0 **kids check-in** shipped (fully digital: pickup codes, sticker panel, rooms with
-ratios, offline desk). 1.46.0 **volunteer rosters** shipped (roles per event or session, sign-ups and
-assigning, swaps on accept, QR self check-in, kids-room roles on duty, optional volunteer ticket).
-Event series and cloning ships as 1.47.0–1.47.3 (2026-10-28); 1.47.0 **copy an event** and 1.47.1 **event series** (series page, Next in this series, follow) 1.47.2 **year-on-year
-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. 1.51.0 **TypeScript backend and `/api/v2`
-foundations**, 1.51.1 **v2 registrations and payments**, 1.51.2 **v2 accounts and check-in** and 1.51.3 **Express 5,
-scanner on v2, v1 deprecation headers** shipped. 1.51.4 **security and dependency updates**, 1.51.5 **Next.js 16** and 1.51.6 **the complete command palette and
-ExcelTS** , 1.51.7 **setting events up on v2, pg-boss 11** and 1.51.8 **the rest of event set-up on v2** and 1.51.9
-**series, passes, deals and campuses on v2** 1.51.10 **managing registrations on v2**, 1.51.11 **money on v2** and 1.51.12 **tickets and
-attendance on v2** 1.51.13 **kids and volunteers on v2**, 1.51.14 **people and messaging on v2** and 1.51.15
-**privacy and admin on v2** and 1.51.16 **incoming webhooks and links on v2** shipped — every
-endpoint is on v2. **Next: 2.0.0.**
+**Status (2026-10-30):** all features in this document are approved, and everything before 2.0.0
+has shipped (1.32.0 – 1.51.17). **2.0.0 is in progress** on the `release/2.0` branch, tagged only
+when all of it is in (decided 2026-10-30):
+
+| # | Part | Where | State |
+|---|------|-------|-------|
+| 1 | AI proxy: key, metering in rand, caps, markup, usage views | Hub 1.6.0 (`events-hub`) | ✅ tagged; real Claude calls tested 2026-10-30 |
+| 2 | AI plumbing: `/api/v2/ai/status`, usage, Site settings → AI, `<AiButton>`, `useAiStatus()`, `AiCall` log, Anthropic operator entry | `release/2.0` | ✅ committed (WIP) |
+| 3 | The five helpers (§15) with their buttons, an eval set, privacy notice text | `release/2.0` | next |
+| 4 | v1 removed (webhook paths and old message links keep working) | `release/2.0` | to do |
+| 5 | Migration guide, docs | `release/2.0` | to do |
+| 6 | Marketing site: Cross Code with a Cross Events page (§17) | its own repo | to do |
+
+The full version list is in [HANDOVER.md](./HANDOVER.md) and the [build order](#suggested-build-order) below.
+
+- **Multi-day events** (§1): 1.33.0 phase A (sessions, late joining, per-session check-in,
+  attendance register, reminders, certificates); 1.35.0 phase B (pick sessions, per-session
+  capacity); 1.35.1 per-session waitlist, session picker at the door.
+- **Platform:** 1.34.0 job queue (pg-boss), Playwright E2E tests and deploy script (the Gitea CI
+  workflow was removed in 1.46.1 — no runner).
+- **Payments** (§2): 1.36.0 provider interface (Yoco behind it); 1.37.0 – 1.37.2 PayFast, "Pay
+  online", payment status checks. SnapScan and Zapper dropped (2026-10-23).
+- **POPIA toolkit** (§3): 1.38.0 – 1.40.0.
+- **Hub** (§13): 1.41.0 connection (licence, heartbeat, read-only mode, `/health`, install
+  script) with Hub 1.0.0; 1.41.3 renamed **Hope Events → Cross Events**; 1.42.0 **Request
+  update** with Hub 1.1.0; 1.42.1 production Hub key built in.
+- **Multi-campus** (§12): 1.43.0 campuses; 1.44.0 campus-scoped staff.
+- **Kids check-in** (§4) 1.45.0; **volunteer rosters** (§5) 1.46.0.
+- **Event series and cloning** (§6): 1.47.0 copy an event, 1.47.1 series, 1.47.2 year-on-year
+  report, 1.47.3 season passes.
+- **Outbound webhooks** (§8) 1.48.0.
+- **Dashboard, palette, bulk actions, saved filters** (§9): 1.49.0 – 1.49.2.
+- **Accessibility** (§11) 1.50.0; 1.50.1 long lists; 1.50.2 event picker and webhook guide.
+- **TypeScript backend and `/api/v2`** (§14): 1.51.0 – 1.51.3 foundations, registrations and
+  payments, accounts and check-in, Express 5; 1.51.4 security and dependency updates; 1.51.5
+  Next.js 16; 1.51.6 command palette and ExcelTS; 1.51.7 – 1.51.16 every remaining area on v2 —
+  **every endpoint is on v2**.
+- 1.51.17 security fix: forgot password and sign-in don't reveal whether an account exists.
+
+Removed from scope (2026-10-28): Wallet passes (§7) and languages (§10).
 
 **Repositories:**
 
@@ -74,8 +79,9 @@ endpoint is on v2. **Next: 2.0.0.**
 14. [Foundations (platform work)](#14-foundations-platform-work)
 15. [AI helpers (2.0 headline)](#15-ai-helpers-20-headline)
 16. [AI: later stages](#16-ai-later-stages)
-17. [Suggested build order](#suggested-build-order)
-18. [Decisions](#decisions-2026-10-22)
+17. [Marketing site (Cross Code)](#17-marketing-site-cross-code)
+18. [Suggested build order](#suggested-build-order)
+19. [Decisions](#decisions-2026-10-22)
 
 ---
 
@@ -833,13 +839,13 @@ keep adding to.
 
 | Item | What |
 |------|------|
-| CI (Gitea Actions) | Lint, typecheck, Jest, build on every push; deploy on tag |
-| Playwright E2E | Register → pay (sandbox) → ticket → scan → cashup; multi-day check-in; kiosk |
-| Job queue | Move `setInterval` jobs out of `index.js` into `pg-boss` (uses Postgres): retries, no double runs, job history in admin |
-| Split big controllers | `registrationController` (2.3k lines), `eventController`, `paymentController` → services by domain. Done **as each feature touches them**, not as a big-bang rewrite |
-| TypeScript backend | Incremental (`allowJs`), new code in TS first; share zod schemas/types with the frontend |
-| API v2 | `/api/v2` with consistent errors, pagination and an OpenAPI spec (replaces the hand-written API docs). `/api` (v1) kept during the transition |
-| Dependencies | Express 5, native `fetch` instead of `node-fetch`, password hashing upgrade with rehash-on-login |
+| ~~CI (Gitea Actions)~~ | Added in 1.34.0, **removed in 1.46.1** (no machine to run a runner): lint, tests and deploy are done by hand |
+| Playwright E2E ✅ | Register → pay (sandbox) → ticket → scan → cashup; multi-day check-in; kiosk (1.34.0) |
+| Job queue ✅ | Move `setInterval` jobs out of `index.js` into `pg-boss` (uses Postgres): retries, no double runs, job history in admin (1.34.0; pg-boss 11 in 1.51.7) |
+| Split big controllers | `registrationController` (2.3k lines), `eventController`, `paymentController` → services by domain. Done **as each feature touches them**, not as a big-bang rewrite. Partly done (1.51.1 – 1.51.10); the handlers behind `v1Route` are a 2.x clean-up |
+| TypeScript backend ✅ | Incremental (`allowJs`), new code in TS first; share zod schemas/types with the frontend (1.51.0) |
+| API v2 ✅ | `/api/v2` with consistent errors, pagination and an OpenAPI spec (replaces the hand-written API docs). `/api` (v1) kept during the transition; every endpoint on v2 since 1.51.16 |
+| Dependencies | Express 5 ✅ (1.51.3); native `fetch` ✅ (nothing uses `node-fetch` any more — it's still in `backend/package.json`, to remove); password hashing upgrade with rehash-on-login — **not done** (still `bcryptjs`), decide whether it's in 2.0 |
 
 ---
 
@@ -868,7 +874,8 @@ never saves, sends or publishes by itself.
 
 - **One provider: Claude (Anthropic), model Claude Haiku 5.5** — the cheapest
   current model ($0.10 per million input tokens, $0.50 per million output, for
-  prompts under 100K tokens; prices as of 2026-10). Good enough for drafting and
+  prompts under 100K tokens; prices as of 2026-10 — **check them against Anthropic's pricing
+  page before setting the markup and caps**). Good enough for drafting and
   summarising; a helper can move to a bigger model later if quality needs it.
 - **Rough cost:** a helper call is ~2,000–10,000 tokens in and ~500 out, so well under
   US$0.002 per click — about R1.50–R3 per thousand clicks. Fixed instructions are
@@ -945,6 +952,23 @@ an install (one leaked install would leak it for everyone), so:
   looks like) to check quality when changing the prompt or model.
 - Help content, audit log entries (AI settings changed), CHANGELOG, FEATURES.md, SETTINGS.md.
 
+### Progress (2026-10-30)
+
+- **Done — Hub 1.6.0:** `POST /api/installs/ai/status` and `/api/installs/ai/complete` (protocol §3b);
+  the worst case of each call held against the cap in a locked transaction; Settings → AI (key,
+  model, prices, exchange rate, default markup, test button, use per site); markup override per
+  licence; AI use (real cost, charged, profit) on the install page. Tested with real calls: a plain
+  message (118 tokens in, 70 out, ~1.3 s) and a JSON-schema event draft (483 in, 95 out, ~3 s), each
+  charged a fraction of a cent (R0.0008 – R0.0017 at R17/$ and 5% markup).
+- **Done — Cross Events, `release/2.0`:** `backend/src/ai/` (status from the licence token, then
+  the Hub, cached a minute; per-helper switches; per-person daily limit; `AiCall` log; 80% email),
+  `/api/v2/ai/status`, `/ai/usage`, `/ai/settings`, the `UNAVAILABLE` (503) error code,
+  `frontend/src/lib/ai.ts` (`runAi`, which posts to `/api/v2/ai/<helper-with-dashes>`),
+  `useAiStatus()`, `<AiButton>` / `<AiNotice>`, Site settings → AI.
+- **Next:** the helpers in `backend/src/ai/helpers.ts` (prompt, schema, `maxTokens`, and what each
+  sends — no personal information), their `/api/v2/ai/<helper>` routes, the buttons on the five
+  screens, the eval set, and the privacy notice text (a `BUILT_IN_UPDATES` entry).
+
 ---
 
 ## 16. AI: later stages
@@ -998,13 +1022,32 @@ income justify the hardware:
 
 ---
 
+## 17. Marketing site (Cross Code)
+
+Part of 2.0 (decided 2026-10-30): a **simple static HTML site** for selling, not part of the app.
+
+- **Cross Code** (Joshua's company) is the main site: who we are, what we make, contact.
+- **Cross Events** has its own page: what it does for a church (registrations and payments,
+  multi-day events, kids check-in, volunteer rosters, series and season passes, campuses, POPIA
+  toolkit, the AI helpers), how it's set up (one site and database per church, updates on request,
+  support through the Hub), and how to get in touch for a licence.
+- **Cross Events is the only product on sale for now.** The site is laid out so more products can
+  be added later — planned: a **church app** and a **full church website** — without a redesign
+  (shown as "coming later" at most, until they exist).
+- Plain HTML and CSS (no build step, no framework), fast on a phone, no tracking cookies.
+- **To decide before building:** the repository (its own, e.g. `joshua/crosscode-site`, not this
+  one), the domain(s) (e.g. crosscode.co.za, with Cross Events at /cross-events or its own domain),
+  hosting, pricing shown or "contact us", and the contact route (email address or a form).
+
+---
+
 ## Suggested build order
 
 | Phase | Version | Features | Why |
 |-------|---------|----------|-----|
 | 0 | 1.32.0 ✅ | **Early-bird ribbon** on event cards (shipped 2026-10-22) | Quick win |
 | 1 | 1.33.0 ✅ | **Multi-day events — phase A** (sessions, whole-course tickets, late joining + late pricing, per-session check-in with whole-day window, attendance register, optional reminders, certificates) | Requested first; touches registration/tickets/scanning, so it shapes later work |
-| 2 | 1.34.0 ✅ | CI + Playwright E2E + job queue | Safety net before the riskiest work (payments). Session reminders move to the queue |
+| 2 | 1.34.0 ✅ | CI (removed in 1.46.1) + Playwright E2E + job queue | Safety net before the riskiest work (payments). Session reminders move to the queue |
 | 3 | 1.35.0 ✅ | Multi-day events — phase B (pick sessions, per-session capacity) | Builds on phase A, now with E2E coverage |
 | 4 | 1.36.0 ✅ – 1.37.2 | Payment provider interface (Yoco moved behind it) → PayFast, then hiding "Pay online" when it can't be used and payment status checks (SnapScan and Zapper dropped) | Payment code gets split out of the big controller as part of this |
 | 5 | 1.38.0 ✅ 1.39.0 ✅ 1.40.0 ✅ | **POPIA toolkit** (1.38.0: user privacy centre, unsubscribe, WhatsApp STOP, data requests inbox; 1.39.0: privacy notice editor + versions, operator register, consent log, access log; 1.40.0: retention jobs, breach register, children’s-data flags, readiness page) | Main selling point; retention jobs use the job queue |
@@ -1014,8 +1057,8 @@ income justify the hardware:
 | 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 ✅, 1.51.1 ✅, 1.51.2 ✅, 1.51.3 ✅ | 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 registrations and payments as TS services, typed frontend calls; 1.51.2 check-in and accounts; 1.51.3 Express 5, the scanner on v2, v1 deprecation headers, v2-shaped shared middleware | The breaking-change groundwork |
-| 11b | 1.51.4 ✅ – 1.51.16 ✅ | **Every endpoint on v2 before 2.0** (decided 2026-10-29): 1.51.4 dependency audit and Node 24 LTS; 1.51.5 Next.js 16 and ESLint 10 (ESLint 9 is out of support); 1.51.6 the complete command palette and ExcelTS instead of exceljs; 1.51.7 setting events up (the staff list, create, change, deactivate, copy-from, notification recipients) and pg-boss 11; 1.51.8 the rest of event set-up (the event in full, ticket options and variants, attachments, sections, costs, uploads, calendar file, alias); 1.51.9 series, season passes, bundles, coupons and campuses; 1.51.10 managing registrations (the staff lists, status, at the door, bulk actions, items, coupons, attendees, attendee forms); 1.51.11 money, staff side (payments, cashup, provider transactions, waitlist, sponsorship, consent, form builder, feedback); 1.51.12 tickets and attendance, staff side (tickets, scan locks, attendance, allocations); 1.51.13 kids check-in and volunteer rosters; 1.51.14 people and messaging (users, WhatsApp, broadcasts, scheduled emails, automations, banner, saved filters, dashboard, stats, analytics, reports); 1.51.15 privacy and admin (privacy, admin, settings, setup, Hub, outbound webhooks, backups); 1.51.16 **incoming webhooks and links in sent messages**: Yoco, PayFast and WAWP webhooks and the links in emails and WhatsApp (unsubscribe, consent, ticket transfer, calendar feeds, waitlist offers) get v2 URLs — new messages and provider registrations use them, and the v1 paths keep answering (links by a 308 redirect to v2, provider webhooks handled by the same code, since providers may not follow a redirect on a POST). Each puts its area's endpoints on v2 (1.51.1 – 1.51.10 by moving the logic into TS services; from 1.51.11 by `v1Route`, which runs the v1 handler behind a v2 route — moving those handlers into TS services is a 2.x clean-up that doesn't change the API), its screens onto `apiV2`, and its v1 routes into `SUCCESSORS` | 2.0 can then remove v1 |
-| 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 removed (all of it is on v2 by then; the old webhook URLs and links already sent in messages keep forwarding to v2), migration guide, marketing site/docs for selling | The release. AI needs the Hub (phase 6) for the key, metering and caps |
+| 11b | 1.51.4 ✅ – 1.51.16 ✅ | **Every endpoint on v2 before 2.0** (decided 2026-10-29): 1.51.4 dependency audit and Node 24 LTS; 1.51.5 Next.js 16 and ESLint 10 (ESLint 9 is out of support); 1.51.6 the complete command palette and ExcelTS instead of exceljs; 1.51.7 setting events up (the staff list, create, change, deactivate, copy-from, notification recipients) and pg-boss 11; 1.51.8 the rest of event set-up (the event in full, ticket options and variants, attachments, sections, costs, uploads, calendar file, alias); 1.51.9 series, season passes, bundles, coupons and campuses; 1.51.10 managing registrations (the staff lists, status, at the door, bulk actions, items, coupons, attendees, attendee forms); 1.51.11 money, staff side (payments, cashup, provider transactions, waitlist, sponsorship, consent, form builder, feedback); 1.51.12 tickets and attendance, staff side (tickets, scan locks, attendance, allocations); 1.51.13 kids check-in and volunteer rosters; 1.51.14 people and messaging (users, WhatsApp, broadcasts, scheduled emails, automations, banner, saved filters, dashboard, stats, analytics, reports); 1.51.15 privacy and admin (privacy, admin, settings, setup, Hub, outbound webhooks, backups); 1.51.16 **incoming webhooks and links in sent messages**: Yoco, PayFast and WAWP webhooks and the links in emails and WhatsApp (unsubscribe, consent, ticket transfer, calendar feeds, waitlist offers) get v2 URLs — new messages and provider registrations use them, and the v1 paths keep answering (links by a 308 redirect to v2, provider webhooks handled by the same code, since providers may not follow a redirect on a POST). Each puts its area's endpoints on v2 (1.51.1 – 1.51.10 by moving the logic into TS services; from 1.51.11 by `v1Route`, which runs the v1 handler behind a v2 route — moving those handlers into TS services is a 2.x clean-up that doesn't change the API), its screens onto `apiV2`, and its v1 routes into `SUCCESSORS`. Then 1.51.17, a security fix (forgot password and sign-in don't reveal accounts) | 2.0 can then remove v1 |
+| 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 removed (all of it is on v2 by then; the old webhook URLs and links already sent in messages keep forwarding to v2), migration guide, docs, and the marketing site (§17: a static Cross Code site with a Cross Events page). Built on `release/2.0` in parts; Hub 1.6.0 (AI proxy) ✅ and the AI plumbing ✅ are in | 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/`),
 audit log entries, Jest tests, a CHANGELOG entry, and updates to FEATURES.md
@@ -1054,6 +1097,8 @@ feature.
 | — | AI cost limits | A **monthly rand cap per install**, set in the Hub per licence to match what the church pays; admins see their usage in Site settings → AI (2026-10-24) |
 | — | v1 in 2.0 | **Every endpoint moves to v2 before 2.0** (1.51.7 – 1.51.16, by area), then 2.0 removes v1. Changed the same day from "retire only what's replaced". Incoming webhooks (Yoco, PayFast, WAWP) and links in emails and WhatsApp (unsubscribe, consent, ticket transfer, calendar feeds) also get v2 URLs (1.51.16); their v1 paths keep working — links redirect (308) to v2, provider webhooks are handled by the same code — because old messages and provider registrations still use them (2026-10-29) |
 | — | AI buttons and markup | AI buttons show only when the licence's monthly cap is **above R0**. When the cap is reached they stay visible but **disabled** until next month or until the cap is raised. Usage is charged at the real cost **plus a markup %** set in the Hub (a default, plus an override per licence). The markup covers small overruns and is the profit. The cap is counted in charged rand, and each call is checked against its worst-case cost before it's sent (2026-10-29) |
+| — | Building 2.0 | On a `release/2.0` branch with a WIP commit per part, tagged 2.0.0 only when everything is in; the Hub's AI proxy ships first as its own release (Hub 1.6.0) (2026-10-30) |
+| — | Marketing site | Part of 2.0: a simple static HTML site — Cross Code as the main site, with a page for Cross Events, the only product on sale for now. Laid out to add a church app and a full church website later. Repo, domain and hosting still to decide (2026-10-30) |
 | — | AI later | Ask AI (read-only, tools only), help/navigation assistant, actions with confirmation, more helpers, and long-term **self-hosted** AI behind the same Hub endpoint — not tied to versions (2026-10-24) |
 | — | POPIA: message kinds | Bulk messages are either **Event updates** (to registrants — still sent after unsubscribing) or **News & announcements** (marketing — opt-in, one-click unsubscribe). Every bulk email links to the preferences (2026-10-23) |
 | — | POPIA: existing users | Kept opted in to news (logged as "existing account"), asked once at their next login to confirm or opt out. New sign-ups choose with an unticked box (2026-10-23) |
@@ -1075,4 +1120,6 @@ feature.
 
 ## Still open
 
-Nothing for now.
+- **Marketing site (§17):** repository, domain(s), hosting, whether prices are shown, and the
+  contact route.
+- **Password hashing upgrade** (§14): in 2.0 or later.

docs/hub-protocol.md

@@ -178,6 +178,65 @@ X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature   (as in §3)
   history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`.
 - **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told.
 
+## 3b. AI (Cross Events 2.0, Hub 1.6.0)
+
+Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the
+key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed
+exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response
+text** — only the install, helper name, tokens, cost and time.
+
+### Status
+
+```
+POST /api/installs/ai/status
+X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature   (as in §3)
+{ "protocolVersion": 1 }
+→ 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4,
+        "usedPercent": 16, "renewsOn": "2026-12-01" }
+```
+
+- **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't
+  active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up.
+- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it
+  renews on 1 December"). Reached means there isn't room left for even a small call.
+- Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a
+  cent). The month is South African time; `renewsOn` is the 1st of the next month.
+
+### A helper call
+
+```
+POST /api/installs/ai/complete
+X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature   (as in §3)
+{
+  "protocolVersion": 1,
+  "helper": "draft_event",          // lower-case name, for usage reports
+  "system": "…",                    // the helper's fixed instructions (cached by Claude)
+  "input": "…",                     // this request's text
+  "schema": { … },                  // optional JSON schema: the reply is JSON in that shape
+  "maxTokens": 2000,                // 1–8000
+  "effort": "low"                   // optional: low (default) | medium | high
+}
+→ 200 { "output": "…" | { … },      // text, or the parsed JSON when a schema was given
+        "usage": { "inputTokens": 1840, "outputTokens": 420 },
+        "chargedCents": 0.31,
+        "status": { …as above… } }
+```
+
+- **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable
+  straight after the call that used up the allowance:
+  - `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude).
+  - `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up).
+  - `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`.
+    `502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used.
+  - `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged.
+  - `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors.
+- **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged =
+  real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst
+  case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per
+  install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount.
+- Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap).
+- A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off".
+
 ## 4. Licence token
 
 `hel1.<payload>.<signature>` — `payload` is base64url JSON, `signature` is the base64url
@@ -195,7 +254,7 @@ Ed25519 signature of the ASCII string `hel1.<payload>`.
   "graceDays": 14,
   "issuedAt": "2026-10-24T08:15:00.000Z",
   "validUntil": "2026-11-23T08:15:00.000Z",          // issuedAt + 30 days
-  "limits": { "aiMonthlyCapCents": 0 }
+  "limits": { "aiMonthlyCapCents": 0 }      // the AI cap (§3b); 0 = AI off
 }
 ```
 
@@ -221,8 +280,3 @@ grace starts). Blocking the Hub can't keep a suspended licence active for more t
   fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they
   don't know.
 - The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`.
-
-## 6. Later (not in v1)
-
-- **AI proxy** (Cross Events 2.0): `POST /api/ai/complete`, signed like the heartbeat; the Hub holds
-  the Claude API key, meters each call in rand and enforces `limits.aiMonthlyCapCents`.

e2e/api-v2.spec.ts

@@ -307,9 +307,16 @@ test.describe("API v2", () => {
 
     const users = (await (await request.get(`${API}/api/v2/users?page=1&limit=2`, { headers: sup })).json()).data;
     expect(users).toMatchObject({ page: 1, limit: 2 });
-    // As v1: an unknown email is NOT_FOUND.
-    const forgot = await request.post(`${API}/api/v2/auth/password/forgot`, { data: { email: "nobody-e2e@example.com" } });
-    expect((await forgot.json()).error.code).toBe("NOT_FOUND");
+    // Forgot-password doesn't say whether an account exists (1.51.17): the same answer either way.
+    const unknown = await request.post(`${API}/api/v2/auth/password/forgot`, { data: { email: "nobody-e2e@example.com" } });
+    const known = await request.post(`${API}/api/v2/auth/password/forgot`, { data: { email: seed().users.user.email } });
+    expect(unknown.status()).toBe(200);
+    expect(await unknown.json()).toEqual(await known.json());
+    // Nor does sign-in: an unknown email is refused like a wrong password.
+    const noAccount = await request.post(`${API}/api/v2/auth/login`, { data: { identifier: "nobody-e2e@example.com", password: "Wrong-password-1" } });
+    const wrongPassword = await request.post(`${API}/api/v2/auth/login`, { data: { identifier: seed().users.user.email, password: "Wrong-password-1" } });
+    expect(noAccount.status()).toBe(wrongPassword.status());
+    expect(await noAccount.json()).toEqual(await wrongPassword.json());
   });
 
   test("privacy and admin: settings, my data, the audit log, webhooks, backups", async ({ request }) => {

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hope-events-frontend",
-      "version": "1.51.16",
+      "version": "1.51.17",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",
         "@hookform/resolvers": "^5.2.1",

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "private": true,
   "scripts": {
     "dev": "next dev",

frontend/src/app/dashboard/admin/settings/page.tsx

@@ -8,7 +8,7 @@ import { ApiError, resolveToApiOrigin } from "@/lib/api";
 import { apiV2Raw, apiV2Data } from "@/lib/apiV2";
 import { useSiteSettings } from "@/contexts/SiteSettingsContext";
 import { useDismissingState } from "@/hooks/useDismissingState";
-import { Building2, Palette, Bell, Mail, Scale, MessageCircle, CreditCard, DatabaseBackup, Timer, KeyRound, MapPinned, type LucideIcon, Webhook } from "lucide-react";
+import { Building2, Palette, Bell, Mail, Scale, MessageCircle, CreditCard, DatabaseBackup, Timer, KeyRound, MapPinned, type LucideIcon, Webhook, Sparkles } from "lucide-react";
 import { ColorPickerField } from "@/components/admin/ColorPickerField";
 import { BrandingPreviewPanel } from "@/components/admin/BrandingPreviewPanel";
 import { BackupsTab } from "@/components/admin/BackupsTab";
@@ -16,6 +16,7 @@ import { JobsTab } from "@/components/admin/JobsTab";
 import { PaymentsTab } from "@/components/admin/PaymentsTab";
 import { LicenceTab } from "@/components/admin/LicenceTab";
 import { WebhooksTab } from "@/components/admin/WebhooksTab";
+import { AiTab } from "@/components/admin/AiTab";
 import { CampusesTab } from "@/components/admin/CampusesTab";
 import { extractDominantColors } from "@/lib/extractColors";
 import { mapsSearchUrl } from "@/lib/maps";
@@ -23,7 +24,7 @@ import { errorMessage } from "@/lib/utils";
 import { BackLink } from "@/components/shared/BackLink";
 import { uploadImage } from "@/lib/eventSetup";
 
-type TabId = "organisation" | "campuses" | "branding" | "notifications" | "email" | "legal" | "whatsapp" | "payments" | "webhooks" | "backups" | "jobs" | "licence";
+type TabId = "organisation" | "campuses" | "branding" | "notifications" | "email" | "legal" | "whatsapp" | "payments" | "webhooks" | "backups" | "jobs" | "licence" | "ai";
 
 const TABS: { id: TabId; label: string; icon: LucideIcon }[] = [
   { id: "organisation",  label: "Organisation",  icon: Building2 },
@@ -38,6 +39,7 @@ const TABS: { id: TabId; label: string; icon: LucideIcon }[] = [
   { id: "backups",       label: "Backups",       icon: DatabaseBackup },
   { id: "jobs",          label: "Background jobs", icon: Timer },
   { id: "licence",       label: "Licence",       icon: KeyRound },
+  { id: "ai",            label: "AI",            icon: Sparkles },
 ];
 
 const inputCls =
@@ -717,6 +719,7 @@ function SiteSettingsPageInner() {
         {activeTab === "webhooks" && <WebhooksTab active={activeTab === "webhooks"} />}
         {activeTab === "jobs" && <JobsTab active={activeTab === "jobs"} />}
         {activeTab === "licence" && <LicenceTab active={activeTab === "licence"} />}
+        {activeTab === "ai" && <AiTab active={activeTab === "ai"} />}
         {activeTab === "campuses" && <CampusesTab active={activeTab === "campuses"} />}
       </div>
 

frontend/src/components/admin/AiTab.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import React, { useEffect, useState } from "react";
+import { Sparkles } from "lucide-react";
+import { useAuth } from "@/hooks/useAuth";
+import { apiV2, type V2Result } from "@/lib/apiV2";
+import { loadAiStatus, renewsText } from "@/lib/ai";
+import { errorMessage } from "@/lib/utils";
+
+type Usage = V2Result<"/ai/usage", "get">["data"];
+type Helper = keyof Usage["settings"]["helpers"];
+
+const HELPERS: { key: Helper; label: string; where: string }[] = [
+  { key: "draft_event", label: "Draft an event", where: "New event: describe it and the form is filled in" },
+  { key: "summarise_report", label: "Summarise this report", where: "Reports: a few plain-language insights" },
+  { key: "draft_message", label: "Draft a message", where: "Emails and WhatsApp messages to attendees, broadcasts" },
+  { key: "summarise_feedback", label: "Summarise feedback", where: "Post-event feedback results" },
+  { key: "improve_text", label: "Improve this text", where: "Event descriptions, the banner, message boxes" },
+];
+
+// Fractions of a cent add up: show R0.0123 below a rand.
+const money = (cents: number) => (cents > 0 && cents < 100 ? `R${(cents / 100).toFixed(4)}` : `R${(cents / 100).toFixed(2)}`);
+
+/** Site settings → AI: the monthly allowance, who used it for what, and a switch per helper. */
+export function AiTab({ active }: { active: boolean }) {
+  const { token } = useAuth();
+  const [usage, setUsage] = useState<Usage | null>(null);
+  const [limit, setLimit] = useState("0");
+  const [msg, setMsg] = useState<{ ok: boolean; text: string } | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    if (!active || !token) return;
+    let alive = true;
+    apiV2("get", "/ai/usage", { authToken: token })
+      .then(({ data }) => { if (alive) { setUsage(data); setLimit(String(data.settings.dailyLimitPerPerson)); } })
+      .catch(e => { if (alive) setMsg({ ok: false, text: errorMessage(e) || "Could not load AI use." }); });
+    return () => { alive = false; };
+  }, [active, token]);
+
+  const save = async (helpers: Partial<Record<Helper, boolean>>, dailyLimitPerPerson?: number) => {
+    if (!token) return;
+    setBusy(true);
+    setMsg(null);
+    try {
+      const { data } = await apiV2("put", "/ai/settings", { authToken: token, body: { helpers, ...(dailyLimitPerPerson != null ? { dailyLimitPerPerson } : {}) } });
+      setUsage(u => (u ? { ...u, settings: data, status: { ...u.status, helpers: data.helpers } } : u));
+      setMsg({ ok: true, text: "Saved." });
+      loadAiStatus(token, { fresh: true }).catch(() => {});
+    } catch (e) { setMsg({ ok: false, text: errorMessage(e) || "Could not save." }); }
+    setBusy(false);
+  };
+
+  if (!usage) return msg ? <p className="text-sm text-red-700">{msg.text}</p> : <p className="text-sm text-gray-500">Loading…</p>;
+  const s = usage.status;
+  const maxDay = Math.max(0.0001, ...usage.days.map(d => d.chargedCents));
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h2 className="flex items-center gap-2 text-lg font-semibold"><Sparkles className="h-5 w-5 text-violet-600" aria-hidden /> AI helpers</h2>
+        <p className="mt-1 text-sm text-gray-600">
+          One-click helpers for supervisors and admins: drafting events and messages, improving text, summarising reports and feedback. A person always checks the suggestion before anything is saved or sent.
+        </p>
+      </div>
+
+      {!s.enabled ? (
+        <div className="rounded-lg border bg-gray-50 p-4 text-sm text-gray-700">
+          AI helpers aren&apos;t part of this site&apos;s licence, so their buttons are hidden. To add them, ask your provider for a monthly AI allowance.
+        </div>
+      ) : (
+        <div className="rounded-lg border p-4">
+          <div className="flex flex-wrap items-baseline justify-between gap-2">
+            <span className="text-sm font-medium">This month</span>
+            <span className="text-sm text-gray-600">{money(s.usedCents)} of {money(s.capCents)} · renews on {renewsText(s.renewsOn)}</span>
+          </div>
+          <div className="mt-2 h-2 w-full overflow-hidden rounded-full bg-gray-100" role="progressbar" aria-label="AI allowance used" aria-valuenow={s.usedPercent} aria-valuemin={0} aria-valuemax={100}>
+            <div className={`h-full ${s.usedPercent >= 80 ? "bg-amber-500" : "bg-violet-500"}`} style={{ width: `${s.usedPercent}%` }} />
+          </div>
+          {s.capReached && <p className="mt-2 text-sm text-amber-800">The allowance is used up: the AI buttons are disabled until {renewsText(s.renewsOn)}, or until your provider raises it.</p>}
+          {!s.available && <p className="mt-2 text-sm text-amber-800">The provider&apos;s Hub can&apos;t be reached right now, so AI is unavailable. Everything else works as usual.</p>}
+          <p className="mt-2 text-xs text-gray-500">Admins get an email when 80% is used.</p>
+        </div>
+      )}
+
+      <div>
+        <h3 className="mb-2 font-medium">Helpers</h3>
+        <ul className="divide-y rounded-lg border">
+          {HELPERS.map(h => (
+            <li key={h.key} className="flex items-center justify-between gap-3 p-3">
+              <div>
+                <label htmlFor={`ai-${h.key}`} className="text-sm font-medium">{h.label}</label>
+                <p className="text-xs text-gray-500">{h.where}</p>
+              </div>
+              <input id={`ai-${h.key}`} type="checkbox" className="h-4 w-4" disabled={busy} checked={usage.settings.helpers[h.key]} onChange={e => save({ [h.key]: e.target.checked })} />
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      <form className="flex flex-wrap items-end gap-3" onSubmit={e => { e.preventDefault(); save({}, Math.max(0, parseInt(limit, 10) || 0)); }}>
+        <div>
+          <label htmlFor="ai-daily-limit" className="block text-sm font-medium">Most uses per person per day</label>
+          <input id="ai-daily-limit" type="number" min={0} max={1000} className="mt-1 w-28 rounded-lg border px-3 py-2 text-sm" value={limit} onChange={e => setLimit(e.target.value)} />
+          <p className="mt-1 text-xs text-gray-500">0 = no limit. Guards against one person using up the month.</p>
+        </div>
+        <button className="rounded-lg bg-brand-600 px-3 py-2 text-sm font-medium text-white hover:bg-brand-700 disabled:opacity-60" disabled={busy}>Save limit</button>
+      </form>
+      {msg && <p className={`text-sm ${msg.ok ? "text-green-700" : "text-red-700"}`} role="status">{msg.text}</p>}
+
+      {s.enabled && (
+        <div className="grid gap-6 md:grid-cols-2">
+          <div>
+            <h3 className="mb-2 font-medium">By person this month</h3>
+            {usage.people.length === 0 ? <p className="text-sm text-gray-500">Nobody has used AI yet this month.</p> : (
+              <table className="w-full text-sm">
+                <thead><tr className="text-left text-xs text-gray-500"><th className="py-1">Person</th><th>Uses</th><th className="text-right">Cost</th></tr></thead>
+                <tbody>{usage.people.map(p => <tr key={p.userId || "removed"} className="border-t"><td className="py-1">{p.name}</td><td>{p.uses}</td><td className="text-right">{money(p.chargedCents)}</td></tr>)}</tbody>
+              </table>
+            )}
+          </div>
+          <div>
+            <h3 className="mb-2 font-medium">By helper this month</h3>
+            {usage.helpers.length === 0 ? <p className="text-sm text-gray-500">—</p> : (
+              <table className="w-full text-sm">
+                <thead><tr className="text-left text-xs text-gray-500"><th className="py-1">Helper</th><th>Uses</th><th className="text-right">Cost</th></tr></thead>
+                <tbody>{usage.helpers.map(h => <tr key={h.helper} className="border-t"><td className="py-1">{HELPERS.find(x => x.key === h.helper)?.label || h.helper}</td><td>{h.uses}</td><td className="text-right">{money(h.chargedCents)}</td></tr>)}</tbody>
+              </table>
+            )}
+          </div>
+          {usage.days.length > 0 && (
+            <div className="md:col-span-2">
+              <h3 className="mb-2 font-medium">Per day</h3>
+              <div className="flex h-20 items-end gap-1" aria-label="AI cost per day this month">
+                {usage.days.map(d => <div key={d.day} title={`${d.day}: ${d.uses} uses, ${money(d.chargedCents)}`} className="flex-1 rounded-t bg-violet-300" style={{ height: `${Math.max(4, (d.chargedCents / maxDay) * 100)}%` }} />)}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      <p className="text-xs text-gray-500">
+        Requests go through your provider&apos;s Hub to Anthropic (Claude) in the United States. Only what a helper needs is sent — never names, contact details, medical or children&apos;s information — and nothing is kept by the provider. Add Anthropic to your operator register (Admin → Privacy) when you start using AI.
+      </p>
+    </div>
+  );
+}

frontend/src/components/shared/AiButton.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import React, { useId } from "react";
+import { Loader2, Sparkles } from "lucide-react";
+import { useAiStatus } from "@/hooks/useAiStatus";
+import { disabledReason, type AiHelper } from "@/lib/ai";
+
+/**
+ * A button for one AI helper. Not shown at all when the site has no AI (or for anyone but
+ * supervisors and admins); shown but disabled, with the reason, when this month's allowance is
+ * used up, the Hub can't be reached, or the helper is switched off in Site settings → AI.
+ */
+export function AiButton({ helper, onClick, busy = false, children, className = "", size = "md" }: {
+  helper: AiHelper;
+  onClick: () => void;
+  busy?: boolean;
+  children: React.ReactNode;
+  className?: string;
+  size?: "sm" | "md";
+}) {
+  const status = useAiStatus();
+  const reasonId = useId();
+  if (!status?.enabled) return null;
+  const reason = disabledReason(status, helper);
+  const pad = size === "sm" ? "px-2 py-1 text-xs" : "px-3 py-1.5 text-sm";
+  return (
+    <span className="inline-flex flex-col">
+      <button
+        type="button"
+        onClick={onClick}
+        disabled={busy || !!reason}
+        title={reason || undefined}
+        aria-describedby={reason ? reasonId : undefined}
+        className={`inline-flex items-center gap-1.5 rounded-lg border border-violet-200 bg-violet-50 font-medium text-violet-800 hover:bg-violet-100 disabled:cursor-not-allowed disabled:opacity-60 ${pad} ${className}`}
+      >
+        {busy ? <Loader2 className="h-4 w-4 animate-spin" aria-hidden /> : <Sparkles className="h-4 w-4" aria-hidden />}
+        {children}
+      </button>
+      {reason && <span id={reasonId} className="sr-only">{reason}</span>}
+    </span>
+  );
+}
+
+/** Under every AI result: a person checks it before anything is saved or sent. */
+export function AiNotice({ className = "" }: { className?: string }) {
+  return (
+    <p className={`flex items-center gap-1.5 text-xs text-violet-800 ${className}`}>
+      <Sparkles className="h-3.5 w-3.5" aria-hidden /> AI suggestion — check it before saving.
+    </p>
+  );
+}

frontend/src/hooks/useAiStatus.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useAuth } from "@/hooks/useAuth";
+import { currentAiStatus, loadAiStatus, subscribeAiStatus, type AiStatus } from "@/lib/ai";
+
+/**
+ * Whether to show the AI buttons, shared across the page (one request per page load). Null while
+ * loading, and for anyone who isn't a supervisor or admin — AI helpers are theirs only.
+ */
+export function useAiStatus(): AiStatus | null {
+  const { user, token } = useAuth();
+  const allowed = !!token && (user?.role === "admin" || user?.role === "supervisor");
+  const [status, setStatus] = useState<AiStatus | null>(() => (allowed ? currentAiStatus() : null));
+
+  useEffect(() => {
+    if (!allowed || !token) return;
+    const off = subscribeAiStatus(setStatus);
+    loadAiStatus(token).then(setStatus).catch(() => {});
+    return off;
+  }, [allowed, token]);
+
+  return allowed ? status : null;
+}

frontend/src/lib/ai.ts

@@ -0,0 +1,76 @@
+import { apiV2Data, apiV2Raw } from "@/lib/apiV2";
+import type { V2Result } from "@/lib/apiV2";
+
+/**
+ * AI helpers (2.0). The site calls AI through the Cross Events Hub, which keeps a monthly
+ * allowance in rand per licence. One status per page load is shared by every AI button
+ * (`useAiStatus`), and every helper call refreshes it — so the buttons disable straight after the
+ * call that used up the allowance.
+ */
+
+export type AiStatus = V2Result<"/ai/status", "get">["data"];
+export type AiHelper = keyof AiStatus["helpers"];
+
+const OFF: AiStatus = {
+  enabled: false, capReached: false, available: true, capCents: 0, usedCents: 0, usedPercent: 0, renewsOn: null,
+  helpers: { draft_event: false, summarise_report: false, draft_message: false, summarise_feedback: false, improve_text: false },
+};
+
+let current: AiStatus | null = null;
+let loading: Promise<AiStatus> | null = null;
+const listeners = new Set<(s: AiStatus) => void>();
+
+function publish(s: AiStatus) {
+  current = s;
+  listeners.forEach(l => l(s));
+}
+
+/** The status, fetched once per page load (staff never see AI, so they never ask). */
+export function loadAiStatus(authToken: string, { fresh = false } = {}): Promise<AiStatus> {
+  if (current && !fresh) return Promise.resolve(current);
+  if (!loading || fresh) {
+    loading = (apiV2Data("get", "/ai/status", { authToken }) as Promise<AiStatus>)
+      .then(s => { publish(s); return s; })
+      .catch(() => { publish(OFF); return OFF; })
+      .finally(() => { loading = null; });
+  }
+  return loading;
+}
+
+export function subscribeAiStatus(fn: (s: AiStatus) => void): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+export function currentAiStatus(): AiStatus | null {
+  return current;
+}
+
+/** "1 December" from "2026-12-01". */
+export function renewsText(renewsOn: string | null): string {
+  if (!renewsOn) return "next month";
+  return new Date(`${renewsOn}T12:00:00Z`).toLocaleDateString("en-ZA", { day: "numeric", month: "long" });
+}
+
+/** What the button's tooltip says when it can't be used. */
+export function disabledReason(s: AiStatus, helper: AiHelper): string | null {
+  if (s.capReached) return `This month's AI allowance is used up — it renews on ${renewsText(s.renewsOn)}.`;
+  if (!s.available) return "AI is unavailable right now. Try again in a few minutes.";
+  if (!s.helpers[helper]) return "This AI helper is switched off in Site settings → AI.";
+  return null;
+}
+
+/**
+ * Run a helper (`POST /api/v2/ai/<helper>`). Resolves to its answer; throws the API error (with
+ * a message written for people). Either way the shared status is refreshed.
+ */
+export async function runAi<T>(helper: AiHelper, body: object, authToken: string): Promise<T> {
+  try {
+    const res = await apiV2Raw<{ output: T; status: AiStatus }>("post", `/ai/${helper.replace(/_/g, "-")}`, { authToken, body });
+    publish(res.status);
+    return res.output;
+  } catch (e) {
+    loadAiStatus(authToken, { fresh: true }).catch(() => {});
+    throw e;
+  }
+}

frontend/src/lib/api-v2/openapi.json

@@ -97,6 +97,9 @@
     },
     {
       "name": "Webhooks"
+    },
+    {
+      "name": "AI"
     }
   ],
   "paths": {
@@ -29239,7 +29242,7 @@
           "Accounts"
         ],
         "summary": "Email me a link to reset my password",
-        "description": "NOT_FOUND when no account has that email (as v1 does).\n\n**Who:** Anyone.",
+        "description": "Always the same answer, so it doesn't say whether an account has that email. Rate-limited like sign-in.\n\n**Who:** Anyone.",
         "operationId": "postAuthPasswordForgot",
         "parameters": [],
         "requestBody": {
@@ -39939,6 +39942,548 @@
           }
         }
       }
+    },
+    "/ai/status": {
+      "get": {
+        "tags": [
+          "AI"
+        ],
+        "summary": "Whether to show the AI buttons",
+        "description": "Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it.\n\n**Who:** Supervisors and admins.",
+        "operationId": "getAiStatus",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "description": "false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub)"
+                        },
+                        "capReached": {
+                          "type": "boolean",
+                          "description": "true: show the buttons disabled until `renewsOn`"
+                        },
+                        "available": {
+                          "type": "boolean",
+                          "description": "false: the Hub couldn't be reached just now"
+                        },
+                        "capCents": {
+                          "type": "number",
+                          "description": "The monthly allowance, in cents"
+                        },
+                        "usedCents": {
+                          "type": "number",
+                          "description": "Used this month, in cents (fractions of a cent)"
+                        },
+                        "usedPercent": {
+                          "type": "number"
+                        },
+                        "renewsOn": {
+                          "description": "YYYY-MM-DD",
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "helpers": {
+                          "type": "object",
+                          "properties": {
+                            "draft_event": {
+                              "type": "boolean"
+                            },
+                            "summarise_report": {
+                              "type": "boolean"
+                            },
+                            "draft_message": {
+                              "type": "boolean"
+                            },
+                            "summarise_feedback": {
+                              "type": "boolean"
+                            },
+                            "improve_text": {
+                              "type": "boolean"
+                            }
+                          },
+                          "required": [
+                            "draft_event",
+                            "summarise_report",
+                            "draft_message",
+                            "summarise_feedback",
+                            "improve_text"
+                          ],
+                          "additionalProperties": false,
+                          "description": "Each helper switched on or off in Site settings → AI"
+                        }
+                      },
+                      "required": [
+                        "enabled",
+                        "capReached",
+                        "available",
+                        "capCents",
+                        "usedCents",
+                        "usedPercent",
+                        "renewsOn",
+                        "helpers"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Not signed in (UNAUTHENTICATED)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Not allowed for this role (FORBIDDEN)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/ai/usage": {
+      "get": {
+        "tags": [
+          "AI"
+        ],
+        "summary": "AI use this month",
+        "description": "For Site settings → AI: the allowance, this site's switches, and this month's use per person, per helper and per day.\n\n**Who:** Admins only.",
+        "operationId": "getAiUsage",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "status": {
+                          "type": "object",
+                          "properties": {
+                            "enabled": {
+                              "type": "boolean",
+                              "description": "false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub)"
+                            },
+                            "capReached": {
+                              "type": "boolean",
+                              "description": "true: show the buttons disabled until `renewsOn`"
+                            },
+                            "available": {
+                              "type": "boolean",
+                              "description": "false: the Hub couldn't be reached just now"
+                            },
+                            "capCents": {
+                              "type": "number",
+                              "description": "The monthly allowance, in cents"
+                            },
+                            "usedCents": {
+                              "type": "number",
+                              "description": "Used this month, in cents (fractions of a cent)"
+                            },
+                            "usedPercent": {
+                              "type": "number"
+                            },
+                            "renewsOn": {
+                              "description": "YYYY-MM-DD",
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "helpers": {
+                              "type": "object",
+                              "properties": {
+                                "draft_event": {
+                                  "type": "boolean"
+                                },
+                                "summarise_report": {
+                                  "type": "boolean"
+                                },
+                                "draft_message": {
+                                  "type": "boolean"
+                                },
+                                "summarise_feedback": {
+                                  "type": "boolean"
+                                },
+                                "improve_text": {
+                                  "type": "boolean"
+                                }
+                              },
+                              "required": [
+                                "draft_event",
+                                "summarise_report",
+                                "draft_message",
+                                "summarise_feedback",
+                                "improve_text"
+                              ],
+                              "additionalProperties": false,
+                              "description": "Each helper switched on or off in Site settings → AI"
+                            }
+                          },
+                          "required": [
+                            "enabled",
+                            "capReached",
+                            "available",
+                            "capCents",
+                            "usedCents",
+                            "usedPercent",
+                            "renewsOn",
+                            "helpers"
+                          ],
+                          "additionalProperties": false
+                        },
+                        "settings": {
+                          "type": "object",
+                          "properties": {
+                            "helpers": {
+                              "type": "object",
+                              "properties": {
+                                "draft_event": {
+                                  "type": "boolean"
+                                },
+                                "summarise_report": {
+                                  "type": "boolean"
+                                },
+                                "draft_message": {
+                                  "type": "boolean"
+                                },
+                                "summarise_feedback": {
+                                  "type": "boolean"
+                                },
+                                "improve_text": {
+                                  "type": "boolean"
+                                }
+                              },
+                              "required": [
+                                "draft_event",
+                                "summarise_report",
+                                "draft_message",
+                                "summarise_feedback",
+                                "improve_text"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "dailyLimitPerPerson": {
+                              "type": "integer",
+                              "minimum": 0,
+                              "maximum": 1000,
+                              "description": "0 = no limit"
+                            }
+                          },
+                          "required": [
+                            "helpers",
+                            "dailyLimitPerPerson"
+                          ],
+                          "additionalProperties": false
+                        },
+                        "people": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "uses": {
+                                "type": "integer",
+                                "minimum": -9007199254740991,
+                                "maximum": 9007199254740991
+                              },
+                              "chargedCents": {
+                                "type": "number"
+                              },
+                              "userId": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "uses",
+                              "chargedCents",
+                              "userId",
+                              "name"
+                            ],
+                            "additionalProperties": false
+                          }
+                        },
+                        "helpers": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "uses": {
+                                "type": "integer",
+                                "minimum": -9007199254740991,
+                                "maximum": 9007199254740991
+                              },
+                              "chargedCents": {
+                                "type": "number"
+                              },
+                              "helper": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "uses",
+                              "chargedCents",
+                              "helper"
+                            ],
+                            "additionalProperties": false
+                          }
+                        },
+                        "days": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "uses": {
+                                "type": "integer",
+                                "minimum": -9007199254740991,
+                                "maximum": 9007199254740991
+                              },
+                              "chargedCents": {
+                                "type": "number"
+                              },
+                              "day": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "uses",
+                              "chargedCents",
+                              "day"
+                            ],
+                            "additionalProperties": false
+                          }
+                        }
+                      },
+                      "required": [
+                        "status",
+                        "settings",
+                        "people",
+                        "helpers",
+                        "days"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Not signed in (UNAUTHENTICATED)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Not allowed for this role (FORBIDDEN)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/ai/settings": {
+      "put": {
+        "tags": [
+          "AI"
+        ],
+        "summary": "Switch helpers on or off, and set a daily limit",
+        "description": "**Who:** Admins only.",
+        "operationId": "putAiSettings",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "helpers": {
+                    "type": "object",
+                    "properties": {
+                      "draft_event": {
+                        "type": "boolean"
+                      },
+                      "summarise_report": {
+                        "type": "boolean"
+                      },
+                      "draft_message": {
+                        "type": "boolean"
+                      },
+                      "summarise_feedback": {
+                        "type": "boolean"
+                      },
+                      "improve_text": {
+                        "type": "boolean"
+                      }
+                    }
+                  },
+                  "dailyLimitPerPerson": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 1000
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "helpers": {
+                          "type": "object",
+                          "properties": {
+                            "draft_event": {
+                              "type": "boolean"
+                            },
+                            "summarise_report": {
+                              "type": "boolean"
+                            },
+                            "draft_message": {
+                              "type": "boolean"
+                            },
+                            "summarise_feedback": {
+                              "type": "boolean"
+                            },
+                            "improve_text": {
+                              "type": "boolean"
+                            }
+                          },
+                          "required": [
+                            "draft_event",
+                            "summarise_report",
+                            "draft_message",
+                            "summarise_feedback",
+                            "improve_text"
+                          ],
+                          "additionalProperties": false
+                        },
+                        "dailyLimitPerPerson": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 1000,
+                          "description": "0 = no limit"
+                        }
+                      },
+                      "required": [
+                        "helpers",
+                        "dailyLimitPerPerson"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation failed (VALIDATION_FAILED)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Not signed in (UNAUTHENTICATED)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Not allowed for this role (FORBIDDEN)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -39973,6 +40518,7 @@
                   "CONFLICT",
                   "RATE_LIMITED",
                   "READ_ONLY",
+                  "UNAVAILABLE",
                   "INTERNAL"
                 ]
               },

frontend/src/lib/api-v2/schema.d.ts

@@ -4509,7 +4509,7 @@ export interface paths {
         put?: never;
         /**
          * Email me a link to reset my password
-         * @description NOT_FOUND when no account has that email (as v1 does).
+         * @description Always the same answer, so it doesn't say whether an account has that email. Rate-limited like sign-in.
          *
          *     **Who:** Anyone.
          */
@@ -6930,6 +6930,70 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/ai/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Whether to show the AI buttons
+         * @description Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it.
+         *
+         *     **Who:** Supervisors and admins.
+         */
+        get: operations["getAiStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/ai/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * AI use this month
+         * @description For Site settings → AI: the allowance, this site's switches, and this month's use per person, per helper and per day.
+         *
+         *     **Who:** Admins only.
+         */
+        get: operations["getAiUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/ai/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Switch helpers on or off, and set a daily limit
+         * @description **Who:** Admins only.
+         */
+        put: operations["putAiSettings"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -6937,7 +7001,7 @@ export interface components {
         Error: {
             error: {
                 /** @enum {string} */
-                code: "VALIDATION_FAILED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "READ_ONLY" | "INTERNAL";
+                code: "VALIDATION_FAILED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "READ_ONLY" | "UNAVAILABLE" | "INTERNAL";
                 message: string;
                 /** @description Per-field problems (VALIDATION_FAILED only) */
                 fields?: {
@@ -29721,4 +29785,229 @@ export interface operations {
             };
         };
     };
+    getAiStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: {
+                            /** @description false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub) */
+                            enabled: boolean;
+                            /** @description true: show the buttons disabled until `renewsOn` */
+                            capReached: boolean;
+                            /** @description false: the Hub couldn't be reached just now */
+                            available: boolean;
+                            /** @description The monthly allowance, in cents */
+                            capCents: number;
+                            /** @description Used this month, in cents (fractions of a cent) */
+                            usedCents: number;
+                            usedPercent: number;
+                            /** @description YYYY-MM-DD */
+                            renewsOn: string | null;
+                            /** @description Each helper switched on or off in Site settings → AI */
+                            helpers: {
+                                draft_event: boolean;
+                                summarise_report: boolean;
+                                draft_message: boolean;
+                                summarise_feedback: boolean;
+                                improve_text: boolean;
+                            };
+                        };
+                    };
+                };
+            };
+            /** @description Not signed in (UNAUTHENTICATED) */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Not allowed for this role (FORBIDDEN) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    getAiUsage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: {
+                            status: {
+                                /** @description false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub) */
+                                enabled: boolean;
+                                /** @description true: show the buttons disabled until `renewsOn` */
+                                capReached: boolean;
+                                /** @description false: the Hub couldn't be reached just now */
+                                available: boolean;
+                                /** @description The monthly allowance, in cents */
+                                capCents: number;
+                                /** @description Used this month, in cents (fractions of a cent) */
+                                usedCents: number;
+                                usedPercent: number;
+                                /** @description YYYY-MM-DD */
+                                renewsOn: string | null;
+                                /** @description Each helper switched on or off in Site settings → AI */
+                                helpers: {
+                                    draft_event: boolean;
+                                    summarise_report: boolean;
+                                    draft_message: boolean;
+                                    summarise_feedback: boolean;
+                                    improve_text: boolean;
+                                };
+                            };
+                            settings: {
+                                helpers: {
+                                    draft_event: boolean;
+                                    summarise_report: boolean;
+                                    draft_message: boolean;
+                                    summarise_feedback: boolean;
+                                    improve_text: boolean;
+                                };
+                                /** @description 0 = no limit */
+                                dailyLimitPerPerson: number;
+                            };
+                            people: {
+                                uses: number;
+                                chargedCents: number;
+                                userId: string | null;
+                                name: string;
+                            }[];
+                            helpers: {
+                                uses: number;
+                                chargedCents: number;
+                                helper: string;
+                            }[];
+                            days: {
+                                uses: number;
+                                chargedCents: number;
+                                day: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+            /** @description Not signed in (UNAUTHENTICATED) */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Not allowed for this role (FORBIDDEN) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    putAiSettings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    helpers?: {
+                        draft_event?: boolean;
+                        summarise_report?: boolean;
+                        draft_message?: boolean;
+                        summarise_feedback?: boolean;
+                        improve_text?: boolean;
+                    };
+                    dailyLimitPerPerson?: number;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: {
+                            helpers: {
+                                draft_event: boolean;
+                                summarise_report: boolean;
+                                draft_message: boolean;
+                                summarise_feedback: boolean;
+                                improve_text: boolean;
+                            };
+                            /** @description 0 = no limit */
+                            dailyLimitPerPerson: number;
+                        };
+                    };
+                };
+            };
+            /** @description Validation failed (VALIDATION_FAILED) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Not signed in (UNAUTHENTICATED) */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Not allowed for this role (FORBIDDEN) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
 }

frontend/src/lib/commandPages.ts

@@ -61,7 +61,7 @@ export const COMMAND_PAGES: CommandPage[] = [
   ...([
     ["organisation", "Organisation"], ["campuses", "Campuses"], ["branding", "Branding"], ["notifications", "Notifications"],
     ["email", "Email"], ["legal", "Legal"], ["whatsapp", "WhatsApp"], ["payments", "Payments"], ["webhooks", "Webhooks"],
-    ["backups", "Backups"], ["jobs", "Background jobs"], ["licence", "Licence & updates"],
+    ["backups", "Backups"], ["jobs", "Background jobs"], ["licence", "Licence & updates"], ["ai", "AI helpers"],
   ] as const).map(([tab, label]): CommandPage => ({ group: "Settings", label: `Settings: ${label}`, href: `/dashboard/admin/settings?tab=${tab}`, roles: ADM, keywords: "site settings" })),
   // Reports — every report in the catalogue
   ...REPORTS.map((r): CommandPage => ({ group: "Reports", label: `Report: ${r.label}`, href: `/dashboard/supervisor/reports?report=${r.key}`, roles: SUP, keywords: `report ${r.category} ${r.description}` })),

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hope-events",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hope-events",
-      "version": "1.51.16",
+      "version": "1.51.17",
       "license": "ISC",
       "devDependencies": {
         "@axe-core/playwright": "^4.14.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hope-events",
-  "version": "1.51.16",
+  "version": "1.51.17",
   "main": "index.js",
   "scripts": {
     "dev:backend": "cd backend && npm run dev",