cyberia 3.2.5 → 3.2.9

package/README.md

@@ -1,672 +1,417 @@
 <p align="center">
-  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine CLI"/>
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
 </p>
 
 <div align="center">
 
-<h1>cyberia</h1>
+### CYBERIA
 
-<h2>Network Object Layer Engine CLI</h2>
+**Network Object Layers**
 
-[![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)
+_Stackable Rendering Layers as a Unified Tokenized Reality_
 
-</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.
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
 
-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.
+</div>
 
-## What this tool does
+# Cyberia CLI
 
-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.
+**Path:** `bin/cyberia.js`
 
-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.
+## Overview
 
-## Getting Started
+The Cyberia CLI (`cyberia`) is an extension of the **Underpost CLI** specifically for the Cyberia MMORPG ecosystem. Underpost is the end-to-end bare-metal infrastructure platform for general-purpose applications; `cyberia` extends it with tooling for the game's content pipeline, economy, and MMO engine toolchain. Unrecognized commands are transparently passed through to `underpost` for infrastructure operations.
 
-### Prerequisites
+The CLI manages:
 
-You must have the following installed in your environment:
+- **Object Layer (`ol`)** — import, generate, and manage game item definitions and sprite atlases.
+- **Instance (`instance`)** — export/import/seed game instance data (maps, entities, configs).
+- **Chain (`chain`)** — Hyperledger Besu deployment and ERC-1155 ObjectLayerToken lifecycle.
+- **Run-Workflow (`run-workflow`)** — execute named operational scripts (seed defaults, build manifests).
 
-- **Node.js** (v24.10.0 recommended)
-- **npm** or **yarn**
-- **MongoDB** (or access to the configured MongoDB instance)
+---
 
-### **Installation**
+## Global Usage
 
 ```bash
-
-npm install -g cyberia
+node bin/cyberia.js <command> [subcommand] [options]
+# or if installed globally:
+cyberia <command> [subcommand] [options]
 ```
 
-### **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`
+## `cyberia ol` — Object Layer Management
 
-Import one or more object layers by item-id. The CLI searches all asset type directories for matching items.
+Manages the Object Layer content pipeline: import PNG assets, generate procedural layers, build atlas sprite sheets, and push to IPFS/MongoDB.
 
 ```bash
-# Import a single item
-cyberia ol hatchet --import
-
-# Import multiple items (comma-separated)
-cyberia ol hatchet,sword,shield --import
+cyberia ol [item-id] [options]
 ```
 
-### 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
-```
+### Options
 
-### Procedural generation with `--generate`
+| Option                          | Description                                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------------------------- |
+| `--import`                      | Import specific item-id(s) (comma-separated) from the PNG asset directory into MongoDB + IPFS |
+| `--import-types [types]`        | Batch import by type (e.g. `skin,floor`) or `all`                                             |
+| `--generate`                    | Generate procedural layers for a semantic item-id (see Semantic Registry below)               |
+| `--count <n>`                   | Shape element count multiplier for `--generate` (default: `3`)                                |
+| `--seed <seed>`                 | Deterministic seed string for `--generate` (e.g. `fx-42`)                                     |
+| `--frame-index <n>`             | Starting frame index for `--generate` (default: `0`)                                          |
+| `--frame-count <n>`             | Number of frames to generate for `--generate` (default: `1`)                                  |
+| `--density <0..1>`              | Shape density factor for `--generate` (default: `0.5`)                                        |
+| `--to-atlas-sprite-sheet [dim]` | Convert ObjectLayer frames to a consolidated atlas PNG                                        |
+| `--show-atlas-sprite-sheet`     | Display the atlas PNG for the given item-id                                                   |
+| `--show-frame [dir_frame]`      | View a single frame (e.g. `08_0`; default: `08_0`)                                            |
+| `--drop`                        | Drop existing data before importing                                                           |
+| `--client-public`               | With `--drop`: also remove static client asset folders                                        |
+| `--git-clean`                   | With `--drop`: run clean on the cyberia asset directory                                       |
+| `--dev`                         | Force development env (uses `.env.development` for localhost IPFS)                            |
+| `--env-path <path>`             | Path to `.env` file (e.g. `./engine-private/conf/dd-cyberia/.env.development`)                |
+| `--mongo-host <host>`           | MongoDB host override                                                                         |
+| `--storage-file-path <path>`    | Storage filter JSON path override                                                             |
 
-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.
+### Examples
 
 ```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
-
-# Skin: any skin tone with natural hair only (brown, blond, grey…)
-cyberia ol skin-natural --generate --seed hero-nat-5 --frame-count 4
-
-# Skin: shaved / bald head (no hair at all)
-cyberia ol skin-shaved --generate --seed hero-bald-1 --frame-count 4
-```
+# Import a single item from PNG source
+cyberia ol hatchet --import --env-path ./engine-private/conf/dd-cyberia/.env.development
 
-**`--generate` options:**
+# Import all items of type 'skin' and 'floor'
+cyberia ol --import-types skin,floor
 
-| 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.  |
+# Import all types
+cyberia ol --import-types all
 
-**Available semantic item-id prefixes:**
+# Generate a procedural floor tile (desert biome, seed fx-42)
+cyberia ol floor-desert --generate --seed fx-42
 
-| 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           |
+# Generate 4 frames of a procedural floor with custom count and density
+cyberia ol floor-grass --generate --frame-count 4 --count 5 --density 0.7
 
-#### How generation works
+# Generate a character skin
+cyberia ol skin-dark-001 --generate --seed my-seed
 
-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`).
+# View a specific frame of an item
+cyberia ol hatchet --show-frame 08_0
 
-**Seed derivation** — deterministic at every level:
+# Rebuild atlas sprite sheet for an item
+cyberia ol hatchet --to-atlas-sprite-sheet
 
-```
-layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
-frameSeed  = hash(layerSeed + ':' + frameIndex)
+# Drop and re-import a single item
+cyberia ol hatchet --drop --import
 ```
 
-**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`).
+## Semantic Item-ID Registry
 
-**Generation pipeline per layer:**
+The `--generate` flag uses item-id prefixes to look up a procedural descriptor from the semantic registry.
 
-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.
+### Floor Prefixes
 
-**Variability factors per layer:**
-`scaleVariance`, `rotationVariance`, `colorShift`, `jitter`, `noiseLevel`, `detailLevel`, `sparsity` — small, deterministic variations that keep each generation unique but semantically coherent.
+| Prefix         | Biome  | Description                                     |
+| -------------- | ------ | ----------------------------------------------- |
+| `floor-desert` | Desert | Sandy, arid tile with warm yellow/brown palette |
+| `floor-grass`  | Grass  | Meadow tile with green/earth tones              |
+| `floor-water`  | Water  | Ocean/lake tile with blue/teal palette          |
+| `floor-stone`  | Stone  | Rock/cobble tile with grey palette              |
+| `floor-lava`   | Lava   | Magma tile with red/orange palette              |
 
-#### What `--generate` persists
+### Skin Prefixes
 
-The full pipeline runs automatically:
+| Prefix         | Description                                     |
+| -------------- | ----------------------------------------------- |
+| `skin-random`  | Fully random skin tone and hair                 |
+| `skin-dark`    | Dark skin tones                                 |
+| `skin-light`   | Light / pale skin tones                         |
+| `skin-vivid`   | Vivid / exotic hair colours (blue, red, green…) |
+| `skin-natural` | Natural hair colours (brown, blond, grey…)      |
+| `skin-shaved`  | Shaved / bald head — no hair                    |
 
-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`.
+### Resource Prefixes
 
-#### Reproducibility example
+Resource prefixes follow the pattern `resource-{biome}-{shape}`:
 
-Running the same command twice produces byte-identical output:
+| Shape Family | Description                            |
+| ------------ | -------------------------------------- |
+| `petal`      | Parabolic arc shapes — coloured petals |
+| `stone`      | Hard, angular mineral shapes           |
+| `polygon`    | Crystal/geometric faceted shapes       |
+| `thread`     | Thin, wispy Bézier lines               |
 
-```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
-```
+**Biomes:** `desert`, `grass`, `water`, `stone`, `lava`
 
-Different seeds produce different but semantically consistent results:
+**Full matrix (20 prefixes):**
 
-```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)
 ```
+resource-desert-petal    resource-grass-petal    resource-water-petal
+resource-desert-stone    resource-grass-stone    resource-water-stone
+resource-desert-polygon  resource-grass-polygon  resource-water-polygon
+resource-desert-thread   resource-grass-thread   resource-water-thread
 
-### 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
+resource-stone-petal     resource-lava-petal
+resource-stone-stone     resource-lava-stone
+resource-stone-polygon   resource-lava-polygon
+resource-stone-thread    resource-lava-thread
 ```
 
-**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:**
+## `cyberia instance` — Instance Management
 
-| 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                                          |
+Manages game instance documents (maps, entities, actions, quests, skill config) in MongoDB.
 
 ```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
+cyberia instance [instance-code] [options]
 ```
 
-### Environment and database flags
+### Options
 
-These flags apply to both `ol` and `chain` commands where database or environment access is needed.
+| Option                | Description                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--export [path]`     | Export instance and all related documents to a backup directory                                                   |
+| `--import [path]`     | Import instance documents from a backup directory (upsert, preserves UUIDs)                                       |
+| `--conf`              | With `--export`/`--import`: only process instance and instance-conf documents (skip maps, entities, ObjectLayers) |
+| `--drop`              | Drop all documents associated with the instance code                                                              |
+| `--env-path <path>`   | Path to `.env` file                                                                                               |
+| `--mongo-host <host>` | MongoDB host override                                                                                             |
+| `--dev`               | Force development environment                                                                                     |
 
-| 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)   |
+### Examples
 
 ```bash
-# Import using a specific environment
-cyberia ol --import-types all --env-path ./engine-private/conf/dd-cyberia/.env.development
+# Export instance to backup
+cyberia instance cyberia-main --export ./backups/cyberia-main
 
-# Use development IPFS localhost
-cyberia ol anon --import --dev
+# Import instance from backup
+cyberia instance cyberia-main --import ./backups/cyberia-main
 
-# Override MongoDB host
-cyberia ol --import-types skin --mongo-host mongodb://localhost:27017
+# Drop instance data
+cyberia instance cyberia-main --drop
 ```
 
-## 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:**
+## `cyberia chain` — Blockchain Lifecycle
 
-- `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
+Full lifecycle management for the Hyperledger Besu network and `ObjectLayerToken` ERC-1155 contract.
 
-This command:
+### Network Commands
 
-- 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
+#### `cyberia chain deploy`
 
-### 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.
+Deploy a new Hyperledger Besu IBFT2 network to Kubernetes:
 
 ```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
-
-
+cyberia chain deploy [options]
 ```
 
-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:**
+| Option                   | Default                    | Description                               |
+| ------------------------ | -------------------------- | ----------------------------------------- |
+| `--validators <n>`       | `4`                        | Number of IBFT2 validators                |
+| `--chain-id <id>`        | `777771`                   | EVM chain ID                              |
+| `--block-period <s>`     | `5`                        | IBFT2 block period in seconds             |
+| `--epoch-length <n>`     | `30000`                    | IBFT2 epoch length                        |
+| `--besu-image <img>`     | `hyperledger/besu:24.12.1` | Besu container image                      |
+| `--node-port-rpc <port>` | `30545`                    | Kubernetes NodePort for JSON-RPC          |
+| `--node-port-ws <port>`  | `30546`                    | Kubernetes NodePort for WebSocket         |
+| `--namespace <ns>`       | `besu`                     | Kubernetes namespace                      |
+| `--pull-image`           | —                          | Pull Besu images before deploying         |
+| `--skip-generate`        | —                          | Use existing `manifests/besu/` as-is      |
+| `--skip-wait`            | —                          | Skip waiting for validators to be Running |
 
-- **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`)
+#### `cyberia chain remove`
 
-**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.
+Remove the Besu network from Kubernetes:
 
 ```bash
-# Show atlas sprite sheet by item-id
-cyberia ol anon --show-atlas-sprite-sheet
-
+cyberia chain remove [--namespace besu] [--clean-keys] [--clean-manifests]
 ```
 
-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
+#### `cyberia chain generate-manifests`
 
-### Complete Asset Processing Pipeline
-
-Process assets from source files through to atlas generation:
+Generate Kubernetes manifests without deploying:
 
 ```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
+cyberia chain generate-manifests [options]  # same options as deploy
 ```
 
-### Procedural Generation Pipeline
+---
 
-Generate an object layer entirely from a semantic descriptor — no source PNGs needed:
+### Contract Commands
 
-```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
+#### `cyberia chain compile`
 
-# 2. Inspect the generated frame
-cyberia ol floor-desert --show-frame 08_0
+Compile the Solidity contracts:
 
-# 3. View the auto-generated atlas
-cyberia ol floor-desert --show-atlas-sprite-sheet
+```bash
+cyberia chain compile
 ```
 
-### Batch Procedural Generation
+#### `cyberia chain deploy-contract`
 
-Generate a full tileset family with consistent seeds:
+Deploy `ObjectLayerToken` to a Besu network (mints 10M CKY to the coinbase address):
 
 ```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
+cyberia chain deploy-contract --network besu-k8s
 ```
 
-### Exploring Seed Variations
+| Option             | Default    | Description                                                  |
+| ------------------ | ---------- | ------------------------------------------------------------ |
+| `--network <name>` | `besu-k8s` | Hardhat network name (`besu-ibft2`, `besu-qbft`, `besu-k8s`) |
 
-```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
+#### `cyberia chain test`
 
-# Inspect each
-cyberia ol floor-desert --show-frame 08_0
-```
-
-### Debugging Asset Issues
+Run the Hardhat contract test suite:
 
 ```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
+cyberia chain test
 ```
 
-### Working with Multiple Items
+---
 
-```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
-```
+### Key Management
 
-### Full Rebuild with Cleanup
+#### `cyberia chain key-gen`
 
-Drop all data, clean static assets, and re-import everything:
+Generate a new secp256k1 Ethereum key pair for the coinbase deployer account:
 
 ```bash
-# 1. Drop all object layers with IPFS cleanup and static asset removal
-cyberia ol --drop --client-public --git-clean
-
-# 2. Re-import all asset types
-cyberia ol --import-types all
-
-# 3. Verify
-cyberia ol anon --show-frame 08_0
+cyberia chain key-gen
+# Output: address + private key + key file written to engine-private/
 ```
 
-### Targeted Drop and Re-import
+#### `cyberia chain set-coinbase`
 
-Drop and re-import specific items without affecting others:
+Set the active coinbase key used for contract deployment and minting:
 
 ```bash
-# 1. Drop specific items and their static folders
-cyberia ol anon,skin --drop --client-public
-
-# 2. Re-import only those items
-cyberia ol anon,skin --import
-
-# 3. Regenerate atlas for each
-cyberia ol anon --to-atlas-sprite-sheet
-cyberia ol skin --to-atlas-sprite-sheet
+cyberia chain set-coinbase --private-key 0xYOUR_KEY
+cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/<address>.key.json
 ```
 
-## Blockchain Operations (`chain`)
+---
 
-The `chain` command group manages Hyperledger Besu IBFT2 network deployment and ERC-1155 token operations for on-chain object layer registration.
+### Token Commands
 
-### Deploy Besu IBFT2 Network
+#### `cyberia chain register`
 
-Deploys a private Besu IBFT2 network to Kubernetes.
+Register a single Object Layer item on-chain:
 
 ```bash
-# Deploy with defaults (4 validators, chain-id 777771)
-cyberia chain deploy
-
-# Custom configuration
-cyberia chain deploy --validators 6 --chain-id 888881 --block-period 3
-
-# Pull container images first
-cyberia chain deploy --pull-image
+cyberia chain register <item-id> [options]
 ```
 
-**`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
+| Option                 | Default    | Description                                           |
+| ---------------------- | ---------- | ----------------------------------------------------- |
+| `--from-db`            | —          | Resolve canonical IPFS CID from MongoDB (recommended) |
+| `--metadata-cid <cid>` | `""`       | Manual CID override (ignored when `--from-db` is set) |
+| `--supply <n>`         | `1`        | Initial token supply (1 = NFT, >1 = semi-fungible)    |
+| `--network <name>`     | `besu-k8s` | Hardhat network name                                  |
+| `--env-path <path>`    | `./.env`   | Path to `.env` file                                   |
+| `--mongo-host <host>`  | —          | MongoDB host override                                 |
 
 ```bash
-# Remove network (keep keys and manifests)
-cyberia chain remove
+# Register unique NFT item (non-fungible)
+cyberia chain register legendary-hatchet --from-db --supply 1
 
-# Full cleanup
-cyberia chain remove --clean-keys --clean-manifests
+# Register stackable resource (semi-fungible)
+cyberia chain register gold-ore --from-db --supply 1000000
 ```
 
-| 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 |
+#### `cyberia chain batch-register`
 
-### Generate Manifests Without Deploying
+Register multiple items in a single batch transaction:
 
 ```bash
-cyberia chain generate-manifests --validators 6 --output-dir ./manifests/besu
+cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"stone","supply":500000}]'
 ```
 
-Accepts the same options as `deploy` plus `--output-dir <dir>` (default: `./manifests/besu`).
+#### `cyberia chain mint`
 
-### Deploy ERC-1155 Contract
+Mint additional tokens for an existing token ID:
 
 ```bash
-cyberia chain deploy-contract
-cyberia chain deploy-contract --network besu-k8s
+cyberia chain mint --token-id 0 --to 0xABCD...1234 --amount 1000000000000000000000
+cyberia chain mint --token-id <tokenId> --to <address> --amount <uint256>
 ```
 
-### Compile and Test Contracts
+#### `cyberia chain balance`
+
+Query the token balance of an address:
 
 ```bash
-cyberia chain compile
-cyberia chain test
+cyberia chain balance --address 0xABCD...1234 --token-id 0
 ```
 
-### Register Object Layer Item On-Chain
+#### `cyberia chain transfer`
 
-Registers an object layer as an ERC-1155 token with its canonical CID.
+Transfer tokens between addresses:
 
 ```bash
-# Register with CID resolved from MongoDB (recommended)
-cyberia chain register --item-id hatchet --from-db
-
-# Register with explicit CID
-cyberia chain register --item-id hatchet --metadata-cid bafk...
-
-# Semi-fungible with supply
-cyberia chain register --item-id wood --from-db --supply 500000
+cyberia chain transfer --from 0x... --to 0x... --token-id 0 --amount 1000
 ```
 
-| 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 chain burn`
 
-### Batch Register Multiple Items
+Burn tokens from an address:
 
 ```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}]'
+cyberia chain burn --token-id 0 --amount 500 --address 0x...
 ```
 
-### Mint, Transfer, and Burn Tokens
-
-```bash
-# Mint additional tokens
-cyberia chain mint --token-id 1 --to 0xAddress --amount 100
+#### `cyberia chain status`
 
-# Transfer tokens
-cyberia chain transfer --from 0xSender --to 0xRecipient --token-id 1 --amount 50
+Query chain and contract status:
 
-# Burn tokens
-cyberia chain burn --address 0xHolder --token-id 1 --amount 10
+```bash
+cyberia chain status [--network besu-k8s]
+# Outputs: chain ID, block number, CKY total supply, deployer address, pause state
 ```
 
-### Query Status and Balances
+#### `cyberia chain pause` / `cyberia chain unpause`
 
-```bash
-# Full network and contract status
-cyberia chain status
+Emergency transfer freeze / resume (owner only):
 
-# Query token balance
-cyberia chain balance --address 0xAddress --token-id 0
+```bash
+cyberia chain pause   [--network besu-k8s]
+cyberia chain unpause [--network besu-k8s]
 ```
 
-### Key Management
-
-```bash
-# Generate a new Ethereum key pair
-cyberia chain key-gen
+---
 
-# Generate and persist keys
-cyberia chain key-gen --save
+## `cyberia run-workflow` — Operational Scripts
 
-# 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
-```
+Pre-built operational workflows for seeding and maintenance:
 
-### Pause / Unpause Token Transfers (Emergency)
+| Subcommand                   | Description                                                                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `import-default-items`       | Import the canonical default item set (`DefaultCyberiaItems`) into MongoDB + IPFS, then seed skill config and dialogues            |
+| `seed-skill-config`          | Upsert `DefaultSkillConfig` into `CyberiaInstanceConf` for the target instance                                                     |
+| `seed-dialogues`             | Upsert `DefaultCyberiaDialogues` (NPC dialogue lines) into the `cyberia-dialogue` collection                                       |
+| `generate-semantic-examples` | Generate procedural examples for skin prefixes (`skin-*`); floor and resource generation is available but commented out by default |
+| `build-manifest`             | Build Kubernetes Deployment + Service YAML manifests for mmo-client and mmo-server instances (kubeadm + kind variants)             |
 
 ```bash
-cyberia chain pause
-cyberia chain unpause
+cyberia run-workflow import-default-items --env-path ./engine-private/conf/dd-cyberia/.env.development
+cyberia run-workflow seed-skill-config --env-path ./engine-private/conf/dd-cyberia/.env.development
+cyberia run-workflow build-manifest
 ```
 
-## Workflow Import (`run-workflow`)
-
-### Import Default Items
+---
 
-Imports default Object Layer items from a JSON configuration file into MongoDB.
+## Environment Variables
 
-```bash
-cyberia run-workflow import-default-items
-
-# Use development environment
-cyberia run-workflow import-default-items --dev
-```
+The CLI respects the following environment variables (typically loaded from an `--env-path` file):
 
-## 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                                 |
+| Variable              | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `DEFAULT_DEPLOY_ID`   | Engine deployment ID — resolves to `engine-private/conf/{id}/`   |
+| `DEFAULT_DEPLOY_HOST` | Deploy host (used to index the conf object)                      |
+| `DEFAULT_DEPLOY_PATH` | Deploy path (used to index the conf object)                      |
+| `MONGODB_URI`         | MongoDB connection string (loaded from conf if not set directly) |
+| `IPFS_API_URL`        | IPFS API URL for pinning (e.g. `http://localhost:5001`)          |