@underpostnet/cyberia 3.2.80 → 3.2.90

package/src/cli/ssh.js

@@ -7,6 +7,7 @@
 import { generateRandomPasswordSelection } from '../client/components/core/CommonJs.js';
 import { pbcopy, shellExec } from '../server/process.js';
 import { loggerFactory } from '../server/logger.js';
+import { waitForPort } from '../server/conf.js';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
@@ -606,8 +607,8 @@ EOF
     },
 
     /**
-     * Waits until a TCP SSH port becomes reachable on a host.
-     * @async
+     * Waits until a TCP SSH port becomes reachable on a host. Delegates to
+     * {@link ServerConfBuilder.waitForPort}, which owns the probe.
      * @function waitForSshPort
      * @memberof UnderpostSSH
      * @param {object} params
@@ -617,25 +618,14 @@ EOF
      * @param {number} [params.intervalMs=3000] - Poll interval.
      * @returns {Promise<boolean>} True once the port accepts connections, false on timeout.
      */
-    waitForSshPort: async ({ host, port = 22, timeoutMs = 10 * 60 * 1000, intervalMs = 3000 }) => {
-      const deadline = Date.now() + timeoutMs;
-      while (Date.now() < deadline) {
-        const probe = shellExec(
-          `timeout 5 bash -c '</dev/tcp/${host}/${port}' >/dev/null 2>&1 && echo open || echo closed`,
-          { silent: true, stdout: true, silentOnError: true, disableLog: true },
-        );
-        if (`${probe}`.trim() === 'open') return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
-      }
-      logger.warn(`SSH port ${host}:${port} not reachable within timeout`);
-      return false;
-    },
+    waitForSshPort: ({ host, port = 22, timeoutMs = 10 * 60 * 1000, intervalMs = 3000 }) =>
+      waitForPort({ host, port, open: true, timeoutMs, intervalMs }),
 
     /**
      * Waits until a host's SSH port stops accepting connections (e.g. while it
      * reboots). Used to detect a reboot edge before waiting for the port to come
      * back up, so callers don't latch onto the pre-reboot (ephemeral) sshd.
-     * @async
+     * Delegates to {@link ServerConfBuilder.waitForPort}.
      * @function waitForSshPortClosed
      * @memberof UnderpostSSH
      * @param {object} params
@@ -645,18 +635,8 @@ EOF
      * @param {number} [params.intervalMs=3000] - Poll interval.
      * @returns {Promise<boolean>} True once the port is closed, false on timeout.
      */
-    waitForSshPortClosed: async ({ host, port = 22, timeoutMs = 3 * 60 * 1000, intervalMs = 3000 }) => {
-      const deadline = Date.now() + timeoutMs;
-      while (Date.now() < deadline) {
-        const probe = shellExec(
-          `timeout 5 bash -c '</dev/tcp/${host}/${port}' >/dev/null 2>&1 && echo open || echo closed`,
-          { silent: true, stdout: true, silentOnError: true, disableLog: true },
-        );
-        if (`${probe}`.trim() === 'closed') return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
-      }
-      return false;
-    },
+    waitForSshPortClosed: ({ host, port = 22, timeoutMs = 3 * 60 * 1000, intervalMs = 3000 }) =>
+      waitForPort({ host, port, open: false, timeoutMs, intervalMs }),
 
     /**
      * Orchestrates a non-interactive, key-only SSH session against a freshly

package/src/client/components/cyberia/InstanceSelectionView.js

@@ -26,6 +26,7 @@ import { htmls, s, htmlStrSanitize } from '../core/VanillaJs.js';
 import { getProxyPath } from '../core/Router.js';
 import { getApiBaseUrl } from '../../services/core/core.service.js';
 import { CyberiaInstanceService } from '../../services/cyberia-instance/cyberia-instance.service.js';
+import { DEFAULT_INSTANCE_CODE } from './SharedDefaultsCyberia.js';
 
 // Client deployment that actually hosts the playable worlds. Matches the portal
 // landing CTA (MainBodyCyberiaPortal); override per-instance via `onPlay`.
@@ -33,9 +34,8 @@ const DEFAULT_CLIENT_BASE_URL = 'https://client.cyberiaonline.com';
 
 // Authoritative simulation host and the default instance's code, mirroring the
 // mmo-server multiInstance block in conf.instances.json. The default variant is
-// served at the root path; other variants at `/<CODE>`.
+// served at `/`; other variants use their literal `/<CODE>` path.
 const DEFAULT_SERVER_BASE_URL = 'https://server.cyberiaonline.com';
-const DEFAULT_INSTANCE_CODE = 'amethyst-strata-expansion';
 
 const placeholderThumbnail = () => `${getProxyPath()}assets/ui-icons/world-default-forest-city.png`;
 
@@ -95,17 +95,17 @@ const normalizeInstance = (doc, { clientBaseUrl }) => {
     players: Number.isFinite(players) ? players : null,
     capacity: Number.isFinite(capacity) && capacity > 0 ? capacity : null,
     tags: Array.isArray(doc.tags) ? doc.tags.filter(Boolean) : [],
-    playUrl: `${clientBaseUrl}${code ? `/${encodeURIComponent(code)}` : ''}`,
+    playUrl: `${clientBaseUrl}${code && code !== DEFAULT_INSTANCE_CODE ? `/${encodeURIComponent(code)}` : ''}`,
     playable: statusMeta(status).playable,
   };
 };
 
 // ── Live status via the cyberia-server metrics API ───────────────────────────
-// Each variant is served at server.cyberiaonline.com/<path> — '/' for the
-// default instance, '/<CODE>' for the rest (the multiInstance variants in
-// conf.instances.json). The proxy strips the prefix, so each world's own
-// /api/v1/metrics reports its health + capacity. Cross-origin, so the metrics
-// CORS allow-list (CYBERIA_CORS_ALLOWED_ORIGINS) must include this portal.
+// The default is served at `/`; other variants use the compact `/<CODE>` paths
+// from conf.instances.json. The proxy strips non-root prefixes, so each world's
+// own /api/v1/metrics reports its health + capacity.
+// Cross-origin, so the metrics CORS allow-list (CYBERIA_CORS_ALLOWED_ORIGINS)
+// must include this portal.
 
 const metricsUrlFor = (code, { serverBaseUrl, defaultInstanceCode }) => {
   const path = code && code !== defaultInstanceCode ? `/${encodeURIComponent(code)}` : '';
@@ -316,6 +316,9 @@ class InstanceSelectionView {
         });
         return;
       }
+      const defaultSuffix = `/${encodeURIComponent(DEFAULT_INSTANCE_CODE)}`;
+      if (instance.playUrl?.endsWith(defaultSuffix))
+        instance.playUrl = instance.playUrl.slice(0, -defaultSuffix.length);
       if (typeof onPlay === 'function') return onPlay(instance);
       if (instance.playUrl) location.href = instance.playUrl;
     };

package/src/client/components/cyberia/SharedDefaultsCyberia.js

@@ -50,6 +50,11 @@
 // Shared content vocabulary
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Default instance code for the Cyberia engine
+ */
+export const DEFAULT_INSTANCE_CODE = 'amethyst-strata-expansion';
+
 /**
  * Canonical set of ObjectLayer item type names. Used as the
  * `data.item.type` discriminator and as the asset directory name on disk.

package/src/client/public/cyberia-docs/ACTION-SYSTEM.md

@@ -8,7 +8,7 @@
 
 The Action System defines how NPC entities interact with players. An **Action** is a spatial, typed payload attached to a map entity that the player activates by tapping the NPC. Actions drive dialogue, shops, crafting, storage, and quest grant events.
 
-> **Implementation status — Alpha (talk / quest-talk):** The CyberiaAction and CyberiaDialogue MongoDB schemas and Engine REST API (`src/api/cyberia-action`, `src/api/cyberia-dialogue`) are defined. The `talk` and `quest-talk` paths are wired end-to-end: the Go server binds actions to entities at instance init, validates dialogue completion, grants quests, and advances `talk` objectives (see **Dialogue Interaction Protocol** below). Shop / craft / storage transaction processing remains planned for a later Alpha increment. The `freeze_start`/`freeze_end` WS messages for modal protection are implemented; dialogue freeze now rides on the `dlg_*` frames.
+> **Implementation status — Alpha (talk / quest-talk / shop):** The CyberiaAction and CyberiaDialogue MongoDB schemas and Engine REST API (`src/api/cyberia-action`, `src/api/cyberia-dialogue`) are defined. The `talk` and `quest-talk` paths are wired end-to-end: the Go server binds actions to entities at instance init, validates dialogue completion, grants quests, and advances `talk` objectives (see **Dialogue Interaction Protocol** below). The `shop` path is wired end-to-end as well (see **Shop Transaction Flow**). Craft / storage transaction processing remains planned for a later Alpha increment. The `freeze_start`/`freeze_end` WS messages for modal protection are implemented; dialogue freeze now rides on the `dlg_*` frames.
 
 ---
 
@@ -18,9 +18,9 @@ The Action System defines how NPC entities interact with players. An **Action**
 
 ```
 CyberiaAction {
-  code:         String  // stable unique slug
-  type:         String  // see Action Types below
-  label:        String  // display label on interaction button
+  code:         String  // stable unique, location-scoped slug
+  label:        String  // NPC overhead nameplate (there is no `type` field —
+                        // see Action Capabilities below)
 
   // Spatial origin — NPC entity cell providing this action
   sourceMapCode: String
@@ -50,7 +50,7 @@ CyberiaAction {
     ingredients: [{ itemId: String, qty: Number }]
   }]
 
-  storageSlots: Number  // storage capacity (type='storage' only)
+  storageSlots: Number  // vault capacity in slots; 0 disables the capability
 }
 ```
 
@@ -70,15 +70,19 @@ A single `code` groups many ordered dialogue lines. The C client fetches all lin
 
 ---
 
-## Action Types
+## Action Capabilities
 
-| Type         | Description                                                    | Active Payload                                       |
-| ------------ | -------------------------------------------------------------- | ---------------------------------------------------- |
-| `quest-talk` | Awards the quest bound to its cell (via Take Quest), shows dialogue | quests bound by cell, `dialogCode`, `questDialogueCodes` |
-| `talk`       | NPC dialogue only — satisfies `talk` quest objectives          | `dialogCode`, `questDialogueCodes`                   |
-| `shop`       | Item shop — player buys items with in-game currency            | `shopItems[]`                                        |
-| `craft`      | Crafting station — consume ingredients to produce output items | `craftRecipes[]`                                     |
-| `storage`    | Personal item storage vault                                    | `storageSlots`                                       |
+An action has **no type**. Its capabilities are whatever payloads are populated,
+resolved per player at interaction time — one action can be a shop and a
+quest-talk giver at once.
+
+| Capability   | Active when                                                     | Payload                                              |
+| ------------ | --------------------------------------------------------------- | ---------------------------------------------------- |
+| `quest-talk` | CyberiaQuests are bound to this action's cell                   | quests bound by cell, `dialogCode`, `questDialogueCodes` |
+| `talk`       | always — satisfies `talk` quest objectives                      | `dialogCode`, `questDialogueCodes`                   |
+| `shop`       | `shopItems[]` is non-empty — player buys items with a currency  | `shopItems[]`                                        |
+| `craft`      | `craftRecipes[]` is non-empty — player assembles outputs        | `craftRecipes[]`                                     |
+| `storage`    | `storageSlots > 0` — player banks items in a personal vault     | `storageSlots`                                       |
 
 ---
 
@@ -109,26 +113,58 @@ graph LR
 
 ## Shop Transaction Flow
 
+An action carrying a non-empty `shopItems[]` is a **vendor** — there is no type
+flag. The catalog reaches the two runtimes on their own transports: the Go
+server receives it with the world over gRPC (`CyberiaActionMessage.shop_items`),
+the C client fetches it by action code over REST and renders the **Shop** tab.
+Only the server prices a purchase.
+
+A live vendor also lights the **action-provider** capability bit
+(`InteractionFlagAction`), so it carries the same overhead attention icon,
+orbiting particles, and coloured interaction-column border as a pending
+action-talk — the player can see there is something to do before tapping.
+
 ```mermaid
 sequenceDiagram
-    participant P as Player
+    participant P as Player (C client)
     participant G as Go Server
     participant E as Engine (Node.js)
 
-    P->>G: Tap shop NPC
-    G->>E: GET /api/cyberia-action?sourceMapCode=...&sourceCellX=...
-    E-->>G: CyberiaAction { type: 'shop', shopItems: [...] }
-    G-->>P: init_data → shop payload (item list + prices)
-    P-->>G: FrozenInteractionState (modal open)
-
-    P->>G: Buy request { itemId, quantity }
-    G->>E: GET player coin balance
-    Note over G: balance >= price * quantity?
-    G->>E: Deduct coins + grant item to inventory
-    G-->>P: FCT: CoinLoss + ItemGain events
-    G-->>P: ThawPlayer (modal close allowed)
+    E-->>G: getFullInstance → CyberiaAction { shopItems: [...] } (world build)
+    G-->>P: AOI bot block → actionCode + action-provider capability bit
+    P->>E: GET /api/cyberia-action/code/:code (interaction modal opens)
+    E-->>P: CyberiaAction { label, dialogCode, questDialogueCodes, shopItems }
+    Note over P: Shop tab leads the strip and opens active.<br/>Two columns of cards: item slot, name,<br/>price icon + qty, Buy (wallet icon)
+
+    P->>P: Buy → quantity picker (◀ / ▶ #N, 1..10, capped by what the player<br/>can pay) with a running total, then Cancel or Buy
+    P->>G: shop_buy { entityId, itemId, quantity }
+    Note over G: vendor bound to entity? row on sale?<br/>entity inside the player's AOI?<br/>held(priceItemId) >= priceQty × quantity?
+    G->>G: FreezePlayer("interact") — no kill mid-trade
+    G->>G: removePlayerItem(priceItemId, priceQty × quantity)
+    G->>G: addPlayerItem(itemId, quantity) + collect-objective reconcile
+    G-->>P: shop_ack { entityId, itemId, quantity, ok, reason }
+    G-->>P: AOI self-player block → authoritative inventory
+    Note over P: the card holds until the grant lands, then the<br/>currency's "-N" pop + expend spray play, and the<br/>item flies from the picker's slot into its<br/>inventory slot ("+N" pop)
 ```
 
+The picker deliberately waits for the grant before animating: a first copy has
+no inventory slot until the server delivers it, so launching the flight on the
+button press would aim at the bar's fallback centre instead of the item's own
+slot. Waiting also fixes the ordering — the spend is seen leaving before the
+goods arrive.
+
+Binary uplink opcode: `shop_buy` `0x1C` — `[u8 kind][str entityId][str itemId][u8 quantity]`.
+The quantity is clamped server-side to `[1, shopBuyMaxQty]` (10); a client that
+sends 0 means one unit. A purchase is all-or-nothing: an unaffordable total is
+rejected rather than partially filled.
+
+Rejection reasons on `shop_ack`: `no_vendor`, `not_for_sale`, `out_of_range`,
+`insufficient_funds`.
+
+`shop_ack` is notify-only, and only a rejection is surfaced (as a toast). The
+inventory itself always arrives through the AOI self-player block, so a dropped
+ack costs the player nothing.
+
 ---
 
 ## Craft Transaction Flow
@@ -159,11 +195,18 @@ sequenceDiagram
 ## Dialogue Interaction Protocol (talk / quest-talk)
 
 Tapping an interaction bubble opens the Raylib-native **`modal_interact`** modal
-(top half of the screen). It has a tab strip — **stack** (active item slots),
-**stats** (six-stat stack totals), and **action** (mission interface, shown only
-for action-provider entities, ESI 8) — over a fixed bottom bar of right-aligned
+(top half of the screen). It has a tab strip — **shop** (vendor catalog, shown
+only when its action carries `shopItems`), **quest** (mission interface, shown
+only when the entity provides quest codes), **stack** (active item slots), and
+**stats** (six-stat stack totals) — over a fixed bottom bar of right-aligned
 integration buttons (**Chat**, **Integration**) that open the JS overlay. The
-action tab's **Talk / Take mission** opens `modal_dialogue` (bottom half).
+paired `modal_dialogue` (bottom half) carries the talk flow.
+
+Capability tabs lead the strip, and the leading one opens active — Shop for a
+vendor, else Quest. Because the catalog resolves through an async REST fetch
+after the modal is already open, the active tab keeps tracking the leading
+capability until the player picks a tab themselves. Switching tabs plays a
+pop-in transition, during which content taps are ignored.
 
 The client is identical for `talk` and `quest-talk`; the **server** branches after
 `dlg_complete`. The client never declares the action type, quest code, or quest
@@ -186,6 +229,25 @@ Binary uplink opcodes: `dlg_start` `0x17`, `dlg_complete` `0x18`, `dlg_cancel`
 client upserts into its local `quest_store` (Quest Journal); it never gates
 simulation state.
 
+### Provider freeze
+
+A dialogue is one step of a provider session, not the whole of it: the interact
+modal stays open afterwards with its shop and quest tabs live. So when the
+talked-to entity has a bound `CyberiaAction`, `dlg_complete` / `dlg_cancel`
+re-bridge the freeze to `"interact"` instead of thawing, and `shop_buy` asserts
+the same freeze before it mutates anything. The player therefore cannot be
+killed anywhere inside a provider session, whether or not the client
+re-asserted the freeze itself.
+
+The client half holds up its end for as long as a modal is open. `modal_interact`,
+`inventory_modal` and `modal_instance_map` each own a freeze reason
+(`"interact"`, `"inventory"`, `"instance-map"`) and call
+`local_player_keep_freeze()` every frame they stay open — without that renewal
+the 30-second freeze watchdog auto-sends `freeze_end`, and a player browsing a
+shop longer than that would silently become killable. A modal closing over
+another one that still owns a freeze re-bridges to it rather than ending the
+freeze, so there is never a thawed frame between them.
+
 ### Server `dlg_complete` handling
 
 1. Validate `player.activeDialogueEntityID == msg.entityId`; drop otherwise.
@@ -292,16 +354,21 @@ The C client fetches the full `code` group sorted by `order`, then renders lines
 
 ```json
 {
-  "code": "wason-npc",
-  "type": "quest-talk",
-  "label": "Talk",
-  "sourceMapCode": "cyberia-village",
-  "sourceCellX": 12,
-  "sourceCellY": 8,
-  "dialogCode": "default-wason",
-  "questDialogueCodes": ["default-wason"],
-  "shopItems": [],
+  "code": "loc-fallback-map-0-18-16",
+  "label": "Punk",
+  "sourceMapCode": "fallback-map-0",
+  "sourceCellX": 18,
+  "sourceCellY": 16,
+  "dialogCode": "default-punk",
+  "questDialogueCodes": [],
+  "shopItems": [{ "itemId": "tim-knife", "priceItemId": "coin", "priceQty": 10 }],
   "craftRecipes": [],
   "storageSlots": 0
 }
 ```
+
+This is the vendor shipped in the canonical defaults
+(`DefaultCyberiaActions`): the `punk`-skinned NPC on `fallback-map-0` at
+(18, 16) sells `tim-knife` for 10 coins. `bin/cyberia run-workflow
+seed-actions-quests` upserts it; the procedural fallback world serves it
+unpersisted.

package/src/client/public/cyberia-docs/ARCHITECTURE.md

@@ -133,6 +133,24 @@ Underpost Platform deploy orchestration ensures the backend layer is ready befor
 
 ---
 
+## Edge tier
+
+Every `cyberiaonline.com` hostname is served through one Envoy Gateway data plane over HTTP/1.1, HTTP/2 and HTTP/3 (QUIC), with TLS terminated per hostname by SNI. In development the certificates are self-signed and locally trusted, and the hostnames are mapped in `/etc/hosts`, so a browser reaches the real routing stack rather than a dev proxy.
+
+Status pages never reach the engine at all, and the engine knows nothing about them. All three runtimes are agnostic: they return a standard HTTP status code or become unreachable. `underpost-gateway` — one shared Nginx workload in the gateway tier — proxies the site paths and intercepts those statuses, serving the declared document with the original URI and the original status code.
+
+| Condition                   | Declared by                             | Answered from                                            |
+| --------------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `404` on any unmatched path | a `CyberiaPortal` view with path `/404` | `www.cyberiaonline.com/root/status-pages/404/index.html` |
+| `502` / `503` / `504`       | the view flagged `maintenanceDefault`   | `www.cyberiaonline.com/root/maintenance/index.html`      |
+| `/offline`, `/maintenance`  | `offlineDefault` / `maintenanceDefault` | the matching context directory                           |
+
+A request to an unknown path reaches the portal, which answers a bare 404; the gateway swaps in the page. The address bar keeps the path the player typed, and the response is a true 404 — no redirect, no client-side script, and nothing for `engine-cyberia`, `cyberia-server` or `cyberia-client` to implement. API sub-paths bypass the interception, so a JSON 404 stays JSON.
+
+Per-instance hosts follow the same layout under their own sub-path — `client.cyberiaonline.com/FOREST/status-pages/404/index.html` — from the `customStatusPages` entries in `conf.instances.json`. Both configuration files live in `engine-private/`, which is a private repository: expect the layout to be referenced without assuming the files are present locally.
+
+---
+
 ## Tick model
 
 The tick is the universal coordinate of the simulation. Every server→client snapshot and every client→server input command carries a tick value.

package/src/client/public/cyberia-docs/CYBERIA-CLI.md

@@ -176,14 +176,14 @@ cyberia chain unpause [--network besu-k8s]
 
 Named scripts from the `scripts/` directory for seeding and build maintenance.
 
-| Subcommand                   | Description                                                                         |
-| ---------------------------- | ----------------------------------------------------------------------------------- |
+| Subcommand                   | Description                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
 | `import-default-items`       | Import default object layers, skills, dialogues, actions/quests, client-hints to Mongo |
-| `seed-skills`                | Upsert `DefaultSkillConfig` into the `cyberia-skill` collection (full records)       |
-| `seed-dialogues`             | Upsert `DefaultCyberiaDialogues` into the `cyberia-dialogue` collection             |
-| `generate-semantic-examples` | Generate one procedural example per registered semantic prefix                      |
-| `build-manifest`             | Build K8s Deployment + Service manifests for mmo-client / mmo-server                |
-| `build-server-dashboard`     | Build the static cyberia-server metrics/status dashboard (`--dev`, `--output-path`) |
+| `seed-skills`                | Upsert `DefaultSkillConfig` into the `cyberia-skill` collection (full records)         |
+| `seed-dialogues`             | Upsert `DefaultCyberiaDialogues` into the `cyberia-dialogue` collection                |
+| `generate-semantic-examples` | Generate one procedural example per registered semantic prefix                         |
+| `build-manifest`             | Build K8s Deployment + Service manifests for mmo-client / mmo-server                   |
+| `build-server-dashboard`     | Build the static cyberia-server metrics/status dashboard (`--dev`, `--output-path`)    |
 
 ```bash
 cyberia run-workflow import-default-items --env-path ./engine-private/conf/dd-cyberia/.env.development
@@ -195,6 +195,43 @@ cyberia run-workflow build-server-dashboard
 
 ---
 
+## Bringing up the full stack locally
+
+```bash
+node bin run cluster 'express,dd-cyberia' --dev
+```
+
+One command, no extra flags. It resets and rebuilds the node, deploys MongoDB / IPFS / Valkey, imports each database from its git backup, installs the Gateway API control plane, and deploys `dd-cyberia` behind it.
+
+What `--dev` implies, rather than requiring you to pass it:
+
+- **Gateway API + Envoy Gateway**, with **HTTP/3 (QUIC) on by default** beside HTTP/2 and HTTP/1.1.
+- **Self-signed, locally trusted TLS** for every hostname in `conf.server.json`, plus the matching `/etc/hosts` entries — so a local Chromium reaches `https://www.cyberiaonline.com` through the real data plane.
+- **The gateway static tier seeded** with the portal's `/404`, `/offline` and `/maintenance` documents before the routes are applied, then refreshed from the running container once it is Ready. See [Architecture → Edge tier](./ARCHITECTURE.md).
+
+The run ends with a gateway status report: listener and route conditions, the workloads behind them, and an HTTPS probe of every route hostname.
+
+### With the MMO services
+
+The optional third path segment brings up custom instances from `engine-private/conf/dd-cyberia/conf.instances.json` in the same run:
+
+```bash
+node bin run cluster 'express,dd-cyberia,mmo-server' --dev
+node bin run cluster 'express,dd-cyberia,mmo-server+mmo-client' --dev
+```
+
+Each id runs only where `dd-cyberia` declares it, and only once the portal workload has rolled out — `cyberia-server` dials the engine's gRPC ClusterIP for its world configuration at boot, so the content authority has to be serving first. `mmo-server` names the whole variant family (`amethyst-strata-expansion`, `FOREST`, `TEST`); `mmo-server-forest` names one variant.
+
+`server.cyberiaonline.com` and `client.cyberiaonline.com` are issued the same self-signed certificates as the portal hosts and written into the same `/etc/hosts` pass, so the three services are reachable over TLS from a local browser without further setup. In production the same segment issues cert-manager certificates instead.
+
+To place the static documents again without redeploying — after rebuilding the portal client, for instance:
+
+```bash
+node bin deploy dd-cyberia development --sync-static --gateway-api --kubeadm
+```
+
+---
+
 ## Operational rules
 
 - Preserve public CLI entrypoints and command names unless a change is intentionally breaking.

package/src/client/public/cyberia-docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Cyberia Online — Development Roadmap
 
-**Current version:** 3.2.80 | **Target milestone:** Open Alpha
+**Current version:** 3.2.90 | **Target milestone:** Open Alpha
 
 ---
 

package/src/client/public/cyberia-docs/WHITE-PAPER.md

@@ -18,7 +18,7 @@ _Stackable Rendering Layers as a Unified Tokenized Reality_
 
 ---
 
-**Version:** 3.2.80 | **Status:** Draft | **Authors:** Underpost Engineering
+**Version:** 3.2.90 | **Status:** Draft | **Authors:** Underpost Engineering
 
 ---
 

package/src/client-builder/client-build.js

@@ -23,12 +23,81 @@ import { shellExec } from '../server/process.js';
 import { SitemapStream, streamToPromise } from 'sitemap';
 import { Readable } from 'stream';
 import { buildIcons } from './client-icons.js';
+import { statusPageBuildSegment } from '../server/underpost-gateway.js';
 import Underpost from '../index.js';
 import { buildDocs } from './client-build-docs.js';
 import { ssrFactory } from './ssr.js';
 
 // Static Site Generation (SSG)
 
+const STATUS_PAGE_VIEW_PATH = /^\/([1-5]\d{2})$/;
+
+// Views a route intercepts before the workload sees the request. They are
+// declared by the flag that already marks them as the app's default for that
+// condition, so a new one becomes edge-served by adding its flag here rather
+// than by naming its path in a second place.
+const INTERCEPT_VIEW_FLAGS = ['maintenanceDefault', 'offlineDefault'];
+
+/**
+ * Resolves the SSR views that render an HTTP status page into the static
+ * artifacts they build to. A view is a status page when its route path is a
+ * bare status code (`/404`, `/500`, `/503`), which the build writes to
+ * `<path>/index.html` inside the served bundle.
+ *
+ * Single source of truth for PWA status-page routing: this build writes the
+ * artifact, and `deploy --build-manifest` points its HTTPRoute rules at the
+ * same resolved URL — neither side hardcodes a status code.
+ * @function statusPageRoutesFactory
+ * @param {Array<object>} [views] - SSR view entries from `conf.ssr.json`.
+ * @param {string} [proxyPath] - The client's proxy sub-path (`/`, `/peer`, ...).
+ * @returns {Array<{status: string, routePath: string, indexUrl: string, title: string, client: string}>}
+ *   One entry per status view, in declaration order.
+ * @memberof clientBuild
+ */
+const statusPageRoutesFactory = ({ views = [], proxyPath = '/' } = {}) => {
+  const prefix = !proxyPath || proxyPath === '/' ? '' : proxyPath.replace(/\/$/, '');
+  return (Array.isArray(views) ? views : [])
+    .map((view) => ({ view, status: STATUS_PAGE_VIEW_PATH.exec(view?.path || '')?.[1] }))
+    .filter(({ status }) => status !== undefined)
+    .map(({ view, status }) => ({
+      status,
+      routePath: `${prefix}${view.path}`,
+      indexUrl: `${prefix}${view.path}/index.html`,
+      title: view.title,
+      client: view.client,
+    }));
+};
+
+/**
+ * Resolves the SSR views a gateway route intercepts and serves statically —
+ * the maintenance and offline documents. They carry no request-time logic, so
+ * the workload never needs to see them; the same build that writes the artifact
+ * hands `deploy --build-manifest` the URL its HTTPRoute rule targets.
+ * @function staticContextRoutesFactory
+ * @param {Array<object>} [views] - SSR view entries from `conf.ssr.json`.
+ * @param {string} [proxyPath] - The client's proxy sub-path (`/`, `/peer`, ...).
+ * @returns {Array<{context: string, routePath: string, indexUrl: string, title: string, client: string}>}
+ *   One entry per intercepted view, in declaration order.
+ * @memberof clientBuild
+ */
+const staticContextRoutesFactory = ({ views = [], proxyPath = '/' } = {}) => {
+  const prefix = !proxyPath || proxyPath === '/' ? '' : proxyPath.replace(/\/$/, '');
+  return (Array.isArray(views) ? views : [])
+    .filter(
+      (view) =>
+        view?.path &&
+        !STATUS_PAGE_VIEW_PATH.test(view.path) &&
+        INTERCEPT_VIEW_FLAGS.some((flag) => view[flag] === true),
+    )
+    .map((view) => ({
+      context: view.path.replace(/^\/+|\/+$/g, ''),
+      routePath: `${prefix}${view.path}`,
+      indexUrl: `${prefix}${view.path}/index.html`,
+      title: view.title,
+      client: view.client,
+    }));
+};
+
 /**
  * Recursively copies files from source to destination, but only files that don't exist in destination.
  * @function copyNonExistingFiles
@@ -742,14 +811,12 @@ const buildClient = async (
       }
 
       if (views) {
-        if (
-          !(
-            enableLiveRebuild &&
-            !options.liveClientBuildPaths.find(
-              (p) => p.srcBuildPath.startsWith(`./src/client/ssr`) || p.srcBuildPath.slice(-9) === '.index.js',
-            )
+        if (!(
+          enableLiveRebuild &&
+          !options.liveClientBuildPaths.find(
+            (p) => p.srcBuildPath.startsWith(`./src/client/ssr`) || p.srcBuildPath.slice(-9) === '.index.js',
           )
-        )
+        ))
           for (const view of views) {
             const buildPath = `${
               rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath
@@ -977,6 +1044,8 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
         // when the network is unreachable.
         const ssrClientConf = confSSR[getCapVariableName(client)] || {};
         const ssrViews = Array.isArray(ssrClientConf.views) ? ssrClientConf.views : [];
+        const statusPageRoutes = statusPageRoutesFactory({ views: ssrViews, proxyPath: path });
+        if (statusPageRoutes.length > 0) logger.info('ssr status page routes', statusPageRoutes);
         const PRE_CACHED_RESOURCES = [];
         let offlineFallbackUrl = null;
         let maintenanceFallbackUrl = null;
@@ -999,9 +1068,16 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
             renderApi: { JSONweb },
           });
 
-          const buildPath = `${
-            rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath
-          }${view.path === '/' ? view.path : `${view.path}/`}`;
+          // A status view is built under `status-pages/<status>/`, not on its own
+          // `/<status>` route: the gateway serves it by intercepting the
+          // runtime's error, and a document on that route would give the runtime
+          // a page of its own to serve or redirect to for the same condition.
+          const statusCode = statusPageRoutes.find((route) => route.routePath === `${proxyPrefix}${view.path}`)?.status;
+          const clientRoot =
+            rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath;
+          const buildPath = statusCode
+            ? `${clientRoot}/${dir.dirname(statusPageBuildSegment(statusCode))}/`
+            : `${clientRoot}${view.path === '/' ? view.path : `${view.path}/`}`;
 
           const indexUrl = buildIndexUrl(view.path);
           if (view.offlineDefault) {
@@ -1089,4 +1165,11 @@ ${swTransformedJs}`,
   }
 };
 
-export { buildClient, copyNonExistingFiles, unzipClientBuild, mergeClientBuildZip };
+export {
+  buildClient,
+  copyNonExistingFiles,
+  unzipClientBuild,
+  mergeClientBuildZip,
+  staticContextRoutesFactory,
+  statusPageRoutesFactory,
+};