cyberia 3.1.3 → 3.2.5

package/bin/cyberia.js

@@ -27,8 +27,8 @@ import {
   pngDirectoryIteratorByObjectLayerType,
   getKeyFramesDirectionsFromNumberFolderDirection,
   buildImgFromTile,
-  itemTypes,
 } from '../src/server/object-layer.js';
+import { ITEM_TYPES as itemTypes } from '../src/api/cyberia-instance-conf/cyberia-instance-conf.defaults.js';
 import { AtlasSpriteSheetGenerator } from '../src/server/atlas-sprite-sheet-generator.js';
 import {
   generateFrame,
@@ -42,6 +42,11 @@ import { program as underpostProgram } from '../src/cli/index.js';
 import crypto from 'crypto';
 import nodePath from 'path';
 import Underpost from '../src/index.js';
+import {
+  DefaultCyberiaItems,
+  DefaultSkillConfig,
+  DefaultCyberiaDialogues,
+} from '../src/client/components/cyberia-portal/CommonCyberiaPortal.js';
 
 /**
  * Connect to the project MongoDB instance using the standard env / conf layout.
@@ -103,7 +108,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 +124,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 +134,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 +143,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 +159,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 +181,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 +200,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 +230,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 +750,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 +773,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 +788,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 +818,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;
 
-              logger.info(`ObjectLayer created (atlas skipped for bulk import): ${objectLayerId}`);
-              console.log(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 ${existingOL ? 'updated' : 'created'} (atlas skipped for bulk import): ${objectLayerId}`,
+              );
+              console.log(objectLayer.toObject ? objectLayer.toObject() : objectLayer);
             }
           }
         }
@@ -527,6 +1343,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 +1367,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 +1385,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 +1410,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}`);
         }
 
@@ -745,6 +1587,16 @@ try {
               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);
@@ -760,6 +1612,16 @@ try {
               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);
@@ -768,6 +1630,7 @@ try {
             // 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;
@@ -811,7 +1674,6 @@ try {
               objectLayer: finalObjectLayer,
               ipfsClient: IpfsClient,
               createPinRecord,
-              userId: undefined, // CLI context has no authenticated user
               options: { host, path },
             });
             logger.info(`Final SHA-256: ${finalized.sha256}`);
@@ -838,6 +1700,641 @@ try {
     )
     .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('--drop', 'Drop existing instance, maps and object layers before importing')
+    .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-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 CyberiaMap = dbModels.CyberiaMap;
+      const ObjectLayer = dbModels.ObjectLayer;
+      const ObjectLayerRenderFrames = dbModels.ObjectLayerRenderFrames;
+      const AtlasSpriteSheet = dbModels.AtlasSpriteSheet;
+      const File = dbModels.File;
+      const Ipfs = dbModels.Ipfs;
+
+      // ── 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 });
+
+        fs.ensureDirSync(`${backupDir}/files`);
+
+        // 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;
+          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 (instance.thumbnail) {
+          await exportFileDoc(instance.thumbnail, `thumb-instance-${instanceCode}`);
+        }
+        logger.info('Exported CyberiaInstance', { code: instanceCode });
+
+        // 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);
+            }
+          }
+        }
+
+        // 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`);
+
+          const allCids = new Set();
+
+          for (const ol of objectLayers) {
+            const fileName = ol.data?.item?.id || ol._id.toString();
+            fs.writeJsonSync(`${backupDir}/object-layers/${fileName}.json`, ol, { spaces: 2 });
+
+            // Export ObjectLayerRenderFrames
+            if (ol.objectLayerRenderFramesId) {
+              const rf = await ObjectLayerRenderFrames.findById(ol.objectLayerRenderFramesId).lean();
+              if (rf) {
+                fs.writeJsonSync(`${backupDir}/render-frames/${fileName}.json`, rf, { spaces: 2 });
+              }
+            }
+
+            // Export AtlasSpriteSheet + its File
+            if (ol.atlasSpriteSheetId) {
+              const atlas = await AtlasSpriteSheet.findById(ol.atlasSpriteSheetId).lean();
+              if (atlas) {
+                fs.writeJsonSync(`${backupDir}/atlas-sprite-sheets/${fileName}.json`, atlas, { spaces: 2 });
+                if (atlas.fileId) {
+                  await exportFileDoc(atlas.fileId, `atlas-${fileName}`);
+                }
+                if (atlas.cid) allCids.add(atlas.cid);
+              }
+            }
+
+            // Collect CIDs for IPFS pin records
+            if (ol.cid) allCids.add(ol.cid);
+            if (ol.data?.render?.cid) allCids.add(ol.data.render.cid);
+            if (ol.data?.render?.metadataCid) allCids.add(ol.data.render.metadataCid);
+          }
+
+          // Export IPFS pin records for all collected CIDs
+          if (allCids.size > 0) {
+            const ipfsDocs = await Ipfs.find({ cid: { $in: [...allCids] } }).lean();
+            if (ipfsDocs.length > 0) {
+              fs.writeJsonSync(`${backupDir}/ipfs/pins.json`, ipfsDocs, { spaces: 2 });
+              logger.info(`Exported ${ipfsDocs.length} Ipfs pin record(s)`);
+            }
+          }
+
+          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) {
+          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);
+
+            // Query other instances/maps for shared thumbnail exclusion
+            const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
+
+            if (dropMapCodes.size > 0) {
+              const dropMaps = await CyberiaMap.find({ code: { $in: [...dropMapCodes] } }).lean();
+              const dropOlItemIds = new Set();
+              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);
+                  }
+                }
+              }
+
+              // Exclude OL item IDs referenced by maps outside this instance
+              const otherMaps = await CyberiaMap.find(
+                { code: { $nin: [...dropMapCodes] } },
+                { 'entities.objectLayerItemIds': 1, thumbnail: 1 },
+              ).lean();
+              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) {
+                // Gather ObjectLayers to collect related doc IDs and CIDs
+                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)`);
+              }
+
+              const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
+              logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap 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 });
+          } else {
+            logger.info('No existing instance to drop', { code: instanceCode });
+          }
+        }
+
+        // 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 });
+            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 });
+            await ObjectLayer.create(olData);
+            olCount++;
+          }
+          logger.info(`Imported ${olCount} ObjectLayer document(s)`);
+        }
+
+        // 5. Import IPFS pin records and re-pin CIDs
+        const ipfsFile = `${backupDir}/ipfs/pins.json`;
+        if (fs.existsSync(ipfsFile)) {
+          const ipfsDocs = fs.readJsonSync(ipfsFile);
+          let ipfsCount = 0;
+          const pinnedCids = new Set();
+          for (const doc of ipfsDocs) {
+            await Ipfs.deleteOne({ _id: doc._id });
+            await Ipfs.create(doc);
+            ipfsCount++;
+            if (doc.cid) pinnedCids.add(doc.cid);
+          }
+          logger.info(`Imported ${ipfsCount} Ipfs pin record(s)`);
+
+          // Re-pin CIDs to IPFS Kubo + Cluster
+          let repinCount = 0;
+          for (const cid of pinnedCids) {
+            const ok = await IpfsClient.pinCid(cid);
+            if (ok) repinCount++;
+          }
+          logger.info(`IPFS re-pin: ${repinCount}/${pinnedCids.size} CIDs pinned`);
+        }
+
+        // 6. 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}`);
+            // Remove any existing map with this code (may have different _id)
+            await CyberiaMap.deleteOne({ code: mapData.code });
+            // Also remove if an old doc with this _id exists
+            await CyberiaMap.deleteOne({ _id: mapData._id });
+            await CyberiaMap.create(mapData);
+            mapCount++;
+          }
+          logger.info(`Imported ${mapCount} CyberiaMap document(s)`);
+        }
+
+        // 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}`);
+        }
+
+        logger.info('Instance import completed', { backupDir });
+      }
+
+      // ── 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);
+
+          // Query other instances for shared thumbnail exclusion
+          const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
+
+          if (dropMapCodes.size > 0) {
+            const dropMaps = await CyberiaMap.find({ code: { $in: [...dropMapCodes] } }).lean();
+            const dropOlItemIds = new Set();
+            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);
+                }
+              }
+            }
+
+            // Exclude OL item IDs referenced by maps outside this instance
+            const otherMaps = await CyberiaMap.find(
+              { code: { $nin: [...dropMapCodes] } },
+              { 'entities.objectLayerItemIds': 1, thumbnail: 1 },
+            ).lean();
+            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 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);
+              }
+
+              if (atlasIds.length > 0) {
+                const atlasDocs = await AtlasSpriteSheet.find({ _id: { $in: atlasIds } }, { fileId: 1, cid: 1 }).lean();
+                const atlasFileIds = atlasDocs.map((a) => a.fileId).filter(Boolean);
+                for (const atlas of atlasDocs) {
+                  if (atlas.cid) cidsToUnpin.add(atlas.cid);
+                }
+                if (atlasFileIds.length > 0) {
+                  const fileResult = await File.deleteMany({ _id: { $in: atlasFileIds } });
+                  logger.info(`Dropped ${fileResult.deletedCount} File document(s) (atlas)`);
+                }
+                const atlasResult = await AtlasSpriteSheet.deleteMany({ _id: { $in: atlasIds } });
+                logger.info(`Dropped ${atlasResult.deletedCount} AtlasSpriteSheet document(s)`);
+              }
+
+              if (renderFrameIds.length > 0) {
+                const rfResult = await ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFrameIds } });
+                logger.info(`Dropped ${rfResult.deletedCount} ObjectLayerRenderFrames document(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)`);
+            }
+
+            const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
+            logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap 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 });
+        } else {
+          logger.info('No existing instance to drop', { code: instanceCode });
+        }
+      }
+
+      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 +2551,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 +2602,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 +2639,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 +2701,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 +2734,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 +2893,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 +2950,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 +3006,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 +3117,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 +3150,186 @@ 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 (itemId, order) — idempotent.
+      let upserted = 0;
+      for (const dlg of DefaultCyberiaDialogues) {
+        await CyberiaDialogue.findOneAndUpdate(
+          { itemId: dlg.itemId, 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',
+      ];
+
+      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.');
+    });
+
   if (underpostProgram.commands.find((c) => c._name == process.argv[2]))
     throw new Error('Trigger underpost passthrough');