feat: add managed ISAC image library

docs/DEPLOYMENT.md

@@ -272,3 +272,58 @@ 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.
+
+### Promote managed images without replacing other data
+
+Image Library assets use stable IDs and can be promoted additively from local
+development. Export a bundle after finishing local uploads and metadata edits:
+
+Set the server-only `REMOVE_BG_API_KEY` in each encrypted environment that
+accepts ISAC uploads. It is sent only from the server in the `X-Api-Key` header.
+Icon uploads that already contain transparency do not call remove.bg; opaque
+icon sources use its preview output and then continue through local trimming,
+white normalization, WebP conversion, and storage.
+
+```sh
+npm run images:export
+```
+
+The command writes a timestamped JSON bundle under `data/backups/`. It contains
+only managed-image metadata and processed WebP files. Transfer that bundle to
+the deployment host, stop the target `app` and `scheduler` services so the
+embedded database is unlocked, and run the merge using the target image:
+
+```sh
+# Staging
+cd /opt/shd-build-stage
+docker compose -f compose.staging.yml stop scheduler app
+docker compose -f compose.staging.yml run --rm \
+  -v /secure/path:/import:ro app \
+  node scripts/managed-images-import.mjs /import/managed-images.json --confirm-merge
+docker compose -f compose.staging.yml up -d app scheduler
+
+# Production
+cd /opt/shd-build-production
+docker compose -f compose.production.yml stop scheduler app
+docker compose -f compose.production.yml run --rm \
+  -v /secure/path:/import:ro app \
+  node scripts/managed-images-import.mjs /import/managed-images.json --confirm-merge
+docker compose -f compose.production.yml up -d app scheduler
+```
+
+Each import creates a full target database backup before changing anything.
+New stable IDs are inserted, identical existing assets are skipped, and a
+different existing record blocks the import. After reviewing an intentional
+metadata or file replacement, add `--update-existing`. Imported changes append
+`image.imported` or `image.import_updated` audit events. Remove the transferred
+bundle after both environments have been verified because it may contain
+unpublished visual assets and creator identifiers.
+
+The `.env.staging` and `.env.production` npm import commands are intended for
+maintenance performed directly in an environment where those database and
+storage paths are mounted:
+
+```sh
+npm run images:import:staging -- /path/to/bundle.json --confirm-merge
+npm run images:import:production -- /path/to/bundle.json --confirm-merge
+```

docs/DESIGN_SYSTEM.md

@@ -1564,6 +1564,31 @@ navigation regions. Search fields have visible or accessible labels, keyboard
 focus uses Signal Orange, and collapsed state must remain understandable
 without motion.
 
+### Managed image library
+
+Reusable uploaded visuals belong in the ISAC Image Library under System
+Configuration. Present assets as a dense responsive registry of preview cards:
+the artwork is primary, while name, assignment category, tags, dimensions, and
+file size remain compact operational metadata. A checkerboard preview surface
+may make transparency legible without changing the asset.
+
+Image intake uses the shared picker, drop-zone, and clipboard control. The
+`Normalize as icon` option trims transparent outer margins and standardizes the
+canvas. When the source has no usable transparency, the server requests
+preview-resolution background removal before local normalization and reports
+configuration, credit, rate-limit, foreground-detection, or network failures
+with a specific recovery. Its dependent `Force white` option converts visible pixels to the
+canonical neutral icon color while preserving alpha. Both controls state their
+processing consequence in text, expose checked and disabled states, and remain
+keyboard accessible. Metadata edits preserve the stable asset identity, close
+after a successful save, and use the shared toast and editor lifecycle.
+
+Use controlled assignment categories for broad placement and free-form,
+normalized tags for discovery. Names are unique and human-readable. Search
+covers names, categories, and tags. On narrow screens, processing controls
+stack vertically and cards reduce to one column so previews and actions retain
+usable sizes.
+
 ### ISAC mutation consequence
 
 Every writable game-data module states what Save will do before the operator