@underpostnet/cyberia 3.3.73 → 3.3.76

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

@@ -30,10 +30,6 @@ class TranslateCyberiaPortal {
       en: 'Cyberia Entity Engine',
       es: 'Cyberia Entity Engine',
     };
-    Translate.Data['fallback-world-engine'] = {
-      en: 'Fallback World Engine',
-      es: 'Fallback World Engine',
-    };
     Translate.Data['instance-selection'] = {
       en: 'Select World',
       es: 'Seleccionar Mundo',

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

@@ -9,8 +9,8 @@ Underpost Platform provides the toolchain, deployment surface, PWA delivery, and
 ## Process model
 
 ```
-┌─────────────────────────────────────────────────────────────────────────┐
-│  UNDERPOST PLATFORM (infra · toolchain · deploy · PWA/Workbox)          │
+┌──────────────────────────────────────────────────────────────────────────┐
+│  UNDERPOST PLATFORM (infra · toolchain · deploy · PWA/Workbox)           │
 │                                                                          │
 │  ┌─────────────────────┐                                                 │
 │  │ Persistent backend  │   ← Cyberia content authority + asset backend   │
@@ -38,9 +38,9 @@ Underpost Platform provides the toolchain, deployment surface, PWA delivery, and
 │  └─────────────────────┘                                                 │
 │            │                                                             │
 │            │ REST (atlas frames, asset metadata, client hints,           │
-│            │       instance-map static presence + capability activity)    │
+│            │       instance-map static presence + capability activity)   │
 │            └──→ engine-cyberia                                           │
-└─────────────────────────────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────────────────┘
 ```
 
 Three processes, strict role separation. The ecosystem is fully operational only when all three are running and healthy at the same time.
@@ -62,7 +62,7 @@ What it owns:
 - gRPC `CyberiaDataService` for world load and content streaming.
 - REST boot fallback (`/api/cyberia-instance/boot/*`): the same world-load / hot-reload payloads as the gRPC service, served over REST for deploys where the engine gRPC server is not enabled.
 - REST APIs for assets and the optional client-hints overrides.
-- Instance Map REST (`/api/cyberia-instance/instance-map/:code/{static,dynamic}`): static map topology plus authored presence POIs, `sumStatsLimit`-capped baseline ObjectLayer stat sums, and capability membership; the dynamic response supplies only per-player capability activity. Never live positions or simulation stats — those stay client-side.
+- Instance Map REST (`/api/cyberia-instance/instance-map/:code/{static,dynamic}`): static map topology plus authored presence POIs, and capability membership; the dynamic response supplies only per-player capability activity. Never live positions or simulation stats — those stay client-side.
 - Static content distribution + Cloudinary-backed asset flow.
 - Editor and CLI integration for content workflows.
 
@@ -125,7 +125,7 @@ The three processes are supervised independently. Each service owns its own moni
 
 Dependency between services is handled by supervision and reconnect loops:
 
-- `cyberia-server` dials `engine-cyberia` gRPC at boot; on dial or load failure it retries over the REST boot fallback (`ENGINE_API_BASE_URL`, `/api/cyberia-instance/boot/*`) and exits only when both transports fail rather than fabricate a world. On reconnect, it reloads world configuration.
+- `cyberia-server` dials `engine-cyberia` 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, it reloads world configuration.
 - `cyberia-client` reconnects to `cyberia-server` over WebSocket and re-fetches content from `engine-cyberia` over REST independently.
 - If any one of the three services goes unhealthy, the game moves to standby until all three recover.
 
@@ -238,18 +238,18 @@ WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequen
 
 `InputCommand.Sequence` is monotonic per client. Every snapshot carries two acknowledgements of it, and they are not interchangeable:
 
-| Field     | Meaning                                                       | Client use                                                                       |
-| --------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `ack`     | Highest sequence **received** for this player.                 | Retires commands from the prediction buffer.                                      |
-| `moveAck` | Highest `PlayerAction` sequence that **re-planned movement**.  | Gates adoption of the authoritative `targetPos` / `path`.                         |
+| Field     | Meaning                                                       | Client use                                                |
+| --------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| `ack`     | Highest sequence **received** for this player.                | Retires commands from the prediction buffer.              |
+| `moveAck` | Highest `PlayerAction` sequence that **re-planned movement**. | Gates adoption of the authoritative `targetPos` / `path`. |
 
-**Movement re-plans once per player per tick, and nothing else throttles it.** Handlers record the tap's destination; `phaseInput` runs one A* per player after the queue is drained. Taps that land in the same tick describe the same instant, so only the newest is planned — the rest were superseded before they could mean anything. That coalescing is the only bound on pathfinder cost.
+**Movement re-plans once per player per tick, and nothing else throttles it.** Handlers record the tap's destination; `phaseInput` runs one A\* per player after the queue is drained. Taps that land in the same tick describe the same instant, so only the newest is planned — the rest were superseded before they could mean anything. That coalescing is the only bound on pathfinder cost.
 
 This is why the two acknowledgements diverge: a superseded tap is acked on arrival and never planned, so `self.path` and `self.targetPos` can still describe an earlier command. A client that adopted the route on `ack` alone would turn back toward the abandoned target — worst during rapid changes of direction, where it reads as input lag and as a walk that sets off the wrong way.
 
 Skills are not coalesced: they fire on every accepted tap, so the uplink carries every tap and the inbound rate limiter (`DefaultMessageRate`, 30/s) is what bounds the stream.
 
-The client predicts every tap immediately and never waits on a cadence. `self.actionCooldownMs` is the skill-trigger period only; keyboard steering paces its *refresh* by it, while a change of heading emits at once.
+The client predicts every tap immediately and never waits on a cadence. `self.actionCooldownMs` is the skill-trigger period only; keyboard steering paces its _refresh_ by it, while a change of heading emits at once.
 
 ---
 
@@ -284,8 +284,8 @@ Every Cyberia document uses the same terms. Aliases are not permitted.
 | **tick rate**             | Simulation Hz on `cyberia-server`.                                                                                                                                                                                                                                                                         |
 | **snapshot**              | AOI-filtered world view at one tick for one player.                                                                                                                                                                                                                                                        |
 | **prediction**            | Optimistic local apply of input commands to the predicted self entity.                                                                                                                                                                                                                                     |
-| **reconciliation**        | Correct prediction by the error measured at one tick: authoritative position minus the position predicted for that tick. Input is a destination, not a per-tick impulse, so the client keeps walking toward the `targetPos` that `moveAck` confirms, rather than replaying a command log.                   |
-| **move coalescing**       | One movement re-plan per player per tick, from the newest tap of that tick. The only bound on pathfinder cost, and the reason `moveAck` trails `ack`.                                                                                                                                                       |
+| **reconciliation**        | Correct prediction by the error measured at one tick: authoritative position minus the position predicted for that tick. Input is a destination, not a per-tick impulse, so the client keeps walking toward the `targetPos` that `moveAck` confirms, rather than replaying a command log.                  |
+| **move coalescing**       | One movement re-plan per player per tick, from the newest tap of that tick. The only bound on pathfinder cost, and the reason `moveAck` trails `ack`.                                                                                                                                                      |
 | **display smoothing**     | Per-render-frame exponential lerp from the discrete predicted self position to a continuous on-screen position. Decouples the visible main player from sim-tick boundaries.                                                                                                                                |
 | **interpolation**         | Render-time smoothing of remote entities, sampled from snapshot history.                                                                                                                                                                                                                                   |
 | **authoritative server**  | `cyberia-server`. Sole authority on world state.                                                                                                                                                                                                                                                           |
@@ -295,7 +295,7 @@ Every Cyberia document uses the same terms. Aliases are not permitted.
 | **presentation metadata** | Render-only data. Client-owned.                                                                                                                                                                                                                                                                            |
 | **input command**         | Typed client→server frame with kind, clientTick, sequence, payload.                                                                                                                                                                                                                                        |
 | **AOI**                   | Area of interest — the spatial filter that defines which entities a given player receives.                                                                                                                                                                                                                 |
-| **Instance Map**          | Client strategic overlay of packed map tiles and authored presence POIs. The static REST response supplies topology, presence, baseline ObjectLayer stat sums, and capability membership; the dynamic response supplies per-player capability activity. Live player presence and stats remain client-side. |
+| **Instance Map**          | Client strategic overlay of packed map tiles and authored presence POIs. The static REST response supplies topology, presence, and capability membership; the dynamic response supplies per-player capability activity. Live player presence and stats remain client-side. |
 | **replication**           | Production and delivery of snapshots from server to clients.                                                                                                                                                                                                                                               |
 | **simulation phase**      | A named step inside one simulation tick.                                                                                                                                                                                                                                                                   |
 | **healthy**               | All three Cyberia services up and connected; game is playable.                                                                                                                                                                                                                                             |

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

@@ -35,28 +35,38 @@ Import PNG assets, generate procedural layers, build atlas sprite sheets, push t
 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                                        |
+| Option                                                                               | Description                                                                |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `--import`                                                                           | Import specific item-id(s), comma-separated; needs one source below        |
+| `--instance <code>`                                                                  | Source `--import` from that instance backup under `engine-private`         |
+| `--from-directory`                                                                   | Source `--import` / `--import-types` from the asset directory              |
+| `--import-types [types]`                                                             | Batch import by type (e.g. `skin,floors`) or `all`; needs `--from-directory` |
+| `--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]`                                                      | Rebuild both atlas renders for the selected items                          |
+| `--minify`                                                                           | Refresh the minified render and the idle still; `--instance` narrows it    |
+| `--upscale <px-factor>`                                                              | Pixels per cell of the human-resolution render; alone, rebuilds it         |
+| `--normalize-stats`                                                                  | Clamp the stats of every layer the action writes to its item type's bounds |
+| `--random-stats`                                                                     | Regenerate the stats of every layer the action writes at random            |
+| `--min-stat <n>` / `--max-stat <n>`                                                  | Narrow the range the two flags above may leave (default `-100`/`100`)      |
+| `--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`                                | env / DB / dev overrides                                                   |
 
 ```bash
-# Import specific items
-cyberia ol hatchet,sword --import --env-path ./engine-private/conf/dd-cyberia/.env.development
+# Restore specific items from an instance backup: the backup is the authority for the item
+cyberia ol hatchet,sword --instance FOREST --import
 
-# Batch import by type, or everything
-cyberia ol --import-types skin,floors
-cyberia ol --import-types all
+# Import specific items from the asset directory
+cyberia ol hatchet,sword --from-directory --import --env-path ./engine-private/conf/dd-cyberia/.env.development
+
+# Batch import by type, or everything, from the asset directory
+cyberia ol --from-directory --import-types skin,floors
+cyberia ol --from-directory --import-types all
 
 # Procedural generation
 cyberia ol floor-desert --generate --seed fx-42
@@ -66,16 +76,29 @@ cyberia ol floor-grass  --generate --frame-count 4 --count 5 --density 0.7
 cyberia ol hatchet --to-atlas-sprite-sheet
 cyberia ol hatchet --show-frame 08_0
 
+# Rebuild both atlas renders. The scope is an item-id, an instance, or everything.
+cyberia ol hatchet --to-atlas-sprite-sheet --upscale 40
+cyberia ol --instance TEST --upscale 20
+cyberia ol --to-atlas-sprite-sheet
+
+# Refresh the minified render the client downloads and the idle still every preview shows
+cyberia ol hatchet --minify
+cyberia ol --minify --instance FOREST
+
+# Balance stats on every layer an action writes
+cyberia ol --minify --instance FOREST --normalize-stats
+cyberia ol hatchet --from-directory --import --random-stats --normalize-stats --max-stat 10
+
 # Drop + re-import a single item, including static folders
-cyberia ol hatchet --drop --client-public --import
+cyberia ol hatchet --drop --client-public --from-directory --import
 ```
 
 ---
 
 ## `cyberia instance` — instance data
 
-Export / import / drop a game instance and its related maps, entities, actions, quests, and object
-layers in MongoDB.
+Export / import / drop a game instance and its related maps, entities, actions, quests, object
+layers and map audio in MongoDB.
 
 ```bash
 cyberia instance [instance-code] [options]
@@ -87,6 +110,7 @@ cyberia instance [instance-code] [options]
 | `--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                    |
+| `--sync-entities`                                     | Sync the conf's entity-type default references and skill config         |
 | `--export-current-fallbackworld`                      | Capture the in-memory procedural fallback world, then export it         |
 | `--keep-fallback-codes`                               | Capture using the raw `fallback-map-*` / canonical action-quest codes   |
 | `--fallback-url <url>`                                | Capture the world a running engine serves instead of regenerating it    |
@@ -98,6 +122,102 @@ cyberia instance FOREST --import ./backups/FOREST
 cyberia instance FOREST --drop
 ```
 
+A backup carries audio too. `cyberia-map-audio-confs/<map-code>.json` holds each map's bindings —
+that configuration belongs to the map, so it travels with the instance and `--drop` removes it with
+the map. The assets those bindings name travel as copies in `cyberia-audio/<code>.json` with their
+WAV beside them in `files/`, because a `CyberiaAudio` document is global: the import upserts it by
+code and leaves other instances' bindings alone, and `--drop` never removes one. A binding whose
+asset is missing is kept as written — the code is the whole reference, so importing the asset later
+is all it takes to make it play.
+
+A backup also carries the entity-type defaults the instance's conf **references**, under
+`cyberia-entity-type-defaults/<_id>.json`. `CyberiaInstanceConf.entityDefaults` holds
+`CyberiaEntityTypeDefault` ids, never copies of the documents, and both directions travel by that
+id: the export writes exactly the referenced documents, and the import restores them under their
+original `_id` so the references keep resolving.
+
+`--sync-entities` builds those references from the world's own content: a default belongs to the
+instance when all of its `liveItemIds` appear together on some entity the maps place — the same
+subset containment the runtime resolves an entity with. It is additive and idempotent, so a
+hand-linked default that no map places (a player or coin default) is kept, and re-running links
+nothing new. A match another instance already references is **reported, not adopted**: two worlds
+built on the same art hold documents with identical live item ids, so matching alone cannot tell
+them apart, and claiming one stays a deliberate act in the Entity engine.
+
+Skills are **derived, never stored**. The `cyberia-skill` collection is deployment-wide and owns
+the definitions; an instance runs the ones whose `triggerItemId` is an item id its own content
+names. That content is four things and no more: what its maps place, what its entity-type defaults
+wire, what its vendor and assembler catalogs trade, and what its quests ask for or pay out. The
+canonical `ENTITY_TYPE_DEFAULTS` count alongside the instance's own, so a world referencing no
+player default still holds `atlas_pistol_mk2` and keeps its projectile skill rather than being
+disarmed.
+
+That last source is why `hatchet` belongs to a world whose maps place no hatchet: a quest objective
+or a shop shelf names one, so a player there can come to hold it and fire it. `--sync-entities`
+reports the resolved list, the export writes exactly those documents to
+`cyberia-skills/`, and the boot payload sends exactly those to the simulation — one rule, so the
+three can no longer disagree. Nothing is written to the instance conf, which carries no
+`skillConfig` field: a stored list was a second answer to the same question, and it was the one
+that went stale.
+
+The Instance engine has the same action as a button, syncing against the map codes currently
+selected.
+
+```bash
+cyberia instance FOREST --sync-entities --dev
+```
+
+A reference cannot outlive its document. Deleting an entity-type default unlinks it from every
+conf first, and both `--export` and `--import` compact the instance's references — dropping any
+whose document is gone — so a backup never carries a dangling id and restoring one never recreates
+it. Saving a default in the Entity engine compacts the collection too. What is exported is
+therefore exactly what resolves.
+
+That reference is what scopes a default to a world. Membership used to be inferred by matching item
+ids, and two instances built on the same art therefore matched each other: exporting one dragged in
+the other's wiring, and importing it overwrote the original by an `(entityType, liveItemIds)`
+"natural key". An id names one document, so neither is possible. A backup written before the change
+still embeds the documents in its conf; importing it converts them to references against the
+documents in that same backup, creating any it cannot find.
+
+An instance that references nothing is complete, not empty: it runs on the canonical
+`ENTITY_TYPE_DEFAULTS`, and referenced documents override only the entity types they cover.
+
+Those documents are also where a world's starting inventory comes from, and an entity has exactly
+one. It carries the **union** of every id its default names — `liveItemIds`, `deadItemIds`,
+`dropItemIds` and the inventory-only `inventoryItemsIds` — deduplicated. Nothing stores which slots
+are worn: the three lifecycle lists are discriminators, and the runtime activates the ones the
+context calls for, which is why the whole union is seeded (the server activates a slot that is
+already there rather than appending one). Spawn state is alive, so the live ids are the active
+ones; everything else is carried empty, a coin balance included.
+
+`overrideItemsIdsState` is the one adjustment to that derivation, per id: `active` forces the spawn
+state — a skin the equipment rules would otherwise leave inactive — `quantity` sizes a stack,
+which is how a drop bundle declares how many tokens it scatters, and `dropChance` (0–1) says how
+often the id actually scatters when the entity dies. It never adds an id; the union decides
+membership, an override only what a member starts as.
+
+`dropChance` is meaningful only for an id the build carries in `dropItemIds`; on any other row it is
+inert, and the resolver reports 1 there so the simulation reads one field and never a missing one.
+Saying nothing means 1, which is what every world did before the field existed, and each drop id is
+rolled independently — a build can pair a common drop with a rare one and have both decided on their
+own. A deliberate 0 survives, because the wire field is explicitly optional: absent and zero are
+different answers.
+
+`inventoryItemsIds` is therefore only for what no lifecycle state ever activates. The instance holds
+no item list of its own: it names entity-type defaults, and the items follow from them, so there is
+exactly one place to read or change a starting kit.
+
+To point a world at the seeded collection, name it:
+
+```bash
+cyberia run-workflow seed-entities --instance FOREST --dev
+```
+
+`seed-entities` upserts `ENTITY_TYPE_DEFAULTS` into the collection; `--instance` then makes that
+instance's conf reference exactly those documents, replacing whatever it referenced before, so
+re-running converges rather than accumulating.
+
 ### Capturing the procedural fallback world
 
 The fallback world is never persisted: every engine process rebuilds it from the code defaults at
@@ -105,7 +225,9 @@ boot and serves it whenever a requested instance is absent. `--export-current-fa
 that in-memory world into MongoDB under a real instance code — maps and portal topology, the
 instance conf, and the content collections the fallback path serves from code rather than the DB
 (skills, entity-type defaults, dialogues, actions, quests) — and then exports it like any other
-instance.
+instance. It writes each captured map's audio configuration too, under the captured map code,
+binding only the codes an imported `CyberiaAudio` actually carries and reporting the rest: the
+client asks for audio by map code, so a namespaced capture would otherwise play nothing.
 
 ```bash
 # Freeze the current fallback world as PROC-1 and back it up
@@ -119,7 +241,7 @@ Map, action and quest codes are namespaced under the instance code (`fallback-ma
 `PROC-1-map-0`) so successive captures never overwrite each other; `--keep-fallback-codes` writes
 the canonical codes verbatim instead. Sprites are the one thing a capture cannot synthesise: when a
 referenced item id has no `ObjectLayer` document the command aborts and names the ids to import with
-`cyberia ol <ids> --import`. Staged fallback default items live only in the serving engine process,
+`cyberia ol <ids> --from-directory --import`. Staged fallback default items live only in the serving engine process,
 so pass `--fallback-url http://localhost:4001` to capture a live world rather than regenerating it.
 
 ---
@@ -148,6 +270,140 @@ cyberia client-hints cyberia-main --export ./client-hints-cyberia-main.json
 
 ---
 
+## `cyberia audio` — audio assets and map audio
+
+Imports recorded [`cyberia-audio`](https://github.com/underpostnet/cyberia-audio) assets into MongoDB and binds
+them to a map. Every recording is a pair — `<name>.wav` and its `<name>.json` manifest — and the pair is the unit
+of import: a WAV with no manifest beside it is skipped. Produce the pair with `cyberia-audio sfx coin` or
+`cyberia-audio music combat`.
+
+```bash
+cyberia audio [audio-code] [options]
+```
+
+| Option                                                | Description                                                          |
+| ----------------------------------------------------- | -------------------------------------------------------------------- |
+| `--import`                                            | Import WAV + manifest pairs; all of them when no code is given       |
+| `--records-path <path>`                               | Records directory to import from (default `./cyberia-audio/records`) |
+| `--map <map-code>`                                    | Target `cyberia-map` code to read or configure                       |
+| `--set-default-music <audio-code>`                    | Default background music for `--map`                                 |
+| `--set-event <logic-event-id:audio-code>`             | Bind an asset to a logic event (e.g. `combat`, `shoot`); repeatable  |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` | env / DB / dev overrides                                             |
+
+```bash
+# Import every recorded asset, or a single one
+cyberia audio --import
+cyberia audio combat --import
+
+# Configure a map, then read back what it resolved to
+cyberia audio --map FOREST --set-default-music exploration \
+  --set-event projectile:shoot --set-event coin_drop_or_transaction:coin
+cyberia audio --map FOREST
+```
+
+An asset is identified by its `code` alone — `cyberia-audio` stores what a sound _is_ (`code`, `fileId`,
+`manifest`) and never what it is for. `manifest.bus` is the `src/audio-module/<bus-id>/` directory the module
+was authored in — the asset's natural route, recorded as provenance; a map binding decides where it actually
+plays. Configuration lands in `cyberia-map-audio-conf`, one document per map code,
+holding `defaultMusic`, a single `events` list and volume/loop/crossfade `settings`. Each binding is the same
+pattern the skill model uses — a semantic `logicEventId` resolving to an `audioCode`:
+
+```js
+{ logicEventId: 'combat', audioCode: 'combat', settings: { bus: 'music', loop: true, crossfadeMs: 800 } }
+{ logicEventId: 'hit', audioCode: 'hit' }
+```
+
+`bus` is one vocabulary with one spelling — `music` and `sfx`, declared once in
+`SharedDefaultsCyberia.AUDIO_BUSES`. The same two ids name the `cyberia-audio/src/audio-module/<bus-id>/`
+directory an asset is authored in, the argument `cyberia-audio <bus-id> <id>` dispatches on, the `bus` a
+recorded manifest carries, and the route a binding's `settings.bus` selects.
+
+The event vocabulary is centralized the same way: `SharedDefaultsCyberia.AUDIO_LOGIC_IDS` declares the
+events a binding may answer and the bus each one naturally routes to, `cyberia-server-defaults` holds the seed's
+bank (`DEFAULT_AUDIO_BANK`) and its bindings (`DEFAULT_AUDIO_BINDINGS`, expanded by `buildAudioEventBindings`),
+and `cyberia-client/src/audio/audio_events.h` holds the same ids for the emitting side. A binding naming an
+unknown event, or an asset the bank does not carry, throws at import rather than playing silence.
+
+The fallback bank binds `projectile`, `coin_drop_or_transaction`, `drop`, `item-pickup`, `victory`, `level-up`,
+`death`, `heal`, `hit`, `portal`, `ui-click` and `footsteps` as one-shots, and `combat`, `boss`, `portal-cooldown` and
+`craft` as music. `victory` is a cue rather than a bed: completing a quest is an event, and holding the
+bus for it would take the map's music away for the length of a flourish. `hit` follows the server's damage events, so it sounds for any entity in view rather than
+only for the player; `level-up` and `death` arrive as server `audio_event` broadcasts, so a level gained or a defeat sounds for every viewer in reach; `ui-click` follows a tap the interface accepted.
+
+`item-pickup` fires where every route into the inventory bar converges — world loot flying in, a quest
+reward, a purchase, an assembly output — so one emission covers them all. It is deliberately plainer than
+`coin`, which stays the reward gesture reserved for currency.
+
+`craft` is a held bed rather than a cue, the same shape as `portal-cooldown`: it takes over the map's music
+for exactly as long as a recipe's assembly bar charges, loops seamlessly while the player waits, and releases
+back to the map on completion. Both holds are arbitrated in `audio_context.c`, which is also what makes them
+outlive a combat exchange instead of being cut by it — the modal owns the bar and only reports whether one is
+running.
+
+Two cues are about the crowd rather than about one event, because sounding them per entity buries the bus.
+`heal` is a milestone: regeneration ticks constantly and in small amounts, so it sounds only when an entity's
+life crosses back above zero, 25%, 50% or 75%, once per snapshot however many entities crossed. `footsteps`
+is a cadence: one gait cycle repeats for as long as anything with feet is walking in view, at one rate for the
+whole scene rather than one per walker.
+
+Portal audio follows the authoritative teleport charge, never the map code: `onPortal` holds `portal-cooldown` as
+a bed for as long as the charge runs, and completing it fires the `portal` one-shot while the departing map's
+bindings are still resident. An intra-map portal moves the player without changing maps, so watching the map code
+was silent for exactly that case; stepping off the pad drops the bed without sounding the jump.
+
+Whether a binding behaves as a bed, a one-shot or a transition follows from the logic event that fires it and the
+settings it carries, not from a classification stored twice. The code is checked against the imported assets, so
+an unimported one is rejected rather than stored as a dangling name. Bindings merge by `logicEventId`: naming an
+event replaces that binding and leaves the others in place. `--map` on its own prints the current configuration
+and writes nothing.
+
+The fallback seed is the exception, and deliberately so: it states a map's complete binding set, so re-running it
+converges. A binding whose logic event the bank no longer declares — a renamed cue, for instance — is dropped and
+logged, instead of surviving as a name the client would keep asking the engine to resolve.
+
+`settings.bus` selects `music` or `sfx` on the binding. It does not classify the asset.
+Omitted settings inherit client or map defaults. Supported overrides include volume, loop, crossfadeMs, pitch, pan, and priority.
+Set music event routing through the map configuration API or the fallback seed workflow.
+Changing only an event's audio code preserves its existing settings.
+
+Record and seed the complete fallback bank from the engine repository root:
+
+```bash
+cyberia run-workflow seed-audio --records-only
+cyberia run-workflow seed-audio --dev --mongo-host 127.0.0.1
+cyberia run-workflow seed-audio --instance my-instance --dev --mongo-host 127.0.0.1
+```
+
+The first command records thirteen WAV and manifest pairs and touches no database.
+The second also upserts generic File references, CyberiaAudio metadata, and audio configuration for the fallback maps.
+The third configures one instance's maps instead: `--instance <instance-code>` reads that instance's own
+`cyberiaMapCodes` and scores every one of them with the same bank, bindings and default bed the fallback world
+uses, so a world built on that topology sounds the way the fallback world does. Every map falls back to the
+`exploration` bed; what makes a place sound different is the event that fires there. The instance must exist and
+declare at least one map, or the run fails without writing anything.
+
+Every form states each map's whole configuration, so re-running converges rather than accumulating: a bed is
+reassigned and a binding the bank no longer declares is dropped.
+It reuses the existing engine environment resolution. Full seeding requires that deployment configuration and MongoDB.
+Use `--records-path` to select the output directory.
+An asset's generic File `_id` is derived from its code and the bytes themselves, so re-importing an unchanged
+bank rewrites nothing, and a changed render lands on a new `fileId` while the blob it replaced is deleted in the
+same step. That is what keeps the client honest: it fetches a WAV as `/api/file/blob/<fileId>` and caches it, so
+new bytes under a reused id would go on playing the old sound. `cyberia-audio.fileId` is registered in
+`src/api/file/file.ref.json`, which is the list `underpost db clean-fs` treats as the complete set of File
+references — a blob no registered field points at is deleted by that sweep. Deleting an asset, through the API or
+by restoring an instance over it, deletes its blob with it. Interrupted imports can be rerun safely.
+
+Recording produces nothing for the client to ship: `cyberia-client` bundles no WAV and fetches every asset from
+engine-cyberia by code, so an asset is reachable only once it is seeded.
+
+The client resolves `logicEventId → audioCode → fileId → /api/file/blob/:fileId` and caches decoded WAVs.
+Fallback maps use exploration, combat, boss, and exploration music in order.
+Missing remote content uses the generated local bank. Unknown effects become silence.
+Regenerate the local bank before building the client after changing audio content.
+
+---
+
 ## `cyberia chain` — Besu + ObjectLayerToken
 
 Hyperledger Besu IBFT2 network and ERC-1155 `ObjectLayerToken` (CKY) lifecycle.

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`)