@underpostnet/cyberia 3.3.73 → 3.3.77

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

@@ -217,10 +217,17 @@ Other message types — init data (0x02), FCT (0x04), ItemFCT (0x05) — carry t
 
 The client speaks REST directly to engine-cyberia for content. None of these calls go through cyberia-server.
 
+The atlas blob is the minified render, at one pixel per cell, and the atlas metadata describes that
+same render. The engine keeps a second, human-resolution render for viewing; the client never
+downloads it. The idle still is the first down-idle frame cut out of that render, and is what the
+interact overlay and every engine editor show as an item's picture. `cyberia ol --minify` refreshes
+the minified render and the idle still of stored items.
+
 | Endpoint                                                       | Purpose                                    |
 | -------------------------------------------------------------- | ------------------------------------------ |
 | `GET /api/atlas-sprite-sheet/metadata/:itemKey`                | Frame layout JSON for a sprite atlas       |
-| `GET /api/atlas-sprite-sheet/blob/:itemKey`                    | Atlas PNG                                  |
+| `GET /api/atlas-sprite-sheet/blob/:itemKey`                    | Minified atlas PNG, one pixel per cell     |
+| `GET /api/atlas-sprite-sheet/idle-preview/:itemKey`            | Down-idle still PNG, the item's picture    |
 | `GET /api/object-layer/:itemId`                                | ObjectLayer JSON metadata                  |
 | `GET /api/cyberia-dialogue/code/default-:itemId`               | Dialogue lines for an NPC                  |
 | `GET /assets/ui-icons/:iconId.png`                             | Status-bar icons                           |
@@ -238,7 +245,8 @@ The Instance Map is a strategic overlay, not a minimap. It visualises the instan
 
 One integrated widget with two modes, split across two modules:
 
-- **Toolbar** (`ui/toolbar`) — the top HUD strip: the compact map readout left-aligned, and the right-hand toggle row `[quest][map][fullscreen]`. The quest button shows/hides the Quest Journal (hidden by default); the **Map** toggle (ui-icon `map`) morphs the container to the full screen with an eased transition and retracts it the same way on close, swapping to a close icon while expanded.
+- **Toolbar** (`ui/toolbar`) — the top HUD strip: the compact map readout left-aligned, and the right-hand toggle row `[quest][map][fullscreen]`. The quest button shows/hides the Quest Journal and the map button shows/hides the minimap; both are hidden by default and stay open together. The coordinate readout opens the expanded Instance Map, which morphs to the full screen with an eased transition and retracts the same way on close.
+- **Side stack** (`ui/hud_side_stack`) — the right-hand column both panels live in: the minimap on top, the Quest Journal beneath, between the toolbar and the inventory bar. The column sizes to the room the bar leaves. When both are open the minimap gives way to at most half of the column so the journal keeps room, and the journal takes only what its content needs. Each panel keeps its own state across toggles: the journal its scroll, sections and pages, the minimap its zoom.
 - **Container** (`ui/modal_map`) — compact mode is the always-on readout (map code, position, fps) hosted inside the toolbar; expanded mode is the full-screen morph target.
 - **Content** (`ui/modal_instance_map`) — renders the Instance Map inside the container: a non-blocking translucent full-screen panel (the world keeps rendering behind it).
 
@@ -253,36 +261,50 @@ Strict independence from the gameplay renderer:
 
 Data lifecycle:
 
-1. Opening the overlay fetches the **static** payload once: graph nodes, portal edges, and authored `presencePois` carrying map-cell presence status, `sumStatsLimit`-capped baseline ObjectLayer stat sums, and static action/quest capability membership. The instance code arrives in the simulation server's `metadata` message.
+1. Opening the overlay fetches the **static** payload once: graph nodes, portal edges, and authored `presencePois` carrying map-cell presence status and static action/quest capability membership. The instance code arrives in the simulation server's `metadata` message.
 2. While open, the client polls the **dynamic** endpoint (~1/s, `?playerId=`) only for per-player capability activity: `acceptable` / `active` quests and active actions.
 3. Closing the overlay stops polling immediately; late responses are discarded.
 
 Live player position never travels through this API — engine-cyberia holds no simulation state. The overlay marks the player's node (and cell fraction within it) from the client's own predicted position, refreshed every frame.
 
-At normal zoom, POIs render only their authored presence-status icon. At inspection zoom, static action and quest capability icons appear with the authored baseline stat sum; dynamic activity only changes capability emphasis. The local player's live presence and authoritative stats sum remain client-side. Decorative map content without a presence status is not rendered as a POI.
+At normal zoom, POIs render only their authored presence-status icon. At inspection zoom, static action and quest capability icons appear; dynamic activity only changes capability emphasis. The local player's live presence and authoritative stats sum remain client-side. Decorative map content without a presence status is not rendered as a POI.
 
 ---
 
+## Stats and progression
+
+Every living entity's overhead HUD shows `[stats] lv.<level>` and `[stack] <stats sum>` above its nameplate, and a gold XP bar under its HP bar. The local player's bar fills with its progress through the current level and carries an `XP n / m` label in a smaller font; entities whose XP the client cannot read show an empty, unlabeled bar.
+
+The Stats tab of the interact modal draws one shared stat panel per block: the stats icon, the signed sum, and a two-column grid with one icon per stat. Every entity gets its effective stats. The local player also gets the OL modifiers, base stats, and temporary modifiers from the self snapshot. The inventory modal draws the same panel for one item.
+
+An XP award floats as gold `+N XP` combat text over the earner only. A server level increment triggers a `LEVEL UP` aura: shaded gold sparks stream from the entity's feet up past its head for 3 s under a spinning star and a label, and the whole effect follows the entity as it moves, for any entity in view. First sight, repeated snapshots, and lower levels do not trigger it.
+
+A defeat of a player or bot triggers the death cue: shaded red sparks burst out of the body and fall while a `skull` icon rises over it for 2.6 s, following the body. It fires once, when an entity seen alive in the prior snapshot is dead in this one. An entity first seen dead, or still dead, triggers nothing. A resource is extracted, not slain: it goes straight to its extracted state with no cue.
+
+While either cue runs, the entity's whole overhead stack, presence icon included, yields the space to it and returns when the cue ends.
+
+The cues are visual only. Their sounds arrive as `audio_event` messages the server broadcasts to every player whose area of interest covers the event, so a defeat, an extraction, or a level gained sounds the same for everyone in reach. The client plays the id through the map's audio bindings.
+
+Item slots badge an object layer with the `stack` icon and its signed stat sum, red when negative.
+
+The server sends six values in canonical order. The client displays these values and uses the supplied movement speed.
+
 ## Build and run
 
 ```bash
 cd cyberia-client
 
-# Development build (defaults: BUILD_MODE=DEBUG, localhost URLs)
+# Development build (BUILD_MODE=DEBUG, localhost websocket URL)
 make -f Web.mk clean && make -f Web.mk all
 
-# Release build — pass the production URLs explicitly (see note below)
-make -f Web.mk clean && make -f Web.mk all BUILD_MODE=RELEASE \
-    WS_URL=wss://server.cyberiaonline.com/ws \
-    API_BASE=https://www.cyberiaonline.com
-
-# Build + serve locally on dev port :8082 (DEBUG, localhost)
-./dev-server.sh            # or: ./dev-server.sh <port>
+# Release build
+make -f Web.mk clean && make -f Web.mk all BUILD_MODE=RELEASE
 ```
 
-`WS_URL` and `API_BASE` are passed straight through to the compiler — see
-[Compile-time configuration](#compile-time-configuration). When omitted they
-default to `localhost`, so **production build pipelines must pass real URLs**.
+`BUILD_MODE` picks the websocket URL baked into the WASM — see
+[Compile-time configuration](#compile-time-configuration). The Data Server URL
+is not a build argument: the client reads it from its own command line at
+startup.
 
 The build is part of the Underpost Platform static + PWA pipeline; production deploys go through `underpost client` and `underpost deploy`.
 
@@ -300,23 +322,23 @@ bin/
 
 ## Compile-time configuration
 
-### Server URLs (build arguments)
+### Server URLs
 
-`WS_URL` and `API_BASE` are `make` arguments baked into the WASM as
-`-DWS_URL_OVERRIDE` / `-DAPI_BASE_URL_OVERRIDE`. There is **no** RELEASE/DEBUG URL
-switch — both default to `localhost` regardless of `BUILD_MODE`:
+`WS_URL` in `src/config.h` holds both websocket endpoints. `BUILD_MODE` picks
+one: DEBUG takes `ws://localhost:8081/ws`, RELEASE takes
+`wss://server.cyberiaonline.com/ws`. `window.CYBERIA_WS_ORIGIN`, injected by
+`wasm-driver.py`, overrides it at runtime.
 
-| make argument | Default                  | Baked macro             |
-| ------------- | ------------------------ | ----------------------- |
-| `WS_URL`      | `ws://localhost:8081/ws` | `WS_URL_OVERRIDE`       |
-| `API_BASE`    | `http://localhost:4005`  | `API_BASE_URL_OVERRIDE` |
+The Data Server URL is a command line argument, not a build argument:
+
+```
+wasm-driver.py --data-server-url=<origin>
+  -> window.CYBERIA_ARGV -> Module.arguments -> main(argc, argv)
+```
 
-> **Production pipelines must pass the URLs.** `BUILD_MODE=RELEASE` alone still
-> yields `localhost`. Any release build — the Docker image build, CI, manual
-> release — must pass `WS_URL=wss://… API_BASE=https://…` as make arguments
-> (or Docker build-args wired through to `make`), or the client ships pointing
-> at localhost. If unset, `src/config.h` falls back to bare `"ws://"` /
-> `"https://"` stubs.
+`config_init()` reads `--data-server-url=<origin>` from `argv`. The argument is
+required: the client asserts and stops if it is absent. There is no environment
+fallback, no config file and no runtime override.
 
 ### Constants (`src/config.h`)
 

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

@@ -100,11 +100,11 @@ security presence, taxes, historical scars — never the subject.
 To make a faction the **central driver** of the saga, name one or more with
 `--faction-context` (comma-separated). Valid keys:
 
-| Key       | Confederation                                  |
-| --------- | ---------------------------------------------- |
-| `zenith`  | the Zenith Empire (Red)                        |
-| `nova`    | the Nova Republic (Blue)                       |
-| `atlas`   | the Atlas Confederation (Yellow)               |
+| Key       | Confederation                                    |
+| --------- | ------------------------------------------------ |
+| `zenith`  | the Zenith Empire (Red)                          |
+| `nova`    | the Nova Republic (Blue)                         |
+| `atlas`   | the Atlas Confederation (Yellow)                 |
 | `neutral` | unaligned independent enclaves / neutral parties |
 
 ```bash
@@ -133,23 +133,23 @@ Two optional flags steer it; **both default to random** when unset:
   from (unset → a random non-empty subset, so runs vary their cultural mix).
   Unknown keys warn and are skipped. Valid keys:
 
-  | Key | Flavor |
-  | --- | ------ |
-  | `low_level_synthetics` | serialized / technical utility-frame designations |
-  | `high_fidelity_synthetics` | refined, near-human synthetic names |
-  | `global_latin_diaspora` | Latin / Iberian-descended |
-  | `east_asian_pacific_diaspora` | East-Asian / Pacific-descended |
-  | `middle_eastern_turkish_diaspora` | Middle-Eastern / Turkish-descended |
-  | `sub_saharan_african_diaspora` | Sub-Saharan African-descended |
-  | `classic_western_scifi` | gritty Anglo operators / enforcers |
-  | `mutagen_clans` | organic, mutation-flavored clan names |
+  | Key                               | Flavor                                            |
+  | --------------------------------- | ------------------------------------------------- |
+  | `low_level_synthetics`            | serialized / technical utility-frame designations |
+  | `high_fidelity_synthetics`        | refined, near-human synthetic names               |
+  | `global_latin_diaspora`           | Latin / Iberian-descended                         |
+  | `east_asian_pacific_diaspora`     | East-Asian / Pacific-descended                    |
+  | `middle_eastern_turkish_diaspora` | Middle-Eastern / Turkish-descended                |
+  | `sub_saharan_african_diaspora`    | Sub-Saharan African-descended                     |
+  | `classic_western_scifi`           | gritty Anglo operators / enforcers                |
+  | `mutagen_clans`                   | organic, mutation-flavored clan names             |
 
 - **`--cultural-exposure <mode>`** — how mixed the population is (unset → random):
 
-  | Mode | Effect |
-  | ---- | ------ |
-  | `cosmopolitan` | heavy mixing, hybrid surnames, intermarriage — maximizes variety |
-  | `local` | isolated clans/enclaves, strong local naming traditions, internally consistent |
+  | Mode           | Effect                                                                         |
+  | -------------- | ------------------------------------------------------------------------------ |
+  | `cosmopolitan` | heavy mixing, hybrid surnames, intermarriage — maximizes variety               |
+  | `local`        | isolated clans/enclaves, strong local naming traditions, internally consistent |
 
 ```bash
 # Latin + East-Asian diaspora names in a highly mixed, cosmopolitan population
@@ -166,26 +166,26 @@ node bin/cyberia.js generate-saga --character-context 'mutagen_clans' --cultural
 The theme commits to one of four broad narrative types — chosen **uniformly
 (~25% each)** unless forced with `--tone`:
 
-| Tone        | Register                                                        |
-| ----------- | -------------------------------------------------------------- |
-| `adventure` | noir high-risk missions: covert ops, sabotage, combat, rogue AI, mystery |
+| Tone        | Register                                                                                                          |
+| ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| `adventure` | noir high-risk missions: covert ops, sabotage, combat, rogue AI, mystery                                          |
 | `politics`  | power & ideology at any scale — councils, clans, enclaves, revolutions (confederation geopolitics only sometimes) |
-| `tragic`    | heartbreaking, intimate: family, bonds, loss, grief            |
-| `comedy`    | everyday absurdity and silliness, played for humor             |
+| `tragic`    | heartbreaking, intimate: family, bonds, loss, grief                                                               |
+| `comedy`    | everyday absurdity and silliness, played for humor                                                                |
 
 #### Spatial context (physical vs. hyperspace)
 
 Cyberia has two equally important layers — the **Physical Layer** (fleets,
 colonies, logistics, force) and the **Hyperspace Layer** (persistent Instances,
-memory-cities, digital ecosystems). Because the lore is titled *The Frontier of
-Hyperspace*, an unconstrained model drifts to hyperspace-only premises. So the
+memory-cities, digital ecosystems). Because the lore is titled _The Frontier of
+Hyperspace_, an unconstrained model drifts to hyperspace-only premises. So the
 auto-theme picks a spatial context **explicitly and uniformly (~33.3% each)**:
 
-| Context      | Premise lives in…                                              |
-| ------------ | -------------------------------------------------------------- |
-| `physical`   | the material frontier only — no hyperspace                     |
-| `mixed`      | the porous interplay where events bleed between both layers    |
-| `hyperspace` | inside the Instances only — not the physical frontier          |
+| Context      | Premise lives in…                                           |
+| ------------ | ----------------------------------------------------------- |
+| `physical`   | the material frontier only — no hyperspace                  |
+| `mixed`      | the porous interplay where events bleed between both layers |
+| `hyperspace` | inside the Instances only — not the physical frontier       |
 
 Force one with `--space-context <physical\|mixed\|hyperspace>`; an invalid value
 warns and falls back to random. This applies to auto-generation only (with
@@ -265,25 +265,25 @@ overwritten and codes are never duplicated.
 
 Options:
 
-| Flag                       | Description                                          |
-| -------------------------- | ---------------------------------------------------- |
-| `--prompt <theme>`         | Theme seed. Omit to auto-generate from the lore.     |
-| `--import <file>`          | Load a generated payload file into the DB.           |
-| `--lore-path <path>`       | Override the base-lore doc (auto-generate mode).     |
-| `--space-context <ctx>`    | Force `physical` \| `mixed` \| `hyperspace` (else random). |
-| `--tone <tone>`            | Force `adventure` \| `politics` \| `tragic` \| `comedy` (else random). |
-| `--faction-context <keys>` | Comma-separated `zenith` \| `nova` \| `atlas` \| `neutral` that DRIVE the theme (else background). |
-| `--character-context <keys>` | Comma-separated `CHARACTER_NAMES_POOL` keys for name inspiration (else random subset). |
-| `--cultural-exposure <mode>` | `cosmopolitan` \| `local` naming-diversity mode (else random). |
-| `--temperature <value>`    | Sampling temperature for every model call (default `1.3`). |
-| `--model <id>`             | Gemini model id (default `gemma-4-26b-a4b-it`).      |
-| `--timeout <ms>`           | Per-request timeout in ms (default `300000`).        |
-| `--thinking-level <level>` | `low` \| `medium` \| `high` (default `high`).        |
-| `--out <file>`             | Payload dump path (default `./engine-private/cyberia-sagas/<saga-code>.json`). |
-| `--dry-run`                | Normalize only; no database writes.                  |
-| `--env-path <path>`        | Env file to load (`GEMINI_API_KEY`, deploy vars).    |
-| `--mongo-host <host>`      | Mongo host override.                                 |
-| `--dev`                    | Force the development environment.                  |
+| Flag                         | Description                                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `--prompt <theme>`           | Theme seed. Omit to auto-generate from the lore.                                                   |
+| `--import <file>`            | Load a generated payload file into the DB.                                                         |
+| `--lore-path <path>`         | Override the base-lore doc (auto-generate mode).                                                   |
+| `--space-context <ctx>`      | Force `physical` \| `mixed` \| `hyperspace` (else random).                                         |
+| `--tone <tone>`              | Force `adventure` \| `politics` \| `tragic` \| `comedy` (else random).                             |
+| `--faction-context <keys>`   | Comma-separated `zenith` \| `nova` \| `atlas` \| `neutral` that DRIVE the theme (else background). |
+| `--character-context <keys>` | Comma-separated `CHARACTER_NAMES_POOL` keys for name inspiration (else random subset).             |
+| `--cultural-exposure <mode>` | `cosmopolitan` \| `local` naming-diversity mode (else random).                                     |
+| `--temperature <value>`      | Sampling temperature for every model call (default `1.3`).                                         |
+| `--model <id>`               | Gemini model id (default `gemma-4-26b-a4b-it`).                                                    |
+| `--timeout <ms>`             | Per-request timeout in ms (default `10000`).                                                       |
+| `--thinking-level <level>`   | `low` \| `medium` \| `high` (default `high`).                                                      |
+| `--out <file>`               | Payload dump path (default `./engine-private/cyberia-sagas/<saga-code>.json`).                     |
+| `--dry-run`                  | Normalize only; no database writes.                                                                |
+| `--env-path <path>`          | Env file to load (`GEMINI_API_KEY`, deploy vars).                                                  |
+| `--mongo-host <host>`        | Mongo host override.                                                                               |
+| `--dev`                      | Force the development environment.                                                                 |
 
 `GEMINI_API_KEY` must be available in the environment or the `--env-path` file.
 
@@ -294,8 +294,7 @@ A single JSON object with these interrelated sections:
 - **saga** — `code`, `name`, `description`, `mapCodes[]`, `itemIds[]`, `questCodes[]`.
 - **instance** — the playable `CyberiaInstance` shell derived from the saga
   metadata: `code`, `name`, `description`, `tags[]`, `cyberiaMapCodes[]` (the
-  saga's map codes), `itemIds[]` (`{ id, defaultPlayerInventory }`),
-  `topologyMode`. Spatial topology (`portals`) and the tuning ref (`conf`) are
+  saga's map codes), `topologyMode`. Spatial topology (`portals`) and the tuning ref (`conf`) are
   left empty here and bound by downstream spatial synthesis.
 - **maps[]** — narrative zones the quest chain visits: `code`, `name`,
   `description` (text only — grid/cells/entities stay at schema defaults). Their
@@ -338,7 +337,7 @@ normalization slugifies every code/id so they line up:
   minimal `skill`-type item for any summoned id the model omitted;
 - `saga.questCodes` / `saga.itemIds` are reconciled to include every generated
   quest and item (including appended skill items), and `instance.cyberiaMapCodes`
-  / `instance.itemIds` mirror the saga's.
+  mirrors the saga's.
 
 ### `talk` objectives (guaranteed fulfillable)
 

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

@@ -38,7 +38,7 @@ persisted maps + rules                  tick + AOI + snapshots           render
 ```
 
 - Each service is supervised independently and owns its own monitor and reconnector.
-- `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.
+- `cyberia-server` dials the Data Server gRPC at boot; on dial or load failure it retries over the REST boot fallback (`--data-server-url`, `/api/cyberia-instance/boot/*`) and exits only when both transports fail rather than fabricate a world.
 - On reconnect, world configuration is reloaded via `GetFullInstance(instanceCode)`.
 - If any one of the three services is unhealthy, the game moves to standby until all three recover.
 
@@ -232,7 +232,7 @@ Paths are relative to `cyberia-server/`. Gameplay logic lives under `src/`; the
 | `src/economy.go`                                                                                  | Fountain & Sink coin economy                                                                            |
 | `src/life_regen.go`                                                                               | HP regeneration                                                                                         |
 | `src/ai.go`                                                                                       | Bot AI                                                                                                  |
-| `src/stats.go`                                                                                    | Active stat aggregation, sum-stats limit enforcement                                                    |
+| `src/stats.go`                                                                                    | Signed stat aggregation and effective floors                                                            |
 | `src/entity_status.go`                                                                            | Entity Status Indicator (ESI) numeric IDs                                                               |
 | `src/frozen_state.go`                                                                             | FrozenInteractionState                                                                                  |
 | `src/handlers.go`                                                                                 | WebSocket lifecycle, binary uplink decoder, JSON-uplink back-compat adapter                             |
@@ -262,15 +262,20 @@ All content data (ObjectLayer metadata, asset blobs, optional client hints, the
 
 ## Environment
 
-| Variable                          | Default           | Description                                        |
-| --------------------------------- | ----------------- | -------------------------------------------------- |
-| `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | engine-cyberia gRPC address (**required**)         |
-| `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                   |
-| `ENGINE_API_BASE_URL`             | _(empty)_         | Internal engine-cyberia origin (server→engine only) |
-| `ENGINE_PUBLIC_URL`               | _(empty)_         | Client-visible Content Authority origin (forwarded to clients) |
-| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval            |
-| `SERVER_PORT`                     | `8081`            | WebSocket + HTTP listen port                       |
-| `STATIC_DIR`                      | `./public`        | Directory for static WASM client files             |
+Two endpoints are command-line flags, not variables. Both are required, and
+each is const for the life of the process.
+
+| Flag                 | Example                         | Description               |
+| -------------------- | ------------------------------- | ------------------------- |
+| `--data-server-url`  | `https://www.cyberiaonline.com` | Data Server REST origin   |
+| `--data-server-grpc` | `localhost:50051`               | Data Server gRPC endpoint |
+
+| Variable                          | Default      | Description                             |
+| --------------------------------- | ------------ | --------------------------------------- |
+| `INSTANCE_CODE`                   | `default`    | Instance code to load on startup        |
+| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_ | ObjectLayer hot-reload polling interval |
+| `SERVER_PORT`                     | `8081`       | WebSocket + HTTP listen port            |
+| `STATIC_DIR`                      | `./public`   | Directory for static WASM client files  |
 
 ---
 

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

@@ -20,7 +20,7 @@ _Stackable Rendering Layers as a Unified Tokenized Reality_
 <!-- CI/CD and health -->
 <div align="center">
 
-[![Node.js CI](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/docker-image.engine-cyberia.ci.yml?branch=main&label=Node.js%20CI)](https://github.com/underpostnet/engine-cyberia/actions/workflows/docker-image.engine-cyberia.ci.yml) [![Test](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/coverall.cyberia.ci.yml?branch=main&label=Test)](https://github.com/underpostnet/engine-cyberia/actions/workflows/coverall.cyberia.ci.yml) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine-cyberia/badge.svg?branch=main)](https://coveralls.io/github/underpostnet/engine-cyberia?branch=main) [![Socket Badge](https://socket.dev/api/badge/npm/package/cyberia/3.3.73)](https://socket.dev/npm/package/cyberia/overview/3.3.73)
+[![Node.js CI](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/docker-image.engine-cyberia.ci.yml?branch=main&label=Node.js%20CI)](https://github.com/underpostnet/engine-cyberia/actions/workflows/docker-image.engine-cyberia.ci.yml) [![Test](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/coverall.cyberia.ci.yml?branch=main&label=Test)](https://github.com/underpostnet/engine-cyberia/actions/workflows/coverall.cyberia.ci.yml) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine-cyberia/badge.svg?branch=main)](https://coveralls.io/github/underpostnet/engine-cyberia?branch=main) [![Socket Badge](https://socket.dev/api/badge/npm/package/cyberia/3.3.77)](https://socket.dev/npm/package/cyberia/overview/3.3.77)
 
 </div>
 
@@ -45,26 +45,26 @@ Go server and the WASM client with data — it does not run the simulation or th
 
 ```text
                          ┌───────────────────────────────────────────────┐
-                         │              UNDERPOST PLATFORM                 │
-                         │  toolchain · deploy · PWA build · static        │
-                         │  delivery · cluster/image/db · monitoring       │
-                         │                                                 │
-                         │   underpost CLI  ──▶  builds & deploys all      │
+                         │              UNDERPOST PLATFORM               │
+                         │  toolchain · deploy · PWA build · static      │
+                         │  delivery · cluster/image/db · monitoring     │
+                         │                                               │
+                         │   underpost CLI  ──▶  builds & deploys all    │
                          └───────────────────────────────────────────────┘
                                             │  hosts / delivers
                                             ▼
-   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
+   ╔═══════════════════════════════ CYBERIA MMO ═══════════════════════════════════╗
    ║                                                                               ║
-   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
-   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
-   ║   │     (Node.js)    │           │       (Go)       │            │           ║
-   ║   │                  │           │                  │            ▼           ║
-   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
-   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
-   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
-   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
-   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
-   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
+   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket             ║
+   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐            ║
+   ║   │     (Node.js)    │           │       (Go)       │            │            ║
+   ║   │                  │           │                  │            ▼            ║
+   ║   │ content          │           │ authoritative    │    ┌──────────────────┐ ║
+   ║   │ validation       │           │ simulation       │    │  cyberia-client  │ ║
+   ║   │ persistence      │           │ world tick       │    │    (C / WASM)    │ ║
+   ║   │ gRPC/REST data   │           │ AOI replication  │    │                  │ ║
+   ║   │ asset metadata   │           │                  │    │ rendering        │ ║
+   ║   └──────────────────┘           └──────────────────┘    │ input            │ ║
    ║            │                                             │ prediction       │ ║
    ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
    ║                                                          └──────────────────┘ ║
@@ -157,17 +157,17 @@ Three supervised processes run in parallel, each with its own monitor and reconn
 
 ```text
         ┌──────────────────────────────────────────────────────────────┐
-        │                    SUPERVISION (parallel)                      │
-        │                                                                │
-        │   engine-cyberia        cyberia-server        cyberia-client   │
-        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
-        │   │  monitor   │        │  monitor   │        │  monitor   │   │
-        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
-        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
-        │         │                     │                     │          │
-        │         └──────────┬──────────┴──────────┬──────────┘          │
-        │                    ▼                     ▼                     │
-        │            all three up & connected?                          │
+        │                    SUPERVISION (parallel)                    │
+        │                                                              │
+        │   engine-cyberia        cyberia-server        cyberia-client │
+        │   ┌────────────┐        ┌────────────┐        ┌────────────┐ │
+        │   │  monitor   │        │  monitor   │        │  monitor   │ │
+        │   │ +reconnect │        │ +reconnect │        │ +reconnect │ │
+        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘ │
+        │         │                     │                     │        │
+        │         └──────────┬──────────┴──────────┬──────────┘        │
+        │                    ▼                     ▼                   │
+        │            all three up & connected?                         │
         └────────────────────────────┬─────────────────────────────────┘
                                       │
                 ┌─────────────────────┼─────────────────────┐

package/src/client/public/cyberia-docs/ENTITY-PROFILE.md

@@ -70,7 +70,7 @@ type PlayerState struct {
     FreezeReason      string             // "dialogue" | "inventory" | ...
     Path              []PointI           // A* path (for smooth movement)
     AOI               Rectangle          // current area-of-interest bounds
-    SumStatsLimit     int                // max aggregate stat sum (equipment rules)
+    Progression       EntityProgression  // level, total XP, and progression freeze
 }
 ```
 
@@ -131,13 +131,19 @@ z-order  type
 
 ## Stat Aggregation
 
-Stats are aggregated across all **active** Object Layers on an entity. The server enforces a `sumStatsLimit` — the maximum sum of all stat values allowed for the player. Attempting to equip items that would exceed this limit is rejected.
+Players, bots, NPCs, and resources share the same progression and stat module.
+Bots, NPCs, and resources have frozen XP. Their authored level selects the same base curve as players.
 
-**Active stats sum:**
+```text
+Effective = max(floor, Base(Level) + ActiveOL + Temporary)
+```
 
-$$\text{activeStatsSum} = \sum_{\text{active layers}} (\text{effect} + \text{resistance} + \text{agility} + \text{range} + \text{intelligence} + \text{utility})$$
+Each active layer with positive quantity contributes once. Each OL stat is an integer in `[-100, +100]`.
+The server applies floors after the full sum. Equipment rules control active slots and item types.
 
-The `sumStatsLimit` and `activeStatsSum` are sent to the client on each AOI update so the inventory UI can show remaining equip budget.
+The self snapshot carries `level`, `xp`, `levelXp`, `nextLevelXp`, and four stat arrays.
+Other living entities carry `level` and `effectiveStats`. `statsSum` is an uncapped display summary.
+The overhead HUD and the Stats tab display the server values. XP and level never belong to `data.stats`.
 
 ---
 

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

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