Merge branch 'docs/moved-to-platform'

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

docs/HANDOVER.md

@@ -1,10 +1,14 @@
 # Handover — where things stand and how to carry on
 
-Last updated: 2026-11-04, after **2.1.1** (deployed), Hub **1.7.0** and **contracts 1.0.0**;
-ROADMAP-v3 updated for the monorepo move and the `crosscode` deploy script (decisions 21–24). **The plan from here is
-[ROADMAP-v3.md](./ROADMAP-v3.md)** (Accounts, Church Website, Church App, Cross Code Hub; decisions
-table near the end). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round
-before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
+Last updated: 2026-11-05, after **2.1.1** (deployed). **This file covers Cross Events only**
+(what's been done, where the code lives, known gaps). **The plan for every product and where each
+phase stands moved to the platform monorepo:** `crosscode-platform/docs/` →
+[ROADMAP-v3.md](../../crosscode-platform/docs/ROADMAP-v3.md),
+[HANDOVER.md](../../crosscode-platform/docs/HANDOVER.md) (all products) and
+[EVENTS-2.2-PLAN.md](../../crosscode-platform/docs/EVENTS-2.2-PLAN.md) (the next Events release:
+the move into the monorepo). The Hub protocol moved there too (`docs/hub-protocol.md`). How Cross
+Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round before that in
+[FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 
 The product is called **Cross Events** (renamed from Hope Events in 1.41.3); the Hub is the
 **Cross Events Hub**. Technical names keep `hope-events` on purpose — the repo, browser storage
@@ -90,38 +94,18 @@ encrypted settings unreadable or break existing installs.
 
 ## Next up
 
-1. **Roadmap v3** ([ROADMAP-v3.md](./ROADMAP-v3.md), decided 2026-11-03). Everything in
-   ROADMAP-v2 is done: 2.1.1 is deployed, and the marketing site (`../crosscode-site`,
-   crosscode.co.za, with prices) is live. Build order (§9):
-   - **0 — contracts 1.0.0: released 2026-11-04** (`../crosscode-platform`, tag `contracts@1.0.0`):
-     `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2, generated
-     JSON Schema in `packages/contracts/schemas/`. Not published to Gitea's package registry, and
-     won't be (decision 22).
-   - **1 — Hub 2.0.0** (`../events-hub`): Cross Code Hub — products, one licence per product,
-     **one install of each product per customer**, domain per customer, bundles, sibling discovery,
-     **releases per product** (Events from `crosscode-platform` `events@…` tags, keeping the
-     `hope-events` `v…` releases) **with requirements** (`— requires accounts 1.2.0`, Request update
-     disabled until met). Contracts as `vendor/crosscode-contracts-1.0.0.tgz` (ROADMAP-v3 §2, §5).
-   - **1b — Cross Events 2.2.0: moves into the monorepo** as `apps/events` with its history, and the
-     **`crosscode` script** (`deploy <church> [events] [website] [app]` — Accounts always —,
-     `status`, `install`, `adopt`) replaces `scripts/deploy.sh` / `install.sh`. Run
-     `crosscode adopt` once per existing install; then archive this repo (ROADMAP-v3 §8,
-     "Releases and updates"). From here on this file and the roadmap live in the monorepo.
-   - **1c — Cross Events 2.3.0:** **authenticator app 2FA** (TOTP + recovery codes) next to email
-     and WhatsApp (`TwoFactorMethod` enum in `prisma/schema.prisma`).
-   - **2 — Cross Events 2.4.0:** protocol v2, Linked products, the event feed (publish and show).
-   - **3 — Accounts 1.0.0**, **4 — Church Website 1.0.0**, **5 — Cross Events 3.0.0** (sign-in
-     moves to Accounts), **6 — Church App 1.0.0** (House of Prayer).
-   - **Before selling the Website or App:** put the prices decided in ROADMAP-v3 §10 in
-     `crosscode-site/src/data/pricing.mjs` and the Hub's `frontend/src/lib/tiers.ts`.
-   - Servers stay **PM2 + nginx** (no Docker); one database per product per church.
+1. **Roadmap v3**, across every product: see `crosscode-platform/docs/HANDOVER.md` ("Where each
+   phase stands", "Next up"). For Cross Events that means **2.2.0** (the move into the monorepo as
+   `apps/events`, with the `crosscode` script; `crosscode-platform/docs/EVENTS-2.2-PLAN.md`), then
+   **2.3.0** (authenticator app 2FA, `TwoFactorMethod` in `prisma/schema.prisma`) and **2.4.0**
+   (protocol v2, Linked products, the event feed).
+   - **Deploying until 2.2.0:** `bash scripts/deploy.sh --check`, then
+     `bash scripts/deploy.sh v<version>` on each server (installs ask through Request update as
+     usual). From 2.2.0 on: `crosscode deploy <church> events`.
    - **AI for a church:** set the licence's monthly AI cap above R0 on the Hub (Hub 1.6.0+); with
      no cap the buttons don't show.
    - 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`.
-   - **Deploying:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v<version>` on
-     each server (installs ask through Request update as usual). From Events 2.2.0 on:
-     `crosscode deploy <church> events` (ROADMAP-v3 §8).
 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
@@ -274,7 +258,7 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026
 
 ## Where the Hub client lives (1.41.0, update requests 1.42.0)
 
-- Protocol: `docs/hub-protocol.md` — the same file is in the Hub repo (`joshua/events-hub`,
+- Protocol: `crosscode-platform/docs/hub-protocol.md` (moved from `docs/` here on 2026-11-05) — the same file is in the Hub repo (`joshua/events-hub`,
   developed at `../events-hub`); change both together.
 - `backend/src/hub/`: `publicKey.js` (the production Hub key, built in since 1.42.1 — if the Hub's
   signing key is ever regenerated, update it here in a release; `HUB_PUBLIC_KEY` env overrides it

docs/ROADMAP-v3.md

@@ -1,757 +1,4 @@
-# Cross Code — Road to three products
+# Cross Code — Road to three products — moved
 
-Planned work to go from one product (Cross Events 2.1.x) to three that can be sold separately or
-together: **Cross Events**, a **Church Website** and a **Church App**, all managed from one
-**Cross Code Hub**. Based on the two concept specs (church website platform, church app v1.1,
-3 November 2026), with the changes decided on 2026-11-03 (see [Decisions](#decisions-2026-11-03)).
-See [ROADMAP-v2.md](./ROADMAP-v2.md) for how Cross Events got to 2.x.
-
-**Theme:** a church can have any mix of products (Events, Website, App, all, or just the
-Website). People sign in to all of them with **one account**, and events flow between them in
-whatever direction the church chooses.
-
-**Updated 2026-11-04:** Cross Events moves into the `crosscode-platform` monorepo (§8), every
-product is released and deployed the same way with one `crosscode` script (§8, "Releases and
-updates"), the Hub tracks releases per product (§5), and the contracts reach the Hub as a file
-committed to its repo instead of through a package registry (§2). Cross Events versions in §9
-moved up by one (the move is 2.2.0). See decisions 21–24.
-
----
-
-## Contents
-
-1. [The shape](#1-the-shape)
-2. [Contracts (shared JSON formats)](#2-contracts-shared-json-formats)
-3. [Accounts (shared users)](#3-accounts-shared-users)
-4. [Event sync in any direction](#4-event-sync-in-any-direction)
-5. [Cross Code Hub (all products)](#5-cross-code-hub-all-products)
-6. [Church Website](#6-church-website)
-7. [Church App](#7-church-app)
-8. [Servers and deployment](#8-servers-and-deployment)
-9. [Build order](#9-build-order)
-10. [Pricing](#10-pricing)
-11. [SEO (every public site)](#11-seo-every-public-site)
-12. [Decisions](#decisions-2026-11-03)
-13. [Still open](#still-open)
-
----
-
-## 1. The shape
-
-Each church gets its own **church stack**: one install per product it has bought, each with its
-own process and its own database. The Hub only sees aggregate stats and licences.
-
-```
-                Cross Code Hub (hub.crosscode.co.za)
-      customers · licences per product · stats · AI proxy · billing
-                 ▲ register / heartbeat / licence (install → Hub only)
- ┌───────────────┼────────────────────────────────────────┐
- │ Church stack (e.g. Hope Family Church)                  │
- │                                                         │
- │   Accounts (accounts.church.co.za) ◄── sign-in (OIDC) ──┤
- │        ▲                ▲                     ▲         │
- │   Website (www.) ◄─feed─► Events (events.) ◄─feed─► App (app.)
- └─────────────────────────────────────────────────────────┘
-```
-
-**Rules**
-
-1. **No shared databases, ever.** Products only talk over HTTPS using documented contracts (§2).
-2. **The Hub is never on the runtime path.** It stays read-only toward installs: installs push to
-   it, it never reaches into them, and a Hub outage switches nobody off.
-3. **One maintained codebase per product.** Each church runs a tagged release of it. Nothing is
-   built specially for one church.
-4. **The origin of a record owns it.** Copies elsewhere are read-only and link back to the origin.
-
-**Products and what each one owns**
-
-| Product | Owns | Doesn't do |
-|---------|------|------------|
-| **Accounts** | People's accounts: name, email, phone, password, 2FA, privacy notice acceptance, news consent | Anything product-specific |
-| **Cross Events** | Events with registrations, tickets, payments, check-in, kids, rosters, POPIA toolkit | Website content |
-| **Church Website** | Public pages, leaders, ministries, messages (sermons), service times, simple events | Registrations or payments |
-| **Church App** | House of Prayer, announcements, devotionals, reading plans, groups, care, simple events | Registrations or payments |
-
----
-
-## 2. Contracts (shared JSON formats)
-
-Everything that crosses between products is defined **once**, in a shared package
-`@crosscode/contracts` (zod schemas + generated JSON Schema + TypeScript types + sample payloads).
-Every product, including Cross Events and the Hub, uses it. This is what keeps the key fields the
-same in every product's JSON.
-
-| Contract | Used for |
-|----------|----------|
-| `crosscode.event/1`, `crosscode.event-feed/1` | One event, and the feed every product publishes and reads (with the `event.changed` webhook) (§4) |
-| `crosscode.church/1` | The church profile: name, logo, colours, campuses, service times, contact details. Set once and shared |
-| `crosscode.identity/1` | The claims Accounts puts in a sign-in token, and the back-channel calls (`user.updated`, `user.deleted`, `user.export`) |
-| Hub protocol v2 | Register, heartbeat, licence token, AI calls, for every product (§5). Today's protocol (Cross Events 2.1, Hub 1.7) is v1, in `docs/hub-protocol.md` |
-
-**Versioning**
-
-- Adding an **optional** field keeps the version (`/1`). Consumers ignore fields they don't know.
-- Removing or renaming a field, adding a value to an enum (older consumers would refuse it), or changing a meaning needs a new version (`/2`). The old
-  version is served alongside it until every install has updated, as with `/api/v2`.
-- Every payload carries its `schema` name, so a consumer always knows what it's reading.
-- The package lives in the platform monorepo (§8). Every product there (Events, Accounts, Website,
-  App) uses it as a workspace, so no registry is involved.
-- **The Hub** (its own repo, §8) uses a packed release committed to its repo
-  (`vendor/crosscode-contracts-<version>.tgz`, `"@crosscode/contracts": "file:vendor/…"`), so its
-  deploys only need git and the public npm registry, and the lockfile pins the file's checksum.
-  Upgrading is a normal commit with the new file. Gitea's package registry isn't used (decided
-  2026-11-04): a registry on the deploy path would need a token on every server and could block a
-  deploy or a roll back.
-
----
-
-## 3. Accounts (shared users)
-
-A small per-church **OpenID Connect** provider (`oidc-provider` on the server, `openid-client` in
-each product). Every church stack has one, including website-only churches (where it only holds
-staff logins).
-
-**Why a separate service:** if one product held the users, cancelling that product would take
-everyone's login with it. With Accounts on its own, products can be added or cancelled without
-touching anyone's account.
-
-### What lives where
-
-| Accounts | Each product (keyed by the account's `sub`, a UUID) |
-|----------|-----------------------------------------------------|
-| Name, email, phone, password (Argon2id), 2FA (email, WhatsApp or an authenticator app), lockout, password reset, login history | Roles in that product. An Events supervisor isn't automatically an App prayer coordinator |
-| Privacy notice versions and acceptance, news consent (email / WhatsApp) | Product data: registrations and tickets (Events), prayer commitments (App), content edits (Website) |
-| "Download my data" and "Delete my account" entry points | Its share of the export and the anonymising, when Accounts asks |
-| Inactive-account retention | — |
-
-### How it works
-
-- Sign-in is the standard authorisation-code flow with PKCE. People sign in once at
-  `accounts.church.co.za` and are signed in to every product of that church.
-- **Sign-in always returns you to where you came from.** When a product sends someone to
-  `accounts.church.co.za` (they clicked Sign in, or opened a page that needs sign-in), it passes
-  the exact page they were on (path and query, e.g. `/events/youth-camp/register?ticket=adult`)
-  in the OIDC `state`. After sign-in, Accounts sends them back to **that product and that page**,
-  not to a dashboard or the account page. This holds through every step in between: 2FA,
-  "forgot password" and the reset link, creating a new account, the news question and privacy
-  notice re-acceptance. (Cross Events works this way today with `?redirect=`; the move to Accounts
-  keeps it.)
-  - **Safe redirects only:** Accounts only returns to the registered `redirect_uri` of a linked
-    product of the same church (exact match, no wildcards), and the product only accepts a
-    relative path from `state` (starting with a single `/`). Anything else falls back to the
-    product's home page. No open redirects.
-  - **Signing out** works the same way (`post_logout_redirect_uri`): you end up back on the
-    product you signed out from, signed out of all of the church's products.
-  - Opening `accounts.church.co.za` directly (nothing to return to) shows the account page.
-  - Tests: Playwright checks for each product that signing in from a deep link (including through
-    2FA and a password reset) lands back on that exact page, and that a foreign or absolute
-    return URL is refused.
-- **Accounts stays in the background** (decided 2026-11-03). Members never see it as a product:
-  the sign-in page carries the church's name and branding ("Sign in to Hope Family Church"), and
-  they manage their account from whichever product they're in. Only **admins** see Accounts as
-  such (people, sign-in settings, linked products), and **account holders** see their own
-  account page (profile, password, 2FA, privacy).
-- **2FA methods:** email, WhatsApp, or an **authenticator app** (TOTP, e.g. Google or Microsoft
-  Authenticator), with one-time recovery codes. Cross Events gets the authenticator option first
-  (2.3.0), and the migration carries it over (below).
-- Each product keeps a local copy of the profile (name, email) for lists and messages, updated on
-  sign-in and by `user.updated`.
-- **POPIA:** the church is one responsible party. "Download my data" asks every linked product for
-  its part (`user.export`) and bundles the answers. "Delete my account" deactivates the account at
-  once, then sends `user.deleted` to each product when an admin approves (the existing Events
-  rules apply: it waits while the person has an open registration for an upcoming event).
-- Back-channel calls are signed with a secret per product link and retried through pg-boss.
-- Accounts gets its own access log entries for exports and admin views of people.
-
-### Moving Cross Events onto Accounts (Cross Events 3.0)
-
-This is a breaking change, so it's a major version.
-
-- A migration copies every Events user into Accounts **with their existing password hash**, 2FA
-  setting (including authenticator secrets and unused recovery codes), consent and notice acceptance, so nobody has to reset anything. The Events `User`
-  table keeps its id (now equal to the account `sub`), role, campus scope and product data.
-- Sign-in, forgot password, 2FA, the news question and the notice re-acceptance move to Accounts.
-  The Events privacy centre links to Accounts for account-level items.
-- Every place Events sends someone to sign in today (`/login?redirect=…`, `useRequireAuth`, the
-  register / ticket flows) goes to Accounts with the current page as the return target, so
-  members land back exactly where they were (§3, "Sign-in always returns you to where you came
-  from"). Old `/login?redirect=…` links keep working by forwarding to Accounts with the same target.
-- Staff accounts work the same way: roles stay in Events.
-
----
-
-## 4. Event sync in any direction
-
-Every product can **publish** the events it owns and **show** events from its siblings. Each
-install has two settings:
-
-- **Publish my events:** on / off.
-- **Show events from:** ☐ Events ☐ Website ☐ App (only linked products are listed).
-
-That covers every setup: Events → Website and App; Events and App → Website; everything to
-everything; or nothing.
-
-### Rules
-
-- **Only the origin edits an event.** Imported events are read-only copies with a link back.
-  Corrections happen at the origin and arrive with the next sync.
-- **No loops:** a product only publishes events it *originated*, never ones it imported.
-- **No duplicates:** an event is identified by `origin.product` + `origin.id`.
-- **Only Cross Events takes registrations and payments.** The Website and App can create
-  **simple events** (title, dates, place, image, description, and an optional external link or
-  contact instructions).
-- Each product keeps the last good copy of each feed. If a source is down, its events keep
-  showing, and admins see "last synced 2 hours ago".
-
-### Transport
-
-- `GET /api/feed/v1/events?updatedSince=<ISO>` → `{ schema: "crosscode.event-feed/1", generatedAt, events: [...], deleted: [...] }`.
-  Public events only, so no personal information ever goes through the feed.
-- A signed webhook `event.changed` tells consumers to fetch straight away.
-- Consumers also poll every 15 minutes as a fallback (pg-boss job).
-- Timeouts, retries with back-off, and one failing source never blocks another.
-
-### `crosscode.event/1`
-
-```json
-{
-  "schema": "crosscode.event/1",
-  "id": "8f1c2a4e-…",
-  "origin": {
-    "product": "events",
-    "installId": "inst_…",
-    "url": "https://events.hopefamily.co.za/events/youth-camp"
-  },
-  "status": "published",
-  "updatedAt": "2026-11-03T10:00:00Z",
-  "title": "Youth Camp 2026",
-  "summary": "Three days at Camp Wartburg",
-  "description": "Sanitised markdown…",
-  "imageUrl": "https://events.hopefamily.co.za/uploads/…",
-  "timezone": "Africa/Johannesburg",
-  "startsAt": "2026-03-14T08:00:00Z",
-  "endsAt": "2026-03-16T14:00:00Z",
-  "allDay": false,
-  "sessions": [
-    { "id": "…", "label": "Day 1", "startsAt": "…", "endsAt": "…", "location": null, "cancelled": false }
-  ],
-  "location": { "name": "Camp Wartburg", "address": "…", "onlineUrl": null },
-  "campus": { "slug": "meyerton", "name": "Meyerton" },
-  "series": { "id": "…", "name": "Youth Camp" },
-  "tags": ["youth"],
-  "registration": {
-    "mode": "origin",
-    "url": "https://events.hopefamily.co.za/events/youth-camp",
-    "status": "open",
-    "opensAt": null,
-    "closesAt": "2026-03-10T22:00:00Z",
-    "priceFrom": { "amountCents": 45000, "currency": "ZAR" }
-  }
-}
-```
-
-| Field | Values / notes |
-|-------|----------------|
-| `origin.product` | `events` · `website` · `app` |
-| `status` | `published` · `cancelled` (unpublished or deleted events go in `deleted`) |
-| `sessions` | Empty for a single-date event. `startsAt` / `endsAt` are always the first start and last end |
-| `campus` | `null` = all campuses or campuses off |
-| `registration.mode` | `origin` (register at the origin, Events only) · `external` (a link) · `contact` (instructions in the description) · `none` |
-| `registration.status` | `open` · `not_open` · `closed` · `full` · `waitlist`. Only Events sends anything but `open` |
-| `priceFrom` | Lowest current price in cents, or `null` for free / not applicable |
-
----
-
-## 5. Cross Code Hub (all products)
-
-The Events Hub (`joshua/events-hub`, Hub 1.7.0) becomes **Cross Code Hub 2.0**: one place for every
-product's customers, licences, stats, AI usage and billing.
-
-- **Customer → installs.** Each install has a `product` (`events` · `website` · `app` ·
-  `accounts`) and its **own licence**. Accounts is licensed with whatever else the church has
-  (no charge of its own). **A customer has at most one install of each product** (decided
-  2026-11-03): the Hub refuses a second licence for the same product, so "the church's website"
-  or "the church's Events" is never ambiguous.
-- **Address per customer:** own domain, Cross Code address (`church.crosscode.co.za`) or domain
-  included (§10), recorded on the customer, since one address covers all its products. The
-  Hub reminds Joshua before an included domain is due for renewal.
-- **Add-ons per customer:** the address (R10 or R25) and extra website storage, billed with the
-  products but never bundle-discounted. Website installs report storage used in the heartbeat.
-- **Billing per customer:** prices per product on the income bands, bundles at **15% off two
-  products** and **25% off all three**, founding prices and the free month (as on
-  crosscode.co.za). Invoices are recorded in the Hub (sent / paid / overdue). A payment provider
-  integration comes later.
-- **Protocol v2:** adds `product` to register and heartbeat, and per-product stats (aggregate
-  counts only, as today: no personal information). The Hub keeps accepting protocol v1, so Events
-  installs keep reporting until they update.
-- **Sibling discovery:** the licence token carries the `customerId`. The heartbeat reply lists the
-  church's other installs (product, URL, public key; nothing else). Each product shows them
-  under **Settings → Linked products** with a **Connect** button that sets up the feed (§4) and
-  the Accounts client (§3). The list is cached, so a Hub outage changes nothing.
-- **AI:** the existing proxy, cap and markup serve every product. Usage is recorded per product,
-  and the cap stays per customer.
-- **Releases per product.** Each product has a release source: repo, tag pattern and notes
-  file. Releases carry a `product`, so "update available", **Request update** and "versions
-  behind" work per install.
-
-  | Product | Repo | Tags | Notes |
-  |---------|------|------|-------|
-  | Events | `crosscode-platform` | `events@2.2.0` on | `apps/events/WHATS-NEW.md` |
-  | Events (before the move) | `hope-events` (archived) | `v1.0.0` … `v2.1.x` | its `WHATS-NEW.md` |
-  | Accounts | `crosscode-platform` | `accounts@1.2.3` | `apps/accounts/WHATS-NEW.md` |
-  | Website | `crosscode-platform` | `website@1.2.3` | `apps/website/WHATS-NEW.md` |
-  | App | `crosscode-platform` | `app@1.2.3` | `apps/app/WHATS-NEW.md` |
-
-  `contracts@` tags are ignored (nobody installs them). The Events releases before the move stay
-  (today's sync removes releases without a tag; with two sources it only removes a release
-  missing from its own source).
-- **Requirements between products.** A release can say what it needs, in its `WHATS-NEW.md`
-  heading: `## 3.0.0 — requires accounts 1.2.0` (several: `requires accounts 1.2.0, website
-  1.1.0`; it can be combined with `— urgent`). The Hub shows it on the install, and **Request
-  update stays disabled** ("Accounts must be updated to 1.2.0 first") until the church's install
-  of that product reports that version or later. The `crosscode` script checks the same thing
-  before it deploys (§8). By default products never need to update together: the contract rules
-  (§2) and protocol v1 + v2 make that possible, so requirements are only for real breaking moves
-  such as Events 3.0.
-- **Request update** works for every product. The Hub still never runs anything on an install.
-- **Domain:** `hub.crosscode.co.za`. `events-hub.crosscode.co.za` stays as an alias so existing
-  installs keep working.
-- Dashboard: installs per product, versions behind latest, health, licence status, monthly
-  recurring revenue, overdue invoices.
-
----
-
-## 6. Church Website
-
-A professional public website the church manages itself. From the website spec, adjusted.
-
-### Public site
-
-- **Pages:** Home, New Here? / Plan Your Visit, About (story, mission, vision, values, beliefs),
-  Leadership, Ministries (overview + one page each), Events (list, detail, calendar, past),
-  Messages (sermons, series), Give (information and provider links), Contact, Privacy /
-  POPIA / safeguarding / terms.
-- **Homepage order:** hero with Plan Your Visit, service times and location, mission,
-  introduction, ministries and team, upcoming events, latest message, final invitation (each
-  template starts from this and arranges it its own way, below).
-- Server-rendered, fast on a phone, accessible (WCAG 2.2 AA, axe checks in Playwright), with
-  the SEO in §11.
-
-### Templates: each church its own identity
-
-The website is the most personal of the products, so churches shouldn't all look the same.
-The Website ships with **four templates**, each with its own **layout and design**. The church
-picks one; its **logo and colours come from the church profile** (`crosscode.church/1`), and its
-**content fills into the chosen template**.
-
-| Template | Character | Layout and design |
-|----------|-----------|-------------------|
-| **Heritage** | Traditional, dignified | Centred logo and navigation above a framed hero image; serif headings; generous margins; content in a single centred column with thin rules between sections; service times in a formal panel |
-| **Bold** | Modern, energetic | Full-screen photo or video hero with large overlaid headline; sticky transparent header; strong sans-serif type; full-bleed alternating image / text bands; large "Plan your visit" call to action |
-| **Community** | Warm, friendly, family | Logo left, rounded friendly type; a hero with photo collage; content in cards (ministries, events, messages as a grid); soft shapes and the church colour as tinted backgrounds; people's faces prominent |
-| **Clean** | Minimal, calm | Small header, lots of white space; typographic hero (no photo needed, good for churches without good photos); narrow text column; lists rather than cards; colour used sparingly as accent |
-
-**How it works**
-
-- **One content model, four presentations.** Content is structured (pages, sections, ministries,
-  leaders, messages, events, service times), never tied to a template. Every template renders
-  every section type in its own way, so **switching template never loses content**.
-- **The template sets the layout:** header and navigation style, hero type, how each section
-  type looks, section spacing, typography (with two or three font pairings to choose from per
-  template), shapes and image treatment, and the default homepage order. Within it, churches can
-  reorder, hide and show the approved sections, but not edit layout freely, so a site always
-  looks designed.
-- **Colours from the church, made safe:** the template builds its palette (tints, shades, text
-  colours, buttons) from the church's primary and accent colours, and checks contrast (WCAG AA).
-  A colour that fails is darkened or lightened automatically, and the admin is told why.
-- **Logo** in the template's header and footer positions; the icon (from the profile) for the
-  favicon and share images.
-- **Choosing:** the setup checklist starts with "Choose your template", showing all four
-  **previewed with the church's own logo, colours and content** (sample content until they have
-  their own). Switching later goes through preview → publish like any other change.
-- **Templates are part of the product**, not per church (§1, rule 3): they improve in each
-  release for every church using them. More templates can be added in later releases.
-- Every template meets the same bar: tested in Playwright (layout at phone / tablet / desktop,
-  axe accessibility) and with the §11 SEO checks.
-
-### Admin (`www.church.co.za/admin`, signed in through Accounts)
-
-- Dashboard with a setup checklist, recent edits and drafts.
-- **Template:** choose and preview the template, font pairing, and which homepage sections show
-  in which order.
-- Pages and sections, About, Leadership, Ministries, Messages, Media library, Contact and
-  service times, Navigation, Settings (including SEO and search engine verification, §11).
-- **Events:** simple events, plus the feed settings (§4) and sync health.
-- **Draft → preview → publish**, archive instead of delete, an audit log of who changed what.
-- **Roles:** Owner, Admin, Editor, Ministry leader (own ministry only), Viewer.
-
-### Not in the first release
-
-Prayer requests and other forms with personal information (they belong in the App), a member
-directory, online giving processing.
-
----
-
-## 7. Church App
-
-A church-branded **web app** (PWA) at `app.church.co.za`, added to the home screen. No app-store
-release. From the app spec, adjusted.
-
-### House of Prayer (the headline)
-
-- **24/7 coverage view:** a 24-hour timeline, coverage % and gaps, in the church's timezone.
-  Live updates through server-sent events, with polling as a fallback.
-- **Commitments:** one-off and recurring slots, change or cancel your own, optional reminders
-  by **email or WhatsApp**, a voluntary "I prayed" marker clearly shown as self-reported.
-- **Booking rules** (defaults decided 2026-11-03; the church can change them):
-
-  | Rule | Default |
-  |------|---------|
-  | Slot length | **1 hour** (church can choose 15, 30 or 60 minutes) |
-  | Book ahead | Up to **12 months** in advance |
-  | Recurring bookings | Daily or weekly, for up to **12 months from the day of booking**. Before it runs out the member gets an email/WhatsApp to renew it for another year |
-  | Cancelling | Up to **8 hours before** the slot. Within 8 hours the slot can't be cancelled in the app (the member is shown who to contact) |
-- **Anonymous:** public views show coverage only, never names. Admin access to bookings is
-  permission-controlled and goes in the access log.
-- **Prayer requests:** private by default (submitter and prayer team only). Public or group
-  prayer needs an explicit choice. Moderation (approve, redact, remove) and a safeguarding
-  escalation route. Never used for analytics or AI.
-- **Campaigns and testimonies:** time-bound campaigns with collective progress (no rankings),
-  testimonies moderated before publishing.
-
-### Other modules (each can be switched off by the church)
-
-Announcements, devotionals, reading plans, sermons (shared with the Website where both exist),
-connect groups, pastoral care (restricted access, audited), serving opportunities, giving links,
-an opt-in directory, and **events** (simple events plus the feed, §4).
-
-**Every module is available to every church.** Pricing follows church size (§10), not features.
-
-**Notifications are email and WhatsApp only** (decided 2026-11-03), using the same email and
-WhatsApp setup as Cross Events. No push notifications. Members choose their channel per kind of
-message (prayer reminders, announcements).
-
-### Roles
-
-Member, Prayer coordinator, Content admin, Pastoral care, Church admin. Public content can be
-browsed without an account. Personal actions need sign-in through Accounts.
-
----
-
-## 8. Servers and deployment
-
-**PM2 and nginx, like Cross Events today.** No Docker.
-
-- **Per church:** one PM2 process (or front/back pair) per product, one PostgreSQL database and
-  database user per product, its own `.env`, secrets, uploads folder, logs and backups. Names
-  carry the church slug (`hopefamily-website`, `hopefamily_website` DB, …).
-- **One `crosscode` script** installs and updates every product (below, "Releases and updates"),
-  built from today's `install.sh` and `deploy.sh`: a tagged update with a database backup,
-  migrations, build, restart and roll back on failure, for whichever products you name.
-- **Domains:** `www.`, `events.`, `app.` and `accounts.` on the church's own domain, or on
-  `<church>.crosscode.co.za` for the Cross Code address (a wildcard DNS record and certificate
-  for `*.crosscode.co.za` subdomains, so no DNS work per church). Certificates through certbot. Only configured domains are served (no trusting arbitrary Host headers).
-- Every product has `/health` (version, DB, jobs, last backup), reported to the Hub.
-- Several churches can share a server at first. Any church can move to its own server later
-  without code changes. The Hub stays on a separate server from church installs.
-
-### Repositories
-
-| Repo | What |
-|------|------|
-| `joshua/crosscode-platform` | **Every product a church installs**, and what they share: `apps/events` (Cross Events, moved here in 2.2.0), `apps/accounts`, `apps/website`, `apps/app`, `packages/contracts`, `packages/ui`, `packages/seo` (§11), and the `crosscode` script (`scripts/`) |
-| `joshua/hope-events` | Cross Events up to 2.1.x. **Archived** after the move (read-only, README points to the monorepo), and kept so installs that haven't moved yet can still deploy or roll back a `v2.1.x` tag |
-| `joshua/events-hub` | Cross Code Hub (renamed in the UI; repo name can stay). Stays on its own: it runs on its own server, is never installed for a church, and is deployed with its own `scripts/deploy.sh`. Gets the contracts as a committed file (§2) |
-| `joshua/crosscode-site` | The marketing site (crosscode.co.za). Updated at the end of every phase that changes what's on sale or what a product does (see §9, "Updating crosscode-site") |
-
-**Stack:** the same as Cross Events (Next.js, Express, TypeScript, Prisma, PostgreSQL, pg-boss,
-Playwright, Jest), so code and habits carry over.
-
-### Releases and updates
-
-**What doesn't change:** git is how code reaches a server, the Hub only records releases and
-passes on update requests (it never deploys, §1 rule 2), and Joshua runs the deploys.
-
-**Releasing.** Each product is tagged on its own in the monorepo: `events@2.2.0`,
-`accounts@1.0.0`, `website@1.0.0`, `app@1.0.0` (and `contracts@1.0.0`, which nobody installs).
-Each app keeps its own `CHANGELOG.md` and church-facing `WHATS-NEW.md` in its folder. The release
-routine is as today (branch → merge → tag → push), with the product's name in the tag. The Hub
-picks the tags up per product (§5).
-
-**On a server.** Each church gets a folder with a config file and one checkout of the monorepo
-per product, each at that product's own tag:
-
-```
-/opt/crosscode/
-  tools/                  the crosscode script (a checkout of main, updated before every run)
-  churches/hopefamily/
-    church.env            slug, products, domains, ports, PM2 names, database names, folders
-    accounts/             crosscode-platform at accounts@1.0.0
-    events/               crosscode-platform at events@3.1.0
-    website/              crosscode-platform at website@1.2.0
-```
-
-A product's folder can live elsewhere (`church.env` says where), so existing installs such as
-`/opt/hope-events` don't have to move, and their PM2 names, nginx names and database names stay
-as they are. Each checkout installs and builds only its own app (`npm ci -w apps/website`, its
-own migrations), so a Website install never builds Events.
-
-**The script** (run as root or the app user; `crosscode help` lists everything):
-
-| Command | What it does |
-|---------|--------------|
-| `crosscode deploy <church> [events] [website] [app]` | Updates **Accounts, always**, plus the products named, to their latest released tags. Products not named aren't touched |
-| `… --version events@3.1.0` | A specific release instead of the latest (repeatable, one per product) |
-| `… --main` | The latest main instead of a tag (for testing on a staging church only) |
-| `crosscode deploy <church> --check` | Only the checks below; changes nothing |
-| `crosscode deploy --every-church [events] …` | The same deploy for every church on this server, one after the other |
-| `crosscode status [<church>]` | Each product's version, latest release, health (from `/health`) and last backup |
-| `crosscode install <church> --products events,website --domain … ` | A new church (from today's `install.sh`): Accounts always, plus the products named; databases, `.env` files, PM2, nginx and certificates; prints the DNS records needed |
-| `crosscode add <church> app` | Adds a product to an existing church |
-| `crosscode adopt <church> --events-dir /opt/hope-events` | Once per existing Cross Events install: moves it onto the monorepo (below) |
-
-Before Accounts exists (until phase 3), "always Accounts" is skipped for churches that don't have
-it yet.
-
-**How a deploy runs**
-
-1. **Checks first, for every product named; if one fails nothing is touched:** files changed by
-   hand in a checkout (as `deploy.sh --check` today), the Node version, and the requirements of
-   the target releases (§5: `events@3.0.0` needs `accounts@1.2.0`, and Accounts is either already
-   there or part of this deploy).
-2. **In a fixed order: Accounts, then Events, Website, App.** Each product: database backup →
-   check out its tag → install and build its app → migrations → PM2 reload → `/health` answers
-   with the new version. If any step fails, **that product rolls back** to its previous tag (as
-   `deploy.sh` does today) and the deploy stops there.
-3. Products already updated in this run stay updated (no product needs its siblings to update
-   with it, §5), and the summary says which ones were updated, which rolled back and which weren't
-   reached.
-
-**Moving existing Cross Events installs (Events 2.2.0, `crosscode adopt`).** Once per server
-install, run by Joshua. It writes `church.env` (pointing at the existing folder), changes the
-checkout's remote to `crosscode-platform`, moves the install's own files to the new paths
-(`backend/.env` → `apps/events/backend/.env`, likewise the frontend `.env`,
-`backend/public/uploads/`, `backend/backups/`, `backend/data/*.json`, and `ecosystem.config.js`
-with its `cwd` paths updated), checks out `events@2.2.0`, builds and reloads. The folder, PM2
-names, nginx config (it only proxies to ports), database and its name stay the same. If anything
-fails it moves the files back and returns to the `hope-events` remote and the version it was on.
-Installs that haven't moved yet keep working with `deploy.sh` on the archived repo.
-
----
-
-## 9. Build order
-
-| Phase | Version | What | Why this order |
-|-------|---------|------|----------------|
-| 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2: schemas, generated JSON Schema, docs, sample payloads, the monorepo set up. **Released 2026-11-04** | Everything else depends on them |
-| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v2 (v1 still accepted), sibling discovery, AI usage per product, **releases per product with requirements** (§5), contracts as a committed file (§2) | Must exist before a second product is sold, and before Events releases come from the monorepo |
-| 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. No feature changes, so a problem is clearly the move | Before more products, so every product is released and deployed the same way from the start |
-| 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses | Independent and useful now; the Accounts migration later carries it over |
-| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events | Small; ready for when the Website exists |
-| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
-| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
-| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |
-| 6 | **Church App 1.0.0** | Foundation (PWA, branding, Accounts), House of Prayer, announcements, devotionals, events (simple + feed) | Starts with shared users and the feed already in place |
-| 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory | After House of Prayer is in use |
-
-Each phase adds help content, audit log entries, tests, a CHANGELOG entry and updates to the
-docs. Branch → merge → tag → push per feature, as before. **A phase isn't done until
-crosscode-site is updated** for it (below), where the phase changes anything the site says.
-
-### Updating crosscode-site
-
-The marketing site (`../crosscode-site`, crosscode.co.za) has to match what's actually shipped.
-At the end of each phase, update it in the same sitting and deploy it (its `DEPLOYMENT.md`):
-
-| Phase | What changes on crosscode-site |
-|-------|--------------------------------|
-| 0 contracts | Nothing |
-| 1 Hub 2.0.0 | Bundle discounts (15% / 25%) and the address add-on (own domain R0 · Cross Code address R10 · domain included R25) in `src/data/pricing.mjs`, worded so it's clear the Website and App are still coming. Legal pages if billing terms change |
-| 1b Events 2.2.0 | Nothing (the move doesn't change what Cross Events does) |
-| 1c Events 2.3.0 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording |
-| 2 Events 2.4.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship |
-| 3 Accounts 1.0.0 | "One sign-in for all your church's products" on the Products page. Accounts isn't sold, so no page or price of its own |
-| 4 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) |
-| 5 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login |
-| 6 App 1.0.0 | **Church App goes on sale:** own page, active-member tiers in `pricing.mjs`, House of Prayer screenshots, the bundle examples from §10 |
-| 7 App 1.x | New modules added to the App page's feature list as each one ships |
-
-Prices change in the Hub's `frontend/src/lib/tiers.ts` in the same phase, so the site and the
-Hub never disagree. Run the site's tests and build before deploying it.
-
-### Release checks (before selling a product)
-
-- Two churches installed from the same tagged release with `crosscode install`, with separate databases, secrets and uploads.
-- `crosscode deploy` updates a church from the previous release, and a failure part-way (e.g. a
-  broken migration) rolls that product back and leaves the others running.
-- Church A's admin can't read or change Church B's data through direct API calls.
-- Stopping one church's install, or the Hub, leaves the others running.
-- A feed source going down: its last events keep showing, the other sources keep working.
-- Signing in once works across all of a church's products; deleting an account reaches every product.
-- Signing in from any page of any product returns to that same page (including through 2FA and a
-  password reset), and a foreign return URL is refused.
-- crosscode-site shows the product as available, with its page, prices and screenshots.
-- The §11 SEO checks pass (Playwright and Lighthouse), for the Website in all four templates.
-- A database backup is restored successfully.
-
----
-
-## 10. Pricing
-
-Aimed at small and mid-sized South African churches: the Website and App start well below Cross
-Events, since they replace things churches often get cheaply or free today (a basic website,
-WhatsApp groups). Prices are rand per month. Decided by Joshua on 2026-11-03.
-When the Website and App go on sale, they go in `crosscode-site/src/data/pricing.mjs` and the Hub's
-`frontend/src/lib/tiers.ts`.
-
-**The same rules as Cross Events apply to every product:** one month free, yearly billing = 10
-months' price, founding churches 35% off for as long as they stay, bundles **15% off** two
-products and **25% off** all three, and the tier is checked once a year at renewal. **Add-ons**
-(address and storage) are not discounted.
-
-### The church's address: three options
-
-One address covers all of a church's products (`www.`, `events.`, `app.`, `accounts.`), so it's
-charged **once per church**, not per product.
-
-| Option | Price | What it means |
-|--------|-------|---------------|
-| **Own domain** | R0 | The church already has a domain (e.g. `hopefamily.co.za`). They, or whoever manages it, add the DNS records we send. We look after the certificates |
-| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own at any time (old addresses redirect for 12 months). Trials use this address for free |
-| **Domain included** | **+R25 / month** | We register a `.co.za` or `.org.za` **in the church's name**, renew it every year and manage the DNS. Other endings (`.com`, `.church`, `.org`) are charged at cost on top. If the church leaves, the domain is transferred to them, free |
-
-### Church Website: one price plus storage
-
-| | Price |
-|--|------:|
-| **Church Website** (5 GB of uploads included) | **R99** |
-| Founding (35% off) | R64 |
-| **Extra storage** add-on | **+R20 / month per extra 5 GB** |
-
-Uploads are photos, documents and sermon notes. Sermon audio and video are linked (YouTube,
-Spotify, SoundCloud…) rather than uploaded, so most churches never need extra storage. Admins see
-how much they've used in the website's settings and get an email at 80%. Storage is counted per
-church and reported to the Hub, which bills the add-on.
-
-### Church App: on active members
-
-Billed on **active members**: accounts that used the App in the last 90 days, reported to the Hub
-as a band (like event income for Cross Events). Visitors browsing without signing in never count.
-
-| Tier | Active members | Price | Founding |
-|------|----------------|------:|---------:|
-| Mustard Seed | Up to 100 | **R99** | R64 |
-| Small Group | 101 – 300 | **R249** | R162 |
-| Congregation | 301 – 750 | R399 | R259 |
-| Gathering | 751 – 2 000 | R649 | R422 |
-| Multitude | 2 001 – 5 000 | R999 | R649 |
-| Network | Over 5 000 | From R1 500 | 35% off |
-
-### What churches would pay (no founding discount)
-
-| Church | Products | Products after bundle | + address | Per month |
-|--------|----------|----------------------:|----------:|----------:|
-| Small, website only | Website | R99 | own domain | **R99** |
-| Small, website only | Website | R99 | Cross Code address | **R109** |
-| Small, website only | Website | R99 | domain included | **R124** |
-| Small, website + app | Website + App (≤100): R198 | R168 (15%) | domain included | **R193** |
-| Small, everything | Events Seed + Website + App (≤100): R548 | R411 (25%) | domain included | **R436** |
-| Mid-sized, everything | Events Grow + Website + App (301–750): R1 348 | R1 011 (25%) | domain included | **R1 036** |
-
-(Rounded to the rand.)
-
----
-
-## 11. SEO (every public site)
-
-Every public site gets search engine optimisation at least as good as Cross Events has today:
-the **Church Website**, **Cross Events**, the public parts of the **Church App**, and the
-marketing site **crosscode.co.za**. A church should be found when someone searches "church near
-me", its name, or an event it's running.
-
-### The baseline (what Cross Events does now, for every product)
-
-- **Server-rendered HTML** with a unique `<title>` and meta description on every page.
-- **Canonical URL** on every page (tracking tags such as `?src=` dropped).
-- **Open Graph and Twitter cards** with an image on every page. Pages without their own image
-  get a share image generated from the church's logo and colours.
-- **`sitemap.xml`** generated from published content and refreshed hourly, and **`robots.txt`**
-  that points to it and keeps admin, sign-in and personal pages out.
-- **schema.org JSON-LD** (e.g. `Event` on event pages, as `frontend/src/lib/eventSchema.ts` does,
-  checked with Google's Rich Results Test).
-- Readable slugs, with **301 redirects** when a slug changes; real 404 status for missing pages;
-  `lang="en-ZA"`.
-- **Fast and accessible:** responsive images with required alt text, good Core Web Vitals on a
-  phone (LCP under 2.5 s, CLS under 0.1), WCAG 2.2 AA.
-
-The JSON-LD builders and meta helpers live in a shared `packages/seo` in the platform monorepo,
-built on `@crosscode/contracts`, so Events, the Website and the App produce the same schema.org
-data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events moves its
-`eventSchema.ts` onto it in 2.4.0.
-
-### Per product
-
-| Product | SEO |
-|---------|-----|
-| **Church Website** | JSON-LD `Church` (name, logo, address, geo, phone, service times, social links) on the home and contact pages, so the church shows up in local search and maps; `Event` for its events; `VideoObject` / `PodcastEpisode` for messages; `BreadcrumbList`. Admin: per-page title and description (with a Google-style snippet preview), warnings for a missing description, alt text or a too-long title, and a field for Google Search Console / Bing verification. Setup checklist links to setting up a Google Business Profile. All four templates produce the same markup and pass the same checks |
-| **Imported events** | A copy of another product's event (§4) has `<link rel="canonical">` pointing to the **origin's** page, so search engines see one event, not three. Only the origin is in its sitemap |
-| **Cross Events** | Already has the baseline. Gains the shared `packages/seo`, `Organization` / `Church` data from the church profile, and the canonical rule for imported events |
-| **Church App** | Public content (events, devotionals, sermons, announcements marked public) gets the baseline. Everything signed in, prayer and care is `noindex` and kept out of the sitemap. **Prayer requests are never indexable** |
-| **Accounts** | `noindex` everywhere, blocked in `robots.txt`: sign-in pages should never appear in search |
-| **Cross Code Hub** | `noindex` everywhere |
-| **crosscode.co.za** | Already has canonical URLs, Open Graph, `Organization` / `WebPage` JSON-LD, sitemap and robots. Adds `SoftwareApplication` JSON-LD with prices (`Offer`) on each product page, `FAQPage` on the FAQs, a page per Website template, and Search Console / Bing set up and checked after each site update (§9, "Updating crosscode-site") |
-
-### Moving addresses
-
-When a church moves from the Cross Code address to its own domain (§10), every old URL
-**301-redirects** to the same page on the new domain for 12 months, so it keeps its search
-ranking.
-
-### Checks (in every product's tests)
-
-- Playwright: every public page has a title, description, canonical, `og:image`, exactly one
-  `<h1>`, and JSON-LD that parses; the sitemap lists the published pages and nothing private;
-  `robots.txt` blocks admin and sign-in; `noindex` pages really are `noindex`.
-- Lighthouse (mobile) on a demo church's home, event and message pages, in every template:
-  SEO 100, accessibility 95+, performance 90+.
-
----
-
-## Decisions (2026-11-03)
-
-| # | Question | Decision |
-|---|----------|----------|
-| 1 | Separate infrastructure | **Yes:** one install and database per product per church, no shared databases, Hub not on the runtime path |
-| 2 | Shared users | **A separate Accounts service per church** (OpenID Connect), used by every product. Roles stay per product |
-| 3 | Docker | **No.** PM2 and nginx, like Cross Events |
-| 4 | Simple events in the Website and App | **Yes.** Only Cross Events takes registrations and payments. (The app spec's "no event creation in the App" is overruled) |
-| 5 | Event sync | Any direction, chosen per install ("Publish my events", "Show events from"). One shared format, `crosscode.event/1`. Only originated events are published |
-| 6 | Domains | `www.`, `events.`, `app.` (and `accounts.`) on the church's own domain |
-| 7 | Hub | Becomes **Cross Code Hub**: every product's licences, stats, AI and billing in one place, still read-only toward installs |
-| 8 | Stack | Next.js + Express + Prisma + PostgreSQL + pg-boss, as Cross Events (not the specs' React + Vite, Redis + BullMQ, Socket.IO) |
-| 9 | Pricing | Income bands per product, bundles 15% (two) / 25% (three); every App module for every church (not the website spec's Starter / Growth / Pro tiers) |
-| 10 | Hub provisioning | Scripts Joshua runs; the Hub records installs but never deploys or rolls back (not the specs' automated provisioning) |
-| 11 | Installs per product | **One install of each product per customer**; the Hub refuses a second licence for the same product |
-| 12 | House of Prayer defaults | 1-hour slots, book up to 12 months ahead, recurring bookings for up to 12 months from the day of booking, no cancelling within 8 hours of the slot |
-| 13 | App notifications | **Email and WhatsApp only.** No push notifications |
-| 14 | Accounts visibility | Hidden from members (branded as the church's sign-in). Only admins and the account holder see account pages |
-| 15 | 2FA | Add an **authenticator app** (TOTP, with recovery codes) next to email and WhatsApp: in Cross Events 2.3.0 first, then in Accounts |
-| 16 | Pricing | Website **R99** with 5 GB, extra storage as an add-on in steps. App **R99** (up to 100 members), then **R249**. Address once per church: own domain R0, **Cross Code address R10**, **domain included R25**. Extra storage R20 per 5 GB; App tiers above 300 members R399 / R649 / R999 / from R1 500. Add-ons aren't bundle-discounted (§10) |
-| 17 | Sign-in return | Signing in through `accounts.church.co.za` always returns to the product and page the person came from (through 2FA, reset, sign-up and notice steps), with exact-match redirect URIs only (§3) |
-| 18 | Marketing site | crosscode-site is updated at the end of every phase that changes what's on sale or what a product does (§9) |
-| 19 | Website templates | **Four templates** (Heritage, Bold, Community, Clean), each with its own layout and design. Colours and logo come from the church; content fills the chosen template; switching never loses content (§6) |
-| 20 | SEO | Every public site (Website, Events, App's public pages, crosscode.co.za) gets at least Cross Events' SEO, through a shared `packages/seo`; Accounts and the Hub are `noindex` (§11) |
-
-**Added 2026-11-04**
-
-| # | Question | Decision |
-|---|----------|----------|
-| 21 | Repos | **Cross Events moves into `crosscode-platform`** (`apps/events`, Events 2.2.0, history kept); `hope-events` is archived. The Hub stays in its own repo (own server, never installed for a church) |
-| 22 | Contracts for the Hub | A packed release **committed to the Hub's repo** (`file:vendor/…`), not Gitea's package registry, so no deploy depends on a registry or a token (§2) |
-| 23 | Deploying | **One `crosscode` script** for every product: `crosscode deploy <church> [events] [website] [app]` always updates Accounts and then the products named, in a fixed order, each rolled back on its own if it fails. Still git checkouts of tags, still run by Joshua; the Hub never deploys (§8) |
-| 24 | Product requirements | A release can require a minimum version of a sibling (`— requires accounts 1.2.0` in `WHATS-NEW.md`). The Hub **disables Request update** until it's met, and the script refuses to deploy without it (§5, §8) |
-
-## Still open
-
-Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
-Website and App move from "coming later" to their own pages and prices when they ship.
+The roadmap for every Cross Code product (Accounts, Church Website, Church App, Cross Events, Cross Code Hub) moved on 2026-11-05 to the platform monorepo, since it covers every product:
+**`joshua/crosscode-platform` → [`docs/ROADMAP-v3.md`](https://c-git.crosscode.co.za/joshua/crosscode-platform/src/branch/main/docs/ROADMAP-v3.md)** (locally `../crosscode-platform/docs/ROADMAP-v3.md`).

docs/hub-protocol.md

@@ -1,290 +1,4 @@
-# Hub protocol (version 1)
+# Hub protocol (versions 1 and 2) — moved
 
-The contract between a **Cross Events install** (the church's site) and the **Cross Events
-Hub** (`events-hub.crosscode.co.za`). A copy of this file lives in both repositories
-(`joshua/hope-events` → `docs/hub-protocol.md`, `joshua/events-hub` → `docs/hub-protocol.md`);
-change both together.
-
-Principles:
-
-- **Install → Hub only.** The install always starts the conversation; the Hub never calls
-  into an install. Works behind firewalls, and the Hub has no access to church data.
-- **No personal information** is ever sent — counts, versions and health only. Income is
-  sent as a range, never an amount.
-- **A Hub outage never switches a church off.** Licences are signed tokens the install
-  verifies offline with the Hub's public key.
-- Every request carries `protocolVersion`. The Hub accepts the current and the previous
-  version, so installs waiting to update keep working.
-
-All bodies are JSON (`Content-Type: application/json`). Times are ISO 8601 UTC strings.
-Errors are `{ "message": "...", "code": "..." }` with a 4xx/5xx status.
-
----
-
-## 1. Public key
-
-```
-GET /api/public-key
-→ 200 { "protocolVersions": [1], "keyId": "k1", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\n…" }
-```
-
-Installs ship with the Hub's public key built in (and may refresh it from here). The private
-key exists only on the Hub server.
-
-## 2. Register an install
-
-Sent once, at the end of `/setup` (licence step) or from Site settings → "Connect to Hub".
-
-```
-POST /api/installs/register
-{
-  "protocolVersion": 1,
-  "licenceKey": "CEH-7K2M-9QXA-P4RT-WD8C",
-  "install": {
-    "name": "Hope Family Church",
-    "url": "https://events.hopefamily.co.za",
-    "adminContact": { "name": "Jane Admin", "email": "jane@hopefamily.co.za" },
-    "version": "1.41.0",
-    "timezone": "Africa/Johannesburg",
-    "server": { "node": "20.18.0", "postgres": "16.4", "os": "linux 6.8" },
-    "features": { "whatsapp": true, "paymentProviders": ["yoco", "payfast"], "campuses": false }
-  }
-}
-→ 201 {
-  "installId": "inst_…",
-  "installSecret": "…",            // shown once; the install stores it encrypted
-  "licence": "<licence token>",
-  "heartbeatIntervalMinutes": 15,
-  "latestVersion": "1.41.0",
-  "releases": [ … ],               // as in the heartbeat reply (§3); Hub 1.4.0+
-  "notices": [ … ]
-}
-```
-
-- `404 LICENCE_NOT_FOUND` — unknown key. `403 LICENCE_REVOKED` — revoked licences can't register.
-- One licence = one install. Registering again **from the same URL** re-registers (new
-  secret, same `installId`). From a different URL → `409 LICENCE_IN_USE` until Joshua releases
-  the licence in the Hub (e.g. after a move to a new domain).
-- The `adminContact` is the one piece of personal information: a work contact for the
-  church's admin, so Joshua can reach them. It is not used for anything else.
-- Rate-limited per IP.
-
-## 3. Heartbeat
-
-Every `heartbeatIntervalMinutes` (15) from the install's job queue.
-
-```
-POST /api/installs/heartbeat
-X-Hub-Install:   inst_…
-X-Hub-Timestamp: 2026-10-24T08:15:00.000Z
-X-Hub-Signature: <hex HMAC-SHA256(installSecret, timestamp + "." + rawBody)>
-{
-  "protocolVersion": 1,
-  "version": "1.41.0",
-  "health": {
-    "uptimeSeconds": 86400,
-    "db": true,
-    "jobs": { "mode": "queue", "failedLast24h": 0 },
-    "lastBackupAt": "2026-10-24T00:00:12.000Z",       // null if none
-    "disk": { "freeBytes": 21474836480, "totalBytes": 53687091200 },  // null if unknown
-    "errorsLast24h": 0,                                // null if not tracked
-    "pendingMigrations": 0
-  },
-  "stats": {
-    "users": 412,
-    "events": { "active": 3, "upcoming": 5, "total": 61 },
-    "registrations": { "last30d": 88, "total": 2310 },
-    "tickets": { "last30d": 140, "total": 3901 },
-    "checkIns": { "last30d": 96 },
-    "messages": { "email30d": 610, "whatsapp30d": 233 },
-    "paymentProviders": ["yoco", "payfast"],
-    "campuses": false,                                 // Site settings → Campuses on/off
-    "campusCount": 0,                                  // active campuses (0 while off; Cross Events 1.43.0+)
-    "income": { "last30d": "R5 001–R20 000", "allTime": "R150 001–R250 000",
-                "eventIncome12m": "R100 001–R150 000" }   // eventIncome12m: Cross Events 2.0.2+
-  }
-}
-→ 200 {
-  "licence": "<fresh licence token>",
-  "latestVersion": "1.42.0",
-  "releases": [                                        // Hub 1.4.0+: newer than the version sent, newest first, at most 20
-    { "version": "1.42.0", "releasedAt": "2026-10-27T10:00:00.000Z", "urgent": false, "notes": "- Event series\n- Fixed: …" }
-  ],
-  "notices": [                                         // Hub 1.4.0+: the provider's banners for this install
-    { "id": "…", "level": "maintenance", "title": "Planned maintenance", "message": "…",
-      "startsAt": "2026-11-01T16:00:00.000Z", "endsAt": "2026-11-01T16:30:00.000Z", "updatedAt": "…" }
-  ],
-  "serverTime": "…"
-}
-```
-
-- **`releases`** — what's new in each version, so the church can decide whether to ask for the
-  update. The Hub takes the versions from the Cross Events repository's `v*` tags and the notes from
-  its `WHATS-NEW.md`. `notes` is plain text; lines starting with `- ` are
-  a list. `urgent` marks security or serious bug fixes: the install shows those in red and doesn't let
-  admins put them off. The highest release is `latestVersion`.
-- **`notices`** — banners Joshua posts on the Hub's Notices page (`level`: `info`, `maintenance` or
-  `warning`). Sent until `endsAt`, including ones that haven't started, so the install shows each one
-  from `startsAt` without waiting for a heartbeat. The install shows them to site admins and
-  supervisors. Notices can also be emailed; that happens on the Hub, not through the install.
-- A Hub older than 1.4.0 sends neither field; the install then shows no notes and no notices.
-- The signature covers the exact bytes sent. Requests more than **5 minutes** off the Hub's
-  clock are refused (`401 STALE_REQUEST`); a bad signature is `401 BAD_SIGNATURE`; an unknown or
-  released install is `404 INSTALL_NOT_FOUND` (the install should show "Reconnect to Hub").
-- **Income bands** (worked out on the install; the amount never leaves it): `R0–R1 000`,
-  `R1 001–R5 000`, `R5 001–R20 000`, `R20 001–R50 000`, `R50 001–R100 000`,
-  `R100 001–R150 000`, `R150 001–R250 000`, `R250 001–R400 000`, `R400 001–R700 000`,
-  `R700 001–R1 000 000`, `R1 000 001–R2 500 000`, `R2 500 001–R5 000 000`,
-  `R5 000 001–R10 000 000`, `over R10 000 000`. Before Cross Events 2.0.2 the bands stopped at
-  `over R100 000`, and donations applied to a registration were counted twice.
-- **`eventIncome12m`** (Cross Events 2.0.2+) is the band of the last 365 days' event income:
-  payments less refunds, without donations or sponsorships. Cross Code's licence tiers are billed
-  on it, so every tier edge is a band edge. Older installs don't send it.
-- The Hub keeps every heartbeat for 30 days, then one per install per day.
-
-## 3a. Update request
-
-Sent when a site admin presses **Request update** (Site settings → Licence). Installs never update
-themselves and never show the deploy command; the request tells Joshua, who updates the server.
-Signed exactly like the heartbeat.
-
-```
-POST /api/installs/update-request
-X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature   (as in §3)
-{ "protocolVersion": 1, "version": "1.41.2" }
-→ 201 { "requestedAt": "2026-10-27T09:00:00.000Z", "version": "1.42.0", "alreadyRequested": false, "changed": false }
-→ 200 { …, "alreadyRequested": true, "changed": false }    // a request for the latest is already open: not emailed again
-→ 200 { …, "alreadyRequested": true, "changed": true, "previousVersion": "1.42.0" }
-                                         // the open request was for an older version: it now asks for the latest
-```
-
-- The Hub opens an `update_requested` alert on the install (shown under Alerts) and emails the
-  alert address once. It is resolved when a heartbeat reports a newer version than before.
-- **Changing a request (Hub 1.5.0):** when a request is open for a version that has since been
-  overtaken, asking again moves it on to the latest version — the alert says "latest is 1.47.3
-  (changed from 1.47.0)" and the alert address is emailed once about the change. `version` is
-  always the version now asked for. A Hub before 1.5.0 doesn't send `changed`; installs then
-  withdraw the request and ask again (two emails, same result).
-- `409 UP_TO_DATE` — the install already runs the Hub's latest version (or none is set).
-- Errors as in §3 (`INSTALL_NOT_FOUND`, `STALE_REQUEST`, `BAD_SIGNATURE`). Rate-limited (10 an
-  hour per IP). A Hub older than this section answers `404 NOT_FOUND`.
-- No personal information: not who pressed the button (the Hub already has the admin contact).
-
-### Withdrawing it
-
-Sent when a site admin presses **Withdraw request**. Signed like the heartbeat.
-
-```
-POST /api/installs/update-request/cancel
-X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature   (as in §3)
-{ "protocolVersion": 1 }
-→ 200 { "cancelled": true }     // the open request was resolved, and Joshua is emailed
-→ 200 { "cancelled": false }    // there was no open request
-```
-
-- The Hub resolves the `update_requested` alert and records `update_request_withdrawn` in the install's
-  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
-Ed25519 signature of the ASCII string `hel1.<payload>`.
-
-```json
-{
-  "v": 1,
-  "licenceId": "lic_…",
-  "installId": "inst_…",
-  "customer": "Hope Family Church",
-  "plan": "standard",
-  "status": "active",                       // active | suspended | revoked
-  "licenceExpiresAt": "2027-10-31T21:59:59.000Z",   // null = no end date
-  "graceDays": 14,
-  "issuedAt": "2026-10-24T08:15:00.000Z",
-  "validUntil": "2026-11-23T08:15:00.000Z",          // issuedAt + 30 days
-  "limits": { "aiMonthlyCapCents": 0 }      // the AI cap (§3b); 0 = AI off
-}
-```
-
-### What the install does with it
-
-The install keeps the newest valid token (signature checks out, `installId` matches) and works
-out its state:
-
-| State | When | What happens |
-|-------|------|--------------|
-| **active** | `status` is active and now is before `min(licenceExpiresAt, validUntil)` | Everything works |
-| **grace** | after that date, for up to `graceDays` | Everything works; **only site admins** see a banner "Licence needs renewing — X days left" |
-| **suspended** | `status` is suspended, or grace has run out | Read-only: events can't be created or edited; no new registrations or payments. Tickets still scan; admins can view and export all data; privacy requests still work |
-| **revoked** | `status` is revoked | Same as suspended, with a permanent banner |
-| **unlicensed** | never connected, or the Hub answered `INSTALL_NOT_FOUND` (the install drops its token) | Same as suspended (events can't be created or edited either); admins see "Connect to Hub" |
-
-`validUntil` is refreshed by every heartbeat, so a Hub outage only matters after 30 days (then
-grace starts). Blocking the Hub can't keep a suspended licence active for more than 30 days.
-
-## 5. Versioning
-
-- `protocolVersion` goes up only for changes an older install can't handle. Adding optional
-  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`.
+The install ↔ Hub protocol, for every product (a copy is also in `joshua/events-hub`, `docs/hub-protocol.md`) moved on 2026-11-05 to the platform monorepo, since it covers every product:
+**`joshua/crosscode-platform` → [`docs/hub-protocol.md`](https://c-git.crosscode.co.za/joshua/crosscode-platform/src/branch/main/docs/hub-protocol.md)** (locally `../crosscode-platform/docs/hub-protocol.md`).