@underpostnet/cyberia 3.3.73 → 3.3.76

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.76)](https://socket.dev/npm/package/cyberia/overview/3.3.76)
 
 </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.76 | **Target milestone:** Open Alpha
 
 ---
 

package/src/client/public/cyberia-docs/STATS-PROGRESSION.md

@@ -0,0 +1,217 @@
+# Cyberia stats and entity progression
+
+The Go server owns effective stats, XP, and level changes.
+The engine owns authored content, configuration, validation, and persistence.
+The client displays server state. The CLI validates content and generates shared contracts.
+
+## Canonical contract
+
+`src/client/components/cyberia/SharedDefaultsCyberia.js` defines the stat order, descriptions, modifier bounds, defaults, effective floors, and what one point is worth. The generated contract carries the scales to the server, so the simulation and the documentation read one table.
+
+| Index | Stat | One point | Effective floor |
+| --- | --- | --- | ---: |
+| 0 | `effect` | Removes one life point per hit | 1 |
+| 1 | `resistance` | Adds one point of maximum life and a tenth of a point to each regeneration | 0 |
+| 2 | `agility` | Adds one percent of base movement speed | -90 |
+| 3 | `range` | Adds fifty milliseconds of summon lifetime | 0 |
+| 4 | `intelligence` | Adds five percentage points of summon chance | 0 |
+| 5 | `utility` | Removes one percent of base cooldown and adds one percentage point of regeneration chance | 0 |
+
+Chances are fractions of one. A tap regenerates with `lifeRegenChance` (default 0.15) plus utility; a skill summons with its `skillRules` chance (projectile 0.75, doppelganger 0.6) plus intelligence. No chance the stats raise passes `maxChance` (default 0.95), so nothing becomes a certainty. Regeneration heals the entity's own base amount plus a tenth of a point per resistance point, never past its maximum.
+
+Each OL modifier is an integer from `-100` through `+100`. Zero is neutral.
+Missing stat keys resolve to zero. Unknown keys, fractions, numeric strings, null values, and values outside the bounds fail validation.
+An OL cannot store XP or level in `data.stats`.
+
+The editor marks negative values as penalties and positive values as bonuses.
+The randomizer validates its bounds and uses the full signed range by default.
+
+## Semantic bounds and balancing
+
+`STAT_TYPE_BOUNDS` in the same module declares the inclusive range each stat may take per item type. A weapon deals its effect and can cost resistance; a skin and a breastplate defend; a skill reaches; world content carries nothing. A type or stat absent there keeps the contract range.
+
+| Type | effect | resistance | agility | range | intelligence | utility |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `weapon` | 5..20 | -10..2 | -5..5 | 0..10 | 0..5 | 0..10 |
+| `skin` | 1 | 0..20 | -5..10 | 0 | 0..2 | 0..5 |
+| `breastplate` | 0 | 5..30 | -15..0 | 0 | 0..3 | 0..5 |
+| `skill` | 0..15 | 0..5 | 0..5 | 5..30 | 0..10 | 0..10 |
+| `resource` | 0 | 0..10 | 0 | 0 | 0 | 0 |
+| world content | 0 | 0 | 0 | 0 | 0 | 0 |
+
+`src/projects/cyberia/stat-balance.js` applies one policy to every object layer the `ol` command writes: import, batch import, generation, atlas rebuilds, and the minify refresh. `--normalize-stats` clamps the stats the content carries into its type's range. `--random-stats` draws every stat inside the range instead. `--min-stat` and `--max-stat` narrow the range; a request that leaves no overlap pins the stat to the semantic edge nearest it. The policy is a pure function of the content and the flags, so a run is deterministic and normalizing is idempotent.
+
+## Aggregation and levels
+
+```text
+BaseStat(level) = baseStats[stat] + (level - 1) * perLevelStats[stat]
+EffectiveStat = max(floor, BaseStat(level) + ActiveOLStat + TemporaryStat)
+TotalXPForLevel(level) = xpPerLevel * (level - 1)^2
+```
+
+Each active OL with positive quantity contributes once. Stack quantity does not multiply its modifier.
+The server applies floors after the full sum. Effective values can exceed the OL bounds.
+Equipment rules still control item types, active slots, and required skins.
+
+Players, bots, NPCs, and resources share `EntityProgression`, the base curve, and stat aggregation.
+Bots, NPCs, and resources have frozen progression. Their content `level` selects the base stats.
+An absent content level uses `defaultBotLevel`. New players start at level 1 with zero XP.
+Terrain and other passive objects carry no progression state.
+
+Summoned entities inherit the caster's base and signed contributions, then add their own contributions.
+The server applies floors after inheritance. A caster cycle stops traversal.
+Temporary modifiers have an ID and expiry time. Setting the same ID replaces that modifier.
+The lifecycle phase removes expired modifiers and updates maximum life.
+
+The agility floor retains at least 10% of configured movement speed.
+The existing minimum action cooldown still applies. Resistance keeps maximum life and regeneration nonnegative.
+Increasing maximum life does not grant an instant heal.
+
+## Server configuration
+
+`src/api/cyberia-server-defaults/cyberia-server-defaults.js` owns progression defaults and configuration limits.
+Instance content can override `progressionRules`. Partial curves inherit missing defaults.
+The engine resolves and validates the complete configuration before transport.
+
+| Setting | Default |
+| --- | ---: |
+| `maxLevel` | 100 |
+| `xpPerLevel` | 100 |
+| `defaultBotLevel` | 1 |
+| `killXp` | 25 |
+| `objectiveXp` | 10 |
+| `questXp` | 100 |
+| `minAwardIntervalMs` | 500 |
+| `repeatWindowMs` | 60000 |
+| `maxRepeatAwards` | 4 |
+| `maxAwardsPerWindow` | 30 |
+
+The default base array is `[5, 10, 0, 0, 0, 0]`.
+The default growth array is `[2, 5, 1, 10, 1, 1]`.
+The first total XP thresholds are `0`, `100`, `400`, and `900`.
+One reward can advance several levels. XP stops at the maximum level threshold.
+
+Authored levels must be integers from 1 through 65535 and cannot exceed the instance maximum.
+Base and growth fields must be integers from 0 through 100.
+The CLI prints the current defaults with `node bin/cyberia.js stats progression`.
+
+Configuration participates in the instance version hash.
+The server validates stat bounds, curves, and authored levels before a full reload mutates state.
+An invalid reload retains its pending version so a corrected payload can retry.
+On a curve change, player XP selects the level under the new curve. The new maximum clamps XP.
+
+## XP rules
+
+Only resolved simulation events can award XP:
+
+- A player or bot defeat can award kill XP.
+- A resource defeat can award objective XP.
+- A completed quest can award quest XP once per quest code and session.
+
+A combat contributor must supply at least 10% of recorded positive damage.
+Self kills, summoned targets, item drops, providers, ghosts, and frozen players cannot produce eligible defeat rewards.
+Bots and NPCs cannot gain XP.
+
+Low-value outcomes share an award interval and a window limit.
+Repeated rewards for the same event kind and target divide by `1`, `2`, `3`, then `4`.
+Further repeats in that window award zero. Lower-level targets reduce the reward again.
+Integer division rounds down. Zero rewards do not consume an award slot.
+
+Unique quest completion bypasses the low-value interval and window limit.
+This permits a final kill and its quest completion to award XP in the same tick.
+Quest completion still rejects repeats.
+
+Raw taps, idle duration, inventory changes, and currency transfers award no XP.
+Player skills and tap regeneration share the server action cooldown. Movement input remains independent.
+
+## API and Object Layer specification
+
+An Object Layer record stores its contract marker outside hashed metadata. The model stamps it on every write:
+
+```json
+{
+  "statContractVersion": 2,
+  "data": {
+    "stats": {
+      "effect": -100,
+      "resistance": 100,
+      "agility": 0,
+      "range": 0,
+      "intelligence": 0,
+      "utility": 0
+    }
+  }
+}
+```
+
+This fragment omits the existing required item, ledger, and asset fields.
+The OL API, import path, generator, and boot assembler use the shared validator.
+Mongo schema validation also enforces integer bounds. API updates run validators.
+
+Entity content stores optional `level` beside `entityType` and `objectLayerItemIds`.
+The map editor preserves this field and accepts an optional level. An empty input uses the instance default.
+`InstanceConfig.progressionRules` carries the resolved server rules over gRPC and REST. Protobuf field 24 is reserved.
+
+The game link uses JSON envelopes over WebSocket. AOI stat arrays use canonical order.
+
+| Snapshot scope | Fields |
+| --- | --- |
+| Living entities | `level`, `effectiveStats[6]`, `statsSum` |
+| Viewing player only | `xp`, `levelXp`, `nextLevelXp`, `baseStats[6]`, `layerStats[6]`, `temporaryStats[6]` |
+
+`xp` is total XP. `levelXp` and `nextLevelXp` are the thresholds that bound the current level, so the client draws in-level progress without the curve. At maximum level, all three equal the final threshold.
+`statsSum` is an uncapped display summary, not an equipment budget.
+Passive objects omit `level` and `effectiveStats`. Other players do not receive private XP or base-stat breakdowns.
+The instance-map REST API serves authored topology and capabilities. It does not calculate simulation stats.
+
+An XP award sends a `combat_text` message of kind `xp` to the earner only. Damage and regen kinds stay broadcast to the area of interest.
+
+The overhead HUD of every living entity shows its level, its stats sum, and an XP bar under the HP bar. The bar fills with the viewing player's in-level progress and stays empty for other entities.
+The Stats tab draws one shared stat panel per block. Every entity gets its effective stats; the viewing player also gets OL, base, and temporary values.
+The level-up effect observes authoritative level increments for an entity already in view.
+First exposure, repeated snapshots, and level decreases produce no effect. Reconnect resets effects.
+The server broadcasts the `level-up` audio event to every viewer in reach when a player's level rises, and the `death` audio event on every defeat.
+
+## Progression lifetime
+
+The guest runtime assigns a new UUID for each WebSocket session.
+Progression survives death, respawn, portal travel, and world reload within that session.
+A disconnect or server restart ends that progression state.
+
+Persistent account progression requires an authenticated, stable account binding and an engine-owned persistence contract.
+The simulation server exposes no XP mutation API and stores no progression.
+
+## Generation and verification
+
+Generate contracts after a shared stat or progression-default change:
+
+```sh
+node bin/cyberia.js stat-contract
+node bin/cyberia.js stat-contract --check
+```
+
+The generator writes the Go contract, C header, and REST test fixtures. Do not edit these outputs by hand.
+Regenerate protobuf output with the existing protobuf toolchain when `gen/proto/cyberia.proto` changes.
+
+Inspect and validate content with:
+
+```sh
+node bin/cyberia.js stats progression
+node bin/cyberia.js stats validate /tmp/object-layers.json
+node bin/cyberia.js stats random --min=-100 --max=100
+```
+
+Focused engine tests:
+
+```sh
+node node_modules/vitest/vitest.mjs run test/integration/app/cyberia/cyberia-stats.test.js
+```
+
+Run `go test ./...` from `cyberia-server`. The REST and WebSocket tests need local loopback socket access.
+The tests cover signed bounds, floors, inheritance, expiry, thresholds, static levels, repeat limits, tap spam, and reload rejection.
+Generated REST fixtures and protobuf round trips check the engine/server contract.
+
+Run the native client tests, including the level-up effect, with `cyberia-client/tests/run.sh`.
+
+Build the client with its existing `Web.mk` target and Emscripten SDK.
+The SDK needs Python 3.10 or later and a writable cache.

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

@@ -18,7 +18,7 @@ _Stackable Rendering Layers as a Unified Tokenized Reality_
 
 ---
 
-**Version:** 3.3.73 | **Status:** Draft | **Authors:** Underpost Engineering
+**Version:** 3.3.76 | **Status:** Draft | **Authors:** Underpost Engineering
 
 ---
 
@@ -208,18 +208,26 @@ The `ObjectLayerToken` contract maps each `tokenId` → canonical `cid` on-chain
 
 ### 4.4 Canonical Stats Schema
 
-Stats govern mechanical behavior across all game systems (combat, movement, skills, drops):
+Each Object Layer contributes six signed integer modifiers in `[-100, +100]`. Zero is neutral.
+The canonical source is `SharedDefaultsCyberia.js`.
 
-```
-Stats {
-  effect:       int  // damage output / skill power
-  resistance:   int  // damage reduction
-  agility:      int  // movement speed modifier
-  range:        int  // attack / interaction range
-  intelligence: int  // skill cooldown / mana modifier
-  utility:      int  // general-purpose utility bonus
-}
-```
+| Stat           | Runtime meaning                                                       |
+| -------------- | --------------------------------------------------------------------- |
+| `effect`       | Life removed by an impact                                             |
+| `resistance`   | Maximum life bonus and life restored by regeneration                  |
+| `agility`      | Movement speed percentage modifier                                    |
+| `range`        | Summoned entity lifetime in milliseconds                              |
+| `intelligence` | Summon success chance modifier                                        |
+| `utility`      | Action cooldown percentage reduction and regeneration chance modifier |
+
+The server adds base stats at the entity level, active OL contributions, and temporary modifiers.
+It applies playable floors after this sum. Players, bots, NPCs, and resources use the same calculation.
+Bots and NPCs use assigned levels with frozen XP.
+
+XP belongs to entity progression. Resolved kills, resource defeats, and quest completions can award XP.
+Cooldowns, contribution checks, repeat limits, and rate limits restrict rewards. Raw taps and idle time award no XP.
+
+The current guest runtime keeps progression for one connected session.
 
 ### 4.5 Item Type Registry