cyberia 3.2.12 → 3.2.70

package/bin/index.js

@@ -5,10 +5,6 @@
  * Provides commands for importing, viewing, and managing object layer assets,
  * render frames, and atlas sprite sheets from the command line.
  *
- * Delegates shared object layer creation logic to {@link ObjectLayerEngine} in
- * `src/server/object-layer.js` to keep a single source of truth shared with
- * the REST API service layer.
- *
  * @module bin/cyberia.js
  * @namespace CyberiaCLI
  */
@@ -19,34 +15,44 @@ import fs from 'fs-extra';
 import stringify from 'fast-json-stable-stringify';
 import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.js';
-import { generateBesuManifests, deployBesu, removeBesu } from '../src/server/besu-genesis-generator.js';
+import { generateBesuManifests, deployBesu, removeBesu } from '../src/projects/cyberia/besu-genesis-generator.js';
 import { DataBaseProviderService } from '../src/db/DataBaseProvider.js';
 import { loadConfServerJson } from '../src/server/conf.js';
 import {
   ObjectLayerEngine,
   resolveCanonicalCid,
   pngDirectoryIteratorByObjectLayerType,
-  getKeyFramesDirectionsFromNumberFolderDirection,
   buildImgFromTile,
-} from '../src/server/object-layer.js';
-import { AtlasSpriteSheetGenerator } from '../src/server/atlas-sprite-sheet-generator.js';
-import { generateMultiFrame, lookupSemantic, semanticRegistry } from '../src/server/semantic-layer-generator.js';
-import { IpfsClient } from '../src/server/ipfs-client.js';
+} from '../src/projects/cyberia/object-layer.js';
+import { getKeyframeDirectionsByCode } from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
+import { AtlasSpriteSheetGenerator } from '../src/projects/cyberia/atlas-sprite-sheet-generator.js';
+import {
+  generateMultiFrame,
+  lookupSemantic,
+  semanticRegistry,
+} from '../src/projects/cyberia/semantic-layer-generator.js';
+import { IpfsClient } from '../src/projects/cyberia/ipfs-client.js';
 import { createPinRecord } from '../src/api/ipfs/ipfs.service.js';
 import { program as underpostProgram } from '../src/cli/index.js';
+import { generateSaga, importSaga } from '../src/projects/cyberia/generate-saga.js';
 import crypto from 'crypto';
 import nodePath from 'path';
 import Underpost from '../src/index.js';
 import { newInstance } from '../src/client/components/core/CommonJs.js';
 import {
-  ITEM_TYPES as itemTypes,
-  DefaultCyberiaItems,
   DefaultSkillConfig,
   DefaultCyberiaDialogues,
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
+  ENTITY_TYPE_DEFAULTS,
+  fillInstanceConfDefaults,
 } from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
 
+import {
+  ITEM_TYPES as itemTypes,
+  DefaultCyberiaItems,
+} from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
+
 /**
  * Connect to the project MongoDB instance using the standard env / conf layout.
  *
@@ -744,7 +750,7 @@ try {
 
           /**
            * Accumulated object layer data keyed by objectLayerId.
-           * @type {Object<string, import('../src/server/object-layer.js').ObjectLayerData>}
+           * @type {Object<string, import('../src/projects/cyberia/object-layer.js').ObjectLayerData>}
            */
           const objectLayers = {};
 
@@ -1221,7 +1227,7 @@ try {
           }
 
           // Get the keyframe direction name from the numerical direction code
-          const objectLayerFrameDirections = getKeyFramesDirectionsFromNumberFolderDirection(direction);
+          const objectLayerFrameDirections = getKeyframeDirectionsByCode(direction);
           if (objectLayerFrameDirections.length === 0) {
             logger.error(`Invalid direction code: ${direction}. Valid codes: 08, 18, 02, 12, 04, 14, 06, 16`);
             process.exit(1);
@@ -1711,11 +1717,18 @@ try {
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
     .option('--mongo-host <mongo-host>', 'Mongo host override')
     .option('--dev', 'Force development environment')
+    .option('--publish-build', 'Build instance backup directory with all related maps, entities and object layers')
+    .option('--publish-remove', 'Remove published instance from underpostnet/cyberia-instances repository')
+    .option('--publish', 'Publish instance in underpostnet/cyberia-instances repository')
+    .option(
+      '--from-n-commit <n>',
+      'Number of latest engine commits to use for the publish commit message (default: 1).',
+    )
     .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);
+        instanceCode = 'amethyst-strata-expansion';
+        logger.warn(`No instance code provided, defaulting to: ${instanceCode}`);
       }
 
       if (!options.envPath) options.envPath = `./.env`;
@@ -1737,6 +1750,113 @@ try {
         logger.error(`Server config not found: ${confServerPath}`);
         process.exit(1);
       }
+
+      if (options.publish || options.publishBuild || options.publishRemove) {
+        if (options.publishBuild) {
+          if (!fs.existsSync('/home/dd/cyberia-instances')) {
+            shellExec('cd /home/dd && underpost clone underpostnet/cyberia-instances');
+          } else {
+            shellExec(`underpost run clean /home/dd/cyberia-instances`);
+            shellExec(`cd /home/dd/cyberia-instances && underpost pull . underpostnet/cyberia-instances`, {
+              silentOnError: true,
+            });
+          }
+
+          fs.mkdirpSync(`/home/dd/cyberia-instances/conf/dd-cyberia`);
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/conf.server.dev.dev.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/conf.server.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/conf.client.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/conf.client.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/conf.cron.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/conf.cron.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/conf.ssr.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/conf.ssr.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/conf.volume.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/conf.volume.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/package.json`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/package.json`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/.env.production`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/.env.development`,
+          );
+          fs.copyFileSync(
+            `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`,
+            `/home/dd/cyberia-instances/conf/dd-cyberia/.env.test`,
+          );
+
+          fs.mkdirpSync(`/home/dd/cyberia-instances/deployments`);
+          fs.copySync(`./src/runtime/engine-cyberia`, `/home/dd/cyberia-instances/deployments/engine-cyberia`);
+          fs.copySync(
+            `./manifests/deployment/dd-cyberia-development/.`,
+            `/home/dd/cyberia-instances/deployments/engine-cyberia/.`,
+          );
+          fs.copySync(`./src/runtime/cyberia-client`, `/home/dd/cyberia-instances/deployments/cyberia-client`);
+          fs.copySync(
+            `./engine-private/conf/dd-cyberia/instances/mmo-client/build/development/.`,
+            `/home/dd/cyberia-instances/deployments/cyberia-client/.`,
+          );
+          fs.copySync(`./src/runtime/cyberia-server`, `/home/dd/cyberia-instances/deployments/cyberia-server`);
+          fs.copySync(
+            `./engine-private/conf/dd-cyberia/instances/mmo-server/build/development/.`,
+            `/home/dd/cyberia-instances/deployments/cyberia-server/.`,
+          );
+          fs.removeSync(`/home/dd/cyberia-instances/public/cyberia`);
+          fs.mkdirpSync(`/home/dd/cyberia-instances/public/cyberia`);
+          for (const assetPath of Object.keys(
+            JSON.parse(fs.readFileSync(`./engine-private/conf/dd-cyberia/storage.engine-cyberia.json`, 'utf-8')),
+          )) {
+            const relativePath = assetPath.replace(/^src\/client\/public\/cyberia\//, '');
+            const targetPath = `/home/dd/cyberia-instances/public/cyberia/${relativePath}`;
+            fs.mkdirpSync(nodePath.dirname(targetPath));
+            logger.info(`Copying asset: ${assetPath} → ${targetPath}`);
+            fs.copySync(`./${assetPath}`, targetPath);
+          }
+
+          fs.mkdirpSync(`/home/dd/cyberia-instances/instances`);
+          fs.copySync(
+            `./engine-private/cyberia-instances/${instanceCode}`,
+            `/home/dd/cyberia-instances/instances/${instanceCode}`,
+          );
+          fs.mkdirpSync(`/home/dd/cyberia-instances/sagas`);
+          fs.copyFileSync(
+            `./engine-private/cyberia-sagas/${instanceCode}.json`,
+            `/home/dd/cyberia-instances/sagas/${instanceCode}.json`,
+          );
+          return;
+        } else if (options.publishRemove) {
+          shellExec(`rm -rf /home/dd/cyberia-instances/instances/${instanceCode}`);
+          shellExec(`rm -rf /home/dd/cyberia-instances/sagas/${instanceCode}.json`);
+          return;
+        }
+        const fromN = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+        const publishMessage =
+          shellExec(`node bin cmt --changelog-msg --from-n-commit ${fromN} --changelog-no-hash`, {
+            stdout: true,
+            silent: true,
+          }).trim() || `Update instance ${instanceCode}`;
+        shellExec(`cd /home/dd/cyberia-instances \
+          && git add . \
+          && git commit -m "${publishMessage.replace(/"/g, '\\"')}" \
+          && underpost push . underpostnet/cyberia-instances`);
+        return;
+      }
+
       const confServer = loadConfServerJson(confServerPath, { resolve: true });
       const { db } = confServer[host][path];
 
@@ -1755,6 +1875,11 @@ try {
           'cyberia-dialogue',
           'cyberia-map',
           'cyberia-entity',
+          'cyberia-quest',
+          'cyberia-action',
+          'cyberia-skill',
+          'cyberia-entity-type-default',
+          'cyberia-saga',
           'object-layer',
           'object-layer-render-frames',
           'atlas-sprite-sheet',
@@ -1770,6 +1895,11 @@ try {
       const CyberiaInstanceConf = DataBaseProviderService.getModel('cyberia-instance-conf', { host, path });
       const CyberiaDialogue = DataBaseProviderService.getModel('cyberia-dialogue', { host, path });
       const CyberiaMap = DataBaseProviderService.getModel('cyberia-map', { host, path });
+      const CyberiaQuest = DataBaseProviderService.getModel('cyberia-quest', { host, path });
+      const CyberiaAction = DataBaseProviderService.getModel('cyberia-action', { host, path });
+      const CyberiaSkill = DataBaseProviderService.getModel('cyberia-skill', { host, path });
+      const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('cyberia-entity-type-default', { host, path });
+      const CyberiaSaga = DataBaseProviderService.getModel('cyberia-saga', { host, path });
       const ObjectLayer = DataBaseProviderService.getModel('object-layer', { host, path });
       const ObjectLayerRenderFrames = DataBaseProviderService.getModel('object-layer-render-frames', { host, path });
       const AtlasSpriteSheet = DataBaseProviderService.getModel('atlas-sprite-sheet', { host, path });
@@ -1852,36 +1982,6 @@ try {
           ...(entry.mfsPaths.length ? { mfsPaths: entry.mfsPaths } : {}),
         }));
 
-      const getDefaultDialoguesByItemId = (itemIds = []) => {
-        const requestedItemIds = new Set(itemIds.filter(Boolean));
-        const defaultsByItemId = new Map();
-
-        for (const dialogue of DefaultCyberiaDialogues) {
-          // Match by code prefix: "default-<itemId>" covers the common case;
-          // callers may also pass a full code directly.
-          const matchingIds = [...requestedItemIds].filter(
-            (id) => dialogue.code === `default-${id}` || dialogue.code === id,
-          );
-          if (!matchingIds.length) continue;
-          for (const id of matchingIds) {
-            if (!defaultsByItemId.has(id)) defaultsByItemId.set(id, []);
-            defaultsByItemId.get(id).push({
-              code: dialogue.code,
-              order: dialogue.order ?? 0,
-              speaker: dialogue.speaker ?? '',
-              text: dialogue.text,
-              mood: dialogue.mood ?? 'neutral',
-            });
-          }
-        }
-
-        for (const dialogues of defaultsByItemId.values()) {
-          dialogues.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-        }
-
-        return defaultsByItemId;
-      };
-
       const rewriteImportedCidReferences = async ({ oldCid, newCid, resourceType }) => {
         if (!oldCid || !newCid || oldCid === newCid) return;
 
@@ -1965,6 +2065,10 @@ try {
           instanceConf = created?.toObject ? created.toObject() : created;
         }
         if (instanceConf) {
+          // `.lean()` skips Mongoose schema defaults and older docs may predate
+          // some fields, so backfill every CyberiaInstanceConfSchema field from
+          // the canonical defaults before writing the backup.
+          instanceConf = fillInstanceConfDefaults(instanceConf);
           fs.writeJsonSync(`${backupDir}/cyberia-instance-conf.json`, instanceConf, { spaces: 2 });
           logger.info('Exported CyberiaInstanceConf', { instanceCode });
         } else {
@@ -1998,6 +2102,36 @@ try {
         }
         logger.info(`Exported ${maps.length} CyberiaMap document(s)`, { codes: maps.map((m) => m.code) });
 
+        // 3b. Export quests + actions bound to THIS instance's maps (sourceMapCode
+        //     in the instance's map codes) — only the content tied to this instance.
+        //     Dialogue codes the actions reference are collected so they travel too.
+        const actionDialogueCodes = new Set();
+        const quests = await CyberiaQuest.find({ sourceMapCode: { $in: [...mapCodes] } }).lean();
+        if (quests.length > 0) {
+          fs.ensureDirSync(`${backupDir}/cyberia-quests`);
+          for (const quest of quests) {
+            fs.writeJsonSync(`${backupDir}/cyberia-quests/${encodeURIComponent(quest.code)}.json`, quest, {
+              spaces: 2,
+            });
+          }
+          logger.info(`Exported ${quests.length} CyberiaQuest document(s)`, { codes: quests.map((q) => q.code) });
+        }
+
+        const actions = await CyberiaAction.find({ sourceMapCode: { $in: [...mapCodes] } }).lean();
+        if (actions.length > 0) {
+          fs.ensureDirSync(`${backupDir}/cyberia-actions`);
+          for (const action of actions) {
+            fs.writeJsonSync(`${backupDir}/cyberia-actions/${encodeURIComponent(action.code)}.json`, action, {
+              spaces: 2,
+            });
+            if (action.dialogCode) actionDialogueCodes.add(action.dialogCode);
+            for (const qd of action.questDialogueCodes || []) {
+              if (qd.dialogCode) actionDialogueCodes.add(qd.dialogCode);
+            }
+          }
+          logger.info(`Exported ${actions.length} CyberiaAction document(s)`, { codes: actions.map((a) => a.code) });
+        }
+
         // 4. Collect all objectLayerItemIds from map entities
         const objectLayerItemIds = new Set();
         for (const map of maps) {
@@ -2008,11 +2142,14 @@ try {
           }
         }
 
-        // 4b. Add instance-level itemIds
-        for (const id of instance.itemIds || []) {
+        // 4b. Add instance-level itemIds ({ id, defaultPlayerInventory }).
+        for (const entry of instance.itemIds || []) {
+          const id = typeof entry === 'string' ? entry : entry?.id;
           if (id) objectLayerItemIds.add(id);
         }
 
+        const contentItemIds = new Set(objectLayerItemIds);
+
         // 4c. Add all itemIds referenced by CyberiaInstanceConf (entityDefaults + skillConfig).
         //     This ensures liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers and
         //     skill trigger items are included even if no map entity currently uses them.
@@ -2035,50 +2172,106 @@ try {
           }
         }
 
-        // 4d. Export dialogues for all relevant object-layer items. Codes follow the pattern
-        //     "default-<itemId>". If an item has no dialogue docs yet but ships with
-        //     DefaultCyberiaDialogues, seed those defaults into Mongo first.
+        // 4d. Export skills whose trigger item belongs to this instance (own model:
+        //     CyberiaSkill, keyed by triggerItemId). Their summoned-entity items are
+        //     added to the OL set so those atlases export too. Runs before the
+        //     dialogue + OL queries so the summoned ids are included.
         if (objectLayerItemIds.size > 0) {
-          const requestedItemIds = [...objectLayerItemIds];
-          const requestedCodes = requestedItemIds.map((id) => `default-${id}`);
-          const defaultDialoguesByItemId = getDefaultDialoguesByItemId(requestedItemIds);
-          const existingDialogueDocs = await CyberiaDialogue.find({
-            code: { $in: requestedCodes },
-          })
-            .sort({ code: 1, order: 1 })
-            .lean();
-
-          const existingDialogueCodes = new Set(existingDialogueDocs.map((dialogue) => dialogue.code).filter(Boolean));
-          let seededDialogueCount = 0;
-
-          for (const [itemId, dialogues] of defaultDialoguesByItemId.entries()) {
-            const firstCode = dialogues[0]?.code;
-            if (firstCode && existingDialogueCodes.has(firstCode)) continue;
+          const skills = await CyberiaSkill.find({ triggerItemId: { $in: [...objectLayerItemIds] } }).lean();
+          if (skills.length > 0) {
+            fs.ensureDirSync(`${backupDir}/cyberia-skills`);
+            for (const skill of skills) {
+              fs.writeJsonSync(`${backupDir}/cyberia-skills/${encodeURIComponent(skill.triggerItemId)}.json`, skill, {
+                spaces: 2,
+              });
+              for (const def of skill.skills || []) {
+                if (def.summonedEntityItemId && !def.summonedEntityItemId.startsWith('$')) {
+                  objectLayerItemIds.add(def.summonedEntityItemId);
+                }
+              }
+            }
+            logger.info(`Exported ${skills.length} CyberiaSkill document(s)`, {
+              triggerItemIds: skills.map((sk) => sk.triggerItemId),
+            });
+          }
+        }
 
-            for (const dialogue of dialogues) {
-              await CyberiaDialogue.findOneAndUpdate(
-                { code: dialogue.code, order: dialogue.order },
-                {
-                  $set: {
-                    speaker: dialogue.speaker,
-                    text: dialogue.text,
-                    mood: dialogue.mood,
-                  },
-                },
-                { upsert: true },
-              );
-              seededDialogueCount++;
+        // 4d-bis. Export entity-type defaults whose item ids belong to this
+        //     instance's real content (own model: CyberiaEntityTypeDefault). A
+        //     default is related when any of its live/dead/drop ids or default
+        //     object-layer ids appears in contentItemIds — map/instance content
+        //     only, NOT the canonical conf defaults every instance shares (which
+        //     would spuriously drag in the global seed entity-type-defaults).
+        //     Matched ids are folded back into objectLayerItemIds so the related
+        //     atlases + dialogues export too.
+        if (contentItemIds.size > 0) {
+          const idsForMatch = [...contentItemIds];
+          const entityDefaults = await CyberiaEntityTypeDefault.find({
+            $or: [
+              { liveItemIds: { $in: idsForMatch } },
+              { deadItemIds: { $in: idsForMatch } },
+              { dropItemIds: { $in: idsForMatch } },
+              { 'defaultObjectLayers.itemId': { $in: idsForMatch } },
+            ],
+          }).lean();
+          if (entityDefaults.length > 0) {
+            fs.ensureDirSync(`${backupDir}/cyberia-entity-type-defaults`);
+            for (const ed of entityDefaults) {
+              fs.writeJsonSync(`${backupDir}/cyberia-entity-type-defaults/${ed._id}.json`, ed, { spaces: 2 });
+              for (const id of ed.liveItemIds || []) if (id) objectLayerItemIds.add(id);
+              for (const id of ed.deadItemIds || []) if (id) objectLayerItemIds.add(id);
+              for (const id of ed.dropItemIds || []) if (id) objectLayerItemIds.add(id);
+              for (const slot of ed.defaultObjectLayers || []) if (slot.itemId) objectLayerItemIds.add(slot.itemId);
             }
+            logger.info(`Exported ${entityDefaults.length} CyberiaEntityTypeDefault document(s)`, {
+              entityTypes: entityDefaults.map((ed) => ed.entityType),
+            });
+          }
+        }
+
+        // 4e. Export sagas related to this instance. A saga is considered related
+        //     when its code matches the instance code (direct namespace match), or
+        //     when its mapCodes or itemIds overlap with the instance's data.
+        //     At this point objectLayerItemIds contains all map-entity, instance-level,
+        //     conf-default, and skill-summoned item IDs — giving the broadest possible
+        //     match surface for saga discovery.
+        const sagaCodeMatch = instanceCode ? await CyberiaSaga.find({ code: instanceCode }).lean() : [];
+        // Disabling overlaps queries for now because they can be very expensive and are not strictly necessary for a backup.
+        const sagaMapOverlap = true
+          ? []
+          : mapCodes.size > 0
+            ? await CyberiaSaga.find({ mapCodes: { $in: [...mapCodes] } }).lean()
+            : [];
+        const sagaItemOverlap = true
+          ? []
+          : objectLayerItemIds.size > 0
+            ? await CyberiaSaga.find({ itemIds: { $in: [...objectLayerItemIds] } }).lean()
+            : [];
+        const allSagas = [
+          ...new Map(
+            [...sagaCodeMatch, ...sagaMapOverlap, ...sagaItemOverlap].map((s) => [s._id.toString(), s]),
+          ).values(),
+        ];
+        if (allSagas.length > 0) {
+          fs.ensureDirSync(`${backupDir}/cyberia-sagas`);
+          for (const saga of allSagas) {
+            fs.writeJsonSync(`${backupDir}/cyberia-sagas/${encodeURIComponent(saga.code)}.json`, saga, { spaces: 2 });
           }
+          logger.info(`Exported ${allSagas.length} CyberiaSaga document(s)`, { codes: allSagas.map((s) => s.code) });
+        }
 
+        // 4f. Export dialogues for all relevant object-layer items (codes follow the
+        //     pattern "default-<itemId>") plus the dialogue codes the instance's
+        //     actions reference. If an item has no dialogue docs yet but ships with
+        //     DefaultCyberiaDialogues, seed those defaults into Mongo first.
+        if (objectLayerItemIds.size > 0 || actionDialogueCodes.size > 0) {
+          const requestedItemIds = [...objectLayerItemIds];
+          const requestedCodes = [
+            ...new Set([...requestedItemIds.map((id) => `default-${id}`), ...actionDialogueCodes]),
+          ];
           const dialogueDocs = await CyberiaDialogue.find({ code: { $in: requestedCodes } })
             .sort({ code: 1, order: 1 })
             .lean();
-
-          if (seededDialogueCount > 0) {
-            logger.info(`Seeded ${seededDialogueCount} CyberiaDialogue default record(s) for export`);
-          }
-
           if (dialogueDocs.length > 0) {
             fs.ensureDirSync(`${backupDir}/cyberia-dialogues`);
             const dialoguesByCode = new Map();
@@ -2164,20 +2357,12 @@ try {
               }
             }
 
-            // Export AtlasSpriteSheet + its File using canonical payload bytes from the DB state.
-            if (ol.atlasSpriteSheetId) {
-              const atlas = await AtlasSpriteSheet.findById(ol.atlasSpriteSheetId).lean();
-              if (!atlas) {
-                ipfsPayloadFailures.push({
-                  itemKey,
-                  resourceType: 'atlas-sprite-sheet',
-                  mfsPath: itemPaths.atlasSpriteSheet,
-                  reason: 'AtlasSpriteSheet document not found in MongoDB',
-                });
-                continue;
-              }
-
+            const atlas =
+              (ol.atlasSpriteSheetId ? await AtlasSpriteSheet.findById(ol.atlasSpriteSheetId).lean() : null) ||
+              (await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey }).lean());
+            if (atlas) {
               const atlasExport = newInstance(atlas);
+              objectLayerExport.atlasSpriteSheetId = atlas._id;
               if (atlas.fileId) {
                 await exportFileDoc(atlas.fileId, `atlas-${itemKey}`);
               }
@@ -2376,6 +2561,11 @@ try {
 
         logger.info('Importing instance', { code: instanceCode, backupDir });
 
+        // Item ids belonging to this instance (collected from imported object
+        // layers + the instance doc) — used to backfill missing skills from the
+        // canonical DefaultSkillConfig when the backup predates the skill model.
+        const importedItemIds = new Set();
+
         // 0. Drop existing documents if --drop is set
         if (options.drop && !options.conf) {
           const existingInstance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
@@ -2395,7 +2585,10 @@ try {
             const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
 
             // Add instance-level itemIds (may not appear in any map entity)
-            for (const id of existingInstance.itemIds || []) if (id) dropOlItemIds.add(id);
+            for (const entry of existingInstance.itemIds || []) {
+              const id = typeof entry === 'string' ? entry : entry?.id;
+              if (id) dropOlItemIds.add(id);
+            }
 
             // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
             const existingConf =
@@ -2435,6 +2628,37 @@ try {
 
               const mapResult = await CyberiaMap.deleteMany({ code: { $in: [...dropMapCodes] } });
               logger.info(`Dropped ${mapResult.deletedCount} CyberiaMap document(s)`);
+
+              // Quests + actions are bound to maps by sourceMapCode, so they drop
+              // with this instance's maps — only the content tied to this instance.
+              const questResult = await CyberiaQuest.deleteMany({ sourceMapCode: { $in: [...dropMapCodes] } });
+              if (questResult.deletedCount > 0)
+                logger.info(`Dropped ${questResult.deletedCount} CyberiaQuest document(s)`);
+
+              // Collect instance-specific dialogue codes the actions reference
+              // (e.g. quest-talk-<questCode>) before deleting the actions. The
+              // shared "default-<itemId>" greetings are left to the item-shared
+              // logic below so dialogues shared with other instances survive.
+              const dropActions = await CyberiaAction.find(
+                { sourceMapCode: { $in: [...dropMapCodes] } },
+                { dialogCode: 1, 'questDialogueCodes.dialogCode': 1 },
+              ).lean();
+              const dropActionDialogueCodes = new Set();
+              const collectDlg = (code) => {
+                if (code && !code.startsWith('default-')) dropActionDialogueCodes.add(code);
+              };
+              for (const a of dropActions) {
+                collectDlg(a.dialogCode);
+                for (const qd of a.questDialogueCodes || []) collectDlg(qd.dialogCode);
+              }
+              const actionResult = await CyberiaAction.deleteMany({ sourceMapCode: { $in: [...dropMapCodes] } });
+              if (actionResult.deletedCount > 0)
+                logger.info(`Dropped ${actionResult.deletedCount} CyberiaAction document(s)`);
+              if (dropActionDialogueCodes.size > 0) {
+                const advResult = await CyberiaDialogue.deleteMany({ code: { $in: [...dropActionDialogueCodes] } });
+                if (advResult.deletedCount > 0)
+                  logger.info(`Dropped ${advResult.deletedCount} CyberiaDialogue document(s) (action-referenced)`);
+              }
             }
 
             // Exclude OL item IDs referenced by maps outside this instance
@@ -2463,6 +2687,12 @@ try {
               const dropDialogueCodes = [...dropOlItemIds].map((id) => `default-${id}`);
               const dialogueResult = await CyberiaDialogue.deleteMany({ code: { $in: dropDialogueCodes } });
               logger.info(`Dropped ${dialogueResult.deletedCount} CyberiaDialogue document(s)`);
+
+              // Skills are keyed by triggerItemId — drop those whose trigger item is
+              // being removed (i.e. not shared with another instance's maps).
+              const skillResult = await CyberiaSkill.deleteMany({ triggerItemId: { $in: [...dropOlItemIds] } });
+              if (skillResult.deletedCount > 0)
+                logger.info(`Dropped ${skillResult.deletedCount} CyberiaSkill document(s)`);
               const olDocs = await ObjectLayer.find(
                 { 'data.item.id': { $in: [...dropOlItemIds] } },
                 {
@@ -2557,7 +2787,9 @@ try {
           const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
           let importedConf = null;
           if (fs.existsSync(confImportPath)) {
-            const confData = fs.readJsonSync(confImportPath);
+            // Backfill any missing schema fields so older backups import a
+            // complete, playable config into the DB.
+            const confData = fillInstanceConfDefaults(fs.readJsonSync(confImportPath));
             if (confData._id) await CyberiaInstanceConf.deleteOne({ _id: confData._id });
             await CyberiaInstanceConf.deleteOne({ instanceCode: confData.instanceCode });
             // Always bump updatedAt so the Go server's version hash changes and
@@ -2664,6 +2896,7 @@ try {
               await ObjectLayer.deleteOne({ sha256: olData.sha256 });
             }
             await ObjectLayer.create(olData);
+            if (olData.data?.item?.id) importedItemIds.add(olData.data.item.id);
             olCount++;
           }
           logger.info(`Imported ${olCount} ObjectLayer document(s)`);
@@ -2735,7 +2968,9 @@ try {
         // 6. Import CyberiaInstanceConf (skillRules, equipmentRules, entityDefaults, etc.)
         const confImportPath = `${backupDir}/cyberia-instance-conf.json`;
         if (fs.existsSync(confImportPath)) {
-          const confData = fs.readJsonSync(confImportPath);
+          // Backfill any missing schema fields so older backups import a
+          // complete, playable config into the DB.
+          const confData = fillInstanceConfDefaults(fs.readJsonSync(confImportPath));
           if (confData._id) await CyberiaInstanceConf.deleteOne({ _id: confData._id });
           await CyberiaInstanceConf.deleteOne({ instanceCode: confData.instanceCode });
           await CyberiaInstanceConf.create(confData);
@@ -2748,6 +2983,13 @@ try {
         const instancePath = `${backupDir}/cyberia-instance.json`;
         if (fs.existsSync(instancePath)) {
           const instanceData = fs.readJsonSync(instancePath);
+          // Heal legacy shapes against the current model. itemIds migrated from a
+          // flat string[] to [{ id, defaultPlayerInventory }] — a raw old backup
+          // would fail Mongoose embedded-cast validation, so normalize it here.
+          instanceData.itemIds = (instanceData.itemIds || [])
+            .map((entry) => (typeof entry === 'string' ? { id: entry, defaultPlayerInventory: false } : entry))
+            .filter((entry) => entry && entry.id);
+          for (const entry of instanceData.itemIds) importedItemIds.add(entry.id);
           await CyberiaInstance.deleteOne({ code: instanceCode });
           await CyberiaInstance.deleteOne({ _id: instanceData._id });
           await CyberiaInstance.create(instanceData);
@@ -2785,6 +3027,126 @@ try {
           logger.info(`Imported ${dialogueCount} CyberiaDialogue document(s)`);
         }
 
+        // 8b. Import CyberiaQuest documents (overwrite by code).
+        const questsDir = `${backupDir}/cyberia-quests`;
+        if (fs.existsSync(questsDir)) {
+          const questFiles = fs.readdirSync(questsDir).filter((f) => f.endsWith('.json'));
+          let questCount = 0;
+          for (const file of questFiles) {
+            const questData = fs.readJsonSync(`${questsDir}/${file}`);
+            if (!questData.code) {
+              logger.warn(`Skipping CyberiaQuest backup without code: ${file}`);
+              continue;
+            }
+            await CyberiaQuest.deleteOne({ code: questData.code });
+            if (questData._id) await CyberiaQuest.deleteOne({ _id: questData._id });
+            await CyberiaQuest.create(questData);
+            questCount++;
+          }
+          logger.info(`Imported ${questCount} CyberiaQuest document(s)`);
+        }
+
+        // 8c. Import CyberiaAction documents (overwrite by code).
+        const actionsDir = `${backupDir}/cyberia-actions`;
+        if (fs.existsSync(actionsDir)) {
+          const actionFiles = fs.readdirSync(actionsDir).filter((f) => f.endsWith('.json'));
+          let actionCount = 0;
+          for (const file of actionFiles) {
+            const actionData = fs.readJsonSync(`${actionsDir}/${file}`);
+            if (!actionData.code) {
+              logger.warn(`Skipping CyberiaAction backup without code: ${file}`);
+              continue;
+            }
+            await CyberiaAction.deleteOne({ code: actionData.code });
+            if (actionData._id) await CyberiaAction.deleteOne({ _id: actionData._id });
+            await CyberiaAction.create(actionData);
+            actionCount++;
+          }
+          logger.info(`Imported ${actionCount} CyberiaAction document(s)`);
+        }
+
+        // 8d. Import CyberiaSkill documents (own model, overwrite by triggerItemId).
+        const skillsDir = `${backupDir}/cyberia-skills`;
+        if (fs.existsSync(skillsDir)) {
+          const skillFiles = fs.readdirSync(skillsDir).filter((f) => f.endsWith('.json'));
+          let skillCount = 0;
+          for (const file of skillFiles) {
+            const skillData = fs.readJsonSync(`${skillsDir}/${file}`);
+            if (!skillData.triggerItemId) {
+              logger.warn(`Skipping CyberiaSkill backup without triggerItemId: ${file}`);
+              continue;
+            }
+            await CyberiaSkill.deleteOne({ triggerItemId: skillData.triggerItemId });
+            if (skillData._id) await CyberiaSkill.deleteOne({ _id: skillData._id });
+            await CyberiaSkill.create(skillData);
+            skillCount++;
+          }
+          logger.info(`Imported ${skillCount} CyberiaSkill document(s)`);
+        }
+
+        // 8d-bis. Import CyberiaEntityTypeDefault documents (own model, overwrite
+        //     by the natural (entityType, liveItemIds) key, then by _id).
+        const entityDefaultsDir = `${backupDir}/cyberia-entity-type-defaults`;
+        if (fs.existsSync(entityDefaultsDir)) {
+          const entityDefaultFiles = fs.readdirSync(entityDefaultsDir).filter((f) => f.endsWith('.json'));
+          let entityDefaultCount = 0;
+          for (const file of entityDefaultFiles) {
+            const edData = fs.readJsonSync(`${entityDefaultsDir}/${file}`);
+            if (!edData.entityType) {
+              logger.warn(`Skipping CyberiaEntityTypeDefault backup without entityType: ${file}`);
+              continue;
+            }
+            await CyberiaEntityTypeDefault.deleteMany({
+              entityType: edData.entityType,
+              liveItemIds: edData.liveItemIds || [],
+            });
+            if (edData._id) await CyberiaEntityTypeDefault.deleteOne({ _id: edData._id });
+            await CyberiaEntityTypeDefault.create(edData);
+            entityDefaultCount++;
+          }
+          logger.info(`Imported ${entityDefaultCount} CyberiaEntityTypeDefault document(s)`);
+        }
+
+        // 8e. Backfill missing skills from the canonical DefaultSkillConfig. Old
+        //     backups predate the CyberiaSkill model and ship no skills/ dir, so
+        //     any instance item that has a canonical skill (e.g. atlas_pistol_mk2,
+        //     coin, hatchet) but no document yet is seeded from defaults. Existing
+        //     skills are never overwritten.
+        let backfilledSkillCount = 0;
+        for (const sk of DefaultSkillConfig) {
+          if (!importedItemIds.has(sk.triggerItemId)) continue;
+          const exists = await CyberiaSkill.findOne({ triggerItemId: sk.triggerItemId }).lean();
+          if (exists) continue;
+          await CyberiaSkill.create({
+            triggerItemId: sk.triggerItemId,
+            logicEventIds: sk.logicEventIds || [],
+            skills: sk.skills || [],
+          });
+          backfilledSkillCount++;
+        }
+        if (backfilledSkillCount > 0) {
+          logger.info(`Backfilled ${backfilledSkillCount} CyberiaSkill document(s) from DefaultSkillConfig`);
+        }
+
+        // 8f. Import CyberiaSaga documents (overwrite by code).
+        const sagasDir = `${backupDir}/cyberia-sagas`;
+        if (fs.existsSync(sagasDir)) {
+          const sagaFiles = fs.readdirSync(sagasDir).filter((f) => f.endsWith('.json'));
+          let sagaCount = 0;
+          for (const file of sagaFiles) {
+            const sagaData = fs.readJsonSync(`${sagasDir}/${file}`);
+            if (!sagaData.code) {
+              logger.warn(`Skipping CyberiaSaga backup without code: ${file}`);
+              continue;
+            }
+            await CyberiaSaga.deleteOne({ code: sagaData.code });
+            if (sagaData._id) await CyberiaSaga.deleteOne({ _id: sagaData._id });
+            await CyberiaSaga.create(sagaData);
+            sagaCount++;
+          }
+          logger.info(`Imported ${sagaCount} CyberiaSaga document(s)`);
+        }
+
         // 9. Restore IPFS pin records and payloads
         const ipfsFile = `${backupDir}/ipfs/pins.json`;
         if (fs.existsSync(ipfsFile)) {
@@ -2815,10 +3177,6 @@ try {
           }
 
           const backupPinEntries = serialiseCanonicalPins(backupPins);
-          const backupCids = [...new Set(backupPinEntries.map((entry) => entry.cid).filter(Boolean))];
-          if (backupCids.length > 0) {
-            await Ipfs.deleteMany({ cid: { $in: backupCids } });
-          }
 
           const restoreAdditionalMfsPaths = async (cid, mfsPaths, primaryPath) => {
             let restoredCount = 0;
@@ -2830,78 +3188,99 @@ try {
             return restoredCount;
           };
 
-          const upsertImportedPin = async ({ cid, resourceType, mfsPath }) => {
-            if (!cid || !resourceType) return;
-            await Ipfs.deleteMany({ cid, resourceType });
-            await createPinRecord({ cid, resourceType, mfsPath: mfsPath || '', options: { host, path } });
-          };
-
           if (fs.existsSync(ipfsContentDir)) {
             let cidRewriteCount = 0;
             let extraMfsRestoreCount = 0;
+            let ipfsAlreadyPresent = 0;
 
             for (const [index, doc] of backupPinEntries.entries()) {
               const mfsPaths = collectMfsPaths(doc);
               const primaryPath = mfsPaths[0] || '';
               const payloadPath = `${ipfsContentDir}/${doc.cid}.bin`;
 
-              logger.info('IPFS raw payload restore start', {
-                index: index + 1,
-                total: backupPinEntries.length,
-                cid: doc.cid,
-                resourceType: doc.resourceType,
-                mfsPath: primaryPath || null,
-              });
+              try {
+                const existing = await Ipfs.findOne({ cid: doc.cid, resourceType: doc.resourceType })
+                  .select({ _id: 1 })
+                  .lean();
+                if (existing) {
+                  ipfsAlreadyPresent++;
+                  continue;
+                }
 
-              if (!fs.existsSync(payloadPath)) {
-                logger.warn('IPFS raw payload file missing from backup', {
+                logger.info('IPFS raw payload restore start', {
+                  index: index + 1,
+                  total: backupPinEntries.length,
                   cid: doc.cid,
                   resourceType: doc.resourceType,
                   mfsPath: primaryPath || null,
                 });
-                ipfsSkipped++;
-                continue;
-              }
 
-              const addResult = await IpfsClient.addToIpfs(
-                fs.readFileSync(payloadPath),
-                nodePath.basename(primaryPath || doc.cid),
-                primaryPath || undefined,
-              );
+                if (!fs.existsSync(payloadPath)) {
+                  logger.warn('IPFS raw payload file missing from backup', {
+                    cid: doc.cid,
+                    resourceType: doc.resourceType,
+                    mfsPath: primaryPath || null,
+                  });
+                  ipfsSkipped++;
+                  continue;
+                }
 
-              if (!addResult?.cid) {
-                logger.warn('IPFS raw payload restore failed', {
-                  cid: doc.cid,
-                  resourceType: doc.resourceType,
-                  mfsPath: primaryPath || null,
-                });
-                ipfsSkipped++;
-                continue;
-              }
+                const addResult = await IpfsClient.addToIpfs(
+                  fs.readFileSync(payloadPath),
+                  nodePath.basename(primaryPath || doc.cid),
+                  primaryPath || undefined,
+                );
+
+                if (!addResult?.cid) {
+                  logger.warn('IPFS raw payload restore failed', {
+                    cid: doc.cid,
+                    resourceType: doc.resourceType,
+                    mfsPath: primaryPath || null,
+                  });
+                  ipfsSkipped++;
+                  continue;
+                }
+
+                const finalCid = addResult.cid;
+                if (doc.cid !== finalCid) {
+                  await rewriteImportedCidReferences({
+                    oldCid: doc.cid,
+                    newCid: finalCid,
+                    resourceType: doc.resourceType,
+                  });
+                  cidRewriteCount++;
+                  logger.warn('IPFS raw payload CID mismatch during import; rewriting imported references', {
+                    oldCid: doc.cid,
+                    newCid: finalCid,
+                    resourceType: doc.resourceType,
+                    mfsPath: primaryPath || null,
+                  });
+                }
 
-              const finalCid = addResult.cid;
-              if (doc.cid !== finalCid) {
-                await rewriteImportedCidReferences({
-                  oldCid: doc.cid,
-                  newCid: finalCid,
+                extraMfsRestoreCount += await restoreAdditionalMfsPaths(finalCid, mfsPaths, primaryPath);
+                // createPinRecord is an idempotent upsert on (cid, resourceType).
+                await createPinRecord({
+                  cid: finalCid,
                   resourceType: doc.resourceType,
+                  mfsPath: primaryPath || '',
+                  options: { host, path },
                 });
-                cidRewriteCount++;
-                logger.warn('IPFS raw payload CID mismatch during import; rewriting imported references', {
-                  oldCid: doc.cid,
-                  newCid: finalCid,
+                ipfsCount++;
+              } catch (entryError) {
+                logger.warn('IPFS pin restore failed for one entry — skipping it, the import continues', {
+                  cid: doc.cid,
                   resourceType: doc.resourceType,
                   mfsPath: primaryPath || null,
+                  error: entryError?.message ?? String(entryError),
                 });
+                ipfsSkipped++;
               }
-
-              extraMfsRestoreCount += await restoreAdditionalMfsPaths(finalCid, mfsPaths, primaryPath);
-              await upsertImportedPin({ cid: finalCid, resourceType: doc.resourceType, mfsPath: primaryPath });
-              ipfsCount++;
             }
 
             logger.info(
-              `Imported ${ipfsCount} Ipfs pin record(s) from exact backup payloads${ipfsSkipped ? `, skipped ${ipfsSkipped}` : ''}`,
+              `Imported ${ipfsCount} Ipfs pin record(s) from exact backup payloads` +
+                `${ipfsAlreadyPresent ? `, ${ipfsAlreadyPresent} already present (skipped)` : ''}` +
+                `${ipfsSkipped ? `, ${ipfsSkipped} skipped` : ''}`,
             );
             logger.info(
               `IPFS raw payload restore: ${ipfsCount}/${backupPinEntries.length} record(s) restored, ${extraMfsRestoreCount} additional MFS path(s) restored${cidRewriteCount ? `, ${cidRewriteCount} CID rewrite(s)` : ''}`,
@@ -3055,7 +3434,10 @@ try {
           const otherInstances = await CyberiaInstance.find({ code: { $ne: instanceCode } }, { thumbnail: 1 }).lean();
 
           // Add instance-level itemIds (may not appear in any map entity)
-          for (const id of existingInstance.itemIds || []) if (id) dropOlItemIds.add(id);
+          for (const entry of existingInstance.itemIds || []) {
+            const id = typeof entry === 'string' ? entry : entry?.id;
+            if (id) dropOlItemIds.add(id);
+          }
 
           // Add conf entityDefaults and skillConfig itemIds (liveItemIds, deadItemIds, dropItemIds, defaultObjectLayers)
           const existingConf =
@@ -3311,6 +3693,154 @@ try {
       }
     });
 
+  // ── generate-saga: Top-Down PCG guided by LLMs (Semantic Reverse-Engineering) ──
+  program
+    .command('generate-saga')
+    .option(
+      '--prompt <theme>',
+      'Theme seed for the saga. If omitted, a distinct theme is auto-generated from the Cyberia base lore',
+    )
+    .option('--import <file>', 'Load a previously generated payload file (the shape --out writes) into the database')
+    .option('--model <model>', 'Gemini model id (default: gemma-4-26b-a4b-it)')
+    .option('--timeout <ms>', 'Per-request timeout in ms (default: 300000)', (v) => parseInt(v, 10))
+    .option('--thinking-level <level>', 'Gemini thinking level: low | medium | high (default: high)')
+    .option(
+      '--lore-path <path>',
+      'Override path to the base-lore doc (default: src/client/public/cyberia-docs/CYBERIA-LORE.md)',
+    )
+    .option(
+      '--space-context <context>',
+      'Force the auto-theme spatial layer: physical | mixed | hyperspace (default: random ~33% each)',
+    )
+    .option(
+      '--tone <tone>',
+      'Force the auto-theme narrative type: adventure | politics | tragic | comedy (default: random ~25% each)',
+    )
+    .option(
+      '--faction-context <keys>',
+      'Comma-separated factions that DRIVE the auto-theme: zenith | nova | atlas | neutral ' +
+        "(e.g. 'nova,zenith'). If unset, confederations stay background, not the main theme",
+    )
+    .option(
+      '--character-context <keys>',
+      'Comma-separated CHARACTER_NAMES_POOL keys to inspire NPC/character names: low_level_synthetics | ' +
+        'high_fidelity_synthetics | global_latin_diaspora | east_asian_pacific_diaspora | ' +
+        'middle_eastern_turkish_diaspora | sub_saharan_african_diaspora | classic_western_scifi | ' +
+        'mutagen_clans (inspiration only). If unset, a random subset is chosen',
+    )
+    .option(
+      '--cultural-exposure <mode>',
+      'Naming diversity mode: cosmopolitan (high mixing) | local (isolated, consistent). ' +
+        'If unset, chosen at random',
+    )
+    .option(
+      '--temperature <value>',
+      'Model sampling temperature, valid range 0.0 (deterministic) to 2.0 (most creative); ' +
+        'higher = more creative/divergent (default: 2.0 for theme synthesis)',
+      parseFloat,
+    )
+    .option('--out <file>', 'Path to dump the payload JSON (default: ./engine-private/cyberia-sagas/<saga-code>.json)')
+    .option('--dry-run', 'Generate and normalize without writing to the database')
+    .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('Generate (via Google Gemini) or import the non-spatial textual layer of a CyberiaSaga ecosystem')
+    .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 });
+      }
+
+      let models = null;
+      let host;
+      let path;
+
+      if (!options.dryRun) {
+        const deployId = process.env.DEFAULT_DEPLOY_ID;
+        host = process.env.DEFAULT_DEPLOY_HOST;
+        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('generate-saga', { deployId, host, path, db });
+
+        await DataBaseProviderService.load({
+          apis: [
+            'cyberia-saga',
+            'cyberia-map',
+            'cyberia-quest',
+            'cyberia-dialogue',
+            'cyberia-action',
+            'cyberia-skill',
+            'cyberia-instance',
+            'object-layer',
+          ],
+          host,
+          path,
+          db,
+        });
+
+        models = {
+          CyberiaSaga: DataBaseProviderService.getModel('cyberia-saga', { host, path }),
+          CyberiaMap: DataBaseProviderService.getModel('cyberia-map', { host, path }),
+          CyberiaQuest: DataBaseProviderService.getModel('cyberia-quest', { host, path }),
+          CyberiaDialogue: DataBaseProviderService.getModel('cyberia-dialogue', { host, path }),
+          CyberiaAction: DataBaseProviderService.getModel('cyberia-action', { host, path }),
+          CyberiaSkill: DataBaseProviderService.getModel('cyberia-skill', { host, path }),
+          CyberiaInstance: DataBaseProviderService.getModel('cyberia-instance', { host, path }),
+          ObjectLayer: DataBaseProviderService.getModel('object-layer', { host, path }),
+        };
+      }
+
+      try {
+        if (options.import) {
+          await importSaga({
+            file: options.import,
+            models,
+            dryRun: !!options.dryRun,
+            out: options.out,
+          });
+        } else {
+          await generateSaga({
+            prompt: options.prompt,
+            models,
+            model: options.model,
+            timeout: options.timeout,
+            thinkingLevel: options.thinkingLevel,
+            lorePath: options.lorePath,
+            spaceContext: options.spaceContext,
+            tone: options.tone,
+            factionContext: options.factionContext,
+            characterContext: options.characterContext,
+            culturalExposure: options.culturalExposure,
+            temperature: options.temperature,
+            dryRun: !!options.dryRun,
+            out: options.out,
+          });
+        }
+      } catch (err) {
+        logger.error('generate-saga command error:', err);
+        process.exitCode = 1;
+      } finally {
+        if (models) await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+      }
+    });
+
   // ── chain: Hyperledger Besu / ERC-1155 lifecycle commands ────────────────
   const chain = program.command('chain').description('Hyperledger Besu chain & ERC-1155 ObjectLayerToken lifecycle');
 
@@ -4131,7 +4661,13 @@ try {
   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, dialogues, and client-hints into MongoDB')
+    .option(
+      '--mongo-host <mongo-host>',
+      'Mongo host override (forwarded to ol, seed-skills, seed-entities, seed-dialogues, seed-actions-quests, client-hints)',
+    )
+    .description(
+      'Import default Object Layer items, skills, entity defaults, dialogues, actions/quests, and client-hints into MongoDB',
+    )
     .action(async (options) => {
       // Pre-flight: every item id referenced by the fallback world must
       // exist in DefaultCyberiaItems. Drift here causes silent missing
@@ -4148,21 +4684,92 @@ try {
       }
 
       const devFlag = options.dev ? ' --dev' : '';
+      const mongoHostFlag = options.mongoHost ? ` --mongo-host ${options.mongoHost}` : '';
       const instanceCode = process.env.INSTANCE_CODE || 'cyberia-main';
-      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}`);
-      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}`);
+      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-skills${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-entities${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-actions-quests${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}${mongoHostFlag}`);
+    });
+
+  runner.command('sync-src').action(() => {
+    fs.copyFileSync('./cyberia-server/README.md', './src/client/public/cyberia-docs/CYBERIA-SERVER.md');
+    fs.copyFileSync('./cyberia-server/Dockerfile', './src/runtime/cyberia-server/Dockerfile');
+    fs.copyFileSync('./cyberia-client/README.md', './src/client/public/cyberia-docs/CYBERIA-CLIENT.md');
+    fs.copyFileSync('./cyberia-client/Dockerfile', './src/runtime/cyberia-client/Dockerfile');
+    shellExec('cp -a ./engine-private/conf/dd-cyberia/docker-compose/cyberia/. ./src/runtime/engine-cyberia/');
+  });
+
+  runner
+    .command('dev-env')
+    .option('--run', 'Run docker:reset, cluster --dev --reset, docker-image, and docker:up after updating compose.env')
+    .option(
+      '--clean',
+      'Restore repositories to canonical state (git checkout Dockerfile, etc.) before updating compose.env',
+    )
+    .action((options) => {
+      if (options.clean) {
+        shellExec(`node bin run clean`);
+        shellExec(`node bin run clean ./cyberia-server`);
+        shellExec(`node bin run clean ./cyberia-client`);
+        return;
+      }
+      const envPath = `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`;
+      const canonicalDevDockerfile = './src/runtime/engine-cyberia/Dockerfile.dev';
+      fs.writeFileSync(
+        canonicalDevDockerfile,
+        fs
+          .readFileSync(canonicalDevDockerfile, 'utf8')
+          .replace('ENGINE_CYBERIA_REPO="engine-cyberia"', 'ENGINE_CYBERIA_REPO="engine-test-cyberia"')
+          .replace(`    # --mount=type=secret,id=github_token`, `    --mount=type=secret,id=github_token`)
+          .replace(
+            `    # export GITHUB_TOKEN="$(cat /run/secrets/github_token)";`,
+            `    export GITHUB_TOKEN="$(cat /run/secrets/github_token)";`,
+          )
+          .replace(`    for _secret in "$GITHUB_USERNAME"; do`, `    # for _secret in "$GITHUB_USERNAME"; do`)
+          .replace(`    unset GITHUB_USERNAME;`, `    # unset GITHUB_USERNAME;`)
+          .replace(
+            `    # for _secret in "$GITHUB_USERNAME" "$GITHUB_TOKEN"; do`,
+            `    for _secret in "$GITHUB_USERNAME" "$GITHUB_TOKEN"; do`,
+          )
+          .replace(`    # unset GITHUB_TOKEN GITHUB_USERNAME;`, `    unset GITHUB_TOKEN GITHUB_USERNAME;`),
+
+        'utf8',
+      );
+      fs.writeFileSync(
+        './src/cli/image.js',
+        fs
+          .readFileSync('./src/cli/image.js', 'utf8')
+          .replace(
+            `      // addBuildSecret('github_token', process.env.GITHUB_TOKEN);`,
+            `      addBuildSecret('github_token', process.env.GITHUB_TOKEN);`,
+          ),
+        'utf8',
+      );
+      fs.writeFileSync(envPath, fs.readFileSync(envPath, 'utf8').replaceAll('underpost/', 'localhost/'), 'utf8');
+      shellExec('node bin/cyberia run-workflow sync-src');
+      shellExec(`git checkout './src/runtime/cyberia-server/Dockerfile'`);
+      shellExec(`git checkout './src/runtime/cyberia-client/Dockerfile'`);
+      shellExec('node bin/cyberia run-workflow build-manifest');
+      if (options.run) {
+        shellExec('node bin/cyberia run-workflow docker:reset');
+        shellExec('node bin cluster --dev --reset');
+        shellExec('node bin/cyberia run-workflow docker-image engine-cyberia');
+        shellExec('node bin/cyberia run-workflow docker-image cyberia-server');
+        shellExec('node bin/cyberia run-workflow docker-image cyberia-client');
+        shellExec('node bin/cyberia run-workflow docker:up');
+      }
     });
 
   runner
-    .command('seed-skill-config')
-    .option('--instance-code <code>', 'CyberiaInstance code to update (default: $INSTANCE_CODE env or "default")')
+    .command('drop-db')
     .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) => {
+    .description('Drop all Cyberia collections and remove File documents referenced by instance/map thumbnails')
+    .action(async (options = {}) => {
       if (!options.envPath) options.envPath = `./.env`;
       if (fs.existsSync(options.envPath)) dotenv.config({ path: options.envPath, override: true });
 
@@ -4174,7 +4781,6 @@ try {
       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)) {
@@ -4190,42 +4796,133 @@ try {
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-skill-config', { instanceCode, deployId, host, path, db });
+      logger.info('drop-db', { deployId, host, path, db });
+
+      const cyberiaCollections = [
+        'cyberia-entity',
+        'cyberia-map',
+        'cyberia-instance',
+        'cyberia-instance-conf',
+        'cyberia-dialogue',
+        'cyberia-quest',
+        'cyberia-quest-progress',
+        'cyberia-action',
+        'cyberia-skill',
+        'cyberia-entity-type-default',
+        'cyberia-client-hints',
+        'cyberia-saga',
+      ];
 
-      await DataBaseProviderService.load({ apis: ['cyberia-instance', 'cyberia-instance-conf'], host, path, db });
+      await DataBaseProviderService.load({ apis: [...cyberiaCollections, 'file'], host, path, db });
 
-      const CyberiaInstance = DataBaseProviderService.getModel('cyberia-instance', { host, path });
-      const CyberiaInstanceConf = DataBaseProviderService.getModel('cyberia-instance-conf', { host, path });
-
-      const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
+      const File = DataBaseProviderService.getModel('file', { host, path });
 
-      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`,
-        );
+      // Thumbnails on instances/maps are File _id references; collect them before
+      // dropping so the backing File documents don't leak as orphans.
+      const thumbnailFileIds = new Set();
+      for (const api of ['cyberia-instance', 'cyberia-map']) {
+        const Model = DataBaseProviderService.getModel(api, { host, path });
+        const docs = await Model.find({ thumbnail: { $ne: null } }, { thumbnail: 1 }).lean();
+        for (const doc of docs) {
+          if (doc.thumbnail) thumbnailFileIds.add(doc.thumbnail.toString());
+        }
       }
 
-      // 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 });
+      if (thumbnailFileIds.size > 0) {
+        const result = await File.deleteMany({ _id: { $in: [...thumbnailFileIds] } });
+        logger.info(`Removed ${result.deletedCount} thumbnail File document(s)`);
       }
 
-      logger.info(
-        `skillConfig seeded for instance "${instanceCode}" (${DefaultSkillConfig.length} entries)`,
-        DefaultSkillConfig.map((e) => `${e.triggerItemId} → [${e.logicEventIds.join(', ')}]`),
-      );
+      for (const api of cyberiaCollections) {
+        const Model = DataBaseProviderService.getModel(api, { host, path });
+        const result = await Model.deleteMany();
+        logger.info(`Dropped ${result.deletedCount} ${api} document(s)`);
+      }
 
       await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
     });
 
+  const dockerImageIds = ['engine-cyberia', 'cyberia-server', 'cyberia-client'];
+
+  runner.command('deploy [id]').action((id) => {
+    if (!dockerImageIds.includes(id)) {
+      logger.error(`Invalid deploy id: ${id}. Must be one of: ${dockerImageIds.join(', ')}`);
+      process.exit(1);
+    }
+    shellExec(`gh workflow run ${id}.cd.yml -R underpostnet/${id} -f job=deploy`);
+  });
+
+  runner
+    .command('docker-image [id]')
+    .option('--load-tar', 'Load a pre-built image tar archive into the enabled target(s) without building.')
+    .action((id, options) => {
+      // no funca
+      if (options.loadTar) {
+        for (const imageId of dockerImageIds)
+          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.2.70.tar`);
+        return;
+      }
+      switch (id) {
+        case 'engine-cyberia':
+          shellExec(`clear
+node bin/build dd-cyberia --conf
+node bin/build dd-cyberia --update-private
+node bin image --path src/runtime/engine-cyberia \
+  --docker-compose --pull-base --build \
+  --dockerfile-name Dockerfile.dev \
+  --image-name engine-cyberia-dev:v3.2.70 \
+  --image-out-path .
+`);
+          break;
+
+        case 'cyberia-server':
+          shellExec(
+            `clear && node bin/cyberia run-workflow build-server-dashboard --output-path ./cyberia-server/public/index.html`,
+          );
+          shellExec(`
+cp -f src/runtime/cyberia-server/Dockerfile.dev cyberia-server/Dockerfile.dev
+node bin image --path cyberia-server \
+  --docker-compose --pull-base --build \
+  --dockerfile-name Dockerfile.dev \
+  --image-name cyberia-server-dev:v3.2.70 \
+  --image-out-path .
+`);
+          break;
+        case 'cyberia-client':
+          shellExec(`clear
+cp -f src/runtime/cyberia-client/Dockerfile.dev cyberia-client/Dockerfile.dev
+node bin image --path cyberia-client \
+  --docker-compose --pull-base --build \
+  --dockerfile-name Dockerfile.dev \
+  --image-name cyberia-client-dev:v3.2.70 \
+  --image-out-path .
+`);
+          break;
+      }
+    });
+
+  {
+    // docker compose lyfe cycle commands for the dd-cyberia deployment
+    const dockerComposeId = 'cyberia';
+    const deployId = 'dd-cyberia';
+    const commands = {
+      'docker:generate': `node bin docker-compose --generate --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:up': `node bin docker-compose --up --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:up:build': `node bin docker-compose --up --build --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:down': `node bin docker-compose --down --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:down:volumes': `node bin docker-compose --down --volumes --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:restart': `node bin docker-compose --restart --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:pull': `node bin docker-compose --pull --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:logs': `node bin docker-compose --logs --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:status': `node bin docker-compose --status --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+      'docker:reset': `node bin docker-compose --reset --deploy-id ${deployId} --docker-compose-id ${dockerComposeId}`,
+    };
+    for (const [cmd, action] of Object.entries(commands))
+      runner.command(cmd).action(() => {
+        shellExec(action);
+      });
+  }
+
   runner
     .command('seed-dialogues')
     .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
@@ -4281,6 +4978,202 @@ try {
       await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
     });
 
+  runner
+    .command('seed-actions-quests')
+    .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 DefaultCyberiaActions + DefaultCyberiaQuests into Mongo (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-actions-quests', { deployId, host, path, db });
+
+      await DataBaseProviderService.load({ apis: ['cyberia-action', 'cyberia-quest'], host, path, db });
+
+      const CyberiaAction = DataBaseProviderService.getModel('cyberia-action', { host, path });
+      const CyberiaQuest = DataBaseProviderService.getModel('cyberia-quest', { host, path });
+
+      let actions = 0;
+      for (const a of DefaultCyberiaActions) {
+        await CyberiaAction.findOneAndUpdate({ code: a.code }, { $set: a }, { upsert: true });
+        actions++;
+      }
+      let quests = 0;
+      for (const q of DefaultCyberiaQuests) {
+        await CyberiaQuest.findOneAndUpdate({ code: q.code }, { $set: q }, { upsert: true });
+        quests++;
+      }
+
+      logger.info(`seed-actions-quests: ${actions} actions, ${quests} quests upserted`);
+
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+    });
+
+  runner
+    .command('seed-skills')
+    .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 DefaultSkillConfig into the cyberia-skill collection (full records, 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-skills', { deployId, host, path, db });
+
+      await DataBaseProviderService.load({ apis: ['cyberia-skill'], host, path, db });
+
+      const CyberiaSkill = DataBaseProviderService.getModel('cyberia-skill', { host, path });
+
+      // Upsert each skill record keyed by triggerItemId — full record (logic
+      // event keys + expanded skills metadata), unlike the instance-conf
+      // skillConfig schema which keeps only triggerItemId + logicEventIds.
+      let upserted = 0;
+      for (const sk of DefaultSkillConfig) {
+        await CyberiaSkill.findOneAndUpdate(
+          { triggerItemId: sk.triggerItemId },
+          { $set: { logicEventIds: sk.logicEventIds || [], skills: sk.skills || [] } },
+          { upsert: true },
+        );
+        upserted++;
+      }
+
+      logger.info(
+        `seed-skills: ${upserted} skill records upserted`,
+        DefaultSkillConfig.map((e) => `${e.triggerItemId} → [${(e.logicEventIds || []).join(', ')}]`),
+      );
+
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+    });
+
+  runner
+    .command('seed-entities')
+    .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
+    .option('--mongo-host <mongo-host>', 'Mongo host override')
+    .option('--dev', 'Force development environment')
+    .description('Upsert ENTITY_TYPE_DEFAULTS into the cyberia-entity-type-default 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-entities', { deployId, host, path, db });
+
+      await DataBaseProviderService.load({ apis: ['cyberia-entity-type-default'], host, path, db });
+
+      const CyberiaEntityTypeDefault = DataBaseProviderService.getModel('cyberia-entity-type-default', { host, path });
+
+      // Reconcile DB indexes with the current schema. This drops the obsolete
+      // unique (entityType, liveItemIds) index from earlier builds so the same
+      // itemId may appear in multiple same-type defaults (subset matching), and
+      // (re)creates the non-unique liveItemIds lookup index.
+      try {
+        await CyberiaEntityTypeDefault.syncIndexes();
+      } catch (error) {
+        logger.warn(`seed-entities: syncIndexes skipped: ${error?.message || error}`);
+      }
+
+      // Resolution is by subset containment (most-specific match wins), so there
+      // is NO per-itemId uniqueness — the same itemId may appear in many entries
+      // (across entity types, or within one type at different specificity). Every
+      // entry is upserted, idempotently, by its exact (entityType, liveItemIds) key.
+      let upserted = 0;
+      for (const ed of ENTITY_TYPE_DEFAULTS) {
+        await CyberiaEntityTypeDefault.findOneAndUpdate(
+          { entityType: ed.entityType, liveItemIds: ed.liveItemIds || [] },
+          {
+            $set: {
+              entityType: ed.entityType,
+              liveItemIds: ed.liveItemIds || [],
+              deadItemIds: ed.deadItemIds || [],
+              dropItemIds: ed.dropItemIds || [],
+              defaultObjectLayers: ed.defaultObjectLayers || [],
+              behavior: ed.behavior || '',
+            },
+          },
+          { upsert: true },
+        );
+        upserted++;
+      }
+
+      logger.info(
+        `seed-entities: ${upserted} entity-type-default records upserted`,
+        ENTITY_TYPE_DEFAULTS.map((e) => `${e.entityType} → [${(e.liveItemIds || []).join(', ')}]`),
+      );
+
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+    });
+
   runner
     .command('generate-semantic-examples')
     .option('--seed <seed>', 'Base seed string (each type gets a unique suffix appended)', 'example')
@@ -4364,6 +5257,14 @@ try {
       // Edit the canonical sources; never hand-edit these generated outputs.
       fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-CLIENT.md', './cyberia-client/README.md');
       fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-SERVER.md', './cyberia-server/README.md');
+      fs.copyFileSync(
+        './.github/workflows/cyberia-client.cd.yml',
+        './cyberia-client/.github/workflows/cyberia-client.cd.yml',
+      );
+      fs.copyFileSync(
+        './.github/workflows/cyberia-server.cd.yml',
+        './cyberia-server/.github/workflows/cyberia-server.cd.yml',
+      );
       logger.info(`run-workflow build-manifest complete (${isDev ? 'dev' : 'prod'})`);
     });
 
@@ -4407,7 +5308,7 @@ try {
     throw new Error('Trigger underpost passthrough');
   }
 
-  program.parse();
+  await program.parseAsync();
 } catch (error) {
   // ONLY reroute on the explicit passthrough sentinel. Any other thrown
   // error (subprocess non-zero from shellExec's fail-fast default, CLI
@@ -4420,7 +5321,7 @@ try {
     process.argv = process.argv.filter((c) => c !== 'underpost');
     logger.warn('Rerouting to underpost cli...');
     try {
-      underpostProgram.parse();
+      await underpostProgram.parseAsync();
     } catch (err) {
       logger.error(err);
       process.exit(1);