cyberia 3.1.3 → 3.2.9

package/bin/cyberia.js

@@ -16,6 +16,7 @@
 import dotenv from 'dotenv';
 import { Command } from 'commander';
 import fs from 'fs-extra';
+import stringify from 'fast-json-stable-stringify';
 import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.js';
 import { generateBesuManifests, deployBesu, removeBesu } from '../src/server/besu-genesis-generator.js';
@@ -27,21 +28,24 @@ import {
   pngDirectoryIteratorByObjectLayerType,
   getKeyFramesDirectionsFromNumberFolderDirection,
   buildImgFromTile,
-  itemTypes,
 } from '../src/server/object-layer.js';
 import { AtlasSpriteSheetGenerator } from '../src/server/atlas-sprite-sheet-generator.js';
-import {
-  generateFrame,
-  generateMultiFrame,
-  lookupSemantic,
-  semanticRegistry,
-} from '../src/server/semantic-layer-generator.js';
+import { generateMultiFrame, lookupSemantic, semanticRegistry } from '../src/server/semantic-layer-generator.js';
 import { IpfsClient } from '../src/server/ipfs-client.js';
 import { createPinRecord } from '../src/api/ipfs/ipfs.service.js';
 import { program as underpostProgram } from '../src/cli/index.js';
 import crypto from 'crypto';
 import nodePath from 'path';
 import Underpost from '../src/index.js';
+import { newInstance } from '../src/client/components/core/CommonJs.js';
+import {
+  ITEM_TYPES as itemTypes,
+  DefaultCyberiaItems,
+  DefaultSkillConfig,
+  DefaultCyberiaDialogues,
+  DefaultCyberiaActions,
+  DefaultCyberiaQuests,
+} from '../src/client/components/cyberia-portal/CommonCyberiaPortal.js';
 
 /**
  * Connect to the project MongoDB instance using the standard env / conf layout.
@@ -103,7 +107,11 @@ try {
       'Convert object layers to atlas sprite sheets, specify 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 [object-layer-type]', 'Commas separated object layer types e.g. skin,floors')
+    .option(
+      '--import',
+      'Import specific item-id(s) passed as comma-separated command argument (e.g. ol hatchet,sword --import)',
+    )
+    .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)
@@ -115,6 +123,9 @@ try {
     .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')
+    .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
     .action(
       /**
        * Main action handler for the `ol` command.
@@ -122,7 +133,8 @@ try {
        *
        * @param {string|undefined} itemId - Optional item ID argument.
        * @param {Object} options - Command options parsed by Commander.
-       * @param {boolean|string} options.import - Object layer types to import (e.g., 'all', 'skin,floor') or `false`.
+       * @param {boolean} options.import - Import specific item-id(s) from the command argument (comma-separated).
+       * @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.
@@ -130,6 +142,9 @@ try {
        * @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.
+       * @param {boolean} options.clientPublic - Also remove static asset folders when dropping.
+       * @param {boolean} options.gitClean - Run underpost clean on the cyberia asset directory when dropping.
+       * @param {boolean} options.dev - Force development environment.
        * @param {boolean} options.generate - Whether to run procedural generation for the item-id.
        * @param {number} options.count - Shape element count multiplier for generation.
        * @param {string} options.seed - Deterministic seed string for generation.
@@ -143,12 +158,17 @@ try {
         itemId,
         options = {
           import: false,
+          importTypes: false,
           showFrame: '',
           envPath: '',
           mongoHost: '',
           storageFilePath: '',
           toAtlasSpriteSheet: '',
           showAtlasSpriteSheet: false,
+          drop: false,
+          clientPublic: false,
+          gitClean: false,
+          dev: false,
           generate: false,
           count: 3,
           seed: '',
@@ -160,6 +180,14 @@ try {
         if (!options.envPath) options.envPath = `./.env`;
         if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
 
+        // --dev: force development environment (IPFS localhost, etc.)
+        if (options.dev && process.env.DEFAULT_DEPLOY_ID) {
+          const deployDevEnvPath = `./engine-private/conf/${process.env.DEFAULT_DEPLOY_ID}/.env.development`;
+          if (fs.existsSync(deployDevEnvPath)) {
+            dotenv.config({ path: deployDevEnvPath, override: true });
+          }
+        }
+
         /** @type {string} */
         const deployId = process.env.DEFAULT_DEPLOY_ID;
         /** @type {string} */
@@ -171,7 +199,11 @@ try {
         const confServer = loadConfServerJson(confServerPath, { resolve: true });
         const { db } = confServer[host][path];
 
-        db.host = options.mongoHost ? options.mongoHost : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
+        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: options.envPath,
@@ -197,23 +229,519 @@ try {
         const AtlasSpriteSheet = DataBaseProvider.instance[`${host}${path}`].mongoose.models.AtlasSpriteSheet;
         /** @type {import('mongoose').Model} */
         const File = DataBaseProvider.instance[`${host}${path}`].mongoose.models.File;
+        /** @type {import('mongoose').Model} */
+        const Ipfs = DataBaseProvider.instance[`${host}${path}`].mongoose.models.Ipfs;
 
         if (options.drop) {
-          await ObjectLayer.deleteMany();
-          await ObjectLayerRenderFrames.deleteMany();
-          shellExec(`cd src/client/public/cyberia && underpost run clean .`);
+          // Parse comma-separated item IDs for targeted drop; if none provided, drop everything
+          const dropItemIds = itemId
+            ? itemId
+                .split(',')
+                .map((id) => id.trim())
+                .filter(Boolean)
+            : null;
+          const isTargetedDrop = dropItemIds && dropItemIds.length > 0;
+
+          if (isTargetedDrop) {
+            logger.info(`Targeted drop for item(s): ${dropItemIds.join(', ')}`);
+          } else {
+            logger.info('Dropping ALL object layer data');
+          }
+
+          // Build query filter: targeted or all
+          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, {
+            cid: 1,
+            'data.item.id': 1,
+            'data.item.type': 1,
+            'data.render': 1,
+            objectLayerRenderFramesId: 1,
+            atlasSpriteSheetId: 1,
+          }).lean();
+          const atlasDocs = await AtlasSpriteSheet.find(atlasFilter, { fileId: 1, cid: 1 }).lean();
+
+          const cidsToUnpin = new Set();
+          const itemIdsToClean = new Set();
+          const renderFrameIds = [];
+          const atlasIds = [];
+
+          for (const doc of olDocs) {
+            if (doc.cid) cidsToUnpin.add(doc.cid);
+            if (doc.data?.render?.cid) cidsToUnpin.add(doc.data.render.cid);
+            if (doc.data?.render?.metadataCid) cidsToUnpin.add(doc.data.render.metadataCid);
+            if (doc.data?.item?.id) itemIdsToClean.add(doc.data.item.id);
+            if (doc.objectLayerRenderFramesId) renderFrameIds.push(doc.objectLayerRenderFramesId);
+            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;
+          }
+
+          // Delete IPFS pin registry records for all collected CIDs
+          if (cidsToUnpin.size > 0) {
+            const ipfsResult = await Ipfs.deleteMany({ cid: { $in: [...cidsToUnpin] } });
+            logger.info(`Dropped ${ipfsResult.deletedCount} Ipfs pin record(s)`);
+          }
+
+          // Unpin CIDs from IPFS Cluster + Kubo and remove MFS directories
+          let unpinCount = 0;
+          let mfsCount = 0;
+          for (const cid of cidsToUnpin) {
+            const ok = await IpfsClient.unpinCid(cid);
+            if (ok) unpinCount++;
+          }
+          for (const itemKey of itemIdsToClean) {
+            const ok = await IpfsClient.removeMfsPath(`/object-layer/${itemKey}`);
+            if (ok) mfsCount++;
+          }
+
+          logger.info(
+            `Dropped: ${olCount} ObjectLayer, ${rfCount} RenderFrames, ${atlasCount} AtlasSpriteSheet, ${fileCount} File (atlas)`,
+          );
+          logger.info(
+            `IPFS cleanup: ${unpinCount}/${cidsToUnpin.size} CIDs unpinned, ${mfsCount}/${itemIdsToClean.size} MFS paths removed`,
+          );
+          if (options.gitClean) {
+            shellExec(`cd src/client/public/cyberia && underpost run clean .`);
+            logger.info('Asset directory cleaned');
+          }
+
+          // --client-public: remove static asset folders for dropped items
+          if (options.clientPublic) {
+            const srcBase = './src/client/public/cyberia/assets';
+            const publicBase = `./public/${host}${path}/assets`;
+            let removedCount = 0;
+            for (const doc of olDocs) {
+              const docItemId = doc.data?.item?.id;
+              const docItemType = doc.data?.item?.type;
+              if (!docItemId || !docItemType) continue;
+              for (const base of [srcBase, publicBase]) {
+                const folder = `${base}/${docItemType}/${docItemId}`;
+                if (fs.existsSync(folder)) {
+                  fs.removeSync(folder);
+                  removedCount++;
+                  logger.info(`Removed static folder: ${folder}`);
+                }
+              }
+            }
+            logger.info(`Static asset cleanup: ${removedCount} folder(s) removed`);
+          }
         }
 
         /** @type {Object|null} */
         const storage = options.storageFilePath ? JSON.parse(fs.readFileSync(options.storageFilePath, 'utf8')) : null;
 
-        // ── Handle --import ──────────────────────────────────────────────
+        // ── 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);
+          }
+
+          const itemIds = itemId
+            .split(',')
+            .map((id) => id.trim())
+            .filter(Boolean);
+          logger.info(`Importing specific item(s): ${itemIds.join(', ')}`);
+
+          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;
+              }
+            }
+
+            if (!foundType) {
+              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}`);
+
+            const { objectLayerRenderFramesData, objectLayerData } =
+              await ObjectLayerEngine.buildObjectLayerDataFromDirectory({
+                folder: foundFolder,
+                objectLayerType: foundType,
+                objectLayerId: currentItemId,
+              });
+
+            // 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,
+              itemId: currentItemId,
+              objectLayerRenderFramesData,
+              objectLayerData,
+              cellPixelDim: 20,
+            });
+
+            // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
+            const existingOL = await ObjectLayer.findOne({ 'data.item.id': 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 = '';
+              let stagingSha256 = '';
+              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 (compute final SHA-256 in memory)
+                stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                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 update of the live document
+                await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                  data: stagingData,
+                  sha256: stagingSha256,
+                  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 ${existingOL._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.findById(existingOL._id);
+            } 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 = '';
+              let stagingSha256 = '';
+              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;
+
+                stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                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.create({
+                  data: stagingData,
+                  sha256: stagingSha256,
+                  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;
+              }
+            }
+
+            // Reload final state to include CID and render updates
+            const finalObjectLayer = await ObjectLayer.findById(objectLayer._id).populate('objectLayerRenderFramesId');
+            console.log(finalObjectLayer.toObject());
+          }
+        }
+
+        // ── Handle --import-types (batch by type) ────────────────────────
+        if (options.importTypes) {
           /** @type {boolean} */
-          const isImportAll = options.import === 'all';
+          const isImportAll = options.importTypes === 'all';
 
           /** @type {string[]} */
-          const argItemTypes = isImportAll ? Object.keys(itemTypes) : options.import.split(',');
+          const argItemTypes = isImportAll ? Object.keys(itemTypes) : options.importTypes.split(',');
 
           /**
            * Accumulated object layer data keyed by objectLayerId.
@@ -221,6 +749,19 @@ try {
            */
           const objectLayers = {};
 
+          // When importing all types, pre-fetch existing item IDs so we can skip them entirely
+          /** @type {Set<string>} */
+          const existingItemIds = new Set();
+          if (isImportAll) {
+            const existingDocs = await ObjectLayer.find({}, { 'data.item.id': 1 }).lean();
+            for (const doc of existingDocs) {
+              if (doc.data?.item?.id) existingItemIds.add(doc.data.item.id);
+            }
+            if (existingItemIds.size > 0) {
+              logger.info(`Skipping ${existingItemIds.size} existing item(s): ${[...existingItemIds].join(', ')}`);
+            }
+          }
+
           for (const argItemType of argItemTypes) {
             await pngDirectoryIteratorByObjectLayerType(
               argItemType,
@@ -231,6 +772,9 @@ try {
                 )
                   return;
 
+                // Skip items that already exist in the database (bulk import only)
+                if (isImportAll && existingItemIds.has(objectLayerId)) return;
+
                 console.log(framePath, { objectLayerType, objectLayerId, direction, frame });
 
                 // On first encounter of an objectLayerId, build its data from the asset directory
@@ -243,6 +787,18 @@ try {
                       objectLayerId,
                     });
 
+                  // 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: objectLayerType,
+                    itemId: objectLayerId,
+                    objectLayerRenderFramesData,
+                    objectLayerData,
+                    cellPixelDim: 20,
+                  });
+
                   objectLayers[objectLayerId] = {
                     ...objectLayerData,
                     objectLayerRenderFramesData,
@@ -261,116 +817,375 @@ try {
             const shouldGenerateAtlas = !isImportAll;
 
             if (shouldGenerateAtlas) {
-              // Use the createObjectLayerDocuments which handles atlas generation
-              // Since we're in CLI context without a full Express req/res, we build a minimal
-              // atlas generation flow using AtlasSpriteSheetGenerator directly after creation.
-              const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
-                ObjectLayer,
-                ObjectLayerRenderFrames,
-                objectLayerRenderFramesData: entry.objectLayerRenderFramesData,
-                objectLayerData: { data: entry.data },
-                createOptions: {
-                  generateAtlas: false,
-                },
-              });
+              // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
+              const existingOL = await ObjectLayer.findOne({ 'data.item.id': 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 = '';
+                let stagingSha256 = '';
+                try {
+                  const itemKey = objectLayerId;
 
-              // Generate atlas sprite sheet for individual imports
-              try {
-                const itemKey = objectLayer.data.item.id;
-                const populatedObjectLayer = await ObjectLayer.findById(objectLayer._id).populate(
-                  'objectLayerRenderFramesId',
-                );
+                  // Generate atlas from in-memory render frames data (plain object, no DB doc needed)
+                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+                    entry.objectLayerRenderFramesData,
+                    itemKey,
+                    20,
+                  );
 
-                const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                  populatedObjectLayer.objectLayerRenderFramesId,
-                  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();
 
-                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();
+                  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);
+                  }
 
-                // Pin atlas PNG to IPFS
-                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(`Atlas sprite sheet pinned to IPFS – CID: ${importAtlasCid}`);
+                  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);
                   }
-                } catch (ipfsError) {
-                  logger.warn('Failed to add atlas sprite sheet 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 (compute final SHA-256 in memory)
+                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                  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);
                 }
 
-                // 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) {
-                    importAtlasMetadataCid = metadataIpfsResult.cid;
-                    logger.info(`Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
+                // 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);
+
+                  await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                    data: stagingData,
+                    sha256: stagingSha256,
+                    cid: stagingCid,
+                    objectLayerRenderFramesId: newRenderFrames._id,
+                    atlasSpriteSheetId: stagingAtlasDoc._id,
+                  });
+
+                  if (oldRenderFramesId) {
+                    await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
                   }
-                } catch (ipfsError) {
-                  logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
+                  logger.info(`[cut-over] Live document ${existingOL._id} updated atomically`);
+                } else {
+                  if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
+                  logger.warn(`[cut-over] Staging rolled back for ${objectLayerId}, live document preserved`);
                 }
 
-                let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+                objectLayer = await ObjectLayer.findById(existingOL._id);
+              } 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 = '';
+                let stagingSha256 = '';
+                try {
+                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+                    entry.objectLayerRenderFramesData,
+                    itemKey,
+                    20,
+                  );
 
-                if (atlasDoc) {
-                  atlasDoc.fileId = fileDoc._id;
-                  atlasDoc.cid = importAtlasCid;
-                  atlasDoc.metadata = metadata;
-                  await atlasDoc.save();
-                  logger.info(`Updated existing AtlasSpriteSheet document: ${atlasDoc._id}`);
-                } else {
-                  atlasDoc = await new AtlasSpriteSheet({
-                    fileId: fileDoc._id,
-                    cid: importAtlasCid,
-                    metadata,
+                  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();
-                  logger.info(`Created new AtlasSpriteSheet document: ${atlasDoc._id}`);
-                }
 
-                populatedObjectLayer.atlasSpriteSheetId = atlasDoc._id;
-                if (!populatedObjectLayer.data.render) populatedObjectLayer.data.render = {};
-                populatedObjectLayer.data.render.cid = importAtlasCid;
-                populatedObjectLayer.data.render.metadataCid = importAtlasMetadataCid;
-                populatedObjectLayer.markModified('data.render');
-                await populatedObjectLayer.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);
+                  }
 
-                logger.info(`Atlas sprite sheet completed for item: ${itemKey}`);
-              } catch (atlasError) {
-                logger.error(`Failed to generate atlas for ${objectLayerId}:`, atlasError);
+                  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;
+
+                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                  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.create({
+                    data: stagingData,
+                    sha256: stagingSha256,
+                    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;
+                }
               }
 
-              console.log(objectLayer);
+              // 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 { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
-                ObjectLayer,
-                ObjectLayerRenderFrames,
-                objectLayerRenderFramesData: entry.objectLayerRenderFramesData,
-                objectLayerData: { data: entry.data },
-                createOptions: {
-                  generateAtlas: false,
-                },
-              });
+              const existingOL = await ObjectLayer.findOne({ 'data.item.id': 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 = '';
+                const stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+
+                // Atomic cut-over: create new RenderFrames, swap live doc, delete old
+                const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
+                const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
+
+                await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                  data: stagingData,
+                  sha256: stagingSha256,
+                  objectLayerRenderFramesId: newRenderFrames._id,
+                });
+
+                if (oldRenderFramesId) {
+                  await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
+                }
+
+                objectLayer = await ObjectLayer.findById(existingOL._id);
+                logger.info(`[cut-over] Live document ${existingOL._id} updated atomically (atlas skipped)`);
+              } else {
+                // New item: create with sha256 populated (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 stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+
+                const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
+                objectLayer = await ObjectLayer.create({
+                  data: stagingData,
+                  sha256: stagingSha256,
+                  objectLayerRenderFramesId: newRenderFrames._id,
+                });
+              }
 
-              logger.info(`ObjectLayer created (atlas skipped for bulk import): ${objectLayerId}`);
-              console.log(objectLayer);
+              logger.info(
+                `ObjectLayer ${existingOL ? 'updated' : 'created'} (atlas skipped for bulk import): ${objectLayerId}`,
+              );
+              console.log(objectLayer.toObject ? objectLayer.toObject() : objectLayer);
             }
           }
         }
@@ -527,6 +1342,15 @@ try {
             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);
@@ -542,6 +1366,15 @@ try {
             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);
+              }
             }
           } catch (ipfsError) {
             logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
@@ -551,7 +1384,8 @@ try {
           let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
 
           if (atlasDoc) {
-            // Update existing
+            // 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;
@@ -575,6 +1409,13 @@ try {
           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}`);
         }
 
@@ -674,169 +1515,1704 @@ try {
             density: genDensity,
           });
 
-          // Overwrite the item id in the generated data with the unique variant
-          multiFrameResult.objectLayerData.data.item.id = uniqueItemId;
+          // Overwrite the item id in the generated data with the unique variant
+          multiFrameResult.objectLayerData.data.item.id = uniqueItemId;
+
+          logger.info(
+            `Generated ${multiFrameResult.frameCount} frame(s) with ${multiFrameResult.objectLayerRenderFramesData.colors.length} unique colors`,
+          );
+
+          // 2. Write static asset PNGs to both source and public directories
+          const srcBasePath = './src/client/public/cyberia/';
+          const publicBasePath = `./public/${host}${path}`;
+          const writtenFiles = await ObjectLayerEngine.writeStaticFrameAssets({
+            basePaths: [srcBasePath, publicBasePath],
+            itemType: descriptor.itemType,
+            itemId: uniqueItemId,
+            objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
+            objectLayerData: multiFrameResult.objectLayerData,
+            cellPixelDim: 20,
+          });
+
+          logger.info(`Wrote ${writtenFiles.length} asset file(s):`);
+          for (const f of writtenFiles) {
+            logger.info(`  → ${f}`);
+          }
+
+          // 3. Persist to MongoDB (ObjectLayerRenderFrames + ObjectLayer)
+          const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
+            ObjectLayer,
+            ObjectLayerRenderFrames,
+            objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
+            objectLayerData: multiFrameResult.objectLayerData,
+            createOptions: {
+              generateAtlas: false,
+            },
+          });
+
+          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);
+                }
+              }
+            } 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})`);
+
+          // Log per-layer summary
+          if (multiFrameResult.frames.length > 0) {
+            const firstFrame = multiFrameResult.frames[0];
+            for (const layer of firstFrame.layers) {
+              logger.info(`  Layer "${layer.layerKey}" (${layer.layerId}): ${layer.keys.length} element(s)`);
+            }
+          }
+        }
+
+        await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+      },
+    )
+    .description('Object layer management');
+
+  // ── instance: Cyberia instance backup / restore ─────────────────────────
+  program
+    .command('instance [instance-code]')
+    .option('--export [path]', 'Export instance and related documents to a backup directory')
+    .option('--import [path]', 'Import instance and related documents from a backup directory (preserveUUID, upsert)')
+    .option(
+      '--conf',
+      'When used with --export or --import, only process cyberia-instance.json and cyberia-instance-conf.json',
+    )
+    .option('--drop', 'Drop all documents associated with the instance code before importing or as a standalone action')
+    .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('Export/import a Cyberia instance with all related maps, entities and object layers')
+    .action(async (instanceCode, options = {}) => {
+      if (!instanceCode) {
+        logger.error('instance-code argument is required');
+        process.exit(1);
+      }
+
+      if (!options.envPath) options.envPath = `./.env`;
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      if (options.dev && process.env.DEFAULT_DEPLOY_ID) {
+        const deployDevEnvPath = `./engine-private/conf/${process.env.DEFAULT_DEPLOY_ID}/.env.development`;
+        if (fs.existsSync(deployDevEnvPath)) {
+          dotenv.config({ path: deployDevEnvPath, 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}`);
+        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('instance env', { env: options.envPath, deployId, host, path, db });
+
+      await DataBaseProvider.load({
+        apis: [
+          'cyberia-instance',
+          'cyberia-instance-conf',
+          'cyberia-dialogue',
+          'cyberia-map',
+          'cyberia-entity',
+          'object-layer',
+          'object-layer-render-frames',
+          'atlas-sprite-sheet',
+          'file',
+          'ipfs',
+        ],
+        host,
+        path,
+        db,
+      });
+
+      const dbModels = DataBaseProvider.instance[`${host}${path}`].mongoose.models;
+      const CyberiaInstance = dbModels.CyberiaInstance;
+      const CyberiaInstanceConf = dbModels.CyberiaInstanceConf;
+      const CyberiaDialogue = dbModels.CyberiaDialogue;
+      const CyberiaMap = dbModels.CyberiaMap;
+      const ObjectLayer = dbModels.ObjectLayer;
+      const ObjectLayerRenderFrames = dbModels.ObjectLayerRenderFrames;
+      const AtlasSpriteSheet = dbModels.AtlasSpriteSheet;
+      const File = dbModels.File;
+      const Ipfs = dbModels.Ipfs;
+
+      const toBuffer = (value) => {
+        if (!value) return null;
+        if (Buffer.isBuffer(value)) return value;
+        if (value.type === 'Buffer' && Array.isArray(value.data)) return Buffer.from(value.data);
+        if (value.buffer) return Buffer.from(value.buffer);
+        return Buffer.from(value);
+      };
+
+      const getCanonicalIpfsPaths = (itemKey) => ({
+        objectLayerData: `/object-layer/${itemKey}/${itemKey}_data.json`,
+        atlasSpriteSheet: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+        atlasMetadata: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+      });
+
+      const collectMfsPaths = (doc = {}) => {
+        const paths = new Set();
+        if (doc.mfsPath) paths.add(doc.mfsPath);
+        for (const p of doc.mfsPaths || []) {
+          if (p) paths.add(p);
+        }
+        return [...paths];
+      };
+
+      const inferResourceType = (doc = {}) => {
+        if (doc.resourceType) return doc.resourceType;
+        for (const path of collectMfsPaths(doc)) {
+          if (path.endsWith('_atlas_sprite_sheet.png')) return 'atlas-sprite-sheet';
+          if (path.endsWith('_atlas_sprite_sheet_metadata.json')) return 'atlas-metadata';
+          if (path.endsWith('_data.json')) return 'object-layer-data';
+        }
+        return null;
+      };
+
+      const findInstanceRelatedIpfsDoc = (ipfsDocs, { linkedCid, resourceType, mfsPath }) =>
+        ipfsDocs.find(
+          (doc) =>
+            inferResourceType(doc) === resourceType &&
+            linkedCid &&
+            doc.cid === linkedCid &&
+            collectMfsPaths(doc).includes(mfsPath),
+        ) ||
+        ipfsDocs.find((doc) => inferResourceType(doc) === resourceType && linkedCid && doc.cid === linkedCid) ||
+        ipfsDocs.find((doc) => inferResourceType(doc) === resourceType && collectMfsPaths(doc).includes(mfsPath)) ||
+        null;
+
+      const upsertCanonicalPinEntry = (pinMap, { cid, resourceType, mfsPath = '' }) => {
+        if (!cid || !resourceType) return;
+        const key = `${resourceType}:${cid}`;
+        const nextPath = mfsPath || '';
+        if (!pinMap.has(key)) {
+          pinMap.set(key, {
+            cid,
+            resourceType,
+            mfsPath: nextPath,
+            mfsPaths: nextPath ? [nextPath] : [],
+          });
+          return;
+        }
+
+        const existing = pinMap.get(key);
+        if (nextPath && !existing.mfsPaths.includes(nextPath)) {
+          existing.mfsPaths.push(nextPath);
+        }
+        if (!existing.mfsPath && nextPath) {
+          existing.mfsPath = nextPath;
+        }
+      };
+
+      const serialiseCanonicalPins = (pinMap) =>
+        [...pinMap.values()].map((entry) => ({
+          cid: entry.cid,
+          resourceType: entry.resourceType,
+          ...(entry.mfsPath ? { mfsPath: entry.mfsPath } : {}),
+          ...(entry.mfsPaths.length ? { mfsPaths: entry.mfsPaths } : {}),
+        }));
+
+      const getDefaultDialoguesByItemId = (itemIds = []) => {
+        const requestedItemIds = new Set(itemIds.filter(Boolean));
+        const defaultsByItemId = new Map();
+
+        for (const dialogue of DefaultCyberiaDialogues) {
+          // Match by code prefix: "default-<itemId>" covers the common case;
+          // callers may also pass a full code directly.
+          const matchingIds = [...requestedItemIds].filter(
+            (id) => dialogue.code === `default-${id}` || dialogue.code === id,
+          );
+          if (!matchingIds.length) continue;
+          for (const id of matchingIds) {
+            if (!defaultsByItemId.has(id)) defaultsByItemId.set(id, []);
+            defaultsByItemId.get(id).push({
+              code: dialogue.code,
+              order: dialogue.order ?? 0,
+              speaker: dialogue.speaker ?? '',
+              text: dialogue.text,
+              mood: dialogue.mood ?? 'neutral',
+            });
+          }
+        }
+
+        for (const dialogues of defaultsByItemId.values()) {
+          dialogues.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        }
+
+        return defaultsByItemId;
+      };
+
+      const rewriteImportedCidReferences = async ({ oldCid, newCid, resourceType }) => {
+        if (!oldCid || !newCid || oldCid === newCid) return;
+
+        if (resourceType === 'object-layer-data') {
+          await ObjectLayer.updateMany({ cid: oldCid }, { $set: { cid: newCid } });
+          return;
+        }
+
+        if (resourceType === 'atlas-sprite-sheet') {
+          await AtlasSpriteSheet.updateMany({ cid: oldCid }, { $set: { cid: newCid } });
+          await ObjectLayer.updateMany({ 'data.render.cid': oldCid }, { $set: { 'data.render.cid': newCid } });
+          return;
+        }
+
+        if (resourceType === 'atlas-metadata') {
+          await ObjectLayer.updateMany(
+            { 'data.render.metadataCid': oldCid },
+            { $set: { 'data.render.metadataCid': newCid } },
+          );
+        }
+      };
+
+      // ── EXPORT ──────────────────────────────────────────────────────
+      if (options.export !== undefined) {
+        const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
+        if (!instance) {
+          logger.error(`CyberiaInstance with code "${instanceCode}" not found`);
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          process.exit(1);
+        }
+
+        const backupDir =
+          typeof options.export === 'string' && options.export
+            ? options.export
+            : `./engine-private/cyberia-instances/${instanceCode}`;
+
+        fs.ensureDirSync(backupDir);
+        logger.info('Exporting instance', { code: instanceCode, backupDir });
+
+        // Helper: export a File document to the files/ directory
+        const exportFileDoc = async (fileId, fileKey) => {
+          if (!fileId) return;
+          const file = await File.findById(fileId).lean();
+          if (!file) return;
+          fs.ensureDirSync(`${backupDir}/files`);
+          const fileExport = { ...file };
+          // Handle both Node.js Buffer and BSON Binary types from .lean()
+          if (fileExport.data) {
+            const buf = Buffer.isBuffer(fileExport.data)
+              ? fileExport.data
+              : Buffer.from(fileExport.data.buffer || fileExport.data);
+            fileExport.data = { $base64: buf.toString('base64') };
+          }
+          fs.writeJsonSync(`${backupDir}/files/${fileKey}.json`, fileExport, { spaces: 2 });
+        };
+
+        // 1. Save instance document + thumbnail
+        fs.writeJsonSync(`${backupDir}/cyberia-instance.json`, instance, { spaces: 2 });
+        if (!options.conf && instance.thumbnail) {
+          await exportFileDoc(instance.thumbnail, `thumb-instance-${instanceCode}`);
+        }
+        logger.info('Exported CyberiaInstance', { code: instanceCode });
+
+        // 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().
+        let instanceConf =
+          (await CyberiaInstanceConf.findOne({ instanceCode }).lean()) ||
+          (instance.conf ? await CyberiaInstanceConf.findById(instance.conf).lean() : null);
+        if (!instanceConf) {
+          logger.info('No CyberiaInstanceConf found — creating default', { instanceCode });
+          const created = await CyberiaInstanceConf.findOneAndUpdate(
+            { instanceCode },
+            { $setOnInsert: { instanceCode } },
+            { upsert: true, returnDocument: 'after' },
+          );
+          // Back-fill the instance.conf ref if it was missing
+          if (created && !instance.conf) {
+            await CyberiaInstance.findByIdAndUpdate(instance._id, { conf: created._id });
+          }
+          instanceConf = created?.toObject ? created.toObject() : created;
+        }
+        if (instanceConf) {
+          fs.writeJsonSync(`${backupDir}/cyberia-instance-conf.json`, instanceConf, { spaces: 2 });
+          logger.info('Exported CyberiaInstanceConf', { instanceCode });
+        } else {
+          logger.warn('Could not create or find CyberiaInstanceConf', { instanceCode });
+        }
+
+        if (options.conf) {
+          logger.info('Instance export completed in --conf mode', {
+            backupDir,
+            exportedFiles: ['cyberia-instance.json', 'cyberia-instance-conf.json'],
+          });
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          return;
+        }
+
+        // 2. Collect all map codes (instance maps + portal targets)
+        const mapCodes = new Set(instance.cyberiaMapCodes || []);
+        for (const portal of instance.portals || []) {
+          if (portal.sourceMapCode) mapCodes.add(portal.sourceMapCode);
+          if (portal.targetMapCode) mapCodes.add(portal.targetMapCode);
+        }
+
+        // 3. Export maps + thumbnails
+        const maps = await CyberiaMap.find({ code: { $in: [...mapCodes] } }).lean();
+        fs.ensureDirSync(`${backupDir}/maps`);
+        for (const map of maps) {
+          fs.writeJsonSync(`${backupDir}/maps/${map.code}.json`, map, { spaces: 2 });
+          if (map.thumbnail) {
+            await exportFileDoc(map.thumbnail, `thumb-map-${map.code}`);
+          }
+        }
+        logger.info(`Exported ${maps.length} CyberiaMap document(s)`, { codes: maps.map((m) => m.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
+        for (const id of instance.itemIds || []) {
+          if (id) objectLayerItemIds.add(id);
+        }
+
+        // 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);
+              }
+            }
+          }
+        }
+
+        // 4d. Export dialogues for all relevant object-layer items. Codes follow the pattern
+        //     "default-<itemId>". If an item has no dialogue docs yet but ships with
+        //     DefaultCyberiaDialogues, seed those defaults into Mongo first.
+        if (objectLayerItemIds.size > 0) {
+          const requestedItemIds = [...objectLayerItemIds];
+          const requestedCodes = requestedItemIds.map((id) => `default-${id}`);
+          const defaultDialoguesByItemId = getDefaultDialoguesByItemId(requestedItemIds);
+          const existingDialogueDocs = await CyberiaDialogue.find({
+            code: { $in: requestedCodes },
+          })
+            .sort({ code: 1, order: 1 })
+            .lean();
+
+          const existingDialogueCodes = new Set(existingDialogueDocs.map((dialogue) => dialogue.code).filter(Boolean));
+          let seededDialogueCount = 0;
+
+          for (const [itemId, dialogues] of defaultDialoguesByItemId.entries()) {
+            const firstCode = dialogues[0]?.code;
+            if (firstCode && existingDialogueCodes.has(firstCode)) continue;
+
+            for (const dialogue of dialogues) {
+              await CyberiaDialogue.findOneAndUpdate(
+                { code: dialogue.code, order: dialogue.order },
+                {
+                  $set: {
+                    speaker: dialogue.speaker,
+                    text: dialogue.text,
+                    mood: dialogue.mood,
+                  },
+                },
+                { upsert: true },
+              );
+              seededDialogueCount++;
+            }
+          }
+
+          const dialogueDocs = await CyberiaDialogue.find({ code: { $in: requestedCodes } })
+            .sort({ code: 1, order: 1 })
+            .lean();
+
+          if (seededDialogueCount > 0) {
+            logger.info(`Seeded ${seededDialogueCount} CyberiaDialogue default record(s) for export`);
+          }
+
+          if (dialogueDocs.length > 0) {
+            fs.ensureDirSync(`${backupDir}/cyberia-dialogues`);
+            const dialoguesByCode = new Map();
+
+            for (const dialogue of dialogueDocs) {
+              if (!dialoguesByCode.has(dialogue.code)) {
+                dialoguesByCode.set(dialogue.code, []);
+              }
+              dialoguesByCode.get(dialogue.code).push(dialogue);
+            }
+
+            for (const [code, dialogues] of dialoguesByCode.entries()) {
+              fs.writeJsonSync(`${backupDir}/cyberia-dialogues/${encodeURIComponent(code)}.json`, dialogues, {
+                spaces: 2,
+              });
+            }
+
+            logger.info(`Exported ${dialogueDocs.length} CyberiaDialogue document(s)`, {
+              codes: [...dialoguesByCode.keys()],
+            });
+          }
+        }
+
+        // 5. Export object layers with related render frames, atlas, files, and IPFS records
+        if (objectLayerItemIds.size > 0) {
+          const objectLayers = await ObjectLayer.find({
+            'data.item.id': { $in: [...objectLayerItemIds] },
+          }).lean();
+
+          fs.ensureDirSync(`${backupDir}/object-layers`);
+          fs.ensureDirSync(`${backupDir}/render-frames`);
+          fs.ensureDirSync(`${backupDir}/atlas-sprite-sheets`);
+          fs.ensureDirSync(`${backupDir}/ipfs`);
+          fs.ensureDirSync(`${backupDir}/ipfs/content`);
+
+          const canonicalPins = new Map();
+          const expectedObjectLayerIpfsRefs = [];
+          const ipfsPayloadFailures = [];
+          let ipfsPayloadExportCount = 0;
+          let ipfsPayloadAliasCount = 0;
+
+          const writeBackupPayload = (cid, payloadBuffer) => {
+            if (!cid) return false;
+            const payloadPath = `${backupDir}/ipfs/content/${cid}.bin`;
+            if (fs.existsSync(payloadPath)) return false;
+            fs.writeFileSync(payloadPath, payloadBuffer);
+            ipfsPayloadExportCount++;
+            return true;
+          };
+
+          const writeBackupPayloadAlias = ({ canonicalCid, linkedCid, payloadBuffer }) => {
+            if (!linkedCid || linkedCid === canonicalCid) return;
+            if (writeBackupPayload(linkedCid, payloadBuffer)) {
+              ipfsPayloadAliasCount++;
+            }
+          };
+
+          const exportCanonicalPayload = async ({ payloadBuffer, resourceType, mfsPath, filename, itemKey }) => {
+            const hashResult = await IpfsClient.hashBufferForIpfs(payloadBuffer, filename);
+            if (!hashResult?.cid) {
+              ipfsPayloadFailures.push({ itemKey, resourceType, mfsPath, reason: 'Failed to hash payload via Kubo' });
+              return null;
+            }
+
+            writeBackupPayload(hashResult.cid, payloadBuffer);
+            return hashResult.cid;
+          };
+
+          for (const ol of objectLayers) {
+            const itemKey = ol.data?.item?.id || ol._id.toString();
+            const itemPaths = getCanonicalIpfsPaths(itemKey);
+            const objectLayerExport = newInstance(ol);
+
+            if (!objectLayerExport.data.render) {
+              objectLayerExport.data.render = {};
+            }
+
+            // Export ObjectLayerRenderFrames
+            if (ol.objectLayerRenderFramesId) {
+              const rf = await ObjectLayerRenderFrames.findById(ol.objectLayerRenderFramesId).lean();
+              if (rf) {
+                fs.writeJsonSync(`${backupDir}/render-frames/${itemKey}.json`, rf, { spaces: 2 });
+              }
+            }
+
+            // Export AtlasSpriteSheet + its File using canonical payload bytes from the DB state.
+            if (ol.atlasSpriteSheetId) {
+              const atlas = await AtlasSpriteSheet.findById(ol.atlasSpriteSheetId).lean();
+              if (!atlas) {
+                ipfsPayloadFailures.push({
+                  itemKey,
+                  resourceType: 'atlas-sprite-sheet',
+                  mfsPath: itemPaths.atlasSpriteSheet,
+                  reason: 'AtlasSpriteSheet document not found in MongoDB',
+                });
+                continue;
+              }
+
+              const atlasExport = newInstance(atlas);
+              if (atlas.fileId) {
+                await exportFileDoc(atlas.fileId, `atlas-${itemKey}`);
+              }
+
+              const atlasFile = atlas.fileId ? await File.findById(atlas.fileId).lean() : null;
+              const atlasBuffer = toBuffer(atlasFile?.data);
+              if (!atlasBuffer) {
+                ipfsPayloadFailures.push({
+                  itemKey,
+                  resourceType: 'atlas-sprite-sheet',
+                  mfsPath: itemPaths.atlasSpriteSheet,
+                  reason: 'Atlas File payload not found in MongoDB',
+                });
+                continue;
+              }
+
+              const atlasCid = await exportCanonicalPayload({
+                payloadBuffer: atlasBuffer,
+                resourceType: 'atlas-sprite-sheet',
+                mfsPath: itemPaths.atlasSpriteSheet,
+                filename: `${itemKey}_atlas_sprite_sheet.png`,
+                itemKey,
+              });
+              if (!atlasCid) continue;
+
+              const linkedAtlasCid = atlas.cid || ol.data?.render?.cid || atlasCid;
+              writeBackupPayloadAlias({
+                canonicalCid: atlasCid,
+                linkedCid: linkedAtlasCid,
+                payloadBuffer: atlasBuffer,
+              });
+              expectedObjectLayerIpfsRefs.push({
+                itemKey,
+                resourceType: 'atlas-sprite-sheet',
+                mfsPath: itemPaths.atlasSpriteSheet,
+                linkedCid: linkedAtlasCid,
+                fallbackCid: atlasCid,
+              });
+
+              const atlasMetadataBuffer = Buffer.from(stringify(atlasExport.metadata || {}), 'utf-8');
+              const atlasMetadataCid = await exportCanonicalPayload({
+                payloadBuffer: atlasMetadataBuffer,
+                resourceType: 'atlas-metadata',
+                mfsPath: itemPaths.atlasMetadata,
+                filename: `${itemKey}_atlas_sprite_sheet_metadata.json`,
+                itemKey,
+              });
+              if (!atlasMetadataCid) continue;
+
+              const linkedAtlasMetadataCid = ol.data?.render?.metadataCid || atlasMetadataCid;
+              writeBackupPayloadAlias({
+                canonicalCid: atlasMetadataCid,
+                linkedCid: linkedAtlasMetadataCid,
+                payloadBuffer: atlasMetadataBuffer,
+              });
+              expectedObjectLayerIpfsRefs.push({
+                itemKey,
+                resourceType: 'atlas-metadata',
+                mfsPath: itemPaths.atlasMetadata,
+                linkedCid: linkedAtlasMetadataCid,
+                fallbackCid: atlasMetadataCid,
+              });
+
+              atlasExport.cid = atlasCid;
+              objectLayerExport.data.render.cid = atlasCid;
+              objectLayerExport.data.render.metadataCid = atlasMetadataCid;
+              fs.writeJsonSync(`${backupDir}/atlas-sprite-sheets/${itemKey}.json`, atlasExport, { spaces: 2 });
+            } else {
+              if (objectLayerExport.data.render?.cid || objectLayerExport.data.render?.metadataCid) {
+                ipfsPayloadFailures.push({
+                  itemKey,
+                  resourceType: 'atlas-sprite-sheet',
+                  mfsPath: itemPaths.atlasSpriteSheet,
+                  reason: 'ObjectLayer references atlas CIDs but no AtlasSpriteSheet document exists',
+                });
+                continue;
+              }
+              delete objectLayerExport.data.render.cid;
+              delete objectLayerExport.data.render.metadataCid;
+            }
+
+            const objectLayerBuffer = Buffer.from(stringify(objectLayerExport.data || {}), 'utf-8');
+            const objectLayerCid = await exportCanonicalPayload({
+              payloadBuffer: objectLayerBuffer,
+              resourceType: 'object-layer-data',
+              mfsPath: itemPaths.objectLayerData,
+              filename: `${itemKey}_data.json`,
+              itemKey,
+            });
+            if (!objectLayerCid) continue;
+
+            const linkedObjectLayerCid = ol.cid || objectLayerCid;
+            writeBackupPayloadAlias({
+              canonicalCid: objectLayerCid,
+              linkedCid: linkedObjectLayerCid,
+              payloadBuffer: objectLayerBuffer,
+            });
+            expectedObjectLayerIpfsRefs.push({
+              itemKey,
+              resourceType: 'object-layer-data',
+              mfsPath: itemPaths.objectLayerData,
+              linkedCid: linkedObjectLayerCid,
+              fallbackCid: objectLayerCid,
+            });
+
+            objectLayerExport.cid = objectLayerCid;
+            fs.writeJsonSync(`${backupDir}/object-layers/${itemKey}.json`, objectLayerExport, { spaces: 2 });
+          }
+
+          if (ipfsPayloadFailures.length > 0) {
+            for (const failure of ipfsPayloadFailures) {
+              logger.error('Canonical IPFS payload export failed', failure);
+            }
+            await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+            process.exit(1);
+          }
+
+          const relatedPinPaths = [
+            ...new Set(expectedObjectLayerIpfsRefs.map((entry) => entry.mfsPath).filter(Boolean)),
+          ];
+          const relatedPinCids = [
+            ...new Set(
+              expectedObjectLayerIpfsRefs.flatMap((entry) => [entry.linkedCid, entry.fallbackCid]).filter(Boolean),
+            ),
+          ];
+          const relatedIpfsDocs =
+            relatedPinPaths.length > 0 || relatedPinCids.length > 0
+              ? await Ipfs.find({
+                  $or: [
+                    ...(relatedPinPaths.length ? [{ mfsPath: { $in: relatedPinPaths } }] : []),
+                    ...(relatedPinPaths.length ? [{ mfsPaths: { $in: relatedPinPaths } }] : []),
+                    ...(relatedPinCids.length ? [{ cid: { $in: relatedPinCids } }] : []),
+                  ],
+                }).lean()
+              : [];
+
+          let ipfsCollectionMatchCount = 0;
+          let ipfsCollectionFallbackCount = 0;
+
+          for (const ref of expectedObjectLayerIpfsRefs) {
+            const matchingDoc = findInstanceRelatedIpfsDoc(relatedIpfsDocs, ref);
+            const exportCid = matchingDoc?.cid || ref.linkedCid || ref.fallbackCid;
+
+            if (!exportCid) {
+              logger.warn('Skipping instance IPFS pin export because the ObjectLayer ref has no linked CID', {
+                itemKey: ref.itemKey,
+                resourceType: ref.resourceType,
+                mfsPath: ref.mfsPath,
+              });
+              continue;
+            }
+
+            upsertCanonicalPinEntry(canonicalPins, {
+              cid: exportCid,
+              resourceType: ref.resourceType,
+              mfsPath: ref.mfsPath,
+            });
+
+            if (matchingDoc) ipfsCollectionMatchCount++;
+            else ipfsCollectionFallbackCount++;
+          }
+
+          const sanitised = serialiseCanonicalPins(canonicalPins);
+          fs.writeJsonSync(`${backupDir}/ipfs/pins.json`, sanitised, { spaces: 2 });
+          logger.info(
+            `Exported ${sanitised.length} instance-related Ipfs pin record(s) and ${ipfsPayloadExportCount} raw payload file(s)`,
+            {
+              matchedFromIpfsCollection: ipfsCollectionMatchCount,
+              fallbackFromObjectLayerRefs: ipfsCollectionFallbackCount,
+              rawPayloadAliases: ipfsPayloadAliasCount,
+            },
+          );
+
+          logger.info(`Exported ${objectLayers.length} ObjectLayer document(s)`, {
+            itemIds: [...objectLayerItemIds],
+          });
+        } else {
+          logger.info('No ObjectLayer references found in map entities');
+        }
+
+        logger.info('Instance export completed', { backupDir });
+      }
+
+      // ── IMPORT ──────────────────────────────────────────────────────
+      if (options.import !== undefined) {
+        const backupDir =
+          typeof options.import === 'string' && options.import
+            ? options.import
+            : `./engine-private/cyberia-instances/${instanceCode}`;
+
+        if (!fs.existsSync(backupDir)) {
+          logger.error(`Backup directory not found: ${backupDir}`);
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          process.exit(1);
+        }
+
+        logger.info('Importing instance', { code: instanceCode, backupDir });
+
+        // 0. Drop existing documents if --drop is set
+        if (options.drop && !options.conf) {
+          const existingInstance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
+          if (existingInstance) {
+            const dropMapCodes = new Set(existingInstance.cyberiaMapCodes || []);
+            for (const portal of existingInstance.portals || []) {
+              if (portal.sourceMapCode) dropMapCodes.add(portal.sourceMapCode);
+              if (portal.targetMapCode) dropMapCodes.add(portal.targetMapCode);
+            }
+
+            // Collect thumbnail File IDs to drop
+            const thumbFileIds = [];
+            if (existingInstance.thumbnail) thumbFileIds.push(existingInstance.thumbnail);
+            const dropOlItemIds = new Set();
+
+            // 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 id of existingInstance.itemIds || []) if (id) dropOlItemIds.add(id);
+
+            // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
+            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);
+                }
+              }
+            }
+
+            const otherMaps = await CyberiaMap.find(
+              { code: { $nin: [...dropMapCodes] } },
+              { 'entities.objectLayerItemIds': 1, thumbnail: 1 },
+            ).lean();
+
+            if (dropMapCodes.size > 0) {
+              const dropMaps = await CyberiaMap.find({ code: { $in: [...dropMapCodes] } }).lean();
+              for (const map of dropMaps) {
+                if (map.thumbnail) thumbFileIds.push(map.thumbnail);
+                for (const entity of map.entities || []) {
+                  for (const itemId of entity.objectLayerItemIds || []) {
+                    dropOlItemIds.add(itemId);
+                  }
+                }
+              }
+
+              const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
+              logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap document(s)`);
+            }
+
+            // Exclude OL item IDs referenced by maps outside this instance
+            const sharedOlItemIds = new Set();
+            for (const m of otherMaps) {
+              for (const entity of m.entities || []) {
+                for (const itemId of entity.objectLayerItemIds || []) {
+                  if (dropOlItemIds.has(itemId)) sharedOlItemIds.add(itemId);
+                }
+              }
+            }
+            for (const shared of sharedOlItemIds) dropOlItemIds.delete(shared);
+            if (sharedOlItemIds.size > 0) {
+              logger.info(`Preserved ${sharedOlItemIds.size} ObjectLayer(s) shared with other maps`);
+            }
+
+            // Exclude thumbnail File IDs referenced by other instances or maps
+            const otherMapThumbs = otherMaps.map((m) => m.thumbnail?.toString()).filter(Boolean);
+            const otherInstThumbs = otherInstances.map((i) => i.thumbnail?.toString()).filter(Boolean);
+            const sharedThumbIds = new Set([...otherMapThumbs, ...otherInstThumbs]);
+            for (let i = thumbFileIds.length - 1; i >= 0; i--) {
+              if (sharedThumbIds.has(thumbFileIds[i].toString())) thumbFileIds.splice(i, 1);
+            }
+
+            if (dropOlItemIds.size > 0) {
+              const dropDialogueCodes = [...dropOlItemIds].map((id) => `default-${id}`);
+              const dialogueResult = await CyberiaDialogue.deleteMany({ code: { $in: dropDialogueCodes } });
+              logger.info(`Dropped ${dialogueResult.deletedCount} CyberiaDialogue document(s)`);
+              const olDocs = await ObjectLayer.find(
+                { 'data.item.id': { $in: [...dropOlItemIds] } },
+                {
+                  cid: 1,
+                  'data.item.id': 1,
+                  'data.render': 1,
+                  objectLayerRenderFramesId: 1,
+                  atlasSpriteSheetId: 1,
+                },
+              ).lean();
+
+              const cidsToUnpin = new Set();
+              const renderFrameIds = [];
+              const atlasIds = [];
+              const itemKeysToClean = new Set();
+
+              for (const doc of olDocs) {
+                if (doc.cid) cidsToUnpin.add(doc.cid);
+                if (doc.data?.render?.cid) cidsToUnpin.add(doc.data.render.cid);
+                if (doc.data?.render?.metadataCid) cidsToUnpin.add(doc.data.render.metadataCid);
+                if (doc.data?.item?.id) itemKeysToClean.add(doc.data.item.id);
+                if (doc.objectLayerRenderFramesId) renderFrameIds.push(doc.objectLayerRenderFramesId);
+                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 RenderFrames
+              if (renderFrameIds.length > 0) {
+                const rfResult = await ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFrameIds } });
+                logger.info(`Dropped ${rfResult.deletedCount} ObjectLayerRenderFrames document(s)`);
+              }
+
+              // Delete IPFS pin records
+              if (cidsToUnpin.size > 0) {
+                const ipfsResult = await Ipfs.deleteMany({ cid: { $in: [...cidsToUnpin] } });
+                logger.info(`Dropped ${ipfsResult.deletedCount} Ipfs pin record(s)`);
+              }
+
+              // Unpin CIDs from IPFS Kubo + Cluster and remove MFS paths
+              let unpinCount = 0;
+              for (const cid of cidsToUnpin) {
+                const ok = await IpfsClient.unpinCid(cid);
+                if (ok) unpinCount++;
+              }
+              let mfsCount = 0;
+              for (const itemKey of itemKeysToClean) {
+                const ok = await IpfsClient.removeMfsPath(`/object-layer/${itemKey}`);
+                if (ok) mfsCount++;
+              }
+              logger.info(
+                `IPFS cleanup: ${unpinCount}/${cidsToUnpin.size} CIDs unpinned, ${mfsCount}/${itemKeysToClean.size} MFS paths removed`,
+              );
+
+              const olResult = await ObjectLayer.deleteMany({ 'data.item.id': { $in: [...dropOlItemIds] } });
+              logger.info(`Dropped ${olResult.deletedCount} ObjectLayer document(s)`);
+            }
+
+            // Drop thumbnail File documents (instance + maps), excluding shared ones
+            if (thumbFileIds.length > 0) {
+              const thumbResult = await File.deleteMany({ _id: { $in: thumbFileIds } });
+              logger.info(`Dropped ${thumbResult.deletedCount} File document(s) (thumbnails)`);
+            }
+
+            await CyberiaInstance.deleteOne({ code: instanceCode });
+            logger.info('Dropped CyberiaInstance', { code: instanceCode });
+            await CyberiaInstanceConf.deleteOne({ instanceCode });
+            logger.info('Dropped CyberiaInstanceConf', { instanceCode });
+          } else {
+            logger.info('No existing instance to drop', { code: instanceCode });
+          }
+        } else if (options.drop && options.conf) {
+          logger.info(
+            'Skipping full instance drop because --conf only imports cyberia-instance.json and cyberia-instance-conf.json',
+          );
+        }
+
+        if (options.conf) {
+          const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
+          let importedConf = null;
+          if (fs.existsSync(confImportPath)) {
+            const confData = fs.readJsonSync(confImportPath);
+            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.
+            confData.updatedAt = new Date();
+            importedConf = await CyberiaInstanceConf.create(confData);
+            logger.info('Imported CyberiaInstanceConf', { instanceCode: confData.instanceCode });
+          } else {
+            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.
+          if (importedConf) {
+            const result = await CyberiaInstance.updateOne(
+              { code: instanceCode },
+              { $set: { conf: importedConf._id, updatedAt: new Date() } },
+            );
+            if (result.matchedCount > 0) {
+              logger.info('Updated CyberiaInstance conf ref', { code: instanceCode });
+            } else {
+              logger.warn(`CyberiaInstance not found in DB for code "${instanceCode}" — cannot update conf ref`);
+            }
+          } else {
+            logger.warn(`Skipping CyberiaInstance conf ref update — no conf was imported`);
+          }
+
+          logger.info('Instance import completed in --conf mode', {
+            backupDir,
+            importedFiles: ['cyberia-instance.json', 'cyberia-instance-conf.json'],
+          });
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          return;
+        }
+
+        // 1. Import File documents first (atlas PNG + thumbnail dependencies)
+        const filesDir = `${backupDir}/files`;
+        if (fs.existsSync(filesDir)) {
+          const fileFiles = fs.readdirSync(filesDir).filter((f) => f.endsWith('.json'));
+          let fileCount = 0;
+          for (const f of fileFiles) {
+            const fileData = fs.readJsonSync(`${filesDir}/${f}`);
+            // Restore base64-encoded Buffer (handle both $base64 and { type: 'Buffer', data: [...] })
+            if (fileData.data) {
+              if (fileData.data.$base64) {
+                fileData.data = Buffer.from(fileData.data.$base64, 'base64');
+              } else if (fileData.data.type === 'Buffer' && Array.isArray(fileData.data.data)) {
+                fileData.data = Buffer.from(fileData.data.data);
+              }
+            }
+            // preserveUUID: delete any existing doc with this _id then create with exact _id
+            await File.deleteOne({ _id: fileData._id });
+            await File.create(fileData);
+            fileCount++;
+          }
+          logger.info(`Imported ${fileCount} File document(s)`);
+        }
+
+        // 2. Import ObjectLayerRenderFrames
+        const rfDir = `${backupDir}/render-frames`;
+        if (fs.existsSync(rfDir)) {
+          const rfFiles = fs.readdirSync(rfDir).filter((f) => f.endsWith('.json'));
+          let rfCount = 0;
+          for (const f of rfFiles) {
+            const rfData = fs.readJsonSync(`${rfDir}/${f}`);
+            if (rfData._id) {
+              await ObjectLayerRenderFrames.deleteOne({ _id: rfData._id });
+              await ObjectLayerRenderFrames.create(rfData);
+              rfCount++;
+            }
+          }
+          logger.info(`Imported ${rfCount} ObjectLayerRenderFrames document(s)`);
+        }
+
+        // 3. Import AtlasSpriteSheet
+        const atlasDir = `${backupDir}/atlas-sprite-sheets`;
+        if (fs.existsSync(atlasDir)) {
+          const atlasFiles = fs.readdirSync(atlasDir).filter((f) => f.endsWith('.json'));
+          let atlasCount = 0;
+          for (const f of atlasFiles) {
+            const atlasData = fs.readJsonSync(`${atlasDir}/${f}`);
+            await AtlasSpriteSheet.deleteOne({ _id: atlasData._id });
+            if (atlasData.metadata?.itemKey) {
+              await AtlasSpriteSheet.deleteOne({ 'metadata.itemKey': atlasData.metadata.itemKey });
+            }
+            await AtlasSpriteSheet.create(atlasData);
+            atlasCount++;
+          }
+          logger.info(`Imported ${atlasCount} AtlasSpriteSheet document(s)`);
+        }
+
+        // 4. Import object layers
+        const olDir = `${backupDir}/object-layers`;
+        if (fs.existsSync(olDir)) {
+          const olFiles = fs.readdirSync(olDir).filter((f) => f.endsWith('.json'));
+          let olCount = 0;
+          for (const file of olFiles) {
+            const olData = fs.readJsonSync(`${olDir}/${file}`);
+            await ObjectLayer.deleteOne({ _id: olData._id });
+            if (olData.sha256) {
+              await ObjectLayer.deleteOne({ sha256: olData.sha256 });
+            }
+            await ObjectLayer.create(olData);
+            olCount++;
+          }
+          logger.info(`Imported ${olCount} ObjectLayer document(s)`);
+        }
+
+        // 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
+        //     asset directory was wiped (e.g. git clean / rm -rf).
+        const rfImportDir = `${backupDir}/render-frames`;
+        const olImportDir = `${backupDir}/object-layers`;
+        if (fs.existsSync(rfImportDir) && fs.existsSync(olImportDir)) {
+          const srcBasePath = './src/client/public/cyberia/';
+          const publicBasePath = `./public/${host}${path}`;
+          let staticWriteCount = 0;
+          const rfFileList = fs.readdirSync(rfImportDir).filter((f) => f.endsWith('.json'));
+          for (const rfFile of rfFileList) {
+            const rfData = fs.readJsonSync(`${rfImportDir}/${rfFile}`);
+            const itemId = nodePath.basename(rfFile, '.json');
+            const olFile = `${olImportDir}/${itemId}.json`;
+            if (!fs.existsSync(olFile)) {
+              logger.warn(`Skipping static asset generation for '${itemId}' — no matching object-layer file`);
+              continue;
+            }
+            const olData = fs.readJsonSync(olFile);
+            const itemType = olData.data?.item?.type;
+            if (!itemType) {
+              logger.warn(`Skipping static asset generation for '${itemId}' — missing data.item.type`);
+              continue;
+            }
+            // rfData matches the ObjectLayerRenderFrames schema: { frames, colors, frame_duration }
+            const objectLayerRenderFramesData = {
+              frames: rfData.frames || {},
+              colors: rfData.colors || [],
+              frame_duration: rfData.frame_duration ?? 100,
+            };
+            try {
+              const written = await ObjectLayerEngine.writeStaticFrameAssets({
+                basePaths: [srcBasePath, publicBasePath],
+                itemType,
+                itemId,
+                objectLayerRenderFramesData,
+                objectLayerData: olData,
+                cellPixelDim: 20,
+              });
+              staticWriteCount += written.length;
+            } catch (err) {
+              logger.warn(`Failed to write static assets for '${itemId}': ${err.message}`);
+            }
+          }
+          logger.info(`Static frame PNGs written: ${staticWriteCount} file(s) across src/client/public and public/`);
+        }
+
+        // 5. Import maps (preserveUUID: delete by code then create with exact _id)
+        const mapsDir = `${backupDir}/maps`;
+        if (fs.existsSync(mapsDir)) {
+          const mapFiles = fs.readdirSync(mapsDir).filter((f) => f.endsWith('.json'));
+          let mapCount = 0;
+          for (const file of mapFiles) {
+            const mapData = fs.readJsonSync(`${mapsDir}/${file}`);
+            await CyberiaMap.deleteOne({ code: mapData.code });
+            await CyberiaMap.deleteOne({ _id: mapData._id });
+            await CyberiaMap.create(mapData);
+            mapCount++;
+          }
+          logger.info(`Imported ${mapCount} CyberiaMap document(s)`);
+        }
+
+        // 6. Import CyberiaInstanceConf (skillRules, equipmentRules, entityDefaults, etc.)
+        const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
+        if (fs.existsSync(confImportPath)) {
+          const confData = fs.readJsonSync(confImportPath);
+          if (confData._id) await CyberiaInstanceConf.deleteOne({ _id: confData._id });
+          await CyberiaInstanceConf.deleteOne({ instanceCode: confData.instanceCode });
+          await CyberiaInstanceConf.create(confData);
+          logger.info('Imported CyberiaInstanceConf', { instanceCode: confData.instanceCode });
+        } else {
+          logger.warn(`CyberiaInstanceConf backup not found: ${confImportPath}`);
+        }
+
+        // 7. Import instance (preserveUUID: delete by code then create with exact _id)
+        const instancePath = `${backupDir}/cyberia-instance.json`;
+        if (fs.existsSync(instancePath)) {
+          const instanceData = fs.readJsonSync(instancePath);
+          await CyberiaInstance.deleteOne({ code: instanceCode });
+          await CyberiaInstance.deleteOne({ _id: instanceData._id });
+          await CyberiaInstance.create(instanceData);
+          logger.info('Imported CyberiaInstance', { code: instanceCode });
+        } else {
+          logger.warn(`Instance file not found: ${instancePath}`);
+        }
+
+        // 8. Import CyberiaDialogue documents
+        const dialoguesDir = `${backupDir}/cyberia-dialogues`;
+        if (fs.existsSync(dialoguesDir)) {
+          const dialogueFiles = fs.readdirSync(dialoguesDir).filter((f) => f.endsWith('.json'));
+          let dialogueCount = 0;
+
+          for (const file of dialogueFiles) {
+            const rawDialogueData = fs.readJsonSync(`${dialoguesDir}/${file}`);
+            const dialogues = Array.isArray(rawDialogueData) ? rawDialogueData : [rawDialogueData];
+            const dialogueCodes = [...new Set(dialogues.map((dialogue) => dialogue.code).filter(Boolean))];
+            if (dialogueCodes.length === 0) {
+              logger.warn(`Skipping CyberiaDialogue backup without code: ${file}`);
+              continue;
+            }
+
+            await CyberiaDialogue.deleteMany({ code: { $in: dialogueCodes } });
+
+            const dialogueIds = dialogues.map((dialogue) => dialogue._id).filter(Boolean);
+            if (dialogueIds.length > 0) {
+              await CyberiaDialogue.deleteMany({ _id: { $in: dialogueIds } });
+            }
+
+            await CyberiaDialogue.create(dialogues);
+            dialogueCount += dialogues.length;
+          }
+
+          logger.info(`Imported ${dialogueCount} CyberiaDialogue document(s)`);
+        }
+
+        // 9. Restore IPFS pin records and payloads
+        const ipfsFile = `${backupDir}/ipfs/pins.json`;
+        if (fs.existsSync(ipfsFile)) {
+          const ipfsDocs = fs.readJsonSync(ipfsFile);
+          const ipfsContentDir = `${backupDir}/ipfs/content`;
+          let ipfsCount = 0;
+          let ipfsSkipped = 0;
+
+          const backupPins = new Map();
+          for (const doc of ipfsDocs) {
+            const resourceType = inferResourceType(doc);
+            if (!resourceType) {
+              logger.warn(
+                `Ipfs record is missing resourceType and cannot be inferred (cid: ${doc.cid}, mfsPath: ${doc.mfsPath ?? '(none)'}) — skipping`,
+              );
+              ipfsSkipped++;
+              continue;
+            }
+
+            const mfsPaths = collectMfsPaths(doc);
+            if (mfsPaths.length === 0) {
+              upsertCanonicalPinEntry(backupPins, { cid: doc.cid, resourceType, mfsPath: '' });
+            } else {
+              for (const mfsPath of mfsPaths) {
+                upsertCanonicalPinEntry(backupPins, { cid: doc.cid, resourceType, mfsPath });
+              }
+            }
+          }
+
+          const backupPinEntries = serialiseCanonicalPins(backupPins);
+          const backupCids = [...new Set(backupPinEntries.map((entry) => entry.cid).filter(Boolean))];
+          if (backupCids.length > 0) {
+            await Ipfs.deleteMany({ cid: { $in: backupCids } });
+          }
+
+          const restoreAdditionalMfsPaths = async (cid, mfsPaths, primaryPath) => {
+            let restoredCount = 0;
+            for (const mfsPath of mfsPaths) {
+              if (!mfsPath || mfsPath === primaryPath) continue;
+              const ok = await IpfsClient.restoreMfsPath(cid, mfsPath);
+              if (ok) restoredCount++;
+            }
+            return restoredCount;
+          };
+
+          const upsertImportedPin = async ({ cid, resourceType, mfsPath }) => {
+            if (!cid || !resourceType) return;
+            await Ipfs.deleteMany({ cid, resourceType });
+            await createPinRecord({ cid, resourceType, mfsPath: mfsPath || '', options: { host, path } });
+          };
+
+          if (fs.existsSync(ipfsContentDir)) {
+            let cidRewriteCount = 0;
+            let extraMfsRestoreCount = 0;
+
+            for (const [index, doc] of backupPinEntries.entries()) {
+              const mfsPaths = collectMfsPaths(doc);
+              const primaryPath = mfsPaths[0] || '';
+              const payloadPath = `${ipfsContentDir}/${doc.cid}.bin`;
+
+              logger.info('IPFS raw payload restore start', {
+                index: index + 1,
+                total: backupPinEntries.length,
+                cid: doc.cid,
+                resourceType: doc.resourceType,
+                mfsPath: primaryPath || null,
+              });
+
+              if (!fs.existsSync(payloadPath)) {
+                logger.warn('IPFS raw payload file missing from backup', {
+                  cid: doc.cid,
+                  resourceType: doc.resourceType,
+                  mfsPath: primaryPath || null,
+                });
+                ipfsSkipped++;
+                continue;
+              }
+
+              const addResult = await IpfsClient.addToIpfs(
+                fs.readFileSync(payloadPath),
+                nodePath.basename(primaryPath || doc.cid),
+                primaryPath || undefined,
+              );
+
+              if (!addResult?.cid) {
+                logger.warn('IPFS raw payload restore failed', {
+                  cid: doc.cid,
+                  resourceType: doc.resourceType,
+                  mfsPath: primaryPath || null,
+                });
+                ipfsSkipped++;
+                continue;
+              }
+
+              const finalCid = addResult.cid;
+              if (doc.cid !== finalCid) {
+                await rewriteImportedCidReferences({
+                  oldCid: doc.cid,
+                  newCid: finalCid,
+                  resourceType: doc.resourceType,
+                });
+                cidRewriteCount++;
+                logger.warn('IPFS raw payload CID mismatch during import; rewriting imported references', {
+                  oldCid: doc.cid,
+                  newCid: finalCid,
+                  resourceType: doc.resourceType,
+                  mfsPath: primaryPath || null,
+                });
+              }
 
-          logger.info(
-            `Generated ${multiFrameResult.frameCount} frame(s) with ${multiFrameResult.objectLayerRenderFramesData.colors.length} unique colors`,
-          );
+              extraMfsRestoreCount += await restoreAdditionalMfsPaths(finalCid, mfsPaths, primaryPath);
+              await upsertImportedPin({ cid: finalCid, resourceType: doc.resourceType, mfsPath: primaryPath });
+              ipfsCount++;
+            }
 
-          // 2. Write static asset PNGs to both source and public directories
-          const srcBasePath = './src/client/public/cyberia/';
-          const publicBasePath = `./public/${host}${path}`;
-          const writtenFiles = await ObjectLayerEngine.writeStaticFrameAssets({
-            basePaths: [srcBasePath, publicBasePath],
-            itemType: descriptor.itemType,
-            itemId: uniqueItemId,
-            objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
-            objectLayerData: multiFrameResult.objectLayerData,
-            cellPixelDim: 20,
-          });
+            logger.info(
+              `Imported ${ipfsCount} Ipfs pin record(s) from exact backup payloads${ipfsSkipped ? `, skipped ${ipfsSkipped}` : ''}`,
+            );
+            logger.info(
+              `IPFS raw payload restore: ${ipfsCount}/${backupPinEntries.length} record(s) restored, ${extraMfsRestoreCount} additional MFS path(s) restored${cidRewriteCount ? `, ${cidRewriteCount} CID rewrite(s)` : ''}`,
+            );
+          } else {
+            logger.warn(
+              'Backup has no raw IPFS payload files under ipfs/content/. Rebuilding a canonical IPFS layout from imported ObjectLayer, AtlasSpriteSheet, and File documents.',
+            );
 
-          logger.info(`Wrote ${writtenFiles.length} asset file(s):`);
-          for (const f of writtenFiles) {
-            logger.info(`  → ${f}`);
-          }
+            const importedItemIds = fs.existsSync(olDir)
+              ? fs
+                  .readdirSync(olDir)
+                  .filter((f) => f.endsWith('.json'))
+                  .map((f) => nodePath.basename(f, '.json'))
+              : [];
+            const importedObjectLayers = importedItemIds.length
+              ? await ObjectLayer.find({ 'data.item.id': { $in: importedItemIds } }).lean()
+              : [];
+
+            let rebuiltObjectLayers = 0;
+
+            for (const [index, objectLayerDoc] of importedObjectLayers.entries()) {
+              const itemKey = objectLayerDoc.data?.item?.id || objectLayerDoc._id.toString();
+              const itemPaths = getCanonicalIpfsPaths(itemKey);
+              const updatedData = newInstance(objectLayerDoc.data || {});
+              if (!updatedData.render) updatedData.render = {};
+
+              logger.info('IPFS legacy canonical rebuild start', {
+                index: index + 1,
+                total: importedObjectLayers.length,
+                itemKey,
+              });
 
-          // 3. Persist to MongoDB (ObjectLayerRenderFrames + ObjectLayer)
-          const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
-            ObjectLayer,
-            ObjectLayerRenderFrames,
-            objectLayerRenderFramesData: multiFrameResult.objectLayerRenderFramesData,
-            objectLayerData: multiFrameResult.objectLayerData,
-            createOptions: {
-              generateAtlas: false,
-            },
-          });
+              let atlasCid = '';
+              let atlasMetadataCid = '';
 
-          logger.info(`ObjectLayer persisted to MongoDB: ${objectLayer._id} (item: ${objectLayer.data.item.id})`);
+              if (objectLayerDoc.atlasSpriteSheetId) {
+                const atlasDoc = await AtlasSpriteSheet.findById(objectLayerDoc.atlasSpriteSheetId).lean();
+                if (atlasDoc) {
+                  const atlasFile = atlasDoc.fileId ? await File.findById(atlasDoc.fileId).lean() : null;
+                  const atlasBuffer = toBuffer(atlasFile?.data);
+
+                  if (atlasBuffer) {
+                    const atlasAddResult = await IpfsClient.addBufferToIpfs(
+                      atlasBuffer,
+                      `${itemKey}_atlas_sprite_sheet.png`,
+                      itemPaths.atlasSpriteSheet,
+                    );
+                    if (atlasAddResult?.cid) {
+                      atlasCid = atlasAddResult.cid;
+                      await AtlasSpriteSheet.updateOne({ _id: atlasDoc._id }, { $set: { cid: atlasCid } });
+                      await createPinRecord({
+                        cid: atlasCid,
+                        resourceType: 'atlas-sprite-sheet',
+                        mfsPath: itemPaths.atlasSpriteSheet,
+                        options: { host, path },
+                      });
+                      ipfsCount++;
+                    } else {
+                      logger.warn(`Failed to rebuild atlas sprite sheet payload for '${itemKey}'`);
+                    }
+                  } else if (atlasDoc.fileId) {
+                    logger.warn(`Atlas File payload missing for '${itemKey}'`);
+                  }
 
-          // 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 atlasMetadataResult = await IpfsClient.addJsonToIpfs(
+                    atlasDoc.metadata || {},
+                    `${itemKey}_atlas_sprite_sheet_metadata.json`,
+                    itemPaths.atlasMetadata,
+                  );
+                  if (atlasMetadataResult?.cid) {
+                    atlasMetadataCid = atlasMetadataResult.cid;
+                    await createPinRecord({
+                      cid: atlasMetadataCid,
+                      resourceType: 'atlas-metadata',
+                      mfsPath: itemPaths.atlasMetadata,
+                      options: { host, path },
+                    });
+                    ipfsCount++;
+                  } else {
+                    logger.warn(`Failed to rebuild atlas metadata payload for '${itemKey}'`);
+                  }
+                }
+              }
 
-            const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-              populatedObjectLayer.objectLayerRenderFramesId,
-              atlasItemKey,
-              20,
+              if (atlasCid) {
+                updatedData.render.cid = atlasCid;
+              } else {
+                delete updatedData.render.cid;
+              }
+              if (atlasMetadataCid) {
+                updatedData.render.metadataCid = atlasMetadataCid;
+              } else {
+                delete updatedData.render.metadataCid;
+              }
+
+              const objectLayerAddResult = await IpfsClient.addJsonToIpfs(
+                updatedData,
+                `${itemKey}_data.json`,
+                itemPaths.objectLayerData,
+              );
+              if (objectLayerAddResult?.cid) {
+                await ObjectLayer.updateOne(
+                  { _id: objectLayerDoc._id },
+                  {
+                    $set: {
+                      cid: objectLayerAddResult.cid,
+                      data: updatedData,
+                    },
+                  },
+                );
+                await createPinRecord({
+                  cid: objectLayerAddResult.cid,
+                  resourceType: 'object-layer-data',
+                  mfsPath: itemPaths.objectLayerData,
+                  options: { host, path },
+                });
+                ipfsCount++;
+                rebuiltObjectLayers++;
+              } else {
+                logger.warn(`Failed to rebuild object-layer-data payload for '${itemKey}'`);
+                ipfsSkipped++;
+              }
+            }
+
+            logger.info(
+              `Legacy IPFS rebuild: ${rebuiltObjectLayers}/${importedObjectLayers.length} ObjectLayer payload(s) rebuilt, ${ipfsCount} canonical pin record(s) upserted${ipfsSkipped ? `, skipped ${ipfsSkipped}` : ''}`,
             );
+          }
+        }
 
-            // 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();
+        logger.info('Instance import completed', { backupDir });
+      }
 
-            // 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}`);
+      // ── DROP (standalone) ───────────────────────────────────────────
+      if (options.drop && options.import === undefined) {
+        const existingInstance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
+        if (existingInstance) {
+          const dropMapCodes = new Set(existingInstance.cyberiaMapCodes || []);
+          for (const portal of existingInstance.portals || []) {
+            if (portal.sourceMapCode) dropMapCodes.add(portal.sourceMapCode);
+            if (portal.targetMapCode) dropMapCodes.add(portal.targetMapCode);
+          }
+
+          // Collect thumbnail File IDs to drop
+          const thumbFileIds = [];
+          if (existingInstance.thumbnail) thumbFileIds.push(existingInstance.thumbnail);
+          const dropOlItemIds = new Set();
+
+          // 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 id of existingInstance.itemIds || []) if (id) dropOlItemIds.add(id);
+
+          // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
+          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);
               }
-            } 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}`);
+          const otherMaps = await CyberiaMap.find(
+            { code: { $nin: [...dropMapCodes] } },
+            { 'entities.objectLayerItemIds': 1, thumbnail: 1 },
+          ).lean();
+
+          if (dropMapCodes.size > 0) {
+            const dropMaps = await CyberiaMap.find({ code: { $in: [...dropMapCodes] } }).lean();
+            for (const map of dropMaps) {
+              if (map.thumbnail) thumbFileIds.push(map.thumbnail);
+              for (const entity of map.entities || []) {
+                for (const itemId of entity.objectLayerItemIds || []) {
+                  dropOlItemIds.add(itemId);
+                }
               }
-            } catch (ipfsError) {
-              logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
             }
+            const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
+            logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap document(s)`);
+          }
 
-            // Upsert AtlasSpriteSheet document (with CID)
-            let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': atlasItemKey });
-            if (atlasDoc) {
-              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}`);
+          // Exclude OL item IDs referenced by maps outside this instance
+          const sharedOlItemIds = new Set();
+          for (const m of otherMaps) {
+            for (const entity of m.entities || []) {
+              for (const itemId of entity.objectLayerItemIds || []) {
+                if (dropOlItemIds.has(itemId)) sharedOlItemIds.add(itemId);
+              }
             }
+          }
+          for (const shared of sharedOlItemIds) dropOlItemIds.delete(shared);
+          if (sharedOlItemIds.size > 0) {
+            logger.info(`Preserved ${sharedOlItemIds.size} ObjectLayer(s) shared with other maps`);
+          }
 
-            // 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();
+          // Exclude thumbnail File IDs referenced by other instances or maps
+          const otherMapThumbs = otherMaps.map((m) => m.thumbnail?.toString()).filter(Boolean);
+          const otherInstThumbs = otherInstances.map((i) => i.thumbnail?.toString()).filter(Boolean);
+          const sharedThumbIds = new Set([...otherMapThumbs, ...otherInstThumbs]);
+          for (let i = thumbFileIds.length - 1; i >= 0; i--) {
+            if (sharedThumbIds.has(thumbFileIds[i].toString())) thumbFileIds.splice(i, 1);
+          }
 
-            // 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}`,
-              );
+          if (dropOlItemIds.size > 0) {
+            const dropDialogueCodes = [...dropOlItemIds].map((id) => `default-${id}`);
+            const dialogueResult = await CyberiaDialogue.deleteMany({ code: { $in: dropDialogueCodes } });
+            logger.info(`Dropped ${dialogueResult.deletedCount} CyberiaDialogue document(s)`);
+
+            const olDocs = await ObjectLayer.find(
+              { 'data.item.id': { $in: [...dropOlItemIds] } },
+              {
+                cid: 1,
+                'data.item.id': 1,
+                'data.render': 1,
+                objectLayerRenderFramesId: 1,
+                atlasSpriteSheetId: 1,
+              },
+            ).lean();
+
+            const cidsToUnpin = new Set();
+            const renderFrameIds = [];
+            const atlasIds = [];
+            const itemKeysToClean = new Set();
+
+            for (const doc of olDocs) {
+              if (doc.cid) cidsToUnpin.add(doc.cid);
+              if (doc.data?.render?.cid) cidsToUnpin.add(doc.data.render.cid);
+              if (doc.data?.render?.metadataCid) cidsToUnpin.add(doc.data.render.metadataCid);
+              if (doc.data?.item?.id) itemKeysToClean.add(doc.data.item.id);
+              if (doc.objectLayerRenderFramesId) renderFrameIds.push(doc.objectLayerRenderFramesId);
+              if (doc.atlasSpriteSheetId) atlasIds.push(doc.atlasSpriteSheetId);
             }
-          } 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,
-              userId: undefined, // CLI context has no authenticated user
-              options: { host, path },
-            });
-            logger.info(`Final SHA-256: ${finalized.sha256}`);
-            if (finalized.cid) {
-              logger.info(`ObjectLayer data pinned to IPFS – CID: ${finalized.cid}`);
+            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)`);
             }
-          } catch (finalizeError) {
-            logger.error('Failed to finalize SHA-256 / IPFS:', finalizeError);
-          }
 
-          logger.info(`✓ Generation complete for "${uniqueItemId}" (seed: ${genSeed}, frames: ${genFrameCount})`);
+            if (renderFrameIds.length > 0) {
+              const rfResult = await ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFrameIds } });
+              logger.info(`Dropped ${rfResult.deletedCount} ObjectLayerRenderFrames document(s)`);
+            }
 
-          // Log per-layer summary
-          if (multiFrameResult.frames.length > 0) {
-            const firstFrame = multiFrameResult.frames[0];
-            for (const layer of firstFrame.layers) {
-              logger.info(`  Layer "${layer.layerKey}" (${layer.layerId}): ${layer.keys.length} element(s)`);
+            if (cidsToUnpin.size > 0) {
+              const ipfsResult = await Ipfs.deleteMany({ cid: { $in: [...cidsToUnpin] } });
+              logger.info(`Dropped ${ipfsResult.deletedCount} Ipfs pin record(s)`);
+            }
+
+            let unpinCount = 0;
+            for (const cid of cidsToUnpin) {
+              const ok = await IpfsClient.unpinCid(cid);
+              if (ok) unpinCount++;
             }
+            let mfsCount = 0;
+            for (const itemKey of itemKeysToClean) {
+              const ok = await IpfsClient.removeMfsPath(`/object-layer/${itemKey}`);
+              if (ok) mfsCount++;
+            }
+            logger.info(
+              `IPFS cleanup: ${unpinCount}/${cidsToUnpin.size} CIDs unpinned, ${mfsCount}/${itemKeysToClean.size} MFS paths removed`,
+            );
+
+            const olResult = await ObjectLayer.deleteMany({ 'data.item.id': { $in: [...dropOlItemIds] } });
+            logger.info(`Dropped ${olResult.deletedCount} ObjectLayer document(s)`);
           }
+
+          // Drop thumbnail File documents (instance + maps), excluding shared ones
+          if (thumbFileIds.length > 0) {
+            const thumbResult = await File.deleteMany({ _id: { $in: thumbFileIds } });
+            logger.info(`Dropped ${thumbResult.deletedCount} File document(s) (thumbnails)`);
+          }
+
+          await CyberiaInstance.deleteOne({ code: instanceCode });
+          logger.info('Dropped CyberiaInstance', { code: instanceCode });
+          await CyberiaInstanceConf.deleteOne({ instanceCode });
+          logger.info('Dropped CyberiaInstanceConf', { instanceCode });
+        } else {
+          logger.info('No existing instance to drop', { code: instanceCode });
         }
+      }
 
-        await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
-      },
-    )
-    .description('Object layer management');
+      if (options.export === undefined && options.import === undefined && !options.drop) {
+        logger.error('Specify --export, --import, or --drop flag');
+      }
+
+      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+    });
 
   // ── chain: Hyperledger Besu / ERC-1155 lifecycle commands ────────────────
   const chain = program.command('chain').description('Hyperledger Besu chain & ERC-1155 ObjectLayerToken lifecycle');
@@ -1054,7 +3430,7 @@ try {
       // Use a Hardhat script via inline JS to call registerObjectLayer
       const registerScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const [deployer] = await ethers.getSigners();
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
@@ -1105,7 +3481,7 @@ try {
 
       const mintScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
           const tx = await token.mint('${options.to}', ${options.tokenId}, ${options.amount}, '0x');
@@ -1142,7 +3518,7 @@ try {
       const statusScript = `
         import hre from 'hardhat';
         import { readFileSync } from 'fs';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const provider = ethers.provider;
           const network = await provider.getNetwork();
@@ -1204,7 +3580,7 @@ try {
 
       const pauseScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const token = await ethers.getContractAt('ObjectLayerToken', '${deployment.address}');
           const tx = await token.pause();
@@ -1237,7 +3613,7 @@ try {
 
       const unpauseScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const token = await ethers.getContractAt('ObjectLayerToken', '${deployment.address}');
           const tx = await token.unpause();
@@ -1396,7 +3772,7 @@ try {
 
       const balanceScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
           const balance = await token.balanceOf('${options.address}', ${options.tokenId});
@@ -1453,7 +3829,7 @@ try {
 
       const transferScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const [signer] = await ethers.getSigners();
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
@@ -1509,7 +3885,7 @@ try {
 
       const burnScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
           const tx = await token.burn('${options.address}', ${options.tokenId}, ${options.amount});
@@ -1620,7 +3996,7 @@ try {
 
       const batchScript = `
         import hre from 'hardhat';
-        const { ethers } = hre;
+        const { ethers } = await hre.network.connect();
         async function main() {
           const [deployer] = await ethers.getSigners();
           const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
@@ -1653,6 +4029,216 @@ try {
       }
     });
 
+  const runner = program.command('run-workflow').description('Run a Cyberia script from the "scripts" directory');
+
+  runner
+    .command('import-default-items')
+    .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
+    .description('Import default Object Layer items, skill config, and dialogues into MongoDB')
+    .action(async (options) => {
+      const devFlag = options.dev ? ' --dev' : '';
+      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-skill-config${devFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}`);
+    });
+
+  runner
+    .command('seed-skill-config')
+    .option('--instance-code <code>', 'CyberiaInstance code to update (default: $INSTANCE_CODE env or "default")')
+    .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('Upsert default skillConfig entries into a CyberiaInstance document')
+    .action(async (options) => {
+      if (!options.envPath) options.envPath = `./.env`;
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      if (options.dev && process.env.DEFAULT_DEPLOY_ID) {
+        const devEnvPath = `./engine-private/conf/${process.env.DEFAULT_DEPLOY_ID}/.env.development`;
+        if (fs.existsSync(devEnvPath)) dotenv.config({ path: devEnvPath, override: true });
+      }
+
+      const deployId = process.env.DEFAULT_DEPLOY_ID;
+      const host = process.env.DEFAULT_DEPLOY_HOST;
+      const path = process.env.DEFAULT_DEPLOY_PATH;
+      const instanceCode = options.instanceCode || process.env.INSTANCE_CODE || 'default';
+
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      if (!fs.existsSync(confServerPath)) {
+        logger.error(`Server config not found: ${confServerPath}`);
+        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('seed-skill-config', { instanceCode, deployId, host, path, db });
+
+      await DataBaseProvider.load({ apis: ['cyberia-instance', 'cyberia-instance-conf'], host, path, db });
+
+      const CyberiaInstance = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaInstance;
+      const CyberiaInstanceConf = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaInstanceConf;
+
+      const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
+
+      if (!instance) {
+        logger.info(
+          `CyberiaInstance "${instanceCode}" not found — seeding skillConfig into conf using fallback defaults. ` +
+            `To link to a live instance, create or import it with: node bin/cyberia instance ${instanceCode} --import`,
+        );
+      }
+
+      // Always upsert the conf with DefaultSkillConfig — idempotent regardless of instance existence.
+      const conf = await CyberiaInstanceConf.findOneAndUpdate(
+        { instanceCode },
+        { $set: { skillConfig: DefaultSkillConfig } },
+        { upsert: true, returnDocument: 'after' },
+      );
+
+      // If a live instance exists, ensure its conf ref is linked.
+      if (instance && (!instance.conf || String(instance.conf) !== String(conf._id))) {
+        await CyberiaInstance.findByIdAndUpdate(instance._id, { conf: conf._id });
+      }
+
+      logger.info(
+        `skillConfig seeded for instance "${instanceCode}" (${DefaultSkillConfig.length} entries)`,
+        DefaultSkillConfig.map((e) => `${e.triggerItemId} → [${e.logicEventIds.join(', ')}]`),
+      );
+
+      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+    });
+
+  runner
+    .command('seed-dialogues')
+    .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('Upsert DefaultCyberiaDialogues into the cyberia-dialogue collection (idempotent)')
+    .action(async (options) => {
+      if (!options.envPath) options.envPath = `./.env`;
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      if (options.dev && process.env.DEFAULT_DEPLOY_ID) {
+        const devEnvPath = `./engine-private/conf/${process.env.DEFAULT_DEPLOY_ID}/.env.development`;
+        if (fs.existsSync(devEnvPath)) dotenv.config({ path: devEnvPath, 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}`);
+        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('seed-dialogues', { deployId, host, path, db });
+
+      await DataBaseProvider.load({ apis: ['cyberia-dialogue'], host, path, db });
+
+      const CyberiaDialogue = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaDialogue;
+
+      // Upsert each dialogue record keyed by (code, order) — idempotent.
+      let upserted = 0;
+      for (const dlg of DefaultCyberiaDialogues) {
+        await CyberiaDialogue.findOneAndUpdate(
+          { code: dlg.code, order: dlg.order },
+          { $set: { speaker: dlg.speaker, text: dlg.text, mood: dlg.mood } },
+          { upsert: true },
+        );
+        upserted++;
+      }
+
+      logger.info(`seed-dialogues: ${upserted} dialogue records upserted`);
+
+      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+    });
+
+  runner
+    .command('generate-semantic-examples')
+    .option('--seed <seed>', 'Base seed string (each type gets a unique suffix appended)', 'example')
+    .option('--frame-count <frameCount>', 'Number of frames to generate per item (default: 4)', parseInt)
+    .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
+    .option('--dev', 'Force development environment')
+    .description('Generate one procedural example of every registered semantic prefix')
+    .action(async (options) => {
+      const SEMANTIC_TYPES = [
+        // 'floor-desert',
+        // 'floor-grass',
+        // 'floor-water',
+        // 'floor-stone',
+        // 'floor-lava',
+        'skin-random',
+        'skin-dark',
+        'skin-light',
+        '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';
+      const frameCount = options.frameCount || 2;
+      const envFlag = options.envPath ? ` --env-path ${options.envPath}` : '';
+      const devFlag = options.dev ? ' --dev' : '';
+
+      logger.info(
+        `Generating ${SEMANTIC_TYPES.length} semantic examples (seed base: "${baseSeed}", frames: ${frameCount})`,
+      );
+
+      for (const prefix of SEMANTIC_TYPES) {
+        const seed = `${baseSeed}-${prefix}`;
+        const cmd = `node bin/cyberia ol ${prefix} --generate --seed ${seed} --frame-count ${frameCount}${envFlag}${devFlag}`;
+        logger.info(`  → ${cmd}`);
+        shellExec(cmd);
+      }
+
+      logger.info('All semantic examples generated.');
+    });
+
+  runner
+    .command('build-manifest')
+    .description('Build k8s resource manifest YAML files from templates')
+    .action(() => {
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' --kubeadm`);
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' --kind --dev`);
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' --kubeadm`);
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' --kind --dev`);
+    });
+
   if (underpostProgram.commands.find((c) => c._name == process.argv[2]))
     throw new Error('Trigger underpost passthrough');