@underpostnet/cyberia 3.2.80 → 3.3.0

package/src/projects/cyberia/besu-genesis-generator.js

@@ -19,6 +19,7 @@ import path from 'path';
 import { keccak256 as ethersKeccak256 } from 'ethers';
 import { loggerFactory } from '../../server/logger.js';
 import { shellExec } from '../../server/process.js';
+import { crictlCommandFactory } from '../../server/cri.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -1394,8 +1395,8 @@ async function deployBesu(options = {}) {
   // ── Step 2: Pull container images if requested ─────────────────────────
   if (pullImage) {
     logger.info('Pulling Besu images via crictl...');
-    shellExec(`sudo crictl pull ${besuImage}`);
-    shellExec(`sudo crictl pull ${curlImage}`);
+    shellExec(crictlCommandFactory(`pull ${besuImage}`));
+    shellExec(crictlCommandFactory(`pull ${curlImage}`));
   }
 
   // ── Step 3: Apply all besu resources via kustomize ─────────────────────

package/src/projects/cyberia/catalog-cyberia.js

@@ -48,6 +48,8 @@ export default {
     '/.github/workflows/docker-image.cyberia-server.dev.ci.yml',
     '/.github/workflows/cyberia-client.cd.yml',
     '/.github/workflows/cyberia-server.cd.yml',
+    '/.github/workflows/coverall.cyberia.ci.yml',
+    '/scripts/coverall-test-cyberia.sh',
   ],
   stripPaths: [
     './src/projects/cyberia',
@@ -56,8 +58,11 @@ export default {
     './src/runtime/cyberia-client',
     './src/runtime/engine-cyberia',
     './test/cyberia-instance-conf-defaults.test.js',
+    './test/cyberia-load.test.js',
+    './test/object-layer-item-id.test.js',
     './test/shape-generator.test.js',
     './src/client/public/cyberia-docs',
+    './scripts/coverall-test-cyberia.sh',
     'bin/cyberia.js',
     './hardhat',
   ],

package/src/projects/cyberia/generate-saga.js

@@ -18,7 +18,6 @@ import fs from 'fs-extra';
 import nodePath from 'path';
 import crypto from 'crypto';
 import { GeminiClient } from './gemini-client.js';
-import { computeSha256 } from './object-layer.js';
 import { loggerFactory } from '../../server/logger.js';
 
 const logger = loggerFactory(import.meta);
@@ -1632,13 +1631,13 @@ function normalizeSagaPayload(raw, { theme }) {
 
 /**
  * Persist normalized object-layer items into the ObjectLayer collection so they
- * are editable in the viewer. Items are created with an empty (`null`) render
- * and an `OFF_CHAIN` ledger; a render/ledger can be set later from
+ * are editable in the viewer. New items get an empty render and an `OFF_CHAIN`
+ * ledger; both can be set later from the object-layer import or from
  * `src/client/components/cyberia/ObjectLayerEngineViewer.js`.
  *
- * Upserts by `data.item.id`. An existing item's render and ledger are PRESERVED
- * (never clobbered back to null) — only the textual stats/item fields are
- * refreshed. `sha256` is recomputed over the resulting data.
+ * Upserts through `ObjectLayer.upsertByItemId`, so `data.item.id` stays unique
+ * and an existing item's render, ledger and CIDs are PRESERVED — only the
+ * textual stats/item fields are refreshed, and `sha256` is recomputed.
  *
  * @async
  * @param {Object} params
@@ -1647,28 +1646,20 @@ function normalizeSagaPayload(raw, { theme }) {
  * @returns {Promise<number>} Count of items created or updated.
  */
 async function persistObjectLayers({ objectLayers, ObjectLayer }) {
+  await ObjectLayer.ensureUniqueItemIdIndex();
+
   let count = 0;
   for (const ol of objectLayers) {
     const itemId = ol.item?.id;
     if (!itemId) continue;
 
-    const existing = await ObjectLayer.findOne({ 'data.item.id': itemId });
-
-    // Preserve any render already set via the viewer; default to empty render.
-    const hasRender = existing?.data?.render?.cid || existing?.data?.render?.metadataCid;
-    const render = hasRender ? existing.data.render : { cid: null, metadataCid: null };
-    const ledger = existing?.data?.ledger?.type ? existing.data.ledger : { type: 'OFF_CHAIN', tokenId: '' };
-
-    const data = { stats: ol.stats, item: ol.item, ledger, render };
-    const sha256 = computeSha256(data);
-
-    if (existing) {
-      existing.data = data;
-      existing.sha256 = sha256;
-      await existing.save();
-    } else {
-      await ObjectLayer.create({ data, sha256, cid: null });
-    }
+    // The saga only owns the textual/statistical fields. Ledger and render are
+    // seeded on insert and never refreshed, so a re-import cannot clobber an
+    // on-chain registration or a render produced by the object-layer import.
+    await ObjectLayer.upsertByItemId(
+      { data: { stats: ol.stats, item: ol.item } },
+      { setOnInsert: { cid: null, data: { ledger: { type: 'OFF_CHAIN', tokenId: '' }, render: {} } } },
+    );
     count++;
   }
   return count;

package/src/projects/cyberia/hot-reload-trigger.js

@@ -51,9 +51,9 @@ const serverApiKey = () => process.env.CYBERIA_SERVER_API_KEY || '';
  *
  * The URL sub-path is preserved as `basePath` ("", "/FOREST", "/TEST") and kept
  * on `restBaseUrl`: a path-based multi-instance proxy routes the REST trigger to
- * the right variant by that prefix (then strips it via pathRewritePolicy, so the
- * backend matches its own instanceCode). Using `url.origin` alone would drop the
- * sub-path and land every trigger on the default (root) deployment.
+ * the right variant, and cyberia-server consumes that same base path natively.
+ * Using `url.origin` alone would drop the sub-path and land every trigger on the
+ * default (root) deployment.
  */
 const resolveTargets = (rawUrl, { grpcPort = DEFAULT_GRPC_PORT } = {}) => {
   const trimmed = String(rawUrl || '').trim();

package/src/projects/cyberia/instance-data.js

@@ -24,11 +24,38 @@ import {
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
 } from '../../api/cyberia-server-defaults/cyberia-server-defaults.js';
-import { DefaultCyberiaItems } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+import {
+  DEFAULT_INSTANCE_CODE,
+  DefaultCyberiaItems,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { generateFallbackWorld } from '../../api/cyberia-instance/cyberia-fallback-world.js';
+import { getFallbackDefaultItems } from '../../api/cyberia-instance/cyberia-fallback-default-items.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * Builds the runtime env for one Cyberia MMO variant. The generic instance
+ * loader deliberately has no knowledge of these application-specific keys;
+ * Cyberia derives them from the normalized variant path/code here.
+ * @param {object} context - Instance env build context.
+ * @param {object} context.instance - Expanded instance descriptor.
+ * @param {Object<string,string>} context.env - Parsed canonical env values.
+ * @returns {Object<string,string>} Materialized Cyberia env values.
+ */
+function buildCyberiaMmoInstanceEnv({ instance = {}, env = {} }) {
+  const built = { ...env };
+  const instanceCode = instance.path === '/' ? DEFAULT_INSTANCE_CODE : instance.instanceCode;
+  if (instance.runtime === 'cyberia-server') {
+    built.INSTANCE_CODE = instanceCode;
+    built.CYBERIA_BASE_PATH = instance.path;
+  } else if (instance.runtime === 'cyberia-client') {
+    built.CYBERIA_INSTANCE_CODE = instanceCode;
+    built.CYBERIA_DEFAULT_INSTANCE = DEFAULT_INSTANCE_CODE;
+    built.CYBERIA_BASE_PATH = instance.path;
+  }
+  return built;
+}
+
 /**
  * Resolves the mongoose model bag for a DB context.
  * @param {{host?: string, path?: string}|string} context - RouterOptions-style
@@ -304,6 +331,8 @@ function toInstanceMsg(doc) {
   };
 }
 
+const toCraftItemMsg = (i) => ({ itemId: i.itemId || '', qty: i.qty ?? 1 });
+
 // CyberiaAction → CyberiaActionMessage (proto camelCase fields).
 function toActionMsg(a) {
   return {
@@ -317,6 +346,17 @@ function toActionMsg(a) {
       questCode: qd.questCode || '',
       dialogCode: qd.dialogCode || '',
     })),
+    shopItems: (a.shopItems || []).map((si) => ({
+      itemId: si.itemId || '',
+      priceItemId: si.priceItemId || 'coin',
+      priceQty: si.priceQty ?? 1,
+    })),
+    craftRecipes: (a.craftRecipes || []).map((r) => ({
+      outputItems: (r.outputItems || []).map(toCraftItemMsg),
+      ingredients: (r.ingredients || []).map(toCraftItemMsg),
+      craftTimeMs: r.craftTimeMs ?? 0,
+    })),
+    storageSlots: a.storageSlots ?? 0,
   };
 }
 
@@ -382,6 +422,7 @@ function toInstanceConfig(gc) {
     botAggroRange: gc.botAggroRange ?? fb.botAggroRange,
     defaultPlayerWidth: gc.defaultPlayerWidth ?? fb.defaultPlayerWidth,
     defaultPlayerHeight: gc.defaultPlayerHeight ?? fb.defaultPlayerHeight,
+    playerBaseSpeed: gc.playerBaseSpeed ?? fb.playerBaseSpeed,
     playerBaseLifeRegenMin: gc.playerBaseLifeRegenMin ?? fb.playerBaseLifeRegenMin,
     playerBaseLifeRegenMax: gc.playerBaseLifeRegenMax ?? fb.playerBaseLifeRegenMax,
     sumStatsLimit: gc.sumStatsLimit ?? fb.sumStatsLimit,
@@ -514,7 +555,7 @@ async function fetchFullInstance(models, requestedInstanceCode) {
   // ── Fallback: instance not found → return a multi-map procedural world ──
   if (!inst) {
     logger.info(`Instance "${instanceCode}" not found — returning fallback world.`);
-    const world = generateFallbackWorld();
+    const world = generateFallbackWorld({ itemIds: getFallbackDefaultItems() });
     const fallbackConf = buildFallbackConfig();
 
     // Collect all objectLayerItemIds from the generated maps so the
@@ -560,6 +601,23 @@ async function fetchFullInstance(models, requestedInstanceCode) {
 
     const fallbackConfig = buildFallbackInstanceConfig(fallbackConf, world.instance.itemIds);
 
+    // Opaque version over everything mutable in this payload, mirroring the
+    // persisted path below. A constant here would make hot reload a silent
+    // no-op: WorldBuilder.ReloadWorld skips the rebuild — and therefore
+    // ApplyInstanceConfig — whenever the version is unchanged. The world
+    // geometry itself is deterministic (code defaults + seed), so the inputs
+    // that can actually differ are the staged default items and the
+    // ObjectLayer docs, which are the only things read from the DB here.
+    const fallbackVersionParts = ['fallback'];
+    for (const entry of world.instance.itemIds || []) {
+      fallbackVersionParts.push(`${entry.id}:${entry.defaultPlayerInventory ? 1 : 0}`);
+    }
+    for (const doc of fallbackOlDocs) fallbackVersionParts.push(String(doc.sha256 || doc._id));
+    const fallbackVersion = `fallback-${crypto
+      .createHash('sha256')
+      .update(fallbackVersionParts.join('|'))
+      .digest('hex')}`;
+
     return {
       instance: toInstanceMsg({ ...world.instance, _id: '', seed: instanceCode }),
       maps: world.maps.map((m) => ({
@@ -574,7 +632,7 @@ async function fetchFullInstance(models, requestedInstanceCode) {
       })),
       objectLayers: fallbackOlDocs.map(toObjectLayerMsg),
       config: fallbackConfig,
-      version: 'fallback',
+      version: fallbackVersion,
       // Mission content for the procedural fallback comes straight from
       // the canonical defaults — no DB, fully self-contained.
       actions: DefaultCyberiaActions.map(toActionMsg),
@@ -693,6 +751,8 @@ async function fetchFullInstance(models, requestedInstanceCode) {
 }
 
 export {
+  buildCyberiaMmoInstanceEnv as buildInstanceEnv,
+  buildCyberiaMmoInstanceEnv,
   getInstanceModels,
   normalizeEntityDefault,
   applyInstanceDefaultPlayerInventory,

package/src/projects/cyberia/object-layer.js

@@ -10,9 +10,7 @@ import path from 'path';
 import { PNG } from 'pngjs';
 import sharp from 'sharp';
 import { Jimp, intToRGBA, rgbaToInt } from 'jimp';
-import crypto from 'crypto';
-import stringify from 'fast-json-stable-stringify';
-
+import { computeObjectLayerSha256 } from '../../api/object-layer/object-layer.model.js';
 import { range } from '../../client/components/core/CommonJs.js';
 import {
   generateRandomStats,
@@ -450,7 +448,7 @@ export class ObjectLayerEngine {
    * @memberof CyberiaObjectLayer
    */
   static computeSha256(data) {
-    return crypto.createHash('sha256').update(stringify(data)).digest('hex');
+    return computeObjectLayerSha256(data);
   }
 
   /**
@@ -642,23 +640,15 @@ export class ObjectLayerEngine {
     }
 
     // 4. Atomic create/upsert - ObjectLayer is fully populated with all CIDs
-    let objectLayer;
-    const existingByItemId = await ObjectLayer.findOne({ 'data.item.id': objectLayerData.data.item.id });
-    if (existingByItemId) {
-      const oldRenderFramesId = existingByItemId.objectLayerRenderFramesId;
-      logger.info(
-        `ObjectLayer for item "${objectLayerData.data.item.id}" exists (${existingByItemId._id}), replacing atomically...`,
-      );
-      objectLayer = await ObjectLayer.findByIdAndUpdate(existingByItemId._id, objectLayerData, {
-        returnDocument: 'after',
-      }).populate('objectLayerRenderFramesId');
-      if (oldRenderFramesId && !oldRenderFramesId.equals(objectLayerRenderFramesDoc._id)) {
-        await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
-      }
-    } else {
-      objectLayer = await (await ObjectLayer.create(objectLayerData)).populate('objectLayerRenderFramesId');
-      logger.info(`ObjectLayer created successfully with id: ${objectLayer._id}`);
+    const existingByItemId = await ObjectLayer.findByItemId(objectLayerData.data.item.id);
+    const oldRenderFramesId = existingByItemId?.objectLayerRenderFramesId;
+
+    const objectLayer = await (await ObjectLayer.upsertByItemId(objectLayerData)).populate('objectLayerRenderFramesId');
+
+    if (oldRenderFramesId && !oldRenderFramesId.equals(objectLayerRenderFramesDoc._id)) {
+      await ObjectLayerRenderFrames.findByIdAndDelete(oldRenderFramesId);
     }
+    logger.info(`ObjectLayer for item "${objectLayerData.data.item.id}" persisted with id: ${objectLayer._id}`);
 
     return { objectLayer, objectLayerRenderFramesDoc };
   }
@@ -848,7 +838,7 @@ export class ObjectLayerEngine {
    * @memberof CyberiaObjectLayer
    */
   static async resolveCanonicalCid({ itemId, ObjectLayer, ipfsClient = null, options }) {
-    const objectLayer = await ObjectLayer.findOne({ 'data.item.id': itemId });
+    const objectLayer = await ObjectLayer.findByItemId(itemId);
     if (!objectLayer) {
       throw new Error(`ObjectLayer "${itemId}" not found in database`);
     }

package/src/projects/underpost/catalog-underpost.js

@@ -18,7 +18,10 @@ const TEMPLATE_RESTORE_PATHS = [
   `./.github/workflows/gitlab.ci.yml`,
   `./.github/workflows/publish.ci.yml`,
   `./.github/workflows/release.cd.yml`,
-  `./src/client/services/user/guest.service.js`,
+  `./deploy/lib`,
+  './deploy/release',
+  './deploy/pwa-microservices-template',
+  './src/client/services/user/guest.service.js',
   './src/api/user/guest.service.js',
   './src/ws/IoInterface.js',
   './src/ws/IoServer.js',

package/src/runtime/cyberia-client/Dockerfile

@@ -14,7 +14,7 @@ RUN make -f Web.mk clean all BUILD_MODE=${BUILD_MODE} OUTPUT_DIR=bin/
 
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 
 RUN set -eux; \

package/src/runtime/cyberia-client/Dockerfile.dev

@@ -43,7 +43,7 @@ RUN make -f Web.mk all BUILD_MODE=${BUILD_MODE} OUTPUT_DIR=bin/
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
 
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 RUN set -eux; \
     dnf -y update; \

package/src/runtime/cyberia-server/Dockerfile

@@ -11,7 +11,7 @@ RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o server ./cmd/cyberia-se
 
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 
 RUN set -eux; \

package/src/runtime/cyberia-server/Dockerfile.dev

@@ -25,7 +25,7 @@ RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
 
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 RUN set -eux; \
     dnf -y update; \

package/src/runtime/engine-cyberia/Dockerfile

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0

package/src/runtime/engine-cyberia/Dockerfile.dev

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0

package/src/runtime/engine-cyberia/Dockerfile.test

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.2.80
+ARG UNDERPOST_VERSION=3.3.0
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0

package/src/runtime/engine-cyberia/compose.env

@@ -40,29 +40,27 @@ VALKEY_HOST=valkey-service
 VALKEY_PORT=6379
 
 # --- Cyberia instance wiring (compose service DNS) ---------------------------
-# cyberia-server-* -> engine-cyberia authority endpoints. INTERNAL only: these
-# use the docker service DNS (engine-cyberia) and must never leak to browser
-# clients. Per-instance INSTANCE_CODE is set on each generated server service
-# from conf.instances.json (multiInstance) — not here.
-ENGINE_API_BASE_URL=http://engine-cyberia:4005
-ENGINE_GRPC_ADDRESS=engine-cyberia:50051
+# cyberia-server-* -> stable engine gateway for HTTP and the raw engine runtime
+# for gRPC. The public engine-cyberia name belongs to nginx, avoiding ambiguous
+# Docker DNS while keeping one stable HTTP endpoint for every module.
+ENGINE_API_BASE_URL=http://engine-cyberia
+ENGINE_GRPC_ADDRESS=engine-cyberia-runtime:50051
 
 # Client-visible Content Authority origin, forwarded to browser/Raylib clients
 # for every engine-cyberia content/asset/metadata request. Host-reachable
-# (docker publishes engine-cyberia :4005). Distinct from ENGINE_API_BASE_URL:
+# (Docker publishes the raw engine runtime on host :4005). Unlike the internal
+# ENGINE_API_BASE_URL, this value is consumed outside the Compose network:
 # the two responsibilities must never overwrite each other.
 ENGINE_PUBLIC_URL=http://localhost:4005
 ENGINE_GRPC_RELOAD_INTERVAL_SEC=300
 
 # --- Browser-facing client runtime config (injected by docker-driver.py) -----
 # The single WASM bundle resolves its instance from the URL sub-path and builds
-# its endpoints from these origins. They point at the nginx proxy on localhost:80
-# (the single gateway that path-routes WS -> server, /api + /assets -> engine),
-# NOT at the raw client/engine container ports — a WS to the client port (8082)
-# has no server behind it. So this must be the proxy origin, not :8082 / :4005.
-#   http://localhost/          -> default instance,  ws -> ws://localhost/ws
-#   http://localhost/FOREST    -> FOREST instance,    ws -> ws://localhost/FOREST/ws
-CYBERIA_WS_ORIGIN=ws://localhost
+# its endpoints from these origins. HTTP client/API traffic uses nginx on :80;
+# WebSocket traffic uses the dedicated multi-path server gateway on :8081.
+#   http://localhost/          -> default, ws://localhost:8081/ws
+#   http://localhost/FOREST    -> FOREST,  ws://localhost:8081/FOREST/ws
+CYBERIA_WS_ORIGIN=ws://localhost:8081
 CYBERIA_ENGINE_API_ORIGIN=http://localhost
 CYBERIA_DEFAULT_INSTANCE=amethyst-strata-expansion
 
@@ -72,6 +70,22 @@ CYBERIA_DEFAULT_INSTANCE=amethyst-strata-expansion
 CYBERIA_SERVER_APP_ENV=development
 CYBERIA_SERVER_LOG_LEVEL=
 
+# --- cyberia-server WebSocket admission and rate limits ----------------------
+# Unset keeps the built-in default. An explicit 0 turns that one limit off.
+# The startup log prints the effective profile ("ws limits: ...").
+#
+# Set CYBERIA_DISABLE_CONNECTION_LIMITS=1 to turn every limit off. The load test
+# (test/cyberia-load.test.js) drives every simulated client from one address, so
+# it needs this. NEVER enable it on a public deploy.
+CYBERIA_DISABLE_CONNECTION_LIMITS=
+CYBERIA_MAX_CONNECTIONS=
+CYBERIA_MAX_CONNECTIONS_PER_IP=
+CYBERIA_CONNECT_RATE_PER_IP=
+CYBERIA_CONNECT_BURST_PER_IP=
+CYBERIA_MESSAGE_RATE=
+CYBERIA_MESSAGE_BURST=
+CYBERIA_MAX_STRIKES=
+
 # --- engine-cyberia runtime env (loaded into the container via env_file) -----
 # The dd-cyberia engine (engine-private/conf/dd-cyberia/conf.server.json) needs
 # these to boot: DB auth + per-site DB names, the base PORT (the cyberia host is
@@ -82,6 +96,7 @@ NODE_OPTIONS=--max-old-space-size=8192
 BASE_API=api
 DEFAULT_DEPLOY_ID=dd-cyberia
 DEPLOY_ID=dd-cyberia
+# Configuration/DB selector from conf.server.json; this is not a Docker DNS alias.
 DEFAULT_DEPLOY_HOST=www.cyberiaonline.com
 DEFAULT_DEPLOY_PATH=/
 DISABLE_API_RATE_LIMIT=true
@@ -131,7 +146,25 @@ IPFS_CLUSTER_API_URL=http://ipfs-cluster:9094
 # in docker-compose.yml). Override for a real/shared cluster.
 # CLUSTER_SECRET=
 
-# --- Host-published ports ----------------------------------------------------
+# --- Local access ------------------------------------------------------------
+# Client gateway:  http://localhost/{,FOREST,TEST}
+# Client port alias: http://localhost:8082/{,FOREST,TEST}
+# Server gateway:  http://localhost:8081/{,FOREST,TEST}
+# Engine authority: http://localhost:4005
+# Docker-network gateways:
+#   http://cyberia-client/{,FOREST,TEST}
+#   http://cyberia-server/{,FOREST,TEST}
+#   http://engine-cyberia/
+#
+# The *.localhost aliases normally resolve to loopback without configuration:
+#   http://client.cyberia.localhost/{,FOREST,TEST}
+#   http://server.cyberia.localhost/{,FOREST,TEST}
+#   http://engine.cyberia.localhost/
+# `node bin/cyberia run-workflow docker:up` maintains this host entry (the
+# aliases already work between containers):
+#   127.0.0.1 cyberia-client cyberia-server engine-cyberia
+#
+# Host-published ports:
 PROXY_HTTP_PORT=80
 IPFS_API_PORT=5001
 IPFS_GATEWAY_PORT=8080
@@ -140,5 +173,7 @@ MONGO_HOST_PORT=27017
 VALKEY_NODEPORT=32079
 ENGINE_CYBERIA_REST_PORT=4005
 ENGINE_CYBERIA_GRPC_PORT=50051
+# Multi-path nginx server gateway, not a single server container publication.
 CYBERIA_SERVER_PORT=8081
+# Multi-path nginx client gateway; raw client containers remain internal.
 CYBERIA_CLIENT_PORT=8082