@underpostnet/cyberia 3.2.80

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

@@ -0,0 +1,307 @@
+# 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 — 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.
+
+---
+
+## 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 — 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 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
+  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` | 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`                                       |
+
+---
+
+## Action–Quest Integration
+
+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\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 -->|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 → `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.
+
+---
+
+## 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
+```
+
+---
+
+## 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:
+
+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
+{ 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,
+  "dialogCode": "default-wason",
+  "questDialogueCodes": ["default-wason"],
+  "shopItems": [],
+  "craftRecipes": [],
+  "storageSlots": 0
+}
+```

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

@@ -0,0 +1,309 @@
+# Cyberia — Architecture
+
+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. The three Cyberia processes operate on top of it.
+
+---
+
+## Process model
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  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 · REST boot fallback (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, client hints,           │
+│            │       instance-map static presence + capability activity)    │
+│            └──→ engine-cyberia                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+Three processes, strict role separation. The ecosystem is fully operational only when all three are running and healthy at the same time.
+
+---
+
+## Role definitions
+
+### engine-cyberia (Node.js) — content authority
+
+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).
+
+What it owns:
+
+- 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 boot fallback (`/api/cyberia-instance/boot/*`): the same world-load / hot-reload payloads as the gRPC service, served over REST for deploys where the engine gRPC server is not enabled.
+- REST APIs for assets and the optional client-hints overrides.
+- Instance Map REST (`/api/cyberia-instance/instance-map/:code/{static,dynamic}`): static map topology plus authored presence POIs, `sumStatsLimit`-capped baseline ObjectLayer stat sums, and capability membership; the dynamic response supplies only per-player capability activity. Never live positions or simulation stats — those stay client-side.
+- Static content distribution + Cloudinary-backed asset flow.
+- Editor and CLI integration for content workflows.
+
+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.
+
+### cyberia-server (Go) — authoritative simulation runtime
+
+The tick-based authoritative simulation. Owns world state and the gameplay rules that mutate it.
+
+What it owns:
+
+- 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.
+
+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.
+
+What it owns:
+
+- 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.
+
+---
+
+## 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                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `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 |
+
+Dependency between services is handled by supervision and reconnect loops:
+
+- `cyberia-server` dials `engine-cyberia` gRPC at boot; on dial or load failure it retries over the REST boot fallback (`ENGINE_API_BASE_URL`, `/api/cyberia-instance/boot/*`) and exits only when both transports fail 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.                                                                                                                                                                                                                 |
+| **Instance Map**          | Client strategic overlay of packed map tiles and authored presence POIs. The static REST response supplies topology, presence, baseline ObjectLayer stat sums, and capability membership; the dynamic response supplies per-player capability activity. Live player presence and stats remain client-side. |
+| **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 |