@underpostnet/cyberia 3.2.80

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

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

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

@@ -0,0 +1,341 @@
+<p align="center">
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA online"/>
+</p>
+
+<div align="center">
+
+<h1>cyberia client</h1>
+
+</div>
+
+**Path:** `cyberia-client/` · **Language:** C11/GNU11 → WebAssembly (Emscripten) · **Role:** presentation runtime for Cyberia
+
+`cyberia-client` is the rendering and interactive runtime for the Cyberia MMO extension on Underpost Platform. It captures input, predicts the local player, reconciles against authoritative snapshots, interpolates remote entities, and renders the world. It owns the render policy locally.
+
+It is **not** a world-simulation authority. The authoritative simulation runs on `cyberia-server`. Persistent content and asset metadata come from `engine-cyberia` via REST.
+
+---
+
+## Operating model
+
+Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
+
+```text
+engine-cyberia          cyberia-server          cyberia-client
+content authority       simulation authority    presentation runtime
+  ^ REST                  | WebSocket binary
+  | atlases, asset        | snapshots  (server -> client)
+  | metadata, optional    | input cmds (client -> server)
+  | client hints          v
+  `---------------- Browser tab: prediction, reconciliation, interpolation, render
+```
+
+- Each service owns its own monitor and reconnector.
+- The client reconnects to `cyberia-server` over WebSocket and fetches content from `engine-cyberia` over REST.
+- If any of the three services is unhealthy, the game moves to standby until all three recover.
+
+The client speaks two transports:
+
+- **WebSocket binary** to `cyberia-server` for snapshots and input commands
+- **REST** to `engine-cyberia` for atlas frames, asset blobs, and optional client-hints overrides
+
+Asset distribution flows through Underpost Platform's static and PWA pipeline.
+
+---
+
+## Render loop
+
+The render loop runs at vsync. Tick simulation is decoupled from render frames via a fixed-timestep accumulator. Step ordering inside one render frame:
+
+1. **Optional client hints poll** — advance the asynchronous hints fetch state machine.
+2. **Input capture** — drain raw OS events.
+3. **Input dispatch** — UI hit-test → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
+4. **Reconciliation** — apply latest snapshot's `lastAcked`: drop acknowledged input commands from the replay buffer; rewind predicted self to authoritative position; replay unacked input commands.
+5. **Fixed-timestep prediction** — while accumulator ≥ `tickDuration`, advance prediction one tick.
+6. **Interpolation** — compute remote-entity view positions at `renderTick = serverTickEstimate − INTERP_TICKS`.
+7. **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.
+
+---
+
+## Module map
+
+Directional dependency: from outermost (UI / render) inward toward `domain/`. Nothing in `domain/` imports outward.
+
+```
+src/
+  domain/
+    tick.h                          tick rate constants, monotonic types
+    presentation_runtime.{c,h}      sole owner of presentation: async fetch of
+                                    /api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE,
+                                    palette/status-icon/camera accessors, tiny
+                                    inline bootstrap fallback
+  input/
+    input_command.{c,h}             typed InputCommand factory; sequence allocation
+  prediction/
+    prediction.{c,h}                predicted self position; replay buffer; reconcile
+  interpolation/
+    interpolation.{c,h}             remote entity view positions at renderTick
+  network/
+    session.{c,h}                   last server tick, last acked sequence, tick estimate
+    client.{c,h}                    WebSocket lifecycle + binary I/O
+    socket.{c,h}                    Emscripten WebSocket bridge
+  ui/                               modals, HUD, inventory bar, FCT, nameplates
+  game_state.{c,h}                  world state mirror (gameplay subset only)
+  binary_aoi_decoder.{c,h}          server snapshot parser
+  game_render.{c,h}, render.{c,h}   render pipeline
+  main.c                            entry point + render loop
+  js/services.{js,c,h}              REST fetch bridge (atlas, ui-icons, client-hints)
+```
+
+| Owner                         | Owns                                                                                                                                                              | Reads                                          | Writes                                                                                          |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `domain/presentation_runtime` | the entire presentation surface (palette, entity colour keys, status icons, camera, cell, interpolation). Inline bootstrap fallback while the fetch is in flight. | JSON response from `/api/cyberia-client-hints` | own table + one-shot hydration of `g_game_state.cell_size`, `.interpolation_ms`, `.camera.zoom` |
+| `input/input_command`         | typed InputCommand factory                                                                                                                                        | session for tick + sequence                    | —                                                                                               |
+| `prediction/`                 | predicted self position, input replay buffer                                                                                                                      | snapshot self + session ack                    | predicted self                                                                                  |
+| `interpolation/`              | remote entity `interp_pos`                                                                                                                                        | snapshot history                               | remote `interp_pos` only                                                                        |
+| `network/session`             | last server tick, last acked sequence                                                                                                                             | snapshot header                                | session singletons                                                                              |
+| `binary_aoi_decoder`          | wire parser                                                                                                                                                       | binary frames                                  | `game_state` + session + prediction (via callback)                                              |
+| `game_state`                  | gameplay world mirror                                                                                                                                             | —                                              | —                                                                                               |
+| `render/`, `ui/`              | rendering                                                                                                                                                         | view models                                    | screen                                                                                          |
+
+`game_state` holds only the gameplay subset of world state (entities, positions, life, AOI, equipment, frozen flag, coins). It does not carry palette state, status-icon visuals, or any other presentation field.
+
+---
+
+## Presentation ownership
+
+The client owns its render policy. The authoritative server holds no presentation state.
+
+Three layers, strictly inward-dependent:
+
+1. **`domain/presentation_runtime.{c,h}`** — sole owner of every presentation value. Fires a single asynchronous GET against `/api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE` at startup, polled once per render frame. When the response settles, parses palette, entity colour keys, status-icon visuals, and camera/cell tunings into a process-local table and writes a one-shot hydration into `g_game_state` (cell_size, interpolation_ms, camera.zoom). The C client carries NO compile-time palette or status table — only a tiny inline neutral-grey bootstrap so the splash screen has something to draw while the fetch is in flight. The canonical schema for the response lives at engine-cyberia's `src/client/components/cyberia/SharedDefaultsCyberia.js`.
+2. **Renderers** — call `presentation_runtime_palette("KEY")`, `presentation_runtime_status_icon(u8)`, `presentation_runtime_status_border(u8)`, `presentation_runtime_entity_fallback_color(entity_type)` at each use site.
+
+What lives in this layer:
+
+- Named palette (colors).
+- Per-entity-type fallback color keys.
+- Status-icon visual table (icon stem + border color per numeric ID).
+- Camera smoothing / zoom defaults.
+- Interpolation window.
+- Dev-overlay flag.
+- Viewport screen factors.
+
+What does **not** travel on the WebSocket init or AOI streams:
+
+- Palette.
+- Camera knobs.
+- Dev-overlay flag.
+- Interpolation window.
+- Status-icon visuals.
+- Per-entity-type color keys.
+
+The numeric status-icon u8 still rides on the AOI wire — that is the protocol-level half. The icon stem and border color are presentation and are resolved entirely on the client.
+
+### Optional client hints
+
+`GET /api/cyberia-client-hints/:instanceCode` (engine-cyberia REST, **not** cyberia-server) returns a JSON document mirroring the structure of the compile-time defaults. The client is required to function with no successful call to this endpoint:
+
+- 200 with `{ palette, entityColorKeys, statusIcons, cameraSmoothing, cameraZoom, defaultWidthScreenFactor, defaultHeightScreenFactor, interpolationMs, devUi }` — overrides applied on top of defaults.
+- 404 if the instance has no overrides — defaults are used.
+- Network error — defaults are used.
+
+No authentication; presentation hints are not secret. The Go authoritative server never calls this endpoint.
+
+---
+
+## Tick-aware components
+
+### Session
+
+`network/session.{c,h}` tracks per-connection tick state:
+
+- `last_server_tick` — highest snapshot tick observed.
+- `last_acked_input_sequence` — highest sequence the server has applied for this client; echoed in every snapshot header.
+- `next_input_sequence` — monotonic counter for outgoing input commands.
+- `server_tick_estimate` — extrapolation of last server tick by elapsed wall time, used to stamp outgoing input commands and to compute `renderTick`.
+
+### Prediction
+
+`prediction/prediction.{c,h}` owns the predicted self position. It is the only writer of the predicted state. Internally it tracks **two** positions: the discrete per-tick `predicted_pos` (where the simulation says the player is) and the continuous render-frame `display_pos` (what the renderer reads). The renderer never sees the discrete value.
+
+- `prediction_apply(cmd)` — optimistic local apply of an input command + push onto replay buffer.
+- `prediction_step(dt)` — fixed-timestep advance, called by the accumulator. Mutates `predicted_pos` only.
+- `prediction_reconcile()` — on snapshot arrival: drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs. Mutates `predicted_pos` only.
+- `prediction_display_step(frame_dt)` — per-render-frame exponential lerp of `display_pos` toward `predicted_pos`. This is the layer that absorbs reconcile snaps and sim-tick stepping so the visible main player moves continuously.
+- `prediction_self_position()` — render-time accessor; returns the smoothed `display_pos`.
+
+### Interpolation
+
+`interpolation/interpolation.{c,h}` owns remote-entity render-time positions. It is the only writer of remote `interp_pos`. It never touches the local player (prediction owns that). Sampling happens at `renderTick = serverTickEstimate − INTERP_TICKS`.
+
+### Input command pipeline
+
+```
+mouse / touch / keyboard
+        │
+        ▼
+input/input_capture
+        │
+        ▼
+UI hit-test cascade  ──► modal/inventory/HUD consumed?
+        │  no
+        ▼
+input_command_build_*   stamps client_tick + sequence
+        │
+        ▼
+prediction_apply        optimistic local apply
+        │
+        ▼
+uplink send             WebSocket binary frame
+```
+
+`InputCommand.Sequence` is allocated by `session_next_input_sequence`. Monotonic, never reused. The server echoes the highest applied sequence in every snapshot header; the prediction module drops acked commands from its replay buffer on reconciliation.
+
+---
+
+## Binary AOI snapshot format
+
+The client decodes server-pushed AOI frames. Header (little-endian, 11 bytes for `0x01`/`0x03`):
+
+```
+[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 client
+[9..10]  u16  entityCount entity blocks that follow
+```
+
+After parsing the header, the decoder invokes `session_on_snapshot(tick, lastAcked)` and then `prediction_reconcile()` so the predicted self stays consistent with the just-arrived authoritative state.
+
+Other message types — init data (0x02), FCT (0x04), ItemFCT (0x05) — carry their own headers and are not part of the per-tick replication stream.
+
+---
+
+## REST fetches (engine-cyberia)
+
+The client speaks REST directly to engine-cyberia for content. None of these calls go through cyberia-server.
+
+| 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/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                           |
+| `GET /api/cyberia-client-hints/:instanceCode`                  | Optional presentation overrides            |
+| `GET /api/cyberia-instance/instance-map/:instanceCode/static`  | Instance Map graph (nodes, edges, POIs)    |
+| `GET /api/cyberia-instance/instance-map/:instanceCode/dynamic` | Instance Map provider activity (~1/s poll) |
+
+All requests are CORS-simple GETs (no preflight) and cacheable. None require credentials.
+
+---
+
+## Instance Map
+
+The Instance Map is a strategic overlay, not a minimap. It visualises the instance as a packed, gapless grid of map cards with animated portal edges, for navigation and planning. It never reproduces the gameplay viewport.
+
+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.
+- **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).
+
+Strict independence from the gameplay renderer:
+
+| Concern    | Owner                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------- |
+| Graph data | `ui/instance_map_data` — engine-cyberia REST only, never the AOI stream                |
+| Camera     | own pan/zoom with smooth exponential interpolation (drag pan, wheel zoom, pinch zoom)  |
+| Layout     | deterministic row-major map-card grid with quarter-turn rotation, computed client-side |
+| Selection  | tap a node → contextual panel (name, quest/action provider counts, portal links)       |
+
+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.
+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.
+
+---
+
+## Build and run
+
+```bash
+cd cyberia-client
+
+# Development build (defaults: BUILD_MODE=DEBUG, localhost URLs)
+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>
+```
+
+`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**.
+
+The build is part of the Underpost Platform static + PWA pipeline; production deploys go through `underpost client` and `underpost deploy`.
+
+### Output
+
+```
+bin/
+  index.html    — Emscripten HTML container (from shell.html template)
+  index.wasm    — Compiled WebAssembly module
+  index.js      — Emscripten JS glue
+  index.data    — Preloaded data bundle
+```
+
+---
+
+## Compile-time configuration
+
+### Server URLs (build arguments)
+
+`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`:
+
+| make argument | Default                  | Baked macro             |
+| ------------- | ------------------------ | ----------------------- |
+| `WS_URL`      | `ws://localhost:8081/ws` | `WS_URL_OVERRIDE`       |
+| `API_BASE`    | `http://localhost:4005`  | `API_BASE_URL_OVERRIDE` |
+
+> **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.
+
+### Constants (`src/config.h`)
+
+| Constant                    | Default        | Description                                                                                                      |
+| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `CYBERIA_CLIENT_HINTS_CODE` | `cyberia-main` | Lookup key for the optional client-hints fetch (presentation override key — never an instance/server identifier) |
+| `MAX_TEXTURE_CACHE_SIZE`    | `512`          | Atlas texture LRU cap                                                                                            |
+| `MAX_LAYER_CACHE_SIZE`      | `256`          | ObjectLayer metadata LRU cap                                                                                     |
+| `MAX_ATLAS_CACHE_SIZE`      | `256`          | Atlas metadata LRU cap                                                                                           |
+| `DEFAULT_FRAME_DURATION_MS` | `100`          | Default animation frame duration                                                                                 |
+
+---
+
+## Persistent storage
+
+`serial.c` uses Emscripten's IDBFS (IndexedDB File System) at `/persistent/` for:
+
+- Player authentication token (EIP-712 signature).
+- Local game settings (audio volume, key bindings).
+- Cached ObjectLayer metadata (session warm-up cache).
+
+No game state is persisted client-side; the authoritative server is the source of truth.

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

@@ -0,0 +1,84 @@
+# **Cyberia Lore — The Frontier of Hyperspace**
+
+### **Setting: Year 2520+**
+
+Earth is a ruined monument to humanity’s first age. Civilization now stretches across shattered continents, orbital fortresses, lunar citadels, asteroid enclaves, and distant colonies. From the ashes of collapse rose **Cyberia**: a living frontier where the physical world and **Hyperspace** — persistent, evolving Instances — have fused into one unstable reality.
+
+The boundary between flesh and code is porous. Relics, memories, wars, and identities bleed between layers, birthing opportunity, conflict, and legend.
+
+---
+
+### **The Historical Fracture**
+
+The **Pacific Cataclysm** (2045) broke the old world through nuclear fire, ecological collapse, engineered plagues, and runaway experiments. As Earth turned hostile, humanity fled into space and deeper into digital realms. What began as simulations evolved into enduring **Instances**: living archives, simulated empires, memory-cities, and battlegrounds where time and identity bend.
+
+Two new peoples emerged alongside baseline humans:
+
+- **Mutagens**: Radiation- and bio-altered survivors, resilient yet often outcast.
+- **Synthetics**: Artificial minds who claimed autonomy and personhood.
+
+Together they navigate Cyberia’s layered existence.
+
+---
+
+### **The Dual Nature of Cyberia**
+
+Cyberia exists on two overlapping, interdependent layers:
+
+- **Physical Layer**: Brutal, resource-scarce reality of fleets, colonies, infrastructure, and raw power. Slow, unforgiving, ruled by logistics and force.
+- **Hyperspace Layer**: A vast web of persistent Instances — fluid realms of data, memory, and simulated worlds where geography, time, and self are malleable.
+
+Neural links, relics, breaches, and megastructures constantly bridge the layers. Actions in one reshape the other. Even destruction follows this duality.
+
+When an entity suffers catastrophic damage, its manifestation does not truly cease to exist. Instead, it undergoes **Fragmentation**: the coherent structure that defines its presence within the current layer collapses into unstable fragments.
+
+During the **Fragmented State**, the entity remains present only as a cluster of residual fragments suspended at the point of collapse. These fragments represent an incomplete manifestation — neither corpse nor spirit — allowing limited awareness and interface access while the structure attempts to reintegrate or reconstruct across layers.
+
+---
+
+### **The Three Great Confederations**
+
+#### **Zenith Empire (Red)**
+
+Militaristic and hierarchical. Masters of the **physical layer** — fleets, fortresses, and territorial control.  
+**Core belief**: Order must be imposed through strength.  
+**Strengths**: Discipline, industrial might, projection of force.  
+**Weaknesses**: Rigidity, prejudice against Mutagens, ecological disregard, and dependency on Nova.  
+**Internal divide**: Iron Legion (expansion) vs. Aether Council (technocratic control).  
+**Relations**: Sees Atlas as chaotic; relies on Nova while resenting it.
+
+#### **Atlas Confederation (Yellow)**
+
+Decentralized network of frontier settlements, Mutagen clans, Synthetics, scavengers, hackers, and nomads. Thrives in the unstable **spaces between** layers.  
+**Core strengths**: Adaptation, improvisation, asymmetric warfare, infiltration.  
+**Weakness**: Fragmentation and internal division.  
+**Internal divide**: Harmony Enclaves (coexistence) vs. Void Nomads (radical autonomy).  
+**Relations**: Sabotages Nova, resists Zenith’s rigidity, and dominates black markets and grey zones.
+
+#### **Nova Republic (Blue)**
+
+Technocratic, intelligence-driven civilization that dominates **Hyperspace**. Obsessed with optimization, prediction, cognitive architecture, and transcendence.  
+**Core strength**: Information control, surveillance, predictive systems, and deep integration into digital realms.  
+**Weakness**: Over-integration with Instances has caused gradual erosion of unified identity among its citizens, leading to internal factionalism and decision paralysis.  
+**Internal split**: Singularity Directive (machine supremacy) vs. Transcendent Conclave (hybrid flesh-machine future).  
+**Relations**: Provides critical systems to Zenith; faces constant subversion from Atlas hackers. Sees itself as the guiding intelligence of civilization.
+
+---
+
+### **The Balance of Power**
+
+The three factions maintain a tense, interdependent equilibrium. Zenith holds physical dominance. Nova commands information and digital architecture. Atlas exploits the gaps, thriving on chaos and mobility. They war, trade, ally, and betray — yet none can achieve total control. The frontier is too layered, unpredictable, and alive.
+
+---
+
+### **Your Role as Player**
+
+You are no chosen one — merely a survivor who has endured long enough to matter.
+
+You might be a soldier, relic hunter, Instance diver, smuggler, hacker, mercenary, diplomat, or rogue Synthetic/Mutagen. You may serve one faction, several, or none at all.
+
+Your power lies in what you **carry, recover, build, protect, steal, or remember**. In Cyberia, the real war is fought over meaning, memory, and access across layers of reality.
+
+Even in the **Fragmented State** — that liminal moment between destruction and reintegration — the prepared mind can still observe, plan, and communicate. Every fragmentation is another lesson in the fragile nature of existence.
+
+**Welcome to Cyberia** — the Hyper-Reality Frontier. A broken future where physical and digital realities collide, ancient scars birth new empires, and your story remains unwritten.