cyberia 3.2.5 → 3.2.12

package/src/client/components/underpost/LogInUnderpost.js

@@ -6,8 +6,9 @@ import { RouterReady } from '../core/Router.js';
 import { s } from '../core/VanillaJs.js';
 import { commonUserGuard } from '../core/CommonJs.js';
 
-const LogInUnderpost = async function () {
-  LogIn.Event['LogInUnderpost'] = async (options) => {
+class LogInUnderpost {
+  static async instance() {
+  LogIn.onLogin(async (options) => {
     const { token, user } = options;
 
     AppStoreUnderpost.Data.user.main.model.user = user;
@@ -15,9 +16,10 @@ const LogInUnderpost = async function () {
     await RouterReady;
     await PanelForm.Data['underpost-panel'].updatePanel();
     if (s(`.main-btn-cloud`) && commonUserGuard(user.role)) s(`.main-btn-cloud`).classList.remove('hide');
-  };
+  }, { key: 'LogInUnderpost' });
   const { user } = await Auth.sessionIn();
   AppStoreUnderpost.Data.user.main.model.user = user;
-};
+  }
+}
 
 export { LogInUnderpost };

package/src/client/components/underpost/LogOutUnderpost.js

@@ -3,13 +3,15 @@ import { AppStoreUnderpost } from './AppStoreUnderpost.js';
 import { PanelForm } from '../core/PanelForm.js';
 import { s } from '../core/VanillaJs.js';
 
-const LogOutUnderpost = async function () {
-  LogOut.Event['LogOutUnderpost'] = async (result = { user: { _id: '' } }) => {
+class LogOutUnderpost {
+  static async instance() {
+  LogOut.onLogout(async (result = { user: { _id: '' } }) => {
     AppStoreUnderpost.Data.user.main.model.user = result.user;
 
     PanelForm.Data['underpost-panel'].updatePanel();
     if (s(`.main-btn-cloud`)) s(`.main-btn-cloud`).classList.add('hide');
-  };
-};
+  }, { key: 'LogOutUnderpost' });
+  }
+}
 
 export { LogOutUnderpost };

package/src/client/components/underpost/RouterUnderpost.js

@@ -0,0 +1,45 @@
+import { loggerFactory } from '../core/Logger.js';
+import { Modal } from '../core/Modal.js';
+import { s } from '../core/VanillaJs.js';
+
+const logger = loggerFactory(import.meta);
+
+const BannerAppTemplate = html`underpost.net`;
+
+class RouterUnderpost {
+  static routes() {
+    return {
+      '/': {
+        title: 'Home',
+        render: () => Modal.onHomeRouterEvent(),
+      },
+      '/contracultura-cyberpunk': {
+        title: 'contracultura-cyberpunk',
+        render: () => s(`.main-btn-contracultura-cyberpunk`).click(),
+      },
+      '/lab-gallery': { title: 'lab-gallery', render: () => s(`.main-btn-lab-gallery`).click() },
+      '/log-in': { title: 'log-in', render: () => s(`.main-btn-log-in`).click() },
+      '/sign-up': { title: 'sign-up', render: () => s(`.main-btn-sign-up`).click() },
+      '/log-out': {
+        title: 'log-out',
+        render: () => s(`.main-btn-log-out`).click(),
+      },
+      '/account': {
+        title: 'account',
+        render: () => s(`.main-btn-account`).click(),
+      },
+      '/u': { title: 'public-profile', render: () => s(`.main-btn-public-profile`).click() },
+      '/settings': { title: 'settings', render: () => s(`.main-btn-settings`).click() },
+      '/recover': { title: 'recover', render: () => s(`.main-btn-recover`).click() },
+      '/content': { title: 'content', render: () => s(`.main-btn-content`).click() },
+      '/cloud': { title: 'cloud', render: () => s(`.main-btn-cloud`).click() },
+      '/polyhedron': { title: 'polyhedron', render: () => s(`.main-btn-polyhedron`).click() },
+    };
+  }
+
+  static instance() {
+    return { Routes: RouterUnderpost.routes };
+  }
+}
+
+export { RouterUnderpost, BannerAppTemplate };

package/src/client/components/underpost/SettingsUnderpost.js

@@ -3,14 +3,14 @@ import { FullScreen } from '../core/FullScreen.js';
 import { Translate } from '../core/Translate.js';
 import { Worker } from '../core/Worker.js';
 
-const SettingsUnderpost = {
-  Render: async function () {
+class SettingsUnderpost {
+  static async instance() {
     let render = await FullScreen.RenderSetting();
     render += await Css.RenderSetting();
     render += await Translate.RenderSetting();
     render += await Worker.RenderSetting();
     return render;
-  },
-};
+  }
+}
 
 export { SettingsUnderpost };

package/src/client/components/underpost/SignUpUnderpost.js

@@ -1,9 +1,11 @@
 import { SignUp } from '../core/SignUp.js';
 
-const SignUpUnderpost = function () {
-  SignUp.Event['SignUpUnderpost'] = async (options) => {
+class SignUpUnderpost {
+  static instance() {
+  SignUp.onSignup(async (options) => {
     const { user } = options;
-  };
-};
+  }, { key: 'SignUpUnderpost' });
+  }
+}
 
 export { SignUpUnderpost };

package/src/client/components/underpost/TranslateUnderpost.js

@@ -1,10 +1,10 @@
 import { Translate } from '../core/Translate.js';
 
-const TranslateUnderpost = {
-  Init: async function () {
+class TranslateUnderpost {
+  static async instance() {
     Translate.Data['contracultura-cyberpunk'] = { en: 'Contracultura Cyberpunk', es: 'Contracultura Cyberpunk' };
     Translate.Data['lab-gallery'] = { en: 'Lab Gallery', es: 'Lab Gallery' };
-  },
-};
+  }
+}
 
 export { TranslateUnderpost };

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

@@ -0,0 +1,235 @@
+# Action System
+
+**Module:** `src/api/cyberia-action` · `src/api/cyberia-dialogue`
+
+---
+
+## Overview
+
+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 — Pre-alpha:** The CyberiaAction and CyberiaDialogue MongoDB schemas and Engine REST API (`src/api/cyberia-action`, `src/api/cyberia-dialogue`) are defined. Go server integration (NPC tap routing to action handlers, shop/craft transaction processing, quest grant on dialogue completion) is planned for the **Alpha milestone**. The `freeze_start`/`freeze_end` WS messages for modal protection are implemented in the Go server today.
+
+---
+
+## Data Model
+
+### CyberiaAction Schema
+
+```
+CyberiaAction {
+  code:         String  // stable unique slug
+  type:         String  // see Action Types below
+  label:        String  // display label on interaction button
+
+  // Spatial origin — NPC entity cell providing this action
+  sourceMapCode: String
+  sourceCellX:   Number
+  sourceCellY:   Number
+
+  // Identity — used to match quest objectives of type 'talk'
+  provideItemId: String  // entity's active skin ObjectLayer item ID (e.g. 'wason', 'alex')
+
+  // Quest grant — first interaction with this NPC starts the linked quest chain
+  grantQuestCode: String  // empty = no quest granted
+
+  // Dialogue
+  dialogCode:        String    // greeting dialogue shown on tap
+  questDialogueCodes: [String] // ordered dialogue codes that satisfy 'talk' quest objectives
+
+  // Type-specific payloads:
+  shopItems: [{
+    itemId:      String  // ObjectLayer item ID being sold
+    priceItemId: String  // currency item ID (default: 'coin')
+    priceQty:    Number  // price quantity
+  }]
+
+  craftRecipes: [{
+    outputItems: [{ itemId: String, qty: Number }]
+    ingredients: [{ itemId: String, qty: Number }]
+  }]
+
+  storageSlots: Number  // storage capacity (type='storage' only)
+}
+```
+
+### CyberiaDialogue Schema
+
+```
+CyberiaDialogue {
+  code:    String  // grouping key (e.g. "wason-intro")
+  order:   Number  // 0-based sequence within the group
+  speaker: String  // display name above the dialogue line
+  text:    String  // dialogue line content
+  mood:    String  // emotion hint: neutral | angry | sad | happy | ...
+}
+```
+
+A single `code` groups many ordered dialogue lines. The C client fetches all lines for a given code in one request, then displays them sequentially.
+
+---
+
+## Action Types
+
+| Type         | Description                                                    | Active Payload                                       |
+| ------------ | -------------------------------------------------------------- | ---------------------------------------------------- |
+| `quest-talk` | Grants a quest on first interaction, then shows dialogue       | `grantQuestCode`, `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`                                       |
+
+---
+
+## Action–Quest Integration
+
+The Action System and Quest System are linked through `provideItemId` and `questDialogueCodes`:
+
+```mermaid
+graph LR
+    Quest["CyberiaQuest\nstep.objective:\n{ type: 'talk', itemId: 'wason' }"]
+    Action["CyberiaAction\nprovideItemId: 'wason'\ngrantQuestCode: 'wason-intro'\nquestDialogueCodes: ['wason-intro']"]
+    Progress["CyberiaQuestProgress\nstep.objectiveProgress[i].current++"]
+
+    Quest -->|matched by provideItemId| Action
+    Action -->|player completes dialogue| Progress
+```
+
+**Talk objective satisfaction flow:**
+
+1. Player taps NPC → interaction bubble shown.
+2. Player taps interaction bubble → Action is fetched by spatial coordinates.
+3. Client displays `dialogCode` dialogue sequence.
+4. On first tap, if `grantQuestCode` is set → server grants the quest.
+5. After viewing all `questDialogueCodes` dialogue lines → server increments the matching `talk` objective's `current` counter.
+
+---
+
+## Shop Transaction Flow
+
+```mermaid
+sequenceDiagram
+    participant P as Player
+    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)
+```
+
+---
+
+## Craft Transaction Flow
+
+```mermaid
+sequenceDiagram
+    participant P as Player
+    participant G as Go Server
+    participant E as Engine (Node.js)
+    participant BC as ObjectLayerToken
+
+    P->>G: Tap craft NPC
+    G-->>P: FrozenInteractionState
+    P->>G: Craft request { recipeIndex }
+    Note over G: Verify player has all ingredients
+    G->>E: Deduct ingredient quantities from inventory
+    G->>E: Grant output items to inventory
+    opt Item has on-chain token (ERC-1155)
+        G->>BC: burn(ingredientTokenId, qty) per ingredient
+        G->>BC: mint(outputTokenId, qty)
+    end
+    G-->>P: FCT: ItemLoss per ingredient + ItemGain per output
+    G-->>P: ThawPlayer
+```
+
+---
+
+## Spatial Binding and Instance Init
+
+`sourceMapCode + sourceCellX + sourceCellY` links an Action to a specific entity cell in a specific map. During instance initialization:
+
+1. `instance_loader.go` reads each `CyberiaEntity` at its `initCellX/initCellY`.
+2. For entities with matching Action source coordinates, the Go server attaches the Action payload to the runtime entity.
+3. The entity's `entityStatus` is set to `action-provider` (ESI id=8) — the bouncing chat icon renders above its nameplate.
+
+---
+
+## Dialogue System
+
+Dialogue groups allow multi-line sequential NPC speech:
+
+```json
+[
+  {
+    "code": "wason-intro",
+    "order": 0,
+    "speaker": "Wason",
+    "text": "Young traveler... you've finally arrived.",
+    "mood": "neutral"
+  },
+  {
+    "code": "wason-intro",
+    "order": 1,
+    "speaker": "Wason",
+    "text": "The village is in danger. I need your help.",
+    "mood": "sad"
+  },
+  {
+    "code": "wason-intro",
+    "order": 2,
+    "speaker": "Wason",
+    "text": "Collect 5 herbs from the forest and return to me.",
+    "mood": "neutral"
+  }
+]
+```
+
+The C client fetches the full `code` group sorted by `order`, then renders lines one at a time in `modal_dialogue.c`. The player advances through lines by tapping.
+
+---
+
+## Indexes
+
+```javascript
+// CyberiaAction
+{ code: 1 }           // unique
+{ provideItemId: 1 }
+{ grantQuestCode: 1 } // sparse
+{ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 }
+
+// CyberiaDialogue
+{ code: 1 }
+{ code: 1, order: 1 }
+```
+
+---
+
+## Example Action Document
+
+```json
+{
+  "code": "wason-npc",
+  "type": "quest-talk",
+  "label": "Talk",
+  "sourceMapCode": "cyberia-village",
+  "sourceCellX": 12,
+  "sourceCellY": 8,
+  "provideItemId": "wason",
+  "grantQuestCode": "wason-intro",
+  "dialogCode": "wason-intro",
+  "questDialogueCodes": ["wason-intro"],
+  "shopItems": [],
+  "craftRecipes": [],
+  "storageSlots": 0
+}
+```

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

@@ -0,0 +1,83 @@
+# Cyberia Architecture
+
+Cyberia is the MMO extension that runs on top of Underpost Platform. Keep the model simple:
+
+- Underpost Platform provides the toolchain, deployment surface, PWA delivery, and base infrastructure.
+- `engine-cyberia` is the content authority.
+- `cyberia-server` is the authoritative simulation.
+- `cyberia-client` is the presentation runtime.
+
+---
+
+## System map
+
+```text
+Underpost Platform
+  -> toolchain, deploy, PWA build, static delivery, monitoring
+
+engine-cyberia (Node.js)
+  -> content, validation, persistence, gRPC/REST data services, asset metadata
+  -> feeds cyberia-server and cyberia-client
+
+cyberia-server (Go)
+  -> authoritative simulation and tick processing
+  -> feeds cyberia-client over WebSocket
+
+cyberia-client (C/WASM)
+  -> rendering, input, prediction, presentation
+```
+
+---
+
+## Responsibility split
+
+| Service          | Owns                                                                      | Must not own                                  |
+| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy       |
+| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication  | content authority, presentation metadata      |
+| `cyberia-client` | rendering, input, prediction, interpolation, presentation                 | authoritative world state, gameplay authority |
+
+Two boundaries are non-negotiable:
+
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
+
+---
+
+## Data flow
+
+```text
+engine-cyberia --gRPC--> cyberia-server --WebSocket--> cyberia-client
+engine-cyberia --REST-------------------------------> cyberia-client
+```
+
+- `engine-cyberia` publishes world content, validation rules, persistence-backed data, and asset metadata.
+- `cyberia-server` loads authoritative world data, advances the simulation tick, and emits per-player AOI snapshots.
+- `cyberia-client` sends typed input commands upstream and renders the result locally with prediction and interpolation.
+
+There is one source of truth per concern:
+
+- Content and world configuration: `engine-cyberia`
+- Real-time authoritative state: `cyberia-server`
+- Presentation and local interaction: `cyberia-client`
+
+---
+
+## Operational guardrails
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts as outputs only; never hand-edit them.
+
+---
+
+## Health states
+
+| State      | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `healthy`  | all three Cyberia services are up and connected                      |
+| `degraded` | at least one service is reconnecting or unavailable                  |
+| `standby`  | gameplay is paused because the full three-service set is not healthy |
+
+This is the model to document, operate, and monitor against.

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

@@ -0,0 +1,204 @@
+# Cyberia CLI
+
+`cyberia` (`bin/cyberia.js`) is the Cyberia-specific extension layer on top of the `underpost` CLI. Use
+it for MMO content and extension workflows; use `underpost` for the shared platform, deployment, and
+infrastructure surface. Unrecognized commands pass through to `underpost`.
+
+This page is intentionally command-first: keep it aligned with the shipped CLI surface and avoid
+repeating architecture prose unless it changes command behavior.
+
+```bash
+node bin/cyberia.js <command> [subcommand] [options]
+# or, installed globally:
+cyberia <command> [subcommand] [options]
+```
+
+| Command        | Purpose                                                               |
+| -------------- | --------------------------------------------------------------------- |
+| `ol`           | object-layer content import, procedural generation, atlas/sprite work |
+| `instance`     | export / import / drop a Cyberia instance and its related documents   |
+| `client-hints` | per-instance presentation hints (palette, camera, status icons)       |
+| `chain`        | Hyperledger Besu network + ERC-1155 `ObjectLayerToken` lifecycle      |
+| `run-workflow` | named operational scripts (seed defaults, build manifests/dashboard)  |
+
+Most data commands resolve the target DB from `DEFAULT_DEPLOY_ID` / `DEFAULT_DEPLOY_HOST` /
+`DEFAULT_DEPLOY_PATH` in the `--env-path` file (default `./.env`). `--dev` forces the deploy's
+`.env.development` (localhost IPFS, etc.); `--mongo-host` overrides the Mongo host.
+
+---
+
+## `cyberia ol` — object layer
+
+Import PNG assets, generate procedural layers, build atlas sprite sheets, push to IPFS + MongoDB.
+
+```bash
+cyberia ol [item-id] [options]
+```
+
+| Option                                                                               | Description                                                              |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `--import`                                                                           | Import specific item-id(s), comma-separated, from the asset directory    |
+| `--import-types [types]`                                                             | Batch import by type (e.g. `skin,floors`) or `all`                       |
+| `--generate`                                                                         | Generate procedural layers from a semantic item-id (e.g. `floor-desert`) |
+| `--count <n>` / `--density <0..1>`                                                   | Shape count multiplier (default `3`) / density (default `0.5`)           |
+| `--seed <seed>`                                                                      | Deterministic seed for `--generate` (e.g. `fx-42`)                       |
+| `--frame-index <n>` / `--frame-count <n>`                                            | Start frame (default `0`) / frame count (default `1`)                    |
+| `--to-atlas-sprite-sheet [dim]`                                                      | Build a consolidated atlas PNG for the item                              |
+| `--show-frame [dir_frame]`                                                           | View one frame (e.g. `08_0`; default `08_0`)                             |
+| `--show-atlas-sprite-sheet`                                                          | Display the atlas PNG for the item                                       |
+| `--drop`                                                                             | Drop existing data before importing (or standalone)                      |
+| `--client-public` / `--git-clean`                                                    | With `--drop`: also remove static asset folders / run clean              |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` · `--storage-file-path <path>` | env / DB / dev / filter overrides                                        |
+
+```bash
+# Import specific items
+cyberia ol hatchet,sword --import --env-path ./engine-private/conf/dd-cyberia/.env.development
+
+# Batch import by type, or everything
+cyberia ol --import-types skin,floors
+cyberia ol --import-types all
+
+# Procedural generation
+cyberia ol floor-desert --generate --seed fx-42
+cyberia ol floor-grass  --generate --frame-count 4 --count 5 --density 0.7
+
+# Atlas / inspect
+cyberia ol hatchet --to-atlas-sprite-sheet
+cyberia ol hatchet --show-frame 08_0
+
+# Drop + re-import a single item, including static folders
+cyberia ol hatchet --drop --client-public --import
+```
+
+---
+
+## `cyberia instance` — instance data
+
+Export / import / drop a game instance and its related maps, entities, actions, quests, and object
+layers in MongoDB.
+
+```bash
+cyberia instance [instance-code] [options]
+```
+
+| Option                                                | Description                                                             |
+| ----------------------------------------------------- | ----------------------------------------------------------------------- |
+| `--export [path]`                                     | Export instance and related documents to a backup directory             |
+| `--import [path]`                                     | Import from a backup directory (upsert, preserves UUIDs)                |
+| `--conf`                                              | With `--export`/`--import`: only `cyberia-instance.json` + `-conf.json` |
+| `--drop`                                              | Drop all documents associated with the instance code                    |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` | env / DB / dev overrides                                                |
+
+```bash
+cyberia instance FOREST --export ./backups/FOREST
+cyberia instance FOREST --import ./backups/FOREST
+cyberia instance FOREST --drop
+```
+
+---
+
+## `cyberia client-hints` — presentation hints
+
+Manage the per-instance `CyberiaClientHints` document (palette, camera, status icons, interpolation).
+These are presentation overrides only — never an instance or server identifier.
+
+```bash
+cyberia client-hints [instance-code] [options]
+```
+
+| Option                                                | Description                                     |
+| ----------------------------------------------------- | ----------------------------------------------- |
+| `--seed-defaults`                                     | Upsert canonical presentation-hint defaults     |
+| `--export [path]`                                     | Export the hints document to JSON               |
+| `--import [path]`                                     | Upsert hints from a JSON file                   |
+| `--drop`                                              | Remove the hints document for the instance code |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` | env / DB / dev overrides                        |
+
+```bash
+cyberia client-hints cyberia-main --seed-defaults
+cyberia client-hints cyberia-main --export ./client-hints-cyberia-main.json
+```
+
+---
+
+## `cyberia chain` — Besu + ObjectLayerToken
+
+Hyperledger Besu IBFT2 network and ERC-1155 `ObjectLayerToken` (CKY) lifecycle.
+
+### Network
+
+```bash
+cyberia chain deploy [options]            # deploy IBFT2 network to Kubernetes
+cyberia chain generate-manifests [opts]   # generate manifests without deploying (same options)
+cyberia chain remove [--namespace besu] [--clean-keys] [--clean-manifests]
+```
+
+Key `deploy` options: `--validators <n>` (4) · `--chain-id <id>` (777771) · `--block-period <s>` (5) ·
+`--epoch-length <n>` (30000) · `--besu-image <img>` · `--node-port-rpc <port>` (30545) ·
+`--node-port-ws <port>` (30546) · `--namespace <ns>` (besu) · `--pull-image` · `--skip-generate` ·
+`--skip-wait`.
+
+### Contract
+
+```bash
+cyberia chain compile
+cyberia chain test
+cyberia chain deploy-contract --network besu-k8s   # deploys ObjectLayerToken, mints initial CKY
+```
+
+### Keys
+
+```bash
+cyberia chain key-gen                                       # new secp256k1 deployer key
+cyberia chain set-coinbase --private-key 0xYOUR_KEY
+cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/<address>.key.json
+```
+
+### Tokens
+
+```bash
+cyberia chain register <item-id> --from-db --supply 1            # 1 = NFT, >1 = semi-fungible
+cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000}]'
+cyberia chain mint     --token-id 0 --to 0xABCD... --amount 1000000000000000000000
+cyberia chain transfer --from 0x... --to 0x... --token-id 0 --amount 1000
+cyberia chain burn     --token-id 0 --address 0x... --amount 500
+cyberia chain balance  --address 0xABCD... --token-id 0
+cyberia chain status   [--network besu-k8s]                     # chain id, block, supply, pause state
+cyberia chain pause   [--network besu-k8s]                      # owner-only transfer freeze / resume
+cyberia chain unpause [--network besu-k8s]
+```
+
+`--from-db` resolves the canonical IPFS CID from MongoDB (recommended over manual `--metadata-cid`).
+
+---
+
+## `cyberia run-workflow` — operational scripts
+
+Named scripts from the `scripts/` directory for seeding and build maintenance.
+
+| Subcommand                   | Description                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `import-default-items`       | Import default object layers, skill config, dialogues, client-hints to Mongo        |
+| `seed-skill-config`          | Upsert `DefaultSkillConfig` into a `CyberiaInstance` (`--instance-code`)            |
+| `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
+cyberia run-workflow seed-skill-config --instance-code default
+cyberia run-workflow generate-semantic-examples
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
+```
+
+---
+
+## Operational rules
+
+- Preserve public CLI entrypoints and command names unless a change is intentionally breaking.
+- Reuse existing helpers for config loading, env resolution, path normalization, and deploy selection.
+- Prefer one source of truth for generated manifests, deploy IDs, runtime choice, and asset metadata.
+- Treat generated artifacts (atlases, manifests, dashboard HTML) as outputs only; never hand-edit them.
+- `engine-private/` is a private external dependency; never assume its contents exist locally.