@underpostnet/cyberia 3.3.0 → 3.3.73

package/.dockerignore

@@ -6,6 +6,7 @@
 /logs
 /build
 /.env
+/.underpost
 /coverage
 /prometheus_data
 /grafana_data

package/.github/workflows/coverall.cyberia.ci.yml

@@ -9,11 +9,14 @@ on:
 jobs:
   test:
     name: Coverall Cyberia Test
+    # Deliberately not the engine repository: two coverage workflows on one commit
+    # are two Coveralls builds, and the badge then shows whichever landed last
+    # rather than the tree's coverage. The engine is served by coverall.ci.yml.
     if: |
       github.actor != 'dependabot[bot]' &&
-      (github.repository == 'underpostnet/engine' ||
-       github.repository == 'underpostnet/engine-cyberia' ||
-       github.repository == 'underpostnet/engine-ghpkg-cyberia')
+      (github.repository == 'underpostnet/engine-cyberia' ||
+       github.repository == 'underpostnet/engine-ghpkg-cyberia' ||
+       github.repository == 'underpostnet/engine-test-cyberia')
     runs-on: ubuntu-latest
     container:
       image: quay.io/rockylinux/rockylinux:9
@@ -34,11 +37,18 @@ jobs:
       - name: Install project dependencies
         run: npm install
 
-      - name: Run tests and generate coverage
-        run: scripts/coverall-test-cyberia.sh
+      # Set the COVERAGE_MIN repository variable to gate below the shipped
+      # default while the suite is catching up to it.
+      - name: Run tests and enforce coverage threshold
+        run: COVERAGE_ENFORCE=1 node bin test unit,infra,app,cyberia
+        env:
+          COVERAGE_MIN: ${{ vars.COVERAGE_MIN }}
 
+      # Stored even when the threshold step failed — that step still fails the
+      # job, but without the report the badge freezes at the last passing build.
       - name: Store coverage report
-        uses: actions/upload-artifact@v4
+        if: '!cancelled()'
+        uses: actions/upload-artifact@v7
         with:
           name: coverall-cyberia-lcov
           path: ./coverage/lcov.info
@@ -47,18 +57,23 @@ jobs:
   upload:
     name: Upload Cyberia Coverage to Coveralls
     needs: test
+    # Host runner, not the Rocky container the suite runs in: every step of the
+    # Coveralls action declares `shell: bash`, which the runner execs inside the
+    # job container and cannot resolve there.
     if: |
+      !cancelled() &&
       github.actor != 'dependabot[bot]' &&
-      (github.repository == 'underpostnet/engine' ||
-       github.repository == 'underpostnet/engine-cyberia' ||
-       github.repository == 'underpostnet/engine-ghpkg-cyberia')
+      (github.repository == 'underpostnet/engine-cyberia' ||
+       github.repository == 'underpostnet/engine-ghpkg-cyberia' ||
+       github.repository == 'underpostnet/engine-test-cyberia')
     runs-on: ubuntu-latest
     steps:
+      # Coveralls reads the commit and branch metadata from the checkout.
       - name: Clone repository
         uses: actions/checkout@v7
 
       - name: Restore coverage report
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: coverall-cyberia-lcov
           path: ./coverage
@@ -68,16 +83,21 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           file: ./coverage/lcov.info
-          flag-name: cyberia
+          format: lcov
           parallel: true
+          fail-on-error: true
 
   finish:
+    name: Finish Cyberia Coveralls build
     needs: upload
+    # The build stays open until this webhook lands, so it runs on any upload
+    # outcome rather than leaving a half-reported build behind.
     if: |
+      !cancelled() &&
       github.actor != 'dependabot[bot]' &&
-      (github.repository == 'underpostnet/engine' ||
-       github.repository == 'underpostnet/engine-cyberia' ||
-       github.repository == 'underpostnet/engine-ghpkg-cyberia')
+      (github.repository == 'underpostnet/engine-cyberia' ||
+       github.repository == 'underpostnet/engine-ghpkg-cyberia' ||
+       github.repository == 'underpostnet/engine-test-cyberia')
     runs-on: ubuntu-latest
     steps:
       - name: Notify Coveralls Finished

package/.github/workflows/cyberia-client.cd.yml

@@ -32,4 +32,9 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            # Carried across the SSH hop so the far side reports in GitHub Actions form:
+            # deploy/lib/github-actions-logging.sh folds its monitor frames into collapsed groups, and the
+            # state domain's telemetry export emits ::notice::/::error:: annotations this job
+            # surfaces. GITHUB_ACTIONS itself is a runner-local variable and does not travel.
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/cyberia-client/deploy.sh

package/.github/workflows/cyberia-server.cd.yml

@@ -32,4 +32,9 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            # Carried across the SSH hop so the far side reports in GitHub Actions form:
+            # deploy/lib/github-actions-logging.sh folds its monitor frames into collapsed groups, and the
+            # state domain's telemetry export emits ::notice::/::error:: annotations this job
+            # surfaces. GITHUB_ACTIONS itself is a runner-local variable and does not travel.
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/cyberia-server/deploy.sh

package/.github/workflows/docker-image.cyberia-client.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -34,9 +34,15 @@ jobs:
       - name: Build cyberia-server SSR dashboard
         working-directory: engine
         run: |
-          node bin/deploy cyberia
+          node bin package dd-cyberia --install
           node bin/cyberia run-workflow build-cyberia-404 --output-path ../assets/404/index.html
 
+      - name: Stage underpost CLI package
+        working-directory: engine
+        # Bakes the CLI into the runtime image from this checkout instead of the registry, so a
+        # starting pod never fetches it. The Dockerfiles COPY ../underpost-cli.tgz.
+        run: node bin/cyberia run-workflow stage-cli --output-path ..
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -65,7 +71,4 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-
-          build-args: |
-            UNDERPOST_VERSION=${{ env.UNDERPOST_VERSION }}
             BUILD_MODE=RELEASE

package/.github/workflows/docker-image.cyberia-client.dev.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -34,9 +34,15 @@ jobs:
       - name: Build cyberia-server SSR dashboard
         working-directory: engine
         run: |
-          node bin/deploy cyberia
+          node bin package dd-cyberia --install
           node bin/cyberia run-workflow build-cyberia-404 --output-path ../assets/404/index.html
 
+      - name: Stage underpost CLI package
+        working-directory: engine
+        # Bakes the CLI into the runtime image from this checkout instead of the registry, so a
+        # starting pod never fetches it. The Dockerfiles COPY ../underpost-cli.tgz.
+        run: node bin/cyberia run-workflow stage-cli --output-path ..
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -66,5 +72,4 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
-            UNDERPOST_VERSION=${{ env.UNDERPOST_VERSION }}
             BUILD_MODE=DEBUG

package/.github/workflows/docker-image.cyberia-server.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -34,10 +34,16 @@ jobs:
       - name: Build cyberia-server SSR dashboard
         working-directory: engine
         run: |
-          node bin/deploy cyberia
+          node bin package dd-cyberia --install
           node bin/cyberia run-workflow build-server-dashboard --output-path ../public/index.html
           node bin/cyberia run-workflow build-cyberia-404 --output-path ../public/404/index.html
 
+      - name: Stage underpost CLI package
+        working-directory: engine
+        # Bakes the CLI into the runtime image from this checkout instead of the registry, so a
+        # starting pod never fetches it. The Dockerfiles COPY ../underpost-cli.tgz.
+        run: node bin/cyberia run-workflow stage-cli --output-path ..
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -66,6 +72,3 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-
-          build-args: |
-            UNDERPOST_VERSION=${{ env.UNDERPOST_VERSION }}

package/.github/workflows/docker-image.cyberia-server.dev.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -34,10 +34,16 @@ jobs:
       - name: Build cyberia-server SSR dashboard (dev)
         working-directory: engine
         run: |
-          node bin/deploy cyberia
+          node bin package dd-cyberia --install
           node bin/cyberia run-workflow build-server-dashboard --dev --output-path ../public/index.html
           node bin/cyberia run-workflow build-cyberia-404 --output-path ../public/404/index.html
 
+      - name: Stage underpost CLI package
+        working-directory: engine
+        # Bakes the CLI into the runtime image from this checkout instead of the registry, so a
+        # starting pod never fetches it. The Dockerfiles COPY ../underpost-cli.tgz.
+        run: node bin/cyberia run-workflow stage-cli --output-path ..
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -66,6 +72,3 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-
-          build-args: |
-            UNDERPOST_VERSION=${{ env.UNDERPOST_VERSION }}

package/.github/workflows/docker-image.engine-cyberia.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -16,6 +16,20 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24.x'
+
+      - name: Install engine dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Stage underpost CLI package
+        # Bakes the CLI into the image from this checkout instead of the registry, so a starting
+        # pod never fetches it. The Dockerfiles COPY underpost-cli.tgz from the build context,
+        # which for this workflow is the repository root.
+        run: node bin/cyberia run-workflow stage-cli --output-path .
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 

package/.github/workflows/docker-image.engine-cyberia.dev.ci.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  UNDERPOST_VERSION: '3.3.0'
+  UNDERPOST_VERSION: '3.3.73'
 
 jobs:
   build-and-push:
@@ -16,6 +16,20 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24.x'
+
+      - name: Install engine dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Stage underpost CLI package
+        # Bakes the CLI into the image from this checkout instead of the registry, so a starting
+        # pod never fetches it. The Dockerfiles COPY underpost-cli.tgz from the build context,
+        # which for this workflow is the repository root.
+        run: node bin/cyberia run-workflow stage-cli --output-path .
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 

package/.github/workflows/engine-cyberia.cd.yml

@@ -40,6 +40,7 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/dd-cyberia/deploy.sh
   sync-and-deploy:
     if: github.event.inputs.job == 'sync-and-deploy'
@@ -65,6 +66,7 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/dd-cyberia/sync-deploy.sh
   init:
     if: github.event.inputs.job == 'init'
@@ -90,4 +92,5 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/dd-cyberia/init.sh

package/.github/workflows/engine-cyberia.ci.yml

@@ -62,13 +62,12 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GIT_AUTH_TOKEN }}
           GITHUB_USERNAME: ${{ github.repository_owner }}
+          # Never interpolated into the script: the propagated payload is multi-line and a shell
+          # expansion would corrupt entries holding `$` and execute anything in `$(...)`.
+          PROPAGATED_MESSAGE: ${{ github.event.inputs.message }}
         run: |
           cd .. && node engine/bin clone underpostnet/pwa-microservices-template
-          if [ -n "${{ github.event.inputs.message }}" ]; then
-            LAST_COMMIT_MESSAGE="${{ github.event.inputs.message }}"
-          else
-            LAST_COMMIT_MESSAGE=$(cd engine && node bin cmt --changelog-msg --from-n-commit 1 --changelog-no-hash 2>/dev/null || echo "")
-          fi
+          LAST_COMMIT_MESSAGE=$(cd engine && node bin cmt --propagate-msg 2>/dev/null || echo "")
           SHOULD_CD="${{ github.event.inputs.sync }}"
           DEPLOY_TYPE="${{ github.event.inputs.deploy_type }}"
           if [ -z "$LAST_COMMIT_MESSAGE" ]; then

package/.github/workflows/ghpkg.ci.yml

@@ -48,20 +48,30 @@ jobs:
           curl -fsSL https://rpm.nodesource.com/setup_24.x | bash -
           dnf install nodejs -y
 
-      - name: Capture commit message
-        run: |
-          FULL_MSG="${{ github.event.head_commit.message }}"
-          LAST_COMMIT_MESSAGE="${FULL_MSG:-update package}"
-          echo "LAST_COMMIT_MESSAGE<<EOF" >> $GITHUB_ENV
-          echo "$LAST_COMMIT_MESSAGE" >> $GITHUB_ENV
-          echo "EOF" >> $GITHUB_ENV
-          echo "[INFO] Commit message: $LAST_COMMIT_MESSAGE"
-
       - name: Install dependencies and set repo configuration
         run: |
           npm install
-          node ./bin/deploy rename-package @underpostnet/underpost
-          node ./bin/deploy set-repo underpostnet/pwa-microservices-template-ghpkg
+          node ./bin package --rename @underpostnet/underpost
+          node ./bin package --set-repo underpostnet/pwa-microservices-template-ghpkg
+
+      # Placed after the install because it resolves the payload through the CLI, which needs the
+      # dependencies. The push that triggers this job carries the payload the engine propagated.
+      - name: Capture commit message
+        env:
+          # Never interpolated into the script: the propagated payload is multi-line and a shell
+          # expansion would corrupt entries holding `$` and execute anything in `$(...)`.
+          PROPAGATED_MESSAGE: ${{ github.event.head_commit.message }}
+        run: |
+          LAST_COMMIT_MESSAGE=$(node ./bin cmt --propagate-msg 2>/dev/null || echo "")
+          if [ -z "$LAST_COMMIT_MESSAGE" ]; then
+            LAST_COMMIT_MESSAGE="update package"
+          fi
+          {
+            echo "LAST_COMMIT_MESSAGE<<PROPAGATION_EOF"
+            echo "$LAST_COMMIT_MESSAGE"
+            echo "PROPAGATION_EOF"
+          } >> $GITHUB_ENV
+          echo "[INFO] Commit message: $LAST_COMMIT_MESSAGE"
 
       - name: Set git global credentials
         run: |
@@ -124,15 +134,20 @@ jobs:
           echo "[INFO] Canonical github package repo: underpostnet/engine-ghpkg-$CONF_ID"
 
       - name: Capture commit message
+        env:
+          # Never interpolated into the script: the propagated payload is multi-line and a shell
+          # expansion would corrupt entries holding `$` and execute anything in `$(...)`.
+          PROPAGATED_MESSAGE: ${{ github.event.inputs.message }}
         run: |
-          FULL_MSG="${{ github.event.inputs.message }}"
-          if [ -z "$FULL_MSG" ]; then
-            FULL_MSG=$(node bin cmt --changelog-msg --from-n-commit 1 --changelog-no-hash 2>/dev/null || echo "")
+          LAST_COMMIT_MESSAGE=$(node bin cmt --propagate-msg 2>/dev/null || echo "")
+          if [ -z "$LAST_COMMIT_MESSAGE" ]; then
+            LAST_COMMIT_MESSAGE="Update canonical github package repo"
           fi
-          LAST_COMMIT_MESSAGE="${FULL_MSG:-Update canonical github package repo}"
-          echo "LAST_COMMIT_MESSAGE<<EOF" >> $GITHUB_ENV
-          echo "$LAST_COMMIT_MESSAGE" >> $GITHUB_ENV
-          echo "EOF" >> $GITHUB_ENV
+          {
+            echo "LAST_COMMIT_MESSAGE<<PROPAGATION_EOF"
+            echo "$LAST_COMMIT_MESSAGE"
+            echo "PROPAGATION_EOF"
+          } >> $GITHUB_ENV
           echo "[INFO] Commit message: $LAST_COMMIT_MESSAGE"
 
       - name: Set git global credentials
@@ -152,8 +167,8 @@ jobs:
           cd engine-$CONF_ID
           rm -rf ./.git
           mv ../$GHPKG_REPO.git ./.git
-          node ../engine/bin/deploy rename-package "$PACKAGE_NAME"
-          node ../engine/bin/deploy set-repo underpostnet/$GHPKG_REPO
+          node ../engine/bin package --rename "$PACKAGE_NAME"
+          node ../engine/bin package --set-repo underpostnet/$GHPKG_REPO
           git init
           git config user.name 'underpostnet'
           git config user.email 'development@underpost.net'

package/.github/workflows/hardhat.ci.yml

@@ -5,13 +5,10 @@ name: CI | Hardhat
 
 on:
   push:
-    paths:
-      - 'hardhat/**'
-      - '.github/workflows/hardhat.ci.yml'
+    branches: ['master', 'main']
   pull_request:
-    paths:
-      - 'hardhat/**'
-      - '.github/workflows/hardhat.ci.yml'
+    branches: ['master', 'main']
+
   workflow_dispatch:
 
 permissions:
@@ -20,6 +17,11 @@ permissions:
 jobs:
   build-and-test:
     name: Compile, Test & Audit
+    if: |
+      github.actor != 'dependabot[bot]' &&
+      (github.repository == 'underpostnet/engine-cyberia' ||
+       github.repository == 'underpostnet/engine-ghpkg-cyberia' ||
+       github.repository == 'underpostnet/engine-test-cyberia')
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -59,18 +61,17 @@ jobs:
 
       # ── Compile ──────────────────────────────────────────────────────────
       - name: Compile Solidity contracts
-        run: npx hardhat compile
+        run: npm run compile
 
       # ── Test ─────────────────────────────────────────────────────────────
       - name: Run tests
-        run: npx hardhat test
+        run: npm test
         env:
           REPORT_GAS: 'true'
 
-      # ── Coverage (optional, only on primary Node version) ────────────────
+      # ── Coverage ─────────────────────────────────────────────────────────
       - name: Solidity coverage
-        if: matrix.node-version == '20'
-        run: npx hardhat coverage
+        run: npm run coverage
 
       # ── Lockfile integrity check ─────────────────────────────────────────
       # Fail if package-lock.json is out of sync with package.json

package/.github/workflows/npmpkg.ci.yml

@@ -51,26 +51,28 @@ jobs:
           curl -fsSL https://rpm.nodesource.com/setup_24.x | bash -
           dnf install nodejs -y
 
+      - name: Install dependencies
+        run: npm install
+
+      # Placed after the install because it resolves the payload through the CLI, which needs the
+      # dependencies. The dispatch input wins; a push carries its own commit message instead.
       - name: Capture commit message
+        env:
+          # Never interpolated into the script: the propagated payload is multi-line and a shell
+          # expansion would corrupt entries holding `$` and execute anything in `$(...)`.
+          PROPAGATED_MESSAGE: ${{ github.event.inputs.message || github.event.head_commit.message }}
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            LAST_COMMIT_MESSAGE="${{ github.event.inputs.message }}"
-            if [ -z "$LAST_COMMIT_MESSAGE" ]; then
-              LAST_COMMIT_MESSAGE="Update repository"
-            fi
-          else
-            FULL_MSG="${{ github.event.head_commit.message }}"
-            REST="$(echo "$FULL_MSG" | tail -n +2 | awk 'NR==1{first=$0; has_first=1; next} NR==2{print first " " $0; has_first=0; next} {print} END{if(has_first) print first}')"
-            LAST_COMMIT_MESSAGE="${REST:-$FULL_MSG}"
+          LAST_COMMIT_MESSAGE=$(node bin cmt --propagate-msg 2>/dev/null || echo "")
+          if [ -z "$LAST_COMMIT_MESSAGE" ]; then
+            LAST_COMMIT_MESSAGE="Update repository"
           fi
-          echo "LAST_COMMIT_MESSAGE<<EOF" >> $GITHUB_ENV
-          echo "$LAST_COMMIT_MESSAGE" >> $GITHUB_ENV
-          echo "EOF" >> $GITHUB_ENV
+          {
+            echo "LAST_COMMIT_MESSAGE<<PROPAGATION_EOF"
+            echo "$LAST_COMMIT_MESSAGE"
+            echo "PROPAGATION_EOF"
+          } >> $GITHUB_ENV
           echo "[INFO] Extracted payload: $LAST_COMMIT_MESSAGE"
 
-      - name: Install dependencies
-        run: npm install
-
       - name: Set git global credentials
         run: |
           git config --global --add safe.directory '*'

package/.github/workflows/pwa-microservices-template-test.ci.yml

@@ -1,4 +1,4 @@
-name: CI | Gihub page | PWA Microservices Template Test
+name: CI | PWA Microservices | Unit & Infra Tests
 
 on: [push]
 
@@ -30,4 +30,4 @@ jobs:
         run: npm install
 
       - name: Run test
-        run: scripts/coverall-test.sh
+        run: node bin test unit,infra

package/.github/workflows/release.cd.yml

@@ -35,4 +35,5 @@ jobs:
           script: |
             set -e
             set -o pipefail
+            export RUN_QUIET_CI=github
             bash /home/dd/engine/deploy/release/deploy.sh

package/.prettierignore

@@ -6,6 +6,7 @@
 /build
 /.env
 /coverage
+/allure-results
 /prometheus_data
 /grafana_data
 .nyc_output

package/AGENTS.md

@@ -0,0 +1,47 @@
+## Commenting policy
+
+- Keep code comments minimal, no redundant or lengthy comment.
+- Prefer clear names, small functions, and extracted helpers over explanatory comments.
+- Comment only non-obvious intent: invariants, protocol boundaries, security constraints, cross-process contracts, or temporary workarounds.
+- Remove stale, redundant, or narrative comments during refactors.
+- Use `TODO:` only for concrete, actionable follow-ups.
+
+## Consistency guardrails
+
+- Keep one source of truth for config, deploy IDs, runtime selection, startup order, and generated assets.
+- Reuse existing helpers, conventions, and resolution logic instead of introducing parallel implementations.
+- Do not duplicate parsing, environment resolution, or path normalization.
+- Keep generated artifacts read-only outputs; never hand-edit them.
+- No dead code, no legacy code, and no legacy concepts.
+- Keep responsibilities explicit and avoid introducing abstractions without a concrete ownership boundary.
+
+## Host, LXD, and orchestration safety
+
+- Treat every host-level change as idempotent, reversible, and explicit.
+- Validate target paths, permissions, ownership, mounts, users, groups, namespaces, and volumes before mutating.
+- Never assume host resources already exist.
+- Prefer dry-run, guarded cleanup, and rollback paths over destructive operations.
+- Protect host-mounted volumes and VM bootstrap flows from partial configuration.
+- Make orchestration safe to interrupt and safe to rerun.
+
+## Testing and verification
+
+- When changing orchestration, bootstrap, config loading, or runtime startup order, add or update focused tests for parsing, validation, and selection logic.
+- For live-service tests, document the required runtime environment and keep execution deterministic.
+- Prefer small, targeted verification over broad manual validation.
+- Verify changed behavior at the closest layer that owns it.
+
+## Cyberia architecture boundaries
+
+- `engine-cyberia` owns content, validation, persistence, gRPC/REST data services, and asset metadata.
+- `cyberia-server` owns authoritative real-time simulation and tick processing.
+- `cyberia-client` owns rendering, input, prediction, reconciliation, and presentation.
+- Keep authoritative simulation out of the client.
+- Keep content-authority and persistence concerns out of the Go runtime.
+- Preserve these boundaries when introducing new flows, APIs, or shared helpers.
+
+## Documentation hot paths
+
+- `src/client/public/nexodev/docs/references/` — Underpost CLI, cluster, baremetal, DB, cron, image, LXD, SSH, and static-generator references.
+- `src/client/public/cyberia-docs/` — Cyberia architecture, server, client, CLI, action, quest, economy, whitepaper, and roadmap documentation.
+- `engine-private/` is private. Do not assume it exists locally; treat references to it as external/private context.