Multi-site distribution readiness: settings-driven site config, security closeout, release engineering, v0.5.0

Make the app distributable to other GE Aerospace sites (one self-hosted
instance per site, ADR-004). GE values remain the shipped defaults; every
site-specific behavior is now a Setting an admin can change in the UI.

Settings-driven site config:
- Branding: site/QR/badge logos, favicon, primary color (upload endpoints
  mirror the map-blueprint pattern; new Settings > Branding section).
- ServiceNow: search/incident/change URL templates ({ticket}), ticket
  prefixes, enable toggle. Defaults point at the current
  geaerospaceqa.service-now.com global search. Disabled = plain-text tickets.
- Employee-id regex (employeeid_pattern), printer hostname template,
  QR label targets (qr_target_printer / qr_target_usb, blank = asset page,
  else URL template with placeholders), usb_label_style (barcode|qr).
- West Jefferson floor-plan PNGs removed from the tree; generic placeholder
  ships as the map default and sites upload their own blueprint.

Security closeout:
- dashboarddefaults writes now require admin.
- Collector: generic error messages (no str(exc) leak); API key accepted
  via X-API-Key header only (BREAKING: querystring api_key removed).
- IP-based login rate limiting (AUTH_RATELIMIT_* knobs) atop account lockout.
- Setting.set() creation race fixed (IntegrityError retry).

Release engineering and docs:
- __version__ 0.5.0 (distinct from __contract_version__, ADR-007),
  CHANGELOG.md, Gitea Actions CI config, frontend version aligned.
- One wizard-first install story across README/DEPLOY; new CONFIG.md,
  UPGRADE.md, BACKUP-RESTORE.md; CLAUDE.md and ROADMAP de-staled.
- Dockerfile multi-stage build now bundles the frontend; compose binds
  MySQL to 127.0.0.1; stale database/schema.sql and one-off SQL removed.

Debt and fixes:
- .query.get() -> db.session.get() sweep; datetime.utcnow() removed
  (naive-UTC via timezone-aware now); users.py on authz decorators.
- Fixed 4 stale tests (slides feed shape, shopfloor splitperemployee,
  plugin contract purity) and the USB label page field mapping (both usb
  modes emit the cmmc shape: device_id/device_desc).
- Health endpoint reports the real version.

248 tests pass; naming/style check green; frontend builds; fresh-DB
flask db upgrade + seeds verified; QR targets verified by decoding
rendered codes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/UPGRADE.md

@@ -0,0 +1,112 @@
+# Upgrading an existing site
+
+This is the procedure for moving a running shopdb-flask instance to a newer
+version. For a first-time install use [DEPLOY.md](DEPLOY.md) instead.
+
+Each site is single-tenant (ADR-004), so an upgrade touches only that site's
+own stack. Read the ADRs added since your last update (`docs/adr/`) and the
+`CHANGELOG.md` before starting; a breaking ADR may require coordinated work.
+
+## Step 0: Back up first
+
+Never upgrade without a fresh backup you have tested. Take a full database dump
+and copy the `instance/` directory. See [BACKUP-RESTORE.md](BACKUP-RESTORE.md).
+
+```bash
+# Docker:
+docker compose exec -T db mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_flask | gzip > pre-upgrade-$(date +%F).sql.gz
+cp -a instance/ instance-backup-$(date +%F)/
+```
+
+## Step 1: Get the new code / image
+
+```bash
+git pull origin main
+```
+
+The application is distributed through the internal GE Aerospace Gitea; pull
+from there. There is no external image registry.
+
+## Step 2: Rebuild
+
+The Docker image builds the Vue frontend in-image, so a container rebuild picks
+up frontend changes automatically:
+
+```bash
+docker compose build api
+docker compose up -d api
+```
+
+Bare-metal / venv install: rebuild the frontend by hand and refresh Python
+dependencies:
+
+```bash
+source venv/bin/activate
+pip install -r requirements.txt
+cd frontend && npm ci && npm run build && cd ..
+```
+
+## Step 3: Apply migrations
+
+```bash
+# Docker:
+docker compose exec api flask db upgrade
+# venv:
+flask db upgrade
+```
+
+`flask db upgrade` applies any new migrations in the core Alembic chain. It is
+idempotent; running it when already at head is a no-op.
+
+## Step 4: Re-seed permissions and settings
+
+New versions may add RBAC permissions or default Settings keys. Both seeders are
+idempotent - they add anything missing and leave existing rows untouched, so
+your site's customized values are preserved.
+
+```bash
+# Docker:
+docker compose exec api flask seed permissions
+docker compose exec api flask seed settings
+# venv:
+flask seed permissions
+flask seed settings
+```
+
+## Step 5: Restart
+
+```bash
+docker compose restart api
+# venv: restart your process manager, e.g. pm2 restart shopdb-flask-api shopdb-flask-ui
+```
+
+Confirm the app is healthy (login page renders, `/api/auth/login` returns a
+`VALIDATION_ERROR` for an empty body rather than a 500).
+
+## Version-specific notes
+
+### Upgrading to v0.5.0 or later: bundled West Jefferson floor plan removed
+
+Versions before 0.5 shipped the West Jefferson facility floor-plan PNGs as the
+map default (`/static/images/sitemap2025-light.png` and `-dark.png`). v0.5+
+removes those bundled PNGs and ships a generic placeholder SVG instead.
+
+If your instance's `map_blueprint_light` / `map_blueprint_dark` Settings still
+point at `/static/images/sitemap2025-*`, the map will 404 those images after the
+upgrade. Re-upload your own floor plan in **Settings > Map**. Uploaded floor
+plans are stored under `instance/` and survive upgrades, so a site that already
+uploaded its own plan is unaffected. Only instances still using the old bundled
+default need to act.
+
+To check what your instance points at:
+
+```bash
+docker compose exec api flask shell -c "from shopdb.core.models.setting import Setting; print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())"
+```
+
+## See also
+
+- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
+- [CONFIG.md](CONFIG.md) - environment variables and Setting keys
+- [DEPLOY.md](DEPLOY.md) - first-time deploy runbook
+- `CHANGELOG.md` - what changed in each release