cyberia 3.2.5 → 3.2.12

package/src/client/public/cyberia-docs/QUEST-SYSTEM.md

@@ -0,0 +1,206 @@
+# Quest System
+
+**Module:** `src/api/cyberia-quest` · `src/api/cyberia-quest-progress`
+
+---
+
+## Overview
+
+The Quest System is a **chain/tree-structured progression framework** linking NPC entities, player actions, map coordinates, and item rewards. Quests are the primary mechanism for guided player progression in Cyberia Online.
+
+Quests are defined server-side as MongoDB documents and delivered to the client through the Engine REST API. Progress is tracked per-player in `CyberiaQuestProgress` documents.
+
+> **Implementation status — Pre-alpha:** The Quest and QuestProgress MongoDB schemas and Engine REST API (`src/api/cyberia-quest`, `src/api/cyberia-quest-progress`) are defined and seeded. Go server integration (quest tracking, objective evaluation, reward delivery via FCT) is planned for the **Alpha milestone**. For pre-alpha, quest progress is ephemeral: it lives in the client session only and resets on page reload.
+
+---
+
+## Data Model
+
+### CyberiaQuest Schema
+
+```
+CyberiaQuest {
+  code:              String   // stable slug, e.g. "fallback-intro-quest"
+  title:             String
+  description:       String
+
+  // Spatial origin — the NPC/entity cell that grants this quest
+  sourceMapCode:     String
+  sourceCellX:       Number
+  sourceCellY:       Number
+
+  // Chain / tree unlock structure
+  prerequisiteCodes: [String] // AND logic — all must be completed to unlock
+  unlocksQuestCodes: [String] // quests activated on completion (chain or tree)
+
+  // Ordered linear step sequence
+  steps: [{
+    id:          String
+    description: String
+    objectives: [{
+      type:     String  // 'collect' | 'talk' | 'kill'
+      itemId:   String  // semantic target (see Objective Types below)
+      quantity: Number  // default: 1
+    }]
+  }]
+
+  // Rewards granted on quest completion
+  rewards: [{
+    itemId:   String
+    quantity: Number
+  }]
+}
+```
+
+### CyberiaQuestProgress Schema
+
+```
+CyberiaQuestProgress {
+  playerId:   String   // Go server player UUID
+  questCode:  String   // references CyberiaQuest.code
+  status:     String   // 'active' | 'completed'
+
+  stepProgress: [{
+    stepId: String
+    objectiveProgress: [{
+      current:  Number  // current count toward objective
+      required: Number  // denormalized from quest definition
+    }]
+  }]
+
+  startedAt:   Date
+  completedAt: Date | null
+}
+```
+
+**Completeness is always computed, never stored.** A step is complete when all `objectiveProgress[i].current >= objectiveProgress[i].required`. The active step is always the first step where not all objectives are done.
+
+---
+
+## Objective Types
+
+| `type`    | `itemId` semantics                                             | Completion trigger                                                                                 |
+| --------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `collect` | ObjectLayer item ID that must appear in the player's inventory | Player inventory contains `>= quantity` of `itemId`                                                |
+| `talk`    | `CyberiaAction.provideItemId` of the NPC to interact with      | Player triggers a talk action where `provideItemId === itemId` and all `questDialogueCodes` viewed |
+| `kill`    | Skin item ID of the target entity (e.g. `"wason"`)             | Player kills an entity whose active skin matches `itemId`                                          |
+
+---
+
+## Quest Graph (Chain and Tree)
+
+Quests form a **directed acyclic graph** via `prerequisiteCodes` → `unlocksQuestCodes`:
+
+```mermaid
+graph LR
+    A["intro-quest\n(no prerequisites)"]
+    B["village-quest\n(requires: intro-quest)"]
+    C["forest-quest\n(requires: intro-quest)"]
+    D["final-quest\n(requires: village-quest AND forest-quest)"]
+
+    A -->|unlocksQuestCodes| B
+    A -->|unlocksQuestCodes| C
+    B -->|unlocksQuestCodes| D
+    C -->|unlocksQuestCodes| D
+```
+
+**AND logic on prerequisites:** A quest only becomes available when **all** listed `prerequisiteCodes` are completed.
+
+**Tree branching:** A quest can list multiple `unlocksQuestCodes`, enabling parallel quest branches that reconverge later.
+
+---
+
+## Quest Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant P as Player
+    participant G as Go Server
+    participant E as Engine (Node.js)
+    participant DB as MongoDB
+
+    P->>G: Tap NPC with grantQuestCode
+    G->>E: POST /api/cyberia-quest-progress (grant quest)
+    E->>DB: Create CyberiaQuestProgress { status: 'active' }
+    E-->>G: Progress document
+
+    loop For each game event (kill / collect / talk)
+        G->>E: PATCH /api/cyberia-quest-progress (increment objective)
+        E->>DB: objectiveProgress[i].current++
+        E-->>G: Updated progress
+    end
+
+    Note over G,E: All steps complete
+    G->>E: PATCH status → 'completed'
+    E->>DB: completedAt = now
+    G->>E: GET unlocksQuestCodes → activate successor quests
+    E->>DB: Create CyberiaQuestProgress for each unlocked quest
+    G-->>P: Deliver reward items (inventory grant + FCT ItemGain events)
+```
+
+---
+
+## Spatial Binding
+
+Each `CyberiaQuest` can declare `sourceMapCode + sourceCellX + sourceCellY`, linking it to the map entity at that cell. This binding is used during instance initialization:
+
+- `instance_loader.go` reads `CyberiaEntity.initCellX/initCellY` and correlates with quest `sourceCellX/sourceCellY` to assign quest-granting behaviors to the correct NPC entity at world construction time.
+- The `ObjectLayerEngineModal` (Engine UI) allows editors to assign quest codes to entity cells visually.
+
+---
+
+## Reward Delivery
+
+On quest completion, the Engine grants each `rewards[].{itemId, quantity}` to the player's inventory:
+
+- Off-chain items are added to the player's `ObjectLayers` array in the Go server.
+- If the item has an on-chain ERC-1155 token, the server relayer calls `mint(playerAddress, tokenId, quantity)` on the `ObjectLayerToken` contract.
+- FCT `ItemGain` events (`MsgTypeItemFCT`, `FCTTypeItemGain`) are broadcast to the client for visual feedback.
+
+---
+
+## Step Progression Rules
+
+1. Steps are always processed in **declared order** — step N cannot advance until step N-1 is complete.
+2. Within a step, all objectives must be satisfied (any order).
+3. Quests do not fail — they remain `active` until completed or explicitly abandoned.
+4. The `required` count is **denormalized** from the quest definition into each `objectiveProgress` record at quest grant time, enabling O(1) progress checks without re-fetching the quest definition.
+
+---
+
+## Indexes
+
+```javascript
+// CyberiaQuest
+{ code: 1 }  // unique
+{ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 }
+
+// CyberiaQuestProgress
+{ playerId: 1, questCode: 1 }  // unique
+{ playerId: 1, status: 1 }
+```
+
+---
+
+## Example Quest Document
+
+```json
+{
+  "code": "wason-intro",
+  "title": "Meet Wason",
+  "description": "Find the village elder to begin your journey.",
+  "sourceMapCode": "cyberia-village",
+  "sourceCellX": 12,
+  "sourceCellY": 8,
+  "prerequisiteCodes": [],
+  "unlocksQuestCodes": ["wason-collection"],
+  "steps": [
+    {
+      "id": "step-talk",
+      "description": "Speak with Wason.",
+      "objectives": [{ "type": "talk", "itemId": "wason", "quantity": 1 }]
+    }
+  ],
+  "rewards": [{ "itemId": "health-potion", "quantity": 2 }]
+}
+```

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

@@ -0,0 +1,240 @@
+# Cyberia Online — Development Roadmap
+
+**Current version:** 3.2.12 | **Target milestone:** Open Alpha
+
+---
+
+## Project Context
+
+Cyberia Online is a real-time tap-based sandbox MMORPG built on three layers:
+
+- **cyberia-client** (C/WASM) — browser-based game client
+- **cyberia-server** (Go) — authoritative real-time game server (binary WebSocket AOI)
+- **engine-cyberia** (Node.js) — data persistence, gRPC data service, REST API, content pipeline
+
+The **Cyberia CLI** (`cyberia`) is an extension of the **Underpost CLI** specifically for this ecosystem. Underpost is the end-to-end bare-metal infrastructure platform; `cyberia` adds the game's content pipeline, economy toolchain, and MMO engine management. Unrecognized commands pass through to `underpost` for general infrastructure operations.
+
+---
+
+## Core Design Principle: Item ID as the Universal Identity
+
+The central data-transmission primitive is the **item ID (`data.item.id`)** — a human-readable string slug (e.g. `hatchet`, `skin-dark-001`, `floor-desert`) that identifies an Object Layer entity.
+
+**Why item IDs, not ObjectIds or hashes:**
+
+- The Go server and C client never transmit full ObjectLayer documents over the game wire.
+- The binary AOI protocol sends only item ID strings per entity in the AOI update packets.
+- The C client uses these item IDs to independently request visual data and atlas metadata from the Engine REST API (`GET /api/object-layer/{itemId}`, `GET /api/atlas-sprite-sheet/{cid}`).
+- This creates a clean separation: the **Go server** manages authoritative game state (positions, HP, coin balances, equipment activation); the **Engine REST API** manages and serves asset/metadata resolution; the **C client** handles all rendering and compositing.
+
+```
+Go Server (binary AOI)
+  → sends entity itemId stack per AOI tick
+    → C client decodes itemIds
+      → C client independently fetches ObjectLayer metadata from Engine REST API
+        → C client fetches atlas CID blobs from Engine REST API
+          → C client composites layers + renders
+```
+
+**gRPC is used only at startup** for world reconstruction (maps, entities, instance config, ObjectLayer cache warm-up). At runtime, the Go server holds all game state in memory and communicates with clients exclusively over binary WebSocket.
+
+---
+
+## Server Types (Production Topology)
+
+Three server modes are planned, addressing different user needs and scaling properties:
+
+| Mode                      | Session Persistence                         | Auth                             | Inventory                           | Economy                           |
+| ------------------------- | ------------------------------------------- | -------------------------------- | ----------------------------------- | --------------------------------- |
+| **Anonymous Off-Chain**   | Ephemeral (in-memory, resets on disconnect) | None                             | itemId-based in-memory              | Off-chain only                    |
+| **Centralized Off-Chain** | Persistent (MongoDB via gRPC)               | Username / password (User model) | Server-authoritative MongoDB        | Off-chain only                    |
+| **On-Chain**              | Decentralized (Hyperledger Besu + IPFS)     | secp256k1 ETH keys (EIP-712)     | ObjectLayerToken ERC-1155 ownership | On-chain: CKY + NFT/semi-fungible |
+
+---
+
+## Release Policy
+
+All release versions have **publicly available features** with no paywalled content. If a server's player capacity is reached, a **queue system** is implemented rather than hard-blocking users.
+
+**Queue system standard:** Token-bucket or FIFO queue with estimated wait time displayed to the user, following the pattern used by major MMOs (World of Warcraft realm queues, FFXIV login queues). The queue is server-side; clients poll a lightweight `/api/v1/queue-status` endpoint. A server-sent event (SSE) or WebSocket notification fires when the slot is granted.
+
+---
+
+## Phase 1 — Pre-Alpha: Anonymous Off-Chain (Ephemeral Sessions)
+
+**Status:** In progress — core game loop functional; action/quest systems pending.
+
+### What works today
+
+- Binary WebSocket AOI protocol (entity movement, combat, HP, FCT)
+- Object Layer item equip/unequip (`item_activation`) with equipment rules enforced
+- Fountain & Sink coin economy (bot spawn coins, kill transfer, coin collect)
+- Skill system: projectile, doppelganger, coin drop/transaction
+- Bot AI: hostile/passive behavior, A\* pathfinding, aggro, respawn
+- FrozenInteractionState entry/exit (`freeze_start`/`freeze_end`)
+- ObjectLayer hot-reload via gRPC manifest diff (incremental update without restart)
+- Go server metrics REST API (`/api/v1/metrics*`)
+- Procedural content pipeline: floor, skin, resource semantic generators
+- CLI toolchain: `cyberia ol`, `cyberia instance`, `cyberia run-workflow`
+
+### Remaining work for Pre-Alpha checkpoint
+
+All items below target selected-user testing with **ephemeral, in-memory sessions** (state resets on disconnect):
+
+| Task                            | Component                           | Notes                                                                                      |
+| ------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| NPC action routing in Go server | `cyberia-server`                    | Tap NPC entity → look up `CyberiaAction` from gRPC-loaded data; dispatch to action handler |
+| Dialogue system integration     | `cyberia-server` + `cyberia-client` | `freeze_start` → client shows dialogue modal; server validates talk objectives             |
+| Shop transaction handler        | `cyberia-server`                    | Deduct coin balance, grant item to inventory (in-memory only)                              |
+| Craft transaction handler       | `cyberia-server`                    | Consume ingredients from in-memory inventory, grant output items                           |
+| Quest tracking (in-memory)      | `cyberia-server`                    | `CyberiaQuestProgress` lives only in player session struct; no persistence                 |
+| Quest objective evaluation      | `cyberia-server`                    | Intercept kill/collect/talk events; update in-memory progress                              |
+| Quest reward delivery           | `cyberia-server`                    | On step/quest completion: grant items + coins via FCT                                      |
+| Action/quest data via gRPC      | `proto + engine + go`               | Extend `GetFullInstanceResponse` with `CyberiaAction[]` and `CyberiaQuest[]`               |
+| Portal transitions              | `cyberia-server`                    | Implement inter-map portal traversal (`portal` entity type collision)                      |
+| Player capacity queue           | `cyberia-server`                    | FIFO queue with `/api/v1/queue-status` SSE; deny connect when at capacity                  |
+
+### Pre-Alpha data contract
+
+```
+Player session (in-memory Go struct only):
+  PlayerState {
+    ID:           string         // ephemeral UUID per connect
+    ObjectLayers: []ObjectLayerState  // equipped item IDs + active flags
+    CoinBalance:  uint32         // Fountain/Sink coin wallet
+    QuestProgress: []QuestProgress  // ephemeral quest state (no persistence)
+    Frozen:       bool
+    MapCode:      string
+    Pos:          Vec2
+    Life:         float64
+  }
+```
+
+No account, no persistent identity, no cross-session carry-over.
+
+---
+
+## Phase 2 — Alpha: Centralized Off-Chain (Persistent Sessions)
+
+**Target:** Persistent player identity, inventory, and progress stored in MongoDB via gRPC.
+
+### Architecture additions
+
+```
+cyberia-server (Go)
+  ↕ gRPC (new RPCs: GetPlayerState, SavePlayerState, CreateSession, etc.)
+engine-cyberia (Node.js)
+  ↕ MongoDB
+    User (src/api/user)     — account: email, username, password, sessions
+    PlayerState (new model) — per-player: inventory, coin balance, quest progress
+```
+
+### Milestone goals
+
+| Task                       | Component        | Notes                                                                |
+| -------------------------- | ---------------- | -------------------------------------------------------------------- |
+| `GetPlayerState` gRPC RPC  | `proto + engine` | Returns saved inventory + coin balance + quest progress for a userId |
+| `SavePlayerState` gRPC RPC | `proto + engine` | Persists player state on clean disconnect or periodic checkpoint     |
+| User model integration     | `engine-cyberia` | Existing `src/api/user` (email/username/password + session tokens)   |
+| Player state model         | `engine-cyberia` | New `src/api/player-state` Mongoose model linked to User             |
+| Go server session auth     | `cyberia-server` | On connect: verify session token with Engine, load persistent state  |
+| Go server state checkpoint | `cyberia-server` | Periodic or on-disconnect `SavePlayerState` gRPC call                |
+| Alpha gRPC contract        | `proto`          | New service or new RPCs within `CyberiaDataService`                  |
+
+### Data contract (alpha)
+
+```
+User (MongoDB):
+  email, username, passwordHash, role, activeSessions[]
+
+PlayerState (MongoDB):
+  userId: ObjectId → User
+  instanceCode: string
+  coinBalance: uint32
+  inventory: [{ itemId: string, active: bool, quantity: int }]
+  questProgress: [{ questCode: string, stepId: string, objectives: [...] }]
+```
+
+---
+
+## Phase 3 — Beta: On-Chain (Decentralized, ETH-Key Sessions)
+
+**Target:** Frictionless, zero-gas transactions directly with Ethereum secp256k1 keys on Hyperledger Besu. Full Object Layer ownership, interoperability, and decentralized player progress sync.
+
+### Architecture additions
+
+```
+cyberia-client (C/WASM)
+  → EIP-712 sign-on: sign { domain, address, timestamp } with ETH private key
+    → session token = EIP-712 signature (no password)
+      → Engine verifies signature against ObjectLayerToken deployer / public address
+        → Go server loads on-chain inventory from ERC-1155 balances
+
+Hyperledger Besu (IBFT2/QBFT, chainId 777771, gasPrice 0)
+  ObjectLayerToken (ERC-1155)
+    Token 0:       CKY fungible (10M initial supply, 18 decimals)
+    Token IDs ≥ 1: Object Layer items (NFT supply=1, semi-fungible supply>1)
+```
+
+### Key properties
+
+- **Zero-gas transactions** — Besu permissioned network, `gasPrice: 0` for all players.
+- **secp256k1 key = player identity** — same key pair authenticates across all three domains (`cryptokoyn.net`, `itemledger.com`, `cyberiaonline.com`).
+- **Inventory = ERC-1155 balances** — `balanceOf(playerAddress, tokenId)` is the authoritative inventory.
+- **No server-side wallet custody** — player holds their own key; the server validates on-chain state.
+- **Interoperability** — items owned on-chain can be used in any Cyberia instance that queries `ObjectLayerToken`.
+- **Decentralized progress sync** — quest progress and equipment state checkpointed to Besu events.
+
+### EIP-712 domain
+
+```json
+{
+  "name": "CyberiaObjectLayer",
+  "version": "1",
+  "chainId": 777771,
+  "verifyingContract": "<ObjectLayerToken address>"
+}
+```
+
+### Milestone goals
+
+| Task                             | Component             | Notes                                                                                          |
+| -------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------- |
+| EIP-712 sign-on in C client      | `cyberia-client`      | JS bridge calls `ethers.signTypedData` (MetaMask or injected key)                              |
+| Signature verification in Engine | `engine-cyberia`      | REST endpoint verifies EIP-712 sig; returns session token                                      |
+| On-chain inventory read          | `engine-cyberia`      | `balanceOf` query on ObjectLayerToken per item type for player address                         |
+| On-chain inventory → gRPC        | `proto + engine + go` | `GetPlayerState` returns on-chain balances as inventory                                        |
+| CKY transfer via Go server       | `cyberia-server`      | Kill transfer calls Engine which calls `ObjectLayerToken.safeTransferFrom` via gasless relayer |
+| Gasless relayer                  | `engine-cyberia`      | Engine holds the coinbase key; signs and submits Besu transactions on behalf of players        |
+| Item registration pipeline       | `cyberia chain` CLI   | `cyberia chain register` / `batch-register` to publish ObjectLayer items on-chain              |
+| ItemFCT on-chain binding         | `cyberia-server`      | ItemGain/Loss FCT events trigger Engine relayer to mint/burn on Besu                           |
+
+---
+
+## Domain Architecture
+
+| Domain              | Role                       | Smart Contract                 |
+| ------------------- | -------------------------- | ------------------------------ |
+| `cryptokoyn.net`    | CKY fungible token hub     | ObjectLayerToken Token ID 0    |
+| `itemledger.com`    | Object Layer item registry | ObjectLayerToken Token IDs ≥ 1 |
+| `cyberiaonline.com` | Game runtime               | Uses both token domains        |
+
+---
+
+## Technology Stack Summary
+
+| Layer            | Technology                       | Purpose                     |
+| ---------------- | -------------------------------- | --------------------------- |
+| Game client      | C / WASM / Emscripten / Raylib   | In-browser rendering        |
+| Game server      | Go / chi / gorilla WS            | Real-time AOI               |
+| Engine           | Node.js / Express / Mongoose     | Data persistence + gRPC     |
+| Database         | MongoDB (StatefulSet)            | Game world data             |
+| Cache            | Valkey                           | Session cache               |
+| Asset storage    | IPFS + Kubo + IPFS Cluster       | Content-addressed assets    |
+| Inter-service    | gRPC + Protobuf                  | Go ↔ Node.js data pipeline  |
+| Blockchain       | Hyperledger Besu (IBFT2/QBFT)    | Permissioned EVM            |
+| Smart contracts  | Solidity 0.8.27 / OpenZeppelin 5 | ERC-1155 ObjectLayerToken   |
+| Contract tooling | Hardhat 3.x + Ethers v6          | Compile, test, deploy       |
+| Infrastructure   | Kubernetes (kubeadm / kind)      | Container orchestration     |
+| Infra CLI        | Underpost CLI                    | Bare-metal automation       |
+| Game CLI         | Cyberia CLI (extends Underpost)  | Content + economy toolchain |

package/src/client/public/cyberia-docs/UNDERPOST-PLATFORM.md

@@ -0,0 +1,106 @@
+# Underpost Platform
+
+Underpost Platform is the base product. It owns the toolchain, deployment surface, PWA delivery, and operational infrastructure. Cyberia is an MMO extension that runs on top of it; Cyberia is not the platform.
+
+---
+
+## Toolchain and base infrastructure
+
+Underpost Platform covers the shared delivery surface for applications and extensions:
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+The platform is the operational backbone. It should stay the source of truth for deploy IDs, runtime selection, host/path layout, generated client assets, and environment resolution.
+
+---
+
+## Underpost CLI
+
+`underpost` is the shared control surface for platform operations. Top-level commands (`underpost <cmd> --help` for options):
+
+| Group              | Command     | Purpose                                                       |
+| ------------------ | ----------- | ------------------------------------------------------------- |
+| **Project / repo** | `new`       | Initialize a new project, service, or configuration           |
+|                    | `clone`     | Clone a GitHub repository into the current directory          |
+|                    | `pull`      | Pull latest changes from a repository                         |
+|                    | `cmt`       | Manage commits (commit types and options)                     |
+|                    | `push`      | Push committed changes to a remote repository                 |
+|                    | `install`   | Import Underpost npm dependencies by copying                  |
+|                    | `root`      | Print the npm installation root path                          |
+| **Build / config** | `client`    | Build client assets / single replicas; sync environment ports |
+|                    | `static`    | Static build of pages, bundles, and documentation             |
+|                    | `env`       | Set env vars and config for a deploy ID                       |
+|                    | `config`    | Manage Underpost configuration via operators                  |
+|                    | `metadata`  | Import/export cluster metadata                                |
+| **Deploy / infra** | `cluster`   | Manage Kubernetes clusters (defaults to Kind init)            |
+|                    | `deploy`    | Manage deployments (defaults to development pods)             |
+|                    | `image`     | Build, save, and load Docker images into clusters             |
+|                    | `secret`    | Manage secrets across platforms                               |
+|                    | `lxd`       | Manage LXD VMs as K3s nodes (control plane / workers)         |
+|                    | `baremetal` | Bare-metal provisioning workflows                             |
+|                    | `ip`        | Show current public machine IP addresses                      |
+| **Data / ops**     | `db`        | Database backup / restore and related operations              |
+|                    | `cron`      | Run cron jobs or generate/apply K8s CronJob manifests         |
+|                    | `fs`        | File storage (defaults to upload)                             |
+|                    | `monitor`   | Health-server monitoring for deployments                      |
+|                    | `ssh`       | Manage SSH credentials and sessions for cluster nodes         |
+|                    | `run`       | Run scripts via named runners                                 |
+|                    | `test`      | Run the test suites                                           |
+|                    | `release`   | Release orchestrator for building and shipping CLI versions   |
+
+Cyberia-specific operations belong in `cyberia`, not in parallel platform commands. Use the base CLI for infrastructure and delivery, then layer Cyberia workflows on top.
+
+---
+
+## PWA delivery model
+
+Every deployed client is delivered as a static application shell with PWA support.
+
+- SSR views declare which pages exist and which fallbacks are precached.
+- The service worker is generated from the configured view set.
+- Offline and maintenance fallbacks are part of the build output, not hand-maintained runtime artifacts.
+- Generated outputs such as `sw.js`, static pages, and compiled bundles are outputs only; never edit them by hand.
+
+```text
+conf.dd-*.js / conf.ssr.json    +    src/client/sw/core.sw.js
+			   │
+			   └──── underpost client / build ────▶ generated index.html + sw.js + precache
+```
+
+Keep those two inputs as the only authored PWA sources.
+
+---
+
+## Cyberia on top of the platform
+
+Cyberia adds a three-service MMO runtime on top of the base platform:
+
+| Service          | Responsibility                                                            |
+| ---------------- | ------------------------------------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata |
+| `cyberia-server` | authoritative simulation and tick processing                              |
+| `cyberia-client` | rendering, input, prediction, presentation                                |
+
+---
+
+## Operational rules
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts as outputs only; never hand-edit them.
+- `engine-private/` is a private external dependency. Reference it as private input only and never assume its contents exist locally.
+
+---
+
+## Safety and orchestration
+
+- Any host-level change must be idempotent, reversible, and explicit.
+- Never assume mounts, users, groups, namespaces, or volumes already exist.
+- Validate before mutating: check paths, permissions, ownership, and target state first.
+- Keep orchestration scripts resilient to interruption and safe to rerun.