cyberia 3.2.9 → 3.2.22

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

@@ -1,417 +1,204 @@
-<p align="center">
-  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
-</p>
-
-<div align="center">
-
-### CYBERIA
-
-**Network Object Layers**
-
-_Stackable Rendering Layers as a Unified Tokenized Reality_
-
-[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
-
-</div>
-
 # Cyberia CLI
 
-**Path:** `bin/cyberia.js`
-
----
-
-## Overview
-
-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.
-
-The CLI manages:
-
-- **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).
-
----
+`cyberia` (`bin/cyberia.js`) is the Cyberia-specific extension layer on top of the `underpost` CLI. Use
+it for MMO content and extension workflows; use `underpost` for the shared platform, deployment, and
+infrastructure surface. Unrecognized commands pass through to `underpost`.
 
-## Global Usage
+This page is intentionally command-first: keep it aligned with the shipped CLI surface and avoid
+repeating architecture prose unless it changes command behavior.
 
 ```bash
 node bin/cyberia.js <command> [subcommand] [options]
-# or if installed globally:
+# or, installed globally:
 cyberia <command> [subcommand] [options]
 ```
 
+| Command        | Purpose                                                               |
+| -------------- | --------------------------------------------------------------------- |
+| `ol`           | object-layer content import, procedural generation, atlas/sprite work |
+| `instance`     | export / import / drop a Cyberia instance and its related documents   |
+| `client-hints` | per-instance presentation hints (palette, camera, status icons)       |
+| `chain`        | Hyperledger Besu network + ERC-1155 `ObjectLayerToken` lifecycle      |
+| `run-workflow` | named operational scripts (seed defaults, build manifests/dashboard)  |
+
+Most data commands resolve the target DB from `DEFAULT_DEPLOY_ID` / `DEFAULT_DEPLOY_HOST` /
+`DEFAULT_DEPLOY_PATH` in the `--env-path` file (default `./.env`). `--dev` forces the deploy's
+`.env.development` (localhost IPFS, etc.); `--mongo-host` overrides the Mongo host.
+
 ---
 
-## `cyberia ol` — Object Layer Management
+## `cyberia ol` — object layer
 
-Manages the Object Layer content pipeline: import PNG assets, generate procedural layers, build atlas sprite sheets, and push to IPFS/MongoDB.
+Import PNG assets, generate procedural layers, build atlas sprite sheets, push to IPFS + MongoDB.
 
 ```bash
 cyberia ol [item-id] [options]
 ```
 
-### 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
+| Option                                                                               | Description                                                              |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `--import`                                                                           | Import specific item-id(s), comma-separated, from the asset directory    |
+| `--import-types [types]`                                                             | Batch import by type (e.g. `skin,floors`) or `all`                       |
+| `--generate`                                                                         | Generate procedural layers from a semantic item-id (e.g. `floor-desert`) |
+| `--count <n>` / `--density <0..1>`                                                   | Shape count multiplier (default `3`) / density (default `0.5`)           |
+| `--seed <seed>`                                                                      | Deterministic seed for `--generate` (e.g. `fx-42`)                       |
+| `--frame-index <n>` / `--frame-count <n>`                                            | Start frame (default `0`) / frame count (default `1`)                    |
+| `--to-atlas-sprite-sheet [dim]`                                                      | Build a consolidated atlas PNG for the item                              |
+| `--show-frame [dir_frame]`                                                           | View one frame (e.g. `08_0`; default `08_0`)                             |
+| `--show-atlas-sprite-sheet`                                                          | Display the atlas PNG for the item                                       |
+| `--drop`                                                                             | Drop existing data before importing (or standalone)                      |
+| `--client-public` / `--git-clean`                                                    | With `--drop`: also remove static asset folders / run clean              |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` · `--storage-file-path <path>` | env / DB / dev / filter overrides                                        |
 
 ```bash
-# Import a single item from PNG source
-cyberia ol hatchet --import --env-path ./engine-private/conf/dd-cyberia/.env.development
+# Import specific items
+cyberia ol hatchet,sword --import --env-path ./engine-private/conf/dd-cyberia/.env.development
 
-# Import all items of type 'skin' and 'floor'
-cyberia ol --import-types skin,floor
-
-# Import all types
+# Batch import by type, or everything
+cyberia ol --import-types skin,floors
 cyberia ol --import-types all
 
-# Generate a procedural floor tile (desert biome, seed fx-42)
+# Procedural generation
 cyberia ol floor-desert --generate --seed fx-42
+cyberia ol floor-grass  --generate --frame-count 4 --count 5 --density 0.7
 
-# 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
-
-# Generate a character skin
-cyberia ol skin-dark-001 --generate --seed my-seed
-
-# View a specific frame of an item
-cyberia ol hatchet --show-frame 08_0
-
-# Rebuild atlas sprite sheet for an item
+# Atlas / inspect
 cyberia ol hatchet --to-atlas-sprite-sheet
+cyberia ol hatchet --show-frame 08_0
 
-# Drop and re-import a single item
-cyberia ol hatchet --drop --import
-```
-
----
-
-## Semantic Item-ID Registry
-
-The `--generate` flag uses item-id prefixes to look up a procedural descriptor from the semantic registry.
-
-### Floor Prefixes
-
-| 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              |
-
-### Skin Prefixes
-
-| 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                    |
-
-### Resource Prefixes
-
-Resource prefixes follow the pattern `resource-{biome}-{shape}`:
-
-| 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               |
-
-**Biomes:** `desert`, `grass`, `water`, `stone`, `lava`
-
-**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
+# Drop + re-import a single item, including static folders
+cyberia ol hatchet --drop --client-public --import
 ```
 
 ---
 
-## `cyberia instance` — Instance Management
+## `cyberia instance` — instance data
 
-Manages game instance documents (maps, entities, actions, quests, skill config) in MongoDB.
+Export / import / drop a game instance and its related maps, entities, actions, quests, and object
+layers in MongoDB.
 
 ```bash
 cyberia instance [instance-code] [options]
 ```
 
-### 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
+| Option                                                | Description                                                             |
+| ----------------------------------------------------- | ----------------------------------------------------------------------- |
+| `--export [path]`                                     | Export instance and related documents to a backup directory             |
+| `--import [path]`                                     | Import from a backup directory (upsert, preserves UUIDs)                |
+| `--conf`                                              | With `--export`/`--import`: only `cyberia-instance.json` + `-conf.json` |
+| `--drop`                                              | Drop all documents associated with the instance code                    |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` | env / DB / dev overrides                                                |
 
 ```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
+cyberia instance FOREST --export ./backups/FOREST
+cyberia instance FOREST --import ./backups/FOREST
+cyberia instance FOREST --drop
 ```
 
 ---
 
-## `cyberia chain` — Blockchain Lifecycle
-
-Full lifecycle management for the Hyperledger Besu network and `ObjectLayerToken` ERC-1155 contract.
-
-### Network Commands
+## `cyberia client-hints` — presentation hints
 
-#### `cyberia chain deploy`
-
-Deploy a new Hyperledger Besu IBFT2 network to Kubernetes:
-
-```bash
-cyberia chain deploy [options]
-```
-
-| 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 |
-
-#### `cyberia chain remove`
-
-Remove the Besu network from Kubernetes:
+Manage the per-instance `CyberiaClientHints` document (palette, camera, status icons, interpolation).
+These are presentation overrides only — never an instance or server identifier.
 
 ```bash
-cyberia chain remove [--namespace besu] [--clean-keys] [--clean-manifests]
+cyberia client-hints [instance-code] [options]
 ```
 
-#### `cyberia chain generate-manifests`
-
-Generate Kubernetes manifests without deploying:
+| Option                                                | Description                                     |
+| ----------------------------------------------------- | ----------------------------------------------- |
+| `--seed-defaults`                                     | Upsert canonical presentation-hint defaults     |
+| `--export [path]`                                     | Export the hints document to JSON               |
+| `--import [path]`                                     | Upsert hints from a JSON file                   |
+| `--drop`                                              | Remove the hints document for the instance code |
+| `--env-path <path>` · `--mongo-host <host>` · `--dev` | env / DB / dev overrides                        |
 
 ```bash
-cyberia chain generate-manifests [options]  # same options as deploy
+cyberia client-hints cyberia-main --seed-defaults
+cyberia client-hints cyberia-main --export ./client-hints-cyberia-main.json
 ```
 
 ---
 
-### Contract Commands
-
-#### `cyberia chain compile`
-
-Compile the Solidity contracts:
-
-```bash
-cyberia chain compile
-```
+## `cyberia chain` — Besu + ObjectLayerToken
 
-#### `cyberia chain deploy-contract`
+Hyperledger Besu IBFT2 network and ERC-1155 `ObjectLayerToken` (CKY) lifecycle.
 
-Deploy `ObjectLayerToken` to a Besu network (mints 10M CKY to the coinbase address):
+### Network
 
 ```bash
-cyberia chain deploy-contract --network besu-k8s
+cyberia chain deploy [options]            # deploy IBFT2 network to Kubernetes
+cyberia chain generate-manifests [opts]   # generate manifests without deploying (same options)
+cyberia chain remove [--namespace besu] [--clean-keys] [--clean-manifests]
 ```
 
-| Option             | Default    | Description                                                  |
-| ------------------ | ---------- | ------------------------------------------------------------ |
-| `--network <name>` | `besu-k8s` | Hardhat network name (`besu-ibft2`, `besu-qbft`, `besu-k8s`) |
+Key `deploy` options: `--validators <n>` (4) · `--chain-id <id>` (777771) · `--block-period <s>` (5) ·
+`--epoch-length <n>` (30000) · `--besu-image <img>` · `--node-port-rpc <port>` (30545) ·
+`--node-port-ws <port>` (30546) · `--namespace <ns>` (besu) · `--pull-image` · `--skip-generate` ·
+`--skip-wait`.
 
-#### `cyberia chain test`
-
-Run the Hardhat contract test suite:
+### Contract
 
 ```bash
+cyberia chain compile
 cyberia chain test
+cyberia chain deploy-contract --network besu-k8s   # deploys ObjectLayerToken, mints initial CKY
 ```
 
----
-
-### Key Management
-
-#### `cyberia chain key-gen`
-
-Generate a new secp256k1 Ethereum key pair for the coinbase deployer account:
-
-```bash
-cyberia chain key-gen
-# Output: address + private key + key file written to engine-private/
-```
-
-#### `cyberia chain set-coinbase`
-
-Set the active coinbase key used for contract deployment and minting:
+### Keys
 
 ```bash
+cyberia chain key-gen                                       # new secp256k1 deployer key
 cyberia chain set-coinbase --private-key 0xYOUR_KEY
 cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/<address>.key.json
 ```
 
----
-
-### Token Commands
-
-#### `cyberia chain register`
-
-Register a single Object Layer item on-chain:
-
-```bash
-cyberia chain register <item-id> [options]
-```
-
-| 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
-# 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
-```
-
-#### `cyberia chain batch-register`
-
-Register multiple items in a single batch transaction:
-
-```bash
-cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"stone","supply":500000}]'
-```
-
-#### `cyberia chain mint`
-
-Mint additional tokens for an existing token ID:
-
-```bash
-cyberia chain mint --token-id 0 --to 0xABCD...1234 --amount 1000000000000000000000
-cyberia chain mint --token-id <tokenId> --to <address> --amount <uint256>
-```
-
-#### `cyberia chain balance`
-
-Query the token balance of an address:
-
-```bash
-cyberia chain balance --address 0xABCD...1234 --token-id 0
-```
-
-#### `cyberia chain transfer`
-
-Transfer tokens between addresses:
+### Tokens
 
 ```bash
+cyberia chain register <item-id> --from-db --supply 1            # 1 = NFT, >1 = semi-fungible
+cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000}]'
+cyberia chain mint     --token-id 0 --to 0xABCD... --amount 1000000000000000000000
 cyberia chain transfer --from 0x... --to 0x... --token-id 0 --amount 1000
-```
-
-#### `cyberia chain burn`
-
-Burn tokens from an address:
-
-```bash
-cyberia chain burn --token-id 0 --amount 500 --address 0x...
-```
-
-#### `cyberia chain status`
-
-Query chain and contract status:
-
-```bash
-cyberia chain status [--network besu-k8s]
-# Outputs: chain ID, block number, CKY total supply, deployer address, pause state
-```
-
-#### `cyberia chain pause` / `cyberia chain unpause`
-
-Emergency transfer freeze / resume (owner only):
-
-```bash
-cyberia chain pause   [--network besu-k8s]
+cyberia chain burn     --token-id 0 --address 0x... --amount 500
+cyberia chain balance  --address 0xABCD... --token-id 0
+cyberia chain status   [--network besu-k8s]                     # chain id, block, supply, pause state
+cyberia chain pause   [--network besu-k8s]                      # owner-only transfer freeze / resume
 cyberia chain unpause [--network besu-k8s]
 ```
 
+`--from-db` resolves the canonical IPFS CID from MongoDB (recommended over manual `--metadata-cid`).
+
 ---
 
-## `cyberia run-workflow` — Operational Scripts
+## `cyberia run-workflow` — operational scripts
 
-Pre-built operational workflows for seeding and maintenance:
+Named scripts from the `scripts/` directory for seeding and build 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)             |
+| Subcommand                   | Description                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `import-default-items`       | Import default object layers, skill config, dialogues, client-hints to Mongo        |
+| `seed-skill-config`          | Upsert `DefaultSkillConfig` into a `CyberiaInstance` (`--instance-code`)            |
+| `seed-dialogues`             | Upsert `DefaultCyberiaDialogues` into the `cyberia-dialogue` collection             |
+| `generate-semantic-examples` | Generate one procedural example per registered semantic prefix                      |
+| `build-manifest`             | Build K8s Deployment + Service manifests for mmo-client / mmo-server                |
+| `build-server-dashboard`     | Build the static cyberia-server metrics/status dashboard (`--dev`, `--output-path`) |
 
 ```bash
 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 seed-skill-config --instance-code default
+cyberia run-workflow generate-semantic-examples
 cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
 ```
 
 ---
 
-## Environment Variables
-
-The CLI respects the following environment variables (typically loaded from an `--env-path` file):
+## Operational rules
 
-| 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`)          |
+- Preserve public CLI entrypoints and command names unless a change is intentionally breaking.
+- Reuse existing helpers for config loading, env resolution, path normalization, and deploy selection.
+- Prefer one source of truth for generated manifests, deploy IDs, runtime choice, and asset metadata.
+- Treat generated artifacts (atlases, manifests, dashboard HTML) as outputs only; never hand-edit them.
+- `engine-private/` is a private external dependency; never assume its contents exist locally.