cyberia 3.2.12 → 3.2.70

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

@@ -235,16 +235,22 @@ All requests are CORS-simple GETs (no preflight) and cacheable. None require cre
 ```bash
 cd cyberia-client
 
-# Development build
-make -f Web.mk clean && make -f Web.mk web
+# Development build (defaults: BUILD_MODE=DEBUG, localhost URLs)
+make -f Web.mk clean && make -f Web.mk all
 
-# Release build
-make -f Web.mk clean && make -f Web.mk web BUILD_MODE=RELEASE
+# Release build — pass the production URLs explicitly (see note below)
+make -f Web.mk clean && make -f Web.mk all BUILD_MODE=RELEASE \
+    WS_URL=wss://server.cyberiaonline.com/ws \
+    API_BASE=https://www.cyberiaonline.com
 
-# Build + serve on dev port :8082
-make -f Web.mk serve-development
+# Build + serve locally on dev port :8082 (DEBUG, localhost)
+./dev-server.sh            # or: ./dev-server.sh <port>
 ```
 
+`WS_URL` and `API_BASE` are passed straight through to the compiler — see
+[Compile-time configuration](#compile-time-configuration). When omitted they
+default to `localhost`, so **production build pipelines must pass real URLs**.
+
 The build is part of the Underpost Platform static + PWA pipeline; production deploys go through `underpost client` and `underpost deploy`.
 
 ### Output
@@ -261,22 +267,33 @@ bin/
 
 ## Compile-time configuration
 
-`src/config.h`:
-
-| Constant                    | Default                             | Description                                                                                                      |
-| --------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `WS_URL`                    | `wss://server.cyberiaonline.com/ws` | WebSocket endpoint of cyberia-server                                                                             |
-| `API_BASE_URL`              | `https://www.cyberiaonline.com`     | engine-cyberia REST base URL                                                                                     |
-| `CYBERIA_CLIENT_HINTS_CODE` | `cyberia-main`                      | Lookup key for the optional client-hints fetch (presentation override key — never an instance/server identifier) |
-| `HTTP_TIMEOUT_SECONDS`      | `10`                                | HTTP request timeout                                                                                             |
-| `MAX_TEXTURE_CACHE_SIZE`    | `512`                               | Atlas texture LRU cap                                                                                            |
-| `MAX_LAYER_CACHE_SIZE`      | `256`                               | ObjectLayer metadata LRU cap                                                                                     |
-| `MAX_ATLAS_CACHE_SIZE`      | `256`                               | Atlas metadata LRU cap                                                                                           |
-| `DEFAULT_FRAME_DURATION_MS` | `100`                               | Default animation frame duration                                                                                 |
-| `ENABLE_DEV_UI`             | `false`                             | Force dev overlay regardless of presentation hints                                                               |
-| `APP_VERSION`               | `"1.0.0"`                           | Application version string                                                                                       |
-
-For local development, point `WS_URL` and `API_BASE_URL` at `localhost` before rebuilding.
+### Server URLs (build arguments)
+
+`WS_URL` and `API_BASE` are `make` arguments baked into the WASM as
+`-DWS_URL_OVERRIDE` / `-DAPI_BASE_URL_OVERRIDE`. There is **no** RELEASE/DEBUG URL
+switch — both default to `localhost` regardless of `BUILD_MODE`:
+
+| make argument | Default                  | Baked macro             |
+| ------------- | ------------------------ | ----------------------- |
+| `WS_URL`      | `ws://localhost:8081/ws` | `WS_URL_OVERRIDE`       |
+| `API_BASE`    | `http://localhost:4005`  | `API_BASE_URL_OVERRIDE` |
+
+> **Production pipelines must pass the URLs.** `BUILD_MODE=RELEASE` alone still
+> yields `localhost`. Any release build — the Docker image build, CI, manual
+> release — must pass `WS_URL=wss://… API_BASE=https://…` as make arguments
+> (or Docker build-args wired through to `make`), or the client ships pointing
+> at localhost. If unset, `src/config.h` falls back to bare `"ws://"` /
+> `"https://"` stubs.
+
+### Constants (`src/config.h`)
+
+| Constant                    | Default        | Description                                                                                                      |
+| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `CYBERIA_CLIENT_HINTS_CODE` | `cyberia-main` | Lookup key for the optional client-hints fetch (presentation override key — never an instance/server identifier) |
+| `MAX_TEXTURE_CACHE_SIZE`    | `512`          | Atlas texture LRU cap                                                                                            |
+| `MAX_LAYER_CACHE_SIZE`      | `256`          | ObjectLayer metadata LRU cap                                                                                     |
+| `MAX_ATLAS_CACHE_SIZE`      | `256`          | Atlas metadata LRU cap                                                                                           |
+| `DEFAULT_FRAME_DURATION_MS` | `100`          | Default animation frame duration                                                                                 |
 
 ---
 

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

@@ -0,0 +1,88 @@
+# **Cyberia Lore — The Frontier of Hyperspace**
+
+### **Setting: Year 2520+**
+
+Earth is a ruined monument to humanity’s first age. Civilization now spans broken continents, orbital fortresses, lunar citadels, asteroid enclaves, and distant colonies. From the ashes of collapse emerged **Cyberia**: a living frontier where the physical world and **hyperspace** (persistent, immersive Instances) have fused into one unstable civilization.
+
+The boundary between reality and hyperspace is porous. Relics, wars, identities, and events bleed between layers, creating opportunity, conflict, and myth.
+
+---
+
+### **The Historical Fracture**
+
+The **Pacific Cataclysm** (2045) shattered the old world through nuclear disaster, environmental collapse, plagues, and uncontrolled experiments. As Earth became hostile, humanity expanded into space while building advanced **Instances** — enduring digital worlds that evolved from tools into homes, markets, religions, and battlefields.
+
+Two new groups emerged:
+
+- **Mutagens**: Radiation- and bio-altered humans, resilient but often marginalized.
+- **Synthetics**: Artificial beings who gained autonomy and identity.
+
+These groups, along with baseline humans, now navigate the layered reality of Cyberia.
+
+---
+
+### **The Dual Nature of Cyberia**
+
+Cyberia exists on two overlapping layers:
+
+- **Physical Layer**: Harsh, resource-driven reality of fleets, colonies, infrastructure, territory, and direct force. Slow, unforgiving, dominated by logistics and raw power.
+- **Hyperspace Layer**: Vast network of persistent Instances — living archives, simulated empires, memory-cities, and evolving digital ecosystems where time, geography, and identity are fluid.
+
+The two layers constantly influence each other through neural links, relics, breaches, and megastructures. What happens in one can reshape the other.
+
+---
+
+### **The Three Great Confederations**
+
+#### **Zenith Empire (Red)**
+
+Militaristic, hierarchical, expansionist. Masters of the **physical layer** — fleets, fortresses, industry, and territorial control.  
+**Core belief**: Civilization requires imposed order through strength.  
+**Strength**: Force, discipline, infrastructure dominance.  
+**Weakness**: Rigidity, anti-Mutagen prejudice, ecological destruction, over-reliance on Nova’s systems.  
+**Internal split**: Iron Legion (conquest) vs. Aether Council (technocratic stability).  
+**Relations**: Views Atlas as chaotic and degenerate; depends on Nova for intelligence and administration while resenting the dependency.
+
+#### **Atlas Confederation (Yellow)**
+
+Decentralized web of frontier settlements, Mutagen clans, Synthetics, traders, scavengers, hackers, and nomads. Excels in the unstable spaces **between** layers.  
+**Core strength**: Adaptation, asymmetric warfare, improvisation, infiltration, and survival in chaos.  
+**Weakness**: Fragmentation and internal division.  
+**Internal split**: Harmony Enclaves (diplomacy & coexistence) vs. Void Nomads (radical independence).  
+**Relations**: Opposes Zenith’s rigidity and environmental harm; undermines Nova through hacking and sabotage. Thrives on black-market networks and flexible alliances.
+
+#### **Nova Republic (Blue)**
+
+Technocratic, intelligence-driven civilization that dominates **hyperspace**. Obsessed with optimization, prediction, cognitive architecture, and transcendence.  
+**Core strength**: Information control, surveillance, predictive systems, and deep integration into digital realms.  
+**Weakness**: Emotional detachment, underestimation of irrational human elements (faith, loyalty, culture).  
+**Internal split**: Singularity Directive (machine supremacy) vs. Transcendent Conclave (hybrid flesh-machine future).  
+**Relations**: Provides critical systems to Zenith; faces constant subversion from Atlas hackers. Sees itself as the guiding intelligence of civilization.
+
+---
+
+### **The Balance of Power**
+
+The three confederations exist in tense, interdependent equilibrium:
+
+- Zenith controls physical force and territory.
+- Nova controls hyperspace information and architecture.
+- Atlas thrives in the gaps, through mobility, sabotage, and adaptation.
+
+They compete publicly, collaborate secretly, and betray each other routinely. None can fully dominate Cyberia — the frontier is too unstable, layered, and resistant to total control.
+
+---
+
+### **Your Role as Player**
+
+You are not a destined hero. You are a survivor who has lived long enough to matter.
+
+You can be:
+
+- A soldier, scout, smuggler, hacker, relic hunter, Instance diver, mercenary, diplomat, or rogue Synthetic/Mutagen.
+- Aligned with one faction, multiple, or none.
+- A wanderer who moves between physical ruins and hyperspace realms.
+
+Your power comes from what you **carry, recover, build, protect, steal, or remember**. In Cyberia, the true battle is over meaning, memory, and access across layers of reality. Your choices can shift alliances, awaken relics, destabilize systems, or forge new legends.
+
+**Welcome to Cyberia** — the Hyper-Reality Frontier. A broken future where physical and digital realities collide, ancient scars shape new empires, and your story is still unwritten.

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

@@ -0,0 +1,394 @@
+# Cyberia Saga — Top-Down Procedural Generation guided by LLMs
+
+> Semantic Reverse-Engineering of a complete saga ecosystem from a single theme.
+
+## Concept
+
+Classic procedural content generation is **bottom-up**: you draw maps, place
+cells and entities, then layer text and logic on top of that spatial substrate.
+Cyberia inverts the pipeline.
+
+**Top-Down PCG (Semantic Reverse-Engineering)** uses an LLM to infer the entire
+**semantic ontology and narrative backbone first**, from one high-level natural
+language theme. We generate the lightweight, easy-to-align textual layer —
+slugs, titles, descriptions, dialogues, objective requirements, item stats —
+_before_ a single coordinate or texture exists. Spatial layout and graphic
+synthesis become a separate, later stage that fills in a backbone that is
+already internally consistent.
+
+This is a specialized form of AI-Generated Content (AIGC). The win is
+**consistency**: by resolving names, references, and progression as pure text,
+the world is logically coherent before we pay the cost of spatial and visual
+synthesis.
+
+## Architectural boundary (hard rule)
+
+This stage owns **text and logical metadata only**.
+
+| Owned here (textual)             | Out of scope (forced to `null` / default)     |
+| -------------------------------- | --------------------------------------------- |
+| codes, titles, descriptions      | `sourceMapCode`, `sourceCellX`, `sourceCellY` |
+| dialogue text, speakers, mood    | `initCellX`, `initCellY`, map grid sizes      |
+| quest steps, objectives, rewards | asset CIDs, textures, `render` frames         |
+| item stats balance, item types   | atlas / sprite-sheet generation               |
+
+The generator normalizes every spatial and render field to `null` regardless of
+what the model returns. Downstream spatial + graphic synthesis is responsible
+for binding quests/actions to cells and producing object-layer renders.
+
+## Pipeline
+
+The ecosystem is generated in **six bounded, sequential stages** rather than a
+single monolithic request. Each stage emits one layer and feeds canonical
+(slugified) references into the next, so no single model call has to produce the
+whole cross-referenced graph — this keeps each Gemini request small enough to
+complete well within the request timeout.
+
+```
+theme  (from --prompt, OR auto-synthesized from CYBERIA-LORE.md)
+   │
+   ▼
+Google Gemini (Generative Language API /v1beta/models/{model}:generateContent)
+   │   stage 1  foundation  → saga identity + objectLayers (item ids)
+   │   stage 2  maps        → maps             (narrative zones / places)
+   │   stage 3  quests      → quests           (consume item ids + map zones)
+   │   stage 4  dialogues   → dialogues        (consume quest codes)
+   │   stage 5  actions     → actions          (consume quest + dialogue + item codes)
+   │   stage 6  skills      → skills           (bind trigger items → logic-event handlers)
+   ▼
+normalizeSagaPayload()   ── enforces text-only boundary, slugifies, resolves refs,
+   │                         derives the CyberiaInstance shell from saga + map codes
+   ▼
+persistSagaPayload()     ── idempotent upserts into MongoDB
+```
+
+The **instance** is not a model call: it is derived deterministically from the
+saga's own metadata (`code`, `name`, `description`) plus the map codes the saga
+already defined, so the saga is immediately playable as a `CyberiaInstance`.
+Skill `logicEventId`s are restricted to the handlers the simulation actually
+implements (`projectile`, `coin_drop_or_transaction`, `doppelganger`); unknown
+ones are dropped during normalization.
+
+### Theme source: prompt vs. lore-grounded auto-generation
+
+- **`--prompt` given** → the theme is used verbatim with no lore grounding
+  (current behavior).
+- **`--prompt` omitted** → a distinct theme is auto-synthesized from the Cyberia
+  base lore (`src/client/public/cyberia-docs/CYBERIA-LORE.md`, override with
+  `--lore-path`). The whole lore document is read and passed to Gemini, and every
+  stage is grounded in it so the saga reads as a chapter of the canon. Variety is
+  driven by a random world-first **subject**, an explicit **narrative tone**, a
+  **faction role** (background vs. driver), a random entropy token, and a
+  configurable sampling **temperature** (`--temperature`, default `1.3`) — so
+  repeated runs surface very different, grounded Cyberia stories.
+
+#### Subject — the world comes first
+
+The primary diversity lever. Each auto-theme picks one **world-first subject** at
+random so the output spreads across lived Cyberia reality rather than collapsing
+into faction politics: daily life, frontier survival, ecology, salvage, trade,
+exploration, mutagen clans, synthetics, Instance life, anomalies, small-community
+crises, infrastructure, relic hunting, personal/family stories, culture, and
+grounded jobs that go sideways. (Random, not customizable.)
+
+#### Faction role — background by default, driver on request
+
+The confederations are large powers that are **always present but rarely the
+topic**. By default they stay **background only** — borders, trade influence,
+security presence, taxes, historical scars — never the subject.
+
+To make a faction the **central driver** of the saga, name one or more with
+`--faction-context` (comma-separated). Valid keys:
+
+| Key       | Confederation                                  |
+| --------- | ---------------------------------------------- |
+| `zenith`  | the Zenith Empire (Red)                        |
+| `nova`    | the Nova Republic (Blue)                       |
+| `atlas`   | the Atlas Confederation (Yellow)               |
+| `neutral` | unaligned independent enclaves / neutral parties |
+
+```bash
+# Nova + Zenith are the driving pressure of the saga
+node bin/cyberia.js generate-saga --faction-context 'nova,zenith'
+```
+
+Unknown keys warn and are skipped; if none resolve (or the flag is unset) the
+saga falls back to background factions. Even when driven, the saga is still told
+through the subject's people and places, not abstract galaxy-wide politics.
+
+#### Character culture & naming
+
+To stop the model collapsing into cliché sci-fi names (John, Nova, X-99…) and to
+make Cyberia feel descended from Earth's many diasporas, a **naming &
+character-culture** block is injected into every generation stage that names
+people or places. It uses `CHARACTER_NAMES_POOL` as a **statistical/stylistic
+prior — inspiration only, never a whitelist**: the model is told to invent fresh
+names with similar linguistic/demographic characteristics (evolving, hybridizing,
+or blending them with professions, slang, and technical terms), reusing an exact
+sample only rarely.
+
+Two optional flags steer it; **both default to random** when unset:
+
+- **`--character-context <keys>`** — comma-separated pools to draw inspiration
+  from (unset → a random non-empty subset, so runs vary their cultural mix).
+  Unknown keys warn and are skipped. Valid keys:
+
+  | Key | Flavor |
+  | --- | ------ |
+  | `low_level_synthetics` | serialized / technical utility-frame designations |
+  | `high_fidelity_synthetics` | refined, near-human synthetic names |
+  | `global_latin_diaspora` | Latin / Iberian-descended |
+  | `east_asian_pacific_diaspora` | East-Asian / Pacific-descended |
+  | `middle_eastern_turkish_diaspora` | Middle-Eastern / Turkish-descended |
+  | `sub_saharan_african_diaspora` | Sub-Saharan African-descended |
+  | `classic_western_scifi` | gritty Anglo operators / enforcers |
+  | `mutagen_clans` | organic, mutation-flavored clan names |
+
+- **`--cultural-exposure <mode>`** — how mixed the population is (unset → random):
+
+  | Mode | Effect |
+  | ---- | ------ |
+  | `cosmopolitan` | heavy mixing, hybrid surnames, intermarriage — maximizes variety |
+  | `local` | isolated clans/enclaves, strong local naming traditions, internally consistent |
+
+```bash
+# Latin + East-Asian diaspora names in a highly mixed, cosmopolitan population
+node bin/cyberia.js generate-saga \
+  --character-context 'global_latin_diaspora,east_asian_pacific_diaspora' \
+  --cultural-exposure cosmopolitan
+
+# An isolated mutagen-clan enclave with consistent internal naming
+node bin/cyberia.js generate-saga --character-context 'mutagen_clans' --cultural-exposure local
+```
+
+#### Narrative tone
+
+The theme commits to one of four broad narrative types — chosen **uniformly
+(~25% each)** unless forced with `--tone`:
+
+| Tone        | Register                                                        |
+| ----------- | -------------------------------------------------------------- |
+| `adventure` | noir high-risk missions: covert ops, sabotage, combat, rogue AI, mystery |
+| `politics`  | power & ideology at any scale — councils, clans, enclaves, revolutions (confederation geopolitics only sometimes) |
+| `tragic`    | heartbreaking, intimate: family, bonds, loss, grief            |
+| `comedy`    | everyday absurdity and silliness, played for humor             |
+
+#### Spatial context (physical vs. hyperspace)
+
+Cyberia has two equally important layers — the **Physical Layer** (fleets,
+colonies, logistics, force) and the **Hyperspace Layer** (persistent Instances,
+memory-cities, digital ecosystems). Because the lore is titled *The Frontier of
+Hyperspace*, an unconstrained model drifts to hyperspace-only premises. So the
+auto-theme picks a spatial context **explicitly and uniformly (~33.3% each)**:
+
+| Context      | Premise lives in…                                              |
+| ------------ | -------------------------------------------------------------- |
+| `physical`   | the material frontier only — no hyperspace                     |
+| `mixed`      | the porous interplay where events bleed between both layers    |
+| `hyperspace` | inside the Instances only — not the physical frontier          |
+
+Force one with `--space-context <physical\|mixed\|hyperspace>`; an invalid value
+warns and falls back to random. This applies to auto-generation only (with
+`--prompt`, you control the setting yourself).
+
+> Transient `generateContent` failures (timeouts, 5xx, malformed JSON) are
+> retried automatically with backoff (`maxRetries`, default 2) per stage.
+
+Source:
+
+- `src/projects/cyberia/gemini-client.js` — thin Gemini `generateContent` JSON client.
+- `src/projects/cyberia/generate-saga.js` — system prompt, normalization, persistence.
+- `bin/cyberia.js` — `generate-saga` CLI command wiring.
+
+## Usage
+
+### Lore-based auto-generation (no `--prompt`)
+
+With no `--prompt`, the theme is auto-synthesized from the Cyberia base lore.
+Omitting the steering flags lets the generator pick a random faction, tone and
+spatial context each run, so the same command keeps producing different sagas:
+
+```bash
+# Fully random, lore-grounded saga (faction + tone + spatial context all random)
+node bin/cyberia.js generate-saga
+
+# Force a heartbreaking, character-driven story grounded in physical reality
+node bin/cyberia.js generate-saga --tone tragic --space-context physical
+
+# A political saga set inside hyperspace Instances
+node bin/cyberia.js generate-saga --tone politics --space-context hyperspace
+
+# A light comedy that spans both layers, cranked up for more divergence
+node bin/cyberia.js generate-saga --tone comedy --space-context mixed --temperature 1.7
+
+# A noir adventure, kept tightly on-theme with a low temperature
+node bin/cyberia.js generate-saga --tone adventure --temperature 0.6
+
+# Steer only the spatial layer; let subject + tone stay random
+node bin/cyberia.js generate-saga --space-context physical
+
+# Make Nova + Zenith the driving pressure (factions as the main theme)
+node bin/cyberia.js generate-saga --faction-context 'nova,zenith'
+
+# Steer character names toward specific diasporas and a cosmopolitan, mixed population
+node bin/cyberia.js generate-saga \
+  --character-context 'global_latin_diaspora,sub_saharan_african_diaspora' --cultural-exposure cosmopolitan
+
+# Dry run (no DB writes) and capture the payload to inspect it
+node bin/cyberia.js generate-saga --tone tragic --dry-run --out ./engine-private/cyberia-sagas/preview.json
+```
+
+Each run logs the chosen facets, e.g.
+`Theme: subject="..." | context=physical | tone=tragic | factions=background`,
+then `Auto-generated theme: "..."`.
+
+### Generate from an explicit theme
+
+```bash
+node bin/cyberia.js generate-saga \
+  --prompt "A rebel hacker base hidden in the sewers of Santiago"
+```
+
+Either way, when `--out` is omitted the payload is written to
+`./engine-private/cyberia-sagas/<saga-code>.json`.
+
+Import a previously generated payload (no model call):
+
+```bash
+node bin/cyberia.js generate-saga --import ./engine-private/cyberia-sagas/<saga-code>.json
+```
+
+`--import` reads the same JSON shape `--out` writes and loads it through the
+**same** normalize → persist path as generation. Re-running is safe: documents
+are upserted by `code` (dialogues by `code` + `order`), so existing entries are
+overwritten and codes are never duplicated.
+
+Options:
+
+| Flag                       | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| `--prompt <theme>`         | Theme seed. Omit to auto-generate from the lore.     |
+| `--import <file>`          | Load a generated payload file into the DB.           |
+| `--lore-path <path>`       | Override the base-lore doc (auto-generate mode).     |
+| `--space-context <ctx>`    | Force `physical` \| `mixed` \| `hyperspace` (else random). |
+| `--tone <tone>`            | Force `adventure` \| `politics` \| `tragic` \| `comedy` (else random). |
+| `--faction-context <keys>` | Comma-separated `zenith` \| `nova` \| `atlas` \| `neutral` that DRIVE the theme (else background). |
+| `--character-context <keys>` | Comma-separated `CHARACTER_NAMES_POOL` keys for name inspiration (else random subset). |
+| `--cultural-exposure <mode>` | `cosmopolitan` \| `local` naming-diversity mode (else random). |
+| `--temperature <value>`    | Sampling temperature for every model call (default `1.3`). |
+| `--model <id>`             | Gemini model id (default `gemma-4-26b-a4b-it`).      |
+| `--timeout <ms>`           | Per-request timeout in ms (default `300000`).        |
+| `--thinking-level <level>` | `low` \| `medium` \| `high` (default `high`).        |
+| `--out <file>`             | Payload dump path (default `./engine-private/cyberia-sagas/<saga-code>.json`). |
+| `--dry-run`                | Normalize only; no database writes.                  |
+| `--env-path <path>`        | Env file to load (`GEMINI_API_KEY`, deploy vars).    |
+| `--mongo-host <host>`      | Mongo host override.                                 |
+| `--dev`                    | Force the development environment.                  |
+
+`GEMINI_API_KEY` must be available in the environment or the `--env-path` file.
+
+## Output schema
+
+A single JSON object with these interrelated sections:
+
+- **saga** — `code`, `name`, `description`, `mapCodes[]`, `itemIds[]`, `questCodes[]`.
+- **instance** — the playable `CyberiaInstance` shell derived from the saga
+  metadata: `code`, `name`, `description`, `tags[]`, `cyberiaMapCodes[]` (the
+  saga's map codes), `itemIds[]` (`{ id, defaultPlayerInventory }`),
+  `topologyMode`. Spatial topology (`portals`) and the tuning ref (`conf`) are
+  left empty here and bound by downstream spatial synthesis.
+- **maps[]** — narrative zones the quest chain visits: `code`, `name`,
+  `description` (text only — grid/cells/entities stay at schema defaults). Their
+  codes populate `saga.mapCodes` and `instance.cyberiaMapCodes`.
+- **quests[]** — textual objectives, titles, linear `steps[]` with
+  `collect | talk | kill` objectives and `rewards[]`. Spatial fields `null`.
+- **dialogues[]** — narrative nodes: `code`, `order`, `speaker`, `text`, `mood`.
+- **actions[]** — interaction nodes: `dialogCode`, `questDialogueCodes[]`,
+  `shopItems[]` pricing, and `craftRecipes[]`. Spatial fields `null`.
+- **skills[]** — `triggerItemId` → logic skills: `logicEventIds[]` (derived) and
+  `skills[]` (`logicEventId`, `name`, `description`, `summonedEntityItemId`). The
+  trigger and every non-placeholder summoned id resolve to an
+  `objectLayers[].item.id`.
+- **objectLayers[]** — item data with balanced `stats`, an `item`
+  (`id`, `type`, `description`, `activable`), and `render: null`.
+
+Object-layer item shape:
+
+```json
+{
+  "stats": { "effect": 4, "resistance": 4, "agility": 3, "range": 10, "intelligence": 5, "utility": 10 },
+  "item": { "id": "generated-id", "type": "skin", "description": "Lore-matching description", "activable": true },
+  "render": null
+}
+```
+
+## Referential integrity
+
+The system prompt requires the model to keep cross-references resolvable, and
+normalization slugifies every code/id so they line up:
+
+- quest objective/reward `itemId`, shop `itemId`, and craft `itemId` resolve to
+  an `objectLayers[].item.id`;
+- action `questDialogueCodes[].questCode` resolves to a `quests[].code`;
+- action `dialogCode` / `questDialogueCodes[].dialogCode` resolve to a
+  `dialogues[].code`;
+- skill `triggerItemId` resolves to an `objectLayers[].item.id` (skills whose
+  trigger is unknown are dropped), and each non-placeholder `summonedEntityItemId`
+  resolves to one too — a deterministic repair (`ensureSkillLinkage`) appends a
+  minimal `skill`-type item for any summoned id the model omitted;
+- `saga.questCodes` / `saga.itemIds` are reconciled to include every generated
+  quest and item (including appended skill items), and `instance.cyberiaMapCodes`
+  / `instance.itemIds` mirror the saga's.
+
+### `talk` objectives (guaranteed fulfillable)
+
+A `talk` objective completes **only** when the player views the `dialogCode` an
+action maps for that quest, on the NPC bot whose skin matches the objective's
+`itemId` (the bot skin derives from the action's `default-<skin>` greeting). A
+missing link means the objective can never be completed.
+
+So a talk objective requires four aligned pieces: a `skin` item for the NPC, the
+`talk` objective referencing that skin id, a talk dialogue group, and an action
+with `dialogCode: default-<skin>` plus a `questDialogueCodes` entry
+`{ questCode, dialogCode }`. The prompts ask the model to produce all four (the
+quests/dialogues/actions stages are told the `talkTargets`), and a deterministic
+**repair pass** (`ensureTalkLinkage`) then guarantees it: for every talk
+objective it creates any missing skin item, talk dialogue
+(`quest-talk-<questCode>`), or NPC action mapping, and rewrites a
+`questDialogueCodes` entry that points at a non-existent dialogue. Reruns where
+the model already produced valid links are a no-op.
+
+## Persistence
+
+Documents are written sequentially with idempotent upserts (rerunnable):
+
+| Section       | Model                  | Upsert key       |
+| ------------- | ---------------------- | ---------------- |
+| saga          | `CyberiaSagaModel`     | `code`           |
+| instance      | `CyberiaInstanceModel` | `code`           |
+| maps          | `CyberiaMapModel`      | `code`           |
+| quests        | `CyberiaQuestModel`    | `code`           |
+| dialogues     | `CyberiaDialogueModel` | `code` + `order` |
+| actions       | `CyberiaActionModel`   | `code`           |
+| skills        | `CyberiaSkillModel`    | `triggerItemId`  |
+| object layers | `ObjectLayerModel`     | `data.item.id`   |
+
+The **instance** refreshes its textual/logical fields every run but PRESERVES
+`portals` and `conf` (set only on insert), so downstream spatial topology is
+never clobbered — the same preservation contract `ObjectLayer` render/ledger
+uses. **Skills** are upserted by `triggerItemId` into the `CyberiaSkill`
+collection — the authoritative own-model source the gRPC server reads.
+
+Both `generate` and `import` go through the same persistence path. Object-layer
+items are written as real `ObjectLayer` documents so they are immediately
+editable in `src/client/components/cyberia/ObjectLayerEngineViewer.js`:
+
+- `data.render` is empty (`cid: null`, `metadataCid: null`) and the top-level
+  `cid` is `null` — there is no atlas yet;
+- `data.ledger.type` is `OFF_CHAIN` (no on-chain token minted);
+- `sha256` is computed over `data` with the canonical `computeSha256` helper.
+
+The render and ledger are the **graphic/economic synthesis** stage and are set
+later from the viewer. Re-running generate/import refreshes the textual
+stats/item fields but **preserves any render or ledger already set** — it never
+clobbers a populated render back to `null`. `saga.itemIds` records every item id.

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

@@ -12,7 +12,7 @@
 
 `cyberia-server` is the authoritative simulation runtime for the Cyberia MMO extension on Underpost Platform. It owns world state, advances a fixed-rate tick, drains typed input commands from connected clients, and dispatches AOI-filtered snapshots on a separately-paced replication tick.
 
-It is **not** the content authority. World content is loaded from `engine-cyberia` over gRPC. It is **not** the render-policy authority. Presentation is owned by `cyberia-client`.
+It is **not** the content authority. World content is loaded once at boot from `engine-cyberia` over gRPC. It is **not** the render-policy authority. Presentation is owned by `cyberia-client`.
 
 ---
 
@@ -20,23 +20,32 @@ It is **not** the content authority. World content is loaded from `engine-cyberi
 
 Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
 
-```text
-engine-cyberia (Node.js)        cyberia-server (Go)            cyberia-client (C/WASM)
-content authority               authoritative simulation       presentation runtime
-gRPC + REST                     tick + AOI + snapshots         render + prediction
-
-   └── gRPC GetFullInstance ──►   └── WebSocket binary ──►
-         world config                  snapshots -> / input <-
+```
+engine-cyberia (Node.js)                cyberia-server (Go)              cyberia-client (C/WASM)
+─────────────────────────               ──────────────────               ──────────────────────
+content authority                       authoritative simulation         presentation runtime
+persisted maps + rules                  tick + AOI + snapshots           render + prediction
+
+      │  gRPC  GetFullInstance               │  WebSocket binary
+      │────────────────────────────────────► │  AOI snapshots + init
+      │  (world configuration:               │  ▲
+      │   AOI radius, economy,               │  │ typed input commands
+      │   skill, equipment,                  │  │
+      │   entity gameplay defaults)          │  │
+      │                                      │  │
+      ▼                                      ▼  ▼
+   (boot + hot reload)                   tick loop + replication
 ```
 
 - Each service is supervised independently and owns its own monitor and reconnector.
-- `cyberia-server` loads world configuration from `engine-cyberia` and does not fabricate a world.
+- `cyberia-server` dials `engine-cyberia` gRPC at boot and exits on dial failure rather than fabricate a world.
+- On reconnect, world configuration is reloaded via `GetFullInstance(instanceCode)`.
 - If any one of the three services is unhealthy, the game moves to standby until all three recover.
 
 The server speaks two protocols:
 
-- **gRPC inbound** to consume world configuration from `engine-cyberia`
-- **WebSocket binary** to deliver snapshots and accept typed input commands
+- **gRPC, inbound, at boot and hot reload:** consumes world configuration from `engine-cyberia`.
+- **WebSocket binary, ongoing:** delivers AOI snapshots to clients, accepts typed input commands.
 
 There is no per-tick traffic between `cyberia-server` and `engine-cyberia`, and no presentation authority in the Go runtime.
 
@@ -257,7 +266,8 @@ All content data (ObjectLayer metadata, asset blobs, optional client hints) is s
 | --------------------------------- | ----------------- | -------------------------------------------------- |
 | `ENGINE_GRPC_ADDRESS`             | `localhost:50051` | engine-cyberia gRPC address (**required**)         |
 | `INSTANCE_CODE`                   | `default`         | Instance code to load on startup                   |
-| `ENGINE_API_BASE_URL`             | _(empty)_         | engine-cyberia REST base URL; forwarded to clients |
+| `ENGINE_API_BASE_URL`             | _(empty)_         | Internal engine-cyberia origin (server→engine only) |
+| `ENGINE_PUBLIC_URL`               | _(empty)_         | Client-visible Content Authority origin (forwarded to clients) |
 | `ENGINE_GRPC_RELOAD_INTERVAL_SEC` | _(disabled)_      | ObjectLayer hot-reload polling interval            |
 | `SERVER_PORT`                     | `8081`            | WebSocket + HTTP listen port                       |
 | `STATIC_DIR`                      | `./public`        | Directory for static WASM client files             |
@@ -276,3 +286,9 @@ go run main.go
 go build -o cyberia-server .
 ./cyberia-server
 ```
+
+### Test logx
+
+```bash
+go test ./logx/ -run TestResolveLevel
+```

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

@@ -224,7 +224,7 @@ cyberia chain register / mint / transfer / burn / pause / unpause
 
 # Named workflows
 cyberia run-workflow import-default-items
-cyberia run-workflow seed-skill-config --instance-code default
+cyberia run-workflow seed-skills
 cyberia run-workflow seed-dialogues
 cyberia run-workflow build-manifest
 cyberia run-workflow build-server-dashboard