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/BACKUP-RESTORE.md

@@ -0,0 +1,123 @@
+# Backup and Restore
+
+Each site owns its own data (single-tenant, ADR-004), so backups are the site's
+responsibility. A complete backup is two parts:
+
+1. **The MySQL database** - all asset, user, audit, and settings data.
+2. **The `instance/` directory** - uploaded floor plans, branding assets,
+   `plugins.json` (the enabled-plugin list), and any tokens or files the app
+   writes to disk. These are NOT in the database, so a DB-only backup loses
+   them. Back up `instance/` alongside every database dump.
+
+Restoring the database without the matching `instance/` directory leaves the
+app pointing at floor plans and logos that no longer exist.
+
+## What to back up
+
+| Item | Location | Why |
+|------|----------|-----|
+| Database | MySQL `shopdb_flask` | All application data. |
+| `instance/branding/` | repo `instance/` dir | Uploaded logos and favicon. |
+| `instance/` floor plans | repo `instance/` dir | Uploaded map blueprints. |
+| `instance/plugins.json` | repo `instance/` dir | Which plugins this site enabled. |
+| `.env` | repo root (offline, secured) | Secrets needed to bring the stack back up. Store separately from the data backup, in a secrets manager. |
+
+## Backup
+
+### Database (Docker)
+
+```bash
+docker compose exec -T db mysqldump \
+  -u root -p"${MYSQL_ROOT_PASSWORD}" \
+  --single-transaction --routines --triggers \
+  shopdb_flask | gzip > shopdb-$(date +%F).sql.gz
+```
+
+`--single-transaction` gives a consistent dump without locking the tables (InnoDB).
+
+### Database (external MySQL, no container)
+
+```bash
+mysqldump -h <host> -u <user> -p \
+  --single-transaction --routines --triggers \
+  shopdb_flask | gzip > shopdb-$(date +%F).sql.gz
+```
+
+### instance directory
+
+```bash
+tar czf instance-$(date +%F).tar.gz instance/
+```
+
+Recommended cadence: nightly database dump to offsite storage, 14-day
+retention; `instance/` captured on the same schedule (and always right before an
+upgrade). Verify a restore quarterly.
+
+## Restore
+
+Restoring replaces the current database contents. Do it into a known-empty or a
+throwaway target first if you are unsure.
+
+### Step 1: Bring up the stack (or a fresh one)
+
+```bash
+cp .env.example .env   # or restore your saved .env
+# ensure MYSQL_* and DATABASE_URL match the dump's database name (shopdb_flask)
+docker compose up -d db
+```
+
+Wait for the `db` container to report healthy (`docker compose ps`).
+
+### Step 2: Load the database dump
+
+```bash
+gunzip -c shopdb-2026-07-10.sql.gz | \
+  docker compose exec -T db mysql -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_flask
+```
+
+For an external MySQL:
+
+```bash
+gunzip -c shopdb-2026-07-10.sql.gz | mysql -h <host> -u <user> -p shopdb_flask
+```
+
+If the target database does not exist yet, create it as utf8mb4 first (matching
+the schema charset):
+
+```sql
+CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### Step 3: Restore the instance directory
+
+```bash
+tar xzf instance-2026-07-10.tar.gz    # restores ./instance/
+```
+
+The docker-compose api container reads `instance/` from the repo working
+directory; make sure it is present before starting `api`.
+
+### Step 4: Bring up the API and reconcile migrations
+
+```bash
+docker compose up -d api
+docker compose exec api flask db upgrade
+```
+
+`flask db upgrade` is a safety net: if the dump predates the current code, this
+applies any newer migrations. If the dump is at the same version it is a no-op.
+
+### Step 5: Verify
+
+- Log in with a known account.
+- Confirm the floor map renders (branding and map blueprints resolve from
+  `instance/`).
+- Spot-check a few asset records and the audit log.
+- `curl -s -X POST -H "Content-Type: application/json" -d '{}' http://localhost:5001/api/auth/login | jq .`
+  should return a `VALIDATION_ERROR`, not a 500.
+
+## See also
+
+- [DEPLOY.md](DEPLOY.md) - first-time deploy
+- [UPGRADE.md](UPGRADE.md) - upgrade procedure (back up first)
+- [CONFIG.md](CONFIG.md) - environment variables and Setting keys