@underpostnet/cyberia 3.2.80

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

@@ -0,0 +1,294 @@
+<p align="center">
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA online"/>
+</p>
+
+<div align="center">
+
+<h1>cyberia server</h1>
+
+</div>
+
+**Path:** `cyberia-server/` · **Language:** Go · **Role:** authoritative simulation runtime for Cyberia
+
+`cyberia-server` is the authoritative simulation runtime for the Cyberia MMO extension on Underpost Platform. It owns world state, advances a fixed-rate tick, drains typed input commands from connected clients, and dispatches AOI-filtered snapshots on a separately-paced replication tick.
+
+It is **not** the content authority. World content is loaded once at boot from `engine-cyberia` over gRPC. It is **not** the render-policy authority. Presentation is owned by `cyberia-client`.
+
+---
+
+## Operating model
+
+Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
+
+```
+engine-cyberia (Node.js)                cyberia-server (Go)              cyberia-client (C/WASM)
+─────────────────────────               ──────────────────               ──────────────────────
+content authority                       authoritative simulation         presentation runtime
+persisted maps + rules                  tick + AOI + snapshots           render + prediction
+
+      │  gRPC  GetFullInstance               │  WebSocket binary
+      │────────────────────────────────────► │  AOI snapshots + init
+      │  (world configuration:               │  ▲
+      │   AOI radius, economy,               │  │ typed input commands
+      │   skill, equipment,                  │  │
+      │   entity gameplay defaults)          │  │
+      │                                      │  │
+      ▼                                      ▼  ▼
+   (boot + hot reload)                   tick loop + replication
+```
+
+- Each service is supervised independently and owns its own monitor and reconnector.
+- `cyberia-server` dials `engine-cyberia` gRPC at boot; on dial or load failure it retries over the REST boot fallback (`ENGINE_API_BASE_URL`, `/api/cyberia-instance/boot/*`) and exits only when both transports fail rather than fabricate a world.
+- On reconnect, world configuration is reloaded via `GetFullInstance(instanceCode)`.
+- If any one of the three services is unhealthy, the game moves to standby until all three recover.
+
+The server speaks two protocols:
+
+- **gRPC (or its REST boot fallback), inbound, at boot and hot reload:** consumes world configuration from `engine-cyberia`.
+- **WebSocket binary, ongoing:** delivers AOI snapshots to clients, accepts typed input commands.
+
+There is no per-tick traffic between `cyberia-server` and `engine-cyberia`, and no presentation authority in the Go runtime.
+
+---
+
+## Tick model
+
+The tick is the universal coordinate of the simulation.
+
+| Concept           | Default         | Notes                                                                                                   |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| **tick**          | `uint32`        | Monotonic, advanced once per simulation step. Resets only on world rebuild.                             |
+| **tick rate**     | `30` Hz         | Simulation Hz. Loaded from world configuration. **The string `fps` is not used to describe this rate.** |
+| **snapshot rate** | `20` Hz         | AOI replication Hz. Decoupled from tick rate so bandwidth scales independently of simulation fidelity.  |
+| **tick duration** | `1 / tick_rate` | The dt used by every simulation phase.                                                                  |
+| **current tick**  | `uint32`        | The simulation step about to run (or just produced). Stamped into every outgoing snapshot.              |
+
+Two independent tickers:
+
+| Ticker      | Rate              | Responsibility                                               |
+| ----------- | ----------------- | ------------------------------------------------------------ |
+| simulation  | `tickRate` Hz     | advance world by exactly one tick; run phases in fixed order |
+| replication | `snapshotRate` Hz | per-player AOI filter + encode + dispatch                    |
+
+Movement integration is `dt`-based: `step = speed * tickDuration.Seconds()`. Frame-count integration is not used anywhere on the server.
+
+---
+
+## Simulation phases
+
+Inside one simulation tick, the phases run in a fixed order. Phases are the **only** functions allowed to mutate world state.
+
+1. **`phaseInput`** — drain each player's `InputQueue`; dispatch typed input commands to gameplay handlers.
+2. **`phaseLifecycle`** — respawn timers, despawn expirations.
+3. **`phaseSkills`** — skill projectile collisions.
+4. **`phaseAI`** — bot behaviour decisions.
+5. **`phaseMovement`** — integrate positions using `tickDuration`.
+6. **`phasePortals`** — portal entry and teleport.
+
+Separately, on the replication ticker:
+
+7. **`phaseReplication`** — per player: compute AOI rectangle, build snapshot, dispatch via the player's WebSocket write channel.
+
+Phases never read presentation data. Phases consume world configuration (gameplay rules) and the per-player input queue.
+
+---
+
+## Input command pipeline
+
+Client input is typed end-to-end. There is no JSON intermediate on the binary path. The simulation tick is the only consumer of input commands.
+
+```
+WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequence, payload}
+                                              │
+                                              ▼
+                                              dispatchInputCommand
+                                              │
+                                              ▼
+                                              PlayerState.InputQueue (per-player, bounded ring)
+                                              │
+                                              ▼
+                         phaseInput (under world mutex, once per simulation tick)
+                                              │
+                                              ▼
+                         phase_input_handlers.go — typed dispatch per InputKind
+                                              │
+                                              ▼
+                         authoritative world state
+```
+
+| Property                          | Detail                                                                                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One queue per player              | drained exactly once per simulation tick                                                                                                           |
+| One typed handler per `InputKind` | each handler runs under the world mutex held by `phaseInput`                                                                                       |
+| One source of truth               | `phase_input_handlers.go` is the only file that translates an input command into world state                                                       |
+| Sequence numbering                | `InputCommand.Sequence` is monotonic per client; the server tracks the highest applied sequence per player in `PlayerState.LastAckedInputSequence` |
+
+A second uplink path, `handleJSONUplink`, parses text-framed JSON uplinks into the same typed `InputCommand` and routes them through the same per-tick queue. No synchronous game-state mutation runs on the WebSocket read goroutine.
+
+### Input kinds
+
+| Kind             | Wire byte | Effect                                                                          |
+| ---------------- | --------- | ------------------------------------------------------------------------------- |
+| `PlayerAction`   | `0x11`    | TAP — movement intent + skill trigger                                           |
+| `ItemActivation` | `0x12`    | Equip/unequip an ObjectLayer item; validated against equipment rules            |
+| `FreezeStart`    | `0x13`    | Enter FrozenInteractionState (blocks movement/damage; rest of world unaffected) |
+| `FreezeEnd`      | `0x14`    | Exit FrozenInteractionState                                                     |
+| `Chat`           | `0x15`    | Pure relay; no game-state mutation                                              |
+| `GetItemsIDs`    | `0x16`    | Skill-item-id lookup; produces a response frame                                 |
+| `Handshake`      | `0x10`    | Connection establishment; no gameplay effect                                    |
+
+---
+
+## AOI replication
+
+The AOI system filters world state per-player so each client receives only what its character can perceive.
+
+Per player:
+
+- AOI is a rectangle centered on the player position with size determined by `aoiRadius` from world configuration.
+- On each replication tick, the server iterates the player's map, includes any entity whose bounding rectangle overlaps the AOI, and emits a snapshot.
+
+### Snapshot header (binary, little-endian)
+
+```
+[0]      u8   msgType     0x01 = aoi_update, 0x03 = full_aoi
+[1..4]   u32  tick        simulation tick at which the snapshot was produced
+[5..8]   u32  lastAcked   highest InputCommand.Sequence applied for this player
+[9..10]  u16  entityCount entity blocks that follow
+```
+
+The `tick` and `lastAcked` fields are how the client reconciles its predicted self with authoritative state. The client drops input commands with `sequence ≤ lastAcked` from its replay buffer, then rewinds and replays the rest.
+
+Other message types (init data, FCT) carry their own headers and are not part of the per-tick replication stream.
+
+---
+
+## World configuration
+
+World configuration is loaded once at boot from engine-cyberia via gRPC `GetFullInstance(instanceCode)`. The simulation consumes the following from it:
+
+| Field                                                                | Used for                                                                          |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `cellSize`                                                           | grid math                                                                         |
+| `tickRate`                                                           | simulation Hz                                                                     |
+| `aoiRadius`                                                          | per-player AOI rectangle size                                                     |
+| `entityBaseSpeed`, `entityBaseMaxLife`, `entityBaseActionCooldownMs` | base stats                                                                        |
+| `economyRules`                                                       | Fountain & Sink coin economy                                                      |
+| `skillRules`                                                         | projectile / doppelganger spawn rates and lifetimes                               |
+| `equipmentRules`                                                     | item activation constraints (one-per-type, requireSkin, activeItemTypes)          |
+| `entityDefaults[*]`                                                  | per-entity-type gameplay defaults: live/dead/drop item IDs, default object layers |
+
+World configuration is gameplay-only. Presentation fields (palette, status-icon visuals, camera knobs, dev-overlay flag, interpolation window, screen factors) are not part of this contract. Presentation metadata ownership is described in the next section.
+
+Hot reload of ObjectLayers is supported via periodic `GetObjectLayerManifest` calls; world topology and gameplay rules are reloaded only on server restart.
+
+---
+
+## Presentation metadata ownership
+
+`cyberia-server` holds **no** presentation state. There is no field on the server for:
+
+- palette
+- status-icon iconId or border color
+- camera smoothing or camera zoom
+- dev-overlay flag
+- screen-factor overrides
+- interpolation window
+
+These live in the client runtime's compile-time defaults. Per-instance presentation overrides are served by engine-cyberia at `GET /api/cyberia-client-hints/:instanceCode` and consumed directly by the client. The Go process never calls that endpoint.
+
+### `sim_palette.go`
+
+A small internal RGBA table inside `sim_palette.go` exists solely to fill the optional per-entity color bytes on the AOI wire for portals, skill projectiles, and freshly spawned players. The table is:
+
+- compile-time constant
+- not loaded from any contract (gRPC, REST, proto, env)
+- read only at world-build and one-shot spawn paths
+- never consulted during any per-tick simulation phase
+
+The client treats those wire bytes as a hint and resolves the actual fallback color from its own palette by entity type.
+
+---
+
+## Source layout
+
+Paths are relative to `cyberia-server/`. Gameplay logic lives under `src/`; the engine transport clients (gRPC + REST fallback dispatcher) and world builder under `engine_client/`; the chi-based REST router under `api/`.
+
+| File                                                                                              | Responsibility                                                                                          |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `main.go`                                                                                         | Entry point — loads `.env`, dials engine-cyberia gRPC, mounts WS and `/api` router, starts listener     |
+| `src/tick.go`                                                                                     | `Tick`, `InputSequence` types and tick rate constants                                                   |
+| `src/server.go`                                                                                   | `GameServer` struct, simulation+replication tickers, `ApplyInstanceConfig`, world mutator orchestration |
+| `src/types.go`                                                                                    | Core data structures (`PlayerState`, `BotState`, `MapState`, `ObjectLayerState`, etc.)                  |
+| `src/simulation_phases.go`                                                                        | Phase entry points called from the tick loop                                                            |
+| `src/phase_input_handlers.go`                                                                     | Typed dispatch per `InputKind`; the only translator from input commands to world state                  |
+| `src/input_command.go`                                                                            | `InputCommand` struct, `InputKind` constants, per-player queue helper                                   |
+| `src/aoi_binary.go`                                                                               | Binary AOI snapshot encoder; message type constants                                                     |
+| `src/object_layer.go`                                                                             | ObjectLayer Go types mirroring MongoDB schema                                                           |
+| `src/instance_loader.go`                                                                          | World reconstruction from gRPC payload                                                                  |
+| `src/collision.go`                                                                                | Grid collision, portal transitions, death handling                                                      |
+| `src/pathfinding.go`                                                                              | A\* pathfinding for bot and player navigation                                                           |
+| `src/skill.go`, `src/skill_dispatcher.go`, `src/skill_projectile.go`, `src/skill_doppelganger.go` | Skill registry and per-skill handlers                                                                   |
+| `src/economy.go`                                                                                  | Fountain & Sink coin economy                                                                            |
+| `src/life_regen.go`                                                                               | HP regeneration                                                                                         |
+| `src/ai.go`                                                                                       | Bot AI                                                                                                  |
+| `src/stats.go`                                                                                    | Active stat aggregation, sum-stats limit enforcement                                                    |
+| `src/entity_status.go`                                                                            | Entity Status Indicator (ESI) numeric IDs                                                               |
+| `src/frozen_state.go`                                                                             | FrozenInteractionState                                                                                  |
+| `src/handlers.go`                                                                                 | WebSocket lifecycle, binary uplink decoder, JSON-uplink back-compat adapter                             |
+| `src/sim_palette.go`                                                                              | Internal RGBA fill for AOI wire bytes (not a contract)                                                  |
+| `engine_client/`                                                                                  | engine-cyberia transport clients (gRPC, REST fallback, dispatcher) + world builder                      |
+| `api/router.go`, `api/metrics.go`                                                                 | chi router; `/api/v1/*` endpoints                                                                       |
+| `proto/cyberia.proto`                                                                             | gRPC service contract shared with engine-cyberia                                                        |
+
+---
+
+## REST surface
+
+`/api/v1/*` is the operational surface; it is independent of the WebSocket gameplay protocol.
+
+| Endpoint                    | Method | Description                               |
+| --------------------------- | ------ | ----------------------------------------- |
+| `/api/v1/health`            | GET    | Simple health check                       |
+| `/api/v1/metrics`           | GET    | Complete server metrics snapshot          |
+| `/api/v1/metrics/health`    | GET    | Detailed health with entity/player counts |
+| `/api/v1/metrics/entities`  | GET    | Entity-type breakdown                     |
+| `/api/v1/metrics/websocket` | GET    | Active connections, message rates         |
+| `/api/v1/metrics/workload`  | GET    | Per-map entity workload                   |
+
+All content data (ObjectLayer metadata, asset blobs, optional client hints, the Instance Map graph) is served directly by engine-cyberia REST. `cyberia-server` does not proxy content; it only forwards `instanceCode` (alongside `apiBaseUrl`) in the WebSocket `metadata` message so the client can key its engine-cyberia fetches.
+
+---
+
+## Environment
+
+| Variable                          | Default           | Description                                        |
+| --------------------------------- | ----------------- | -------------------------------------------------- |
+| `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | engine-cyberia gRPC address (**required**)         |
+| `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                   |
+| `ENGINE_API_BASE_URL`             | _(empty)_         | Internal engine-cyberia origin (server→engine only) |
+| `ENGINE_PUBLIC_URL`               | _(empty)_         | Client-visible Content Authority origin (forwarded to clients) |
+| `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval            |
+| `SERVER_PORT`                     | `8081`            | WebSocket + HTTP listen port                       |
+| `STATIC_DIR`                      | `./public`        | Directory for static WASM client files             |
+
+---
+
+## Build and run
+
+```bash
+cd cyberia-server
+
+# Development
+go run main.go
+
+# Production binary
+go build -o cyberia-server .
+./cyberia-server
+```
+
+### Test logx
+
+```bash
+go test ./logx/ -run TestResolveLevel
+```

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

@@ -0,0 +1,259 @@
+<div align="center">
+
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
+
+<h1>CYBERIA</h1>
+
+**Network Object Layers**
+
+_Stackable Rendering Layers as a Unified Tokenized Reality_
+
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
+
+</div>
+Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
+toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
+runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.
+
+`engine-cyberia` is the **sidecar-backed data layer**: a Node.js sidecar that owns content,
+validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
+Go server and the WASM client with data — it does not run the simulation or the presentation.
+
+---
+
+## Ecosystem at a glance
+
+```text
+                         ┌───────────────────────────────────────────────┐
+                         │              UNDERPOST PLATFORM                 │
+                         │  toolchain · deploy · PWA build · static        │
+                         │  delivery · cluster/image/db · monitoring       │
+                         │                                                 │
+                         │   underpost CLI  ──▶  builds & deploys all      │
+                         └───────────────────────────────────────────────┘
+                                            │  hosts / delivers
+                                            ▼
+   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
+   ║                                                                               ║
+   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
+   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
+   ║   │     (Node.js)    │           │       (Go)       │            │           ║
+   ║   │                  │           │                  │            ▼           ║
+   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
+   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
+   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
+   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
+   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
+   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
+   ║            │                                             │ prediction       │ ║
+   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
+   ║                                                          └──────────────────┘ ║
+   ╚═══════════════════════════════════════════════════════════════════════════════╝
+
+   One source of truth per concern:
+     content & world config ── engine-cyberia
+     real-time world state  ── cyberia-server
+     presentation & input   ── cyberia-client
+```
+
+---
+
+## 1. Toolchain and base infrastructure
+
+Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
+selection, host/path layout, generated client assets, and environment resolution.
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+`underpost` is the shared control surface for everything infrastructural. Cyberia-specific work belongs
+in the `cyberia` CLI, never in parallel platform commands. When a concern already exists in `underpost`,
+reuse it instead of forking a Cyberia variant.
+
+---
+
+## 2. PWA workflow
+
+Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
+inputs:
+
+- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
+- the service worker source in `src/client/sw/core.sw.js`
+
+Everything else — `index.html` pages, `sw.js`, the precache list — is **generated** during the client
+build. Treat them as outputs only; never hand-edit them.
+
+Runtime service-worker behavior:
+
+| Request       | Strategy                         |
+| ------------- | -------------------------------- |
+| static assets | stale-while-revalidate           |
+| API `GET`     | network-first + short cache      |
+| API mutations | network-only + background replay |
+| navigation    | network-first + fallback shells  |
+
+Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
+fallback view. Only fallback-marked views are guaranteed precached.
+
+---
+
+## 3. Cyberia MMO extension
+
+### Responsibility split
+
+| Service          | Owns                                                                      | Must not own                                  |
+| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy       |
+| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication  | content authority, presentation metadata      |
+| `cyberia-client` | rendering, input, prediction, interpolation, presentation                 | authoritative world state, gameplay authority |
+
+Two boundaries are non-negotiable:
+
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
+
+### Data flow
+
+```text
+engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
+engine-cyberia ──REST──────────────────────────────▶ cyberia-client
+```
+
+### `engine-cyberia` as the sidecar-backed data layer
+
+`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
+
+- Boot-time world configuration flows from `engine-cyberia` to `cyberia-server` over gRPC `GetFullInstance`.
+- Client-facing assets, object layers, dialogues, and presentation hints flow from `engine-cyberia` to `cyberia-client` over REST.
+- Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.
+
+### Runtime / health model
+
+Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.
+
+```text
+        ┌──────────────────────────────────────────────────────────────┐
+        │                    SUPERVISION (parallel)                      │
+        │                                                                │
+        │   engine-cyberia        cyberia-server        cyberia-client   │
+        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
+        │   │  monitor   │        │  monitor   │        │  monitor   │   │
+        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
+        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
+        │         │                     │                     │          │
+        │         └──────────┬──────────┴──────────┬──────────┘          │
+        │                    ▼                     ▼                     │
+        │            all three up & connected?                          │
+        └────────────────────────────┬─────────────────────────────────┘
+                                      │
+                ┌─────────────────────┼─────────────────────┐
+                ▼                     ▼                     ▼
+          ┌───────────┐        ┌───────────┐         ┌───────────┐
+          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
+          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
+          │ gameplay  │        │ reconnect-│         │ paused    │
+          │ live      │        │ ing / down│         │ until all │
+          │           │        │           │         │ 3 healthy │
+          └───────────┘        └───────────┘         └───────────┘
+```
+
+| State      | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `healthy`  | all three Cyberia services are up and connected                      |
+| `degraded` | at least one service is reconnecting or unavailable                  |
+| `standby`  | gameplay is paused because the full three-service set is not healthy |
+
+---
+
+## User commands
+
+Use `underpost` for platform, infrastructure, build, and deploy. Use `cyberia` for MMO content and
+extension workflows. Both share the same helpers — never duplicate config, env, or path logic.
+
+### Platform (underpost)
+
+```bash
+# Bootstrap a new app (local app serves on http://localhost:4001)
+underpost new app-name
+
+# Build the client bundle / static + PWA output
+underpost client
+npm run build            # node bin client
+
+# Deploy and operate
+underpost deploy <deploy-id>
+underpost monitor
+```
+
+### Cyberia (cyberia) — `bin/cyberia.js`
+
+| Group          | Command                                | Purpose                                                  |
+| -------------- | -------------------------------------- | -------------------------------------------------------- |
+| `ol`           | `cyberia ol [item-id]`                 | ObjectLayer import, procedural generation, atlas/sprite  |
+| `instance`     | `cyberia instance [instance-code]`     | export / import / drop a Cyberia instance and its data   |
+| `client-hints` | `cyberia client-hints [instance-code]` | per-instance presentation hints (palette, camera, icons) |
+| `chain`        | `cyberia chain <sub>`                  | Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle   |
+| `run-workflow` | `cyberia run-workflow <name>`          | named maintenance/build scripts from `scripts/`          |
+
+Common examples:
+
+```bash
+# Object layer content
+cyberia ol hatchet,sword --import                 # import specific items
+cyberia ol --import-types skin,floors             # batch import by type (or: all)
+cyberia ol floor-desert --generate --seed fx-42   # procedural generation
+cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
+cyberia ol --drop --client-public                 # drop data + static asset folders
+
+# Instance data
+cyberia instance FOREST --export ./backup
+cyberia instance FOREST --import ./backup
+cyberia instance FOREST --drop
+
+# Presentation hints
+cyberia client-hints cyberia-main --seed-defaults
+
+# Chain / token lifecycle
+cyberia chain deploy --chain-id 777771
+cyberia chain status
+cyberia chain register / mint / transfer / burn / pause / unpause
+
+# Named workflows
+cyberia run-workflow import-default-items
+cyberia run-workflow seed-skills
+cyberia run-workflow seed-dialogues
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
+```
+
+### Run the MMO services
+
+```bash
+# engine-cyberia (Node.js data/content services)
+npm start                                          # node src/server
+
+# cyberia-server (Go authoritative simulation)
+cd cyberia-server && go run main.go                # dev
+cd cyberia-server && go build -o cyberia-server . && ./cyberia-server
+
+# cyberia-client (C / WASM presentation)
+cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
+cd cyberia-client && make -f Web.mk serve-development     # serves on :8082
+```
+
+---
+
+## Operational guardrails
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts (`sw.js`, static pages, atlases, README, manifests) as outputs only.
+- Host-level changes must be idempotent, reversible, and explicit; validate before mutating; keep
+  orchestration scripts safe to rerun.
+- `engine-private/` is a private external dependency. Reference it only as private input; never assume
+  its contents exist locally.