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
+```