cyberia 3.2.5 → 3.2.12

package/README.md

@@ -1,672 +1,259 @@
-<p align="center">
-  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine CLI"/>
-</p>
-
 <div align="center">
 
-<h1>cyberia</h1>
-
-<h2>Network Object Layer Engine CLI</h2>
-
-[![Downloads](https://img.shields.io/npm/dm/cyberia.svg)](https://www.npmjs.com/package/cyberia) [![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
-
-</div>
-
-This Command Line Interface (CLI) is a core tool for the **Cyberia Network Object Layer Engine**, specifically designed for processing, generating, and managing game assets, primarily **Object Layer** elements like skins, floors, and weapons.
-
-It handles image asset quantization, generates data matrices and color palettes, creates separate render frame documents, and persists the resulting structured data into the game's database with top-level references to render frames and atlas sprite sheets.
-
-## What this tool does
-
-The CLI scans the local asset folders (`./src/client/public/cyberia/assets/{type}/{id}/{direction}/{frame}`), quantizes images to a tile matrix and color palette, creates separate ObjectLayerRenderFrames documents, and persists the resulting object-layer documents with references to your configured MongoDB. It also supports reconstructing a visual PNG from the stored matrix for inspection.
-
-Key features:
-
-- Walks the asset directory structure and processes PNG/GIF files.
-- Produces `frame_matrix` and `map_color` arrays from images.
-- **Procedurally generates object layers** from semantic item-id descriptors with deterministic seeds and temporal coherence.
-- Saves processed objects to the `ObjectLayer` model with top-level references to `ObjectLayerRenderFrames`.
-- Creates separate `ObjectLayerRenderFrames` documents for render data.
-- Links ObjectLayers to AtlasSpriteSheet documents via top-level `atlasSpriteSheetId`.
-- Generates unique UUID v4 seeds (via `crypto.randomUUID()`) for SHA256 hash uniqueness.
-- Generates SHA256 hash using `fast-json-stable-stringify` for deterministic serialization.
-- Reconstructs PNG frames from stored tile data for debugging.
-- Writes static asset PNGs, atlas sprite sheets, and metadata to the conventional directory structure.
-- **Drop and cleanup** — removes ObjectLayer, RenderFrames, AtlasSpriteSheet, File documents and unpins IPFS CIDs. Supports targeted drop (specific items) or full drop.
-- **Static asset cleanup** — optionally removes client-side static asset folders and runs git-clean on the asset directory.
-- **IPFS integration** — pins CIDs to IPFS Cluster and Kubo, manages MFS paths, and unpins on drop.
-- **Blockchain integration** — deploys Besu IBFT2 networks, manages ERC-1155 tokens (register, mint, transfer, burn), and resolves canonical CIDs from MongoDB for on-chain registration.
-- **Cut-over consistency** — stages all IPFS operations, file creation, and atlas generation in-memory before atomically updating live MongoDB documents.
-
-## Getting Started
-
-### Prerequisites
-
-You must have the following installed in your environment:
-
-- **Node.js** (v24.10.0 recommended)
-- **npm** or **yarn**
-- **MongoDB** (or access to the configured MongoDB instance)
-
-### **Installation**
-
-```bash
-
-npm install -g cyberia
-```
-
-### **Environment Setup**
-
-Ensure your required environment variables (e.g., `DEFAULT_DEPLOY_ID`, `DEFAULT_DEPLOY_HOST`, `DEFAULT_DEPLOY_PATH`) are correctly configured, typically in a .env file, to point the CLI to the correct database instance defined in conf.server.json.
-
-## Usage
-
-The CLI is executed from the project root via the `cyberia.js` script.
-
-### Import specific items with `--import`
-
-Import one or more object layers by item-id. The CLI searches all asset type directories for matching items.
-
-```bash
-# Import a single item
-cyberia ol hatchet --import
-
-# Import multiple items (comma-separated)
-cyberia ol hatchet,sword,shield --import
-```
-
-### Batch import by type with `--import-types`
-
-Iterate asset folders for the given types and store processed objects in MongoDB.
-
-```bash
-# Process specific types (comma-separated)
-cyberia ol --import-types skin,floor
-
-# Process all recognized types (skips items that already exist in the database)
-cyberia ol --import-types all
-```
-
-### Procedural generation with `--generate`
-
-Produces semantically consistent object layers with controlled, reproducible variation and short-term temporal coherence (consecutive frames stay visually consistent). Uses the parametric shape generator and object layer engine under the hood.
-
-```bash
-# Generate a desert floor tile (single frame, auto seed)
-cyberia ol floor-desert --generate
-
-# Full control: 3 frames, explicit seed, density
-cyberia ol floor-desert --generate --count 3 --seed fx-42 --frame-index 0 --frame-count 3 --density 0.5
-
-# Grass terrain, sparse, 5 frames
-cyberia ol floor-grass --generate --seed meadow-7 --frame-count 5 --density 0.3
-
-# Water surface, dense, high element count
-cyberia ol floor-water --generate --seed ocean-1 --count 5 --density 0.8 --frame-count 4
-
-# Stone cobblestone
-cyberia ol floor-stone --generate --seed cobble-99 --count 4 --density 0.6
-
-# Lava flow, 3-frame animation
-cyberia ol floor-lava --generate --seed magma-3 --frame-count 3 --density 0.7
-
-# Skin: random skin tone and hair
-cyberia ol skin-random --generate --seed hero-1 --frame-count 4
-
-# Skin: dark skin only
-cyberia ol skin-dark --generate --seed hero-dark-7
-
-# Skin: light/pale skin only
-cyberia ol skin-light --generate --seed hero-light-3 --frame-count 4
-
-# Skin: any skin tone with vivid (blue/red/green…) hair
-cyberia ol skin-vivid --generate --seed hero-vivid-2
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
 
-# Skin: any skin tone with natural hair only (brown, blond, grey…)
-cyberia ol skin-natural --generate --seed hero-nat-5 --frame-count 4
+<h1>CYBERIA</h1>
 
-# Skin: shaved / bald head (no hair at all)
-cyberia ol skin-shaved --generate --seed hero-bald-1 --frame-count 4
-```
-
-**`--generate` options:**
-
-| Option              | Default   | Description                                         |
-| ------------------- | --------- | --------------------------------------------------- |
-| `--seed <str>`      | auto UUID | Deterministic seed string. Same seed → same output. |
-| `--count <n>`       | `3`       | Shape element count multiplier per layer.           |
-| `--frame-index <n>` | `0`       | Starting frame index.                               |
-| `--frame-count <n>` | `1`       | Number of consecutive frames to generate.           |
-| `--density <f>`     | `0.5`     | Overall density factor (`0`–`1`). Lower = sparser.  |
-
-**Available semantic item-id prefixes:**
-
-| Prefix         | Type  | Tags                 | Palette                    |
-| -------------- | ----- | -------------------- | -------------------------- |
-| `floor-desert`  | floor | sand, dune, arid      | warm ochres, sand tones              |
-| `floor-grass`   | floor | grass, meadow, earth  | greens, earth browns                 |
-| `floor-water`   | floor | water, ocean, wave    | blues, foam whites                   |
-| `floor-stone`   | floor | stone, rock, cobble   | greys, warm/cool stone               |
-| `floor-lava`    | floor | lava, magma, fire     | reds, oranges, dark crust            |
-| `skin-random`   | skin  | character, body       | any skin tone, any hair              |
-| `skin-dark`     | skin  | character, body       | dark/melanin-rich skin only          |
-| `skin-light`    | skin  | character, body       | light/pale skin only                 |
-| `skin-vivid`    | skin  | character, body       | any skin + vivid hair (blue, red…)   |
-| `skin-natural`  | skin  | character, body       | any skin + natural hair (brown…)     |
-| `skin-shaved`   | skin  | character, body       | any skin, bald/shaved head           |
-
-#### How generation works
-
-Each item-id maps to a **semantic descriptor** that provides `semanticTags`, `paletteHints`, `preferredShapes`, and named **layer specs** (e.g. `base`, `dunes`, `rocks`, `tufts` for `floor-desert`).
-
-**Seed derivation** — deterministic at every level:
-
-```
-layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
-frameSeed  = hash(layerSeed + ':' + frameIndex)
-```
-
-**Temporal coherence** — shape topology (which shapes, how many, where) is locked to `layerSeed` and never changes between frames. Only smooth, low-frequency noise perturbations (position jitter, slight rotation/scale wobble) are derived from `frameSeed`, so frame N and N+1 differ by ~2% of cells.
-
-**Layer naming** — every generated layer gets an id: `<itemId>-<layerKey>` (e.g. `floor-desert-dunes`).
-
-**Generation pipeline per layer:**
-
-1. Pick generator type (`noise-field` for base fills, `shape` for element placement).
-2. Select palette colors deterministically from `paletteHints` with per-element `colorShift`.
-3. For shape layers: pick shape via weighted `preferredShapes`, compute stable base transform `(x, y, scale, rotation)`, apply frame-level smooth noise.
-4. Stamp shapes onto a 24×24 grid via `intCoords` rasterization from the parametric shape generator.
-5. Composite all layers into a final `frame_matrix` + unified `colors` palette.
-
-**Variability factors per layer:**
-`scaleVariance`, `rotationVariance`, `colorShift`, `jitter`, `noiseLevel`, `detailLevel`, `sparsity` — small, deterministic variations that keep each generation unique but semantically coherent.
-
-#### What `--generate` persists
-
-The full pipeline runs automatically:
-
-1. **Static assets** — PNGs written to `./src/client/public/cyberia/assets/{type}/{itemId}/{dirCode}/{frame}.png` + `metadata.json`.
-2. **MongoDB** — `ObjectLayerRenderFrames` + `ObjectLayer` documents created with SHA-256 hash.
-3. **Atlas sprite sheet** — generated, saved to `File` + `AtlasSpriteSheet` collections, and linked via `atlasSpriteSheetId`.
-
-#### Reproducibility example
-
-Running the same command twice produces byte-identical output:
-
-```bash
-# Run 1
-cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
-
-# Run 2 (identical output)
-cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
-```
+**Network Object Layers**
 
-Different seeds produce different but semantically consistent results:
+_Stackable Rendering Layers as a Unified Tokenized Reality_
 
-```bash
-cyberia ol floor-desert --generate --seed fx-42   # variant A
-cyberia ol floor-desert --generate --seed fx-99   # variant B (same style, different arrangement)
-```
-
-### Drop and cleanup with `--drop`
-
-Removes object layer data from MongoDB and IPFS. Supports both targeted (specific items) and full drop.
-
-```bash
-# Drop specific items by item-id
-cyberia ol anon,skin --drop
-
-# Drop all object layers before re-importing
-cyberia ol --drop --import-types all
-```
-
-**What `--drop` removes per item:**
-
-- `ObjectLayer` document
-- `ObjectLayerRenderFrames` document
-- `AtlasSpriteSheet` document
-- Associated `File` documents
-- IPFS CID pins (objectLayer.cid, render.cid, render.metadataCid, AtlasSpriteSheet.cid) from both IPFS Cluster and Kubo
-- MFS paths (`/object-layer/{itemKey}`)
-
-**`--drop` companion flags:**
-
-| Flag              | Description                                                                                                                                 |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--client-public` | Also remove static asset folders: `./src/client/public/cyberia/assets/{type}/{itemId}/` and `./public/{host}{path}/assets/{type}/{itemId}/` |
-| `--git-clean`     | Run `underpost run clean .` on the `src/client/public/cyberia` directory to remove untracked files                                          |
-
-```bash
-# Drop items and remove their static asset folders
-cyberia ol anon --drop --client-public
-
-# Full rebuild: drop everything, clean assets, re-import all
-cyberia ol --drop --git-clean --import-types all
-```
-
-### Environment and database flags
-
-These flags apply to both `ol` and `chain` commands where database or environment access is needed.
-
-| Flag                         | Default  | Description                                                                   |
-| ---------------------------- | -------- | ----------------------------------------------------------------------------- |
-| `--env-path <path>`          | `./.env` | Path to .env file (e.g., `./engine-private/conf/dd-cyberia/.env.development`) |
-| `--mongo-host <host>`        | —        | MongoDB host override                                                         |
-| `--storage-file-path <path>` | —        | Storage file path override (JSON filter for selective import)                 |
-| `--dev`                      | `false`  | Force development environment (loads `.env.development` for IPFS localhost)   |
-
-```bash
-# Import using a specific environment
-cyberia ol --import-types all --env-path ./engine-private/conf/dd-cyberia/.env.development
-
-# Use development IPFS localhost
-cyberia ol anon --import --dev
-
-# Override MongoDB host
-cyberia ol --import-types skin --mongo-host mongodb://localhost:27017
-```
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
 
-## Visualize a processed frame
-
-Reconstructs and opens a PNG from the database-stored frame data. Requires item-id as the first positional argument, followed by direction and frame index in the format `[direction]_[frameIndex]`.
-
-```bash
-# Show frame with default direction and frame (08_0)
-cyberia ol anon --show-frame
-
-# Show specific direction and frame
-cyberia ol anon --show-frame 08_0
-
-# Show different directions
-cyberia ol anon --show-frame 02_0  # up_idle
-cyberia ol anon --show-frame 04_1  # left_idle (second frame)
-```
-
-**Valid direction codes:**
-
-- `08`: down_idle, none_idle, default_idle
-- `18`: down_walking
-- `02`: up_idle
-- `12`: up_walking
-- `04`: left_idle, up_left_idle, down_left_idle
-- `14`: left_walking, up_left_walking, down_left_walking
-- `06`: right_idle, up_right_idle, down_right_idle
-- `16`: right_walking, up_right_walking, down_right_walking
-
-This command:
-
-- Finds the ObjectLayer by item-id
-- Loads the associated ObjectLayerRenderFrames document
-- Reconstructs the PNG from the stored `frame_matrix` and `map_color`
-- Saves it temporarily to disk as `{item-id}_{direction}_{frame}.png`
-- Opens it with Firefox for visual inspection
-
-### Generate Atlas Sprite Sheet
-
-Consolidates all frames (8 directions, multiple modes) from an object layer's render frames into a single optimized PNG atlas with metadata.
-
-```bash
-# Generate atlas sprite sheet with auto-calculated dimensions (recommended)
-cyberia ol anon --to-atlas-sprite-sheet
-
-# Generate atlas with custom dimensions (manual override)
-cyberia ol anon --to-atlas-sprite-sheet 4096
-
-
-```
-
-This command:
-
-- Finds the ObjectLayer by item-id or MongoDB `_id`
-- Loads the associated ObjectLayerRenderFrames document
-- **Auto-calculates optimal atlas dimensions** based on total frame count (8 directions × all animation modes)
-- Generates a consolidated PNG with all animation frames properly arranged
-- Stores the PNG in the File collection
-- Creates/updates an AtlasSpriteSheet document with frame positions
-- Updates the ObjectLayer with top-level `atlasSpriteSheetId` reference
-- Uses power-of-2 dimensions for GPU efficiency
-
-**Atlas Dimension Calculation:**
-
-- **Auto (default)**: Dynamically calculates optimal size based on:
-  - Total number of frames across all directions and modes
-  - Individual frame dimensions
-  - Grid layout to minimize wasted space
-  - Power-of-2 optimization (1024, 2048, 4096, etc.)
-- **Manual override**: Specify exact dimension (e.g., `--to-atlas-sprite-sheet 4096`)
-
-**Common Atlas Sizes:**
-
-- **1024x1024**: ~6-10 frames
-- **2048x2048**: ~20-40 frames (typical for character sprites)
-- **4096x4096**: ~80-160 frames (complex animations)
-- **8192x8192**: Maximum, for extreme cases
-
-The tool automatically warns if frames exceed the specified dimension and suggests a larger size.
-
-### View Atlas Sprite Sheet
-
-Opens the consolidated atlas sprite sheet PNG for inspection.
-
-```bash
-# Show atlas sprite sheet by item-id
-cyberia ol anon --show-atlas-sprite-sheet
-
-```
-
-This command:
-
-- Finds the ObjectLayer by item-id
-- Retrieves the associated AtlasSpriteSheet via top-level `atlasSpriteSheetId` or by matching `metadata.itemKey`
-- Saves it temporarily to disk
-- Opens it with Firefox for visual inspection
-- Displays atlas dimensions in the console
-
-## Common Workflows
-
-### Complete Asset Processing Pipeline
-
-Process assets from source files through to atlas generation:
-
-```bash
-# 1. Import object layers from asset directories
-cyberia ol --import-types skin
-
-# 2. Verify a specific frame was imported correctly
-cyberia ol anon --show-frame 08_0
-
-# 3. Generate optimized atlas sprite sheet
-cyberia ol anon --to-atlas-sprite-sheet
-
-# 4. View the generated atlas
-cyberia ol anon --show-atlas-sprite-sheet
-```
-
-### Procedural Generation Pipeline
-
-Generate an object layer entirely from a semantic descriptor — no source PNGs needed:
-
-```bash
-# 1. Generate a 3-frame desert floor with explicit seed
-cyberia ol floor-desert --generate --seed fx-42 --frame-count 3 --density 0.5
-
-# 2. Inspect the generated frame
-cyberia ol floor-desert --show-frame 08_0
-
-# 3. View the auto-generated atlas
-cyberia ol floor-desert --show-atlas-sprite-sheet
-```
-
-### Batch Procedural Generation
-
-Generate a full tileset family with consistent seeds:
-
-```bash
-cyberia ol floor-desert --generate --seed world-1 --frame-count 3
-cyberia ol floor-grass  --generate --seed world-1 --frame-count 3
-cyberia ol floor-water  --generate --seed world-1 --frame-count 4
-cyberia ol floor-stone  --generate --seed world-1 --frame-count 2
-cyberia ol floor-lava   --generate --seed world-1 --frame-count 3
-```
-
-### Exploring Seed Variations
-
-```bash
-# Same item, different seeds — compare visual output
-cyberia ol floor-desert --generate --seed alpha  --frame-count 1
-cyberia ol floor-desert --generate --seed beta   --frame-count 1
-cyberia ol floor-desert --generate --seed gamma  --frame-count 1
-
-# Inspect each
-cyberia ol floor-desert --show-frame 08_0
-```
-
-### Debugging Asset Issues
+</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.
 
-```bash
-# Check if frame data is correct for all directions
-cyberia ol anon --show-frame 08_0  # down_idle
-cyberia ol anon --show-frame 02_0  # up_idle
-cyberia ol anon --show-frame 04_0  # left_idle
-cyberia ol anon --show-frame 06_0  # right_idle
-
-# Verify walking animations
-cyberia ol anon --show-frame 18_0  # down_walking
-cyberia ol anon --show-frame 12_0  # up_walking
-cyberia ol anon --show-frame 14_0  # left_walking
-cyberia ol anon --show-frame 16_0  # right_walking
-```
+---
 
-### Working with Multiple Items
+## Ecosystem at a glance
 
-```bash
-# Import multiple types at once
-cyberia ol --import-types skin,floor,weapon
-
-# Process individual items
-cyberia ol sword --show-frame 08_0
-cyberia ol sword --to-atlas-sprite-sheet
-cyberia ol shield --show-frame 08_0
-cyberia ol shield --to-atlas-sprite-sheet
-```
+```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     │ ║
+   ║                                                          └──────────────────┘ ║
+   ╚═══════════════════════════════════════════════════════════════════════════════╝
 
-### Full Rebuild with Cleanup
+   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.
 
-Drop all data, clean static assets, and re-import everything:
+---
 
-```bash
-# 1. Drop all object layers with IPFS cleanup and static asset removal
-cyberia ol --drop --client-public --git-clean
+## 2. PWA workflow
 
-# 2. Re-import all asset types
-cyberia ol --import-types all
+Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
+inputs:
 
-# 3. Verify
-cyberia ol anon --show-frame 08_0
-```
+- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
+- the service worker source in `src/client/sw/core.sw.js`
 
-### Targeted Drop and Re-import
+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.
 
-Drop and re-import specific items without affecting others:
+Runtime service-worker behavior:
 
-```bash
-# 1. Drop specific items and their static folders
-cyberia ol anon,skin --drop --client-public
+| Request       | Strategy                         |
+| ------------- | -------------------------------- |
+| static assets | stale-while-revalidate           |
+| API `GET`     | network-first + short cache      |
+| API mutations | network-only + background replay |
+| navigation    | network-first + fallback shells  |
 
-# 2. Re-import only those items
-cyberia ol anon,skin --import
+Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
+fallback view. Only fallback-marked views are guaranteed precached.
 
-# 3. Regenerate atlas for each
-cyberia ol anon --to-atlas-sprite-sheet
-cyberia ol skin --to-atlas-sprite-sheet
-```
+---
 
-## Blockchain Operations (`chain`)
+## 3. Cyberia MMO extension
 
-The `chain` command group manages Hyperledger Besu IBFT2 network deployment and ERC-1155 token operations for on-chain object layer registration.
+### Responsibility split
 
-### Deploy Besu IBFT2 Network
+| 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 |
 
-Deploys a private Besu IBFT2 network to Kubernetes.
+Two boundaries are non-negotiable:
 
-```bash
-# Deploy with defaults (4 validators, chain-id 777771)
-cyberia chain deploy
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
 
-# Custom configuration
-cyberia chain deploy --validators 6 --chain-id 888881 --block-period 3
+### Data flow
 
-# Pull container images first
-cyberia chain deploy --pull-image
+```text
+engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
+engine-cyberia ──REST──────────────────────────────▶ cyberia-client
 ```
 
-**`deploy` options:**
-
-| Option                      | Default                    | Description                                        |
-| --------------------------- | -------------------------- | -------------------------------------------------- |
-| `--validators <count>`      | `4`                        | Number of IBFT2 validators                         |
-| `--chain-id <id>`           | `777771`                   | Chain ID for the network                           |
-| `--block-period <seconds>`  | `5`                        | IBFT2 block period in seconds                      |
-| `--epoch-length <length>`   | `30000`                    | IBFT2 epoch length                                 |
-| `--coinbase-address <addr>` | auto-detect                | Coinbase deployer address                          |
-| `--besu-image <image>`      | `hyperledger/besu:24.12.1` | Besu container image                               |
-| `--curl-image <image>`      | `curlimages/curl:8.11.1`   | Curl init container image                          |
-| `--node-port-rpc <port>`    | `30545`                    | NodePort for external JSON-RPC access              |
-| `--node-port-ws <port>`     | `30546`                    | NodePort for external WebSocket access             |
-| `--namespace <ns>`          | `besu`                     | Kubernetes namespace for Besu resources            |
-| `--pull-image`              | `false`                    | Pull Besu container images before deployment       |
-| `--skip-generate`           | `false`                    | Skip manifest generation, use existing manifests   |
-| `--skip-wait`               | `false`                    | Skip waiting for validators to reach Running state |
-
-### Remove Besu Network
+### `engine-cyberia` as the sidecar-backed data layer
 
-```bash
-# Remove network (keep keys and manifests)
-cyberia chain remove
+`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
 
-# Full cleanup
-cyberia chain remove --clean-keys --clean-manifests
-```
+- 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.
 
-| Option              | Default | Description                                         |
-| ------------------- | ------- | --------------------------------------------------- |
-| `--namespace <ns>`  | `besu`  | Kubernetes namespace for Besu resources             |
-| `--clean-keys`      | `false` | Also remove generated validator keys                |
-| `--clean-manifests` | `false` | Also remove the generated manifests/besu/ directory |
+### Runtime / health model
 
-### Generate Manifests Without Deploying
+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.
 
-```bash
-cyberia chain generate-manifests --validators 6 --output-dir ./manifests/besu
+```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 │
+          └───────────┘        └───────────┘         └───────────┘
 ```
 
-Accepts the same options as `deploy` plus `--output-dir <dir>` (default: `./manifests/besu`).
+| 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 |
 
-### Deploy ERC-1155 Contract
+---
 
-```bash
-cyberia chain deploy-contract
-cyberia chain deploy-contract --network besu-k8s
-```
-
-### Compile and Test Contracts
-
-```bash
-cyberia chain compile
-cyberia chain test
-```
+## User commands
 
-### Register Object Layer Item On-Chain
+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.
 
-Registers an object layer as an ERC-1155 token with its canonical CID.
+### Platform (underpost)
 
 ```bash
-# Register with CID resolved from MongoDB (recommended)
-cyberia chain register --item-id hatchet --from-db
+# Bootstrap a new app (local app serves on http://localhost:4001)
+underpost new app-name
 
-# Register with explicit CID
-cyberia chain register --item-id hatchet --metadata-cid bafk...
+# Build the client bundle / static + PWA output
+underpost client
+npm run build            # node bin client
 
-# Semi-fungible with supply
-cyberia chain register --item-id wood --from-db --supply 500000
+# Deploy and operate
+underpost deploy <deploy-id>
+underpost monitor
 ```
 
-| Option                 | Default    | Required | Description                                             |
-| ---------------------- | ---------- | -------- | ------------------------------------------------------- |
-| `--item-id <itemId>`   | —          | yes      | Human-readable item identifier                          |
-| `--metadata-cid <cid>` | —          | —        | IPFS metadata CID (ignored when `--from-db` is set)     |
-| `--from-db`            | `false`    | —        | Resolve canonical CID from MongoDB ObjectLayer document |
-| `--supply <supply>`    | `1`        | —        | Initial token supply (1 = NFT, >1 = semi-fungible)      |
-| `--network <network>`  | `besu-k8s` | —        | Hardhat network name                                    |
-| `--env-path <path>`    | `./.env`   | —        | Path to .env file                                       |
-| `--mongo-host <host>`  | —          | —        | MongoDB host override                                   |
+### Cyberia (cyberia) — `bin/cyberia.js`
 
-### Batch Register Multiple Items
+| 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/`          |
 
-```bash
-# Batch register with CIDs from MongoDB
-cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"hatchet","supply":1}]'
-
-# Batch register with explicit CIDs
-cyberia chain batch-register --items '[{"itemId":"wood","cid":"bafk...","supply":500000}]'
-```
-
-### Mint, Transfer, and Burn Tokens
+Common examples:
 
 ```bash
-# Mint additional tokens
-cyberia chain mint --token-id 1 --to 0xAddress --amount 100
-
-# Transfer tokens
-cyberia chain transfer --from 0xSender --to 0xRecipient --token-id 1 --amount 50
+# 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
 
-# Burn tokens
-cyberia chain burn --address 0xHolder --token-id 1 --amount 10
-```
+# Instance data
+cyberia instance FOREST --export ./backup
+cyberia instance FOREST --import ./backup
+cyberia instance FOREST --drop
 
-### Query Status and Balances
+# Presentation hints
+cyberia client-hints cyberia-main --seed-defaults
 
-```bash
-# Full network and contract status
+# Chain / token lifecycle
+cyberia chain deploy --chain-id 777771
 cyberia chain status
+cyberia chain register / mint / transfer / burn / pause / unpause
 
-# Query token balance
-cyberia chain balance --address 0xAddress --token-id 0
+# Named workflows
+cyberia run-workflow import-default-items
+cyberia run-workflow seed-skill-config --instance-code default
+cyberia run-workflow seed-dialogues
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
 ```
 
-### Key Management
+### Run the MMO services
 
 ```bash
-# Generate a new Ethereum key pair
-cyberia chain key-gen
-
-# Generate and persist keys
-cyberia chain key-gen --save
+# engine-cyberia (Node.js data/content services)
+npm start                                          # node src/server
 
-# Set coinbase deployer key
-cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/0xAddr.key.json
-cyberia chain set-coinbase --private-key 0xHexKey
-```
-
-### Pause / Unpause Token Transfers (Emergency)
+# cyberia-server (Go authoritative simulation)
+cd cyberia-server && go run main.go                # dev
+cd cyberia-server && go build -o cyberia-server . && ./cyberia-server
 
-```bash
-cyberia chain pause
-cyberia chain unpause
+# 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
 ```
 
-## Workflow Import (`run-workflow`)
+---
 
-### Import Default Items
-
-Imports default Object Layer items from a JSON configuration file into MongoDB.
-
-```bash
-cyberia run-workflow import-default-items
-
-# Use development environment
-cyberia run-workflow import-default-items --dev
-```
+## Operational guardrails
 
-## Complete `ol` Command Reference
-
-| Flag                            | Type    | Default     | Description                                                |
-| ------------------------------- | ------- | ----------- | ---------------------------------------------------------- |
-| `--import`                      | boolean | `false`     | Import specific item(s) passed as comma-separated argument |
-| `--import-types [type]`         | string  | —           | Batch import by type: `skin`, `floors`, or `all`           |
-| `--show-frame [dir_frame]`      | string  | `08_0`      | View object layer frame (direction_frameIndex)             |
-| `--to-atlas-sprite-sheet [dim]` | number  | auto        | Generate atlas sprite sheet, optionally specify dimension  |
-| `--show-atlas-sprite-sheet`     | boolean | `false`     | Display the atlas sprite sheet PNG for an item             |
-| `--generate`                    | boolean | `false`     | Generate procedural object layers from semantic item-id    |
-| `--seed <str>`                  | string  | random UUID | Deterministic seed for `--generate`                        |
-| `--count <n>`                   | number  | `3`         | Shape element count multiplier for `--generate`            |
-| `--frame-index <n>`             | number  | `0`         | Starting frame index for `--generate`                      |
-| `--frame-count <n>`             | number  | `1`         | Number of frames for `--generate`                          |
-| `--density <f>`                 | number  | `0.5`       | Density factor (0–1) for `--generate`                      |
-| `--drop`                        | boolean | `false`     | Drop existing data (targeted or full)                      |
-| `--client-public`               | boolean | `false`     | With `--drop`, remove static asset folders                 |
-| `--git-clean`                   | boolean | `false`     | With `--drop`, run underpost clean on cyberia assets       |
-| `--dev`                         | boolean | `false`     | Force development environment                              |
-| `--env-path <path>`             | string  | `./.env`    | Path to .env file                                          |
-| `--mongo-host <host>`           | string  | —           | MongoDB host override                                      |
-| `--storage-file-path <path>`    | string  | —           | Storage file path override                                 |
+- 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.