fix(analytics): serve umami via /trace/trace.js and add privacy policy with opt-out switch (#71 )

chore(release): deploy www sha-9200529 [skip ci]
chore(release): deploy docs sha-9200529 [skip ci]
2026-11-01 21:15:39 +03:00 · 2026-10-29 21:15:44 +00:00 · 2026-10-29 21:06:42 +00:00 · 2026-10-30 00:05:44 +03:00 · 2026-10-26 11:22:28 +00:00 · 2026-10-26 14:21:15 +03:00
160 changed files with 4146 additions and 3381 deletions
@@ -2,12 +2,21 @@
 #/            public-key encryption for .env files          /
 #/       [how it works](https://dotenvx.com/encryption)     /
 #/----------------------------------------------------------/
+DOTENV_PUBLIC_KEY_DEV="02a9d0f6522086b04ac7763e008a6ad0273c58258715e613c977fd6c82a2030d92"
+
+# .env.dev
+#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
+#/            public-key encryption for .env files          /
+#/       [how it works](https://dotenvx.com/encryption)     /
+#/----------------------------------------------------------/
 DOTENV_PUBLIC_KEY="02a9d0f6522086b04ac7763e008a6ad0273c58258715e613c977fd6c82a2030d92"

 # .env
-COM_ERMNVLDMR_STATIC_S3_BUCKET="encrypted:BL1vJLB9uPSvsUvrJah4UegRU8uPdFjE7sya+Fae3rwOmVzWsK5+TP4z4YzigTAuwit4FANvANvhRV46se+ZgprYplU8Cw1tZ5mHKO4rWAjif2sJCnsGXUKp8GZ2J7PrMH35MY0YrXX4NVqe18b2NEv2B9K7"
-COM_ERMNVLDMR_STATIC_S3_REGION="encrypted:BAj3iuo7tWWNR2V4yQ+LHnFCB4JcZp7TTfUtvv+2FPntNhwc/fV95IeFWz6S0z6aPRkDG+UQzPXNwdMz7y8ZbTHbduDDrgydHu1fST1NfQd2s1Bbpf+yJTG7dPBSc5RSNKZkkpB4v55qg/UC"
-COM_ERMNVLDMR_STATIC_S3_ENDPOINT_URL="encrypted:BNkQrgsrxtz544vuJbgwWUh5cPjHG5wbmHNcxTUWrzbFJJsdncaAitviCvIrS7Q41w+FiWkssv3D05Tu8Inn2P62E6G3PU4gNxO2oLdmGEdrzUqB/xvxOvLvos42j54QOZf7lOqMPKH6SL2/rheCAo10gSCicCqkfh4xsCAbYpyL"
-COM_ERMNVLDMR_STATIC_AWS_ACCESS_KEY_ID="encrypted:BCsp8p4bp3cB+9grxHo634isRUaFGU3MOc1lr8ClSFRYLjqjqukyrbJCTZWV2Xdo8iQ33EylmbzUltbwzTWMQcjJSvIskesVLyV93q60o/Mu9L9jg/apwHuBgHv4zVuHstJ0zkHWgapbNTIlWD3RCm0ujeX/H1gBH3U="
-COM_ERMNVLDMR_STATIC_AWS_SECRET_ACCESS_KEY="encrypted:BM7aPliOyiPrqFPZMfqpn534Nu+Y0Nbh/YRoxv2KY6XAi2dNO0LSEf97DqSUQYdsnu9iibZmVNktF2K/D6mtHr9+gumF6KsmaLH65KE7c9ly7NdFQHL9I26wxRq1Sr3Zgrfs954J6oURSlBRKqJFdcTsBltuuupGuqJHyLS9+DE0jD+bl0Qg0lA="
+COM_ERMNVLDMR_STATIC_S3_BUCKET="encrypted:BE65d5I9m1jrHGVNKDmfGL3Cjb7LjhB4tVWyNzSPU1Zu5Y00+R8NXgqSBrzBnXVj3vVinibjihVt3fStegyiqI52GtSycX1NlFSVJlRFWadUJ6SVK+SYfB7sFKSJ2jKGfwRaXKMzaKCdPWY+ni685oPXU9Rp"
+COM_ERMNVLDMR_STATIC_S3_REGION="encrypted:BPQ2+ms76A+PLFUeKL1Cnz8bdOcsJou03e8AyGwzdhozpcAwhP5yWXSqhTK8ZccAvmfjJcM4NK+x2a2r4g0ALd/UaQDa9xy2eZ6QnXwkoHXu2ce+F86/HuFnzX0qWqYTWi4q+N4="
+COM_ERMNVLDMR_STATIC_S3_ENDPOINT_URL="encrypted:BCcK2ih1QrABMImpUj31KIQYlbp9zhnafzrXINAwvyCaCjbOst6UGnhhi5M3LtQ+Fhgpx52ZKGjmke1oVxnvU6BBGz/lAbSD5euhHNbJ6EIoSqc25XpcmgucIQGx1cfiJxsL4sDR95FyR3fNaS9KGr005DwQaIRKGg86gALUCPhaLekq/Sd6Nn+TDoqmigLJPozdxp33AFpmWF+EwayYae2u"
+COM_ERMNVLDMR_STATIC_AWS_ACCESS_KEY_ID="encrypted:BPaBvzNo1eH3Z2ro+NFq4zLi4krZQT48h20r0etBfVFLDNS01gh5Uosy70Ip29rC8sa1JoP4Q8isJ2Xz0pr5Vxxa62vVFOJ9wJ6LkXbYF2bUm+UNyjfsIztJsMyiVZfPEEPEEKcniXZ3faqePwgLwCZSTa/Qry6znNmMV5FshSsP"
+COM_ERMNVLDMR_STATIC_AWS_SECRET_ACCESS_KEY="encrypted:BFiOxOo/TNvSIMOjyeOswLcl+9AVdqp4axW+I46c1CL0ckSucQS+7CLpO8fNfakmW2bSibqru+xfWUbQT7FDH1YB3CPXUc0qPm1PsG0FiLixDefQuDrC/JHuA0Z3/dOAkn/e94BBuPtyJXxcLRP1v517MijPa0MuNqhI9BS3jFHKjWivqc9AVPs2ybglo14b/nEO1GqlM0TYflPoDhHoWjM="
 SOPS_AGE_KEY="encrypted:BKiJVxKYhiadu0kNCw8wVLYdaEWZreAVu2PaujxhvcXeCowCGjivEuQD/uhduAy/CwwDWyQkgQJ2FJMEKA47e7QDjS9TMdPCXO19/teR7LThgqTf6AbSM3sebln5zalgyplay4A/7cVytPXuOvVkaYyoh9CgzTVsPJKXRq5yMaDEx/9/91Yo8zUMF3z1vq3/preI5baK4/1xXewR3OwfZqnNGyd7LXkdqyT5"
+COM_ERMNVLDMR_DEV_ROOT_CA_KEY="encrypted:BP+GhCwutIMF2hSxIs92VNSoEAvfdhYRFSi5MUpFfCs+pNxJkZ7tFOAadMqSlPiLBcm9+A3yIn/04/oEtRNjXk/jlZQ2G21mt30sd89NARjJO+94ui6XbllW65E5/T+d8fDmRhz4c4OcNoKk70aXcdJqd1CJT7IlYQn++zQvB2el9cp9e7E22rvGtvum40iISEt/pVU84uHyQg6ZeCn+1czM+nLhPiWOAgveTz3EAgExlJW2de1ilDIuBCFXJy5+KvnCj3WNwRTAbIYgCwFnZMOUE5jYlhP6OZ2DQ3sWv7noG/Xaa/P+EomP9dwcamlAU32tRruyA8ZSp/ah9E8hFfmBqgKfSbRlWq3qGkq/F935DZfU/C+PjRcepS/eLZQ0mfD23B21VX2CjOhEkp5V+9I5L8XkXDjDg56JDRGvF/umpdqF/KpmtimqcgB0yDVY1Z3yT1U5IZ6Yf4WlqzhchdJXRWfo0bqK8Tk0b442/6AQgRP3n6DIrCjcpmr4jx+RJiejOr3xv3QtHGafDdkF2gO7DrYztdd6XpRjij0orBUiyYECgPsLHuwd+/2jXnxLVTavVTQ0Ddz0LLNjaYxqr8KK/B+0MeS/iuLXmACs8XCKwQmV8hPYQ0C/JXGiL4GOH0V70r6ghBxCDDMpJjPasCbiCBxSAMLkQ7ZmLbO0WVPPUTMAsZ8aKUy2MLe466zizXN640B4H6bkI7x/KC29sroEJWpUufD7f+t2tnVx/KLeAxAC6afuUCGi4ibFiwLHZjfimYKaYpuMcSZHQ64iONixyfUDIRNIOWQSiX1V5EBJgBDE0JVDnExmQYAIG5isYQEorC/7z6IJeZHc4NuiKDWuvd+jwwj8tN8PVAcACJKpQHpyUU20kvp4dYgBEeiQZpBfXWrnmOJZ0HgDHbvVxPW+SHTL/uoi/Tl9xdKe+z3Q/MoT8iYXggMPcFQIqVemQUTw9Tu0oNsSj3xueR9awJc2Le9aYbKTg54MAtcBnfKXN+3cYQkNVbqC5RfiAe2D3gfbT1OgApTUNz8n8v1dgAzTa+EB0i+w8nTsb3N/N4yAXMNSKdGeUl2rFRuQO7qlWorKc3pE+nBC2ex0sOMEUFYUXcyULaxsKM3ddakCAv9/jesnkrZl2gX7YDp8iqiFzh7l8jMAFHtFCMp3CSXlBAOpfQlGLY80qTSi1e8GrnV9Ow9t0DdS1wP7J6ES9DiNuEep5atHD+0MC6u0Dw0GtmsNnNRp77my/KI8ILhF4VBVBFQ5BiJDfdpAA3RNlANo2gK5ZCKPw4tXCYUknjYdwkqvUaIQCJcr2n+WkE2eCUCqjXTFr/KMvRByY6Fb1vAwcGoCWjP2g0Tliz3hcyh/72+umn05NO3cJSAfDEjfcYBUQZ/LCcy86G0EsHXP3NabgeHNXf/Z/VG7zWqQAPX0KaVrF9XC6I2FLkg1aNGWZfJGv4uohdIny7rWU7FWPaxy9GMk6x7xBh/Hk/5/rrGHCNGs+SegLglDs2+v4P56316k4kg//dmVl/vh3h0KC2P/1xiJZ10I91k7HqZLb2qdXToa4yOHB5Euu49UV/Qtv+cZU03fuT81sEv3YT819OdmwUZgkq0PT/Lrck+pbNDaUOakpgkGAbXy6SCvjM87jYN9Ia7druulWWO0pPi4T8daQ26ZQmZp57gdkpuh/He4kC5m1aWpT2s5STSbapChd9tFNjPhjCG1DZb7h0X8jg1VkxqutDDu17jOXrhElT1ejvYqYy9lIG1b1r7Jmjxo7LgGQuPMX6CIo/BLTsuNJyC5SfSCxEm56LvJgoNk2Vaeq6mLDOaKm2PNwPuYPnJw9xWBM0EetJBnsYMutPDMXhrB7x/8DKy5/hCsKICTfhlsboUHmbSfsikvGPYx7YOaOo8xFh4yAQ73T8hFX7kn2DBfRzGkJm8SQJRPj0Hjsf5mEFUt/OrieK/Jw10HKD6hDoEFmUDv5svC3nUY0FX0fTyi0jRAri+burrCQ0HXk/qj4Xs+WLiJgfQbprV2TwTIlzOdLb/jD8PeiElNzBxmOonRj76QKcbkOnPkCWCMFKapOJskxe0ASJVjYt142D0ndTa6F7oFu72ue5U+hyoToKeb7ONZilhF0+yL7akNfFKURUa/X+cEoewuSM7r8whWwZyG+M2cwGUTRMJiAC9wK7yE8MqdrEuQtILnCA0yRTPOh1Z9ifUY0asL1Tw9cbdGRW8svHH/oVHkWe3P+yepTNrn7xQlX/O1/p4FXRm0gSE3Fdnbli8VZdwVn2SET3WkPH9rJT2F7/hovfhx+lQzBQq9ZBpNLrWRdhXzCpiaC04o7q/eef+8dZwU62A1pd8uZ+0dI5T7lOVXoo03uF863YSOKX8ad2CiYUJ8gMvMA8FSWnsUbxiDaiXPj8kni5TLsvrkH/CKY/okG5SdRCF/XCcRcXP5dxdsS90tIWdd0xi/2wbalmn3CPQ2eVeDI3dP/jCRBkfiNtD70flhxVngZMZW+Rr1c0Cpo//fMCiV5ksDIBGin5AfOPmvSnPYWV5zcU3QEfl2F5fLXgDCbpaYjaOYjyRt9ZTqabSf1Ar4L9yQFBr4N9cNg4jKskvbha4BDmUL8J7xz/F/OXHFnEDV2YkMcpBfGM2XhKDevceOQcjrPkF5/e5LdwQeYhqgzzm6ur42OwHB2HBU7ulXn/LCk2eYCFa2D1f+2F3ExbwAvnDMhymdQdUniF/NzOfG/1L3yplFsqi270T/2gT1LdOQ/Fgp3FA81k/sMLbICcF/qCp/nS3x+iMZn9B+WLjUQvJy2PehXNcpXEvXWM/e1X4PWDUhwQi7+wjJwERX2W5SB1XjQa7n/osZqpOUG2ShssPNpS3mecaV+MTpRPVYTPFiDTIgkG7F/DSND0c2PDWsBLFus0h4jG70L94uDxVNiMJb/xq/7d2+7FMNPh9UJSK75XcKDhrRYJo3iU7mfl1U89vJB179ulGrdMpWd8v5DHWEDrn3NRBa0KWVYKpqeQ0195XXH1YlZjzK7615K/5ooOGUL42PlX2Hw1zxOJubsIl6LZt8V6wa6zJgywuVLsZb+kpjtHTHmVZyhY8IUnAn6Uj8erYXapvZ8rlhUpjvVuosn8gB9JM6vNct5dVn4e8Wbt6KnRcogHYUJT32QRSWsHCaZNEqwbX+dYaLx1FQZ5daYbXSWwiHhtAJRuYutbmWwWCRTVzyNNMh3sMAI1EcmMoOIX0DEhXYNe7daErR6vMyizQ+h5YKUYK4nUu270M0x/YKRHlxwK8WkEqWv8vfhZqzV0YGud1Hwd5JwWhIEZQ7cc1uPeYJJ5kAaIFqCffmwecS2gzVvOgDkNC5eENXSk7SzDpVgm8IcfZV47L17ni75tyJCS/kreODjap6VdpDNTyS1YJaaO2TMX/s4kWiEZ22Ma4CEv2eQq1uGazGamli+ZwExAtehw=="
+COM_ERMNVLDMR_STATIC_PUBLIC_URL="encrypted:BEZbNy1WbNKhgUWmKO648nvuVNyMNXrMnq64WkjsScTOcE/HFtMX3nQktbIvEYiTSNHvoceUeW10E9i4n+C5ZEHKIBi9VUk3nuqVIcwAr6xTfqKjM1cJlRNKFQzwhHbBTYcImLoxFvM56KU4L/9Ei/XuQ/QRz0KTabhvGMM="
@@ -116,7 +116,7 @@ jobs:
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.STATIC_AWS_ACCESS_KEY_ID || secrets.COM_ERMNVLDMR_STATIC_AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.STATIC_AWS_SECRET_ACCESS_KEY || secrets.COM_ERMNVLDMR_STATIC_AWS_SECRET_ACCESS_KEY }}
-          AWS_DEFAULT_REGION: ${{ secrets.STATIC_AWS_REGION || secrets.COM_ERMNVLDMR_STATIC_S3_REGION || 'ru-central1' }}
+          AWS_DEFAULT_REGION: ${{ secrets.STATIC_AWS_REGION || secrets.COM_ERMNVLDMR_STATIC_S3_REGION || 'auto' }}
          S3_ENDPOINT: ${{ secrets.STATIC_S3_ENDPOINT_URL || secrets.COM_ERMNVLDMR_STATIC_S3_ENDPOINT_URL }}
          S3_BUCKET: ${{ secrets.STATIC_S3_BUCKET || secrets.COM_ERMNVLDMR_STATIC_S3_BUCKET }}
          IMAGE_NAME: ${{ needs.build-image.outputs.image_name }}
@@ -126,7 +126,7 @@ jobs:
            ENDPOINT_FLAG=""
            [ -n "${S3_ENDPOINT}" ] && ENDPOINT_FLAG="--endpoint-url=${S3_ENDPOINT}"
            echo "Cleaning up older images in dev/images/ to free bucket storage..."
-            aws ${ENDPOINT_FLAG} s3 rm "s3://${S3_BUCKET}/dev/images/" --recursive || true
+            aws ${ENDPOINT_FLAG} s3 rm "s3://${S3_BUCKET}/dev/images/" --recursive --exclude "*" --include "com-ermnvldmr-debian-12-k3s-*.qcow2" || true
            aws ${ENDPOINT_FLAG} s3 cp "output-qemu/${IMAGE_NAME}" "s3://${S3_BUCKET}/dev/images/${IMAGE_NAME}"
            echo "Golden image uploaded to s3://${S3_BUCKET}/dev/images/${IMAGE_NAME}"
          else
@@ -5,6 +5,10 @@ on:
    branches: [next]
    paths:
      - 'services/docs/**'
+      - '.github/workflows/services-docs-next-required.yml'
+      - 'ci/docker/docs/**'
+      - 'ci/config/nginx/**'
+      - 'ci/scripts/**'

 concurrency:
  group: ci-docs-${{ github.ref_name }}
@@ -139,23 +143,42 @@ jobs:

          MAX_ATTEMPTS=45
          ATTEMPT=1
+          CF_BLOCKED_COUNT=0

          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
            echo "Attempt $ATTEMPT/$MAX_ATTEMPTS: Polling $ENDPOINT..."

-            RESPONSE=$(curl -sfL --max-time 10 -H "User-Agent: GitHub-Actions-Rollout-Verifier" "$ENDPOINT" 2>/dev/null || true)
-
-            if [ -n "$RESPONSE" ]; then
-              LIVE_COMMIT=$(echo "$RESPONSE" | jq -r '.commit // empty')
+            RESP_FILE=$(mktemp)
+            HTTP_CODE=$(curl -sL --max-time 10 \
+              -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
+              -H "Accept: application/json" \
+              -o "$RESP_FILE" \
+              -w "%{http_code}" \
+              "$ENDPOINT" || echo "000")

+            if [ "$HTTP_CODE" = "200" ]; then
+              LIVE_COMMIT=$(jq -r '.commit // empty' "$RESP_FILE" 2>/dev/null || true)
              echo "  Live commit: ${LIVE_COMMIT:-<none>}"

              if [ "$LIVE_COMMIT" = "$TARGET_COMMIT" ]; then
                echo "✅ Success! Production docs has successfully rolled out $TARGET_COMMIT."
+                rm -f "$RESP_FILE"
                exit 0
              fi
+            elif [ "$HTTP_CODE" = "403" ] || [ "$HTTP_CODE" = "503" ]; then
+              echo "  HTTP $HTTP_CODE: Cloudflare WAF/challenge encountered from runner IP."
+              CF_BLOCKED_COUNT=$((CF_BLOCKED_COUNT + 1))
            else
-              echo "  Endpoint did not return valid JSON or timed out."
+              echo "  HTTP $HTTP_CODE: Endpoint returned unexpected status code or timed out."
+            fi
+
+            rm -f "$RESP_FILE"
+
+            if [ $CF_BLOCKED_COUNT -ge 5 ]; then
+              echo "⚠️ Cloudflare WAF consistently blocked external probe requests from this runner IP (HTTP $HTTP_CODE)."
+              echo "The GitOps release commit was already pushed to the repository; FluxCD will reconcile the cluster."
+              echo "Skipping further external HTTP verification to avoid false negative."
+              exit 0
            fi

            ATTEMPT=$((ATTEMPT + 1))
@@ -9,6 +9,7 @@ on:
      - 'packages/stl/**'
      - 'packages/i18n/**'
      - '.github/workflows/services-static-next-required.yml'
+      - 'ci/scripts/**'
      - 'pnpm-lock.yaml'

 concurrency:
@@ -9,6 +9,7 @@ on:
      - 'packages/stl/**'
      - 'packages/i18n/**'
      - '.github/workflows/services-static-pr-required.yml'
+      - 'ci/scripts/**'
      - 'pnpm-lock.yaml'

 concurrency:
@@ -9,6 +9,9 @@ on:
      - 'packages/stl/**'
      - 'packages/i18n/**'
      - '.github/workflows/services-www-next-required.yml'
+      - 'ci/docker/www/**'
+      - 'ci/config/nginx/**'
+      - 'ci/scripts/**'
      - 'pnpm-lock.yaml'
  workflow_dispatch:

@@ -459,23 +462,42 @@ jobs:

          MAX_ATTEMPTS=45
          ATTEMPT=1
+          CF_BLOCKED_COUNT=0

          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
            echo "Attempt $ATTEMPT/$MAX_ATTEMPTS: Polling $ENDPOINT..."

-            RESPONSE=$(curl -sfL --max-time 10 -H "User-Agent: GitHub-Actions-Rollout-Verifier" "$ENDPOINT" 2>/dev/null || true)
-
-            if [ -n "$RESPONSE" ]; then
-              LIVE_COMMIT=$(echo "$RESPONSE" | jq -r '.commit // empty')
+            RESP_FILE=$(mktemp)
+            HTTP_CODE=$(curl -sL --max-time 10 \
+              -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
+              -H "Accept: application/json" \
+              -o "$RESP_FILE" \
+              -w "%{http_code}" \
+              "$ENDPOINT" || echo "000")

+            if [ "$HTTP_CODE" = "200" ]; then
+              LIVE_COMMIT=$(jq -r '.commit // empty' "$RESP_FILE" 2>/dev/null || true)
              echo "  Live commit:  ${LIVE_COMMIT:-<none>}"

              if [ "$LIVE_COMMIT" = "$TARGET_COMMIT" ]; then
                echo "✅ Success! Production has successfully rolled out $TARGET_COMMIT."
+                rm -f "$RESP_FILE"
                exit 0
              fi
+            elif [ "$HTTP_CODE" = "403" ] || [ "$HTTP_CODE" = "503" ]; then
+              echo "  HTTP $HTTP_CODE: Cloudflare WAF/challenge encountered from runner IP."
+              CF_BLOCKED_COUNT=$((CF_BLOCKED_COUNT + 1))
            else
-              echo "  Endpoint did not return valid JSON or timed out."
+              echo "  HTTP $HTTP_CODE: Endpoint returned unexpected status code or timed out."
+            fi
+
+            rm -f "$RESP_FILE"
+
+            if [ $CF_BLOCKED_COUNT -ge 5 ]; then
+              echo "⚠️ Cloudflare WAF consistently blocked external probe requests from this runner IP (HTTP $HTTP_CODE)."
+              echo "The GitOps release commit was already pushed to the repository; FluxCD will reconcile the cluster."
+              echo "Skipping further external HTTP verification to avoid false negative."
+              exit 0
            fi

            ATTEMPT=$((ATTEMPT + 1))
@@ -5,6 +5,9 @@ server {
    root /usr/share/nginx/html;
    index index.html;

+    # Prevent HTTP protocol downgrade behind reverse proxy on redirects
+    absolute_redirect off;
+
    # Security Headers (Defense in depth)
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
@@ -32,13 +35,15 @@ server {
    # root is inherited from server block, so /en/static/js/file.js resolves correctly
    location ~* \.(js|css|woff|woff2|ttf|eot)$ {
        expires 1y;
-        add_header Cache-Control "public, immutable";
+        add_header Cache-Control "public, immutable" always;
+        add_header Access-Control-Allow-Origin "*" always;
    }

    # Cache images
    location ~* \.(png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
-        add_header Cache-Control "public, no-transform";
+        add_header Cache-Control "public, no-transform" always;
+        add_header Access-Control-Allow-Origin "*" always;
    }

    # English locale — SPA fallback for non-asset routes
@@ -55,6 +60,7 @@ server {
    location = /version.json {
        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
        add_header Content-Type "application/json" always;
+        add_header Access-Control-Allow-Origin "*" always;
        try_files /version.json =404;
    }

@@ -6,4 +6,4 @@ resources:
 - service.yaml
 images:
 - name: ghcr.io/deytenit/ermnvldmr.com/docs
-  newTag: sha-4e4cac0
+  newTag: sha-9200529
@@ -6,4 +6,4 @@ metadata:
 data:
  DATABASE_TYPE: "postgresql"
  CLIENT_IP_HEADER: "X-Forwarded-For"
-  TRACKER_SCRIPT_NAME: "beacon.js"
+  TRACKER_SCRIPT_NAME: "trace.js"
@@ -18,7 +18,7 @@ spec:
      labels:
        app: umami
      annotations:
-        config/tracker-script-name: "beacon.js"
+        config/tracker-script-name: "trace.js"
    spec:
      containers:
        - name: umami
@@ -6,4 +6,4 @@ resources:
 - service.yaml
 images:
 - name: ghcr.io/deytenit/ermnvldmr.com/www
-  newTag: sha-2bf21cd
+  newTag: sha-9200529
@@ -20,7 +20,7 @@ spec:
    - host: www.ermnvldmr.com
      http:
        paths:
-          - path: /beacon
+          - path: /trace
            pathType: Prefix
            backend:
              service:
@@ -30,7 +30,7 @@ spec:
    - host: docs.ermnvldmr.com
      http:
        paths:
-          - path: /beacon
+          - path: /trace
            pathType: Prefix
            backend:
              service:
@@ -6,4 +6,4 @@ metadata:
 spec:
  stripPrefix:
    prefixes:
-      - /beacon
+      - /trace
@@ -29,14 +29,13 @@ fi

 # Configure AWS region
 export AWS_DEFAULT_REGION="$AWS_REGION"
-ENDPOINT_URL="$S3_ENDPOINT_URL"
+ENDPOINT_URL="${S3_ENDPOINT_URL%/}"

 # Upload all static files
 echo "Uploading static files..."
 aws s3 cp "$DIST_DIR/" "s3://$S3_BUCKET/" \
  --recursive \
  --endpoint-url="$ENDPOINT_URL" \
-  --cache-control "max-age=300" \
-  --metadata-directive REPLACE
+  --cache-control "max-age=300"

 echo "Static files deployed successfully!"
@@ -11,6 +11,7 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';

 /**
 * Checks whether a hostname entry exists in the specified hosts file.
@@ -113,6 +114,56 @@ export function findWorkspaceRoot(startDir = dirname(fileURLToPath(import.meta.u
  return process.cwd();
 }

+/**
+ * Resolves the development Root CA private key from the environment or .env.dev.
+ *
+ * @param {string} workspaceRoot - Absolute path to workspace root
+ * @returns {string | undefined} The PEM private key string, or undefined if unavailable
+ */
+export function loadDevRootCaKey(workspaceRoot = findWorkspaceRoot()) {
+  if (process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY) {
+    const raw = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+    return raw.includes('\\n') ? raw.replace(/\\n/g, '\n') : raw;
+  }
+
+  const envDevPath = join(workspaceRoot, '.env.dev');
+  const envKeysPath = join(workspaceRoot, '.env.keys');
+
+  if (!existsSync(envDevPath)) {
+    return undefined;
+  }
+
+  const candidatePackages = [
+    join(workspaceRoot, 'packages/cli/package.json'),
+    join(workspaceRoot, 'package.json'),
+  ];
+
+  for (const pkgPath of candidatePackages) {
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const req = createRequire(pkgPath);
+      const dotenvx = req('@dotenvx/dotenvx');
+      if (dotenvx && typeof dotenvx.config === 'function') {
+        dotenvx.config({ path: envDevPath, envKeysFile: envKeysPath });
+        const key = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+        if (key) {
+          return key.includes('\\n') ? key.replace(/\\n/g, '\n') : key;
+        }
+      }
+    } catch {
+      // Continue to next candidate package
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Remote public URL for the Ermnvldmr development root CA certificate.
+ */
+export const REMOTE_ROOT_CA_URL =
+  'https://static.ermnvldmr.com/dev/ssl/certs/ErmnvldmrDevelopmentRootCA.pem';
+
 /**
 * Ensures valid development certificates exist for localhost.ermnvldmr.com.
 *
@@ -123,128 +174,101 @@ export function ensureDevCertificates(workspaceRoot = findWorkspaceRoot()) {
  const certsDir = join(workspaceRoot, '.certs');
  const certPath = join(certsDir, 'localhost.ermnvldmr.com.pem');
  const keyPath = join(certsDir, 'localhost.ermnvldmr.com-key.pem');
+  const caCertPath = join(certsDir, 'ErmnvldmrDevelopmentRootCA.pem');
+  const caKeyPath = join(certsDir, 'ErmnvldmrDevelopmentRootCA-key.pem');

  ensureHostsEntry('localhost.ermnvldmr.com', '127.0.0.1');

-  if (existsSync(certPath) && existsSync(keyPath)) {
-    return { certPath, keyPath };
-  }
+  const home = homedir();
+  const globalCaDir = join(home, '.local/share/mkcert');
+  const globalCaCert = join(globalCaDir, 'ErmnvldmrDevelopmentRootCA.pem');
+  const globalCaKey = join(globalCaDir, 'ErmnvldmrDevelopmentRootCA-key.pem');

  mkdirSync(certsDir, { recursive: true, mode: 0o700 });

-  const home = homedir();
-  const hugoCaCert = join(home, '.local/share/mkcert/rootCA.pem');
-  const hugoCaKey = join(home, '.local/share/mkcert/rootCA-key.pem');
-
-  let hasMkcertCli = false;
-  try {
-    execFileSync('mkcert', ['-help'], { stdio: 'ignore' });
-    hasMkcertCli = true;
-  } catch {
-    hasMkcertCli = false;
-  }
-
-  if (hasMkcertCli) {
-    execFileSync(
-      'mkcert',
-      [
-        '-cert-file',
-        certPath,
-        '-key-file',
-        keyPath,
-        'localhost.ermnvldmr.com',
-        '*.localhost.ermnvldmr.com',
-        'localhost',
-        '127.0.0.1',
-        '::1',
-      ],
-      { stdio: 'inherit' }
-    );
-    chmodSync(keyPath, 0o600);
-    return { certPath, keyPath };
-  }
-
-  if (existsSync(hugoCaCert) && existsSync(hugoCaKey)) {
-    const tempDir = tmpdir();
-    const tempCsr = join(tempDir, `ermnvldmr-dev-${Date.now()}.csr`);
-    const tempExt = join(tempDir, `ermnvldmr-dev-${Date.now()}.cnf`);
-
-    try {
-      writeFileSync(
-        tempExt,
-        'subjectAltName=DNS:localhost.ermnvldmr.com,DNS:*.localhost.ermnvldmr.com,DNS:localhost,IP:127.0.0.1,IP:::1\n'
-      );
-      execFileSync(
-        'openssl',
-        [
-          'req',
-          '-new',
-          '-nodes',
-          '-newkey',
-          'rsa:2048',
-          '-keyout',
-          keyPath,
-          '-out',
-          tempCsr,
-          '-subj',
-          '/CN=localhost.ermnvldmr.com',
-          '-batch',
-        ],
-        { stdio: 'pipe' }
-      );
-      execFileSync(
-        'openssl',
-        [
-          'x509',
-          '-req',
-          '-in',
-          tempCsr,
-          '-CA',
-          hugoCaCert,
-          '-CAkey',
-          hugoCaKey,
-          '-CAcreateserial',
-          '-out',
-          certPath,
-          '-days',
-          '825',
-          '-extfile',
-          tempExt,
-        ],
-        { stdio: 'pipe' }
-      );
-      chmodSync(keyPath, 0o600);
-      chmodSync(certPath, 0o644);
-    } finally {
-      rmSync(tempCsr, { force: true });
-      rmSync(tempExt, { force: true });
+  // 1. Sync CA cert from global cache if available, or download from remote static URL
+  if (!existsSync(caCertPath)) {
+    if (existsSync(globalCaCert)) {
+      writeFileSync(caCertPath, readFileSync(globalCaCert));
+      chmodSync(caCertPath, 0o644);
+    } else {
+      try {
+        execFileSync('curl', ['-sSfL', REMOTE_ROOT_CA_URL, '-o', caCertPath], {
+          stdio: 'ignore',
+        });
+        chmodSync(caCertPath, 0o644);
+        try {
+          mkdirSync(globalCaDir, { recursive: true });
+          writeFileSync(globalCaCert, readFileSync(caCertPath));
+          chmodSync(globalCaCert, 0o644);
+        } catch {
+          // Best-effort global cache
+        }
+      } catch {
+        // Failed to download, will fall back to generation if key also needed
+      }
    }
-    return { certPath, keyPath };
  }

-  const caDir = join(home, '.local/share/mkcert');
-  mkdirSync(caDir, { recursive: true });
-  execFileSync(
-    'openssl',
-    [
-      'req',
-      '-x509',
-      '-nodes',
-      '-newkey',
-      'rsa:3072',
-      '-keyout',
-      hugoCaKey,
-      '-out',
-      hugoCaCert,
-      '-days',
-      '3650',
-      '-subj',
-      '/CN=mkcert development CA/O=mkcert development CA',
-      '-batch',
-    ],
-    { stdio: 'pipe' }
-  );
+  // 2. Sync CA key from global cache if available, or decrypt from .env.dev
+  if (!existsSync(caKeyPath)) {
+    if (existsSync(globalCaKey)) {
+      writeFileSync(caKeyPath, readFileSync(globalCaKey));
+      chmodSync(caKeyPath, 0o600);
+    } else {
+      const decryptedKey = loadDevRootCaKey(workspaceRoot);
+      if (decryptedKey) {
+        writeFileSync(caKeyPath, decryptedKey);
+        chmodSync(caKeyPath, 0o600);
+        try {
+          mkdirSync(globalCaDir, { recursive: true });
+          writeFileSync(globalCaKey, decryptedKey);
+          chmodSync(globalCaKey, 0o600);
+        } catch {
+          // Best-effort global cache
+        }
+      }
+    }
+  }

+  // If server cert and CA cert already exist, return them
+  if (existsSync(certPath) && existsSync(keyPath) && existsSync(caCertPath)) {
+    return { certPath, keyPath, caCertPath };
+  }
+
+  // Ensure ErmnvldmrDevelopmentRootCA exists
+  if (!existsSync(caCertPath) || !existsSync(caKeyPath)) {
+    mkdirSync(globalCaDir, { recursive: true });
+    execFileSync(
+      'openssl',
+      [
+        'req',
+        '-x509',
+        '-nodes',
+        '-newkey',
+        'rsa:3072',
+        '-keyout',
+        caKeyPath,
+        '-out',
+        caCertPath,
+        '-days',
+        '3650',
+        '-subj',
+        '/CN=Ermnvldmr Development Root CA/O=ermnvldmr.com',
+        '-batch',
+      ],
+      { stdio: 'pipe' }
+    );
+    chmodSync(caKeyPath, 0o600);
+    chmodSync(caCertPath, 0o644);
+
+    writeFileSync(globalCaCert, readFileSync(caCertPath));
+    writeFileSync(globalCaKey, readFileSync(caKeyPath));
+    chmodSync(globalCaKey, 0o600);
+    chmodSync(globalCaCert, 0o644);
+  }
+
+  // Generate server certificate signed by ErmnvldmrDevelopmentRootCA
  const tempDir = tmpdir();
  const tempCsr = join(tempDir, `ermnvldmr-dev-${Date.now()}.csr`);
  const tempExt = join(tempDir, `ermnvldmr-dev-${Date.now()}.cnf`);
@@ -280,9 +304,9 @@ export function ensureDevCertificates(workspaceRoot = findWorkspaceRoot()) {
        '-in',
        tempCsr,
        '-CA',
-        hugoCaCert,
+        caCertPath,
        '-CAkey',
-        hugoCaKey,
+        caKeyPath,
        '-CAcreateserial',
        '-out',
        certPath,
@@ -300,7 +324,7 @@ export function ensureDevCertificates(workspaceRoot = findWorkspaceRoot()) {
    rmSync(tempExt, { force: true });
  }

-  return { certPath, keyPath };
+  return { certPath, keyPath, caCertPath };
 }

 // Run if called directly
@@ -14,7 +14,10 @@ export default [
  // Additional ignores for monorepo
  {
    ignores: [
-      'services/docs/**/*', // Hugo content, no linting needed
+      'services/docs/public/**',
+      'services/docs/resources/**',
+      'services/docs/assets/**',
+      'services/docs/archetypes/**',
      '**/node_modules/**',
      '**/dist/**',
      '**/build/**',
@@ -40,6 +40,6 @@
    "@types/node": "^22.13.0",
    "sharp": "^0.35.2",
    "typescript": "^5.8.2",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
  }
 }
@@ -376,4 +376,33 @@ describe('runS3Sync', () => {
    const content = fs.readFileSync(srcPath, 'utf-8');
    expect(content).toContain('https://cdn.example.com/www/img.webp');
  });
+
+  it('should fallback to COM_ERMNVLDMR_STATIC_PUBLIC_URL when publicUrl is not explicitly configured', async () => {
+    process.env.COM_ERMNVLDMR_STATIC_PUBLIC_URL = 'https://static.ermnvldmr.com';
+
+    const staticDir = path.join(tempDir, 'static');
+    fs.mkdirSync(staticDir, { recursive: true });
+    fs.writeFileSync(path.join(staticDir, 'asset.png'), 'png-content');
+
+    const srcDir = path.join(tempDir, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    const srcPath = path.join(srcDir, 'index.ts');
+    fs.writeFileSync(srcPath, 'const img = "/static/asset.png";');
+
+    const cmd: S3SyncCommandConfig = {
+      name: 'sync',
+      description: 'desc',
+      bucket: 'com-ermnvldmr-static',
+      targetPrefix: 'www',
+      sourceDir: './static',
+      type: 's3-sync',
+    };
+
+    await runS3Sync(cmd, {});
+
+    const content = fs.readFileSync(srcPath, 'utf-8');
+    expect(content).toContain('https://static.ermnvldmr.com/www/asset.png');
+
+    delete process.env.COM_ERMNVLDMR_STATIC_PUBLIC_URL;
+  });
 });
@@ -53,6 +53,7 @@ export async function runS3Sync(
  const bucket = cmd.bucket ?? process.env.S3_BUCKET;
  const region = cmd.region ?? process.env.AWS_REGION ?? process.env.S3_REGION;
  const endpoint = cmd.endpoint ?? process.env.S3_ENDPOINT_URL ?? process.env.S3_ENDPOINT;
+  const publicUrl = cmd.publicUrl ?? process.env.COM_ERMNVLDMR_STATIC_PUBLIC_URL ?? process.env.S3_PUBLIC_URL;
  const accessKey = cmd.accessKeyId ?? process.env.AWS_ACCESS_KEY_ID ?? process.env.S3_ACCESS_KEY_ID;
  const secretKey = cmd.secretAccessKey ?? process.env.AWS_SECRET_ACCESS_KEY ?? process.env.S3_SECRET_ACCESS_KEY;

@@ -149,8 +150,8 @@ export async function runS3Sync(
   */
  const getS3Url = (finalName: string): string => {
    const normalizedKey = normalizeKey(cmd.targetPrefix, finalName);
-    if (cmd.publicUrl) {
-      const cleanPublicUrl = cmd.publicUrl.replace(/\/+$/, '');
+    if (publicUrl) {
+      const cleanPublicUrl = publicUrl.replace(/\/+$/, '');
      return `${cleanPublicUrl}/${normalizedKey}`;
    }
    if (bucket.includes('.')) {
@@ -10,6 +10,9 @@
  "files": [
    "src"
  ],
+  "scripts": {
+    "test": "node --test src/lib/rules/no-hanging-particles.test.js"
+  },
  "dependencies": {
    "@eslint/js": "^9.39.2",
    "eslint-config-prettier": "^10.1.2",
@@ -0,0 +1,31 @@
+// @ts-check
+import { i18nPlugin } from '../plugins/i18n.js';
+import { markdownParser } from '../parsers/markdown.js';
+
+/**
+ * i18n typography and validation ESLint configuration.
+ */
+export const i18nConfig = [
+  {
+    files: ['**/*.i18n.{ts,tsx,js,jsx,mjs}'],
+    plugins: {
+      i18n: i18nPlugin,
+    },
+    rules: {
+      'i18n/no-hanging-particles': 'error',
+    },
+  },
+  {
+    files: ['**/*.{md,mdx}'],
+    languageOptions: {
+      parser: markdownParser,
+    },
+    plugins: {
+      i18n: i18nPlugin,
+    },
+    rules: {
+      'no-irregular-whitespace': 'off',
+      'i18n/no-hanging-particles': 'error',
+    },
+  },
+];
@@ -6,6 +6,7 @@ import { jsdocConfig } from './jsdoc.js';
 import { testingConfig } from './testing.js';
 import { toolingConfig } from './tooling.js';
 import { defineMonorepoRestrictedImports } from './monorepo.js';
+import { i18nConfig } from './i18n.js';

 /**
 * Common ignores for the entire monorepo.
@@ -38,6 +39,9 @@ export function defineBaseConfig(rootDir) {
    ...jsdocConfig,
    ...testingConfig,
    ...toolingConfig,
+    ...i18nConfig,
    ...defineMonorepoRestrictedImports(rootDir),
  ];
 }
+
+export { i18nConfig };
@@ -1,6 +1,7 @@
 // @ts-check
 import path from 'node:path';
-import { defineBaseConfig } from './config/index.js';
+import { defineBaseConfig, i18nConfig } from './config/index.js';
+import { i18nPlugin } from './plugins/i18n.js';

 // Resolve the monorepo root relative to this library's location
 const rootDir = path.resolve(import.meta.dirname, '../../../../');
@@ -10,4 +11,4 @@ const rootDir = path.resolve(import.meta.dirname, '../../../../');
 */
 export const baseConfig = defineBaseConfig(rootDir);

-export { defineBaseConfig };
+export { defineBaseConfig, i18nConfig, i18nPlugin };
@@ -0,0 +1,61 @@
+// @ts-check
+
+/**
+ * Calculates start and end line/column locations for a string offset.
+ *
+ * @param {string} code - Entire source code.
+ * @returns {import('eslint').AST.SourceLocation} Full document SourceLocation.
+ */
+function getDocumentLocation(code) {
+  const lines = code.split('\n');
+  const lastLine = lines.length;
+  const lastColumn = lines[lines.length - 1].length;
+
+  return {
+    start: { line: 1, column: 0 },
+    end: { line: lastLine, column: lastColumn },
+  };
+}
+
+/**
+ * Custom lightweight parser for Markdown and MDX documents.
+ * Produces an AST that enables typography linting and autofixing on prose text.
+ */
+export const markdownParser = {
+  meta: {
+    name: 'eslint-parser-markdown-typography',
+    version: '1.0.0',
+  },
+  parseForESLint(code, options = {}) {
+    const filePath = options.filePath || '';
+    const isRu = /(?:^|[\\/])ru(?:[\\/]|\.ru\.)/i.test(filePath);
+    const isEn = /(?:^|[\\/])en(?:[\\/]|\.en\.)/i.test(filePath);
+    const locale = isRu ? 'ru' : isEn ? 'en' : undefined;
+
+    const loc = getDocumentLocation(code);
+
+    return {
+      ast: {
+        type: 'Program',
+        range: [0, code.length],
+        loc,
+        body: [
+          {
+            type: 'MarkdownDocument',
+            range: [0, code.length],
+            loc,
+            value: code,
+            locale,
+            filePath,
+          },
+        ],
+        tokens: [],
+        comments: [],
+      },
+      visitorKeys: {
+        Program: ['body'],
+        MarkdownDocument: [],
+      },
+    };
+  },
+};
@@ -0,0 +1,15 @@
+// @ts-check
+import { noHangingParticlesRule } from '../rules/no-hanging-particles.js';
+
+/**
+ * ESLint plugin providing i18n translation validation and typography rules.
+ */
+export const i18nPlugin = {
+  meta: {
+    name: 'eslint-plugin-i18n',
+    version: '1.0.0',
+  },
+  rules: {
+    'no-hanging-particles': noHangingParticlesRule,
+  },
+};
@@ -0,0 +1,310 @@
+// @ts-check
+
+const RU_PARTICLES = [
+  '[а-яё]',
+  'во', 'со', 'ко', 'до', 'по', 'на', 'из', 'за', 'от', 'об', 'не', 'ни', 'но', 'да', 'то', 'уж',
+  'обо', 'под', 'над', 'при', 'про', 'для', 'без', 'или', 'как', 'что', 'еще', 'ещё', 'уже',
+  'через', 'сквозь', 'перед', 'из-за', 'из-под',
+].join('|');
+
+const EN_PARTICLES = [
+  'a', 'an', 'the',
+  'in', 'on', 'at', 'to', 'of', 'by', 'for', 'up', 'as', 'if', 'is', 'it', 'no',
+  'and', 'or', 'nor', 'but', 'yet', 'so', 'with', 'into', 'from',
+].join('|');
+
+const RU_TRAILING = ['ли', 'ль', 'же', 'ж', 'бы', 'б'].join('|');
+
+const KNOWN_LOCALES = new Set(['en', 'ru']);
+const PLURAL_KEYS = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+
+/**
+ * Applies non-breaking space typography rules to a translation string value.
+ *
+ * @param {string} input - The raw translation string.
+ * @param {string} [locale] - The locale code ('en' | 'ru').
+ * @returns {string} The transformed string with non-breaking spaces.
+ */
+export function applyTypography(input, locale) {
+  let text = input.replaceAll('&nbsp;', '\u00A0');
+
+  /** @type {string[]} */
+  const protectedTokens = [];
+  text = text.replace(/\{[^}]+\}|<[^>]+>|\]\([^)]+\)/g, (match) => {
+    const idx = protectedTokens.length;
+    protectedTokens.push(match);
+    return `__TYPO_PROT_${idx}__`;
+  });
+
+  // Em-dash and en-dash (prepend non-breaking space)
+  text = text.replace(/(?<=\S)[\t \u00A0]+([—–])[\t ]+/g, '\u00A0$1 ');
+
+  // Numbers & units/symbols
+  text = text.replace(/(?<=\d)[\t ]+(?=[a-zA-Zа-яА-ЯёЁ%№$€₽]|__TYPO_PROT_)/g, '\u00A0');
+  text = text.replace(/(?<=[№§$€₽])[\t ]+(?=\d|__TYPO_PROT_)/g, '\u00A0');
+
+  // Trailing particles (Russian)
+  if (!locale || locale === 'ru') {
+    const trailingRegex = new RegExp(`(?<=[а-яА-ЯёЁ\\w])\\s+(${RU_TRAILING})(?=[\\s\\u00A0.,!?:;»"')\\]]|$)`, 'gi');
+    text = text.replace(trailingRegex, '\u00A0$1');
+  }
+
+  // Leading particles (RU / EN)
+  const particles = locale === 'en' ? EN_PARTICLES : locale === 'ru' ? RU_PARTICLES : `${RU_PARTICLES}|${EN_PARTICLES}`;
+  const leadingRegex = new RegExp(`(?<=^|[\\s\\u00A0.,!?:;«"'(])(${particles})[ \\t]+(?=\\S)`, 'gi');
+  text = text.replace(leadingRegex, '$1\u00A0');
+
+  // Restore protected tokens
+  text = text.replace(/__TYPO_PROT_(\d+)__/g, (_, idx) => protectedTokens[Number(idx)]);
+
+  return text;
+}
+
+/**
+ * Masks frontmatter non-title/description lines.
+ *
+ * @param {string} text - Raw document text.
+ * @param {(str: string) => string} mask - Masking function.
+ * @returns {string} Text with frontmatter metadata masked.
+ */
+function maskFrontmatter(text, mask) {
+  if (!text.startsWith('---')) return text;
+  const endIdx = text.indexOf('\n---', 3);
+  if (endIdx === -1) return text;
+  const fm = text.slice(0, endIdx + 4);
+  const rest = text.slice(endIdx + 4);
+
+  const lines = fm.split('\n');
+  const processedLines = lines.map((line, idx) => {
+    if (idx === 0 || idx === lines.length - 1) return mask(line);
+    const trimmed = line.trim();
+    if (trimmed.startsWith('title:') || trimmed.startsWith('description:')) {
+      return line;
+    }
+    return mask(line);
+  });
+  return processedLines.join('\n') + rest;
+}
+
+/**
+ * Applies typography rules to a Markdown/MDX document, protecting code blocks,
+ * inline code, shortcodes, link URLs, HTML tags, and frontmatter metadata.
+ *
+ * @param {string} content - Markdown document content.
+ * @param {string} [locale] - The document locale ('en' | 'ru').
+ * @returns {string} Transformed markdown content.
+ */
+export function applyMarkdownTypography(content, locale) {
+  /** @type {string[]} */
+  const protectedTokens = [];
+  /**
+   * @param {string} str
+   * @returns {string}
+   */
+  function mask(str) {
+    const idx = protectedTokens.length;
+    protectedTokens.push(str);
+    return `__MD_PROT_${idx}__`;
+  }
+
+  let text = maskFrontmatter(content, mask);
+
+  // Mask fenced code blocks ```...``` and ~~~...~~~
+  text = text.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~/g, mask);
+  // Mask Hugo shortcodes {{< ... >}} or {{% ... %}}
+  text = text.replace(/\{\{[<%][\s\S]*?[>%]\}\}/g, mask);
+  // Mask inline code `...`
+  text = text.replace(/`[^`\n]+`/g, mask);
+  // Mask Markdown link targets ](...)
+  text = text.replace(/\]\([^)]+\)/g, mask);
+  // Mask HTML tags
+  text = text.replace(/<[^>]+>/g, mask);
+
+  // Apply typography rules
+  text = applyTypography(text, locale);
+
+  // Restore protected tokens
+  text = text.replace(/__MD_PROT_(\d+)__/g, (_, idx) => protectedTokens[Number(idx)]);
+
+  return text;
+}
+
+/**
+ * Serializes a string into a valid JS string literal with specified quote.
+ *
+ * @param {string} str - String to escape and wrap.
+ * @param {string} quote - Quote character (' or ").
+ * @returns {string} Serialized literal.
+ */
+function serializeStringLiteral(str, quote) {
+  const escaped = str
+    .replace(/\\/g, '\\\\')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\t/g, '\\t')
+    .replace(new RegExp(quote, 'g'), `\\${quote}`);
+  return `${quote}${escaped}${quote}`;
+}
+
+/**
+ * Extracts property name from a property node.
+ *
+ * @param {any} prop - Property AST node.
+ * @returns {string | null} Property name or null.
+ */
+function getPropertyName(prop) {
+  if (!prop || !prop.key) return null;
+  if (prop.key.type === 'Identifier') return prop.key.name;
+  if (prop.key.type === 'Literal') return String(prop.key.value);
+  return null;
+}
+
+/**
+ * ESLint rule module for enforcing non-breaking spaces in i18n translation values
+ * and Markdown/MDX documentation.
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+export const noHangingParticlesRule = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Enforce non-breaking spaces for hanging particles and numbers in i18n translation values and markdown documentation.',
+      recommended: true,
+    },
+    fixable: 'whitespace',
+    schema: [],
+    messages: {
+      hangingParticle: 'Translation value contains hanging particles or numbers that should be bound with a non-breaking space (\\u00A0).',
+    },
+  },
+  create(context) {
+    /**
+     * Checks and fixes a single string literal node.
+     *
+     * @param {any} node - String Literal AST node.
+     * @param {string} [locale] - The locale code if known.
+     */
+    function checkStringLiteral(node, locale) {
+      if (!node || typeof node.value !== 'string') return;
+      const original = node.value;
+      const formatted = applyTypography(original, locale);
+
+      if (original !== formatted) {
+        context.report({
+          node,
+          messageId: 'hangingParticle',
+          fix(fixer) {
+            const raw = node.raw || '';
+            const quote = raw.startsWith('"') ? '"' : "'";
+            return fixer.replaceText(node, serializeStringLiteral(formatted, quote));
+          },
+        });
+      }
+    }
+
+    /**
+     * Inspects a locale entry inside a translation item.
+     *
+     * @param {any} prop - Locale property node (e.g. en or ru).
+     */
+    function processLocaleEntry(prop) {
+      const locale = getPropertyName(prop);
+      if (!locale || !KNOWN_LOCALES.has(locale)) return;
+
+      const valueNode = prop.value;
+      if (!valueNode) return;
+
+      if (valueNode.type === 'Literal') {
+        checkStringLiteral(valueNode, locale);
+      } else if (valueNode.type === 'ObjectExpression' && Array.isArray(valueNode.properties)) {
+        for (const pluralProp of valueNode.properties) {
+          if (pluralProp.type === 'Property') {
+            const pluralKey = getPropertyName(pluralProp);
+            if (pluralKey && PLURAL_KEYS.has(pluralKey) && pluralProp.value?.type === 'Literal') {
+              checkStringLiteral(pluralProp.value, locale);
+            }
+          }
+        }
+      }
+    }
+
+    /**
+     * Processes keyset object dictionary properties.
+     *
+     * @param {any} objectNode - Keyset ObjectExpression AST node.
+     */
+    function processKeysetObject(objectNode) {
+      if (!objectNode || !Array.isArray(objectNode.properties)) return;
+
+      for (const dictEntry of objectNode.properties) {
+        if (
+          dictEntry.type === 'Property' &&
+          dictEntry.value &&
+          dictEntry.value.type === 'ObjectExpression' &&
+          Array.isArray(dictEntry.value.properties)
+        ) {
+          for (const localeProp of dictEntry.value.properties) {
+            if (localeProp.type === 'Property') {
+              processLocaleEntry(localeProp);
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee &&
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'createKeyset' &&
+          node.arguments.length > 0 &&
+          node.arguments[0].type === 'ObjectExpression'
+        ) {
+          processKeysetObject(node.arguments[0]);
+        }
+      },
+
+      MarkdownDocument(node) {
+        if (!node || typeof node.value !== 'string') return;
+        const original = node.value;
+        const formatted = applyMarkdownTypography(original, node.locale);
+
+        if (original === formatted) return;
+
+        const origLines = original.split('\n');
+        const formLines = formatted.split('\n');
+
+        let reported = false;
+        for (let i = 0; i < origLines.length; i++) {
+          const origLine = origLines[i];
+          const formLine = formLines[i];
+          if (origLine !== formLine) {
+            let diffCol = 0;
+            while (
+              diffCol < origLine.length &&
+              diffCol < formLine.length &&
+              origLine[diffCol] === formLine[diffCol]
+            ) {
+              diffCol++;
+            }
+
+            const isFirst = !reported;
+            reported = true;
+
+            context.report({
+              node,
+              loc: {
+                start: { line: i + 1, column: diffCol },
+                end: { line: i + 1, column: diffCol + 1 },
+              },
+              messageId: 'hangingParticle',
+              fix: isFirst ? (fixer) => fixer.replaceText(node, formatted) : undefined,
+            });
+          }
+        }
+      },
+    };
+  },
+};
@@ -0,0 +1,251 @@
+// @ts-check
+import { describe, it } from 'node:test';
+import { RuleTester } from 'eslint';
+import { noHangingParticlesRule } from './no-hanging-particles.js';
+import { markdownParser } from '../parsers/markdown.js';
+
+// Configure RuleTester for node:test
+RuleTester.describe = describe;
+RuleTester.it = it;
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-hanging-particles', noHangingParticlesRule, {
+  valid: [
+    {
+      code: `
+        createKeyset({
+          'Yet capturing context': {
+            en: 'Yet\\u00A0capturing context and\\u00A0architectural decisions',
+            ru: 'Мои мысли и\\u00A0проекты',
+          },
+        });
+      `,
+    },
+    {
+      // Keys should not trigger errors even if they contain particles
+      code: `
+        createKeyset({
+          'и иные проблемы': {
+            en: 'and\\u00A0other issues',
+            ru: 'и\\u00A0иные проблемы',
+          },
+        });
+      `,
+    },
+    {
+      // Manual {nbsp} token is allowed
+      code: `
+        createKeyset({
+          manual: {
+            en: 'Yet{nbsp}capturing',
+            ru: 'и{nbsp}иные',
+          },
+        });
+      `,
+    },
+    {
+      // Not a createKeyset call
+      code: `
+        const regularObj = {
+          en: 'Yet capturing without keyset',
+        };
+      `,
+    },
+  ],
+  invalid: [
+    {
+      // English leading particle
+      code: `
+        createKeyset({
+          key: {
+            en: 'Yet capturing context',
+            ru: 'Фиксация контекста',
+          },
+        });
+      `,
+      output: `
+        createKeyset({
+          key: {
+            en: 'Yet\u00A0capturing context',
+            ru: 'Фиксация контекста',
+          },
+        });
+      `,
+      errors: [
+        {
+          messageId: 'hangingParticle',
+        },
+      ],
+    },
+    {
+      // Russian leading particle
+      code: `
+        createKeyset({
+          'и иные проблемы': {
+            en: 'and other issues',
+            ru: 'и иные проблемы',
+          },
+        });
+      `,
+      output: `
+        createKeyset({
+          'и иные проблемы': {
+            en: 'and\u00A0other issues',
+            ru: 'и\u00A0иные проблемы',
+          },
+        });
+      `,
+      errors: [
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+      ],
+    },
+    {
+      // Interpolation placeholder & trailing particles & dashes & numbers
+      code: `
+        createKeyset({
+          welcome: {
+            en: 'Inspect the {repositoryLink} for 10 items — all good',
+            ru: 'Загляните в {repositoryLink}, как же так — это 10 вещей в 2026 году',
+          },
+        });
+      `,
+      output: `
+        createKeyset({
+          welcome: {
+            en: 'Inspect the\u00A0{repositoryLink} for\u00A010\u00A0items\u00A0— all good',
+            ru: 'Загляните в\u00A0{repositoryLink}, как\u00A0же так\u00A0— это 10\u00A0вещей в\u00A02026\u00A0году',
+          },
+        });
+      `,
+      errors: [
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+      ],
+    },
+    {
+      // HTML entity replacement
+      code: `
+        createKeyset({
+          test: {
+            en: 'Text&nbsp;with entity',
+            ru: 'Текст&nbsp;с сущностью',
+          },
+        });
+      `,
+      output: `
+        createKeyset({
+          test: {
+            en: 'Text\u00A0with\u00A0entity',
+            ru: 'Текст\u00A0с\u00A0сущностью',
+          },
+        });
+      `,
+      errors: [
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+      ],
+    },
+    {
+      // Plural forms
+      code: `
+        createKeyset({
+          counter: {
+            en: {
+              one: '{count} item',
+              other: '{count} items in stock',
+            },
+            ru: {
+              one: '{count} штука в наличии',
+              few: '{count} штуки в наличии',
+              many: '{count} штук в наличии',
+              other: '{count} штук в наличии',
+            },
+          },
+        });
+      `,
+      output: `
+        createKeyset({
+          counter: {
+            en: {
+              one: '{count} item',
+              other: '{count} items in\u00A0stock',
+            },
+            ru: {
+              one: '{count} штука в\u00A0наличии',
+              few: '{count} штуки в\u00A0наличии',
+              many: '{count} штук в\u00A0наличии',
+              other: '{count} штук в\u00A0наличии',
+            },
+          },
+        });
+      `,
+      errors: [
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+      ],
+    },
+  ],
+});
+
+const markdownRuleTester = new RuleTester({
+  languageOptions: {
+    parser: markdownParser,
+  },
+});
+
+markdownRuleTester.run('no-hanging-particles (markdown)', noHangingParticlesRule, {
+  valid: [
+    {
+      code: '# Title\n\nYet\\u00A0capturing context\\u00A0— for\\u00A010\\u00A0items',
+      filename: 'content/en/overview.md',
+    },
+    {
+      // Code blocks should be protected
+      code: '```ts\nconst in = 10;\n```',
+      filename: 'content/en/guide.md',
+    },
+    {
+      // Inline code and link targets should be protected
+      code: 'Use `in` keyword here [link](https://example.com/in/path).',
+      filename: 'content/en/guide.md',
+    },
+    {
+      // Hugo shortcodes should be protected
+      code: '{{< card link="apex" title="apex" >}}',
+      filename: 'content/en/guide.md',
+    },
+    {
+      // Frontmatter tags/date should be protected
+      code: '---\ntitle: "Title"\ntags: [a, in, on]\n---\nBody text',
+      filename: 'content/en/guide.md',
+    },
+  ],
+  invalid: [
+    {
+      code: '# Title\n\nYet capturing context — for 10 items',
+      output: '# Title\n\nYet\u00A0capturing context\u00A0— for\u00A010\u00A0items',
+      filename: 'content/en/overview.md',
+      errors: [{ messageId: 'hangingParticle' }],
+    },
+    {
+      code: 'Это руководство для заметок с нуля',
+      output: 'Это руководство для\u00A0заметок с\u00A0нуля',
+      filename: 'content/ru/overview.md',
+      errors: [{ messageId: 'hangingParticle' }],
+    },
+    {
+      code: '---\ntitle: "Руководство по развертыванию"\ntags: [a, in]\n---\nС нуля',
+      output: '---\ntitle: "Руководство по\u00A0развертыванию"\ntags: [a, in]\n---\nС\u00A0нуля',
+      filename: 'content/ru/guide.md',
+      errors: [
+        { messageId: 'hangingParticle' },
+        { messageId: 'hangingParticle' },
+      ],
+    },
+  ],
+});
@@ -45,6 +45,6 @@
    "@vitest/coverage-v8": "^4.0.18",
    "react": "^19.1.0",
    "typescript": "^5.8.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
  }
 }
@@ -68,7 +68,7 @@
    "storybook": "^8.6.17",
    "storybook-react-rsbuild": "^1.0.3",
    "typescript": "^5.8.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.11",
    "wait-on": "^8.0.3"
  },
  "peerDependencies": {
@@ -76,7 +76,7 @@ export function PageHead({

  useEffect(() => {
    if (isCollapsible) {
-      setIsCollapsed(scrollY > 200);
+      setIsCollapsed(scrollY > 150);
    }
  }, [scrollY, isCollapsible]);

@@ -91,13 +91,13 @@ export function PageHead({
          <HStack align="center" className="min-h-[60px] py-2.5" gap={4} justify="between" wrap="wrap">
            <HStack align="center" className="flex-1" gap={4}>
              {addonLeft && <div className="flex-shrink-0 whitespace-nowrap">{addonLeft}</div>}
-              {breadcrumbs && <div className="hidden sm:block">{breadcrumbs}</div>}
+              {breadcrumbs && <div className="hidden sm:block text-label-l [&_ol]:text-label-l">{breadcrumbs}</div>}
            </HStack>
            {addonRight && <div className="flex-shrink-0">{addonRight}</div>}
          </HStack>
        </PageContainer>
      )}
-      <PageContainer className={cn(hasTopBar ? 'pt-4 pb-8 sm:pt-6 sm:pb-12' : 'py-8 sm:py-12')}>
+      <PageContainer className={cn(hasTopBar ? 'pt-2.5 pb-8 sm:pt-3.5 sm:pb-12' : 'pt-5 pb-8 sm:pt-9 sm:pb-12')}>
        <VStack gap={4}>
          <Header level={1}>{heading}</Header>
          {typeof caption === 'string' ? (
@@ -117,7 +117,7 @@ export function PageHead({
      <HStack align="center" className="min-h-[60px] py-2.5" gap={4} justify="between" wrap="wrap">
        <HStack align="center" className="flex-1" gap={4}>
          {addonLeft && <div className="flex-shrink-0 whitespace-nowrap">{addonLeft}</div>}
-          {breadcrumbs && <div className="hidden sm:block">{breadcrumbs}</div>}
+          {breadcrumbs && <div className="hidden sm:block text-label-l [&_ol]:text-label-l">{breadcrumbs}</div>}
          <Header
            className={cn('min-w-0', breadcrumbs && 'sm:hidden')}
            level={4}
@@ -27,6 +27,6 @@
    "react-dom": "^19.1.0",
    "typescript": "^5.8.2",
    "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
  }
 }
@@ -26,9 +26,6 @@ export function defineServiceConfig(config: RsbuildConfig = {}): RsbuildConfig {
      distPath: {
        font: 'static/font',
      },
-      filename: {
-        font: '[name][ext]',
-      },
    },
    html: {
      template: './src/static/index.html',
@@ -8,6 +8,7 @@ import {
  ensureHostsEntry,
  findWorkspaceRoot,
  hasHostsEntry,
+  loadDevRootCaKey,
  localDevServer,
 } from './server.js';

@@ -21,9 +22,45 @@ describe('server dev configuration', () => {
    const certs = ensureDevCertificates();
    expect(existsSync(certs.certPath)).toBe(true);
    expect(existsSync(certs.keyPath)).toBe(true);
+    expect(certs.caCertPath).toBeDefined();
+    if (certs.caCertPath) {
+      expect(existsSync(certs.caCertPath)).toBe(true);
+      expect(certs.caCertPath).toContain('ErmnvldmrDevelopmentRootCA.pem');
+    }
    expect(certs.certPath).toContain('.certs/localhost.ermnvldmr.com.pem');
  });

+  it('loads dev root CA key from environment variable when present', () => {
+    const prevKey = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+    try {
+      process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY = 'mock-key-value\\nwith-newline';
+      const key = loadDevRootCaKey();
+      expect(key).toBe('mock-key-value\nwith-newline');
+    } finally {
+      if (prevKey !== undefined) {
+        process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY = prevKey;
+      } else {
+        delete process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+      }
+    }
+  });
+
+  it('loads dev root CA key from .env.dev when available', () => {
+    const prevKey = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+    delete process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+    try {
+      const key = loadDevRootCaKey();
+      expect(key).toBeDefined();
+      if (key) {
+        expect(key).toContain('BEGIN PRIVATE KEY');
+      }
+    } finally {
+      if (prevKey !== undefined) {
+        process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY = prevKey;
+      }
+    }
+  });
+
  it('returns production configuration without https when NODE_ENV is production', () => {
    const prevEnv = process.env.NODE_ENV;
    try {
@@ -10,6 +10,7 @@ import {
 } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';

 import type { ServerConfig } from '@rsbuild/core';

@@ -39,6 +40,10 @@ export interface DevCertificates {
   * Absolute path to the PEM private key file.
   */
  keyPath: string;
+  /**
+   * Absolute path to the PEM Root CA certificate file.
+   */
+  caCertPath?: string;
 }

 /**
@@ -146,11 +151,76 @@ export function findWorkspaceRoot(startDir: string = process.cwd()): string {
  return startDir;
 }

+interface DotenvxModule {
+  config: (options: { path?: string; envKeysFile?: string }) => void;
+}
+
+function isDotenvxModule(val: unknown): val is DotenvxModule {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    'config' in val &&
+    typeof val.config === 'function'
+  );
+}
+
+/**
+ * Resolves the development Root CA private key from the environment or .env.dev.
+ *
+ * @param workspaceRoot - Absolute path to workspace root
+ * @returns The PEM private key string, or undefined if unavailable
+ */
+export function loadDevRootCaKey(
+  workspaceRoot: string = findWorkspaceRoot()
+): string | undefined {
+  if (process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY) {
+    const raw = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+    return raw.includes('\\n') ? raw.replace(/\\n/g, '\n') : raw;
+  }
+
+  const envDevPath = join(workspaceRoot, '.env.dev');
+  const envKeysPath = join(workspaceRoot, '.env.keys');
+
+  if (!existsSync(envDevPath)) {
+    return undefined;
+  }
+
+  const candidatePackages = [
+    join(workspaceRoot, 'packages/cli/package.json'),
+    join(workspaceRoot, 'package.json'),
+  ];
+
+  for (const pkgPath of candidatePackages) {
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const req = createRequire(pkgPath);
+      const dotenvx: unknown = req('@dotenvx/dotenvx');
+      if (isDotenvxModule(dotenvx)) {
+        dotenvx.config({ path: envDevPath, envKeysFile: envKeysPath });
+        const key = process.env.COM_ERMNVLDMR_DEV_ROOT_CA_KEY;
+        if (key) {
+          return key.includes('\\n') ? key.replace(/\\n/g, '\n') : key;
+        }
+      }
+    } catch {
+      // Continue to next candidate package
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Remote public URL for the Ermnvldmr development root CA certificate.
+ */
+export const REMOTE_ROOT_CA_URL =
+  'https://static.ermnvldmr.com/dev/ssl/certs/ErmnvldmrDevelopmentRootCA.pem';
+
 /**
 * Ensures that valid TLS development certificates exist for localhost.ermnvldmr.com.
 *
- * Checks for certificates in the workspace `.certs` directory. If absent, generates
- * new certificates signed by either an existing mkcert/Hugo root CA or an openssl-generated CA.
+ * Checks for certificates in the workspace `.certs` directory. If absent, downloads
+ * or uses ErmnvldmrDevelopmentRootCA.pem and generates certificates signed by it.
 *
 * @param workspaceRoot - Absolute path to workspace root
 * @returns Paths to the certificate and private key files
@@ -161,128 +231,101 @@ export function ensureDevCertificates(
  const certsDir = join(workspaceRoot, '.certs');
  const certPath = join(certsDir, 'localhost.ermnvldmr.com.pem');
  const keyPath = join(certsDir, 'localhost.ermnvldmr.com-key.pem');
+  const caCertPath = join(certsDir, 'ErmnvldmrDevelopmentRootCA.pem');
+  const caKeyPath = join(certsDir, 'ErmnvldmrDevelopmentRootCA-key.pem');

  ensureHostsEntry('localhost.ermnvldmr.com', '127.0.0.1');

-  if (existsSync(certPath) && existsSync(keyPath)) {
-    return { certPath, keyPath };
-  }
+  const home = homedir();
+  const globalCaDir = join(home, '.local/share/mkcert');
+  const globalCaCert = join(globalCaDir, 'ErmnvldmrDevelopmentRootCA.pem');
+  const globalCaKey = join(globalCaDir, 'ErmnvldmrDevelopmentRootCA-key.pem');

  mkdirSync(certsDir, { recursive: true, mode: 0o700 });

-  const home = homedir();
-  const hugoCaCert = join(home, '.local/share/mkcert/rootCA.pem');
-  const hugoCaKey = join(home, '.local/share/mkcert/rootCA-key.pem');
-
-  let hasMkcertCli = false;
-  try {
-    execFileSync('mkcert', ['-help'], { stdio: 'ignore' });
-    hasMkcertCli = true;
-  } catch {
-    hasMkcertCli = false;
-  }
-
-  if (hasMkcertCli) {
-    execFileSync(
-      'mkcert',
-      [
-        '-cert-file',
-        certPath,
-        '-key-file',
-        keyPath,
-        'localhost.ermnvldmr.com',
-        '*.localhost.ermnvldmr.com',
-        'localhost',
-        '127.0.0.1',
-        '::1',
-      ],
-      { stdio: 'inherit' }
-    );
-    chmodSync(keyPath, 0o600);
-    return { certPath, keyPath };
-  }
-
-  if (existsSync(hugoCaCert) && existsSync(hugoCaKey)) {
-    const tempDir = tmpdir();
-    const tempCsr = join(tempDir, `ermnvldmr-dev-${Date.now()}.csr`);
-    const tempExt = join(tempDir, `ermnvldmr-dev-${Date.now()}.cnf`);
-
-    try {
-      writeFileSync(
-        tempExt,
-        'subjectAltName=DNS:localhost.ermnvldmr.com,DNS:*.localhost.ermnvldmr.com,DNS:localhost,IP:127.0.0.1,IP:::1\n'
-      );
-      execFileSync(
-        'openssl',
-        [
-          'req',
-          '-new',
-          '-nodes',
-          '-newkey',
-          'rsa:2048',
-          '-keyout',
-          keyPath,
-          '-out',
-          tempCsr,
-          '-subj',
-          '/CN=localhost.ermnvldmr.com',
-          '-batch',
-        ],
-        { stdio: 'pipe' }
-      );
-      execFileSync(
-        'openssl',
-        [
-          'x509',
-          '-req',
-          '-in',
-          tempCsr,
-          '-CA',
-          hugoCaCert,
-          '-CAkey',
-          hugoCaKey,
-          '-CAcreateserial',
-          '-out',
-          certPath,
-          '-days',
-          '825',
-          '-extfile',
-          tempExt,
-        ],
-        { stdio: 'pipe' }
-      );
-      chmodSync(keyPath, 0o600);
-      chmodSync(certPath, 0o644);
-    } finally {
-      rmSync(tempCsr, { force: true });
-      rmSync(tempExt, { force: true });
+  // 1. Sync CA cert from global cache if available, or download from remote static URL
+  if (!existsSync(caCertPath)) {
+    if (existsSync(globalCaCert)) {
+      writeFileSync(caCertPath, readFileSync(globalCaCert));
+      chmodSync(caCertPath, 0o644);
+    } else {
+      try {
+        execFileSync('curl', ['-sSfL', REMOTE_ROOT_CA_URL, '-o', caCertPath], {
+          stdio: 'ignore',
+        });
+        chmodSync(caCertPath, 0o644);
+        try {
+          mkdirSync(globalCaDir, { recursive: true });
+          writeFileSync(globalCaCert, readFileSync(caCertPath));
+          chmodSync(globalCaCert, 0o644);
+        } catch {
+          // Best-effort global cache
+        }
+      } catch {
+        // Failed to download, will fall back to generation if key also needed
+      }
    }
-    return { certPath, keyPath };
  }

-  const caDir = join(home, '.local/share/mkcert');
-  mkdirSync(caDir, { recursive: true });
-  execFileSync(
-    'openssl',
-    [
-      'req',
-      '-x509',
-      '-nodes',
-      '-newkey',
-      'rsa:3072',
-      '-keyout',
-      hugoCaKey,
-      '-out',
-      hugoCaCert,
-      '-days',
-      '3650',
-      '-subj',
-      '/CN=mkcert development CA/O=mkcert development CA',
-      '-batch',
-    ],
-    { stdio: 'pipe' }
-  );
+  // 2. Sync CA key from global cache if available, or decrypt from .env.dev
+  if (!existsSync(caKeyPath)) {
+    if (existsSync(globalCaKey)) {
+      writeFileSync(caKeyPath, readFileSync(globalCaKey));
+      chmodSync(caKeyPath, 0o600);
+    } else {
+      const decryptedKey = loadDevRootCaKey(workspaceRoot);
+      if (decryptedKey) {
+        writeFileSync(caKeyPath, decryptedKey);
+        chmodSync(caKeyPath, 0o600);
+        try {
+          mkdirSync(globalCaDir, { recursive: true });
+          writeFileSync(globalCaKey, decryptedKey);
+          chmodSync(globalCaKey, 0o600);
+        } catch {
+          // Best-effort global cache
+        }
+      }
+    }
+  }

+  // If server cert and CA cert already exist, return them
+  if (existsSync(certPath) && existsSync(keyPath) && existsSync(caCertPath)) {
+    return { certPath, keyPath, caCertPath };
+  }
+
+  // Ensure ErmnvldmrDevelopmentRootCA exists
+  if (!existsSync(caCertPath) || !existsSync(caKeyPath)) {
+    mkdirSync(globalCaDir, { recursive: true });
+    execFileSync(
+      'openssl',
+      [
+        'req',
+        '-x509',
+        '-nodes',
+        '-newkey',
+        'rsa:3072',
+        '-keyout',
+        caKeyPath,
+        '-out',
+        caCertPath,
+        '-days',
+        '3650',
+        '-subj',
+        '/CN=Ermnvldmr Development Root CA/O=ermnvldmr.com',
+        '-batch',
+      ],
+      { stdio: 'pipe' }
+    );
+    chmodSync(caKeyPath, 0o600);
+    chmodSync(caCertPath, 0o644);
+
+    writeFileSync(globalCaCert, readFileSync(caCertPath));
+    writeFileSync(globalCaKey, readFileSync(caKeyPath));
+    chmodSync(globalCaKey, 0o600);
+    chmodSync(globalCaCert, 0o644);
+  }
+
+  // Generate server certificate signed by ErmnvldmrDevelopmentRootCA
  const tempDir = tmpdir();
  const tempCsr = join(tempDir, `ermnvldmr-dev-${Date.now()}.csr`);
  const tempExt = join(tempDir, `ermnvldmr-dev-${Date.now()}.cnf`);
@@ -318,9 +361,9 @@ export function ensureDevCertificates(
        '-in',
        tempCsr,
        '-CA',
-        hugoCaCert,
+        caCertPath,
        '-CAkey',
-        hugoCaKey,
+        caKeyPath,
        '-CAcreateserial',
        '-out',
        certPath,
@@ -338,7 +381,7 @@ export function ensureDevCertificates(
    rmSync(tempExt, { force: true });
  }

-  return { certPath, keyPath };
+  return { certPath, keyPath, caCertPath };
 }

 /**
@@ -24,6 +24,7 @@
    "build": "tsc",
    "lint": "eslint src --max-warnings 0",
    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
    "clean": "rm -rf dist"
  },
  "dependencies": {
@@ -39,6 +40,8 @@
    "@rsbuild/core": "^1.7.3",
    "@rsbuild/plugin-react": "^1.1.1",
    "@rsbuild/plugin-type-check": "^1.1.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
    "@types/node": "*",
    "@types/react": "^19.1.2",
    "@types/react-dom": "^19.1.2",
@@ -46,7 +49,8 @@
    "fast-glob": "^3.3.3",
    "jsdom": "^28.0.0",
    "rsbuild-plugin-dts": "^0.19.5",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.11"
  },
  "peerDependencies": {
    "react": "^19.1.0",
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { umamiAnalytics } from './umami';
+
+describe('umamiAnalytics', () => {
+  it('suppresses script injection in non-production environments when not forced', () => {
+    const provider = umamiAnalytics({
+      serverUrl: '/pulse',
+      websiteId: 'test-website-id',
+    });
+
+    expect(provider.getHtmlTags(false)).toEqual([]);
+  });
+
+  it('injects script tag in non-production when force is true', () => {
+    const provider = umamiAnalytics({
+      serverUrl: '/pulse',
+      websiteId: 'test-website-id',
+      force: true,
+    });
+
+    const tags = provider.getHtmlTags(false);
+    expect(tags).toHaveLength(1);
+    expect(tags[0]?.attrs?.src).toBe('/pulse/script.js');
+  });
+
+  it('generates expected script attributes in production builds', () => {
+    const provider = umamiAnalytics({
+      serverUrl: '/trace/',
+      scriptName: 'trace.js',
+      hostUrl: '/trace',
+      websiteId: '41c7699a-0675-4f49-bcd0-3df47a66b6b1',
+      domains: 'ermnvldmr.com,www.ermnvldmr.com',
+      doNotTrack: true,
+      tag: 'landing',
+    });
+
+    const tags = provider.getHtmlTags(true);
+    expect(tags).toEqual([
+      {
+        tag: 'script',
+        head: true,
+        publicPath: false,
+        attrs: {
+          defer: true,
+          src: '/trace/trace.js',
+          'data-website-id': '41c7699a-0675-4f49-bcd0-3df47a66b6b1',
+          'data-host-url': '/trace',
+          'data-domains': 'ermnvldmr.com,www.ermnvldmr.com',
+          'data-do-not-track': 'true',
+          'data-tag': 'landing',
+        },
+      },
+    ]);
+  });
+});
@@ -5,14 +5,36 @@ import path from 'node:path';

 import React from 'react';

+import { getPageOptions } from '../core/createPage.js';
+
 import type { RsbuildPlugin } from '@rsbuild/core';

+/**
+ * Escapes HTML special characters for safe injection into markup.
+ *
+ * @param str - The raw string to escape.
+ * @returns The escaped HTML string.
+ * @example
+ * ```ts
+ * escapeHtml('<script>alert("xss")</script>');
+ * ```
+ */
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
 const SSR_RUNNER_SCRIPT = `
 import { createRsbuild } from '@rsbuild/core';

 async function main() {
  const entries = JSON.parse(process.argv[1]);
  const ssrDistPath = process.argv[2];
+  const locale = process.argv[3] || process.env.LOCALE || 'en';

  const plugins = [];
  try {
@@ -31,10 +53,35 @@ async function main() {
    // MDX plugins not installed or needed in this service
  }

+  if (locale !== 'en') {
+    plugins.push({
+      name: 'ermnvldmr:ssr-locale-mdx-replacement',
+      setup(api) {
+        api.modifyRspackConfig((config, { rspack }) => {
+          config.plugins = [
+            ...(config.plugins ?? []),
+            new rspack.NormalModuleReplacementPlugin(
+              /\\.en\\.mdx$/,
+              (resource) => {
+                resource.request = resource.request.replace(/\\.en\\.mdx$/, '.' + locale + '.mdx');
+              }
+            ),
+          ];
+          return config;
+        });
+      },
+    });
+  }
+
  const ssrBuild = await createRsbuild({
    rsbuildConfig: {
      plugins,
-      source: { entry: entries },
+      source: {
+        entry: entries,
+        define: {
+          'process.env.LOCALE': JSON.stringify(locale),
+        },
+      },
      output: {
        target: 'node',
        distPath: { root: ssrDistPath, js: '.' },
@@ -119,11 +166,16 @@ export function ssgPlugin(): RsbuildPlugin {
          );
        const ssrDistPath = path.join(path.dirname(webDistPath), 'dist-ssr');

+        const locale = process.env.LOCALE ?? 'en';
+
        console.log('[ssg-plugin] Building SSR bundles...');
        execFileSync(
          process.execPath,
-          ['--input-type=module', '-e', SSR_RUNNER_SCRIPT, JSON.stringify(entries), ssrDistPath],
-          { stdio: 'inherit' }
+          ['--input-type=module', '-e', SSR_RUNNER_SCRIPT, JSON.stringify(entries), ssrDistPath, locale],
+          {
+            stdio: 'inherit',
+            env: { ...process.env, LOCALE: locale },
+          }
        );
        console.log('[ssg-plugin] SSR bundles ready.');

@@ -134,10 +186,11 @@ export function ssgPlugin(): RsbuildPlugin {
        const Critters = _require('critters') as new (opts?: {
          path?: string;
          publicPath?: string;
-          preload?: string;
+          preload?: 'body' | 'media' | 'swap' | 'js' | 'js-lazy' | boolean;
          inlineFonts?: boolean;
          pruneSource?: boolean;
          reduceInlineStyles?: boolean;
+          allowRules?: (string | RegExp)[];
        }) => { process(html: string): Promise<string> };

        const configuredAssetPrefix =
@@ -147,10 +200,11 @@ export function ssgPlugin(): RsbuildPlugin {
        const critters = new Critters({
          path: webDistPath,
          publicPath: configuredAssetPrefix,
-          preload: 'media',
+          preload: false,
          inlineFonts: false,
          pruneSource: false,
          reduceInlineStyles: false,
+          allowRules: [/\.dark/],
        });

        for (const entryName of entryNames) {
@@ -173,8 +227,10 @@ export function ssgPlugin(): RsbuildPlugin {
            React.createElement(React.StrictMode, null, React.createElement(Component))
          );

+          const pageOptions = getPageOptions(Component);
+
          const source = await fs.readFile(webHtmlPath, 'utf8');
-          const injected = source.replace(
+          let injected = source.replace(
            /<div id="root"[^>]*>\s*<\/div>/,
            `<div id="root">${renderedHtml}</div>`
          );
@@ -185,9 +241,29 @@ export function ssgPlugin(): RsbuildPlugin {
            );
          }

+          if (pageOptions?.title) {
+            injected = injected.replace(
+              /<title>[^<]*<\/title>/i,
+              `<title>${escapeHtml(pageOptions.title)}</title>`
+            );
+          }
+
+          if (pageOptions?.description) {
+            if (/<meta\s+[^>]*name=["']description["'][^>]*>/i.test(injected)) {
+              injected = injected.replace(
+                /<meta\s+[^>]*name=["']description["'][^>]*>/i,
+                `<meta name="description" content="${escapeHtml(pageOptions.description)}">`
+              );
+            } else {
+              injected = injected.replace(
+                /<\/head>/i,
+                `  <meta name="description" content="${escapeHtml(pageOptions.description)}">\n</head>`
+              );
+            }
+          }
+
          const processed = await critters.process(injected);

-          const locale = process.env.LOCALE ?? 'en';
          const localized = processed.replace(
            /<html([^>]*)\slang="[^"]*"/,
            `<html$1 lang="${locale}"`
@@ -0,0 +1,78 @@
+import React from 'react';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { createPage, getPageOptions } from './createPage';
+
+describe('createPage and getPageOptions', () => {
+  beforeEach(() => {
+    document.title = 'Default Title';
+    const existingMeta = document.querySelector('meta[name="description"]');
+    if (existingMeta) {
+      existingMeta.remove();
+    }
+  });
+
+  it('attaches metadata options to component and retrieves them via getPageOptions', () => {
+    function SamplePage(): React.JSX.Element {
+      return <div>Sample</div>;
+    }
+
+    createPage(SamplePage, {
+      title: 'Sample Title',
+      description: 'Sample Description',
+    });
+
+    const options = getPageOptions(SamplePage);
+    expect(options).toEqual({
+      title: 'Sample Title',
+      description: 'Sample Description',
+    });
+  });
+
+  it('returns undefined for entities without metadata options', () => {
+    function PlainComponent(): React.JSX.Element {
+      return <div>Plain</div>;
+    }
+
+    expect(getPageOptions(PlainComponent)).toBeUndefined();
+    expect(getPageOptions(null)).toBeUndefined();
+    expect(getPageOptions(undefined)).toBeUndefined();
+    expect(getPageOptions('string')).toBeUndefined();
+    expect(getPageOptions(123)).toBeUndefined();
+    expect(getPageOptions({})).toBeUndefined();
+  });
+
+  it('updates document.title and creates meta description in DOM', () => {
+    function MetaPage(): React.JSX.Element {
+      return <div>Meta</div>;
+    }
+
+    createPage(MetaPage, {
+      title: 'Custom Title',
+      description: 'Custom Description',
+    });
+
+    expect(document.title).toBe('Custom Title');
+    const meta = document.querySelector('meta[name="description"]');
+    expect(meta).not.toBeNull();
+    expect(meta?.getAttribute('content')).toBe('Custom Description');
+  });
+
+  it('updates existing meta description if already present in DOM', () => {
+    const existingMeta = document.createElement('meta');
+    existingMeta.setAttribute('name', 'description');
+    existingMeta.setAttribute('content', 'Old Description');
+    document.head.appendChild(existingMeta);
+
+    function AnotherMetaPage(): React.JSX.Element {
+      return <div>Another Meta</div>;
+    }
+
+    createPage(AnotherMetaPage, {
+      description: 'Updated Description',
+    });
+
+    const meta = document.querySelector('meta[name="description"]');
+    expect(meta?.getAttribute('content')).toBe('Updated Description');
+  });
+});
@@ -0,0 +1,121 @@
+import React from 'react';
+
+/**
+ * Options for page creation.
+ */
+export interface PageOptions {
+  /** Document title to set on mount. */
+  title?: string;
+  /** Content of the meta description tag. */
+  description?: string;
+}
+
+/**
+ * Internal interface representing a component with attached page options.
+ */
+interface HasPageOptions {
+  /** The attached page options. */
+  __pageOptions?: PageOptions;
+}
+
+/**
+ * Type predicate checking if a value is an object or function with attached page options.
+ *
+ * @param value - The value to inspect.
+ * @returns True if value has __pageOptions.
+ * @example
+ * ```ts
+ * if (hasPageOptions(Component)) {
+ *   console.log(Component.__pageOptions);
+ * }
+ * ```
+ */
+function hasPageOptions(value: unknown): value is HasPageOptions {
+  return (
+    (typeof value === 'function' || (typeof value === 'object' && value !== null)) &&
+    '__pageOptions' in value
+  );
+}
+
+/**
+ * Retrieves the page metadata options attached to a component via createPage.
+ *
+ * @param component - The component to inspect.
+ * @returns The associated PageOptions, or undefined if none are set.
+ * @example
+ * ```ts
+ * const options = getPageOptions(MyPageComponent);
+ * ```
+ */
+export function getPageOptions(component: unknown): PageOptions | undefined {
+  if (hasPageOptions(component)) {
+    return component.__pageOptions;
+  }
+  return undefined;
+}
+
+/**
+ * Mounts or hydrates a React component into the `#root` element.
+ *
+ * Attaches metadata options for SSG extraction. Skips DOM mounting during the SSG
+ * server-side render pass (`typeof window === 'undefined'`). On the client, hydrates
+ * asynchronously during idle time to unblock First Contentful Paint.
+ *
+ * @param Component - The React component to render.
+ * @param options - Optional page metadata (title, description).
+ *
+ * @example
+ * ```tsx
+ * createPage(App, { title: 'My Page' });
+ * ```
+ */
+export function createPage(Component: React.ComponentType, options: PageOptions = {}): void {
+  Object.assign(Component, { __pageOptions: options });
+
+  if (typeof window === 'undefined') return; // SSG build context: skip DOM mounting
+  const rootElement = document.getElementById('root');
+
+  if (options.title && document.title !== options.title) {
+    document.title = options.title;
+  }
+
+  if (options.description) {
+    let metaDescription = document.querySelector('meta[name="description"]');
+    if (!metaDescription) {
+      metaDescription = document.createElement('meta');
+      metaDescription.setAttribute('name', 'description');
+      document.head.appendChild(metaDescription);
+    }
+    if (metaDescription.getAttribute('content') !== options.description) {
+      metaDescription.setAttribute('content', options.description);
+    }
+  }
+
+  if (!rootElement) return;
+
+  const mountOrHydrate = () => {
+    void import('react-dom/client')
+      .then(({ createRoot, hydrateRoot }) => {
+        const node = React.createElement(
+          React.StrictMode,
+          null,
+          React.createElement(Component)
+        );
+
+        if (rootElement.hasChildNodes()) {
+          hydrateRoot(rootElement, node);
+        } else {
+          createRoot(rootElement).render(node);
+        }
+      })
+      .catch((err: unknown) => {
+        console.error('[createPage] Client hydration failed:', err);
+      });
+  };
+
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(mountOrHydrate);
+  } else {
+    setTimeout(mountOrHydrate, 1);
+  }
+}
@@ -1,73 +0,0 @@
-import React from 'react';
-
-/**
- * Options for page creation.
- */
-export interface PageOptions {
-  /** Document title to set on mount. */
-  title?: string;
-  /** Content of the meta description tag. */
-  description?: string;
-}
-
-/**
- * Mounts or hydrates a React component into the `#root` element.
- *
- * Skips DOM mounting during the SSG server-side render pass
- * (`typeof window === 'undefined'`). On the client, hydrates asynchronously
- * during idle time to unblock First Contentful Paint.
- *
- * @param Component - The React component to render.
- * @param options - Optional page metadata (title, description).
- *
- * @example
- * ```tsx
- * createPage(App, { title: 'My Page' });
- * ```
- */
-export function createPage(Component: React.ComponentType, options: PageOptions = {}): void {
-  if (typeof window === 'undefined') return; // SSG build context: skip DOM mounting
-  const rootElement = document.getElementById('root');
-
-  if (options.title) {
-    document.title = options.title;
-  }
-
-  if (options.description) {
-    let metaDescription = document.querySelector('meta[name="description"]');
-    if (!metaDescription) {
-      metaDescription = document.createElement('meta');
-      metaDescription.setAttribute('name', 'description');
-      document.head.appendChild(metaDescription);
-    }
-    metaDescription.setAttribute('content', options.description);
-  }
-
-  if (!rootElement) return;
-
-  const mountOrHydrate = () => {
-    void import('react-dom/client')
-      .then(({ createRoot, hydrateRoot }) => {
-        const node = (
-          <React.StrictMode>
-            <Component />
-          </React.StrictMode>
-        );
-
-        if (rootElement.hasChildNodes()) {
-          hydrateRoot(rootElement, node);
-        } else {
-          createRoot(rootElement).render(node);
-        }
-      })
-      .catch((err: unknown) => {
-        console.error('[createPage] Client hydration failed:', err);
-      });
-  };
-
-  if ('requestIdleCallback' in window) {
-    window.requestIdleCallback(mountOrHydrate);
-  } else {
-    setTimeout(mountOrHydrate, 1);
-  }
-}
@@ -0,0 +1,9 @@
+import { baseVitestConfig } from '@ermnvldmr/rsbuild-config/dev';
+import { mergeConfig } from 'vitest/config';
+
+export default mergeConfig(baseVitestConfig, {
+  test: {
+    environment: 'jsdom',
+    exclude: ['dist/**', 'node_modules/**'],
+  },
+});
@@ -53,7 +53,7 @@
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "typescript": "^5.8.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
  },
  "peerDependencies": {
    "react": "^19.1.0",
@@ -30,6 +30,6 @@
    "babel-plugin-istanbul": "^7.0.1",
    "storybook-react-rsbuild": "^1.0.3",
    "typescript": "^5.8.3",
-    "vite": "^8.0.7"
+    "vite": "^8.1.6"
  }
 }
@@ -91,11 +91,11 @@
    "http-server": "^14.1.1",
    "jsdom": "^28.0.0",
    "playwright": "^1.57.0",
-    "postcss": "^8.5.14",
+    "postcss": "^8.5.23",
    "storybook": "^8.6.17",
    "storybook-react-rsbuild": "^1.0.3",
    "typescript": "^5.8.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.11",
    "wait-on": "^8.0.3"
  },
  "peerDependencies": {
@@ -76,3 +76,15 @@ export const WithBullets: Story = {
    </Breadcrumbs>
  ),
 };
+
+export const Large: Story = {
+  render: () => (
+    <Breadcrumbs size="l">
+      <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Separator variant="slash" />
+      <Breadcrumbs.Item href="/articles">Articles</Breadcrumbs.Item>
+      <Breadcrumbs.Separator variant="slash" />
+      <Breadcrumbs.Item isCurrent>Deep Learning</Breadcrumbs.Item>
+    </Breadcrumbs>
+  ),
+};
@@ -36,6 +36,16 @@ describe('components/Breadcrumbs', () => {
    expect(ol.className).toContain('text-label-m');
  });

+  it('supports custom size variant', () => {
+    render(
+      <Breadcrumbs size="l">
+        <Breadcrumbs.Item href="/test">Home</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    const ol = screen.getByRole('list');
+    expect(ol.className).toContain('text-label-l');
+  });
+
  it('supports isCurrent state', () => {
    render(
      <Breadcrumbs>
@@ -16,15 +16,44 @@ import type { ClassNameProps, TestIdProps } from '@ermnvldmr/stl';
 export interface BreadcrumbsProps extends HStackProps {
  /** Breadcrumb items and separators */
  children: React.ReactNode;
+  /**
+   * Typography size variant for the breadcrumbs trail.
+   * @default 'm'
+   */
+  size?: 's' | 'm' | 'l';
 }

+const breadcrumbsVariants = cva('font-sans font-medium', {
+  variants: {
+    size: {
+      s: 'text-label-s',
+      m: 'text-label-m',
+      l: 'text-label-l',
+    },
+  },
+  defaultVariants: {
+    size: 'm',
+  },
+});
+
 /**
 * Root component for hierarchical navigation.
 */
-const BreadcrumbsRoot = memo(function Breadcrumbs({ children, className, ...props }: BreadcrumbsProps) {
+const BreadcrumbsRoot = memo(function Breadcrumbs({
+  children,
+  className,
+  size = 'm',
+  ...props
+}: BreadcrumbsProps) {
  return (
-    <nav aria-label="Breadcrumb" className={className}>
-      <HStack align="center" as="ol" className="text-label-m font-sans font-medium" gap={2} {...props}>
+    <nav aria-label="Breadcrumb">
+      <HStack
+        align="center"
+        as="ol"
+        className={cn(breadcrumbsVariants({ size }), className)}
+        gap={2}
+        {...props}
+      >
        {children}
      </HStack>
    </nav>
@@ -126,7 +155,7 @@ const BreadcrumbsSeparator = memo(function BreadcrumbsSeparator({
  const content = {
    slash: '/',
    bull: '•',
-    arrow: <ChevronRight className="size-4" />,
+    arrow: <ChevronRight className="size-[1em]" />,
  };

  return (
@@ -1,6 +1,7 @@
 import React, { useState } from 'react';

 import { Switch } from './Switch';
+import { VStack } from '../VStack/VStack';

 import type { Meta, StoryObj } from '@storybook/react';

@@ -8,6 +9,16 @@ const meta: Meta<typeof Switch> = {
  title: 'Components/Switch',
  component: Switch,
  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['s', 'm', 'l'],
+    },
+    variant: {
+      control: 'select',
+      options: ['solid', 'outline', 'ghost'],
+    },
+  },
 };

 export default meta;
@@ -19,6 +30,16 @@ export const Default: Story = {
  },
 };

+export const Sizes: Story = {
+  render: () => (
+    <VStack gap={4}>
+      <Switch size="s">Small Switch</Switch>
+      <Switch size="m">Medium Switch</Switch>
+      <Switch size="l">Large Switch</Switch>
+    </VStack>
+  ),
+};
+
 export const Selected: Story = {
  args: {
    children: 'Selected State',
@@ -66,5 +66,18 @@ describe('components/Switch', () => {
    expect(track).toHaveClass('data-[selected=true]:bg-primary');
    expect(thumb).toHaveClass('data-[selected=true]:bg-primary-text');
  });
+
+  it('applies size variant classes to track and thumb', () => {
+    const { container, rerender } = render(<Switch size="s">Small</Switch>);
+    const track = container.querySelector('[aria-hidden="true"]');
+    const thumb = track?.firstElementChild;
+
+    expect(track).toHaveClass('w-7', 'h-4');
+    expect(thumb).toHaveClass('w-2.5', 'h-2.5');
+
+    rerender(<Switch size="l">Large</Switch>);
+    expect(track).toHaveClass('w-14', 'h-8');
+    expect(thumb).toHaveClass('w-6', 'h-6');
+  });
 });

@@ -14,6 +14,11 @@ import type { AriaSwitchProps } from 'react-aria';
 */
 export type SwitchVariant = 'solid' | 'outline' | 'ghost';

+/**
+ * Switch size variants.
+ */
+export type SwitchSize = 's' | 'm' | 'l';
+
 /**
 * Switch color themes.
 */
@@ -39,12 +44,14 @@ export interface SwitchProps extends AriaSwitchProps, ClassNameProps, DataAttrib
  children?: React.ReactNode;
  /** Visual style variant */
  variant?: SwitchVariant;
+  /** Switch size */
+  size?: SwitchSize;
  /** Color theme */
  color?: SwitchColor;
 }

 const trackVariants = cva(
-  'relative w-11 h-6 transition-all duration-200 ease-in-out rounded-full outline-none flex items-center',
+  'relative transition-all duration-200 ease-in-out rounded-full outline-none flex items-center',
  {
    variants: {
      variant: {
@@ -52,6 +59,11 @@ const trackVariants = cva(
        outline: 'border-2 data-[selected=false]:bg-transparent data-[selected=false]:border-muted',
        ghost: 'data-[selected=false]:bg-transparent data-[selected=false]:border-transparent',
      },
+      size: {
+        s: 'w-7 h-4',
+        m: 'w-11 h-6',
+        l: 'w-14 h-8',
+      },
      color: {
        primary: '',
        'primary-negative': '',
@@ -118,19 +130,25 @@ const trackVariants = cva(
    ],
    defaultVariants: {
      variant: 'solid',
+      size: 'm',
      color: 'primary',
    },
  }
 );

 const thumbVariants = cva(
-  'w-4 h-4 transition-all duration-200 ease-in-out transform rounded-full shadow-sm data-[selected=false]:bg-[var(--rb-text)] data-[selected=false]:translate-x-0',
+  'transition-all duration-200 ease-in-out transform rounded-full shadow-sm data-[selected=false]:bg-[var(--rb-text)] data-[selected=false]:translate-x-0',
  {
    variants: {
      variant: {
-        solid: 'ml-1 data-[selected=true]:translate-x-5',
-        outline: 'ml-0.5 data-[selected=true]:translate-x-4.5',
-        ghost: 'ml-1 data-[selected=true]:translate-x-5',
+        solid: '',
+        outline: '',
+        ghost: '',
+      },
+      size: {
+        s: 'w-2.5 h-2.5',
+        m: 'w-4 h-4',
+        l: 'w-6 h-6',
      },
      color: {
        primary: '',
@@ -146,6 +164,17 @@ const thumbVariants = cva(
      },
    },
    compoundVariants: [
+      // size + variant offsets
+      { size: 's', variant: 'solid', className: 'ml-0.5 data-[selected=true]:translate-x-3.5' },
+      { size: 's', variant: 'outline', className: 'ml-0.5 data-[selected=true]:translate-x-2.5' },
+      { size: 's', variant: 'ghost', className: 'ml-0.5 data-[selected=true]:translate-x-3.5' },
+      { size: 'm', variant: 'solid', className: 'ml-1 data-[selected=true]:translate-x-5' },
+      { size: 'm', variant: 'outline', className: 'ml-0.5 data-[selected=true]:translate-x-4.5' },
+      { size: 'm', variant: 'ghost', className: 'ml-1 data-[selected=true]:translate-x-5' },
+      { size: 'l', variant: 'solid', className: 'ml-1 data-[selected=true]:translate-x-6' },
+      { size: 'l', variant: 'outline', className: 'ml-0.5 data-[selected=true]:translate-x-5.5' },
+      { size: 'l', variant: 'ghost', className: 'ml-1 data-[selected=true]:translate-x-6' },
+
      // primary
      { variant: 'solid', color: 'primary', className: 'data-[selected=true]:bg-primary-text' },
      { variant: 'outline', color: 'primary', className: 'data-[selected=true]:bg-primary-text' },
@@ -198,6 +227,7 @@ const thumbVariants = cva(
    ],
    defaultVariants: {
      variant: 'solid',
+      size: 'm',
      color: 'primary',
    },
  }
@@ -216,7 +246,7 @@ const thumbVariants = cva(
 * ```
 */
 export function Switch(props: SwitchProps): React.JSX.Element {
-  const { children, className, variant = 'solid', color = 'primary' } = props;
+  const { children, className, variant = 'solid', size = 'm', color = 'primary' } = props;
  const state = useToggleState(props);
  const ref = useRef<HTMLInputElement>(null);
  const { inputProps } = useSwitch(props, state, ref);
@@ -238,14 +268,14 @@ export function Switch(props: SwitchProps): React.JSX.Element {
      <div
        aria-hidden="true"
        className={cn(
-          trackVariants({ variant, color }),
+          trackVariants({ variant, size, color }),
          isFocusVisible && 'ring-2 ring-offset-2 ring-[var(--rb-ring)]',
          props.isDisabled && 'grayscale-[0.5]'
        )}
        data-selected={state.isSelected}
      >
        <div
-          className={thumbVariants({ variant, color })}
+          className={thumbVariants({ variant, size, color })}
          data-selected={state.isSelected}
        />
      </div>
@@ -253,7 +283,7 @@ export function Switch(props: SwitchProps): React.JSX.Element {
        <Text
          bold={state.isSelected}
          color={state.isSelected ? 'default' : 'muted'}
-          size="s"
+          size={size}
          type="label"
        >
          {children}
@@ -10,7 +10,7 @@ export const THEME_INIT_SCRIPT = `(function(){try{var k='ermnvldmr/ui/lib/theme'
 * These align with the main palette in styles.css.
 */
 export const THEME_INIT_STYLES = `
-  :root { background-color: #fafafa; color: #262626; }
-  .dark { background-color: #141414; color: #f6f6f6; }
+  :root { --rb-background: #fafafa; --rb-base: #f6f6f6; --rb-text: #262626; background-color: #fafafa; color: #262626; }
+  .dark { --rb-background: #141414; --rb-base: #262626; --rb-text: #f6f6f6; background-color: #141414; color: #f6f6f6; }
  body { margin: 0; transition: background-color 0.2s ease; }
 `;
@@ -6,16 +6,17 @@ export default defineCli({
      name: 'sync:static',
      description: 'Sync static assets to S3',
      targetPrefix: 'docs',
-      sourceDir: './static',
+      sourceDir: './public/static',
      sourceFilesPattern: 'content/**/*.{md,html}',
      urlPrefixes: ['/static/', '/images/'],
      bucket: env('COM_ERMNVLDMR_STATIC_S3_BUCKET'),
+      publicUrl: env('COM_ERMNVLDMR_STATIC_PUBLIC_URL', 'https://static.ermnvldmr.com'),
      region: env('COM_ERMNVLDMR_STATIC_S3_REGION'),
      endpoint: env('COM_ERMNVLDMR_STATIC_S3_ENDPOINT_URL'),
      accessKeyId: env('COM_ERMNVLDMR_STATIC_AWS_ACCESS_KEY_ID'),
      secretAccessKey: env('COM_ERMNVLDMR_STATIC_AWS_SECRET_ACCESS_KEY'),
      hooks: {
-        beforeSync: 'bash ../../ci/scripts/optimize-images.sh ./static',
+        beforeSync: 'bash ../../ci/scripts/optimize-images.sh ./public/static',
      },
    }),
  ],
@@ -0,0 +1,36 @@
+(function () {
+  var KEY = "umami.disabled";
+  var toggles = document.querySelectorAll("[data-umami-toggle]");
+  if (!toggles.length) return;
+
+  function sync() {
+    var enabled = true;
+    try {
+      enabled = window.localStorage.getItem(KEY) !== "1";
+    } catch (e) {}
+    toggles.forEach(function (el) {
+      el.checked = enabled;
+    });
+  }
+
+  sync();
+
+  toggles.forEach(function (el) {
+    el.addEventListener("change", function () {
+      try {
+        if (el.checked) {
+          window.localStorage.removeItem(KEY);
+        } else {
+          window.localStorage.setItem(KEY, "1");
+        }
+      } catch (e) {}
+      sync();
+    });
+  });
+
+  window.addEventListener("storage", function (e) {
+    if (e.key === KEY || e.key === null) {
+      sync();
+    }
+  });
+})();
@@ -8,15 +8,15 @@ layout: hextra-home

 <div class="hx:mb-6">
 {{< hextra/hero-headline >}}
-Documenting Decisions<br class="hx:sm:block hx:hidden" />Without the&nbsp;Actual Decisions
+Documenting Decisions<br class="hx:sm:block hx:hidden" />Without the Actual Decisions
 {{< /hextra/hero-headline >}}
 </div>

 <div class="hx:mb-6">
 {{< hextra/hero-subtitle >}}
-I&nbsp;have neither the&nbsp;time nor the&nbsp;desire to&nbsp;manually craft every line of&nbsp;this half-baked novel. Yet&nbsp;capturing context and&nbsp;architectural decisions is&nbsp;essential, otherwise the&nbsp;number of&nbsp;entities comprehending what goes on&nbsp;here drops to&nbsp;zero. Consider this a&nbsp;structured neural knowledge dump for&nbsp;AI&nbsp;agents and&nbsp;rare human visitors.
+I have neither the time nor the desire to manually craft every line of this half-baked novel. Yet capturing context and architectural decisions is essential, otherwise the number of entities comprehending what goes on here drops to zero. Consider this a structured neural knowledge dump for AI agents and rare human visitors.
 <br /><br />
-If&nbsp;you ever feel like fixing anything (why though?)&nbsp;— any contribution here is&nbsp;guaranteed to&nbsp;be an&nbsp;improvement.
+If you ever feel like fixing anything (why though?) — any contribution here is guaranteed to be an improvement.
 {{< /hextra/hero-subtitle >}}
 </div>

@@ -46,7 +46,7 @@ If&nbsp;you ever feel like fixing anything (why though?)&nbsp;— any contributi
 <div class="hx:overflow-hidden hx:border hx:border-gray-200 hx:dark:border-neutral-800 hx:shadow-lg hx:bg-gray-50 hx:dark:bg-neutral-900/50" style="border-radius: 1.5rem; height: 100%; display: flex; flex-direction: column;">
 <img src="https://static.ermnvldmr.com/docs/images/home/dead-internet-debugging.webp" alt="Dead Internet Debugging" class="hx:w-full" style="flex: 1 1 auto; width: 100%; height: 100%; min-height: 340px; object-fit: cover; object-position: top; border-radius: 1.5rem 1.5rem 0 0;" />
 <div class="hx:p-3 hx:text-xs hx:text-gray-500 hx:dark:text-gray-400 hx:text-center hx:border-t hx:border-gray-200 hx:dark:border-neutral-800" style="flex-shrink: 0;">
-Image enhanced with Gemini&nbsp;4&nbsp;Argon&nbsp;· <a href="https://www.reddit.com/r/ProgrammerHumor/s/UVVd1CnFxH" target="_blank" rel="noreferrer" class="hx:underline hx:hover:text-primary-600">Original on&nbsp;Reddit</a>
+Image enhanced with Gemini 4 Argon · <a href="https://www.reddit.com/r/ProgrammerHumor/s/UVVd1CnFxH" target="_blank" rel="noreferrer" class="hx:underline hx:hover:text-primary-600">Original on Reddit</a>
 </div>
 </div>
 </div>
@@ -1,24 +1,24 @@
 ---
-title: Documentation of the apex fleet operations framework
-description: "Documentation for the apex fleet operations framework: a stdlib-python engine and a shared compose core for self-hosted nodes."
+title: Documentation of the apex fleet operations framework
+description: "Documentation for the apex fleet operations framework: a stdlib-python engine and a shared compose core for self-hosted nodes."
 weight: 1
 type: docs
 cascade:
  type: docs
 ---

-`apex` is the [commons](/apex/glossary#commons) of a fleet of self-hosted [nodes](/apex/glossary#node): a python3-stdlib [engine](/apex/glossary#engine) that runs grouped [actions](/apex/glossary#action) as `apex <group>/<action>`, paired with a shared, `${env}`-parameterized docker-compose core. Every node repository consumes the framework as the pinned `commons/` git submodule. apex succeeds the bash `root` commons framework.
+`apex` is the [commons](/apex/glossary#commons) of a fleet of self-hosted [nodes](/apex/glossary#node): a python3-stdlib [engine](/apex/glossary#engine) that runs grouped [actions](/apex/glossary#action) as `apex <group>/<action>`, paired with a shared, `${env}`-parameterized docker-compose core. Every node repository consumes the framework as the pinned `commons/` git submodule. apex succeeds the bash `root` commons framework.

-The stack is deliberately small: `git` plus the Python 3 standard library. There is no `pip`, Node, Go, or CUE, and compose files are hand-authored — no code generation.
+The stack is deliberately small: `git` plus the Python 3 standard library. There is no `pip`, Node, Go, or CUE, and compose files are hand-authored — no code generation.

 ## Core features

- **Single entrypoint on the local checkout** — `apex` always acts on the checkout it runs from; there is no `<node>` argument to pass.
- **Explicit identity from `node.env`** — [node identity](/apex/glossary#node-identity) is declared per node in `node.env` (`APEX_NODE_FQDN`, `APEX_NODE_HOST`, `APEX_SUBNET`); the framework assumes no particular domain, and the short node `name` is just the first label of the host.
- **Four-pillar node repositories** — every node repository follows the same shape: the pinned `commons/` submodule, node-local [proprietaries](/apex/glossary#proprietaries), the node's [compositions](/apex/glossary#compositions), and its `node.env`.
- **Proprietary overlay** — node-local proprietaries are [overlaid](/apex/glossary#overlay) over the shared actions; commons holds only what every node shares.
- **Tiered storage with privilege isolation** — standardized storage [tiers](/apex/glossary#tier) with per-project privilege isolation.
- **Shared core composition** — the [core composition](/apex/glossary#core-composition) (`compositions/apex/docker-compose.yml`) is `${env}`-parameterized and included in every node's compositions.
+- **Single entrypoint on the local checkout** — `apex` always acts on the checkout it runs from; there is no `<node>` argument to pass.
+- **Explicit identity from `node.env`** — [node identity](/apex/glossary#node-identity) is declared per node in `node.env` (`APEX_NODE_FQDN`, `APEX_NODE_HOST`, `APEX_SUBNET`); the framework assumes no particular domain, and the short node `name` is just the first label of the host.
+- **Four-pillar node repositories** — every node repository follows the same shape: the pinned `commons/` submodule, node-local [proprietaries](/apex/glossary#proprietaries), the node's [compositions](/apex/glossary#compositions), and its `node.env`.
+- **Proprietary overlay** — node-local proprietaries are [overlaid](/apex/glossary#overlay) over the shared actions; commons holds only what every node shares.
+- **Tiered storage with privilege isolation** — standardized storage [tiers](/apex/glossary#tier) with per-project privilege isolation.
+- **Shared core composition** — the [core composition](/apex/glossary#core-composition) (`compositions/apex/docker-compose.yml`) is `${env}`-parameterized and included in every node's compositions.

 ## Sections

@@ -1,10 +1,10 @@
 ---
 title: Concepts
-description: "Architecture, identity, actions, execution context, compositions, storage, addressing, and security."
+description: "Architecture, identity, actions, execution context, compositions, storage, addressing, and security."
 weight: 10
 ---

-Theoretical foundations of the apex fleet-operations framework: how a [node](/apex/glossary#node) declares its [identity](/apex/concepts/node-identity), how [actions](/apex/glossary#action) execute, and how a node organizes its services, storage, and addressing.
+Theoretical foundations of the apex fleet-operations framework: how a [node](/apex/glossary#node) declares its [identity](/apex/concepts/node-identity), how [actions](/apex/glossary#action) execute, and how a node organizes its services, storage, and addressing.

 {{% cards %}}
 {{< card link="architecture" title="Architecture" icon="share" subtitle="The engine, commons, and configs layers and how they fit together." >}}
@@ -21,5 +21,5 @@ Theoretical foundations of the apex fleet-operations framework: how a [node](/ap

 **See also:**

- [Guides: Operating an apex fleet](/apex/guides)
- [Reference: Commands and interfaces](/apex/reference)
+- [Guides: Operating an apex fleet](/apex/guides)
+- [Reference: Commands and interfaces](/apex/reference)
@@ -1,19 +1,19 @@
 ---
-title: "Actions and the overlay"
-description: "The action contract and how node-local proprietaries shadow commons actions."
+title: "Actions and the overlay"
+description: "The action contract and how node-local proprietaries shadow commons actions."
 weight: 13
 ---

-Every unit of automation in apex is an [action](/apex/glossary#action): a single Python module that the [engine](/apex/glossary#engine) dispatches by name. The [overlay](/apex/glossary#overlay) lets a node's [proprietaries](/apex/glossary#proprietaries) add, override, or disable [commons](/apex/glossary#commons) actions without forking them. This page defines the action contract, the declarative argument descriptors, and the resolution rules.
+Every unit of automation in apex is an [action](/apex/glossary#action): a single Python module that the [engine](/apex/glossary#engine) dispatches by name. The [overlay](/apex/glossary#overlay) lets a node's [proprietaries](/apex/glossary#proprietaries) add, override, or disable [commons](/apex/glossary#commons) actions without forking them. This page defines the action contract, the declarative argument descriptors, and the resolution rules.

-## The action contract {#contract}
+## The action contract {#contract}

-An action is one `.py` file under an `actions/` tree. The file path **is** the action name: `actions/<group>/<action>.py` is invoked as `apex <group>/<action> [args...]`. There is no registry to update — dropping a file into the tree publishes the action.
+An action is one `.py` file under an `actions/` tree. The file path **is** the action name: `actions/<group>/<action>.py` is invoked as `apex <group>/<action> [args...]`. There is no registry to update — dropping a file into the tree publishes the action.

-The module must expose two things:
+The module must expose two things:

- **`METADATA = Meta(...)`** &rarr; the summary and argument descriptors that drive both the help text and parsing. The descriptor system succeeds the `action_metadata()` heredoc of the bash "root" commons framework, apex's predecessor.
- **`run(ctx, args)`** &rarr; the entrypoint. `ctx` is the engine-built execution context; `args` is the parsed `argparse` namespace.
+- **`METADATA = Meta(...)`** &rarr; the summary and argument descriptors that drive both the help text and parsing. The descriptor system succeeds the `action_metadata()` heredoc of the bash "root" commons framework, apex's predecessor.
+- **`run(ctx, args)`** &rarr; the entrypoint. `ctx` is the engine-built execution context; `args` is the parsed `argparse` namespace.

 ```python {filename="actions/<group>/<action>.py"}
 from engine.descriptor import Meta, Arg, Flag
@@ -31,36 +31,36 @@ def run(ctx, args):
    return 0
 ```

-The return value of `run` becomes the process exit code. A non-integer return (including `None`) is treated as success (`0`). An unhandled exception is logged with the context prefix and exits `1`.
+The return value of `run` becomes the process exit code. A non-integer return (including `None`) is treated as success (`0`). An unhandled exception is logged with the context prefix and exits `1`.

 > [!NOTE]
-> `METADATA` is technically optional — a module without it is dispatched with an empty `Meta` and accepts no arguments — but every real action should declare it, since the listing and `--help` output are generated from it.
+> `METADATA` is technically optional — a module without it is dispatched with an empty `Meta` and accepts no arguments — but every real action should declare it, since the listing and `--help` output are generated from it.

 ## Declarative arguments {#arguments}

-`Meta.args` is a list of descriptors. Each maps to exactly one `argparse` construct:
+`Meta.args` is a list of descriptors. Each maps to exactly one `argparse` construct:

-| Descriptor | Maps to | Behavior |
+| Descriptor | Maps to | Behavior |
 | --- | --- | --- |
-| `Arg("name")` | positional argument | Required by default; `required=False` makes it an optional positional (`nargs="?"`, default `None`). |
-| `Opt("--name", default=...)` | value option | An optional flag that takes a value, with a declared default. |
+| `Arg("name")` | positional argument | Required by default; `required=False` makes it an optional positional (`nargs="?"`, default `None`). |
+| `Opt("--name", default=...)` | value option | An optional flag that takes a value, with a declared default. |
 | `Flag("--name")` | boolean flag | `store_true`; present means `True`. |
-| `Rest("name")` | remainder | Greedy passthrough of all remaining argv (`argparse.REMAINDER`). |
+| `Rest("name")` | remainder | Greedy passthrough of all remaining argv (`argparse.REMAINDER`). |

-The engine builds the parser as `apex <group>/<action>` and parses the remaining argv before calling `run`. `--help` is handled at parse time. A usage error — unknown flag, missing positional — prints usage and exits `64` (`EX_USAGE`) instead of argparse's default `2`.
+The engine builds the parser as `apex <group>/<action>` and parses the remaining argv before calling `run`. `--help` is handled at parse time. A usage error — unknown flag, missing positional — prints usage and exits `64` (`EX_USAGE`) instead of argparse's default `2`.

 ## Listing without importing {#listing}

-`apex` with no arguments (or `--help`) lists every available action. Listing never imports action modules: the engine statically scans each file with the `ast` module and extracts only the `METADATA` summary and any `DISABLED` constant. Action code therefore cannot run — or crash — at list time; a file that fails to parse is listed as `(unparseable)` rather than breaking the listing.
+`apex` with no arguments (or `--help`) lists every available action. Listing never imports action modules: the engine statically scans each file with the `ast` module and extracts only the `METADATA` summary and any `DISABLED` constant. Action code therefore cannot run — or crash — at list time; a file that fails to parse is listed as `(unparseable)` rather than breaking the listing.

-Each entry is tagged with its overlay source:
+Each entry is tagged with its overlay source:

- no tag &rarr; a commons action,
- `(local)` &rarr; exists only in proprietaries,
- `(local override)` &rarr; a proprietaries action shadowing a commons one,
- `[DISABLED: reason]` &rarr; the action declares `DISABLED`.
+- no tag &rarr; a commons action,
+- `(local)` &rarr; exists only in proprietaries,
+- `(local override)` &rarr; a proprietaries action shadowing a commons one,
+- `[DISABLED: reason]` &rarr; the action declares `DISABLED`.

-## The overlay {#overlay}
+## The overlay {#overlay}

 Action names are resolved across two trees, proprietaries first:

@@ -81,31 +81,31 @@ Action names are resolved across two trees, proprietaries first:
 {{< /filetree/folder >}}
 {{< /filetree/container >}}

-The engine detects this layout by its own location: when it runs from a `commons/` directory whose parent contains `node.env`, the parent is the [node](/apex/glossary#node) repository root and `proprietaries/actions/` is the overlay tree. A standalone commons checkout is its own root and has no overlay layer. Inside a node repository, [node identity](/apex/glossary#node-identity) is resolved from the host FQDN before dispatch.
+The engine detects this layout by its own location: when it runs from a `commons/` directory whose parent contains `node.env`, the parent is the [node](/apex/glossary#node) repository root and `proprietaries/actions/` is the overlay tree. A standalone commons checkout is its own root and has no overlay layer. Inside a node repository, [node identity](/apex/glossary#node-identity) is resolved from the host FQDN before dispatch.

-Resolution for a given name checks `proprietaries/actions/<name>.py` first and `commons/actions/<name>.py` second; exactly one module is loaded by path. An unknown name is an error (exit `1`). The overlay supports four moves:
+Resolution for a given name checks `proprietaries/actions/<name>.py` first and `commons/actions/<name>.py` second; exactly one module is loaded by path. An unknown name is an error (exit `1`). The overlay supports four moves:

- **Add** &rarr; a file that exists only in proprietaries becomes a node-local action, listed as `(local)`.
- **Override** &rarr; a proprietaries file at the same relative path shadows the commons implementation entirely; the commons path is recorded on the resolution as `shadowed`.
- **Wrap** &rarr; an overriding module can delegate to the implementation it shadows via `ctx.commons.run(args)`, adding node-local behavior before or after the commons logic instead of replacing it.
- **Disable** &rarr; a module that assigns `DISABLED = "reason"` is refused at dispatch: the engine logs the reason and exits `1`. The listing shows `[DISABLED: reason]`. A bare `DISABLED = True` also disables, with the generic reason `disabled`; an empty string does not.
+- **Add** &rarr; a file that exists only in proprietaries becomes a node-local action, listed as `(local)`.
+- **Override** &rarr; a proprietaries file at the same relative path shadows the commons implementation entirely; the commons path is recorded on the resolution as `shadowed`.
+- **Wrap** &rarr; an overriding module can delegate to the implementation it shadows via `ctx.commons.run(args)`, adding node-local behavior before or after the commons logic instead of replacing it.
+- **Disable** &rarr; a module that assigns `DISABLED = "reason"` is refused at dispatch: the engine logs the reason and exits `1`. The listing shows `[DISABLED: reason]`. A bare `DISABLED = True` also disables, with the generic reason `disabled`; an empty string does not.

 ## Exit codes {#exit-codes}

-Actions and the engine follow a fixed exit-code convention:
+Actions and the engine follow a fixed exit-code convention:

 | Code | Meaning | Typical cause |
 | --- | --- | --- |
-| `0` | success | `run` returned `0` or a non-integer. |
+| `0` | success | `run` returned `0` or a non-integer. |
 | `1` | general error | Unknown action, disabled action, unhandled exception, non-integer `SystemExit`. |
-| `64` | usage error | Arguments rejected by the parser (`EX_USAGE`). |
-| `65` | data error | Malformed input data (`EX_DATAERR`), raised by engine libraries. |
-| `66` | missing input | A required input is absent (`EX_NOINPUT`), raised by engine libraries. |
+| `64` | usage error | Arguments rejected by the parser (`EX_USAGE`). |
+| `65` | data error | Malformed input data (`EX_DATAERR`), raised by engine libraries. |
+| `66` | missing input | A required input is absent (`EX_NOINPUT`), raised by engine libraries. |

 ---

 **See also:**

 - [Concept: Framework architecture](/apex/concepts/architecture)
- [Concept: The execution context](/apex/concepts/execution-context)
+- [Concept: The execution context](/apex/concepts/execution-context)
 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
@@ -1,46 +1,46 @@
 ---
 title: "Fleet addressing scheme"
-description: "Per-node /24 subnets and static anchor IPs inside the enclave space (default 198.18.0.0/16)."
+description: "Per-node /24 subnets and static anchor IPs inside the enclave space (default 198.18.0.0/16)."
 weight: 17
 ---

-Apex assigns every service a fixed, predictable IPv4 address inside a per-node subnet. Each node declares its own `/24`, service anchors are static addresses within it, and the whole scheme is enforced mechanically by the anchor-IP lint.
+Apex assigns every service a fixed, predictable IPv4 address inside a per-node subnet. Each node declares its own `/24`, service anchors are static addresses within it, and the whole scheme is enforced mechanically by the anchor-IP lint.

 ## Address space {#address-space}

-The [enclave](/apex/glossary#enclave) space defaults to `198.18.0.0/16`, the benchmarking range set aside by [RFC 2544: Benchmarking Methodology for Network Interconnect Devices](https://datatracker.ietf.org/doc/html/rfc2544). This range is never routed on the public Internet and does not collide with the common private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) that cloud providers and home networks already consume. The operator may override it via `APEX_ENCLAVE_SUBNET`.
+The [enclave](/apex/glossary#enclave) space defaults to `198.18.0.0/16`, the benchmarking range set aside by [RFC 2544: Benchmarking Methodology for Network Interconnect Devices](https://datatracker.ietf.org/doc/html/rfc2544). This range is never routed on the public Internet and does not collide with the common private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) that cloud providers and home networks already consume. The operator may override it via `APEX_ENCLAVE_SUBNET`.

 ## Node subnets {#node-subnets}

-Each [node](/apex/glossary#node) declares exactly one `/24` as `APEX_SUBNET` in its `node.env`, and that subnet is the `direct` network's IPAM range. The operator assigns it; conventionally it sits inside the enclave space (`198.18.0.0/16` by default, or whatever `APEX_ENCLAVE_SUBNET` is set to), but the framework imposes no arithmetic on the choice.
+Each [node](/apex/glossary#node) declares exactly one `/24` as `APEX_SUBNET` in its `node.env`, and that subnet is the `direct` network's IPAM range. The operator assigns it; conventionally it sits inside the enclave space (`198.18.0.0/16` by default, or whatever `APEX_ENCLAVE_SUBNET` is set to), but the framework imposes no arithmetic on the choice.

 > [!NOTE]
-> As an optional operator convention, you may organize node `/24`s into contiguous blocks (for example, grouping related nodes) to keep allocations legible. This is a bookkeeping choice, not a framework rule.
+> As an optional operator convention, you may organize node `/24`s into contiguous blocks (for example, grouping related nodes) to keep allocations legible. This is a bookkeeping choice, not a framework rule.

-## Allocation inside a node /24 {#node-allocation}
+## Allocation inside a node /24 {#node-allocation}

-Within a node's `/24`, host addresses are partitioned by role:
+Within a node's `/24`, host addresses are partitioned by role:

 | Range | Purpose |
 |---|---|
-| `.10`–`.19` | Reserved for [core composition](/apex/glossary#core-composition) anchors; `traefik` is always `.10` (via `APEX_TRAEFIK_DIRECT_IP`) |
-| `.20` and up | Service anchors, allocated per `<project>` |
+| `.10`–`.19` | Reserved for [core composition](/apex/glossary#core-composition) anchors; `traefik` is always `.10` (via `APEX_TRAEFIK_DIRECT_IP`) |
+| `.20` and up | Service anchors, allocated per `<project>` |

-Every service anchor is a static `ipv4_address` on the direct network — a fixed [anchor IP](/apex/glossary#anchor-ip) rather than a dynamically assigned lease. Allocations are recorded in `compositions/ADDRESSING.md`, which serves as the human-readable register for the node's subnet.
+Every service anchor is a static `ipv4_address` on the direct network — a fixed [anchor IP](/apex/glossary#anchor-ip) rather than a dynamically assigned lease. Allocations are recorded in `compositions/ADDRESSING.md`, which serves as the human-readable register for the node's subnet.

 ## Enforcement {#enforcement}

-The compose lint validates anchor IPs across all [compositions](/apex/glossary#compositions) on a node. For every `ipv4_address` found in `compositions/*/docker-compose.yml` it checks that the address is:
+The compose lint validates anchor IPs across all [compositions](/apex/glossary#compositions) on a node. For every `ipv4_address` found in `compositions/*/docker-compose.yml` it checks that the address is:

- **Well-formed** — a malformed literal is reported as a lint error, not a crash.
- **Unique** — the same anchor IP may not appear in two projects; duplicates are reported with both offending projects.
- **Inside the node subnet** — every anchor must fall within the node's declared `/24`.
+- **Well-formed** — a malformed literal is reported as a lint error, not a crash.
+- **Unique** — the same anchor IP may not appear in two projects; duplicates are reported with both offending projects.
+- **Inside the node subnet** — every anchor must fall within the node's declared `/24`.

-Any violation fails the lint with exit code `1` (general error). Passing validation logs `Anchor IP validation passed.` The implementation lives in the `utils/lint-docker-compose` [action](/apex/glossary#action); see [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com).
+Any violation fails the lint with exit code `1` (general error). Passing validation logs `Anchor IP validation passed.` The implementation lives in the `utils/lint-docker-compose` [action](/apex/glossary#action); see [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com).

 ---

 **See also:**

 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
- [RFC 2544: Benchmarking Methodology for Network Interconnect Devices](https://datatracker.ietf.org/doc/html/rfc2544)
+- [RFC 2544: Benchmarking Methodology for Network Interconnect Devices](https://datatracker.ietf.org/doc/html/rfc2544)
@@ -1,14 +1,14 @@
 ---
 title: Framework architecture
-description: Four-pillar node repositories, the commons submodule, and the dispatch flow.
+description: Four-pillar node repositories, the commons submodule, and the dispatch flow.
 weight: 11
 ---

-apex splits fleet automation into one shared repository — the [commons](/apex/glossary#commons) — and one repository per [node](/apex/glossary#node). The commons carries everything every node shares: the [engine](/apex/glossary#engine), the shared [actions](/apex/glossary#action), and the [core composition](/apex/glossary#core-composition). A node repository carries everything that makes that node itself: its identity, host [configs](/apex/glossary#configs), service [compositions](/apex/glossary#compositions), and node-local [proprietaries](/apex/glossary#proprietaries).
+apex splits fleet automation into one shared repository — the [commons](/apex/glossary#commons) — and one repository per [node](/apex/glossary#node). The commons carries everything every node shares: the [engine](/apex/glossary#engine), the shared [actions](/apex/glossary#action), and the [core composition](/apex/glossary#core-composition). A node repository carries everything that makes that node itself: its identity, host [configs](/apex/glossary#configs), service [compositions](/apex/glossary#compositions), and node-local [proprietaries](/apex/glossary#proprietaries).

-## The four pillars {#pillars}
+## The four pillars {#pillars}

-Every node repository has the same shape:
+Every node repository has the same shape:

 {{< filetree/container >}}
 {{< filetree/folder name="<node>.<your-domain>" state="open" >}}
@@ -23,16 +23,16 @@ Every node repository has the same shape:

 | Pillar | Content | Ownership |
 |---|---|---|
-| `commons/` | Git submodule → `apex.ermnvldmr.com`, pinned to a release tag | Shared, versioned |
-| `proprietaries/` | Node-local actions, libraries, and tool sources ([overlaid](/apex/glossary#overlay) over commons) | Node |
+| `commons/` | Git submodule → `apex.ermnvldmr.com`, pinned to a release tag | Shared, versioned |
+| `proprietaries/` | Node-local actions, libraries, and tool sources ([overlaid](/apex/glossary#overlay) over commons) | Node |
 | `configs/` | Host configuration sources: `ufw/`, `cron/crontab`, `systemd/`, `crowdsec/` | Node |
-| `compositions/` | One directory per project plus the `apex/` core wrapper and the addressing ledger | Node |
+| `compositions/` | One directory per project plus the `apex/` core wrapper and the addressing ledger | Node |

-The submodule pin is the framework's version contract: a node runs exactly the engine and core composition recorded in its gitlink. Upgrading a node is a deliberate act — check out a newer tag inside `commons/` and commit the moved pointer.
+The submodule pin is the framework's version contract: a node runs exactly the engine and core composition recorded in its gitlink. Upgrading a node is a deliberate act — check out a newer tag inside `commons/` and commit the moved pointer.

 ## Dispatch flow {#dispatch}

-The launcher `commons/apex` acts on the local checkout; there is no node argument anywhere.
+The launcher `commons/apex` acts on the local checkout; there is no node argument anywhere.

 ```mermaid
 flowchart TD
@@ -47,32 +47,30 @@ flowchart TD
    H --> I["run(ctx, args)"]
 ```

-The engine detects the layout from its own location: running from a directory named `commons/` whose parent contains `node.env` means "node checkout" — the parent becomes the repository root and `proprietaries/actions/` becomes the overlay tree. Any other location is a standalone commons checkout acting as its own root.
+The engine detects the layout from its own location: running from a directory named `commons/` whose parent contains `node.env` means "node checkout" — the parent becomes the repository root and `proprietaries/actions/` becomes the overlay tree. Any other location is a standalone commons checkout acting as its own root.

-Listing (`apex --help`) never imports action modules; summaries and disabled markers are extracted by static `ast` scanning. Dispatch loads exactly one module by path. Details in [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay).
+Listing (`apex --help`) never imports action modules; summaries and disabled markers are extracted by static `ast` scanning. Dispatch loads exactly one module by path. Details in [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay).

-## The capture-up model {#capture-up}
+## The capture-up model {#capture-up}

-Node repositories are ledgers, not just sources: the host itself records what it runs.
+`apex sync/repository` records the working tree and commons pin in a
+`sync/<node>` branch, rebases onto `origin/main`, and pushes with
+`--force-with-lease`. It refuses to run when commons has uncommitted changes
+or the `compositions/` directory is missing. A rebase conflict aborts the sync.

-1. A scheduled `sync/repository` run on the host commits the working tree to a `sync/<node>` branch (including the commons submodule pointer), rebases it onto `origin/main`, and pushes with `--force-with-lease`.
-2. A scheduled CI job in the node repository merges `sync/<node>` back into `main` under a bot identity.
-
-This [capture-up](/apex/glossary#capture-up) loop means drift on a host becomes a commit — visible, diffable, and revertable — instead of silent divergence. The sync aborts rather than committing when the commons submodule is dirty or the `compositions/` tree is missing, so a broken checkout never becomes the recorded state.
-
-> [!NOTE]
-> The CI merge job checks out the repository *without* submodules: the commons submodule uses an SSH URL that the default CI token cannot fetch, and the merge only moves the gitlink pointer anyway.
+Review and integration of that branch are repository policies. APEX does not
+supply a CI merge workflow or require a particular repository hosting setup.

 ## Design constraints {#constraints}

- **Stdlib only.** The engine runs on a stock Debian Python 3 — no `pip`, no third-party imports. The optional `vendor/` directory exists for pinned pure-Python code but ships empty.
- **Hand-authored composes.** There is no manifest layer or code generation; compose files are the source of truth.
- **Evidence over convention.** Anything enforceable is enforced by an action (anchor-IP lint, crontab rollback, marker-block self-healing) rather than by documentation.
+- **Stdlib only.** The engine runs on a stock Debian Python 3 — no `pip`, no third-party imports. The optional `vendor/` directory exists for pinned pure-Python code but ships empty.
+- **Hand-authored composes.** There is no manifest layer or code generation; compose files are the source of truth.
+- **Evidence over convention.** Anything enforceable is enforced by an action (anchor-IP lint, crontab rollback, marker-block self-healing) rather than by documentation.

 ---

 **See also:**

- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
+- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
 - [Concept: Node identity resolution](/apex/concepts/node-identity)
- [Guide: Build a node repository](/apex/guides/node-repository)
+- [Guide: Build a node repository](/apex/guides/node-repository)
@@ -1,14 +1,14 @@
 ---
-title: Compositions and the shared core
-description: The include-based core composition, profiles, networks, and env layering.
+title: Compositions and the shared core
+description: The include-based core composition, profiles, networks, and env layering.
 weight: 15
 ---

-A node's runtime is declared as [compositions](/apex/glossary#compositions): one docker-compose project per service under `compositions/<project>/`, plus the [core composition](/apex/glossary#core-composition) — the edge and infrastructure services every node needs. The core lives in the [commons](/apex/glossary#commons) and is consumed per node through a thin wrapper, so its definition is written once and versioned with the framework.
+A node's runtime is declared as [compositions](/apex/glossary#compositions): one docker-compose project per service under `compositions/<project>/`, plus the [core composition](/apex/glossary#core-composition) — the edge and infrastructure services every node needs. The core lives in the [commons](/apex/glossary#commons) and is consumed per node through a thin wrapper, so its definition is written once and versioned with the framework.

-## The include wrapper {#include}
+## The include wrapper {#include}

-Each node's `compositions/apex/docker-compose.yml` is three lines:
+Each node's `compositions/apex/docker-compose.yml` is three lines:

 ```yaml {filename="compositions/apex/docker-compose.yml"}
 name: apex
@@ -16,9 +16,9 @@ include:
  - ../../commons/compositions/apex/docker-compose.yml
 ```

-The shared file is fully `${APEX_*}`-parameterized and contains no relative host paths — every mount resolves through variables the [engine](/apex/glossary#engine) exports at invocation, so the same file is correct on every node.
+The shared file is fully `${APEX_*}`-parameterized and contains no relative host paths — every mount resolves through variables the [engine](/apex/glossary#engine) exports at invocation, so the same file is correct on every node.

-A structural outlier — a node that genuinely needs to change a core service, such as publishing an extra host port — layers an override through the include path-list form instead of editing the shared file:
+A structural outlier — a node that genuinely needs to change a core service, such as publishing an extra host port — layers an override through the include path-list form instead of editing the shared file:

 ```yaml {filename="compositions/apex/docker-compose.yml"}
 name: apex
@@ -29,59 +29,59 @@ include:
 ```

 > [!NOTE]
-> The `include:` directive requires Docker Compose v2.20 or newer.
+> The `include:` directive requires Docker Compose v2.20 or newer.

-## Core services and profiles {#core-services}
+## Core services and profiles {#core-services}

-The core composition defines the fleet's shared service set. Always-on services:
+The core composition defines the fleet's shared service set. Always-on services:

- **traefik** — the edge reverse proxy and the anchor of the `direct` network (always `.10` in the node subnet). It terminates TLS via a DNS challenge, discovers backends through docker labels, and exposes its dashboard on the node FQDN behind an [enclave](/apex/glossary#enclave) IP allowlist.
- **socket-proxy** — a filtered docker-socket proxy; traefik reads container state through it and never touches the socket directly.
+- **traefik** — the edge reverse proxy and the anchor of the `direct` network (always `.10` in the node subnet). It terminates TLS via a DNS challenge, discovers backends through docker labels, and exposes its dashboard on the node FQDN behind an [enclave](/apex/glossary#enclave) IP allowlist.
+- **socket-proxy** — a filtered docker-socket proxy; traefik reads container state through it and never touches the socket directly.

-Opt-in services, gated by compose profiles a node enables in `COMPOSE_PROFILES` (set in `apex.env`):
+Opt-in services, gated by compose profiles a node enables in `COMPOSE_PROFILES` (set in `apex.env`):

 | Profile | Service | Role |
 |---|---|---|
-| `xray` | xray | Host-network proxy edge for the enclave. |
-| `adguard` | adguard | DNS filtering, sharing traefik's network namespace; routed at `/adguard` on the node FQDN. |
-| `alloy` | alloy | Per-node observability agent (Grafana Alloy). Collects host + container metrics and journal + container logs and **pushes** them outbound to a central Prometheus and Loki (see [Concept: Security model](/apex/concepts/security-model#observability)). Its container `hostname` is set to `APEX_NODE_HOST`, and that value stamps the `node` and `instance` labels on every metric and log stream. |
-| `manual` | resticontainer | One-shot label-driven backup runner (`ghcr.io/deytenit/resticontainer`) — never starts with `up`; invoked by the `backup/run` action, which discovers per-service backup intent from `restic.*` compose labels. |
+| `xray` | xray | Host-network proxy edge for the enclave. |
+| `adguard` | adguard | DNS filtering, sharing traefik's network namespace; routed at `/adguard` on the node FQDN. |
+| `alloy` | alloy | Optional Grafana Alloy agent. Sends host/container metrics and journal/container logs to configured compatible endpoints. See [observability configuration](/apex/concepts/security-model#observability). |
+| `manual` | resticontainer | One-shot label-driven backup runner (`ghcr.io/deytenit/resticontainer`) — never starts with `up`; invoked by the `backup/run` action, which discovers per-service backup intent from `restic.*` compose labels. |

 ## Networks {#networks}

-The core composition owns the three node networks; service compositions reference them by key with `external: true`.
+The core composition owns the three node networks; service compositions reference them by key with `external: true`.

 | Network | Type | Purpose |
 |---|---|---|
-| `direct` | bridge, subnet = `APEX_SUBNET` | Static-[anchor-IP](/apex/glossary#anchor-ip) network; every project's anchor holds a fixed address here (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)). |
+| `direct` | bridge, subnet = `APEX_SUBNET` | Static-[anchor-IP](/apex/glossary#anchor-ip) network; every project's anchor holds a fixed address here (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)). |
 | `enclave` | bridge, `internal: true` | Reverse-proxy backend network; traefik reaches labeled services here. |
 | `socket` | bridge, `internal: true` | Carries only traefik ↔ socket-proxy traffic. |

-Within a project, sibling containers typically join the anchor's network namespace (`network_mode: service:<anchor>`) instead of attaching to networks themselves.
+Within a project, sibling containers typically join the anchor's network namespace (`network_mode: service:<anchor>`) instead of attaching to networks themselves.

 ## Environment layering {#env-layering}

-Values reach a composition from three layers, in increasing precedence:
+Values reach a composition from three layers, in increasing precedence:

-1. **`.env`** — uncommitted secrets, a symlink into tier-1 storage (`APEX_RESTIC_*` credentials, `APEX_TRAEFIK_*` tokens, the UID/GID block).
-2. **`apex.env`** — committed non-secret scalars (`APEX_TRAEFIK_DIRECT_IP`, `APEX_RESTIC_REPOSITORY`, `COMPOSE_PROFILES`, optional `APEX_RESTIC_COMPRESSION`).
-3. **Engine exports** — the `APEX_*` identity and [tier](/apex/glossary#tier) paths from `ctx.vars()`, injected into the process environment by the orchestration actions and therefore winning over both files.
+1. **`.env`** — uncommitted secrets, a symlink into tier-1 storage (`APEX_RESTIC_*` credentials, `APEX_TRAEFIK_*` tokens, the UID/GID block).
+2. **`apex.env`** — committed non-secret scalars (`APEX_TRAEFIK_DIRECT_IP`, `APEX_RESTIC_REPOSITORY`, `COMPOSE_PROFILES`, optional `APEX_RESTIC_COMPRESSION`).
+3. **Engine exports** — the `APEX_*` identity and [tier](/apex/glossary#tier) paths from `ctx.vars()`, injected into the process environment by the orchestration actions and therefore winning over both files.

-Critical variables carry `?error` markers in the shared file, so a missing secret fails composition config loudly instead of starting a misconfigured container.
+Critical variables carry `?error` markers in the shared file, so a missing secret fails composition config loudly instead of starting a misconfigured container.

 ## Orchestration {#orchestration}

-`apex compose <action>` drives every composition on the node:
+`apex compose <action>` drives every composition on the node:

- **Order** — the core project first (it owns the networks), then every service composition in alphabetical order; `down` reverses the sequence.
- **Env files** — for each project, `.env` and `apex.env` are passed as `--env-file` when present.
- **`up`** implies `-d`; any extra arguments pass through to `docker compose`.
- **`--dry-run`** prints each command with its working directory instead of executing — accepted anywhere on the command line.
+- **Order** — the core project first (it owns the networks), then every service composition in alphabetical order; `down` reverses the sequence.
+- **Env files** — for each project, `.env` and `apex.env` are passed as `--env-file` when present.
+- **`up`** implies `-d`; any extra arguments pass through to `docker compose`.
+- **`--dry-run`** prints each command with its working directory instead of executing — accepted anywhere on the command line.

 ---

 **See also:**

 - [Concept: Fleet addressing scheme](/apex/concepts/addressing)
- [Guide: Add a service composition](/apex/guides/service-composition)
+- [Guide: Add a service composition](/apex/guides/service-composition)
 - [Reference: Environment variables](/apex/reference/environment)
@@ -1,66 +1,66 @@
 ---
-title: The execution context
-description: ctx — the single seam between an action and the host.
+title: The execution context
+description: ctx — the single seam between an action and the host.
 weight: 14
 ---

-Every [action](/apex/glossary#action) receives a `ctx` object as its first argument. It is the only sanctioned way to touch the host: logging, process execution, template rendering, file mutation, firewall and service management, and notifications all go through it. Actions therefore stay declarative, and behavior that must be consistent fleet-wide (log format, backup discipline, notification payloads) lives in one place — the [engine](/apex/glossary#engine).
+Every [action](/apex/glossary#action) receives a `ctx` object as its first argument. It is the only sanctioned way to touch the host: logging, process execution, template rendering, file mutation, firewall and service management, and notifications all go through it. Actions therefore stay declarative, and behavior that must be consistent fleet-wide (log format, backup discipline, notification payloads) lives in one place — the [engine](/apex/glossary#engine).

 ## Members {#members}

 | Member | Purpose |
 |---|---|
-| `ctx.log` | Prefixed logging: `[<node>] [<action>] [LEVEL] message`; errors go to stderr, everything else to stdout. |
-| `ctx.sys` | Process execution (`run`, `sudo`, `ok`), systemd service helpers, and idempotent package installation. |
-| `ctx.tpl` | Template rendering over the `configs/` pillar with `string.Template.safe_substitute`. |
-| `ctx.host` | Idempotent host mutation: timestamped backups, atomic file writes, marker-block injection, crontab installation with rollback. |
-| `ctx.ufw` | Host and container firewall application (see [Concept: Security model](/apex/concepts/security-model)). |
-| `ctx.crowdsec` | CrowdSec installation, config deployment, and collection management. |
-| `ctx.systemd` | Rendering and enabling systemd units from `configs/systemd/`. |
-| `ctx.notify` | Telegram notifications; every method returns a boolean so actions can gate their exit code on delivery. |
-| `ctx.paths` | Resolved repository paths: `repo_root`, `commons`, `proprietaries`, `configs`, `compositions`, `core`, and the tier properties. |
-| `ctx.node` | The resolved [node identity](/apex/glossary#node-identity) record (`name`, `subnet`, `fqdn`, `host`); `None` in a standalone commons checkout. |
-| `ctx.commons` | Available only in an overriding proprietary action: `ctx.commons.run(args)` delegates to the shadowed commons implementation. |
+| `ctx.log` | Prefixed logging: `[<node>] [<action>] [LEVEL] message`; errors go to stderr, everything else to stdout. |
+| `ctx.sys` | Process execution (`run`, `sudo`, `ok`), systemd service helpers, and idempotent package installation. |
+| `ctx.tpl` | Template rendering over the `configs/` pillar with `string.Template.safe_substitute`. |
+| `ctx.host` | Idempotent host mutation: timestamped backups, atomic file writes, marker-block injection, crontab installation with rollback. |
+| `ctx.ufw` | Host and container firewall application (see [Concept: Security model](/apex/concepts/security-model)). |
+| `ctx.crowdsec` | CrowdSec installation, config deployment, and collection management. |
+| `ctx.systemd` | Rendering and enabling systemd units from `configs/systemd/`. |
+| `ctx.notify` | Telegram notifications; every method returns a boolean so actions can gate their exit code on delivery. |
+| `ctx.paths` | Resolved repository paths: `repo_root`, `commons`, `proprietaries`, `configs`, `compositions`, `core`, and the tier properties. |
+| `ctx.node` | The resolved [node identity](/apex/glossary#node-identity) record (`name`, `subnet`, `fqdn`, `host`); `None` in a standalone commons checkout. |
+| `ctx.commons` | Available only in an overriding proprietary action: `ctx.commons.run(args)` delegates to the shadowed commons implementation. |

-Method-level signatures are listed in [Reference: Engine API](/apex/reference/engine-api).
+Method-level signatures are listed in [Reference: Engine API](/apex/reference/engine-api).

 ## Template semantics {#templates}

-`ctx.tpl` renders files from `configs/` with Python's `string.Template.safe_substitute`:
+`ctx.tpl` renders files from `configs/` with Python's `string.Template.safe_substitute`:

- Known `$VAR` and `${VAR}` references are replaced.
- **Unknown references stay literal.** A typo in a template survives into the rendered output where it is visible, instead of silently collapsing to an empty string.
- Shell command substitution (`$(...)`) passes through untouched, which keeps crontab entries with embedded `$(cat ...)` intact.
+- Known `$VAR` and `${VAR}` references are replaced.
+- **Unknown references stay literal.** A typo in a template survives into the rendered output where it is visible, instead of silently collapsing to an empty string.
+- Shell command substitution (`$(...)`) passes through untouched, which keeps crontab entries with embedded `$(cat ...)` intact.

-The substitution set is `ctx.vars()` — the full process environment plus the engine-provided `APEX_*` values below. Loops and conditionals never live in templates; they belong in the action.
+The substitution set is `ctx.vars()` — the full process environment plus the engine-provided `APEX_*` values below. Loops and conditionals never live in templates; they belong in the action.

-## The variable export {#vars}
+## The variable export {#vars}

-`ctx.vars()` returns the environment used for every template render, and its `APEX_*` subset is exported to `docker compose` by the orchestration actions. On a node it contains:
+`ctx.vars()` returns the environment used for every template render, and its `APEX_*` subset is exported to `docker compose` by the orchestration actions. On a node it contains:

 | Variable | Value |
 |---|---|
-| `APEX_COMMONS` | Absolute path of the commons directory (the launcher lives at `$APEX_COMMONS/apex`). |
-| `APEX_REPO_ROOT` | Absolute path of the node repository root. |
-| `APEX_NODE_HOST`, `APEX_NODE_FQDN`, `APEX_SUBNET` | The resolved identity fields. |
-| `APEX_TIER1`…`APEX_TIER3` | The core project's per-[tier](/apex/glossary#tier) data directories. |
-| `APEX_TIER1_SHARED`…`APEX_TIER3_SHARED` | The shared areas inside each tier. |
-| `APEX_TIER_ROOT1`…`APEX_TIER_ROOT3` | The tier storage roots (node-level links). |
+| `APEX_COMMONS` | Absolute path of the commons directory (the launcher lives at `$APEX_COMMONS/apex`). |
+| `APEX_REPO_ROOT` | Absolute path of the node repository root. |
+| `APEX_NODE_HOST`, `APEX_NODE_FQDN`, `APEX_SUBNET` | The resolved identity fields. |
+| `APEX_TIER1`…`APEX_TIER3` | The core project's per-[tier](/apex/glossary#tier) data directories. |
+| `APEX_TIER1_SHARED`…`APEX_TIER3_SHARED` | The shared areas inside each tier. |
+| `APEX_TIER_ROOT1`…`APEX_TIER_ROOT3` | The tier storage roots (node-level links). |

-The full origin/consumer matrix is in [Reference: Environment variables](/apex/reference/environment).
+The full origin/consumer matrix is in [Reference: Environment variables](/apex/reference/environment).

 ## Host mutation discipline {#host}

-`ctx.host` encodes the framework's write rules:
+`ctx.host` encodes the framework's write rules:

- **Atomic writes.** `write_file` renders to a temporary file (mode `0644`, matching what a root shell redirect would create) and installs it with `mv` or `sudo cp`; overwriting an existing file preserves that file's mode.
- **Timestamped backups.** When requested, the previous file is kept next to the target as `<name>.<epoch>.bak` before the write.
- **Marker-block injection.** Managed blocks inside system files (for example `/etc/ufw/before.rules`) are delimited by start/end marker comments. Injection removes every prior managed block — including blocks left by predecessor tooling — before inserting the fresh one after its anchor line, so re-runs never accumulate.
- **Crontab rollback.** `install_crontab` snapshots the current crontab, refuses an empty render (exit `65`), previews the result, and restores the snapshot if installation fails.
+- **Atomic writes.** `write_file` renders to a temporary file (mode `0644`, matching what a root shell redirect would create) and installs it with `mv` or `sudo cp`; overwriting an existing file preserves that file's mode.
+- **Timestamped backups.** When requested, the previous file is kept next to the target as `<name>.<epoch>.bak` before the write.
+- **Marker-block injection.** Managed blocks inside system files (for example `/etc/ufw/before.rules`) are delimited by start/end marker comments. Injection removes every prior managed block — including blocks left by predecessor tooling — before inserting the fresh one after its anchor line, so re-runs never accumulate.
+- **Crontab rollback.** `install_crontab` snapshots the current crontab, refuses an empty render (exit `65`), previews the result, and restores the snapshot if installation fails.

 ## Notifications {#notifications}

-`ctx.notify` posts Telegram messages through the standard library (`urllib`). Payloads carry the instance name — the node's public host `APEX_NODE_HOST` — a status (`firing`/`resolved`), an escalation level, and the message truncated to 200 characters. Every method returns `True` only when the send succeeded; unattended actions treat a failed send of their final status message as a failure (exit `1`), so a broken notification channel is noticed instead of silently tolerated.
+`ctx.notify` posts Telegram messages through the standard library (`urllib`). Payloads carry the instance name — the node's public host `APEX_NODE_HOST` — a status (`firing`/`resolved`), an escalation level, and the message truncated to 200 characters. Every method returns `True` only when the send succeeded; unattended actions treat a failed send of their final status message as a failure (exit `1`), so a broken notification channel is noticed instead of silently tolerated.

 ---

@@ -68,4 +68,4 @@ The full origin/consumer matrix is in [Reference: Environment variables](/apex/r

 - [Reference: Engine API](/apex/reference/engine-api)
 - [Reference: Environment variables](/apex/reference/environment)
- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
+- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
@@ -1,74 +1,74 @@
 ---
 title: "Node identity resolution"
-description: "How a node learns who it is: node.env identity keys and the FQDN fallback."
+description: "How a node learns who it is: node.env identity keys and the FQDN fallback."
 weight: 12
 ---

-Every apex operation runs in the context of exactly one [node](/apex/glossary#node). The [engine](/apex/glossary#engine) derives that [node identity](/apex/glossary#node-identity) — node name, subnet, FQDN, and public host — from the `node.env` file at the repository root, with the OS hostname as a fallback for the FQDN only. The framework assumes no domain and no clustering: a node declares who it is explicitly. This resolution step succeeds the `root_require_node` mechanism of the bash "root" commons framework that apex replaces.
+Every apex operation runs in the context of exactly one [node](/apex/glossary#node). The [engine](/apex/glossary#engine) derives that [node identity](/apex/glossary#node-identity) — node name, subnet, FQDN, and public host — from the `node.env` file at the repository root, with the OS hostname as a fallback for the FQDN only. The framework assumes no domain and no clustering: a node declares who it is explicitly. This resolution step succeeds the `root_require_node` mechanism of the bash "root" commons framework that apex replaces.

 ## Identity sources {#sources}

 ### node.env

-`node.env` is a plain `KEY=value` file (shell-sourceable) located at the repository root. When parsed, comments and blank lines are ignored, and surrounding single or double quotes around values are stripped.
+`node.env` is a plain `KEY=value` file (shell-sourceable) located at the repository root. When parsed, comments and blank lines are ignored, and surrounding single or double quotes around values are stripped.

-It declares identity explicitly through these keys:
+It declares identity explicitly through these keys:

- `APEX_NODE_FQDN` — the node's real FQDN, used for traefik `Host()` routing. If unset, the engine falls back to the OS hostname (and warns).
- `APEX_NODE_HOST` — the node's public host name, used for the backup `--host` and the observability/notify `instance`. Defaults to `APEX_NODE_FQDN`.
- `APEX_SUBNET` — the node's `/24` for the `direct` network. **Required**; there is no other source for it (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)).
+- `APEX_NODE_FQDN` — the node's real FQDN, used for traefik `Host()` routing. If unset, the engine falls back to the OS hostname (and warns).
+- `APEX_NODE_HOST` — the node's public host name, used for the backup `--host` and the observability/notify `instance`. Defaults to `APEX_NODE_FQDN`.
+- `APEX_SUBNET` — the node's `/24` for the `direct` network. **Required**; there is no other source for it (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)).

 ```ini {filename="node.env"}
 APEX_NODE_FQDN=node1.example.com
 APEX_NODE_HOST=node1.example.com
-APEX_SUBNET=198.18.16.0/24
+APEX_SUBNET=198.18.0.0/24
 ```

-### The OS hostname
+### The OS hostname

-The OS hostname is consulted only as a fallback for `APEX_NODE_FQDN`. When `node.env` does not set `APEX_NODE_FQDN`, the engine uses the hostname and emits a warning. It is never parsed for a node name or any other coordinate.
+The OS hostname is consulted only as a fallback for `APEX_NODE_FQDN`. When `node.env` does not set `APEX_NODE_FQDN`, the engine uses the hostname and emits a warning. It is never parsed for a node name or any other coordinate.

 ## Resolution order {#resolution}

 {{% steps %}}

-### Resolve the FQDN
+### Resolve the FQDN

-`fqdn` is `APEX_NODE_FQDN` from `node.env`, or the OS hostname when that key is unset. If neither yields a value, resolution fails (see [Failure modes](#failures)).
+`fqdn` is `APEX_NODE_FQDN` from `node.env`, or the OS hostname when that key is unset. If neither yields a value, resolution fails (see [Failure modes](#failures)).

-### Resolve the public host
+### Resolve the public host

-`host` is `APEX_NODE_HOST` from `node.env`, or `fqdn` when that key is unset.
+`host` is `APEX_NODE_HOST` from `node.env`, or `fqdn` when that key is unset.

-### Derive the short name
+### Derive the short name

-`name` is the **first label** of `host` (`host.split(".")[0]`) — for example, `node1` for `node1.example.com`. It is used for logs, the `sync/<node>` branch, and messages.
+`name` is the **first label** of `host` (`host.split(".")[0]`) — for example, `node1` for `node1.example.com`. It is used for logs, the `sync/<node>` branch, and messages.

-### Read the subnet
+### Read the subnet

-`subnet` is always read from `APEX_SUBNET` in `node.env`. It is required.
+`subnet` is always read from `APEX_SUBNET` in `node.env`. It is required.

 {{% /steps %}}

-The result is a `Node` record with four fields: `name`, `subnet`, `fqdn`, and `host`.
+The result is a `Node` record with four fields: `name`, `subnet`, `fqdn`, and `host`.

 ## Warnings {#warnings}

-Identity resolution emits exactly one warning; it signals a recoverable inconsistency that should be fixed.
+Identity resolution emits exactly one warning; it signals a recoverable inconsistency that should be fixed.

 | Condition | Warning message |
 |---|---|
-| `APEX_NODE_FQDN` is unset in `node.env` (the hostname is used instead) | `APEX_NODE_FQDN not set in node.env; using hostname '<fqdn>'.` |
+| `APEX_NODE_FQDN` is unset in `node.env` (the hostname is used instead) | `APEX_NODE_FQDN not set in node.env; using hostname '<fqdn>'.` |

 ## Failure modes {#failures}

-Resolution refuses to guess. Two conditions are fatal, and both exit with code `66` — the engine's exit-code convention for missing input:
+Resolution refuses to guess. Two conditions are fatal, and both exit with code `66` — the engine's exit-code convention for missing input:

- **No FQDN at all.** `APEX_NODE_FQDN` is unset in `node.env` *and* the OS hostname is empty. The engine writes `identity: APEX_NODE_FQDN missing from node.env and no hostname` to stderr and exits.
- **No subnet.** `APEX_SUBNET` is absent from `node.env` (including when the file itself is missing). The engine writes `identity: APEX_SUBNET missing from node.env` to stderr and exits.
+- **No FQDN at all.** `APEX_NODE_FQDN` is unset in `node.env` *and* the OS hostname is empty. The engine writes `identity: APEX_NODE_FQDN missing from node.env and no hostname` to stderr and exits.
+- **No subnet.** `APEX_SUBNET` is absent from `node.env` (including when the file itself is missing). The engine writes `identity: APEX_SUBNET missing from node.env` to stderr and exits.

 > [!WARNING]
-> A valid `node.env` carrying `APEX_SUBNET` is required on every node. `APEX_NODE_FQDN` may be omitted only when the OS hostname supplies a usable FQDN.
+> A valid `node.env` carrying `APEX_SUBNET` is required on every node. `APEX_NODE_FQDN` may be omitted only when the OS hostname supplies a usable FQDN.

 ---

@@ -1,53 +1,57 @@
 ---
 title: Security model
-description: Privilege isolation, firewall management, intrusion detection, and secret handling.
+description: Privilege isolation, firewall management, intrusion detection, and secret handling.
 weight: 18
 ---

-apex hardens a [node](/apex/glossary#node) in independent layers: filesystem privilege isolation, a managed host firewall, intrusion detection, container-level containment, and a strict secrets boundary. Each layer is applied by an [action](/apex/glossary#action) and is therefore reproducible and re-runnable.
+apex hardens a [node](/apex/glossary#node) in independent layers: filesystem privilege isolation, a managed host firewall, intrusion detection, container-level containment, and a strict secrets boundary. Each layer is applied by an [action](/apex/glossary#action) and is therefore reproducible and re-runnable.

 ## Privilege isolation {#privilege}

-Every project runs as its own locked `noroot-<project>` system user; shared storage is group-writable with the sticky bit so projects can exchange files without being able to delete each other's. The full mechanism — users, groups, and the ownership matrix — is described in [Concept: Tiered storage](/apex/concepts/tiered-storage).
+Every project runs as its own locked `noroot-<project>` system user; shared storage is group-writable with the sticky bit so projects can exchange files without being able to delete each other's. The full mechanism — users, groups, and the ownership matrix — is described in [Concept: Tiered storage](/apex/concepts/tiered-storage).

 ## Host firewall {#firewall}

-`apex configure/ufw` applies the node's firewall from the `configs/ufw/` pillar in three parts:
+`apex configure/ufw` applies the node's firewall from the `configs/ufw/` pillar in three parts:

- **Host rules** (`configs/ufw/host/host.rules`) — plain `ufw` commands, one per line, applied in order.
- **Kernel-level rule blocks** (`configs/ufw/host/before.rules`, `after.rules`) — injected into `/etc/ufw/before.rules` and `/etc/ufw/after.rules` as managed marker blocks. Injection is **self-healing**: every previous managed block — including blocks left by predecessor tooling — is removed before the fresh block is inserted after ufw's `# End required lines` anchor, and a timestamped `.bak` of the target is kept beside it.
- **Container rules** (`configs/ufw/docker/*.rules`) — applied through `ufw-docker`, which translates them into rules that survive Docker's own iptables manipulation. `configure/base` installs the helper to `~/.local/bin/ufw-docker`.
+- **Host rules** (`configs/ufw/host/host.rules`) — plain `ufw` commands, one per line, applied in order.
+- **Kernel-level rule blocks** (`configs/ufw/host/before.rules`, `after.rules`) — injected into `/etc/ufw/before.rules` and `/etc/ufw/after.rules` as managed marker blocks. Injection is **self-healing**: every previous managed block — including blocks left by predecessor tooling — is removed before the fresh block is inserted after ufw's `# End required lines` anchor, and a timestamped `.bak` of the target is kept beside it.
+- **Container rules** (`configs/ufw/docker/*.rules`) — applied through `ufw-docker`, which translates them into rules that survive Docker's own iptables manipulation. `configure/base` installs the helper to `~/.local/bin/ufw-docker`.

-Missing configuration is an error, not a silent skip: an absent `docker/` or `host/` directory exits `66` when its counterpart exists, and a missing `/etc/ufw` target file aborts the run. The action finishes with a reminder that `ufw` must be restarted to take effect — and that the SSH port must be allowed first.
+Missing configuration is an error, not a silent skip: an absent `docker/` or `host/` directory exits `66` when its counterpart exists, and a missing `/etc/ufw` target file aborts the run. The action finishes with a reminder that `ufw` must be restarted to take effect — and that the SSH port must be allowed first.

 ## Intrusion detection {#crowdsec}

-`apex configure/crowdsec` installs CrowdSec through its official installer when `cscli` is absent, renders everything under `configs/crowdsec/` into `/etc/crowdsec/` (acquisition sources, parsers, bouncer configuration), and installs the `crowdsecurity/linux` and `crowdsecurity/traefik` collections. When the node's configs include a firewall-bouncer configuration, the matching bouncer package is installed as well, closing the loop from detection to blocking.
+`apex configure/crowdsec` installs CrowdSec through its official installer when `cscli` is absent, renders everything under `configs/crowdsec/` into `/etc/crowdsec/` (acquisition sources, parsers, bouncer configuration), and installs the `crowdsecurity/linux` and `crowdsecurity/traefik` collections. When the node's configs include a firewall-bouncer configuration, the matching bouncer package is installed as well, closing the loop from detection to blocking.

 ## Container containment {#containers}

-The [core composition](/apex/glossary#core-composition) encodes container-level hardening:
+The [core composition](/apex/glossary#core-composition) encodes container-level hardening:

- The edge proxy never touches the Docker socket: it discovers backends through a **filtered socket proxy** that exposes read-only container/service state on an isolated network.
- `enclave` and `socket` are `internal: true` networks — no egress, no host port exposure.
- Core services set `no-new-privileges` and run under the project's noroot identity wherever the workload allows; capabilities are granted per service, not globally.
+- The edge proxy never touches the Docker socket: it discovers backends through a **filtered socket proxy** that exposes read-only container/service state on an isolated network.
+- `enclave` and `socket` are `internal: true` networks — no egress, no host port exposure.
+- Core services set `no-new-privileges` and run under the project's noroot identity wherever the workload allows; capabilities are granted per service, not globally.

 ## Observability {#observability}

-Observability is an **outbound push**, not an exposed route. The optional `alloy` core service (Grafana Alloy, one agent per node) collects host metrics (a `node_exporter`-equivalent), container metrics (cadvisor), the systemd journal, and docker container logs, and pushes them to a **central** Prometheus and Loki that live on a designated node — the metrics via `prometheus.remote_write` to `APEX_PROM_PUSH_URL`, the logs via `loki.write` to `APEX_LOKI_PUSH_URL`. Both targets are authenticated with HTTP basic auth using `APEX_OBS_BASIC_AUTH_USER` / `APEX_OBS_BASIC_AUTH_PASS`. Because the push is outbound, Alloy attaches to the `direct` network (which has egress) rather than the `internal` `enclave`; there is no node-local log store and no `/loki` route to protect.
+The optional `alloy` service sends host and container metrics to
+`APEX_PROM_PUSH_URL` and logs to `APEX_LOKI_PUSH_URL`. Configure compatible
+endpoints and HTTP basic-auth credentials through `APEX_OBS_BASIC_AUTH_USER`
+and `APEX_OBS_BASIC_AUTH_PASS`. The service requires outbound connectivity to
+those endpoints; their hosting and access policy are deployment choices.

 ## Secrets boundary {#secrets}

- Secrets live only in per-project `.env` files, which are **symlinks into tier-1 storage** — outside the repository working tree and covered by `.gitignore` (`**/.env`).
- Each node repository documents its expected keys in `SECRETS.md`; the file documents names, never values.
- Committed configuration (`apex.env`) is restricted to non-secret scalars.
- The shared composition marks critical secrets with `?error`, so a missing value fails fast at compose-config time.
- [Capture-up](/apex/glossary#capture-up) commits are safe by construction: the ignored `.env` links and tier data never enter the git index.
+- Secrets live only in per-project `.env` files, which are **symlinks into tier-1 storage** — outside the repository working tree and covered by `.gitignore` (`**/.env`).
+- Each node repository documents its expected keys in `SECRETS.md`; the file documents names, never values.
+- Committed configuration (`apex.env`) is restricted to non-secret scalars.
+- The shared composition marks critical secrets with `?error`, so a missing value fails fast at compose-config time.
+- [Capture-up](/apex/glossary#capture-up) commits are safe by construction: the ignored `.env` links and tier data never enter the git index.

 ---

 **See also:**

- [Concept: Tiered storage and privilege isolation](/apex/concepts/tiered-storage)
- [Concept: Compositions and the shared core](/apex/concepts/compositions)
+- [Concept: Tiered storage and privilege isolation](/apex/concepts/tiered-storage)
+- [Concept: Compositions and the shared core](/apex/concepts/compositions)
 - [Reference: Actions](/apex/reference/actions)
@@ -1,25 +1,25 @@
 ---
-title: Tiered storage and privilege isolation
-description: The @tier link structure, shared storage, and per-project noroot users.
+title: Tiered storage and privilege isolation
+description: The @tier link structure, shared storage, and per-project noroot users.
 weight: 16
 ---

-Service data never lives inside a [node](/apex/glossary#node) repository. It lives in three storage [tiers](/apex/glossary#tier) — separate locations chosen per host — and reaches [compositions](/apex/glossary#compositions) through a standardized symlink structure. Ownership of that data is delegated to per-project system users, so no service container writes as root.
+Service data never lives inside a [node](/apex/glossary#node) repository. It lives in three storage [tiers](/apex/glossary#tier) — separate locations chosen per host — and reaches [compositions](/apex/glossary#compositions) through a standardized symlink structure. Ownership of that data is delegated to per-project system users, so no service container writes as root.

-## The tier link structure {#links}
+## The tier link structure {#links}

-`apex tiers/link <tier1> <tier2> <tier3>` builds two layers of links:
+`apex tiers/link <tier1> <tier2> <tier3>` builds two layers of links:

- **Node-level:** `compositions/@tierN` → the tier storage root. These are what the engine exposes as `APEX_TIER_ROOT1..3`.
- **Per-project:** for every `compositions/<project>/`, the action creates `<tier-root>/<project>/` and links `compositions/<project>/@tierN` → `<tier-root>/<project>`. Inside each tier it also maintains `shared/` with a per-project subdirectory, and a relative `shared` link inside every project's tier directory pointing back at it.
+- **Node-level:** `compositions/@tierN` → the tier storage root. These are what the engine exposes as `APEX_TIER_ROOT1..3`.
+- **Per-project:** for every `compositions/<project>/`, the action creates `<tier-root>/<project>/` and links `compositions/<project>/@tierN` → `<tier-root>/<project>`. Inside each tier it also maintains `shared/` with a per-project subdirectory, and a relative `shared` link inside every project's tier directory pointing back at it.

-Each project additionally gets `compositions/<project>/.env` → `<tier1-root>/<project>/.env` (created empty if missing) — the uncommitted secrets file described in [Concept: Compositions](/apex/concepts/compositions). The `@tierN` links and `.env` files are ignored by git; the repository stays pure source.
+Each project additionally gets `compositions/<project>/.env` → `<tier1-root>/<project>/.env` (created empty if missing) — the uncommitted secrets file described in [Concept: Compositions](/apex/concepts/compositions). The `@tierN` links and `.env` files are ignored by git; the repository stays pure source.

-If a path that should be a symlink exists as a real file or directory, the action warns and asks for confirmation before removing it; declining (including non-interactive EOF) skips that link and continues.
+If a path that should be a symlink exists as a real file or directory, the action warns and asks for confirmation before removing it; declining (including non-interactive EOF) skips that link and continues.

-## Users and groups {#users}
+## Users and groups {#users}

-`apex tiers/useradd` provisions one locked system user per project — `noroot-<project>` (name sanitized, its own primary group) — plus the fleet-wide `noroot-shared` group every project user joins. It then injects the resolved IDs into the project's `.env` between marker comments, replacing any previous block on re-runs:
+`apex tiers/useradd` provisions one locked system user per project — `noroot-<project>` (name sanitized, its own primary group) — plus the fleet-wide `noroot-shared` group every project user joins. It then injects the resolved IDs into the project's `.env` between marker comments, replacing any previous block on re-runs:

 ```ini {filename="compositions/<project>/.env"}
 # START AUTO GENERATED APEX-NOROOT-USERS
@@ -29,42 +29,42 @@ APEX_SHARED_GID=997
 # END AUTO GENERATED APEX-NOROOT-USERS
 ```

-Compositions consume these as `user: "${APEX_UID?error}:${APEX_GID?error}"` and `group_add: ["${APEX_SHARED_GID?error}"]`.
+Compositions consume these as `user: "${APEX_UID?error}:${APEX_GID?error}"` and `group_add: ["${APEX_SHARED_GID?error}"]`.

-## The ownership matrix {#ownership}
+## The ownership matrix {#ownership}

-`apex tiers/chown` enforces ownership across all three tiers. Without arguments it operates on the tier roots (`APEX_TIER_ROOT1..3`); explicit tier paths can override.
+`apex tiers/chown` enforces ownership across all three tiers. Without arguments it operates on the tier roots (`APEX_TIER_ROOT1..3`); explicit tier paths can override.

 | Path | Ownership | Notes |
 |---|---|---|
 | `<tier-root>` | `root:root` | Directory inode only. |
-| `<tier-root>/shared` | `root:root` | Directory inode only — never recursive, so existing project data inside is untouched. |
+| `<tier-root>/shared` | `root:root` | Directory inode only — never recursive, so existing project data inside is untouched. |
 | `<tier-root>/node-infra` | `root:root` | Recursive. |
-| `<tier-root>/<project>` | `uid:gid` | Recursive; IDs read from the project `.env`. |
-| `<tier-root>/shared/<project>` | `uid:shared_gid` | Recursive, plus the sticky bit — collaborators can add files but only delete their own. |
+| `<tier-root>/<project>` | `uid:gid` | Recursive; IDs read from the project `.env`. |
+| `<tier-root>/shared/<project>` | `uid:shared_gid` | Recursive, plus the sticky bit — collaborators can add files but only delete their own. |

-Projects with an incomplete `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` set are skipped with a warning pointing at `tiers/useradd`.
+Projects with an incomplete `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` set are skipped with a warning pointing at `tiers/useradd`.

 ## Engine tier variables {#variables}

-| Variable | Resolves to |
+| Variable | Resolves to |
 |---|---|
-| `APEX_TIER_ROOT1..3` | The tier storage roots (`compositions/@tierN`, fully resolved). |
-| `APEX_TIER1..3` | The core project's data directories inside each tier (`compositions/apex/@tierN`). |
-| `APEX_TIER1..3_SHARED` | The shared area inside the core project's tiers. |
+| `APEX_TIER_ROOT1..3` | The tier storage roots (`compositions/@tierN`, fully resolved). |
+| `APEX_TIER1..3` | The core project's data directories inside each tier (`compositions/apex/@tierN`). |
+| `APEX_TIER1..3_SHARED` | The shared area inside the core project's tiers. |

-The core composition mounts through these exclusively; the backup runner instead mounts the fleet data root `/srv` read-only and resolves each labeled service's container mounts back to their host paths.
+The core composition mounts through these exclusively; the backup runner instead mounts the fleet data root `/srv` read-only and resolves each labeled service's container mounts back to their host paths.

 ## Backups {#backups}

-`apex backup/run <telegram-bot-url>` drives the core `resticontainer` service (profile `manual`, one-shot) end to end. Backup intent is **label-driven**: resticontainer discovers every service carrying `restic.enable=true`, reads its `restic.backup.paths` (and optional `restic.backup.stop` / `restic.hooks.*`), resolves those container paths to host paths, and snapshots their union in a single restic run.
+`apex backup/run <telegram-bot-url>` drives the core `resticontainer` service (profile `manual`, one-shot) end to end. Backup intent is **label-driven**: resticontainer discovers every service carrying `restic.enable=true`, reads its `restic.backup.paths` (and optional `restic.backup.stop` / `restic.hooks.*`), resolves those container paths to host paths, and snapshots their union in a single restic run.

-1. Checks repository reachability with `snapshots`; initializes the repository if needed.
-2. Runs `backup` with `--host <APEX_NODE_HOST>` and `--tag biweekly` — resticontainer runs each labeled service's pre-hook, stops any container flagged `restic.backup.stop`, snapshots the resolved host paths, then restarts and runs post-hooks. The run refuses to report success if no new snapshot lands (a guard against zero labels being discovered).
-3. Applies retention with `forget --prune` (7 daily, 4 weekly, 12 monthly).
-4. Sends a Telegram status either way; a success whose notification cannot be delivered still exits `1` so schedulers notice.
+1. Checks repository reachability with `snapshots`; initializes the repository if needed.
+2. Runs `backup` with `--host <APEX_NODE_HOST>` and `--tag biweekly` — resticontainer runs each labeled service's pre-hook, stops any container flagged `restic.backup.stop`, snapshots the resolved host paths, then restarts and runs post-hooks. The run refuses to report success if no new snapshot lands (a guard against zero labels being discovered).
+3. Applies retention with `forget --prune` (7 daily, 4 weekly, 12 monthly).
+4. Sends a Telegram status either way; a success whose notification cannot be delivered still exits `1` so schedulers notice.

-The repository location and credentials come entirely from `APEX_RESTIC_*` configuration (see [Reference: Environment variables](/apex/reference/environment)). Which data is captured is decided per service by its `restic.*` labels — for example the core services back up only their configuration (traefik dynamic rules, xray/adguard config), leaving reproducible tier-3 data such as caches and logs out of the set.
+The repository location and credentials come entirely from `APEX_RESTIC_*` configuration (see [Reference: Environment variables](/apex/reference/environment)). Which data is captured is decided per service by its `restic.*` labels — for example the core services back up only their configuration (traefik dynamic rules, xray/adguard config), leaving reproducible tier-3 data such as caches and logs out of the set.

 ---

@@ -72,4 +72,4 @@ The repository location and credentials come entirely from `APEX_RESTIC_*` confi

 - [Concept: Security model](/apex/concepts/security-model)
 - [Reference: Actions](/apex/reference/actions)
- [Guide: Add a service composition](/apex/guides/service-composition)
+- [Guide: Add a service composition](/apex/guides/service-composition)
@@ -1,24 +1,24 @@
 ---
-title: Getting started with an apex node
-description: Bootstrap a node repository and bring a host under apex management.
+title: Getting started with an apex node
+description: Bootstrap a node repository and bring a host under apex management.
 weight: 5
 ---

-This quick start takes a fresh host from a cloned [node](/apex/glossary#node) repository to a running service stack. It assumes the node repository already exists — to build one from scratch, see [Guide: Build a node repository](/apex/guides/node-repository).
+This quick start takes a fresh host from a cloned [node](/apex/glossary#node) repository to a running service stack. It assumes the node repository already exists — to build one from scratch, see [Guide: Build a node repository](/apex/guides/node-repository).

 ## Prerequisites

- A Debian-based host. Any FQDN works — [node identity](/apex/glossary#node-identity) is declared explicitly in `node.env` (`APEX_NODE_FQDN`, `APEX_NODE_HOST`, `APEX_SUBNET`), not parsed from a required hostname shape.
- `git` and Python 3 — the [engine](/apex/glossary#engine) uses the standard library only; `pip` is never required.
- Docker with Compose v2.20 or newer (the [core composition](/apex/glossary#core-composition) is consumed through the `include:` directive).
- A sudo-capable login user.
- Three storage locations for the [tiers](/apex/glossary#tier) (for example, three mount points).
+- A Debian-based host. Any FQDN works — [node identity](/apex/glossary#node-identity) is declared explicitly in `node.env` (`APEX_NODE_FQDN`, `APEX_NODE_HOST`, `APEX_SUBNET`), not parsed from a required hostname shape.
+- `git` and Python 3 — the [engine](/apex/glossary#engine) uses the standard library only; `pip` is never required.
+- Docker with Compose v2.20 or newer (the [core composition](/apex/glossary#core-composition) is consumed through the `include:` directive).
+- A sudo-capable login user.
+- Three storage locations for the [tiers](/apex/glossary#tier) (for example, three mount points).

 ## Bootstrap

 {{% steps %}}

-### Clone the node repository
+### Clone the node repository

 ```bash
 git clone --recurse-submodules git@github.com:<owner>/<node-repo>.git
@@ -27,7 +27,7 @@ cd <node-repo>
 source ~/.bashrc
 ```

-`init.sh` initializes the `commons/` submodule, points `core.hooksPath` at `commons/githooks`, marks the checkout `safe.directory`, and prepends `commons/` to `PATH` — the launcher is `commons/apex`.
+`init.sh` initializes the `commons/` submodule, points `core.hooksPath` at `commons/githooks`, marks the checkout `safe.directory`, and prepends `commons/` to `PATH` — the launcher is `commons/apex`.

 ### Verify action discovery

@@ -35,15 +35,15 @@ source ~/.bashrc
 apex --help
 ```

-The listing shows every [commons](/apex/glossary#commons) action plus any node-local [proprietaries](/apex/glossary#proprietaries) tagged `(local)`. When `node.env` has no `APEX_NODE_FQDN`, the engine warns and falls back to the OS hostname — harmless on a workstation, but set `APEX_NODE_FQDN` explicitly on the node itself. (`APEX_SUBNET` is required: if it is missing the engine exits `66`.)
+The listing shows every [commons](/apex/glossary#commons) action plus any node-local [proprietaries](/apex/glossary#proprietaries) tagged `(local)`. When `node.env` has no `APEX_NODE_FQDN`, the engine warns and falls back to the OS hostname — harmless on a workstation, but set `APEX_NODE_FQDN` explicitly on the node itself. (`APEX_SUBNET` is required: if it is missing the engine exits `66`.)

-### Link the storage tiers
+### Link the storage tiers

 ```bash
 apex tiers/link <tier1-path> <tier2-path> <tier3-path>
 ```

-Creates the node-level `compositions/@tierN` links, the per-project tier directories and `@tierN` links, `shared/` areas, and each project's `.env` symlink into tier 1. Success ends with `@tier setup completed.`
+Creates the node-level `compositions/@tierN` links, the per-project tier directories and `@tierN` links, `shared/` areas, and each project's `.env` symlink into tier 1. Success ends with `@tier setup completed.`

 ### Provision project users

@@ -52,11 +52,11 @@ apex tiers/useradd
 apex tiers/chown
 ```

-`tiers/useradd` creates one `noroot-<project>` system user per composition plus the `noroot-shared` group, and injects `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` into each project `.env`. `tiers/chown` then applies the ownership matrix (see [Concept: Tiered storage](/apex/concepts/tiered-storage)) and ends with `Permissions applied.`
+`tiers/useradd` creates one `noroot-<project>` system user per composition plus the `noroot-shared` group, and injects `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` into each project `.env`. `tiers/chown` then applies the ownership matrix (see [Concept: Tiered storage](/apex/concepts/tiered-storage)) and ends with `Permissions applied.`

-### Fill the core secrets
+### Fill the core secrets

-Edit `compositions/apex/.env` (a symlink into tier-1 storage, never committed) with the keys documented in the node repository's `SECRETS.md`:
+Edit `compositions/apex/.env` (a symlink into tier-1 storage, never committed) with the keys documented in the node repository's `SECRETS.md`:

 ```ini {filename="compositions/apex/.env"}
 APEX_RESTIC_PASSWORD=...
@@ -67,36 +67,36 @@ APEX_TRAEFIK_ACME_EMAIL=...
 APEX_OBS_BASIC_AUTH_PASS=...   # only when the alloy observability profile is enabled
 ```

-`APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` are already present — `tiers/useradd` maintains them between marker comments. Non-secret scalars (`APEX_RESTIC_REPOSITORY`, the push URLs, `COMPOSE_PROFILES`, `TZ`, …) live in the committed `compositions/apex/apex.env` instead — see [Guide: Build a node repository](/apex/guides/node-repository).
+`APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` are already present — `tiers/useradd` maintains them between marker comments. Non-secret scalars (`APEX_RESTIC_REPOSITORY`, the push URLs, `COMPOSE_PROFILES`, `TZ`, …) live in the committed `compositions/apex/apex.env` instead — see [Guide: Build a node repository](/apex/guides/node-repository).

-### Configure the host
+### Configure the host

 ```bash
 apex configure
 ```

-Runs every `configure/*` action in fixed order: `base`, `ufw`, `crowdsec`, `cron`, `systemd`, `routing`. Each step is also individually invocable; several accept `--dry-run`. See [Guide: Operate a node](/apex/guides/host-operations).
+Runs every `configure/*` action in fixed order: `base`, `ufw`, `crowdsec`, `cron`, `systemd`, `routing`. Each step is also individually invocable; several accept `--dry-run`. See [Guide: Operate a node](/apex/guides/host-operations).

-### Bring the stack up
+### Bring the stack up

 ```bash
 apex compose up
 ```

-The core composition comes up first (it owns the networks), then every service composition in alphabetical order.
+The core composition comes up first (it owns the networks), then every service composition in alphabetical order.

 {{% /steps %}}

 ## Validation

- `apex --help` lists actions without warnings on the live host.
- `docker ps` shows the core containers (`apex-traefik`, `apex-socket-proxy`, plus any profile-enabled services) and each project's anchor.
+- `apex --help` lists actions without warnings on the live host.
+- `docker ps` shows the core containers (`apex-traefik`, `apex-socket-proxy`, plus any profile-enabled services) and each project's anchor.
 - `apex utils/lint-docker-compose` reports `Anchor IP validation passed.`

 ---

 **See also:**

- [Guide: Build a node repository](/apex/guides/node-repository)
+- [Guide: Build a node repository](/apex/guides/node-repository)
 - [Concept: Framework architecture](/apex/concepts/architecture)
 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
@@ -1,66 +1,66 @@
 ---
 title: Glossary
-description: Terminology used within the apex fleet operations framework.
+description: Terminology used within the apex fleet operations framework.
 weight: 100
 ---

-Terminology used within the apex fleet operations framework.
+Terminology used within the apex fleet operations framework.

 ## Action {#action}

-**Action** - An atomic automation task: one Python module exposing `METADATA = Meta(...)` and `run(ctx, args)`, dispatched by its file path as `apex <group>/<action>`.
+**Action** - An atomic automation task: one Python module exposing `METADATA = Meta(...)` and `run(ctx, args)`, dispatched by its file path as `apex <group>/<action>`.

 ## Anchor IP {#anchor-ip}

-**Anchor IP** - The static `ipv4_address` a project's main container holds on the `direct` network. Anchors make service addresses predictable and are validated by the compose lint.
+**Anchor IP** - The static `ipv4_address` a project's main container holds on the `direct` network. Anchors make service addresses predictable and are validated by the compose lint.

 ## Capture-up {#capture-up}

-**Capture-up** - The flow that records a host's live state back into its repository: a scheduled commit to the `sync/<node>` branch, rebased onto `main` and folded back by CI. Drift becomes a diff instead of divergence.
+**Capture-up** — Recording a host's working state in a `sync/<node>` branch through `apex sync/repository`. The repository's own policy determines review and integration.

 ## Commons {#commons}

-**Commons** - The shared repository (`apex.ermnvldmr.com`) holding the engine, the shared actions, and the core composition. Every node consumes it as the pinned `commons/` git submodule.
+**Commons** - The shared repository (`apex.ermnvldmr.com`) holding the engine, the shared actions, and the core composition. Every node consumes it as the pinned `commons/` git submodule.

 ## Compositions {#compositions}

-**Compositions** - The node-repository pillar declaring the node's runtime: one docker-compose project per service plus the core wrapper and the addressing ledger.
+**Compositions** - The node-repository pillar declaring the node's runtime: one docker-compose project per service plus the core wrapper and the addressing ledger.

 ## Configs {#configs}

-**Configs** - The node-repository pillar holding host configuration sources (`ufw/`, `cron/`, `systemd/`, `crowdsec/`), rendered through the template layer by the `configure/*` actions.
+**Configs** - The node-repository pillar holding host configuration sources (`ufw/`, `cron/`, `systemd/`, `crowdsec/`), rendered through the template layer by the `configure/*` actions.

 ## Core composition {#core-composition}

-**Core composition** - The shared, `${APEX_*}`-parameterized docker-compose project defining the fleet's common services (edge proxy, socket proxy, and the opt-in profile services). Defined once in the commons, included per node.
+**Core composition** - The shared, `${APEX_*}`-parameterized docker-compose project defining the fleet's common services (edge proxy, socket proxy, and the opt-in profile services). Defined once in the commons, included per node.

 ## Enclave {#enclave}

-**Enclave** - The fleet's private address space, `198.18.0.0/16`, and by extension the internal reverse-proxy backend network named `enclave` in the core composition.
+**Enclave** - The fleet's private address space, `198.18.0.0/16`, and by extension the internal reverse-proxy backend network named `enclave` in the core composition.

 ## Engine {#engine}

-**Engine** - The stdlib-Python runtime under `commons/engine/`: the launcher, identity resolution, the overlay, the execution context, and the `ctx.*` helper library.
+**Engine** - The stdlib-Python runtime under `commons/engine/`: the launcher, identity resolution, the overlay, the execution context, and the `ctx.*` helper library.

 ## Node {#node}

-**Node** - A host managed by the framework, defined by exactly one node repository and identified by the FQDN it declares in `node.env` (for example, `node1.example.com`).
+**Node** - A host managed by the framework, defined by exactly one node repository and identified by the FQDN it declares in `node.env` (for example, `node1.example.com`).

 ## Node identity {#node-identity}

-**Node identity** - The resolved record of who a node is — name, subnet, FQDN, public host — derived from `node.env`, with the OS hostname as a fallback for the FQDN.
+**Node identity** - The resolved record of who a node is — name, subnet, FQDN, public host — derived from `node.env`, with the OS hostname as a fallback for the FQDN.

 ## Overlay {#overlay}

-**Overlay** - The resolution rule that lets a node's proprietaries add, override, wrap, or disable commons actions: `proprietaries/actions/` is consulted before `commons/actions/`.
+**Overlay** - The resolution rule that lets a node's proprietaries add, override, wrap, or disable commons actions: `proprietaries/actions/` is consulted before `commons/actions/`.

 ## Proprietaries {#proprietaries}

-**Proprietaries** - The node-repository pillar for node-local code: actions, libraries, and tool sources that apply to exactly one node and therefore do not belong in the commons.
+**Proprietaries** - The node-repository pillar for node-local code: actions, libraries, and tool sources that apply to exactly one node and therefore do not belong in the commons.

 ## Tier {#tier}

-**Tier** - One of the three standardized storage classes a node mounts (configuration, valuable data, reproducible data), reached from compositions through the `@tierN` symlink structure.
+**Tier** - One of the three standardized storage classes a node mounts (configuration, valuable data, reproducible data), reached from compositions through the `@tierN` symlink structure.

 ---

@@ -1,10 +1,10 @@
 ---
 title: Guides
-description: Task-oriented guides for building node repositories, actions, and compositions.
+description: Task-oriented guides for building node repositories, actions, and compositions.
 weight: 20
 ---

-Task-oriented guides for day-to-day work with apex. Each guide solves one recurring problem: assembling a [node](/apex/glossary#node) repository, developing [actions](/apex/glossary#action) for the [engine](/apex/glossary#engine), defining service [compositions](/apex/glossary#compositions), and operating the underlying host.
+Task-oriented guides for day-to-day work with apex. Each guide solves one recurring problem: assembling a [node](/apex/glossary#node) repository, developing [actions](/apex/glossary#action) for the [engine](/apex/glossary#engine), defining service [compositions](/apex/glossary#compositions), and operating the underlying host.

 ## Available guides {#available-guides}

@@ -1,12 +1,12 @@
 ---
 title: Develop actions
-description: Write, override, and test engine actions in commons or proprietaries.
+description: Write, override, and test engine actions in commons or proprietaries.
 weight: 22
 ---

-**Context:** all automation ships as [actions](/apex/glossary#action) — one Python module each, dispatched by path. Shared behavior belongs in [commons](/apex/glossary#commons) `actions/`; anything node-specific belongs in that node's `proprietaries/actions/`. Both use the identical contract, and the launcher puts both trees on `sys.path`, so a proprietary action imports `engine.*` exactly like a commons one.
+**Context:** all automation ships as [actions](/apex/glossary#action) — one Python module each, dispatched by path. Shared behavior belongs in [commons](/apex/glossary#commons) `actions/`; anything node-specific belongs in that node's `proprietaries/actions/`. Both use the identical contract, and the launcher puts both trees on `sys.path`, so a proprietary action imports `engine.*` exactly like a commons one.

-## A minimal action {#minimal}
+## A minimal action {#minimal}

 ```python {filename="proprietaries/actions/utils/example.py"}
 """One-line module docstring describing the action."""
@@ -29,14 +29,14 @@ def run(ctx, args):
    ctx.log.success("Config deployed.")
 ```

-The file's path is its name: the module above dispatches as `apex utils/example`. Return `0`/`None` for success, an integer for a specific exit code, or raise `SystemExit(code)`; the [exit-code convention](/apex/concepts/actions-and-overlay#exit-codes) is `64` usage, `65` data error, `66` missing input, `1` general.
+The file's path is its name: the module above dispatches as `apex utils/example`. Return `0`/`None` for success, an integer for a specific exit code, or raise `SystemExit(code)`; the [exit-code convention](/apex/concepts/actions-and-overlay#exit-codes) is `64` usage, `65` data error, `66` missing input, `1` general.

-## Conventions for unattended actions {#unattended}
+## Conventions for unattended actions {#unattended}

-Actions that run from cron follow two rules so failures page instead of vanishing:
+Actions that run from cron follow two rules so failures page instead of vanishing:

- **Wrap the body** in `try/except Exception` and send `ctx.notify.error(...)` before re-raising as `SystemExit(1)` — the Python equivalent of a shell ERR trap.
- **Gate the exit code on the final notification**: `ctx.notify.*` returns `False` on delivery failure; a completed run whose status message never arrived should still exit `1`.
+- **Wrap the body** in `try/except Exception` and send `ctx.notify.error(...)` before re-raising as `SystemExit(1)` — the Python equivalent of a shell ERR trap.
+- **Gate the exit code on the final notification**: `ctx.notify.*` returns `False` on delivery failure; a completed run whose status message never arrived should still exit `1`.

 ```python
    try:
@@ -54,7 +54,7 @@ Actions that run from cron follow two rules so failures page instead of vanishin

 ## Override, wrap, disable {#override}

-A proprietary file at the same relative path as a commons action shadows it completely. Inside the shadowing module, `ctx.commons.run(args)` invokes the shadowed implementation — the wrap pattern:
+A proprietary file at the same relative path as a commons action shadows it completely. Inside the shadowing module, `ctx.commons.run(args)` invokes the shadowed implementation — the wrap pattern:

 ```python {filename="proprietaries/actions/sync/packages.py"}
 from engine.descriptor import Meta, Arg
@@ -67,24 +67,24 @@ def run(ctx, args):
    return ctx.commons.run(args)          # delegate to the commons implementation
 ```

-To retire an action on one node, assign `DISABLED = "reason"` at module top level: dispatch refuses it (exit `1`) and the listing shows `[DISABLED: reason]`.
+To retire an action on one node, assign `DISABLED = "reason"` at module top level: dispatch refuses it (exit `1`) and the listing shows `[DISABLED: reason]`.

 ## Testing {#testing}

-The commons test suite is stdlib `unittest`:
+The commons test suite is stdlib `unittest`:

 ```bash
 ./tests/run.sh          # python3 -m unittest discover -s tests -p 'test_*.py' -v
 ```

-Engine changes must keep the suite green. A cheap smoke gate for any action — commons or proprietary — is its parser: `apex <name> --help` must exit `0`, which proves the module parses, its `METADATA` is well-formed, and discovery sees it.
+Engine changes must keep the suite green. A cheap smoke gate for any action — commons or proprietary — is its parser: `apex <name> --help` must exit `0`, which proves the module parses, its `METADATA` is well-formed, and discovery sees it.

-The commons pre-commit hook (wired by `init.sh` via `core.hooksPath`) runs `apex utils/lint-docker-compose --hook` against staged compose files, so composition changes are linted at commit time.
+The commons pre-commit hook (wired by `init.sh` via `core.hooksPath`) runs `apex utils/lint-docker-compose --hook` against staged compose files, so composition changes are linted at commit time.

 ---

 **See also:**

- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
- [Concept: The execution context](/apex/concepts/execution-context)
+- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
+- [Concept: The execution context](/apex/concepts/execution-context)
 - [Reference: Engine API](/apex/reference/engine-api)
@@ -1,25 +1,26 @@
 ---
-title: Operate a node
-description: "Day-2 operations: configure, compose, backups, and repository sync."
+title: Operate a node
+description: "Day-2 operations: configure, compose, backups, and repository sync."
 weight: 24
 ---

-**Context:** once bootstrapped, a [node](/apex/glossary#node) is operated entirely through the [engine](/apex/glossary#engine). This guide covers the recurring operations and what each actually does on the host.
+**Context:** once bootstrapped, a [node](/apex/glossary#node) is operated entirely through the [engine](/apex/glossary#engine). This guide covers the recurring operations and what each actually does on the host.

 ## Host configuration {#configure}

-`apex configure` runs the full configuration suite in a fixed order; each step is individually invocable when only one layer changed:
+`apex configure` runs the full configuration suite in a fixed order; each step is individually invocable when only one layer changed:

 | Step | Effect |
 |---|---|
-| `configure/base` | Ensures a Debian base: package index update, essential packages (`curl`, `wget`, `git`, `rsyslog`), rsyslog running, `ufw` installed, and the `ufw-docker` helper at `~/.local/bin/ufw-docker`. |
-| `configure/ufw` | Applies host rules, injects the managed kernel-rule blocks, applies container rules via `ufw-docker`. Supports `--dry-run`. |
-| `configure/crowdsec` | Installs CrowdSec if absent, deploys `configs/crowdsec/` to `/etc/crowdsec/`, installs collections, and the firewall bouncer when configured. Supports `--dry-run`. |
-| `configure/cron` | Renders `configs/cron/crontab` through the template layer and installs it — with preview, empty-render refusal (exit `65`), and rollback on a failed install. Supports `--dry-run`. |
-| `configure/systemd` | Renders the top-level files of `configs/systemd/` into `/etc/systemd/system/`, then daemon-reloads and enables each `.service`. Supports `--dry-run`. |
-| `configure/routing` | Enables IP forwarding and installs the fwmark policy-routing rule and table used by the enclave edge; idempotent. |
+| `configure/base` | Installs missing Debian packages after checking that APT's simulation contains no upgrades or removals, ensures rsyslog is running, and verifies the pinned `/usr/local/bin/ufw-docker` before privileged execution. Avoid concurrent package operations. |
+| `configure/timezone` | Applies `configs/timezone` when present and refreshes active cron after a timezone change. Supports `--dry-run`. |
+| `configure/ufw` | Applies host rules, injects the managed kernel-rule blocks, applies container rules via `ufw-docker`. Supports `--dry-run`. |
+| `configure/crowdsec` | Installs CrowdSec if absent, deploys `configs/crowdsec/` to `/etc/crowdsec/`, installs collections, and the firewall bouncer when configured. Supports `--dry-run`. |
+| `configure/cron` | Renders `configs/cron/crontab` through the template layer and installs it — with preview, empty-render refusal (exit `65`), and rollback on a failed install. Supports `--dry-run`. |
+| `configure/systemd` | Renders the top-level files of `configs/systemd/` into `/etc/systemd/system/`, then daemon-reloads and enables each `.service`. Supports `--dry-run`. |
+| `configure/routing` | Enables IP forwarding and installs the fwmark policy-routing rule and table used by the enclave edge; idempotent. |

-After `configure/ufw`, restart `ufw` deliberately (`sudo systemctl restart ufw`) — the action reminds you, and warns that the SSH port must already be allowed.
+After `configure/ufw`, restart `ufw` deliberately (`sudo systemctl restart ufw`) — the action reminds you, and warns that the SSH port must already be allowed.

 ## Composition lifecycle {#compose}

@@ -27,10 +28,39 @@ After `configure/ufw`, restart `ufw` deliberately (`sudo systemctl restart ufw`)
 apex compose up            # core first, then services alphabetically
 apex compose down          # reverse order
 apex compose restart
-apex compose up --dry-run  # print the commands only
+apex compose --dry-run up  # print the commands only
+apex compose -p apex restart traefik
+apex compose -p app up -d
 ```

-Extra arguments pass through to `docker compose` per project. Each project's `.env` and `apex.env` are supplied automatically when present.
+Put wrapper options (`-p` and `--dry-run`) before the action. Extra arguments pass
+through to Docker Compose for the selected project. Each project's `.env` and
+`apex.env` are supplied automatically when present. Positional targeting remains
+available as `apex compose restart apex traefik` or `apex compose up -d apex`;
+prefer `-p` when arguments could also name a composition.
+
+Replace `app` with a composition defined in your repository. When a mount or
+other container definition changes, use targeted `up -d` to recreate it:
+`restart` retains the existing definition.
+
+### Direct core Compose commands
+
+```bash
+apex env --sync
+cd compositions/apex
+docker compose config --quiet
+docker compose restart traefik
+```
+
+Sync preserves existing secret and UID/GID text in `.env` and its tier-storage
+symlink. A managed block loads committed `apex.env` settings, including profiles,
+then synthesized node/path values. Writes use mode `0600`. Resync after changing
+those settings or paths; do not hand-edit the managed block. Docker's shell
+environment still overrides file values.
+
+`eval "$(apex env)"`, `apex env --dotenv`, and `apex env --write generated.env`
+export or save generated APEX values only. They do not load composition secrets
+or replace the full `--sync` bridge. Output modes are mutually exclusive.

 ## Backups {#backups}

@@ -38,7 +68,7 @@ Extra arguments pass through to `docker compose` per project. Each project's `.e
 apex backup/run "$(cat <path-to-telegram-url-file>)"
 ```

-Runs [resticontainer](https://github.com/deytenit/resticontainer) one-shot under the `manual` compose profile: init-if-needed, then a label-driven backup that discovers each service's intent from its `restic.*` compose labels (`restic.enable`, `restic.backup.paths`, …), snapshots the union of the resolved host paths in a single restic run (`--host` = `APEX_NODE_HOST`, `--compression max`), applies retention (`forget --prune`), and notifies. It refuses to report success if no `restic.*`-labelled service produced a new snapshot. The full flow is described in [Concept: Tiered storage](/apex/concepts/tiered-storage#backups). Schedule it from `configs/cron/crontab` so the run and its Telegram outcome are unattended.
+Runs [resticontainer](https://github.com/deytenit/resticontainer) one-shot under the `manual` compose profile: init-if-needed, then a label-driven backup that discovers each service's intent from its `restic.*` compose labels (`restic.enable`, `restic.backup.paths`, …), snapshots the union of the resolved host paths in a single restic run (`--host` = `APEX_NODE_HOST`, `--compression max`), applies retention (`forget --prune`), and notifies. It refuses to report success if no `restic.*`-labelled service produced a new snapshot. The full flow is described in [Concept: Tiered storage](/apex/concepts/tiered-storage#backups). Schedule it from `configs/cron/crontab` so the run and its Telegram outcome are unattended.

 ## Repository sync (capture-up) {#sync}

@@ -46,7 +76,7 @@ Runs [resticontainer](https://github.com/deytenit/resticontainer) one-shot under
 apex sync/repository <telegram-bot-url>
 ```

-Commits the live checkout to `sync/<node>`, rebases onto `origin/main`, and force-pushes with lease; CI folds the branch back into `main`. The action refuses to run — with a paged error — when the commons submodule is dirty or the `compositions/` tree is missing, and aborts cleanly on a rebase conflict (manual intervention required). See [Concept: Framework architecture](/apex/concepts/architecture#capture-up) for the model.
+Commits the live checkout to `sync/<node>`, rebases onto `origin/main`, and force-pushes with lease. The action refuses to run — with a paged error — when the commons submodule is dirty or the `compositions/` tree is missing, and aborts cleanly on a rebase conflict (manual intervention required). See [Concept: Framework architecture](/apex/concepts/architecture#capture-up) for the model.

 ## Update awareness {#updates}

@@ -54,7 +84,7 @@ Commits the live checkout to `sync/<node>`, rebases onto `origin/main`, and forc
 apex sync/packages <telegram-bot-url>
 ```

-Reports pending apt upgrades and out-of-date container images (local digests compared against the registry via `skopeo`) in a single Telegram digest. It changes nothing on the host — it is a scheduled awareness check.
+Reports pending apt upgrades and out-of-date container images (local digests compared against the registry via `skopeo`) in a single Telegram digest. It changes nothing on the host — it is a scheduled awareness check.

 ## Certificate extraction {#certs}

@@ -62,12 +92,12 @@ Reports pending apt upgrades and out-of-date container images (local digests com
 apex utils/extract-traefik-certs <acme.json> <dest-dir> [telegram-bot-url]
 ```

-Dumps the edge proxy's ACME store into per-domain `fullchain.pem`/`privkey.pem` pairs (via a containerized dumper), restricts key permissions to `600`, and re-owns the output to the invoking user — for services that need raw PEM material instead of proxy-terminated TLS.
+Dumps the edge proxy's ACME store into per-domain `fullchain.pem`/`privkey.pem` pairs (via a containerized dumper), restricts key permissions to `600`, and re-owns the output to the invoking user — for services that need raw PEM material instead of proxy-terminated TLS.

 ---

 **See also:**

- [Getting started with an apex node](/apex/getting-started)
+- [Getting started with an apex node](/apex/getting-started)
 - [Reference: Actions](/apex/reference/actions)
 - [Docs: Troubleshooting](/apex/troubleshooting)
@@ -1,14 +1,14 @@
 ---
-title: Build a node repository
-description: Assemble the four pillars, pin commons, and wire the capture-up flow.
+title: Build a node repository
+description: Assemble the four pillars, pin commons, and wire the capture-up flow.
 weight: 21
 ---

-**Context:** every [node](/apex/glossary#node) gets exactly one repository. Pick any repository name — [identity](/apex/glossary#node-identity) is declared explicitly in `node.env`, so the repo name is a convention, not a functional input. This guide assembles one from nothing.
+**Context:** every [node](/apex/glossary#node) gets exactly one repository. Pick any repository name — [identity](/apex/glossary#node-identity) is declared explicitly in `node.env`, so the repo name is a convention, not a functional input. This guide assembles one from nothing.

 {{% steps %}}

-### Initialize the repository and pin commons
+### Initialize the repository and pin commons

 ```bash
 git init <node-repo> && cd <node-repo>
@@ -18,21 +18,21 @@ git add .gitmodules commons
 mkdir -p proprietaries/actions proprietaries/lib configs compositions/apex .github/workflows
 ```

-The gitlink pins the exact engine version the node runs. Upgrading later means checking out a newer tag inside `commons/` and committing the moved pointer.
+The gitlink pins the exact engine version the node runs. Upgrading later means checking out a newer tag inside `commons/` and committing the moved pointer.

 ### Declare identity

 ```ini {filename="node.env"}
 APEX_NODE_FQDN=node1.example.com
 APEX_NODE_HOST=node1.example.com
-APEX_SUBNET=198.18.16.0/24
+APEX_SUBNET=198.18.0.0/24
 APEX_GIT_AUTHOR_NAME=apex [bot]
 APEX_GIT_AUTHOR_EMAIL=apex@localhost
 ```

-`node.env` declares the node's identity explicitly — no domain shape is assumed. `APEX_NODE_FQDN` is the real FQDN used for traefik `Host()` routing (fallback: the OS hostname, with a warning). `APEX_NODE_HOST` is the public host name used for the backup `--host` and the observability/notify `instance` label (default: `APEX_NODE_FQDN`); the short node `name` is its first label. `APEX_SUBNET` is the node's /24 for the `direct` network and is **required** — a missing value exits `66` (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)). `APEX_GIT_AUTHOR_NAME`/`APEX_GIT_AUTHOR_EMAIL` are the capture-up bot identity (generic defaults if unset).
+`node.env` declares the node's identity explicitly — no domain shape is assumed. `APEX_NODE_FQDN` is the real FQDN used for traefik `Host()` routing (fallback: the OS hostname, with a warning). `APEX_NODE_HOST` is the public host name used for the backup `--host` and the observability/notify `instance` label (default: `APEX_NODE_FQDN`); the short node `name` is its first label. `APEX_SUBNET` is the node's /24 for the `direct` network and is **required** — a missing value exits `66` (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)). `APEX_GIT_AUTHOR_NAME`/`APEX_GIT_AUTHOR_EMAIL` are the capture-up bot identity (generic defaults if unset).

-### Write the core wrapper and its env files
+### Write the core wrapper and its env files

 ```yaml {filename="compositions/apex/docker-compose.yml"}
 name: apex
@@ -41,7 +41,7 @@ include:
 ```

 ```ini {filename="compositions/apex/apex.env"}
-APEX_TRAEFIK_DIRECT_IP=198.18.16.10
+APEX_TRAEFIK_DIRECT_IP=198.18.0.10
 APEX_RESTIC_REPOSITORY=s3:<endpoint>/<bucket>/<node>
 COMPOSE_PROFILES=adguard,xray,alloy
 # observability push targets (only when the alloy profile is enabled)
@@ -55,9 +55,9 @@ APEX_OBS_BASIC_AUTH_USER=<node-user>
 # APEX_RESTIC_AWS_ENDPOINT=                # e.g. an S3-compatible endpoint URL
 ```

-`apex.env` holds committed non-secret scalars only. `COMPOSE_PROFILES` selects which optional core services this node runs — `adguard`, `xray`, `alloy` (the observability push agent), and `manual` (one-shot backups) — and may be empty. Document the uncommitted secret keys in `compositions/apex/SECRETS.md` so an operator on a fresh host knows what to fill in `.env` (`APEX_RESTIC_PASSWORD`, the S3 access keys, `APEX_TRAEFIK_CF_DNS_API_TOKEN`, `APEX_TRAEFIK_ACME_EMAIL`, and `APEX_OBS_BASIC_AUTH_PASS` when observability is on).
+`apex.env` holds committed non-secret scalars only. `COMPOSE_PROFILES` selects which optional core services this node runs — `adguard`, `xray`, `alloy` (the observability push agent), and `manual` (one-shot backups) — and may be empty. Document the uncommitted secret keys in `compositions/apex/SECRETS.md` so an operator on a fresh host knows what to fill in `.env` (`APEX_RESTIC_PASSWORD`, the S3 access keys, `APEX_TRAEFIK_CF_DNS_API_TOKEN`, `APEX_TRAEFIK_ACME_EMAIL`, and `APEX_OBS_BASIC_AUTH_PASS` when observability is on).

-### Ignore what never belongs in git
+### Ignore what never belongs in git

 ```gitignore {filename=".gitignore"}
 **/@tier1
@@ -69,17 +69,20 @@ __pycache__/
 *.pyc
 ```

-### Add the bootstrap script
+### Add the bootstrap script

-`init.sh` prepares a fresh clone on the host: `git submodule update --init --recursive`, `git config core.hooksPath commons/githooks`, `git config --global --add safe.directory <repo>`, and prepend `<repo>/commons` to `PATH` in the login shell so `apex` resolves. Mark it executable.
+`init.sh` prepares a fresh clone on the host: `git submodule update --init --recursive`, `git config core.hooksPath commons/githooks`, `git config --global --add safe.directory <repo>`, and prepend `<repo>/commons` to `PATH` in the login shell so `apex` resolves. Mark it executable.

-### Start the addressing ledger
+### Start the addressing ledger

-Create `compositions/ADDRESSING.md` with the node's subnet (`APEX_SUBNET`) and the reserved ranges (`.10`–`.19` core, `.20`+ services). Every [anchor IP](/apex/glossary#anchor-ip) allocated later is recorded here.
+Create `compositions/ADDRESSING.md` with the node's subnet (`APEX_SUBNET`) and the reserved ranges (`.10`–`.19` core, `.20`+ services). Every [anchor IP](/apex/glossary#anchor-ip) allocated later is recorded here.

-### Wire capture-up CI
+### Choose a sync review policy

-Add a scheduled workflow that merges `sync/<node>` into `main` when the branch exists, committing under a bot identity. Check out **without** submodules — the merge only moves the commons pointer, and an SSH submodule URL is not fetchable with the default CI token. See [Concept: Framework architecture](/apex/concepts/architecture) for the full [capture-up](/apex/glossary#capture-up) loop.
+Decide how to review and integrate the `sync/<node>` branch produced by
+`apex sync/repository`. If you automate integration, configure repository
+permissions and submodule access for that workflow. See the
+[capture-up model](/apex/concepts/architecture#capture-up).

 ### Validate

@@ -87,19 +90,19 @@ Add a scheduled workflow that merges `sync/<node>` into `main` when the branch e
 ./commons/apex --help
 ```

-The listing must show every commons action (plus your proprietaries, once added). Off-host — before `node.env` is filled — expect the harmless warning that `APEX_NODE_FQDN` is unset (the engine falls back to the OS hostname); `APEX_SUBNET` must still be set or the engine exits `66`. Commit the assembled repository on `main`.
+The listing must show every commons action (plus your proprietaries, once added). Off-host — before `node.env` is filled — expect the harmless warning that `APEX_NODE_FQDN` is unset (the engine falls back to the OS hostname); `APEX_SUBNET` must still be set or the engine exits `66`. Commit the assembled repository on `main`.

 {{% /steps %}}

 ## Notes

- The `proprietaries/` pillar may start empty (keep it present with `.gitkeep` files); the engine treats a missing overlay gracefully.
- Migrate host config sources into `configs/` (`ufw/`, `cron/crontab`, `systemd/`, `crowdsec/`) as the node adopts each `configure/*` step — the actions consume `configs/` verbatim through the template layer.
+- The `proprietaries/` pillar may start empty (keep it present with `.gitkeep` files); the engine treats a missing overlay gracefully.
+- Migrate host config sources into `configs/` (`ufw/`, `cron/crontab`, `systemd/`, `crowdsec/`) as the node adopts each `configure/*` step — the actions consume `configs/` verbatim through the template layer.

 ---

 **See also:**

- [Getting started with an apex node](/apex/getting-started)
+- [Getting started with an apex node](/apex/getting-started)
 - [Concept: Framework architecture](/apex/concepts/architecture)
- [Guide: Add a service composition](/apex/guides/service-composition)
+- [Guide: Add a service composition](/apex/guides/service-composition)
@@ -1,18 +1,18 @@
 ---
-title: Add a service composition
-description: "Wire a new project into a node: anchor IP, networks, tiers, and lint."
+title: Add a service composition
+description: "Wire a new project into a node: anchor IP, networks, tiers, and lint."
 weight: 23
 ---

-**Context:** a project joins a [node](/apex/glossary#node) as one directory under `compositions/` containing a hand-authored compose file. The framework's contract for that file is small: a static [anchor IP](/apex/glossary#anchor-ip) on the `direct` network, external network references by key, and tier-relative data paths.
+**Context:** a project joins a [node](/apex/glossary#node) as one directory under `compositions/` containing a hand-authored compose file. The framework's contract for that file is small: a static [anchor IP](/apex/glossary#anchor-ip) on the `direct` network, external network references by key, and tier-relative data paths.

 {{% steps %}}

-### Allocate the anchor address
+### Allocate the anchor address

-Pick the next free address at `.20` or above in the node's /24 and record it in `compositions/ADDRESSING.md`. Addresses `.10`–`.19` are reserved for the [core composition](/apex/glossary#core-composition) (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)).
+Pick the next free address at `.20` or above in the node's /24 and record it in `compositions/ADDRESSING.md`. Addresses `.10`–`.19` are reserved for the [core composition](/apex/glossary#core-composition) (see [Concept: Fleet addressing scheme](/apex/concepts/addressing)).

-### Author the compose file
+### Author the compose file

 ```yaml {filename="compositions/<project>/docker-compose.yml"}
 name: <project>
@@ -28,7 +28,7 @@ services:
      - ./@tier2/<anchor>/data:/data
    networks:
      direct:
-        ipv4_address: 198.18.16.20
+        ipv4_address: 198.18.0.20
      enclave: {}
    labels:
      - "traefik.enable=true"
@@ -50,16 +50,16 @@ networks:
    external: true
 ```

-Conventions at work:
+Conventions at work:

- **One anchor per project** holds the static `ipv4_address` on `direct`; sidecars share its network namespace via `network_mode: service:<anchor>`.
- **Networks are referenced by key** (`direct`, `enclave`, `socket`) with `external: true` — the core composition owns their definitions.
- **`enclave` membership plus traefik labels** publishes the service through the edge proxy; the proxy discovers it via the socket proxy, never via published ports.
- **Data paths are tier-relative** (`./@tierN/...`) and resolve through the symlinks created by `tiers/link`.
- **Backup is opt-in via `restic.*` labels.** `apex backup/run` drives [resticontainer](https://github.com/deytenit/resticontainer), which discovers what to snapshot from compose labels: `restic.enable=true` marks the service, `restic.backup.paths=<container-path>` names the mounts to back up (resticontainer resolves them to host paths). A service with no `restic.*` labels is simply not backed up. Back up config only where the data is regenerable.
- The `${APEX_UID...}` trio comes from the project `.env` maintained by `tiers/useradd`.
+- **One anchor per project** holds the static `ipv4_address` on `direct`; sidecars share its network namespace via `network_mode: service:<anchor>`.
+- **Networks are referenced by key** (`direct`, `enclave`, `socket`) with `external: true` — the core composition owns their definitions.
+- **`enclave` membership plus traefik labels** publishes the service through the edge proxy; the proxy discovers it via the socket proxy, never via published ports.
+- **Data paths are tier-relative** (`./@tierN/...`) and resolve through the symlinks created by `tiers/link`.
+- **Backup is opt-in via `restic.*` labels.** `apex backup/run` drives [resticontainer](https://github.com/deytenit/resticontainer), which discovers what to snapshot from compose labels: `restic.enable=true` marks the service, `restic.backup.paths=<container-path>` names the mounts to back up (resticontainer resolves them to host paths). A service with no `restic.*` labels is simply not backed up. Back up config only where the data is regenerable.
+- The `${APEX_UID...}` trio comes from the project `.env` maintained by `tiers/useradd`.

-### Provision storage and identity
+### Provision storage and identity

 ```bash
 apex tiers/link <tier1> <tier2> <tier3>
@@ -67,7 +67,7 @@ apex tiers/useradd
 apex tiers/chown
 ```

-Re-running the trio is idempotent; it picks up the new project, creates its tier directories and `.env`, provisions its `noroot-<project>` user, and applies the ownership matrix.
+Re-running the trio is idempotent; it picks up the new project, creates its tier directories and `.env`, provisions its `noroot-<project>` user, and applies the ownership matrix.

 ### Lint

@@ -75,7 +75,7 @@ Re-running the trio is idempotent; it picks up the new project, creates its tier
 apex utils/lint-docker-compose
 ```

-Validates every anchor IP (well-formed, unique, inside the node subnet) and runs the compose linter over the repository. The pre-commit hook enforces the same lint on staged compose files.
+Validates every anchor IP (well-formed, unique, inside the node subnet) and runs the compose linter over the repository. The pre-commit hook enforces the same lint on staged compose files.

 ### Deploy

@@ -83,19 +83,19 @@ Validates every anchor IP (well-formed, unique, inside the node subnet) and runs
 apex compose up
 ```

-The core composition is already up; the new project starts in its alphabetical slot. Verify with `docker ps` and, if the service is proxied, through its route on the edge.
+The core composition is already up; the new project starts in its alphabetical slot. Verify with `docker ps` and, if the service is proxied, through its route on the edge.

 {{% /steps %}}

 ## Notes

- Service-internal secrets (for example a database password) live in the project's own `.env` in tier-1 storage, alongside the auto-injected UID block.
- Never define `direct`/`enclave`/`socket` inside a project file — a second definition would race the core composition for network ownership.
+- Service-internal secrets (for example a database password) live in the project's own `.env` in tier-1 storage, alongside the auto-injected UID block.
+- Never define `direct`/`enclave`/`socket` inside a project file — a second definition would race the core composition for network ownership.

 ---

 **See also:**

- [Concept: Compositions and the shared core](/apex/concepts/compositions)
- [Concept: Tiered storage and privilege isolation](/apex/concepts/tiered-storage)
+- [Concept: Compositions and the shared core](/apex/concepts/compositions)
+- [Concept: Tiered storage and privilege isolation](/apex/concepts/tiered-storage)
 - [Concept: Fleet addressing scheme](/apex/concepts/addressing)
@@ -1,10 +1,10 @@
 ---
 title: Reference
-description: CLI, actions, environment variables, and the engine API.
+description: CLI, actions, environment variables, and the engine API.
 weight: 30
 ---

-Technical reference for the apex fleet-operations framework surface: the command-line interface, the built-in [actions](/apex/glossary#action), the environment contract they consume, and the Python [engine](/apex/glossary#engine) API.
+Technical reference for the apex fleet-operations framework surface: the command-line interface, the built-in [actions](/apex/glossary#action), the environment contract they consume, and the Python [engine](/apex/glossary#engine) API.

 {{% cards %}}
 {{< card link="cli" title="CLI reference" icon="terminal" subtitle="Command-line invocation, subcommands, and exit codes." >}}
@@ -1,10 +1,10 @@
 ---
 title: Actions reference
-description: "Every commons action: arguments and behavior."
+description: "Every commons action: arguments and behavior."
 weight: 32
 ---

-The sixteen [commons](/apex/glossary#commons) actions, by group. Arguments are shown as the parser accepts them; optional arguments are bracketed. Exit codes follow the [engine convention](/apex/reference/cli#exit-codes).
+The [commons](/apex/glossary#commons) actions, by group. Arguments are shown as the parser accepts them; optional arguments are bracketed. Exit codes follow the [engine convention](/apex/reference/cli#exit-codes).

 ## configure {#configure}

@@ -12,43 +12,49 @@ The sixteen [commons](/apex/glossary#commons) actions, by group. Arguments are s

 `apex configure [--dry-run]`

-Runs the whole suite in fixed order — `base`, `ufw`, `crowdsec`, `cron`, `systemd`, `routing` — and stops at the first failing step, propagating its exit code. `--dry-run` is forwarded to the steps that support it.
+Runs the suite in order: `base`, `timezone`, `ufw`, `crowdsec`, `cron`, `systemd`, `routing`, then additional node actions. A failing step contributes a nonzero exit status; later steps may still run. `--dry-run` is forwarded only to steps that support it, so it is not a guarantee that the entire umbrella command is read-only.

 ### configure/base

 `apex configure/base`

-Debian-only guard (exit `1` elsewhere). Updates the package index, installs the essential packages (`curl`, `wget`, `git`, `rsyslog`), ensures rsyslog is running, installs `ufw` when absent, and downloads the `ufw-docker` helper to `~/.local/bin/ufw-docker` (skipped when already present).
+Debian-only guard (exit `1` elsewhere). Checks installed package state for `curl`, `wget`, `git`, `rsyslog`, and `ufw`; installs missing packages and ensures rsyslog is running. Refuses an APT simulation containing upgrades or removals and uses `--no-upgrade --no-remove`. Avoid concurrent package operations: simulation and installation are separate transactions. Verifies the immutable revision and SHA-256 of `/usr/local/bin/ufw-docker` before running it as root. Unsafe paths and unverified downloads are rejected; an executable file alone is not trusted.
+
+### configure/timezone
+
+`apex configure/timezone [--dry-run]`
+
+Applies the IANA zone named in `configs/timezone` and refreshes active cron after a change. An absent declaration preserves the current timezone; an invalid zone fails before changing it.

 ### configure/ufw

 `apex configure/ufw [--dry-run]`

-Applies the node firewall from `configs/ufw/`: `host/host.rules` through plain `ufw`, `host/before.rules`/`after.rules` as self-healing managed blocks inside `/etc/ufw/`, and `docker/*.rules` through `ufw-docker`. Exits `1` when the config root is missing, `66` when exactly one of `docker/`/`host/` is absent, `1` when a `/etc/ufw` target file does not exist. Requires `configure/base` first (checks `ufw` and `ufw-docker`). Finishes with a restart reminder.
+Applies the node firewall from `configs/ufw/`: `host/host.rules` through plain `ufw`, `host/before.rules`/`after.rules` as self-healing managed blocks inside `/etc/ufw/`, and `docker/*.rules` through `ufw-docker`. Exits `1` when the config root is missing, `66` when exactly one of `docker/`/`host/` is absent, `1` when a `/etc/ufw` target file does not exist. Requires `configure/base` first (checks `ufw` and `ufw-docker`). Finishes with a restart reminder.

 ### configure/crowdsec

 `apex configure/crowdsec [--dry-run]`

-Installs CrowdSec via the official script when `cscli` is absent, renders `configs/crowdsec/` into `/etc/crowdsec/` (backing up overwritten files), installs the `crowdsecurity/linux` and `crowdsecurity/traefik` collections, and installs the iptables firewall bouncer when `configs/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local` exists and the package is missing. `--dry-run` renders without writing and skips install steps.
+Installs CrowdSec via the official script when `cscli` is absent, renders `configs/crowdsec/` into `/etc/crowdsec/` (backing up overwritten files), installs the `crowdsecurity/linux` and `crowdsecurity/traefik` collections, and installs the iptables firewall bouncer when `configs/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local` exists and the package is missing. `--dry-run` renders without writing and skips install steps.

 ### configure/cron

 `apex configure/cron [--dry-run]`

-Renders `configs/cron/crontab` with `ctx.vars()` and installs it via `crontab -`. Missing source file: exit `1`. Empty render: exit `65`, previous crontab kept. Failed install: previous crontab restored, exit `1`. The rendered result is always printed for review.
+Renders `configs/cron/crontab` with `ctx.vars()` and installs it via `crontab -`. Missing source file: exit `1`. Empty render: exit `65`, previous crontab kept. Failed install: previous crontab restored, exit `1`. The rendered result is always printed for review.

 ### configure/systemd

 `apex configure/systemd [--dry-run]`

-Renders every top-level, non-hidden file of `configs/systemd/` into `/etc/systemd/system/<name>`; for each `.service` unit it daemon-reloads and enables `--now`. Missing config directory: exit `1`.
+Renders every top-level, non-hidden file of `configs/systemd/` into `/etc/systemd/system/<name>`; for each `.service` unit it daemon-reloads and enables `--now`. Missing config directory: exit `1`.

 ### configure/routing

 `apex configure/routing`

-Enables `net.ipv4.ip_forward`, installs the fwmark `0x1` → routing-table-100 policy rule and the local default route in that table. Both checks are idempotent — re-runs change nothing.
+Enables `net.ipv4.ip_forward`, installs the fwmark `0x1` → routing-table-100 policy rule and the local default route in that table. Both checks are idempotent — re-runs change nothing.

 ## sync {#sync}

@@ -56,13 +62,13 @@ Enables `net.ipv4.ip_forward`, installs the fwmark `0x1` → routing-table-100 p

 `apex sync/repository <telegram_bot_url>`

-The [capture-up](/apex/glossary#capture-up) commit: switches to (or creates) `sync/<node>`, stages the whole tree plus the refreshed commons submodule pointer, commits under a bot identity when anything changed, rebases onto `origin/main`, updates submodules, and pushes with `--force-with-lease`. Aborts (exit `1`) when the commons submodule is dirty or `compositions/` is missing; on a rebase conflict it aborts the rebase and pages via Telegram. Success and every failure path notify; a failed success-notification also exits `1`.
+The [capture-up](/apex/glossary#capture-up) commit: switches to (or creates) `sync/<node>`, stages the whole tree plus the refreshed commons submodule pointer, commits under a bot identity when anything changed, rebases onto `origin/main`, updates submodules, and pushes with `--force-with-lease`. Aborts (exit `1`) when the commons submodule is dirty or `compositions/` is missing; on a rebase conflict it aborts the rebase and pages via Telegram. Success and every failure path notify; a failed success-notification also exits `1`.

 ### sync/packages

 `apex sync/packages <telegram_bot_url>`

-Debian-only. Collects pending apt upgrades (`--just-print`) and out-of-date running container images (local RepoDigest vs the registry digest via `skopeo`), then sends one Telegram digest. Read-only with respect to packages and images. Unhandled failures page via Telegram and exit `1`; so does a failed digest delivery.
+Debian-only. Collects pending apt upgrades (`--just-print`) and out-of-date running container images (local RepoDigest vs the registry digest via `skopeo`), then sends one Telegram digest. Read-only with respect to packages and images. Unhandled failures page via Telegram and exit `1`; so does a failed digest delivery.

 ## backup {#backup}

@@ -70,7 +76,7 @@ Debian-only. Collects pending apt upgrades (`--just-print`) and out-of-date runn

 `apex backup/run <telegram_bot_url>`

-Drives the label-driven `resticontainer` core service one-shot (profile `manual`): repository reachability check with init-if-needed, then a single `backup` in which resticontainer discovers every service carrying `restic.*` compose labels, runs their pre-hooks, stops any container flagged `restic.backup.stop`, resolves the labeled container mounts to host paths, and snapshots the union in one restic run. The snapshot is stamped `--host <APEX_NODE_HOST>`, `--tag biweekly`, `--compression max`. A guard then proves a fresh snapshot for this host actually landed — if no `restic.*` labels were discovered the backup is a silent no-op, so it refuses to report success. Retention follows via `forget --prune` (7 daily / 4 weekly / 12 monthly). Each restic failure pages and exits `1`; success pages too, and a failed success-notification exits `1`.
+Drives the label-driven `resticontainer` core service one-shot (profile `manual`): repository reachability check with init-if-needed, then a single `backup` in which resticontainer discovers every service carrying `restic.*` compose labels, runs their pre-hooks, stops any container flagged `restic.backup.stop`, resolves the labeled container mounts to host paths, and snapshots the union in one restic run. The snapshot is stamped `--host <APEX_NODE_HOST>`, `--tag biweekly`, `--compression max`. A guard then proves a fresh snapshot for this host actually landed — if no `restic.*` labels were discovered the backup is a silent no-op, so it refuses to report success. Retention follows via `forget --prune` (7 daily / 4 weekly / 12 monthly). Each restic failure pages and exits `1`; success pages too, and a failed success-notification exits `1`.

 ## tiers {#tiers}

@@ -78,19 +84,19 @@ Drives the label-driven `resticontainer` core service one-shot (profile `manual`

 `apex tiers/link <tier1_path> <tier2_path> <tier3_path>`

-Builds the whole [tier](/apex/glossary#tier) symlink structure: node-level `compositions/@tierN` links, per-project tier directories, `shared/` areas with back-links, per-project `@tierN` links, and the `.env` symlink into tier 1 (target created when missing). Existing non-symlink paths prompt for confirmation; declining skips that link.
+Builds the whole [tier](/apex/glossary#tier) symlink structure: node-level `compositions/@tierN` links, per-project tier directories, `shared/` areas with back-links, per-project `@tierN` links, and the `.env` symlink into tier 1 (target created when missing). Existing non-symlink paths prompt for confirmation; declining skips that link.

 ### tiers/useradd

 `apex tiers/useradd`

-Ensures the `noroot-shared` group, then one locked `noroot-<project>` system user per composition project (own primary group, no home, `nologin` shell, member of the shared group), and injects `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` into each project `.env` between managed markers.
+Ensures the `noroot-shared` group, then one locked `noroot-<project>` system user per composition project (own primary group, no home, `nologin` shell, member of the shared group), and injects `APEX_UID`/`APEX_GID`/`APEX_SHARED_GID` into each project `.env` between managed markers.

 ### tiers/chown

 `apex tiers/chown [tier1_path] [tier2_path] [tier3_path]`

-Applies the ownership matrix (see [Concept: Tiered storage](/apex/concepts/tiered-storage#ownership)) across the tier roots — defaults are the node-level tier links. Requires `noroot-shared` to exist (exit `1` otherwise); projects with incomplete `.env` identity are skipped with a warning.
+Applies the ownership matrix (see [Concept: Tiered storage](/apex/concepts/tiered-storage#ownership)) across the tier roots — defaults are the node-level tier links. Requires `noroot-shared` to exist (exit `1` otherwise); projects with incomplete `.env` identity are skipped with a warning.

 ## utils {#utils}

@@ -98,26 +104,36 @@ Applies the ownership matrix (see [Concept: Tiered storage](/apex/concepts/tiere

 `apex utils/extract-traefik-certs <source_acme> <dest_dir> [telegram_bot_url]`

-Extracts the ACME store into per-domain `fullchain.pem`/`privkey.pem` via a containerized dumper, then `chmod 600` on the keys and re-owns the output tree to the invoking user. Missing source: exit `1`. Failures inside the extraction page via Telegram when a URL was given.
+Extracts the ACME store into per-domain `fullchain.pem`/`privkey.pem` via a containerized dumper, then `chmod 600` on the keys and re-owns the output tree to the invoking user. Missing source: exit `1`. Failures inside the extraction page via Telegram when a URL was given.

 ### utils/lint-docker-compose

 `apex utils/lint-docker-compose [--hook]`

-Two passes: (1) [anchor-IP](/apex/glossary#anchor-ip) validation over `compositions/*/docker-compose.yml` — well-formed, unique, inside the node subnet; (2) the `dclint` compose linter with `--fix`, run in a container over the repository (tier links, `.env`, and the commons submodule excluded). `--hook` restricts pass 2 to staged compose files and re-stages what the linter fixed. The exit code reflects both passes.
+Two passes: (1) [anchor-IP](/apex/glossary#anchor-ip) validation over `compositions/*/docker-compose.yml` — well-formed, unique, inside the node subnet; (2) the `dclint` compose linter with `--fix`, run in a container over the repository (tier links, `.env`, and the commons submodule excluded). `--hook` restricts pass 2 to staged compose files and re-stages what the linter fixed. The exit code reflects both passes.

 ## compose {#compose}

 ### compose

-`apex compose <action> [--dry-run] [extra...]`
+`apex compose [-p <composition>] [--dry-run] <action> [extra...]`

-Orchestrates `docker compose <action>` across the node: the core project first, then services alphabetically (reversed for `down`). `up` implies `-d`; `.env`/`apex.env` are passed per project when present; extra arguments pass through; `--dry-run` (accepted in any position) prints commands instead of executing.
+Without a target, visits core first and other compositions alphabetically, reversed for `down`. `-p` selects one composition or `all`; `up` defaults to detached mode. `.env` then `apex.env` are passed per project, with generated identity/path values in the process environment. Remaining arguments pass through to Docker Compose. Wrapper options precede the action; `--dry-run` prints commands without executing them.
+
+Compatibility forms include `apex compose restart apex traefik` and `apex compose up -d apex`. Use explicit `-p` to distinguish a composition from a service or option value.
+
+## env {#env}
+
+`apex env [--export | --dotenv | --write <path> | --sync]`
+
+Default output is shell-quoted APEX exports for `eval "$(apex env)"`. `--dotenv` emits dotenv syntax; `--write` writes generated values to a separate file, including a relative filename. These modes do not read composition credentials or merge `apex.env`.
+
+`--sync` preserves existing `compositions/apex/.env` text and updates only its managed block: committed `apex.env` settings first, generated identity/path values last. This includes non-APEX settings such as `COMPOSE_PROFILES` and `TZ`, allowing bare Docker Compose commands in the core directory. Existing tier symlinks remain intact, and synchronized files use mode `0600`. Resync after changing source settings or tier paths. Malformed managed markers fail without rewriting uncertain content. Shell environment values still have Docker Compose precedence.

 ---

 **See also:**

 - [Reference: CLI](/apex/reference/cli)
- [Guide: Operate a node](/apex/guides/host-operations)
+- [Guide: Operate a node](/apex/guides/host-operations)
 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
@@ -1,56 +1,56 @@
 ---
 title: CLI reference
-description: "The apex launcher: listing, dispatch, help, and exit codes."
+description: "The apex launcher: listing, dispatch, help, and exit codes."
 weight: 31
 ---

-The launcher is a single stdlib-Python script, `commons/apex` (on `PATH` after `init.sh`). Everything it does targets the local checkout — no node argument exists.
+The launcher is a single stdlib-Python script, `commons/apex` (on `PATH` after `init.sh`). Everything it does targets the local checkout — no node argument exists.

 ## Invocation forms {#invocation}

 | Command | Behavior |
 |---|---|
-| `apex` or `apex --help` | List every available [action](/apex/glossary#action) with its summary; exit `0`. |
+| `apex` or `apex --help` | List every available [action](/apex/glossary#action) with its summary; exit `0`. |
 | `apex <group>/<action> [args...]` | Dispatch one action. |
-| `apex <group>/<action> --help` | Print the action's argparse help generated from its `METADATA`; exit `0`. |
+| `apex <group>/<action> --help` | Print the action's argparse help generated from its `METADATA`; exit `0`. |

-The listing tags each entry with its [overlay](/apex/glossary#overlay) source — no tag (commons), `(local)`, `(local override)` — and appends `[DISABLED: reason]` where a module declares `DISABLED`. Listing uses static `ast` scanning, so no action code executes.
+The listing tags each entry with its [overlay](/apex/glossary#overlay) source — no tag (commons), `(local)`, `(local override)` — and appends `[DISABLED: reason]` where a module declares `DISABLED`. Listing uses static `ast` scanning, so no action code executes.

-## Layout and path resolution {#layout}
+## Layout and path resolution {#layout}

-At startup the launcher decides which of two layouts it is in:
+At startup the launcher decides which of two layouts it is in:

- **Node checkout** — the launcher lives in a directory named `commons/` whose parent contains `node.env`. The parent is the repository root; `proprietaries/actions/` is the overlay tree; [node identity](/apex/glossary#node-identity) is resolved before dispatch, and any identity warnings are logged first.
- **Standalone commons** — any other location. The commons directory is its own root, there is no overlay, and `ctx.node` is `None` (log lines carry the `global` prefix).
+- **Node checkout** — the launcher lives in a directory named `commons/` whose parent contains `node.env`. The parent is the repository root; `proprietaries/actions/` is the overlay tree; [node identity](/apex/glossary#node-identity) is resolved before dispatch, and any identity warnings are logged first.
+- **Standalone commons** — any other location. The commons directory is its own root, there is no overlay, and `ctx.node` is `None` (log lines carry the `global` prefix).

-`sys.path` is assembled as: the commons directory (makes `engine` importable), then `commons/vendor/` when present, then `../proprietaries/` in a node checkout (makes proprietary `lib/` code importable).
+`sys.path` is assembled as: the commons directory (makes `engine` importable), then `commons/vendor/` when present, then `../proprietaries/` in a node checkout (makes proprietary `lib/` code importable).

 ## Exit codes {#exit-codes}

 | Code | Source |
 |---|---|
-| `0` | Action returned `0` or a non-integer; `--help` paths. |
-| `1` | Unknown action; disabled action; unhandled exception (logged as `Type: message` with the context prefix); non-integer `SystemExit`. |
-| `64` | Usage error from argument parsing (`EX_USAGE`). |
-| `65` | Data error raised by engine libraries (`EX_DATAERR`) — for example an empty rendered crontab. |
-| `66` | Missing input (`EX_NOINPUT`) — for example missing identity fields or an absent ufw config directory. |
+| `0` | Action returned `0` or a non-integer; `--help` paths. |
+| `1` | Unknown action; disabled action; unhandled exception (logged as `Type: message` with the context prefix); non-integer `SystemExit`. |
+| `64` | Usage error from argument parsing (`EX_USAGE`). |
+| `65` | Data error raised by engine libraries (`EX_DATAERR`) — for example an empty rendered crontab. |
+| `66` | Missing input (`EX_NOINPUT`) — for example missing identity fields or an absent ufw config directory. |

-Any other code is whatever the action itself returned or raised.
+Any other code is whatever the action itself returned or raised.

 ## Log format {#log-format}

-All engine and action output follows one line shape:
+All engine and action output follows one line shape:

 ```text
 [<node>] [<group>/<action>] [LEVEL] message
 ```

-`LEVEL` is `INFO`, `WARN`, `ERROR`, or `SUCCESS`; `ERROR` lines go to stderr, everything else to stdout — cron-friendly for both capture and alerting.
+`LEVEL` is `INFO`, `WARN`, `ERROR`, or `SUCCESS`; `ERROR` lines go to stderr, everything else to stdout — cron-friendly for both capture and alerting.

 ---

 **See also:**

- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
+- [Concept: Actions and the overlay](/apex/concepts/actions-and-overlay)
 - [Reference: Actions](/apex/reference/actions)
 - [Reference: Engine API](/apex/reference/engine-api)
@@ -1,10 +1,10 @@
 ---
 title: Engine API reference
-description: The descriptor and ctx APIs available to action authors.
+description: The descriptor and ctx APIs available to action authors.
 weight: 34
 ---

-The surface an [action](/apex/glossary#action) author programs against: the argument descriptors in `engine.descriptor` and the members of the execution context. Conceptual background in [Concept: The execution context](/apex/concepts/execution-context).
+The surface an [action](/apex/glossary#action) author programs against: the argument descriptors in `engine.descriptor` and the members of the execution context. Conceptual background in [Concept: The execution context](/apex/concepts/execution-context).

 ## Descriptors {#descriptors}

@@ -14,20 +14,20 @@ from engine.descriptor import Meta, Arg, Opt, Flag, Rest

 | Class | Signature | argparse mapping |
 |---|---|---|
-| `Meta` | `Meta(summary, args=[])` | Drives both the listing summary and the parser. |
+| `Meta` | `Meta(summary, args=[])` | Drives both the listing summary and the parser. |
 | `Arg` | `Arg(name, help="", required=True)` | Positional; `required=False` → `nargs="?"`, default `None`. |
-| `Opt` | `Opt(name, help="", default=None)` | Value option (`--name VALUE`) with a default. |
+| `Opt` | `Opt(name, help="", default=None)` | Value option (`--name VALUE`) with a default. |
 | `Flag` | `Flag(name, help="")` | Boolean `store_true` flag. |
 | `Rest` | `Rest(name, help="")` | Greedy remainder (`argparse.REMAINDER`). |

-Usage errors exit `64` instead of argparse's default `2`.
+Usage errors exit `64` instead of argparse's default `2`.

 > [!WARNING]
-> `Rest` captures *everything* after the first positional — including flags. A `Flag` declared next to a `Rest` is only recognized *before* the positional; an action that must accept its flag anywhere has to strip it out of the remainder itself (the `compose` action does exactly this for `--dry-run`).
+> `Rest` captures *everything* after the first positional — including flags. A `Flag` declared next to a `Rest` is only recognized *before* the positional; an action that must accept its flag anywhere has to strip it out of the remainder itself (the `compose` action does exactly this for `--dry-run`).

 ## ctx.log {#log}

-`info(msg)` · `warn(msg)` · `success(msg)` → stdout; `error(msg)` → stderr. All lines carry the `[<node>] [<action>] [LEVEL]` prefix.
+`info(msg)` · `warn(msg)` · `success(msg)` → stdout; `error(msg)` → stderr. All lines carry the `[<node>] [<action>] [LEVEL]` prefix.

 ## ctx.sys {#sys}

@@ -41,27 +41,27 @@ Usage errors exit `64` instead of argparse's default `2`.
 | `ensure_running(name)` | `enable --now` when inactive. |
 | `restart(name)` / `reload(name, dry_run=False)` / `daemon_reload()` | Service lifecycle. |
 | `wait_for(name, timeout=30, interval=2)` | Poll until active. |
-| `install_packages(packages)` | For each package: skip when its binary is on `PATH`, else `apt-get update -y` + `apt-get install -y`. |
+| `install_packages(packages)` | For each package: skip when its binary is on `PATH`, else `apt-get update -y` + `apt-get install -y`. |

 ## ctx.tpl {#tpl}

 | Method | Behavior |
 |---|---|
-| `render(path, vars)` | Render one file (relative paths resolve against `configs/`); `safe_substitute` semantics — unknown variables stay literal. |
-| `render_dir(rel_dir, vars)` | Render every file under a `configs/` subtree; returns `{relative_path: content}`. |
+| `render(path, vars)` | Render one file (relative paths resolve against `configs/`); `safe_substitute` semantics — unknown variables stay literal. |
+| `render_dir(rel_dir, vars)` | Render every file under a `configs/` subtree; returns `{relative_path: content}`. |

 ## ctx.host {#host}

 | Method | Behavior |
 |---|---|
-| `backup(path, sudo=False)` | Copy the file to `<path>.<epoch>.bak`; returns the backup path or `None`. |
-| `write_file(path, content, backup=True, dry_run=False, sudo=False)` | Atomic install via temp file (mode `0644`); optional prior backup; `sudo` variant preserves an existing target's mode. |
-| `inject_block(target, content, start, end, anchor=None, old_pairs=(), dry_run=False, sudo=True)` | Managed marker-block replacement; removes current and legacy blocks, inserts after the first anchor line; `False` when the anchor is missing; missing target is an error. |
-| `install_crontab(text, dry_run=False)` | Snapshot, refuse empty render (`SystemExit(65)`), preview, install via `crontab -`, restore snapshot on failure (`SystemExit(1)`). |
+| `backup(path, sudo=False)` | Copy the file to `<path>.<epoch>.bak`; returns the backup path or `None`. |
+| `write_file(path, content, backup=True, dry_run=False, sudo=False)` | Atomic install via temp file (mode `0644`); optional prior backup; `sudo` variant preserves an existing target's mode. |
+| `inject_block(target, content, start, end, anchor=None, old_pairs=(), dry_run=False, sudo=True)` | Managed marker-block replacement; removes current and legacy blocks, inserts after the first anchor line; `False` when the anchor is missing; missing target is an error. |
+| `install_crontab(text, dry_run=False)` | Snapshot, refuse empty render (`SystemExit(65)`), preview, install via `crontab -`, restore snapshot on failure (`SystemExit(1)`). |

 ## ctx.ufw {#ufw}

-`apply(rules_dir, config_dir=None, dry_run=False)` — the full firewall pass: directory guards (exit `66`), tool guards (`ufw`, `ufw-docker`), host rules, managed-block injection into `/etc/ufw/before.rules` and `after.rules`, container rules from `*.rules` files.
+`apply(rules_dir, config_dir=None, dry_run=False)` — the full firewall pass: directory guards (exit `66`), tool guards (`ufw`, `ufw-docker`), host rules, managed-block injection into `/etc/ufw/before.rules` and `after.rules`, container rules from `*.rules` files.

 ## ctx.crowdsec {#crowdsec}

@@ -69,20 +69,20 @@ Usage errors exit `64` instead of argparse's default `2`.

 ## ctx.systemd {#systemd}

-`deploy_units(configs_subdir, vars, dry_run=False)` — render the subtree's top-level non-hidden files into `/etc/systemd/system/`, then daemon-reload and `enable --now` each `.service`.
+`deploy_units(configs_subdir, vars, dry_run=False)` — render the subtree's top-level non-hidden files into `/etc/systemd/system/`, then daemon-reload and `enable --now` each `.service`.

 ## ctx.notify {#notify}

-`telegram(title, bot_url, message, node=None, level="INFO")` plus the shorthands `success` / `error` / `info` / `warn`. All return `bool` — `True` only when the message was delivered; an empty `bot_url` logs a warning and returns `False`. The alert `instance` defaults to the node's public host (`APEX_NODE_HOST`) — no domain or node prefix is applied.
+`telegram(title, bot_url, message, node=None, level="INFO")` plus the shorthands `success` / `error` / `info` / `warn`. All return `bool` — `True` only when the message was delivered; an empty `bot_url` logs a warning and returns `False`. The alert `instance` defaults to the node's public host (`APEX_NODE_HOST`) — no domain or node prefix is applied.

-## ctx.paths and ctx.node {#paths}
+## ctx.paths and ctx.node {#paths}

-`ctx.paths`: `repo_root`, `commons`, `proprietaries`, `configs`, `compositions`, `core`, `tier1..3`, `stier1..3`, `root_tier1..3`. `ctx.node`: the identity record (`name`, `subnet`, `fqdn`, `host`) or `None` in a standalone commons checkout. `ctx.vars()`: the template/compose environment (see [Reference: Environment variables](/apex/reference/environment)). `ctx.commons.run(args)`: delegate to the shadowed commons action — only valid in an overriding proprietary module.
+`ctx.paths`: `repo_root`, `commons`, `proprietaries`, `configs`, `compositions`, `core`, `tier1..3`, `stier1..3`, `root_tier1..3`. `ctx.node`: the identity record (`name`, `subnet`, `fqdn`, `host`) or `None` in a standalone commons checkout. `ctx.vars()`: the template/compose environment (see [Reference: Environment variables](/apex/reference/environment)). `ctx.commons.run(args)`: delegate to the shadowed commons action — only valid in an overriding proprietary module.

 ---

 **See also:**

- [Concept: The execution context](/apex/concepts/execution-context)
+- [Concept: The execution context](/apex/concepts/execution-context)
 - [Guide: Develop actions](/apex/guides/action-development)
 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
@@ -1,78 +1,78 @@
 ---
 title: Environment variables reference
-description: Every APEX_* variable, where it is set, and who consumes it.
+description: Every APEX_* variable, where it is set, and who consumes it.
 weight: 33
 ---

-The `APEX_*` namespace is the framework's entire configuration surface. Variables originate in one of four layers; later layers win when the orchestration actions assemble the process environment.
+The `APEX_*` namespace is the framework's entire configuration surface. Variables originate in one of four layers; later layers win when the orchestration actions assemble the process environment.

-## node.env — identity {#node-env}
+## node.env — identity {#node-env}

-Committed at the repository root; read by [node identity](/apex/glossary#node-identity) resolution. The framework is domain-agnostic: a node declares its own FQDN and public host name — there is no cluster concept and no required FQDN shape.
+Committed at the repository root; read by [node identity](/apex/glossary#node-identity) resolution. The framework is domain-agnostic: a node declares its own FQDN and public host name — there is no cluster concept and no required FQDN shape.

 | Variable | Meaning | Notes |
 |---|---|---|
-| `APEX_NODE_FQDN` | The node's real FQDN (Traefik `Host()` routing) | Falls back to the OS hostname (with a warning) when unset. |
-| `APEX_NODE_HOST` | The node's public host name (backup `--host`, obs/notify `instance`) | Defaults to `APEX_NODE_FQDN`. Its first label becomes the short `name`. |
-| `APEX_SUBNET` | The node's /24 for the `direct` network | Required, only source of the subnet. Missing = exit `66`. |
-| `APEX_GIT_AUTHOR_NAME` | Bot identity for capture-up commits | Generic default (`apex [bot]`). |
-| `APEX_GIT_AUTHOR_EMAIL` | Bot identity email for capture-up commits | Generic default (`apex@localhost`). |
+| `APEX_NODE_FQDN` | The node's real FQDN (Traefik `Host()` routing) | Falls back to the OS hostname (with a warning) when unset. |
+| `APEX_NODE_HOST` | The node's public host name (backup `--host`, obs/notify `instance`) | Defaults to `APEX_NODE_FQDN`. Its first label becomes the short `name`. |
+| `APEX_SUBNET` | The node's /24 for the `direct` network | Required, only source of the subnet. Missing = exit `66`. |
+| `APEX_GIT_AUTHOR_NAME` | Bot identity for capture-up commits | Generic default (`apex [bot]`). |
+| `APEX_GIT_AUTHOR_EMAIL` | Bot identity email for capture-up commits | Generic default (`apex@localhost`). |

-## apex.env — committed scalars {#apex-env}
+## apex.env — committed scalars {#apex-env}

-Committed at `compositions/apex/`; non-secret by definition.
+Committed at `compositions/apex/`; non-secret by definition.

 | Variable | Meaning | Notes |
 |---|---|---|
-| `APEX_TRAEFIK_DIRECT_IP` | The edge proxy's [anchor IP](/apex/glossary#anchor-ip) in the node subnet | Required by the core composition (`?error`). |
+| `APEX_TRAEFIK_DIRECT_IP` | The edge proxy's [anchor IP](/apex/glossary#anchor-ip) in the node subnet | Required by the core composition (`?error`). |
 | `APEX_RESTIC_REPOSITORY` | Backup repository locator | Required (`?error`). |
-| `APEX_RESTIC_COMPRESSION` | Restic compression level | Optional; defaults to `max` (fleet policy — `backup/run` also forces `--compression max`). |
-| `APEX_RESTIC_AWS_REGION` | S3 backend region | Optional; defaults to `us-east-1`. |
-| `APEX_RESTIC_AWS_ENDPOINT` | S3 backend endpoint URL | Optional; defaults to empty (AWS S3). Set for any non-AWS S3-compatible store. |
-| `APEX_LOKI_PUSH_URL` | Loki ingest URL for the [Alloy](/apex/concepts/architecture) agent (`loki.write`) | Required by the `alloy` profile (`?error`). |
-| `APEX_PROM_PUSH_URL` | Prometheus `remote_write` URL for the Alloy agent | Required by the `alloy` profile (`?error`). |
-| `APEX_OBS_BASIC_AUTH_USER` | Basic-auth user for the observability push targets | Required by the `alloy` profile (`?error`). |
-| `COMPOSE_PROFILES` | Opt-in core profiles (`adguard`, `xray`, `alloy`) | May be empty; `manual` is activated by `backup/run`, not here. |
-| `TZ` | Container timezone | Optional; defaults to `Etc/UTC`. |
+| `APEX_RESTIC_COMPRESSION` | Restic compression level | Optional; defaults to `max` (fleet policy — `backup/run` also forces `--compression max`). |
+| `APEX_RESTIC_AWS_REGION` | S3 backend region | Optional; defaults to `us-east-1`. |
+| `APEX_RESTIC_AWS_ENDPOINT` | S3 backend endpoint URL | Optional; defaults to empty (AWS S3). Set for any non-AWS S3-compatible store. |
+| `APEX_LOKI_PUSH_URL` | Loki ingest URL for the [Alloy](/apex/concepts/architecture) agent (`loki.write`) | Required by the `alloy` profile (`?error`). |
+| `APEX_PROM_PUSH_URL` | Prometheus `remote_write` URL for the Alloy agent | Required by the `alloy` profile (`?error`). |
+| `APEX_OBS_BASIC_AUTH_USER` | Basic-auth user for the observability push targets | Required by the `alloy` profile (`?error`). |
+| `COMPOSE_PROFILES` | Opt-in core profiles (`adguard`, `xray`, `alloy`) | May be empty; `manual` is activated by `backup/run`, not here. |
+| `TZ` | Container timezone | Optional; defaults to `Etc/UTC`. |

-## .env — secrets {#secrets}
+## .env — secrets {#secrets}

-Uncommitted; a symlink into tier-1 storage. Keys are documented per node in `SECRETS.md`.
+Uncommitted; a symlink into tier-1 storage. Keys are documented per node in `SECRETS.md`.

 | Variable | Meaning | Notes |
 |---|---|---|
-| `APEX_UID`, `APEX_GID`, `APEX_SHARED_GID` | The project's noroot identity | Auto-injected by `tiers/useradd`; required (`?error`). |
+| `APEX_UID`, `APEX_GID`, `APEX_SHARED_GID` | The project's noroot identity | Auto-injected by `tiers/useradd`; required (`?error`). |
 | `APEX_RESTIC_PASSWORD` | Backup repository password | Required (`?error`). |
 | `APEX_RESTIC_AWS_ACCESS_KEY_ID`, `APEX_RESTIC_AWS_SECRET_ACCESS_KEY` | Object-storage credentials | Required (`?error`). |
-| `APEX_TRAEFIK_CF_DNS_API_TOKEN` | DNS-challenge token for ACME | Required (`?error`). |
+| `APEX_TRAEFIK_CF_DNS_API_TOKEN` | DNS-challenge token for ACME | Required (`?error`). |
 | `APEX_TRAEFIK_ACME_EMAIL` | ACME account email | Required (`?error`). |
-| `APEX_OBS_BASIC_AUTH_PASS` | Basic-auth password for the observability push targets | Required by the `alloy` profile (`?error`). |
-| `APEX_LOKI_BASIC_AUTH` | htpasswd users for the central Loki/Prometheus ingest | Not core-required. Only on a node that itself fronts the central observability ingest. |
+| `APEX_OBS_BASIC_AUTH_PASS` | Basic-auth password for the observability push targets | Required by the `alloy` profile (`?error`). |
+| `APEX_LOKI_BASIC_AUTH` | htpasswd users for the central Loki/Prometheus ingest | Not core-required. Only on a node that itself fronts the central observability ingest. |

-## Engine exports — ctx.vars() {#engine}
+## Engine exports — ctx.vars() {#engine}

-Computed by the [engine](/apex/glossary#engine) at invocation; exported to `docker compose` by the orchestration actions and available to every template render. Never set these by hand.
+Computed by the [engine](/apex/glossary#engine) at invocation; exported to `docker compose` by the orchestration actions and available to every template render. Never set these by hand.

 | Variable | Value |
 |---|---|
-| `APEX_NODE_HOST` | The node's public host name (`node.host`); backup `--host` and obs/notify `instance`. |
-| `APEX_NODE_FQDN` | The node's real FQDN (`node.fqdn`); used for edge routing rules. |
+| `APEX_NODE_HOST` | The node's public host name (`node.host`); backup `--host` and obs/notify `instance`. |
+| `APEX_NODE_FQDN` | The node's real FQDN (`node.fqdn`); used for edge routing rules. |
 | `APEX_SUBNET` | Node subnet. |
-| `APEX_COMMONS` | Absolute commons directory (`$APEX_COMMONS/apex` is the launcher — crontabs and systemd units use it). |
+| `APEX_COMMONS` | Absolute commons directory (`$APEX_COMMONS/apex` is the launcher — crontabs and systemd units use it). |
 | `APEX_REPO_ROOT` | Absolute node repository root. |
 | `APEX_TIER1`, `APEX_TIER2`, `APEX_TIER3` | Core project data directory per [tier](/apex/glossary#tier). |
 | `APEX_TIER1_SHARED`, `APEX_TIER2_SHARED`, `APEX_TIER3_SHARED` | Shared area per tier. |
 | `APEX_TIER_ROOT1`, `APEX_TIER_ROOT2`, `APEX_TIER_ROOT3` | Tier storage roots. |

 > [!NOTE]
-> Variables marked `?error` above are enforced by the shared core composition: `docker compose` refuses to evaluate the model while they are unset, which turns a forgotten secret into an immediate, explicit failure.
+> Variables marked `?error` above are enforced by the shared core composition: `docker compose` refuses to evaluate the model while they are unset, which turns a forgotten secret into an immediate, explicit failure.

-Several core-composition variables use `${VAR:-default}` instead, so they are optional and overridable per node: `TZ` (`Etc/UTC`), `APEX_RESTIC_AWS_REGION` (`us-east-1`), `APEX_RESTIC_AWS_ENDPOINT` (empty), `APEX_RESTIC_COMPRESSION` (`max`), and `APEX_ENCLAVE_SUBNET` (`198.18.0.0/16`, the ipallowlist source range for the Traefik dashboard/adguard routes).
+Several core-composition variables use `${VAR:-default}` instead, so they are optional and overridable per node: `TZ` (`Etc/UTC`), `APEX_RESTIC_AWS_REGION` (`us-east-1`), `APEX_RESTIC_AWS_ENDPOINT` (empty), `APEX_RESTIC_COMPRESSION` (`max`), and `APEX_ENCLAVE_SUBNET` (`198.18.0.0/16`, the ipallowlist source range for the Traefik dashboard/adguard routes).

 ---

 **See also:**

- [Concept: The execution context](/apex/concepts/execution-context)
- [Concept: Compositions and the shared core](/apex/concepts/compositions)
+- [Concept: The execution context](/apex/concepts/execution-context)
+- [Concept: Compositions and the shared core](/apex/concepts/compositions)
 - [Concept: Node identity resolution](/apex/concepts/node-identity)
@@ -1,79 +1,79 @@
 ---
 title: Troubleshooting
-description: Symptoms, diagnosis, and fixes for common apex failure modes.
+description: Symptoms, diagnosis, and fixes for common apex failure modes.
 weight: 40
 ---

-Failure modes the [engine](/apex/glossary#engine) reports, with the exact log lines it emits.
+Failure modes the [engine](/apex/glossary#engine) reports, with the exact log lines it emits.

-## APEX_NODE_FQDN falls back to the hostname {#fqdn-fallback}
+## APEX_NODE_FQDN falls back to the hostname {#fqdn-fallback}

 **Symptoms:** every action logs `APEX_NODE_FQDN not set in node.env; using hostname '<fqdn>'.`

-**Diagnosis:** `node.env` does not set `APEX_NODE_FQDN`, so the engine derived the FQDN from the OS hostname. On a node whose hostname is the intended FQDN this is harmless; otherwise traefik `Host()` routing will use the wrong name.
+**Diagnosis:** `node.env` does not set `APEX_NODE_FQDN`, so the engine derived the FQDN from the OS hostname. On a node whose hostname is the intended FQDN this is harmless; otherwise traefik `Host()` routing will use the wrong name.

-**Solution:** set `APEX_NODE_FQDN` explicitly in `node.env` at the repository root (for example `APEX_NODE_FQDN=node1.example.com`).
+**Solution:** set `APEX_NODE_FQDN` explicitly in `node.env` at the repository root (for example `APEX_NODE_FQDN=node1.example.com`).

-## Identity exits 66 {#identity-66}
+## Identity exits 66 {#identity-66}

-**Symptoms:** `identity: APEX_NODE_FQDN missing from node.env and no hostname` or `identity: APEX_SUBNET missing from node.env`, exit `66`.
+**Symptoms:** `identity: APEX_NODE_FQDN missing from node.env and no hostname` or `identity: APEX_SUBNET missing from node.env`, exit `66`.

-**Diagnosis:** a required identity field cannot be resolved. The first line means neither `APEX_NODE_FQDN` nor an OS hostname yields an FQDN; the second means `APEX_SUBNET` is absent. The engine refuses to guess.
+**Diagnosis:** a required identity field cannot be resolved. The first line means neither `APEX_NODE_FQDN` nor an OS hostname yields an FQDN; the second means `APEX_SUBNET` is absent. The engine refuses to guess.

-**Solution:** create or complete `node.env` at the repository root — set `APEX_SUBNET`, and set `APEX_NODE_FQDN` (or ensure the OS hostname is usable).
+**Solution:** create or complete `node.env` at the repository root — set `APEX_SUBNET`, and set `APEX_NODE_FQDN` (or ensure the OS hostname is usable).

-## configure/ufw exits 66 {#ufw-66}
+## configure/ufw exits 66 {#ufw-66}

-**Symptoms:** `Rules directory does not exist: ...` or `Config directory does not exist: ...`, exit `66`.
+**Symptoms:** `Rules directory does not exist: ...` or `Config directory does not exist: ...`, exit `66`.

-**Diagnosis:** exactly one of `configs/ufw/docker/` or `configs/ufw/host/` is missing — a broken config layout rather than an intentionally rule-less node.
+**Diagnosis:** exactly one of `configs/ufw/docker/` or `configs/ufw/host/` is missing — a broken config layout rather than an intentionally rule-less node.

-**Solution:** restore the missing directory (empty is acceptable: an empty `docker/` warns `No .rules files found ... nothing to apply.` and continues).
+**Solution:** restore the missing directory (empty is acceptable: an empty `docker/` warns `No .rules files found ... nothing to apply.` and continues).

 ## ufw tooling missing {#ufw-tools}

-**Symptoms:** `ufw not installed/working via sudo. Run configure/base first.` or `ufw-docker not found at ~/.local/bin/ufw-docker. Run configure/base first.`, exit `1`.
+**Symptoms:** `ufw not installed/working via sudo. Run configure/base first.` or `ufw-docker not found at ~/.local/bin/ufw-docker. Run configure/base first.`, exit `1`.

-**Diagnosis:** the firewall layer's prerequisites are absent.
+**Diagnosis:** the firewall layer's prerequisites are absent.

 **Solution:** run `apex configure/base`, then retry `apex configure/ufw`.

-## Crontab install refused or rolled back {#cron}
+## Crontab install refused or rolled back {#cron}

-**Symptoms:** `Rendered crontab is empty; aborting (previous kept).` (exit `65`) or `crontab install failed; restoring previous.` (exit `1`).
+**Symptoms:** `Rendered crontab is empty; aborting (previous kept).` (exit `65`) or `crontab install failed; restoring previous.` (exit `1`).

-**Diagnosis:** the rendered `configs/cron/crontab` was empty (template/variable problem — remember unknown `$VARS` stay literal, they do not blank the file) or `crontab` rejected the syntax.
+**Diagnosis:** the rendered `configs/cron/crontab` was empty (template/variable problem — remember unknown `$VARS` stay literal, they do not blank the file) or `crontab` rejected the syntax.

-**Solution:** inspect the printed preview, fix the template, re-run `apex configure/cron`. The previous crontab is intact in both cases.
+**Solution:** inspect the printed preview, fix the template, re-run `apex configure/cron`. The previous crontab is intact in both cases.

 ## sync/repository aborts {#sync-aborts}

-**Symptoms:** `Commons submodule at <path> has uncommitted changes. Aborting.` or `Directory '<repo>/compositions' does not exist. Cannot sync.`, exit `1`.
+**Symptoms:** `Commons submodule at <path> has uncommitted changes. Aborting.` or `Directory '<repo>/compositions' does not exist. Cannot sync.`, exit `1`.

-**Diagnosis:** the [capture-up](/apex/glossary#capture-up) commit refuses to record a broken checkout — a dirty pinned submodule or a missing [compositions](/apex/glossary#compositions) tree.
+**Diagnosis:** the [capture-up](/apex/glossary#capture-up) commit refuses to record a broken checkout — a dirty pinned submodule or a missing [compositions](/apex/glossary#compositions) tree.

-**Solution:** for a dirty submodule, `git -C commons checkout -- .` (or commit an intentional pin move); for a missing tree, restore the checkout before the next scheduled run.
+**Solution:** for a dirty submodule, `git -C commons checkout -- .` (or commit an intentional pin move); for a missing tree, restore the checkout before the next scheduled run.

 ## Telegram not delivered {#telegram}

-**Symptoms:** `Telegram Bot URL not provided. Skipping notification.` or `Failed to send Telegram notification: <error>` — and notify-gated actions (`backup/run`, `sync/repository`, `sync/packages`) exit `1` even though their work succeeded.
+**Symptoms:** `Telegram Bot URL not provided. Skipping notification.` or `Failed to send Telegram notification: <error>` — and notify-gated actions (`backup/run`, `sync/repository`, `sync/packages`) exit `1` even though their work succeeded.

-**Diagnosis:** the bot URL argument was empty, or the send failed (network, proxy, revoked token). The non-zero exit is deliberate: an unattended run whose status cannot be reported is treated as failed.
+**Diagnosis:** the bot URL argument was empty, or the send failed (network, proxy, revoked token). The non-zero exit is deliberate: an unattended run whose status cannot be reported is treated as failed.

-**Solution:** verify the URL source file the cron line reads, network/proxy reachability, and the bot token; re-run manually to confirm delivery.
+**Solution:** verify the URL source file the cron line reads, network/proxy reachability, and the bot token; re-run manually to confirm delivery.

-## docker compose rejects the core wrapper {#compose-include}
+## docker compose rejects the core wrapper {#compose-include}

-**Symptoms:** `docker compose` errors on the `include` keyword when evaluating `compositions/apex/docker-compose.yml`.
+**Symptoms:** `docker compose` errors on the `include` keyword when evaluating `compositions/apex/docker-compose.yml`.

-**Diagnosis:** the [core composition](/apex/glossary#core-composition) is consumed through `include:`, which requires Docker Compose v2.20+.
+**Diagnosis:** the [core composition](/apex/glossary#core-composition) is consumed through `include:`, which requires Docker Compose v2.20+.

-**Solution:** upgrade the Compose plugin (`docker compose version` to verify).
+**Solution:** upgrade the Compose plugin (`docker compose version` to verify).

 ---

 **See also:**

 - [Reference: CLI](/apex/reference/cli)
- [Guide: Operate a node](/apex/guides/host-operations)
+- [Guide: Operate a node](/apex/guides/host-operations)
 - [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
@@ -6,11 +6,11 @@ cascade:
  type: docs
 ---

-**Quetza** is a modular Discord bot framework built with TypeScript and Discord.js. It transforms feature development from core modification into independent module addition.
+**Quetza** is a modular Discord bot framework built with TypeScript and Discord.js. It transforms feature development from core modification into independent module addition.

 ## Project Vision

-The framework addresses the fundamental challenge of extensible bot design: providing a scalable architecture where functionality can be added without increasing system complexity or coupling.
+The framework addresses the fundamental challenge of extensible bot design: providing a scalable architecture where functionality can be added without increasing system complexity or coupling.

 ## Documentation Sections

@@ -25,6 +25,6 @@ The framework addresses the fundamental challenge of extensible bot design: prov
 ## Key Features

 - **Modular Architecture:** Features are plugins, not core modifications.
- **TypeScript First:** Built for type safety and developer experience.
+- **TypeScript First:** Built for type safety and developer experience.
 - **Zero-Config Discovery:** Filesystem-based module registration.
- **State Management:** Built-in patterns for guild-scoped services.
+- **State Management:** Built-in patterns for guild-scoped services.
@@ -3,7 +3,7 @@ title: Concepts
 weight: 4
 ---

-**Quetza** concepts explain the _Why_ and _How_ behind the framework's design. These documents cover the underlying philosophy and architectural decisions.
+**Quetza** concepts explain the _Why_ and _How_ behind the framework's design. These documents cover the underlying philosophy and architectural decisions.

 ## Key Topics

@@ -3,38 +3,38 @@ title: Architecture & Philosophy
 weight: 1
 ---

-**Goal:** Understand the core design principles that drive Quetza's modularity.
+**Goal:** Understand the core design principles that drive Quetza's modularity.

 ## Design Philosophies

 ### Convention Over Configuration

-Quetza minimizes boilerplate by relying on strict folder structures.
+Quetza minimizes boilerplate by relying on strict folder structures.

- **No central registry:** The filesystem _is_ the registry.
- **Result:** You don't update a config file to add a module; you just create the folder.
+- **No central registry:** The filesystem _is_ the registry.
+- **Result:** You don't update a config file to add a module; you just create the folder.

 ### Composition Over Inheritance

-Modules are composed of capabilities, not inherited from a base class.
+Modules are composed of capabilities, not inherited from a base class.

- **Flexibility:** Modules can use any internal architecture (Functional, OOP) as long as they export the required interfaces.
+- **Flexibility:** Modules can use any internal architecture (Functional, OOP) as long as they export the required interfaces.

 ### Isolation Over Integration

 Modules cannot directly invoke each other.

 - **Why:** Prevents tight coupling.
- **Benefit:** You can delete any module without breaking the rest of the bot.
+- **Benefit:** You can delete any module without breaking the rest of the bot.

 ## Core Entities

 | Entity         | Role                           | Lifecycle                     |
 | :------------- | :----------------------------- | :---------------------------- |
-| **Client**     | Service Locator & Orchestrator | Singleton. Runs the show.     |
-| **Module**     | Namespace for features         | Loaded at startup.            |
+| **Client**     | Service Locator & Orchestrator | Singleton. Runs the show.     |
+| **Module**     | Namespace for features         | Loaded at startup.            |
 | **Command**    | User Interaction Endpoint      | Stateless. Request/Response.  |
-| **Event**      | Reactive Observer              | Subscribed at startup.        |
+| **Event**      | Reactive Observer              | Subscribed at startup.        |
 | **Controller** | State Manager                  | Persists across interactions. |

 ---
@@ -1,15 +1,15 @@
 ---
-title: The Module System
+title: The Module System
 weight: 2
 ---

-**Goal:** Define the vocabulary and mechanics of Quetza's primary abstraction unit.
+**Goal:** Define the vocabulary and mechanics of Quetza's primary abstraction unit.

 ## System Vocabulary

 ### Module Declaration

-The `module.ts` file acts as the manifest. It is the entry point for discovery.
+The `module.ts` file acts as the manifest. It is the entry point for discovery.

 ```typescript
 export const name = 'my-module'; // ID
@@ -18,36 +18,36 @@ export const description = '...'; // Doc

 ### Command Registration

-Occurs during the `ready` event.
+Occurs during the `ready` event.

 1.  Quetza scans all `commands/` folders.
 2.  Compiles `ApplicationCommandData`.
-3.  PUTs the payload to Discord's API.
+3.  PUTs the payload to Discord's API.

 ### Controller Injection

-State is injected, not imported.
+State is injected, not imported.

 ```typescript
 // The framework calls this:
 execute(client, interaction, controller);
 ```

- **Why?** Allows the framework to manage the controller's lifecycle (singleton per module).
+- **Why?** Allows the framework to manage the controller's lifecycle (singleton per module).

 ## State Management Philosophy

-### Ephemeral by Default
+### Ephemeral by Default

 Quetza provides **no built-in database**.

- **Memory:** Controllers store state in JS `Map` or `Set` objects.
- **Restart:** All state is lost when the process exits.
- **Persistence:** Must be implemented manually (e.g., SQLite, Redis) inside the Controller.
+- **Memory:** Controllers store state in JS `Map` or `Set` objects.
+- **Restart:** All state is lost when the process exits.
+- **Persistence:** Must be implemented manually (e.g., SQLite, Redis) inside the Controller.

-### Scope as Key
+### Scope as Key

-State must be keyed by its boundary.
+State must be keyed by its boundary.

 - `Map<GuildID, ...>` - Server specific (Most common).
 - `Map<UserID, ...>` - User specific (DM bots).
@@ -58,7 +58,7 @@ State must be keyed by its boundary.

 - **Validation:** Check permissions/inputs immediately.
 - **User-Facing:** "You don't have permission" (Not "Error: 403").
- **Isolation:** A crash in `/ping` catches itself and doesn't kill the bot.
+- **Isolation:** A crash in `/ping` catches itself and doesn't kill the bot.

 ---

@@ -3,60 +3,60 @@ title: Getting Started
 weight: 1
 ---

-**Quetza** is a modular Discord bot framework built with TypeScript that enables developers to build feature-rich Discord applications through self-contained, composable modules.
+**Quetza** is a modular Discord bot framework built with TypeScript that enables developers to build feature-rich Discord applications through self-contained, composable modules.

-## What is Quetza?
+## What is Quetza?

-Quetza provides an architectural foundation that transforms feature development from core modification into module addition. It solves the problem of rigid bot design by inverting dependency structures—the core knows nothing about modules, yet modules have full access to capabilities through defined contracts.
+Quetza provides an architectural foundation that transforms feature development from core modification into module addition. It solves the problem of rigid bot design by inverting dependency structures—the core knows nothing about modules, yet modules have full access to capabilities through defined contracts.

-## The Core Philosophy
+## The Core Philosophy

-### The Problem
+### The Problem

-Traditional monolithic bots suffer from brittleness. Adding features requires modifying core logic, intertwining dependencies, and managing growing codebases that are difficult to test or change.
+Traditional monolithic bots suffer from brittleness. Adding features requires modifying core logic, intertwining dependencies, and managing growing codebases that are difficult to test or change.

-### The Solution
+### The Solution

-Quetza treats modules as plugins.
+Quetza treats modules as plugins.

- **Zero-Touch Extension:** Add features by creating a folder. No core code modification required.
+- **Zero-Touch Extension:** Add features by creating a folder. No core code modification required.
 - **Isolation:** Modules operate independently.
- **Composition:** Enable/disable features by simply adding or removing module folders.
+- **Composition:** Enable/disable features by simply adding or removing module folders.

 ## High-Level Architecture

-Quetza consists of three primary layers:
+Quetza consists of three primary layers:

-1. **Foundation Layer**: The `Discord.js` client extended with module-aware registries (Commands, Events, Modules). It acts as a service locator.
-2. **Module Layer**: Self-contained feature packages. Each module exposes its own commands and events via a standardized file structure.
+1. **Foundation Layer**: The `Discord.js` client extended with module-aware registries (Commands, Events, Modules). It acts as a service locator.
+2. **Module Layer**: Self-contained feature packages. Each module exposes its own commands and events via a standardized file structure.
 3. **Service Layer**: Optional **Controllers** that manage stateful business logic (e.g., audio players, conversation context) across guilds.

 ## Key Concepts

 ### Mental Model

-To work effectively with Quetza, adopt this framework:
+To work effectively with Quetza, adopt this framework:

- **Modules are Plugins:** Independent folders discovered at runtime.
+- **Modules are Plugins:** Independent folders discovered at runtime.
 - **Commands are Endpoints:** Stateless handlers acting like REST API endpoints.
- **Events are Observers:** Reactive logic subscribing to Discord lifecycle events.
- **Controllers are Services:** Stateful managers bridging the gap between stateless commands and persistent behavior.
+- **Events are Observers:** Reactive logic subscribing to Discord lifecycle events.
+- **Controllers are Services:** Stateful managers bridging the gap between stateless commands and persistent behavior.

 ### System Boundaries

-Understanding constraints is critical for design:
+Understanding constraints is critical for design:

- **No Persistence:** In-memory state is lost on restart. External storage is required for persistence.
+- **No Persistence:** In-memory state is lost on restart. External storage is required for persistence.
 - **No Inter-Module Communication:** Modules cannot directly invoke each other, ensuring loose coupling.
- **No Dynamic Loading:** Modules are loaded only at startup.
+- **No Dynamic Loading:** Modules are loaded only at startup.

 ## Architectural Invariants

-Quetza trades flexibility for predictability through strict conventions:
+Quetza trades flexibility for predictability through strict conventions:

- **Convention-Based Discovery:** Modules _must_ follow the directory structure (`module.ts`, `commands/`, `events/`) to be loaded.
- **Single-Phase Initialization:** All loading happens before the Discord connection is established.
- **Interface Compliance:** All commands and events must export specific interfaces to be registered.
+- **Convention-Based Discovery:** Modules _must_ follow the directory structure (`module.ts`, `commands/`, `events/`) to be loaded.
+- **Single-Phase Initialization:** All loading happens before the Discord connection is established.
+- **Interface Compliance:** All commands and events must export specific interfaces to be registered.

 ---

@@ -3,15 +3,15 @@ title: Guides
 weight: 2
 ---

-**Quetza** guides provide step-by-step instructions for common tasks and workflows. These documents focus on practical application of the framework's concepts.
+**Quetza** guides provide step-by-step instructions for common tasks and workflows. These documents focus on practical application of the framework's concepts.

 ## Core Workflows

-The development and operation of Quetza bots revolve around three primary workflows:
+The development and operation of Quetza bots revolve around three primary workflows:

-1.  **Module Development:** Creating new features by adding self-contained modules.
-2.  **Deployment & Operations:** Running the bot in various environments (Docker, Source).
-3.  **Lifecycle Management:** Maintaining modules from creation to deprecation.
+1.  **Module Development:** Creating new features by adding self-contained modules.
+2.  **Deployment & Operations:** Running the bot in various environments (Docker, Source).
+3.  **Lifecycle Management:** Maintaining modules from creation to deprecation.

 ## Available Guides

@@ -3,26 +3,26 @@ title: Conversational AI Integration
 weight: 4
 ---

-**Goal:** Integrate Large Language Models (LLMs) while managing context and Discord's timeout constraints.
+**Goal:** Integrate Large Language Models (LLMs) while managing context and Discord's timeout constraints.

 ## 1. Context Management Strategy

-Conversations require history to be coherent.
+Conversations require history to be coherent.

 - **Scoping:** `Map<GuildID, Map<UserID, Message[]>>`
  - **Guild Key:** Prevents cross-server leaks.
-  - **User Key:** Prevents cross-user confusion in public channels.
- **Lifecycle:** Implement a rolling window (e.g., last 50 messages) to prevent context bloat.
+  - **User Key:** Prevents cross-user confusion in public channels.
+- **Lifecycle:** Implement a rolling window (e.g., last 50 messages) to prevent context bloat.

 ## 2. Response Streaming

-LLMs are slow; Discord is fast (3s timeout).
+LLMs are slow; Discord is fast (3s timeout).

 {{% steps %}}

 ### Step 1: Defer Interaction

-Immediately call `interaction.deferReply()`. This buys you 15 minutes.
+Immediately call `interaction.deferReply()`. This buys you 15 minutes.

 ### Step 2: Invoke LLM

@@ -53,4 +53,4 @@ export async function execute(interaction, controller) {

 > [!WARNING]
 > **API Costs:**
-> AI APIs are often billed by token. Implement strict user-based rate limits in your Controller to prevent abuse.
+> AI APIs are often billed by token. Implement strict user-based rate limits in your Controller to prevent abuse.
@@ -3,31 +3,31 @@ title: Deployment & Operations
 weight: 2
 ---

-**Goal:** Configure, deploy, and monitor a Quetza bot instance.
+**Goal:** Configure, deploy, and monitor a Quetza bot instance.

 ## 1. Environment Preparation

-Quetza relies on environment variables for configuration. **Never** commit these to version control.
+Quetza relies on environment variables for configuration. **Never** commit these to version control.

 | Variable        | Description                                   | Required |
 | :-------------- | :-------------------------------------------- | :------- |
-| `DISCORD_TOKEN` | Bot token from Discord Developer Portal       | **Yes**  |
-| `CLIENT_ID`     | Application ID for slash command registration | **Yes**  |
-| `LLAMA_API_KEY` | Required if using the AI module               | No       |
+| `DISCORD_TOKEN` | Bot token from Discord Developer Portal       | **Yes**  |
+| `CLIENT_ID`     | Application ID for slash command registration | **Yes**  |
+| `LLAMA_API_KEY` | Required if using the AI module               | No |

 ## 2. Deployment Strategies

 {{< tabs >}}
 {{< tab name="Docker (Recommended)" >}}
-**Docker** ensures a consistent runtime environment.
+**Docker** ensures a consistent runtime environment.

-1.  **Build** the image:
+1.  **Build** the image:

    ```bash
    docker build -t quetza-bot .
    ```

-2.  **Run** the container:
+2.  **Run** the container:
    `bash
 docker run -d \
  --env-file .env \
@@ -36,7 +36,7 @@ docker run -d \
 `
    {{< /tab >}}
    {{< tab name="Source" >}}
-    **Source** deployment is useful for development.
+    **Source** deployment is useful for development.

 3.  **Install** dependencies:

@@ -44,13 +44,13 @@ docker run -d \
    pnpm install
    ```

-4.  **Build** the project:
+4.  **Build** the project:

    ```bash
    pnpm build
    ```

-5.  **Start** the bot:
+5.  **Start** the bot:
    `bash
 pnpm start
 `
@@ -59,15 +59,15 @@ pnpm start

 ## 3. Operational Monitoring

-Once running, use these mechanisms to check health:
+Once running, use these mechanisms to check health:

- **Logs:** Check standard output (Docker logs) for initialization errors.
- **`/ping` Command:** Verifies network latency and API responsiveness.
- **`/modules` Command:** Lists all loaded modules to confirm feature availability.
+- **Logs:** Check standard output (Docker logs) for initialization errors.
+- **`/ping` Command:** Verifies network latency and API responsiveness.
+- **`/modules` Command:** Lists all loaded modules to confirm feature availability.

 > [!WARNING]
 > **Scaling Constraint:**
-> Quetza follows a single-instance-per-token model. Do not run multiple instances with the same token, as this will cause WebSocket conflicts.
+> Quetza follows a single-instance-per-token model. Do not run multiple instances with the same token, as this will cause WebSocket conflicts.

 ---

@@ -3,19 +3,19 @@ title: Module Development Workflow
 weight: 1
 ---

-**Goal:** Create a new feature for the Quetza bot by implementing a self-contained module.
+**Goal:** Create a new feature for the Quetza bot by implementing a self-contained module.

 ## 1. Conceptualization Phase

-Before writing code, determine the module's architecture:
+Before writing code, determine the module's architecture:

- **Simple Command:** Needs only a `commands/` folder (e.g., utility commands).
- **Reactive Logic:** Needs `events/` to listen to Discord lifecycles (e.g., welcome messages).
- **Stateful Feature:** Needs a **Controller** to manage state across guilds (e.g., music player).
+- **Simple Command:** Needs only a `commands/` folder (e.g., utility commands).
+- **Reactive Logic:** Needs `events/` to listen to Discord lifecycles (e.g., welcome messages).
+- **Stateful Feature:** Needs a **Controller** to manage state across guilds (e.g., music player).

 ## 2. Structure Establishment

-Create the module directory structure. The presence of these files triggers automatic discovery.
+Create the module directory structure. The presence of these files triggers automatic discovery.

 {{< filetree/container >}}
 {{< filetree/folder name="src" state="open" >}}
@@ -34,9 +34,9 @@ Create the module directory structure. The presence of these files triggers auto

 {{% steps %}}

-### Step 1: Create the Manifest
+### Step 1: Create the Manifest

-Create `module.ts` to declare the module.
+Create `module.ts` to declare the module.

 ```typescript
 // src/modules/my-feature/module.ts
@@ -47,7 +47,7 @@ export const description = 'Adds cool feature capabilities';

 ### Step 2: Implement Commands

-Create command files in `commands/`. Each file exports data and an executor.
+Create command files in `commands/`. Each file exports data and an executor.

 ```typescript
 // src/modules/my-feature/commands/ping.ts
@@ -62,7 +62,7 @@ export async function execute(interaction) {

 ### Step 3: Implement Events (Optional)

-Create event handlers in `events/` to observe Discord state.
+Create event handlers in `events/` to observe Discord state.

 ```typescript
 // src/modules/my-feature/events/ready.ts
@@ -78,14 +78,14 @@ export function execute(client) {

 ### Step 4: Define Controller (Optional)

-For stateful logic, implement a controller in `lib/` and export it in `module.ts`.
+For stateful logic, implement a controller in `lib/` and export it in `module.ts`.

 ### Step 5: Validate

-Restart the bot.
+Restart the bot.

-1.  Check logs for "Loaded module: my-feature".
-2.  Verify the command `/ping` appears in Discord.
+1.  Check logs for "Loaded module: my-feature".
+2.  Verify the command `/ping` appears in Discord.

 {{% /steps %}}

@@ -3,37 +3,37 @@ title: Interactive Voice Features
 weight: 3
 ---

-**Goal:** Implement sophisticated voice interactions that respect guild boundaries and manage ephemeral resources.
+**Goal:** Implement sophisticated voice interactions that respect guild boundaries and manage ephemeral resources.

 ## 1. Resource Scoping Strategy

-Voice features **MUST** be scoped to the Guild.
+Voice features **MUST** be scoped to the Guild.

- **Pattern:** The Controller maintains a `Map<GuildID, Player>`.
+- **Pattern:** The Controller maintains a `Map<GuildID, Player>`.
 - **Behavior:**
-  - **Join:** Create a Player for `Guild A` if none exists.
-  - **Leave:** Destroy the Player and release connections.
-  - **Isolation:** Commands in `Guild B` never affect `Guild A`.
+  - **Join:** Create a Player for `Guild A` if none exists.
+  - **Leave:** Destroy the Player and release connections.
+  - **Isolation:** Commands in `Guild B` never affect `Guild A`.

 ## 2. Command Orchestration

-Voice features require a suite of commands coordinated via the Controller.
+Voice features require a suite of commands coordinated via the Controller.

 | Command | Action             | Controller Logic                    |
 | :------ | :----------------- | :---------------------------------- |
-| `/join` | Connect to channel | `createPlayer(guildId, channelId)`  |
-| `/play` | Add track to queue | `getPlayer(guildId).enqueue(track)` |
+| `/join` | Connect to channel | `createPlayer(guildId, channelId)`  |
+| `/play` | Add track to queue | `getPlayer(guildId).enqueue(track)` |
 | `/stop` | Disconnect         | `destroyPlayer(guildId)`            |

 ## 3. State Persistence

 Audio sessions are ephemeral.

- **Transient State:** Active audio stream (Lost on disconnect).
- **Durable State:** Queue/Playlist (Persisted in Controller until restart).
+- **Transient State:** Active audio stream (Lost on disconnect).
+- **Durable State:** Queue/Playlist (Persisted in Controller until restart).

 > [!TIP]
-> **Resilience:** Separate the _Queue_ logic from the _Voice Connection_ logic. This allows the bot to reconnect without losing the user's playlist.
+> **Resilience:** Separate the _Queue_ logic from the _Voice Connection_ logic. This allows the bot to reconnect without losing the user's playlist.

 ## 4. Implementation Sketch

@@ -3,7 +3,7 @@ title: Troubleshooting
 weight: 5
 ---

-**Quetza** troubleshooting focuses on diagnosing structural and conceptual issues. Because of its convention-based nature, most errors are silent (missing files) rather than noisy (stack traces).
+**Quetza** troubleshooting focuses on diagnosing structural and conceptual issues. Because of its convention-based nature, most errors are silent (missing files) rather than noisy (stack traces).

 ## Common Issue Categories

@@ -3,39 +3,39 @@ title: Diagnostics Guide
 weight: 1
 ---

-**Goal:** Identify and fix common pitfalls in Quetza development.
+**Goal:** Identify and fix common pitfalls in Quetza development.

 ## 1. Module Discovery Failures

-**Symptom:** The bot starts, but my module is ignored.
-**Cause:** Violation of filesystem conventions.
+**Symptom:** The bot starts, but my module is ignored.
+**Cause:** Violation of filesystem conventions.

 {{% details title="Checklist: Directory Structure" closed="false" %}}

 - [ ] Does `src/modules/<name>/` exist?
 - [ ] Does `module.ts` export `name`?
- [ ] Are commands in `commands/` (not `cmds/`)?
- [ ] Did you run `pnpm build`? (Quetza runs from `dist/`).
+- [ ] Are commands in `commands/` (not `cmds/`)?
+- [ ] Did you run `pnpm build`? (Quetza runs from `dist/`).
      {{% /details %}}

 ## 2. Command Registration Issues

-**Symptom:** `/command` does not appear in Discord.
+**Symptom:** `/command` does not appear in Discord.

 ### Global vs. Test Guild Registration

- **Global:** Commands pushed to the application globally can take up to 1 hour to propagate and are subject to stricter rate limits.
- **Test Guild:** Quetza automatically pushes commands to a specific guild in development mode for instant updates.
-  - **Requirement:** Ensure `NODE_ENV=development` and `DEV_GUILD_ID` is correctly set in your `.env`.
+- **Global:** Commands pushed to the application globally can take up to 1 hour to propagate and are subject to stricter rate limits.
+- **Test Guild:** Quetza automatically pushes commands to a specific guild in development mode for instant updates.
+  - **Requirement:** Ensure `NODE_ENV=development` and `DEV_GUILD_ID` is correctly set in your `.env`.

 ### Rate Limits

-Frequent updates to global commands may trigger Discord's rate limits. Use a test guild for iterative development.
+Frequent updates to global commands may trigger Discord's rate limits. Use a test guild for iterative development.

 ## 3. Interaction Failures

-**Symptom:** "The application did not respond".
-**Cause:** Command took > 3 seconds without deferral.
+**Symptom:** "The application did not respond".
+**Cause:** Command took > 3 seconds without deferral.

 **Solution:**

@@ -53,21 +53,21 @@ await interaction.editReply('Done');
 ## 4. State Management Leaks

 **Symptom:** Bot memory usage grows; cross-server weirdness.
-**Cause:** Storing state globally instead of per-guild.
+**Cause:** Storing state globally instead of per-guild.

 **Diagnostic:**
 Check your Controller.

- ❌ `private player: AudioPlayer;` (Shared by everyone!)
- ✅ `private players = new Map<string, AudioPlayer>();` (Scoped by ID).
+- ❌ `private player: AudioPlayer;` (Shared by everyone!)
+- ✅ `private players = new Map<string, AudioPlayer>();` (Scoped by ID).

 ## 5. Event Handling

-**Symptom:** Events fire multiple times or not at all.
+**Symptom:** Events fire multiple times or not at all.

- **Multiple:** Events are additive. Did you register the same handler in two modules?
- **None:** Did you export `name` and `execute` correctly?
+- **Multiple:** Events are additive. Did you register the same handler in two modules?
+- **None:** Did you export `name` and `execute` correctly?

 > [!TIP]
 > **Debug Mode:**
-> Enable verbose logging to see exactly which modules and commands are loaded at startup.
+> Enable verbose logging to see exactly which modules and commands are loaded at startup.
@@ -8,15 +8,15 @@ layout: hextra-home

 <div class="hx:mb-6">
 {{< hextra/hero-headline >}}
-Документация решений<br class="hx:sm:block hx:hidden" />без&nbsp;решений как&nbsp;таковых
+Документация решений<br class="hx:sm:block hx:hidden" />без решений как таковых
 {{< /hextra/hero-headline >}}
 </div>

 <div class="hx:mb-6">
 {{< hextra/hero-subtitle >}}
-У&nbsp;меня нет ни&nbsp;времени, ни&nbsp;желания вручную выписывать каждую строчку этого недоромана. Однако фиксировать контекст и&nbsp;принятые решения нужно, иначе число сущностей, понимающих происходящее, упадёт до&nbsp;нуля. Считайте это структурированной нейробазой для&nbsp;агентов и&nbsp;редких живых гостей.
+У меня нет ни времени, ни желания вручную выписывать каждую строчку этого недоромана. Однако фиксировать контекст и принятые решения нужно, иначе число сущностей, понимающих происходящее, упадёт до нуля. Считайте это структурированной нейробазой для агентов и редких живых гостей.
 <br /><br />
-А&nbsp;если вдруг захотите что-то исправить (зачем?)&nbsp;— любой вклад здесь пойдёт на&nbsp;пользу.
+А если вдруг захотите что-то исправить (зачем?) — любой вклад здесь пойдёт на пользу.
 {{< /hextra/hero-subtitle >}}
 </div>

@@ -46,7 +46,7 @@ layout: hextra-home
 <div class="hx:overflow-hidden hx:border hx:border-gray-200 hx:dark:border-neutral-800 hx:shadow-lg hx:bg-gray-50 hx:dark:bg-neutral-900/50" style="border-radius: 1.5rem; height: 100%; display: flex; flex-direction: column;">
 <img src="https://static.ermnvldmr.com/docs/images/home/dead-internet-debugging.webp" alt="Dead Internet Debugging" class="hx:w-full" style="flex: 1 1 auto; width: 100%; height: 100%; min-height: 340px; object-fit: cover; object-position: top; border-radius: 1.5rem 1.5rem 0 0;" />
 <div class="hx:p-3 hx:text-xs hx:text-gray-500 hx:dark:text-gray-400 hx:text-center hx:border-t hx:border-gray-200 hx:dark:border-neutral-800" style="flex-shrink: 0;">
-Изображение улучшено с&nbsp;помощью Gemini&nbsp;4&nbsp;Argon&nbsp;· <a href="https://www.reddit.com/r/ProgrammerHumor/s/UVVd1CnFxH" target="_blank" rel="noreferrer" class="hx:underline hx:hover:text-primary-600">Оригинал на&nbsp;Reddit</a>
+Изображение улучшено с помощью Gemini 4 Argon · <a href="https://www.reddit.com/r/ProgrammerHumor/s/UVVd1CnFxH" target="_blank" rel="noreferrer" class="hx:underline hx:hover:text-primary-600">Оригинал на Reddit</a>
 </div>
 </div>
 </div>