cyberia 3.2.12 → 3.2.70

package/src/client/components/cyberia-portal/TranslateCyberiaPortal.js

@@ -22,6 +22,14 @@ class TranslateCyberiaPortal {
       en: 'Cyberia Instance Engine',
       es: 'Cyberia Instance Engine',
     };
+    Translate.Data['cyberia-action-engine'] = {
+      en: 'Cyberia Action Engine',
+      es: 'Cyberia Action Engine',
+    };
+    Translate.Data['cyberia-entity-engine'] = {
+      en: 'Cyberia Entity Engine',
+      es: 'Cyberia Entity Engine',
+    };
   }
 }
 

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 — 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.
+> **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.
 
 ---
 
@@ -27,11 +27,12 @@ CyberiaAction {
   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')
+  // Identity — the NPC skin is derived from the `default-<skin>` dialogue code
+  // (no stored field); 'talk' objectives match the talked-to bot's active skin.
 
-  // Quest grant — first interaction with this NPC starts the linked quest chain
-  grantQuestCode: String  // empty = no quest granted
+  // Quest award — NOT stored on the action. The quest(s) this action awards are
+  // the CyberiaQuest documents whose (sourceMapCode, sourceCellX, sourceCellY)
+  // match this action's cell; the runtime offers the next acceptable one.
 
   // Dialogue
   dialogCode:        String    // greeting dialogue shown on tap
@@ -73,7 +74,7 @@ A single `code` groups many ordered dialogue lines. The C client fetches all lin
 
 | Type         | Description                                                    | Active Payload                                       |
 | ------------ | -------------------------------------------------------------- | ---------------------------------------------------- |
-| `quest-talk` | Grants a quest on first interaction, then shows dialogue       | `grantQuestCode`, `dialogCode`, `questDialogueCodes` |
+| `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[]`                                     |
@@ -83,25 +84,26 @@ A single `code` groups many ordered dialogue lines. The C client fetches all lin
 
 ## Action–Quest Integration
 
-The Action System and Quest System are linked through `provideItemId` and `questDialogueCodes`:
+The Action System and Quest System are linked by **cell** (the action and the
+quest it awards share `sourceMapCode/sourceCellX/sourceCellY`) and by the NPC's
+active **skin** (which `talk` objectives match):
 
 ```mermaid
 graph LR
-    Quest["CyberiaQuest\nstep.objective:\n{ type: 'talk', itemId: 'wason' }"]
-    Action["CyberiaAction\nprovideItemId: 'wason'\ngrantQuestCode: 'wason-intro'\nquestDialogueCodes: ['wason-intro']"]
+    Quest["CyberiaQuest\nsource cell: (12,10)\nstep.objective: { type: 'talk', itemId: 'wason' }"]
+    Action["CyberiaAction\nsource cell: (12,10)\nquestDialogueCodes: ['default-wason']"]
     Progress["CyberiaQuestProgress\nstep.objectiveProgress[i].current++"]
 
-    Quest -->|matched by provideItemId| Action
+    Quest -->|same source cell| 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.
+2. Player taps interaction bubble → `modal_interact` opens; the offered quest is the one bound to the NPC's cell.
+3. Accepting is explicit: the **Take Quest** button sends `quest_accept` and the server grants the acceptable quest bound to that cell (prerequisites met, not active/completed).
+4. Talk objectives advance only after the player reads **all** `questDialogueCodes` lines (`dlg_complete`), validated server-side; never by a button.
 
 ---
 
@@ -154,6 +156,80 @@ 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
+integration buttons (**Chat**, **Integration**) that open the JS overlay. The
+action tab's **Talk / Take mission** opens `modal_dialogue` (bottom half).
+
+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
+dialogue codes — the server resolves the bound action from its own
+`entityId → CyberiaAction` cache (bound at instance init).
+
+### Wire messages
+
+| Direction | Message        | When                                  | Payload                              |
+| --------- | -------------- | ------------------------------------- | ------------------------------------ |
+| C → S     | `dlg_start`    | `modal_dialogue` opens                | `{ entityId, itemId }`               |
+| C → S     | `dlg_complete` | player reads all lines, closes        | `{ entityId, itemId, dialogCode }`   |
+| C → S     | `dlg_cancel`   | player dismisses early (✕ / outside)  | `{ entityId, itemId }`               |
+| S → C     | `dlg_ack`      | after `dlg_complete` is processed     | `{ questGranted, objectivesDone, quests[] }` |
+
+Binary uplink opcodes: `dlg_start` `0x17`, `dlg_complete` `0x18`, `dlg_cancel`
+`0x19` (JSON aliases of the same names are also accepted).
+
+`dlg_ack` is notify-only — it carries the affected quest snapshot entries the
+client upserts into its local `quest_store` (Quest Journal); it never gates
+simulation state.
+
+### Server `dlg_complete` handling
+
+1. Validate `player.activeDialogueEntityID == msg.entityId`; drop otherwise.
+2. Clear the dialogue context and thaw the player (modal protection off).
+3. Resolve the action from `actionCache[entityId]`. `talk` → ack only.
+4. `quest-talk`: `dlg_complete` NEVER grants — it advances every active quest
+   whose **current step** has a `{ type: 'talk', itemId == bot active skin }`
+   objective, **only** when `msg.dialogCode` is in the action's
+   `questDialogueCodes`. Granting is a separate explicit `quest_accept`, which
+   grants the acceptable quest bound to the NPC's cell. On quest completion,
+   deliver rewards (FCT); successors are NOT auto-granted (the player accepts
+   each from its NPC).
+
+> **Dialogue-code contract.** The C client fetches dialogue groups at
+> `/api/cyberia-dialogue/code/default-<itemId>`, so the code it reports on
+> `dlg_complete` is `default-<provideItemId>`. For a `quest-talk` objective to
+> advance, the action's `questDialogueCodes` must contain that code.
+
+### Freeze semantics
+
+| Event                              | Player state              |
+| ---------------------------------- | ------------------------- |
+| `modal_interact` open              | Active (no freeze)        |
+| `dlg_start` sent                   | Frozen — immune to damage |
+| `dlg_complete` / `dlg_cancel` sent | Unfrozen                  |
+
+---
+
+## Fallback World mission instantiation
+
+The default mission system is playable in the procedural **Fallback World**.
+`DefaultCyberiaActions` carry `sourceMapCode` / `sourceCellX` / `sourceCellY`
+(all on `fallback-map-0`), and the world generator's
+`generateActionProviderBots()` places one passive NPC bot per action at those
+exact cells (skin = `provideItemId`, zero spawn/aggro radius). The fallback map
+builder reserves those cells (dropping any overlapping obstacle) so the NPCs
+always stand on walkable ground. The Go server then binds each bot back to its
+action by `sourceMapCode + sourceCellX + sourceCellY` at instance init and keeps
+an **ephemeral** per-session `CyberiaQuestProgress` (no persistence) — matching
+the ROADMAP Road-to-Alpha-Open contract. `scp-2040` kill targets spawn from the
+random bot pool, so the intro quest's talk → collect → kill loop is reachable.
+
+---
+
 ## Spatial Binding and Instance Init
 
 `sourceMapCode + sourceCellX + sourceCellY` links an Action to a specific entity cell in a specific map. During instance initialization:
@@ -203,8 +279,6 @@ The C client fetches the full `code` group sorted by `order`, then renders lines
 ```javascript
 // CyberiaAction
 { code: 1 }           // unique
-{ provideItemId: 1 }
-{ grantQuestCode: 1 } // sparse
 { sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 }
 
 // CyberiaDialogue
@@ -224,10 +298,8 @@ The C client fetches the full `code` group sorted by `order`, then renders lines
   "sourceMapCode": "cyberia-village",
   "sourceCellX": 12,
   "sourceCellY": 8,
-  "provideItemId": "wason",
-  "grantQuestCode": "wason-intro",
-  "dialogCode": "wason-intro",
-  "questDialogueCodes": ["wason-intro"],
+  "dialogCode": "default-wason",
+  "questDialogueCodes": ["default-wason"],
   "shopItems": [],
   "craftRecipes": [],
   "storageSlots": 0

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

@@ -1,78 +1,118 @@
-# Cyberia Architecture
+# Cyberia — Architecture
 
-Cyberia is the MMO extension that runs on top of Underpost Platform. Keep the model simple:
+Cyberia is the real-time MMO extension that runs on Underpost Platform. This document describes the three Cyberia processes, their boundaries, the data flow between them, and the canonical model for tick, snapshot, prediction, reconciliation, interpolation, and replication.
 
-- 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.
+Underpost Platform provides the toolchain, deployment surface, PWA delivery, and base infrastructure. The three Cyberia processes operate on top of it.
 
 ---
 
-## System map
+## Process model
 
-```text
-Underpost Platform
-  -> toolchain, deploy, PWA build, static delivery, monitoring
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  UNDERPOST PLATFORM (infra · toolchain · deploy · PWA/Workbox)          │
+│                                                                          │
+│  ┌─────────────────────┐                                                 │
+│  │ Persistent backend  │   ← Cyberia content authority + asset backend   │
+│  │ ──────────────────  │                                                 │
+│  │  engine-cyberia     │     Node.js                                     │
+│  │  MongoDB            │                                                 │
+│  │  IPFS / Cloudinary  │                                                 │
+│  │  ObjectLayerToken   │     Hyperledger Besu (off-line dependency)      │
+│  └─────────┬───────────┘                                                 │
+│            │ gRPC (world load, hot reload)                               │
+│            ▼                                                             │
+│  ┌─────────────────────┐                                                 │
+│  │ Authoritative       │   ← Cyberia simulation authority                │
+│  │ simulation runtime  │                                                 │
+│  │ ──────────────────  │                                                 │
+│  │  cyberia-server     │     Go                                          │
+│  └─────────┬───────────┘                                                 │
+│            │ WebSocket (binary AOI snapshots, typed input commands)      │
+│            ▼                                                             │
+│  ┌─────────────────────┐                                                 │
+│  │ Presentation        │   ← Cyberia render + prediction client          │
+│  │ runtime             │                                                 │
+│  │ ──────────────────  │                                                 │
+│  │  cyberia-client     │     C / WebAssembly (Raylib · Emscripten)       │
+│  └─────────────────────┘                                                 │
+│            │                                                             │
+│            │ REST (atlas frames, asset metadata, optional client hints)  │
+│            └──→ engine-cyberia                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
 
-engine-cyberia (Node.js)
-  -> content, validation, persistence, gRPC/REST data services, asset metadata
-  -> feeds cyberia-server and cyberia-client
+Three processes, strict role separation. The ecosystem is fully operational only when all three are running and healthy at the same time.
 
-cyberia-server (Go)
-  -> authoritative simulation and tick processing
-  -> feeds cyberia-client over WebSocket
+---
 
-cyberia-client (C/WASM)
-  -> rendering, input, prediction, presentation
-```
+## Role definitions
 
----
+### engine-cyberia (Node.js) — content authority
 
-## Responsibility split
+The content-authoring backend and persistence layer for Cyberia. Owns persisted data and exposes it through two transports: gRPC (consumed by `cyberia-server` at boot and during hot reload) and REST (consumed by `cyberia-client` for asset distribution and optional presentation overrides).
 
-| 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 |
+What it owns:
 
-Two boundaries are non-negotiable:
+- Content generation, validation, and persistence.
+- Maps, portals, object layers, atlas/sprite-sheet metadata.
+- World configuration: AOI radius, economy rules, skill rules, equipment rules, entity gameplay defaults.
+- Persisted character/quest/dialogue/action data.
+- gRPC `CyberiaDataService` for world load and content streaming.
+- REST APIs for assets and the optional client-hints overrides.
+- Static content distribution + Cloudinary-backed asset flow.
+- Editor and CLI integration for content workflows.
 
-- Do not move authoritative logic into the client.
-- Do not move content-authority logic into the Go runtime.
+What it does NOT own:
 
----
+- Real-time simulation. It is not a gameplay runtime.
+- Per-tick state advancement.
+- Client presentation policy (palette, camera, dev overlay, icon visuals).
+- World mutation during gameplay.
 
-## Data flow
+### cyberia-server (Go) — authoritative simulation runtime
 
-```text
-engine-cyberia --gRPC--> cyberia-server --WebSocket--> cyberia-client
-engine-cyberia --REST-------------------------------> cyberia-client
-```
+The tick-based authoritative simulation. Owns world state and the gameplay rules that mutate it.
 
-- `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.
+What it owns:
 
-There is one source of truth per concern:
+- Authoritative world state.
+- The tick: a `uint32` advanced once per simulation step at a fixed `tickRate`.
+- Simulation phases — the only allowed mutators of world state.
+- AOI replication: per-player interest filtering and snapshot emission.
+- Input command processing: typed input commands drained from per-player queues each tick.
+- Snapshot generation and delivery via WebSocket.
 
-- Content and world configuration: `engine-cyberia`
-- Real-time authoritative state: `cyberia-server`
-- Presentation and local interaction: `cyberia-client`
+What it does NOT own:
 
----
+- Persistence (loaded once at boot from engine-cyberia).
+- Client presentation. The server holds no palette, no camera knobs, no dev-overlay flag, no status-icon visuals.
+
+### cyberia-client (C / WebAssembly) — presentation runtime
+
+The render and interactive runtime. Compiled to WASM via Emscripten and served as a Progressive Web App through the Underpost Platform delivery pipeline.
 
-## Operational guardrails
+What it owns:
 
-- 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.
+- Rendering and UI.
+- Input capture: raw OS events → typed input commands with monotonic sequence numbers.
+- Prediction of the local player.
+- Reconciliation against authoritative snapshots.
+- Interpolation of remote entities.
+- Presentation defaults (palette, status-icon visuals, camera knobs, interpolation window, dev-overlay flag) — loaded at startup from the client-hints REST endpoint.
+- Optional client-hints fetch for per-instance presentation overrides.
+
+What it does NOT own:
+
+- World simulation.
+- Economy outcomes, combat resolution, skill dispatch decisions.
+- Any state another client depends on for correctness.
 
 ---
 
-## Health states
+## Runtime operating model
+
+The three processes are supervised independently. Each service owns its own monitor and reconnector. The game is playable only when all three are healthy at the same time.
 
 | State      | Meaning                                                              |
 | ---------- | -------------------------------------------------------------------- |
@@ -80,4 +120,186 @@ There is one source of truth per concern:
 | `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.
+Dependency between services is handled by supervision and reconnect loops:
+
+- `cyberia-server` dials `engine-cyberia` gRPC at boot and exits on dial failure rather than fabricate a world. On reconnect, it reloads world configuration.
+- `cyberia-client` reconnects to `cyberia-server` over WebSocket and re-fetches content from `engine-cyberia` over REST independently.
+- If any one of the three services goes unhealthy, the game moves to standby until all three recover.
+
+Underpost Platform deploy orchestration ensures the backend layer is ready before the simulation layer is started, and the simulation layer is ready before the presentation layer connects. This ordering is an infrastructure concern, not a documentation model: the processes themselves are supervised and reconnect without requiring a manual restart chain.
+
+---
+
+## 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.
+
+| Concept                  | Value                                 | Notes                                                                                                   |
+| ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **tick**                 | `uint32`                              | Monotonic simulation step counter on `cyberia-server`. Resets only on world rebuild.                    |
+| **tick rate**            | Hz (default `30`)                     | Simulation frequency. Authoritative; comes from world configuration. The string "fps" is never used to describe the server. |
+| **snapshot rate**        | Hz (default `20`)                     | AOI replication frequency. Decoupled from tick rate so bandwidth scales independently of simulation fidelity. |
+| **tick duration**        | `1 / tick_rate`                       | The dt used by every simulation phase.                                                                  |
+| **client tick estimate** | derived                               | Client estimate of the server's current tick, used to stamp outgoing input commands.                    |
+| **render tick**          | `server_tick_estimate − INTERP_TICKS` | The tick the interpolation module samples remote entities at.                                           |
+
+Three clocks, one tick number: simulation tick (server), snapshot tick (server replication), render frame (client). The tick number is the only synchronization point.
+
+---
+
+## Simulation phases
+
+Inside one simulation tick, `cyberia-server` runs the following phases in fixed order. These are the only functions that mutate authoritative world state:
+
+1. `phaseInput` — drain each player's `InputQueue`; dispatch typed input commands to gameplay handlers.
+2. `phaseLifecycle` — respawn timers, despawn expirations.
+3. `phaseSkills` — skill projectile collisions.
+4. `phaseAI` — bot behaviour decisions.
+5. `phaseMovement` — integrate positions using `tickDuration`.
+6. `phasePortals` — portal entry and teleport.
+
+A separate ticker runs replication independently of the simulation:
+
+- `phaseReplication` — per player: compute AOI, encode snapshot, dispatch. Runs at `snapshotRate`.
+
+Phases never read presentation data. They consume world configuration loaded at boot (gameplay rules) and the input queue.
+
+---
+
+## Client render frame
+
+The render frame runs at vsync. Inside one render frame, `cyberia-client` performs:
+
+1. Poll any pending optional client-hints fetch.
+2. Capture raw input → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
+3. Reconcile against the latest snapshot: drop input commands ≤ `lastAckedSequence`, rewind self to authoritative position, replay unacked commands.
+4. Fixed-timestep simulation: while accumulator ≥ `tickDuration`, advance prediction one tick.
+5. Interpolation: compute remote-entity view positions at `renderTick`.
+6. Render. Read view models; never mutate world state.
+
+Render frame rate is independent of simulation tick rate. The fixed-timestep accumulator ensures the predicted simulation advances at the authoritative `tickRate` regardless of FPS.
+
+---
+
+## Wire protocol — AOI snapshot header
+
+Snapshots travel as binary WebSocket frames. The header carries the simulation tick and the per-player acknowledged input sequence.
+
+```
+Header (binary, little-endian, 11 bytes for AOI snapshots):
+  [0]       u8   msgType     0x01 = aoi_update, 0x03 = full_aoi
+  [1..4]    u32  tick        simulation tick at which the snapshot was produced
+  [5..8]    u32  lastAcked   highest InputCommand.Sequence applied for this player
+  [9..10]   u16  entityCount entity blocks that follow
+```
+
+Other message types (init data, FCT) use their own headers and are not part of the per-tick replication stream.
+
+---
+
+## Input command pipeline
+
+Client input flows through a typed pipeline. There is no JSON intermediate on the binary path. The simulation tick is the only consumer.
+
+```
+WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequence, payload}
+                                              ↓
+                                              dispatchInputCommand
+                                              ↓
+                                              PlayerState.InputQueue (per-player, bounded)
+                                              ↓
+                       phaseInput (under world mutex, once per simulation tick)
+                                              ↓
+                       phase_input_handlers.go — typed dispatch per InputKind
+                                              ↓
+                       authoritative world state
+```
+
+`InputCommand.Sequence` is monotonic per client. The server tracks the highest applied sequence per player; `phaseReplication` writes it into every snapshot header. The client drops acknowledged input commands from its prediction replay buffer using this value.
+
+---
+
+## Presentation metadata ownership
+
+Presentation is client-owned. The authoritative server holds no presentation state.
+
+| Concern                                          | Owner                 | Mechanism                                                                       |
+| ------------------------------------------------ | --------------------- | ------------------------------------------------------------------------------- |
+| Palette (named ColorRGBA entries)                | engine-cyberia (REST) | served by `GET /api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE`. Source schema: `SharedDefaultsCyberia.js`. |
+| Status-icon visuals (icon stems + border colors) | engine-cyberia (REST) | same                                                                            |
+| Per-entity-type fallback color keys              | engine-cyberia (REST) | same                                                                            |
+| Camera defaults (smoothing, zoom)                | engine-cyberia (REST) | same                                                                            |
+| Cell-pixel size, default object dims             | engine-cyberia (REST) | same                                                                            |
+| Interpolation window                             | engine-cyberia (REST) | same                                                                            |
+| Dev-overlay flag                                 | engine-cyberia (REST) | same                                                                            |
+| World configuration (gameplay rules)             | engine-cyberia (gRPC) | `CyberiaInstanceConf` — no presentation; only simulation                        |
+
+The cyberia-client carries **no** compile-time palette. `domain/presentation_runtime.{c,h}` fetches the full presentation surface on startup; until the fetch settles the runtime returns a tiny inline neutral-grey bootstrap so the splash screen has something to draw. The simulation is unaffected by the fetch outcome.
+
+`cyberia-server` never reads any presentation field. The only "representational" data on the simulation wire is the **active item IDs** carried inside each AOI snapshot. Everything else visual is the client's job, fed by the hints REST endpoint.
+
+---
+
+## Canonical vocabulary
+
+Every Cyberia document uses the same terms. Aliases are not permitted.
+
+| Term                      | Definition                                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **tick**                  | Monotonic simulation step counter.                                                                                        |
+| **tick rate**             | Simulation Hz on `cyberia-server`.                                                                                        |
+| **snapshot**              | AOI-filtered world view at one tick for one player.                                                                       |
+| **prediction**            | Optimistic local apply of input commands to the predicted self entity.                                                    |
+| **reconciliation**        | Drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs.                                   |
+| **display smoothing**     | Per-render-frame exponential lerp from the discrete predicted self position to a continuous on-screen position. Decouples the visible main player from sim-tick boundaries. |
+| **interpolation**         | Render-time smoothing of remote entities, sampled from snapshot history.                                                  |
+| **authoritative server**  | `cyberia-server`. Sole authority on world state.                                                                          |
+| **content authority**     | `engine-cyberia`. Sole authority on persisted content and world configuration.                                            |
+| **client hints**          | Optional presentation overrides served by engine-cyberia.                                                                 |
+| **world configuration**   | Gameplay parameters loaded at server boot from engine-cyberia.                                                            |
+| **presentation metadata** | Render-only data. Client-owned.                                                                                           |
+| **input command**         | Typed client→server frame with kind, clientTick, sequence, payload.                                                       |
+| **AOI**                   | Area of interest — the spatial filter that defines which entities a given player receives.                                |
+| **replication**           | Production and delivery of snapshots from server to clients.                                                              |
+| **simulation phase**      | A named step inside one simulation tick.                                                                                  |
+| **healthy**               | All three Cyberia services up and connected; game is playable.                                                            |
+| **standby**               | Game paused because at least one of the three services is not healthy.                                                    |
+
+Forbidden usages:
+
+- "fps" on `cyberia-server` (use **tick rate**).
+- "frame-based" simulation language on the server.
+- "game_state" as a god object on the client.
+- Render metadata in `cyberia-server` state.
+- "engine" without qualifier when the project name is intended. Use **engine-cyberia** for the Cyberia content backend; use **Underpost Platform** for the umbrella product.
+
+---
+
+## Instance topology
+
+A `CyberiaInstance` (persisted in MongoDB, served by engine-cyberia) is a directed graph:
+
+- **Vertices** — `CyberiaMap` documents (grid-based maps).
+- **Edges** — `PortalEdge` records connecting source cell → target map/cell.
+
+Portal modes:
+
+| Mode           | Behaviour                                       |
+| -------------- | ----------------------------------------------- |
+| `inter-portal` | Teleport to a specific cell on a target map     |
+| `inter-random` | Teleport to a random valid cell on a target map |
+| `intra-portal` | Teleport within the same map to a specific cell |
+| `intra-random` | Teleport within the same map to a random cell   |
+
+Topology modes: `linear`, `hub-spoke`, `open`, `grid`.
+
+---
+
+## Entity types
+
+| Type           | Behavior              | Description                 |
+| -------------- | --------------------- | --------------------------- |
+| `player`       | interactive           | Local player (self)         |
+| `other_player` | interactive           | Remote players inside AOI   |
+| `bot`          | `hostile` / `passive` | AI-controlled entities      |
+| `skill`        | `skill`               | Runtime-spawned projectile  |

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

@@ -178,8 +178,8 @@ 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`)            |
+| `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                |
@@ -187,7 +187,7 @@ Named scripts from the `scripts/` directory for seeding and build maintenance.
 
 ```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 seed-skills
 cyberia run-workflow generate-semantic-examples
 cyberia run-workflow build-manifest
 cyberia run-workflow build-server-dashboard