@underpostnet/cyberia 3.2.80 → 3.3.0

package/bin/index.js

@@ -17,7 +17,7 @@ import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.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 { etcHostFactory, loadConfServerJson, normalizeInstanceTopology } from '../src/server/conf.js';
 import {
   ObjectLayerEngine,
   resolveCanonicalCid,
@@ -51,6 +51,7 @@ import {
 } from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
 
 import {
+  DEFAULT_INSTANCE_CODE,
   ITEM_TYPES as itemTypes,
   DefaultCyberiaItems,
 } from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
@@ -95,6 +96,22 @@ async function connectDbForChain({ envPath, mongoHost }) {
 /** @type {Function} */
 const logger = loggerFactory(import.meta);
 
+const CYBERIA_DOCKER_HOST_ALIASES = ['cyberia-client', 'cyberia-server', 'engine-cyberia'];
+
+const installCyberiaDockerHostAliases = () => {
+  try {
+    const { changed } = etcHostFactory(CYBERIA_DOCKER_HOST_ALIASES, {
+      append: true,
+      blockId: 'dd-cyberia-docker-compose',
+    });
+    return { aliases: CYBERIA_DOCKER_HOST_ALIASES, changed };
+  } catch (error) {
+    if (error?.code === 'EACCES' || error?.code === 'EPERM')
+      throw new Error('Cannot update /etc/hosts for Cyberia Docker aliases. Re-run the workflow as root.');
+    throw error;
+  }
+};
+
 try {
   const program = new Command();
 
@@ -219,7 +236,6 @@ try {
           deployId,
           host,
           path,
-          db,
         });
 
         await DataBaseProviderService.load({
@@ -240,6 +256,17 @@ try {
         /** @type {import('mongoose').Model} */
         const Ipfs = DataBaseProviderService.getModel('ipfs', { host, path });
 
+        // Idempotent repair, run only before flows that write: collapses legacy
+        // duplicates and upgrades the data.item.id index to unique so every
+        // later write has exactly one document to land on. Read-only
+        // subcommands stay side-effect free — findByItemId already resolves the
+        // same canonical document whether or not duplicates are still present.
+        if (options.import || options.importTypes || options.drop || options.generate) {
+          const { removedIds, indexUpgraded } = await ObjectLayer.ensureUniqueItemIdIndex();
+          if (removedIds.length > 0) logger.warn(`Removed ${removedIds.length} duplicate ObjectLayer document(s)`);
+          if (indexUpgraded) logger.info('Upgraded data.item.id index to unique');
+        }
+
         if (options.drop) {
           // Parse comma-separated item IDs for targeted drop; if none provided, drop everything
           const dropItemIds = itemId
@@ -423,7 +450,7 @@ try {
             });
 
             // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
-            const existingOL = await ObjectLayer.findOne({ 'data.item.id': currentItemId });
+            const existingOL = await ObjectLayer.findByItemId(currentItemId);
             let objectLayer;
 
             if (existingOL) {
@@ -441,7 +468,6 @@ try {
               let stagingFileDoc = null;
               let stagingAtlasDoc = null;
               let stagingCid = '';
-              let stagingSha256 = '';
               try {
                 const itemKey = currentItemId;
 
@@ -530,8 +556,7 @@ try {
                 stagingData.render.cid = importItemCid;
                 stagingData.render.metadataCid = importItemMetadataCid;
 
-                // Pin data JSON to IPFS (compute final SHA-256 in memory)
-                stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                // Pin data JSON to IPFS
                 try {
                   const ipfsDataResult = await IpfsClient.addJsonToIpfs(
                     stagingData,
@@ -569,10 +594,9 @@ try {
                 // 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, {
+                // Single atomic upsert on the natural key; empty staged CIDs keep their stored value
+                objectLayer = await ObjectLayer.upsertByItemId({
                   data: stagingData,
-                  sha256: stagingSha256,
                   cid: stagingCid,
                   objectLayerRenderFramesId: newRenderFrames._id,
                   atlasSpriteSheetId: stagingAtlasDoc._id,
@@ -583,14 +607,13 @@ try {
                   await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
                 }
 
-                logger.info(`[cut-over] Live document ${existingOL._id} updated atomically`);
+                logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically`);
               } else {
                 // Rollback: only File/AtlasSpriteSheet were written, clean those up
                 if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
                 logger.warn(`[cut-over] Staging rolled back for ${currentItemId}, live document preserved`);
+                objectLayer = await ObjectLayer.findByItemId(currentItemId);
               }
-
-              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...`);
@@ -605,7 +628,6 @@ try {
               let stagingFileDoc = null;
               let stagingAtlasDoc = null;
               let stagingCid = '';
-              let stagingSha256 = '';
               try {
                 const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
                   objectLayerRenderFramesData,
@@ -689,7 +711,6 @@ try {
                 stagingData.render.cid = importItemCid;
                 stagingData.render.metadataCid = importItemMetadataCid;
 
-                stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
                 try {
                   const ipfsDataResult = await IpfsClient.addJsonToIpfs(
                     stagingData,
@@ -722,9 +743,8 @@ try {
 
               if (cutoverReady) {
                 const newRenderFrames = await ObjectLayerRenderFrames.create(objectLayerRenderFramesData);
-                objectLayer = await ObjectLayer.create({
+                objectLayer = await ObjectLayer.upsertByItemId({
                   data: stagingData,
-                  sha256: stagingSha256,
                   cid: stagingCid,
                   objectLayerRenderFramesId: newRenderFrames._id,
                   atlasSpriteSheetId: stagingAtlasDoc._id,
@@ -826,7 +846,7 @@ try {
 
             if (shouldGenerateAtlas) {
               // Check if an ObjectLayer with the same item.id already exists (upsert by item ID)
-              const existingOL = await ObjectLayer.findOne({ 'data.item.id': objectLayerId });
+              const existingOL = await ObjectLayer.findByItemId(objectLayerId);
               let objectLayer;
 
               if (existingOL) {
@@ -844,7 +864,6 @@ try {
                 let stagingFileDoc = null;
                 let stagingAtlasDoc = null;
                 let stagingCid = '';
-                let stagingSha256 = '';
                 try {
                   const itemKey = objectLayerId;
 
@@ -932,8 +951,7 @@ try {
                   stagingData.render.cid = importAtlasCid;
                   stagingData.render.metadataCid = importAtlasMetadataCid;
 
-                  // Pin data JSON to IPFS (compute final SHA-256 in memory)
-                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
+                  // Pin data JSON to IPFS
                   try {
                     const ipfsDataResult = await IpfsClient.addJsonToIpfs(
                       stagingData,
@@ -969,9 +987,8 @@ try {
                   const oldRenderFramesId = existingOL.objectLayerRenderFramesId;
                   const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
 
-                  await ObjectLayer.findByIdAndUpdate(existingOL._id, {
+                  objectLayer = await ObjectLayer.upsertByItemId({
                     data: stagingData,
-                    sha256: stagingSha256,
                     cid: stagingCid,
                     objectLayerRenderFramesId: newRenderFrames._id,
                     atlasSpriteSheetId: stagingAtlasDoc._id,
@@ -980,13 +997,12 @@ try {
                   if (oldRenderFramesId) {
                     await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
                   }
-                  logger.info(`[cut-over] Live document ${existingOL._id} updated atomically`);
+                  logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically`);
                 } else {
                   if (stagingFileDoc) await File.findByIdAndDelete(stagingFileDoc._id);
                   logger.warn(`[cut-over] Staging rolled back for ${objectLayerId}, live document preserved`);
+                  objectLayer = await ObjectLayer.findByItemId(objectLayerId);
                 }
-
-                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...`);
@@ -1001,7 +1017,6 @@ try {
                 let stagingFileDoc = null;
                 let stagingAtlasDoc = null;
                 let stagingCid = '';
-                let stagingSha256 = '';
                 try {
                   const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
                     entry.objectLayerRenderFramesData,
@@ -1085,7 +1100,6 @@ try {
                   stagingData.render.cid = importAtlasCid;
                   stagingData.render.metadataCid = importAtlasMetadataCid;
 
-                  stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
                   try {
                     const ipfsDataResult = await IpfsClient.addJsonToIpfs(
                       stagingData,
@@ -1118,9 +1132,8 @@ try {
 
                 if (cutoverReady) {
                   const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-                  objectLayer = await ObjectLayer.create({
+                  objectLayer = await ObjectLayer.upsertByItemId({
                     data: stagingData,
-                    sha256: stagingSha256,
                     cid: stagingCid,
                     objectLayerRenderFramesId: newRenderFrames._id,
                     atlasSpriteSheetId: stagingAtlasDoc._id,
@@ -1143,7 +1156,7 @@ try {
               if (existingItemIds.has(objectLayerId)) continue;
 
               // --import all: create documents without atlas generation
-              const existingOL = await ObjectLayer.findOne({ 'data.item.id': objectLayerId });
+              const existingOL = await ObjectLayer.findByItemId(objectLayerId);
               let objectLayer;
 
               if (existingOL) {
@@ -1156,15 +1169,13 @@ try {
                 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, {
+                objectLayer = await ObjectLayer.upsertByItemId({
                   data: stagingData,
-                  sha256: stagingSha256,
                   objectLayerRenderFramesId: newRenderFrames._id,
                 });
 
@@ -1172,20 +1183,17 @@ try {
                   await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
                 }
 
-                objectLayer = await ObjectLayer.findById(existingOL._id);
-                logger.info(`[cut-over] Live document ${existingOL._id} updated atomically (atlas skipped)`);
+                logger.info(`[cut-over] Live document ${objectLayer._id} updated atomically (atlas skipped)`);
               } else {
-                // New item: create with sha256 populated (no atlas for bulk import)
+                // New item (no atlas for bulk import)
                 const stagingData = JSON.parse(JSON.stringify(entry.data));
                 if (!stagingData.render) stagingData.render = {};
                 stagingData.render.cid = '';
                 stagingData.render.metadataCid = '';
-                const stagingSha256 = ObjectLayerEngine.computeSha256(stagingData);
 
                 const newRenderFrames = await ObjectLayerRenderFrames.create(entry.objectLayerRenderFramesData);
-                objectLayer = await ObjectLayer.create({
+                objectLayer = await ObjectLayer.upsertByItemId({
                   data: stagingData,
-                  sha256: stagingSha256,
                   objectLayerRenderFramesId: newRenderFrames._id,
                 });
               }
@@ -1215,9 +1223,7 @@ try {
           logger.info(`Showing frame for item: ${itemId}, direction: ${direction}, frame: ${frameIndexNum}`);
 
           // Find ObjectLayer by item-id
-          const objectLayer = await ObjectLayer.findOne({ 'data.item.id': itemId }).populate(
-            'objectLayerRenderFramesId',
-          );
+          const objectLayer = await ObjectLayer.findByItemId(itemId).populate('objectLayerRenderFramesId');
 
           if (!objectLayer) {
             logger.error(`ObjectLayer not found for item-id: ${itemId}`);
@@ -1301,9 +1307,7 @@ try {
           }
 
           // Find ObjectLayer by item-id
-          const objectLayer = await ObjectLayer.findOne({ 'data.item.id': itemId }).populate(
-            'objectLayerRenderFramesId',
-          );
+          const objectLayer = await ObjectLayer.findByItemId(itemId).populate('objectLayerRenderFramesId');
 
           if (!objectLayer) {
             logger.error(`ObjectLayer not found for item-id: ${itemId}`);
@@ -1437,7 +1441,7 @@ try {
           logger.info(`Looking up atlas sprite sheet for item: ${itemId}`);
 
           // Find ObjectLayer by item-id
-          const objectLayer = await ObjectLayer.findOne({ 'data.item.id': itemId });
+          const objectLayer = await ObjectLayer.findByItemId(itemId);
 
           if (!objectLayer) {
             logger.error(`ObjectLayer not found for item-id: ${itemId}`);
@@ -1954,7 +1958,7 @@ try {
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('instance env', { env: options.envPath, deployId, host, path, db });
+      logger.info('instance env', { env: options.envPath, deployId, host, path });
 
       await DataBaseProviderService.load({
         apis: [
@@ -2679,6 +2683,12 @@ try {
 
         logger.info('Importing instance', { code: instanceCode, backupDir });
 
+        // Idempotent: a backup restore writes object layers, so collapse any
+        // legacy duplicates and make the data.item.id index unique first.
+        const { removedIds, indexUpgraded } = await ObjectLayer.ensureUniqueItemIdIndex();
+        if (removedIds.length > 0) logger.warn(`Removed ${removedIds.length} duplicate ObjectLayer document(s)`);
+        if (indexUpgraded) logger.info('Upgraded data.item.id index to unique');
+
         // Item ids belonging to this instance (collected from imported object
         // layers + the instance doc) — used to backfill missing skills from the
         // canonical DefaultSkillConfig when the backup predates the skill model.
@@ -3013,12 +3023,21 @@ try {
           let olCount = 0;
           for (const file of olFiles) {
             const olData = fs.readJsonSync(`${olDir}/${file}`);
-            await ObjectLayer.deleteOne({ _id: olData._id });
-            if (olData.sha256) {
-              await ObjectLayer.deleteOne({ sha256: olData.sha256 });
+            const olItemId = olData.data?.item?.id;
+            if (!olItemId) {
+              logger.warn(`Skipping object-layer file '${file}' — missing data.item.id`);
+              continue;
             }
-            await ObjectLayer.create(olData);
-            if (olData.data?.item?.id) importedItemIds.add(olData.data.item.id);
+            // preserveUUID only applies to items this database does not have yet.
+            // An item that already exists keeps its own _id and simply absorbs the
+            // backup's attribute values, so a restore can never fork data.item.id
+            // into two documents. sha256 needs no separate cleanup: it is derived
+            // from data, so an identical hash implies the same item id.
+            const existingOL = await ObjectLayer.findByItemId(olItemId);
+            if (!existingOL && olData._id) await ObjectLayer.deleteOne({ _id: olData._id });
+
+            await ObjectLayer.upsertByItemId(olData);
+            importedItemIds.add(olItemId);
             olCount++;
           }
           logger.info(`Imported ${olCount} ObjectLayer document(s)`);
@@ -3892,7 +3911,7 @@ try {
             ? db.host
             : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-        logger.info('generate-saga', { deployId, host, path, db });
+        logger.info('generate-saga', { deployId, host, path });
 
         await DataBaseProviderService.load({
           apis: [
@@ -4835,6 +4854,7 @@ try {
       '--clean',
       'Restore repositories to canonical state (git checkout Dockerfile, etc.) before updating compose.env',
     )
+    .option('--test', 'Test DNS connectivity accross cyberia deployments')
     .option('--reset', 'Reset the development environment before updating compose.env')
     .action((options) => {
       if (options.reset) {
@@ -4848,6 +4868,25 @@ try {
         shellExec(`node bin run clean ./cyberia-client`);
         return;
       }
+      if (options.test) {
+        const testHosts = [
+          'localhost',
+          'localhost:4005',
+          'localhost:8081',
+          'localhost:8082',
+          'engine-cyberia',
+          'cyberia-server',
+          'cyberia-client',
+        ];
+        const testPaths = ['/', '/TEST', '/FOREST'];
+        for (const host of testHosts) {
+          for (const path of testPaths) {
+            shellExec(`curl -L -v -i -s http://${host}${path} | head -n 10`, {
+              silentOnError: true,
+            });
+          }
+        }
+      }
       const envPath = `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`;
       const canonicalDevDockerfile = './src/runtime/engine-cyberia/Dockerfile.dev';
       fs.writeFileSync(
@@ -4930,7 +4969,7 @@ try {
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('drop-db', { deployId, host, path, db });
+      logger.info('drop-db', { deployId, host, path });
 
       const cyberiaCollections = [
         'cyberia-entity',
@@ -4990,6 +5029,19 @@ try {
     shellExec(`gh workflow run ${id}.cd.yml -R underpostnet/${id} -f job=deploy`);
   });
 
+  runner
+    .command('test')
+    .option('--n-con <connections>', 'Number of concurrent WebSocket connections')
+    .option('--duration <ms>', 'Load test duration in milliseconds')
+    .option('--tap-freq <seconds>', 'Frequency of tap events in seconds')
+    .action((options) => {
+      shellExec(`CYBERIA_LOAD_WS_URL=ws://localhost:8081/ws \
+CYBERIA_LOAD_CONNECTIONS=${options.nCon ?? 40} \
+CYBERIA_LOAD_TAP_FREQUENCY=${options.tapFreq ?? 5} \
+CYBERIA_LOAD_DURATION_MS=${options.duration ?? 1000 * 60 * 30} \
+c8 mocha test/cyberia-load.test.js`);
+    });
+
   runner
     .command('docker-image [id]')
     .option('--load-tar', 'Load a pre-built image tar archive into the enabled target(s) without building.')
@@ -4997,7 +5049,7 @@ try {
       // no funca
       if (options.loadTar) {
         for (const imageId of dockerImageIds)
-          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.2.80.tar`);
+          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.3.0.tar`);
         return;
       }
       switch (id) {
@@ -5008,7 +5060,7 @@ node bin/build dd-cyberia --update-private
 node bin image --path src/runtime/engine-cyberia \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name engine-cyberia-dev:v3.2.80 \
+  --image-name engine-cyberia-dev:v3.3.0 \
   --image-out-path .
 `);
           break;
@@ -5019,7 +5071,7 @@ cp -f src/runtime/cyberia-server/Dockerfile.dev cyberia-server/Dockerfile.dev
 node bin image --path cyberia-server \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-server-dev:v3.2.80 \
+  --image-name cyberia-server-dev:v3.3.0 \
   --image-out-path .
 `);
           break;
@@ -5029,7 +5081,7 @@ cp -f src/runtime/cyberia-client/Dockerfile.dev cyberia-client/Dockerfile.dev
 node bin image --path cyberia-client \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-client-dev:v3.2.80 \
+  --image-name cyberia-client-dev:v3.3.0 \
   --image-out-path .
 `);
           break;
@@ -5038,6 +5090,10 @@ node bin image --path cyberia-client \
 
   for (const [cmd, action] of Object.entries(DOCKER_SCRIPTS))
     runner.command(cmd).action(() => {
+      if (cmd === 'docker:up' || cmd === 'docker:up:build' || cmd === 'docker:restart') {
+        const { aliases, changed } = installCyberiaDockerHostAliases();
+        logger.info(`Docker host aliases ${changed ? 'installed' : 'already configured'}`, { aliases });
+      }
       shellExec(action);
     });
 
@@ -5074,7 +5130,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-dialogues', { deployId, host, path, db });
+      logger.info('seed-dialogues', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-dialogue'], host, path, db });
 
@@ -5129,7 +5185,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-actions-quests', { deployId, host, path, db });
+      logger.info('seed-actions-quests', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-action', 'cyberia-quest'], host, path, db });
 
@@ -5185,7 +5241,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-skills', { deployId, host, path, db });
+      logger.info('seed-skills', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-skill'], host, path, db });
 
@@ -5245,7 +5301,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-entities', { deployId, host, path, db });
+      logger.info('seed-entities', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-entity-type-default'], host, path, db });
 
@@ -5353,6 +5409,84 @@ node bin image --path cyberia-client \
       logger.info('All semantic examples generated.');
     });
 
+  // Instance id → project root. Single source of truth for the workloads this
+  // workflow builds: both the k8s manifests and the status page artifacts each
+  // project ships are resolved from this list plus conf.instances.json.
+  const CYBERIA_INSTANCE_PROJECTS = [
+    { id: 'mmo-client', rootPath: './cyberia-client' },
+    { id: 'mmo-server', rootPath: './cyberia-server' },
+  ];
+  const CYBERIA_CONF_INSTANCES_PATH = './engine-private/conf/dd-cyberia/conf.instances.json';
+  const CYBERIA_CONF_SSR_PATH = './engine-private/conf/dd-cyberia/conf.ssr.json';
+  // Copy shared by the server and the client for a given status code. A status
+  // without an entry falls back to its conf.ssr.json view title.
+  const CYBERIA_STATUS_PAGE_META = {
+    404: {
+      title: 'Cyberia — Sector Not Found',
+      description: 'Cyberia Online 404 — the requested sector is not on the grid.',
+    },
+  };
+
+  /**
+   * Reads the raw (unexpanded) conf.instances.json entries.
+   * @returns {Array<object>} Instance entries, or an empty list when unavailable.
+   */
+  const readCyberiaConfInstances = () => {
+    try {
+      return JSON.parse(fs.readFileSync(CYBERIA_CONF_INSTANCES_PATH, 'utf8'));
+    } catch (err) {
+      logger.warn(`Could not read ${CYBERIA_CONF_INSTANCES_PATH}: ${err.message}`);
+      return [];
+    }
+  };
+
+  /**
+   * Resolves the SSR view that renders a status page. The view is declared in
+   * conf.ssr.json as a route whose path is the bare status code (`/404`), the
+   * same declaration the PWA build turns into `/404/index.html`.
+   * @param {string} status - HTTP status code.
+   * @returns {{ client: string, title: string }|null} View descriptor, or null when undeclared.
+   */
+  const resolveStatusPageView = (status) => {
+    if (!fs.existsSync(CYBERIA_CONF_SSR_PATH)) return null;
+    const confSSR = JSON.parse(fs.readFileSync(CYBERIA_CONF_SSR_PATH, 'utf8'));
+    for (const clientConf of Object.values(confSSR))
+      for (const view of clientConf?.views || []) if (view.path === `/${status}`) return view;
+    return null;
+  };
+
+  /**
+   * Renders one custom status page to a static HTML artifact. The workloads no
+   * longer serve error pages themselves — the document is carried into the
+   * gateway config by `run instance-build-manifest`, so this only has to place
+   * it at the `hostPath` the instance declares.
+   * @param {string} status - HTTP status code.
+   * @param {string} outputPath - Destination HTML path.
+   * @param {boolean} [dev] - Render the development variant.
+   * @returns {boolean} True when the artifact was rendered.
+   */
+  const buildCyberiaStatusPage = ({ status, outputPath, dev = false }) => {
+    const view = resolveStatusPageView(status);
+    const pagePath = `./src/client/ssr/views/${view?.client || `Cyberia${status}`}.js`;
+    if (!fs.existsSync(pagePath)) {
+      logger.warn(`[build-status-page] No SSR view for status ${status}; skipping`, { pagePath, outputPath });
+      return false;
+    }
+    const meta = CYBERIA_STATUS_PAGE_META[status] || {};
+    const title = meta.title || view?.title || `Cyberia — ${status}`;
+    const description = meta.description || `Cyberia Online ${status}.`;
+    shellExec(
+      `node bin static --page ${pagePath}` +
+        ` --output-path ${outputPath}` +
+        ` --title '${title}'` +
+        ` --favicon /favicon.ico` +
+        ` --description '${description}'` +
+        ` --lang en` +
+        ` --env ${dev ? 'development' : 'production'}`,
+    );
+    return true;
+  };
+
   runner
     .command('build-manifest')
     .option(
@@ -5385,24 +5519,24 @@ node bin image --path cyberia-client \
       // A variant declared in conf.instances.json without the instance
       // directory is silently skipped so the Dockerfile never tries to
       // copy a non-existent directory and the container build does not fail.
-      const confInstancesPath = './engine-private/conf/dd-cyberia/conf.instances.json';
       const cyberiaInstancesDir = '/home/dd/cyberia-instances';
       let instanceCodes = 'amethyst-strata-expansion,FOREST'; // fallback
+      const confInstancesEntries = readCyberiaConfInstances();
       try {
-        const confInstances = JSON.parse(fs.readFileSync(confInstancesPath, 'utf8'));
-        const serverInstances = confInstances.filter((inst) => inst.runtime === 'cyberia-server');
+        const serverInstances = confInstancesEntries.filter((inst) => inst.runtime === 'cyberia-server');
         const codes = new Set();
         for (const inst of serverInstances) {
           if (inst.multiInstance?.variants) {
-            for (const v of inst.multiInstance.variants) {
-              if (!v.code) continue;
+            const topology = normalizeInstanceTopology(inst.multiInstance, `dd-cyberia/${inst.id}`);
+            for (const v of topology.variants) {
+              const code = v.path === '/' ? DEFAULT_INSTANCE_CODE : v.code;
               // Skip codes that have no on-disk instance backup dir
-              const instanceDir = `${cyberiaInstancesDir}/instances/${v.code}`;
+              const instanceDir = `${cyberiaInstancesDir}/instances/${code}`;
               if (!fs.existsSync(instanceDir)) {
-                logger.info(`[build-manifest] Skipping code "${v.code}": no instance dir at ${instanceDir}`);
+                logger.info(`[build-manifest] Skipping code "${code}": no instance dir at ${instanceDir}`);
                 continue;
               }
-              codes.add(v.code);
+              codes.add(code);
             }
           }
         }
@@ -5413,7 +5547,7 @@ node bin image --path cyberia-client \
           logger.warn(`[build-manifest] No valid instance codes found; keeping fallback: ${instanceCodes}`);
         }
       } catch (err) {
-        logger.warn(`[build-manifest] Could not read ${confInstancesPath}: ${err.message}; using fallback`);
+        logger.warn(`[build-manifest] Could not read ${CYBERIA_CONF_INSTANCES_PATH}: ${err.message}; using fallback`);
       }
 
       // ── Update Dockerfile.dev + Dockerfile INSTANCE_CODES build arg ──────
@@ -5474,33 +5608,46 @@ node bin image --path cyberia-client \
         logger.warn(`[build-manifest] Could not update ${catalogPath}: ${err.message}`);
       }
 
+      // ── Build SSR views ──────────────────────────────────────────────────
+      // Status pages are rendered BEFORE the manifests: the gateway manifests
+      // embed each document declared under an instance's `customStatusPages`,
+      // so the artifact has to exist at its `hostPath` by manifest time.
+      const statusPagesBuilt = [];
+      for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS) {
+        const instance = confInstancesEntries.find((entry) => entry.id === id);
+        for (const page of instance?.customStatusPages || []) {
+          if (!page?.status || !page?.hostPath) continue;
+          const outputPath = nodePath.normalize(`${rootPath}/${page.hostPath}`);
+          if (buildCyberiaStatusPage({ status: page.status, outputPath, dev: isDev }))
+            statusPagesBuilt.push({ instance: id, status: page.status, outputPath });
+        }
+      }
+      logger.info('[build-manifest] Custom status pages built', statusPagesBuilt);
+      shellExec(
+        `node bin/cyberia run-workflow build-server-dashboard --output-path ./cyberia-server/public/index.html`,
+      );
+
       // ── Build dev manifests (always --kind --dev) ────────────────────────
       {
         const flags = `--kind --dev${nodeFlag}`;
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' ${flags}`);
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' ${flags}`);
+        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
+          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
       }
       // ── Build prod manifests (--kubeadm, no --dev) ───────────────────────
       if (!isDev) {
         const flags = `--kubeadm${nodeFlag}`;
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' ${flags}`);
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' ${flags}`);
+        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
+          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
       }
 
-      // ── Build SSR views ──────────────────────────────────────────────────
-      const env404 = isDev ? ' --dev' : '';
-      shellExec(
-        `node bin/cyberia run-workflow build-cyberia-404 --output-path ./cyberia-server/public/404.html${env404}`,
-      );
-      shellExec(`node bin/cyberia run-workflow build-cyberia-404 --output-path ./cyberia-client/bin/404.html${env404}`);
-      shellExec(
-        `node bin/cyberia run-workflow build-server-dashboard --output-path ./cyberia-server/public/index.html`,
-      );
-
       // Copy canonical doc sources into the generated project READMEs.
       // Edit the canonical sources; never hand-edit these generated outputs.
+      fs.copySync('./deploy/lib', './cyberia-server/deploy/lib', { overwrite: true });
+      fs.copySync('./deploy/lib', './cyberia-client/deploy/lib', { overwrite: true });
       fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-CLIENT.md', './cyberia-client/README.md');
+      fs.copySync('./deploy/cyberia-client', './cyberia-client/deploy');
       fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-SERVER.md', './cyberia-server/README.md');
+      fs.copySync('./deploy/cyberia-server', './cyberia-server/deploy');
       fs.copyFileSync(
         './.github/workflows/cyberia-client.cd.yml',
         './cyberia-client/.github/workflows/cyberia-client.cd.yml',
@@ -5565,27 +5712,54 @@ node bin image --path cyberia-client \
       );
     });
 
+  runner
+    .command('build-status-page')
+    .requiredOption(
+      '--status <status>',
+      'HTTP status code to render (must be declared as an SSR view in conf.ssr.json).',
+    )
+    .option('--dev', 'Build a development variant of the status page.')
+    .option(
+      '--output-path <path>',
+      'Output path for the rendered HTML. Defaults to the `hostPath` the mmo-server instance declares for the status.',
+    )
+    .description(
+      'Build one custom status page artifact. The SSR view is resolved from the conf.ssr.json route whose path is ' +
+        'the bare status code; the rendered document is served by the gateway, not by the workload.',
+    )
+    .action((options) => {
+      const status = `${options.status}`;
+      const statusPage = (
+        readCyberiaConfInstances().find((entry) => entry.id === 'mmo-server')?.customStatusPages || []
+      ).find((page) => `${page.status}` === status);
+      const outputPath =
+        options.outputPath || (statusPage ? nodePath.normalize(`./cyberia-server/${statusPage.hostPath}`) : null);
+      if (!outputPath) {
+        logger.error(`[build-status-page] No --output-path and no customStatusPages entry for status ${status}`);
+        return;
+      }
+      buildCyberiaStatusPage({ status, outputPath, dev: !!options.dev });
+    });
+
   runner
     .command('build-cyberia-404')
     .option('--dev', 'Build a development variant of the 404 page.')
     .option(
       '--output-path <path>',
       'Output path for the rendered 404.html (default: ./cyberia-server/public/404.html). ' +
-        'The same page is served, sub-path aware, by every instance variant of both the ' +
-        'cyberia-server (Go static server) and cyberia-client (docker-driver).',
+        'The same page is served, sub-path aware, by the gateway for every instance variant of both the ' +
+        'cyberia-server and cyberia-client workloads.',
+    )
+    .description(
+      'Build the cyberpunk pixel-art "sector not found" (404) page shared by the Cyberia server + client. ' +
+        'Thin alias of `build-status-page --status 404`, kept as the entrypoint the instance CI workflows call.',
     )
-    .description('Build the cyberpunk pixel-art "sector not found" (404) page shared by the Cyberia server + client.')
     .action((options) => {
-      const outputPath = options.outputPath || './cyberia-server/public/404.html';
-      shellExec(
-        `node bin static --page ./src/client/ssr/views/Cyberia404.js` +
-          ` --output-path ${outputPath}` +
-          ` --title 'Cyberia — Sector Not Found'` +
-          ` --favicon /favicon.ico` +
-          ` --description 'Cyberia Online 404 — the requested sector is not on the grid.'` +
-          ` --lang en` +
-          ` --env ${options.dev ? 'development' : 'production'}`,
-      );
+      buildCyberiaStatusPage({
+        status: '404',
+        outputPath: options.outputPath || './cyberia-server/public/404.html',
+        dev: !!options.dev,
+      });
     });
 
   // Passthrough check: if the user invoked a command that is OWNED by the