docs: handover after the 2.3.0 / agent 1.0 / Hub 2.1 release

Root HANDOVER: phases 1b–1d released and VM tested, the nine bugs the VM
test found, rollout next. Events HANDOVER: 2.3.0, where two-factor and the
Hub-install pieces live. AGENT-1.0-PLAN and EVENTS-2.2-PLAN: tested and
released, the VM changes; ROADMAP §9 marked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ls1vMdni7EfytGYqQTprME
This commit is contained in:
2026-11-17 22:41:10 +02:00
co-authored by Claude Opus 5.5
parent d985a4c853
commit a286f8abce
5 changed files with 107 additions and 40 deletions
+30 -7
View File
@@ -1,6 +1,8 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-05, after **2.1.1** (deployed). **This file covers Cross Events only**
Last updated: 2026-11-17, after **2.3.0** (released, tested on a VM, not deployed yet; servers
still run 2.1.1 until they're adopted, see the root [ROLLOUT-1.0.md](../../../docs/ROLLOUT-1.0.md)).
**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 are in the monorepo's root `docs/`** →
[ROADMAP-v3.md](../../../docs/ROADMAP-v3.md),
@@ -95,13 +97,13 @@ encrypted settings unreadable or break existing installs.
## Next up
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**
phase stands", "Next up"). **2.2.0** (the move into the monorepo) and **2.3.0** (authenticator
app 2FA and recovery codes, plus what installs from the Hub need) are released (2026-11-17).
Next for Cross Events is **rolling them out** (each install adopted from the Hub), then **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`.
- **Deploying:** installs still on 2.1.1 move with `adopt` (Hub → Servers → Installs → Link
existing → Move onto the monorepo, or `crosscode adopt` by hand), never `deploy`. After that,
updates are planned on the Hub (Updates), or `crosscode deploy <church> events` by hand.
- **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
@@ -119,6 +121,27 @@ encrypted settings unreadable or break existing installs.
Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026-10-28).
## Where two-factor lives (2.3.0)
- `backend/src/utils/twoFactor.js`: every method (email, WhatsApp, `authenticator`), challenges,
recovery codes (10 per set, stored as HMACs, single use). `backend/src/utils/totp.js`: RFC 6238
with a last-step check (`User.totpLastStep`), so a code can't be used twice.
- **`totpSecret` never goes to the browser:** `LOGIN_USER_SELECT` doesn't include it (that selection
is sent back on sign-in), so `createChallenge` reads it from the database itself.
- Frontend: the profile page draws the QR code in the browser (a dynamic `import("qrcode")`);
`LoginForm.tsx` has "Use a recovery code". Tests: `tests/twoFactorAuthenticator.test.js`.
## Where the Hub-install pieces live (2.3.0)
- `env.template.json` (copied to `scripts/products/events.env.template.json` at the monorepo root;
keep them the same): every `.env` variable with its layer (`server`, `defaults`, `install`,
`generated`). The Hub has its own copy (`events-hub/backend/src/utils/envTemplates/events.json`).
A new variable goes in all three.
- `backend/scripts/export-church.ts` (`src/services/churchExport.ts`): the church's data as
`crosscode.church-export/1`, for `crosscode export` and uninstalls. No internal ids.
- `backend/src/hub/client.js` `connectFromEnv()`: a site the Hub installed registers by itself on
first start from `HUB_LICENCE_KEY`.
## Working on this repo
- **Release routine:** branch `feat/<name>` → commit → bump with