@underpostnet/cyberia 3.3.73 → 3.3.77

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

@@ -56,10 +56,6 @@ class RouterCyberiaPortal {
         title: 'cyberia-entity-engine',
         render: () => s(`.main-btn-cyberia-entity-engine`).click(),
       },
-      '/fallback-world-engine': {
-        title: 'fallback-world-engine',
-        render: () => s(`.main-btn-fallback-world-engine`).click(),
-      },
       '/instance-selection': {
         title: 'instance-selection',
         render: () => s(`.main-btn-instance-selection`).click(),

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/components/default/AppShellDefault.js

@@ -31,8 +31,6 @@ class AppShellDefault {
     const RouterInstance = RouterDefault.instance();
 
     const { barConfig } = await Themes[Css.currentTheme]();
-
-    const badgeNotificationMenuStyle = { top: '-33px', left: '24px' };
     const barMode = undefined; // 'top-bottom-bar';
     await Modal.instance({
       id: 'modal-menu',
@@ -197,8 +195,7 @@ class AppShellDefault {
             ${await Badge.instance({
               id: 'main-btn-chat',
               type: 'circle-red',
-              style: badgeNotificationMenuStyle,
-              classList: 'hide',
+              classList: 'hide badge-notification-menu',
             })}`,
             attrs: `data-id="chat"`,
             tabHref: `${getProxyPath()}chat`,

package/src/client/components/itemledger/AppShellItemledger.js

@@ -27,8 +27,6 @@ class AppShellItemledger {
     const RouterInstance = RouterItemledger.instance();
 
     const { barConfig } = await Themes[Css.currentTheme]();
-
-    const badgeNotificationMenuStyle = { top: '-33px', left: '24px' };
     const barMode = undefined; // 'top-bottom-bar';
     await Modal.instance({
       id: 'modal-menu',

package/src/client/components/underpost/AppShellUnderpost.js

@@ -227,7 +227,7 @@ class AppShellUnderpost {
       titleRender: () => {
         return '';
       },
-      mode: 'slide-menu',
+      mode: 'slide-menu-right',
       RouterInstance,
       searchCustomImgClass: 'underpost-menu-icon',
       htmlMainBody: async () => {

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.