cyberia 3.1.3 → 3.2.9

package/README.md

@@ -1,347 +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_
+
+[![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.
+# Cyberia CLI
 
-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.
+**Path:** `bin/cyberia.js`
 
-## 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.
+## Overview
 
-Key features:
+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.
 
-- 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.
+The CLI manages:
 
-## Getting Started
+- **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).
 
-### Prerequisites
+---
 
-You must have the following installed in your environment:
+## Global Usage
 
-- **Node.js** (v24.10.0 recommended)
-- **npm** or **yarn**
-- **MongoDB** (or access to the configured MongoDB instance)
+```bash
+node bin/cyberia.js <command> [subcommand] [options]
+# or if installed globally:
+cyberia <command> [subcommand] [options]
+```
 
-### **Installation**
+---
 
-```bash
+## `cyberia ol` — Object Layer Management
 
-npm install -g cyberia
+Manages the Object Layer content pipeline: import PNG assets, generate procedural layers, build atlas sprite sheets, and push to IPFS/MongoDB.
+
+```bash
+cyberia ol [item-id] [options]
 ```
 
-### **Environment Setup**
+### Options
+
+| 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                                                             |
+
+### Examples
 
-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.
+```bash
+# Import a single item from PNG source
+cyberia ol hatchet --import --env-path ./engine-private/conf/dd-cyberia/.env.development
 
-## Usage
+# Import all items of type 'skin' and 'floor'
+cyberia ol --import-types skin,floor
 
-The CLI is executed from the project root via the `cyberia.js` script.
+# Import all types
+cyberia ol --import-types all
 
-### Process and import object-layer assets
+# Generate a procedural floor tile (desert biome, seed fx-42)
+cyberia ol floor-desert --generate --seed fx-42
 
-This will iterate asset folders for the given types and store processed objects in MongoDB.
+# 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
 
-```bash
-# Process specific types (comma-separated)
-cyberia ol --import skin,floor
+# Generate a character skin
+cyberia ol skin-dark-001 --generate --seed my-seed
 
-# Process all recognized types
-cyberia ol --import all
+# View a specific frame of an item
+cyberia ol hatchet --show-frame 08_0
+
+# Rebuild atlas sprite sheet for an item
+cyberia ol hatchet --to-atlas-sprite-sheet
+
+# Drop and re-import a single item
+cyberia ol hatchet --drop --import
 ```
 
-### 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.
+## Semantic Item-ID Registry
 
-```bash
-# Generate a desert floor tile (single frame, auto seed)
-cyberia ol floor-desert --generate
+The `--generate` flag uses item-id prefixes to look up a procedural descriptor from the semantic registry.
 
-# 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
+### Floor Prefixes
 
-# Grass terrain, sparse, 5 frames
-cyberia ol floor-grass --generate --seed meadow-7 --frame-count 5 --density 0.3
+| 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              |
 
-# Water surface, dense, high element count
-cyberia ol floor-water --generate --seed ocean-1 --count 5 --density 0.8 --frame-count 4
+### Skin Prefixes
 
-# Stone cobblestone
-cyberia ol floor-stone --generate --seed cobble-99 --count 4 --density 0.6
+| 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                    |
 
-# Lava flow, 3-frame animation
-cyberia ol floor-lava --generate --seed magma-3 --frame-count 3 --density 0.7
-```
+### Resource Prefixes
 
-**`--generate` options:**
+Resource prefixes follow the pattern `resource-{biome}-{shape}`:
 
-| 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. |
+| 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               |
 
-**Available semantic item-id prefixes:**
+**Biomes:** `desert`, `grass`, `water`, `stone`, `lava`
 
-| 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-*` | skin | character, body | skin tones, clothing darks |
+**Full matrix (20 prefixes):**
+
+```
+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
+
+resource-stone-petal     resource-lava-petal
+resource-stone-stone     resource-lava-stone
+resource-stone-polygon   resource-lava-polygon
+resource-stone-thread    resource-lava-thread
+```
 
-#### 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`).
+## `cyberia instance` — Instance Management
 
-**Seed derivation** — deterministic at every level:
+Manages game instance documents (maps, entities, actions, quests, skill config) in MongoDB.
 
+```bash
+cyberia instance [instance-code] [options]
 ```
-layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
-frameSeed  = hash(layerSeed + ':' + frameIndex)
+
+### Options
+
+| 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                                                                                     |
+
+### Examples
+
+```bash
+# Export instance to backup
+cyberia instance cyberia-main --export ./backups/cyberia-main
+
+# Import instance from backup
+cyberia instance cyberia-main --import ./backups/cyberia-main
+
+# Drop instance data
+cyberia instance cyberia-main --drop
 ```
 
-**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`).
+## `cyberia chain` — Blockchain Lifecycle
 
-**Generation pipeline per layer:**
+Full lifecycle management for the Hyperledger Besu network and `ObjectLayerToken` ERC-1155 contract.
 
-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.
+### Network Commands
 
-**Variability factors per layer:**
-`scaleVariance`, `rotationVariance`, `colorShift`, `jitter`, `noiseLevel`, `detailLevel`, `sparsity` — small, deterministic variations that keep each generation unique but semantically coherent.
+#### `cyberia chain deploy`
 
-#### What `--generate` persists
+Deploy a new Hyperledger Besu IBFT2 network to Kubernetes:
 
-The full pipeline runs automatically:
+```bash
+cyberia chain deploy [options]
+```
 
-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`.
+| 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 |
 
-#### Reproducibility example
+#### `cyberia chain remove`
 
-Running the same command twice produces byte-identical output:
+Remove the Besu network from Kubernetes:
 
 ```bash
-# Run 1
-cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+cyberia chain remove [--namespace besu] [--clean-keys] [--clean-manifests]
+```
 
-# Run 2 (identical output)
-cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+#### `cyberia chain generate-manifests`
+
+Generate Kubernetes manifests without deploying:
+
+```bash
+cyberia chain generate-manifests [options]  # same options as deploy
 ```
 
-Different seeds produce different but semantically consistent results:
+---
+
+### Contract Commands
+
+#### `cyberia chain compile`
+
+Compile the Solidity contracts:
 
 ```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)
+cyberia chain compile
 ```
 
-## Visualize a processed frame
+#### `cyberia chain deploy-contract`
 
-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]`.
+Deploy `ObjectLayerToken` to a Besu network (mints 10M CKY to the coinbase address):
 
 ```bash
-# Show frame with default direction and frame (08_0)
-cyberia ol anon --show-frame
+cyberia chain deploy-contract --network besu-k8s
+```
 
-# Show specific direction and frame
-cyberia ol anon --show-frame 08_0
+| Option             | Default    | Description                                                  |
+| ------------------ | ---------- | ------------------------------------------------------------ |
+| `--network <name>` | `besu-k8s` | Hardhat network name (`besu-ibft2`, `besu-qbft`, `besu-k8s`) |
 
-# Show different directions
-cyberia ol anon --show-frame 02_0  # up_idle
-cyberia ol anon --show-frame 04_1  # left_idle (second frame)
+#### `cyberia chain test`
+
+Run the Hardhat contract test suite:
+
+```bash
+cyberia chain test
 ```
 
-**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
+### Key Management
 
-### Generate Atlas Sprite Sheet
+#### `cyberia chain key-gen`
 
-Consolidates all frames (8 directions, multiple modes) from an object layer's render frames into a single optimized PNG atlas with metadata.
+Generate a new secp256k1 Ethereum key pair for the coinbase deployer account:
 
 ```bash
-# Generate atlas sprite sheet with auto-calculated dimensions (recommended)
-cyberia ol anon --to-atlas-sprite-sheet
+cyberia chain key-gen
+# Output: address + private key + key file written to engine-private/
+```
 
-# Generate atlas with custom dimensions (manual override)
-cyberia ol anon --to-atlas-sprite-sheet 4096
+#### `cyberia chain set-coinbase`
 
+Set the active coinbase key used for contract deployment and minting:
 
+```bash
+cyberia chain set-coinbase --private-key 0xYOUR_KEY
+cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/<address>.key.json
 ```
 
-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`)
+### Token Commands
 
-**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
+#### `cyberia chain register`
 
-The tool automatically warns if frames exceed the specified dimension and suggests a larger size.
+Register a single Object Layer item on-chain:
 
-### View Atlas Sprite Sheet
+```bash
+cyberia chain register <item-id> [options]
+```
 
-Opens the consolidated atlas sprite sheet PNG for inspection.
+| 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
-# Show atlas sprite sheet by item-id
-cyberia ol anon --show-atlas-sprite-sheet
+# Register unique NFT item (non-fungible)
+cyberia chain register legendary-hatchet --from-db --supply 1
 
+# Register stackable resource (semi-fungible)
+cyberia chain register gold-ore --from-db --supply 1000000
 ```
 
-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
+#### `cyberia chain batch-register`
 
-## Common Workflows
-
-### Complete Asset Processing Pipeline
-
-Process assets from source files through to atlas generation:
+Register multiple items in a single batch transaction:
 
 ```bash
-# 1. Import object layers from asset directories
-cyberia ol --import skin
+cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"stone","supply":500000}]'
+```
 
-# 2. Verify a specific frame was imported correctly
-cyberia ol anon --show-frame 08_0
+#### `cyberia chain mint`
 
-# 3. Generate optimized atlas sprite sheet
-cyberia ol anon --to-atlas-sprite-sheet
+Mint additional tokens for an existing token ID:
 
-# 4. View the generated atlas
-cyberia ol anon --show-atlas-sprite-sheet
+```bash
+cyberia chain mint --token-id 0 --to 0xABCD...1234 --amount 1000000000000000000000
+cyberia chain mint --token-id <tokenId> --to <address> --amount <uint256>
 ```
 
-### Procedural Generation Pipeline
+#### `cyberia chain balance`
 
-Generate an object layer entirely from a semantic descriptor — no source PNGs needed:
+Query the token balance of an address:
 
 ```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 balance --address 0xABCD...1234 --token-id 0
+```
 
-# 2. Inspect the generated frame
-cyberia ol floor-desert --show-frame 08_0
+#### `cyberia chain transfer`
 
-# 3. View the auto-generated atlas
-cyberia ol floor-desert --show-atlas-sprite-sheet
+Transfer tokens between addresses:
+
+```bash
+cyberia chain transfer --from 0x... --to 0x... --token-id 0 --amount 1000
 ```
 
-### Batch Procedural Generation
+#### `cyberia chain burn`
 
-Generate a full tileset family with consistent seeds:
+Burn tokens from an 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 burn --token-id 0 --amount 500 --address 0x...
 ```
 
-### Exploring Seed Variations
+#### `cyberia chain status`
 
-```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
+Query chain and contract status:
 
-# Inspect each
-cyberia ol floor-desert --show-frame 08_0
+```bash
+cyberia chain status [--network besu-k8s]
+# Outputs: chain ID, block number, CKY total supply, deployer address, pause state
 ```
 
-### Debugging Asset Issues
+#### `cyberia chain pause` / `cyberia chain unpause`
+
+Emergency transfer freeze / resume (owner only):
 
 ```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 pause   [--network besu-k8s]
+cyberia chain unpause [--network besu-k8s]
 ```
 
-### Working with Multiple Items
+---
+
+## `cyberia run-workflow` — Operational Scripts
+
+Pre-built operational workflows for seeding and maintenance:
+
+| 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
-# Import multiple types at once
-cyberia ol --import 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
+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
 ```
+
+---
+
+## Environment Variables
+
+The CLI respects the following environment variables (typically loaded from an `--env-path` file):
+
+| 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`)          |