fix

README.md

@@ -34,7 +34,12 @@ npm run build
 pm2 start ecosystem.config.cjs
 ```
 
-The production server runs on <http://localhost:3010>. It serves `/health`
+The production server runs on <http://localhost:3010>. PM2 starts the web app in
+cluster mode with two workers by default, waits for each worker to signal that it
+is ready, and then reloads workers one at a time during deploys. Override the
+worker count with `WEB_INSTANCES`.
+
+The server serves `/health`
 locally and only proxies the API routes used by the app:
 
 - `GET /api/tss/leaderboard/teams?limit=1..100`
@@ -171,14 +176,17 @@ The default deploy flow is:
 
 ```sh
 git pull --ff-only
-npm install --production=false --include=dev --include=optional
-npm run build
+npm ci --include=dev --include=optional
+npm run build -- --outDir dist-next
+# the webhook promotes dist-next to dist after carrying over old hashed assets
 pm2 reload tssbot-web --update-env
 ```
 
 Only processes listed in `PM2_RESTART_TARGETS` are reloaded. The default is
-`tssbot-web`, so unrelated PM2 processes are left alone. The webhook exits after
-24 hours so PM2 restarts it cleanly.
+`tssbot-web`, so unrelated PM2 processes are left alone. The web server handles
+`SIGINT` and `SIGTERM` by closing its listener and SQLite handles before exit,
+which lets PM2 finish reloads without dropping active requests. The webhook
+exits after 24 hours so PM2 restarts it cleanly.
 
 When webhook code changes are deployed, restart the webhook process once so PM2
 loads the updated listener: