cyberia 3.0.3 → 3.2.5

package/bin/index.js

@@ -18,14 +18,17 @@ import { Command } from 'commander';
 import fs from 'fs-extra';
 import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.js';
+import { generateBesuManifests, deployBesu, removeBesu } from '../src/server/besu-genesis-generator.js';
 import { DataBaseProvider } from '../src/db/DataBaseProvider.js';
+import { loadConfServerJson } from '../src/server/conf.js';
 import {
   ObjectLayerEngine,
+  resolveCanonicalCid,
   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,
@@ -39,6 +42,47 @@ 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.
+ *
+ * @async
+ * @function connectDbForChain
+ * @param {Object} params
+ * @param {string} params.envPath   – path to .env file.
+ * @param {string} [params.mongoHost] – optional mongo host override.
+ * @returns {Promise<{ ObjectLayer: import('mongoose').Model, host: string, path: string }>}
+ * @memberof CyberiaCLI
+ */
+async function connectDbForChain({ envPath, mongoHost }) {
+  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)) {
+    throw new Error(`Server config not found: ${confServerPath}. Ensure DEFAULT_DEPLOY_ID is set.`);
+  }
+  const confServer = loadConfServerJson(confServerPath, { resolve: true });
+  const { db } = confServer[host][path];
+
+  db.host = mongoHost ? mongoHost : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
+
+  await DataBaseProvider.load({
+    apis: ['object-layer'],
+    host,
+    path,
+    db,
+  });
+
+  const ObjectLayer = DataBaseProvider.instance[`${host}${path}`].mongoose.models.ObjectLayer;
+  return { ObjectLayer, host, path };
+}
 
 /** @type {Function} */
 const logger = loggerFactory(import.meta);
@@ -64,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)
@@ -76,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.
@@ -83,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.
@@ -91,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.
@@ -104,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: '',
@@ -121,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} */
@@ -129,10 +197,14 @@ try {
         const path = process.env.DEFAULT_DEPLOY_PATH;
 
         const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-        const confServer = JSON.parse(fs.readFileSync(confServerPath, 'utf8'));
+        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,
@@ -158,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.
@@ -182,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,
@@ -192,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
@@ -204,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,
@@ -222,116 +818,375 @@ try {
             const shouldGenerateAtlas = !isImportAll;
 
             if (shouldGenerateAtlas) {
-              // Use the centralized createObjectLayerDocuments which handles atlas generation
-              // Since we're in CLI context without a full Express req/res, we build a minimal
-              // atlas generation flow using AtlasSpriteSheetGenerator directly after creation.
-              const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
-                ObjectLayer,
-                ObjectLayerRenderFrames,
-                objectLayerRenderFramesData: entry.objectLayerRenderFramesData,
-                objectLayerData: { data: entry.data },
-                createOptions: {
-                  generateAtlas: false,
-                },
-              });
+              // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
+              const existingOL = await ObjectLayer.findOne({ 'data.item.id': objectLayerId });
+              let objectLayer;
+
+              if (existingOL) {
+                // ── Cut-over consistency: stage everything in memory before touching the live document ──
+                logger.info(`ObjectLayer '${objectLayerId}' already exists (${existingOL._id}), staging update...`);
+
+                // 1. Prepare staging data entirely in memory (no DB writes yet)
+                const stagingData = JSON.parse(JSON.stringify(entry.data));
+                if (!stagingData.render) stagingData.render = {};
+                stagingData.render.cid = '';
+                stagingData.render.metadataCid = '';
+
+                // 2. Generate atlas, pin to IPFS, compute SHA-256 — all in memory
+                let cutoverReady = false;
+                let stagingFileDoc = null;
+                let stagingAtlasDoc = null;
+                let stagingCid = '';
+                let stagingSha256 = '';
+                try {
+                  const itemKey = objectLayerId;
 
-              // Generate atlas sprite sheet for individual imports
-              try {
-                const itemKey = objectLayer.data.item.id;
-                const populatedObjectLayer = await ObjectLayer.findById(objectLayer._id).populate(
-                  'objectLayerRenderFramesId',
-                );
+                  // Generate atlas from in-memory render frames data (plain object, no DB doc needed)
+                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+                    entry.objectLayerRenderFramesData,
+                    itemKey,
+                    20,
+                  );
 
-                const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-                  populatedObjectLayer.objectLayerRenderFramesId,
-                  itemKey,
-                  20,
-                );
+                  stagingFileDoc = await new File({
+                    name: `${itemKey}-atlas.png`,
+                    data: buffer,
+                    size: buffer.length,
+                    mimetype: 'image/png',
+                    md5: crypto.createHash('md5').update(buffer).digest('hex'),
+                  }).save();
 
-                const fileDoc = await new File({
-                  name: `${itemKey}-atlas.png`,
-                  data: buffer,
-                  size: buffer.length,
-                  mimetype: 'image/png',
-                  md5: crypto.createHash('md5').update(buffer).digest('hex'),
-                }).save();
+                  let importAtlasCid = '';
+                  let importAtlasMetadataCid = '';
+                  try {
+                    const ipfsResult = await IpfsClient.addBufferToIpfs(
+                      buffer,
+                      `${itemKey}_atlas_sprite_sheet.png`,
+                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+                    );
+                    if (ipfsResult) {
+                      importAtlasCid = ipfsResult.cid;
+                      logger.info(`[staging] Atlas pinned to IPFS – CID: ${importAtlasCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: importAtlasCid,
+                          resourceType: 'atlas-sprite-sheet',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
+                  }
 
-                // Pin atlas PNG to IPFS
-                let importAtlasCid = '';
-                let importAtlasMetadataCid = '';
-                try {
-                  const ipfsResult = await IpfsClient.addBufferToIpfs(
-                    buffer,
-                    `${itemKey}_atlas_sprite_sheet.png`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-                  );
-                  if (ipfsResult) {
-                    importAtlasCid = ipfsResult.cid;
-                    logger.info(`Atlas sprite sheet pinned to IPFS – CID: ${importAtlasCid}`);
+                  try {
+                    const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
+                      metadata,
+                      `${itemKey}_atlas_sprite_sheet_metadata.json`,
+                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+                    );
+                    if (metadataIpfsResult) {
+                      importAtlasMetadataCid = metadataIpfsResult.cid;
+                      logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: importAtlasMetadataCid,
+                          resourceType: 'atlas-metadata',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
                   }
-                } catch (ipfsError) {
-                  logger.warn('Failed to add atlas sprite sheet to IPFS:', ipfsError.message);
+
+                  stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+                  if (stagingAtlasDoc) {
+                    if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
+                    stagingAtlasDoc.fileId = stagingFileDoc._id;
+                    stagingAtlasDoc.cid = importAtlasCid;
+                    stagingAtlasDoc.metadata = metadata;
+                    await stagingAtlasDoc.save();
+                  } else {
+                    stagingAtlasDoc = await new AtlasSpriteSheet({
+                      fileId: stagingFileDoc._id,
+                      cid: importAtlasCid,
+                      metadata,
+                    }).save();
+                  }
+
+                  // Finalize staging data in memory with render CIDs
+                  stagingData.render.cid = importAtlasCid;
+                  stagingData.render.metadataCid = importAtlasMetadataCid;
+
+                  // Pin data JSON to IPFS (compute final SHA-256 in memory)
+                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                  try {
+                    const ipfsDataResult = await IpfsClient.addJsonToIpfs(
+                      stagingData,
+                      `${itemKey}_data.json`,
+                      `/object-layer/${itemKey}/${itemKey}_data.json`,
+                    );
+                    if (ipfsDataResult) {
+                      stagingCid = ipfsDataResult.cid;
+                      logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: stagingCid,
+                          resourceType: 'object-layer-data',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create data pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
+                  }
+
+                  cutoverReady = true;
+                  logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for cut-over`);
+                } catch (atlasError) {
+                  logger.error(`[staging] Failed for ${objectLayerId}, live document untouched:`, atlasError);
                 }
 
-                // Pin atlas metadata JSON to IPFS (fast-json-stable-stringify)
-                try {
-                  const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-                    metadata,
-                    `${itemKey}_atlas_sprite_sheet_metadata.json`,
-                    `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-                  );
-                  if (metadataIpfsResult) {
-                    importAtlasMetadataCid = metadataIpfsResult.cid;
-                    logger.info(`Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
+                // 3. Atomic cut-over: create new RenderFrames, swap live ObjectLayer in a single update
+                if (cutoverReady) {
+                  const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
+                  const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
+
+                  await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                    data: stagingData,
+                    sha256: stagingSha256,
+                    cid: stagingCid,
+                    objectLayerRenderFramesId: newRenderFrames._id,
+                    atlasSpriteSheetId: stagingAtlasDoc._id,
+                  });
+
+                  if (oldRenderFramesId) {
+                    await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
                   }
-                } catch (ipfsError) {
-                  logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
+                  logger.info(`[cut-over] Live document ${existingOL._id} updated atomically`);
+                } else {
+                  if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
+                  logger.warn(`[cut-over] Staging rolled back for ${objectLayerId}, live document preserved`);
                 }
 
-                let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+                objectLayer = await ObjectLayer.findById(existingOL._id);
+              } else {
+                // ── New item: stage everything before creating (same cut-over pattern) ──
+                logger.info(`ObjectLayer '${objectLayerId}' is new, staging creation...`);
+
+                const itemKey = objectLayerId;
+                const stagingData = JSON.parse(JSON.stringify(entry.data));
+                if (!stagingData.render) stagingData.render = {};
+                stagingData.render.cid = '';
+                stagingData.render.metadataCid = '';
+
+                let cutoverReady = false;
+                let stagingFileDoc = null;
+                let stagingAtlasDoc = null;
+                let stagingCid = '';
+                let stagingSha256 = '';
+                try {
+                  const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+                    entry.objectLayerRenderFramesData,
+                    itemKey,
+                    20,
+                  );
 
-                if (atlasDoc) {
-                  atlasDoc.fileId = fileDoc._id;
-                  atlasDoc.cid = importAtlasCid;
-                  atlasDoc.metadata = metadata;
-                  await atlasDoc.save();
-                  logger.info(`Updated existing AtlasSpriteSheet document: ${atlasDoc._id}`);
-                } else {
-                  atlasDoc = await new AtlasSpriteSheet({
-                    fileId: fileDoc._id,
-                    cid: importAtlasCid,
-                    metadata,
+                  stagingFileDoc = await new File({
+                    name: `${itemKey}-atlas.png`,
+                    data: buffer,
+                    size: buffer.length,
+                    mimetype: 'image/png',
+                    md5: crypto.createHash('md5').update(buffer).digest('hex'),
                   }).save();
-                  logger.info(`Created new AtlasSpriteSheet document: ${atlasDoc._id}`);
-                }
 
-                populatedObjectLayer.atlasSpriteSheetId = atlasDoc._id;
-                if (!populatedObjectLayer.data.render) populatedObjectLayer.data.render = {};
-                populatedObjectLayer.data.render.cid = importAtlasCid;
-                populatedObjectLayer.data.render.metadataCid = importAtlasMetadataCid;
-                populatedObjectLayer.markModified('data.render');
-                await populatedObjectLayer.save();
+                  let importAtlasCid = '';
+                  let importAtlasMetadataCid = '';
+                  try {
+                    const ipfsResult = await IpfsClient.addBufferToIpfs(
+                      buffer,
+                      `${itemKey}_atlas_sprite_sheet.png`,
+                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+                    );
+                    if (ipfsResult) {
+                      importAtlasCid = ipfsResult.cid;
+                      logger.info(`[staging] Atlas pinned to IPFS – CID: ${importAtlasCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: importAtlasCid,
+                          resourceType: 'atlas-sprite-sheet',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create atlas pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to add atlas to IPFS:', ipfsError.message);
+                  }
 
-                logger.info(`Atlas sprite sheet completed for item: ${itemKey}`);
-              } catch (atlasError) {
-                logger.error(`Failed to generate atlas for ${objectLayerId}:`, atlasError);
+                  try {
+                    const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
+                      metadata,
+                      `${itemKey}_atlas_sprite_sheet_metadata.json`,
+                      `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+                    );
+                    if (metadataIpfsResult) {
+                      importAtlasMetadataCid = metadataIpfsResult.cid;
+                      logger.info(`[staging] Atlas metadata pinned to IPFS – CID: ${importAtlasMetadataCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: importAtlasMetadataCid,
+                          resourceType: 'atlas-metadata',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create atlas-metadata pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to add atlas metadata to IPFS:', ipfsError.message);
+                  }
+
+                  stagingAtlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+                  if (stagingAtlasDoc) {
+                    if (stagingAtlasDoc.fileId) await File.findByIdAndDelete(stagingAtlasDoc.fileId);
+                    stagingAtlasDoc.fileId = stagingFileDoc._id;
+                    stagingAtlasDoc.cid = importAtlasCid;
+                    stagingAtlasDoc.metadata = metadata;
+                    await stagingAtlasDoc.save();
+                  } else {
+                    stagingAtlasDoc = await new AtlasSpriteSheet({
+                      fileId: stagingFileDoc._id,
+                      cid: importAtlasCid,
+                      metadata,
+                    }).save();
+                  }
+
+                  stagingData.render.cid = importAtlasCid;
+                  stagingData.render.metadataCid = importAtlasMetadataCid;
+
+                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                  try {
+                    const ipfsDataResult = await IpfsClient.addJsonToIpfs(
+                      stagingData,
+                      `${itemKey}_data.json`,
+                      `/object-layer/${itemKey}/${itemKey}_data.json`,
+                    );
+                    if (ipfsDataResult) {
+                      stagingCid = ipfsDataResult.cid;
+                      logger.info(`[staging] Data JSON pinned to IPFS – CID: ${stagingCid}`);
+                      try {
+                        await createPinRecord({
+                          cid: stagingCid,
+                          resourceType: 'object-layer-data',
+                          mfsPath: `/object-layer/${itemKey}/${itemKey}_data.json`,
+                          options: { host, path },
+                        });
+                      } catch (prErr) {
+                        logger.warn('[staging] Failed to create data pin record:', prErr.message);
+                      }
+                    }
+                  } catch (ipfsError) {
+                    logger.warn('[staging] Failed to pin data JSON to IPFS:', ipfsError.message);
+                  }
+
+                  cutoverReady = true;
+                  logger.info(`[staging] Item '${itemKey}' fully staged in memory, ready for creation`);
+                } catch (atlasError) {
+                  logger.error(`[staging] Failed for ${objectLayerId}, no document created:`, atlasError);
+                }
+
+                if (cutoverReady) {
+                  const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
+                  objectLayer = await ObjectLayer.create({
+                    data: stagingData,
+                    sha256: stagingSha256,
+                    cid: stagingCid,
+                    objectLayerRenderFramesId: newRenderFrames._id,
+                    atlasSpriteSheetId: stagingAtlasDoc._id,
+                  });
+                  logger.info(`[cut-over] New ObjectLayer ${objectLayer._id} created with all CIDs populated`);
+                } else {
+                  if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
+                  logger.warn(`[cut-over] Staging failed for ${objectLayerId}, no ObjectLayer created`);
+                  continue;
+                }
               }
 
-              console.log(objectLayer);
+              // Reload final state to include CID and render updates
+              const finalObjectLayer = await ObjectLayer.findById((objectLayer._id || objectLayer).toString()).populate(
+                'objectLayerRenderFramesId',
+              );
+              console.log(finalObjectLayer.toObject());
             } else {
+              // --import all: skip items that already exist in the database
+              if (existingItemIds.has(objectLayerId)) continue;
+
               // --import all: create documents without atlas generation
-              const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
-                ObjectLayer,
-                ObjectLayerRenderFrames,
-                objectLayerRenderFramesData: entry.objectLayerRenderFramesData,
-                objectLayerData: { data: entry.data },
-                createOptions: {
-                  generateAtlas: false,
-                },
-              });
+              const existingOL = await ObjectLayer.findOne({ 'data.item.id': objectLayerId });
+              let objectLayer;
+
+              if (existingOL) {
+                logger.info(
+                  `ObjectLayer '${objectLayerId}' already exists (${existingOL._id}), staging update (atlas skipped)...`,
+                );
+
+                // ── In-memory staging (no atlas) ──────────────────────
+                const stagingData = JSON.parse(JSON.stringify(entry.data));
+                if (!stagingData.render) stagingData.render = {};
+                stagingData.render.cid = '';
+                stagingData.render.metadataCid = '';
+                const stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+
+                // Atomic cut-over: create new RenderFrames, swap live doc, delete old
+                const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
+                const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
+
+                await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                  data: stagingData,
+                  sha256: stagingSha256,
+                  objectLayerRenderFramesId: newRenderFrames._id,
+                });
+
+                if (oldRenderFramesId) {
+                  await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
+                }
 
-              logger.info(`ObjectLayer created (atlas skipped for bulk import): ${objectLayerId}`);
-              console.log(objectLayer);
+                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);
             }
           }
         }
@@ -384,7 +1239,9 @@ try {
 
           if (frameIndexNum >= frames.length) {
             logger.error(
-              `Frame index ${frameIndexNum} out of range. Available frames: 0-${frames.length - 1} for direction ${objectLayerFrameDirection}`,
+              `Frame index ${frameIndexNum} out of range. Available frames: 0-${
+                frames.length - 1
+              } for direction ${objectLayerFrameDirection}`,
             );
             process.exit(1);
           }
@@ -486,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);
@@ -501,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);
@@ -510,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;
@@ -534,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}`);
         }
 
@@ -704,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);
@@ -719,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);
@@ -727,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;
@@ -770,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}`);
@@ -797,7 +1700,1638 @@ try {
     )
     .description('Object layer management');
 
-  if (process.argv[2] == 'underpost') throw new Error('Trigger underpost passthrough');
+  // ── 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');
+
+  chain
+    .command('deploy')
+    .description(
+      'Deploy Besu IBFT2 network to kubeadm Kubernetes cluster.\n' +
+        'Dynamically generates fresh validator keys, genesis, extraData, enode URLs,\n' +
+        'and all K8s manifests in manifests/besu/ before applying via kustomize.\n' +
+        'Each invocation creates a unique chain identity (new keys, new extraData).',
+    )
+    .option('--pull-image', 'Pull Besu container images into containerd before deployment')
+    .option('--validators <count>', 'Number of IBFT2 validators (default: 4)', '4')
+    .option('--chain-id <chainId>', 'Chain ID for the network (default: 777771)', '777771')
+    .option('--block-period <seconds>', 'IBFT2 block period in seconds (default: 5)', '5')
+    .option('--epoch-length <length>', 'IBFT2 epoch length (default: 30000)', '30000')
+    .option('--coinbase-address <address>', 'Coinbase deployer address (auto-detected from engine-private if omitted)')
+    .option('--besu-image <image>', 'Besu container image', 'hyperledger/besu:24.12.1')
+    .option('--curl-image <image>', 'Curl init container image', 'curlimages/curl:8.11.1')
+    .option('--node-port-rpc <port>', 'NodePort for external JSON-RPC access', '30545')
+    .option('--node-port-ws <port>', 'NodePort for external WebSocket access', '30546')
+    .option('--namespace <ns>', 'Kubernetes namespace for Besu resources', 'besu')
+    .option('--skip-generate', 'Skip manifest generation and use existing manifests/besu/ as-is')
+    .option('--skip-wait', 'Skip waiting for validators to reach Running state')
+    .action(async (options) => {
+      const result = await deployBesu({
+        pullImage: !!options.pullImage,
+        validators: parseInt(options.validators, 10),
+        chainId: parseInt(options.chainId, 10),
+        blockPeriodSeconds: parseInt(options.blockPeriod, 10),
+        epochLength: parseInt(options.epochLength, 10),
+        coinbaseAddress: options.coinbaseAddress || '',
+        besuImage: options.besuImage,
+        curlImage: options.curlImage,
+        nodePortRpc: parseInt(options.nodePortRpc, 10),
+        nodePortWs: parseInt(options.nodePortWs, 10),
+        namespace: options.namespace,
+        skipGenerate: !!options.skipGenerate,
+        skipWait: !!options.skipWait,
+        manifestsPath: './manifests/besu',
+        networkConfigDir: './hardhat/networks',
+        privateKeysDir: './engine-private/eth-networks/besu/validators',
+      });
+      if (!result && !options.skipGenerate) {
+        process.exit(1);
+      }
+    });
+
+  chain
+    .command('remove')
+    .description('Remove Besu IBFT2 network from kubeadm Kubernetes cluster')
+    .option('--namespace <ns>', 'Kubernetes namespace for Besu resources', 'besu')
+    .option('--clean-keys', 'Also remove generated validator keys from engine-private/')
+    .option('--clean-manifests', 'Also remove the generated manifests/besu/ directory')
+    .action(async (options) => {
+      removeBesu({
+        namespace: options.namespace,
+        cleanKeys: !!options.cleanKeys,
+        cleanManifests: !!options.cleanManifests,
+        manifestsPath: './manifests/besu',
+        privateKeysDir: './engine-private/eth-networks/besu/validators',
+      });
+    });
+
+  chain
+    .command('generate-manifests')
+    .description(
+      'Generate fresh Besu IBFT2 K8s manifests without deploying.\n' +
+        'Creates new validator keys, genesis, extraData, and all manifest files\n' +
+        'in manifests/besu/. Use "cyberia chain deploy --skip-generate" to apply them later.',
+    )
+    .option('--validators <count>', 'Number of IBFT2 validators (default: 4)', '4')
+    .option('--chain-id <chainId>', 'Chain ID for the network (default: 777771)', '777771')
+    .option('--block-period <seconds>', 'IBFT2 block period in seconds (default: 5)', '5')
+    .option('--epoch-length <length>', 'IBFT2 epoch length (default: 30000)', '30000')
+    .option('--coinbase-address <address>', 'Coinbase deployer address (auto-detected from engine-private if omitted)')
+    .option('--besu-image <image>', 'Besu container image', 'hyperledger/besu:24.12.1')
+    .option('--curl-image <image>', 'Curl init container image', 'curlimages/curl:8.11.1')
+    .option('--node-port-rpc <port>', 'NodePort for external JSON-RPC access', '30545')
+    .option('--node-port-ws <port>', 'NodePort for external WebSocket access', '30546')
+    .option('--namespace <ns>', 'Kubernetes namespace for Besu resources', 'besu')
+    .option('--output-dir <dir>', 'Output directory for manifests', './manifests/besu')
+    .action(async (options) => {
+      try {
+        const result = await generateBesuManifests({
+          outputDir: options.outputDir,
+          networkConfigDir: './hardhat/networks',
+          validatorCount: parseInt(options.validators, 10),
+          namespace: options.namespace,
+          chainId: parseInt(options.chainId, 10),
+          blockPeriodSeconds: parseInt(options.blockPeriod, 10),
+          epochLength: parseInt(options.epochLength, 10),
+          requestTimeoutSeconds: 10,
+          coinbaseAddress: options.coinbaseAddress || '',
+          besuImage: options.besuImage,
+          curlImage: options.curlImage,
+          nodePortRpc: parseInt(options.nodePortRpc, 10),
+          nodePortWs: parseInt(options.nodePortWs, 10),
+          savePrivateKeys: true,
+          privateKeysDir: './engine-private/eth-networks/besu/validators',
+        });
+        logger.info('');
+        logger.info('Manifests generated successfully. To deploy:');
+        logger.info('  cyberia chain deploy --skip-generate');
+        logger.info('');
+        logger.info('Validator summary:');
+        for (const v of result.validators) {
+          logger.info(`  Validator ${v.index}: address=${v.address} pubkey=${v.publicKey.slice(0, 16)}...`);
+        }
+      } catch (err) {
+        logger.error(`Manifest generation failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  chain
+    .command('deploy-contract')
+    .description('Deploy ObjectLayerToken (ERC-1155) contract to a Besu network via Hardhat')
+    .option('--network <network>', 'Hardhat network name (besu-k8s for kubeadm cluster)', 'besu-k8s')
+    .action(async (options) => {
+      const network = options.network || 'besu-k8s';
+      logger.info(`Deploying ObjectLayerToken to network: ${network}`);
+      shellExec(`cd hardhat && npx hardhat run scripts/deployObjectLayerToken.js --network ${network}`);
+      logger.info('Contract deployment complete. Check hardhat/deployments/ for the artifact.');
+    });
+
+  chain
+    .command('compile')
+    .description('Compile Solidity contracts via Hardhat')
+    .action(async () => {
+      logger.info('Compiling contracts...');
+      shellExec('cd hardhat && npx hardhat compile');
+      logger.info('Compilation complete.');
+    });
+
+  chain
+    .command('test')
+    .description('Run Hardhat tests for ObjectLayerToken')
+    .action(async () => {
+      logger.info('Running ObjectLayerToken tests...');
+      shellExec('cd hardhat && npx hardhat test test/ObjectLayerToken.js');
+    });
+
+  chain
+    .command('register')
+    .description(
+      'Register an Object Layer item on-chain via the deployed ObjectLayerToken contract.\n' +
+        'When --from-db is set the canonical CID is resolved from MongoDB (fast-json-stable-stringify of objectLayer.data).\n' +
+        'This guarantees the on-chain metadataCid always matches the content-addressed IPFS payload.',
+    )
+    .requiredOption('--item-id <itemId>', 'Human-readable item identifier (e.g. "hatchet")')
+    .option('--metadata-cid <cid>', 'IPFS metadata CID for the item (ignored when --from-db is set)', '')
+    .option('--from-db', 'Resolve the canonical CID from the ObjectLayer MongoDB document (recommended)')
+    .option('--supply <supply>', 'Initial token supply (1 = non-fungible, >1 = semi-fungible)', '1')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .option('--mongo-host <mongoHost>', 'MongoDB host override (used with --from-db)')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      // ── Resolve canonical CID ───────────────────────────────────────
+      let canonicalCid = options.metadataCid || '';
+
+      if (options.fromDb) {
+        try {
+          const { ObjectLayer, host, path } = await connectDbForChain({
+            envPath: options.envPath,
+            mongoHost: options.mongoHost,
+          });
+          const resolved = await resolveCanonicalCid({
+            itemId: options.itemId,
+            ObjectLayer,
+            ipfsClient: IpfsClient,
+            options: { host, path },
+          });
+
+          if (options.metadataCid && options.metadataCid !== resolved.cid) {
+            logger.warn(
+              `Provided --metadata-cid "${options.metadataCid}" differs from canonical CID "${resolved.cid}" (source: ${resolved.source}).`,
+            );
+            logger.warn('Using the canonical CID to ensure on-chain integrity.');
+          }
+
+          canonicalCid = resolved.cid;
+          logger.info(`Canonical CID resolved (${resolved.source}): ${canonicalCid}`);
+          logger.info(`  SHA-256: ${resolved.sha256}`);
+
+          // Close the DB connection after resolving
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+        } catch (dbErr) {
+          logger.error(`Failed to resolve canonical CID from database: ${dbErr.message}`);
+          process.exit(1);
+        }
+      } else if (!canonicalCid) {
+        logger.warn(
+          'No --metadata-cid provided and --from-db not set. The on-chain metadataCid will be empty.\n' +
+            'Consider using --from-db to automatically resolve the canonical CID from the database.',
+        );
+      }
+
+      logger.info(`Registering Object Layer item "${options.itemId}" on contract ${contractAddress}`);
+      logger.info(`  Metadata CID: ${canonicalCid || '(none)'}`);
+      logger.info(`  Supply: ${options.supply}`);
+
+      // Use a Hardhat script via inline JS to call registerObjectLayer
+      const registerScript = `
+        import hre from 'hardhat';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const [deployer] = await ethers.getSigners();
+          const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
+          const tx = await token.registerObjectLayer(
+            deployer.address,
+            '${options.itemId}',
+            '${canonicalCid}',
+            ${options.supply},
+            '0x'
+          );
+          const receipt = await tx.wait();
+          const tokenId = await token.computeTokenId('${options.itemId}');
+          console.log('Registered tokenId:', tokenId.toString());
+          console.log('Tx hash:', receipt.hash);
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_register_tmp.js';
+      fs.writeFileSync(tmpScript, registerScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_register_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  chain
+    .command('mint')
+    .description('Mint additional tokens for an existing token ID')
+    .requiredOption('--token-id <tokenId>', 'ERC-1155 token ID (uint256)')
+    .requiredOption('--to <address>', 'Recipient address')
+    .requiredOption('--amount <amount>', 'Amount to mint')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      logger.info(`Minting ${options.amount} of token ID ${options.tokenId} to ${options.to}`);
+
+      const mintScript = `
+        import hre from 'hardhat';
+        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');
+          const receipt = await tx.wait();
+          console.log('Mint tx hash:', receipt.hash);
+          const balance = await token.balanceOf('${options.to}', ${options.tokenId});
+          console.log('New balance:', balance.toString());
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_mint_tmp.js';
+      fs.writeFileSync(tmpScript, mintScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_mint_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  chain
+    .command('status')
+    .description('Query Besu chain and ObjectLayerToken contract status')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+
+      logger.info('── Besu Chain Status ──');
+
+      // Check node connectivity
+      const statusScript = `
+        import hre from 'hardhat';
+        import { readFileSync } from 'fs';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const provider = ethers.provider;
+          const network = await provider.getNetwork();
+          const blockNumber = await provider.getBlockNumber();
+          const [deployer] = await ethers.getSigners();
+          const balance = await provider.getBalance(deployer.address);
+          console.log('Network:', JSON.stringify({
+            name: network.name,
+            chainId: network.chainId.toString(),
+            blockNumber,
+            deployerAddress: deployer.address,
+            deployerBalance: ethers.formatEther(balance) + ' ETH'
+          }, null, 2));
+
+          ${
+            fs.existsSync(artifactPath)
+              ? `
+          const deployment = JSON.parse(readFileSync('${nodePath.resolve(artifactPath)}', 'utf8'));
+          try {
+            const token = await ethers.getContractAt('ObjectLayerToken', deployment.address);
+            const cryptokoynSupply = await token['totalSupply(uint256)'](0);
+            const deployerCKY = await token.balanceOf(deployer.address, 0);
+            const isPaused = false; // pausable check would need try-catch
+            console.log('Contract:', JSON.stringify({
+              address: deployment.address,
+              cryptokoynTotalSupply: ethers.formatEther(cryptokoynSupply) + ' CKY',
+              deployerCryptokoynBalance: ethers.formatEther(deployerCKY) + ' CKY',
+            }, null, 2));
+          } catch (e) {
+            console.log('Contract not accessible:', e.message);
+          }
+          `
+              : `console.log('No deployment artifact found for network ${options.network}.');`
+          }
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_status_tmp.js';
+      fs.writeFileSync(tmpScript, statusScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_status_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  chain
+    .command('pause')
+    .description('Pause all token transfers on the ObjectLayerToken contract (emergency governance)')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .action(async (options) => {
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+
+      const pauseScript = `
+        import hre from 'hardhat';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const token = await ethers.getContractAt('ObjectLayerToken', '${deployment.address}');
+          const tx = await token.pause();
+          await tx.wait();
+          console.log('Contract PAUSED. All transfers are frozen.');
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_pause_tmp.js';
+      fs.writeFileSync(tmpScript, pauseScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_pause_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  chain
+    .command('unpause')
+    .description('Unpause token transfers on the ObjectLayerToken contract')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .action(async (options) => {
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+
+      const unpauseScript = `
+        import hre from 'hardhat';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const token = await ethers.getContractAt('ObjectLayerToken', '${deployment.address}');
+          const tx = await token.unpause();
+          await tx.wait();
+          console.log('Contract UNPAUSED. Transfers resumed.');
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_unpause_tmp.js';
+      fs.writeFileSync(tmpScript, unpauseScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_unpause_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  // ── key-gen: Generate Ethereum secp256k1 key pair ───────────────────────
+  chain
+    .command('key-gen')
+    .description('Generate a new Ethereum secp256k1 key pair for player identity or deployer accounts')
+    .option(
+      '--save',
+      'Persist key files to default paths (private → ./engine-private/, public → ./hardhat/deployments/)',
+    )
+    .option('--private-path <path>', 'Custom path for the private key JSON file (overrides default)')
+    .option('--public-path <path>', 'Custom path for the public key JSON file (overrides default)')
+    .action(async (options) => {
+      const { ethers } = await import('ethers');
+      const wallet = ethers.Wallet.createRandom();
+
+      const addressLower = wallet.address.toLowerCase();
+
+      const privateData = {
+        address: wallet.address,
+        privateKey: wallet.privateKey,
+        mnemonic: wallet.mnemonic ? wallet.mnemonic.phrase : null,
+      };
+
+      const publicData = {
+        address: wallet.address,
+        publicKey: wallet.publicKey,
+      };
+
+      logger.info('── New Ethereum Key Pair ──');
+      logger.info(`  Address    : ${wallet.address}`);
+      logger.info(`  Private Key: ${wallet.privateKey}`);
+      logger.info(`  Public Key : ${wallet.publicKey}`);
+      if (privateData.mnemonic) {
+        logger.info(`  Mnemonic   : ${privateData.mnemonic}`);
+      }
+
+      const shouldSave = options.save || options.privatePath || options.publicPath;
+
+      if (shouldSave) {
+        const privatePath = options.privatePath || `./engine-private/eth-networks/besu/${addressLower}.key.json`;
+        const publicPath = options.publicPath || `./hardhat/deployments/${addressLower}.pub.json`;
+
+        fs.ensureDirSync(nodePath.dirname(privatePath));
+        fs.writeJsonSync(privatePath, privateData, { spaces: 2 });
+        logger.info(`  Private key saved to: ${privatePath}`);
+        logger.warn('  ⚠  Keep this file secure! Anyone with the private key controls this address.');
+
+        fs.ensureDirSync(nodePath.dirname(publicPath));
+        fs.writeJsonSync(publicPath, publicData, { spaces: 2 });
+        logger.info(`  Public key saved to : ${publicPath}`);
+      }
+    });
+
+  // ── set-coinbase: Set the Besu deployer (coinbase) private key ──────────
+  chain
+    .command('set-coinbase')
+    .description(
+      'Set the coinbase deployer private key used by hardhat.config.js for Besu network deployments.\n' +
+        'Accepts either a raw hex private key via --private-key, or a .key.json file generated by "cyberia chain key-gen --save" via --from-file.',
+    )
+    .option('--private-key <hex>', 'Raw hex private key (with or without 0x prefix)')
+    .option(
+      '--from-file <path>',
+      'Path to a .key.json file (e.g. ./engine-private/eth-networks/besu/<address>.key.json)',
+    )
+    .option(
+      '--coinbase-path <path>',
+      'Custom output path for the coinbase file',
+      './engine-private/eth-networks/besu/coinbase',
+    )
+    .action(async (options) => {
+      let privateKey;
+
+      if (options.fromFile) {
+        if (!fs.existsSync(options.fromFile)) {
+          logger.error(`Key file not found: ${options.fromFile}`);
+          process.exit(1);
+        }
+        try {
+          const keyData = fs.readJsonSync(options.fromFile);
+          if (!keyData.privateKey) {
+            logger.error(`Key file does not contain a "privateKey" field: ${options.fromFile}`);
+            process.exit(1);
+          }
+          privateKey = keyData.privateKey;
+          logger.info(`Read private key for address ${keyData.address || '(unknown)'} from ${options.fromFile}`);
+        } catch (e) {
+          logger.error(`Failed to parse key file: ${e.message}`);
+          process.exit(1);
+        }
+      } else if (options.privateKey) {
+        privateKey = options.privateKey;
+      } else {
+        logger.error('Provide either --private-key <hex> or --from-file <path>.');
+        process.exit(1);
+      }
+
+      // Normalise: ensure 0x prefix
+      privateKey = privateKey.trim();
+      if (!privateKey.startsWith('0x')) privateKey = `0x${privateKey}`;
+
+      // Validate the key by deriving the address
+      try {
+        const { ethers } = await import('ethers');
+        const wallet = new ethers.Wallet(privateKey);
+        logger.info(`  Derived address: ${wallet.address}`);
+      } catch (e) {
+        logger.error(`Invalid private key: ${e.message}`);
+        process.exit(1);
+      }
+
+      // Write the coinbase file
+      const coinbasePath = options.coinbasePath;
+      fs.ensureDirSync(nodePath.dirname(coinbasePath));
+      fs.writeFileSync(coinbasePath, privateKey, 'utf8');
+      logger.info(`Coinbase private key written to: ${coinbasePath}`);
+      logger.warn('⚠  Keep this file secure! Anyone with the private key controls the deployer address.');
+      logger.info('hardhat.config.js will read this file automatically for Besu network deployments.');
+    });
+
+  // ── balance: Query token balance for an address ─────────────────────────
+  chain
+    .command('balance')
+    .description('Query ERC-1155 token balance for an address (CKY fungible, semi-fungible, or non-fungible)')
+    .requiredOption('--address <address>', 'Ethereum address to query')
+    .option('--token-id <tokenId>', 'ERC-1155 token ID (default: 0 = CKY)', '0')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      const balanceScript = `
+        import hre from 'hardhat';
+        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});
+          const itemId = await token.getItemId(${options.tokenId});
+          const metadataCid = await token.getMetadataCID(${options.tokenId});
+          let totalSupply;
+          try { totalSupply = await token['totalSupply(uint256)'](${options.tokenId}); } catch (_) { totalSupply = 'N/A'; }
+          console.log(JSON.stringify({
+            address: '${options.address}',
+            tokenId: '${options.tokenId}',
+            itemId: itemId || '(unregistered)',
+            balance: balance.toString(),
+            formattedBalance: ${options.tokenId} === '0' || ${options.tokenId} === 0 ? ethers.formatEther(balance) + ' CKY' : balance.toString() + ' units',
+            totalSupply: totalSupply.toString(),
+            metadataCid: metadataCid || '(none)',
+          }, null, 2));
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_balance_tmp.js';
+      fs.writeFileSync(tmpScript, balanceScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_balance_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  // ── transfer: Transfer ERC-1155 tokens between addresses ────────────────
+  chain
+    .command('transfer')
+    .description('Transfer ERC-1155 tokens (CKY, semi-fungible resources, or non-fungible items)')
+    .requiredOption('--from <address>', 'Sender address (must be the deployer/owner for relayed transfers)')
+    .requiredOption('--to <address>', 'Recipient address')
+    .requiredOption('--token-id <tokenId>', 'ERC-1155 token ID (0 = CKY)')
+    .requiredOption('--amount <amount>', 'Amount to transfer')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      logger.info(
+        `Transferring ${options.amount} of token ID ${options.tokenId} from ${options.from} to ${options.to}`,
+      );
+
+      const transferScript = `
+        import hre from 'hardhat';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const [signer] = await ethers.getSigners();
+          const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
+          const tx = await token.safeTransferFrom(
+            '${options.from}',
+            '${options.to}',
+            ${options.tokenId},
+            ${options.amount},
+            '0x'
+          );
+          const receipt = await tx.wait();
+          console.log('Transfer tx hash:', receipt.hash);
+          const senderBal = await token.balanceOf('${options.from}', ${options.tokenId});
+          const recipientBal = await token.balanceOf('${options.to}', ${options.tokenId});
+          console.log('Sender balance:', senderBal.toString());
+          console.log('Recipient balance:', recipientBal.toString());
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_transfer_tmp.js';
+      fs.writeFileSync(tmpScript, transferScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_transfer_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  // ── burn: Burn ERC-1155 tokens ──────────────────────────────────────────
+  chain
+    .command('burn')
+    .description(
+      'Burn ERC-1155 tokens (CKY to reduce supply, semi-fungible for crafting cost, non-fungible to destroy)',
+    )
+    .requiredOption('--address <address>', 'Address holding the tokens to burn')
+    .requiredOption('--token-id <tokenId>', 'ERC-1155 token ID (0 = CKY)')
+    .requiredOption('--amount <amount>', 'Amount to burn')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      logger.info(`Burning ${options.amount} of token ID ${options.tokenId} from ${options.address}`);
+
+      const burnScript = `
+        import hre from 'hardhat';
+        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});
+          const receipt = await tx.wait();
+          console.log('Burn tx hash:', receipt.hash);
+          const remaining = await token.balanceOf('${options.address}', ${options.tokenId});
+          console.log('Remaining balance:', remaining.toString());
+          let totalSupply;
+          try { totalSupply = await token['totalSupply(uint256)'](${options.tokenId}); } catch (_) { totalSupply = 'N/A'; }
+          console.log('Total supply after burn:', totalSupply.toString());
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_burn_tmp.js';
+      fs.writeFileSync(tmpScript, burnScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_burn_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  // ── batch-register: Register multiple Object Layer items in one tx ──────
+  chain
+    .command('batch-register')
+    .description(
+      'Batch-register multiple Object Layer items on-chain in a single transaction.\n' +
+        'When --from-db is set, the canonical CID for every item is resolved from MongoDB\n' +
+        '(fast-json-stable-stringify of objectLayer.data), overriding any "cid" values in the JSON input.',
+    )
+    .requiredOption('--items <json>', 'JSON array of items: [{"itemId":"wood","cid":"bafk...","supply":500000}, ...]')
+    .option('--from-db', 'Resolve canonical CIDs from the ObjectLayer MongoDB documents (recommended)')
+    .option('--network <network>', 'Hardhat network name', 'besu-k8s')
+    .option('--env-path <envPath>', 'Env path', './.env')
+    .option('--mongo-host <mongoHost>', 'MongoDB host override (used with --from-db)')
+    .action(async (options) => {
+      if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
+
+      let items;
+      try {
+        items = JSON.parse(options.items);
+        if (!Array.isArray(items) || items.length === 0) throw new Error('Must be a non-empty array');
+      } catch (e) {
+        logger.error(`Invalid --items JSON: ${e.message}`);
+        process.exit(1);
+      }
+
+      const deploymentsDir = './hardhat/deployments';
+      const artifactPath = `${deploymentsDir}/${options.network}-ObjectLayerToken.json`;
+      if (!fs.existsSync(artifactPath)) {
+        logger.error(`Deployment artifact not found: ${artifactPath}. Run "cyberia chain deploy-contract" first.`);
+        process.exit(1);
+      }
+      const deployment = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      const contractAddress = deployment.address;
+
+      // ── Resolve canonical CIDs when --from-db is set ────────────────
+      if (options.fromDb) {
+        let ObjectLayer, host, path;
+        try {
+          ({ ObjectLayer, host, path } = await connectDbForChain({
+            envPath: options.envPath,
+            mongoHost: options.mongoHost,
+          }));
+        } catch (dbErr) {
+          logger.error(`Failed to connect to database: ${dbErr.message}`);
+          process.exit(1);
+        }
+
+        for (const item of items) {
+          try {
+            const resolved = await resolveCanonicalCid({
+              itemId: item.itemId,
+              ObjectLayer,
+              ipfsClient: IpfsClient,
+              options: { host, path },
+            });
+
+            if (item.cid && item.cid !== resolved.cid) {
+              logger.warn(
+                `Item "${item.itemId}": provided cid "${item.cid}" differs from canonical "${resolved.cid}" (${resolved.source}). Using canonical.`,
+              );
+            }
+
+            item.cid = resolved.cid;
+            logger.info(`  "${item.itemId}" canonical CID (${resolved.source}): ${resolved.cid}`);
+          } catch (resolveErr) {
+            logger.error(`Failed to resolve canonical CID for "${item.itemId}": ${resolveErr.message}`);
+            process.exit(1);
+          }
+        }
+
+        try {
+          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+        } catch (_) {
+          /* ignore close errors */
+        }
+      }
+
+      const itemIds = items.map((i) => i.itemId);
+      const cids = items.map((i) => i.cid || '');
+      const supplies = items.map((i) => i.supply || 1);
+
+      logger.info(`Batch-registering ${items.length} items on contract ${contractAddress}`);
+      for (const item of items) {
+        logger.info(`  - ${item.itemId} (supply: ${item.supply || 1}, cid: ${item.cid || '(none)'})`);
+      }
+
+      const batchScript = `
+        import hre from 'hardhat';
+        const { ethers } = await hre.network.connect();
+        async function main() {
+          const [deployer] = await ethers.getSigners();
+          const token = await ethers.getContractAt('ObjectLayerToken', '${contractAddress}');
+          const itemIds = ${JSON.stringify(itemIds)};
+          const cids = ${JSON.stringify(cids)};
+          const supplies = ${JSON.stringify(supplies)};
+          const tx = await token.batchRegisterObjectLayers(
+            deployer.address,
+            itemIds,
+            cids,
+            supplies,
+            '0x'
+          );
+          const receipt = await tx.wait();
+          console.log('Batch register tx hash:', receipt.hash);
+          for (const id of itemIds) {
+            const tokenId = await token.computeTokenId(id);
+            const balance = await token.balanceOf(deployer.address, tokenId);
+            console.log('  ' + id + ' -> tokenId:', tokenId.toString(), '  balance:', balance.toString());
+          }
+        }
+        main().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
+      `;
+      const tmpScript = './hardhat/scripts/_cli_batch_register_tmp.js';
+      fs.writeFileSync(tmpScript, batchScript, 'utf8');
+      try {
+        shellExec(`cd hardhat && npx hardhat run scripts/_cli_batch_register_tmp.js --network ${options.network}`);
+      } finally {
+        fs.removeSync(tmpScript);
+      }
+    });
+
+  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');
 
   program.parse();
 } catch (error) {