From c5ca8d0efa883bd680c339e9b466918358ce66fb Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:08:53 -0700
Subject: [PATCH 1/7] feat(streaming): proxy /stream/ through the app

The app forwards /stream/ to the session manager, WebSocket upgrades
and the save-sync event stream included, ahead of helmet and
compression. A reverse proxy in front now needs no route of its own
for streams, and the session manager publishes no ports.
---
 .env.example                           |  1 -
 backend/src/config.ts                  |  2 +
 backend/src/routes/streamProxy.test.ts | 87 ++++++++++++++++++++++++++
 backend/src/routes/streamProxy.ts      | 40 ++++++++++++
 backend/src/server.ts                  | 10 +++
 docker-compose.yml                     |  7 +--
 6 files changed, 142 insertions(+), 5 deletions(-)
 create mode 100644 backend/src/routes/streamProxy.test.ts
 create mode 100644 backend/src/routes/streamProxy.ts

diff --git a/.env.example b/.env.example
index 154a306..05dcc5e 100644
--- a/.env.example
+++ b/.env.example
@@ -107,7 +107,6 @@ ENABLE_CACHE_PREWARM=true
 # and enable the profile. See docs/10-features/13-streaming.md.
 # COMPOSE_PROFILES=streaming
 # STREAMING_API_TOKEN=
-# STREAM_PORT=8081
 # MAX_SESSIONS=4
 # Sign in users an authenticating reverse proxy (e.g. Authentik forward auth)
 # names in a header. Off unless TRUSTED_HEADER_USERNAME and TRUSTED_PROXIES are
diff --git a/backend/src/config.ts b/backend/src/config.ts
index 65726c2..3f32282 100644
--- a/backend/src/config.ts
+++ b/backend/src/config.ts
@@ -173,6 +173,8 @@ export const config = {
   // Java applets (flashpoint-ultimate-server). Streaming is off unless both are set.
   streamingApiUrl: process.env.STREAMING_API_URL || null,
   streamingApiToken: process.env.STREAMING_API_TOKEN || null,
+  // Where /stream/ is proxied to: the session manager's stream port
+  streamingStreamUrl: process.env.STREAMING_STREAM_URL || null,
 
   // Sign users in from a header set by an authenticating reverse proxy, such as
   // Authentik forward auth. Off unless the header name and the proxy addresses
diff --git a/backend/src/routes/streamProxy.test.ts b/backend/src/routes/streamProxy.test.ts
new file mode 100644
index 0000000..02fb125
--- /dev/null
+++ b/backend/src/routes/streamProxy.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import http, { type Server } from 'http';
+import type { AddressInfo } from 'net';
+import express from 'express';
+import { mountStreamProxy } from './streamProxy';
+
+vi.mock('../utils/logger', () => ({
+  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
+}));
+
+let upstream: Server;
+let app: Server;
+let base: string;
+
+function listen(server: Server): Promise<number> {
+  return new Promise((resolve) =>
+    server.listen(0, '127.0.0.1', () => resolve((server.address() as AddressInfo).port))
+  );
+}
+
+beforeAll(async () => {
+  // A stand-in session manager: echoes the path, and accepts WebSocket upgrades
+  upstream = http.createServer((req, res) => {
+    res.setHeader('Content-Type', 'text/plain');
+    res.end(`upstream saw ${req.method} ${req.url}`);
+  });
+  upstream.on('upgrade', (req, socket) => {
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n'
+    );
+    socket.write(`ws ${req.url}`);
+    socket.end();
+  });
+  const upstreamPort = await listen(upstream);
+
+  const expressApp = express();
+  const attach = mountStreamProxy(expressApp, `http://127.0.0.1:${upstreamPort}`);
+  expressApp.get('/other', (_req, res) => {
+    res.send('app');
+  });
+  app = http.createServer(expressApp);
+  attach(app);
+  base = `http://127.0.0.1:${await listen(app)}`;
+});
+
+afterAll(() => {
+  app.close();
+  upstream.close();
+});
+
+describe('stream proxy', () => {
+  it('forwards /stream/ requests with their full path', async () => {
+    const res = await fetch(`${base}/stream/abc/_fp/start`, { method: 'POST' });
+    expect(await res.text()).toBe('upstream saw POST /stream/abc/_fp/start');
+  });
+
+  it('leaves other routes to the app', async () => {
+    expect(await (await fetch(`${base}/other`)).text()).toBe('app');
+  });
+
+  it('forwards WebSocket upgrades', async () => {
+    const received = await new Promise<string>((resolve, reject) => {
+      const req = http.request(`${base}/stream/abc/websocket`, {
+        headers: { Connection: 'Upgrade', Upgrade: 'websocket' },
+      });
+      req.on('upgrade', (res, socket, head) => {
+        expect(res.statusCode).toBe(101);
+        let data = head.toString();
+        socket.on('data', (chunk) => (data += chunk.toString()));
+        socket.on('end', () => resolve(data));
+      });
+      req.on('error', reject);
+      req.end();
+    });
+    expect(received).toBe('ws /stream/abc/websocket');
+  });
+
+  it('answers 502 when the session manager is down', async () => {
+    const down = express();
+    mountStreamProxy(down, 'http://127.0.0.1:9');
+    const server = http.createServer(down);
+    const port = await listen(server);
+    const res = await fetch(`http://127.0.0.1:${port}/stream/abc/`);
+    server.close();
+    expect(res.status).toBe(502);
+  });
+});
diff --git a/backend/src/routes/streamProxy.ts b/backend/src/routes/streamProxy.ts
new file mode 100644
index 0000000..39c391f
--- /dev/null
+++ b/backend/src/routes/streamProxy.ts
@@ -0,0 +1,40 @@
+import { ServerResponse, type IncomingMessage, type Server } from 'http';
+import type { Socket } from 'net';
+import type { Express } from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import { logger } from '../utils/logger';
+
+/**
+ * Proxies /stream/ to the session manager, WebSockets included, so a reverse
+ * proxy in front of the app needs no route of its own for streams. Returns a
+ * function that wires WebSocket upgrades into the HTTP server once it exists.
+ */
+export function mountStreamProxy(app: Express, target: string): (server: Server) => void {
+  const proxy = createProxyMiddleware('/stream/', {
+    target,
+    ws: true,
+    logLevel: 'silent',
+    // Save sync is a long-lived event stream; don't let the server's idle timeout cut it
+    onProxyReq: (_proxyReq, req) => {
+      req.socket.setTimeout(0);
+    },
+    onError: (error, req, res) => {
+      logger.warn('[Streaming] Stream proxy error', { url: req.url, error: error.message });
+      // A failed WebSocket upgrade hands over the raw socket instead of a response
+      if (!(res instanceof ServerResponse)) {
+        (res as Socket).destroy();
+      } else if (!res.headersSent) {
+        res.writeHead(502).end();
+      }
+    },
+  });
+  app.use(proxy);
+
+  return (server) => {
+    server.on('upgrade', (req: IncomingMessage, socket: Socket, head: Buffer) => {
+      if (!req.url?.startsWith('/stream/')) return;
+      socket.setTimeout(0);
+      proxy.upgrade?.(req as Parameters<NonNullable<typeof proxy.upgrade>>[0], socket, head);
+    });
+  };
+}
diff --git a/backend/src/server.ts b/backend/src/server.ts
index 4a0bfa4..2c6217d 100644
--- a/backend/src/server.ts
+++ b/backend/src/server.ts
@@ -44,6 +44,8 @@ import { zipManager } from './game/zip-manager';
 import { gameZipServer } from './game/gamezipserver';
 import gameProxyRouter from './routes/game-proxy';
 import gameZipRouter from './routes/game-zip';
+import { mountStreamProxy } from './routes/streamProxy';
+import { StreamingService } from './services/StreamingService';
 
 /**
  * Compute SHA-256 CSP hashes for inline <script> blocks (those without a src
@@ -112,6 +114,13 @@ async function startServer() {
   app.use('/game-proxy', gameCors, startupGate, gameProxyRouter);
   app.use('/game-zip', gameCors, startupGate, gameZipRouter);
 
+  // Streams are proxied before helmet and compression, which would break the
+  // streamer's page and its event stream
+  const attachStreamProxy =
+    StreamingService.isEnabled() && config.streamingStreamUrl
+      ? mountStreamProxy(app, config.streamingStreamUrl)
+      : null;
+
   // When the backend also serves the SPA, allow the app's own resources by
   // hash/keyword rather than the blanket 'unsafe-inline'/'unsafe-eval':
   //   - scriptSrc: 'self' for hashed bundles, sha256 hashes for the inline theme
@@ -230,6 +239,7 @@ async function startServer() {
     logger.info(`🎮 Game content: /game-proxy/* and /game-zip/* (integrated)`);
     logger.info(`🌍 Environment: ${config.nodeEnv}`);
   });
+  attachStreamProxy?.(server);
 
   // Prevent connection exhaustion - critical for handling game file requests
   server.keepAliveTimeout = 65000; // 65s - slightly above common load balancer timeout
diff --git a/docker-compose.yml b/docker-compose.yml
index f95585a..8efaae4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -58,6 +58,7 @@ services:
       - ENABLE_CGI=${ENABLE_CGI:-false}
       # Streamed play for games that can't run in a browser (off unless the token is set)
       - STREAMING_API_URL=${STREAMING_API_URL:-http://session-manager:8080}
+      - STREAMING_STREAM_URL=${STREAMING_STREAM_URL:-http://session-manager:8081}
       - STREAMING_API_TOKEN=${STREAMING_API_TOKEN:-}
       # Sign in users named by an authenticating reverse proxy (off unless both are set)
       - TRUSTED_HEADER_USERNAME=${TRUSTED_HEADER_USERNAME:-}
@@ -96,16 +97,14 @@ services:
     networks:
       - arcade
 
-  # Starts a streamer container per player and proxies its stream at /stream/
+  # Starts a streamer container per player. The app proxies /stream/ to it, so
+  # it publishes no ports.
   session-manager:
     profiles: [streaming]
     build: streaming/session-manager
     image: dotcom-arcade-session-manager:${IMAGE_TAG:-latest}
     container_name: dotcom-arcade-session-manager
     restart: unless-stopped
-    ports:
-      # Route /stream/ on the site to this port (see streaming/README.md)
-      - "${STREAM_PORT:-8081}:8081"
     volumes:
       # Starts and removes streamer containers. Docker socket access is
       # effectively root on the host.

From 8875d4cc0aa92a63b554b19ea8aea13b33f6a90b Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:10:52 -0700
Subject: [PATCH 2/7] feat(scripts): check storage first; download only from a
 supplied torrent

The script no longer carries download links: --torrent takes the
.torrent file from Flashpoint's downloads page, and --infinity the
Infinity archive. Before doing anything it works out the space the
download and extraction need, refuses to start without it, and asks
for confirmation unless --yes is given. It notes Flashpoint's unsettled
legal standing and the user's responsibility.
---
 scripts/setup-flashpoint.sh | 125 +++++++++++++++++++++++++-----------
 1 file changed, 89 insertions(+), 36 deletions(-)

diff --git a/scripts/setup-flashpoint.sh b/scripts/setup-flashpoint.sh
index 26df741..52a87f0 100755
--- a/scripts/setup-flashpoint.sh
+++ b/scripts/setup-flashpoint.sh
@@ -1,44 +1,55 @@
 #!/usr/bin/env bash
-# Downloads Flashpoint Ultimate and extracts it into a directory Dotcom Arcade
-# can serve. Safe to re-run: it resumes the download and skips archives it has
-# already extracted.
+# Extracts Flashpoint Ultimate into a directory Dotcom Arcade can serve, and
+# can download it first from a torrent you got from Flashpoint. Safe to re-run:
+# it resumes the download and skips archives it has already extracted.
 #
 #   scripts/setup-flashpoint.sh [options] /path/to/flashpoint
 #
 # Options:
-#   --downloads DIR    where the torrent downloads to (default: DEST/../downloads)
-#   --keep-archives    keep each archive after extracting it, to keep seeding;
-#                      needs room for both (about 4.6 TB for Ultimate 14)
-#   --skip-download    use archives already in the downloads directory
-#   --with-infinity    add Flashpoint Infinity for Linux's software, which
-#                      streaming needs (FPSoftware/, Server/)
+#   --torrent FILE     download Flashpoint Ultimate with aria2c, from the
+#                      .torrent file on https://flashpointarchive.org/downloads
+#   --downloads DIR    where the archives are or will be downloaded to
+#                      (default: DEST/../downloads)
+#   --infinity FILE    add the software streaming needs (FPSoftware/, Server/)
+#                      from Flashpoint Infinity for Linux (.7z, same page)
+#   --keep-archives    keep each archive after extracting it, e.g. to seed;
+#                      needs room for both copies
+#   --yes              don't ask for confirmation
 #
-# Requires aria2c (unless --skip-download) and 7-Zip (7z, 7zz or 7za).
+# Without --torrent, it uses the Ultimate archives already in the downloads
+# directory. Requires 7-Zip (7z, 7zz or 7za), and aria2c with --torrent.
+#
+# Flashpoint Ultimate is more than 2 TB. This script checks for the space
+# before it starts and refuses to run without it.
+#
+# Flashpoint Archive's legal standing is unsettled. You are responsible for
+# complying with copyright law where you live. This script contains no
+# download links: it only downloads from a torrent you supply.
 set -euo pipefail
 
-ULTIMATE_VERSION=14
-TORRENT_URL="https://download.unstable.life/FlashpointUltimate${ULTIMATE_VERSION}.torrent"
-INFINITY_URL="https://download.unstable.life/upload/fp14.0.3_lin_20251201.7z"
-INFINITY_SHA256=f393a98c5c35e229a744c102b0cb53270b1b4f1b3ebd40d604f98323444a4b1f
-# Free space to leave on the disk after each archive
+# Free space to leave on the disk after each archive, and headroom for the
+# largest archive being extracted while its zip still exists
 MARGIN=$((20 * 1024 ** 3))
+LARGEST_ARCHIVE=$((100 * 1024 ** 3))
 
 usage() {
-  sed -n '6,16p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '6,27p' "$0" | sed 's/^# \{0,1\}//'
   exit 1
 }
 
 DEST=
 DOWNLOADS=
+TORRENT=
+INFINITY=
 KEEP=false
-DOWNLOAD=true
-INFINITY=false
+YES=false
 while (($#)); do
   case $1 in
+    --torrent) TORRENT=${2:?}; shift ;;
     --downloads) DOWNLOADS=${2:?}; shift ;;
+    --infinity) INFINITY=${2:?}; shift ;;
     --keep-archives) KEEP=true ;;
-    --skip-download) DOWNLOAD=false ;;
-    --with-infinity) INFINITY=true ;;
+    --yes) YES=true ;;
     -h | --help) usage ;;
     -*) echo "Unknown option: $1" >&2; usage ;;
     *) DEST=$1 ;;
@@ -46,6 +57,8 @@ while (($#)); do
   shift
 done
 [[ -n $DEST ]] || usage
+[[ -z $TORRENT || -f $TORRENT ]] || { echo "No torrent file at $TORRENT" >&2; exit 1; }
+[[ -z $INFINITY || -f $INFINITY ]] || { echo "No Infinity archive at $INFINITY" >&2; exit 1; }
 mkdir -p "$DEST"
 DEST=$(cd "$DEST" && pwd)
 DOWNLOADS=${DOWNLOADS:-$(dirname "$DEST")/downloads}
@@ -53,8 +66,57 @@ mkdir -p "$DOWNLOADS"
 
 SEVENZIP=$(command -v 7zz || command -v 7z || command -v 7za || true)
 [[ -n $SEVENZIP ]] || { echo "7-Zip is required (7z, 7zz or 7za)" >&2; exit 1; }
+[[ -z $TORRENT ]] || command -v aria2c >/dev/null || { echo "aria2c is required for --torrent" >&2; exit 1; }
 
 gib() { echo "$(($1 / 1024 ** 3))G"; }
+free_bytes() { df --output=avail -B1 "$1" | tail -1; }
+same_disk() { [[ $(stat -c %d "$1") == $(stat -c %d "$2") ]]; }
+
+DONE=$DOWNLOADS/.extracted
+touch "$DONE"
+
+# What's left to extract, measured from the archives on disk
+remaining=0
+while IFS= read -r -d '' archive; do
+  grep -qxF "$(basename "$archive")" "$DONE" || remaining=$((remaining + $(stat -c %s "$archive")))
+done < <(find "$DOWNLOADS" -maxdepth 2 -name '*.zip' -print0)
+
+# The download's size, from the torrent
+download=0
+if [[ -n $TORRENT ]]; then
+  download=$(aria2c -S "$TORRENT" | awk -F'[()]' '/Total Length/ { gsub(/,/, "", $2); print $2; exit }')
+  [[ $download =~ ^[0-9]+$ ]] || { echo "Couldn't read the download's size from $TORRENT" >&2; exit 1; }
+  remaining=$download
+fi
+
+# Extracted files take about as much room as the archives. Unless they're
+# kept, each archive is deleted once extracted, so on a shared disk only the
+# largest one is ever stored twice.
+if $KEEP; then extra=$remaining; else extra=$((remaining < LARGEST_ARCHIVE ? remaining : LARGEST_ARCHIVE)); fi
+if same_disk "$DOWNLOADS" "$DEST"; then
+  checks=("$DEST:$((download + extra + MARGIN))")
+else
+  checks=("$DOWNLOADS:$((download + MARGIN))" "$DEST:$((remaining + MARGIN))")
+fi
+
+if ((remaining > 0)); then
+  echo "Flashpoint Ultimate is very large: about $(gib "$remaining") of game data."
+  short=false
+  for check in "${checks[@]}"; do
+    dir=${check%:*} need=${check##*:} avail=$(free_bytes "${check%:*}")
+    echo "  $dir needs about $(gib "$need"), has $(gib "$avail") free"
+    ((avail >= need)) || short=true
+  done
+  if $short; then
+    echo "Not enough free space. Free up room or choose another disk; see the README's hosting requirements." >&2
+    exit 1
+  fi
+  if ! $YES; then
+    [[ -t 0 ]] || { echo "Run with --yes to continue without a prompt." >&2; exit 1; }
+    read -r -p "This takes a day or more. Continue? [y/N] " answer
+    [[ $answer == [yY]* ]] || exit 1
+  fi
+fi
 
 # Extracts ARCHIVE into DEST, or only the entries listed in LIST if given.
 # Archives may wrap everything in one top-level folder (e.g. "Flashpoint
@@ -86,19 +148,16 @@ extract() {
 }
 
 # 1. Download the packed archives
-if $DOWNLOAD; then
-  command -v aria2c >/dev/null || { echo "aria2c is required to download" >&2; exit 1; }
-  echo "==> Downloading Flashpoint Ultimate ${ULTIMATE_VERSION} into $DOWNLOADS"
+if [[ -n $TORRENT ]]; then
+  echo "==> Downloading into $DOWNLOADS"
   aria2c --dir="$DOWNLOADS" --seed-time=0 --check-integrity=true \
-    --file-allocation=falloc --bt-max-peers=100 --follow-torrent=mem "$TORRENT_URL"
+    --file-allocation=falloc --bt-max-peers=100 "$TORRENT"
 fi
 # fp-index.json stays behind once the archives are extracted and deleted
 PACKED=$(find "$DOWNLOADS" -maxdepth 2 \( -name GameData_1.zip -o -name fp-index.json \) -printf '%h\n' | head -1)
 [[ -n $PACKED ]] || { echo "No Ultimate archives found under $DOWNLOADS" >&2; exit 1; }
 
 # 2. Extract the game data, images and htdocs, one archive at a time
-DONE=$DOWNLOADS/.extracted
-touch "$DONE"
 shopt -s nullglob
 for archive in "$PACKED"/Images_*.zip "$PACKED"/Htdocs_*.zip "$PACKED"/GameData_*.zip "$PACKED"/Extras_*.zip; do
   name=$(basename "$archive")
@@ -128,22 +187,16 @@ if [[ ! -f $DEST/preferences.json && -f $DEST/.preferences.defaults.json ]]; the
 fi
 
 # 4. Optionally add Infinity for Linux's software, without replacing anything
-if $INFINITY; then
-  infinity=$DOWNLOADS/$(basename "$INFINITY_URL")
-  if [[ ! -f $infinity ]]; then
-    echo "==> Downloading Flashpoint Infinity for Linux"
-    curl -fL --retry 3 -o "$infinity.part" "$INFINITY_URL"
-    mv "$infinity.part" "$infinity"
-  fi
-  echo "$INFINITY_SHA256  $infinity" | sha256sum -c --quiet
+if [[ -n $INFINITY ]]; then
+  echo "==> $(basename "$INFINITY")"
   staging=$DEST/.extracting
   rm -rf "$staging"
-  "$SEVENZIP" x -y -bso0 -bsp1 -o"$staging" "$infinity"
+  "$SEVENZIP" x -y -bso0 -bsp1 -o"$staging" "$INFINITY"
   root=$(dirname "$(find "$staging" -maxdepth 3 -name version.txt | head -1)")
   cp -an "$root/." "$DEST/"
   rm -rf "$staging"
 fi
 
 [[ -f $DEST/Data/flashpoint.sqlite ]] ||
-  echo "Warning: no Data/flashpoint.sqlite. Re-run with --with-infinity to take Infinity's." >&2
+  echo "Warning: no Data/flashpoint.sqlite. Re-run with --infinity to take Infinity's." >&2
 echo "Done. Set FLASHPOINT_HOST_PATH=$DEST in .env."

From dd60c49dda131fd6b2994ff6adff584c62e9e35c Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:12:03 -0700
Subject: [PATCH 3/7] docs: state hosting requirements and the legal position
 up front

The README opens with storage, CPU and HTTPS requirements, including the
per-player cost of streaming, and explains Flashpoint's legal standing.
Setup now uses the torrent and Infinity archive from Flashpoint's site,
and the streaming docs reflect the app proxying /stream/.
---
 README.md                                   | 69 +++++++++++++++------
 docs/09-deployment/docker-deployment.md     | 15 +++--
 docs/09-deployment/environment-variables.md |  1 +
 docs/10-features/13-streaming.md            | 43 ++++++++-----
 streaming/streamer/README.md                |  2 +-
 5 files changed, 88 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index d41c4c0..8019daa 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,21 @@ Flash Player stream from your server.
 > Flashpoint Archive. It's built on
 > [flashpoint-web](https://github.com/darkraise/flashpoint-web) by darkraise.
 
+## Before you start: hosting requirements
+
+> [!WARNING]
+>
+> **Dotcom Arcade needs a lot of disk, and streaming needs a lot of CPU.** Check
+> these before you download anything.
+
+| Resource      | Needed                                                                                                                                                                                                                       |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Storage**   | **More than 2.3 TB** for Flashpoint Ultimate 14, and growing with each release. 4.6 TB if you keep the downloaded archives to seed them. A spare desktop drive won't do.                                                     |
+| **Time**      | A day or more to download and extract, depending on your connection and disks.                                                                                                                                               |
+| **Server**    | Linux with Docker. 2 CPU cores and 4 GB of RAM serve the site and in-browser games to a household.                                                                                                                           |
+| **Streaming** | Optional, and heavy: every player gets their own container running the game and encoding its video on the CPU. Plan on roughly 1 to 2 CPU cores and 1 GB of RAM per player streaming at once, and a few Mbps of upload each. |
+| **HTTPS**     | Required for streaming, since browsers only allow its video decoder on secure pages. Recommended anyway.                                                                                                                     |
+
 ## Features
 
 - **Plays almost everything.**
@@ -54,27 +69,37 @@ Flash Player stream from your server.
 
 ## Getting started
 
-You need a Linux server with Docker, and enough disk for Flashpoint Ultimate:
-about 2.3 TB for version 14, or 4.6 TB if you keep the downloaded archives to
-seed. Expect the download and extraction to take a day or more.
+Check the [hosting requirements](#before-you-start-hosting-requirements) first.
 
 ### 1. Get Flashpoint Ultimate
 
-[`scripts/setup-flashpoint.sh`](scripts/setup-flashpoint.sh) downloads the
-torrent with `aria2c` and then extracts each archive in turn. It checks free
-space before each one and deletes it afterwards, so the disk never needs room
-for both. It also pulls the database, settings and playlists out of
-`Base_1.zip`, which otherwise only holds Windows software. Re-run it to resume
-after an interruption.
+Download two files from Flashpoint's
+[downloads page](https://flashpointarchive.org/downloads):
+
+- the **Flashpoint Ultimate** `.torrent` file;
+- **Flashpoint Infinity for Linux** (`.7z`), whose software streaming needs.
+
+[`scripts/setup-flashpoint.sh`](scripts/setup-flashpoint.sh) then does the rest:
+
+- It checks that you have the disk space, and stops before downloading anything
+  if you don't.
+- It downloads the torrent with `aria2c`.
+- It extracts each archive in turn and deletes it afterwards, so the disk never
+  needs room for both.
+- It pulls the database, settings and playlists out of `Base_1.zip`, which
+  otherwise only holds Windows software.
+
+Re-run it to resume after an interruption.
 
 ```sh
 sudo apt install aria2 7zip tmux
 tmux new -s flashpoint
-scripts/setup-flashpoint.sh --with-infinity /srv/flashpoint
+scripts/setup-flashpoint.sh --torrent FlashpointUltimate14.torrent \
+  --infinity fp14.0.3_lin_20251201.7z /srv/flashpoint
 ```
 
-`--with-infinity` adds Flashpoint Infinity for Linux's software, which streaming
-needs. `--keep-archives` keeps the archives so you can keep seeding.
+`--keep-archives` keeps the archives so you can keep seeding, which needs room
+for both copies.
 
 ### 2. Configure
 
@@ -105,7 +130,7 @@ Under **Settings → App** you can set the site name and tagline.
 
 Streaming plays the games browsers can't. To turn it on:
 
-1. Run the setup script with `--with-infinity`.
+1. Run the setup script with `--infinity`.
 2. Add to `.env`:
 
    ```sh
@@ -114,13 +139,12 @@ Streaming plays the games browsers can't. To turn it on:
    ```
 
 3. Rebuild with `docker compose up -d --build`.
-4. Route `/stream/` on your site to the session manager (port 8081). Streams
-   need HTTPS. See the [streaming guide](docs/10-features/13-streaming.md) for
-   an nginx example.
+4. Serve the site over HTTPS. The app proxies streams itself, so your reverse
+   proxy only needs to pass WebSocket upgrades and allow long-lived connections.
+   See the [streaming guide](docs/10-features/13-streaming.md).
 
 The session manager starts containers through the Docker socket, which amounts
-to root on the host. Keep it off the public internet. Only `/stream/` needs to
-be reachable, and only through your proxy.
+to root on the host. It publishes no ports: only the app talks to it.
 
 ### Signing in through a reverse proxy
 
@@ -156,6 +180,15 @@ and development. Useful starting points:
 - [Selkies](https://github.com/selkies-project/selkies), which streams the
   games.
 
+## Legal
+
+Flashpoint Archive is a preservation project whose legal standing has never been
+settled. It removes games when their rights holders ask. Dotcom Arcade contains
+no games and links to no game downloads. You get Flashpoint from Flashpoint's
+own site, and you are responsible for complying with copyright law where you
+live. Rights holders who want a game removed should contact
+[Flashpoint Archive](https://flashpointarchive.org/).
+
 ## License
 
 GPL-3.0, like flashpoint-web. See [LICENSE](LICENSE).
diff --git a/docs/09-deployment/docker-deployment.md b/docs/09-deployment/docker-deployment.md
index 27dbccf..13160cf 100644
--- a/docs/09-deployment/docker-deployment.md
+++ b/docs/09-deployment/docker-deployment.md
@@ -6,8 +6,11 @@ walks through a first install; this page covers the details.
 ## Prerequisites
 
 - **Docker:** Engine 24+ with the Compose plugin.
-- **Memory:** 4 GB of RAM. With streaming, allow about 1 GB more per concurrent
-  stream, since each streamer container gets 1 GB of shared memory.
+- **Storage:** more than 2.3 TB for Flashpoint Ultimate 14, or 4.6 TB to keep
+  the downloaded archives.
+- **CPU and memory:** 2 cores and 4 GB of RAM for the site. Streaming adds
+  roughly 1 to 2 CPU cores and 1 GB of RAM per player streaming at once, since
+  each player's container runs the game and encodes its video on the CPU.
 - **A Flashpoint install** at `FLASHPOINT_HOST_PATH`, with
   `Data/flashpoint.sqlite`, `Data/Games/`, `Data/Images/`, `Data/Playlists/`
   and `Legacy/htdocs/`. `scripts/setup-flashpoint.sh` produces one from the
@@ -18,7 +21,7 @@ walks through a first install; this page covers the details.
 | Service           | Image                          | Profile     | Purpose                                                  |
 | ----------------- | ------------------------------ | ----------- | -------------------------------------------------------- |
 | `app`             | `dotcom-arcade`                | (always)    | UI, API and game content on port 3100                    |
-| `session-manager` | `dotcom-arcade-session-manager` | `streaming` | Starts streamer containers; serves `/stream/` on port 8081 |
+| `session-manager` | `dotcom-arcade-session-manager` | `streaming` | Starts streamer containers and serves their streams, through the app |
 | `streamer`        | `dotcom-arcade-streamer`       | `streaming` | Built only; the session manager runs one per player      |
 
 All three are built from this repository by `docker compose up -d --build`.
@@ -37,14 +40,14 @@ socket, and passes `FLASHPOINT_HOST_PATH` on to the streamer containers.
 ## Ports and networks
 
 - **App:** listens on `WEB_PORT` (default 80) on the host.
-- **Session manager:** serves `/stream/` on `STREAM_PORT` (default 8081).
+- **Session manager:** publishes no ports. The app proxies `/stream/` to it.
 - **`dotcom-arcade` network:** the app and the session manager share it.
 - **`dotcom-arcade-streams` network:** holds the streamer containers. It's
   internal, so they have no internet access and only the session manager can
   reach them.
 
 Put a reverse proxy with HTTPS in front of the app. Streaming needs HTTPS, and
-the proxy must route `/stream/` to the session manager (see
+the proxy must pass WebSocket upgrades (see
 [Streaming](../10-features/13-streaming.md#reverse-proxy)).
 
 ## Health checks
@@ -72,7 +75,7 @@ docker compose logs -f session-manager
   `docker compose exec app ls /data/flashpoint/Data`.
 - **Missing playlists or settings:** `Data/Playlists` or `preferences.json` is
   missing. Re-run `scripts/setup-flashpoint.sh`, which takes them from
-  `Base_1.zip`, or add `--with-infinity`.
+  `Base_1.zip`, or pass `--infinity`.
 - **Permission errors on `./data` or `./logs`:** set `PUID`/`PGID` to the owner
   of those folders.
 
diff --git a/docs/09-deployment/environment-variables.md b/docs/09-deployment/environment-variables.md
index fcb776f..b8a080f 100644
--- a/docs/09-deployment/environment-variables.md
+++ b/docs/09-deployment/environment-variables.md
@@ -125,6 +125,7 @@ streamed by the session manager under `streaming/`. It runs under the
 | Variable              | Default                       | Description                                                     |
 | --------------------- | ----------------------------- | --------------------------------------------------------------- |
 | `STREAMING_API_URL`   | `http://session-manager:8080` | Session manager's internal API                                  |
+| `STREAMING_STREAM_URL` | `http://session-manager:8081` | Where the app proxies `/stream/` to                            |
 | `STREAMING_API_TOKEN` | -                             | Token shared with the session manager. Streaming is off without it |
 
 **Trusted Header Login:**
diff --git a/docs/10-features/13-streaming.md b/docs/10-features/13-streaming.md
index 8a02c92..e95fc26 100644
--- a/docs/10-features/13-streaming.md
+++ b/docs/10-features/13-streaming.md
@@ -17,7 +17,7 @@ they need the Flashpoint Launcher.
   for Flash games.
 - **The session manager** (`streaming/session-manager`) starts one streamer
   container per session through the Docker socket, and proxies the browser's
-  connection to it at `/stream/<id>/`.
+  connection to it at `/stream/<id>/`. The app forwards `/stream/` to it.
 - **The streamer** (`streaming/streamer`) launches the game the way
   Flashpoint's Linux launcher does, and streams the screen and sound with
   [Selkies](https://github.com/selkies-project/selkies). The display is sized to
@@ -37,13 +37,16 @@ and [streaming/streamer/README.md](../../streaming/streamer/README.md).
 
 - **Infinity for Linux's software.** The streamer runs Flashpoint's Linux
   builds of the game server, Java, Wine and the Flash and Shockwave players.
-  Ultimate's archives only include the Windows builds. Run
-  `scripts/setup-flashpoint.sh --with-infinity`, which adds them without
+  Ultimate's archives only include the Windows builds. Download Flashpoint
+  Infinity for Linux from Flashpoint's downloads page and pass it to
+  `scripts/setup-flashpoint.sh --infinity`, which adds the software without
   replacing anything.
 - **HTTPS.** Browsers only allow the video decoder Selkies uses on secure
   pages.
-- **A reverse proxy route** for `/stream/`, including WebSocket upgrades (see
-  below).
+- **A server with CPU to spare.** Every player streaming at once has a
+  container running the game and encoding its video on the CPU. Plan on roughly
+  1 to 2 CPU cores and 1 GB of RAM each, and a few Mbps of upload. Set
+  `MAX_SESSIONS` so the server isn't overloaded.
 
 ## Enabling it
 
@@ -63,18 +66,24 @@ sets up.
 | --------------------- | ----------------------------- | ----------------------------------------------------------------- |
 | `STREAMING_API_TOKEN` | -                             | Shared secret between the app and the session manager; required   |
 | `STREAMING_API_URL`   | `http://session-manager:8080` | Session manager's internal API                                    |
-| `STREAM_PORT`         | `8081`                        | Host port the session manager serves `/stream/` on                |
+| `STREAMING_STREAM_URL` | `http://session-manager:8081` | Where the app proxies `/stream/` to                              |
 | `MAX_SESSIONS`        | `4`                           | Most streams running at once                                      |
 | `STREAM_PLATFORMS`    | `Java,Shockwave,Flash`        | Platforms offered for streaming                                   |
 
 ## Reverse proxy
 
-Route `/stream/` to the session manager and everything else to the app. With
-nginx:
+The app proxies `/stream/` to the session manager itself, so no extra route is
+needed. A reverse proxy in front of the app must still:
+
+- pass WebSocket upgrades;
+- allow long-lived connections, at least as long as a play session;
+- not buffer responses, which would hold back the save-sync event stream.
+
+With nginx:
 
 ```nginx
-location /stream/ {
-    proxy_pass http://127.0.0.1:8081;
+location / {
+    proxy_pass http://127.0.0.1:80;
     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection "upgrade";
@@ -84,16 +93,16 @@ location /stream/ {
 }
 ```
 
-If another proxy sits in front of this one, it needs WebSocket support and
-long timeouts as well. A stream that connects and then immediately fails with
-HTTP 400 usually means a proxy in the chain doesn't pass the WebSocket upgrade.
+If another proxy sits in front of this one, it needs the same. A stream that
+connects and then immediately fails with HTTP 400 usually means a proxy in the
+chain doesn't pass the WebSocket upgrade.
 
 ## Security
 
 The session manager holds the Docker socket, which is effectively root on the
-host. Expose only its `/stream/` port, and only through your proxy. Streamer
-containers run on an internal network with no internet access, reachable only
-from the session manager.
+host. It publishes no ports; only the app reaches it, on the compose network.
+Streamer containers run on an internal network with no internet access,
+reachable only from the session manager.
 
 ## Troubleshooting
 
@@ -110,4 +119,4 @@ from the session manager.
 
   `200` means the game can be streamed; `422` means it can't.
 - **The stream stays black or disconnects at once.** Check that the page is on
-  HTTPS, and that `/stream/` passes WebSocket upgrades.
+  HTTPS, and that your proxy passes WebSocket upgrades.
diff --git a/streaming/streamer/README.md b/streaming/streamer/README.md
index 8f6e9c2..cf45cbf 100644
--- a/streaming/streamer/README.md
+++ b/streaming/streamer/README.md
@@ -12,7 +12,7 @@ application path of `LocalGames\<name>\<game>.exe`.
 A Linux Flashpoint install. The streamer uses the Infinity build's
 `Server/FlashpointGameServer`, `FPSoftware/Java` and `FPSoftware/Wine`, which
 Ultimate's archives only include for Windows.
-`scripts/setup-flashpoint.sh --with-infinity` adds them without overwriting
+`scripts/setup-flashpoint.sh --infinity` adds them without overwriting
 anything.
 
 ## Running one by hand

From 5e7b2bc72ee1a341676b2e036d1f7c660c0f3f2c Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:14:42 -0700
Subject: [PATCH 4/7] ci: publish images from Gitea Actions; make the update
 check opt-in

A Gitea workflow builds the app, session manager and streamer images
and pushes them to the instance's registry on pushes to main and on
version tags, reading the registry host at run time. Compose can pull
them with IMAGE_PREFIX. The update checker reads APP_UPDATE_URL instead
of upstream's GitHub releases and is off without it. Upstream's Docker
Hub workflow is removed.
---
 .env.example                                  |   7 +-
 .gitea/workflows/images.yml                   |  65 ++++++
 .github/workflows/README.md                   | 204 ------------------
 .github/workflows/docker-build-push.yml       | 144 -------------
 backend/src/config.ts                         |   2 +
 backend/src/services/AppUpdateService.test.ts |  25 ++-
 backend/src/services/AppUpdateService.ts      |  22 +-
 docker-compose.yml                            |  12 +-
 .../src/components/settings/AppUpdateCard.tsx |   3 +
 frontend/src/lib/api/updates.ts               |   2 +
 10 files changed, 122 insertions(+), 364 deletions(-)
 create mode 100644 .gitea/workflows/images.yml
 delete mode 100644 .github/workflows/README.md
 delete mode 100644 .github/workflows/docker-build-push.yml

diff --git a/.env.example b/.env.example
index 05dcc5e..019d641 100644
--- a/.env.example
+++ b/.env.example
@@ -10,8 +10,13 @@ JWT_SECRET=replace-with-a-secure-random-string
 # ---------------------------------------------------------------------------
 # Container Images
 # ---------------------------------------------------------------------------
-# Tag for the locally built images
+# Built from source by default. To pull published images instead, set the
+# registry path they live under (ending in /), then:
+#   docker compose pull && docker compose up -d
+# IMAGE_PREFIX=registry.example.com/owner/
 # IMAGE_TAG=latest
+# "Latest release" API URL to check for updates (GitHub or Gitea); off when unset
+# APP_UPDATE_URL=https://git.example.com/api/v1/repos/owner/dotcom-arcade/releases/latest
 
 # ---------------------------------------------------------------------------
 # Port (host mapping)
diff --git a/.gitea/workflows/images.yml b/.gitea/workflows/images.yml
new file mode 100644
index 0000000..f2e36bd
--- /dev/null
+++ b/.gitea/workflows/images.yml
@@ -0,0 +1,65 @@
+# Builds the app, session manager and streamer images and pushes them to this
+# Gitea instance's container registry, under the repository's owner.
+#
+# Needs repository secrets REGISTRY_USERNAME and REGISTRY_TOKEN: a user, and an
+# access token of theirs with package write access.
+name: Images
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*.*.*']
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: dotcom-arcade
+            context: .
+          - image: dotcom-arcade-session-manager
+            context: streaming/session-manager
+          - image: dotcom-arcade-streamer
+            context: streaming/streamer
+    steps:
+      - uses: actions/checkout@v4
+
+      # The registry lives on the same host as this Gitea instance
+      - name: Locate the registry
+        id: registry
+        run: |
+          host=${GITHUB_SERVER_URL#*://}
+          echo "host=${host%/}" >> "$GITHUB_OUTPUT"
+          echo "owner=${GITHUB_REPOSITORY_OWNER,,}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ steps.registry.outputs.host }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ steps.registry.outputs.host }}/${{ steps.registry.outputs.owner }}/${{ matrix.image }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=ref,event=branch
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: ${{ matrix.context }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64
+          build-args: |
+            VERSION=${{ steps.meta.outputs.version }}
+          provenance: false
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
deleted file mode 100644
index 4678e9e..0000000
--- a/.github/workflows/README.md
+++ /dev/null
@@ -1,204 +0,0 @@
-# GitHub Actions Workflows
-
-This directory contains automated workflows for the Flashpoint Web project.
-
-## Workflows
-
-### 1. Docker Build and Push (`docker-build-push.yml`)
-
-Builds and pushes the single Docker image to the container registry.
-
-#### Triggers
-
-- **Version tags** (`v*.*.*`): Builds and pushes the image with version tags and `latest` tag
-- **Manual dispatch**: Can be triggered manually from GitHub Actions tab
-
-#### Image Built
-
-- `flashpoint-web` - Single image serving both the REST API (including game
-  content) and the React web UI
-
-#### Container Registry
-
-The workflow pushes images to **Docker Hub**.
-
-#### Setup Instructions
-
-##### Docker Hub (Required)
-
-1. **Create Docker Hub account** at https://hub.docker.com
-
-2. **Create access token**:
-   - Go to Account Settings → Security → Access Tokens
-   - Click "New Access Token"
-   - Name: "GitHub Actions"
-   - Permissions: Read & Write
-   - Copy the token (you won't see it again!)
-
-3. **Add GitHub Secrets**:
-   - Go to your repository → Settings → Secrets and variables → Actions
-   - Click "New repository secret"
-   - Add two secrets:
-     - `DOCKERHUB_USERNAME`: Your Docker Hub username
-     - `DOCKERHUB_TOKEN`: The access token from step 2
-
-4. **Image will be pushed to**:
-   ```
-   docker.io/darkraise/flashpoint-web:latest
-   ```
-
-#### Image Tags
-
-The workflow automatically creates multiple tags when you push a version tag:
-
-| Tag Type | Example | Description |
-|----------|---------|-------------|
-| `latest` | `latest` | Always created for every version tag |
-| Full version | `1.2.3` | Git tag `v1.2.3` → `1.2.3` |
-| Major.Minor | `1.2` | Git tag `v1.2.3` → `1.2` |
-| Major | `1` | Git tag `v1.2.3` → `1` |
-
-#### Creating a Release
-
-To create a versioned release:
-
-```bash
-# Ensure you're on master branch
-git checkout master
-
-# Tag the commit
-git tag v1.0.0
-
-# Push the tag (this triggers the workflow)
-git push origin v1.0.0
-```
-
-This will create images tagged as:
-- `1.0.0`
-- `1.0`
-- `1`
-- `latest`
-
-#### Platform Support
-
-Images are built for:
-- `linux/amd64` (x86_64) - Standard servers and desktops
-
-**Note:** ARM64 support has been disabled to significantly reduce build times. If you need ARM64 images, you can build them locally or enable multi-platform builds by adding `linux/arm64` to the platforms in the workflow file.
-
-#### Build Caching
-
-The workflow uses GitHub Actions cache to speed up builds:
-- Layer cache stored between runs
-- Significantly faster builds after the first run
-- Cache automatically invalidated when dependencies change
-
-#### Usage Examples
-
-##### Pull and Run the Image
-
-```bash
-# Pull the latest image
-docker pull darkraise/flashpoint-web:latest
-
-# Or use a specific version
-docker pull darkraise/flashpoint-web:1.0.0
-```
-
-##### Use in Docker Compose
-
-Update your `docker-compose.yml` to use the pre-built image:
-
-```yaml
-services:
-  flashpoint-web:
-    image: darkraise/flashpoint-web:latest
-    # Remove build section
-    ports:
-      - "80:3100"
-    # ... rest of config
-```
-
-Then simply run:
-```bash
-docker compose pull  # Pull the latest image
-docker compose up -d # Start the service
-```
-
-#### Making Images Public
-
-By default, Docker Hub images are private. To make them public:
-
-1. Go to https://hub.docker.com/repositories
-2. Click on the repository (e.g., `flashpoint-web`)
-3. Click "Settings"
-4. Change visibility to "Public"
-
-#### Troubleshooting
-
-##### Build Fails
-
-Check the Actions tab for detailed error logs:
-```
-https://github.com/<username>/<repo>/actions
-```
-
-##### Docker Hub Not Pushing
-
-Verify secrets are set correctly:
-- Repository → Settings → Secrets and variables → Actions
-- Check `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` exist
-
-##### Image Not Found
-
-For private images, authenticate first:
-```bash
-docker login docker.io
-```
-
-#### Performance
-
-Typical build times (optimized for amd64 only):
-- First build: 3-5 minutes
-- Subsequent builds (with cache): 1-2 minutes
-- Frontend and backend build stages run within a single image build
-
-**Optimizations applied:**
-- Single platform (amd64) instead of multi-platform
-- npm ci with `--prefer-offline` and `--no-audit` flags
-- Disabled provenance and SBOM generation
-- Latest BuildKit image
-- GitHub Actions cache for Docker layers
-
-#### Security
-
-- Secrets are never exposed in logs
-- Images are scanned for vulnerabilities (optional - can add)
-- Multi-stage builds minimize attack surface
-- Non-root users in all containers
-- Read-only root filesystems where possible
-
----
-
-### 2. Performance Budget (`performance-budget.yml`)
-
-Frontend performance monitoring workflow.
-
-See the workflow file for details.
-
----
-
-## Adding New Workflows
-
-To add a new workflow:
-
-1. Create a new YAML file in `.github/workflows/`
-2. Use the GitHub Actions syntax
-3. Test locally with [act](https://github.com/nektos/act) (optional)
-4. Push to trigger the workflow
-
-## References
-
-- [GitHub Actions Documentation](https://docs.github.com/en/actions)
-- [Docker Build Push Action](https://github.com/docker/build-push-action)
-- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
diff --git a/.github/workflows/docker-build-push.yml b/.github/workflows/docker-build-push.yml
deleted file mode 100644
index 2dc3d92..0000000
--- a/.github/workflows/docker-build-push.yml
+++ /dev/null
@@ -1,144 +0,0 @@
-name: Build and Push Docker Images
-
-on:
-  push:
-    tags:
-      - 'v*.*.*'
-  workflow_dispatch:
-
-env:
-  REGISTRY_DOCKERHUB: docker.io
-
-jobs:
-  build-and-push:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-
-    permissions:
-      contents: read
-
-    outputs:
-      version: ${{ steps.meta.outputs.version }}
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-        with:
-          driver-opts: |
-            image=moby/buildkit:latest
-            network=host
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY_DOCKERHUB }}
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Extract metadata (tags, labels)
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY_DOCKERHUB }}/${{ secrets.DOCKERHUB_USERNAME }}/flashpoint-web
-          tags: |
-            # Tag with full version (v1.0.0 -> 1.0.0)
-            type=semver,pattern={{version}}
-            # Tag with major.minor (v1.0.0 -> 1.0)
-            type=semver,pattern={{major}}.{{minor}}
-            # Tag with major version (v1.0.0 -> 1)
-            type=semver,pattern={{major}}
-            # Latest tag
-            type=raw,value=latest
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=flashpoint-web
-          cache-to: type=gha,scope=flashpoint-web,mode=max
-          platforms: linux/amd64
-          build-args: |
-            BUILD_DATE=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
-            VCS_REF=${{ github.sha }}
-            VERSION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] }}
-          provenance: false
-          sbom: false
-
-  summary:
-    needs: build-and-push
-    runs-on: ubuntu-latest
-    if: always()
-    steps:
-      - name: Build Summary
-        run: |
-          echo "## Docker Build Summary" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Image Built:" >> $GITHUB_STEP_SUMMARY
-          echo "- \`flashpoint-web\` (API + UI)" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Registry:" >> $GITHUB_STEP_SUMMARY
-          echo "- Docker Hub: \`${{ secrets.DOCKERHUB_USERNAME }}/flashpoint-web\`" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Pull Command:" >> $GITHUB_STEP_SUMMARY
-          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
-          echo "docker pull ${{ secrets.DOCKERHUB_USERNAME }}/flashpoint-web:latest" >> $GITHUB_STEP_SUMMARY
-          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
-
-  create-release:
-    needs: build-and-push
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/v')
-
-    permissions:
-      contents: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Get version from tag
-        id: version
-        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-
-      - name: Generate release notes
-        id: release-notes
-        run: |
-          # Get the previous tag
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-
-          echo "## Docker Image" >> release_notes.md
-          echo "" >> release_notes.md
-          echo "Pull the image from Docker Hub:" >> release_notes.md
-          echo "" >> release_notes.md
-          echo "\`\`\`bash" >> release_notes.md
-          echo "docker pull ${{ secrets.DOCKERHUB_USERNAME }}/flashpoint-web:${{ steps.version.outputs.version }}" >> release_notes.md
-          echo "\`\`\`" >> release_notes.md
-          echo "" >> release_notes.md
-
-          if [ -n "$PREV_TAG" ]; then
-            echo "## Changes since $PREV_TAG" >> release_notes.md
-            echo "" >> release_notes.md
-            git log --pretty=format:"- %s (%h)" $PREV_TAG..HEAD >> release_notes.md
-            echo "" >> release_notes.md
-          fi
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: ${{ steps.version.outputs.version }}
-          name: Release ${{ steps.version.outputs.version }}
-          body_path: release_notes.md
-          draft: false
-          prerelease: ${{ contains(steps.version.outputs.version, '-') }}
-          generate_release_notes: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/backend/src/config.ts b/backend/src/config.ts
index 3f32282..71822bd 100644
--- a/backend/src/config.ts
+++ b/backend/src/config.ts
@@ -210,6 +210,8 @@ export const config = {
   // marks the build as unreleased. `||` is deliberate: a whitespace-only value
   // must collapse to null, which `??` would not do.
   appVersion: process.env.APP_VERSION?.trim() || null,
+  // A GitHub- or Gitea-style "latest release" API URL; update checks are off without it
+  appUpdateUrl: process.env.APP_UPDATE_URL?.trim() || null,
 } as const;
 
 /** Resolves external image CDN URLs from Flashpoint preferences, with hardcoded fallbacks. */
diff --git a/backend/src/services/AppUpdateService.test.ts b/backend/src/services/AppUpdateService.test.ts
index 49f046d..8116c7c 100644
--- a/backend/src/services/AppUpdateService.test.ts
+++ b/backend/src/services/AppUpdateService.test.ts
@@ -4,7 +4,15 @@ vi.mock('../utils/logger', () => ({
   logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
 }));
 
-const configMock = vi.hoisted(() => ({ config: { appVersion: '1.0.38' as string | null } }));
+const RELEASE_URL = 'https://git.example.com/api/v1/repos/owner/dotcom-arcade/releases/latest';
+const configMock = vi.hoisted(() => ({
+  config: {
+    appVersion: '1.0.38' as string | null,
+    appUpdateUrl: 'https://git.example.com/api/v1/repos/owner/dotcom-arcade/releases/latest' as
+      | string
+      | null,
+  },
+}));
 vi.mock('../config', () => configMock);
 
 vi.mock('axios', () => ({
@@ -20,7 +28,7 @@ function release(tagName: string) {
     data: {
       tag_name: tagName,
       published_at: '2026-08-12T07:11:45Z',
-      html_url: `https://github.com/darkraise/flashpoint-web/releases/tag/${tagName}`,
+      html_url: `https://git.example.com/owner/dotcom-arcade/releases/tag/${tagName}`,
       body: '## Changes since v1.0.37\n\n- feat: something',
     },
   };
@@ -30,6 +38,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   AppUpdateService.clearCache();
   configMock.config.appVersion = '1.0.38';
+  configMock.config.appUpdateUrl = RELEASE_URL;
 });
 
 describe('AppUpdateService.getUpdateInfo', () => {
@@ -105,10 +114,20 @@ describe('AppUpdateService.getUpdateInfo', () => {
     await AppUpdateService.getUpdateInfo();
 
     expect(axios.get).toHaveBeenCalledWith(
-      'https://api.github.com/repos/darkraise/flashpoint-web/releases/latest',
+      RELEASE_URL,
       expect.objectContaining({ timeout: 10000 })
     );
   });
+
+  it('checks nothing when no release source is configured', async () => {
+    configMock.config.appUpdateUrl = null;
+
+    const info = await AppUpdateService.getUpdateInfo(true);
+
+    expect(axios.get).not.toHaveBeenCalled();
+    expect(info.enabled).toBe(false);
+    expect(info.updateAvailable).toBe(false);
+  });
 });
 
 describe('AppUpdateService caching', () => {
diff --git a/backend/src/services/AppUpdateService.ts b/backend/src/services/AppUpdateService.ts
index e19cca2..37efe74 100644
--- a/backend/src/services/AppUpdateService.ts
+++ b/backend/src/services/AppUpdateService.ts
@@ -3,12 +3,13 @@ import { config } from '../config';
 import { logger } from '../utils/logger';
 import { compareVersions, isReleaseVersion, normalizeVersion } from '../utils/version';
 
-const LATEST_RELEASE_URL = 'https://api.github.com/repos/darkraise/flashpoint-web/releases/latest';
 const CACHE_TTL_MS = 60 * 60 * 1000;
 const FORCED_REFRESH_FLOOR_MS = 60 * 1000;
 const REQUEST_TIMEOUT_MS = 10000;
 
 export interface AppUpdateInfo {
+  /** False when no release source is configured (APP_UPDATE_URL) */
+  enabled: boolean;
   currentVersion: string | null;
   latestVersion: string | null;
   updateAvailable: boolean;
@@ -28,7 +29,8 @@ interface CachedRelease {
   fetchedAt: number;
 }
 
-interface GitHubRelease {
+/** The fields GitHub's and Gitea's release APIs have in common */
+interface Release {
   tag_name?: unknown;
   published_at?: unknown;
   html_url?: unknown;
@@ -50,6 +52,9 @@ export class AppUpdateService {
   private static lastFailedAt: number | null = null;
 
   static async getUpdateInfo(force = false): Promise<AppUpdateInfo> {
+    if (config.appUpdateUrl === null) {
+      return this.buildInfo();
+    }
     // A forced check still respects a 60s floor. Express rate limiting allows
     // 100 requests a minute, which is no protection for a GitHub quota of 60 an
     // hour that this shares with the star count and the Ruffle update check.
@@ -69,7 +74,7 @@ export class AppUpdateService {
       } catch (error: unknown) {
         this.lastCheckFailed = true;
         this.lastFailedAt = Date.now();
-        logger.warn('[AppUpdate] Could not reach GitHub for the latest release', {
+        logger.warn('[AppUpdate] Could not fetch the latest release', {
           error: error instanceof Error ? error.message : 'Unknown error',
         });
       }
@@ -96,19 +101,19 @@ export class AppUpdateService {
   }
 
   private static async requestLatestRelease(): Promise<CachedRelease> {
-    const response = await axios.get(LATEST_RELEASE_URL, {
+    const response = await axios.get(config.appUpdateUrl ?? '', {
       timeout: REQUEST_TIMEOUT_MS,
       headers: {
-        Accept: 'application/vnd.github.v3+json',
-        'User-Agent': 'Flashpoint-Web',
+        Accept: 'application/json',
+        'User-Agent': 'Dotcom-Arcade',
       },
     });
 
-    const release = (response.data ?? {}) as GitHubRelease;
+    const release = (response.data ?? {}) as Release;
     const tagName = asString(release.tag_name);
 
     if (tagName === null) {
-      throw new Error('GitHub release response carried no tag_name');
+      throw new Error('Release response carried no tag_name');
     }
 
     return {
@@ -131,6 +136,7 @@ export class AppUpdateService {
         : null;
 
     return {
+      enabled: config.appUpdateUrl !== null,
       currentVersion,
       latestVersion: latest?.version ?? null,
       updateAvailable: comparison !== null && comparison < 0,
diff --git a/docker-compose.yml b/docker-compose.yml
index 8efaae4..f1abd41 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,6 +8,8 @@
 # Usage:
 #   1. Copy .env.example to .env and set the required variables
 #   2. docker compose up -d --build
+#      (or, with IMAGE_PREFIX set to a registry's images:
+#      docker compose pull && docker compose up -d)
 #   3. For streaming, set STREAMING_API_TOKEN and COMPOSE_PROFILES=streaming in
 #      .env, then run `docker compose up -d --build` again
 #
@@ -18,7 +20,7 @@
 services:
   app:
     build: .
-    image: dotcom-arcade:${IMAGE_TAG:-latest}
+    image: ${IMAGE_PREFIX:-}dotcom-arcade:${IMAGE_TAG:-latest}
     container_name: dotcom-arcade
     restart: unless-stopped
     ports:
@@ -55,6 +57,8 @@ services:
       - RATE_LIMIT_MAX_REQUESTS=${RATE_LIMIT_MAX_REQUESTS:-100}
       # Application
       - HOME_RECENT_HOURS=${HOME_RECENT_HOURS:-24}
+      # "Latest release" API URL (GitHub or Gitea) for update checks; off when unset
+      - APP_UPDATE_URL=${APP_UPDATE_URL:-}
       - ENABLE_CGI=${ENABLE_CGI:-false}
       # Streamed play for games that can't run in a browser (off unless the token is set)
       - STREAMING_API_URL=${STREAMING_API_URL:-http://session-manager:8080}
@@ -102,7 +106,7 @@ services:
   session-manager:
     profiles: [streaming]
     build: streaming/session-manager
-    image: dotcom-arcade-session-manager:${IMAGE_TAG:-latest}
+    image: ${IMAGE_PREFIX:-}dotcom-arcade-session-manager:${IMAGE_TAG:-latest}
     container_name: dotcom-arcade-session-manager
     restart: unless-stopped
     volumes:
@@ -114,7 +118,7 @@ services:
       - FLASHPOINT_HOST_PATH
       # The session manager refuses to start without it
       - API_TOKEN=${STREAMING_API_TOKEN:-}
-      - STREAMER_IMAGE=dotcom-arcade-streamer:${IMAGE_TAG:-latest}
+      - STREAMER_IMAGE=${IMAGE_PREFIX:-}dotcom-arcade-streamer:${IMAGE_TAG:-latest}
       - STREAMER_NETWORK=dotcom-arcade-streams
       - MAX_SESSIONS=${MAX_SESSIONS:-4}
       - STREAM_PLATFORMS=${STREAM_PLATFORMS:-Java,Shockwave,Flash}
@@ -128,7 +132,7 @@ services:
   streamer:
     profiles: [streaming]
     build: streaming/streamer
-    image: dotcom-arcade-streamer:${IMAGE_TAG:-latest}
+    image: ${IMAGE_PREFIX:-}dotcom-arcade-streamer:${IMAGE_TAG:-latest}
     scale: 0
 
 networks:
diff --git a/frontend/src/components/settings/AppUpdateCard.tsx b/frontend/src/components/settings/AppUpdateCard.tsx
index ee26434..d5be374 100644
--- a/frontend/src/components/settings/AppUpdateCard.tsx
+++ b/frontend/src/components/settings/AppUpdateCard.tsx
@@ -73,6 +73,9 @@ export function AppUpdateCard() {
     setShowChangelog(true);
   }
 
+  // Without a release source (APP_UPDATE_URL) there is nothing to check
+  if (info?.enabled === false) return null;
+
   const checkFailedEntirely =
     isLoadingError || (info?.lastCheckFailed === true && info.latestVersion === null);
   const currentVersionMatchesLatest = info
diff --git a/frontend/src/lib/api/updates.ts b/frontend/src/lib/api/updates.ts
index 5936503..fc5f1a3 100644
--- a/frontend/src/lib/api/updates.ts
+++ b/frontend/src/lib/api/updates.ts
@@ -38,6 +38,8 @@ export interface AssetDownloadProgress {
 }
 
 export interface AppUpdateInfo {
+  /** False when the server has no release source configured */
+  enabled: boolean;
   currentVersion: string | null;
   latestVersion: string | null;
   updateAvailable: boolean;

From cd1d7fbb35002d70c322115950a19097cf6a49bb Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:19:34 -0700
Subject: [PATCH 5/7] chore: remove leftovers from upstream

Drops the /flash and /html5 sections (old URLs redirect to /browse),
the GitHub star count endpoint, the unused HOME_RECENT_HOURS setting,
upstream's design notes and code review docs, and the issue template's
link to upstream discussions.
---
 .env.example                                  |    1 -
 .github/ISSUE_TEMPLATE/config.yml             |    3 -
 CLAUDE.md                                     |    7 +-
 backend/.env.example                          |    1 -
 backend/src/config.ts                         |    2 -
 backend/src/routes/github.ts                  |   56 -
 backend/src/routes/index.ts                   |    2 -
 backend/src/routes/system-settings.ts         |    5 -
 backend/src/routes/updates.test.ts            |    2 +-
 backend/src/services/AppUpdateService.ts      |    6 +-
 docker-compose.yml                            |    1 -
 docs/04-frontend/architecture.md              |    4 +-
 .../components/layout-components.md           |   16 +-
 docs/04-frontend/views-routing.md             |   29 +-
 docs/06-api-reference/README.md               |    1 -
 docs/06-api-reference/admin-api.md            |   13 -
 docs/09-deployment/environment-variables.md   |    1 -
 .../games-filter-panel-review.md              |  328 ----
 .../plans/2026-08-11-downloaded-games.md      | 1382 -----------------
 .../plans/2026-08-12-web-app-update.md        | 1183 --------------
 .../2026-08-13-ruffle-persistent-install.md   |  798 ----------
 .../2026-08-11-downloaded-games-design.md     |  184 ---
 .../specs/2026-08-12-web-app-update-design.md |  234 ---
 ...-08-13-ruffle-persistent-install-design.md |  131 --
 frontend/src/App.tsx                          |   76 +-
 .../components/library/GameBrowseLayout.tsx   |    2 +-
 frontend/src/components/library/GameCard.tsx  |    2 +-
 frontend/src/components/library/GameGrid.tsx  |    2 +-
 frontend/src/components/library/GameList.tsx  |    2 +-
 .../src/components/library/GameListItem.tsx   |    2 +-
 frontend/src/lib/sectionRoutes.ts             |   32 +-
 frontend/src/test/mocks/handlers.ts           |    1 -
 frontend/src/types/settings.ts                |    6 +-
 frontend/src/views/FlashGamesView.tsx         |   13 -
 frontend/src/views/HTML5GamesView.tsx         |   13 -
 35 files changed, 40 insertions(+), 4501 deletions(-)
 delete mode 100644 backend/src/routes/github.ts
 delete mode 100644 docs/13-code-reviews/games-filter-panel-review.md
 delete mode 100644 docs/superpowers/plans/2026-08-11-downloaded-games.md
 delete mode 100644 docs/superpowers/plans/2026-08-12-web-app-update.md
 delete mode 100644 docs/superpowers/plans/2026-08-13-ruffle-persistent-install.md
 delete mode 100644 docs/superpowers/specs/2026-08-11-downloaded-games-design.md
 delete mode 100644 docs/superpowers/specs/2026-08-12-web-app-update-design.md
 delete mode 100644 docs/superpowers/specs/2026-08-13-ruffle-persistent-install-design.md
 delete mode 100644 frontend/src/views/FlashGamesView.tsx
 delete mode 100644 frontend/src/views/HTML5GamesView.tsx

diff --git a/.env.example b/.env.example
index 019d641..9083283 100644
--- a/.env.example
+++ b/.env.example
@@ -105,7 +105,6 @@ ENABLE_CACHE_PREWARM=true
 # ---------------------------------------------------------------------------
 # Application
 # ---------------------------------------------------------------------------
-# HOME_RECENT_HOURS=24
 # ENABLE_CGI=false
 # Streamed play for games that can't run in a browser (Java, Shockwave, the
 # original Flash Player, Windows games). Set a token (e.g. `openssl rand -hex 32`)
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 2109efa..e539373 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,5 @@
 blank_issues_enabled: true
 contact_links:
-  - name: Ask a Question
-    url: https://github.com/darkraise/flashpoint-web/discussions
-    about: Use Discussions for questions, help, and general conversation
   - name: Flashpoint Archive
     url: https://github.com/FlashpointProject
     about: For issues with Flashpoint itself (not this web interface)
diff --git a/CLAUDE.md b/CLAUDE.md
index b08cec0..7232ae0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1193,13 +1193,8 @@ Before submitting code, verify:
 ## Environment
 
 ```bash
-FLASHPOINT_PATH=D:/Flashpoint   # Required - path to Flashpoint installation
+FLASHPOINT_PATH=/path/to/flashpoint   # Required - path to Flashpoint installation
 JWT_SECRET=your-secret          # Required - random string for JWT signing
 DOMAIN=http://localhost:5173    # Optional - frontend URL for CORS
 LOG_LEVEL=info                  # Optional - debug, info, warn, error
 ```
-
-## Source References
-
-- Flashpoint Launcher: `D:\Repositories\Community\launcher`
-- Flashpoint Game Server: `D:\Repositories\Community\FlashpointGameServer`
diff --git a/backend/.env.example b/backend/.env.example
index de0e0e3..6e79ec5 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -22,7 +22,6 @@ BCRYPT_SALT_ROUNDS=10
 # ENABLE_CGI=false
 
 # Misc
-HOME_RECENT_HOURS=24
 
 # ---------------------------------------------------------------------------
 # Database Performance Optimization (for network storage)
diff --git a/backend/src/config.ts b/backend/src/config.ts
index 71822bd..b3fc24e 100644
--- a/backend/src/config.ts
+++ b/backend/src/config.ts
@@ -167,8 +167,6 @@ export const config = {
 
   bcryptSaltRounds: parseInt(process.env.BCRYPT_SALT_ROUNDS || '', 10) || 10,
 
-  homeRecentHours: parseInt(process.env.HOME_RECENT_HOURS || '', 10) || 24,
-
   // Session manager that streams games which can't run in a browser, such as
   // Java applets (flashpoint-ultimate-server). Streaming is off unless both are set.
   streamingApiUrl: process.env.STREAMING_API_URL || null,
diff --git a/backend/src/routes/github.ts b/backend/src/routes/github.ts
deleted file mode 100644
index a426283..0000000
--- a/backend/src/routes/github.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { Router, Request, Response } from 'express';
-import { logger } from '../utils/logger';
-import { asyncHandler } from '../middleware/asyncHandler';
-
-const router = Router();
-
-// In-memory cache for GitHub star count (avoid hitting 60/hr unauthenticated rate limit)
-let cachedStars: { count: number; fetchedAt: number } | null = null;
-const CACHE_TTL_MS = 15 * 60 * 1000;
-
-// Proxy to avoid browser CORS issues with GitHub API
-router.get(
-  '/stars',
-  asyncHandler(async (_req: Request, res: Response) => {
-    if (cachedStars && Date.now() - cachedStars.fetchedAt < CACHE_TTL_MS) {
-      return res.json({
-        success: true,
-        data: { stars: cachedStars.count },
-      });
-    }
-
-    const repoUrl = 'https://api.github.com/repos/darkraise/flashpoint-web';
-
-    const response = await fetch(repoUrl, {
-      headers: {
-        Accept: 'application/vnd.github.v3+json',
-        'User-Agent': 'Flashpoint-Web-App',
-      },
-    });
-
-    if (!response.ok) {
-      // If rate-limited and we have a stale cache, return it
-      if (cachedStars) {
-        logger.debug('[GitHub] Rate limited, returning stale cache');
-        return res.json({
-          success: true,
-          data: { stars: cachedStars.count },
-        });
-      }
-      throw new Error(`GitHub API error: ${response.status}`);
-    }
-
-    const data = (await response.json()) as { stargazers_count: number };
-
-    cachedStars = { count: data.stargazers_count, fetchedAt: Date.now() };
-
-    res.json({
-      success: true,
-      data: {
-        stars: data.stargazers_count,
-      },
-    });
-  })
-);
-
-export default router;
diff --git a/backend/src/routes/index.ts b/backend/src/routes/index.ts
index d8c242c..32524e9 100644
--- a/backend/src/routes/index.ts
+++ b/backend/src/routes/index.ts
@@ -25,7 +25,6 @@ import ratingsRouter from './ratings';
 import gameSavesRouter from './game-saves';
 import discoveryRouter from './discovery';
 import ruffleRouter from './ruffle';
-import githubRouter from './github';
 import domainsRouter from './domains';
 import healthRouter from './health';
 import cacheRouter from './cache';
@@ -40,7 +39,6 @@ export function setupRoutes(app: Express): void {
   app.use('/api/settings/auth', authSettingsRouter);
   app.use('/api/settings', systemSettingsRouter);
   app.use('/api/ruffle', ruffleRouter);
-  app.use('/api/github', githubRouter);
   app.use('/api/domains', domainsRouter);
   app.use('/api/jobs', jobsRouter);
   app.use('/api/users', usersRouter);
diff --git a/backend/src/routes/system-settings.ts b/backend/src/routes/system-settings.ts
index b3afd0e..1044173 100644
--- a/backend/src/routes/system-settings.ts
+++ b/backend/src/routes/system-settings.ts
@@ -80,11 +80,6 @@ router.get(
       Record<string, unknown>
     > = systemSettings.getPublicSettings();
 
-    if (!publicSettings.app) {
-      publicSettings.app = {};
-    }
-    publicSettings.app.homeRecentHours = config.homeRecentHours;
-
     // Inject edition/version from config (auto-detected from version.txt, not stored in DB)
     if (!publicSettings.metadata) {
       publicSettings.metadata = {};
diff --git a/backend/src/routes/updates.test.ts b/backend/src/routes/updates.test.ts
index c51e819..1c47ed2 100644
--- a/backend/src/routes/updates.test.ts
+++ b/backend/src/routes/updates.test.ts
@@ -51,7 +51,7 @@ const INFO = {
   updateAvailable: true,
   isUnreleasedBuild: false,
   publishedAt: '2026-08-12T07:11:45Z',
-  releaseUrl: 'https://github.com/darkraise/flashpoint-web/releases/tag/v1.0.42',
+  releaseUrl: 'https://git.example.com/owner/dotcom-arcade/releases/tag/v1.0.42',
   changelog: '## Changes',
   checkedAt: '2026-08-12T08:00:00.000Z',
   lastCheckFailed: false,
diff --git a/backend/src/services/AppUpdateService.ts b/backend/src/services/AppUpdateService.ts
index 37efe74..b1cc3ad 100644
--- a/backend/src/services/AppUpdateService.ts
+++ b/backend/src/services/AppUpdateService.ts
@@ -56,12 +56,12 @@ export class AppUpdateService {
       return this.buildInfo();
     }
     // A forced check still respects a 60s floor. Express rate limiting allows
-    // 100 requests a minute, which is no protection for a GitHub quota of 60 an
-    // hour that this shares with the star count and the Ruffle update check.
+    // 100 requests a minute, which is no protection for a release API's quota
+    // (GitHub allows 60 an hour, shared with the Ruffle update check).
     const maxAge = force ? FORCED_REFRESH_FLOOR_MS : CACHE_TTL_MS;
     const age = this.cached === null ? Infinity : Date.now() - this.cached.fetchedAt;
     // A failure also respects the 60s floor, even when force is true, so a
-    // GitHub outage or rate limit can't be hammered every request while it
+    // source's outage or rate limit can't be hammered every request while it
     // still shares the API's blocking timeout with each caller.
     const failureAge = this.lastFailedAt === null ? Infinity : Date.now() - this.lastFailedAt;
     const withinFailureFloor = failureAge < FORCED_REFRESH_FLOOR_MS;
diff --git a/docker-compose.yml b/docker-compose.yml
index f1abd41..003ecfc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -56,7 +56,6 @@ services:
       - RATE_LIMIT_WINDOW_MS=${RATE_LIMIT_WINDOW_MS:-60000}
       - RATE_LIMIT_MAX_REQUESTS=${RATE_LIMIT_MAX_REQUESTS:-100}
       # Application
-      - HOME_RECENT_HOURS=${HOME_RECENT_HOURS:-24}
       # "Latest release" API URL (GitHub or Gitea) for update checks; off when unset
       - APP_UPDATE_URL=${APP_UPDATE_URL:-}
       - ENABLE_CGI=${ENABLE_CGI:-false}
diff --git a/docs/04-frontend/architecture.md b/docs/04-frontend/architecture.md
index 5c41721..07b2603 100644
--- a/docs/04-frontend/architecture.md
+++ b/docs/04-frontend/architecture.md
@@ -205,9 +205,9 @@ Routes are defined in `App.tsx` with nested routing structure:
     <AppShell>
       <Routes>
         {/* Public routes */}
-        <Route path="/flash-games" element={
+        <Route path="/browse" element={
           <ProtectedRoute requireAuth={false}>
-            <FlashGamesView />
+            <BrowseView />
           </ProtectedRoute>
         } />
 
diff --git a/docs/04-frontend/components/layout-components.md b/docs/04-frontend/components/layout-components.md
index f13e039..945ff9e 100644
--- a/docs/04-frontend/components/layout-components.md
+++ b/docs/04-frontend/components/layout-components.md
@@ -286,16 +286,7 @@ interface SidebarProps {
 
 ```typescript
 const gameNavItems: NavItem[] = [
-  {
-    path: '/flash-games',
-    iconImage: '/images/Flash.png',
-    label: 'Flash Games',
-  },
-  {
-    path: '/html5-games',
-    iconImage: '/images/HTML5.png',
-    label: 'HTML5 Games',
-  },
+  { path: '/', icon: Home, label: 'Home' },
   { path: '/animations', icon: Film, label: 'Animations' },
   { path: '/browse', icon: Gamepad2, label: 'Browse' },
 ];
@@ -360,11 +351,6 @@ const isNavItemActive = (item: NavItem) => {
     );
   }
 
-  // Special case: Home (/) should highlight Flash Games
-  if (location.pathname === '/' && itemPath === '/flash-games') {
-    return true;
-  }
-
   return location.pathname === itemPath;
 };
 ```
diff --git a/docs/04-frontend/views-routing.md b/docs/04-frontend/views-routing.md
index 1314492..71e2423 100644
--- a/docs/04-frontend/views-routing.md
+++ b/docs/04-frontend/views-routing.md
@@ -6,24 +6,24 @@ Dotcom Arcade frontend.
 ## Route Structure
 
 ```
-/                         → Redirects to /flash-games
+/                         → HomeView (discovery homepage)
 /login                    → LoginView (no auth required)
 /register                 → RegisterView (no auth required)
 /unauthorized             → UnauthorizedView
 
 # Game Views (Public/Guest Accessible)
-/flash-games              → FlashGamesView
-/html5-games              → HTML5GamesView
 /browse                   → BrowseView
 /animations               → AnimationsView
-/games/:id                → GameDetailView
+/browse/:id               → GamePage (also /animations/:id, /games/:id)
+/flash/*, /html5/*        → Redirect to the same path under /browse
 
 # Protected Routes (Auth Required)
-/games/:id/play           → GamePlayerView (requires "games.play" permission)
+/browse/:id/play          → GamePage, game started (requires "games.play")
 /dashboard                → DashboardView
 /favorites                → FavoritesView
-/playlists                → PlaylistsView
-/playlists/:id            → PlaylistDetailView
+/playlists                → UserPlaylistsView
+/playlists/:id            → UserPlaylistDetailView
+/flashpoint-playlists     → PlaylistsView
 /settings                 → SettingsView
 
 # Admin Routes (Permission-Based)
@@ -91,17 +91,6 @@ interface ProtectedRouteProps {
 
 ## Key Views
 
-### FlashGamesView / HTML5GamesView
-
-Pre-filtered game browsing views.
-
-**Features:**
-
-- Platform-specific filtering
-- Grid/List view toggle
-- Pagination
-- Add to favorites/playlists
-
 ### BrowseView
 
 Main game browsing view with full filtering.
@@ -191,9 +180,9 @@ Routes are configured in `App.tsx`:
     <AppShell>
       <Routes>
         {/* Public routes */}
-        <Route path="/flash-games" element={
+        <Route path="/browse" element={
           <ProtectedRoute requireAuth={false}>
-            <FlashGamesView />
+            <BrowseView />
           </ProtectedRoute>
         } />
 
diff --git a/docs/06-api-reference/README.md b/docs/06-api-reference/README.md
index 372058a..0780412 100644
--- a/docs/06-api-reference/README.md
+++ b/docs/06-api-reference/README.md
@@ -202,7 +202,6 @@ Default: 100 requests per 15 minutes. Headers: `X-RateLimit-Limit`,
 - [GET /api/metrics/summary](./admin-api.md#get-metrics-summary)
 - [GET /api/metrics/endpoints](./admin-api.md#get-endpoint-metrics)
 - [GET /api/jobs](./admin-api.md#list-all-jobs)
-- [GET /api/github/stars](./admin-api.md#get-github-star-count)
 - [GET /api/settings/auth](./admin-api.md#get-auth-settings)
 - [PATCH /api/settings/auth](./admin-api.md#update-auth-settings)
 - [GET /game-files/\*](./admin-api.md#get-game-file)
diff --git a/docs/06-api-reference/admin-api.md b/docs/06-api-reference/admin-api.md
index 70d9110..e862adf 100644
--- a/docs/06-api-reference/admin-api.md
+++ b/docs/06-api-reference/admin-api.md
@@ -213,19 +213,6 @@ Returns `202 Accepted`
 
 Returns progress percentage, stage, estimated completion time.
 
-## GitHub Endpoints
-
-### Get GitHub Star Count
-
-`GET /api/github/stars` - No auth required
-
-```json
-{
-  "success": true,
-  "data": { "stars": 2847 }
-}
-```
-
 ## Statistics Endpoints
 
 ### Get Archive Statistics
diff --git a/docs/09-deployment/environment-variables.md b/docs/09-deployment/environment-variables.md
index b8a080f..2ef3e62 100644
--- a/docs/09-deployment/environment-variables.md
+++ b/docs/09-deployment/environment-variables.md
@@ -103,7 +103,6 @@ Two notes that save debugging time:
 | Variable             | Default | Description                                      |
 | -------------------- | ------- | ------------------------------------------------ |
 | `ENABLE_CGI`         | false   | Enable PHP CGI execution for legacy game content |
-| `HOME_RECENT_HOURS`  | 24      | Hours to look back for "recently added" games    |
 
 **Frontend Serving:**
 
diff --git a/docs/13-code-reviews/games-filter-panel-review.md b/docs/13-code-reviews/games-filter-panel-review.md
deleted file mode 100644
index 127c09b..0000000
--- a/docs/13-code-reviews/games-filter-panel-review.md
+++ /dev/null
@@ -1,328 +0,0 @@
-# Games Filter Panel & Filter Logic - Code Review
-
-**Date:** 2026-02-15
-**Reviewer:** Claude
-**Status:** Review Complete
-
-## Overview
-
-The filter system spans frontend components, hooks, API layer, and backend services. Overall, the implementation is solid with good patterns like config-driven rendering and proper caching. However, there are several issues and improvement opportunities.
-
-## Files Reviewed
-
-### Frontend Components
-- `frontend/src/components/search/FilterPanel.tsx`
-- `frontend/src/components/search/FilterDropdown.tsx`
-- `frontend/src/components/search/FilterChips.tsx`
-- `frontend/src/components/search/filterConfig.ts`
-- `frontend/src/components/search/SearchBar.tsx`
-- `frontend/src/components/search/SortControls.tsx`
-- `frontend/src/components/library/GameBrowseLayout.tsx`
-
-### Frontend Hooks & Types
-- `frontend/src/hooks/useGames.ts`
-- `frontend/src/hooks/useFilterOptions.ts`
-- `frontend/src/hooks/useFilterDropdowns.ts`
-- `frontend/src/types/game.ts`
-- `frontend/src/lib/api/games.ts`
-
-### Backend
-- `backend/src/routes/games.ts`
-- `backend/src/services/GameService.ts`
-
----
-
-## Issues Found
-
-### 1. Type Safety Issues
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `FilterPanel.tsx:22-23` | Unsafe `split()` on potentially undefined value | Medium |
-| `GameBrowseLayout.tsx:72` | Type assertion `as 'asc' | 'desc'` without validation | Medium |
-| `FilterDropdown.tsx:42` | No validation that `selectedValues` array items exist in `options` | Low |
-
-```typescript
-// FilterPanel.tsx:22-23 - currentValue could be number/undefined for yearFrom/yearTo
-const current = typeof currentValue === 'string' ? currentValue.split(',').filter(Boolean) : [];
-// This works but paramKey includes non-string fields (yearFrom, yearTo, page, limit)
-```
-
-### 2. Missing Year Range Filter in UI
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `filterConfig.ts` | `yearFrom`/`yearTo` filters defined in `GameFilters` but not exposed in UI | Medium |
-| `FilterPanel.tsx` | No year range slider or inputs despite backend support | Medium |
-
-The `FilterOptions.yearRange` is fetched but never used - users cannot filter by release year.
-
-### 3. Inconsistent Filter Chips Implementation
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `FilterPanel.tsx:105-140` | `renderFilterBadges()` duplicates logic already in `FilterChips.tsx` | Low |
-| `GameBrowseLayout.tsx:110-198` | Separate filter chip generation vs `FilterChips` component | Low |
-
-Two different chip rendering systems exist:
-- `FilterPanel.tsx` renders inline badges
-- `GameBrowseLayout.tsx` creates `FilterChip[]` array for `FilterChips` component
-
-### 4. Performance: Redundant Handlers Recreation
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `FilterPanel.tsx:68-74` | `createFilterHandlers()` called on every render for every filter | Low |
-| `FilterPanel.tsx:113-119` | Same handlers recreated in `renderFilterBadges()` | Low |
-
-```typescript
-// Called inside map() on every render
-const handlers = createFilterHandlers(
-  config.paramKey,
-  config.id,
-  filters,
-  updateFilter,
-  dropdowns
-);
-```
-
-### 5. Missing Search Debouncing in SearchBar
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `SearchBar.tsx:10-15` | No debounce - navigates immediately on form submit | Low |
-| N/A | No "search as you type" with debounce option | Enhancement |
-
-### 6. Backend: Filter Options Limit Inconsistency
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `GameService.ts:706-707` | Series limited to 100 | Low |
-| `GameService.ts:730-731` | Developers limited to 100 | Low |
-| `GameService.ts:780-781` | Play modes NOT limited | Inconsistent |
-| `GameService.ts:849` | Tags limited to 100 | Low |
-
-Play modes query lacks `LIMIT 100` that other filter queries have.
-
-### 7. Missing Input Validation on Frontend
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `GameBrowseLayout.tsx:72` | `page` parsed without `isNaN()` check | Medium |
-| `GameBrowseLayout.tsx:58-68` | Year parsing validates `isNaN()` - good! | N/A |
-
-```typescript
-// Line 72 - could pass NaN to API
-page: parseInt(searchParams.get('page') || '1', 10),
-```
-
-### 8. URL Encoding Issues
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `GameBrowseLayout.tsx:134` | `encodeURIComponent()` used for chip IDs but inconsistent | Low |
-| `FilterPanel.tsx:125` | Badge key uses raw `value` - may have special chars | Low |
-
-```typescript
-// Line 125 - key should be encoded for consistency
-<Badge key={value} variant="secondary" className="gap-1">
-```
-
-### 9. Missing Error Boundary for Filter Options
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `useFilterOptions.ts` | No `onError` handler | Low |
-| `FilterPanel.tsx:79` | Falls back to empty array `|| []` but no loading state | Low |
-
-If filter options fail to load, dropdowns show "No options available" with no retry mechanism.
-
-### 10. Accessibility Issues
-
-| Location | Issue | Severity |
-|----------|-------|----------|
-| `SortControls.tsx:26` | Native `<select>` used without styling wrapper | Low |
-| `FilterDropdown.tsx:103` | `<label>` wraps checkbox - good | N/A |
-| `SortControls.tsx:35-45` | Sort order button shows "A-Z/Z-A" but not meaningful for dates | Medium |
-
-```typescript
-// "A-Z" / "Z-A" makes sense for title, not for dateAdded
-<span className="ml-1 text-xs">{sortOrder === 'asc' ? 'A-Z' : 'Z-A'}</span>
-```
-
----
-
-## Improvements Recommended
-
-### High Priority
-
-1. **Add Year Range Filter UI**
-   - Add a dual-handle range slider component
-   - Use `yearRange` from `FilterOptions`
-   - Connect to `yearFrom`/`yearTo` URL params
-
-2. **Validate Page Parameter**
-   ```typescript
-   // GameBrowseLayout.tsx:72
-   page: Math.max(1, parseInt(searchParams.get('page') || '1', 10) || 1),
-   ```
-
-3. **Fix Sort Order Label for Dates**
-   ```typescript
-   const sortOrderLabel = useMemo(() => {
-     if (['releaseDate', 'dateAdded', 'dateModified'].includes(sortBy)) {
-       return sortOrder === 'asc' ? 'Oldest' : 'Newest';
-     }
-     return sortOrder === 'asc' ? 'A-Z' : 'Z-A';
-   }, [sortBy, sortOrder]);
-   ```
-
-### Medium Priority
-
-4. **Consolidate Filter Chip Rendering**
-   - Remove inline badge rendering from `FilterPanel.tsx`
-   - Use `FilterChips` component consistently
-   - Pass chip generation logic via props or shared utility
-
-5. **Add Filter Options Loading State**
-   ```typescript
-   const { data: filterOptions, isLoading: filterOptionsLoading, error } = useFilterOptions();
-
-   // Show skeleton or disabled state while loading
-   ```
-
-6. **Memoize Filter Handlers**
-   ```typescript
-   const handlers = useMemo(() =>
-     FILTER_CONFIGS.reduce((acc, config) => ({
-       ...acc,
-       [config.id]: createFilterHandlers(config.paramKey, config.id, filters, updateFilter, dropdowns)
-     }), {}),
-     [filters, updateFilter, dropdowns]
-   );
-   ```
-
-7. **Add Search-as-You-Type with Debounce**
-   ```typescript
-   // In a new SearchInput component
-   const [inputValue, setInputValue] = useState('');
-   const debouncedSearch = useDebounce(inputValue, 300);
-
-   useEffect(() => {
-     if (debouncedSearch) {
-       navigate(`/browse?search=${encodeURIComponent(debouncedSearch)}`);
-     }
-   }, [debouncedSearch]);
-   ```
-
-### Low Priority
-
-8. **Consistent LIMIT on All Filter Queries**
-   ```sql
-   -- GameService.ts:780-781
-   ORDER BY count DESC, playMode ASC
-   LIMIT 100  -- Add this
-   ```
-
-9. **Add Filter Presets**
-   - Save/load common filter combinations
-   - "Popular Flash Games", "Recent Additions", etc.
-
-10. **Add Filter Count in Dropdown Trigger**
-    - Show total matching games for current filter combination
-    - Update counts dynamically based on other selected filters (cascading filters)
-
-11. **Keyboard Navigation Improvements**
-    - Arrow keys to navigate dropdown options
-    - Enter to toggle selection
-    - Escape to close dropdown
-
----
-
-## Code Quality Observations
-
-### Positive Patterns
-
-| Pattern | Location | Notes |
-|---------|----------|-------|
-| Config-driven filter rendering | `filterConfig.ts` | Eliminates 7 duplicate filter definitions |
-| Proper `asyncHandler()` usage | `games.ts` routes | All async routes wrapped |
-| Zod validation | `games.ts:27-49` | Comprehensive query validation |
-| Window function for count | `GameService.ts:247` | Efficient single-query pagination |
-| Cache pre-warming | `GameService.ts:158-166` | Filter options cached at startup |
-| Proper URL param handling | `GameBrowseLayout.tsx` | `searchParams` synced correctly |
-
-### Areas for Improvement
-
-| Area | Current | Recommended |
-|------|---------|-------------|
-| Handler memoization | Created inline per render | Use `useMemo` or move outside component |
-| Error handling | Silent fallback to `[]` | Show error state with retry |
-| Year range UI | Missing | Add range slider component |
-| Filter persistence | URL only | Consider localStorage for user defaults |
-
----
-
-## Summary
-
-| Category | Issues | Improvements |
-|----------|--------|--------------|
-| Type Safety | 3 | Validate all URL params |
-| Missing Features | 2 | Year filter, presets |
-| Performance | 2 | Memoize handlers |
-| Consistency | 3 | Unify chip rendering |
-| Accessibility | 2 | Sort labels, keyboard nav |
-| Backend | 1 | Consistent LIMIT |
-| **Total** | **13** | **10 recommendations** |
-
-The filter system is functional and well-architected with the config-driven approach. The main gaps are the missing year range filter UI, sort order labels that don't match the sort type, and some performance optimizations around handler memoization.
-
----
-
-## Action Items
-
-- [x] Add year range filter slider to FilterPanel *(Fixed: 2026-02-15)*
-- [x] Fix page parameter validation in GameBrowseLayout *(Fixed: 2026-02-15)*
-- [x] Update SortControls to show context-aware labels (Oldest/Newest vs A-Z/Z-A) *(Fixed: 2026-02-15)*
-- [x] Add LIMIT 100 to play modes query in GameService *(Fixed: 2026-02-15)*
-- [x] Consolidate filter chip rendering to use FilterChips component only *(Fixed: 2026-02-15)*
-- [x] Add loading/error states for filter options *(Fixed: 2026-02-15)*
-- [x] Memoize filter handlers in FilterPanel *(Fixed: 2026-02-15)*
-
-## Fixes Applied (2026-02-15)
-
-### Files Modified
-
-1. **`frontend/src/components/library/GameBrowseLayout.tsx`**
-   - Added `isNaN()` validation for page parameter with `Math.max(1, ...)` fallback
-   - Added year range chip generation and removal handling
-
-2. **`frontend/src/components/search/SortControls.tsx`**
-   - Added context-aware sort order labels: "Oldest/Newest" for date fields, "A-Z/Z-A" for text fields
-   - Improved accessibility with `aria-label`
-
-3. **`frontend/src/components/search/FilterPanel.tsx`**
-   - Memoized filter handlers using `useMemo` to avoid recreation on every render
-   - Memoized `updateFilter` with `useCallback`
-   - Memoized `visibleConfigs` array
-   - Removed duplicate badge rendering (now uses `FilterChips` only)
-   - Added loading state for filter options ("Loading..." message)
-   - Integrated `YearRangeFilter` component
-
-4. **`frontend/src/components/search/YearRangeFilter.tsx`** (new file)
-   - Created year range filter component with from/to inputs
-   - Supports compact mode for mobile
-   - Proper validation of year values
-
-5. **`backend/src/services/GameService.ts`**
-   - Added `LIMIT 100` to play modes query for consistency with other filter queries
-
-## Additional Improvements (2026-02-15)
-
-### Error State with Retry for Filter Options
-
-**`frontend/src/components/search/FilterPanel.tsx`** - Added:
-- Error state detection from `useFilterOptions` hook
-- User-friendly error message with alert styling
-- Retry button to refetch filter options
-- Graceful fallback - shows filters if data exists even with stale error
diff --git a/docs/superpowers/plans/2026-08-11-downloaded-games.md b/docs/superpowers/plans/2026-08-11-downloaded-games.md
deleted file mode 100644
index 1e95833..0000000
--- a/docs/superpowers/plans/2026-08-11-downloaded-games.md
+++ /dev/null
@@ -1,1382 +0,0 @@
-# Downloaded Games Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a Downloaded games page, a downloaded filter on the browse pages, and
-three admin settings controlling the page, guest access to it, and whether the
-filter starts on.
-
-**Architecture:** "Downloaded" means a `game_data` row with `presentOnDisk = 1`, so
-the filter is a single SQL `EXISTS` clause. A reconciler service rebuilds that flag
-from the ZIP files on disk to survive Launcher syncs and to backfill games that were
-downloaded through the Play path, which previously never recorded anything. The
-three settings are public boolean rows in the existing `features` settings category.
-
-**Tech Stack:** Express + TypeScript + better-sqlite3 (backend, port 3100), React +
-Vite + TanStack Query + Zustand + Tailwind (frontend), Zod for validation, Vitest for
-tests on both sides.
-
-**Spec:** `docs/superpowers/specs/2026-08-11-downloaded-games-design.md`
-
-## Global Constraints
-
-- No `any` types; use `unknown`, generics, or real interfaces.
-- No non-null assertions (`!`); use `?? defaultValue` or explicit null checks.
-- Use `??` not `||` for defaults.
-- Throw `AppError`, not plain `Error`, from request paths.
-- Every async Express handler is wrapped in `asyncHandler()`.
-- Never write to `flashpoint.sqlite` except through `GameDatabaseUpdater`, which
-  documents the deliberate exception at `backend/src/services/GameDatabaseUpdater.ts:19-25`.
-- Frontend: `@/` imports, theme tokens (`text-muted-foreground`, not `text-gray-400`),
-  `logger` not `console`, all API calls through `@/lib/api`.
-- Fire-and-forget promises get a `.catch()`.
-- Before each commit: `npx prettier --write <files>` then `npm run typecheck`.
-- Backend tests: `cd backend && npx vitest run <file>`. Frontend tests:
-  `cd frontend && npx vitest run <file>`.
-- **Known pre-existing failure:** `frontend/src/components/auth/ProtectedRoute.test.tsx`
-  fails all 13 tests on a clean checkout (zustand/localStorage in the test env). Do not
-  try to fix it; do not treat it as caused by your change.
-
----
-
-### Task 1: Backend search filter
-
-**Files:**
-
-- Modify: `backend/src/services/GameService.ts` (`GameSearchQuery` at line 5, `searchGames` WHERE-clause block around lines 390-470)
-- Modify: `backend/src/services/GameSearchCache.ts:49-75` (`generateCacheKey`)
-- Modify: `backend/src/routes/games.ts:28-50` (`searchBodySchema`), `:57-68` (logActivity filter list), `:84-105` (query pass-through)
-- Test: `backend/src/services/GameService.downloaded.test.ts`
-
-**Interfaces:**
-
-- Consumes: nothing from earlier tasks.
-- Produces: `GameSearchQuery.downloaded?: boolean` — `true` restricts results to games
-  having a `game_data` row with `presentOnDisk = 1`; `false` and `undefined` both mean
-  no restriction. Task 7 sends this field from the frontend.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/services/GameService.downloaded.test.ts`:
-
-```typescript
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import BetterSqlite3 from 'better-sqlite3';
-
-vi.mock('./DatabaseService', () => ({
-  DatabaseService: {
-    all: vi.fn(),
-    get: vi.fn(),
-    getDatabase: vi.fn(),
-  },
-}));
-
-vi.mock('../utils/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
-}));
-
-import { DatabaseService } from './DatabaseService';
-import { GameService } from './GameService';
-
-let db: BetterSqlite3.Database;
-
-function seed(): void {
-  db.exec(`
-    CREATE TABLE game (
-      id TEXT PRIMARY KEY, title TEXT, alternateTitles TEXT, series TEXT,
-      developer TEXT, publisher TEXT, platformName TEXT, library TEXT,
-      orderTitle TEXT, dateAdded TEXT, dateModified TEXT, releaseDate TEXT,
-      playMode TEXT, language TEXT, tagsStr TEXT, broken INTEGER DEFAULT 0,
-      extreme INTEGER DEFAULT 0, activeDataId INTEGER, activeDataOnDisk INTEGER,
-      launchCommand TEXT, archiveState INTEGER
-    );
-    CREATE TABLE game_data (
-      id INTEGER PRIMARY KEY, gameId TEXT, dateAdded TEXT, sha256 TEXT,
-      path TEXT, presentOnDisk INTEGER DEFAULT 0, launchCommand TEXT
-    );
-    INSERT INTO game (id, title, orderTitle, platformName, library) VALUES
-      ('11111111-1111-1111-1111-111111111111', 'Downloaded Game', 'downloaded game', 'HTML5', 'arcade'),
-      ('22222222-2222-2222-2222-222222222222', 'Absent Game', 'absent game', 'HTML5', 'arcade');
-    INSERT INTO game_data (id, gameId, dateAdded, presentOnDisk) VALUES
-      (1, '11111111-1111-1111-1111-111111111111', '2020-01-01T00:00:00.000Z', 1),
-      (2, '22222222-2222-2222-2222-222222222222', '2020-01-01T00:00:00.000Z', 0);
-  `);
-}
-
-beforeEach(() => {
-  db = new BetterSqlite3(':memory:');
-  seed();
-  vi.mocked(DatabaseService.all).mockImplementation(
-    (sql: string, params: unknown[] = []) => db.prepare(sql).all(...params) as unknown[]
-  );
-  vi.mocked(DatabaseService.get).mockImplementation(
-    (sql: string, params: unknown[] = []) => db.prepare(sql).get(...params) as unknown
-  );
-});
-
-afterEach(() => {
-  db.close();
-  vi.clearAllMocks();
-});
-
-const baseQuery = {
-  sortBy: 'title',
-  sortOrder: 'asc' as const,
-  page: 1,
-  limit: 50,
-  showBroken: false,
-  showExtreme: false,
-  fields: 'list' as const,
-};
-
-describe('GameService downloaded filter', () => {
-  it('returns only games with presentOnDisk=1 when downloaded is true', async () => {
-    const result = await new GameService().searchGames({ ...baseQuery, downloaded: true });
-    expect(result.data.map((g) => g.title)).toEqual(['Downloaded Game']);
-  });
-
-  it('returns all games when downloaded is undefined', async () => {
-    const result = await new GameService().searchGames(baseQuery);
-    expect(result.data).toHaveLength(2);
-  });
-
-  it('returns all games when downloaded is false', async () => {
-    const result = await new GameService().searchGames({ ...baseQuery, downloaded: false });
-    expect(result.data).toHaveLength(2);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd backend && npx vitest run src/services/GameService.downloaded.test.ts`
-Expected: FAIL — the first test returns 2 games, because `downloaded` is ignored.
-
-- [ ] **Step 3: Add the field to the query interface**
-
-In `backend/src/services/GameService.ts`, inside `GameSearchQuery` after `library?: string;`:
-
-```typescript
-  /** true = only games with a game_data row where presentOnDisk = 1; false/undefined = no restriction */
-  downloaded?: boolean;
-```
-
-- [ ] **Step 4: Add the SQL condition**
-
-In `searchGames`, directly after the `if (query.library) { ... }` block:
-
-```typescript
-      if (query.downloaded === true) {
-        sql += ` AND EXISTS (
-          SELECT 1 FROM game_data gd
-          WHERE gd.gameId = g.id AND gd.presentOnDisk = 1
-        )`;
-      }
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `cd backend && npx vitest run src/services/GameService.downloaded.test.ts`
-Expected: PASS (3 tests).
-
-- [ ] **Step 6: Include the field in the cache key**
-
-In `backend/src/services/GameSearchCache.ts`, inside `generateCacheKey`'s
-`normalizedQuery`, after the `library` line:
-
-```typescript
-      downloaded: query.downloaded ?? '',
-```
-
-`??` matters here: `||` would collapse `false` and `undefined` into the same key.
-
-- [ ] **Step 7: Accept the field on the route**
-
-In `backend/src/routes/games.ts`, add to `searchBodySchema` after the `library` line:
-
-```typescript
-  downloaded: z.boolean().optional(),
-```
-
-Add `'downloaded'` to the `filters` array in the `logActivity` callback, and pass it
-through to `GameSearchCache.searchGames`:
-
-```typescript
-      downloaded: body.downloaded,
-```
-
-- [ ] **Step 8: Verify and commit**
-
-```bash
-cd backend && npx vitest run src/services/GameService.downloaded.test.ts
-cd .. && npx prettier --write backend/src/services/GameService.ts backend/src/services/GameSearchCache.ts backend/src/routes/games.ts backend/src/services/GameService.downloaded.test.ts
-npm run typecheck
-git add backend/src
-git commit -m "feat(games): filter search results by downloaded state"
-```
-
----
-
-### Task 2: Downloaded-aware filter options
-
-Without this, the dropdowns on the Downloaded page list values from the whole
-catalog and most selections return nothing.
-
-**Files:**
-
-- Modify: `backend/src/services/GameService.ts` (`FilterOptionsParams` at lines 86-98, `getFilterOptionsCacheKey` at lines 135-168, `buildFilterOptionsConditions` at lines 836+)
-- Modify: `backend/src/routes/games.ts:113-129` (`filterOptionsQuerySchema`) and the params object it builds around line 148
-- Test: `backend/src/services/GameService.downloaded.test.ts` (extend Task 1's file)
-
-**Interfaces:**
-
-- Consumes: Task 1's `downloaded` semantics.
-- Produces: `FilterOptionsParams.downloaded?: boolean`, honoured by every
-  `get*Options` method and by `getYearRange`.
-
-- [ ] **Step 1: Write the failing test**
-
-Append to `backend/src/services/GameService.downloaded.test.ts`:
-
-```typescript
-describe('filter options honour the downloaded filter', () => {
-  beforeEach(() => {
-    db.exec(`
-      UPDATE game SET series = 'Downloaded Series'
-        WHERE id = '11111111-1111-1111-1111-111111111111';
-      UPDATE game SET series = 'Absent Series'
-        WHERE id = '22222222-2222-2222-2222-222222222222';
-    `);
-  });
-
-  it('lists only series belonging to downloaded games', () => {
-    const options = new GameService().getSeriesOptions({ downloaded: true });
-    expect(options).toEqual(['Downloaded Series']);
-  });
-
-  it('lists every series when the filter is off', () => {
-    const options = new GameService().getSeriesOptions({});
-    expect(options).toHaveLength(2);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd backend && npx vitest run src/services/GameService.downloaded.test.ts`
-Expected: FAIL — the first new test returns both series.
-
-- [ ] **Step 3: Add the field and the shared condition**
-
-In `FilterOptionsParams`, after `library?: string;`:
-
-```typescript
-  downloaded?: boolean;
-```
-
-In `buildFilterOptionsConditions`, after the `params?.library` block:
-
-```typescript
-    if (params?.downloaded === true) {
-      // These queries select `FROM game` with no alias, and game_data has its own
-      // `id` column, so the outer column must be qualified as game.id.
-      conditions.push(
-        'EXISTS (SELECT 1 FROM game_data gd WHERE gd.gameId = game.id AND gd.presentOnDisk = 1)'
-      );
-    }
-```
-
-- [ ] **Step 4: Add it to the options cache key**
-
-In `getFilterOptionsCacheKey`, add `params?.downloaded === true` as another
-`hasDynamicFilters` disjunct, add `downloaded: params?.downloaded ?? false` to the
-dynamic key object, and extend the static key so the two populations never share an
-entry:
-
-```typescript
-    return {
-      key: `${params?.platform ?? ''}_${params?.library ?? ''}_${params?.downloaded === true ? 'dl' : ''}`,
-      isDynamic: false,
-    };
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `cd backend && npx vitest run src/services/GameService.downloaded.test.ts`
-Expected: PASS (5 tests).
-
-- [ ] **Step 6: Accept the param on the route**
-
-In `filterOptionsQuerySchema` add `downloaded: booleanSchema.optional(),` (the
-`booleanSchema` preprocessor already defined at the top of the file handles the
-`'false'` string correctly), and pass `downloaded: query.downloaded` into the params
-object built for the service call.
-
-- [ ] **Step 7: Verify and commit**
-
-```bash
-cd backend && npx vitest run src/services/GameService.downloaded.test.ts
-cd .. && npx prettier --write backend/src/services/GameService.ts backend/src/routes/games.ts backend/src/services/GameService.downloaded.test.ts
-npm run typecheck
-git add backend/src
-git commit -m "feat(games): narrow filter options to downloaded games"
-```
-
----
-
-### Task 3: Downloaded reconciler
-
-Rebuilds `presentOnDisk` from the ZIPs actually on disk. This is what backfills
-games downloaded through the Play path and what restores the flag after a Launcher
-sync overwrites the local database copy.
-
-**Files:**
-
-- Create: `backend/src/services/DownloadedReconciler.ts`
-- Modify: `backend/src/services/DatabaseService.ts` (add `noteSelfWrite`, call the reconciler at the end of `syncAndReload` around line 352)
-- Modify: `backend/src/server.ts:246` (run once after `DatabaseService.initialize()`)
-- Test: `backend/src/services/DownloadedReconciler.test.ts`
-
-**Interfaces:**
-
-- Consumes: `GameDataDownloader.getFilename(gameId, dateAdded)` from
-  `backend/src/game/services/GameDataDownloader.ts:75`.
-- Produces:
-  - `DownloadedReconciler.reconcile(): Promise<{ scanned: number; marked: number }>`
-  - `DatabaseService.noteSelfWrite(): void` — re-stats the source database and
-    advances `lastModifiedTime` so the file watcher does not treat our own write as a
-    Launcher change. Task 4 calls it.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/services/DownloadedReconciler.test.ts`:
-
-```typescript
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import BetterSqlite3 from 'better-sqlite3';
-import fs from 'fs/promises';
-import os from 'os';
-import path from 'path';
-
-vi.mock('../utils/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
-}));
-
-let gamesDir: string;
-
-vi.mock('../config', () => ({
-  config: {
-    get flashpointGamesPath() {
-      return gamesDir;
-    },
-    flashpointPath: 'C:/Flashpoint',
-  },
-}));
-
-vi.mock('./DatabaseService', () => ({
-  DatabaseService: { getDatabase: vi.fn(), noteSelfWrite: vi.fn() },
-}));
-
-import { DatabaseService } from './DatabaseService';
-import { DownloadedReconciler } from './DownloadedReconciler';
-
-const GAME_ID = '11111111-1111-1111-1111-111111111111';
-const DATE_ADDED = '2020-01-01T00:00:00.000Z';
-let db: BetterSqlite3.Database;
-
-beforeEach(async () => {
-  gamesDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fp-games-'));
-  db = new BetterSqlite3(':memory:');
-  db.exec(`
-    CREATE TABLE game (id TEXT PRIMARY KEY, activeDataId INTEGER, activeDataOnDisk INTEGER);
-    CREATE TABLE game_data (
-      id INTEGER PRIMARY KEY, gameId TEXT, dateAdded TEXT, path TEXT,
-      presentOnDisk INTEGER DEFAULT 0
-    );
-    INSERT INTO game (id, activeDataId, activeDataOnDisk) VALUES ('${GAME_ID}', 1, 0);
-    INSERT INTO game_data (id, gameId, dateAdded, presentOnDisk)
-      VALUES (1, '${GAME_ID}', '${DATE_ADDED}', 0);
-  `);
-  vi.mocked(DatabaseService.getDatabase).mockReturnValue(db);
-});
-
-afterEach(async () => {
-  db.close();
-  await fs.rm(gamesDir, { recursive: true, force: true });
-  vi.clearAllMocks();
-});
-
-describe('DownloadedReconciler', () => {
-  it('marks a game whose ZIP is present on disk', async () => {
-    const timestamp = new Date(DATE_ADDED).getTime();
-    await fs.writeFile(path.join(gamesDir, `${GAME_ID}-${timestamp}.zip`), 'x');
-
-    const result = await DownloadedReconciler.reconcile();
-
-    expect(result.marked).toBe(1);
-    const row = db.prepare('SELECT presentOnDisk FROM game_data WHERE id = 1').get() as {
-      presentOnDisk: number;
-    };
-    expect(row.presentOnDisk).toBe(1);
-    const game = db.prepare(`SELECT activeDataOnDisk FROM game WHERE id = '${GAME_ID}'`).get() as {
-      activeDataOnDisk: number;
-    };
-    expect(game.activeDataOnDisk).toBe(1);
-  });
-
-  it('ignores files that are not game ZIPs', async () => {
-    await fs.writeFile(path.join(gamesDir, 'notes.txt'), 'x');
-    await fs.writeFile(path.join(gamesDir, 'random-name.zip'), 'x');
-
-    const result = await DownloadedReconciler.reconcile();
-
-    expect(result.marked).toBe(0);
-  });
-
-  it('marks nothing and does not throw when the directory is unreadable', async () => {
-    await fs.rm(gamesDir, { recursive: true, force: true });
-
-    const result = await DownloadedReconciler.reconcile();
-
-    expect(result).toEqual({ scanned: 0, marked: 0 });
-  });
-
-  it('never clears the flag for a game whose ZIP is missing', async () => {
-    db.prepare('UPDATE game_data SET presentOnDisk = 1 WHERE id = 1').run();
-
-    await DownloadedReconciler.reconcile();
-
-    const row = db.prepare('SELECT presentOnDisk FROM game_data WHERE id = 1').get() as {
-      presentOnDisk: number;
-    };
-    expect(row.presentOnDisk).toBe(1);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd backend && npx vitest run src/services/DownloadedReconciler.test.ts`
-Expected: FAIL — cannot resolve `./DownloadedReconciler`.
-
-- [ ] **Step 3: Implement the reconciler**
-
-Create `backend/src/services/DownloadedReconciler.ts`:
-
-```typescript
-import fs from 'fs/promises';
-import path from 'path';
-import { config } from '../config';
-import { logger } from '../utils/logger';
-import { DatabaseService } from './DatabaseService';
-
-const ZIP_NAME_PATTERN =
-  /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})-(\d+)\.zip$/i;
-
-interface PendingRow {
-  id: number;
-  gameId: string;
-  dateAdded: string;
-}
-
-/**
- * Rebuilds game_data.presentOnDisk from the ZIP files actually present in the games
- * directory. Marks only: a missing ZIP is not proof of absence, because the Launcher
- * may store game data outside config.flashpointGamesPath.
- */
-export class DownloadedReconciler {
-  static async reconcile(): Promise<{ scanned: number; marked: number }> {
-    let files: string[];
-    try {
-      files = await fs.readdir(config.flashpointGamesPath);
-    } catch (error: unknown) {
-      logger.warn(
-        { error, path: config.flashpointGamesPath },
-        '[DownloadedReconciler] Games directory unreadable, skipping reconciliation'
-      );
-      return { scanned: 0, marked: 0 };
-    }
-
-    const onDisk = new Map<string, Set<number>>();
-    for (const file of files) {
-      const match = ZIP_NAME_PATTERN.exec(file);
-      if (!match) continue;
-      const gameId = match[1].toLowerCase();
-      const timestamp = Number(match[2]);
-      const timestamps = onDisk.get(gameId) ?? new Set<number>();
-      timestamps.add(timestamp);
-      onDisk.set(gameId, timestamps);
-    }
-
-    if (onDisk.size === 0) {
-      return { scanned: files.length, marked: 0 };
-    }
-
-    const db = DatabaseService.getDatabase();
-    const pending = db
-      .prepare(
-        `SELECT id, gameId, dateAdded FROM game_data WHERE presentOnDisk = 0 OR presentOnDisk IS NULL`
-      )
-      .all() as PendingRow[];
-
-    const toMark = pending.filter((row) => {
-      const timestamps = onDisk.get(row.gameId.toLowerCase());
-      if (!timestamps) return false;
-      const parsed = new Date(row.dateAdded).getTime();
-      return !isNaN(parsed) && timestamps.has(parsed);
-    });
-
-    if (toMark.length === 0) {
-      return { scanned: files.length, marked: 0 };
-    }
-
-    const markData = db.prepare('UPDATE game_data SET presentOnDisk = 1 WHERE id = ?');
-    const markGame = db.prepare(
-      'UPDATE game SET activeDataOnDisk = 1 WHERE id = ? AND activeDataId = ?'
-    );
-
-    db.transaction(() => {
-      for (const row of toMark) {
-        markData.run(row.id);
-        markGame.run(row.gameId, row.id);
-      }
-    })();
-
-    DatabaseService.noteSelfWrite();
-
-    logger.info(
-      { scanned: files.length, marked: toMark.length },
-      '[DownloadedReconciler] Reconciled downloaded game data'
-    );
-
-    return { scanned: files.length, marked: toMark.length };
-  }
-}
-```
-
-- [ ] **Step 4: Add `noteSelfWrite` to DatabaseService**
-
-In `backend/src/services/DatabaseService.ts`, add a public static method near
-`syncAndReload`:
-
-```typescript
-  /**
-   * Record that this process just wrote to the database, so the file watcher does not
-   * mistake our own write for a Launcher change and trigger a full reload plus cache flush.
-   */
-  static noteSelfWrite(): void {
-    try {
-      const stats = fs.statSync(this.sourceDbPath);
-      if (stats.mtimeMs > this.lastModifiedTime) {
-        this.lastModifiedTime = stats.mtimeMs;
-      }
-    } catch (error: unknown) {
-      logger.debug('[DatabaseService] Could not stat source database after self-write:', error);
-    }
-  }
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `cd backend && npx vitest run src/services/DownloadedReconciler.test.ts`
-Expected: PASS (4 tests).
-
-- [ ] **Step 6: Wire the reconciler into startup and sync**
-
-In `backend/src/server.ts`, immediately after `await DatabaseService.initialize();`:
-
-```typescript
-    DownloadedReconciler.reconcile().catch((error: unknown) =>
-      logger.error('[Startup] Downloaded reconciliation failed:', error)
-    );
-```
-
-with `import { DownloadedReconciler } from './services/DownloadedReconciler';` added
-to the imports.
-
-In `DatabaseService.syncAndReload`, after the cache invalidation block (the
-`logger.info('Database reloaded, caches invalidated')` line), re-run reconciliation
-because a local-copy sync overwrites our flags. Use a lazy `require` to match the
-existing cycle-avoidance pattern used for `GameSearchCache` in this file:
-
-```typescript
-      const { DownloadedReconciler } = require('./DownloadedReconciler') as {
-        DownloadedReconciler: { reconcile: () => Promise<{ scanned: number; marked: number }> };
-      };
-      DownloadedReconciler.reconcile().catch((error: unknown) =>
-        logger.error('[DatabaseService] Post-sync reconciliation failed:', error)
-      );
-```
-
-- [ ] **Step 7: Verify and commit**
-
-```bash
-cd backend && npx vitest run src/services/DownloadedReconciler.test.ts
-cd .. && npx prettier --write backend/src/services/DownloadedReconciler.ts backend/src/services/DownloadedReconciler.test.ts backend/src/services/DatabaseService.ts backend/src/server.ts
-npm run typecheck
-git add backend/src
-git commit -m "feat(games): reconcile downloaded state from disk"
-```
-
----
-
-### Task 4: Mark downloads from the Play path
-
-**Files:**
-
-- Modify: `backend/src/game/gamezipserver.ts` (`mountZip` params at lines 57-64, the `downloadAndMountInBackground` signature at line 328 and its call site at line 152, the success block at lines 364-386)
-- Modify: `backend/src/services/GameDataService.ts:92-98` (pass the id into `mountZip`)
-
-**Interfaces:**
-
-- Consumes: `GameDatabaseUpdater.markAsDownloaded(gameDataId: number, filePath: string): Promise<GameData>`, `DatabaseService.noteSelfWrite()` from Task 3.
-- Produces: no new exports; the Play path now records `presentOnDisk = 1`.
-
-- [ ] **Step 1: Thread the game_data id through the mount call**
-
-`GameDataService.getGameDataEntry` already selects `id`, so no extra query is needed.
-In `backend/src/services/GameDataService.ts`, extend the `mountZip` call:
-
-```typescript
-      const result = await gameZipServer.mountZip({
-        id: mountId,
-        zipPath,
-        gameId: gameDataEntry?.gameId ?? gameId,
-        dateAdded: gameDataEntry?.dateAdded,
-        sha256: gameDataEntry?.sha256,
-        gameDataId: gameDataEntry?.id,
-      });
-```
-
-In `backend/src/game/gamezipserver.ts`, add `gameDataId?: number;` to the `mountZip`
-params type, destructure it, and pass it as a new trailing argument to
-`downloadAndMountInBackground` (add `gameDataId: number | undefined` as the last
-parameter of that method).
-
-- [ ] **Step 2: Mark the row on successful download**
-
-In `downloadAndMountInBackground`, inside `if (result.success && result.filePath)`,
-after the successful `zipManager.mount(...)` and `DownloadRegistry.complete(gameId)`
-calls:
-
-```typescript
-          if (gameDataId !== undefined) {
-            try {
-              await GameDatabaseUpdater.markAsDownloaded(gameDataId, result.filePath);
-              DatabaseService.noteSelfWrite();
-              GameSearchCache.clearCache();
-              GameService.clearFilterOptionsCache();
-            } catch (error: unknown) {
-              // A failed flag update must not fail the download: the game is mounted and
-              // playable, and the reconciler will mark it on the next run.
-              logger.warn(
-                `[GameZipServer] Could not record downloaded state for ${gameId}: ${
-                  error instanceof Error ? error.message : 'unknown error'
-                }`
-              );
-            }
-          }
-```
-
-Add the four imports at the top of the file
-(`GameDatabaseUpdater`, `DatabaseService`, `GameSearchCache`, `GameService` — all from
-`../services/...`). The file already imports from `../services`, so this introduces no
-cycle.
-
-Note the checksum caveat: `GameDataDownloader` only verifies SHA-256 when the
-`game_data` row carries one. We mark regardless, because the ZIP mounted successfully,
-which is a stronger signal than an absent checksum.
-
-- [ ] **Step 3: Verify the whole backend still compiles and tests pass**
-
-```bash
-npm run typecheck
-cd backend && npx vitest run
-```
-
-Expected: typecheck clean; the backend suite passes.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd .. && npx prettier --write backend/src/game/gamezipserver.ts backend/src/services/GameDataService.ts
-git add backend/src
-git commit -m "fix(games): record downloaded state after play-path download"
-```
-
----
-
-### Task 5: Settings plumbing
-
-**Files:**
-
-- Create: `backend/src/migrations/004_downloaded_settings.sql`
-- Modify: `frontend/src/types/settings.ts:12-21` (`FeatureSettings`)
-- Modify: `frontend/src/hooks/useFeatureFlags.ts`
-- Modify: `frontend/src/components/settings/FeaturesSettingsTab.tsx`
-
-**Interfaces:**
-
-- Produces, from `useFeatureFlags()`:
-  - `enableDownloadedPage: boolean` — admin bypass applies, defaults true.
-  - `enableDownloadedPageForGuests: boolean` — no bypass, defaults false.
-  - `enableDownloadedFilterDefault: boolean` — no bypass, defaults false.
-  Tasks 7 and 8 consume all three.
-
-- [ ] **Step 1: Write the migration**
-
-Create `backend/src/migrations/004_downloaded_settings.sql`:
-
-```sql
--- ===================================
--- Migration 004: Downloaded games page and filter settings
--- ===================================
-
-INSERT OR IGNORE INTO system_settings (key, value, data_type, category, description, is_public, default_value, validation_schema)
-VALUES
-  ('features.enable_downloaded_page', '1', 'boolean', 'features', 'Show the Downloaded games page', 1, '1', '{"type":"boolean"}'),
-  ('features.enable_downloaded_page_for_guests', '0', 'boolean', 'features', 'Allow guests to see the Downloaded games page', 1, '0', '{"type":"boolean"}'),
-  ('features.enable_downloaded_filter_default', '0', 'boolean', 'features', 'Turn the downloaded filter on by default when browsing', 1, '0', '{"type":"boolean"}');
-```
-
-`SystemSettingsService` maps `enable_downloaded_page` to `enableDownloadedPage`
-automatically via its `snakeToCamel`/`camelToSnake` helpers, so no service change is
-needed.
-
-- [ ] **Step 2: Extend the frontend settings type**
-
-In `frontend/src/types/settings.ts`, add to `FeatureSettings`:
-
-```typescript
-  enableDownloadedPage: boolean;
-  enableDownloadedPageForGuests: boolean;
-  enableDownloadedFilterDefault: boolean;
-```
-
-- [ ] **Step 3: Expose the flags**
-
-In `frontend/src/hooks/useFeatureFlags.ts`, add to the returned object:
-
-```typescript
-    enableDownloadedPage: isAdmin || (features.enableDownloadedPage ?? true),
-    // Default-off flags are read strictly: the `?? true` fallback used above would
-    // invert them while public settings are still loading or if the key is missing.
-    enableDownloadedPageForGuests: features.enableDownloadedPageForGuests === true,
-    enableDownloadedFilterDefault: features.enableDownloadedFilterDefault === true,
-```
-
-- [ ] **Step 4: Add the three switches**
-
-In `frontend/src/components/settings/FeaturesSettingsTab.tsx`, after the existing
-"I'm Feeling Lucky" block, add the page switch, then the guest switch rendered only
-when the page flag is on, then the default switch:
-
-```tsx
-            {/* Downloaded page */}
-            <div className="flex items-center justify-between">
-              <div className="space-y-0.5">
-                <Label htmlFor="enable-downloaded-page" className="text-base">
-                  Enable Downloaded Page
-                </Label>
-                <p className="text-sm text-muted-foreground">
-                  Show a page listing only games whose files are downloaded.
-                </p>
-              </div>
-              <Switch
-                id="enable-downloaded-page"
-                checked={featureSettings.enableDownloadedPage !== false}
-                onCheckedChange={(checked: boolean) => {
-                  updateSystemSettings.mutate({
-                    category: 'features',
-                    settings: { enableDownloadedPage: checked },
-                  });
-                }}
-                disabled={updateSystemSettings.isPending}
-              />
-            </div>
-
-            {featureSettings.enableDownloadedPage !== false ? (
-              <div className="flex items-center justify-between pl-6 border-l-2 border-border">
-                <div className="space-y-0.5">
-                  <Label htmlFor="enable-downloaded-page-guests" className="text-base">
-                    Show Downloaded Page To Guests
-                  </Label>
-                  <p className="text-sm text-muted-foreground">
-                    Let signed-out guests open the Downloaded page.
-                  </p>
-                </div>
-                <Switch
-                  id="enable-downloaded-page-guests"
-                  checked={featureSettings.enableDownloadedPageForGuests === true}
-                  onCheckedChange={(checked: boolean) => {
-                    updateSystemSettings.mutate({
-                      category: 'features',
-                      settings: { enableDownloadedPageForGuests: checked },
-                    });
-                  }}
-                  disabled={updateSystemSettings.isPending}
-                />
-              </div>
-            ) : null}
-
-            {/* Downloaded filter default */}
-            <div className="flex items-center justify-between">
-              <div className="space-y-0.5">
-                <Label htmlFor="enable-downloaded-filter-default" className="text-base">
-                  Filter To Downloaded By Default
-                </Label>
-                <p className="text-sm text-muted-foreground">
-                  Browse pages start with the downloaded filter on. This one also applies to
-                  admins; anyone can still switch it off per page.
-                </p>
-              </div>
-              <Switch
-                id="enable-downloaded-filter-default"
-                checked={featureSettings.enableDownloadedFilterDefault === true}
-                onCheckedChange={(checked: boolean) => {
-                  updateSystemSettings.mutate({
-                    category: 'features',
-                    settings: { enableDownloadedFilterDefault: checked },
-                  });
-                }}
-                disabled={updateSystemSettings.isPending}
-              />
-            </div>
-```
-
-- [ ] **Step 5: Verify the migration applies**
-
-```bash
-cd backend && npm run dev
-```
-
-Watch for `[UserDB] Running migration: 004_downloaded_settings` in the log, then stop
-the server with Ctrl+C. Confirm the process is gone before continuing.
-
-- [ ] **Step 6: Commit**
-
-```bash
-npx prettier --write frontend/src/types/settings.ts frontend/src/hooks/useFeatureFlags.ts frontend/src/components/settings/FeaturesSettingsTab.tsx
-npm run typecheck
-git add backend/src/migrations frontend/src
-git commit -m "feat(settings): add downloaded page and filter settings"
-```
-
----
-
-### Task 6: Tri-state URL parameter
-
-**Files:**
-
-- Modify: `frontend/src/lib/filterUrlCompression.ts` (`FilterUrlParams` at lines 6-21, `CATEGORY_TO_ABBR` at lines 24-34, `toUrlSafeFormat` at lines 92-111, `fromUrlSafeFormat` at lines 116-173, `parseFilterParams` legacy branch at lines 355-370, `hasLegacyParams` at lines 403-418)
-- Test: `frontend/src/lib/filterUrlCompression.test.ts`
-
-**Interfaces:**
-
-- Produces: `FilterUrlParams.downloaded?: '0' | '1'` encoded under the key `w`.
-  `'1'` on, `'0'` off, absent means "use the admin default". Task 7 resolves it.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `frontend/src/lib/filterUrlCompression.test.ts`:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import {
-  buildFilterSearchParams,
-  parseFilterParams,
-  compressFilters,
-  decompressFilters,
-} from './filterUrlCompression';
-
-describe('downloaded filter URL round-trip', () => {
-  it('round-trips an explicit on', () => {
-    const encoded = compressFilters({ downloaded: '1' });
-    expect(encoded).not.toBeNull();
-    expect(decompressFilters(encoded ?? '')?.downloaded).toBe('1');
-  });
-
-  it('round-trips an explicit off rather than dropping it', () => {
-    const encoded = compressFilters({ downloaded: '0' });
-    expect(encoded).not.toBeNull();
-    expect(decompressFilters(encoded ?? '')?.downloaded).toBe('0');
-  });
-
-  it('survives buildFilterSearchParams and parseFilterParams', () => {
-    const params = buildFilterSearchParams({ downloaded: '0', search: 'sonic' });
-    const parsed = parseFilterParams(params);
-    expect(parsed.downloaded).toBe('0');
-    expect(parsed.search).toBe('sonic');
-  });
-
-  it('leaves downloaded undefined when absent', () => {
-    const parsed = parseFilterParams(new URLSearchParams());
-    expect(parsed.downloaded).toBeUndefined();
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd frontend && npx vitest run src/lib/filterUrlCompression.test.ts`
-Expected: FAIL — `downloaded` is not a known param, so it is dropped.
-
-- [ ] **Step 3: Implement the encoding**
-
-In `frontend/src/lib/filterUrlCompression.ts`:
-
-Add to `FilterUrlParams`:
-
-```typescript
-  /** '1' = downloaded only, '0' = explicitly off, undefined = use the admin default */
-  downloaded?: '0' | '1';
-```
-
-Add to `CATEGORY_TO_ABBR`:
-
-```typescript
-  Downloaded: 'W',
-```
-
-In `toUrlSafeFormat`, before the `fo` line — note the `!== undefined` guard, since a
-truthiness check would silently drop `'0'`:
-
-```typescript
-  if (params.downloaded !== undefined) parts.push(`w.${params.downloaded}`);
-```
-
-In `fromUrlSafeFormat`'s switch:
-
-```typescript
-        case 'w':
-          if (value === '0' || value === '1') params.downloaded = value;
-          break;
-```
-
-In the legacy branch of `parseFilterParams`, add:
-
-```typescript
-    downloaded: searchParams.get('downloaded') === '1'
-      ? '1'
-      : searchParams.get('downloaded') === '0'
-        ? '0'
-        : undefined,
-```
-
-and add `'downloaded'` to the `legacyKeys` array in `hasLegacyParams`.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `cd frontend && npx vitest run src/lib/filterUrlCompression.test.ts`
-Expected: PASS (4 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd .. && npx prettier --write frontend/src/lib/filterUrlCompression.ts frontend/src/lib/filterUrlCompression.test.ts
-npm run typecheck
-git add frontend/src/lib
-git commit -m "feat(filters): encode downloaded filter in the URL"
-```
-
----
-
-### Task 7: Filter UI and default resolution
-
-**Files:**
-
-- Modify: `frontend/src/types/game.ts:48-66` (`GameFilters`)
-- Modify: `frontend/src/lib/api/games.ts:11-38` (search POST body) and `:39-57` (`getFilterOptions` params type)
-- Modify: `frontend/src/hooks/useFilterOptions.ts:6-18` (`FilterOptionsParams`)
-- Modify: `frontend/src/components/library/GameBrowseLayout.tsx` (filters memo lines 70-89, filterOptionsParams lines 93-108, chips memo lines 164-294, `handleRemoveChip` lines 306-360, `handleRemoveWithChildren` lines 363-399, `handleClearAllFilters` lines 401-407)
-- Modify: `frontend/src/components/search/FilterPanel.tsx` (props at lines 17-32, desktop row at lines 224-233, mobile row at lines 236-246)
-
-**Interfaces:**
-
-- Consumes: `FilterUrlParams.downloaded` (Task 6), `enableDownloadedFilterDefault`
-  (Task 5), `GameSearchQuery.downloaded` (Task 1).
-- Produces: `GameBrowseLayoutProps.library?: 'arcade' | 'theatre'` and
-  `GameBrowseLayoutProps.forceDownloaded?: boolean`, both consumed by Task 8.
-
-- [ ] **Step 1: Add the field to the API layer**
-
-In `frontend/src/types/game.ts`, add to `GameFilters`:
-
-```typescript
-  downloaded?: boolean;
-```
-
-In `frontend/src/lib/api/games.ts`, add to the `body` object inside `search`, directly
-after the `library` line:
-
-```typescript
-      downloaded: filters.downloaded,
-```
-
-and add `downloaded?: boolean;` to the inline params type of `getFilterOptions`, which
-already forwards the whole object as query params.
-
-In `frontend/src/hooks/useFilterOptions.ts`, add `downloaded?: boolean;` to
-`FilterOptionsParams` after `library?: string;`. The hook builds its query key from
-this object, so the new field participates in cache invalidation automatically.
-
-- [ ] **Step 2: Resolve the tri-state in GameBrowseLayout**
-
-Add the props and resolution:
-
-```tsx
-interface GameBrowseLayoutProps {
-  title: string;
-  library?: 'arcade' | 'theatre';
-  platform?: string;
-  headerContent?: ReactNode;
-  breadcrumbContext?: BreadcrumbContext;
-  sectionKey?: string | null;
-  /** Pin the downloaded filter on and hide its switch (used by the Downloaded page) */
-  forceDownloaded?: boolean;
-}
-```
-
-```tsx
-  const { enableDownloadedFilterDefault } = useFeatureFlags();
-
-  const downloaded = useMemo(() => {
-    if (forceDownloaded) return true;
-    if (urlParams.downloaded === '1') return true;
-    if (urlParams.downloaded === '0') return false;
-    return enableDownloadedFilterDefault;
-  }, [forceDownloaded, urlParams.downloaded, enableDownloadedFilterDefault]);
-```
-
-Add `downloaded: downloaded ? true : undefined` to the `filters` memo (and its
-dependency array) and `downloaded: filters.downloaded` to `filterOptionsParams`.
-Sending `undefined` rather than `false` keeps the request body and the backend cache
-key clean.
-
-- [ ] **Step 3: Add the chip**
-
-In the `filterChips` memo, after the platform chip:
-
-```tsx
-    if (filters.downloaded && !forceDownloaded) {
-      chips.push({
-        id: 'downloaded',
-        label: 'Downloaded',
-        value: 'Downloaded only',
-        category: 'Downloaded',
-        order: getOrder('Downloaded'),
-      });
-    }
-```
-
-Add `forceDownloaded` to the memo's dependency array.
-
-- [ ] **Step 4: Make removal write an explicit off**
-
-This is the critical case: when the admin default is on, clearing the param means
-"use the default", which immediately re-applies the filter. In `handleRemoveChip`,
-alongside the existing `chipId === 'platform'` branch:
-
-```tsx
-      } else if (chipId === 'downloaded') {
-        // Clearing the param would fall back to the admin default and re-apply the
-        // filter, so an explicit off is required when the default is on.
-        newParams.downloaded = enableDownloadedFilterDefault ? '0' : undefined;
-        categoryRemoved = 'Downloaded';
-```
-
-Add `Downloaded: ['downloaded']` to `categoryToParamKeys` in
-`handleRemoveWithChildren`, and after that function's param-clearing loop:
-
-```tsx
-      if (categoriesToRemove.includes('Downloaded') && enableDownloadedFilterDefault) {
-        newParams.downloaded = '0';
-      }
-```
-
-In `handleClearAllFilters`:
-
-```tsx
-  const handleClearAllFilters = useCallback(() => {
-    const newParams: FilterUrlParams = {
-      sortBy: urlParams.sortBy,
-      sortOrder: urlParams.sortOrder,
-      downloaded: enableDownloadedFilterDefault ? '0' : undefined,
-    };
-    setSearchParams(buildFilterSearchParams(newParams));
-  }, [urlParams.sortBy, urlParams.sortOrder, enableDownloadedFilterDefault, setSearchParams]);
-```
-
-Add `enableDownloadedFilterDefault` to the dependency arrays of the two callbacks
-above as well.
-
-- [ ] **Step 5: Add the switch to the filter panel**
-
-In `FilterPanel`, add two props:
-
-```tsx
-  /** Current resolved value of the downloaded filter */
-  downloaded?: boolean;
-  /** Hide the downloaded switch (the Downloaded page pins it on) */
-  showDownloadedFilter?: boolean;
-```
-
-Default `showDownloadedFilter = true`, and render this beside `YearRangeFilter` in
-both the desktop and mobile rows (give the two instances distinct ids):
-
-```tsx
-            {showDownloadedFilter ? (
-              <div className="flex items-center gap-2">
-                <Switch
-                  id="downloaded-filter-desktop"
-                  checked={downloaded === true}
-                  onCheckedChange={(checked: boolean) => {
-                    const newParams: FilterUrlParams = {
-                      ...urlParams,
-                      downloaded: checked ? '1' : '0',
-                      page: undefined,
-                      fo: getUpdatedFilterOrder(urlParams.fo, 'Downloaded', checked ? 'add' : 'remove'),
-                    };
-                    setSearchParams(buildFilterSearchParams(newParams));
-                  }}
-                />
-                <Label htmlFor="downloaded-filter-desktop" className="text-sm whitespace-nowrap">
-                  Downloaded only
-                </Label>
-              </div>
-            ) : null}
-```
-
-Always write an explicit `'1'` or `'0'` here — never clear the key — so the control
-reflects the user's choice rather than snapping back to the admin default. Import
-`Switch` from `@/components/ui/switch` and `Label` from `@/components/ui/label`.
-
-Pass both new props from `GameBrowseLayout`:
-
-```tsx
-          downloaded={downloaded}
-          showDownloadedFilter={!forceDownloaded}
-```
-
-- [ ] **Step 6: Verify manually**
-
-```bash
-npm run dev
-```
-
-Open `http://localhost:5173/browse`. Confirm: the switch turns the filter on and the
-result count drops; the chip appears; removing the chip turns it off; with
-`Filter To Downloaded By Default` enabled in Settings, removing the chip still turns
-the filter off and Clear All does not re-apply it. Stop the dev server with Ctrl+C and
-confirm the processes are gone.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write frontend/src/types/game.ts frontend/src/lib/api/games.ts frontend/src/components/library/GameBrowseLayout.tsx frontend/src/components/search/FilterPanel.tsx
-npm run typecheck
-git add frontend/src
-git commit -m "feat(filters): add downloaded filter to browse pages"
-```
-
----
-
-### Task 8: Downloaded page, route, and sidebar
-
-**Files:**
-
-- Create: `frontend/src/views/DownloadedView.tsx`
-- Modify: `frontend/src/App.tsx` (lazy import block and the route list near `/favorites` at line 439)
-- Modify: `frontend/src/components/auth/ProtectedRoute.tsx:7-17` (props), `:67-79` (feature check)
-- Modify: `frontend/src/components/layout/Sidebar.tsx:48` (flags), `:78-86` (library items), `:179-190` (section gate)
-
-**Interfaces:**
-
-- Consumes: `GameBrowseLayout` props from Task 7, the three flags from Task 5.
-- Produces: route `/downloaded`; `ProtectedRouteProps.requireFeatureForGuests?: 'enableDownloadedPageForGuests'`.
-
-- [ ] **Step 1: Create the view**
-
-Create `frontend/src/views/DownloadedView.tsx`:
-
-```tsx
-import { GameBrowseLayout } from '@/components/library/GameBrowseLayout';
-
-export function DownloadedView() {
-  return (
-    <GameBrowseLayout
-      title="Downloaded"
-      forceDownloaded
-      sectionKey={null}
-      breadcrumbContext={{ label: 'Downloaded', href: '/downloaded' }}
-    />
-  );
-}
-```
-
-`BreadcrumbContext` is `{ label: string; href: string; icon?: SectionIcon; parent?: BreadcrumbContext }`
-(`frontend/src/components/common/Breadcrumbs.tsx:6-12`) — the key is `href`, not `path`.
-
-- [ ] **Step 2: Extend ProtectedRoute for guests**
-
-Guests satisfy `requireAuth`, so a feature flag alone does not keep them out. Add to
-`ProtectedRouteProps`:
-
-```typescript
-  requireFeature?:
-    | 'enablePlaylists'
-    | 'enableFavorites'
-    | 'enableStatistics'
-    | 'enableDownloadedPage';
-  /** Checked only when the viewer is a guest; the named flag must be true */
-  requireFeatureForGuests?: 'enableDownloadedPageForGuests';
-```
-
-Destructure `requireFeatureForGuests` and add the check immediately after the existing
-`requireFeature` block:
-
-```tsx
-  if (requireFeatureForGuests && isGuest && !featureFlags[requireFeatureForGuests]) {
-    return (
-      <Navigate
-        to="/unauthorized"
-        state={{ requiredFeature: requireFeatureForGuests, fromPath: location.pathname }}
-        replace
-      />
-    );
-  }
-```
-
-- [ ] **Step 3: Register the route**
-
-In `frontend/src/App.tsx`, add the lazy import next to the other views:
-
-```tsx
-const DownloadedView = lazy(() =>
-  import('@/views/DownloadedView').then((m) => ({ default: m.DownloadedView }))
-);
-```
-
-Match the exact lazy-import style already used in the file. Add the route beside
-`/favorites`:
-
-```tsx
-            <Route
-              path="/downloaded"
-              element={
-                <ProtectedRoute
-                  requireFeature="enableDownloadedPage"
-                  requireFeatureForGuests="enableDownloadedPageForGuests"
-                >
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <DownloadedView />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
-```
-
-- [ ] **Step 4: Add the sidebar entry without leaking the others**
-
-The Library block is currently hidden wholesale for guests, so its items never check
-guest status themselves. Give each item its own predicate before relaxing the block. In
-`Sidebar.tsx`, extend the flags destructure with `enableDownloadedPage` and
-`enableDownloadedPageForGuests`, then:
-
-```tsx
-  const libraryNavItems: NavItem[] = [
-    enableDownloadedPage &&
-      (!isGuest || enableDownloadedPageForGuests) && {
-        path: '/downloaded',
-        icon: HardDriveDownload,
-        label: 'Downloaded',
-      },
-    !isGuest && enableFavorites && { path: '/favorites', icon: Heart, label: 'Favorites' },
-    !isGuest && enablePlaylists && { path: '/playlists', icon: ListVideo, label: 'My Playlists' },
-    !isGuest &&
-      enablePlaylists && {
-        path: '/flashpoint-playlists',
-        icon: ListIcon,
-        label: 'Flashpoint Playlists',
-      },
-  ].filter((item): item is Exclude<typeof item, false> => Boolean(item));
-```
-
-Import `HardDriveDownload` from `lucide-react`. Change the section gate from
-`!isGuest && libraryNavItems.length > 0` to `libraryNavItems.length > 0`, since each
-item now carries its own guest rule.
-
-- [ ] **Step 5: Verify manually**
-
-```bash
-npm run dev
-```
-
-Check, stopping the server afterwards with Ctrl+C:
-
-1. `/downloaded` lists only downloaded games and shows no downloaded switch.
-2. Turning off `Enable Downloaded Page` hides the sidebar entry for a non-admin and
-   redirects `/downloaded` to `/unauthorized`.
-3. As a guest with the guest flag off, the entry is hidden and `/downloaded`
-   redirects; with it on, both work, and Favorites and Playlists stay hidden.
-
-- [ ] **Step 6: Commit**
-
-```bash
-npx prettier --write frontend/src/views/DownloadedView.tsx frontend/src/App.tsx frontend/src/components/auth/ProtectedRoute.tsx frontend/src/components/layout/Sidebar.tsx
-npm run typecheck
-git add frontend/src
-git commit -m "feat(games): add downloaded games page"
-```
-
----
-
-### Task 9: Documentation
-
-**Files:**
-
-- Modify: `docs/06-api-reference/games-api.md`
-- Modify: `docs/06-api-reference/settings-api.md`
-- Modify: `docs/10-features/02-game-browsing-filtering.md`
-
-- [ ] **Step 1: Document the API parameter**
-
-In `docs/06-api-reference/games-api.md`, add `downloaded` (boolean, optional) to both
-the search request body table and the filter-options query table, described as
-"restrict to games whose data is present on disk".
-
-- [ ] **Step 2: Document the settings**
-
-In `docs/06-api-reference/settings-api.md`, add three rows to the settings table:
-
-```markdown
-| features | enableDownloadedPage           | boolean | true           | -                                      |
-| features | enableDownloadedPageForGuests  | boolean | false          | -                                      |
-| features | enableDownloadedFilterDefault  | boolean | false          | -                                      |
-```
-
-- [ ] **Step 3: Document the feature**
-
-In `docs/10-features/02-game-browsing-filtering.md`, add a short section covering the
-Downloaded page, the filter, the tri-state URL parameter, and the two limitations from
-the spec: games with no `game_data` rows never appear, and the reconciler only ever
-sets the flag, never clears it.
-
-- [ ] **Step 4: Commit**
-
-```bash
-npx prettier --write docs/06-api-reference/games-api.md docs/06-api-reference/settings-api.md docs/10-features/02-game-browsing-filtering.md
-git add docs
-git commit -m "docs: document downloaded games page and filter"
-```
-
----
-
-## Final verification
-
-- [ ] `npm run typecheck` passes.
-- [ ] `cd backend && npx vitest run` passes.
-- [ ] `cd frontend && npx vitest run src/lib/filterUrlCompression.test.ts` passes
-      (the pre-existing `ProtectedRoute.test.tsx` failures remain; they are unrelated).
-- [ ] `npm run build` succeeds.
-- [ ] No dev servers or watchers left running.
diff --git a/docs/superpowers/plans/2026-08-12-web-app-update.md b/docs/superpowers/plans/2026-08-12-web-app-update.md
deleted file mode 100644
index e92cafe..0000000
--- a/docs/superpowers/plans/2026-08-12-web-app-update.md
+++ /dev/null
@@ -1,1183 +0,0 @@
-# Web App Update Check Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Show an admin on Settings → Update whether a newer release of Flashpoint Web exists, what changed, and how to upgrade.
-
-**Architecture:** A backend service reads the running version from `APP_VERSION`, fetches the latest GitHub release with axios, compares them, and serves a bare JSON object from `GET /api/updates/app`. A React card renders the result. The card notifies only — it never pulls, restarts, or writes anything.
-
-**Tech Stack:** Express + TypeScript, axios, vitest + supertest, React + TanStack Query, react-markdown + remark-gfm, Tailwind theme tokens.
-
-**Spec:** `docs/superpowers/specs/2026-08-12-web-app-update-design.md`
-
-## Global Constraints
-
-- The repository is hardcoded: `https://api.github.com/repos/darkraise/flashpoint-web/releases/latest`.
-- The route always answers HTTP 200. Never throw `AppError` from this feature — the axios interceptor in `frontend/src/lib/api/client.ts` fires a global toast for any status at or above 500, which would double up with the card's own error state.
-- The response is a **bare object**, `res.json(info)` — matching every endpoint in `backend/src/routes/updates.ts`. Do not use the `{success, data}` envelope from `routes/github.ts`.
-- Cache TTL is 1 hour; a forced refresh is floored at 60 seconds; the axios timeout is 10 seconds.
-- Strip a single leading `v` from **both** sides before comparing. GitHub tags are `v1.0.38`; `APP_VERSION` is `1.0.38`.
-- A version is a release only if it is exactly three numeric parts. Everything else — unset, `dev`, `latest`, `1.1.0-rc1`, `1.0.38-5-gabc123` — is an **unreleased build** and never reports an update.
-- Project standards in `CLAUDE.md` are mandatory: no `any`, no non-null assertions, `??` over `||` (one documented exception in Task 2), `asyncHandler` on async handlers, `logger` not `console`, theme tokens not hardcoded colors, `@/` imports, all frontend API calls through `frontend/src/lib/api`.
-- Run `npx prettier --write <files>` before every commit. Backend tests run from `backend/`: `npx vitest run` (the repo's tests fail when run from the repo root — a fixture path issue unrelated to this work).
-
----
-
-### Task 1: Version comparison utility
-
-**Files:**
-
-- Create: `backend/src/utils/version.ts`
-- Test: `backend/src/utils/version.test.ts`
-
-**Interfaces:**
-
-- Consumes: nothing.
-- Produces: `normalizeVersion(value: string): string`, `isReleaseVersion(value: string | null): boolean`, `compareVersions(a: string, b: string): number | null`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/utils/version.test.ts`:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { compareVersions, isReleaseVersion, normalizeVersion } from './version';
-
-describe('normalizeVersion', () => {
-  it('strips a single leading v', () => {
-    expect(normalizeVersion('v1.0.38')).toBe('1.0.38');
-    expect(normalizeVersion('1.0.38')).toBe('1.0.38');
-  });
-});
-
-describe('isReleaseVersion', () => {
-  it('accepts three numeric parts with or without a v', () => {
-    expect(isReleaseVersion('1.0.38')).toBe(true);
-    expect(isReleaseVersion('v1.0.38')).toBe(true);
-  });
-
-  it('rejects anything else', () => {
-    expect(isReleaseVersion(null)).toBe(false);
-    expect(isReleaseVersion('')).toBe(false);
-    expect(isReleaseVersion('dev')).toBe(false);
-    expect(isReleaseVersion('latest')).toBe(false);
-    expect(isReleaseVersion('1.0')).toBe(false);
-    expect(isReleaseVersion('1.1.0-rc1')).toBe(false);
-    expect(isReleaseVersion('1.0.38-5-gabc123')).toBe(false);
-  });
-});
-
-describe('compareVersions', () => {
-  it('reports equality', () => {
-    expect(compareVersions('1.0.38', '1.0.38')).toBe(0);
-    expect(compareVersions('1.0.38', 'v1.0.38')).toBe(0);
-  });
-
-  it('reports a newer right side as negative', () => {
-    expect(compareVersions('1.0.38', 'v1.0.42')).toBeLessThan(0);
-    expect(compareVersions('1.0.38', 'v1.1.0')).toBeLessThan(0);
-    expect(compareVersions('1.0.38', 'v2.0.0')).toBeLessThan(0);
-  });
-
-  it('reports an older right side as positive', () => {
-    expect(compareVersions('1.0.38', 'v1.0.37')).toBeGreaterThan(0);
-  });
-
-  it('compares numerically, not as strings', () => {
-    expect(compareVersions('1.0.38', 'v1.0.9')).toBeGreaterThan(0);
-  });
-
-  it('returns null when either side is not a release version', () => {
-    expect(compareVersions('dev', 'v1.0.38')).toBeNull();
-    expect(compareVersions('1.0.38-5-gabc123', 'v1.0.38')).toBeNull();
-    expect(compareVersions('1.0.38', 'v2.0')).toBeNull();
-    expect(compareVersions('', '')).toBeNull();
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run from `backend/`: `npx vitest run src/utils/version.test.ts`
-Expected: FAIL — cannot resolve `./version`.
-
-- [ ] **Step 3: Write the implementation**
-
-Create `backend/src/utils/version.ts`:
-
-```typescript
-/** A release version is exactly three numeric parts, with an optional leading v. */
-const RELEASE_VERSION = /^v?(\d+)\.(\d+)\.(\d+)$/;
-
-/** GitHub tags carry a leading v that APP_VERSION does not. */
-export function normalizeVersion(value: string): string {
-  const trimmed = value.trim();
-  return trimmed.startsWith('v') ? trimmed.slice(1) : trimmed;
-}
-
-export function isReleaseVersion(value: string | null): boolean {
-  return typeof value === 'string' && RELEASE_VERSION.test(value.trim());
-}
-
-/**
- * Negative when a is older than b, positive when newer, zero when equal.
- * Null when either side is not a release version, which is what keeps an
- * unreleased build from claiming to be behind.
- */
-export function compareVersions(a: string, b: string): number | null {
-  const left = RELEASE_VERSION.exec(a.trim());
-  const right = RELEASE_VERSION.exec(b.trim());
-
-  if (!left || !right) {
-    return null;
-  }
-
-  for (let part = 1; part <= 3; part++) {
-    const difference = Number(left[part]) - Number(right[part]);
-    if (difference !== 0) {
-      return difference;
-    }
-  }
-
-  return 0;
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run from `backend/`: `npx vitest run src/utils/version.test.ts`
-Expected: PASS, 6 tests.
-
-- [ ] **Step 5: Commit**
-
-```bash
-npx prettier --write backend/src/utils/version.ts backend/src/utils/version.test.ts
-git add backend/src/utils/version.ts backend/src/utils/version.test.ts
-git commit -m "feat(utils): add release version comparison"
-```
-
----
-
-### Task 2: Server reports its running version
-
-**Files:**
-
-- Modify: `backend/src/config.ts` (add `appVersion` beside the Flashpoint version fields, around line 150)
-- Modify: `Dockerfile` (final stage, after the existing `ARG VERSION=dev` near line 56)
-- Modify: `docs/09-deployment/environment-variables.md`
-
-**Interfaces:**
-
-- Consumes: nothing.
-- Produces: `config.appVersion: string | null`.
-
-- [ ] **Step 1: Add the config field**
-
-In `backend/src/config.ts`, immediately after `flashpointPackagedAt`:
-
-```typescript
-  // Baked into the image from the VERSION build arg; unset elsewhere, which
-  // marks the build as unreleased. `||` is deliberate: a whitespace-only value
-  // must collapse to null, which `??` would not do.
-  appVersion: process.env.APP_VERSION?.trim() || null,
-```
-
-- [ ] **Step 2: Pass the build arg into the running container**
-
-In `Dockerfile`, the final stage already declares `ARG VERSION=dev` above the labels. Add directly below the `LABEL` lines:
-
-```dockerfile
-# An ARG does not survive into the running container; the server reads this to
-# decide whether it is a released build.
-ENV APP_VERSION=${VERSION}
-```
-
-- [ ] **Step 3: Verify both states**
-
-Run from `backend/`:
-
-```bash
-npm run build
-APP_VERSION=1.0.38 node -e "console.log(require('./dist/config.js').config.appVersion)"   # 1.0.38
-APP_VERSION="   " node -e "console.log(require('./dist/config.js').config.appVersion)"    # null
-node -e "console.log(require('./dist/config.js').config.appVersion)"                      # null
-```
-
-Expected: `1.0.38`, then `null`, then `null`.
-
-- [ ] **Step 4: Document the variable**
-
-In `docs/09-deployment/environment-variables.md`, add to the table under **Paths** a new row in the general/optional section (place it next to the other optional server variables):
-
-```markdown
-| `APP_VERSION` | set by the Docker build | Release version the server reports on Settings → Update. Baked into the official image from the release tag; set it by hand for a non-Docker deployment, or update checks stay off. |
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-npx prettier --write backend/src/config.ts docs/09-deployment/environment-variables.md
-git add backend/src/config.ts Dockerfile docs/09-deployment/environment-variables.md
-git commit -m "feat(config): report the running app version"
-```
-
----
-
-### Task 3: AppUpdateService — fetch and compare
-
-**Files:**
-
-- Create: `backend/src/services/AppUpdateService.ts`
-- Test: `backend/src/services/AppUpdateService.test.ts`
-
-**Interfaces:**
-
-- Consumes: `compareVersions`, `isReleaseVersion`, `normalizeVersion` from `../utils/version`; `config.appVersion`.
-- Produces: `AppUpdateService.getUpdateInfo(force?: boolean): Promise<AppUpdateInfo>`, `AppUpdateService.clearCache(): void`, and the exported `AppUpdateInfo` interface.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/services/AppUpdateService.test.ts`:
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-vi.mock('../utils/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
-}));
-
-const configMock = vi.hoisted(() => ({ config: { appVersion: '1.0.38' as string | null } }));
-vi.mock('../config', () => configMock);
-
-vi.mock('axios', () => ({
-  default: { get: vi.fn() },
-}));
-
-import axios from 'axios';
-import { AppUpdateService } from './AppUpdateService';
-
-/** The shape of the fields this service reads from a GitHub release. */
-function release(tagName: string) {
-  return {
-    data: {
-      tag_name: tagName,
-      published_at: '2026-08-12T07:11:45Z',
-      html_url: `https://github.com/darkraise/flashpoint-web/releases/tag/${tagName}`,
-      body: '## Changes since v1.0.37\n\n- feat: something',
-    },
-  };
-}
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  AppUpdateService.clearCache();
-  configMock.config.appVersion = '1.0.38';
-});
-
-describe('AppUpdateService.getUpdateInfo', () => {
-  it('reports an update when the release is newer', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.updateAvailable).toBe(true);
-    expect(info.currentVersion).toBe('1.0.38');
-    expect(info.latestVersion).toBe('1.0.42');
-    expect(info.isUnreleasedBuild).toBe(false);
-    expect(info.lastCheckFailed).toBe(false);
-    expect(info.publishedAt).toBe('2026-08-12T07:11:45Z');
-    expect(info.releaseUrl).toContain('/releases/tag/v1.0.42');
-    expect(info.changelog).toContain('Changes since');
-    expect(info.checkedAt).not.toBeNull();
-  });
-
-  it('reports no update when the versions match', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.38'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.updateAvailable).toBe(false);
-    expect(info.latestVersion).toBe('1.0.38');
-  });
-
-  it('reports no update when the running build is newer than the release', async () => {
-    configMock.config.appVersion = '1.0.42';
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.38'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.updateAvailable).toBe(false);
-  });
-
-  it('never claims an update on an unreleased build, but still reports the release', async () => {
-    configMock.config.appVersion = '1.0.38-5-gabc123';
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.isUnreleasedBuild).toBe(true);
-    expect(info.updateAvailable).toBe(false);
-    expect(info.latestVersion).toBe('1.0.42');
-    expect(info.changelog).toContain('Changes since');
-  });
-
-  it('treats an unset version as an unreleased build', async () => {
-    configMock.config.appVersion = null;
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.currentVersion).toBeNull();
-    expect(info.isUnreleasedBuild).toBe(true);
-    expect(info.updateAvailable).toBe(false);
-  });
-
-  it('reports no update when the release tag is malformed', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v2.0'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.updateAvailable).toBe(false);
-    expect(info.latestVersion).toBe('2.0');
-  });
-
-  it('requests the latest release with a timeout', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.38'));
-
-    await AppUpdateService.getUpdateInfo();
-
-    expect(axios.get).toHaveBeenCalledWith(
-      'https://api.github.com/repos/darkraise/flashpoint-web/releases/latest',
-      expect.objectContaining({ timeout: 10000 })
-    );
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run from `backend/`: `npx vitest run src/services/AppUpdateService.test.ts`
-Expected: FAIL — cannot resolve `./AppUpdateService`.
-
-- [ ] **Step 3: Write the implementation**
-
-Create `backend/src/services/AppUpdateService.ts`:
-
-```typescript
-import axios from 'axios';
-import { config } from '../config';
-import { logger } from '../utils/logger';
-import { compareVersions, isReleaseVersion, normalizeVersion } from '../utils/version';
-
-const LATEST_RELEASE_URL =
-  'https://api.github.com/repos/darkraise/flashpoint-web/releases/latest';
-const CACHE_TTL_MS = 60 * 60 * 1000;
-const FORCED_REFRESH_FLOOR_MS = 60 * 1000;
-const REQUEST_TIMEOUT_MS = 10000;
-
-export interface AppUpdateInfo {
-  currentVersion: string | null;
-  latestVersion: string | null;
-  updateAvailable: boolean;
-  isUnreleasedBuild: boolean;
-  publishedAt: string | null;
-  releaseUrl: string | null;
-  changelog: string | null;
-  checkedAt: string | null;
-  lastCheckFailed: boolean;
-}
-
-interface CachedRelease {
-  version: string;
-  publishedAt: string | null;
-  releaseUrl: string | null;
-  changelog: string | null;
-  fetchedAt: number;
-}
-
-interface GitHubRelease {
-  tag_name?: unknown;
-  published_at?: unknown;
-  html_url?: unknown;
-  body?: unknown;
-}
-
-function asString(value: unknown): string | null {
-  return typeof value === 'string' && value.length > 0 ? value : null;
-}
-
-/**
- * Reports whether a newer release of this app exists. Notify-only: nothing here
- * downloads, installs, or restarts anything.
- */
-export class AppUpdateService {
-  private static cached: CachedRelease | null = null;
-  private static inFlight: Promise<CachedRelease> | null = null;
-  private static lastCheckFailed = false;
-
-  static async getUpdateInfo(force = false): Promise<AppUpdateInfo> {
-    // A forced check still respects a 60s floor. Express rate limiting allows
-    // 100 requests a minute, which is no protection for a GitHub quota of 60 an
-    // hour that this shares with the star count and the Ruffle update check.
-    const maxAge = force ? FORCED_REFRESH_FLOOR_MS : CACHE_TTL_MS;
-    const age = this.cached === null ? Infinity : Date.now() - this.cached.fetchedAt;
-
-    if (age >= maxAge) {
-      try {
-        await this.fetchLatestRelease();
-        this.lastCheckFailed = false;
-      } catch (error: unknown) {
-        this.lastCheckFailed = true;
-        logger.warn('[AppUpdate] Could not reach GitHub for the latest release', {
-          error: error instanceof Error ? error.message : 'Unknown error',
-        });
-      }
-    }
-
-    return this.buildInfo();
-  }
-
-  /** Concurrent callers on a cold cache share one request. */
-  private static async fetchLatestRelease(): Promise<CachedRelease> {
-    if (this.inFlight !== null) {
-      return this.inFlight;
-    }
-
-    this.inFlight = this.requestLatestRelease();
-
-    try {
-      const release = await this.inFlight;
-      this.cached = release;
-      return release;
-    } finally {
-      this.inFlight = null;
-    }
-  }
-
-  private static async requestLatestRelease(): Promise<CachedRelease> {
-    const response = await axios.get(LATEST_RELEASE_URL, {
-      timeout: REQUEST_TIMEOUT_MS,
-      headers: {
-        Accept: 'application/vnd.github.v3+json',
-        'User-Agent': 'Flashpoint-Web',
-      },
-    });
-
-    const release = (response.data ?? {}) as GitHubRelease;
-    const tagName = asString(release.tag_name);
-
-    if (tagName === null) {
-      throw new Error('GitHub release response carried no tag_name');
-    }
-
-    return {
-      version: normalizeVersion(tagName),
-      publishedAt: asString(release.published_at),
-      releaseUrl: asString(release.html_url),
-      changelog: asString(release.body),
-      fetchedAt: Date.now(),
-    };
-  }
-
-  private static buildInfo(): AppUpdateInfo {
-    const currentVersion = config.appVersion;
-    const isUnreleasedBuild = !isReleaseVersion(currentVersion);
-    const latest = this.cached;
-
-    const comparison =
-      latest !== null && currentVersion !== null && !isUnreleasedBuild
-        ? compareVersions(currentVersion, latest.version)
-        : null;
-
-    return {
-      currentVersion,
-      latestVersion: latest?.version ?? null,
-      updateAvailable: comparison !== null && comparison < 0,
-      isUnreleasedBuild,
-      publishedAt: latest?.publishedAt ?? null,
-      releaseUrl: latest?.releaseUrl ?? null,
-      changelog: latest?.changelog ?? null,
-      checkedAt: latest === null ? null : new Date(latest.fetchedAt).toISOString(),
-      lastCheckFailed: this.lastCheckFailed,
-    };
-  }
-
-  /** Drops the held release. Used by tests. */
-  static clearCache(): void {
-    this.cached = null;
-    this.inFlight = null;
-    this.lastCheckFailed = false;
-  }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run from `backend/`: `npx vitest run src/services/AppUpdateService.test.ts`
-Expected: PASS, 7 tests.
-
-- [ ] **Step 5: Commit**
-
-```bash
-npx prettier --write backend/src/services/AppUpdateService.ts backend/src/services/AppUpdateService.test.ts
-git add backend/src/services/AppUpdateService.ts backend/src/services/AppUpdateService.test.ts
-git commit -m "feat(updates): compare the app version against the latest release"
-```
-
----
-
-### Task 4: AppUpdateService — caching and failure handling
-
-**Files:**
-
-- Modify: `backend/src/services/AppUpdateService.test.ts` (append a describe block)
-- Modify: `backend/src/services/AppUpdateService.ts` only if a test fails
-
-**Interfaces:**
-
-- Consumes: everything from Task 3.
-- Produces: no new API. This task proves the caching, floor, dedupe, and failure behaviour written in Task 3.
-
-- [ ] **Step 1: Write the failing test**
-
-Append to `backend/src/services/AppUpdateService.test.ts`:
-
-```typescript
-describe('AppUpdateService caching', () => {
-  it('serves the cached release inside the hour', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-    await AppUpdateService.getUpdateInfo();
-    await AppUpdateService.getUpdateInfo();
-
-    expect(axios.get).toHaveBeenCalledTimes(1);
-  });
-
-  it('refetches after the cache expires', async () => {
-    vi.useFakeTimers();
-    try {
-      vi.setSystemTime(new Date('2026-08-12T00:00:00Z'));
-      vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-      await AppUpdateService.getUpdateInfo();
-      vi.setSystemTime(new Date('2026-08-12T01:00:01Z'));
-      await AppUpdateService.getUpdateInfo();
-
-      expect(axios.get).toHaveBeenCalledTimes(2);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('ignores a forced refresh inside the 60 second floor', async () => {
-    vi.useFakeTimers();
-    try {
-      vi.setSystemTime(new Date('2026-08-12T00:00:00Z'));
-      vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-      await AppUpdateService.getUpdateInfo();
-      vi.setSystemTime(new Date('2026-08-12T00:00:30Z'));
-      await AppUpdateService.getUpdateInfo(true);
-
-      expect(axios.get).toHaveBeenCalledTimes(1);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('honours a forced refresh past the floor', async () => {
-    vi.useFakeTimers();
-    try {
-      vi.setSystemTime(new Date('2026-08-12T00:00:00Z'));
-      vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-      await AppUpdateService.getUpdateInfo();
-      vi.setSystemTime(new Date('2026-08-12T00:01:01Z'));
-      await AppUpdateService.getUpdateInfo(true);
-
-      expect(axios.get).toHaveBeenCalledTimes(2);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('makes one request for concurrent callers on a cold cache', async () => {
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-
-    await Promise.all([
-      AppUpdateService.getUpdateInfo(),
-      AppUpdateService.getUpdateInfo(),
-      AppUpdateService.getUpdateInfo(),
-    ]);
-
-    expect(axios.get).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe('AppUpdateService failures', () => {
-  it('keeps serving the held release and flags the failed check', async () => {
-    vi.useFakeTimers();
-    try {
-      vi.setSystemTime(new Date('2026-08-12T00:00:00Z'));
-      vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-      await AppUpdateService.getUpdateInfo();
-
-      vi.setSystemTime(new Date('2026-08-12T02:00:00Z'));
-      vi.mocked(axios.get).mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));
-      const info = await AppUpdateService.getUpdateInfo();
-
-      expect(info.lastCheckFailed).toBe(true);
-      expect(info.latestVersion).toBe('1.0.42');
-      expect(info.updateAvailable).toBe(true);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it('reports a failed check with no release when it has never succeeded', async () => {
-    vi.mocked(axios.get).mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.lastCheckFailed).toBe(true);
-    expect(info.latestVersion).toBeNull();
-    expect(info.checkedAt).toBeNull();
-    expect(info.updateAvailable).toBe(false);
-    expect(info.currentVersion).toBe('1.0.38');
-  });
-
-  it('treats a response with no tag_name as a failed check', async () => {
-    vi.mocked(axios.get).mockResolvedValue({ data: { body: 'no tag here' } });
-
-    const info = await AppUpdateService.getUpdateInfo();
-
-    expect(info.lastCheckFailed).toBe(true);
-    expect(info.latestVersion).toBeNull();
-  });
-
-  it('clears the failure flag once a later check succeeds', async () => {
-    vi.mocked(axios.get).mockRejectedValueOnce(new Error('offline'));
-    const failed = await AppUpdateService.getUpdateInfo();
-    expect(failed.lastCheckFailed).toBe(true);
-
-    vi.mocked(axios.get).mockResolvedValue(release('v1.0.42'));
-    const recovered = await AppUpdateService.getUpdateInfo();
-
-    expect(recovered.lastCheckFailed).toBe(false);
-    expect(recovered.latestVersion).toBe('1.0.42');
-  });
-});
-```
-
-- [ ] **Step 2: Run the tests**
-
-Run from `backend/`: `npx vitest run src/services/AppUpdateService.test.ts`
-Expected: PASS, 16 tests total. If any fail, fix `AppUpdateService.ts` — the tests define the contract, not the other way around.
-
-Note on the recovery test: a failed check leaves `cached` null, so the next call refetches immediately with no TTL to wait out. That is intended — there is nothing to serve, so nothing to protect.
-
-- [ ] **Step 3: Run the whole backend suite**
-
-Run from `backend/`: `npx vitest run`
-Expected: all files pass.
-
-- [ ] **Step 4: Commit**
-
-```bash
-npx prettier --write backend/src/services/AppUpdateService.test.ts
-git add backend/src/services/AppUpdateService.test.ts backend/src/services/AppUpdateService.ts
-git commit -m "test(updates): cover app update caching and failures"
-```
-
----
-
-### Task 5: The endpoint and its API client
-
-**Files:**
-
-- Modify: `backend/src/routes/updates.ts` (add the route directly after `const metadataSyncService = ...`, before the `/check` route)
-- Create: `backend/src/routes/updates.test.ts`
-- Modify: `frontend/src/lib/api/updates.ts`
-- Modify: `frontend/src/lib/api/index.ts:44`
-
-**Interfaces:**
-
-- Consumes: `AppUpdateService.getUpdateInfo`, `AppUpdateInfo` from Task 3.
-- Produces: `GET /api/updates/app`; `updatesApi.getAppUpdate(refresh?: boolean): Promise<AppUpdateInfo>`; the frontend `AppUpdateInfo` type exported from `@/lib/api`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/routes/updates.test.ts`:
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import express, { Express } from 'express';
-import request from 'supertest';
-
-vi.mock('../utils/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
-}));
-
-// The route's own behaviour is what is under test, not the middleware stack.
-vi.mock('../middleware/auth', () => ({
-  authenticate: (_req: unknown, _res: unknown, next: () => void) => next(),
-}));
-vi.mock('../middleware/rbac', () => ({
-  requirePermission: () => (_req: unknown, _res: unknown, next: () => void) => next(),
-}));
-vi.mock('../middleware/activityLogger', () => ({
-  logActivity: () => (_req: unknown, _res: unknown, next: () => void) => next(),
-}));
-vi.mock('../middleware/rateLimiter', () => ({
-  rateLimitStandard: (_req: unknown, _res: unknown, next: () => void) => next(),
-}));
-
-const getUpdateInfo = vi.hoisted(() => vi.fn());
-vi.mock('../services/AppUpdateService', () => ({
-  AppUpdateService: { getUpdateInfo },
-}));
-
-// Imported for their side effects only; the route under test does not use them.
-vi.mock('../services/UpdateService', () => ({ updateService: {} }));
-vi.mock('../services/MetadataUpdateService', () => ({ MetadataUpdateService: class {} }));
-vi.mock('../services/MetadataSyncService', () => ({ MetadataSyncService: class {} }));
-vi.mock('../services/AssetDownloadService', () => ({ AssetDownloadService: {} }));
-vi.mock('../services/SyncStatusService', () => ({ SyncStatusService: { getInstance: () => ({}) } }));
-
-import updatesRouter from './updates';
-
-const INFO = {
-  currentVersion: '1.0.38',
-  latestVersion: '1.0.42',
-  updateAvailable: true,
-  isUnreleasedBuild: false,
-  publishedAt: '2026-08-12T07:11:45Z',
-  releaseUrl: 'https://github.com/darkraise/flashpoint-web/releases/tag/v1.0.42',
-  changelog: '## Changes',
-  checkedAt: '2026-08-12T08:00:00.000Z',
-  lastCheckFailed: false,
-};
-
-let app: Express;
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  getUpdateInfo.mockResolvedValue(INFO);
-  app = express();
-  app.use('/api/updates', updatesRouter);
-});
-
-describe('GET /api/updates/app', () => {
-  it('returns the update info as a bare object', async () => {
-    const response = await request(app).get('/api/updates/app');
-
-    expect(response.status).toBe(200);
-    expect(response.body).toEqual(INFO);
-  });
-
-  it('does not force a refresh by default', async () => {
-    await request(app).get('/api/updates/app');
-
-    expect(getUpdateInfo).toHaveBeenCalledWith(false);
-  });
-
-  it('forces a refresh for refresh=true', async () => {
-    await request(app).get('/api/updates/app?refresh=true');
-
-    expect(getUpdateInfo).toHaveBeenCalledWith(true);
-  });
-
-  it('ignores any other refresh value', async () => {
-    await request(app).get('/api/updates/app?refresh=1');
-    await request(app).get('/api/updates/app?refresh=yes');
-    await request(app).get('/api/updates/app?refresh[]=true');
-
-    expect(getUpdateInfo).toHaveBeenNthCalledWith(1, false);
-    expect(getUpdateInfo).toHaveBeenNthCalledWith(2, false);
-    expect(getUpdateInfo).toHaveBeenNthCalledWith(3, false);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run from `backend/`: `npx vitest run src/routes/updates.test.ts`
-Expected: FAIL — 404, because the route does not exist yet.
-
-- [ ] **Step 3: Add the route**
-
-In `backend/src/routes/updates.ts`, add the import beside the other service imports:
-
-```typescript
-import { AppUpdateService } from '../services/AppUpdateService';
-```
-
-and add this route immediately before the existing `/check` route:
-
-```typescript
-router.get(
-  '/app',
-  authenticate,
-  requirePermission('settings.update'),
-  asyncHandler(async (req, res) => {
-    // Any value other than the exact string is falsy here, so no schema is
-    // warranted; the service's own 60s floor is what guards the GitHub quota.
-    const info = await AppUpdateService.getUpdateInfo(req.query.refresh === 'true');
-    res.json(info);
-  })
-);
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run from `backend/`: `npx vitest run src/routes/updates.test.ts`
-Expected: PASS, 4 tests.
-
-- [ ] **Step 5: Add the API client method**
-
-In `frontend/src/lib/api/updates.ts`, add the interface after `AssetDownloadProgress`:
-
-```typescript
-export interface AppUpdateInfo {
-  currentVersion: string | null;
-  latestVersion: string | null;
-  updateAvailable: boolean;
-  isUnreleasedBuild: boolean;
-  publishedAt: string | null;
-  releaseUrl: string | null;
-  changelog: string | null;
-  checkedAt: string | null;
-  lastCheckFailed: boolean;
-}
-```
-
-and add this method inside `updatesApi`:
-
-```typescript
-  getAppUpdate: async (refresh = false): Promise<AppUpdateInfo> => {
-    const { data } = await apiClient.get<AppUpdateInfo>('/updates/app', {
-      params: refresh ? { refresh: 'true' } : undefined,
-    });
-    return data;
-  },
-```
-
-In `frontend/src/lib/api/index.ts`, extend the existing type re-export on line 44:
-
-```typescript
-export type {
-  MetadataUpdateInfo,
-  MetadataSyncStatus,
-  AssetDownloadProgress,
-  AppUpdateInfo,
-} from './updates';
-```
-
-- [ ] **Step 6: Typecheck**
-
-Run from the repo root: `npm run typecheck`
-Expected: no errors in either workspace.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write backend/src/routes/updates.ts backend/src/routes/updates.test.ts frontend/src/lib/api/updates.ts frontend/src/lib/api/index.ts
-git add backend/src/routes/updates.ts backend/src/routes/updates.test.ts frontend/src/lib/api/updates.ts frontend/src/lib/api/index.ts
-git commit -m "feat(updates): serve the app update check"
-```
-
----
-
-### Task 6: The card
-
-**Files:**
-
-- Create: `frontend/src/components/settings/AppUpdateCard.tsx`
-- Modify: `frontend/src/components/settings/UpdateSettingsTab.tsx`
-- Modify: `docs/10-features/09-system-settings.md`
-
-**Interfaces:**
-
-- Consumes: `updatesApi.getAppUpdate`, `AppUpdateInfo` from Task 5.
-- Produces: `<AppUpdateCard />`.
-
-- [ ] **Step 1: Write the card**
-
-Create `frontend/src/components/settings/AppUpdateCard.tsx`:
-
-```tsx
-import { useState } from 'react';
-import {
-  AlertCircle,
-  Calendar,
-  CheckCircle2,
-  ChevronDown,
-  ChevronUp,
-  ExternalLink,
-  RefreshCw,
-  Rocket,
-} from 'lucide-react';
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import ReactMarkdown from 'react-markdown';
-import remarkGfm from 'remark-gfm';
-import { Button } from '@/components/ui/button';
-import { Label } from '@/components/ui/label';
-import { FormattedDate } from '@/components/common/FormattedDate';
-import { useDialog } from '@/contexts/DialogContext';
-import { updatesApi, type AppUpdateInfo } from '@/lib/api';
-
-const UPGRADE_COMMAND = 'docker compose pull && docker compose up -d';
-
-export function AppUpdateCard() {
-  const { showToast } = useDialog();
-  const queryClient = useQueryClient();
-  const [showChangelog, setShowChangelog] = useState(false);
-
-  const { data: info, isLoading } = useQuery({
-    queryKey: ['appUpdate'],
-    queryFn: () => updatesApi.getAppUpdate(),
-    staleTime: 5 * 60 * 1000,
-  });
-
-  // A refetch would reuse the original query function, so it cannot ask for a
-  // forced check; the mutation writes its result into the same cache entry.
-  const checkNow = useMutation({
-    mutationFn: () => updatesApi.getAppUpdate(true),
-    onSuccess: (result: AppUpdateInfo) => {
-      queryClient.setQueryData(['appUpdate'], result);
-
-      if (result.lastCheckFailed) {
-        showToast('Could not reach GitHub to check for updates', 'error');
-      } else if (result.updateAvailable) {
-        showToast(`Flashpoint Web ${result.latestVersion} is available`, 'success');
-      } else if (!result.isUnreleasedBuild) {
-        showToast('Flashpoint Web is up to date', 'success');
-      }
-    },
-    onError: () => showToast('Could not check for updates', 'error'),
-  });
-
-  const checkFailedEntirely = info?.lastCheckFailed === true && info.latestVersion === null;
-
-  return (
-    <div className="bg-card rounded-lg p-6 border border-border shadow-md">
-      <div className="flex items-center justify-between mb-4">
-        <div className="flex items-center gap-2">
-          <Rocket size={24} className="text-primary" aria-hidden="true" />
-          <h2 className="text-xl font-semibold">Flashpoint Web</h2>
-        </div>
-        <Button
-          variant="outline"
-          size="sm"
-          onClick={() => checkNow.mutate()}
-          disabled={checkNow.isPending || isLoading}
-        >
-          <RefreshCw
-            className={`mr-2 h-4 w-4 ${checkNow.isPending ? 'animate-spin' : ''}`}
-            aria-hidden="true"
-          />
-          {checkNow.isPending ? 'Checking...' : 'Check for Updates'}
-        </Button>
-      </div>
-
-      <div className="space-y-4">
-        <div className="space-y-1">
-          <Label className="text-sm text-muted-foreground">Current Version</Label>
-          <div className="flex items-center gap-2">
-            <span className="text-lg font-semibold">{info?.currentVersion ?? 'Unknown'}</span>
-            {info && !info.isUnreleasedBuild && !info.updateAvailable && !info.lastCheckFailed ? (
-              <CheckCircle2 className="h-5 w-5 text-green-500" aria-hidden="true" />
-            ) : null}
-          </div>
-        </div>
-
-        {isLoading ? (
-          <div className="h-20 bg-muted rounded-lg animate-pulse" />
-        ) : null}
-
-        {checkFailedEntirely ? (
-          <div className="p-4 border border-border rounded-lg bg-muted/50 flex items-start gap-3">
-            <AlertCircle className="h-5 w-5 text-yellow-500 flex-shrink-0 mt-0.5" aria-hidden="true" />
-            <div>
-              <p className="font-medium">Could not check for updates</p>
-              <p className="text-sm text-muted-foreground mt-1">
-                GitHub could not be reached. This does not affect anything else.
-              </p>
-            </div>
-          </div>
-        ) : null}
-
-        {info && !checkFailedEntirely && info.isUnreleasedBuild ? (
-          <div className="p-4 border border-border rounded-lg bg-muted/50 space-y-1">
-            <p className="font-medium">Update checks are off</p>
-            <p className="text-sm text-muted-foreground">
-              The server did not report a released version, so there is nothing to compare
-              against. Latest release: {info.latestVersion ?? 'unknown'}
-              {info.publishedAt ? (
-                <>
-                  {' '}
-                  (<FormattedDate date={info.publishedAt} type="date" />)
-                </>
-              ) : null}
-              .
-            </p>
-          </div>
-        ) : null}
-
-        {info && !checkFailedEntirely && !info.isUnreleasedBuild ? (
-          <div className="p-4 border border-border rounded-lg bg-muted/50 space-y-3">
-            <div>
-              <p className="font-medium">
-                {info.updateAvailable
-                  ? `Update available: ${info.latestVersion}`
-                  : "You're up to date!"}
-              </p>
-              {info.publishedAt ? (
-                <div className="flex items-center gap-1 mt-2 text-xs text-muted-foreground">
-                  <Calendar className="h-3 w-3" aria-hidden="true" />
-                  <span>
-                    Released <FormattedDate date={info.publishedAt} type="date" />
-                  </span>
-                </div>
-              ) : null}
-              {info.lastCheckFailed && info.checkedAt ? (
-                <p className="text-xs text-muted-foreground mt-2">
-                  The last check failed. Showing the result from{' '}
-                  <FormattedDate date={info.checkedAt} type="datetime" />.
-                </p>
-              ) : null}
-            </div>
-
-            {info.updateAvailable ? (
-              <div className="space-y-2 border-t border-border pt-3">
-                <p className="text-sm text-muted-foreground">To upgrade, on the server:</p>
-                <pre className="bg-background border border-border rounded-lg p-3 text-xs overflow-x-auto">
-                  <code>{UPGRADE_COMMAND}</code>
-                </pre>
-                <p className="text-xs text-muted-foreground">
-                  If you pinned <span className="font-mono">IMAGE_TAG</span> in your{' '}
-                  <span className="font-mono">.env</span>, raise it first — otherwise the pull
-                  fetches the version you pinned.
-                </p>
-                {info.releaseUrl ? (
-                  <a
-                    href={info.releaseUrl}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
-                  >
-                    View release on GitHub
-                    <ExternalLink className="h-3 w-3" aria-hidden="true" />
-                  </a>
-                ) : null}
-              </div>
-            ) : null}
-
-            {info.updateAvailable && info.changelog ? (
-              <div className="border-t border-border pt-3">
-                <button
-                  onClick={() => setShowChangelog(!showChangelog)}
-                  className="flex items-center gap-2 text-sm font-medium hover:text-primary transition-colors w-full"
-                >
-                  {showChangelog ? (
-                    <ChevronUp className="h-4 w-4" aria-hidden="true" />
-                  ) : (
-                    <ChevronDown className="h-4 w-4" aria-hidden="true" />
-                  )}
-                  <span>{showChangelog ? 'Hide' : 'View'} Changelog</span>
-                </button>
-                {showChangelog ? (
-                  <div className="mt-3 p-3 bg-background border border-border rounded-lg">
-                    <div className="text-sm text-foreground/90 max-h-96 overflow-y-auto prose prose-sm dark:prose-invert max-w-none prose-headings:mt-3 prose-headings:mb-2 prose-p:my-2 prose-ul:my-2 prose-li:my-0.5 prose-code:text-xs prose-pre:text-xs">
-                      <ReactMarkdown remarkPlugins={[remarkGfm]}>{info.changelog}</ReactMarkdown>
-                    </div>
-                  </div>
-                ) : null}
-              </div>
-            ) : null}
-          </div>
-        ) : null}
-      </div>
-    </div>
-  );
-}
-```
-
-- [ ] **Step 2: Auto-expand the changelog when an update appears**
-
-Add below the `checkNow` mutation, so a fresh update opens its notes without a click:
-
-```tsx
-  const [expandedFor, setExpandedFor] = useState<string | null>(null);
-
-  if (info?.updateAvailable && info.changelog && expandedFor !== info.latestVersion) {
-    setExpandedFor(info.latestVersion);
-    setShowChangelog(true);
-  }
-```
-
-This is the render-phase state-adjustment pattern React documents for deriving state from props, and it avoids the effect-plus-dependency loop the project's guidelines warn about.
-
-- [ ] **Step 3: Mount the card**
-
-In `frontend/src/components/settings/UpdateSettingsTab.tsx`, import it and render it first:
-
-```tsx
-import { AppUpdateCard } from './AppUpdateCard';
-```
-
-```tsx
-      {/* Web App Updates (Admin Only) */}
-      {isAdmin ? <AppUpdateCard /> : null}
-
-      {/* Game Metadata Updates Section (Admin Only) */}
-      {isAdmin ? <MetadataUpdateCard /> : null}
-```
-
-- [ ] **Step 4: Typecheck and build**
-
-Run from the repo root: `npm run typecheck && npm run build`
-Expected: both clean.
-
-- [ ] **Step 5: Verify in the running app**
-
-```bash
-npm run dev
-```
-
-Open http://localhost:5173/settings → Update as an admin. With no `APP_VERSION` set, the card must show "Update checks are off" naming the latest release — not an update prompt. Then restart the backend with `APP_VERSION=1.0.1` and confirm the card reports an update, renders the changelog, and shows the upgrade command. Stop the dev servers when done.
-
-- [ ] **Step 6: Document the tab**
-
-In `docs/10-features/09-system-settings.md`, add a section after the App Tab section:
-
-```markdown
-#### Update Tab
-
-- **Flashpoint Web** - Compares the running version against the latest GitHub
-  release and shows the changelog and upgrade command. Notify only: it never
-  pulls or restarts anything. A build with no release version — a source
-  checkout, or an image built without the `VERSION` build arg — reports that
-  checks are off rather than claiming to be behind.
-- **Game Metadata** - Sync game metadata from a configured source
-- **Ruffle Emulator Management** - Check for and install Ruffle updates
-```
-
-Note: the tab list under "Settings Tabs" in that file is already stale — it names Metadata and Game tabs that the UI no longer has. Leave that alone; correcting it is not this feature's job.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write frontend/src/components/settings/AppUpdateCard.tsx frontend/src/components/settings/UpdateSettingsTab.tsx docs/10-features/09-system-settings.md
-git add frontend/src/components/settings/AppUpdateCard.tsx frontend/src/components/settings/UpdateSettingsTab.tsx docs/10-features/09-system-settings.md
-git commit -m "feat(settings): add the web app update card"
-```
-
----
-
-## Final verification
-
-- [ ] From `backend/`: `npx vitest run` — every test passes.
-- [ ] From the repo root: `npm run typecheck` — clean.
-- [ ] From the repo root: `npm run build` — clean.
-- [ ] `git log --oneline` shows six commits, one per task.
diff --git a/docs/superpowers/plans/2026-08-13-ruffle-persistent-install.md b/docs/superpowers/plans/2026-08-13-ruffle-persistent-install.md
deleted file mode 100644
index b50f823..0000000
--- a/docs/superpowers/plans/2026-08-13-ruffle-persistent-install.md
+++ /dev/null
@@ -1,798 +0,0 @@
-# Persistent Ruffle Installation Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-> **Implementer assignments:** each task names its implementer agent in an
-> `**Implementer:**` line. When executing with
-> superpowers:subagent-driven-development, REQUIRED SUB-SKILL:
-> dcc-superpower-companions:dispatching-tiered-implementers. Under
-> superpowers:executing-plans these lines are inert; ignore them.
-
-**Goal:** A Ruffle version installed through Settings → Update survives container recreation.
-
-**Architecture:** Ruffle installs into `/app/data/ruffle`, which sits on the already-mounted data volume, instead of `/app/frontend/dist/ruffle`, which lives in the container's throwaway writable layer. A fresh volume is seeded from the copy baked into the image, so Flash works immediately and offline. Express serves the persisted directory at `/ruffle`, ahead of the dist handler and with cache headers that let an updated loader actually reach browsers.
-
-**Tech Stack:** Express + TypeScript, vitest + supertest, Docker Compose.
-
-**Spec:** `docs/superpowers/specs/2026-08-13-ruffle-persistent-install-design.md`
-
-## Global Constraints
-
-- Backend tests run from the `backend/` directory with `npx vitest run`. Do **not** use `npm test` from the repository root — it enters watch mode and hangs.
-- Never introduce `any` types or non-null assertions (`!`). Use `??` for defaults, never `||`.
-- Use `logger` from `../utils/logger`, never `console`.
-- Run `npx prettier --write <files>` on every changed file before committing.
-- The environment variable name is exactly `RUFFLE_DATA_PATH`. The production default is exactly `/app/data/ruffle`.
-- `config.ruffleDataPath` is the install directory itself, not its parent. `path.join(config.ruffleDataPath, 'ruffle')` is always wrong.
-- Ruffle's content-hashed files are detected by a hex run of **16 or more** characters in the basename (`core.ruffle.4ca82b563e9711217164.js`, `f2a570ccf4468b20d95a.wasm`). Everything else — `ruffle.js`, `ruffle.js.map`, `package.json` — is stable-named and must revalidate.
-- Do not delete `frontend/public/ruffle/`. It is the seed source, and Vite serves it in development.
-- Do not add a release-note entry to `docs/09-deployment/upgrade-guide.md`. That file gains a version heading only when a release is cut, and inventing a version number here would be wrong.
-
----
-
-### Task 1: Persisted install path
-
-**Files:**
-
-- Modify: `backend/src/config.ts:118-119`
-- Modify: `backend/src/services/RuffleService.ts:41-52`
-- Test: `backend/src/services/RuffleService.test.ts:7,78-85,124-126,138-157`
-
-**Interfaces:**
-
-- Consumes: nothing.
-- Produces: `config.ruffleDataPath: string` — the absolute directory Ruffle is installed into. `RuffleService` gains a private `installPath` (the install target) and a private `bundledPath` (the image's baked copy at `<frontendDistPath>/ruffle`), both read by Task 2.
-
-**Implementer:** dcc-superpower-companions:impl-sonnet-max
-**Evaluation:** files 1 - spec 0 - coupling 2 - risk 2 = 5
-
-- [ ] **Step 1: Add the config value**
-
-In `backend/src/config.ts`, find this block:
-
-```typescript
-  // __dirname is backend/dist at runtime, so this resolves to the frontend build
-  // copied next to the backend in the image (/app/frontend/dist).
-  frontendDistPath:
-    process.env.FRONTEND_DIST_PATH ?? path.resolve(__dirname, '../../frontend/dist'),
-```
-
-Insert directly after it:
-
-```typescript
-  // Ruffle installs here rather than under the served frontend build. That build
-  // is part of the image, so it lives in the container's writable layer and an
-  // in-app update was discarded whenever the container was recreated.
-  ruffleDataPath:
-    process.env.RUFFLE_DATA_PATH ??
-    (process.env.NODE_ENV === 'production'
-      ? '/app/data/ruffle'
-      : path.resolve(__dirname, '../data/ruffle')),
-```
-
-- [ ] **Step 2: Update the test fixtures to a separate data directory**
-
-In `backend/src/services/RuffleService.test.ts`, change the declaration on line 7:
-
-```typescript
-let distDir: string;
-```
-
-to:
-
-```typescript
-let distDir: string;
-let dataDir: string;
-```
-
-Replace the config mock (lines 78-85):
-
-```typescript
-vi.mock('../config', () => ({
-  config: {
-    serveFrontend: true,
-    get frontendDistPath() {
-      return distDir;
-    },
-  },
-}));
-```
-
-with:
-
-```typescript
-vi.mock('../config', () => ({
-  config: {
-    serveFrontend: true,
-    get frontendDistPath() {
-      return distDir;
-    },
-    get ruffleDataPath() {
-      return nodePath.join(dataDir, 'ruffle');
-    },
-  },
-}));
-```
-
-Replace the `ruffleDir` helper (lines 124-126):
-
-```typescript
-function ruffleDir(): string {
-  return nodePath.join(distDir, 'ruffle');
-}
-```
-
-with:
-
-```typescript
-function ruffleDir(): string {
-  return nodePath.join(dataDir, 'ruffle');
-}
-```
-
-In `beforeEach`, replace the single `distDir` assignment:
-
-```typescript
-  distDir = nodeFs.mkdtempSync(nodePath.join(os.tmpdir(), 'fp-ruffle-'));
-```
-
-with:
-
-```typescript
-  distDir = nodeFs.mkdtempSync(nodePath.join(os.tmpdir(), 'fp-ruffle-dist-'));
-  dataDir = nodeFs.mkdtempSync(nodePath.join(os.tmpdir(), 'fp-ruffle-data-'));
-```
-
-In `afterEach`, replace:
-
-```typescript
-  nodeFs.rmSync(distDir, { recursive: true, force: true });
-```
-
-with:
-
-```typescript
-  nodeFs.rmSync(distDir, { recursive: true, force: true });
-  nodeFs.rmSync(dataDir, { recursive: true, force: true });
-```
-
-- [ ] **Step 3: Run the tests to verify they fail**
-
-Run from `backend/`: `npx vitest run src/services/RuffleService.test.ts`
-
-Expected: FAIL. The suite now asserts against `dataDir/ruffle` while the service still installs into `distDir/ruffle`, so assertions such as `expect(nodeFs.readFileSync(nodePath.join(ruffleDir(), 'ruffle.js'), 'utf-8')).toBe('new build')` throw ENOENT.
-
-- [ ] **Step 4: Point the service at the persisted path**
-
-In `backend/src/services/RuffleService.ts`, replace the field declaration and constructor (lines 41-52):
-
-```typescript
-  private readonly frontendPublicPath: string;
-  private readonly githubApiUrl = 'https://api.github.com/repos/ruffle-rs/ruffle/releases';
-
-  constructor() {
-    // Install into the directory that is actually served. In a built deployment
-    // that is the frontend's dist output; in development Vite serves public/.
-    // Pointing at public/ in a container made every fresh start re-download
-    // Ruffle even though the image already ships it in dist/.
-    this.frontendPublicPath = config.serveFrontend
-      ? path.join(config.frontendDistPath, 'ruffle')
-      : path.resolve(__dirname, '../../../frontend/public/ruffle');
-  }
-```
-
-with:
-
-```typescript
-  private readonly installPath: string;
-  private readonly bundledPath: string;
-  private readonly githubApiUrl = 'https://api.github.com/repos/ruffle-rs/ruffle/releases';
-
-  constructor() {
-    // A built deployment installs onto the mounted data volume and serves it
-    // from there: the frontend build is part of the image, so anything written
-    // into it is discarded when the container is recreated. In development Vite
-    // serves public/, which is the only directory reachable there.
-    this.installPath = config.serveFrontend
-      ? config.ruffleDataPath
-      : path.resolve(__dirname, '../../../frontend/public/ruffle');
-    this.bundledPath = path.join(config.frontendDistPath, 'ruffle');
-  }
-```
-
-Then rename the remaining nine references. Every other occurrence of `this.frontendPublicPath` in the file becomes `this.installPath` — lines 81, 447, 495, 520, 526, 527, 532, 546, and 576. A whole-word replace of `frontendPublicPath` with `installPath` across the file is exact; there are no other matches.
-
-- [ ] **Step 5: Run the tests to verify they pass**
-
-Run from `backend/`: `npx vitest run src/services/RuffleService.test.ts`
-
-Expected: PASS, all existing cases green. They now exercise install, backup, rollback, and the rename/copy fallbacks against the persisted directory.
-
-- [ ] **Step 6: Typecheck**
-
-Run from the repository root: `npm run typecheck`
-
-Expected: no errors.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write backend/src/config.ts backend/src/services/RuffleService.ts backend/src/services/RuffleService.test.ts
-git add backend/src/config.ts backend/src/services/RuffleService.ts backend/src/services/RuffleService.test.ts
-git commit -m "fix(ruffle): install onto the persisted data volume"
-```
-
----
-
-### Task 2: Seed a fresh volume from the bundled copy
-
-**Files:**
-
-- Modify: `backend/src/services/RuffleService.ts` (add two methods after `verifyInstallation`)
-- Modify: `backend/src/server.ts:296-314`
-- Test: `backend/src/services/RuffleService.test.ts` (append a new `describe` block)
-
-**Interfaces:**
-
-- Consumes: `this.installPath` and `this.bundledPath` from Task 1; the existing private `copyDirectory(source: string, target: string): void`.
-- Produces: `RuffleService.ensureInstalled(): Promise<'present' | 'seeded' | 'downloaded'>`, called by `backend/src/server.ts`.
-
-**Implementer:** dcc-superpower-companions:impl-sonnet-xhigh
-**Evaluation:** files 1 - spec 0 - coupling 2 - risk 1 = 4
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `backend/src/services/RuffleService.test.ts`:
-
-```typescript
-function installBundledRuffle(): void {
-  const bundled = nodePath.join(distDir, 'ruffle');
-  nodeFs.mkdirSync(bundled, { recursive: true });
-  nodeFs.writeFileSync(nodePath.join(bundled, 'ruffle.js'), 'bundled build');
-  nodeFs.writeFileSync(
-    nodePath.join(bundled, 'package.json'),
-    JSON.stringify({ version: '0.2.0-nightly.2026.1.29' })
-  );
-}
-
-describe('RuffleService.ensureInstalled', () => {
-  it('leaves an existing installation alone', async () => {
-    installExistingRuffle();
-    installBundledRuffle();
-
-    const result = await new RuffleService().ensureInstalled();
-
-    expect(result).toBe('present');
-    expect(nodeFs.readFileSync(nodePath.join(ruffleDir(), 'ruffle.js'), 'utf-8')).toBe('old build');
-    expect(axios.get).not.toHaveBeenCalled();
-  });
-
-  it('seeds from the bundled copy when nothing is installed', async () => {
-    installBundledRuffle();
-    const service = new RuffleService();
-
-    const result = await service.ensureInstalled();
-
-    expect(result).toBe('seeded');
-    expect(nodeFs.readFileSync(nodePath.join(ruffleDir(), 'ruffle.js'), 'utf-8')).toBe(
-      'bundled build'
-    );
-    expect(service.getCurrentVersion()).toBe('0.2.0-nightly.2026.1.29');
-    expect(axios.get).not.toHaveBeenCalled();
-  });
-
-  it('downloads when neither an installation nor a bundled copy exists', async () => {
-    const result = await new RuffleService().ensureInstalled();
-
-    expect(result).toBe('downloaded');
-    expect(nodeFs.readFileSync(nodePath.join(ruffleDir(), 'ruffle.js'), 'utf-8')).toBe('new build');
-    expect(axios.get).toHaveBeenCalled();
-  });
-});
-```
-
-- [ ] **Step 2: Run the tests to verify they fail**
-
-Run from `backend/`: `npx vitest run src/services/RuffleService.test.ts -t ensureInstalled`
-
-Expected: FAIL with `ensureInstalled is not a function`.
-
-- [ ] **Step 3: Implement the methods**
-
-In `backend/src/services/RuffleService.ts`, add both methods directly after `verifyInstallation()`, inside the class:
-
-```typescript
-  /**
-   * Copy the Ruffle shipped inside the image into the install directory. A fresh
-   * data volume otherwise has no player at all until a download finishes — and
-   * never gets one on a host that cannot reach GitHub.
-   */
-  private seedFromBundle(): boolean {
-    if (this.bundledPath === this.installPath) {
-      return false;
-    }
-    if (!fs.existsSync(path.join(this.bundledPath, 'ruffle.js'))) {
-      return false;
-    }
-    try {
-      this.copyDirectory(this.bundledPath, this.installPath);
-      logger.info(
-        `✅ Ruffle seeded from the bundled copy (version: ${this.getCurrentVersion() ?? 'unknown'})`
-      );
-      return true;
-    } catch (error: unknown) {
-      logger.warn('[RuffleService] Could not seed Ruffle from the bundled copy:', error);
-      return false;
-    }
-  }
-
-  /**
-   * Make a Ruffle available, preferring what is already installed, then the copy
-   * baked into the image, and only then a download.
-   */
-  async ensureInstalled(): Promise<'present' | 'seeded' | 'downloaded'> {
-    if (this.verifyInstallation()) {
-      logger.info(`✅ Ruffle verified (version: ${this.getCurrentVersion() ?? 'unknown'})`);
-      return 'present';
-    }
-
-    if (this.seedFromBundle()) {
-      return 'seeded';
-    }
-
-    logger.info('🎮 Ruffle not found, downloading latest version...');
-    await this.updateRuffle();
-    logger.info('✅ Ruffle installation complete');
-    return 'downloaded';
-  }
-```
-
-- [ ] **Step 4: Run the tests to verify they pass**
-
-Run from `backend/`: `npx vitest run src/services/RuffleService.test.ts`
-
-Expected: PASS, including the three new cases and every pre-existing one.
-
-- [ ] **Step 5: Call it from startup**
-
-In `backend/src/server.ts`, replace lines 296-314:
-
-```typescript
-  // Ruffle installs in the background: it downloads from GitHub, and awaiting it
-  // here kept the port closed for minutes on slow storage — indefinitely if the
-  // download stalled. Flash games need it, everything else does not.
-  void (async () => {
-    try {
-      const ruffleService = new RuffleService();
-      if (!ruffleService.verifyInstallation()) {
-        logger.info('🎮 Ruffle not found, downloading latest version...');
-        await ruffleService.updateRuffle();
-        logger.info('✅ Ruffle installation complete');
-      } else {
-        const version = ruffleService.getCurrentVersion();
-        logger.info(`✅ Ruffle verified (version: ${version || 'unknown'})`);
-      }
-    } catch (error) {
-      logger.error('Failed to install Ruffle:', error);
-      logger.warn('⚠️  Continuing without Ruffle - Flash games will not work');
-    }
-  })();
-```
-
-with:
-
-```typescript
-  // Ruffle resolves in the background: seeding copies ~20 MB and the download
-  // fallback reaches GitHub, and awaiting either here kept the port closed for
-  // minutes on slow storage. Flash games need it, everything else does not.
-  void (async () => {
-    try {
-      await new RuffleService().ensureInstalled();
-    } catch (error) {
-      logger.error('Failed to install Ruffle:', error);
-      logger.warn('⚠️  Continuing without Ruffle - Flash games will not work');
-    }
-  })();
-```
-
-- [ ] **Step 6: Typecheck and run the full backend suite**
-
-Run from the repository root: `npm run typecheck`
-
-Then run from `backend/`: `npx vitest run`
-
-Expected: no type errors, no new test failures.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write backend/src/services/RuffleService.ts backend/src/services/RuffleService.test.ts backend/src/server.ts
-git add backend/src/services/RuffleService.ts backend/src/services/RuffleService.test.ts backend/src/server.ts
-git commit -m "feat(ruffle): seed a fresh data volume from the bundled copy"
-```
-
----
-
-### Task 3: Serve the persisted directory with correct cache headers
-
-**Files:**
-
-- Modify: `backend/src/middleware/frontendServing.ts:20-55`
-- Modify: `backend/src/middleware/startupOrdering.test.ts:12-17`
-- Create: `backend/src/middleware/ruffleServing.test.ts`
-
-**Interfaces:**
-
-- Consumes: `config.ruffleDataPath` from Task 1.
-- Produces: nothing consumed by later tasks. `registerFrontendServing(app, distPath?)` keeps its existing signature; the Ruffle mount reads `config.ruffleDataPath` directly.
-
-**Implementer:** dcc-superpower-companions:impl-sonnet-max
-**Evaluation:** files 1 - spec 0 - coupling 2 - risk 2 = 5
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/middleware/ruffleServing.test.ts`:
-
-```typescript
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import express, { Express } from 'express';
-import request from 'supertest';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-vi.mock('../utils/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn(), debug: vi.fn(), warn: vi.fn() },
-}));
-
-let ruffleDir: string;
-
-vi.mock('../config', () => ({
-  config: {
-    serveFrontend: true,
-    get ruffleDataPath() {
-      return ruffleDir;
-    },
-  },
-}));
-
-import { registerFrontendServing } from './frontendServing';
-
-const HASHED_CHUNK = 'core.ruffle.4ca82b563e9711217164.js';
-
-let distDir: string;
-let app: Express;
-
-beforeEach(() => {
-  distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fp-serve-dist-'));
-  ruffleDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fp-serve-ruffle-'));
-
-  fs.writeFileSync(path.join(distDir, 'index.html'), '<!doctype html><div id="root"></div>');
-  fs.mkdirSync(path.join(distDir, 'ruffle'));
-  fs.writeFileSync(path.join(distDir, 'ruffle', 'ruffle.js'), 'bundled loader');
-  fs.writeFileSync(path.join(distDir, 'ruffle', 'only-in-bundle.js'), 'bundled extra');
-
-  fs.writeFileSync(path.join(ruffleDir, 'ruffle.js'), 'updated loader');
-  fs.writeFileSync(path.join(ruffleDir, HASHED_CHUNK), 'updated chunk');
-
-  app = express();
-  registerFrontendServing(app, distDir);
-});
-
-afterEach(() => {
-  fs.rmSync(distDir, { recursive: true, force: true });
-  fs.rmSync(ruffleDir, { recursive: true, force: true });
-});
-
-describe('Ruffle serving', () => {
-  it('serves the persisted copy in preference to the bundled one', async () => {
-    const response = await request(app).get('/ruffle/ruffle.js');
-
-    expect(response.status).toBe(200);
-    expect(response.text).toBe('updated loader');
-  });
-
-  it('falls back to the bundled copy for a file the persisted copy lacks', async () => {
-    const response = await request(app).get('/ruffle/only-in-bundle.js');
-
-    expect(response.status).toBe(200);
-    expect(response.text).toBe('bundled extra');
-  });
-
-  it('makes the stable-named loader revalidate', async () => {
-    const response = await request(app).get('/ruffle/ruffle.js');
-
-    expect(response.headers['cache-control']).toBe('no-cache, no-store, must-revalidate');
-  });
-
-  it('makes a content-hashed chunk immutable', async () => {
-    const response = await request(app).get(`/ruffle/${HASHED_CHUNK}`);
-
-    expect(response.headers['cache-control']).toBe('public, max-age=31536000, immutable');
-  });
-
-  it('makes the bundled fallback loader revalidate too', async () => {
-    const response = await request(app).get('/ruffle/only-in-bundle.js');
-
-    expect(response.headers['cache-control']).toBe('no-cache, no-store, must-revalidate');
-  });
-});
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run from `backend/`: `npx vitest run src/middleware/ruffleServing.test.ts`
-
-Expected: FAIL. `/ruffle/ruffle.js` returns `bundled loader` because no persisted mount exists, and its `Cache-Control` is `public, max-age=31536000, immutable`.
-
-- [ ] **Step 3: Add the mount and the cache policy**
-
-In `backend/src/middleware/frontendServing.ts`, add this import alongside the existing ones:
-
-```typescript
-import type { Response } from 'express';
-```
-
-Add these two declarations directly above `export function registerFrontendServing`:
-
-```typescript
-/**
- * Ruffle content-hashes its chunks (`core.ruffle.4ca82b563e9711217164.js`,
- * `f2a570ccf4468b20d95a.wasm`) but not its entry points. Detecting the hash
- * rather than listing the stable names keeps this correct when a release adds a
- * file.
- */
-const HASHED_RUFFLE_ASSET = /[0-9a-f]{16,}/i;
-
-/**
- * `ruffle.js` keeps its name across versions, so serving it immutable pinned
- * every returning browser to the loader it first saw — an update reached the
- * disk and nothing else.
- */
-function setRuffleCacheControl(res: Response, filePath: string): void {
-  res.setHeader(
-    'Cache-Control',
-    HASHED_RUFFLE_ASSET.test(path.basename(filePath))
-      ? 'public, max-age=31536000, immutable'
-      : 'no-cache, no-store, must-revalidate'
-  );
-}
-```
-
-Inside `registerFrontendServing`, insert this immediately after the `index.html` existence guard and before the existing `app.use(express.static(distPath, ...))` call:
-
-```typescript
-  // Ahead of the dist handler so an updated Ruffle shadows the one baked into
-  // the image. `fallthrough` lets the baked copy answer for anything the
-  // persisted directory is missing, including before the first seed finishes.
-  app.use(
-    '/ruffle',
-    express.static(config.ruffleDataPath, {
-      index: false,
-      fallthrough: true,
-      setHeaders: setRuffleCacheControl,
-    })
-  );
-```
-
-Then replace the `setHeaders` option on the existing dist handler:
-
-```typescript
-      setHeaders: (res, filePath) => {
-        // Hashed assets are immutable; index.html must always be revalidated.
-        if (filePath.endsWith('index.html')) {
-          res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-        }
-      },
-```
-
-with:
-
-```typescript
-      setHeaders: (res, filePath) => {
-        // Hashed assets are immutable; index.html must always be revalidated.
-        if (filePath.endsWith('index.html')) {
-          res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-          return;
-        }
-        if (filePath.startsWith(bundledRufflePath + path.sep)) {
-          setRuffleCacheControl(res, filePath);
-        }
-      },
-```
-
-and declare `bundledRufflePath` at the top of the function body, directly below the existing `const indexHtml = path.join(distPath, 'index.html');`:
-
-```typescript
-  const bundledRufflePath = path.join(distPath, 'ruffle');
-```
-
-- [ ] **Step 4: Run the test to verify it passes**
-
-Run from `backend/`: `npx vitest run src/middleware/ruffleServing.test.ts`
-
-Expected: PASS, all five cases.
-
-- [ ] **Step 5: Repair the sibling middleware test's config mock**
-
-`backend/src/middleware/startupOrdering.test.ts` mocks `../config` without `ruffleDataPath`, and `express.static(undefined)` throws `TypeError: root path required`. Replace its mock (lines 12-17):
-
-```typescript
-vi.mock('../config', () => ({
-  config: {
-    serveFrontend: true,
-    frontendDistPath: '/unused-in-tests',
-  },
-}));
-```
-
-with:
-
-```typescript
-vi.mock('../config', () => ({
-  config: {
-    serveFrontend: true,
-    frontendDistPath: '/unused-in-tests',
-    ruffleDataPath: '/unused-in-tests/ruffle',
-  },
-}));
-```
-
-- [ ] **Step 6: Run the full backend suite and typecheck**
-
-Run from `backend/`: `npx vitest run`
-
-Then run from the repository root: `npm run typecheck`
-
-Expected: no failures and no type errors. `startupOrdering.test.ts` in particular must stay green — a missing-directory static mount with `fallthrough: true` calls `next()` instead of throwing.
-
-- [ ] **Step 7: Commit**
-
-```bash
-npx prettier --write backend/src/middleware/frontendServing.ts backend/src/middleware/ruffleServing.test.ts backend/src/middleware/startupOrdering.test.ts
-git add backend/src/middleware/frontendServing.ts backend/src/middleware/ruffleServing.test.ts backend/src/middleware/startupOrdering.test.ts
-git commit -m "fix(ruffle): serve the persisted install ahead of the bundled one"
-```
-
----
-
-### Task 4: Deployment configuration and documentation
-
-**Files:**
-
-- Modify: `docker-compose.dev.yml:28-40`
-- Modify: `docker-compose.yml:29-33`
-- Modify: `docs/09-deployment/environment-variables.md:113-116`
-
-**Interfaces:**
-
-- Consumes: the `RUFFLE_DATA_PATH` variable name and the `/app/data/ruffle` default from Task 1.
-- Produces: nothing.
-
-**Implementer:** dcc-superpower-companions:impl-sonnet-medium
-**Evaluation:** files 1 - spec 0 - coupling 1 - risk 0 = 2
-
-- [ ] **Step 1: Set the variable in the dev compose file**
-
-`docker-compose.dev.yml` runs `NODE_ENV=development` with `SERVE_FRONTEND=true`, so the production-keyed default resolves to a relative path inside the container and misses the `backend-db:/app/data` volume. In `docker-compose.dev.yml`, find:
-
-```yaml
-      # Matches the read-only mount above. Set explicitly because the backend's
-      # fallback only points here when NODE_ENV=production.
-      - FLASHPOINT_PATH=/data/flashpoint
-```
-
-Insert directly after it:
-
-```yaml
-      # Same reason as FLASHPOINT_PATH above: this container runs
-      # NODE_ENV=development, so the production default would put Ruffle outside
-      # the data volume and lose every update on recreate.
-      - RUFFLE_DATA_PATH=/app/data/ruffle
-```
-
-- [ ] **Step 2: Update both volume comments**
-
-In `docker-compose.yml`, find:
-
-```yaml
-      - ${FLASHPOINT_HOST_PATH:?FLASHPOINT_HOST_PATH is required}:/data/flashpoint
-      - ${DATA_PATH:-./data}:/app/data
-```
-
-Replace with:
-
-```yaml
-      - ${FLASHPOINT_HOST_PATH:?FLASHPOINT_HOST_PATH is required}:/data/flashpoint
-      # Holds user.db and the installed Ruffle. Without this mount an in-app
-      # Ruffle update is lost the next time the container is recreated.
-      - ${DATA_PATH:-./data}:/app/data
-```
-
-In `docker-compose.dev.yml`, find:
-
-```yaml
-      - ${FLASHPOINT_HOST_PATH:?FLASHPOINT_HOST_PATH is required}:/data/flashpoint
-      - backend-db:/app/data
-```
-
-Replace with:
-
-```yaml
-      - ${FLASHPOINT_HOST_PATH:?FLASHPOINT_HOST_PATH is required}:/data/flashpoint
-      # Holds user.db and the installed Ruffle. Without this mount an in-app
-      # Ruffle update is lost the next time the container is recreated.
-      - backend-db:/app/data
-```
-
-- [ ] **Step 3: Document the variable**
-
-In `docs/09-deployment/environment-variables.md`, find this table:
-
-```markdown
-| Variable             | Default                       | Description                                                    |
-| -------------------- | ----------------------------- | -------------------------------------------------------------- |
-| `SERVE_FRONTEND`     | true in production, else false | Serve the built frontend and SPA fallback from the backend    |
-| `FRONTEND_DIST_PATH` | `<backend>/../frontend/dist`  | Location of the built frontend (rarely needed)                 |
-```
-
-Add one row to it:
-
-```markdown
-| `RUFFLE_DATA_PATH`   | `/app/data/ruffle` in production | Where Ruffle is installed. Must sit on a mounted volume, or an in-app update is lost when the container is recreated |
-```
-
-- [ ] **Step 4: Verify both compose files still parse**
-
-Run from the repository root:
-
-```bash
-docker compose -f docker-compose.yml config --quiet
-docker compose -f docker-compose.dev.yml config --quiet
-```
-
-Expected: both exit 0 and print nothing. Each file requires `FLASHPOINT_HOST_PATH` and `JWT_SECRET`; if the repository has no `.env`, supply throwaway values inline:
-
-```bash
-FLASHPOINT_HOST_PATH=/tmp/fp JWT_SECRET=x docker compose -f docker-compose.yml config --quiet
-FLASHPOINT_HOST_PATH=/tmp/fp JWT_SECRET=x docker compose -f docker-compose.dev.yml config --quiet
-```
-
-If the Docker CLI is unavailable in this environment, say so rather than skipping silently, and parse both files directly instead:
-
-```bash
-node -e "const y=require('yaml');const fs=require('fs');for(const f of ['docker-compose.yml','docker-compose.dev.yml']){y.parse(fs.readFileSync(f,'utf8'));console.log(f,'ok')}"
-```
-
-The `yaml` package is already present in the repository's `node_modules` as a transitive dependency. This proves the YAML parses; it does not check Compose semantics, so report which of the two checks you ran.
-
-- [ ] **Step 5: Commit**
-
-```bash
-npx prettier --write docker-compose.yml docker-compose.dev.yml docs/09-deployment/environment-variables.md
-git add docker-compose.yml docker-compose.dev.yml docs/09-deployment/environment-variables.md
-git commit -m "docs(ruffle): document the persisted install path"
-```
-
----
-
-## Verification
-
-After Task 4, confirm the whole change from the repository root:
-
-```bash
-npm run typecheck
-npm run build
-```
-
-Then from `backend/`: `npx vitest run`
-
-Expected: typecheck clean, build succeeds, backend suite green.
-
-Manual confirmation in a container, which is what the reported bug needs:
-
-1. `docker compose -f docker-compose.dev.yml up -d --build`
-2. Settings → Update → update Ruffle, and note the version.
-3. `docker compose -f docker-compose.dev.yml up -d --force-recreate`
-4. Settings → Update still reports the updated version, and a hard-refreshed
-   browser loads it.
diff --git a/docs/superpowers/specs/2026-08-11-downloaded-games-design.md b/docs/superpowers/specs/2026-08-11-downloaded-games-design.md
deleted file mode 100644
index 57772cb..0000000
--- a/docs/superpowers/specs/2026-08-11-downloaded-games-design.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# Downloaded games: page, filter, and settings
-
-Date: 2026-08-11
-
-## Goal
-
-1. A "Downloaded" sidebar entry and page listing only downloaded games.
-2. A downloaded filter in the filter panel on the existing browse pages.
-3. An admin setting to show or hide the Downloaded page.
-4. An admin setting that lets guests see the Downloaded page, offered only when
-   the page itself is enabled.
-5. An admin setting that turns the downloaded filter on by default.
-
-## Definition of "downloaded"
-
-A game is downloaded when it has at least one `game_data` row with
-`presentOnDisk = 1`.
-
-Games with no `game_data` rows at all — legacy titles served from htdocs — can
-never be downloaded under this definition and never appear on the page. This
-matches the existing per-game badge, which reads the same flag through the
-`MAX(presentOnDisk)` post-processing in `GameService.searchGames`.
-
-## Keeping the flag truthful
-
-`presentOnDisk` is currently written only by the Flashpoint Launcher and by the
-explicit Download button (`DownloadManager` → `GameDatabaseUpdater.markAsDownloaded`).
-Three gaps must close before the flag can drive a whole page.
-
-**Play-path downloads never set it.** `GameZipServer.downloadAndMountInBackground`
-writes the ZIP and returns without touching the database. On success it will call
-`GameDatabaseUpdater.markAsDownloaded`. The `game_data.id` is already loaded by
-`GameDataService.getGameDataEntry`; thread it through the `mountZip` params rather
-than re-querying by `gameId` + `dateAdded`. Mark the row even when `sha256` is
-absent, since `GameDataDownloader` only verifies a checksum when one exists and the
-file is otherwise a complete, mountable download.
-
-**Local-copy mode erases the flag.** With `ENABLE_LOCAL_DB_COPY=true`, queries and
-our writes hit `config.localDbPath`, and `DatabaseService.syncAndReload` copies the
-source over that file whenever the Launcher's database changes. A new
-`DownloadedReconciler` service restores truth from disk:
-
-- Scan `config.flashpointGamesPath` for files matching `{uuid}-{timestamp}.zip`,
-  the deterministic name produced by `GameDataDownloader.getFilename`.
-- Resolve each to its `game_data` row by `gameId` plus the timestamp derived from
-  `dateAdded`, and bulk-set `presentOnDisk = 1` in a single transaction, skipping
-  rows already flagged.
-- Update `game.activeDataOnDisk` where the marked row is the game's active data.
-- Run once at startup after `DatabaseService` initialization, and again after every
-  `syncAndReload`. Both runs are fire-and-forget with a `.catch()`; an unreadable
-  games directory logs a warning and yields zero marks.
-
-The reconciler only ever marks. It never clears the flag for a missing ZIP, because
-the Launcher can store game data outside `flashpointGamesPath` and we would be
-overwriting its state with a false negative.
-
-This scan also backfills every game downloaded through the Play path before this
-feature ships, which is otherwise the largest population of invisible downloads.
-
-**Our own writes trigger a full reload.** In non-copy mode the write lands in the
-file `DatabaseService` watches, so the watcher fires, reopens the connection, and
-clears the search, flash-SWF, and filter-options caches — per download. Add
-`DatabaseService.noteSelfWrite()`, which re-stats the source and advances
-`lastModifiedTime` so `syncAndReload` short-circuits, and call it from
-`markAsDownloaded` and the reconciler. The caller then clears only the search and
-filter-options caches, so a freshly downloaded game appears immediately.
-
-A Launcher write landing in the same millisecond as ours could be swallowed by this
-check. The consequence is a delayed reload, not data loss, and the next Launcher
-write recovers it.
-
-## Backend filter
-
-`downloaded?: boolean` joins the POST `/api/games` body schema, `GameSearchQuery`,
-and the filter-options query schema. `true` restricts to downloaded games;
-`false` and `undefined` both mean "no restriction", and the frontend omits the
-field when the filter is off.
-
-In `GameService.searchGames` the condition is:
-
-```sql
-AND EXISTS (SELECT 1 FROM game_data gd WHERE gd.gameId = g.id AND gd.presentOnDisk = 1)
-```
-
-`buildFilterOptionsConditions` gets the same condition so dropdown values and the
-year range narrow to downloaded games; qualify the outer column with its table name
-there, since those queries have no alias and `game_data` has its own `id` column.
-
-Both `GameSearchCache.generateCacheKey` and `GameService.getFilterOptionsCacheKey`
-include `downloaded`, normalized with `??` so `undefined` and `false` stay distinct.
-Add `'downloaded'` to the `filters` array in the search route's `logActivity`
-callback so the recorded filter count stays accurate.
-
-## Frontend filter
-
-`GameFilters.downloaded?: boolean` carries the value to the API.
-`FilterUrlParams.downloaded?: '0' | '1'` carries it in the URL under the unused
-single-character key `w`, guarded with `!== undefined` rather than truthiness so an
-explicit off survives `toUrlSafeFormat`.
-
-The value is tri-state: `w.1` on, `w.0` off, absent means "use the admin default".
-`GameBrowseLayout` resolves it once and passes a plain boolean down.
-
-Because absent means "default", removal cannot clear the parameter when the default
-is on — the filter would immediately reapply. When the admin default is on,
-`handleRemoveChip` and `handleClearAllFilters` write `w.0` instead of dropping the
-key; when it is off, they clear it as every other filter does. `CATEGORY_TO_ABBR`
-gains `Downloaded: 'W'` and `categoryToParamKeys` gains the matching entry so the
-chip participates in the existing filter hierarchy.
-
-A bookmarked URL with no `w` changes meaning if an admin later flips the default.
-That is inherent to the tri-state and accepted.
-
-`FilterPanel` renders a "Downloaded only" switch beside the year range in both the
-desktop and mobile rows, and an active filter chip. A new `showDownloadedFilter`
-prop hides the switch on the Downloaded page, where the filter is the page.
-
-## Downloaded page
-
-Route `/downloaded` renders `DownloadedView`, a thin wrapper over
-`GameBrowseLayout` with the filter pinned on and no library restriction, so results
-span arcade and theatre. `GameBrowseLayout`'s `library` prop becomes optional and it
-gains `forceDownloaded`.
-
-The page passes `sectionKey={null}`, so game links resolve to the existing
-`/games/:id` detail route. No new per-section detail or play routes.
-
-## Settings
-
-Migration `004_downloaded_settings.sql` seeds three public boolean settings in the
-`features` category, following the existing `enable_*` naming:
-
-| Key | Default | Effect |
-| --- | --- | --- |
-| `features.enable_downloaded_page` | 1 | Sidebar entry and `/downloaded` route |
-| `features.enable_downloaded_page_for_guests` | 0 | Guests may see the page |
-| `features.enable_downloaded_filter_default` | 0 | Browse pages start filtered |
-
-`useFeatureFlags` exposes `enableDownloadedPage` with the usual admin bypass, so an
-admin cannot lock themselves out. The other two are read as `=== true`: they default
-off, and the hook's `?? true` fallback would otherwise invert them during the
-public-settings loading window and whenever the key is missing.
-
-`ProtectedRoute` gains `'enableDownloadedPage'` in its `requireFeature` union and a
-new `requireFeatureForGuests` prop, checked only when the viewer is a guest, so a
-guest deep-linking to `/downloaded` with the guest flag off is redirected to
-`/unauthorized`. A flag check alone would let them through, since guests satisfy
-`requireAuth`.
-
-These flags are presentation, not access control: `POST /api/games` is open to
-guests and accepts `downloaded` regardless, and the page shows no data a guest
-cannot already reach by filtering Browse. No backend enforcement is added.
-
-`FeaturesSettingsTab` gains the three switches, with the guest row rendered only
-while the page flag is on. Its stored value persists while hidden and resurfaces if
-the page is re-enabled.
-
-## Sidebar
-
-The Downloaded entry sits in the Library section with Favorites. That block is
-currently hidden wholesale for guests, so its items never check guest status
-themselves. Relaxing the block requires giving each item its own predicate:
-Favorites and both playlist entries become explicitly `!isGuest`, Downloaded
-becomes `enableDownloadedPage && (!isGuest || enableDownloadedPageForGuests)`, and
-the section renders when any item survives. The existing
-`isViewingSharedPlaylistWithoutGuestAccess` case is unaffected.
-
-## Testing
-
-- `GameService.searchGames` returns only flagged games with `downloaded: true`, and
-  is unaffected when the field is absent.
-- Filter options narrow when `downloaded` is set, and cache keys distinguish
-  `undefined`, `false`, and `true`.
-- `DownloadedReconciler` maps ZIP filenames to the right `game_data` rows, ignores
-  unrelated files, and marks nothing when the directory is unreadable.
-- `filterUrlCompression` round-trips `w.0` and `w.1`, and an explicit off survives
-  `buildFilterSearchParams`.
-- Chip removal writes an explicit off when the admin default is on.
-
-## Documentation
-
-Update `docs/06-api-reference/games-api.md` (search and filter-options parameters),
-`docs/06-api-reference/settings-api.md` (three new settings), and
-`docs/10-features/02-game-browsing-filtering.md` (the filter and the page).
diff --git a/docs/superpowers/specs/2026-08-12-web-app-update-design.md b/docs/superpowers/specs/2026-08-12-web-app-update-design.md
deleted file mode 100644
index a62d19a..0000000
--- a/docs/superpowers/specs/2026-08-12-web-app-update-design.md
+++ /dev/null
@@ -1,234 +0,0 @@
-# Web app update check on the Update page
-
-Date: 2026-08-12
-
-## Goal
-
-An admin opening Settings → Update sees whether a newer release of Flashpoint
-Web exists, what changed in it, and how to upgrade.
-
-The card notifies only. It never pulls an image, restarts a container, or writes
-anything: self-updating from inside the container needs the Docker socket
-mounted, which hands the container root-equivalent control of the host.
-
-## What counts as an update
-
-The running version comes from `APP_VERSION`, an environment variable baked into
-the image from the `VERSION` build arg that CI already passes (see
-`.github/workflows/docker-build-push.yml`). This mirrors `VITE_APP_VERSION`,
-which the frontend build consumes for the same value.
-
-A version counts as a release build only when it is three clean numbers, with an
-optional leading `v` — `1.0.38` or `v1.0.38`. Anything else is an **unreleased
-build**: the variable unset, `dev` from a local `docker build`, `latest` from a
-`workflow_dispatch` run, a release candidate like `1.1.0-rc1`, or a
-`git describe` string like `1.0.38-5-gabc123`. An unreleased build never claims
-to be behind, because its commits may already include everything in the latest
-release.
-
-The comparison target is GitHub's
-`/repos/darkraise/flashpoint-web/releases/latest`, which excludes prereleases by
-definition. No prerelease filtering is needed, and release candidates never
-surface.
-
-Verified against the live endpoint on 2026-08-12: it answers 200 with
-`tag_name: "v1.0.38"`, `prerelease: false`, `published_at`, `html_url`, and a
-markdown `body`. The tag carries a leading `v` that `APP_VERSION` does not, so
-both sides are stripped before comparing — the tag always has one, and a manual
-`docker build --build-arg VERSION=v1.0.38` would otherwise be misread as
-unreleased.
-
-## The two version sources must not contradict each other
-
-The frontend already resolves its own version at build time
-(`frontend/vite.config.ts`, `frontend/src/lib/version.ts`) and shows it on the
-General tab as "Web App Version". This design adds a second, server-side source,
-and the two sit one tab apart.
-
-In Docker they agree: both build stages receive the same `VERSION` build arg. In
-a source checkout they can differ — the frontend falls back to `git describe`,
-while the backend has no `APP_VERSION` at all — so the General tab could read
-`1.0.38` while the card reads "unreleased build". The card's copy therefore
-attributes the state to the server rather than to the operator: "The server did
-not report a released version, so update checks are off."
-
-`APP_VERSION` is documented in `docs/09-deployment/environment-variables.md` as
-an optional operator-settable variable, so a non-Docker deployment can opt into
-update checks.
-
-## Backend
-
-### `compareVersions(a, b)` — `backend/src/utils/version.ts`
-
-Returns a negative number, zero, or a positive number by comparing major, minor,
-and patch numerically, after stripping an optional leading `v` from each side.
-Returns `null` when either input is not exactly three numeric parts, which is
-what routes an unreleased build away from the comparison. Numeric comparison
-matters: string ordering puts `1.0.9` above `1.0.38`.
-
-A `null` result from a malformed *latest* tag — a hand-cut release tagged `v2.0`
-— yields `updateAvailable: false`. Reporting nothing is preferable to reporting
-a wrong direction.
-
-### `AppUpdateService` — `backend/src/services/AppUpdateService.ts`
-
-One public method, `getUpdateInfo(force = false)`, returning:
-
-```ts
-interface AppUpdateInfo {
-  currentVersion: string | null; // null when APP_VERSION is unset
-  latestVersion: string | null; // null when GitHub has never been reached
-  updateAvailable: boolean;
-  isUnreleasedBuild: boolean;
-  publishedAt: string | null;
-  releaseUrl: string | null;
-  changelog: string | null;
-  checkedAt: string | null; // when the held result was fetched
-  lastCheckFailed: boolean;
-}
-```
-
-The result is cached in memory for one hour and shared by every admin. The cache
-holds the last *successful* result; a failed check returns that result with
-`lastCheckFailed: true` rather than discarding it.
-
-**Concurrency.** The in-flight fetch promise is stored and returned to
-concurrent callers, so a cold cache hit by several requests at once produces one
-GitHub call, not several.
-
-**Forced refresh.** `force` bypasses the one-hour cache but not a 60-second
-floor: a forced check within 60 seconds of the last fetch returns the held
-result. `rateLimitStandard` is 100 requests per 60-second window
-(`backend/src/config.ts`, `RATE_LIMIT_MAX_REQUESTS`), which is no protection for
-a 60-per-hour unauthenticated GitHub quota that this feature shares with the
-star-count proxy and the Ruffle update check. The floor is what keeps the quota
-intact.
-
-`isUnreleasedBuild: true` still fetches and reports `latestVersion` and the
-changelog for reference, but forces `updateAvailable: false`.
-
-### Failure handling
-
-The route always answers 200. A total failure — no cached result and GitHub
-unreachable — returns `latestVersion: null` with `lastCheckFailed: true`, and
-the card renders its failed state.
-
-It does **not** throw `AppError(502)`, because the axios interceptor in
-`frontend/src/lib/api/client.ts` fires a global "Server error occurred" toast for
-any status at or above 500. A card that renders its own inline error would
-double up with that toast, which is what the Ruffle card does today.
-
-`backend/src/routes/github.ts` is the precedent for serving a stale result, but
-it is a weaker version of this design and should not be copied line for line: it
-throws a plain `Error`, has no request timeout, and its stale path covers only a
-non-OK response, so a network failure or hang bypasses the cache entirely. Here
-the `try` wraps the whole fetch, and the request carries an explicit timeout.
-
-### `GET /api/updates/app`
-
-Added to `backend/src/routes/updates.ts` behind `authenticate` and
-`requirePermission('settings.update')` from `../middleware/rbac`. That matches
-the tab's own gate in `UpdateSettingsTab.tsx`; note that two GETs in that file
-use `settings.read`, so "the same as its neighbours" is not exact.
-
-The handler returns the bare `AppUpdateInfo` object — `res.json(info)` — as
-every endpoint in `updates.ts` does and as `updatesApi` expects. The
-`{success, data}` envelope in `github.ts` is that router's convention, not this
-one.
-
-`?refresh=true` sets `force`, read as `req.query.refresh === 'true'`. Any other
-value, array, or object is falsy, so no schema or bounds check is warranted; the
-60-second floor is the real control. `rateLimitStandard` already applies to the
-whole router.
-
-### `config.appVersion`
-
-`process.env.APP_VERSION?.trim() || null`, added to `backend/src/config.ts`
-beside the Flashpoint version fields. `||` is deliberate here and must not be
-"corrected" to `??`: an empty or whitespace-only variable has to collapse to
-`null`, which `??` would not do.
-
-### Dockerfile
-
-The final stage already declares `ARG VERSION=dev` for the image label. It gains
-`ENV APP_VERSION=$VERSION`, since an `ARG` alone does not survive into the
-running container.
-
-## Frontend
-
-`AppUpdateCard` — `frontend/src/components/settings/AppUpdateCard.tsx` — renders
-first in `UpdateSettingsTab`, above the metadata and Ruffle cards, admin-only
-like both of them.
-
-A `useQuery` on mount performs the check. The Check button cannot be a
-`refetch()`, which reuses the original query function and so cannot add
-`refresh=true`; it is a `useMutation` calling the endpoint with the flag, writing
-its result back through `queryClient.setQueryData`. This is the shape the Ruffle
-card already uses.
-
-The card reuses the vocabulary of `RuffleManagementCard`: a collapsible
-changelog rendered with `react-markdown` and `remark-gfm`, `FormattedDate` for
-the release date, the same button placement and toast behaviour. No sanitizer is
-added — without `rehype-raw`, react-markdown escapes raw HTML, and the source is
-the project's own CI-generated release notes.
-
-Five states:
-
-| State            | Condition                                | Shows                                                                                                    |
-| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Update available | `updateAvailable`                        | Both versions, release date, changelog expanded, link to the release, upgrade commands                   |
-| Up to date       | versions match                           | Current version and when it was checked                                                                  |
-| Unreleased build | `isUnreleasedBuild`                      | "The server did not report a released version, so update checks are off", plus the latest release for reference |
-| Stale            | `lastCheckFailed` with a `latestVersion` | The held result, labelled as a check that failed at `checkedAt`                                          |
-| Check failed     | `lastCheckFailed`, no `latestVersion`    | A muted error and a retry button                                                                         |
-
-The upgrade command is `docker compose pull && docker compose up -d`, matching
-the deployment `docker-compose.yml` documents. That file pins
-`image: darkraise/flashpoint-web:${IMAGE_TAG:-latest}`, so the card adds one
-line: an operator who set `IMAGE_TAG` to a fixed version must raise it first, or
-the pull is a no-op.
-
-The release body generated by CI opens with its own "## Docker Image" section
-carrying a `docker pull` line, so the changelog repeats part of this. The card
-still states the commands itself, because the compose commands are the actual
-upgrade and the changelog is collapsible.
-
-The API call goes through `updatesApi` in `frontend/src/lib/api/updates.ts`, with
-`AppUpdateInfo` declared there and re-exported from `lib/api/index.ts`, as the
-other update types are.
-
-## Testing
-
-Backend unit tests in the repo's existing style, with no test for the card —
-`components/settings` has no test coverage today and this change does not
-introduce the pattern.
-
-- `compareVersions`: equal, newer, older, multi-digit ordering (`1.0.38` above
-  `1.0.9`), a leading `v` on either or both sides, and malformed inputs (`dev`,
-  `latest`, `1.0.38-5-gabc123`, `1.0`, empty).
-- `AppUpdateService` with a mocked fetch: update available, up to date,
-  unreleased build, malformed latest tag, cache hit inside the hour, forced
-  refresh honoured after the 60-second floor and ignored inside it, one GitHub
-  call for concurrent cold-cache requests, a held result returned with
-  `lastCheckFailed` after a failure, and a 200 with `latestVersion: null` when a
-  failure has no cache to fall back on.
-
-## Decisions taken
-
-- **Notify only.** Self-update requires the Docker socket; a restart-only button
-  cannot pull, so it would only ever help someone who had already pulled.
-- **The repository is hardcoded** to `darkraise/flashpoint-web`, as it already is
-  in the star-count proxy. A fork wanting its own release feed would need this
-  made configurable; nothing here is designed to prevent that later.
-- **Docker Compose is the documented deployment**, so it is the only upgrade
-  command shown.
-- **No notification badge** elsewhere in the UI, and no scheduled background
-  check. The cached on-open check covers the stated goal; a `JobScheduler` job
-  would be the way to add a badge later.
-
-## Known limitation, not addressed here
-
-A `workflow_dispatch` run of the build workflow tags the image `:latest` and
-passes `VERSION=latest`, so that image reports an unreleased build. The card
-makes a pre-existing CI wart visible; fixing it means changing what the manual
-trigger publishes, which is out of scope for this feature.
diff --git a/docs/superpowers/specs/2026-08-13-ruffle-persistent-install-design.md b/docs/superpowers/specs/2026-08-13-ruffle-persistent-install-design.md
deleted file mode 100644
index f3bc738..0000000
--- a/docs/superpowers/specs/2026-08-13-ruffle-persistent-install-design.md
+++ /dev/null
@@ -1,131 +0,0 @@
-# Persistent Ruffle installation
-
-Date: 2026-08-13
-
-## Goal
-
-A Ruffle version installed through Settings → Update survives container
-recreation. Today it does not: the update lands in the container's writable
-layer, and the next `docker compose up -d` after an image pull or a config
-change throws it away.
-
-## Why it reverts
-
-`RuffleService` installs into `config.frontendDistPath/ruffle` — `/app/frontend/dist/ruffle`
-inside the container. The only mounted volumes are `/data/flashpoint`,
-`/app/data`, and `/app/logs`, so that path lives entirely in the overlay
-writable layer.
-
-`frontend/public/ruffle/` is committed to the repository at
-`0.2.0-nightly.2026.1.29`. Vite copies `public/` into `frontend/dist/` at build
-time and the Dockerfile bakes that directory into the image. When a recreate
-discards the writable layer, the baked copy is what remains.
-
-Startup only downloads when `verifyInstallation()` is false
-(`backend/src/server.ts:302`). The baked copy satisfies that check, so the
-server logs the stale version and keeps it. The scheduled `ruffle-update` job
-would eventually re-apply the update, but only if that job is enabled.
-
-A plain `docker restart` preserves the writable layer and does not trigger this.
-The recreate paths do: `docker compose up -d` after an image pull or any change
-to the resolved service config, `down` then `up`, `--force-recreate`, and the
-update actions in Portainer and Unraid.
-
-## Install location
-
-A new `config.ruffleDataPath` names the install directory:
-
-```
-process.env.RUFFLE_DATA_PATH ??
-  (NODE_ENV === 'production' ? '/app/data/ruffle' : <repo>/backend/data/ruffle)
-```
-
-`RuffleService` swaps only its `serveFrontend` branch to this path. The other
-branch keeps writing to `frontend/public/ruffle`, because in a source checkout
-Vite serves `public/` and an install anywhere else would not be reachable.
-
-`docker-compose.dev.yml` sets `RUFFLE_DATA_PATH=/app/data/ruffle` explicitly. It
-runs `NODE_ENV=development` with `SERVE_FRONTEND=true`, so the production-keyed
-default would miss its `backend-db:/app/data` volume. The file already sets
-`FLASHPOINT_PATH` for exactly this reason, and the new variable follows that
-precedent. Production compose needs no change: `NODE_ENV=production` already
-resolves to the right path.
-
-The entrypoint chowns `/app/data` to the app user on every start, so a non-default
-`PUID` can write the new directory without further work.
-
-## Seeding a fresh install
-
-`RuffleService.ensureInstalled()` replaces the inline block at
-`backend/src/server.ts:299-314` and resolves in three steps:
-
-1. `ruffle.js` exists at the data path — log the version and stop.
-2. Otherwise the image's bundled `frontend/dist/ruffle` exists — copy it into
-   the data path via the existing private `copyDirectory`.
-3. Otherwise — download the latest release from GitHub, which is the current
-   behaviour.
-
-Seeding from the bundle rather than downloading means Flash works the moment a
-fresh container is up, and works at all on a host that cannot reach GitHub. The
-copy is roughly 20 MB and happens once per persisted volume, not once per
-container.
-
-The call stays fire-and-forget in the background. Awaiting it would hold the
-port closed for the duration of a download, which is the regression the current
-comment at `server.ts:296-298` records.
-
-## Serving
-
-`registerFrontendServing` mounts the data path at `/ruffle` **before**
-`express.static(distPath)`, so the persisted copy shadows the baked one. The
-mount uses `fallthrough: true`: if the persisted tree is missing a file, the
-baked `dist/ruffle` still answers rather than 404ing into a dead player.
-
-The frontend needs no change. `RufflePlayer.tsx` already loads
-`/ruffle/ruffle.js` and sets `publicPath: '/ruffle/'`, both of which the new
-mount serves.
-
-## Cache headers
-
-The dist handler currently serves everything with `maxAge: '1y', immutable: true`,
-including `ruffle/ruffle.js`, which is not content-hashed. A browser that has
-loaded the page once will therefore keep the old loader for a year, so
-persistence alone would not make an update visible to returning users.
-
-A shared helper decides the policy from the basename: `immutable, max-age=1y`
-when it contains a hex run of 16 or more characters, otherwise
-`no-cache, no-store, must-revalidate`. Ruffle's chunks carry such a run
-(`core.ruffle.4ca82b563e9711217164.js`, `f2a570ccf4468b20d95a.wasm`) while its
-stable entry points do not (`ruffle.js`, `ruffle.js.map`, `package.json`).
-Detecting the hash rather than listing the stable names keeps the rule correct
-when a future Ruffle release adds a file.
-
-The helper applies to both the new `/ruffle` mount and to `ruffle/` paths under
-the dist handler, so the fallback cannot reintroduce a stale loader.
-
-## Testing
-
-`RuffleService.test.ts` mocks `../config`; that mock gains `ruffleDataPath` and
-the existing `ruffleDir()` helper points at it. The update tests are otherwise
-unchanged — they exercise the rename and copy fallbacks, which the new path does
-not alter.
-
-New cases cover `ensureInstalled()`:
-
-- an existing install is left alone and no download is attempted;
-- an empty data path with a bundled copy present is seeded from the bundle, and
-  no download is attempted;
-- an empty data path with no bundle falls through to the download.
-
-A new `frontendServing` test asserts the `/ruffle` mount is registered ahead of
-the dist handler, that `ruffle.js` comes back revalidating, and that a hashed
-chunk comes back immutable.
-
-## Out of scope
-
-`config.userDbPath` and `config.tempDownloadPath` use the same
-`NODE_ENV === 'production'` keying as the new variable. In the dev compose
-container that evaluates to `development`, so `user.db` lands at
-`/app/backend/user.db` and the `backend-db:/app/data` volume goes unused — dev
-container app data is not persisted today. Real, but unrelated to Ruffle, and
-touching database paths carries risk this change does not need.
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index d421e1f..218414c 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,4 +1,4 @@
-import { Routes, Route, useNavigate, useLocation } from 'react-router-dom';
+import { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-dom';
 import { useEffect, lazy, Suspense } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { MainLayout } from './components/layout/MainLayout';
@@ -41,12 +41,6 @@ const HomeView = lazy(() => import('./views/HomeView').then((m) => ({ default: m
 const BrowseView = lazy(() =>
   import('./views/BrowseView').then((m) => ({ default: m.BrowseView }))
 );
-const FlashGamesView = lazy(() =>
-  import('./views/FlashGamesView').then((m) => ({ default: m.FlashGamesView }))
-);
-const HTML5GamesView = lazy(() =>
-  import('./views/HTML5GamesView').then((m) => ({ default: m.HTML5GamesView }))
-);
 const AnimationsView = lazy(() =>
   import('./views/AnimationsView').then((m) => ({ default: m.AnimationsView }))
 );
@@ -95,6 +89,12 @@ const ActivitiesView = lazy(() =>
   import('./views/ActivitiesView').then((m) => ({ default: m.ActivitiesView }))
 );
 
+/** The old /flash and /html5 sections are now part of /browse */
+function LegacySectionRedirect() {
+  const { pathname, search } = useLocation();
+  return <Navigate to={pathname.replace(/^\/(flash|html5)/, '/browse') + search} replace />;
+}
+
 function App() {
   const { isAuthenticated, isGuest, clearAuth, setGuestMode } = useAuthStore();
   const isServerStarting = useServerStatusStore((state) => state.isStarting);
@@ -289,6 +289,8 @@ function App() {
 
           {/* ==================== STANDALONE ==================== */}
           <Route path="/maintenance" element={<MaintenancePage />} />
+          <Route path="/flash/*" element={<LegacySectionRedirect />} />
+          <Route path="/html5/*" element={<LegacySectionRedirect />} />
 
           {/* ==================== PORTAL LAYOUT ==================== */}
           <Route element={<PortalLayout />}>
@@ -304,26 +306,6 @@ function App() {
             />
 
             {/* Public/guest accessible routes */}
-            <Route
-              path="/flash"
-              element={
-                <ProtectedRoute requireAuth={false}>
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <FlashGamesView />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
-            <Route
-              path="/html5"
-              element={
-                <ProtectedRoute requireAuth={false}>
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <HTML5GamesView />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
             <Route
               path="/browse"
               element={
@@ -346,46 +328,6 @@ function App() {
             />
 
             {/* Section-based game routes - must come before /games/:id */}
-            <Route
-              path="/flash/:id"
-              element={
-                <ProtectedRoute requireAuth={false} allowSharedAccess={true}>
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <GamePage />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
-            <Route
-              path="/flash/:id/play"
-              element={
-                <ProtectedRoute requirePermission="games.play">
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <GamePage autoPlay />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
-            <Route
-              path="/html5/:id"
-              element={
-                <ProtectedRoute requireAuth={false} allowSharedAccess={true}>
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <GamePage />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
-            <Route
-              path="/html5/:id/play"
-              element={
-                <ProtectedRoute requirePermission="games.play">
-                  <Suspense fallback={<RouteLoadingFallback />}>
-                    <GamePage autoPlay />
-                  </Suspense>
-                </ProtectedRoute>
-              }
-            />
             <Route
               path="/animations/:id"
               element={
diff --git a/frontend/src/components/library/GameBrowseLayout.tsx b/frontend/src/components/library/GameBrowseLayout.tsx
index 7bfbdc3..ffcefa0 100644
--- a/frontend/src/components/library/GameBrowseLayout.tsx
+++ b/frontend/src/components/library/GameBrowseLayout.tsx
@@ -35,7 +35,7 @@ interface GameBrowseLayoutProps {
   platform?: string;
   headerContent?: ReactNode;
   breadcrumbContext?: BreadcrumbContext;
-  /** Section key for URL building ('flash', 'html5', 'animations', 'browse') */
+  /** Section key for URL building ('animations', 'browse') */
   sectionKey?: string | null;
   /** Pin the downloaded filter on and hide its switch (used by the Downloaded page) */
   forceDownloaded?: boolean;
diff --git a/frontend/src/components/library/GameCard.tsx b/frontend/src/components/library/GameCard.tsx
index 81bb7e0..3dcec7b 100644
--- a/frontend/src/components/library/GameCard.tsx
+++ b/frontend/src/components/library/GameCard.tsx
@@ -29,7 +29,7 @@ interface GameCardProps {
   isFavoritePage?: boolean;
   shareToken?: string | null;
   breadcrumbContext?: BreadcrumbContext;
-  /** Section key for URL building ('flash', 'html5', 'animations', 'browse') */
+  /** Section key for URL building ('animations', 'browse') */
   sectionKey?: string | null;
   /** Rating aggregate data for this game */
   ratingData?: BatchRatingAggregate;
diff --git a/frontend/src/components/library/GameGrid.tsx b/frontend/src/components/library/GameGrid.tsx
index 68713c6..0b36900 100644
--- a/frontend/src/components/library/GameGrid.tsx
+++ b/frontend/src/components/library/GameGrid.tsx
@@ -12,7 +12,7 @@ interface GameGridProps {
   isFavoritePage?: boolean;
   shareToken?: string | null;
   breadcrumbContext?: BreadcrumbContext;
-  /** Section key for URL building ('flash', 'html5', 'animations', 'browse') */
+  /** Section key for URL building ('animations', 'browse') */
   sectionKey?: string | null;
   /** Batch rating data keyed by game ID */
   ratingDataMap?: Record<string, BatchRatingAggregate>;
diff --git a/frontend/src/components/library/GameList.tsx b/frontend/src/components/library/GameList.tsx
index a450c74..9dc250b 100644
--- a/frontend/src/components/library/GameList.tsx
+++ b/frontend/src/components/library/GameList.tsx
@@ -12,7 +12,7 @@ interface GameListProps {
   isFavoritePage?: boolean;
   shareToken?: string | null;
   breadcrumbContext?: BreadcrumbContext;
-  /** Section key for URL building ('flash', 'html5', 'animations', 'browse') */
+  /** Section key for URL building ('animations', 'browse') */
   sectionKey?: string | null;
   /** Batch rating data keyed by game ID */
   ratingDataMap?: Record<string, BatchRatingAggregate>;
diff --git a/frontend/src/components/library/GameListItem.tsx b/frontend/src/components/library/GameListItem.tsx
index db36893..589db45 100644
--- a/frontend/src/components/library/GameListItem.tsx
+++ b/frontend/src/components/library/GameListItem.tsx
@@ -28,7 +28,7 @@ interface GameListItemProps {
   isFavoritePage?: boolean;
   shareToken?: string | null;
   breadcrumbContext?: BreadcrumbContext;
-  /** Section key for URL building ('flash', 'html5', 'animations', 'browse') */
+  /** Section key for URL building ('animations', 'browse') */
   sectionKey?: string | null;
   /** Rating aggregate data for this game */
   ratingData?: BatchRatingAggregate;
diff --git a/frontend/src/lib/sectionRoutes.ts b/frontend/src/lib/sectionRoutes.ts
index 09d6a41..2275f80 100644
--- a/frontend/src/lib/sectionRoutes.ts
+++ b/frontend/src/lib/sectionRoutes.ts
@@ -12,9 +12,9 @@ export interface SectionIcon {
  * Section configuration for game routes
  */
 export interface SectionConfig {
-  /** URL prefix for game routes (e.g., '/flash') */
+  /** URL prefix for game routes (e.g., '/browse') */
   prefix: string;
-  /** Sidebar item path (e.g., '/flash') */
+  /** Sidebar item path (e.g., '/browse') */
   sidebarPath: string;
   /** Label for breadcrumbs */
   breadcrumbLabel: string;
@@ -28,20 +28,6 @@ export interface SectionConfig {
  * Section configurations keyed by section identifier
  */
 export const SECTION_CONFIGS: Record<string, SectionConfig> = {
-  flash: {
-    prefix: '/flash',
-    sidebarPath: '/flash',
-    breadcrumbLabel: 'Flash Games',
-    breadcrumbHref: '/flash',
-    icon: { type: 'image', value: '/images/Flash.png' },
-  },
-  html5: {
-    prefix: '/html5',
-    sidebarPath: '/html5',
-    breadcrumbLabel: 'HTML5 Games',
-    breadcrumbHref: '/html5',
-    icon: { type: 'image', value: '/images/HTML5.png' },
-  },
   animations: {
     prefix: '/animations',
     sidebarPath: '/animations',
@@ -65,8 +51,6 @@ export const SECTION_CONFIGS: Record<string, SectionConfig> = {
  * When breadcrumb context exists, it takes priority over prefix matching.
  */
 export const SIDEBAR_PREFIX_MAP: Record<string, readonly string[]> = {
-  '/flash': ['/flash/'],
-  '/html5': ['/html5/'],
   '/animations': ['/animations/'],
   '/browse': ['/browse/', '/games/'], // /games/ only highlights Browse on direct URL access
   '/playlists': ['/playlists/'],
@@ -76,7 +60,7 @@ export const SIDEBAR_PREFIX_MAP: Record<string, readonly string[]> = {
 
 /**
  * Get section configuration from a URL pathname
- * @param pathname - Current URL pathname (e.g., '/flash/abc-123')
+ * @param pathname - Current URL pathname (e.g., '/browse/abc-123')
  * @returns Section config if pathname matches a section route, null otherwise
  */
 export function getSectionFromPath(pathname: string): SectionConfig | null {
@@ -90,8 +74,8 @@ export function getSectionFromPath(pathname: string): SectionConfig | null {
 
 /**
  * Get section key from a URL pathname
- * @param pathname - Current URL pathname (e.g., '/flash/abc-123')
- * @returns Section key ('flash', 'html5', etc.) or null
+ * @param pathname - Current URL pathname (e.g., '/browse/abc-123')
+ * @returns Section key ('browse', 'animations') or null
  */
 export function getSectionKeyFromPath(pathname: string): string | null {
   for (const [key, config] of Object.entries(SECTION_CONFIGS)) {
@@ -105,9 +89,9 @@ export function getSectionKeyFromPath(pathname: string): string | null {
 /**
  * Build a section-based game URL
  * @param gameId - Game UUID
- * @param sectionKey - Section key ('flash', 'html5', 'animations', 'browse') or null
+ * @param sectionKey - Section key ('animations', 'browse') or null
  * @param isPlay - Whether this is a play URL (adds '/play' suffix)
- * @returns URL string (e.g., '/flash/abc-123' or '/flash/abc-123/play')
+ * @returns URL string (e.g., '/browse/abc-123' or '/browse/abc-123/play')
  */
 export function buildSectionGameUrl(
   gameId: string,
@@ -127,7 +111,7 @@ export function buildSectionGameUrl(
 
 /**
  * Derive breadcrumb context from a URL pathname
- * @param pathname - Current URL pathname (e.g., '/flash/abc-123')
+ * @param pathname - Current URL pathname (e.g., '/browse/abc-123')
  * @returns BreadcrumbContext if pathname matches a section route, null otherwise
  */
 export function getBreadcrumbContextFromPath(pathname: string): BreadcrumbContext | null {
diff --git a/frontend/src/test/mocks/handlers.ts b/frontend/src/test/mocks/handlers.ts
index bb929f9..e699f87 100644
--- a/frontend/src/test/mocks/handlers.ts
+++ b/frontend/src/test/mocks/handlers.ts
@@ -154,7 +154,6 @@ export const handlers = [
       app: {
         maintenance_mode: false,
         allow_registration: true,
-        homeRecentHours: 24,
       },
       metadata: {
         flashpointEdition: 'infinity',
diff --git a/frontend/src/types/settings.ts b/frontend/src/types/settings.ts
index 2798333..0b4b6cf 100644
--- a/frontend/src/types/settings.ts
+++ b/frontend/src/types/settings.ts
@@ -7,7 +7,6 @@ export interface AppSettings {
   maintenanceMessage: string;
   defaultTheme?: string;
   defaultPrimaryColor?: string;
-  homeRecentHours?: number;
 }
 
 export interface FeatureSettings {
@@ -71,10 +70,7 @@ export interface Domain {
 }
 
 export interface PublicSettings {
-  app: Pick<
-    AppSettings,
-    'siteName' | 'tagline' | 'maintenanceMode' | 'maintenanceMessage' | 'homeRecentHours'
-  >;
+  app: Pick<AppSettings, 'siteName' | 'tagline' | 'maintenanceMode' | 'maintenanceMessage'>;
   auth: Pick<AuthSettings, 'guestAccessEnabled' | 'userRegistrationEnabled'>;
   features?: Partial<FeatureSettings>;
   metadata?: {
diff --git a/frontend/src/views/FlashGamesView.tsx b/frontend/src/views/FlashGamesView.tsx
deleted file mode 100644
index d55d476..0000000
--- a/frontend/src/views/FlashGamesView.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-import { GameBrowseLayout } from '@/components/library/GameBrowseLayout';
-
-export function FlashGamesView() {
-  return (
-    <GameBrowseLayout
-      title="Flash Games"
-      library="arcade"
-      platform="Flash"
-      breadcrumbContext={{ label: 'Flash Games', href: '/flash' }}
-      sectionKey="flash"
-    />
-  );
-}
diff --git a/frontend/src/views/HTML5GamesView.tsx b/frontend/src/views/HTML5GamesView.tsx
deleted file mode 100644
index d4c07e0..0000000
--- a/frontend/src/views/HTML5GamesView.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-import { GameBrowseLayout } from '@/components/library/GameBrowseLayout';
-
-export function HTML5GamesView() {
-  return (
-    <GameBrowseLayout
-      title="HTML5 Games"
-      library="arcade"
-      platform="HTML5"
-      breadcrumbContext={{ label: 'HTML5 Games', href: '/html5' }}
-      sectionKey="html5"
-    />
-  );
-}

From 8d0504f6f2dbadf8392a41544badec7168ea4a07 Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:20:08 -0700
Subject: [PATCH 6/7] docs: document prebuilt images, publishing and update
 checks

---
 docs/09-deployment/docker-deployment.md     | 22 +++++++++++++++++++++
 docs/09-deployment/environment-variables.md |  8 ++++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/09-deployment/docker-deployment.md b/docs/09-deployment/docker-deployment.md
index 13160cf..69958ee 100644
--- a/docs/09-deployment/docker-deployment.md
+++ b/docs/09-deployment/docker-deployment.md
@@ -26,6 +26,28 @@ walks through a first install; this page covers the details.
 
 All three are built from this repository by `docker compose up -d --build`.
 
+### Prebuilt images
+
+To pull published images instead of building, set `IMAGE_PREFIX` in `.env` to
+the registry path they live under, ending in `/`, and optionally `IMAGE_TAG`:
+
+```sh
+IMAGE_PREFIX=registry.example.com/owner/
+IMAGE_TAG=latest
+```
+
+Then run `docker compose pull && docker compose up -d`.
+
+### Publishing images
+
+`.gitea/workflows/images.yml` builds all three images on Gitea Actions and
+pushes them to the Gitea instance's container registry, under the repository's
+owner. Pushes to `main` publish a `main` tag; `v1.2.3` tags publish `1.2.3`,
+`1.2` and `latest`. It needs two repository secrets:
+
+- `REGISTRY_USERNAME`: a user;
+- `REGISTRY_TOKEN`: an access token of theirs with package write access.
+
 ## Volumes
 
 | Host                    | Container          | Purpose                                                              |
diff --git a/docs/09-deployment/environment-variables.md b/docs/09-deployment/environment-variables.md
index 2ef3e62..de83a85 100644
--- a/docs/09-deployment/environment-variables.md
+++ b/docs/09-deployment/environment-variables.md
@@ -115,6 +115,14 @@ and API share one origin.
 | `FRONTEND_DIST_PATH` | `<backend>/../frontend/dist`  | Location of the built frontend (rarely needed)                 |
 | `RUFFLE_DATA_PATH`   | `/app/data/ruffle` in production | Where Ruffle is installed. Must sit on a mounted volume, or an in-app update is lost when the container is recreated |
 
+**Images and updates:**
+
+| Variable         | Default  | Description                                                                                       |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `IMAGE_PREFIX`   | -        | Registry path to pull images from, ending in `/`. Unset builds them from source                   |
+| `IMAGE_TAG`      | `latest` | Image tag to build or pull                                                                        |
+| `APP_UPDATE_URL` | -        | "Latest release" API URL (GitHub or Gitea) that Settings checks for new versions; off when unset |
+
 **Streaming:**
 
 Games that can't run in a browser, such as Java applets and Shockwave, can be

From 33b99cafd51f3738f59873f88758a52fc9a0605d Mon Sep 17 00:00:00 2001
From: Brad Anderson <brad@branderson.io>
Date: Tue, 13 Oct 2026 21:49:27 -0700
Subject: [PATCH 7/7] feat(scripts): seed Flashpoint Ultimate before extracting

--seed-ratio and --seed-hours keep aria2c seeding after the download,
stopping at whichever limit comes first, before extraction starts; this
needs no extra disk. The README asks people to seed and explains
long-term seeding with --keep-archives. Re-running with --torrent once
extraction has begun no longer downloads the deleted archives again.
---
 README.md                   | 19 ++++++++++++---
 scripts/setup-flashpoint.sh | 47 +++++++++++++++++++++++++++++++++----
 2 files changed, 58 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 8019daa..158fad2 100644
--- a/README.md
+++ b/README.md
@@ -95,11 +95,24 @@ Re-run it to resume after an interruption.
 sudo apt install aria2 7zip tmux
 tmux new -s flashpoint
 scripts/setup-flashpoint.sh --torrent FlashpointUltimate14.torrent \
-  --infinity fp14.0.3_lin_20251201.7z /srv/flashpoint
+  --infinity fp14.0.3_lin_20251201.7z --seed-ratio 1.0 /srv/flashpoint
 ```
 
-`--keep-archives` keeps the archives so you can keep seeding, which needs room
-for both copies.
+#### Please seed
+
+Flashpoint Ultimate is shared over BitTorrent, and stays available only as long
+as people seed it. If you can, give back at least what you downloaded:
+
+- **Seed before extracting.** `--seed-ratio 1.0` keeps seeding after the
+  download until you've uploaded as much as you downloaded. `--seed-hours 24`
+  seeds for a day. With both, seeding stops at whichever comes first. This needs
+  no extra disk space, but extraction waits until seeding stops.
+- **Seed for the long term.** `--keep-archives` keeps the archives after
+  extracting (about 4.6 TB in total), so a torrent client such as qBittorrent or
+  Transmission can go on seeding the downloads directory.
+- **Let peers reach you.** The download listens on ports 6881-6999, TCP and UDP.
+  Forwarding them on your router and allowing them through your firewall lets
+  more people download from you.
 
 ### 2. Configure
 
diff --git a/scripts/setup-flashpoint.sh b/scripts/setup-flashpoint.sh
index 52a87f0..d0bf24c 100755
--- a/scripts/setup-flashpoint.sh
+++ b/scripts/setup-flashpoint.sh
@@ -12,10 +12,17 @@
 #                      (default: DEST/../downloads)
 #   --infinity FILE    add the software streaming needs (FPSoftware/, Server/)
 #                      from Flashpoint Infinity for Linux (.7z, same page)
-#   --keep-archives    keep each archive after extracting it, e.g. to seed;
-#                      needs room for both copies
+#   --seed-ratio N     after downloading, keep seeding until N times the
+#                      download has been uploaded (e.g. 1.0), then extract
+#   --seed-hours N     after downloading, keep seeding for up to N hours, then
+#                      extract; with --seed-ratio, whichever comes first
+#   --keep-archives    keep each archive after extracting it, e.g. to go on
+#                      seeding with a torrent client; needs room for both copies
 #   --yes              don't ask for confirmation
 #
+# Seeding helps keep Flashpoint's torrent alive for everyone. Seeding before
+# extracting needs no extra disk space.
+#
 # Without --torrent, it uses the Ultimate archives already in the downloads
 # directory. Requires 7-Zip (7z, 7zz or 7za), and aria2c with --torrent.
 #
@@ -33,7 +40,7 @@ MARGIN=$((20 * 1024 ** 3))
 LARGEST_ARCHIVE=$((100 * 1024 ** 3))
 
 usage() {
-  sed -n '6,27p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '6,34p' "$0" | sed 's/^# \{0,1\}//'
   exit 1
 }
 
@@ -43,11 +50,15 @@ TORRENT=
 INFINITY=
 KEEP=false
 YES=false
+SEED_RATIO=
+SEED_HOURS=
 while (($#)); do
   case $1 in
     --torrent) TORRENT=${2:?}; shift ;;
     --downloads) DOWNLOADS=${2:?}; shift ;;
     --infinity) INFINITY=${2:?}; shift ;;
+    --seed-ratio) SEED_RATIO=${2:?}; shift ;;
+    --seed-hours) SEED_HOURS=${2:?}; shift ;;
     --keep-archives) KEEP=true ;;
     --yes) YES=true ;;
     -h | --help) usage ;;
@@ -57,6 +68,14 @@ while (($#)); do
   shift
 done
 [[ -n $DEST ]] || usage
+# aria2c reads a ratio of 0 as "seed forever", which would never get to extracting
+[[ -z $SEED_RATIO || ($SEED_RATIO =~ ^[0-9]+(\.[0-9]+)?$ && $SEED_RATIO =~ [1-9]) ]] ||
+  { echo "--seed-ratio takes a number above 0, e.g. 1.0" >&2; exit 1; }
+[[ -z $SEED_HOURS || $SEED_HOURS =~ ^[0-9]+$ ]] || { echo "--seed-hours takes a whole number of hours" >&2; exit 1; }
+if [[ -z $TORRENT && -n $SEED_RATIO$SEED_HOURS ]]; then
+  echo "Seeding needs --torrent" >&2
+  exit 1
+fi
 [[ -z $TORRENT || -f $TORRENT ]] || { echo "No torrent file at $TORRENT" >&2; exit 1; }
 [[ -z $INFINITY || -f $INFINITY ]] || { echo "No Infinity archive at $INFINITY" >&2; exit 1; }
 mkdir -p "$DEST"
@@ -74,6 +93,12 @@ same_disk() { [[ $(stat -c %d "$1") == $(stat -c %d "$2") ]]; }
 
 DONE=$DOWNLOADS/.extracted
 touch "$DONE"
+# Once extraction has started, extracted archives are deleted; downloading
+# again would fetch them all over
+if [[ -n $TORRENT && -s $DONE ]]; then
+  echo "Extraction already started; continuing it without downloading."
+  TORRENT=
+fi
 
 # What's left to extract, measured from the archives on disk
 remaining=0
@@ -149,8 +174,17 @@ extract() {
 
 # 1. Download the packed archives
 if [[ -n $TORRENT ]]; then
-  echo "==> Downloading into $DOWNLOADS"
-  aria2c --dir="$DOWNLOADS" --seed-time=0 --check-integrity=true \
+  # aria2c stops seeding at whichever limit it reaches first; with neither, it
+  # stops as soon as the download completes
+  seed=(--seed-time=0)
+  if [[ -n $SEED_RATIO || -n $SEED_HOURS ]]; then
+    seed=(--seed-ratio="${SEED_RATIO:-0.0}")
+    [[ -z $SEED_HOURS ]] || seed+=(--seed-time="$((SEED_HOURS * 60))")
+    echo "==> Downloading into $DOWNLOADS, then seeding (${SEED_RATIO:+ratio $SEED_RATIO}${SEED_RATIO:+${SEED_HOURS:+, }}${SEED_HOURS:+up to $SEED_HOURS hours})"
+  else
+    echo "==> Downloading into $DOWNLOADS"
+  fi
+  aria2c --dir="$DOWNLOADS" "${seed[@]}" --check-integrity=true \
     --file-allocation=falloc --bt-max-peers=100 "$TORRENT"
 fi
 # fp-index.json stays behind once the archives are extracted and deleted
@@ -200,3 +234,6 @@ fi
 [[ -f $DEST/Data/flashpoint.sqlite ]] ||
   echo "Warning: no Data/flashpoint.sqlite. Re-run with --infinity to take Infinity's." >&2
 echo "Done. Set FLASHPOINT_HOST_PATH=$DEST in .env."
+if [[ -n $TORRENT && -z $SEED_RATIO$SEED_HOURS ]]; then
+  echo "Consider seeding next time (--seed-ratio 1.0, or --seed-hours 24) to help keep Flashpoint's torrent alive."
+fi