From 20d53b79f15aab55e891ed4d15366fd5616c1737 Mon Sep 17 00:00:00 2001 From: joshua Date: Fri, 30 Oct 2026 09:58:48 +0200 Subject: [PATCH] Docs: 2.0 progress, marketing site plan, AI tested Co-Authored-By: Claude Opus 5.5 --- apps/events/docs/HANDOVER.md | 21 ++++++++--- apps/events/docs/ROADMAP-v2.md | 64 ++++++++++++++++++++++++++++++---- 2 files changed, 74 insertions(+), 11 deletions(-) diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index 1747ae8..0cdc62a 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,6 +1,6 @@ # Handover — where things stand and how to carry on -Last updated: 2026-10-30, after **1.51.17** (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). @@ -79,10 +79,21 @@ encrypted settings unreadable or break existing installs. Hub 1.1.0 is deployed with update requests rolled out, and `scripts/install.sh` has been tried on a test server (both done 2026-10-28). -1. **2.0.0** — AI helpers (§15), v1 removed, a migration guide, and marketing site/docs for - selling. 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. +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, + ``, `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 diff --git a/apps/events/docs/ROADMAP-v2.md b/apps/events/docs/ROADMAP-v2.md index c4720f9..569f998 100644 --- a/apps/events/docs/ROADMAP-v2.md +++ b/apps/events/docs/ROADMAP-v2.md @@ -12,8 +12,19 @@ providers), maintainable (tests, CI, typed backend, versioned API), and with **AI helpers** as the headline feature (§15). **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). **Next: 2.0.0** — AI helpers (§15) and v1 removed. The full -version list is in [HANDOVER.md](./HANDOVER.md) and the [build order](#suggested-build-order) below. +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, ``, `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 @@ -68,8 +79,9 @@ Removed from scope (2026-10-28): Wallet passes (§7) and languages (§10). 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) --- @@ -940,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/`), + `useAiStatus()`, `` / ``, 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/` routes, the buttons on the five + screens, the eval set, and the privacy notice text (a `BUILT_IN_UPDATES` entry). + --- ## 16. AI: later stages @@ -993,6 +1022,25 @@ 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 | @@ -1010,7 +1058,7 @@ income justify the hardware: | 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`. 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, marketing site/docs for selling | The release. AI needs the Hub (phase 6) for the key, metering and caps | +| 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 @@ -1049,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) | @@ -1070,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.