feat: refine ISAC design and prepare production deployment

docs/DEPLOYMENT.md

@@ -1,4 +1,4 @@
-# Container and staging deployment
+# Container, staging, and production deployment
 
 SHD.build is packaged as a Node 24 container using the official SvelteKit Node
 adapter. The image contains application code, migration and notification
@@ -197,8 +197,78 @@ volume containing the embedded database and uploads.
 
 ## Production promotion
 
-Production should use a separate compose project, volume, database filename,
-runtime environment, port, and deployment workflow. Do not point staging and
-production at the same embedded database or storage volume. Once staging is
-proven, the same container image can be tagged for production so promotion does
-not rebuild application code.
+Production uses a separate compose project, volume, database filename, runtime
+environment, port, and deployment workflow:
+
+- Public origin: `https://shd.build`
+- Reverse-proxy upstream: host port `3102`
+- Deployment directory: `/opt/shd-build-production`
+- Database: `/app/data/shd-build-production.db`
+- Persistent volume: `shd-build-production-data`
+
+Routine pushes never import or replace production data. The production deploy
+stops only its application and scheduler, creates a timestamped JSON backup,
+applies repeatable migrations, restarts, and verifies database health. Never
+run `docker compose down --volumes` against production.
+
+Add these repository Action secrets:
+
+- `DOTENV_PRIVATE_KEY_PRODUCTION`, matching the ignored local `.env.keys`
+- `SCHEDULER_TOKEN_PRODUCTION`, a long random value used only by the internal
+  scheduler endpoint
+
+Optional repository variables are `PRODUCTION_DEPLOY_PATH` (default
+`/opt/shd-build-production`) and `PRODUCTION_PORT` (default `3102`). The
+`deploy-production.yml` workflow deploys production on pushes to `main` and
+manual dispatches using the trusted `stage-deploy` host runner.
+
+Prepare the host directory once from an interactive SSH session:
+
+```sh
+sudo install -d -o jb -g jb -m 0750 /opt/shd-build-production
+```
+
+Generate the scheduler secret locally without printing it into a shared log,
+then enter it directly in Gitea's repository-secret form. Do not commit it or
+reuse the staging scheduler token.
+
+### Initial production bootstrap
+
+The one-time production bootstrap clones current development data and uploads.
+Stop this project's development server before creating the bundle:
+
+```sh
+npm run production:bootstrap:export
+```
+
+Copy the resulting ignored JSON bundle to the deployment host over SSH, then:
+
+```sh
+/opt/shd-build-production/bootstrap-production.sh \
+  /secure/path/shd-production-bootstrap-YYYY-MM-DDTHH-MM-SSZ.json
+```
+
+The importer verifies the bundle target, creates a production safety backup,
+and refuses to replace a production database containing users, builds, audit
+events, or proposals. Remove the remote transfer copy after verification.
+
+### Pull production ISAC data into development
+
+Manually run **Export production ISAC data** in Gitea Actions and download its
+`shd-production-isac-data` artifact. Stop the local development server, then:
+
+```sh
+npm run isac:import -- /path/to/isac-production.json --confirm-replace-isac-data
+```
+
+The importer creates a complete local database backup and an ISAC-only snapshot
+before replacing canonical game data. It leaves accounts, content, proposals,
+notifications, settings, and audit history untouched.
+
+### Pull production ISAC data into staging
+
+Manually run **Replace staging ISAC data from production** in Gitea Actions.
+The workflow exports a consistent production snapshot, restarts production,
+then stops staging and imports it. The staging importer creates both full and
+ISAC-only safety backups before replacement. This is intentionally manual and
+never runs as part of either deployment.