@clubedge/create-clubedge-app 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.45.0
+
+- **Starter v0.29.0** by default (#159). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.29.0) cover:
+  - an update policy for apps installed on phones: a minimum announced for a date, values per platform, and APIs that answer apps below the minimum `426 update_required`;
+  - a new design for the native app (`--mobile expo`);
+  - splash screens that are never cropped or stretched.
+- **`package.json` merges by key** (#158) when `add`, `remove`, or `upgrade` merges the Starter's changes into your project:
+  - A key only one side changed takes that side's value, and objects merge key by key, so your dependencies and the Starter's no longer collide line by line.
+  - A key both sides changed differently is a conflict, with the usual markers around that key's lines only.
+  - Your key order and indentation are kept. A file that doesn't parse, such as one with markers left from an earlier merge, merges by line as before.
+- **The Starter pin** keeps the release a change came with in notes such as "since CLI 0.44.0, with Starter v0.28.0", which moving the pin to v0.29.0 had changed.
+- CI uses astral-sh/setup-uv 10.3.2 (#154).
+
 ## 0.44.0
 
 - **The native app with Expo**: default to Starter `v0.28.0` (#151). `--mobile expo` adds `apps/mobile`, an Android and iOS app with its own native screens, which calls the project's API (#147):

package/README.md

@@ -241,7 +241,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.28.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.29.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -260,13 +260,14 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.28.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.29.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
 
 - Files you never changed are updated, added, or deleted.
 - Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve. The Starter's whole new version of each such file is saved in `.clubedge/incoming/` to compare with yours (`git diff --no-index <file> .clubedge/incoming/<file>`); Git ignores that folder, so delete it when you are done.
+- `package.json` files merge by key, not by line: a script, dependency, or override you added next to the Starter's keeps both, and markers wrap only a key you both changed to different values, such as the same dependency's range. The file keeps your key order, indentation, and line endings.
 - Your own files are never touched.
 - Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local`, `apps/shell/.env.local`, or `apps/mobile/.env.local` when the project has them) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
 - `pnpm-lock.yaml` is replaced if you never changed your dependencies; otherwise `pnpm install` reconciles it.
@@ -399,27 +400,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.44.0
+create-clubedge-app v0.45.0
         |
         v
-Clubedge Starter v0.28.0
-commit 090b05a9561f6eb7bb3bc0ab0b15ada7702aef8c
+Clubedge Starter v0.29.0
+commit 29350332db4bc44acc1e7b989c04825ff4c0f7b7
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.44.0` | `clubedge-starter@v0.28.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.45.0` | `clubedge-starter@v0.29.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.28.0` tag is expected to resolve to commit
-`090b05a9561f6eb7bb3bc0ab0b15ada7702aef8c`. The CLI verifies this before
+The `v0.29.0` tag is expected to resolve to commit
+`29350332db4bc44acc1e7b989c04825ff4c0f7b7`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.28.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.29.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -474,7 +475,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.28.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.29.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -529,6 +530,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.42.0 | v0.27.0 | Starter v0.27.0: mobile apps with Capacitor (`--shell capacitor`, template schema 5); client addresses per platform; Docker Compose behind Caddy, with images on GHCR |
 | 0.43.0 | v0.27.1 | Upgrades keep each app's own version; add, remove, and upgrade that change nothing skip the Starter download |
 | 0.44.0 | v0.28.0 | Starter v0.28.0: the native app with Expo (`--mobile expo`, template schema 6); projects without a website (`--framework none`), with template rules; audit exceptions per stack |
+| 0.45.0 | v0.29.0 | Starter v0.29.0: an update policy for installed apps, a new design for the native app, and clean splash screens; `package.json` merged by key |
 
 ## Community
 

package/dist/core/merge.js

@@ -1,7 +1,8 @@
 // Three-way merge between what the CLI generated (base), what it would generate now (target),
 // and the project as it is (current). Changes from base to target are applied to the project
 // without losing the project's own edits. Pure: callers read and write the files.
-import { diff3Merge } from "node-diff3";
+import { diff3Merge, diffComm } from "node-diff3";
+import { mergePackageJson } from "./package-json-merge.js";
 export const CONFLICT_LABELS = { yours: "yours", theirs: "clubedge" };
 /**
  * Where the Starter's versions of files left to resolve are saved, next to the project's own,
@@ -35,28 +36,41 @@ export function sameContent(a, b) {
         return a.equals(b);
     return normalize(a) === normalize(b);
 }
-/** Merges base -> target into current. Resolves null for binary files, which cannot be merged. */
-export function mergeText(current, base, target) {
-    if (isBinary(current) || isBinary(base) || isBinary(target))
-        return null;
-    const split = (content) => normalize(content).split("\n");
-    const regions = diff3Merge(split(current), split(base), split(target), { excludeFalseConflicts: true });
+/** The merged text, with conflict markers around each region where the two sides differ. */
+function withMarkers(regions) {
     const lines = [];
     let conflict = false;
     for (const region of regions) {
-        if (region.ok) {
+        if ("ok" in region) {
             lines.push(...region.ok);
             continue;
         }
-        if (!region.conflict)
-            continue;
         conflict = true;
-        lines.push(`<<<<<<< ${CONFLICT_LABELS.yours}`, ...region.conflict.a, "=======", ...region.conflict.b, `>>>>>>> ${CONFLICT_LABELS.theirs}`);
+        lines.push(`<<<<<<< ${CONFLICT_LABELS.yours}`, ...region.yours, "=======", ...region.theirs, `>>>>>>> ${CONFLICT_LABELS.theirs}`);
     }
     return { text: lines.join("\n"), conflict };
 }
+/** Merges base -> target into current. Resolves null for binary files, which cannot be merged. */
+export function mergeText(current, base, target) {
+    if (isBinary(current) || isBinary(base) || isBinary(target))
+        return null;
+    const split = (content) => normalize(content).split("\n");
+    const regions = diff3Merge(split(current), split(base), split(target), { excludeFalseConflicts: true });
+    return withMarkers(regions.flatMap((region) => region.ok ? [{ ok: region.ok }] : region.conflict ? [{ yours: region.conflict.a, theirs: region.conflict.b }] : []));
+}
+/**
+ * Merges a package.json by key (see package-json-merge.ts), so edits to different keys never
+ * conflict, and markers wrap only the lines of a key both sides changed differently. Resolves
+ * null when a side does not parse, for mergeText to merge it by line.
+ */
+export function mergePackageJsonText(current, base, target) {
+    const merged = mergePackageJson(normalize(current), normalize(base), normalize(target));
+    if (!merged)
+        return null;
+    return withMarkers(diffComm(merged.yours.split("\n"), merged.theirs.split("\n")).map((region) => region.common !== undefined ? { ok: region.common } : { yours: region.buffer1, theirs: region.buffer2 }));
+}
 function merged(path, current, base, target, binaryReason) {
-    const result = mergeText(current, base, target);
+    const result = (/(^|\/)package\.json$/.test(path) ? mergePackageJsonText(current, base, target) : null) ?? mergeText(current, base, target);
     if (!result)
         return { path, kind: "keep", reason: binaryReason, incoming: target };
     const content = withLineEndings(result.text, current);

package/dist/core/package-json-merge.js

@@ -0,0 +1,106 @@
+// package.json files merge by key instead of by line (#142), so edits to different keys never
+// conflict: a script the project adds after the Starter's, or an override next to one the
+// Starter adds. A key both sides changed to different values is a conflict. The merged file is
+// written twice, with your value for each such key and with the Starter's, and merge.ts puts
+// conflict markers around the lines where the two differ, which are that key's.
+/** A key both sides changed to different values; undefined is a side that removed it. */
+class Conflict {
+    yours;
+    theirs;
+    constructor(yours, theirs) {
+        this.yours = yours;
+        this.theirs = theirs;
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Conflict);
+const own = (object, key) => (Object.hasOwn(object, key) ? object[key] : undefined);
+/** Sets a key as data, so a key named __proto__ cannot change the object's prototype. */
+function set(object, key, value) {
+    Object.defineProperty(object, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/** Equal JSON values; objects regardless of their key order. */
+function same(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((item, i) => same(item, b[i]));
+    if (isObject(a) && isObject(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]));
+    }
+    return false;
+}
+/**
+ * One key's value: whoever changed it, or a conflict when both did, differently. Objects both
+ * changed merge key by key; arrays and scalars are single values. Undefined is a removed key.
+ */
+function merge(base, yours, theirs) {
+    if (same(yours, theirs) || same(base, theirs))
+        return yours;
+    if (same(base, yours))
+        return theirs;
+    if (isObject(yours) && isObject(theirs))
+        return mergeObjects(isObject(base) ? base : {}, yours, theirs);
+    return new Conflict(yours, theirs);
+}
+/**
+ * Your keys in your order; a key only the Starter has goes after the key it follows in the
+ * Starter's file, or first. At the root, `clubedge` (the provenance) is always the Starter's.
+ */
+function mergeObjects(base, yours, theirs, root = false) {
+    const order = Object.keys(yours);
+    let previous;
+    for (const key of Object.keys(theirs)) {
+        if (!order.includes(key))
+            order.splice(previous === undefined ? 0 : order.indexOf(previous) + 1, 0, key);
+        previous = key;
+    }
+    const result = {};
+    for (const key of order) {
+        const value = root && key === "clubedge" ? own(theirs, key) : merge(own(base, key), own(yours, key), own(theirs, key));
+        if (value !== undefined)
+            set(result, key, value);
+    }
+    return result;
+}
+/** The merged value with one side's value for each conflict. */
+function resolve(value, side) {
+    if (value instanceof Conflict)
+        return value[side];
+    if (!isObject(value))
+        return value;
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        const resolved = resolve(item, side);
+        if (resolved !== undefined)
+            set(result, key, resolved);
+    }
+    return result;
+}
+/**
+ * The file's indentation, as npm reads it: the whitespace before the first key, after the
+ * opening brace's line. A file on one line has none, and stays on one line.
+ */
+function indentation(text) {
+    return /^\s*\{\n([ \t]*)"/.exec(text)?.[1] ?? "";
+}
+/**
+ * Merges base -> target into current, all LF text. Resolves the result written with your value
+ * for each conflict and with the Starter's (equal when there are none), in your file's
+ * indentation and final newline; null when a side is not a JSON object, to merge by line.
+ */
+export function mergePackageJson(current, base, target) {
+    let parsed;
+    try {
+        parsed = [JSON.parse(current), JSON.parse(base), JSON.parse(target)];
+    }
+    catch {
+        return null;
+    }
+    const [yours, before, theirs] = parsed;
+    if (!isObject(yours) || !isObject(before) || !isObject(theirs))
+        return null;
+    const merged = mergeObjects(before, yours, theirs, true);
+    const write = (side) => JSON.stringify(resolve(merged, side), null, indentation(current)) + (current.endsWith("\n") ? "\n" : "");
+    return { yours: write("yours"), theirs: write("theirs") };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -24,8 +24,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.28.0",
-    "starterCommit": "090b05a9561f6eb7bb3bc0ab0b15ada7702aef8c"
+    "starterRef": "v0.29.0",
+    "starterCommit": "29350332db4bc44acc1e7b989c04825ff4c0f7b7"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
           node-version: 22
           cache: pnpm
       # Apps in other languages run their lint, typecheck, and tests with their own tools.
-      - uses: astral-sh/setup-uv@v10.3.0
+      - uses: astral-sh/setup-uv@v10.3.2
         if: ${{ hashFiles('apps/*/pyproject.toml') != '' }}
       - run: pnpm install --frozen-lockfile
       - run: pnpm format:check

package/template/.railway/railway.ts

@@ -1,7 +1,16 @@
+// clubedge:if framework=next|tanstack-start
 // Railway's configuration for this project, as code: the migrations before each release and the
 // health check. `pnpm clubedge deploy` applies it before each release; elsewhere, run
 // `railway config apply` once. Railway builds the root Dockerfile; set variables with
 // `railway variable set` or the dashboard.
+// clubedge:end
+// clubedge:if framework=vite|none
+// Railway's configuration for this project, as code. Each app runs as its own Railway service,
+// built from its own Dockerfile, such as apps/api/Dockerfile: `pnpm clubedge deploy` writes that
+// configuration here, with the API's migrations before each release and the health checks, and
+// applies it. Deploy with it: as written, this file describes one service built from a root
+// Dockerfile, which this project doesn't have.
+// clubedge:end
 import { readFileSync } from "node:fs";
 import { defineRailway, project, service } from "railway/iac";
 

package/template/README.md

@@ -38,9 +38,11 @@ Every combination in the CI matrix is generated as a real project and runs its f
 
 To try the mobile app on an Android phone, download [clubedge-demo.apk](https://github.com/Clubedge/clubedge-starter/releases/latest/download/clubedge-demo.apk) from the latest release and open it, allowing installs from unknown sources when Android asks. It is the app's demo build, with sample data that stays on the phone and no server behind it. iPhones install apps only from the App Store or TestFlight, so there is no file for them.
 
+To try the native app, download [clubedge-native-demo.apk](https://github.com/Clubedge/clubedge-starter/releases/latest/download/clubedge-native-demo.apk) the same way. It is the native app of a project without a website, and you sign up and sign in for real against that project's API. The API runs on Render's free plan, so after a quiet spell its first answer takes about a minute. Use a password you don't use elsewhere: the demo's accounts can be deleted at any time.
+
 <!-- In generated projects, the block below supplies the title that create-clubedge-app replaces with the project's name; its comment keeps it hidden here. -->
 <!-- clubedge:end -->
-<!-- clubedge:if framework=next|tanstack-start|none
+<!-- clubedge:if framework=next|tanstack-start|vite|none
 # Clubedge Starter
 <!-- clubedge:end -->
 
@@ -104,7 +106,8 @@ To try the mobile app on an Android phone, download [clubedge-demo.apk](https://
 - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release. <!-- clubedge:only api=none -->
 - Production images for the frontend, served by Node, and for the API, which includes the migrator (`node /app/migrate.mjs`) for running migrations before each release. <!-- clubedge:only api!=none && framework!=none -->
 - A production image for the API, which includes the migrator (`node /app/migrate.mjs`) for running migrations before each release. <!-- clubedge:only framework=none -->
-- A manual deploy workflow for the chosen platform, and a readiness endpoint (`/api/ready`) that checks the database.
+- A manual deploy workflow for the chosen platform, and a readiness endpoint (`/api/ready`) that checks the database. <!-- clubedge:only deploy!=docker -->
+- Deployment with Docker Compose behind Caddy: `pnpm clubedge deploy` writes the Compose file, a Caddyfile, and a workflow that publishes the images to GitHub's container registry with each release. A readiness endpoint (`/api/ready`) checks the database. <!-- clubedge:only deploy=docker -->
 - Deployment to Fly.io with `fly.toml`: migrations run as the release command. <!-- clubedge:only deploy=fly -->
 - Deployment to Railway with `.railway/railway.ts`: migrations run before each release, and `pnpm clubedge deploy` sets up the project. <!-- clubedge:only deploy=railway -->
 - Deployment to Render with a `render.yaml` Blueprint: migrations run before each deploy. <!-- clubedge:only deploy=render -->
@@ -161,7 +164,7 @@ corepack enable
 pnpm install
 ```
 
-<!-- clubedge:if framework!=none -->
+<!-- clubedge:if framework!=none && infra!=neon -->
 
 Copy the example environment file to the web app's local environment file.
 
@@ -178,7 +181,7 @@ cp .env.example apps/web/.env.local
 ```
 
 <!-- clubedge:end -->
-<!-- clubedge:if framework=none -->
+<!-- clubedge:if framework=none && infra!=neon -->
 
 Copy the API's example environment file to its local environment file.
 
@@ -226,8 +229,8 @@ Nothing else to install: `pnpm dev` starts a local PostgreSQL database (PGlite,
 <!-- clubedge:end -->
 <!-- clubedge:if infra=neon -->
 
-Nothing to install: create-clubedge-app created a free [Neon](https://neon.com) database and put its URLs in `apps/web/.env.local`. It lasts 72 hours; claim it into a free Neon account to keep it. Apply the migrations: <!-- clubedge:only framework!=none -->
-Nothing to install: create-clubedge-app created a free [Neon](https://neon.com) database and put its URLs in `apps/api/.env.local`. It lasts 72 hours; claim it into a free Neon account to keep it. Apply the migrations: <!-- clubedge:only framework=none -->
+Nothing to install: create-clubedge-app created a free [Neon](https://neon.com) database and put its URLs in `apps/web/.env.local`. It lasts 72 hours; claim it into a free Neon account to keep it. Apply the migrations: <!-- clubedge:only framework=next|tanstack-start -->
+Nothing to install: create-clubedge-app created a free [Neon](https://neon.com) database and put its URLs in `apps/api/.env.local`. It lasts 72 hours; claim it into a free Neon account to keep it. Apply the migrations: <!-- clubedge:only framework=vite|none -->
 
 ```sh
 pnpm db:migrate
@@ -524,15 +527,21 @@ Shared components are generated under `packages/ui/src/components` and can be im
 
 Each phase ends with a Starter release and a create-clubedge-app release pinned to it. The full plan is in [ROADMAP.md](ROADMAP.md).
 
-| Release          | Theme                                                                                    |
-| ---------------- | ---------------------------------------------------------------------------------------- |
-| v0.5.0 to v0.8.0 | Optional modules, local services with and without Docker, `add`, `remove`, and `upgrade` |
-| v0.9.0           | Email, password reset, and email verification                                            |
-| v0.10.0          | Deployment to Docker hosts, Fly.io, Railway, Render, Vercel, and Netlify                 |
-| v0.11.0          | Payments with Stripe                                                                     |
-| v0.12.0          | Background jobs with pg-boss                                                             |
-| v0.13.0          | Observability with OpenTelemetry or Sentry                                               |
-| next             | Browser error reporting, Sentry source maps, and auth emails through the job queue       |
+| Release            | Theme                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------- |
+| v0.5.0 to v0.8.0   | Optional modules, local services with and without Docker, `add`, `remove`, and `upgrade`       |
+| v0.9.0             | Email, password reset, and email verification                                                  |
+| v0.10.0            | Deployment to Docker hosts, Fly.io, Railway, Render, Vercel, and Netlify                       |
+| v0.11.0            | Payments with Stripe                                                                           |
+| v0.12.0            | Background jobs with pg-boss                                                                   |
+| v0.13.0            | Observability with OpenTelemetry or Sentry                                                     |
+| v0.14.0 to v0.15.0 | Account settings, browser error reporting, and the docs-style dashboard                        |
+| v0.16.0 to v0.19.0 | Upgrades as pull requests, Railway configuration as code, production variable checks, and Neon |
+| v0.20.0 to v0.21.0 | Pluggable jobs (BullMQ, Inngest) and auth (Firebase, Appwrite), each with a conformance suite  |
+| v0.22.0 to v0.26.0 | React + Vite with a separate Hono or FastAPI API, and every module on both                     |
+| v0.27.0            | Mobile apps with Capacitor                                                                     |
+| v0.28.0            | The native app with Expo, and projects without a website                                       |
+| next               | Proposed: organizations and teams, shipping the native app to stores, and an admin area        |
 
 ## Community
 

package/template/SETUP.md

@@ -17,7 +17,7 @@ If pnpm reports that it ignored a package build script needed by your environmen
 
 ## Configure the local environment
 
-<!-- clubedge:if framework!=none -->
+<!-- clubedge:if framework!=none && infra!=neon -->
 
 Copy `.env.example` to `apps/web/.env.local`.
 
@@ -34,7 +34,7 @@ cp .env.example apps/web/.env.local
 ```
 
 <!-- clubedge:end -->
-<!-- clubedge:if framework=none -->
+<!-- clubedge:if framework=none && infra!=neon -->
 
 Copy `apps/api/.env.example` to `apps/api/.env.local`.
 
@@ -52,6 +52,9 @@ cp apps/api/.env.example apps/api/.env.local
 
 <!-- clubedge:end -->
 
+create-clubedge-app created `apps/web/.env.local` from `.env.example`, with the URLs of the Neon database it created: keep that file, since copying the example over it would remove them. <!-- clubedge:only infra=neon && framework=next|tanstack-start -->
+create-clubedge-app created the local environment files from their examples, and wrote the URLs of the Neon database it created into `apps/api/.env.local`: keep that file, since copying the example over it would remove them. <!-- clubedge:only infra=neon && framework=vite|none -->
+
 The example file points at the local services described in [Local services](#local-services) and leaves provider keys blank, so the app builds and starts before anything is configured. <!-- clubedge:only infra!=none -->
 The example file leaves provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`. <!-- clubedge:only infra=none -->
 
@@ -65,7 +68,8 @@ The variables are:
 - `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=tanstack-start|none && auth=supabase -->
 - `BETTER_AUTH_SECRET` (for sign-in): see [Better Auth](#better-auth). <!-- clubedge:only auth=better-auth && framework!=none -->
 - `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` (for sign-in): see [Better Auth](#better-auth). <!-- clubedge:only auth=better-auth && framework=none -->
-- `FIREBASE_PROJECT_ID`, `FIREBASE_API_KEY`, and in production a service account: see [Firebase Authentication](#firebase-authentication). <!-- clubedge:only auth=firebase -->
+- `FIREBASE_PROJECT_ID`, `FIREBASE_API_KEY`, and in production a service account: see [Firebase Authentication](#firebase-authentication). <!-- clubedge:only auth=firebase && api!=fastapi -->
+- `FIREBASE_PROJECT_ID` and `FIREBASE_API_KEY`: see [Firebase Authentication](#firebase-authentication). <!-- clubedge:only auth=firebase && api=fastapi -->
 - `APPWRITE_ENDPOINT`, `APPWRITE_PROJECT_ID`, and `APPWRITE_API_KEY` (for sign-in): see [Appwrite](#appwrite). <!-- clubedge:only auth=appwrite -->
 - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
 - `SMTP_URL` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=smtp -->
@@ -151,8 +155,10 @@ These emails are sent by the `send-email` [background job](#background-jobs), so
 
 ## Firebase Authentication
 
-[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Password reset and email confirmation links are generated by Firebase and sent through the [email module](#email), so they open the app's own pages and need no setup in the Firebase console. <!-- clubedge:only email!=none && framework!=none -->
-[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Without the email module there is no password reset. <!-- clubedge:only email=none && framework!=none -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Password reset and email confirmation links are generated by Firebase and sent through the [email module](#email), so they open the app's own pages and need no setup in the Firebase console. <!-- clubedge:only email!=none && framework=next|tanstack-start -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in with Firebase's SDK, which keeps the session in the browser, and send its ID token with each request to the API (`Authorization: Bearer <token>`), which verifies it. Password reset and email confirmation links are generated by Firebase and sent through the [email module](#email), so they open the app's own pages and need no setup in the Firebase console. <!-- clubedge:only email!=none && framework=vite -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Without the email module there is no password reset. <!-- clubedge:only email=none && framework=next|tanstack-start -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in with Firebase's SDK, which keeps the session in the browser, and send its ID token with each request to the API (`Authorization: Bearer <token>`), which verifies it. Without the email module there is no password reset. <!-- clubedge:only email=none && framework=vite -->
 [Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts. Clients sign users in with Firebase's SDK and send the ID token with each request (`Authorization: Bearer <token>`); the API verifies it, and accepts only confirmed email addresses. <!-- clubedge:only framework=none -->
 
 In development, `pnpm auth:dev` starts Firebase's Auth Emulator (`firebase.json`, port 9099), which the example environment points at: no Firebase project or account is needed. Accounts live in memory until it stops. <!-- clubedge:only framework!=none -->
@@ -162,8 +168,11 @@ In production:
 
 1. In the [Firebase console](https://console.firebase.google.com), create a project and turn on **Email/Password** under Authentication, Sign-in method.
 2. Set `FIREBASE_PROJECT_ID` and `FIREBASE_API_KEY` (the Web API key, under Project settings, General).
-3. Under Project settings, Service accounts, generate a private key, and set `FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from it (the key's line breaks as `\n` are fine).
-4. Remove `FIREBASE_AUTH_EMULATOR_HOST`; `pnpm check:env` refuses it in production.
+3. Under Project settings, Service accounts, generate a private key, and set `FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from it (the key's line breaks as `\n` are fine). <!-- clubedge:only api!=fastapi -->
+
+Remove `FIREBASE_AUTH_EMULATOR_HOST` too: `pnpm check:env` refuses it in production.
+
+The FastAPI API needs no service account: it checks each ID token with Firebase's Identity Toolkit, using the Web API key. <!-- clubedge:only api=fastapi -->
 
 Changing a password or resetting it signs out every other session; deleting an account removes it from Firebase after the app's own data for the user.
 
@@ -239,10 +248,10 @@ PGlite runs a single database session, so connections take turns. That is plenty
 
 This project's database is hosted on [Neon](https://neon.com), so there is nothing to install or start:
 
-- **PostgreSQL:** create-clubedge-app created a free, unclaimed Neon database and wrote `DATABASE_URL` (pooled) and `DATABASE_URL_DIRECT` into `apps/web/.env.local`. It expires 72 hours after creation and holds up to 100 MB until it is claimed. `pnpm clubedge neon` shows how long it has left. <!-- clubedge:only framework!=none -->
-- **PostgreSQL:** create-clubedge-app created a free, unclaimed Neon database and wrote `DATABASE_URL` (pooled) and `DATABASE_URL_DIRECT` into `apps/api/.env.local`. It expires 72 hours after creation and holds up to 100 MB until it is claimed. `pnpm clubedge neon` shows how long it has left. <!-- clubedge:only framework=none -->
-- **Keep it:** `pnpm clubedge neon claim` opens Neon's claim page; sign in (free) and the database moves to your account with its data. Claiming resets the password, so copy the new connection strings from the Neon console into `apps/web/.env.local` afterwards: the pooled one into `DATABASE_URL`, the direct one into `DATABASE_URL_DIRECT`. <!-- clubedge:only framework!=none -->
-- **Keep it:** `pnpm clubedge neon claim` opens Neon's claim page; sign in (free) and the database moves to your account with its data. Claiming resets the password, so copy the new connection strings from the Neon console into `apps/api/.env.local` afterwards: the pooled one into `DATABASE_URL`, the direct one into `DATABASE_URL_DIRECT`. <!-- clubedge:only framework=none -->
+- **PostgreSQL:** create-clubedge-app created a free, unclaimed Neon database and wrote `DATABASE_URL` (pooled) and `DATABASE_URL_DIRECT` into `apps/web/.env.local`. It expires 72 hours after creation and holds up to 100 MB until it is claimed. `pnpm clubedge neon` shows how long it has left. <!-- clubedge:only framework=next|tanstack-start -->
+- **PostgreSQL:** create-clubedge-app created a free, unclaimed Neon database and wrote `DATABASE_URL` (pooled) and `DATABASE_URL_DIRECT` into `apps/api/.env.local`. It expires 72 hours after creation and holds up to 100 MB until it is claimed. `pnpm clubedge neon` shows how long it has left. <!-- clubedge:only framework=vite|none -->
+- **Keep it:** `pnpm clubedge neon claim` opens Neon's claim page; sign in (free) and the database moves to your account with its data. Claiming resets the password, so copy the new connection strings from the Neon console into `apps/web/.env.local` afterwards: the pooled one into `DATABASE_URL`, the direct one into `DATABASE_URL_DIRECT`. <!-- clubedge:only framework=next|tanstack-start -->
+- **Keep it:** `pnpm clubedge neon claim` opens Neon's claim page; sign in (free) and the database moves to your account with its data. Claiming resets the password, so copy the new connection strings from the Neon console into `apps/api/.env.local` afterwards: the pooled one into `DATABASE_URL`, the direct one into `DATABASE_URL_DIRECT`. <!-- clubedge:only framework=vite|none -->
 - **Start over:** `pnpm clubedge neon create` creates a new database and replaces the two URLs, for example after one expired.
 - **Your own project:** paste the connection strings from any Neon project instead; nothing else changes.
 - **Cache:** without `REDIS_URL`, the cache and rate limits use process memory. <!-- clubedge:only cache=redis -->
@@ -291,7 +300,8 @@ Redis is optional. Set `REDIS_URL` to a TCP connection URL:
 REDIS_URL=rediss://default:<password>@<host>:6379
 ```
 
-Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencrypted connection on a trusted network. The app uses the standard Redis protocol and requires a Node.js runtime with outbound TCP access.
+Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencrypted connection on a trusted network. The app uses the standard Redis protocol and requires a Node.js runtime with outbound TCP access. <!-- clubedge:only api!=fastapi -->
+The API uses the standard Redis protocol and needs outbound TCP access. <!-- clubedge:only api=fastapi -->
 
 Without `REDIS_URL`, the rate limiter and cache use process memory. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Never commit a real Redis URL or password.
 
@@ -685,7 +695,7 @@ It runs once the repository has the Neon settings below, in Settings, then Secre
 
 The Starter repository also runs `.github/workflows/stack-previews.yml`. For each pull request, it generates React + Vite with Hono and FastAPI through the CLI, then deploys each generated frontend and API as separate Render web services. Both stacks use the existing main Supabase project's Auth endpoint and publishable key, retrieved by the workflow and passed to their generated frontend and API. Set the Actions secret `SUPABASE_ACCESS_TOKEN` and the repository secret or variable `SUPABASE_PROJECT_REF`. The token needs permission to read API gateway keys. These previews share the main project's Supabase Auth configuration and user pool; their application databases remain isolated on per-stack Neon branches. Also set the existing `RENDER_API_KEY`, `NEON_PROJECT_ID`, and `NEON_API_KEY`; if the Render token can access multiple workspaces, set `RENDER_OWNER_ID`. Connect the Starter GitHub repository to that Render workspace so Render can build generated preview branches. Each stack's Neon branch, API service, frontend service, and generated Git branch are deleted when the pull request closes. To allow Supabase email confirmation and password-reset links to return to the Render frontends, add `https://clubedge-starter-vite-**-web.onrender.com/**` under the Supabase project's Auth URL Configuration > Redirect URLs; [Supabase documents the wildcard format](https://supabase.com/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls). Render free services can take about a minute to wake after inactivity. These settings apply only to the Starter repository and are not copied into generated projects. <!-- clubedge:only starter-repository -->
 
-From your machine, `pnpm clubedge deploy --preview` does the same for the current Git branch. <!-- clubedge:only deploy=vercel|railway && framework!=none -->
+From your machine, `pnpm clubedge deploy --preview` does the same for the current Git branch. <!-- clubedge:only deploy=vercel|railway && framework=next|tanstack-start -->
 
 <!-- clubedge:end -->
 
@@ -852,13 +862,20 @@ The API is in Python and managed with [uv](https://docs.astral.sh/uv/): its `pac
 
 ### Apps installed on phones
 
-An app installed on a phone calls the API and keeps the version it shipped with, often for months. It asks `/api/app-version` which versions the API serves, and the answer is never cached. Set them in `apps/api/.env.local`, or in the API's environment in production; each is `null` while unset:
+An app installed on a phone calls the API and keeps the version it shipped with, often for months. It asks `/api/app-version` which versions the API serves, and the answer is never cached, so a change applies on each app's next check, with no new release of the app. Set them in `apps/api/.env.local`, or in the API's environment in production; each is `null` while unset:
 
 - `APP_MINIMUM_VERSION`, the oldest app version the API still serves: below it, the app shows a blocking update screen.
 - `APP_LATEST_VERSION`, the newest released version: below it, the app may show an optional update notice.
 - `APP_UPDATE_URL`, where to get the update: an `https://` link to the store listing or a download page.
+- `APP_NEXT_MINIMUM_VERSION` and `APP_NEXT_MINIMUM_VERSION_FROM`, a minimum announced for a date and time with its time zone, such as `2026-11-01T00:00:00Z`. Until then, apps below it keep working and tell their users to update by that date; from then, the API requires it, with no redeploy.
 
-Versions are `MAJOR.MINOR.PATCH`, such as `1.4.0`, and the latest may not be older than the minimum. Other values fail the request rather than reach the apps, and `pnpm check:env` lists them before a deploy.
+Each can be set for one platform by adding `_IOS` or `_ANDROID` to its name, such as `APP_UPDATE_URL_IOS` for the App Store listing and `APP_UPDATE_URL_ANDROID` for Google Play, or `APP_LATEST_VERSION_IOS` while App Store review holds a release Google Play already has. The apps say which platform they run on, and the platform's own value wins over the shared one.
+
+Versions are `MAJOR.MINOR.PATCH`, such as `1.4.0`. The latest may not be older than the minimum, nor the announced minimum, and the announced minimum must be newer than the current one. Other values fail the request rather than reach the apps, and `pnpm check:env` lists them before a deploy.
+
+The apps also send their version (`X-App-Version`) and platform (`X-App-Platform`) with every request. To a request whose version is below the minimum, the API answers `426 update_required`, on every route but `/api/health`, `/api/ready`, and `/api/app-version`, so an app left open for days shows its update screen at its next request, not only when it starts again. Apps built from a Starter before v0.29.0 send no version: the API serves them, and they find the new minimum at their next start. The version is what the app says it is, so this keeps old apps from calling an API they no longer match; it is not a security control.
+
+For an urgent fix, raise `APP_MINIMUM_VERSION` itself: the apps below it stop at their next request (older builds, at their next start). Once a security fix is out, don't lower the minimum again, even to roll back a broken release: ship a fixed version instead.
 
 Installed apps keep calling the contract they shipped with, so change `openapi.yaml` only in ways they survive: add fields and operations, but never remove or rename them, and never make an optional request field required. The CI workflow's `contract` job compares each pull request's contract with its base branch's using [oasdiff](https://github.com/oasdiff/oasdiff), and fails on a change that breaks existing clients. For a deliberate break before any app has shipped, label the pull request `breaking-contract` and run the job again. Once apps have shipped, a break also needs `APP_MINIMUM_VERSION` raised to the first version that handles it, so older apps ask for an update instead of failing.
 
@@ -872,7 +889,12 @@ Installed apps keep calling the contract they shipped with, so change `openapi.y
 
 1. Set your app's id in `apps/shell/capacitor.config.ts`: a reverse-domain name you own, such as `com.yourcompany.app`. It becomes permanent once the Android and iOS projects exist and a store lists the app, so set it before the first build. The app's name comes from `apps/web/src/config/site.json`.
 2. Set `WEB_URL` in `apps/shell/.env.local` to the website's public `https://` address, such as `https://app.example.com`. The build refuses any other: the app sends its session there.
-3. Run `pnpm --filter @clubedge/shell android` (or `ios`). It builds the web app for the app, creates `apps/shell/android` (or `apps/shell/ios`) on the first run, copies the build into it, and opens Android Studio (or Xcode), where you run the app on a device or an emulator. Commit `android/` and `ios/`: from then on they are your app's own, with its icons, permissions, and signing settings. The first run also makes the app's icons and splash screens from `apps/shell/assets/logo.svg`, the white mark on the brand's blue square, with Capacitor's asset tool (run through npx, so it needs the network then); after changing it, run `pnpm --filter @clubedge/shell icons`, and set the backgrounds to match it at the top of `apps/shell/scripts/icons.mjs`.
+3. Run `pnpm --filter @clubedge/shell android` (or `ios`). It builds the web app for the app, creates `apps/shell/android` (or `apps/shell/ios`) on the first run, copies the build into it, and opens Android Studio (or Xcode), where you run the app on a device or an emulator. Commit `android/` and `ios/`: from then on they are your app's own, with its icons, permissions, and signing settings. The first run also makes the app's icons and splash screens from the art in `apps/shell/assets`, with Capacitor's asset tool (run through npx, so it needs the network then):
+   - `logo.svg`, the icon: the white mark on the brand's blue square.
+   - `splash.svg` and `splash-dark.svg`, iOS's splash screens: the blue mark in the middle of the light and dark backgrounds.
+   - `splash-icon.png`, the blue mark alone, which Android draws in the middle of those backgrounds at 128dp. Android 12 and later show it through a circle 192dp across, which the mark stays inside, and no screen's shape stretches it.
+
+   After changing them, run `pnpm --filter @clubedge/shell icons`, and set the colors to match at the top of `apps/shell/scripts/icons.mjs`.
 
 After changing the web app, `pnpm --filter @clubedge/shell sync` copies a new build into the native projects. Release builds and store listings are made in Android Studio and Xcode, as Capacitor's guides for [Google Play](https://capacitorjs.com/docs/android/deploying-to-google-play) and the [App Store](https://capacitorjs.com/docs/ios/deploying-to-app-store) describe. The project's CI builds a debug APK too; set a `WEB_URL` repository variable so that it calls your website.
 
@@ -901,11 +923,12 @@ Ctrl+C stops it. The installed app keeps loading its pages from your computer un
 
 ### Updates
 
-Each time it starts, the app compares its version with the versions the API serves ([Apps installed on phones](#apps-installed-on-phones)):
+The app compares its version with the versions the API serves ([Apps installed on phones](#apps-installed-on-phones)) when it starts, when it comes back to the foreground (at most every 15 minutes), and whenever the API answers one of its requests `426 update_required`:
 
-- Below `APP_MINIMUM_VERSION`, it shows **Update required**, a screen that keeps the app closed, with an **Update** button that opens `APP_UPDATE_URL` in the phone's browser.
-- Below `APP_LATEST_VERSION` only, a notice above the page offers the same button, and **Not now** hides it until the app starts again.
-- When the API cannot be reached, or does not know `/api/app-version` yet, nothing shows and the app works as usual.
+- Below `APP_MINIMUM_VERSION`, it shows **Update required**, a screen that keeps the app closed, with an **Update** button that opens `APP_UPDATE_URL` in the phone's browser. The app remembers it, so it holds when the app next starts offline, until it is updated.
+- Below `APP_NEXT_MINIMUM_VERSION`, a notice above the page says the date it stops working, with the same button. **Not now** hides it until the next day.
+- Below `APP_LATEST_VERSION` only, a notice offers the update, and **Not now** hides it until a newer version is out.
+- When the API cannot be reached, or does not know `/api/app-version` yet, nothing new shows: a remembered **Update required** still holds, and otherwise the app works as usual.
 
 The app's version is its `versionName` in `apps/shell/android/app/build.gradle`, and its version (`MARKETING_VERSION`) in Xcode. Give it as `MAJOR.MINOR.PATCH`, such as `1.4.0`, and raise it with each release; `1.0` counts as `1.0.0`, and a version in another form never sees a notice.
 
@@ -926,7 +949,7 @@ Builds without `--demo` contain none of it. The demo replaces the app's build in
 
 ## The native app
 
-`apps/mobile` is a native Android and iOS app, built with [Expo](https://expo.dev) (SDK 58) and React Native, with its own screens: sign-in, a dashboard, and settings. <!-- clubedge:only auth!=none -->
+`apps/mobile` is a native Android and iOS app, built with [Expo](https://expo.dev) (SDK 58) and React Native, with its own screens: a welcome screen and sign-in, then two tabs, a dashboard and the settings, with the user's profile. <!-- clubedge:only auth!=none -->
 `apps/mobile` is a native Android and iOS app, built with [Expo](https://expo.dev) (SDK 58) and React Native, with its own screens. <!-- clubedge:only auth=none -->
 It calls the API through your website, as the website does, with the same contract client (`@clubedge/contract`). Expo generates its Android and iOS projects from `apps/mobile/app.config.ts` whenever it builds them (`expo prebuild`), so `android/` and `ios/` are not committed, and upgrades only change the app's TypeScript and config. <!-- clubedge:only framework!=none -->
 It calls the API directly, with the contract client (`@clubedge/contract`). Expo generates its Android and iOS projects from `apps/mobile/app.config.ts` whenever it builds them (`expo prebuild`), so `android/` and `ios/` are not committed, and upgrades only change the app's TypeScript and config. <!-- clubedge:only framework=none -->
@@ -970,11 +993,14 @@ How the app works with the API: <!-- clubedge:only framework=none -->
 - Emailed links, such as sign-up confirmations and password resets, open the website. After confirming an address or setting a new password, sign in again in the app. <!-- clubedge:only auth!=none && framework!=none -->
 - Emailed links open the app, through its address scheme: confirming a new account opens its sign-in screen, and a password reset link opens its reset screen, which sets the new password. <!-- clubedge:only auth=better-auth && email!=none && framework=none -->
 - Supabase's emailed links open the app, through its address scheme, once its Redirect URLs list it (see [Supabase Auth](#supabase-auth)): confirming a new account opens the sign-in screen, and a password reset link opens the reset screen, which sets the new password. <!-- clubedge:only auth=supabase && framework=none -->
-- Deleting the account is in the app's settings, as the App Store requires of apps that let people sign up. <!-- clubedge:only auth!=none -->
+- The Settings tab holds the account: the display name, a Dark mode switch that holds over the phone's appearance, the password, deleting the account (as the App Store requires of apps that let people sign up), and signing out of this device or of all of them. <!-- clubedge:only auth!=none -->
 - The app has no billing: app stores require their own in-app purchases for digital goods, so subscriptions stay on the website. <!-- clubedge:only payments!=none -->
 - Its icon, Android's adaptive icon, and its splash screen are the images in `apps/mobile/assets`, which `app.config.ts` names.
+- Its look is in `apps/mobile/src/lib/theme.ts`: its colors, in light and dark, and its type scale, in Inter, which loads while the splash screen shows.
+- The welcome screen shows the brand's blue and the app's mark. For a photo of your own there, add it to `apps/mobile/assets` and set `heroPhoto` in `apps/mobile/src/app/welcome.tsx`. <!-- clubedge:only auth!=none -->
+- The welcome and sign-up screens link to your Terms and Privacy Policy: set their addresses, `links.terms` and `links.privacy` in `apps/mobile/src/config/site.json`, before the first release. The stores ask for a privacy policy too. <!-- clubedge:only auth!=none -->
 
-Each time it starts, the app compares its version, `version` in `app.config.ts` (`MAJOR.MINOR.PATCH`; raise it with each release), with the versions the API serves ([Apps installed on phones](#apps-installed-on-phones)). Below `APP_MINIMUM_VERSION`, it shows only **Update required**, with an **Update** button that opens `APP_UPDATE_URL`; below `APP_LATEST_VERSION`, the dashboard says an update is available.
+The app compares its version, `version` in `app.config.ts` (`MAJOR.MINOR.PATCH`; raise it with each release), with the versions the API serves ([Apps installed on phones](#apps-installed-on-phones)) when it starts, when it comes back to the foreground (at most every 15 minutes), and whenever the API answers one of its requests `426 update_required`. Below `APP_MINIMUM_VERSION`, it shows only **Update to continue**, with the installed and required versions and an **Update now** button that opens `APP_UPDATE_URL`, and remembers it, so it holds when the app next starts offline, until it is updated. Below `APP_NEXT_MINIMUM_VERSION`, a sheet over any screen offers the update, with the date this version stops working and the days left; **Not now** hides it until the next day. Below `APP_LATEST_VERSION`, a banner on Home offers the update, and its close button hides it until a newer version is out. All of them are in `src/components/update-gate.tsx`. The logic is shared with the API in `packages/contract` (`app-version.ts` and `app-update.ts`).
 
 <!-- clubedge:end -->