@underpostnet/cyberia 3.3.73 → 3.3.76

package/bin/index.js

@@ -10,7 +10,8 @@
  */
 
 import dotenv from 'dotenv';
-import { Command } from 'commander';
+import { registerStatCommands } from '../src/projects/cyberia/stat-commands.js';
+import { Command, InvalidArgumentError } from 'commander';
 import fs from 'fs-extra';
 import stringify from 'fast-json-stable-stringify';
 import { shellExec } from '../src/server/runtime/process.js';
@@ -18,9 +19,23 @@ import { cli } from '../src/server/build/execution.js';
 import { loggerFactory } from '../src/server/ops/logger.js';
 import { generateBesuManifests, deployBesu, removeBesu } from '../src/projects/cyberia/besu-genesis-generator.js';
 import { DataBaseProviderService } from '../src/db/DataBaseProvider.js';
+import { CyberiaAudioService } from '../src/api/cyberia-audio/cyberia-audio.service.js';
+import { CyberiaEntityTypeDefaultService } from '../src/api/cyberia-entity-type-default/cyberia-entity-type-default.service.js';
+import { CyberiaInstanceConfService } from '../src/api/cyberia-instance-conf/cyberia-instance-conf.service.js';
+import {
+  collectInstanceItemIds,
+  collectSummonedItemIds,
+  selectInstanceSkills,
+} from '../src/api/cyberia-instance/cyberia-instance-items.js';
+import { prepareFallbackAudio, seedFallbackAudio, seedInstanceAudio } from '../src/projects/cyberia/seed-audio.js';
+import {
+  CyberiaMapAudioConfService,
+  parseEventAudioBinding,
+} from '../src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.service.js';
 import {
   deployEnvFilePath,
   etcHostFactory,
+  instanceProjectPathFactory,
   loadConfServerJson,
   normalizeInstanceTopology,
 } from '../src/server/runtime/conf.js';
@@ -30,8 +45,12 @@ import {
   pngDirectoryIteratorByObjectLayerType,
   buildImgFromTile,
 } from '../src/projects/cyberia/object-layer.js';
+import { fetchInstanceObjectLayerItemIds, getInstanceModels } from '../src/projects/cyberia/instance-data.js';
+import { atlasBackupFileKey, restoreObjectLayerBackup } from '../src/projects/cyberia/instance-backup.js';
 import { getKeyframeDirectionsByCode } from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
-import { AtlasSpriteSheetGenerator } from '../src/projects/cyberia/atlas-sprite-sheet-generator.js';
+import { DEFAULT_ATLAS_UPSCALE_FACTOR } from '../src/projects/cyberia/atlas-sprite-sheet-generator.js';
+import { ATLAS_FILE_FIELDS, AtlasSpriteSheetStore } from '../src/projects/cyberia/atlas-sprite-sheet-store.js';
+import { fileRefFields } from '../src/api/file/file.ref.js';
 import {
   generateMultiFrame,
   lookupSemantic,
@@ -51,7 +70,6 @@ import {
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
   ENTITY_TYPE_DEFAULTS,
-  fillInstanceConfDefaults,
 } from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
 import cyberiaCatalog from '../src/projects/cyberia/catalog-cyberia.js';
 
@@ -60,6 +78,7 @@ import {
   ITEM_TYPES as itemTypes,
   DefaultCyberiaItems,
 } from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
+import { balanceStats, resolveStatBounds, statPolicyActive } from '../src/projects/cyberia/stat-balance.js';
 import { loadDeployCatalog } from '../src/server/build/catalog.js';
 import {
   DEPLOY_MANIFEST_INDENT,
@@ -105,9 +124,193 @@ async function connectDbForChain({ envPath, mongoHost }) {
   return { ObjectLayer, host, path };
 }
 
+/**
+ * Rewrites a conf backup's `entityDefaults` into the reference shape the schema now stores.
+ *
+ * Backups written before the collection became the single owner embedded whole documents in the
+ * conf. Those files are the only place that shape still exists, so it is converted here, at the
+ * boundary where they enter — nothing downstream understands anything but an id.
+ *
+ * Each embedded entry is matched against the entity-type-default documents travelling in the same
+ * backup, by entity type and live-item set. That lookup is safe precisely because it cannot see
+ * the database: it can only ever resolve to a document this instance exported. An entry with no
+ * counterpart is written to the collection so the reference it gets resolves to something.
+ *
+ * @param {object} confData - Parsed cyberia-instance-conf.json.
+ * @param {string} backupDir - Backup root, holding cyberia-entity-type-defaults/.
+ * @param {import('mongoose').Model} CyberiaEntityTypeDefault
+ * @returns {Promise<object>} The conf, with `entityDefaults` as ids.
+ */
+const adoptEntityTypeDefaultRefs = async (confData, backupDir, CyberiaEntityTypeDefault) => {
+  const entries = confData.entityDefaults || [];
+  const embedded = entries.filter((entry) => entry && 'object' === typeof entry && entry.entityType);
+  if (0 === embedded.length) return confData;
+
+  const dir = `${backupDir}/cyberia-entity-type-defaults`;
+  const exported = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((file) => file.endsWith('.json'))
+        .map((file) => fs.readJsonSync(`${dir}/${file}`))
+    : [];
+  const liveKey = (doc) => `${doc.entityType}::${[...(doc.liveItemIds || [])].sort().join(',')}`;
+  const byKey = new Map(exported.map((doc) => [liveKey(doc), doc]));
+
+  const ids = [];
+  let created = 0;
+  for (const entry of entries) {
+    if (!entry || 'object' !== typeof entry || !entry.entityType) {
+      if (entry) ids.push(entry);
+      continue;
+    }
+    const match = byKey.get(liveKey(entry));
+    if (match?._id) {
+      ids.push(match._id);
+      continue;
+    }
+    const doc = await CyberiaEntityTypeDefault.create({
+      entityType: entry.entityType,
+      liveItemIds: entry.liveItemIds || [],
+      deadItemIds: entry.deadItemIds || [],
+      dropItemIds: entry.dropItemIds || [],
+      inventoryItemsIds: entry.inventoryItemsIds || [],
+      overrideItemsIdsState: entry.overrideItemsIdsState || [],
+      behavior: entry.behavior || '',
+    });
+    ids.push(doc._id);
+    created++;
+  }
+  confData.entityDefaults = ids;
+  logger.info('Migrated embedded conf entityDefaults to collection references', {
+    instanceCode: confData.instanceCode,
+    references: ids.length,
+    created,
+  });
+  return confData;
+};
+
+/** Default source of recorded `<name>.wav` + `<name>.json` pairs for `cyberia audio --import`. */
+const DEFAULT_AUDIO_RECORDS_PATH = './cyberia-audio/records';
+
+/**
+ * Commander parser for the repeatable `<logic-event-id>:<audio-code>` flag.
+ *
+ * @function eventAudioBindingFactory
+ * @param {string} flag - Flag name, used in the usage error.
+ * @returns {(value: string, previous: Array<{event: string, code: string}>) => Array<{event: string, code: string}>} Accumulating parser.
+ * @memberof CyberiaCLI
+ */
+const eventAudioBindingFactory =
+  (flag) =>
+  (value, previous = []) => {
+    try {
+      return previous.concat([parseEventAudioBinding(value)]);
+    } catch {
+      throw new InvalidArgumentError(`${flag} expects <logic-event-id>:<audio-code>`);
+    }
+  };
+
 /** @type {Function} */
 const logger = loggerFactory(import.meta);
 
+/**
+ * Reads the comma-separated item-id argument of the `ol` command.
+ *
+ * @param {string} [itemId] - The raw command argument.
+ * @returns {string[]} Trimmed, non-empty item ids.
+ */
+const parseItemIds = (itemId) =>
+  itemId
+    ? itemId
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean)
+    : [];
+
+/**
+ * Applies the `ol` stat policy (`--normalize-stats`, `--random-stats`,
+ * `--min-stat`, `--max-stat`) to one object layer before it is written.
+ * Marks the path on a Mongoose document so the save carries it; a plain
+ * payload needs no mark. A policy that changes nothing leaves the stats alone.
+ *
+ * @param {{ data: { item: { id: string, type: string }, stats: Object }, markModified?: Function }} objectLayer
+ * @param {import('../src/projects/cyberia/stat-balance.js').StatPolicy} policy
+ * @returns {boolean} Whether the stats were rewritten.
+ */
+const applyStatPolicy = (objectLayer, policy) => {
+  if (!statPolicyActive(policy)) return false;
+  const { stats, item } = objectLayer.data;
+  objectLayer.data.stats = balanceStats({
+    stats: typeof stats?.toObject === 'function' ? stats.toObject() : stats,
+    itemType: item.type,
+    policy,
+  });
+  if (typeof objectLayer.markModified === 'function') objectLayer.markModified('data.stats');
+  logger.info(
+    `Stats for '${objectLayer.data.item.id}' (${objectLayer.data.item.type}): ${JSON.stringify(objectLayer.data.stats)}`,
+  );
+  return true;
+};
+
+/**
+ * Finds the asset type directory that holds one item id.
+ *
+ * @param {string} itemId - Object layer item id.
+ * @returns {{ type: string, folder: string }|null} The type and folder, or null when absent.
+ */
+const findAssetFolder = (itemId) => {
+  for (const type of Object.keys(itemTypes)) {
+    const folder = `./src/client/public/cyberia/assets/${type}/${itemId}`;
+    if (fs.existsSync(folder) && fs.statSync(folder).isDirectory()) return { type, folder };
+  }
+  return null;
+};
+
+/**
+ * Resolves the stored item ids one `ol` action works on.
+ *
+ * The scope is the item-id argument, one instance, or the whole ObjectLayer
+ * collection. Only ids the collection holds survive, so an action can never
+ * create an object layer. Exits when the scope resolves to nothing.
+ *
+ * @param {Object} params
+ * @param {import('mongoose').Model} params.ObjectLayer - Mongoose ObjectLayer model.
+ * @param {string} [params.itemId] - The comma-separated item-id argument.
+ * @param {string} [params.instance] - Instance code from `--instance`.
+ * @param {string} params.host - Deploy host.
+ * @param {string} params.path - Deploy path.
+ * @param {string} params.action - The flag being served, for the log lines.
+ * @returns {Promise<string[]>} Item ids to work on.
+ */
+const selectScopedItemIds = async ({ ObjectLayer, itemId, instance, host, path, action }) => {
+  let storedItemIds;
+  if (instance) {
+    try {
+      storedItemIds = await fetchInstanceObjectLayerItemIds(getInstanceModels({ host, path }), instance);
+    } catch (instanceError) {
+      logger.error(instanceError.message);
+      process.exit(1);
+    }
+    logger.info(`Instance '${instance}' runs on ${storedItemIds.length} stored object layer(s)`);
+  } else {
+    const storedDocs = await ObjectLayer.find({}, { 'data.item.id': 1 }).lean();
+    storedItemIds = storedDocs.map((doc) => doc?.data?.item?.id);
+  }
+
+  const { itemIds, missingItemIds } = ObjectLayerEngine.selectStoredItemIds({
+    storedItemIds,
+    requestedItemIds: parseItemIds(itemId),
+  });
+
+  const scope = instance ? `instance '${instance}'` : 'the ObjectLayer collection';
+  if (missingItemIds.length > 0) logger.warn(`Not in ${scope}, skipped: ${missingItemIds.join(', ')}`);
+  if (itemIds.length === 0) {
+    logger.error(`No object layer of ${scope} matches the requested item-id(s) for ${action}`);
+    process.exit(1);
+  }
+  return itemIds;
+};
+
 const CYBERIA_DOCKER_HOST_ALIASES = ['cyberia-client', 'cyberia-server', 'engine-cyberia'];
 
 const installCyberiaDockerHostAliases = () => {
@@ -126,6 +329,7 @@ const installCyberiaDockerHostAliases = () => {
 
 try {
   const program = new Command();
+  registerStatCommands(program);
 
   /** @type {string} */
   const version = Underpost.version;
@@ -142,14 +346,52 @@ try {
     .command('ol [item-id]')
     .option(
       '--to-atlas-sprite-sheet [dim]',
-      'Convert object layers to atlas sprite sheets, specify dimension (default: auto-calculated based on frame count)',
+      'Rebuild both atlas renders of stored object layers, optionally capped to a dimension (default: auto-calculated based on frame count)',
     )
     .option('--show-atlas-sprite-sheet', 'Show consolidated atlas sprite sheet PNG for given item-id')
     .option(
       '--import',
-      'Import specific item-id(s) passed as comma-separated command argument (e.g. ol hatchet,sword --import)',
+      'Import specific item-id(s) passed as comma-separated command argument (e.g. ol hatchet,sword --instance FOREST --import); with --from-directory, from the asset directory instead',
+    )
+    .option(
+      '--from-directory',
+      'Source --import and --import-types from src/client/public/cyberia/assets/<type>/<item-id>/<direction>/<frame>.png',
+    )
+    .option(
+      '--minify',
+      'Refresh the minified atlas render the client downloads, for stored object layers (e.g. ol hatchet --minify, or ol --minify for all)',
+    )
+    .option(
+      '--instance <instance-code>',
+      'Limit --minify and --to-atlas-sprite-sheet to the object layers one instance runs on, or make --import restore item(s) from that instance backup under engine-private (e.g. ol hatchet --instance FOREST --import)',
+    )
+    .option(
+      '--normalize-stats',
+      'Clamp every stat of each object layer the action writes into the semantic bounds of its item type',
+    )
+    .option(
+      '--random-stats',
+      'Regenerate every stat of each object layer the action writes, with random signed modifiers',
+    )
+    .option(
+      '--min-stat <value>',
+      'Lowest value --random-stats or --normalize-stats may leave (default: -100)',
+      parseInt,
+    )
+    .option(
+      '--max-stat <value>',
+      'Highest value --random-stats or --normalize-stats may leave (default: 100)',
+      parseInt,
+    )
+    .option(
+      '--upscale <px-factor>',
+      `Pixels per cell of the human-resolution atlas render; on its own it rebuilds that render (default: ${DEFAULT_ATLAS_UPSCALE_FACTOR})`,
+      parseInt,
+    )
+    .option(
+      '--import-types [object-layer-type]',
+      'Batch import by object layer type from the asset directory, needs --from-directory (e.g. skin,floors or all)',
     )
-    .option('--import-types [object-layer-type]', 'Batch import by object layer type e.g. skin,floors or all')
     .option('--show-frame [direction-frame]', 'View object layer frame for given item-id e.g. 08_0 (default: 08_0)')
     .option('--generate', 'Generate procedural object layers from semantic item-id (e.g. floor-desert)')
     .option('--count <count>', 'Shape element count multiplier for --generate (default: 3)', parseFloat)
@@ -159,7 +401,6 @@ try {
     .option('--density <density>', 'Density factor 0..1 for --generate (default: 0.5)', parseFloat)
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
     .option('--mongo-host <mongo-host>', 'Mongo host override')
-    .option('--storage-file-path <storage-file-path>', 'Storage file path override')
     .option('--drop', 'Drop existing data before importing')
     .option('--client-public', 'When used with --drop, also remove static asset folders for dropped items')
     .option('--git-clean', 'When used with --drop, run underpost clean on the cyberia asset directory')
@@ -172,11 +413,18 @@ try {
        * @param {string|undefined} itemId - Optional item ID argument.
        * @param {Object} options - Command options parsed by Commander.
        * @param {boolean} options.import - Import specific item-id(s) from the command argument (comma-separated).
+       * @param {boolean} options.fromDirectory - Source --import and --import-types from the asset directory.
+       * @param {boolean} options.minify - Refresh the minified atlas render of stored item(s).
+       * @param {string} options.instance - Instance code whose object layers --minify reprocesses.
+       * @param {boolean} options.normalizeStats - Clamp the stats of every object layer the action writes to its type's bounds.
+       * @param {boolean} options.randomStats - Regenerate the stats of every object layer the action writes.
+       * @param {number} [options.minStat] - Lowest value --random-stats may draw.
+       * @param {number} [options.maxStat] - Highest value --random-stats may draw.
+       * @param {number} options.upscale - Pixels per cell of the human-resolution atlas render.
        * @param {boolean|string} options.importTypes - Object layer types to batch import (e.g., 'all', 'skin,floor') or `false`.
        * @param {boolean|string} options.showFrame - Direction-frame string (e.g., '08_0') or `true` for default.
        * @param {string} options.envPath - Path to the `.env` file.
        * @param {string} options.mongoHost - MongoDB host override.
-       * @param {string} options.storageFilePath - Path to a storage filter JSON file.
        * @param {boolean|string} options.toAtlasSpriteSheet - Atlas dimension or `true` for auto-calc.
        * @param {boolean} options.showAtlasSpriteSheet - Whether to display the atlas sprite sheet.
        * @param {boolean} options.drop - Whether to drop existing data before importing.
@@ -196,11 +444,16 @@ try {
         itemId,
         options = {
           import: false,
+          fromDirectory: false,
+          minify: false,
+          instance: '',
+          upscale: DEFAULT_ATLAS_UPSCALE_FACTOR,
           importTypes: false,
+          normalizeStats: false,
+          randomStats: false,
           showFrame: '',
           envPath: '',
           mongoHost: '',
-          storageFilePath: '',
           toAtlasSpriteSheet: '',
           showAtlasSpriteSheet: false,
           drop: false,
@@ -215,6 +468,12 @@ try {
           density: 0.5,
         },
       ) => {
+        const upscaleFactor = options.upscale ?? DEFAULT_ATLAS_UPSCALE_FACTOR;
+        if (!Number.isInteger(upscaleFactor) || upscaleFactor < 1) {
+          logger.error('--upscale takes a whole pixel factor of 1 or more');
+          process.exit(1);
+        }
+
         if (!options.envPath) options.envPath = `./.env`;
         if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
 
@@ -250,8 +509,21 @@ try {
           path,
         });
 
+        // --instance reads the world the runtime reads, so its content collections load too.
+        const instanceApis = options.instance
+          ? [
+              'cyberia-instance',
+              'cyberia-instance-conf',
+              'cyberia-map',
+              'cyberia-quest',
+              'cyberia-action',
+              'cyberia-skill',
+              'cyberia-entity-type-default',
+            ]
+          : [];
+
         await DataBaseProviderService.load({
-          apis: ['object-layer', 'object-layer-render-frames', 'atlas-sprite-sheet', 'file', 'ipfs'],
+          apis: ['object-layer', 'object-layer-render-frames', 'atlas-sprite-sheet', 'file', 'ipfs', ...instanceApis],
           host,
           path,
           db,
@@ -268,12 +540,47 @@ try {
         /** @type {import('mongoose').Model} */
         const Ipfs = DataBaseProviderService.getModel('ipfs', { host, path });
 
-        // Idempotent repair, run only before flows that write: collapses legacy
-        // duplicates and upgrades the data.item.id index to unique so every
-        // later write has exactly one document to land on. Read-only
-        // subcommands stay side-effect free — findByItemId already resolves the
-        // same canonical document whether or not duplicates are still present.
-        if (options.import || options.importTypes || options.drop || options.generate) {
+        // A model handle binds to one connection, and the health monitor replaces that
+        // connection when it drops. A batch that runs for minutes therefore resolves its
+        // model per item instead of holding the handle it started with.
+        const liveObjectLayer = () => DataBaseProviderService.getModel('object-layer', { host, path });
+
+        const rebuildAtlases = ObjectLayerEngine.selectAtlasRebuild(options);
+
+        /* Bounds fail here, before any write, rather than on the first item. */
+        const statPolicy = {
+          normalize: !!options.normalizeStats,
+          random: !!options.randomStats,
+          min: options.minStat,
+          max: options.maxStat,
+        };
+        if (statPolicyActive(statPolicy)) {
+          try {
+            resolveStatBounds('', statPolicy);
+          } catch (boundsError) {
+            logger.error(`--min-stat/--max-stat: ${boundsError.message}`);
+            process.exit(1);
+          }
+        } else if (statPolicy.min !== undefined || statPolicy.max !== undefined) {
+          logger.warn('--min-stat and --max-stat only bound --random-stats and --normalize-stats, ignored');
+        }
+
+        if (options.instance && !options.minify && !rebuildAtlases && !options.import) {
+          logger.warn('--instance only narrows --minify and --to-atlas-sprite-sheet, or sources --import, ignored');
+        }
+
+        // Idempotent repair, run only before a flow that writes: collapse
+        // duplicates and make the data.item.id index unique, so every later
+        // write lands on one document. A read-only subcommand stays free of
+        // side effects; findByItemId resolves the same canonical document.
+        if (
+          options.import ||
+          options.minify ||
+          options.importTypes ||
+          options.drop ||
+          options.generate ||
+          rebuildAtlases
+        ) {
           const { removedIds, indexUpgraded } = await ObjectLayer.ensureUniqueItemIdIndex();
           if (removedIds.length > 0) logger.warn(`Removed ${removedIds.length} duplicate ObjectLayer document(s)`);
           if (indexUpgraded) logger.info('Upgraded data.item.id index to unique');
@@ -295,9 +602,9 @@ try {
             logger.info('Dropping ALL object layer data');
           }
 
-          // Build query filter: targeted or all
+          // Build query filter: targeted or all. The atlas side of the drop is selected by
+          // the store, from the item keys and the links collected below.
           const olFilter = isTargetedDrop ? { 'data.item.id': { $in: dropItemIds } } : {};
-          const atlasFilter = isTargetedDrop ? { 'metadata.itemKey': { $in: dropItemIds } } : {};
 
           // Collect data before deletion
           const olDocs = await ObjectLayer.find(olFilter, {
@@ -308,7 +615,6 @@ try {
             objectLayerRenderFramesId: 1,
             atlasSpriteSheetId: 1,
           }).lean();
-          const atlasDocs = await AtlasSpriteSheet.find(atlasFilter, { fileId: 1, cid: 1 }).lean();
 
           const cidsToUnpin = new Set();
           const itemIdsToClean = new Set();
@@ -324,34 +630,36 @@ try {
             if (doc.atlasSpriteSheetId) atlasIds.push(doc.atlasSpriteSheetId);
           }
 
-          const atlasFileIds = atlasDocs.map((a) => a.fileId).filter(Boolean);
-          for (const atlas of atlasDocs) {
-            if (atlas.cid) cidsToUnpin.add(atlas.cid);
-          }
-
           const olCount = olDocs.length;
-          const atlasCount = atlasDocs.length;
 
           // Delete targeted documents
           if (isTargetedDrop) {
             const olIds = olDocs.map((d) => d._id);
             if (olIds.length > 0) await ObjectLayer.deleteMany({ _id: { $in: olIds } });
             if (renderFrameIds.length > 0) await ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFrameIds } });
-            if (atlasIds.length > 0) await AtlasSpriteSheet.deleteMany({ _id: { $in: atlasIds } });
           } else {
             await ObjectLayer.deleteMany();
             await ObjectLayerRenderFrames.deleteMany();
-            await AtlasSpriteSheet.deleteMany();
           }
 
           const rfCount = renderFrameIds.length;
 
-          // Remove only the File documents that were referenced by atlas sprite sheets
-          let fileCount = 0;
-          if (atlasFileIds.length > 0) {
-            const result = await File.deleteMany({ _id: { $in: atlasFileIds } });
-            fileCount = result.deletedCount || 0;
-          }
+          // The atlas owns two renders and the store is what knows that: a drop naming
+          // `fileId` alone left every minified render unreachable in the File collection.
+          // Both selectors are passed, so an atlas linked by the object layer and one
+          // matching the item key are the same drop.
+          const purged = await AtlasSpriteSheetStore.purge({
+            itemKeys: isTargetedDrop ? dropItemIds : [],
+            atlasIds: isTargetedDrop ? atlasIds : [],
+            all: !isTargetedDrop,
+            options: { host, path },
+          });
+          for (const cid of purged.cids) cidsToUnpin.add(cid);
+          const atlasCount = purged.atlases;
+          // Renders an earlier drop left behind are unreachable by definition, so this
+          // drop takes them too instead of letting them accumulate.
+          const fileCount =
+            purged.files + (await AtlasSpriteSheetStore.pruneOrphanRenders({ options: { host, path } }));
 
           // Delete IPFS pin registry records for all collected CIDs
           if (cidsToUnpin.size > 0) {
@@ -404,374 +712,166 @@ try {
           }
         }
 
-        /** @type {Object|null} */
-        const storage = options.storageFilePath ? JSON.parse(fs.readFileSync(options.storageFilePath, 'utf8')) : null;
+        // ── Handle --minify (stored item-id(s)) ──────────────────────────
+        // Refreshes only the minified atlas render, the one the client runtime
+        // downloads. It reads its item ids from the collection, so it never
+        // creates an object layer. With --random-stats every stored document
+        // in scope is rewritten, whether or not its render can be refreshed.
+        if (options.minify) {
+          const selectedItemIds = await selectScopedItemIds({
+            ObjectLayer,
+            itemId,
+            instance: options.instance,
+            host,
+            path,
+            action: '--minify',
+          });
 
-        // ── Handle --import (specific item-id(s)) ─────────────────────
-        if (options.import) {
-          if (!itemId) {
-            logger.error('item-id is required for --import (comma-separated item IDs, e.g. ol hatchet,sword --import)');
-            process.exit(1);
+          logger.info(`Minify refresh for ${selectedItemIds.length} stored item(s)`);
+          const tally = { updated: 0, unchanged: 0, missing: 0, stale: 0, failed: [] };
+
+          // Isolated per item, for the same reason the atlas rebuild is.
+          for (const currentItemId of selectedItemIds) {
+            try {
+              const objectLayer = await liveObjectLayer()
+                .findByItemId(currentItemId)
+                .populate('objectLayerRenderFramesId');
+              if (objectLayer && applyStatPolicy(objectLayer, statPolicy)) {
+                await objectLayer.save();
+                await ObjectLayerEngine.computeAndSaveFinalSha256({ objectLayer, options: { host, path } });
+              }
+              if (!objectLayer?.objectLayerRenderFramesId) {
+                logger.warn(`No render frames stored for '${currentItemId}', render skipped`);
+                tally.missing++;
+                continue;
+              }
+
+              const { status } = await AtlasSpriteSheetStore.syncMinifyRender({
+                itemKey: currentItemId,
+                objectLayerRenderFrames: objectLayer.objectLayerRenderFramesId,
+                options: { host, path },
+              });
+              tally[status]++;
+
+              if (status === 'missing') logger.warn(`No atlas stored for '${currentItemId}'; generate it first`);
+              else if (status === 'stale')
+                logger.warn(`Render frames of '${currentItemId}' moved the atlas layout; regenerate the atlas`);
+              else logger.info(`Minified render ${status} for '${currentItemId}'`);
+
+              const still = await AtlasSpriteSheetStore.syncIdlePreview({
+                itemKey: currentItemId,
+                options: { host, path },
+              });
+              if (still.status !== 'missing') logger.info(`Idle preview ${still.status} for '${currentItemId}'`);
+            } catch (minifyError) {
+              logger.error(`Minify failed for '${currentItemId}': ${minifyError.message}`);
+              tally.failed.push(currentItemId);
+            }
           }
 
-          const itemIds = itemId
-            .split(',')
-            .map((id) => id.trim())
-            .filter(Boolean);
-          logger.info(`Importing specific item(s): ${itemIds.join(', ')}`);
+          logger.info(
+            `Minify done: ${tally.updated} updated, ${tally.unchanged} unchanged, ` +
+              `${tally.stale} stale, ${tally.missing} without an atlas, ${tally.failed.length} failed`,
+          );
+          if (tally.failed.length > 0) {
+            logger.warn(`Rerun for the failed item(s): ${tally.failed.join(',')}`);
+          }
+        }
 
+        // ── Handle --import --instance: restore item(s) from the instance backup ──
+        // The backup under engine-private is the authority for the item id: every document it
+        // holds for the item replaces the database's, rather than regenerating from the asset
+        // directory. The item never touches the stat policy — the backup already states its stats.
+        if (options.import && options.instance) {
+          const itemIds = parseItemIds(itemId);
+          if (itemIds.length === 0) {
+            logger.error(
+              'item-id is required for --import --instance (e.g. ol hatchet,sword --instance FOREST --import)',
+            );
+            process.exit(1);
+          }
+          const backupDir = `./engine-private/cyberia-instances/${options.instance}`;
+          if (!fs.existsSync(backupDir)) {
+            logger.error(`No instance backup at ${backupDir}`);
+            process.exit(1);
+          }
+          logger.info(`Restoring ${itemIds.length} item(s) from instance backup '${options.instance}'`);
+          let restored = 0;
           for (const currentItemId of itemIds) {
-            // Search across all asset type directories to find which type contains this item-id
-            let foundType = null;
-            let foundFolder = null;
-            for (const type of Object.keys(itemTypes)) {
-              const candidateFolder = `./src/client/public/cyberia/assets/${type}/${currentItemId}`;
-              if (fs.existsSync(candidateFolder) && fs.statSync(candidateFolder).isDirectory()) {
-                foundType = type;
-                foundFolder = candidateFolder;
-                break;
-              }
+            try {
+              const summary = await restoreObjectLayerBackup({
+                backupDir,
+                itemId: currentItemId,
+                options: { host, path },
+              });
+              logger.info(`Restored '${currentItemId}' from backup`, summary);
+              restored++;
+            } catch (restoreError) {
+              logger.error(`Restore failed for '${currentItemId}': ${restoreError.message}`);
             }
+          }
+          logger.info(`Instance restore done: ${restored}/${itemIds.length} item(s)`);
+        }
 
-            if (!foundType) {
+        if (options.import && !options.instance === !options.fromDirectory) {
+          logger.error(
+            '--import takes exactly one source: --instance <code> for a backup, or --from-directory for the asset tree',
+          );
+          process.exit(1);
+        }
+        if (options.importTypes && !options.fromDirectory) {
+          logger.error('--import-types reads the asset tree and needs --from-directory');
+          process.exit(1);
+        }
+
+        // ── Handle --import --from-directory (specific item-id(s)) ────────
+        if (options.import && options.fromDirectory) {
+          const itemIds = parseItemIds(itemId);
+          if (itemIds.length === 0) {
+            logger.error(
+              'item-id is required for --import --from-directory (comma-separated item IDs, e.g. ol hatchet,sword --from-directory --import)',
+            );
+            process.exit(1);
+          }
+          logger.info(`Importing specific item(s) from the asset directory: ${itemIds.join(', ')}`);
+
+          for (const currentItemId of itemIds) {
+            const found = findAssetFolder(currentItemId);
+            if (!found) {
               logger.error(
                 `Item-id '${currentItemId}' not found in any asset type directory (${Object.keys(itemTypes).join(', ')})`,
               );
               continue;
             }
-
-            logger.info(`Found item '${currentItemId}' in type '${foundType}' at ${foundFolder}`);
+            logger.info(`Found item '${currentItemId}' in type '${found.type}' at ${found.folder}`);
 
             const { objectLayerRenderFramesData, objectLayerData } =
               await ObjectLayerEngine.buildObjectLayerDataFromDirectory({
-                folder: foundFolder,
-                objectLayerType: foundType,
+                folder: found.folder,
+                objectLayerType: found.type,
                 objectLayerId: currentItemId,
               });
+            applyStatPolicy(objectLayerData, statPolicy);
 
             // Write processed frames back to disk so WebP matches atlas
-            const srcBasePath = './src/client/public/cyberia/';
-            const publicBasePath = `./public/${host}${path}`;
             await ObjectLayerEngine.writeStaticFrameAssets({
-              basePaths: [srcBasePath, publicBasePath],
-              itemType: foundType,
+              basePaths: ['./src/client/public/cyberia/', `./public/${host}${path}`],
+              itemType: found.type,
               itemId: currentItemId,
               objectLayerRenderFramesData,
               objectLayerData,
-              cellPixelDim: 20,
+              cellPixelDim: upscaleFactor,
             });
 
-            // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
-            const existingOL = await ObjectLayer.findByItemId(currentItemId);
-            let objectLayer;
-
-            if (existingOL) {
-              // ── Cut-over consistency: stage everything in memory before touching the live document ──
-              logger.info(`ObjectLayer '${currentItemId}' already exists (${existingOL._id}), staging update...`);
-
-              // 1. Prepare staging data entirely in memory (no DB writes yet)
-              const stagingData = JSON.parse(JSON.stringify(objectLayerData.data));
-              if (!stagingData.render) stagingData.render = {};
-              stagingData.render.cid = '';
-              stagingData.render.metadataCid = '';
-
-              // 2. Generate atlas, pin to IPFS, compute SHA-256 — all in memory
-              let cutoverReady = false;
-              let stagingFileDoc = null;
-              let stagingAtlasDoc = null;
-              let stagingCid = '';
-              try {
-                const itemKey = currentItemId;
-
-                // Generate atlas from in-memory render frames data (plain object, no DB doc needed)
-                const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                  objectLayerRenderFramesData,
-                  itemKey,
-                  20,
-                );
-
-                stagingFileDoc = await new File({
-                  name: `${itemKey}-atlas.png`,
-                  data: buffer,
-                  size: buffer.length,
-                  mimetype: 'image/png',
-                  md5: crypto.createHash('md5').update(buffer).digest('hex'),
-                }).save();
-
-                let importItemCid = '';
-                let importItemMetadataCid = '';
-                try {
-                  const ipfsResult = await IpfsClient.addBufferToIpfs(
-                    buffer,
-                    `${itemKey}_atlas_sprite_sheet.png`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                  );
-                  if (ipfsResult) {
-                    importItemCid = ipfsResult.cid;
-                    logger.info(`[staging] Atlas pinned to IPFS – CID: ${importItemCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: importItemCid,
-                        resourceType: 'atlas-sprite-sheet',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
-                }
-
-                try {
-                  const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                    metadata,
-                    `${itemKey}_atlas_sprite_sheet_metadata.json`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                  );
-                  if (metadataIpfsResult) {
-                    importItemMetadataCid = metadataIpfsResult.cid;
-                    logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importItemMetadataCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: importItemMetadataCid,
-                        resourceType: 'atlas-metadata',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
-                }
-
-                // Persist atlas doc (or update existing one for this itemKey)
-                stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
-                if (stagingAtlasDoc) {
-                  if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
-                  stagingAtlasDoc.fileId = stagingFileDoc._id;
-                  stagingAtlasDoc.cid = importItemCid;
-                  stagingAtlasDoc.metadata = metadata;
-                  await stagingAtlasDoc.save();
-                } else {
-                  stagingAtlasDoc = await new AtlasSpriteSheet({
-                    fileId: stagingFileDoc._id,
-                    cid: importItemCid,
-                    metadata,
-                  }).save();
-                }
-
-                // Finalize staging data in memory with render CIDs
-                stagingData.render.cid = importItemCid;
-                stagingData.render.metadataCid = importItemMetadataCid;
-
-                // Pin data JSON to IPFS
-                try {
-                  const ipfsDataResult = await IpfsClient.addJsonToIpfs(
-                    stagingData,
-                    `${itemKey}_data.json`,
-                    `/object-layer/${itemKey}/${itemKey}_data.json`,
-                  );
-                  if (ipfsDataResult) {
-                    stagingCid = ipfsDataResult.cid;
-                    logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: stagingCid,
-                        resourceType: 'object-layer-data',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create data pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
-                }
-
-                cutoverReady = true;
-                logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for cut-over`);
-              } catch (atlasError) {
-                logger.error(`[staging] Failed for ${currentItemId}, live document untouched:`, atlasError);
-              }
-
-              // 3. Atomic cut-over: create new RenderFrames, swap live ObjectLayer in a single update
-              if (cutoverReady) {
-                const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
-
-                // Create the new RenderFrames doc (only now touches DB)
-                const newRenderFrames = await ObjectLayerRenderFrames.create(objectLayerRenderFramesData);
-
-                // Single atomic upsert on the natural key; empty staged CIDs keep their stored value
-                objectLayer = await ObjectLayer.upsertByItemId({
-                  data: stagingData,
-                  cid: stagingCid,
-                  objectLayerRenderFramesId: newRenderFrames._id,
-                  atlasSpriteSheetId: stagingAtlasDoc._id,
-                });
-
-                // Clean up old render frames
-                if (oldRenderFramesId) {
-                  await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
-                }
-
-                logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically`);
-              } else {
-                // Rollback: only File/AtlasSpriteSheet were written, clean those up
-                if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
-                logger.warn(`[cut-over] Staging rolled back for ${currentItemId}, live document preserved`);
-                objectLayer = await ObjectLayer.findByItemId(currentItemId);
-              }
-            } else {
-              // ── New item: stage everything before creating (same cut-over pattern) ──
-              logger.info(`ObjectLayer '${currentItemId}' is new, staging creation...`);
-
-              const itemKey = currentItemId;
-              const stagingData = JSON.parse(JSON.stringify(objectLayerData.data));
-              if (!stagingData.render) stagingData.render = {};
-              stagingData.render.cid = '';
-              stagingData.render.metadataCid = '';
-
-              let cutoverReady = false;
-              let stagingFileDoc = null;
-              let stagingAtlasDoc = null;
-              let stagingCid = '';
-              try {
-                const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                  objectLayerRenderFramesData,
-                  itemKey,
-                  20,
-                );
-
-                stagingFileDoc = await new File({
-                  name: `${itemKey}-atlas.png`,
-                  data: buffer,
-                  size: buffer.length,
-                  mimetype: 'image/png',
-                  md5: crypto.createHash('md5').update(buffer).digest('hex'),
-                }).save();
-
-                let importItemCid = '';
-                let importItemMetadataCid = '';
-                try {
-                  const ipfsResult = await IpfsClient.addBufferToIpfs(
-                    buffer,
-                    `${itemKey}_atlas_sprite_sheet.png`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                  );
-                  if (ipfsResult) {
-                    importItemCid = ipfsResult.cid;
-                    logger.info(`[staging] Atlas pinned to IPFS – CID: ${importItemCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: importItemCid,
-                        resourceType: 'atlas-sprite-sheet',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
-                }
-
-                try {
-                  const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                    metadata,
-                    `${itemKey}_atlas_sprite_sheet_metadata.json`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                  );
-                  if (metadataIpfsResult) {
-                    importItemMetadataCid = metadataIpfsResult.cid;
-                    logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importItemMetadataCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: importItemMetadataCid,
-                        resourceType: 'atlas-metadata',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
-                }
-
-                stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
-                if (stagingAtlasDoc) {
-                  if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
-                  stagingAtlasDoc.fileId = stagingFileDoc._id;
-                  stagingAtlasDoc.cid = importItemCid;
-                  stagingAtlasDoc.metadata = metadata;
-                  await stagingAtlasDoc.save();
-                } else {
-                  stagingAtlasDoc = await new AtlasSpriteSheet({
-                    fileId: stagingFileDoc._id,
-                    cid: importItemCid,
-                    metadata,
-                  }).save();
-                }
-
-                stagingData.render.cid = importItemCid;
-                stagingData.render.metadataCid = importItemMetadataCid;
-
-                try {
-                  const ipfsDataResult = await IpfsClient.addJsonToIpfs(
-                    stagingData,
-                    `${itemKey}_data.json`,
-                    `/object-layer/${itemKey}/${itemKey}_data.json`,
-                  );
-                  if (ipfsDataResult) {
-                    stagingCid = ipfsDataResult.cid;
-                    logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
-                    try {
-                      await createPinRecord({
-                        cid: stagingCid,
-                        resourceType: 'object-layer-data',
-                        mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
-                        options: { host, path },
-                      });
-                    } catch (prErr) {
-                      logger.warn('[staging] Failed to create data pin record:', prErr.message);
-                    }
-                  }
-                } catch (ipfsError) {
-                  logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
-                }
-
-                cutoverReady = true;
-                logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for creation`);
-              } catch (atlasError) {
-                logger.error(`[staging] Failed for ${currentItemId}, no document created:`, atlasError);
-              }
-
-              if (cutoverReady) {
-                const newRenderFrames = await ObjectLayerRenderFrames.create(objectLayerRenderFramesData);
-                objectLayer = await ObjectLayer.upsertByItemId({
-                  data: stagingData,
-                  cid: stagingCid,
-                  objectLayerRenderFramesId: newRenderFrames._id,
-                  atlasSpriteSheetId: stagingAtlasDoc._id,
-                });
-                logger.info(`[cut-over] New ObjectLayer ${objectLayer._id} created with all CIDs populated`);
-              } else {
-                if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
-                logger.warn(`[cut-over] Staging failed for ${currentItemId}, no ObjectLayer created`);
-                continue;
-              }
-            }
+            const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
+              ObjectLayer,
+              ObjectLayerRenderFrames,
+              objectLayerRenderFramesData,
+              objectLayerData,
+              persistOptions: { upscaleFactor, options: { host, path } },
+            });
 
-            // Reload final state to include CID and render updates
-            const finalObjectLayer = await ObjectLayer.findById(objectLayer._id).populate('objectLayerRenderFramesId');
-            console.log(finalObjectLayer.toObject());
+            console.log((await ObjectLayer.findById(objectLayer._id).populate('objectLayerRenderFramesId')).toObject());
           }
         }
 
@@ -806,12 +906,6 @@ try {
             await pngDirectoryIteratorByObjectLayerType(
               argItemType,
               async ({ path: framePath, objectLayerType, objectLayerId, direction, frame }) => {
-                if (
-                  storage &&
-                  !storage[`src/client/public/cyberia/assets/${objectLayerType}/${objectLayerId}/08/0.png`]
-                )
-                  return;
-
                 // Skip items that already exist in the database (bulk import only)
                 if (isImportAll && existingItemIds.has(objectLayerId)) return;
 
@@ -826,6 +920,7 @@ try {
                       objectLayerType,
                       objectLayerId,
                     });
+                  applyStatPolicy(objectLayerData, statPolicy);
 
                   // Write processed frames back to disk so WebP matches atlas
                   const srcBasePath = './src/client/public/cyberia/';
@@ -836,14 +931,10 @@ try {
                     itemId: objectLayerId,
                     objectLayerRenderFramesData,
                     objectLayerData,
-                    cellPixelDim: 20,
+                    cellPixelDim: upscaleFactor,
                   });
 
-                  objectLayers[objectLayerId] = {
-                    ...objectLayerData,
-                    objectLayerRenderFramesData,
-                    _processed: true,
-                  };
+                  objectLayers[objectLayerId] = { ...objectLayerData, objectLayerRenderFramesData };
                 }
               },
             );
@@ -852,369 +943,17 @@ try {
           for (const objectLayerId of Object.keys(objectLayers)) {
             const entry = objectLayers[objectLayerId];
 
-            // Skip atlas generation when importing all object layers at once (bulk import).
-            // Individual imports or explicit --to-atlas-sprite-sheet calls will still generate atlases.
-            const shouldGenerateAtlas = !isImportAll;
-
-            if (shouldGenerateAtlas) {
-              // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
-              const existingOL = await ObjectLayer.findByItemId(objectLayerId);
-              let objectLayer;
-
-              if (existingOL) {
-                // ── Cut-over consistency: stage everything in memory before touching the live document ──
-                logger.info(`ObjectLayer '${objectLayerId}' already exists (${existingOL._id}), staging update...`);
-
-                // 1. Prepare staging data entirely in memory (no DB writes yet)
-                const stagingData = JSON.parse(JSON.stringify(entry.data));
-                if (!stagingData.render) stagingData.render = {};
-                stagingData.render.cid = '';
-                stagingData.render.metadataCid = '';
-
-                // 2. Generate atlas, pin to IPFS, compute SHA-256 — all in memory
-                let cutoverReady = false;
-                let stagingFileDoc = null;
-                let stagingAtlasDoc = null;
-                let stagingCid = '';
-                try {
-                  const itemKey = objectLayerId;
-
-                  // Generate atlas from in-memory render frames data (plain object, no DB doc needed)
-                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                    entry.objectLayerRenderFramesData,
-                    itemKey,
-                    20,
-                  );
-
-                  stagingFileDoc = await new File({
-                    name: `${itemKey}-atlas.png`,
-                    data: buffer,
-                    size: buffer.length,
-                    mimetype: 'image/png',
-                    md5: crypto.createHash('md5').update(buffer).digest('hex'),
-                  }).save();
-
-                  let importAtlasCid = '';
-                  let importAtlasMetadataCid = '';
-                  try {
-                    const ipfsResult = await IpfsClient.addBufferToIpfs(
-                      buffer,
-                      `${itemKey}_atlas_sprite_sheet.png`,
-                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                    );
-                    if (ipfsResult) {
-                      importAtlasCid = ipfsResult.cid;
-                      logger.info(`[staging] Atlas pinned to IPFS – CID: ${importAtlasCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: importAtlasCid,
-                          resourceType: 'atlas-sprite-sheet',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
-                  }
-
-                  try {
-                    const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                      metadata,
-                      `${itemKey}_atlas_sprite_sheet_metadata.json`,
-                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                    );
-                    if (metadataIpfsResult) {
-                      importAtlasMetadataCid = metadataIpfsResult.cid;
-                      logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: importAtlasMetadataCid,
-                          resourceType: 'atlas-metadata',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
-                  }
-
-                  stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
-                  if (stagingAtlasDoc) {
-                    if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
-                    stagingAtlasDoc.fileId = stagingFileDoc._id;
-                    stagingAtlasDoc.cid = importAtlasCid;
-                    stagingAtlasDoc.metadata = metadata;
-                    await stagingAtlasDoc.save();
-                  } else {
-                    stagingAtlasDoc = await new AtlasSpriteSheet({
-                      fileId: stagingFileDoc._id,
-                      cid: importAtlasCid,
-                      metadata,
-                    }).save();
-                  }
-
-                  // Finalize staging data in memory with render CIDs
-                  stagingData.render.cid = importAtlasCid;
-                  stagingData.render.metadataCid = importAtlasMetadataCid;
-
-                  // Pin data JSON to IPFS
-                  try {
-                    const ipfsDataResult = await IpfsClient.addJsonToIpfs(
-                      stagingData,
-                      `${itemKey}_data.json`,
-                      `/object-layer/${itemKey}/${itemKey}_data.json`,
-                    );
-                    if (ipfsDataResult) {
-                      stagingCid = ipfsDataResult.cid;
-                      logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: stagingCid,
-                          resourceType: 'object-layer-data',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create data pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
-                  }
-
-                  cutoverReady = true;
-                  logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for cut-over`);
-                } catch (atlasError) {
-                  logger.error(`[staging] Failed for ${objectLayerId}, live document untouched:`, atlasError);
-                }
-
-                // 3. Atomic cut-over: create new RenderFrames, swap live ObjectLayer in a single update
-                if (cutoverReady) {
-                  const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
-                  const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-
-                  objectLayer = await ObjectLayer.upsertByItemId({
-                    data: stagingData,
-                    cid: stagingCid,
-                    objectLayerRenderFramesId: newRenderFrames._id,
-                    atlasSpriteSheetId: stagingAtlasDoc._id,
-                  });
-
-                  if (oldRenderFramesId) {
-                    await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
-                  }
-                  logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically`);
-                } else {
-                  if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
-                  logger.warn(`[cut-over] Staging rolled back for ${objectLayerId}, live document preserved`);
-                  objectLayer = await ObjectLayer.findByItemId(objectLayerId);
-                }
-              } else {
-                // ── New item: stage everything before creating (same cut-over pattern) ──
-                logger.info(`ObjectLayer '${objectLayerId}' is new, staging creation...`);
-
-                const itemKey = objectLayerId;
-                const stagingData = JSON.parse(JSON.stringify(entry.data));
-                if (!stagingData.render) stagingData.render = {};
-                stagingData.render.cid = '';
-                stagingData.render.metadataCid = '';
-
-                let cutoverReady = false;
-                let stagingFileDoc = null;
-                let stagingAtlasDoc = null;
-                let stagingCid = '';
-                try {
-                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                    entry.objectLayerRenderFramesData,
-                    itemKey,
-                    20,
-                  );
-
-                  stagingFileDoc = await new File({
-                    name: `${itemKey}-atlas.png`,
-                    data: buffer,
-                    size: buffer.length,
-                    mimetype: 'image/png',
-                    md5: crypto.createHash('md5').update(buffer).digest('hex'),
-                  }).save();
-
-                  let importAtlasCid = '';
-                  let importAtlasMetadataCid = '';
-                  try {
-                    const ipfsResult = await IpfsClient.addBufferToIpfs(
-                      buffer,
-                      `${itemKey}_atlas_sprite_sheet.png`,
-                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                    );
-                    if (ipfsResult) {
-                      importAtlasCid = ipfsResult.cid;
-                      logger.info(`[staging] Atlas pinned to IPFS – CID: ${importAtlasCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: importAtlasCid,
-                          resourceType: 'atlas-sprite-sheet',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
-                  }
-
-                  try {
-                    const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                      metadata,
-                      `${itemKey}_atlas_sprite_sheet_metadata.json`,
-                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                    );
-                    if (metadataIpfsResult) {
-                      importAtlasMetadataCid = metadataIpfsResult.cid;
-                      logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: importAtlasMetadataCid,
-                          resourceType: 'atlas-metadata',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
-                  }
-
-                  stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
-                  if (stagingAtlasDoc) {
-                    if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
-                    stagingAtlasDoc.fileId = stagingFileDoc._id;
-                    stagingAtlasDoc.cid = importAtlasCid;
-                    stagingAtlasDoc.metadata = metadata;
-                    await stagingAtlasDoc.save();
-                  } else {
-                    stagingAtlasDoc = await new AtlasSpriteSheet({
-                      fileId: stagingFileDoc._id,
-                      cid: importAtlasCid,
-                      metadata,
-                    }).save();
-                  }
-
-                  stagingData.render.cid = importAtlasCid;
-                  stagingData.render.metadataCid = importAtlasMetadataCid;
-
-                  try {
-                    const ipfsDataResult = await IpfsClient.addJsonToIpfs(
-                      stagingData,
-                      `${itemKey}_data.json`,
-                      `/object-layer/${itemKey}/${itemKey}_data.json`,
-                    );
-                    if (ipfsDataResult) {
-                      stagingCid = ipfsDataResult.cid;
-                      logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
-                      try {
-                        await createPinRecord({
-                          cid: stagingCid,
-                          resourceType: 'object-layer-data',
-                          mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
-                          options: { host, path },
-                        });
-                      } catch (prErr) {
-                        logger.warn('[staging] Failed to create data pin record:', prErr.message);
-                      }
-                    }
-                  } catch (ipfsError) {
-                    logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
-                  }
-
-                  cutoverReady = true;
-                  logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for creation`);
-                } catch (atlasError) {
-                  logger.error(`[staging] Failed for ${objectLayerId}, no document created:`, atlasError);
-                }
-
-                if (cutoverReady) {
-                  const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-                  objectLayer = await ObjectLayer.upsertByItemId({
-                    data: stagingData,
-                    cid: stagingCid,
-                    objectLayerRenderFramesId: newRenderFrames._id,
-                    atlasSpriteSheetId: stagingAtlasDoc._id,
-                  });
-                  logger.info(`[cut-over] New ObjectLayer ${objectLayer._id} created with all CIDs populated`);
-                } else {
-                  if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
-                  logger.warn(`[cut-over] Staging failed for ${objectLayerId}, no ObjectLayer created`);
-                  continue;
-                }
-              }
-
-              // Reload final state to include CID and render updates
-              const finalObjectLayer = await ObjectLayer.findById((objectLayer._id || objectLayer).toString()).populate(
-                'objectLayerRenderFramesId',
-              );
-              console.log(finalObjectLayer.toObject());
-            } else {
-              // --import all: skip items that already exist in the database
-              if (existingItemIds.has(objectLayerId)) continue;
-
-              // --import all: create documents without atlas generation
-              const existingOL = await ObjectLayer.findByItemId(objectLayerId);
-              let objectLayer;
-
-              if (existingOL) {
-                logger.info(
-                  `ObjectLayer '${objectLayerId}' already exists (${existingOL._id}), staging update (atlas skipped)...`,
-                );
-
-                // ── In-memory staging (no atlas) ──────────────────────
-                const stagingData = JSON.parse(JSON.stringify(entry.data));
-                if (!stagingData.render) stagingData.render = {};
-                stagingData.render.cid = '';
-                stagingData.render.metadataCid = '';
-
-                // Atomic cut-over: create new RenderFrames, swap live doc, delete old
-                const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-                const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
-
-                objectLayer = await ObjectLayer.upsertByItemId({
-                  data: stagingData,
-                  objectLayerRenderFramesId: newRenderFrames._id,
-                });
-
-                if (oldRenderFramesId) {
-                  await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
-                }
-
-                logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically (atlas skipped)`);
-              } else {
-                // New item (no atlas for bulk import)
-                const stagingData = JSON.parse(JSON.stringify(entry.data));
-                if (!stagingData.render) stagingData.render = {};
-                stagingData.render.cid = '';
-                stagingData.render.metadataCid = '';
-
-                const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-                objectLayer = await ObjectLayer.upsertByItemId({
-                  data: stagingData,
-                  objectLayerRenderFramesId: newRenderFrames._id,
-                });
-              }
+            // A bulk import of every type skips atlas generation; `--to-atlas-sprite-sheet`
+            // or a targeted `--import` builds the atlas for an item that needs one.
+            const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
+              ObjectLayer,
+              ObjectLayerRenderFrames,
+              objectLayerRenderFramesData: entry.objectLayerRenderFramesData,
+              objectLayerData: { data: entry.data },
+              persistOptions: { generateAtlas: !isImportAll, upscaleFactor, options: { host, path } },
+            });
 
-              logger.info(
-                `ObjectLayer ${existingOL ? 'updated' : 'created'} (atlas skipped for bulk import): ${objectLayerId}`,
-              );
-              console.log(objectLayer.toObject ? objectLayer.toObject() : objectLayer);
-            }
+            console.log(objectLayer.toObject());
           }
         }
 
@@ -1234,20 +973,16 @@ try {
 
           logger.info(`Showing frame for item: ${itemId}, direction: ${direction}, frame: ${frameIndexNum}`);
 
-          // Find ObjectLayer by item-id
           const objectLayer = await ObjectLayer.findByItemId(itemId).populate('objectLayerRenderFramesId');
-
           if (!objectLayer) {
             logger.error(`ObjectLayer not found for item-id: ${itemId}`);
             process.exit(1);
           }
-
           if (!objectLayer.objectLayerRenderFramesId) {
             logger.error(`ObjectLayerRenderFrames not found for item: ${itemId}`);
             process.exit(1);
           }
 
-          // Get the keyframe direction name from the numerical direction code
           const objectLayerFrameDirections = getKeyframeDirectionsByCode(direction);
           if (objectLayerFrameDirections.length === 0) {
             logger.error(`Invalid direction code: ${direction}. Valid codes: 08, 18, 02, 12, 04, 14, 06, 16`);
@@ -1271,15 +1006,14 @@ try {
             process.exit(1);
           }
 
-          const itemKey = objectLayer.data.item.id;
-          const outputPath = `./${itemKey}_${showFrameInput}.png`;
+          const outputPath = `./${objectLayer.data.item.id}_${showFrameInput}.png`;
 
           await buildImgFromTile({
             tile: {
               map_color: objectLayer.objectLayerRenderFramesId.colors,
               frame_matrix: frames[frameIndexNum],
             },
-            cellPixelDim: 20,
+            cellPixelDim: upscaleFactor,
             opacityFilter: (x, y, color) => 255,
             imagePath: outputPath,
           });
@@ -1289,158 +1023,90 @@ try {
         }
 
         // ── Handle --to-atlas-sprite-sheet ───────────────────────────────
-        if (options.toAtlasSpriteSheet !== undefined) {
-          // If toAtlasSpriteSheet is true (flag without value), use null for auto-calc
-          // If it's a string/number, parse it as integer
+        // Rebuilds both atlas renders. The scope is the same selection --minify
+        // uses: the given item-id(s), one instance, or the whole collection.
+        // A bare --upscale asks for the same rebuild, since the factor only
+        // takes effect on the human-resolution render.
+        if (rebuildAtlases) {
           /** @type {number|null} */
-          const maxAtlasDim = options.toAtlasSpriteSheet === true ? null : parseInt(options.toAtlasSpriteSheet) || null;
+          const maxAtlasDim =
+            options.toAtlasSpriteSheet === true || options.toAtlasSpriteSheet === undefined
+              ? null
+              : parseInt(options.toAtlasSpriteSheet) || null;
 
-          if (!itemId) {
-            logger.error('item-id is required for --to-atlas-sprite-sheet');
-            process.exit(1);
-          }
-
-          if (maxAtlasDim) {
-            /** @type {string} */
+          if (maxAtlasDim !== null) {
             const sizeRecommendation =
               maxAtlasDim < 2048
                 ? ' (Warning: May be too small for all frames)'
                 : maxAtlasDim > 4096
-                  ? ' (Large size: ensure GPU compatibility)'
-                  : ' (Recommended size)';
-
-            logger.info(
-              `Generating atlas sprite sheet for item: ${itemId} with max dimension: ${maxAtlasDim}x${maxAtlasDim}${sizeRecommendation}`,
-            );
-          } else {
-            logger.info(
-              `Generating atlas sprite sheet for item: ${itemId} with auto-calculated dimensions (based on frame count)`,
-            );
-          }
-
-          // Find ObjectLayer by item-id
-          const objectLayer = await ObjectLayer.findByItemId(itemId).populate('objectLayerRenderFramesId');
-
-          if (!objectLayer) {
-            logger.error(`ObjectLayer not found for item-id: ${itemId}`);
-            process.exit(1);
-          }
-
-          const itemKey = objectLayer.data.item.id;
-          logger.info(`Found ObjectLayer: ${itemKey} (${objectLayer._id})`);
-
-          // Generate atlas sprite sheet
-          const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-            objectLayer.objectLayerRenderFramesId,
-            itemKey,
-            20, // cellPixelDim
-            maxAtlasDim,
-          );
-
-          /** @type {number} */
-          const frameCount = Object.values(metadata.frames).reduce((sum, frames) => sum + frames.length, 0);
-          logger.info(
-            `Atlas generated: ${metadata.atlasWidth}x${metadata.atlasHeight} pixels (${frameCount} frames packed)`,
-          );
-
-          // Save to File collection
-          const fileDoc = await new File({
-            name: `${itemKey}-atlas.png`,
-            data: buffer,
-            size: buffer.length,
-            mimetype: 'image/png',
-            md5: crypto.createHash('md5').update(buffer).digest('hex'),
-          }).save();
-
-          logger.info(`File saved with ID: ${fileDoc._id}`);
-
-          // Pin atlas PNG to IPFS
-          let toAtlasCid = '';
-          let toAtlasMetadataCid = '';
-          try {
-            const ipfsResult = await IpfsClient.addBufferToIpfs(
-              buffer,
-              `${itemKey}_atlas_sprite_sheet.png`,
-              `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-            );
-            if (ipfsResult) {
-              toAtlasCid = ipfsResult.cid;
-              logger.info(`Atlas sprite sheet pinned to IPFS – CID: ${toAtlasCid}`);
-              try {
-                await createPinRecord({
-                  cid: toAtlasCid,
-                  resourceType: 'atlas-sprite-sheet',
-                  mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                });
-              } catch (e) {
-                logger.warn('Failed to create pin record for atlas sprite sheet:', e.message);
-              }
-            }
-          } catch (ipfsError) {
-            logger.warn('Failed to add atlas sprite sheet to IPFS:', ipfsError.message);
+                  ? ' (Large size: ensure GPU compatibility)'
+                  : ' (Recommended size)';
+            logger.info(`Max atlas dimension: ${maxAtlasDim}x${maxAtlasDim}${sizeRecommendation}`);
           }
 
-          // Pin atlas metadata JSON to IPFS (fast-json-stable-stringify)
-          try {
-            const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-              metadata,
-              `${itemKey}_atlas_sprite_sheet_metadata.json`,
-              `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-            );
-            if (metadataIpfsResult) {
-              toAtlasMetadataCid = metadataIpfsResult.cid;
-              logger.info(`Atlas metadata pinned to IPFS – CID: ${toAtlasMetadataCid}`);
-              try {
-                await createPinRecord({
-                  cid: toAtlasMetadataCid,
-                  resourceType: 'atlas-metadata',
-                  mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                });
-              } catch (e) {
-                logger.warn('Failed to create pin record for atlas metadata:', e.message);
+          const selectedItemIds = await selectScopedItemIds({
+            ObjectLayer,
+            itemId,
+            instance: options.instance,
+            host,
+            path,
+            action: '--to-atlas-sprite-sheet',
+          });
+
+          logger.info(`Atlas rebuild for ${selectedItemIds.length} stored item(s) at ${upscaleFactor}px per cell`);
+          const tally = { rebuilt: 0, skipped: 0, failed: [] };
+
+          // One item at a time, isolated: a long batch runs through IPFS and can
+          // meet a dropped database connection, and a rerun of a failed item is a
+          // no-op for every item that already succeeded.
+          for (const currentItemId of selectedItemIds) {
+            try {
+              const objectLayer = await liveObjectLayer()
+                .findByItemId(currentItemId)
+                .populate('objectLayerRenderFramesId');
+              if (!objectLayer?.objectLayerRenderFramesId) {
+                logger.warn(`No render frames stored for '${currentItemId}', skipped`);
+                tally.skipped++;
+                continue;
               }
+
+              const { atlasDoc, metadata, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+                itemKey: currentItemId,
+                objectLayerRenderFrames: objectLayer.objectLayerRenderFramesId,
+                upscaleFactor,
+                maxAtlasDim,
+                options: { host, path },
+              });
+
+              const frameCount = Object.values(metadata.frames).reduce((sum, frames) => sum + frames.length, 0);
+              logger.info(
+                `Atlas for '${currentItemId}': ${metadata.atlasWidth}x${metadata.atlasHeight} cells, ` +
+                  `${frameCount} frames packed`,
+              );
+
+              objectLayer.atlasSpriteSheetId = atlasDoc._id;
+              if (!objectLayer.data.render) objectLayer.data.render = {};
+              objectLayer.data.render.cid = atlasCid;
+              objectLayer.data.render.metadataCid = atlasMetadataCid;
+              objectLayer.markModified('data.render');
+              applyStatPolicy(objectLayer, statPolicy);
+              await objectLayer.save();
+
+              await ObjectLayerEngine.computeAndSaveFinalSha256({ objectLayer, options: { host, path } });
+              tally.rebuilt++;
+            } catch (rebuildError) {
+              logger.error(`Atlas rebuild failed for '${currentItemId}': ${rebuildError.message}`);
+              tally.failed.push(currentItemId);
             }
-          } catch (ipfsError) {
-            logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
           }
 
-          // Check if atlas sprite sheet already exists
-          let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
-
-          if (atlasDoc) {
-            // Update existing – remove old File to prevent orphans
-            if (atlasDoc.fileId) await File.findByIdAndDelete(atlasDoc.fileId);
-            atlasDoc.fileId = fileDoc._id;
-            atlasDoc.cid = toAtlasCid;
-            atlasDoc.metadata = metadata;
-            await atlasDoc.save();
-            logger.info(`Updated existing AtlasSpriteSheet document: ${atlasDoc._id}`);
-          } else {
-            // Create new
-            atlasDoc = await new AtlasSpriteSheet({
-              fileId: fileDoc._id,
-              cid: toAtlasCid,
-              metadata,
-            }).save();
-            logger.info(`Created new AtlasSpriteSheet document: ${atlasDoc._id}`);
+          logger.info(
+            `Atlas rebuild done: ${tally.rebuilt} rebuilt, ${tally.skipped} without render frames, ` +
+              `${tally.failed.length} failed`,
+          );
+          if (tally.failed.length > 0) {
+            logger.warn(`Rerun for the failed item(s): ${tally.failed.join(',')}`);
           }
-
-          // Update ObjectLayer with reference to atlas sprite sheet and render CIDs
-          objectLayer.atlasSpriteSheetId = atlasDoc._id;
-          if (!objectLayer.data.render) objectLayer.data.render = {};
-          objectLayer.data.render.cid = toAtlasCid;
-          objectLayer.data.render.metadataCid = toAtlasMetadataCid;
-          objectLayer.markModified('data.render');
-          await objectLayer.save();
-
-          // Compute final SHA-256 and pin object layer data JSON to IPFS
-          await ObjectLayerEngine.computeAndSaveFinalSha256({
-            objectLayer,
-            ipfsClient: IpfsClient,
-            createPinRecord,
-          });
-
-          logger.info(`Atlas sprite sheet completed for item: ${itemKey}`);
         }
 
         // ── Handle --show-atlas-sprite-sheet ─────────────────────────────
@@ -1541,6 +1207,7 @@ try {
 
           // Overwrite the item id in the generated data with the unique variant
           multiFrameResult.objectLayerData.data.item.id = uniqueItemId;
+          applyStatPolicy(multiFrameResult.objectLayerData, statPolicy);
 
           logger.info(
             `Generated ${multiFrameResult.frameCount} frame(s) with ${multiFrameResult.objectLayerRenderFramesData.colors.length} unique colors`,
@@ -1555,7 +1222,7 @@ try {
             itemId: uniqueItemId,
             objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
             objectLayerData: multiFrameResult.objectLayerData,
-            cellPixelDim: 20,
+            cellPixelDim: upscaleFactor,
           });
 
           logger.info(`Wrote ${writtenFiles.length} asset file(s):`);
@@ -1563,148 +1230,34 @@ try {
             logger.info(`  → ${f}`);
           }
 
-          // 3. Persist to MongoDB (ObjectLayerRenderFrames + ObjectLayer)
-          const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
+          // 3. Persist ObjectLayer, render frames and the atlas, with every CID staged first
+          const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
             ObjectLayer,
             ObjectLayerRenderFrames,
             objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
             objectLayerData: multiFrameResult.objectLayerData,
-            createOptions: {
-              generateAtlas: false,
-            },
+            persistOptions: { upscaleFactor, options: { host, path } },
           });
 
           logger.info(`ObjectLayer persisted to MongoDB: ${objectLayer._id} (item: ${objectLayer.data.item.id})`);
-
-          // 4. Generate atlas sprite sheet + pin to IPFS
-          let atlasCid = '';
-          try {
-            const atlasItemKey = objectLayer.data.item.id;
-            const populatedObjectLayer = await ObjectLayer.findById(objectLayer._id).populate(
-              'objectLayerRenderFramesId',
-            );
-
-            const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-              populatedObjectLayer.objectLayerRenderFramesId,
-              atlasItemKey,
-              20,
-            );
-
-            // Save atlas file to File collection
-            const fileDoc = await new File({
-              name: `${atlasItemKey}-atlas.png`,
-              data: buffer,
-              size: buffer.length,
-              mimetype: 'image/png',
-              md5: crypto.createHash('md5').update(buffer).digest('hex'),
-            }).save();
-
-            // Pin atlas PNG to IPFS + copy into MFS
-            let atlasMetadataCid = '';
-            try {
-              const ipfsResult = await IpfsClient.addBufferToIpfs(
-                buffer,
-                `${atlasItemKey}_atlas_sprite_sheet.png`,
-                `/object-layer/${atlasItemKey}/${atlasItemKey}_atlas_sprite_sheet.png`,
-              );
-              if (ipfsResult) {
-                atlasCid = ipfsResult.cid;
-                logger.info(`Atlas sprite sheet pinned to IPFS – CID: ${atlasCid}`);
-                try {
-                  await createPinRecord({
-                    cid: atlasCid,
-                    resourceType: 'atlas-sprite-sheet',
-                    mfsPath: `/object-layer/${atlasItemKey}/${atlasItemKey}_atlas_sprite_sheet.png`,
-                    options: { host, path },
-                  });
-                } catch (e) {
-                  logger.warn('Failed to create pin record for atlas sprite sheet:', e.message);
-                }
-              }
-            } catch (ipfsError) {
-              logger.warn('Failed to add atlas sprite sheet to IPFS:', ipfsError.message);
-            }
-
-            // Pin atlas metadata JSON to IPFS (fast-json-stable-stringify)
-            try {
-              const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                metadata,
-                `${atlasItemKey}_atlas_sprite_sheet_metadata.json`,
-                `/object-layer/${atlasItemKey}/${atlasItemKey}_atlas_sprite_sheet_metadata.json`,
-              );
-              if (metadataIpfsResult) {
-                atlasMetadataCid = metadataIpfsResult.cid;
-                logger.info(`Atlas metadata pinned to IPFS – CID: ${atlasMetadataCid}`);
-                try {
-                  await createPinRecord({
-                    cid: atlasMetadataCid,
-                    resourceType: 'atlas-metadata',
-                    mfsPath: `/object-layer/${atlasItemKey}/${atlasItemKey}_atlas_sprite_sheet_metadata.json`,
-                    options: { host, path },
-                  });
-                } catch (e) {
-                  logger.warn('Failed to create pin record for atlas metadata:', e.message);
-                }
+          logger.info(`Final SHA-256: ${objectLayer.sha256}`);
+          if (objectLayer.cid) logger.info(`ObjectLayer data pinned to IPFS – CID: ${objectLayer.cid}`);
+
+          // 4. Mirror the human-resolution atlas PNG into both static asset directories
+          if (objectLayer.atlasSpriteSheetId) {
+            const atlasDoc = await AtlasSpriteSheet.findById(objectLayer.atlasSpriteSheetId);
+            const atlasFile = atlasDoc ? await File.findById(atlasDoc.fileId) : null;
+            if (atlasFile?.data) {
+              for (const bp of [srcBasePath, publicBasePath]) {
+                const atlasOutputDir = nodePath.join(bp, 'assets', descriptor.itemType, uniqueItemId);
+                await fs.ensureDir(atlasOutputDir);
+                const atlasOutputPath = nodePath.join(atlasOutputDir, `${uniqueItemId}-atlas.png`);
+                await fs.writeFile(atlasOutputPath, atlasFile.data);
+                logger.info(
+                  `Atlas sprite sheet written: ${atlasDoc.metadata.atlasWidth}x${atlasDoc.metadata.atlasHeight} cells → ${atlasOutputPath}`,
+                );
               }
-            } catch (ipfsError) {
-              logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
-            }
-
-            // Upsert AtlasSpriteSheet document (with CID)
-            let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': atlasItemKey });
-            if (atlasDoc) {
-              if (atlasDoc.fileId) await File.findByIdAndDelete(atlasDoc.fileId);
-              atlasDoc.fileId = fileDoc._id;
-              atlasDoc.cid = atlasCid;
-              atlasDoc.metadata = metadata;
-              await atlasDoc.save();
-              logger.info(`Updated existing AtlasSpriteSheet document: ${atlasDoc._id}`);
-            } else {
-              atlasDoc = await new AtlasSpriteSheet({
-                fileId: fileDoc._id,
-                cid: atlasCid,
-                metadata,
-              }).save();
-              logger.info(`Created new AtlasSpriteSheet document: ${atlasDoc._id}`);
-            }
-
-            // Link atlas to ObjectLayer and set data.render.cid + data.render.metadataCid
-            populatedObjectLayer.atlasSpriteSheetId = atlasDoc._id;
-            if (!populatedObjectLayer.data.render) populatedObjectLayer.data.render = {};
-            populatedObjectLayer.data.render.cid = atlasCid;
-            populatedObjectLayer.data.render.metadataCid = atlasMetadataCid;
-            populatedObjectLayer.markModified('data.render');
-            await populatedObjectLayer.save();
-
-            // Also write atlas PNG to both static asset directories
-            for (const bp of [srcBasePath, publicBasePath]) {
-              const atlasOutputDir = nodePath.join(bp, 'assets', descriptor.itemType, uniqueItemId);
-              await fs.ensureDir(atlasOutputDir);
-              const atlasOutputPath = nodePath.join(atlasOutputDir, `${atlasItemKey}-atlas.png`);
-              await fs.writeFile(atlasOutputPath, buffer);
-              logger.info(
-                `Atlas sprite sheet generated: ${metadata.atlasWidth}x${metadata.atlasHeight} → ${atlasOutputPath}`,
-              );
-            }
-          } catch (atlasError) {
-            logger.error(`Failed to generate atlas for ${uniqueItemId}:`, atlasError);
-          }
-
-          // 5. Compute final SHA-256, pin OL data JSON to IPFS, create pin records
-          try {
-            const finalObjectLayer = await ObjectLayer.findById(objectLayer._id).populate('objectLayerRenderFramesId');
-            const finalized = await ObjectLayerEngine.computeAndSaveFinalSha256({
-              objectLayer: finalObjectLayer,
-              ipfsClient: IpfsClient,
-              createPinRecord,
-              options: { host, path },
-            });
-            logger.info(`Final SHA-256: ${finalized.sha256}`);
-            if (finalized.cid) {
-              logger.info(`ObjectLayer data pinned to IPFS – CID: ${finalized.cid}`);
             }
-          } catch (finalizeError) {
-            logger.error('Failed to finalize SHA-256 / IPFS:', finalizeError);
           }
 
           logger.info(`✓ Generation complete for "${uniqueItemId}" (seed: ${genSeed}, frames: ${genFrameCount})`);
@@ -1748,6 +1301,10 @@ try {
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
     .option('--mongo-host <mongo-host>', 'Mongo host override')
     .option('--dev', 'Force development environment')
+    .option(
+      '--sync-entities',
+      'Point the instance conf at every entity-type default its maps place and every skill their items trigger, dropping what the world no longer carries',
+    )
     .option('--publish-build', 'Build instance backup directory with all related maps, entities and object layers')
     .option('--publish-remove', 'Remove published instance from underpostnet/cyberia-instances repository')
     .option('--publish', 'Publish instance in underpostnet/cyberia-instances repository')
@@ -1818,14 +1375,9 @@ try {
         // and git refuses to touch a tree owned by someone else until it is declared safe.
         Underpost.repo.declareSafeDirectory('/home/dd/cyberia-instances');
         if (options.publishBuild) {
-          if (!fs.existsSync('/home/dd/cyberia-instances')) {
+          if (!fs.existsSync('/home/dd/cyberia-instances'))
             shellExec(`cd /home/dd && ${cli()} clone underpostnet/cyberia-instances`);
-          } else {
-            shellExec(`${cli()} run clean /home/dd/cyberia-instances`);
-            shellExec(`cd /home/dd/cyberia-instances && ${cli()} pull . underpostnet/cyberia-instances`, {
-              silentOnError: true,
-            });
-          }
+          else shellExec(`cd /home/dd/cyberia-instances && ${cli()} cmt --switch-repo underpostnet/cyberia-instances`);
 
           fs.mkdirpSync(`/home/dd/cyberia-instances/conf/dd-cyberia`);
           fs.copyFileSync(
@@ -1902,11 +1454,21 @@ try {
             `./engine-private/conf/dd-cyberia/instances/mmo-server/build/development/.`,
             `/home/dd/cyberia-instances/deployments/cyberia-server/.`,
           );
+          const folders = ['ui-icons', 'cursor', 'fonts', 'icons', 'splash', 'templates'];
+          for (const folder of folders)
+            fs.copySync(
+              `./src/client/public/cyberia/assets/${folder}`,
+              `/home/dd/cyberia-instances/public/cyberia/assets/${folder}`,
+            );
           // fs.removeSync(`/home/dd/cyberia-instances/public/cyberia`);
           // fs.mkdirpSync(`/home/dd/cyberia-instances/public/cyberia`);
           fs.mkdirpSync(`/home/dd/cyberia-instances/instances`);
           fs.mkdirpSync(`/home/dd/cyberia-instances/sagas`);
           for (const _instanceCode of instanceCode.split(',')) {
+            if (fs.existsSync(`/home/dd/cyberia-instances/instances/${_instanceCode}`))
+              shellExec(`rm -rf /home/dd/cyberia-instances/instances/${_instanceCode}`);
+            if (fs.existsSync(`/home/dd/cyberia-instances/sagas/${_instanceCode}.json`))
+              shellExec(`rm -rf /home/dd/cyberia-instances/sagas/${_instanceCode}.json`);
             fs.copySync(
               `./engine-private/cyberia-instances/${_instanceCode}`,
               `/home/dd/cyberia-instances/instances/${_instanceCode}`,
@@ -1923,6 +1485,19 @@ try {
               '/home/dd/cyberia-instances/conf/dd-cyberia/conf.instances.json',
             );
 
+          if (!fs.existsSync('/home/dd/cyberia-instances/manifests'))
+            fs.mkdirSync('/home/dd/cyberia-instances/manifests');
+          fs.copySync('./cyberia-server/manifests', '/home/dd/cyberia-instances/manifests', { overwrite: true });
+          fs.copySync('./cyberia-client/manifests', '/home/dd/cyberia-instances/manifests', { overwrite: true });
+          if (!fs.existsSync('/home/dd/cyberia-instances/manifests/deployments/dd-cyberia-development'))
+            fs.mkdirSync('/home/dd/cyberia-instances/manifests/deployments/dd-cyberia-development', {
+              recursive: true,
+            });
+          fs.copySync(
+            './manifests/deployment/dd-cyberia-development',
+            '/home/dd/cyberia-instances/manifests/deployments/dd-cyberia-development',
+            { overwrite: true },
+          );
           const fromN = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
           const publishMessage =
             shellExec(`node bin cmt --changelog-msg --from-n-commit ${fromN} --changelog-no-hash`, {
@@ -1987,6 +1562,8 @@ try {
           'cyberia-skill',
           'cyberia-entity-type-default',
           'cyberia-saga',
+          'cyberia-audio',
+          'cyberia-map-audio-conf',
           'object-layer',
           'object-layer-render-frames',
           'atlas-sprite-sheet',
@@ -2007,6 +1584,8 @@ try {
       const CyberiaSkill = DataBaseProviderService.getModel('cyberia-skill', { host, path });
       const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('cyberia-entity-type-default', { host, path });
       const CyberiaSaga = DataBaseProviderService.getModel('cyberia-saga', { host, path });
+      const CyberiaAudio = DataBaseProviderService.getModel('cyberia-audio', { host, path });
+      const CyberiaMapAudioConf = DataBaseProviderService.getModel('cyberia-map-audio-conf', { host, path });
       const ObjectLayer = DataBaseProviderService.getModel('object-layer', { host, path });
       const ObjectLayerRenderFrames = DataBaseProviderService.getModel('object-layer-render-frames', { host, path });
       const AtlasSpriteSheet = DataBaseProviderService.getModel('atlas-sprite-sheet', { host, path });
@@ -2027,8 +1606,8 @@ try {
         atlasMetadata: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
       });
 
-      // Canonical pins now carry a single `mfsPath`; `mfsPaths` (plural) is only read
-      // for backward compatibility with older backups that consolidated shared CIDs.
+      // A canonical pin carries one `mfsPath`. `mfsPaths` (plural) is read too,
+      // because a backup that consolidated shared CIDs writes that field.
       const collectMfsPaths = (doc = {}) => {
         const paths = new Set();
         if (doc.mfsPath) paths.add(doc.mfsPath);
@@ -2084,10 +1663,9 @@ try {
           ...(entry.mfsPath ? { mfsPath: entry.mfsPath } : {}),
         }));
 
-      // Bring the live Ipfs collection in line with the mfsPath-unique model: collapse
-      // duplicate mfsPath rows (keeping the most recently updated association) then sync
-      // indexes so the legacy {cid,resourceType} unique index is dropped and the new
-      // partial unique index on mfsPath is built. Idempotent and safe to re-run.
+      // Bring the Ipfs collection in line with the mfsPath-unique model: collapse
+      // duplicate mfsPath rows, keeping the most recent, then sync indexes so the
+      // partial unique index on mfsPath is built. Safe to re-run.
       const reconcileIpfsRegistryIndexes = async () => {
         let removedDuplicates = 0;
         const duplicateGroups = await Ipfs.aggregate([
@@ -2141,13 +1719,10 @@ try {
 
       // ── CAPTURE CURRENT FALLBACK WORLD ──────────────────────────────
       //
-      // The procedural fallback world only exists in engine memory (see
-      // cyberia-fallback-world.js): it is rebuilt from code defaults on every
-      // boot and intercepts any service that asks for an absent instance.
-      // Capturing writes that exact world into MongoDB under [instance-code] —
-      // together with the content collections the fallback path serves from
-      // code defaults rather than the DB — so the export below can back it up
-      // and `--import` can restore it as an ordinary persisted instance.
+      // The procedural fallback world lives only in engine memory. A capture
+      // writes it to MongoDB under [instance-code], with the content
+      // collections the fallback path serves from code defaults, so the export
+      // below can back it up and `--import` can restore it.
       if (options.exportCurrentFallbackworld) {
         const { generateFallbackWorld } = await import('../src/api/cyberia-instance/cyberia-fallback-world.js');
         const { captureFallbackWorld } = await import('../src/api/cyberia-instance/cyberia-fallback-capture.js');
@@ -2188,6 +1763,8 @@ try {
             CyberiaSkill,
             CyberiaEntityTypeDefault,
             CyberiaDialogue,
+            CyberiaMapAudioConf,
+            CyberiaAudio,
             ObjectLayer,
           },
           world,
@@ -2202,7 +1779,7 @@ try {
           logger.error(
             `Capture aborted: ${capture.missingObjectLayerItemIds.length} referenced item id(s) have no ObjectLayer in MongoDB:`,
             capture.missingObjectLayerItemIds.join(', '),
-            `— run \`node bin/cyberia ol ${capture.missingObjectLayerItemIds.join(' ')} --import\` (or ` +
+            `— run \`node bin/cyberia ol ${capture.missingObjectLayerItemIds.join(',')} --from-directory --import\` (or ` +
               '`node bin/cyberia run-workflow import-default-items`) first.',
           );
           await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
@@ -2214,6 +1791,7 @@ try {
           mapCodes: capture.plan.instance.cyberiaMapCodes,
           actions: capture.plan.actions.length,
           quests: capture.plan.quests.length,
+          audioConfs: capture.audio.audioConfs,
           objectLayerItemIds: capture.plan.itemIds.length,
         });
 
@@ -2222,6 +1800,28 @@ try {
         if (options.export === undefined) options.export = true;
       }
 
+      // ── SYNC ENTITY-TYPE DEFAULTS ───────────────────────────────────
+      if (options.syncEntities) {
+        const result = await CyberiaEntityTypeDefaultService.syncInstance({ instanceCode }, { host, path });
+        logger.info(`sync-entities ${instanceCode}`, {
+          maps: result.mapCodes.length,
+          references: result.entityDefaults.length,
+          ...(result.linked.length > 0 ? { linked: result.linked } : {}),
+          ...(result.dropped.length > 0 ? { dropped: result.dropped } : {}),
+          ...(result.skipped.length > 0 ? { claimedByAnotherInstance: result.skipped } : {}),
+          ...(result.skills.length > 0 ? { skills: result.skills } : {}),
+          ...(result.entitiesUpdated.length > 0
+            ? { entitiesUpdated: result.entitiesUpdated.map(({ mapCode, entities }) => `${mapCode}:${entities}`) }
+            : {}),
+          ...(result.conflicts.length > 0 ? { notLinkedSameBuildAlreadyReferenced: result.conflicts } : {}),
+          ...(result.duplicates.length > 0 ? { duplicateReferencesDeleteOne: result.duplicates } : {}),
+        });
+        if (options.export === undefined && !options.import && !options.drop) {
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+          return;
+        }
+      }
+
       // ── EXPORT ──────────────────────────────────────────────────────
       if (options.export !== undefined) {
         const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
@@ -2237,6 +1837,25 @@ try {
             : `./engine-private/cyberia-instances/${instanceCode}`;
 
         fs.ensureDirSync(backupDir);
+        // The export is a projection of what this instance references, never an archive of
+        // everything it once did: a document that drops out of the world has to leave the
+        // directory with it, or the next import brings it back from the dead. Emptied up front,
+        // so a collection that exports nothing this run ends up empty rather than stale. The
+        // asset directories — files, ipfs, render-frames, atlas sheets — are content-addressed
+        // and expensive to refetch, so they keep what they have.
+        for (const collection of [
+          'maps',
+          'cyberia-map-audio-confs',
+          'cyberia-audio',
+          'cyberia-quests',
+          'cyberia-actions',
+          'cyberia-skills',
+          'cyberia-entity-type-defaults',
+          'cyberia-dialogues',
+          'object-layers',
+        ]) {
+          fs.emptyDirSync(`${backupDir}/${collection}`);
+        }
         logger.info('Exporting instance', { code: instanceCode, backupDir });
 
         // Helper: export a File document to the files/ directory
@@ -2266,6 +1885,11 @@ try {
         // 1b. Export linked CyberiaInstanceConf (skillRules, equipmentRules, entityDefaults, etc.)
         // If no conf doc exists yet (instance created before auto-upsert logic), create one using
         // schema defaults — identical to the behaviour in CyberiaInstanceService.post().
+        //
+        // Compact first: a reference whose entity-type default is gone cannot be exported, and
+        // writing it into the backup would carry the dangling id into every world restored from
+        // it. Dropping it here repairs the live conf and the backup in one step.
+        await CyberiaEntityTypeDefaultService.compactInstanceRefs({ host, path }, { instanceCode });
         let instanceConf =
           (await CyberiaInstanceConf.findOne({ instanceCode }).lean()) ||
           (instance.conf ? await CyberiaInstanceConf.findById(instance.conf).lean() : null);
@@ -2283,10 +1907,10 @@ try {
           instanceConf = created?.toObject ? created.toObject() : created;
         }
         if (instanceConf) {
-          // `.lean()` skips Mongoose schema defaults and older docs may predate
-          // some fields, so backfill every CyberiaInstanceConfSchema field from
-          // the canonical defaults before writing the backup.
-          instanceConf = fillInstanceConfDefaults(instanceConf);
+          // `.lean()` skips the schema defaults and a document written before a bound tightened
+          // may carry a value the schema now rejects; the backup is made whole and valid here so
+          // it imports back as-is.
+          ({ conf: instanceConf } = await CyberiaInstanceConfService.coerceToSchema(instanceConf, CyberiaInstanceConf));
           fs.writeJsonSync(`${backupDir}/cyberia-instance-conf.json`, instanceConf, { spaces: 2 });
           logger.info('Exported CyberiaInstanceConf', { instanceCode });
         } else {
@@ -2323,6 +1947,50 @@ try {
         }
         logger.info(`Exported ${maps.length} CyberiaMap document(s)`, { codes: maps.map((m) => m.code) });
 
+        // 3a. Export the audio configuration of those maps, and the assets it binds.
+        //     A CyberiaMapAudioConf belongs to one map, so it travels with the instance. A
+        //     CyberiaAudio is global and shared by every map that binds its code, so it travels
+        //     as a copy: the import upserts it by code and leaves other instances' bindings alone.
+        //     The WAV rides along as an ordinary File document, keeping its _id so `fileId` still
+        //     resolves after a restore.
+        const audioConfs = await CyberiaMapAudioConf.find({ mapCode: { $in: [...mapCodes] } }).lean();
+        if (audioConfs.length > 0) {
+          fs.ensureDirSync(`${backupDir}/cyberia-map-audio-confs`);
+          const audioCodes = new Set();
+          for (const conf of audioConfs) {
+            fs.writeJsonSync(`${backupDir}/cyberia-map-audio-confs/${encodeURIComponent(conf.mapCode)}.json`, conf, {
+              spaces: 2,
+            });
+            if (conf.defaultMusic) audioCodes.add(conf.defaultMusic);
+            for (const event of conf.events || []) if (event.audioCode) audioCodes.add(event.audioCode);
+          }
+          logger.info(`Exported ${audioConfs.length} CyberiaMapAudioConf document(s)`, {
+            mapCodes: audioConfs.map((c) => c.mapCode),
+          });
+
+          const audioAssets = await CyberiaAudio.find({ code: { $in: [...audioCodes] } }).lean();
+          if (audioAssets.length > 0) {
+            fs.ensureDirSync(`${backupDir}/cyberia-audio`);
+            for (const asset of audioAssets) {
+              fs.writeJsonSync(`${backupDir}/cyberia-audio/${encodeURIComponent(asset.code)}.json`, asset, {
+                spaces: 2,
+              });
+              if (asset.fileId) await exportFileDoc(asset.fileId, `audio-${asset.code}`);
+            }
+          }
+          const missingAudioCodes = [...audioCodes].filter((code) => !audioAssets.some((asset) => asset.code === code));
+          logger.info(`Exported ${audioAssets.length} CyberiaAudio document(s)`, {
+            codes: audioAssets.map((a) => a.code),
+          });
+          if (missingAudioCodes.length > 0) {
+            logger.warn(
+              'Audio bindings reference codes with no imported CyberiaAudio document — ' +
+                'run `node bin/cyberia audio --import` before restoring this backup',
+              { codes: missingAudioCodes },
+            );
+          }
+        }
+
         // 3b. Export quests + actions bound to THIS instance's maps (sourceMapCode
         //     in the instance's map codes) — only the content tied to this instance.
         //     Dialogue codes the actions reference are collected so they travel too.
@@ -2353,134 +2021,51 @@ try {
           logger.info(`Exported ${actions.length} CyberiaAction document(s)`, { codes: actions.map((a) => a.code) });
         }
 
-        // 4. Collect all objectLayerItemIds from map entities
-        const objectLayerItemIds = new Set();
-        for (const map of maps) {
-          for (const entity of map.entities || []) {
-            for (const itemId of entity.objectLayerItemIds || []) {
-              objectLayerItemIds.add(itemId);
-            }
-          }
-        }
-
-        // 4b. Add instance-level itemIds ({ id, defaultPlayerInventory }).
-        for (const entry of instance.itemIds || []) {
-          const id = typeof entry === 'string' ? entry : entry?.id;
-          if (id) objectLayerItemIds.add(id);
-        }
-
-        const contentItemIds = new Set(objectLayerItemIds);
-
-        // 4c. Add all itemIds referenced by CyberiaInstanceConf (entityDefaults + skillConfig).
-        //     This ensures liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers and
-        //     skill trigger items are included even if no map entity currently uses them.
-        if (instanceConf) {
-          for (const ed of instanceConf.entityDefaults || []) {
-            for (const id of ed.liveItemIds || []) if (id) objectLayerItemIds.add(id);
-            for (const id of ed.deadItemIds || []) if (id) objectLayerItemIds.add(id);
-            for (const id of ed.dropItemIds || []) if (id) objectLayerItemIds.add(id);
-            for (const slot of ed.defaultObjectLayers || []) {
-              if (slot.itemId) objectLayerItemIds.add(slot.itemId);
-            }
-          }
-          for (const sc of instanceConf.skillConfig || []) {
-            if (sc.triggerItemId) objectLayerItemIds.add(sc.triggerItemId);
-            for (const skill of sc.skills || []) {
-              if (skill.summonedEntityItemId && !skill.summonedEntityItemId.startsWith('$')) {
-                objectLayerItemIds.add(skill.summonedEntityItemId);
-              }
-            }
-          }
-        }
-
-        // 4c-bis. Add the item ids the instance's vendor / assembler / quest
-        //     catalogs name. The interact modal draws an icon for every shop
-        //     item, recipe ingredient/output and quest reward, so their atlases
-        //     must travel with the backup even when no map entity wears them.
-        //     Kept out of contentItemIds: catalogs must not widen the
-        //     entity-type-default match surface below.
-        for (const action of actions) {
-          for (const shopItem of action.shopItems || []) {
-            if (shopItem.itemId) objectLayerItemIds.add(shopItem.itemId);
-            if (shopItem.priceItemId) objectLayerItemIds.add(shopItem.priceItemId);
-          }
-          for (const recipe of action.craftRecipes || []) {
-            for (const ingredient of recipe.ingredients || []) {
-              if (ingredient.itemId) objectLayerItemIds.add(ingredient.itemId);
-            }
-            for (const output of recipe.outputItems || []) {
-              if (output.itemId) objectLayerItemIds.add(output.itemId);
-            }
-          }
-        }
-        for (const quest of quests) {
-          for (const step of quest.steps || []) {
-            for (const objective of step.objectives || []) {
-              if (objective.itemId) objectLayerItemIds.add(objective.itemId);
-            }
-          }
-          for (const reward of quest.rewards || []) {
-            if (reward.itemId) objectLayerItemIds.add(reward.itemId);
+        // 4. Export the entity-type defaults this instance's conf references, by _id.
+        //    Membership is a reference, not a resemblance: matching on item ids used to pull in
+        //    every document that happened to share a skin, so two instances built on the same
+        //    art exported each other's wiring and overwrote it on the way back in.
+        const referencedIds = (instanceConf?.entityDefaults || []).map((id) => String(id?._id ?? id));
+        // Every reference resolves: the conf was compacted before it was read.
+        const entityDefaults = referencedIds.length
+          ? await CyberiaEntityTypeDefault.find({ _id: { $in: referencedIds } }).lean()
+          : [];
+        if (entityDefaults.length > 0) {
+          fs.ensureDirSync(`${backupDir}/cyberia-entity-type-defaults`);
+          for (const ed of entityDefaults) {
+            fs.writeJsonSync(`${backupDir}/cyberia-entity-type-defaults/${ed._id}.json`, ed, { spaces: 2 });
           }
+          logger.info(`Exported ${entityDefaults.length} CyberiaEntityTypeDefault document(s)`, {
+            entityTypes: entityDefaults.map((ed) => ed.entityType),
+          });
         }
 
-        // 4d. Export skills whose trigger item belongs to this instance (own model:
-        //     CyberiaSkill, keyed by triggerItemId). Their summoned-entity items are
-        //     added to the OL set so those atlases export too. Runs before the
-        //     dialogue + OL queries so the summoned ids are included.
-        if (objectLayerItemIds.size > 0) {
-          const skills = await CyberiaSkill.find({ triggerItemId: { $in: [...objectLayerItemIds] } }).lean();
+        // 4b. Everything this instance names: what its maps place, what its entity-type defaults
+        //     wire, and what its vendor / assembler / quest catalogs trade. Every one of these
+        //     draws an icon somewhere, so the atlases travel with the backup even when no map
+        //     entity wears them. One rule, shared with the boot payload and the editor's sync.
+        const objectLayerItemIds = collectInstanceItemIds({ maps, entityDefaults, actions, quests });
+
+        // 4c. Export the skills this instance runs: the collection owns the definitions, and one
+        //     belongs here when its trigger item is an id the instance names — which is how a
+        //     trigger only a quest objective or a vendor's shelf mentions still travels. Their
+        //     summoned entities join the OL set, so this runs before the dialogue + OL queries.
+        {
+          const skills = selectInstanceSkills(await CyberiaSkill.find({}).lean(), objectLayerItemIds);
           if (skills.length > 0) {
             fs.ensureDirSync(`${backupDir}/cyberia-skills`);
             for (const skill of skills) {
               fs.writeJsonSync(`${backupDir}/cyberia-skills/${encodeURIComponent(skill.triggerItemId)}.json`, skill, {
                 spaces: 2,
               });
-              for (const def of skill.skills || []) {
-                if (def.summonedEntityItemId && !def.summonedEntityItemId.startsWith('$')) {
-                  objectLayerItemIds.add(def.summonedEntityItemId);
-                }
-              }
             }
+            for (const summoned of collectSummonedItemIds(skills)) objectLayerItemIds.add(summoned);
             logger.info(`Exported ${skills.length} CyberiaSkill document(s)`, {
               triggerItemIds: skills.map((sk) => sk.triggerItemId),
             });
           }
         }
 
-        // 4d-bis. Export entity-type defaults whose item ids belong to this
-        //     instance's real content (own model: CyberiaEntityTypeDefault). A
-        //     default is related when any of its live/dead/drop ids or default
-        //     object-layer ids appears in contentItemIds — map/instance content
-        //     only, NOT the canonical conf defaults every instance shares (which
-        //     would spuriously drag in the global seed entity-type-defaults).
-        //     Matched ids are folded back into objectLayerItemIds so the related
-        //     atlases + dialogues export too.
-        if (contentItemIds.size > 0) {
-          const idsForMatch = [...contentItemIds];
-          const entityDefaults = await CyberiaEntityTypeDefault.find({
-            $or: [
-              { liveItemIds: { $in: idsForMatch } },
-              { deadItemIds: { $in: idsForMatch } },
-              { dropItemIds: { $in: idsForMatch } },
-              { 'defaultObjectLayers.itemId': { $in: idsForMatch } },
-            ],
-          }).lean();
-          if (entityDefaults.length > 0) {
-            fs.ensureDirSync(`${backupDir}/cyberia-entity-type-defaults`);
-            for (const ed of entityDefaults) {
-              fs.writeJsonSync(`${backupDir}/cyberia-entity-type-defaults/${ed._id}.json`, ed, { spaces: 2 });
-              for (const id of ed.liveItemIds || []) if (id) objectLayerItemIds.add(id);
-              for (const id of ed.deadItemIds || []) if (id) objectLayerItemIds.add(id);
-              for (const id of ed.dropItemIds || []) if (id) objectLayerItemIds.add(id);
-              for (const slot of ed.defaultObjectLayers || []) if (slot.itemId) objectLayerItemIds.add(slot.itemId);
-            }
-            logger.info(`Exported ${entityDefaults.length} CyberiaEntityTypeDefault document(s)`, {
-              entityTypes: entityDefaults.map((ed) => ed.entityType),
-            });
-          }
-        }
-
         // 4e. Export sagas related to this instance. A saga is considered related
         //     when its code matches the instance code (direct namespace match), or
         //     when its mapCodes or itemIds overlap with the instance's data.
@@ -2488,22 +2073,7 @@ try {
         //     conf-default, and skill-summoned item IDs — giving the broadest possible
         //     match surface for saga discovery.
         const sagaCodeMatch = instanceCode ? await CyberiaSaga.find({ code: instanceCode }).lean() : [];
-        // Disabling overlaps queries for now because they can be very expensive and are not strictly necessary for a backup.
-        const sagaMapOverlap = true
-          ? []
-          : mapCodes.size > 0
-            ? await CyberiaSaga.find({ mapCodes: { $in: [...mapCodes] } }).lean()
-            : [];
-        const sagaItemOverlap = true
-          ? []
-          : objectLayerItemIds.size > 0
-            ? await CyberiaSaga.find({ itemIds: { $in: [...objectLayerItemIds] } }).lean()
-            : [];
-        const allSagas = [
-          ...new Map(
-            [...sagaCodeMatch, ...sagaMapOverlap, ...sagaItemOverlap].map((s) => [s._id.toString(), s]),
-          ).values(),
-        ];
+        const allSagas = [...new Map(sagaCodeMatch.map((s) => [s._id.toString(), s])).values()];
         if (allSagas.length > 0) {
           fs.ensureDirSync(`${backupDir}/cyberia-sagas`);
           for (const saga of allSagas) {
@@ -2615,8 +2185,9 @@ try {
             if (atlas) {
               const atlasExport = newInstance(atlas);
               objectLayerExport.atlasSpriteSheetId = atlas._id;
-              if (atlas.fileId) {
-                await exportFileDoc(atlas.fileId, `atlas-${itemKey}`);
+              // Every render travels with the atlas, so a restore leaves no reference dangling.
+              for (const field of ATLAS_FILE_FIELDS) {
+                if (atlas[field]) await exportFileDoc(atlas[field], atlasBackupFileKey(field, itemKey));
               }
 
               const atlasFile = atlas.fileId ? await File.findById(atlas.fileId).lean() : null;
@@ -2812,15 +2383,15 @@ try {
 
         logger.info('Importing instance', { code: instanceCode, backupDir });
 
-        // Idempotent: a backup restore writes object layers, so collapse any
-        // legacy duplicates and make the data.item.id index unique first.
+        // A restore writes object layers, so collapse duplicates and make the
+        // data.item.id index unique first.
         const { removedIds, indexUpgraded } = await ObjectLayer.ensureUniqueItemIdIndex();
         if (removedIds.length > 0) logger.warn(`Removed ${removedIds.length} duplicate ObjectLayer document(s)`);
         if (indexUpgraded) logger.info('Upgraded data.item.id index to unique');
 
-        // Item ids belonging to this instance (collected from imported object
-        // layers + the instance doc) — used to backfill missing skills from the
-        // canonical DefaultSkillConfig when the backup predates the skill model.
+        // Item ids of this instance, from the imported object layers and the
+        // instance doc. They backfill skills from DefaultSkillConfig when the
+        // backup carries none.
         const importedItemIds = new Set();
 
         // 0. Drop existing documents if --drop is set
@@ -2841,30 +2412,17 @@ try {
             // Query other instances/maps for shared thumbnail exclusion
             const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
 
-            // Add instance-level itemIds (may not appear in any map entity)
-            for (const entry of existingInstance.itemIds || []) {
-              const id = typeof entry === 'string' ? entry : entry?.id;
-              if (id) dropOlItemIds.add(id);
-            }
-
-            // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
+            // Add the item ids the conf's referenced entity-type defaults name.
             const existingConf =
               (await CyberiaInstanceConf.findOne({ instanceCode }).lean()) ||
               (existingInstance.conf ? await CyberiaInstanceConf.findById(existingInstance.conf).lean() : null);
             if (existingConf) {
-              for (const ed of existingConf.entityDefaults || []) {
-                for (const id of ed.liveItemIds || []) if (id) dropOlItemIds.add(id);
-                for (const id of ed.deadItemIds || []) if (id) dropOlItemIds.add(id);
-                for (const id of ed.dropItemIds || []) if (id) dropOlItemIds.add(id);
-                for (const slot of ed.defaultObjectLayers || []) if (slot.itemId) dropOlItemIds.add(slot.itemId);
-              }
-              for (const sc of existingConf.skillConfig || []) {
-                if (sc.triggerItemId) dropOlItemIds.add(sc.triggerItemId);
-                for (const skill of sc.skills || []) {
-                  if (skill.summonedEntityItemId && !skill.summonedEntityItemId.startsWith('$'))
-                    dropOlItemIds.add(skill.summonedEntityItemId);
-                }
-              }
+              // The conf names its entity-type defaults by _id; read the documents to reach their items.
+              const referencedIds = (existingConf.entityDefaults || []).map((id) => String(id?._id ?? id));
+              const referenced = referencedIds.length
+                ? await CyberiaEntityTypeDefault.find({ _id: { $in: referencedIds } }).lean()
+                : [];
+              for (const itemId of collectInstanceItemIds({ entityDefaults: referenced })) dropOlItemIds.add(itemId);
             }
 
             const otherMaps = await CyberiaMap.find(
@@ -2888,6 +2446,12 @@ try {
               const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
               logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap document(s)`);
 
+              // A map's audio configuration belongs to that map. The assets it bound do not:
+              // they are global and shared, so they stay.
+              const audioConfResult = await CyberiaMapAudioConf.deleteMany({ mapCode: { $in: [...dropMapCodes] } });
+              if (audioConfResult.deletedCount > 0)
+                logger.info(`Dropped ${audioConfResult.deletedCount} CyberiaMapAudioConf document(s)`);
+
               // Quests + actions are bound to maps by sourceMapCode, so they drop
               // with this instance's maps — only the content tied to this instance.
               const questResult = await CyberiaQuest.deleteMany({ sourceMapCode: { $in: [...dropMapCodes] } });
@@ -2920,6 +2484,15 @@ try {
               }
             }
 
+            // A conf stores no skills: the ones this instance ran are the ones its own items trigger.
+            // What those summon is drawn by this instance alone, so it joins the drop surface and is
+            // then protected by the same shared-with-another-map check as everything else.
+            for (const itemId of collectSummonedItemIds(
+              selectInstanceSkills(await CyberiaSkill.find({}).lean(), dropOlItemIds),
+            )) {
+              dropOlItemIds.add(itemId);
+            }
+
             // Exclude OL item IDs referenced by maps outside this instance
             const sharedOlItemIds = new Set();
             for (const m of otherMaps) {
@@ -2979,19 +2552,17 @@ try {
                 if (doc.atlasSpriteSheetId) atlasIds.push(doc.atlasSpriteSheetId);
               }
 
-              // Delete AtlasSpriteSheet + referenced File docs
-              if (atlasIds.length > 0) {
-                const atlasDocs = await AtlasSpriteSheet.find({ _id: { $in: atlasIds } }, { fileId: 1, cid: 1 }).lean();
-                const atlasFileIds = atlasDocs.map((a) => a.fileId).filter(Boolean);
-                for (const atlas of atlasDocs) {
-                  if (atlas.cid) cidsToUnpin.add(atlas.cid);
-                }
-                if (atlasFileIds.length > 0) {
-                  const fileResult = await File.deleteMany({ _id: { $in: atlasFileIds } });
-                  logger.info(`Dropped ${fileResult.deletedCount} File document(s) (atlas)`);
-                }
-                const atlasResult = await AtlasSpriteSheet.deleteMany({ _id: { $in: atlasIds } });
-                logger.info(`Dropped ${atlasResult.deletedCount} AtlasSpriteSheet document(s)`);
+              // Delete AtlasSpriteSheet + every File render it owns, through the store that
+              // knows how many renders that is.
+              if (atlasIds.length > 0 || itemKeysToClean.size > 0) {
+                const purged = await AtlasSpriteSheetStore.purge({
+                  itemKeys: [...itemKeysToClean],
+                  atlasIds,
+                  options: { host, path },
+                });
+                for (const cid of purged.cids) cidsToUnpin.add(cid);
+                if (purged.files > 0) logger.info(`Dropped ${purged.files} File document(s) (atlas)`);
+                if (purged.atlases > 0) logger.info(`Dropped ${purged.atlases} AtlasSpriteSheet document(s)`);
               }
 
               // Delete RenderFrames
@@ -3048,13 +2619,16 @@ try {
           const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
           let importedConf = null;
           if (fs.existsSync(confImportPath)) {
-            // Backfill any missing schema fields so older backups import a
-            // complete, playable config into the DB.
-            const confData = fillInstanceConfDefaults(fs.readJsonSync(confImportPath));
+            // Made whole and valid before the live conf is touched, so a backup the schema
+            // rejects resets to defaults rather than leaving the instance with no conf.
+            const { conf: confData } = await CyberiaInstanceConfService.coerceToSchema(
+              await adoptEntityTypeDefaultRefs(fs.readJsonSync(confImportPath), backupDir, CyberiaEntityTypeDefault),
+              CyberiaInstanceConf,
+            );
             if (confData._id) await CyberiaInstanceConf.deleteOne({ _id: confData._id });
             await CyberiaInstanceConf.deleteOne({ instanceCode: confData.instanceCode });
-            // Always bump updatedAt so the Go server's version hash changes and
-            // ReloadWorld re-applies the config without requiring a full restart.
+            // Bump updatedAt so the world version changes and the server
+            // re-applies the config without a restart.
             confData.updatedAt = new Date();
             importedConf = await CyberiaInstanceConf.create(confData);
             logger.info('Imported CyberiaInstanceConf', { instanceCode: confData.instanceCode });
@@ -3062,11 +2636,10 @@ try {
             logger.warn(`CyberiaInstanceConf backup not found: ${confImportPath}`);
           }
 
-          // In --conf mode we must NOT delete + recreate the CyberiaInstance because
-          // that would overwrite cyberiaMapCodes / portals / itemIds with whatever was
-          // in the (possibly stale) backup, effectively removing the live maps and OLs
-          // from the instance.  Only update the conf ref and bump updatedAt so the Go
-          // server's version hash changes and ReloadWorld re-applies the config.
+          // --conf must not recreate the CyberiaInstance: that would overwrite
+          // cyberiaMapCodes, portals and itemIds from a possibly stale backup.
+          // Update the conf ref and bump updatedAt, so the world version changes
+          // and the server re-applies the config.
           if (importedConf) {
             const result = await CyberiaInstance.updateOne(
               { code: instanceCode },
@@ -3130,6 +2703,7 @@ try {
 
         // 3. Import AtlasSpriteSheet
         const atlasDir = `${backupDir}/atlas-sprite-sheets`;
+        const atlasesWithoutMinify = new Set();
         if (fs.existsSync(atlasDir)) {
           const atlasFiles = fs.readdirSync(atlasDir).filter((f) => f.endsWith('.json'));
           let atlasCount = 0;
@@ -3143,6 +2717,22 @@ try {
             atlasCount++;
           }
           logger.info(`Imported ${atlasCount} AtlasSpriteSheet document(s)`);
+          // A backup from before the still existed restores without one; cut each from its render.
+          // An atlas restored without its minified render is rebuilt whole once its object
+          // layer is in place, below.
+          let stillCount = 0;
+          for (const f of atlasFiles) {
+            const atlasData = fs.readJsonSync(`${atlasDir}/${f}`);
+            const itemKey = atlasData.metadata?.itemKey;
+            if (!itemKey) continue;
+            if (!atlasData.minifyFileId) atlasesWithoutMinify.add(itemKey);
+            const { status } = await AtlasSpriteSheetStore.syncIdlePreview({ itemKey, options: { host, path } });
+            if (status === 'updated') stillCount++;
+          }
+          if (stillCount) logger.info(`Filled ${stillCount} idle preview still(s)`);
+          // The replaced atlases took their renders out of reach; the imported ones are
+          // already stored, so what no atlas points at now is exactly the leftover.
+          await AtlasSpriteSheetStore.pruneOrphanRenders({ options: { host, path } });
         }
 
         // 4. Import object layers
@@ -3172,6 +2762,36 @@ try {
           logger.info(`Imported ${olCount} ObjectLayer document(s)`);
         }
 
+        // 4a. An atlas the backup restored without its minified render cannot be served: the
+        //     client runtime pairs the blob with the metadata, so a render cut from the frames
+        //     alone would be refused wherever the stored layout moved. Regenerate the whole
+        //     atlas from the frames the backup carries, and relink the object layer to it the
+        //     way `ol --to-atlas-sprite-sheet` does.
+        for (const itemKey of atlasesWithoutMinify) {
+          try {
+            const objectLayer = await ObjectLayer.findByItemId(itemKey).populate('objectLayerRenderFramesId');
+            if (!objectLayer?.objectLayerRenderFramesId) {
+              logger.warn(`Backup atlas '${itemKey}' has no minified render and no render frames to rebuild it from`);
+              continue;
+            }
+            const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+              itemKey,
+              objectLayerRenderFrames: objectLayer.objectLayerRenderFramesId,
+              options: { host, path },
+            });
+            objectLayer.atlasSpriteSheetId = atlasDoc._id;
+            if (!objectLayer.data.render) objectLayer.data.render = {};
+            objectLayer.data.render.cid = atlasCid;
+            objectLayer.data.render.metadataCid = atlasMetadataCid;
+            objectLayer.markModified('data.render');
+            await objectLayer.save();
+            await ObjectLayerEngine.computeAndSaveFinalSha256({ objectLayer, options: { host, path } });
+            logger.info(`Rebuilt the atlas of '${itemKey}': the backup carried no minified render`);
+          } catch (rebuildError) {
+            logger.error(`Atlas rebuild failed for '${itemKey}': ${rebuildError.message}`);
+          }
+        }
+
         // 4b. Regenerate static frame PNGs from imported render-frames + object-layer documents.
         //     Mirrors the writeStaticFrameAssets call in `ol --import` so src/client/public/cyberia
         //     and the public/<host><path> deployment dir are populated even when the cyberia
@@ -3210,7 +2830,7 @@ try {
                 itemId,
                 objectLayerRenderFramesData,
                 objectLayerData: olData,
-                cellPixelDim: 20,
+                cellPixelDim: DEFAULT_ATLAS_UPSCALE_FACTOR,
               });
               staticWriteCount += written.length;
             } catch (err) {
@@ -3235,12 +2855,69 @@ try {
           logger.info(`Imported ${mapCount} CyberiaMap document(s)`);
         }
 
+        // 5a. Import audio assets, then the map bindings that reference them by code. Assets are
+        //     upserted by code (they are global and may already be present from another import);
+        //     their File documents were restored above with their original _id, so `fileId` still
+        //     resolves. A binding whose asset is absent is kept: the code is the reference, and
+        //     importing the asset later makes it play.
+        const audioAssetsDir = `${backupDir}/cyberia-audio`;
+        if (fs.existsSync(audioAssetsDir)) {
+          const assetFiles = fs.readdirSync(audioAssetsDir).filter((f) => f.endsWith('.json'));
+          let assetCount = 0;
+          let replacedFiles = 0;
+          for (const file of assetFiles) {
+            const assetData = fs.readJsonSync(`${audioAssetsDir}/${file}`);
+            if (!assetData.code) {
+              logger.warn(`Skipping CyberiaAudio backup without code: ${file}`);
+              continue;
+            }
+            // The asset this restore supersedes may hold different bytes under a different
+            // fileId. Replacing the document without dropping that blob leaves it referenced by
+            // nothing — an orphan `db clean-fs` would later have to sweep.
+            const superseded = await CyberiaAudio.find({
+              $or: [{ code: assetData.code }, ...(assetData._id ? [{ _id: assetData._id }] : [])],
+            }).lean();
+            await CyberiaAudio.deleteOne({ code: assetData.code });
+            if (assetData._id) await CyberiaAudio.deleteOne({ _id: assetData._id });
+            await CyberiaAudio.create(assetData);
+            for (const old of superseded) {
+              if (!old.fileId || String(old.fileId) === String(assetData.fileId)) continue;
+              if (await File.findByIdAndDelete(old.fileId)) replacedFiles++;
+            }
+            assetCount++;
+          }
+          logger.info(`Imported ${assetCount} CyberiaAudio document(s)`, {
+            ...(replacedFiles > 0 ? { replacedFiles } : {}),
+          });
+        }
+
+        const audioConfsDir = `${backupDir}/cyberia-map-audio-confs`;
+        if (fs.existsSync(audioConfsDir)) {
+          const confFiles = fs.readdirSync(audioConfsDir).filter((f) => f.endsWith('.json'));
+          let audioConfCount = 0;
+          for (const file of confFiles) {
+            const confData = fs.readJsonSync(`${audioConfsDir}/${file}`);
+            if (!confData.mapCode) {
+              logger.warn(`Skipping CyberiaMapAudioConf backup without mapCode: ${file}`);
+              continue;
+            }
+            await CyberiaMapAudioConf.deleteOne({ mapCode: confData.mapCode });
+            if (confData._id) await CyberiaMapAudioConf.deleteOne({ _id: confData._id });
+            await CyberiaMapAudioConf.create(confData);
+            audioConfCount++;
+          }
+          logger.info(`Imported ${audioConfCount} CyberiaMapAudioConf document(s)`);
+        }
+
         // 6. Import CyberiaInstanceConf (skillRules, equipmentRules, entityDefaults, etc.)
         const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
         if (fs.existsSync(confImportPath)) {
-          // Backfill any missing schema fields so older backups import a
-          // complete, playable config into the DB.
-          const confData = fillInstanceConfDefaults(fs.readJsonSync(confImportPath));
+          // Made whole and valid before the live conf is touched, so a backup the schema
+          // rejects resets to defaults rather than leaving the instance with no conf.
+          const { conf: confData } = await CyberiaInstanceConfService.coerceToSchema(
+            await adoptEntityTypeDefaultRefs(fs.readJsonSync(confImportPath), backupDir, CyberiaEntityTypeDefault),
+            CyberiaInstanceConf,
+          );
           if (confData._id) await CyberiaInstanceConf.deleteOne({ _id: confData._id });
           await CyberiaInstanceConf.deleteOne({ instanceCode: confData.instanceCode });
           await CyberiaInstanceConf.create(confData);
@@ -3253,13 +2930,6 @@ try {
         const instancePath = `${backupDir}/cyberia-instance.json`;
         if (fs.existsSync(instancePath)) {
           const instanceData = fs.readJsonSync(instancePath);
-          // Heal legacy shapes against the current model. itemIds migrated from a
-          // flat string[] to [{ id, defaultPlayerInventory }] — a raw old backup
-          // would fail Mongoose embedded-cast validation, so normalize it here.
-          instanceData.itemIds = (instanceData.itemIds || [])
-            .map((entry) => (typeof entry === 'string' ? { id: entry, defaultPlayerInventory: false } : entry))
-            .filter((entry) => entry && entry.id);
-          for (const entry of instanceData.itemIds) importedItemIds.add(entry.id);
           await CyberiaInstance.deleteOne({ code: instanceCode });
           await CyberiaInstance.deleteOne({ _id: instanceData._id });
           await CyberiaInstance.create(instanceData);
@@ -3354,29 +3024,32 @@ try {
           logger.info(`Imported ${skillCount} CyberiaSkill document(s)`);
         }
 
-        // 8d-bis. Import CyberiaEntityTypeDefault documents (own model, overwrite
-        //     by the natural (entityType, liveItemIds) key, then by _id).
+        // 8d-bis. Import CyberiaEntityTypeDefault documents by _id (preserveUUID), which is how
+        //     the conf's references keep resolving after a restore. Only the documents this
+        //     backup carries are touched: overwriting by an (entityType, liveItemIds) "natural
+        //     key" clobbered another instance's document whenever two worlds shared a skin.
         const entityDefaultsDir = `${backupDir}/cyberia-entity-type-defaults`;
         if (fs.existsSync(entityDefaultsDir)) {
           const entityDefaultFiles = fs.readdirSync(entityDefaultsDir).filter((f) => f.endsWith('.json'));
           let entityDefaultCount = 0;
           for (const file of entityDefaultFiles) {
             const edData = fs.readJsonSync(`${entityDefaultsDir}/${file}`);
-            if (!edData.entityType) {
-              logger.warn(`Skipping CyberiaEntityTypeDefault backup without entityType: ${file}`);
+            if (!edData.entityType || !edData._id) {
+              logger.warn(`Skipping CyberiaEntityTypeDefault backup without entityType or _id: ${file}`);
               continue;
             }
-            await CyberiaEntityTypeDefault.deleteMany({
-              entityType: edData.entityType,
-              liveItemIds: edData.liveItemIds || [],
-            });
-            if (edData._id) await CyberiaEntityTypeDefault.deleteOne({ _id: edData._id });
+            await CyberiaEntityTypeDefault.deleteOne({ _id: edData._id });
             await CyberiaEntityTypeDefault.create(edData);
             entityDefaultCount++;
           }
           logger.info(`Imported ${entityDefaultCount} CyberiaEntityTypeDefault document(s)`);
         }
 
+        // A conf can reference a default this backup does not carry — an older backup, or one
+        // exported before the reference existed. Restoring that reference would recreate the
+        // orphan the export just removed, so the restored conf is compacted too.
+        await CyberiaEntityTypeDefaultService.compactInstanceRefs({ host, path }, { instanceCode });
+
         // 8e. Backfill missing skills from the canonical DefaultSkillConfig. Old
         //     backups predate the CyberiaSkill model and ship no skills/ dir, so
         //     any instance item that has a canonical skill (e.g. atlas_pistol_mk2,
@@ -3693,30 +3366,17 @@ try {
           // Query other instances for shared thumbnail exclusion
           const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
 
-          // Add instance-level itemIds (may not appear in any map entity)
-          for (const entry of existingInstance.itemIds || []) {
-            const id = typeof entry === 'string' ? entry : entry?.id;
-            if (id) dropOlItemIds.add(id);
-          }
-
-          // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
+          // Add the item ids the conf's referenced entity-type defaults name.
           const existingConf =
             (await CyberiaInstanceConf.findOne({ instanceCode }).lean()) ||
             (existingInstance.conf ? await CyberiaInstanceConf.findById(existingInstance.conf).lean() : null);
           if (existingConf) {
-            for (const ed of existingConf.entityDefaults || []) {
-              for (const id of ed.liveItemIds || []) if (id) dropOlItemIds.add(id);
-              for (const id of ed.deadItemIds || []) if (id) dropOlItemIds.add(id);
-              for (const id of ed.dropItemIds || []) if (id) dropOlItemIds.add(id);
-              for (const slot of ed.defaultObjectLayers || []) if (slot.itemId) dropOlItemIds.add(slot.itemId);
-            }
-            for (const sc of existingConf.skillConfig || []) {
-              if (sc.triggerItemId) dropOlItemIds.add(sc.triggerItemId);
-              for (const skill of sc.skills || []) {
-                if (skill.summonedEntityItemId && !skill.summonedEntityItemId.startsWith('$'))
-                  dropOlItemIds.add(skill.summonedEntityItemId);
-              }
-            }
+            // The conf names its entity-type defaults by _id; read the documents to reach their items.
+            const referencedIds = (existingConf.entityDefaults || []).map((id) => String(id?._id ?? id));
+            const referenced = referencedIds.length
+              ? await CyberiaEntityTypeDefault.find({ _id: { $in: referencedIds } }).lean()
+              : [];
+            for (const itemId of collectInstanceItemIds({ entityDefaults: referenced })) dropOlItemIds.add(itemId);
           }
 
           const otherMaps = await CyberiaMap.find(
@@ -3737,6 +3397,20 @@ try {
             }
             const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
             logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap document(s)`);
+
+            // A map's audio configuration belongs to that map; the shared assets it bound do not.
+            const audioConfResult = await CyberiaMapAudioConf.deleteMany({ mapCode: { $in: [...dropMapCodes] } });
+            if (audioConfResult.deletedCount > 0)
+              logger.info(`Dropped ${audioConfResult.deletedCount} CyberiaMapAudioConf document(s)`);
+          }
+
+          // A conf stores no skills: the ones this instance ran are the ones its own items trigger.
+          // What those summon is drawn by this instance alone, so it joins the drop surface and is
+          // then protected by the same shared-with-another-map check as everything else.
+          for (const itemId of collectSummonedItemIds(
+            selectInstanceSkills(await CyberiaSkill.find({}).lean(), dropOlItemIds),
+          )) {
+            dropOlItemIds.add(itemId);
           }
 
           // Exclude OL item IDs referenced by maps outside this instance
@@ -3793,18 +3467,15 @@ try {
               if (doc.atlasSpriteSheetId) atlasIds.push(doc.atlasSpriteSheetId);
             }
 
-            if (atlasIds.length > 0) {
-              const atlasDocs = await AtlasSpriteSheet.find({ _id: { $in: atlasIds } }, { fileId: 1, cid: 1 }).lean();
-              const atlasFileIds = atlasDocs.map((a) => a.fileId).filter(Boolean);
-              for (const atlas of atlasDocs) {
-                if (atlas.cid) cidsToUnpin.add(atlas.cid);
-              }
-              if (atlasFileIds.length > 0) {
-                const fileResult = await File.deleteMany({ _id: { $in: atlasFileIds } });
-                logger.info(`Dropped ${fileResult.deletedCount} File document(s) (atlas)`);
-              }
-              const atlasResult = await AtlasSpriteSheet.deleteMany({ _id: { $in: atlasIds } });
-              logger.info(`Dropped ${atlasResult.deletedCount} AtlasSpriteSheet document(s)`);
+            if (atlasIds.length > 0 || itemKeysToClean.size > 0) {
+              const purged = await AtlasSpriteSheetStore.purge({
+                itemKeys: [...itemKeysToClean],
+                atlasIds,
+                options: { host, path },
+              });
+              for (const cid of purged.cids) cidsToUnpin.add(cid);
+              if (purged.files > 0) logger.info(`Dropped ${purged.files} File document(s) (atlas)`);
+              if (purged.atlases > 0) logger.info(`Dropped ${purged.atlases} AtlasSpriteSheet document(s)`);
             }
 
             if (renderFrameIds.length > 0) {
@@ -3956,6 +3627,130 @@ try {
       }
     });
 
+  const runAudioCommand = async (audioCode, options = {}) => {
+    const assignments = {
+      ...(options.setDefaultMusic === undefined ? {} : { defaultMusic: options.setDefaultMusic }),
+      events: options.setEvent ?? [],
+    };
+    const configuring = assignments.defaultMusic !== undefined || assignments.events.length > 0;
+
+    if (configuring && !options.map) {
+      logger.error('--map <map-code> is required to apply --set-default-music/--set-event');
+      process.exit(1);
+    }
+    if (!options.import && !options.map) {
+      logger.error('Nothing to do: pass --import, or --map <map-code> to read or configure a map');
+      process.exit(1);
+    }
+
+    if (options.envPath && !fs.existsSync(options.envPath)) {
+      logger.error(`Env file not found: ${options.envPath}`);
+      process.exit(1);
+    }
+    const envPath =
+      options.envPath || `./engine-private/conf/dd-cyberia/.env.${options.dev ? 'development' : 'production'}`;
+    if (fs.existsSync(envPath)) dotenv.config({ path: envPath, override: true });
+
+    const deployId = process.env.DEFAULT_DEPLOY_ID;
+    const host = process.env.DEFAULT_DEPLOY_HOST;
+    const path = process.env.DEFAULT_DEPLOY_PATH;
+    const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+    if (!fs.existsSync(confServerPath)) {
+      logger.error(`Server config not found: ${confServerPath}. Ensure DEFAULT_DEPLOY_ID is set.`);
+      process.exit(1);
+    }
+    const confServer = loadConfServerJson(confServerPath, { resolve: true });
+    const { db } = confServer[host][path];
+    db.host = options.mongoHost
+      ? options.mongoHost
+      : options.dev
+        ? db.host
+        : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
+
+    logger.info('env', { env: envPath, deployId, host, path });
+
+    await DataBaseProviderService.load({
+      apis: ['cyberia-audio', 'cyberia-instance', 'cyberia-map', 'cyberia-map-audio-conf', 'file'],
+      host,
+      path,
+      db,
+    });
+
+    try {
+      if (options.seedWorld) {
+        // An instance names its own maps, in its own order; without one the fallback world is the
+        // world being scored. Either way the bank and the rotation are the same.
+        const result = options.instance
+          ? await seedInstanceAudio(
+              { instanceCode: options.instance, recordsPath: options.recordsPath },
+              { host, path },
+            )
+          : await seedFallbackAudio({ recordsPath: options.recordsPath }, { host, path });
+        logger.info(
+          `seed-audio${options.instance ? ` --instance ${options.instance}` : ''}: ` +
+            `${result.assets.length} assets, ${result.maps.length} maps`,
+        );
+      } else if (options.import) {
+        const recordsPath = options.recordsPath || DEFAULT_AUDIO_RECORDS_PATH;
+        const codes = audioCode
+          ? audioCode
+              .split(',')
+              .map((code) => code.trim())
+              .filter(Boolean)
+          : null;
+        const imported = await CyberiaAudioService.importRecords({ recordsPath, codes }, { host, path });
+        logger.info(`audio --import: imported ${imported.length} asset(s) from ${recordsPath}`);
+      }
+
+      if (options.map) {
+        /** @type {import('mongoose').Model} */
+        const CyberiaMap = DataBaseProviderService.getModel('cyberia-map', { host, path });
+        if (!(await CyberiaMap.exists({ code: options.map }))) {
+          throw new Error(`cyberia-map not found for code="${options.map}"`);
+        }
+
+        if (configuring) {
+          const conf = await CyberiaMapAudioConfService.assign(
+            { mapCode: options.map, ...assignments },
+            { host, path },
+          );
+          logger.info(`audio --map: updated audio configuration for "${options.map}"`, {
+            defaultMusic: conf.defaultMusic || null,
+            events: conf.events.map(({ logicEventId, audioCode: code }) => `${logicEventId}:${code}`),
+          });
+        } else {
+          const conf = await CyberiaMapAudioConfService.getByMapCode(options.map, { host, path });
+          if (!conf) logger.warn(`No audio configuration for map "${options.map}"`);
+          else console.log(JSON.stringify(conf, null, 2));
+        }
+      }
+    } finally {
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+    }
+  };
+
+  // ── audio: import cyberia-audio assets and configure per-map audio ──
+  program
+    .command('audio [audio-code]')
+    .option('--import', 'Import <name>.wav + <name>.json pairs into MongoDB (all pairs when no id is given)')
+    .option(
+      '--records-path <records-path>',
+      `Records directory to import from (default: ${DEFAULT_AUDIO_RECORDS_PATH})`,
+    )
+    .option('--map <map-code>', 'Target cyberia-map code to read or configure')
+    .option('--set-default-music <audio-code>', 'Set the default background music of --map')
+    .option(
+      '--set-event <logic-event-id:audio-code>',
+      'Bind an audio asset to a logic event e.g. combat:combat or shoot:shoot, repeatable',
+      eventAudioBindingFactory('--set-event'),
+      [],
+    )
+    .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
+    .option('--mongo-host <mongo-host>', 'Mongo host override')
+    .option('--dev', 'Force development environment')
+    .description('Import cyberia-audio assets into MongoDB and configure cyberia-map audio')
+    .action(runAudioCommand);
+
   // ── generate-saga: Top-Down PCG guided by LLMs (Semantic Reverse-Engineering) ──
   program
     .command('generate-saga')
@@ -3965,7 +3760,7 @@ try {
     )
     .option('--import <file>', 'Load a previously generated payload file (the shape --out writes) into the database')
     .option('--model <model>', 'Gemini model id (default: gemma-4-26b-a4b-it)')
-    .option('--timeout <ms>', 'Per-request timeout in ms (default: 300000)', (v) => parseInt(v, 10))
+    .option('--timeout <ms>', 'Per-request timeout in ms (default: 10000)', (v) => parseInt(v, 10))
     .option('--thinking-level <level>', 'Gemini thinking level: low | medium | high (default: high)')
     .option(
       '--lore-path <path>',
@@ -4921,6 +4716,26 @@ try {
 
   const runner = program.command('run-workflow').description('Run a Cyberia script from the "scripts" directory');
 
+  runner
+    .command('seed-audio')
+    .option('--records-path <path>', 'Recorded WAV and manifest directory', DEFAULT_AUDIO_RECORDS_PATH)
+    .option('--records-only', 'Record the WAV and manifest pairs without touching the database')
+    .option(
+      '--instance <instance-code>',
+      "Configure that instance's maps instead of the fallback world's, in its own cyberiaMapCodes order",
+    )
+    .option('--env-path <path>', 'Engine environment file')
+    .option('--mongo-host <host>', 'Mongo host override')
+    .option('--dev', 'Use the development environment')
+    .description("Record audio, upsert generic files and audio metadata, and configure a world's maps")
+    .action(async (options) => {
+      // Recording writes only `records/`: the client bundles no audio and fetches every asset
+      // from engine-cyberia by code, so seeding the database is what makes a recording reachable.
+      await prepareFallbackAudio({ recordsPath: options.recordsPath ?? DEFAULT_AUDIO_RECORDS_PATH });
+      if (!options.recordsOnly) await runAudioCommand(undefined, { ...options, import: true, seedWorld: true });
+      logger.info('seed-audio complete');
+    });
+
   runner
     .command('import-default-items')
     .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
@@ -4976,15 +4791,51 @@ try {
     .description('Packs this engine checkout as underpost-cli.tgz for a runtime image build context')
     .action((options) => stageCliPackage(options.outputPath || '.'));
 
-  runner.command('sync-src').action(() => {
-    fs.copyFileSync('./cyberia-server/README.md', './src/client/public/cyberia-docs/CYBERIA-SERVER.md');
-    fs.copyFileSync('./cyberia-server/Dockerfile', './src/runtime/cyberia-server/Dockerfile');
-    fs.copyFileSync('./cyberia-client/README.md', './src/client/public/cyberia-docs/CYBERIA-CLIENT.md');
-    fs.copyFileSync('./cyberia-client/Dockerfile', './src/runtime/cyberia-client/Dockerfile');
-  });
+  // Every file mirrored between this engine and a product checkout, engine path first. One
+  // table for both directions, so a pair cannot be synced one way and forgotten the other.
+  const cyberiaSrcSyncPairs = [
+    ['./src/client/public/cyberia-docs/CYBERIA-SERVER.md', './cyberia-server/README.md'],
+    ['./src/runtime/cyberia-server/Dockerfile', './cyberia-server/Dockerfile'],
+    ['./src/runtime/cyberia-server/Dockerfile.dev', './cyberia-server/Dockerfile.dev'],
+    ['./src/client/public/cyberia-docs/CYBERIA-CLIENT.md', './cyberia-client/README.md'],
+    ['./src/runtime/cyberia-client/Dockerfile', './cyberia-client/Dockerfile'],
+    ['./src/runtime/cyberia-client/Dockerfile.dev', './cyberia-client/Dockerfile.dev'],
+  ];
+
+  runner
+    .command('sync-src')
+    .option('--from-repo', 'Copy from the product checkouts into this engine instead of out to them')
+    .option('--dry-run', 'Report what would be copied without writing it')
+    .description(
+      'Mirrors the cyberia product READMEs and runtime Dockerfiles between this engine and the product checkouts',
+    )
+    .action((options) => {
+      const fromRepo = options.fromRepo === true;
+      const dryRun = options.dryRun === true;
+      const copied = [];
+      const missing = [];
+
+      for (const [enginePath, repoPath] of cyberiaSrcSyncPairs) {
+        const [source, target] = fromRepo ? [repoPath, enginePath] : [enginePath, repoPath];
+        // A product checkout `setup-workspace` has not cloned yet must not leave the run
+        // half applied, so a missing source is reported rather than thrown on.
+        if (!fs.existsSync(source)) {
+          missing.push(source);
+          continue;
+        }
+        if (!dryRun) fs.copySync(source, target);
+        copied.push(`${source} -> ${target}`);
+      }
+
+      logger.info(`Cyberia sources synced ${fromRepo ? 'from' : 'to'} the product checkouts`, {
+        copied,
+        missing,
+        dryRun,
+      });
+    });
 
   runner.command('setup-workspace').action(() => {
-    shellExec(`node bin fs src/client/public/cyberia --git --recursive --pull --deploy-id dd-cyberia`);
+    shellExec(`node bin fs src/client/public/cyberia --tracked --pull --deploy-id dd-cyberia`);
     shellExec(`node bin/deploy.js cyberia`);
     if (!fs.existsSync('./cyberia-server')) shellExec(`${cli()} clone underpostnet/cyberia-server`);
     if (!fs.existsSync('./cyberia-client')) shellExec(`${cli()} clone underpostnet/cyberia-client`);
@@ -5096,7 +4947,7 @@ try {
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
     .option('--mongo-host <mongo-host>', 'Mongo host override')
     .option('--dev', 'Force development environment')
-    .description('Drop all Cyberia collections and remove File documents referenced by instance/map thumbnails')
+    .description('Drop all Cyberia collections and remove the File documents they reference')
     .action(async (options = {}) => {
       if (!options.envPath) options.envPath = `./.env`;
       if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
@@ -5139,30 +4990,37 @@ try {
         'cyberia-entity-type-default',
         'cyberia-client-hints',
         'cyberia-saga',
+        'cyberia-audio',
+        'cyberia-map-audio-conf',
       ];
 
+      // Every File _id a Cyberia document owns: instance and map thumbnails and previews, and the
+      // recorded WAV each audio asset points at. Read from the registry that maps a model to its
+      // File fields, so a reference added there is dropped here without editing this command, and
+      // read before anything is dropped, so no backing File survives the collection that held it.
+      const fileReferences = cyberiaCollections
+        .map((api) => ({ api, fields: fileRefFields(api) }))
+        .filter(({ fields }) => fields.length > 0);
+
       await DataBaseProviderService.load({ apis: [...cyberiaCollections, 'file'], host, path, db });
 
       const File = DataBaseProviderService.getModel('file', { host, path });
 
-      // Thumbnails/previews on instances/maps are File _id references; collect
-      // them before dropping so the backing File documents don't leak as orphans.
-      const thumbnailFileIds = new Set();
-      for (const api of ['cyberia-instance', 'cyberia-map']) {
+      const fileIds = new Set();
+      for (const { api, fields } of fileReferences) {
         const Model = DataBaseProviderService.getModel(api, { host, path });
         const docs = await Model.find(
-          { $or: [{ thumbnail: { $ne: null } }, { preview: { $ne: null } }] },
-          { thumbnail: 1, preview: 1 },
+          { $or: fields.map((field) => ({ [field]: { $ne: null } })) },
+          Object.fromEntries(fields.map((field) => [field, 1])),
         ).lean();
         for (const doc of docs) {
-          if (doc.thumbnail) thumbnailFileIds.add(doc.thumbnail.toString());
-          if (doc.preview) thumbnailFileIds.add(doc.preview.toString());
+          for (const field of fields) if (doc[field]) fileIds.add(doc[field].toString());
         }
       }
 
-      if (thumbnailFileIds.size > 0) {
-        const result = await File.deleteMany({ _id: { $in: [...thumbnailFileIds] } });
-        logger.info(`Removed ${result.deletedCount} thumbnail File document(s)`);
+      if (fileIds.size > 0) {
+        const result = await File.deleteMany({ _id: { $in: [...fileIds] } });
+        logger.info(`Removed ${result.deletedCount} referenced File document(s)`);
       }
 
       for (const api of cyberiaCollections) {
@@ -5242,7 +5100,7 @@ node bin test cyberia --grep 'Cyberia load'`);
       // no funca
       if (options.loadTar) {
         for (const imageId of dockerImageIds)
-          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.3.73.tar`);
+          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.3.76.tar`);
         return;
       }
       switch (id) {
@@ -5254,7 +5112,7 @@ node bin/build dd-cyberia --update-private
 node bin image --path src/runtime/engine-cyberia \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name engine-cyberia-dev:v3.3.73 \
+  --image-name engine-cyberia-dev:v3.3.76 \
   --image-out-path .
 `);
           break;
@@ -5266,7 +5124,7 @@ cp -f src/runtime/cyberia-server/Dockerfile.dev cyberia-server/Dockerfile.dev
 node bin image --path cyberia-server \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-server-dev:v3.3.73 \
+  --image-name cyberia-server-dev:v3.3.76 \
   --image-out-path .
 `);
           break;
@@ -5277,7 +5135,7 @@ cp -f src/runtime/cyberia-client/Dockerfile.dev cyberia-client/Dockerfile.dev
 node bin image --path cyberia-client \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-client-dev:v3.3.73 \
+  --image-name cyberia-client-dev:v3.3.76 \
   --image-out-path .
 `);
           break;
@@ -5443,9 +5301,9 @@ node bin image --path cyberia-client \
 
       const CyberiaSkill = DataBaseProviderService.getModel('cyberia-skill', { host, path });
 
-      // Upsert each skill record keyed by triggerItemId — full record (logic
-      // event keys + expanded skills metadata), unlike the instance-conf
-      // skillConfig schema which keeps only triggerItemId + logicEventIds.
+      // Upsert each skill record keyed by triggerItemId — the full record (logic event keys +
+      // expanded skills metadata). The collection is deployment-wide; an instance runs the
+      // subset its own content triggers, decided at export and boot, never stored.
       let upserted = 0;
       for (const sk of DefaultSkillConfig) {
         await CyberiaSkill.findOneAndUpdate(
@@ -5468,6 +5326,10 @@ node bin image --path cyberia-client \
     .command('seed-entities')
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
     .option('--mongo-host <mongo-host>', 'Mongo host override')
+    .option(
+      '--instance <instance-code>',
+      "Point that instance's conf at the seeded documents, replacing whatever it referenced",
+    )
     .option('--dev', 'Force development environment')
     .description('Upsert ENTITY_TYPE_DEFAULTS into the cyberia-entity-type-default collection (idempotent)')
     .action(async (options) => {
@@ -5499,7 +5361,12 @@ node bin image --path cyberia-client \
 
       logger.info('seed-entities', { deployId, host, path });
 
-      await DataBaseProviderService.load({ apis: ['cyberia-entity-type-default'], host, path, db });
+      await DataBaseProviderService.load({
+        apis: ['cyberia-entity-type-default', 'cyberia-instance-conf'],
+        host,
+        path,
+        db,
+      });
 
       const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('cyberia-entity-type-default', { host, path });
 
@@ -5518,8 +5385,9 @@ node bin image --path cyberia-client \
       // (across entity types, or within one type at different specificity). Every
       // entry is upserted, idempotently, by its exact (entityType, liveItemIds) key.
       let upserted = 0;
+      const seededIds = [];
       for (const ed of ENTITY_TYPE_DEFAULTS) {
-        await CyberiaEntityTypeDefault.findOneAndUpdate(
+        const doc = await CyberiaEntityTypeDefault.findOneAndUpdate(
           { entityType: ed.entityType, liveItemIds: ed.liveItemIds || [] },
           {
             $set: {
@@ -5527,12 +5395,14 @@ node bin image --path cyberia-client \
               liveItemIds: ed.liveItemIds || [],
               deadItemIds: ed.deadItemIds || [],
               dropItemIds: ed.dropItemIds || [],
-              defaultObjectLayers: ed.defaultObjectLayers || [],
+              inventoryItemsIds: ed.inventoryItemsIds || [],
+              overrideItemsIdsState: ed.overrideItemsIdsState || [],
               behavior: ed.behavior || '',
             },
           },
-          { upsert: true },
+          { upsert: true, returnDocument: 'after' },
         );
+        if (doc?._id) seededIds.push(doc._id);
         upserted++;
       }
 
@@ -5541,6 +5411,23 @@ node bin image --path cyberia-client \
         ENTITY_TYPE_DEFAULTS.map((e) => `${e.entityType} → [${(e.liveItemIds || []).join(', ')}]`),
       );
 
+      // A seeded document reaches a world only when that world's conf names it. Binding here is
+      // what makes an edited row take effect, and it states the whole reference set so re-running
+      // converges instead of accumulating.
+      if (options.instance) {
+        const CyberiaInstanceConf = DataBaseProviderService.getModel('cyberia-instance-conf', { host, path });
+        const conf = await CyberiaInstanceConf.findOneAndUpdate(
+          { instanceCode: options.instance },
+          { $set: { entityDefaults: seededIds, updatedAt: new Date() } },
+          { returnDocument: 'after' },
+        );
+        if (!conf) {
+          logger.error(`cyberia-instance-conf not found for instanceCode="${options.instance}"`);
+          process.exit(1);
+        }
+        logger.info(`seed-entities --instance ${options.instance}: ${seededIds.length} reference(s) bound`);
+      }
+
       await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
     });
 
@@ -5564,26 +5451,6 @@ node bin image --path cyberia-client \
         'skin-vivid',
         'skin-natural',
         'skin-shaved',
-        // 'resource-desert-petal',
-        // 'resource-desert-stone',
-        // 'resource-desert-polygon',
-        // 'resource-desert-thread',
-        // 'resource-grass-petal',
-        // 'resource-grass-stone',
-        // 'resource-grass-polygon',
-        // 'resource-grass-thread',
-        // 'resource-water-petal',
-        // 'resource-water-stone',
-        // 'resource-water-polygon',
-        // 'resource-water-thread',
-        // 'resource-stone-petal',
-        // 'resource-stone-stone',
-        // 'resource-stone-polygon',
-        // 'resource-stone-thread',
-        // 'resource-lava-petal',
-        // 'resource-lava-stone',
-        // 'resource-lava-polygon',
-        // 'resource-lava-thread',
       ];
 
       const baseSeed = options.seed || 'example';
@@ -5608,10 +5475,10 @@ node bin image --path cyberia-client \
   // Instance id → project root. Single source of truth for the workloads this
   // workflow builds: both the k8s manifests and the status page artifacts each
   // project ships are resolved from this list plus conf.instances.json.
-  const CYBERIA_INSTANCE_PROJECTS = [
-    { id: 'mmo-client', rootPath: './cyberia-client' },
-    { id: 'mmo-server', rootPath: './cyberia-server' },
-  ];
+  // The template instances this deploy builds artifacts for. Where each one publishes is not
+  // listed here: instanceProjectPathFactory reads it off the conf entry, the same rule
+  // instance-build-manifest applies, so the two can never name different checkouts.
+  const CYBERIA_INSTANCE_IDS = ['mmo-client', 'mmo-server'];
   const CYBERIA_CONF_INSTANCES_PATH = './engine-private/conf/dd-cyberia/conf.instances.json';
   const CYBERIA_CONF_SSR_PATH = './engine-private/conf/dd-cyberia/conf.ssr.json';
   // Copy shared by the server and the client for a given status code. A status
@@ -5704,10 +5571,9 @@ node bin image --path cyberia-client \
       const nodeFlag = options.nodeName ? ` --node-name ${options.nodeName}` : '';
 
       // ── Dynamically resolve instance codes from conf.instances.json ──────
-      // Read all cyberia-server runtime instances and collect their
-      // multiInstance variant codes. These are used to update the
-      // INSTANCE_CODES label in Dockerfile.dev so the dev image
-      // provisions every variant's backup dir and saga at build time.
+      // Collect the multiInstance variant codes of every game-server runtime
+      // instance. They set the INSTANCE_CODES label in Dockerfile.dev, so the
+      // dev image provisions each variant's backup dir and saga at build time.
       //
       // Only codes that have an on-disk instance backup directory are
       // included. The saga file is optional — the Dockerfile's for loop
@@ -5769,14 +5635,12 @@ node bin image --path cyberia-client \
       }
 
       // ── Update catalog-cyberia.js privateConfPaths ───────────────────────
-      // The array block in privateConfPaths is bounded by /** INSTANCE_CODES */
-      // markers (valid JS comments here). Replace everything between them with
-      // the resolved per-code paths. These are synced by syncPrivateConf, which
-      // copies each entry from `./engine-private/<path>` — so they must match the
-      // LOCAL engine-private layout (`cyberia-instances/<code>`,
-      // `cyberia-sagas/<code>.json`), not the published cyberia-instances repo
-      // (which uses `instances/` + `sagas/`). Only emit paths that exist on disk
-      // so the sync never hits ENOENT on a variant without local content.
+      // The privateConfPaths array block sits between the /** INSTANCE_CODES */
+      // markers. Replace its content with the resolved per-code paths.
+      // syncPrivateConf copies each entry from `./engine-private/<path>`, so the
+      // paths follow the local engine-private layout (`cyberia-instances/<code>`,
+      // `cyberia-sagas/<code>.json`). Emit only paths that exist on disk, so the
+      // sync never hits ENOENT for a variant without local content.
       const catalogPath = './src/projects/cyberia/catalog-cyberia.js';
       try {
         const catalogContent = fs.readFileSync(catalogPath, 'utf8');
@@ -5809,11 +5673,11 @@ node bin image --path cyberia-client \
       // embed each document declared under an instance's `customStatusPages`,
       // so the artifact has to exist at its `hostPath` by manifest time.
       const statusPagesBuilt = [];
-      for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS) {
+      for (const id of CYBERIA_INSTANCE_IDS) {
         const instance = confInstancesEntries.find((entry) => entry.id === id);
         for (const page of instance?.customStatusPages || []) {
           if (!page?.status || !page?.hostPath) continue;
-          const outputPath = nodePath.normalize(`${rootPath}/${page.hostPath}`);
+          const outputPath = nodePath.normalize(`${instanceProjectPathFactory(instance)}/${page.hostPath}`);
           if (buildCyberiaStatusPage({ status: page.status, outputPath, dev: isDev }))
             statusPagesBuilt.push({ instance: id, status: page.status, outputPath });
         }
@@ -5826,23 +5690,22 @@ node bin image --path cyberia-client \
       // ── Build dev manifests (always --kind --dev) ────────────────────────
       {
         const flags = `--kind --dev${nodeFlag}`;
-        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
-          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
+        for (const id of CYBERIA_INSTANCE_IDS)
+          shellExec(`node bin run instance-build-manifest --deploy-id dd-cyberia --instance-id ${id} ${flags}`);
       }
       // ── Build prod manifests (--kubeadm, no --dev) ───────────────────────
       if (!isDev) {
         const flags = `--kubeadm${nodeFlag}`;
-        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
-          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
+        for (const id of CYBERIA_INSTANCE_IDS)
+          shellExec(`node bin run instance-build-manifest --deploy-id dd-cyberia --instance-id ${id} ${flags}`);
       }
 
       // Copy canonical doc sources into the generated project READMEs.
       // Edit the canonical sources; never hand-edit these generated outputs.
-      // The mirrored deploy tree is a generated artifact, rebuilt from scratch so a file
-      // dropped or renamed upstream cannot linger in the published repo. It reproduces the
-      // engine layout exactly — the <deploy-id> directory beside lib/ — because every deploy
-      // script sources `$SCRIPT_DIR/../lib/logging.sh`, which only resolves when lib/ is the
-      // script directory's sibling there too.
+      // The mirrored deploy tree is generated, and rebuilt from scratch so a file
+      // renamed upstream cannot linger. It keeps the engine layout, the
+      // <deploy-id> directory beside lib/, because every deploy script sources
+      // `$SCRIPT_DIR/../lib/logging.sh`.
       for (const project of ['cyberia-client', 'cyberia-server']) {
         const scripts = `./deploy/${project}`;
         // A tree assembled before these scripts were packaged does not carry them; mirroring is
@@ -5866,9 +5729,8 @@ node bin image --path cyberia-client \
         './cyberia-server/.github/workflows/cyberia-server.cd.yml',
       );
       shellExec('cp -a ./engine-private/conf/dd-cyberia/docker-compose/cyberia/. ./src/runtime/engine-cyberia/');
-      // The publish is scoped to the deployment this workflow builds — every other step here is —
-      // so it reads dd-cyberia's own environment instead of the working-tree `./.env`, which names
-      // whichever deployment `app load` ran for last.
+      // Scope the publish to the deployment this workflow builds: read
+      // dd-cyberia's own environment, not the working-tree `./.env`.
       shellExec(
         `node bin/cyberia.js instance --publish-build --env-path ${deployEnvFilePath(
           'dd-cyberia',
@@ -5885,6 +5747,7 @@ node bin image --path cyberia-client \
       if (options.dryRun) {
         shellExec('node bin cmt --log --unpush cyberia-server');
         shellExec('node bin cmt --log --unpush cyberia-client');
+        shellExec('node bin cmt --log --unpush cyberia-audio');
         shellExec('node bin cmt --log --unpush');
         shellExec('node bin cmt --log --unpush ../cyberia-instances');
       } else {
@@ -5897,6 +5760,9 @@ node bin image --path cyberia-client \
         shellExec('node bin push cyberia-client underpostnet/cyberia-client', {
           silentOnError: true,
         });
+        shellExec('node bin push cyberia-audio underpostnet/cyberia-audio', {
+          silentOnError: true,
+        });
         shellExec('node bin run template-deploy', {
           silentOnError: true,
         });
@@ -5995,15 +5861,23 @@ node bin image --path cyberia-client \
 
   await program.parseAsync();
 } catch (error) {
-  // ONLY reroute on the explicit passthrough sentinel. Any other thrown
-  // error (subprocess non-zero from shellExec's fail-fast default, CLI
-  // parse errors, missing modules) must propagate as a non-zero process
-  // exit so GitHub Actions / CI parents observe the failure. Without this
-  // guard, a genuine build failure was being silently rerouted into the
-  // underpost CLI and then masked behind a misleading "unknown command"
-  // line.
+  // Reroute only on the passthrough sentinel. Every other error — a non-zero
+  // subprocess, a CLI parse error, a missing module — must exit non-zero, so a
+  // CI parent sees the failure.
   if (error && error.message === 'Trigger underpost passthrough') {
-    process.argv = process.argv.filter((c) => c !== 'underpost');
+    // A redundant CLI name can only appear before the command; everything from the command
+    // onward is an argument. Filtering the whole of argv removed those too, so an option whose
+    // value happens to be `underpost` — a storage id, a public asset path — lost it, and the
+    // parse failed on a missing argument rather than on anything the caller wrote.
+    const commandIndex = process.argv.findIndex(
+      (token, index) => index >= 2 && underpostProgram.commands.some((command) => command._name === token),
+    );
+    if (commandIndex > 2)
+      process.argv = [
+        ...process.argv.slice(0, 2),
+        ...process.argv.slice(2, commandIndex).filter((token) => token !== 'underpost'),
+        ...process.argv.slice(commandIndex),
+      ];
     if (!process.argv.includes('--plain')) logger.info('Rerouting to underpost cli...');
     try {
       await underpostProgram.parseAsync();