fix(studio): count pages, not items, in organize-imports button

The "Create" CTA used totalSelected (the sum of furni items across
approved groups) as its plural count, so with many imported items it
claimed to create thousands of pages. One approved group creates exactly
one page, so the label now counts approved groups instead.

.dockerignore

@@ -0,0 +1,46 @@
+.git
+.gitignore
+.next
+node_modules
+coverage
+storage
+prod.log
+update.log
+.pm2
+# Only the pnpm lockfile is used. Ignore other lockfile formats and stray
+# package managers so they never taint the build context by accident.
+package-lock.json
+yarn.lock
+bun.lockb
+.npmrc.bak
+# Installation secrets must never enter any image layer (including migrations).
+.env
+.env.*
+**/.env
+**/.env.*
+!.env.example
+*.pem
+*.key
+*.tsbuildinfo
+# Runtime write targets; bound as RW volumes at runtime (see docker-compose.yml)
+public/nitro-assets
+public/swf
+
+.deploy.lock
+logs
+
+# Other installation data and local tool artifacts
+public/cache
+public/tmp
+db_backup_*.sql
+*.log
+.codex
+.agents
+
+.docker-install
+.docker-install.tmp.*
+.env.install.*
+build-reports
+test-results
+playwright-report
+blob-report

.env.example

@@ -1,95 +1,86 @@
-# Connection to the LIVE/COPY emulator MySQL/MariaDB database.
-# The schema is owned by the Arcturus emulator — this app reads/writes data,
-# it does NOT own or migrate the emulator tables. Format:
-DATABASE_URL=mysql://user:[email protected]:3306/atomcms
+# ==============================================================================
+# Epicnextcms — Ultimate Speed & Low-Latency Example Configuration
+# ==============================================================================
 
-# Optional pool tuning (defaults shown)
-DATABASE_POOL_SIZE=10
-DATABASE_IDLE_TIMEOUT_MS=300000
-DATABASE_CONNECT_TIMEOUT_MS=10000
+# --- DATABASE (High Performance Pooling & Strict Timeouts) ---
+DATABASE_URL="mysql://user:password@localhost:3306/dbname?charset=utf8mb4&connection_limit=150&connect_timeout=5"
+DATABASE_POOL_SIZE=150
+DATABASE_IDLE_TIMEOUT_MS=60000
+DATABASE_CONNECT_TIMEOUT_MS=5000
 
-# Redis for rate limits, site-settings cache, and JWT invalidation
-# REDIS_URL=redis://localhost:6379
+# --- REDIS (Lightning Fast Caching & Sessions) ---
+REDIS_URL=redis://127.0.0.1:6379?connect_timeout=2
+REDIS_CACHE_TTL_DEFAULT=7200
 
-# Used by SSO ticket generation ({HOTEL_NAME}-{uuid})
-HOTEL_NAME=Atom
-APP_URL=http://localhost:3000
-# NEXT_PUBLIC_APP_URL=https://yourdomain.com
-AUTH_URL=http://localhost:3000
+# --- CORE RUNTIME & PERFORMANCE FLAGS ---
+NODE_ENV=production
+PORT=3002
+NEXT_TELEMETRY_DISABLED=1
+UV_THREADPOOL_SIZE=16
+# Production requires this kill switch plus housekeeping.preview.access.
+HOUSEKEEPING_NEXT_PREVIEW_ENABLED=false
 
-# NextAuth — required in production (>=32 chars). Optional in development.
-# Laravel APP_KEY (base64:...) for existing 2FA secrets.
-AUTH_SECRET=
-APP_KEY=
-CONVERT_PASSWORDS=false
+# --- HOTEL & URLS ---
+HOTEL_NAME=EPIC WEB CONTROL
+APP_URL=http://localhost:3002
+AUTH_URL=http://localhost:3002
 
-# Password hashing for NEW/upgraded passwords: "bcrypt" (default; 60-char $2y$,
-# fits a varchar(64) users.password) or "argon2id" (~97 chars, needs a wider
-# column). Existing accounts in either format still verify on login.
-PASSWORD_HASH=bcrypt
+# --- IMAGER ---
+# Avatar imager: Polaris-imager (avatar-imaging-pixinode) serves /avatarimage on 8082.
+IMAGING_UPSTREAM_URL=http://127.0.0.1:8082/avatarimage
+# Runtime values: changing these only requires recreating the container.
+IMAGER_URL=http://127.0.0.1:8082/avatarimage
+BADGE_URL=/swf/c_images/album1584
+# Legacy NEXT_PUBLIC_IMAGER_URL / NEXT_PUBLIC_BADGE_URL are still read at runtime.
 
-# Filesystem directory the badge uploader (/admin/badges) writes <code>.gif into
-# — the emulator's badge image folder (e.g. .../assets/c_images/album1584).
-# Leave unset to disable badge uploads.
-BADGE_UPLOAD_DIR=
+# --- SECURITY & HASHING ---
+AUTH_SECRET=your-super-secret-auth-key-change-this-min-32-chars
+APP_KEY=base64:your-app-key-here=
+CONVERT_PASSWORDS=true
+# CONVERT_PASSWORDS: enables legacy md5/argon2id -> bcrypt upgrade on login.
+BCRYPT_COST=12
 
-# Emulator JAR backup job (jobs-worker, runs host-side). When both are set, the
-# worker copies the JAR daily into the backup dir, keeping the newest N.
-EMULATOR_JAR_PATH=
-EMULATOR_BACKUP_DIR=
+# --- PATHS ---
+BADGE_UPLOAD_DIR=./public/assets/images/badges
+EMULATOR_JAR_PATH=./emulator/Arcturus.jar
+EMULATOR_BACKUP_DIR=./backups/emulator
 EMULATOR_BACKUP_KEEP=7
+# Optional mysqldump (jobs-worker daily 03:30). Requires mysqldump on PATH.
+DB_BACKUP_DIR=
+DB_BACKUP_KEEP=7
+# Minutes between repeat health-fail alerts from jobs-worker (default 15).
+HEALTH_ALERT_COOLDOWN_MIN=15
 
-# RCON link to the Arcturus emulator
+# --- RCON (Low Latency Loop) ---
 RCON_HOST=127.0.0.1
-RCON_PORT=3001
+RCON_PORT=3003
+EMU_PORT=3004
+RCON_TIMEOUT_MS=2000
 
-# Public imager URL — overrides the default /imaging relative path.
-# Falls back to NEXT_PUBLIC_APP_URL/imaging when only the app URL is set.
-# NEXT_PUBLIC_IMAGER_URL=https://epicnabbo.nl/imaging
-
-# Preferred email provider (HTTP API). Used before SMTP when set.
-RESEND_API_KEY=
-
-# Optional SMTP fallback (password reset / alert emails)
+# --- EMAIL & NOTIFICATIONS ---
 SMTP_HOST=
 SMTP_PORT=587
 SMTP_USER=
 SMTP_PASSWORD=
-SMTP_FROM=
+SMTP_FROM=[email protected]
 
-# Optional alerting (jobs worker / alert service)
+# --- ALERTING & MONITORING ---
 DISCORD_WEBHOOK_URL=
 ALERT_EMAIL=
 
-# Optional AI content moderation (user comments / guestbook).
-# When set, posts are checked against the OpenAI Moderations endpoint in
-# addition to the website_wordfilter blocklist. Fail-open if unset/erroring.
+# --- MODERATION & PAYMENTS ---
 OPENAI_API_KEY=
-
-# Optional PayPal top-up (sandbox by default)
 PAYPAL_CLIENT_ID=
 PAYPAL_SECRET=
 PAYPAL_API=https://api-m.sandbox.paypal.com
 
-# Redis — REQUIRED for production (shared rate limits, site-settings cache,
-# JWT session invalidation cache). Without REDIS_URL the app falls back to
-# in-process memory: limits reset on restart and do not work across instances.
-# Deploy logs a loud warning when this is unset in production.
-REDIS_URL=redis://127.0.0.1:6379
+# --- LOGGING ---
+LOG_LEVEL=error
 
-# Logging level (debug | info | warn | error). Defaults to 'info' in production,
-# 'debug' in development. Production logs use structured JSON via pino.
-LOG_LEVEL=info
+# --- BYPARR (Cloudflare bypass for clone sources) ---
+BYPARR_URL=http://localhost:8191
 
-# Optional Sentry error monitoring (no-op when unset).
-# Server/edge use SENTRY_DSN; browser uses NEXT_PUBLIC_SENTRY_DSN.
-SENTRY_DSN=
-NEXT_PUBLIC_SENTRY_DSN=
-# Optional source-map upload during CI builds (requires SENTRY_AUTH_TOKEN).
-SENTRY_ORG=
-SENTRY_PROJECT=
-SENTRY_AUTH_TOKEN=
-# Optional release tag shown in Sentry (e.g. git sha).
-# Deploy sets APP_VERSION + NEXT_PUBLIC_APP_VERSION from git sha.
-APP_VERSION=
-NEXT_PUBLIC_APP_VERSION=
+# Catalog Studio export: dedicated clean clone on Beta-3 with Git push credentials.
+CATALOG_GIT_CHECKOUT=
+# Persistent directory shared by CMS and worker, outside the catalog clone.
+CATALOG_GIT_STATE_DIR=

.gitattributes

@@ -0,0 +1,2 @@
+.husky/* text eol=lf
+*.sh text eol=lf

.gitea/workflows/ci.yaml

@@ -1,41 +1,131 @@
 name: CI
+
 on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
   pull_request:
-    branches:
-      - main
+    branches: [main, master]
+  workflow_dispatch:
 
 jobs:
+  # ─────────────────────────────────────────────
+  # Lint, typecheck & unit tests
+  # Draait op de host (self-hosted) waar Node 26 +
+  # pnpm 11 geïnstalleerd zijn en internet beschikbaar is.
+  # De job-container (docker mode) heeft GEEN outbound
+  # internet, dus we draaien alles direct op de host.
+  # ─────────────────────────────────────────────
   check:
-    runs-on: shell
+    runs-on: self-hosted
     steps:
-      - name: Typecheck, lint, and test
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Toolchain check
+        run: node scripts/check-node-toolchain.mjs
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Dependency security audit
+        run: pnpm deps:audit
+
+      - name: Lint
+        run: pnpm biome:lint
+
+      - name: CMS translation contracts
+        run: pnpm i18n:check
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        env:
+          SKIP_ENV_VALIDATION: 1
+          NODE_ENV: test
+          DATABASE_URL: "mysql://test:test@localhost:3306/test?charset=utf8mb4"
+          REDIS_URL: "redis://127.0.0.1:6379?connect_timeout=2"
+          AUTH_SECRET: "ci-test-secret-key-that-is-long-enough"
+          BCRYPT_ROUNDS: 4
         run: |
-          set -e
-          WORK="$(mktemp -d /var/tmp/epicnext-ci.XXXXXX)"
-          cleanup() { rm -rf "${WORK}"; }
-          trap cleanup EXIT
-
-          echo "--- CI checks (${WORK}) ---"
-          git clone --depth 50 \
-            /docker/gitea/gitea/git/repositories/remco/epicnext-cms.git \
-            "${WORK}"
-          cd "${WORK}"
-
-          REF="${{ gitea.sha }}"
-          if [ -z "${REF}" ]; then
-            echo "ERROR: missing gitea.sha" >&2
-            exit 1
+          if [ -x /usr/bin/time ]; then
+            /usr/bin/time -f 'Tests: %e seconds; peak process RSS: %M KiB' pnpm test:coverage --maxWorkers=4
+          else
+            time pnpm test:coverage --maxWorkers=4
           fi
-          git fetch --depth 50 origin "${REF}"
-          git checkout -f "${REF}"
 
-          export SKIP_ENV_VALIDATION=1
-          export ARGON2_MEMORY_SIZE=1024
-          export ARGON2_ITERATIONS=1
-          export BCRYPT_ROUNDS=4
-          pnpm install --frozen-lockfile
-          pnpm prisma:generate
-          pnpm biome:lint
-          pnpm typecheck
-          pnpm test
-          echo "--- CI checks passed ---"
+      # Compare against reviewed Linux references; updates are explicit.
+      - name: Install UI test browser
+        run: pnpm exec playwright install chromium
+
+      - name: Accessibility and UI regression checks
+        run: pnpm test:ui
+
+      - name: Upload UI results
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: ui-results
+          path: |
+            e2e/ui/__screenshots__/linux/
+            playwright-report/ui/
+            test-results/ui/
+          retention-days: 14
+
+  # ─────────────────────────────────────────────
+  # Docker build & deploy
+  # Draait op de host (self-hosted) zodat Docker
+  # toegang heeft tot de daemon en volumes.
+  # ─────────────────────────────────────────────
+  deploy:
+    needs: check
+    if: gitea.event_name == 'push' && (gitea.ref_name == 'main' || gitea.ref_name == 'master')
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Build, deploy and smoke test
+        shell: bash
+        env:
+          DEPLOY_BRANCH: ${{ gitea.ref_name }}
+        run: bash scripts/ci-deploy.sh
+
+      - name: Upload JavaScript size report
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: javascript-size-report
+          path: build-reports/
+          if-no-files-found: warn
+          retention-days: 14
+
+  # Publish only after checks and the production deployment have succeeded.
+  # Serial execution also avoids two builds competing on the self-hosted runner.
+  publish-container:
+    needs: deploy
+    if: gitea.event_name == 'push' && (gitea.ref_name == 'main' || gitea.ref_name == 'master')
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Build, verify portability and publish
+        shell: bash
+        env:
+          REGISTRY_SERVER: ${{ gitea.server_url }}
+          REGISTRY_REPOSITORY: ${{ gitea.repository }}
+          REGISTRY_NAMESPACE: ${{ vars.CONTAINER_REGISTRY_NAMESPACE }}
+          REGISTRY_USER: ${{ secrets.CONTAINER_REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.CONTAINER_REGISTRY_TOKEN }}
+        run: bash scripts/publish-container.sh

.gitea/workflows/container.yaml

@@ -0,0 +1,35 @@
+name: Publish portable container
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+      - name: Install and verify
+        run: |
+          node scripts/check-node-toolchain.mjs
+          pnpm install --frozen-lockfile
+          pnpm typecheck
+          pnpm biome:lint
+          pnpm test:coverage
+        env:
+          SKIP_ENV_VALIDATION: 1
+          NODE_ENV: test
+          DATABASE_URL: mysql://test:[email protected]:9/test
+          AUTH_SECRET: container-test-secret-at-least-32-characters
+      - name: Build, verify portability and publish
+        shell: bash
+        env:
+          REGISTRY_SERVER: ${{ gitea.server_url }}
+          REGISTRY_REPOSITORY: ${{ gitea.repository }}
+          REGISTRY_NAMESPACE: ${{ vars.CONTAINER_REGISTRY_NAMESPACE }}
+          REGISTRY_USER: ${{ secrets.CONTAINER_REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.CONTAINER_REGISTRY_TOKEN }}
+        run: bash scripts/publish-container.sh

.gitea/workflows/deploy.yaml

@@ -1,417 +0,0 @@
-name: Deploy
-on:
-  push:
-    branches:
-      - main
-    tags:
-      - "v*"
-jobs:
-  release:
-    if: startsWith(gitea.ref_name, 'v')
-    runs-on: shell
-    steps:
-      - name: Create Release
-        env:
-          VERSION: ${{ gitea.ref_name }}
-          GITEA_API: ${{ gitea.api_url }}
-          GITEA_REPO: ${{ gitea.repository }}
-        run: |
-          set -e
-          exec 2>&1
-          BARE="/docker/gitea/gitea/git/repositories/remco/epicnext-cms.git"
-          echo "=== Creating release for ${VERSION} ==="
-
-          PREV_TAG="$(git -C "$BARE" tag --sort=-creatordate | head -2 | tail -1 || echo '')"
-
-          if [ -n "$PREV_TAG" ] && [ "$PREV_TAG" != "$VERSION" ]; then
-            CHANGELOG="$(git -C "$BARE" log --oneline --no-decorate --max-count=50 "${PREV_TAG}..${VERSION}")"
-            [ -z "$CHANGELOG" ] && CHANGELOG="No commit changes since ${PREV_TAG}"
-          else
-            TOTAL="$(git -C "$BARE" rev-list --count "${VERSION}" 2>/dev/null || echo '?')"
-            CHANGELOG="Initial release of EpicNext-CMS (${TOTAL} commits)."
-          fi
-          [ -z "$CHANGELOG" ] && CHANGELOG="Initial release"
-
-          # Pin the other components at their current commits so the release is reproducible.
-          CAT_REF="$(git ls-remote https://gitlab.epicnabbo.nl/remco/Epicnabbo-Catalogus-Updated-Daily.git Beta-3 2>/dev/null | awk '{print $1}')"
-          NITRO_REF="$(git ls-remote https://github.com/duckietm/Nitro-V3.git main 2>/dev/null | awk '{print $1}')"
-          RENDER_REF="$(git ls-remote https://github.com/duckietm/Nitro_Render_V3.git main 2>/dev/null | awk '{print $1}')"
-          EMU_REF="$(git ls-remote https://github.com/duckietm/Polaris-Emulator.git main 2>/dev/null | awk '{print $1}')"
-
-          {
-            echo "# EpicNext-CMS ${VERSION}"
-            echo ""
-            echo "> Modern, high-performance CMS for Habbo hotel emulators — built on Next.js 16, React 19 and Prisma 7. Integrates with Polaris / Arcturus Morningstar databases."
-            echo ""
-            echo "## Menu"
-            echo "- [What is EpicNext-CMS?](#what-is-epicnext-cms)"
-            echo "- [System Requirements](#system-requirements)"
-            echo "- [Installation Wizard](#installation-wizard)"
-            echo "- [How it is used](#how-it-is-used)"
-            echo "- [Changes](#changes)"
-            echo "- [Linked repositories](#linked-repositories)"
-            echo ""
-            echo '<a id="what-is-epicnext-cms"></a>'
-            echo "## What is EpicNext-CMS?"
-            echo ""
-            echo "EpicNext-CMS is a full public-facing hotel website plus an administrative panel. It features NextAuth authentication (argon2id/bcrypt with MD5 upgrade), real-time RCON communication with the emulator, Server-Sent Events for live radio, smooth page transitions and extensive extensibility. Full documentation: https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/README.md"
-            echo ""
-            echo '<a id="system-requirements"></a>'
-            echo "## System Requirements"
-            echo ""
-            echo "What you need to install before running the CMS:"
-            echo ""
-            echo "| Component | Version | Notes |"
-            echo "| --------- | ------- | ----- |"
-            echo "| Node.js | >= 22 | Required by Next.js 16 |"
-            echo "| pnpm | >= 10.33.4 | Package manager (npm/yarn not supported) |"
-            echo "| MySQL / MariaDB | 8.0+ / 10.6+ | Shared with the emulator |"
-            echo "| Redis | 7.x+ | Optional — caching, rate limiting, SSE |"
-            echo "| Java | 17+ | Only if building the emulator |"
-            echo "| Maven | 3.9+ | Only if building the emulator |"
-            echo ""
-            echo "The CMS shares its database with the Polaris / Arcturus emulator. It only reads/writes emulator-owned tables and never alters them."
-            echo ""
-            echo '<a id="installation-wizard"></a>'
-            echo "## Installation Wizard"
-            echo ""
-            echo "A complete hotel stack = **EpicNext-CMS** (this repo) + **Polaris Emulator** + **Nitro V3 client** + **Catalogus** data. Follow the steps in order."
-            echo ""
-            echo "**Quick links:** [Full setup guide](https://github.com/duckietm/Complete-Retro-on-Ubuntu) · [EpicNext-CMS repo](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms) · [Reference configs in this repo](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/setup)"
-            echo ""
-            echo "### 1. Clone & Install the CMS"
-            echo '```bash'
-            echo "git clone https://gitlab.epicnabbo.nl/remco/EpicNext-Cms.git"
-            echo "cd EpicNext-Cms"
-            echo "pnpm install"
-            echo '```'
-            echo ""
-            echo "### 2. Database Setup"
-            echo ""
-            echo "The CMS shares the emulator database. Import the Polaris/Arcturus database first, then create the CMS schema:"
-            echo '```sql'
-            echo "CREATE DATABASE IF NOT EXISTS epicnext_cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
-            echo '```'
-            echo ""
-            echo "### 3. Configure Environment"
-            echo '```bash'
-            echo "cp .env.example .env"
-            echo '```'
-            echo ""
-            echo "Edit .env with at minimum: DATABASE_URL, AUTH_SECRET, HOTEL_NAME and APP_URL. See .env.example for RCON, email, Redis, OAuth and PayPal options."
-            echo ""
-            echo "### 4. Generate Prisma Client"
-            echo '```bash'
-            echo "pnpm prisma:generate"
-            echo '```'
-            echo ""
-            echo "### 5. Run CMS Migrations"
-            echo '```bash'
-            echo "pnpm db:migrate"
-            echo '```'
-            echo ""
-            echo "Creates all CMS-owned tables (website_*, radio_*, acl_*, admin_audit_log). Emulator tables are never touched. Check status with pnpm db:migrate:status."
-            echo ""
-            echo "### 6. Polaris Emulator"
-            echo ""
-            echo "Clone and build the emulator (requires Java 17+ and Maven 3.9+):"
-            echo '```bash'
-            echo "git clone https://github.com/duckietm/Polaris-Emulator.git /var/www/emulator"
-            echo "cd /var/www/emulator/Emulator"
-            echo "mvn clean package"
-            echo '```'
-            echo ""
-            echo "Place the built Habbo-*-jar-with-dependencies.jar next to **config.ini** (see [setup/emulator/config.ini](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/setup/emulator/config.ini)), then create a systemd unit from [setup/emulator/emulator.service](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/setup/emulator/emulator.service) with the [emulator](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/setup/emulator/emulator) launcher so it starts on boot. The bundled update-Nitrov3.sh in this repo automates cloning, building and updating the emulator and Nitro — run it any time to pull the latest commits and rebuild:"
-            echo '```bash'
-            echo "./update-Nitrov3.sh"
-            echo '```'
-            echo ""
-            echo "### 7. Nitro V3 & Renderer"
-            echo ""
-            echo "Clone both Nitro repos and build the client:"
-            echo '```bash'
-            echo "git clone https://github.com/duckietm/Nitro_Render_V3.git /var/www/Nitro_Render_V3"
-            echo "git clone https://github.com/duckietm/Nitro-V3.git /var/www/Nitro-V3"
-            echo "cd /var/www/Nitro_Render_V3 && yarn install && yarn link"
-            echo "cd /var/www/Nitro-V3 && yarn install && yarn link \"@nitrots/nitro-renderer\" && yarn build"
-            echo '```'
-            echo ""
-            echo "Copy the reference configs from [setup/nitro/](https://gitlab.epicnabbo.nl/remco/EpicNext-Cms/src/branch/main/setup/nitro) into /var/www/Nitro-V3/public/configuration, keep them as *.json, and replace **MY_DOMAIN** with your domain, API URL and gamedata paths (see the Full setup guide, NitroV3_And_Emulator.md)."
-            echo ""
-            echo "### 8. Catalogus (catalog & gamedata)"
-            echo ""
-            echo "Catalogus holds the daily-updated catalog/gamedata. Clone the Beta-3 branch alongside the other components:"
-            echo '```bash'
-            echo "git clone -b Beta-3 https://gitlab.epicnabbo.nl/remco/Epicnabbo-Catalogus-Updated-Daily.git /var/www/catalogus"
-            echo '```'
-            echo ""
-            echo "### 9. Build & Start the CMS"
-            echo '```bash'
-            echo "# Development (hot reload)"
-            echo "pnpm dev"
-            echo ""
-            echo "# Production"
-            echo "pnpm build && pnpm start"
-            echo '```'
-            echo ""
-            echo "Open http://localhost:3000 in your browser."
-            echo ""
-            echo "### 10. First Login"
-            echo ""
-            echo "1. Register at /register, or log in with an existing emulator account."
-            echo "2. Grant admin access: UPDATE users SET rank = 7 WHERE username = 'yourname';"
-            echo "3. Visit /admin and configure your hotel via Admin -> CMS Settings."
-            echo ""
-            echo '<a id="how-it-is-used"></a>'
-            echo "## How it is used"
-            echo ""
-            echo "- Public site: browse the hotel, news, radio and the Nitro client at /client."
-            echo "- Admin panel: /admin for CMS settings, theming (12 presets), users, radio and more."
-            echo "- Background jobs: run pnpm jobs:worker for daily backups and cleanup."
-            echo "- Optional: Cloudflare Turnstile / reCAPTCHA, OpenAI moderation and email/PayPal via .env."
-            echo ""
-            echo '<a id="changes"></a>'
-            echo "## Changes"
-            echo '```'
-            echo "${CHANGELOG}"
-            echo '```'
-            echo ""
-            echo '<a id="linked-repositories"></a>'
-            echo "## Linked repositories (exact commits)"
-            echo ""
-            echo "The game components below are pinned to the exact commits used by this release and are deployed alongside the CMS:"
-            echo ""
-            echo "| Component | Repository | Commit |"
-            echo "|-----------|------------|--------|"
-            echo "| Catalogus | https://gitlab.epicnabbo.nl/remco/Epicnabbo-Catalogus-Updated-Daily | ${CAT_REF:-?} |"
-            echo "| Nitro-V3 | https://github.com/duckietm/Nitro-V3 | ${NITRO_REF:-?} |"
-            echo "| Nitro-Render-V3 | https://github.com/duckietm/Nitro_Render_V3 | ${RENDER_REF:-?} |"
-            echo "| Polaris Emulator | https://github.com/duckietm/Polaris-Emulator | ${EMU_REF:-?} |"
-            echo ""
-            echo "**[Nitro-V3](https://github.com/duckietm/Nitro-V3)** · **[Nitro Renderer](https://github.com/duckietm/Nitro_Render_V3)** · **[Polaris Emulator](https://github.com/duckietm/Polaris-Emulator)** · **[Catalogus](https://gitlab.epicnabbo.nl/remco/Epicnabbo-Catalogus-Updated-Daily)**"
-            echo ""
-            echo "---"
-            echo "*Automated release from Gitea Actions*"
-          } > /tmp/release-body.md
-
-          PAYLOAD="$(jq -Rs --arg v "${VERSION}" '{tag_name: $v, name: $v, body: ., draft: false, prerelease: false}' < /tmp/release-body.md)"
-
-          TOKEN="${GITEA_TOKEN:-${{ secrets.GITEA_TOKEN }}}"
-
-          HTTP_CODE="$(curl -s -w '%{http_code}' -o /tmp/release-resp.json \
-            -X POST "${GITEA_API}/repos/${GITEA_REPO}/releases" \
-            -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "$PAYLOAD")"
-
-          if [ "${HTTP_CODE}" = "409" ]; then
-            RELEASES="$(curl -sf "${GITEA_API}/repos/${GITEA_REPO}/releases" \
-              -H "Authorization: token ${TOKEN}")"
-            REL_ID="$(echo "$RELEASES" | jq -r ".[] | select(.tag_name==\"${VERSION}\") | .id")"
-            HTTP_CODE="$(curl -s -w '%{http_code}' -o /tmp/release-resp.json \
-              -X PATCH "${GITEA_API}/repos/${GITEA_REPO}/releases/${REL_ID}" \
-              -H "Authorization: token ${TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "$PAYLOAD")"
-          fi
-
-          if [ "${HTTP_CODE:-0}" -ge 200 ] && [ "${HTTP_CODE:-0}" -lt 300 ]; then
-            echo "SUCCESS: Release ${VERSION} created/updated"
-            cat /tmp/release-resp.json | jq -r '.html_url // .id'
-          else
-            echo "FAILED HTTP ${HTTP_CODE}"
-            cat /tmp/release-resp.json
-            exit 1
-          fi
-  deploy:
-    if: startsWith(gitea.ref_name, 'v') == false
-    runs-on: shell
-    steps:
-      - name: Deploy
-        run: |
-          set -e
-
-          exec 9>/var/tmp/epic_web_control_deploy.lock
-          flock -n 9 || { echo "ERROR: Another deployment is already running! Cancelling."; exit 1; }
-
-          echo "--- Deploying ---"
-
-          LIVE="/var/www/atom-nexst"
-          STAGE=""
-          CUTOVER_STARTED=0
-
-          error_handler() {
-            cd /var/www/atom-nexst 2>/dev/null || cd / || true
-            echo "!!! DEPLOYMENT FAILED on line $1 !!!" >&2
-            # Roll back the build artifact if cutover already moved .next into place.
-            if [ "${CUTOVER_STARTED}" = "1" ] && [ -d "${LIVE}/.next.prev" ]; then
-              echo "Rolling back .next to previous artifact..." >&2
-              rm -rf "${LIVE}/.next" || true
-              mv "${LIVE}/.next.prev" "${LIVE}/.next" || true
-            fi
-            if [ -n "${STAGE}" ] && [ -d "${STAGE}" ]; then
-              git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
-            fi
-            pm2 restart next --update-env 2>/dev/null || pm2 start pnpm --name "next" -- start 2>/dev/null || true
-            exit 1
-          }
-          trap 'error_handler $LINENO' ERR
-
-          docker image prune -f
-
-          DEPLOY_USER="$(id -un)"
-          DEPLOY_GROUP="$(id -gn)"
-          sudo chown -R "${DEPLOY_USER}:${DEPLOY_GROUP}" "${LIVE}" 2>/dev/null || true
-          git config --global --add safe.directory "${LIVE}"
-          git -C "${LIVE}" remote set-url origin /docker/gitea/gitea/git/repositories/remco/epicnext-cms.git/
-
-          echo "Fetching origin/main..."
-          git -C "${LIVE}" fetch origin --prune
-
-          echo "Clearing sticky git index bits (if any)..."
-          STICKY_LIST="$(git -C "${LIVE}" ls-files -v | awk '/^[a-zS]/ {print substr($0,3)}' || true)"
-          if [ -n "${STICKY_LIST}" ]; then
-            echo "${STICKY_LIST}" | while IFS= read -r f; do
-              [ -n "$f" ] || continue
-              git -C "${LIVE}" update-index --no-skip-worktree --no-assume-unchanged -- "$f" 2>/dev/null || true
-            done
-          fi
-
-          export APP_VERSION="$(git -C "${LIVE}" rev-parse --short origin/main)"
-          export NEXT_PUBLIC_APP_VERSION="${APP_VERSION}"
-          echo "APP_VERSION=${APP_VERSION}"
-
-          STAGE="/var/tmp/atom-nexst-stage-${APP_VERSION}"
-          echo "Preparing stage worktree at ${STAGE} (live site stays up)..."
-          git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
-          git -C "${LIVE}" worktree add --detach "${STAGE}" origin/main
-
-          # Production env stays on the live tree; stage only needs a symlink for build/migrate.
-          ln -sfn "${LIVE}/.env" "${STAGE}/.env"
-
-          if ! grep -qE '^[[:space:]]*REDIS_URL=.+' "${LIVE}/.env" 2>/dev/null; then
-            echo "WARNING: REDIS_URL is unset in ${LIVE}/.env" >&2
-            echo "WARNING: Rate limits, site-settings cache, and JWT invalidation cache will be in-process only." >&2
-          fi
-
-          cd "${STAGE}"
-          rm -f tsconfig.tsbuildinfo .tsbuildinfo
-          find . -maxdepth 3 -name '*.tsbuildinfo' -delete 2>/dev/null || true
-          rm -rf .output dist .next .next/types .next/dev
-
-          # Restore build cache from last deploy so Turbopack can do
-          # incremental compilation (much faster rebuilds).
-          if [ -d "${LIVE}/.next/cache" ]; then
-            mkdir -p .next/cache
-            cp -r "${LIVE}/.next/cache/." .next/cache/
-          fi
-
-          # Stage shares MySQL with the live app + emulator. Keep the stage pool
-          # tiny so install/test/build cannot exhaust max_connections.
-          export DATABASE_POOL_SIZE="${DEPLOY_DATABASE_POOL_SIZE:-5}"
-          echo "STAGE DATABASE_POOL_SIZE=${DATABASE_POOL_SIZE}"
-
-          pnpm install --frozen-lockfile
-          # prisma generate does not need a live DB connection.
-          pnpm prisma:generate
-          export ARGON2_MEMORY_SIZE=1024 ARGON2_ITERATIONS=1 BCRYPT_ROUNDS=4
-          pnpm typecheck
-          pnpm test
-          # Validate production env (AUTH_SECRET, DATABASE_URL, …) during build.
-          # Do not set SKIP_ENV_VALIDATION here — that flag is for tests/tooling only.
-          pnpm build
-
-          if [ ! -d "${STAGE}/.next" ]; then
-            echo "ERROR: stage build produced no .next/" >&2
-            exit 1
-          fi
-
-          echo "Cutover: stop service (free DB connections), migrate, swap .next..."
-          CUTOVER_STARTED=1
-          pm2 stop next --kill-timeout 10000 || true
-          # Wait for PM2 to fully exit and MariaDB to reclaim connections.
-          sleep 10
-
-          # Migrate only after live is stopped — avoids ER_CON_COUNT_ERROR while
-          # the old process still holds DATABASE_POOL_SIZE connections.
-          cd "${STAGE}"
-          MIGRATE_OK=0
-          for i in $(seq 1 10); do
-            if pnpm db:migrate; then
-              MIGRATE_OK=1
-              break
-            fi
-            echo "migrate attempt ${i}/10 failed (likely DB connections), retrying..."
-            sleep 5
-          done
-          if [ "${MIGRATE_OK}" != "1" ]; then
-            echo "ERROR: db:migrate failed after retries" >&2
-            exit 1
-          fi
-
-          cd "${LIVE}"
-          echo "Hard reset live tree to origin/main (no nuclear src wipe)..."
-          git reset --hard origin/main
-          # Keep env, uploads, and deps we are about to replace from stage.
-          git clean -fd \
-            -e .env -e .env.local -e .env.production -e .env*.local \
-            -e storage -e public/cache -e node_modules -e .next -e .next.prev
-
-          if ! git diff --exit-code HEAD -- src >/dev/null; then
-            echo "ERROR: live src/ still differs from HEAD after reset:" >&2
-            git diff --stat HEAD -- src >&2 || true
-            exit 1
-          fi
-          echo "Verified live src/ matches HEAD"
-
-          # Save current .next as backup before swapping (kept until health check passes).
-          if [ -d .next ]; then
-            mv .next .next.prev
-          fi
-          mv "${STAGE}/.next" .next
-
-          # Use the exact node_modules the stage build resolved against.
-          rm -rf node_modules
-          mv "${STAGE}/node_modules" node_modules
-
-          # Prisma client is gitignored — regenerate into live src/generated.
-          pnpm prisma:generate
-
-          sudo chown -R www-data:www-data "${LIVE}" 2>/dev/null || true
-
-          echo "Starting PM2 (zero-downtime reload)..."
-          pm2 reload next --update-env || pm2 start next --update-env
-
-          sleep 3
-          if ! pm2 show next 2>/dev/null | grep -q 'online'; then
-            echo "ERROR: PM2 next failed to start!" >&2
-            pm2 logs next --lines 20 --nostream >&2 || true
-            exit 1
-          fi
-
-          echo "Waiting for HTTP health check..."
-          HEALTH_URL="${DEPLOY_HEALTH_URL:-http://127.0.0.1:3000/api/health}"
-          HEALTH_OK=0
-          for i in $(seq 1 15); do
-            BODY="$(curl -sf --max-time 5 "${HEALTH_URL}" 2>/dev/null || true)"
-            if echo "${BODY}" | grep -q '"database":true'; then
-              echo "Health OK (${HEALTH_URL})"
-              HEALTH_OK=1
-              break
-            fi
-            echo "Health attempt ${i}/15 failed, retrying..."
-            sleep 2
-          done
-          if [ "${HEALTH_OK}" != "1" ]; then
-            echo "ERROR: Health check failed after deploy (${HEALTH_URL})" >&2
-            echo "Last body: ${BODY:-<empty>}" >&2
-            pm2 logs next --lines 40 --nostream >&2 || true
-            exit 1
-          fi
-
-          echo "Cleaning stage worktree and previous .next backup..."
-          rm -rf "${LIVE}/.next.prev"
-          git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
-          STAGE=""
-
-          echo "--- Deployed successfully ---"

.gitea/workflows/renovate.yaml

@@ -6,14 +6,17 @@ on:
 
 jobs:
   renovate:
-    runs-on: shell
+    runs-on: ubuntu-latest
     steps:
+      - name: Fix Git safe directory
+        run: "git config --global --add safe.directory '*' && git remote set-url origin https://epicnabbo.nl || true"
+      - name: Install Bash in Alpine
+        run: "if [ -f /etc/alpine-release ]; then apk add --no-cache bash; fi"
       - name: Self-hosted Renovate
         run: |
           set -e
-          
-          # Zorg ervoor dat de cache-map lokaal bestaat vóór Docker start
-          # Dit voorkomt dat Docker de map automatisch als 'root' aanmaakt
+
+          # Ensure cache dir exists before Docker starts
           mkdir -p /var/tmp/renovate-cache
 
           docker run --rm \
@@ -22,7 +25,6 @@ jobs:
             -e RENOVATE_AUTODISCOVER=false \
             -e RENOVATE_REPOSITORIES="${{ gitea.repository }}" \
             -e RENOVATE_ONBOARDING=false \
-            -e RENOVATE_CONFIG_FILE='{"extends":["config:recommended"]}' \
             -e LOG_LEVEL=info \
             -v /var/tmp/renovate-cache:/tmp/renovate-cache \
-            ghcr.io/renovatebot/renovate:latest
+            ghcr.io/renovatebot/renovate:latest

.gitignore

@@ -1,11 +1,12 @@
 node_modules/
+node_modules.prev/
 .turbo/
 .next/
 .next.prev/
+.next-staging/
 next-env.d.ts
 .env
 *.tsbuildinfo
-# Prisma client is generated by `prisma generate`
 src/generated/
 # Runtime avatar/badge imaging disk cache
 public/cache/
@@ -17,7 +18,8 @@ prod.log
 db_backup_*.sql
 
 # Local project documentation
-/docs/
+/docs/*
+!/docs/cms-upgrade-2026-09.md
 
 # Local gitea binary symlink
 gitea
@@ -25,5 +27,28 @@ gitea
 # Runtime uploaded media (persistent, outside public/)
 storage/
 
+# Runtime downloaded furni assets (mirrored from gamedata / audit repair)
+public/nitro-assets/bundled/furniture/
+public/swf/dcr/
+public/tmp/
+
 # Test coverage reports
 coverage/
+.aider*
+
+/public/vendor/tinymce/
+
+# Shared deployment lock (never application source)
+.deploy.lock
+
+# Browser verification artifacts
+test-results/
+playwright-report/
+blob-report/
+
+# Local Docker installation metadata
+.docker-install
+.docker-install.tmp.*
+.env.install.*
+build-reports/
+!/docs/performance-budgets.md

.npmrc

@@ -0,0 +1 @@
+strict-peer-dependencies=false

.nvmrc

@@ -1 +1 @@
-22
+26.8.2

CATALOG_EXPORT.md

@@ -0,0 +1,73 @@
+# Catalog Studio repository export
+
+Studio mutations automatically queue an export to
+`https://gitlab.epicnabbo.nl/remco/Epicnabbo-Catalogus-Updated-Daily.git`, branch
+`Beta-3`. The jobs worker processes pending exports every minute. Streaming
+imports stay active until their stream completes. Server actions for catalog
+pages, offers, deletion and maintenance are covered as well.
+
+## Server setup
+
+1. Create a **dedicated clean clone** of the repository on `Beta-3`, outside the
+   CMS directory. Configure non-interactive Git push authentication for the
+   worker OS account using its credential helper. Do not put tokens in URLs.
+2. Set `CATALOG_GIT_CHECKOUT` to that absolute clone directory in the CMS and
+   worker environments. Set `CATALOG_GIT_STATE_DIR` to a persistent, writable
+   directory outside the clone, shared by both processes on the same host.
+3. Run `pnpm jobs:worker` alongside the CMS under your process supervisor.
+   Both processes must have access to the configured asset directories and DB.
+   The worker command enables the React server condition for server-only modules.
+4. Restart the CMS after setting the environment. In **Studio → Sync**, use
+   **Export now / retry** for the initial export. Subsequent mutations queue
+   automatically. Status shows pending/active operations and the last commit.
+
+Leaving `CATALOG_GIT_CHECKOUT` empty disables export. No credentials are shipped.
+This source change alone does not configure or deploy the production service.
+
+## Exported content
+
+| Source | Repository destination |
+| --- | --- |
+| Configured Nitro bundles, including furniture, figures, effects and pets | `Gamedata/bundled` |
+| Configured furni icons | `Gamedata/icons` |
+| Existing badge/catalog images | `Gamedata/c_images` |
+| FurnitureData and supported public game-data JSON files | `Gamedata/config` |
+| Existing localized FurnitureData files | `catalogue version 2 ( Final (Dev)/langs furnidata` |
+| `items_base`, `catalog_pages`, `catalog_items` | `catalogue version 2 ( Final (Dev)/sqls` |
+| `catalog_pages_bc`, `catalog_items_bc`, when present | Same SQL directory |
+
+SQL is read in one consistent, read-only InnoDB transaction. Dumps contain table
+definitions and deterministic upserts with hexadecimal UTF-8 string literals.
+Import `items_base.sql`, then `catalog_pages.sql`, then `catalog_items.sql`.
+Existing schemas are not migrated by these dumps. Rows absent from the source
+are omitted; importing an upsert dump into another existing database does not
+delete that database's extra rows. No user, session or credential tables are exported.
+
+Only existing local assets are exported. Translation generation follows Studio's
+existing setting; export does not generate missing languages or download assets.
+Public JSON is explicitly allowlisted so translation caches and private runtime
+files cannot enter the repository. Invalid JSON or concurrent Studio changes
+prevent publication of that snapshot.
+
+## Failure and concurrency behavior
+
+- Pending events survive process restarts; events added during publication remain
+  pending for the next run. Partial imports are exported as their settled local
+  state, including successful items from a batch containing failures.
+- A single filesystem lock serializes the worker. Dead local process markers are
+  recovered on the next run. For an unreadable marker or a marker from another
+  host, stop the CMS and worker before repairing the queue directory.
+- A failed push retains the local commit and pending events for retry. Concurrent
+  upstream commits are rebased; a conflict aborts the rebase and leaves the event
+  pending. Resolve conflicts in the dedicated clone, then retry.
+- The checkout must be clean before each run. Unrelated files are preserved and
+  no force push is used. Missing local files do not cause remote deletions.
+- Status errors omit raw Git output to avoid exposing authentication material.
+
+## Verification
+
+Run the `catalog-git-*` service tests and `src/lib/catalog-export-api.test.ts` with
+Vitest. The integration test creates a temporary bare remote and verifies push,
+failed-push recovery, no-op export and preservation of unrelated files. SQL
+snapshot tests mock the database; production DB import and production push need
+verification in the deployed environment.

CMS_TRANSLATIONS.md

@@ -0,0 +1,30 @@
+# CMS translation audit and editor
+
+The CMS editor at `/admin/translations/cms` now uses the same bundled catalogs as the request-time translator. Runtime changes are stored separately in `storage/cms-translations/<locale>.json`, inside the existing persistent `/app/storage` mount. No source-file write, environment-variable change or rebuild is required to apply an edit.
+
+Only overrides are saved. Unchanged messages continue to receive updates from Git. Saves use a file lock, an atomic replacement and a revision check; a stale editor cannot overwrite another operator's changes. ICU syntax, argument names, rich-text tags and allowed keys are checked server-side. Invalid or obsolete overrides are excluded when reading a new release. Storage read errors are reported to the CMS error monitor and public pages fall back to bundled text.
+
+The page starts in the operator's language. It shows all English reference keys, including missing translations, and supports search by key, translated text or English source. Filters separate missing, identical and modified text. Drafts survive language switches and failed saves. Users without `SETTINGS_EDIT` can review and export but cannot save.
+
+## Audit outcome, 6 September 2026
+
+- Scanned 25 JSON catalogs; 22 languages are selectable. The small Arabic, Finnish and Japanese catalogs are legacy files and remain outside the supported locale list.
+- Repaired 66 malformed ICU messages across the 22 active catalogs, including HTML fragments and unescaped JSON examples.
+- Added 199 missing English reference keys used by page components, with Italian translations, and fixed the incorrect navigation namespace in the admin error page.
+- Completed the 31 previously missing Italian reference keys.
+- Repaired missing `count` and `preset` variables in other locales.
+- Final checks: zero malformed messages, zero argument/tag mismatches and zero missing references among the statically resolved translation calls.
+- English contains 3,423 reference keys. Italian covers all of them; 629 values match English. Dutch is missing 524 reference keys and has 618 identical values. Matching English can be intentional for names and technical labels; this is not proof of translation quality.
+- Found 1,577 literal JSX text candidates outside translation calls. These include labels, technical strings and names; they are an editorial inventory, not 1,577 confirmed bugs. The largest concentrations are the catalog item table (118), Studio main component (79), import audit (53), sound management (50) and permission editor (42).
+
+## Repeatable checks
+
+- `pnpm i18n:check`: fails on malformed messages, incompatible variables/tags, empty messages, source parsing errors or missing statically referenced keys. Runs in Gitea CI.
+- `pnpm i18n:audit`: prints coverage and findings.
+- `node scripts/audit-cms-translations.mjs --json`: full machine-readable inventory, including file and line references for literal JSX candidates.
+
+Static analysis resolves literal translator namespaces and literal message keys. Dynamic key construction, prose embedded in arbitrary JavaScript strings, and the linguistic accuracy of all 22 translations still require targeted review. English fallback remains explicit; copying English into other catalogs would hide untranslated entries and is intentionally avoided.
+
+## Validation
+
+Automated tests exercise message syntax, actual translator output, persistent overrides, invalid-message rejection, revision conflicts and reset behavior. A browser fixture mounts the real editor and verifies missing-key editing, validation, failed-save preservation, language switching, successful saves, read-only access and mobile layout. Server actions are simulated in that fixture; authenticated production editing requires a staff session.

Dockerfile

@@ -0,0 +1,68 @@
+# syntax=docker/dockerfile:1
+# Pin the runtime to the supported engine; update both stages deliberately.
+FROM node:26.8.2-alpine AS migrations
+WORKDIR /app
+ENV NEXT_TELEMETRY_DISABLED=1
+# Keep the bootstrap aligned with package.json packageManager.
+# The apk cache is persisted in a BuildKit cache mount so git is not
+# re-downloaded on every build.
+RUN --mount=type=cache,target=/var/cache/apk \
+    apk add --no-cache git \
+    && npm install -g [email protected]
+# The pnpm store is kept in a BuildKit cache mount that persists across builds
+# on the builder. This is what stops disk usage from growing unbounded: the
+# downloaded dependency store is shared and reused instead of being copied into
+# a fresh image layer on every build. Unlike an image layer it is also prunable
+# independently, so a hard cap (see ci-deploy.sh) keeps it bounded.
+ENV PNPM_HOME=/pnpm PNPM_STORE=/pnpm/store
+# pnpm-workspace.yaml + .npmrc must be present too: the lockfile records the
+# overrides from pnpm-workspace.yaml, and --frozen-lockfile rejects a build
+# where the workspace config is absent (ERR_PNPM_LOCKFILE_CONFIG_MISMATCH).
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml* .npmrc* ./
+# pnpm fetch: download all deps into the shared cache-mounted store.
+RUN --mount=type=cache,target=/pnpm \
+    pnpm fetch --ignore-scripts
+# Install offline from the cache-mounted store; the store itself stays in the
+# build cache between builds.
+RUN --mount=type=cache,target=/pnpm \
+    pnpm install --frozen-lockfile --ignore-scripts --offline
+COPY . .
+FROM migrations AS builder
+ARG NEXT_DEPLOYMENT_ID="unknown"
+ENV NEXT_DEPLOYMENT_ID="$NEXT_DEPLOYMENT_ID"
+# Fixture values exist only for this build command; production secrets are runtime-only.
+# Cache Next.js build output and webpack caches so rebuilds only redo the
+# changed parts.
+RUN --mount=type=cache,target=/app/.next/cache \
+    DATABASE_URL="mysql://build:[email protected]:9/build" \
+    HOTEL_NAME="Build fixture" APP_URL="http://localhost:3002" \
+    AUTH_SECRET="build-fixture-not-for-runtime-use-000000000000" \
+    pnpm run build \
+    && PERFORMANCE_COMMIT_SHA="$NEXT_DEPLOYMENT_ID" node scripts/performance-report.mjs --output-dir build-reports
+
+FROM node:26.8.2-alpine AS runner
+ARG NEXT_DEPLOYMENT_ID="unknown"
+LABEL org.opencontainers.image.revision="$NEXT_DEPLOYMENT_ID"
+WORKDIR /app
+ENV NODE_ENV=production \
+    NEXT_TELEMETRY_DISABLED=1 \
+    PORT=3002 \
+    HOSTNAME=0.0.0.0
+RUN apk add --no-cache tini curl \
+    && addgroup -g 33 -S nextjs && adduser -u 33 -S -G nextjs nextjs \
+    && mkdir -p /app/storage /app/public/nitro-assets /app/public/swf /var/www/Gamedata \
+    && chown -R 33:33 /app/storage /app/public /var/www/Gamedata
+COPY --from=builder --chown=nextjs:nextjs /app/public ./public
+COPY --from=builder --chown=nextjs:nextjs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nextjs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nextjs /app/build-reports ./build-reports
+COPY --from=builder --chown=nextjs:nextjs /app/drizzle/migrations ./drizzle/migrations
+COPY --chown=nextjs:nextjs scripts/docker-start.mjs ./docker-start.mjs
+USER nextjs
+EXPOSE 3002
+# Self-contained healthcheck so `docker run` (ci-deploy) also gets Docker-level
+# health; docker-compose overrides this with its own probe if needed.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+    CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||'3002')+'/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "docker-start.mjs"]

README.md

@@ -1,8 +1,8 @@
-# EpicNext-CMS v1.0.1
+# EpicNext-CMS v1.0.3
 
-A modern, high-performance content management system for Habbo hotel emulators, built on **Next.js 16** (App Router) with **Prisma 7** and **React 19**. Designed to integrate seamlessly with Polaris / Arcturus Morningstar MySQL/MariaDB databases.
+A modern, high-performance content management system for Habbo hotel emulators, built on **Next.js 16** (App Router) with **Drizzle ORM** and **React 19**. Designed to integrate seamlessly with Polaris / Arcturus Morningstar MySQL/MariaDB databases.
 
-Features a premium animated homepage (typewriter hero, floating orbs, scroll counters), a full admin panel, NextAuth authentication (argon2id/bcrypt with MD5-to-argon2id upgrade), real-time RCON communication, Server-Sent Events for live radio data, smooth page transitions, and PM2 production deployment.
+Features a premium animated homepage (typewriter hero, floating orbs, scroll counters), a full admin panel, NextAuth authentication (argon2id hashing with legacy md5/bcrypt auto-upgrade), real-time RCON communication, Server-Sent Events for live radio data, smooth page transitions, and PM2 production deployment.
 
 ---
 
@@ -10,12 +10,13 @@ Features a premium animated homepage (typewriter hero, floating orbs, scroll cou
 
 | Component       | Version        | Notes                                    |
 | --------------- | -------------- | ---------------------------------------- |
-| Node.js         | >= 22          | Required by Next.js 16                   |
-| pnpm            | >= 10.33.4     | Package manager (npm/yarn not supported) |
+| Node.js         | 26.8.1         | Current release pinned in `.nvmrc`       |
+| pnpm            | >= 11.25.0     | Recommended package manager              |
+| npm             | >= 11.x        | Supported alternative                    |
+| yarn            | >= 4.x         | Supported alternative                    |
 | MySQL / MariaDB | 8.0+ / 10.6+   | Shared with the emulator                 |
-| Redis           | 7.x+           | Optional — caching, rate limiting, SSE   |
-| Java            | 17+            | Required only if building the emulator   |
-| Maven           | 3.9+           | Required only if building the emulator   |
+| Docker          | 24+            | Optional — for containerized deployment  |
+| Valkey          | 8.x+           | Optional — caching, rate limiting, SSE   |
 
 ---
 
@@ -23,12 +24,28 @@ Features a premium animated homepage (typewriter hero, floating orbs, scroll cou
 
 ### 1. Clone & Install
 
+Choose your preferred package manager:
+
 ```bash
 git clone https://gitlab.epicnabbo.nl/remco/EpicNext-Cms.git
 cd EpicNext-Cms
+```
+
+**pnpm (recommended):**
+```bash
 pnpm install
 ```
 
+**npm:**
+```bash
+npm install
+```
+
+**yarn:**
+```bash
+yarn install
+```
+
 ### 2. Database Setup
 
 The CMS shares a database with the Polaris/Arcturus emulator. Use an existing database or create a new one:
@@ -37,7 +54,9 @@ The CMS shares a database with the Polaris/Arcturus emulator. Use an existing da
 CREATE DATABASE IF NOT EXISTS epicnext_cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 ```
 
-The CMS reads emulator-owned tables (`users`, `items`, `rooms`, `bans`, etc.) directly. It never creates, alters, or drops them.
+The CMS reads emulator-owned tables (`users`, `items`, `rooms`, `bans`, etc.) directly. It never creates, alters, or drops them. The Drizzle schema in `src/db/schema.ts` is generated from the existing database structure and does not modify it.
+
+> **Note:** The CMS does **not** own the emulator schema — it maps to those tables via Drizzle. Never run `drizzle-kit push` / `migrate` against the shared DB. CMS-owned tables (`website_*`, `radio_*`, etc.) are created via idempotent SQL in `drizzle/migrations/`.
 
 ### 3. Configure Environment
 
@@ -51,46 +70,39 @@ Edit `.env` with at minimum:
 DATABASE_URL=mysql://user:[email protected]:3306/epicnext_cms
 AUTH_SECRET=<random 32+ character string>
 HOTEL_NAME=YourHotel
-APP_URL=http://localhost:3000
+APP_URL=http://localhost:3002
 ```
 
-See `.env.example` for all optional variables (RCON, email, Redis, OAuth, PayPal, etc.).
+See `.env.example` for all optional variables (RCON, email, Valkey, OAuth, PayPal, etc.).
 
-### 4. Generate Prisma Client
-
-```bash
-pnpm prisma:generate
-```
-
-Generates TypeScript types in `src/generated/prisma/`.
-
-### 5. Run CMS Migrations
+### 4. Run CMS Migrations
 
 ```bash
+# pnpm
 pnpm db:migrate
+
+# npm
+npm run db:migrate
+
+# yarn
+yarn db:migrate
 ```
 
-Creates all CMS-owned tables (`website_*`, `radio_*`, `acl_*`, `admin_audit_log`, etc.) via idempotent SQL files in `prisma/migrations/`. Emulator tables are never touched.
+Creates all CMS-owned tables (`website_*`, `radio_*`, `acl_*`, `admin_audit_log`, etc.) via idempotent SQL files in `drizzle/migrations/`. Emulator tables are never touched.
 
-Check migration status:
-
-```bash
-pnpm db:migrate:status
-```
-
-### 6. Build & Start
+### 5. Build & Start
 
 ```bash
 # Development (hot reload)
-pnpm dev
+pnpm dev      # or: npm run dev / yarn dev
 
 # Production
-pnpm build && pnpm start
+pnpm build && pnpm start       # or: npm run build && npm start
 ```
 
-Open `http://localhost:3000` in your browser.
+Open `http://localhost:3002` in your browser.
 
-### 7. First Login
+### 6. First Login
 
 1. Register an account at `/register`, or log in with an existing emulator account.
 2. Grant yourself admin access: `UPDATE users SET rank = 7 WHERE username = 'yourname';`
@@ -98,6 +110,641 @@ Open `http://localhost:3000` in your browser.
 
 ---
 
+## Docker Deployment
+
+The CMS ships with a multi-stage Dockerfile that automatically detects your package manager (pnpm, npm, or yarn) based on which lockfile is present. The **CMS** runs in Docker; the Nitro/Octane client stays outside and is served by nginx on the host. The server-side **avatar imager** also runs in its own Docker container (`avatar-imaging-pixinode`, port 8082) — see [Avatar Imaging](#avatar-imaging).
+
+### Prerequisites
+
+- Docker 24+ and Docker Compose v2
+- `.env` file configured (see step 3 above)
+- A MySQL/MariaDB database reachable from the container (`DATABASE_URL` host should point to the DB server, not `127.0.0.1` unless it's reachable from inside the container)
+- (Optional) A shared `Gamedata` directory at `/var/www/Gamedata` with write access (see [Volumes](#volumes) below)
+
+### Quick Start with Docker
+
+```bash
+# 1. Clone and configure
+git clone https://gitlab.epicnabbo.nl/remco/EpicNext-Cms.git
+cd EpicNext-Cms
+cp .env.example .env
+# Edit .env with your database credentials and settings.
+# The container runs on the host network, so all 127.0.0.1 references
+# (DATABASE_URL, REDIS_URL, RCON, imaging) keep pointing at the host as-is.
+
+# 2. Stop any existing host-side CMS that occupies port 3002 (if present).
+pm2 stop next 2>/dev/null || true
+
+# 3. Ensure the write directories are owned by www-data (UID/GID 33) so the
+#    container user can write imports/uploads to them.
+sudo mkdir -p ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+
+# 4. Build, migrate and start a release tied to the Git commit.
+# Requires Linux, Bash, Git, flock and Docker Compose v2; no host Node/pnpm.
+bash scripts/docker-update.sh
+
+# 5. Follow logs
+docker compose logs -f cms
+```
+
+The CMS listens on port 3002 using Linux host networking. Existing database,
+Redis, emulator and shared gamedata services must already be configured.
+Create the mounted directories before installation; do not mount the checkout,
+`.next` or `node_modules` over `/app` inside the production container.
+
+### Updating a Docker clone
+
+From your clone, run:
+
+```bash
+# Also verifies that your public domain serves the expected commit:
+CMS_PUBLIC_URL=https://your-hotel.example bash scripts/docker-update.sh
+```
+
+The script follows the **current branch's configured Git upstream**. It refuses
+local uncommitted/untracked work, pulls fast-forward only and restarts itself if
+the updater changed. It does not reset or delete local work. Configure the
+upstream to your fork/branch if that is where you receive updates.
+
+It builds a commit-tagged image and runs migrations in the matching builder
+container, using the clone's `.env`; no host dependency installation is needed.
+Only after build and migrations succeed does it recreate the CMS service. It
+compares the running image ID, image revision and `/api/health` release with the
+expected Git commit. With `CMS_PUBLIC_URL`, it also checks the domain through
+your proxy/CDN. A healthy response from another release is an error.
+
+`git pull` alone updates source files, not an existing container. `docker compose
+restart` restarts the same image. `docker compose pull` downloads registry images;
+it does not fetch changes to this Git-built CMS. Use the updater for releases.
+A clone does **not** install an automatic scheduler. If desired, explicitly add a
+cron entry with the absolute path of **your** checkout; keep logs in its `logs`
+directory. Do not configure both CI and Compose updates for the same instance.
+The updater refuses an active `epicnext-cms-app` CI-managed container.
+
+Logs: `logs/docker-update.log`. After cutover, a startup, image or HTTP check
+failure automatically recreates the CMS with its previous image and verifies its
+local HTTP release and database health. The command still returns nonzero: a
+rollback is not a successful update. Recovery uses the current Compose configuration
+and `.env`; it restores application code, not configuration edits or database migrations.
+The previous image must carry a valid release label. First installations have no
+previous release: a failed candidate remains available for diagnosis. A failed
+rollback is explicitly logged with a retained `epicnext-cms:rollback-...` recovery tag.
+Public routing must be checked separately after rollback. SIGKILL or host power loss
+cannot run the rollback handler.
+
+After success, the updater keeps the two most recent distinct releases tracked in
+`logs/docker-release-history.log`. Cleanup only removes older recorded CMS image
+tags, without force; images referenced by other containers (including stopped ones)
+are preserved and retried on later updates. Untracked historical images, build cache,
+other services and persistent volumes are not pruned. Retain the history file between
+updates. Before production migrations, retain your normal database backup.
+
+### Portable images on the Gitea registry
+
+Docker builds no longer load your installation's `.env`. The builder uses disposable
+fixture values; the runtime reads `HOTEL_NAME`, `APP_URL`, `AUTH_SECRET`, database and
+asset settings when the container starts. Missing/invalid required runtime values
+stop startup with the setting names, without printing credentials.
+
+Configure `IMAGER_URL` with the actual avatar renderer endpoint and `BADGE_URL` with
+the badge directory URL (or a local path). The legacy `NEXT_PUBLIC_IMAGER_URL` and
+`NEXT_PUBLIC_BADGE_URL` names remain supported at runtime. If the imager points back
+to the CMS `/imaging` proxy, set `IMAGING_UPSTREAM_URL` to the actual renderer to avoid
+a loop. With no imager configured, the CMS uses Habbo's public renderer. Client
+requests use the existing `/api/imaging/avatar` proxy. Admin badges preserve their
+local `/swf/c_images/album1584` fallback. Public URL resolution uses runtime `APP_URL`.
+After changing `.env`, recreate the container; an image rebuild is not required.
+`NEXT_PUBLIC_CMS_RELEASE` deliberately remains compiled into the image.
+
+### Guided installation from this repository
+
+On a Linux host with Docker Engine, the Compose plugin, Git and `flock` available:
+
+```bash
+git clone https://gitlab.epicnabbo.nl/remco/EpicNext-Cms.git
+cd EpicNext-Cms
+bash cms install
+```
+
+The wizard asks for your public URL, delivery method, hotel name, existing database
+connection, Redis and avatar imager. It generates an authentication secret and
+creates `.env` with private permissions. An existing `.env` is preserved; review
+its `APP_URL`, `AUTH_URL`, RCON and optional original Laravel `APP_KEY` when moving
+an existing hotel. This installs the CMS, not the Habbo database, emulator, Redis
+or reverse proxy. Point HTTPS at port 3002 before running the final public check.
+The wizard may request sudo to prepare persistent directories for UID/GID 33;
+it does not recursively change ownership of existing assets.
+
+Choose **prebuilt** to download the images specified by this repository in
+`docker-image.txt`, without entering a registry namespace or commit tag. Choose
+**source** when building your own fork on the installation host. Private packages
+still require `docker login` on that host. Maintainers must update `docker-image.txt`
+if the publication registry or namespace changes.
+
+After installation, update with:
+
+```bash
+bash cms update
+```
+
+The updater pulls the configured Git upstream, loads `.docker-install`, uses the
+matching application/migration images and verifies the running release locally
+and at the saved public URL. If publication for the new commit is still running,
+it stops before replacing the current container; run the same command after CI
+succeeds. Existing application rollback remains available on a failed cutover;
+database migrations are not reversed.
+
+`bash cms install --configure-only` saves configuration without preparing runtime
+directories or starting containers. Neither `.env` nor `.docker-install` is
+committed or sent in Docker build contexts. Existing users of
+`bash scripts/docker-update.sh` retain the previous behavior when no wizard
+profile exists; explicit `CMS_IMAGE_REPOSITORY`/`CMS_PUBLIC_URL` overrides still work.
+
+To publish from Gitea:
+
+Gitea packages belong to an account or organization, independently of repository
+permissions. Publication defaults to the lowercase `CONTAINER_REGISTRY_USER`
+namespace, so a Simo token publishes `simo/epicnext-cms` even though the Git
+repository belongs to remco. Set the Actions variable
+`CONTAINER_REGISTRY_NAMESPACE` only to override this (for example, an organization
+where the token account has package write access). Keep the login username and
+token from the same account. Changing namespace also changes the image URL used
+by installations; existing remco image tags are not moved automatically.
+
+1. In the repository's Actions secrets, configure `CONTAINER_REGISTRY_USER` and
+   `CONTAINER_REGISTRY_TOKEN`. Use a Gitea access token with package read/write
+   permission belonging to the login account. For the Simo token, set
+   `CONTAINER_REGISTRY_USER=Simo`; the default package namespace will be `simo`.
+2. Every push to `main` or `master` automatically builds and publishes the images
+   after the CI checks and production deployment succeed. Pull requests do not
+   publish images. The publication job builds from committed source only and checks
+   the same application image with two runtime configurations before pushing.
+   Missing registry secrets fail the publication job explicitly; they do not undo
+   an already successful production deployment. No `latest` tag is moved.
+   **Publish portable container** remains available for manual retries on the
+   commit/branch to distribute, without redeploying production.
+3. The images are `<gitea-host>/<owner>/<repository-lowercase>:<full-commit>` and
+   `:<full-commit>-migrations`. Only the application image runs the website; the
+   migrations image is used temporarily for the matching database migrations.
+
+Publication uses checksum-pinned regctl v0.11.6 with 8 MiB blob requests to
+avoid monolithic layer uploads exceeding reverse-proxy limits. Both images are
+exported and uploaded sequentially; temporary archives and credentials are removed
+on exit. The runner needs curl, sha256sum and temporary disk space for one Docker
+image archive plus its extracted OCI layout. The remote image config digest is checked against the locally normalized archive
+after each upload. A proxy must still allow the OCI registry PATCH/PUT endpoints.
+
+For this repository the image base is
+`gitlab.epicnabbo.nl/simo/epicnext-cms`. Package access is controlled by Gitea.
+For private packages, run `docker login gitlab.epicnabbo.nl` on the installation
+with a token that can read packages. Then update with:
+
+```bash
+CMS_IMAGE_REPOSITORY=gitlab.epicnabbo.nl/simo/epicnext-cms \
+CMS_PUBLIC_URL=https://your-hotel.example \
+bash scripts/docker-update.sh
+```
+
+The updater pulls the configured Git upstream and requires both images for that
+exact commit. A missing image or failed login stops before replacing the running
+CMS. Local builds remain the default when `CMS_IMAGE_REPOSITORY` is unset. Both
+paths retain the existing image/HTTP checks and automatic application rollback.
+Migration secrets are mounted read-only for the temporary migration container;
+they are never copied into its image. Registry images currently target the Linux
+architecture of the self-hosted build runner; this is not a multi-architecture release.
+
+The portability gate checks release identity, runtime avatar/badge routing and
+absence of installation environment files in the application image. It uses an
+unreachable fixture database and does not replace a full live database/site smoke
+test. See `scripts/verify-portable-image.mjs`. Production deployment remains verified
+separately by the existing CI workflow.
+
+References: [Gitea container registry](https://docs.gitea.com/usage/packages/container/)
+and [Next.js runtime environment variables](https://nextjs.org/docs/app/guides/self-hosting).
+
+### Diagnose an update that is not visible
+
+```bash
+git rev-parse HEAD
+docker inspect --format '{{.Image}}' epicnext-cms
+docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' epicnext-cms
+curl -fsS http://127.0.0.1:3002/api/health
+curl -fsS https://your-hotel.example/api/health
+```
+
+Both HTTP responses must report the expected `release`. `unknown` means the image
+was built without a commit ID. If the local endpoint is current but the public
+one is old, check nginx's upstream, other CMS processes and proxy/CDN caching.
+Health responses must not be cached. The release is compiled into Next.js and
+cannot be changed simply by injecting a new variable into an old container.
+
+### Docker commands
+
+| Command | Purpose |
+| --- | --- |
+| `bash scripts/docker-update.sh` | Pull, build, migrate, recreate and verify |
+| `docker compose logs -f cms` | View CMS logs |
+| `docker compose exec cms sh` | Open a shell in the running CMS |
+| `docker compose restart cms` | Restart the existing release |
+| `docker compose down` | Stop services; does not update code |
+| `pnpm db:up` / `pnpm db:down` | Manage the optional MariaDB service |
+
+For a manual build, export `CMS_RELEASE=$(git rev-parse HEAD)` before
+`docker compose build cms`; deployment and migration verification remain your
+responsibility. Docker uses the committed pnpm lockfile and pinned Node version.
+The build cache can stay enabled: copying changed source invalidates the
+application build layer. Deleting all Docker cache is not an update mechanism.
+
+### Volumes
+
+Only the CMS (and the optional avatar imager container, see [Avatar Imaging](#avatar-imaging)) run in Docker. The heavy client assets and gamedata stay on the host and are shared into the container so imports and uploads persist:
+
+| Container Path             | Host Path                  | Mode | Purpose                              |
+| -------------------------- | -------------------------- | ---- | ------------------------------------ |
+| `/app/public/nitro-assets` | `./public/nitro-assets`    | rw   | Imported furni/pet/effect assets     |
+| `/app/public/swf`          | `./public/swf`             | rw   | SWF costumes / icons (imports)       |
+| `/app/storage`             | `./storage`                | rw   | Uploaded media (persistent)          |
+| `/var/www/Gamedata`        | `/var/www/Gamedata`        | rw   | Shared gamedata root (hardcoded path)|
+
+**About the hardcoded `/var/www/Gamedata` path:** `src/lib/services/furni-asset-dirs.ts` defines `DEFAULT_GAMEDATA_ROOT = /var/www/Gamedata` as an absolute on-disk path the CMS reads and mirrors imported assets into. The compose file mounts the host `/var/www/Gamedata` at the identical path inside the container so `existsSync('/var/www/Gamedata')` succeeds and nginx keeps serving `/gamedata/` from the same directory.
+
+**The Nitro/Octane client and renderer are NOT mounted** — nginx on the host serves them directly:
+
+| Component            | Host path               | How it's served                                                        |
+| -------------------- | ----------------------- | ---------------------------------------------------------------------- |
+| Nitro/Octane client  | `/var/www/Octane/dist`  | nginx `location ^~ /client/` and `/nitro-client/` alias                |
+| Avatar imager        | `/docker/Polaris-imager`| Docker container `avatar-imaging-pixinode` on port `8082` — see [Avatar Imaging](#avatar-imaging) |
+| Camera uploads       | `/var/www/Camera`       | nginx `/camera/` alias                                                 |
+
+**Container user & write permissions:** the CMS container runs as `www-data` (UID/GID 33) by default to match the host owner of `/var/www/Gamedata`. Ensure the other write volumes (`./public/nitro-assets`, `./public/swf`, `./storage`) are also owned by `www-data` on the host:
+
+```bash
+sudo mkdir -p ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+sudo chmod -R o+rX ./public/nitro-assets ./public/swf ./storage
+```
+
+If your host user UID differs, override the run user at build time (defaults to `www-data`, which already exists in the base image with UID/GID 33):
+
+```bash
+docker compose build --build-arg RUN_USER=1000
+```
+
+### Networking
+
+The CMS container runs with `network_mode: host`. This lets the existing `127.0.0.1` references in `.env` keep working against host services — MariaDB (`3306`), Valkey/Redis (`6379`), the emulator RCON/API (`3003`/`3001`) and the avatar imager — without re-writing any environment variables. The container consequently listens **directly on the host's port 3002**, so stop any previous host-side CMS (e.g. `pm2 stop next`) that occupies that port before starting it.
+
+The **build** also runs on the host network (`build.network: host`) because this host disables Docker iptables (`/etc/docker/daemon.json`: `"iptables": false`), which would otherwise leave build containers without outbound NAT/DNS when fetching packages.
+
+### Health Check
+
+The container includes a health check that hits `/api/health` on port 3002 every 30 seconds (and reports DB/Redis/emulator status). Check status with:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' epicnext-cms
+```
+
+### MariaDB Turbo (bulk loads)
+
+`docker-compose.yml` ships an opt-in **`mariadb-turbo`** service — a dedicated MariaDB 11 container tuned for loading >50 MB JSON dumps (furnidata, external texts, etc.). It configures itself via mysqld flags on the `command:`, so no external `.cnf` file has to be mounted or kept in sync:
+
+```bash
+pnpm db:up        # docker compose --profile db up -d (starts mariadb-turbo)
+```
+
+Key settings (see the `command:` block in `docker-compose.yml`):
+
+- `max_allowed_packet = 512M` — 50 MB JSON batches no longer hit the 16 MB packet ceiling.
+- `innodb_flush_log_at_trx_commit = 2` + `innodb_doublewrite = 0` — durability relaxed for bulk writes.
+- `innodb_buffer_pool_size = 2G`, `innodb_log_file_size = 1G`, `bulk_insert_buffer_size = 512M`.
+- `net_read_timeout` / `net_write_timeout = 600`, `wait_timeout = 3600` — fixes the `drizzle-kit` **"Pulling schema from database..."** hang by never starving introspection/DDL sessions behind a long import.
+- `performance_schema = OFF` — saves ~1-2 GB RAM.
+
+The datadir lives in a **named volume** (`mariadb-turbo-data`), never a host bind-mount: shared-filesystem sync trashes InnoDB files the same way it corrupts pnpm's `node_modules`. Named volumes stay inside the container filesystem, so 50 MB of JSON writes never cross a host-sync boundary.
+
+> **Port note:** the service uses `network_mode: host` and binds `127.0.0.1:3306` — stop the host MariaDB first, otherwise the port collides with the standalone `.env` `DATABASE_URL` (`localhost:3306`).
+
+#### node_modules & host-sync corruption
+
+pnpm's store is hard-linked and its `.bin` shims are symlinks, so **node_modules must never be a host bind-mount** (Docker Desktop gRPC-FUSE/VirtioFS, Unison and Syncthing all corrupt it). The production build bakes `node_modules` into the image at build time; it is never bind-mounted. For local dev, mount a *named volume* (`node_modules:/app/node_modules`) instead of the host directory, and keep `node_modules` / the pnpm store out of any shared-filesystem bind.
+
+#### Loading a 50 MB JSON dump
+
+```bash
+# Habbo furnidata (auto-detects roomitemtypes / wallitemtypes / effecttypes)
+pnpm db:bulk --file=/var/www/Gamedata/config/FurnitureData.json
+
+# Flat array of documents → generic JSON store
+pnpm db:bulk --file=/data/products.json --table=docs --category=furni
+
+# Key/value texts
+pnpm db:bulk --file=/data/external_texts.json --table=texts --category=default
+```
+
+The importer (`scripts/bulk-import-json.ts`) maps rows onto `src/db/schema-gamedata.ts`, batches them into **2000-row multi-row INSERTs** (one statement per chunk), uses `ON DUPLICATE KEY UPDATE` so re-runs are idempotent and interrupted loads resume, and prints rows/s + ETA. See ["ORM Setup & Type Generation"](#orm-setup--type-generation) → *Bulk JSON storage* for the design.
+
+
+---
+
+## ORM Setup & Type Generation
+
+### Drizzle ORM (Primary Data Layer)
+
+Drizzle ORM is the runtime data layer. The connection is a singleton in `src/lib/db.ts`:
+
+```ts
+import { db } from "@/lib/db";
+import { users } from "@/db/schema";
+import { eq } from "drizzle-orm/expressions";
+
+const found = await db.select()
+  .from(users)
+  .where(eq(users.username, "hello"));
+```
+
+**Drizzle CLI** (`drizzle-kit`) is used for local development tasks — it is a devDependency and is never bundled in production.
+
+| Command                | What it does                                                           |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `pnpm db:generate`     | Draft SQL from Drizzle schema into `drizzle/drafts/` (review + copy)   |
+| `pnpm db:studio`       | Open Drizzle Studio (dev only)                                         |
+| `pnpm db:introspect`   | Reverse-engineer an existing DB into a Drizzle schema draft            |
+| `pnpm db:bulk`         | Batch-import >50 MB JSON (2000-row chunks, resumable) via `scripts/bulk-import-json.ts` |
+| `pnpm db:schema:generate` | Regen committed `src/db/schema.ts` from previous schema + live DB   |
+
+> The CMS does **not** use `drizzle-kit push` or `drizzle-kit migrate` — the database is shared with the emulator. Apply CMS DDL only via `pnpm db:migrate`.
+
+#### Bulk JSON storage (MariaDB)
+
+Emulator/hotel JSON dumps (furnidata, external texts, product data) are often >50 MB. MariaDB's `JSON` type is an alias for `LONGTEXT` and can **never be indexed directly**, so `src/db/schema-gamedata.ts` follows the "promote + index" pattern:
+
+- The raw JSON document stays intact in a `longtext` / `mediumtext` column (`payload`, `value`).
+- The fields you actually `WHERE` / `ORDER BY` on are promoted into real columns (`sprite_id`, `class_name`, `kind`, `title`, `text_key`) and indexed.
+- Optional **VIRTUAL generated columns** extract indexed fields from the payload with `JSON_EXTRACT` (MariaDB supports secondary indexes on virtual columns, 10.2+), so no duplicate data has to be written by the importer.
+
+Three tables are exported:
+
+| Table                | Purpose                                        | Unique key                  |
+| -------------------- | ---------------------------------------------- | --------------------------- |
+| `gamedata_furnidata` | One row per furni/clothing item (habbo furnidata_json shape) | `(source, sprite_id)` |
+| `gamedata_docs`      | Generic JSON document store (per-key documents) | `(category, doc_key)`       |
+| `gamedata_texts`     | External-texts style key/value pairs           | `(category, text_key)`      |
+
+The bulk importer (`scripts/bulk-import-json.ts`, run via `pnpm db:bulk`) is DB-driven and fast precisely because each chunk is a *single* multi-row `INSERT … VALUES () ()… ON DUPLICATE KEY UPDATE`, so a 50 MB dump is a few dozen statements instead of hundreds of thousands of round-trips. Flags:
+
+| Flag                 | Default     | Description                                       |
+| -------------------- | ----------- | ------------------------------------------------- |
+| `--file=<path>`      | — (required)| JSON file (habbo furnidata_json or flat array)    |
+| `--table=<name>`     | `furnidata` | One of `furnidata` \| `docs` \| `texts`           |
+| `--source=<x>`       | `habbo`     | `source` value for `furnidata`                    |
+| `--category=<x>`     | `default`   | `category` value for `docs` / `texts`             |
+| `--chunk-size=N`     | `2000`      | Rows per multi-row INSERT                         |
+| `--limit=N`          | `0`         | Stop after N rows (dry-test)                      |
+| `--truncate`         | off         | DELETE rows for this source/category first        |
+
+The script sets `FOREIGN_KEY_CHECKS=0` for the session and is safe to interrupt: each chunk commits on its own, and `ON DUPLICATE KEY UPDATE` makes re-runs overwrite instead of appending.
+
+---
+
+## Valkey (Caching, Rate Limiting, SSE)
+
+Valkey is a drop-in, Redis-compatible open-source in-memory datastore (successor to Redis OSS). The CMS connects to it via `REDIS_URL` using the `ioredis` client. It is optional: without it the CMS falls back to in-memory memory.
+
+### Install (Ubuntu/Debian)
+
+```bash
+# Option 1: Package repository (recommended)
+curl -fsSL https://packages.valkey.io/valkey-pgp-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/valkey-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/valkey-archive-keyring.gpg] https://packages.valkey.io/apt $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/valkey.list
+apt-get update && apt-get install -y valkey
+
+# Option 2: Direct .deb download
+curl -fsSL -o /tmp/valkey_amd64.deb \
+  https://github.com/valkey-io/valkey/releases/download/8.1.1/valkey_8.1.1-1_amd64.deb
+apt-get install -y /tmp/valkey_amd64.deb
+
+systemctl enable --now valkey
+```
+
+### Configure
+
+Edit `/etc/valkey/valkey.conf`:
+
+```ini
+bind 127.0.0.1
+port 6379
+maxmemory 2gb
+maxmemory-policy allkeys-lru
+```
+
+### Point the CMS at it
+
+```dotenv
+REDIS_URL=redis://127.0.0.1:6379?connect_timeout=2
+```
+
+Verify via `/api/health` — it should report `"redis": true`.
+
+---
+
+## Nginx Configuration
+
+The CMS is designed to run behind an nginx reverse proxy. Below is a reference configuration.
+
+### Prerequisites
+
+- SSL certificates in `/etc/ssl/cert.pem` and `/etc/ssl/key.pem` (or use Let's Encrypt)
+- CMS running on `127.0.0.1:3002`
+
+### Reference Configuration
+
+```nginx
+proxy_cache_path /var/cache/nginx/html_cache levels=1:2 keys_zone=html_cache:50m max_size=500m inactive=10m use_temp_path=off;
+
+server {
+    listen 80;
+    server_name yourdomain.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name yourdomain.com;
+
+    ssl_certificate /etc/ssl/cert.pem;
+    ssl_certificate_key /etc/ssl/key.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    client_max_body_size 20m;
+
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    location / {
+        proxy_pass http://127.0.0.1:3002;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_cache html_cache;
+        proxy_cache_valid 200 60s;
+        proxy_ignore_headers Vary;
+        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:3002;
+        add_header Cache-Control "no-cache, no-store, must-revalidate";
+    }
+
+    location /_next/static/ {
+        proxy_pass http://127.0.0.1:3002;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    location /imaging/ {
+        proxy_pass http://127.0.0.1:8082/;
+        proxy_set_header Connection "";
+        proxy_http_version 1.1;
+        add_header Cache-Control "public, max-age=300";
+    }
+
+    location /health {
+        access_log off;
+        return 200 "OK";
+        add_header Content-Type text/plain;
+    }
+}
+```
+
+> **`/imaging` trailing-slash gotcha:** `location /imaging` (no trailing slash) combined with `proxy_pass http://…8082/;` rewrites `/imaging/avatarimage` into `//avatarimage` and 404s. Always use `location /imaging/` + a trailing-slash `proxy_pass` so `/imaging/avatarimage` reaches the imager's `/avatarimage` route.
+
+---
+
+## Avatar Imaging
+
+Avatar images (profile figures, chat badges, forum avatars, admin previews) are rendered server-side by **Polaris-imager** ([duckietm/Polaris-imager](https://github.com/duckietm/Polaris-imager)) — a headless Nitro/Octane renderer that runs `@pixi/node` (real WebGL via `gl` + Xvfb) inside a Docker container named **`avatar-imaging-pixinode`**. It serves `GET /avatarimage?figure=…` on port **8082** and can emit PNG/APNG/GIF, gestures, actions, scenes and more.
+
+### Request flow
+
+```
+browser → Cloudflare → (page rule /origin for /imaging/*) → host:8082
+browser → nginx origin → location /imaging/ → 127.0.0.1:8082/avatarimage
+```
+
+URLs look like `https://<hotel>/imaging/avatarimage?figure=hd-180-1.ch-210-66&img_format=png&size=l&direction=4`. The public `NEXT_PUBLIC_IMAGER_URL` points at that endpoint (see `src/lib/imager.ts`). Responses carry `Cache-Control: public, max-age=300`, so browsers and Cloudflare reuse a render for 5 minutes.
+
+### Requirements (host)
+
+- Docker (daemon with `build.network: host`, same as the CMS build — this host disables Docker iptables).
+- An nginx that serves `/gamedata/` (FigureData/FigureMap/EffectMap…) and `/gamedata/bundled` (`.nitro` assets) over HTTP so the renderer can fetch them. The compose file points at `host.docker.internal:8081`.
+
+### Configuration — `/docker/Polaris-imager/.env`
+
+```dotenv
+NITRO_GAMEDATA_URL=http://host.docker.internal:8081/gamedata/config
+NITRO_ASSET_URL=http://host.docker.internal:8081/gamedata/bundled
+AVATAR_IMAGING_FPS=12
+AVATAR_IMAGING_MAX_FRAMES=60
+AVATAR_IMAGING_HOST=0.0.0.0
+AVATAR_IMAGING_PORT=8082
+AVATAR_IMAGING_RATELIMIT_MAX=600
+AVATAR_IMAGING_SCENE=1
+AVATAR_IMAGING_WARDROBE=1
+AVATAR_IMAGING_HABBO_FONTS=1
+AVATAR_IMAGING_CHAT_BUBBLES=1
+AVATAR_IMAGING_HOTEL_URL=https://<hotel>
+AVATAR_IMAGING_HOTEL_NAME=<hotel>
+```
+
+### Build & start
+
+The image is self-contained — the `Dockerfile` clones the pinned Nitro/Octane renderer and runs the full `yarn`/`vite` bundle at build time, then produces a slim Debian runtime with Xvfb + Mesa software rendering:
+
+```bash
+cd /docker/Polaris-imager
+docker compose build
+docker compose up -d        # container: avatar-imaging-pixinode
+docker logs -f avatar-imaging-pixinode   # expect: "listening on http://0.0.0.0:8082"
+```
+
+The container runs `restart: unless-stopped` and ships a healthcheck that probes `/health` (reports `{ "ready": true }` once the headless renderer has booted). Verify a render:
+
+```bash
+curl -o avatar.png 'http://127.0.0.1:8082/avatarimage?figure=hr-893-45.hd-600-1.ch-255-66.lg-280-110.sh-295-62&img_format=png&size=l'
+```
+
+A production issue that this section documents: **the `avatar-imaging-pixinode` image can be removed by a `docker image prune`**, which takes the whole site's avatars offline (502 on `/imaging/*`). Keep the image tagged and re-build it via the commands above if it ever disappears (`docker compose build && docker compose up -d`).
+
+### Figure string validation (`src/app/api/imaging/avatar/route.ts`)
+
+The CMS-side route re-validates the incoming figure against `/^[a-z]{2}-\d+(-\d+)?(\.[a-z]{2}-\d+(-\d+)?)*$/i`. Real Habbo figure strings use `type-id-color` parts separated by dots (`hd-180-1.ch-210-66`), so each part allows an optional second number. Invalid input is rejected with `400` before any render happens.
+
+---
+
+## Performance Tuning (production)
+
+The CMS shares its MySQL/MariaDB database with the emulator, so the hot wins come from caching, asset serving and database knob-tuning — not from a storage-engine migration.
+
+### 1. gzip_static pre-compression of gamedata JSON
+
+The client downloads `FurnitureData.json` (~48 MB, one file per supported language) plus other large JSON from `/gamedata/`. nginx has `gzip` and `gzip_static on` (see `/etc/nginx/nginx.conf`), but with no pre-built `.gz` file it re-compressed the 48 MB **on every request** (~0.25–0.30 s of CPU per miss).
+
+`scripts/compress-gamedata.mjs` pre-compresses every JSON >1 MB in `<Gamedata>/config` and `<Gamedata>/bundled/config` once (gzip level 9): `FurnitureData*.json` go from ~48 MB to ~2.4 MB (~95 % smaller). It is idempotent — a file is only re-compressed when the source mtime is newer than its `.gz` (e.g. after a Studio catalog export).
+
+```bash
+pnpm gamedata:compress    # manual run
+```
+
+Once the `.gz` exists, nginx `gzip_static` serves it straight from disk with `Content-Encoding: gzip` and effectively zero CPU. **Measured result on the production origin: 0.25–0.30 s → ~0.005 s per file.**
+
+The production host runs the script on a cron so newly exported catalogs are compressed shortly after they land:
+
+```bash
+crontab -e
+# */15 * * * * node /var/www/atom-nexst/scripts/compress-gamedata.mjs >> /var/www/atom-nexst/logs/gamedata-compress.log 2>&1
+```
+
+### 2. MariaDB tuning
+
+The whole `habbo` datadir is roughly 0.5 GB; the default InnoDB buffer pool (128 MB) pushed index/row reads to disk. The pool is raised to **4 GB** and the slow-query log is enabled (threshold 2 s), both live (`SET GLOBAL …`) and persisted for boot in `/etc/mysql/mariadb.conf.d/zz-cms-performance.cnf`:
+
+```ini
+[mysqld]
+innodb_buffer_pool_size = 4G
+slow_query_log = 1
+long_query_time = 2
+slow_query_log_file = /var/log/mysql/mariadb-slow.log
+```
+
+The slow-query log surfaces hot-spot SQL for a follow-up index/query audit. The CMS connection pool itself is already tuned (pool size 25, `connection_limit` in `DATABASE_URL`).
+
+For bulk-written tables (game-data JSON, imports) a containerized **`mariadb-turbo`** variant is available — see [MariaDB Turbo](#mariadb-turbo-bulk-loads).
+
+### 3. Asset caching headers
+
+| Path                           | Cache-Control                                                  |
+| ------------------------------ | -------------------------------------------------------------- |
+| `/swf/**`, `/nitro-assets/**`  | `public, max-age=604800, stale-while-revalidate=2592000`       |
+| `/gamedata/**`, `/client/**`   | `public` + `expires 7–30 d` (nginx)                            |
+| `/imaging/*`                   | `public, max-age=300`                                          |
+| `/camera/**`                   | `public, max-age=31536000, immutable`                          |
+| `/_next/static/**`             | `public, max-age=31536000, immutable`                          |
+
+### 4. Cache layers (Redis + CDN)
+
+The CMS caches through `cached()` / `cachedQuery()` (`src/lib/cache.ts`): an in-memory fast path with a Redis (Valkey-compatible) fallback and single-flight protection against cache stampedes. Public API routes (home, leaderboard, online count, radio, photos, …) fill Redis keys per route; verify with `redis-cli DBSIZE`. With Cloudflare in front, static and `/imaging/*` responses are additionally cached edge-side (`cf-cache-status`), cutting origin load further.
+
+---
+
 ## Production Deployment (PM2)
 
 ```bash
@@ -115,24 +762,31 @@ pnpm build
 pm2 restart next
 ```
 
-The CMS runs behind an nginx reverse proxy on the default port 3000. Static assets (media uploads) are persisted via `/api/media/*` and survive rebuilds.
-
 ---
 
 ## Scripts
 
-| Command                | Description                                        |
-| ---------------------- | -------------------------------------------------- |
-| `pnpm dev`             | Start development server (hot reload)              |
-| `pnpm build`           | Production build                                   |
-| `pnpm start`           | Start production server                            |
-| `pnpm typecheck`       | Run TypeScript type checking                       |
-| `pnpm test`            | Run all tests (Vitest)                             |
-| `pnpm db:migrate`      | Apply pending SQL migrations                       |
-| `pnpm db:migrate:status` | Show migration status                           |
-| `pnpm analyze`         | Build + open bundle analyzer                       |
-| `pnpm jobs:worker`     | Start background task worker (systemd / PM2)       |
-| `pnpm biome:check`     | Lint and format code                               |
+| Command                   | Description                                        |
+| ------------------------- | -------------------------------------------------- |
+| `pnpm dev`                | Start development server (hot reload)              |
+| `pnpm build`              | Production build                                   |
+| `pnpm start`              | Start production server                            |
+| `pnpm typecheck`          | Run TypeScript type checking                       |
+| `pnpm test`               | Run all tests (Vitest)                             |
+| `pnpm db:migrate`         | Apply pending SQL migrations                       |
+| `pnpm db:migrate:status`  | Show migration status                              |
+| `pnpm db:schema:generate` | Regen `src/db/schema.ts` from prior schema + live DB |
+| `pnpm db:generate`        | Draft SQL via drizzle-kit → `drizzle/drafts/`      |
+| `pnpm db:studio`          | Drizzle Studio (dev)                               |
+| `pnpm db:introspect`      | drizzle-kit introspect (draft)                     |
+| `pnpm db:bulk`            | Batch-import >50 MB JSON via `scripts/bulk-import-json.ts` |
+| `pnpm db:up` / `pnpm db:down` | Start / stop the `mariadb-turbo` container     |
+| `pnpm gamedata:compress`  | Pre-compress large gamedata JSON to `.gz` (gzip_static) |
+| `pnpm analyze`            | Build + open bundle analyzer                       |
+| `pnpm jobs:worker`        | Start background task worker                       |
+| `pnpm biome:check`        | Lint and format code                               |
+
+> Replace `pnpm` with `npm run` or `yarn` for other package managers.
 
 ---
 
@@ -142,16 +796,14 @@ The CMS runs behind an nginx reverse proxy on the default port 3000. Static asse
 | ------------------------------ | -------------------------------------------------------------- |
 | **React Compiler**             | Automatic memoization — reduces unnecessary re-renders         |
 | **View Transitions API**       | Native browser transitions between page navigations            |
-| **Lenis Smooth Scroll**        | Fluid, customizable scrolling (respects `prefers-reduced-motion`) |
-| **Server-Sent Events**         | Real-time radio now-playing & listeners via SSE (no polling)   |
-| **Redis Caching**              | Caches API responses (home, radio config) up to 30s in Redis   |
-| **Bundle Analyzer**            | Run `pnpm analyze` to visualize and optimize bundle sizes      |
+| **Lenis Smooth Scroll**        | Fluid, customizable scrolling                                  |
+| **Server-Sent Events**         | Real-time radio now-playing & listeners via SSE                |
+| **Valkey Caching**             | Caches API responses up to 30s in Valkey                     |
 | **RCON (TCP Socket)**          | Live commands to the emulator (credits, badges, kick, ban)     |
 | **Streaming & Suspense**       | Next.js App Router streaming for fast page loads               |
 | **Automatic Image Optimization** | `next/image` with Sharp for resizing and WebP/AVIF          |
-| **CSS-based Animations**       | `input-glow`, `btn-shine`, `Reveal` scroll animations, floating orbs |
 | **Compression**                | Gzip compression enabled on all responses                      |
-| **Stale Times**                | Optimized router cache (30s dynamic, 180s static)              |
+| **gzip_static (gamedata)**     | 48 MB FurnitureData JSON served from pre-built `.gz` — no per-request CPU |
 | **PWA**                        | Service worker with skip-waiting, stale CSS chunk recovery     |
 | **Biome**                      | Fast linting and formatting (replaces ESLint + Prettier)       |
 
@@ -160,44 +812,41 @@ The CMS runs behind an nginx reverse proxy on the default port 3000. Static asse
 ## Architecture
 
 ```
-├── prisma/
-│   ├── schema.prisma          # ~190 models (emulator + CMS)
-│   └── migrations/            # 16 SQL migrations for CMS tables
+├── drizzle/
+│   ├── migrations/            # CMS SQL migrations (idempotent, tracked in cms_migrations)
+│   └── drafts/                # drizzle-kit generate output (never auto-applied)
 ├── scripts/
-│   ├── apply-migrations.ts    # Custom migration runner
+│   ├── apply-migrations.ts    # SQL migration runner (apply + status)
+│   ├── bulk-import-json.ts    # 50 MB+ JSON importer (2000-row chunks, UPSERT)
 │   ├── jobs-worker.ts         # Background task scheduler
-│   └── sql-statements.ts      # SQL parsing utilities
+│   ├── generate-drizzle-schema.mjs # Regen src/db/schema.ts from schema + live DB
+│   └── compress-gamedata.mjs  # Pre-compress large gamedata JSON (gzip_static)
 ├── src/
+│   ├── db/
+│   │   ├── schema.ts          # Drizzle ORM schema (committed — runtime data layer)
+│   │   ├── schema-gamedata.ts # Large-JSON storage schema (furnidata/docs/texts)
+│   │   └── relations.ts       # Drizzle relations
 │   ├── app/                   # Next.js App Router (pages & API routes)
 │   ├── actions/               # Server Actions
 │   ├── components/            # UI components
 │   ├── lib/
 │   │   ├── auth/              # NextAuth, password hashing, 2FA, SSO tickets
 │   │   ├── services/          # RCON, email, currency, PayPal, alerts
-│   │   ├── prisma.ts          # Database connection singleton
-│   │   ├── redis.ts           # Redis client (ioredis)
-│   │   ├── redis-cache.ts     # Redis caching utility for API routes
-│   │   ├── cache.ts           # In-memory cache fallback
-│   │   ├── motion.ts          # Framer Motion animation variants
-│   │   └── use-event-source.ts # React hook for SSE subscriptions
+│   │   ├── db.ts              # Drizzle connection singleton (runtime)
+│   │   ├── redis.ts           # Cache client (ioredis → Valkey)
+│   │   └── motion.ts          # Framer Motion animation variants
 │   ├── messages/              # i18n translations (en, nl, de, fr, es, it, pt, da, no, sv)
 │   └── env.ts                 # Zod-validated environment schema
 ├── public/
 │   ├── assets/                # Images, icons, fonts
-│   └── scripts/               # Client-side scripts (theme-init.js)
-├── update-Nitrov3.sh          # Emulator & Nitro updater utility
+│   ├── nitro-assets/          # Nitro client assets (~3GB, volume-mounted in Docker)
+│   └── swf/                   # SWF client files (volume-mounted in Docker)
+├── docker-compose.yml         # Docker Compose configuration
+├── Dockerfile                 # Multi-stage, multi-package-manager Docker build
 ├── next.config.ts             # Next.js configuration
 └── .env.example               # Environment template with all options
 ```
 
-### Database Ownership
-
-| Component                                         | Type                    | Migrations                          |
-| ------------------------------------------------- | ----------------------- | ----------------------------------- |
-| Emulator tables (`users`, `items`, `rooms`, etc.) | Existing Polaris schema | None — CMS reads/writes only        |
-| CMS tables (`website_*`, `radio_*`, etc.)         | CMS-owned               | `prisma/migrations/*.sql` (16 files) |
-| Migration tracking                                | `cms_migrations` table  | Auto-created by migration runner     |
-
 ---
 
 ## Optional Integrations
@@ -224,25 +873,36 @@ The radio player uses SSE for real-time updates (10s interval, no polling).
 Run as a persistent process:
 
 ```bash
-pnpm jobs:worker
+pnpm jobs:worker    # or: npm run jobs:worker / yarn jobs:worker
 ```
 
-Scheduled tasks:
-- **Daily 03:00** — Emulator JAR backup (requires `EMULATOR_JAR_PATH` + `EMULATOR_BACKUP_DIR`)
-- **Daily 04:00** — Cleanup login logs (>30 days) and expired password reset tokens (>7 days)
-
-### CAPTCHA
-
-Supports Cloudflare Turnstile and Google reCAPTCHA. Configure via CMS Settings.
-
-### Theming
-
-12 preset themes with fully customizable colors via **Admin → Theme** (`/admin/theme`).
-
 ### AI Content Moderation
 
 Optional OpenAI-powered moderation for comments and guestbook posts. Set `OPENAI_API_KEY`.
 
+### Byparr (Cloudflare Bypass)
+
+Some clone sources are protected by Cloudflare. Byparr (a FlareSolverr successor) solves these challenges automatically.
+
+```bash
+docker compose up -d byparr
+```
+
+```dotenv
+BYPARR_URL=http://localhost:8191
+```
+
+### Furniture Import with Auto-Translation
+
+The CMS automatically translates furniture names and descriptions to **13 languages** on every import:
+
+- **Native languages** (via official Habbo gamedata): Dutch, English, German, French, Spanish, Turkish, Italian
+- **Additional languages** (via LibreTranslate Docker at `127.0.0.1:5000`): Portuguese, Finnish, Polish, Russian, Arabic, Japanese
+
+### Theming
+
+12 preset themes with fully customizable colors via **Admin → Theme** (`/admin/theme`).
+
 ---
 
 ## Development
@@ -258,9 +918,10 @@ pnpm biome:check  # Lint and format
 ### Contributing
 
 1. Ensure typecheck and tests pass: `pnpm typecheck && pnpm test`
-2. Follow existing code conventions (Server Components where possible, minimal client boundaries)
-3. Use the `src/lib/motion.ts` animation variants for consistent animations
-4. SQL migrations in `prisma/migrations/` must be idempotent
+2. Follow existing code conventions (Server Components where possible)
+3. SQL migrations in `drizzle/migrations/` must be idempotent
+4. For new database code, use the Drizzle runtime directly (`import { db } from "@/lib/db"`)
+5. Avoid `any` — use `biome-ignore` comments only when unavoidable
 
 ---
 

backups/legacy-delete/items_base_second-batch_2026-09-06T15-01-00-161Z.json

@@ -0,0 +1,205 @@
+[
+	{
+		"id": 132,
+		"sprite_id": 132,
+		"item_name": "floortile",
+		"public_name": "Floor Tile",
+		"type": "s",
+		"width": 1,
+		"length": 1,
+		"stack_height": 0,
+		"allow_stack": 1,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 1,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 420,
+		"sprite_id": 420,
+		"item_name": "soft_jaggara_norja",
+		"public_name": "Norja-pehmojakkara",
+		"type": "s",
+		"width": 1,
+		"length": 3,
+		"stack_height": 1.7,
+		"allow_stack": 1,
+		"allow_sit": 1,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 1,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 1001,
+		"sprite_id": 1001,
+		"item_name": "Chess",
+		"public_name": "",
+		"type": "i",
+		"width": 1,
+		"length": 1,
+		"stack_height": 1,
+		"allow_stack": 1,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 1011,
+		"sprite_id": 1011,
+		"item_name": "TicTacToe",
+		"public_name": "",
+		"type": "i",
+		"width": 1,
+		"length": 1,
+		"stack_height": 1,
+		"allow_stack": 1,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 1021,
+		"sprite_id": 1021,
+		"item_name": "BattleShip",
+		"public_name": "",
+		"type": "i",
+		"width": 1,
+		"length": 1,
+		"stack_height": 1,
+		"allow_stack": 1,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 1659,
+		"sprite_id": 1659,
+		"item_name": "ticket",
+		"public_name": "Big Ticket Bundle",
+		"type": "s",
+		"width": 1,
+		"length": 1,
+		"stack_height": 1,
+		"allow_stack": 1,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "429",
+		"rare": "0"
+	},
+	{
+		"id": 10056,
+		"sprite_id": 10056,
+		"item_name": "Vacuum",
+		"public_name": "laundry_r18_vacuum",
+		"type": "s",
+		"width": 1,
+		"length": 1,
+		"stack_height": 0,
+		"allow_stack": 0,
+		"allow_sit": 0,
+		"allow_lay": 0,
+		"allow_walk": 0,
+		"allow_gift": 1,
+		"allow_trade": 1,
+		"allow_recycle": 0,
+		"allow_marketplace_sell": 0,
+		"allow_inventory_stack": 1,
+		"interaction_type": "default",
+		"interaction_modes_count": 0,
+		"vending_ids": "0",
+		"multiheight": "",
+		"customparams": "",
+		"effect_id_male": 0,
+		"effect_id_female": 0,
+		"clothing_on_walk": "",
+		"page_id": "9966",
+		"rare": "0"
+	}
+]

biome.json

@@ -7,7 +7,7 @@
 	},
 	"files": {
 		"ignoreUnknown": false,
-		"includes": ["**", "!setup", "!*.cjs", "!coverage"]
+		"includes": ["**", "!setup", "!*.cjs", "!coverage", "!drizzle/drafts/meta"]
 	},
 	"formatter": {
 		"enabled": true,

cms

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "${1:-help}" in
+  install) shift; exec bash "$DIR/scripts/docker-install.sh" "$@" ;;
+  update) shift; [[ $# = 0 ]] || { echo "Usage: bash cms update" >&2; exit 1; }; exec bash "$DIR/scripts/docker-update.sh" ;;
+  help|--help|-h) printf '%s\n' 'bash cms install   Configure and install on a Linux Docker host' 'bash cms update    Update using the saved installation settings' ;;
+  *) echo "Unknown command. Use: bash cms install | update" >&2; exit 1 ;;
+esac

docker-compose.yml

@@ -0,0 +1,109 @@
+services:
+  cms:
+    image: epicnext-cms:${CMS_RELEASE:-local}
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        NEXT_DEPLOYMENT_ID: ${CMS_RELEASE:-unknown}
+      network: host
+    container_name: epicnext-cms
+    network_mode: host
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOSTNAME=0.0.0.0
+    volumes:
+      - ./public/nitro-assets:/app/public/nitro-assets
+      - ./public/swf:/app/public/swf
+      - ./storage:/app/storage
+      - /var/www/Gamedata:/var/www/Gamedata
+
+    # ── Resource limits aangepast voor 24 GB RAM ──
+    # Verwijderd: mem_limit, memswap_limit en cpus. Next.js mag onbeperkt presteren.
+    pids_limit: 1024 # Verhoogd van 512 zodat Node.js/Next.js oneindig veel async requests aankan
+
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:3002/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # ── Byparr (Cloudflare bypass for clone sources) ──
+  byparr:
+    image: ghcr.io/thephaseless/byparr:latest
+    container_name: byparr
+    network_mode: host
+    restart: unless-stopped
+    environment:
+      - LOG_LEVEL=INFO
+    
+    # Resource limits verwijderd: Headless Chrome heeft bij zware pagina-scrapes 
+    # soms tijdelijk meer dan 1 GB RAM nodig. Nu krijgt hij alle ruimte.
+    pids_limit: 256
+
+    healthcheck:
+      test: ["CMD", "curl", "http://localhost:8191/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # ── MariaDB "Turbo" (heavy JSON / bulk-loads) ──
+  mariadb-turbo:
+    image: mariadb:11
+    container_name: mariadb-turbo
+    profiles: ["db"]
+    network_mode: host
+    restart: unless-stopped
+    environment:
+      - MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD:-root}
+      - MARIADB_DATABASE=${MARIADB_DATABASE:-habbo}
+      - MARIADB_USER=${MARIADB_USER:-cms}
+      - MARIADB_PASSWORD=${MARIADB_PASSWORD:-cms}
+      - MARIADB_AUTO_UPGRADE=1
+    command: [
+        "--character-set-server=utf8mb4",
+        "--collation-server=utf8mb4_unicode_ci",
+        "--max-allowed-packet=512M",
+        "--net-buffer-length=1M",
+        "--connect-timeout=30",
+        "--wait-timeout=3600",
+        "--interactive-timeout=3600",
+        "--net-read-timeout=600",
+        "--net-write-timeout=600",
+        "--innodb-flush-log-at-trx-commit=2",
+        "--innodb-buffer-pool-size=2G", # Perfect ingesteld voor een 24 GB server!
+        "--innodb-buffer-pool-instances=4",
+        "--innodb-log-file-size=1G",
+        "--innodb-log-buffer-size=64M",
+        "--innodb-flush-method=O_DIRECT",
+        "--innodb-autoextend-increment=512",
+        "--innodb-max-dirty-pages-pct=90",
+        "--bulk-insert-buffer-size=512M",
+        "--innodb-doublewrite=0",
+        "--innodb-use-native-aio=0",
+        "--tmp-table-size=256M",
+        "--max-heap-table-size=256M",
+        "--read-buffer-size=4M",
+        "--read-rnd-buffer-size=16M",
+        "--performance-schema=OFF",
+        "--skip-name-resolve",
+      ]
+    volumes:
+      - mariadb-turbo-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "healthcheck.sh --connect --innodb_initialized || mariadb-admin ping --silent"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    
+    # Geoptimaliseerd: We verhogen de limiet naar 6 GB of halen hem volledig weg, 
+    # zodat de InnoDB buffer pool en zware JSON imports nooit Out Of Memory gaan.
+
+volumes:
+  mariadb-turbo-data:
+    driver: local

docker-image.txt

@@ -0,0 +1 @@
+gitlab.epicnabbo.nl/simo/epicnext-cms

docs/CATALOG_REFACTOR_PLAN.md

@@ -0,0 +1,118 @@
+# Refactor del catalogo HK — analisi e programma
+
+Data: 6 settembre 2026. Base verificata: main, commit 9b0ea2fb. Documento di proposta, non implementazione approvata. Il sito /admin/catalog reindirizza al login senza sessione staff: nessuna prova delle mutazioni sul database di produzione. Le criticità indicate sono percorsi verificati nel codice; gli effetti concorrenti richiedono riproduzione controllata.
+
+## Obiettivo e perimetro
+
+Un catalogo HK con un solo ambiente di lavoro, regole coerenti e operazioni recuperabili. Conservare stile HK, icone reali, salvataggio diretto, catalogo normale e Builder Club. Nessun ritorno dei Preferiti.
+
+Inclusi: albero, categorie, offerte, prezzi, bundle, disponibilità, proprietà condivise dei furni, traduzioni, ricerca, anteprima, operazioni massive, manutenzione, collegamenti a Catalog Studio e sincronizzazione Git/hotel.
+
+Catalog Studio conserva la responsabilità di importare, convertire e riparare .nitro, icone e furnidata. Il refactor collega questi strumenti alla selezione del catalogo; non comporta riscrivere il convertitore, cambiare protocollo dell'emulatore o sostituire il sistema Git/Gitea già esistente.
+
+## Inventario verificato
+
+Sono già presenti virtualizzazione dell'albero, trascinamento, multiselezione, griglia/tabella, editor dei prezzi, anteprima negozio, import massivo, traduzioni, manutenzione e coda di export Git. Vanno riutilizzati.
+
+| File | Righe attuali | Responsabilità da separare |
+|---|---:|---|
+| src/app/admin/catalog/[id]/catalog-items-table/catalog-items-table.tsx | 2342 | Rendering, selezione, editor offerta/furno, prezzi massivi, drag and drop, dialoghi |
+| src/components/admin/catalog-manager/sortable-tree.tsx | 1135 | Lettura albero, mutazioni, ricerca, trascinamento, comandi |
+| src/components/admin/catalog-manager/inline-editor.tsx | 775 | Fetch, stato modifiche, schede, salvataggio, anteprima |
+| src/app/admin/catalog/[id]/catalog-page-form.tsx | 738 | Campi, layout, media, salvataggio |
+| src/app/admin/catalog/[id]/catalog-translate-tab.tsx | 617 | Selezione, proposta traduzioni, applicazione |
+| src/app/admin/catalog/builder-club/bc-manager.tsx | 608 | Gestione parallela BC |
+| src/app/admin/catalog/page.tsx | 526 | Query, conteggi, varianti normale/BC, composizione UI |
+
+Le dimensioni aiutano a trovare i punti di intervento: l'obiettivo non è un limite arbitrario di righe, ma responsabilità verificabili e riutilizzabili.
+
+## Problemi e interventi
+
+| Priorità | Evidenza | Intervento |
+|---|---|---|
+| P0 | sortable-tree.tsx invia il riordino dei fratelli con Promise.allSettled, una action per riga; catalog.ts aggiorna RCON per ciascuna | Un comando batch con lista completa, validazione, transazione e un solo evento di aggiornamento |
+| P0 | catalog-items.ts riordina le offerte con update sequenziali fuori transazione | Stesso contratto atomico per l'ordine delle offerte |
+| P0 | updateCatalogPage accetta parentId direttamente; il controllo cicli è separato in movePage | Validazione comune per creazione, form, spostamento e API; controllare destinazioni inesistenti e concorrenza |
+| P0 | deletePage normale sposta figli, elimina offerte e pagina separatamente | Transazione, analisi dell'impatto e snapshot ripristinabile |
+| P0 | updateCatalogItem modifica pagina, offerta e items_base con scritture separate | Transazione e verifica che il furno appartenga all'offerta; scope distinto per proprietà condivise |
+| P1 | cascadeDelete non mantiene un insieme di nodi visitati; il calcolo profondità BC è ricorsivo senza guardia ai cicli | Lettura tollerante di dati incoerenti, diagnostica e arresto sicuro delle traversate |
+| P1 | handleEditTab modifica lo stato prima della conferma; chiusura X bypassa la protezione | Un unico controllo delle modifiche per cambio pagina, offerta, scheda, uscita e navigazione |
+| P1 | loadPage/loadItemsData non annullano o identificano la richiesta precedente | AbortController e identità della selezione; solo la risposta corrente può aggiornare l'editor |
+| P1 | Il salvataggio ignora il booleano restituito da RCON; Git opera in coda | Distinguere DB salvato, invio hotel riuscito/fallito e stato Git; retry senza risalvare i dati |
+| P1 | loadCatalogItemsData usa Number(value) || fallback per order_number, offer_id e amount | Definire semantica di zero/null per campo e testare il round trip prima di cambiare i fallback |
+| P2 | Tutte le offerte e metadati sono caricati insieme; filtro con CAST(page_id AS CHAR) | Misurare query/payload, separare elenco e dettagli, paginazione e adapter compatibile INT/VARCHAR |
+| P2 | Editor normale/BC e form condividono solo parte delle regole; testi anche letterali | Contratti comuni, differenze BC esplicite, traduzioni e permessi coerenti |
+
+Riferimenti principali: src/actions/catalog.ts, src/actions/catalog-items.ts, src/actions/catalog-bc.ts, src/lib/services/catalog-tree.ts, src/lib/services/catalog-items-loader.ts, src/app/api/admin/catalog/tree/route.ts, src/components/admin/catalog-manager/catalog-manager-dialog.tsx, src/components/admin/catalog-manager/inline-editor.tsx.
+
+## Alternative
+
+1. **Pulizia dei file mantenendo tutti gli editor:** rischio iniziale basso, ma conserva duplicazioni e differenze operative. Utile solo come passaggio iniziale.
+2. **Refactor progressivo con un editor principale — consigliato:** servizi comuni prima, poi promozione del Visual Manager a pagina. Permette piccoli rilasci e confronti tra vecchio e nuovo percorso.
+3. **Riscrittura completa:** libertà maggiore, ma più rischio di perdere casi speciali, compatibilità DB e funzioni già presenti. Non giustificata dall'inventario attuale.
+
+## Architettura proposta
+
+Modulo src/features/catalog con confini chiari:
+
+- domain/: tipi Page, Offer, FurnitureReference, CatalogKind; validazione gerarchie, prezzi, bundle e disponibilità; nessuna dipendenza React/DB.
+- server/queries/: letture albero, elenco offerte, dettaglio e ricerca; output serializzabile esplicito.
+- server/commands/: create/update/move/reorder/delete; autorizzazione, validazione, transazioni, controllo revisione e audit.
+- server/repositories/: accesso Drizzle e compatibilità delle colonne; adapter normale/BC senza fingere che tutti i campi coincidano.
+- client/: stato selezione, modifiche locali, operazioni in corso, caricamento e gestione conflitti.
+- components/: albero, elenco offerte, editor categoria, editor offerta, dettagli furno, diagnostica, stato sincronizzazione.
+
+Le route e le action attuali rimangono inizialmente adapter sottili. Un unico risultato di operazione include ID operazione, revisione, elementi modificati, eventuali errori di campo e stato sincronizzazione. Non introdurre nuove librerie prima di verificare i limiti degli strumenti già installati.
+
+Flusso di scrittura: permesso → validazione → verifica revisione → transazione DB con audit → risposta di salvataggio → aggiornamento hotel/export Git. La durabilità del passaggio DB→coda va garantita con un evento persistito nella transazione o meccanismo equivalente verificato. Un fallimento Git/RCON non deve far ripetere una creazione già committata. Riutilizzare il worker e la coda esistenti, aggiungendo idempotenza dove manca.
+
+## UX proposta
+
+Pagina /admin/catalog con barra: Normale/BC, ricerca, nuova categoria, aggiungi furni, stato operazioni. Sotto: categorie a sinistra, offerte al centro, dettagli a destra. Il pannello dettagli si richiude; su schermi piccoli diventa una vista dedicata. Un solo scorrimento per ciascuna area, azioni di salvataggio sempre raggiungibili.
+
+La URL conserva catalogo, categoria, offerta, vista e ricerca; i campi non salvati restano nello stato locale. Indietro/avanti e ricaricamento devono riaprire il contesto corretto. I vecchi URL dei dettagli continuano a funzionare.
+
+Tre oggetti riconoscibili:
+
+- Categoria: percorso, titolo, icona, layout, visibilità e requisiti.
+- Offerta: prezzo, valuta, quantità, componenti bundle, disponibilità e ordine.
+- Furno condiviso: classname, sprite, dimensioni e interazioni; mostrare quante offerte lo referenziano prima di una modifica globale.
+
+Idee operative:
+
+- Ricerca trasversale per nome, classname, ID pagina/offerta/furno e sprite ID, con percorso nei risultati.
+- Selettore visuale di categoria e layout; proprietà tecniche nelle Avanzate.
+- Prezzi con icone reali delle valute; mostrare il prima/dopo delle operazioni massive, arrotondamenti ed elementi esclusi.
+- Multiselezione con riepilogo di spostamento/eliminazione; dopo un errore mantenere selezionati i falliti.
+- Anteprima del negozio già esistente integrata nel contesto; non presentarla come prova completa del comportamento del client hotel.
+- Diagnostica su richiesta: offerta, SQL, furnidata, Nitro e icona separati. Collegamento a Catalog Studio sul furno esatto; nessuna scansione pesante a ogni apertura.
+- Storico di chi/cosa/quando con differenze e ripristino. Il ripristino controlla revisioni successive: non sovrascrive in silenzio modifiche di altri operatori e non annulla acquisti già avvenuti.
+- Riepilogo visibile: salvato, invio hotel, Git. Gli errori hanno riferimento al monitor CMS.
+- Stati vuoti, errori, caricamento e sola lettura distinti; traduzioni complete e uso da tastiera.
+
+## Programma di lavoro e criteri di uscita
+
+| Lotto | Consegna | Criterio per proseguire |
+|---|---|---|
+| 1. Baseline | Matrice funzioni/route/permessi normale e BC; fixture con bundle, LTD, offerte speciali, zeri/null, alberi incoerenti; misure query e rete | Tutti i flussi esistenti hanno una destinazione nel piano, senza omissioni |
+| 2. Integrità | Validatori, transazioni di riordino/spostamento/eliminazione, gerarchie sicure, revisioni | Un fallimento intermedio non lascia dati parziali; due operatori non si sovrascrivono |
+| 3. Servizi condivisi | Query/command/repository e risultato comune; vecchie route come adapter | Vecchie UI superano le stesse prove con il nuovo backend |
+| 4. Stato editor | Unica gestione delle modifiche, richieste annullabili, risposta coerente con selezione | Annullare l'uscita conserva tutto; cambi rapidi mostrano sempre l'ultima selezione |
+| 5. Pagina unificata | Visual Manager nella pagina, griglia/tabella condivise, URL, layout adattivo | Parità normale/BC e vecchi link conservati; niente perdita di scroll o azioni nascoste |
+| 6. Operazioni avanzate | Ricerca, editor bundle, prezzi massivi con differenze, storico e diagnosi contestuale | Gli effetti sono spiegati prima dell'applicazione; retry applica solo ciò che manca |
+| 7. Sincronizzazione | Stato DB/hotel/Git, operazioni persistenti, retry/idempotenza | Guasto dopo commit e riavvio worker non duplicano né perdono l'operazione |
+| 8. Prestazioni e rimozione duplicati | Paginazione, caricamento progressivo, accessibilità, eliminazione vecchi componenti | Confronto misurato e prove finali; nessuna route o funzione rimasta senza equivalente |
+
+I lotti 2 e 7 condividono il contratto delle operazioni: progettare subito evento persistente e idempotenza, anche se la UI di stato arriva dopo. Nessuna stima in giorni finché non sono note dimensioni reali del catalogo, varianti DB e casi speciali attivi. Ogni lotto può richiedere più PR piccole; niente sostituzione monolitica.
+
+## Verifica e rilascio
+
+Test unitari delle regole; integrazione su MariaDB per rollback, concorrenza e varianti INT/VARCHAR; browser con permessi lettura/modifica, desktop e schermo ridotto. Simulare doppio submit, timeout, risposta fuori ordine, fallimento RCON, Git non raggiungibile, riavvio dopo commit. Conservare test e componenti esistenti finché la parità non è dimostrata.
+
+Registrare baseline e risultati per categorie grandi/piccole: richieste per riordino, tempo DB, payload, tempo fino a editor utilizzabile, risposte fallite. Non promettere percentuali senza dati.
+
+Rilascio progressivo con selezione reversibile del nuovo editor. Il ritorno alla UI precedente deve usare gli stessi servizi corretti. Migrazioni additive e compatibili; il rollback dell'app non deve richiedere la cancellazione di dati. Eliminare le vecchie UI solo dopo parità verificata. Confermare CI, deploy, health e prove staff prima di dichiarare risolto il flusso live.
+
+## Primo passo consigliato
+
+Lotti 1 e 2: inventario di compatibilità e correzione delle operazioni a rischio, mantenendo inizialmente l'aspetto corrente. Poi estrarre i servizi e unificare l'editor. È la sequenza che permette di migliorare UX senza portare avanti gli stessi difetti dentro una nuova schermata.

docs/cms-upgrade-2026-09.md

@@ -0,0 +1,156 @@
+# CMS upgrade — September 2026
+
+## Operator changes
+
+| Area | Behavior and location |
+| --- | --- |
+| Release | Deployment checks HTTP health, release identity and Chromium pages before marking the running image verified. Registry publication reuses that verified digest on the shared runner; independent hosts build and verify their own image. |
+| Shared HK | Dialogs scroll within the available viewport. Table column preferences persist per page in the current browser session; filters already remain in the URL. No favorites added. |
+| Catalog Studio | Dedicated detail drawer and five separate completeness states: SQL, offers, furnidata, icon and Nitro. Sprite/type conflicts are consistently excluded from import and linked to audit. Missing source files are never represented as available. |
+| Operations | Command center includes permission-filtered error groups, personal import failures, open support tickets and news drafts. A failed source is shown separately from an empty source. |
+| Error center | Retained occurrence counts, first/last times, identified users, release counts, self-assignment and recognized local links. Assignment requires edit permission and is audited. |
+| News | Private server-backed autosave, recover/discard/retry, prior saved revisions restored as a draft, and concurrent-edit detection. New status/search filters and pagination make older drafts reachable. |
+| Jobs | Cancellation finishes the current item and stops pending items. Completed work stays completed. Uncertain interrupted mutations are excluded from retry. Live lease checks stop known stale worker writes. |
+| Installation | `/admin/devops/installation` shows release, DB latency, Redis, emulator, storage permissions, migration history and worker heartbeat. Renderer defaults are recognized. Registry access is explicitly unverified from the web process. |
+| Public dashboard | Current/next published event, clearer unread-message action, useful empty/error states and mobile layout refinements. |
+| Audit | Exact actor/action and UTC date filters, readable recorded before/after values and permission-protected CSV of the filtered page, capped at 100 rows. |
+| Performance | Active import polling remains 5 seconds; idle polling is 30 seconds and pauses in hidden tabs. History returns at most 30 owned jobs and initially renders 50 items per job. Health probes are deduplicated within a render; diagnostics report observed probe duration. |
+| Text | New messages are translated in English, Italian and Dutch. Other locales have explicit English fallback strings. Existing translation debt is not reported as resolved. |
+
+## Deployment requirements
+
+- Apply migration `0026_article_editor_recovery.sql` through `pnpm db:migrate` before enabling the new news editor. It adds private drafts and revision tables without modifying existing articles.
+- Keep `storage` persistent and writable. Error assignments and import cancellation markers use the existing shared storage.
+- Run the existing `pnpm jobs:worker` process with the installation configuration. It now publishes a heartbeat to Redis every minute. A web process alone does not establish that scheduled-news jobs are running.
+- The deploy runner installs Chromium before cutover. Browser checks visit only public login/news/staff pages; they do not create production content or authenticate staff. The host must satisfy Chromium system-library requirements.
+- Use the existing Gitea registry secrets. The CMS does not read or display those credentials.
+
+## Boundaries
+
+- Operations is a bounded operational summary: errors use at most 1,000 retained events and imports use the latest 30 owned jobs. Empty checked records do not prove that all historical work is resolved.
+- Import history bounds payloads and concurrent file reads. Directory metadata scanning and worker enumeration still scale with stored history.
+- Redis lease checks and file saves are separate operations. They reduce stale writes but do not provide atomic fencing across Redis, SQL and filesystem operations. An import interrupted after SQL may require local-data inspection.
+- Revision history displays the latest 20 saved versions; revisions are retained in the database. New-article recovery has one private slot per staff account.
+- The database connection probe is a measurement, not a performance benchmark. No throughput or latency improvement is claimed without production measurements.
+- A rollback restores an application image; it does not reverse database migrations. The new tables are additive.
+
+## Verification
+
+Local verification on 2026-09-09:
+
+- Production build succeeded with fixture configuration and an intentionally unavailable database. Build-time fallback logs are expected in this check.
+- Full Vitest run: 254 files passed, 4 skipped; 1,466 tests passed, 6 skipped. Coverage thresholds passed (19.89% lines); this does not imply exhaustive coverage.
+- Global Biome rules/import checks passed across 1,328 files; modified source/locales were formatted separately to avoid unrelated Windows line-ending changes.
+- Translation audit: no invalid ICU messages, variable mismatches or missing static references. Existing locale gaps and 1,560 hardcoded-text candidates still need editorial work; they are not silently marked translated.
+- Headless Edge verification of actual shared components with compiled CSS and the CMS theme at widths 1,280 and 390 pixels: the switch changes state and thumb position, the dialog stays within the 720px viewport, the final button is reachable, and the background page does not scroll. This isolated fixture does not establish full authenticated-page parity.
+- Deployment rollback, verified-digest publication, ownership/cancellation and concurrent news edit behavior have focused regression tests.
+
+Docker runtime, database migration execution and authenticated browser flows still require an integration environment. Check the Gitea pipeline and live release identifier after publication. A successful local build is not production verification.
+
+
+## Catalog packages
+
+The normal catalog toolbar now opens a dedicated Catalog packages dialog.
+Create a named draft from selected categories and their descendants, either to
+update those categories or copy them under a chosen parent. Drafts are shared
+with authorized staff; saving a draft does not modify the live catalog.
+
+Edit category metadata and offer prices, or review bulk price changes before
+applying them to the draft. The catalog preview supports category navigation,
+search, real local furniture icons and rank/Club/VIP access simulation. It does
+not render the game client or evaluate ancestors outside the selected package;
+special layouts and that access limitation are disclosed in the preview.
+
+Publication requires a saved draft and a fresh review. Concurrent source changes
+block publication; version checks prevent one editor overwriting another.
+Copying preserves the underlying category and offer fields and remaps internal
+references while retaining furniture IDs and assets. The catalog writes and
+published result are committed together; retrying the same published package
+does not copy it again. Failures in hotel notifications, audit or Git export
+scheduling after commit are reported as warnings rather than failed publication.
+
+Apply additive migration `0027_catalog_packages.sql` before opening this tool.
+Existing migration automation discovers the file. Limits are 200 categories,
+500 offers and 8 MB of package data. Package source checks inspect at most 20,000
+catalog categories. Publication briefly locks category rows while validating and
+writing changes, so large live catalogs should be checked under realistic load.
+English, Italian and Dutch copy is provided; other locales use the new English
+strings pending translation. No new dependency is required.
+
+Validation: 1,506 tests passed (six skipped), type checking, lint, translation
+contracts and a production build with fixture configuration. A browser fixture
+verified the real dialog at 1280 and 390 pixels; server actions were simulated.
+The new database migration and package publication have not run in production.
+
+## Housekeeping search and user overview
+
+The existing global search now includes furniture, normal/Club catalog categories
+and both ticket sources. Results respect module permissions, accept single-digit
+IDs, and remain usable when one source fails. Keyboard navigation and cancellation
+prevent stale search responses from replacing newer results.
+
+User details open on an operational overview with up to five records from each
+authorized source: bans, active mute, support tickets, help tickets, reports,
+payments, catalog purchases and audit activity. Failed sources are distinguished
+from empty results. User detail and edit pages also apply log permissions before
+loading activity and exposing counters.
+
+Italian and Dutch navigation, user management, news and support labels were
+reviewed. The new search and overview copy has English, Italian and Dutch text;
+other locales receive English fallback strings. This is a focused editorial pass,
+not a full translation of every CMS page. No database migration or dependency
+change is required. Browser checks use real components with simulated data at
+1280 and 390 pixels; production database behavior still needs deployment validation.
+
+## Operational reliability and recovery
+
+- Audit history now records category settings (normal/Club), individual/bulk offer prices, update-mode package publication and news edits inside the write transaction. The audit screen previews and restores individual changes after locking and comparing the current recorded fields. Deleted records, hierarchy changes, LTD counters, imports and historical entries without complete snapshots cannot be restored. Restores create their own history entry. Apply migration `0028_history_snapshots.sql` before running this version: it widens audit snapshots to MEDIUMTEXT without deleting existing data.
+- `/admin/operations` reuses durable import jobs, stable history pagination and owner-scoped failed-item retries. A deterministic child ID prevents duplicate retries. The shared Git export queue displays actual pending/running state and latest result; synchronous/SSE synchronization remains linked rather than represented as a durable job history.
+- Catalog maintenance includes a read-only integrity report for normal/Club categories, offers, furniture references and local icons. Known sentinel IDs are preserved. Only categories pointing to a missing positive parent have an automated repair: preview lists every affected category and apply compares the locked graph before reattaching those categories at the root. No records are deleted. Other issues require an explicit manual edit. Reports display up to 200 issues with complete counts; unavailable icon storage is distinguished from missing assets.
+- CMS errors support exact release and time filters plus frequency sorting. Counts refer to retained matching events, while group resolution remains current across releases.
+- User/settings forms now protect unsaved edits and preserve failed submissions. User/news validation errors appear at the affected fields; settings show returned validation errors inline. Existing submission locking is retained and tested in a browser.
+- `/admin/permissions/preview` shows one role's section access and known CMS grants using live ACL and the existing highest-rank policy. It never changes sessions. Additional user roles, navigation customization and record-specific authorization remain explicit limits of the preview.
+
+New UI copy is supplied in English, Italian and Dutch; other locales receive English fallback strings. No new runtime dependencies. Browser fixtures use real UI components with simulated server responses; the database migration and production behavior have not been exercised on the live hotel.
+
+Validation for this increment: 1,589 tests passed, six skipped; TypeScript, Biome, translation contracts and fixture production build passed. Browser checks covered user/settings/news forms, permission preview, CMS errors, integrity preview and history restore at 1280 and 390 pixels. Double submission, stale preview, blocked navigation, field focus and horizontal overflow were checked with simulated server actions. No live database writes or deployment were performed.
+
+
+## September 11: public pages and staff workflows
+
+- Docker stages now follow the exact `.nvmrc` release, enforced by the toolchain check.
+- `/news` supports search, ordering by effective publication date and real pagination.
+- `/events` supports upcoming/ongoing/completed filters, explicit UTC week windows, local displayed times and personal registrations.
+- `/search` searches users, open rooms, published news and events with independent pagination and partial failure states.
+- `/me` shows support replies, incoming friend requests, the next registered event and available referral rewards. Reply availability does not claim unread status.
+- Profile privacy is managed in `/settings`. Wallet values are private by default; visitors do not receive hidden sections in HTML. Photo galleries initially show six photos and can expand to the loaded limit of 24.
+- Ticket desks support waiting-for-staff and assignment filters, with elapsed time since the latest reply.
+- HK table views save filters, order and visible columns per account and table (maximum 20). Existing session column preferences remain available until a named view is applied.
+- Official and clone synchronization run through the existing durable import queue. Reloading restores history; interrupted uncertain writes still require inspection before repair. Successful items are not repeated.
+- Publication preflight validates URL syntax/protocols and schedules, shows affected page links and keeps existing article previews. It does not claim remote URLs are reachable. Drafts remain savable. Partial event updates preserve omitted fields.
+- Admin APIs return `x-operation-id`; server errors, staff audit records and import jobs share correlation context. Error and audit screens link to each other. Older records without this context remain readable.
+- Public reads distinguish unavailability from empty results and real 404s, preserving independently available sections on home, dashboard, staff, photos, rankings and groups/forums.
+
+### Data and verification
+
+Additive migrations `0029_admin_table_views.sql` and `0030_profile_privacy.sql` run through the existing deployment migration runner. They create CMS-owned tables and do not change emulator user settings. Keep the existing shared storage volume and background jobs worker for durable imports.
+
+Browser verification used real components with controlled data fixtures at 1280 and 390 pixels, including failure and partial-result cases. Production compilation and full lint were checked locally. No production content was created during those checks; real authenticated content and external source availability remain environment-dependent.
+
+## Original furniture bundle recovery and progress
+
+Catalog Studio queued imports and repairs now search other enabled Nitro sources when their initial downloads/conversion produce no local bundle. Recovery checks an exact classname, floor/wall type and positive revision against the source furnidata, then validates the bundle filename, internal name and PNG texture before writing it. It does not copy the alternative source's prices, IDs or descriptive metadata.
+
+The recovery pass checks at most eight eligible sources, excludes the selected source, and has a 20-second network budget with four-second request limits. Catalog downloads are capped at 20 MiB; bundle downloads and attachment decompression are capped at 50 MiB. A bounded catalog cache avoids downloading full furnidata for every item. Blocked or incompatible sources can still require the original bundle to be attached manually.
+
+Import history displays the current phase and elapsed time, the last phase on failure/interruption, and the source/revision of a recovered bundle. Phases are persisted under the existing worker lease; a retry clears old phase/provenance fields. Synchronization jobs also report their existing importer phases, but their clone-specific asset strategy is unchanged.
+
+No additional secrets or environment variables are needed. Source definitions remain managed through the existing source configuration.
+
+## Catalog workflow and public diagnostics
+
+- Bulk offer edits retain the existing preview and now record complete price/category snapshots. The success notification offers an atomic batch Undo for 15 seconds; individual changes remain restorable from audit history afterward. Undo rejects changed records or missing categories rather than overwriting newer edits. No additional migration is needed beyond the existing history snapshot migration.
+- Catalog Studio preserves the existing in-place search/filter/selection flow and now restores list scroll and focus after closing furniture details. Escape closes details before clearing selection. Obsolete list responses cannot replace a newer search; switching source invalidates pending review preparation.
+- Import review groups furniture needing completion, conflicting records and unverified components. Each row lists missing or unknown components and suggests the next action. These are inspection recommendations; final import validation remains authoritative.
+- DevOps performance has separate HK API and public-page groups, each limited to 200 recent samples for one hour. Public instrumentation measures root server page invocations on /me, news, profiles, events and search, including measured database/external work. It excludes metadata, separately rendered children, cached responses that do not invoke the page, network transfer and browser rendering. Static build invocations are excluded. Routes use fixed labels without usernames or search terms; component outcomes are distinct from HTTP status codes.
+- Shared unsaved-change protection now coordinates dirty forms and protects global-search navigation. Prefix, badge and room-furniture editors protect explicit dismissal and remain open after failed saves. Browser Back is intercepted when the cancellable Navigation API is available; reload/close and links retain their existing protection. Prefix saving now waits for the real server action result before closing.

docs/operations/cms-error-center.md

@@ -0,0 +1,85 @@
+# CMS error center and dependency maintenance
+
+Open **HK > DevOps > CMS error center** (`/admin/devops/cms-errors`).
+The previous `/admin/devops/errors` page still displays emulator errors.
+
+## Access and workflow
+
+- Read: existing `admin.devops.view` permission, checked on the server.
+- Mark resolved: `admin.devops.edit`, checked again in the server action; recorded in the staff audit log.
+- Search by event reference, Next.js digest, route, message or deployment version.
+- Expand a group for its latest stack, sanitized context and occurrence references.
+- Marking a group resolved does not delete evidence. A later occurrence reopens it.
+- Refresh is manual so inspecting an expanded error is not interrupted by polling.
+
+## What is collected
+
+Pino `logger.error`, `logServerError`, unexpected action errors, Next.js request
+failures, React error boundaries, uncaught browser errors and unhandled browser
+promise rejections. API wrapper failures return an `errorId`; Next.js boundary
+errors can be correlated by their digest. Release identifiers come from the build.
+Browser reports retain their own client release separately from the receiving server.
+
+Reports are stored in `storage/cms-errors`, using the existing persistent storage
+mount. No third-party service, token or new database table is required.
+Storage does not depend on database availability; viewing the HK and its permission
+checks still require authentication/database availability. Server console logs
+remain the fallback when the CMS itself cannot serve requests.
+
+Retention: seven days; approximately 10 MB/day, 100 queued server writes, and the
+latest 1,000 events in the viewer. Limits are per CMS process/storage volume;
+this is intended for the existing single-instance deployment. Daily expiry runs
+on the next write. The browser endpoint is same-origin, body-size bounded and
+rate-limited. Browser reports are untrusted observations and cannot grant access.
+Known credential patterns and URL parameters are redacted; arbitrary object
+metadata and request bodies are excluded. Avoid putting personal data in error
+messages: this is pattern-based redaction, not a universal data-loss filter.
+
+This does not collect historical console logs, process crashes before framework
+startup, nginx failures, all `console.error` calls, or every handled business
+validation error. A browser stack may point at minified chunks; private source-map
+symbolication and distributed traces are not part of this local viewer. A recorded
+stack is diagnostic evidence, not an automatic root-cause determination.
+
+## Dependencies
+
+`pnpm install --frozen-lockfile`, `pnpm deps:audit`, `pnpm typecheck`, `pnpm test`,
+`pnpm biome:lint`, and `pnpm build` are the verification sequence.
+`pnpm analyze --output` writes a Next.js bundle analysis (not an application build).
+
+TinyMCE 8.9 is pinned in pnpm. `pnpm assets:editor` copies its runtime files and
+license notices to ignored `public/vendor/tinymce`; dev/build run this first.
+The Docker build includes the generated assets. The editor retains its existing
+HTML fields and toolbar; validate saved content and preview when upgrading it.
+
+Lenis has been removed; the public site now uses native scrolling. Other used
+runtime libraries remain. Vitest and its coverage provider are upgraded together;
+`clearMocks: false` preserves initialization-time permission contract assertions.
+
+Renovate uses separate development/UI/Vitest groups with manual merge and a
+three-day release age. The existing external Gitea bot configuration is retained.
+Node/pnpm upgrades remain coordinated with Docker and the runner toolchain.
+Obsolete global overrides were removed; a scoped esbuild override remains because
+Drizzle Kit's loader still resolves a vulnerable legacy development-server build.
+The two deprecated esbuild-kit packages remain upstream dependencies of Drizzle
+Kit; replacing the ORM is not warranted for this tooling issue.
+
+## HK request performance
+
+Open **DevOps → Request performance** (`/admin/devops/performance`). Access requires `DEVOPS_VIEW`; collection only retains requests that passed authentication and permission checks through `withAdmin`.
+
+The view shows recent requests, their server duration, completed database query count/time/errors, monitored curl download count/time/errors, HTTP status and the existing operation ID. Search by route or operation ID, sort by duration or recency, and filter requests taking at least one second.
+
+### Measurement boundaries
+
+- Duration ends when the handler returns its response. Streaming completion, background jobs, browser rendering and public pages are not measured.
+- Database spans wrap the shared mysql2 promise pool and transaction connection query/execute calls. Query parameters and SQL are never collected. Explicit transaction connection acquisition and transaction control methods are not separate spans.
+- External spans currently cover `curlFetchText` and `curlDownload`; ordinary fetch calls and other integrations are not covered.
+- Concurrent dependency durations can exceed wall-clock request duration. Do not subtract the sums to infer application CPU time.
+- Dynamic route values and query strings are removed. No request bodies, headers, usernames, download URLs or SQL text are stored.
+
+### Storage and operation
+
+No new environment variables or packages are required. Redis stores at most 200 recent samples under `cms:performance:v1`, with one-hour retention. Writes are best effort, restricted to an already-ready connection and at most four pending batches; the request never waits for persistence. The view reads at most 200 entries and falls back after one second if shared storage is unavailable.
+
+An in-process buffer preserves up to 200 samples during outages. The page explicitly labels this local mode; it is per instance and disappears on restart. Filtering applies to the retained samples, not complete traffic history. Under load or during storage outages, some shared samples may be omitted.

docs/performance-budgets.md

@@ -0,0 +1,39 @@
+# Informational route JavaScript budgets
+
+Run after the existing production build; no second build or server is needed:
+
+```sh
+node scripts/performance-report.mjs --next-dir .next --config scripts/performance-budgets.json --output-dir build-reports
+```
+
+The command writes `report.json` and `report.md` and prints the Markdown report. An optional `PERFORMANCE_COMMIT_SHA` environment variable records the commit declared by the build caller; the script does not infer that an existing build matches the current checkout. JSON also records `BUILD_ID`, Node/zlib versions, manifest provenance, exact file paths, sizes and source entries.
+
+## What is measured
+
+For each configured App Router route, resolve its exact app path using `app-path-routes-manifest.json` and `server/app-paths-manifest.json`. Read its generated `page_client-reference-manifest.js` as a JSON assignment **without executing JavaScript**. Use its sibling `page/build-manifest.json`, falling back to the root build manifest only if that sibling is absent.
+
+The **initial entry envelope** is the union of route bootstrap `rootMainFilesTree[appPath]` (or `rootMainFiles`) and every `entryJSFiles` list in that route's client-reference manifest. This includes layout, page and boundary/loading entries. The definition follows the data exposed by the installed Next 16.3.4 Turbopack build and the `getLinkAndScriptTags` / `getRequiredScripts` renderer helpers; it is deliberately a build-artifact envelope, not a browser network trace. Conditional rendering, redirects, streaming and browser caches can change actual requests.
+
+- Raw bytes are filesystem byte lengths of unique JavaScript assets in that envelope.
+- Gzip bytes are the **sum of independent gzip level 9 compressions** of those files using the recorded Node/zlib runtime. They are not gzip of concatenated source, nor observed CDN transfer sizes.
+- Deployment query strings and `/_next/` prefixes are normalized before deduplication. Shared files count once per route; each route is measured independently, with no misleading cross-route total.
+- Legacy `nomodule` polyfills are measured separately, outside the modern initial budget. CSS, source maps, images, external scripts, HTML/RSC payloads and async-only chunks absent from `entryJSFiles` are excluded.
+- This report makes no claims about execution cost, LCP, hydration time or real-user performance.
+
+## Initial limits
+
+The first limits are **baseline bytes × 1.15, rounded upward to the next 10 KiB (10,240 bytes)** independently for raw and gzip. They are provisional size alerts, not validated speed targets. Baseline: existing local production build `build-TfctsWXpff2fKS`, Next 16.3.4; its source commit was not inferred.
+
+| Route | Baseline raw bytes | Baseline gzip bytes | Raw limit | Gzip limit |
+| --- | ---: | ---: | ---: | ---: |
+| `/me` | 767156 | 238571 | 890880 | 276480 |
+| `/news` | 765367 | 237599 | 880640 | 276480 |
+| `/events` | 765851 | 237964 | 890880 | 276480 |
+| `/search` | 765851 | 237964 | 890880 | 276480 |
+| `/admin/catalog` | 1654898 | 492619 | 1904640 | 573440 |
+| `/admin/studio/furni` | 1241312 | 391541 | 1433600 | 450560 |
+
+Configured limits are positive integer bytes; `null` explicitly means observe-only. `scripts/performance-budgets.json` remains `mode: informational`. Exceeding a limit produces `over-budget` and a warning, with exit code 0. Missing production `BUILD_ID`, unsupported manifests, missing routes or missing referenced assets produce `unavailable` with a reason and **no partial/zero total**, also exit code 0. Malformed budget configuration or an unwritable output directory fails the command. This keeps initial CI reporting non-blocking while preventing invalid configuration from quietly disabling limits.
+
+Synthetic tests cover shared-chunk deduplication, exact byte/gzip calculations, route bootstrap selection, missing data, safe parsing and CLI exit behavior. Run `pnpm exec vitest run --coverage.enabled=false scripts/performance-report.test.mjs`.
+

docs/superpowers/plans/2026-08-02-furni-import-hotel-source.md

@@ -0,0 +1,111 @@
+# Furni Import Hotel Source Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the furni import visibly and consistently use the CMS `habbo_gamedata_hotel` setting without Italy-specific names or messages.
+
+**Architecture:** Keep locale selection centralized in `getHabboGamedataHotel()` and expose normalized display metadata to the server-rendered import page. Rename the furnidata cache contract to generic official-Habbo terminology, and keep asset downloads on the global `images.habbo.com` CDN.
+
+**Tech Stack:** TypeScript 7, React 19, Next.js 16, Vitest 4.
+
+## Global Constraints
+
+- `habbo_gamedata_hotel` remains the single source of truth.
+- Furnidata and external texts use `www.habbo.<hotel>`.
+- SWF and icon downloads remain on `images.habbo.com`.
+- Cache entries must never leak across two configured hotels.
+- Existing import behavior and permissions remain unchanged.
+
+---
+
+### Task 1: Generic official-Habbo furnidata contract
+
+**Files:**
+- Create: `src/lib/services/habbo-furnidata-cache.test.ts`
+- Modify: `src/types/furni.ts`
+- Modify: `src/lib/services/habbo-furnidata-cache.ts`
+- Modify: `src/lib/services/habbofurni.ts`
+- Modify: `src/lib/services/furni-data.ts`
+- Modify: `src/lib/services/furni-import.ts`
+- Modify: `src/actions/admin-settings.ts`
+- Modify: `src/app/api/admin/import/furni/route.ts`
+- Modify: `src/app/api/admin/import/furni/resync/route.ts`
+- Modify: `src/app/api/admin/import/furni/batch-regen/route.ts`
+
+**Interfaces:**
+- Produces: `OfficialHabboFurniEntry`.
+- Produces: `getOfficialHabboFurnidata()`, `lookupOfficialHabboFurni()`, and `clearOfficialHabboFurnidataCache()`.
+- Consumes: `getHabboGamedataHotel()` and `habboFurnidataUrl(hotel)`.
+
+- [ ] **Step 1: Write a failing cache-isolation test**
+
+Mock the selected hotel as `it` for the first request and `nl` for the second. Return distinct fixtures from `fetch` and assert that the second call returns the Dutch fixture and requests `https://www.habbo.nl/gamedata/furnidata_json/1`.
+
+- [ ] **Step 2: Run the cache test and verify RED**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/habbo-furnidata-cache.test.ts`
+
+Expected: FAIL because the generic official-Habbo API is not exported yet.
+
+- [ ] **Step 3: Rename the cache contract and consumers**
+
+Rename the Italy-specific type and functions throughout the import pipeline. Keep the existing hotel-keyed cache behavior and update comments to say “configured official Habbo hotel”.
+
+- [ ] **Step 4: Run the cache test and verify GREEN**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/habbo-furnidata-cache.test.ts`
+
+Expected: PASS with separate `it` and `nl` fetches.
+
+### Task 2: Display and report the configured source
+
+**Files:**
+- Create: `src/app/admin/import/furni/import-source.test.ts`
+- Create: `src/app/admin/import/furni/import-source.ts`
+- Modify: `src/app/admin/import/furni/page.tsx`
+- Modify: `src/app/admin/import/furni/import-furni-client.tsx`
+- Modify: `src/lib/services/furni-import.ts`
+- Modify: `src/lib/services/furni-import.test.ts`
+
+**Interfaces:**
+- Produces: `FurniImportSource { hotel, label, host, furnidataUrl }`.
+- Produces: `getFurniImportSource()` for the server page.
+- Produces: `formatOfficialHabboEnrichmentWarning(hotel, name)`.
+
+- [ ] **Step 1: Write failing source and message tests**
+
+Assert that an `nl` setting becomes `{ hotel: "nl", label: "Netherlands (habbo.nl)", host: "habbo.nl", furnidataUrl: "https://www.habbo.nl/gamedata/furnidata_json/1" }` and that enrichment reports `Enriched from habbo.nl`.
+
+- [ ] **Step 2: Run the tests and verify RED**
+
+Run: `pnpm exec vitest run --coverage=false src/app/admin/import/furni/import-source.test.ts src/lib/services/furni-import.test.ts`
+
+Expected: FAIL because source metadata and the dynamic warning formatter do not exist.
+
+- [ ] **Step 3: Implement source metadata and UI**
+
+Read the normalized hotel on the server page, pass source metadata into `ImportFurniClient`, and render a compact source badge/link above the furni controls. Replace literal `habbo.it` enrichment wording with the resolved host.
+
+- [ ] **Step 4: Run focused verification**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/habbo-furnidata-cache.test.ts src/app/admin/import/furni/import-source.test.ts src/lib/services/furni-import.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Run repository verification**
+
+Run:
+
+```text
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Expected: all commands exit with status 0 using the same non-secret production validation environment as CI where required.
+
+- [ ] **Step 6: Commit the implementation**
+
+```text
+fix: use configured Habbo hotel in furni import
+```

docs/superpowers/plans/2026-08-02-manual-recent-furni-resync.md

@@ -0,0 +1,357 @@
+# Manual Recent Furni Resync Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a guarded Tools command to Admin Import Furni that resyncs furniture imported during the last seven days and displays the operation result.
+
+**Architecture:** Keep the existing permission-protected `/api/admin/import/furni/resync` route unchanged. Add a client-safe request/normalization helper with an injected fetcher so its exact URL, HTTP method, success payload, partial failures, and transport failures are testable without rendering the large Import Furni client. The existing client component owns the confirmation, loading, and result UI state.
+
+**Tech Stack:** TypeScript, React 19, Next.js 16 App Router, Vitest, shadcn/Radix UI, Sonner, Biome.
+
+## Global Constraints
+
+- The operation targets only `furni_import` audit entries from the last seven days.
+- Use the existing `ASSETS_IMPORT`-protected endpoint and `adminFetch` CSRF flow.
+- Do not expose `all=1`, delete database rows, or regenerate `.nitro`, SWF, or icon files.
+- Display examined, resynced, failed, RCON status, and returned per-item errors.
+- Prevent duplicate submissions while a request is active.
+
+---
+
+### Task 1: Tested recent-resync client contract
+
+**Files:**
+- Create: `src/lib/admin/recent-furni-resync.ts`
+- Test: `src/lib/admin/recent-furni-resync.test.ts`
+
+**Interfaces:**
+- Consumes: a fetcher matching `(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>`.
+- Produces: `RECENT_FURNI_RESYNC_URL`, `RecentFurniResyncError`, `RecentFurniResyncResult`, and `requestRecentFurniResync(fetcher): Promise<RecentFurniResyncResult>`.
+
+- [ ] **Step 1: Write the failing request-contract tests**
+
+Create `src/lib/admin/recent-furni-resync.test.ts`:
+
+```ts
+import { describe, expect, it, vi } from "vitest";
+import {
+	RECENT_FURNI_RESYNC_URL,
+	requestRecentFurniResync,
+} from "./recent-furni-resync";
+
+describe("requestRecentFurniResync", () => {
+	it("posts to the fixed seven-day resync endpoint and normalizes the result", async () => {
+		const fetcher = vi.fn(async () =>
+			Response.json({
+				ok: true,
+				mode: "days",
+				days: 7,
+				examined: 4,
+				resynced: 3,
+				failed: 1,
+				rconOk: false,
+				errors: [{ classname: "chair", message: "invalid entry" }],
+			}),
+		);
+
+		await expect(requestRecentFurniResync(fetcher)).resolves.toEqual({
+			examined: 4,
+			resynced: 3,
+			failed: 1,
+			rconOk: false,
+			errors: [{ classname: "chair", message: "invalid entry" }],
+		});
+		expect(RECENT_FURNI_RESYNC_URL).toBe(
+			"/api/admin/import/furni/resync?days=7",
+		);
+		expect(fetcher).toHaveBeenCalledWith(RECENT_FURNI_RESYNC_URL, {
+			method: "POST",
+		});
+	});
+
+	it("throws the API error when the request fails", async () => {
+		const fetcher = vi.fn(async () =>
+			Response.json({ error: "Forbidden" }, { status: 403 }),
+		);
+
+		await expect(requestRecentFurniResync(fetcher)).rejects.toThrow(
+			"Forbidden",
+		);
+	});
+});
+```
+
+- [ ] **Step 2: Run the tests and verify RED**
+
+Run:
+
+```powershell
+pnpm exec vitest run --coverage=false src/lib/admin/recent-furni-resync.test.ts
+```
+
+Expected: FAIL because `recent-furni-resync.ts` does not exist.
+
+- [ ] **Step 3: Implement the minimal typed request helper**
+
+Create `src/lib/admin/recent-furni-resync.ts`:
+
+```ts
+export const RECENT_FURNI_RESYNC_URL =
+	"/api/admin/import/furni/resync?days=7";
+
+export interface RecentFurniResyncError {
+	classname: string;
+	message: string;
+}
+
+export interface RecentFurniResyncResult {
+	examined: number;
+	resynced: number;
+	failed: number;
+	rconOk: boolean;
+	errors: RecentFurniResyncError[];
+}
+
+type AdminFetcher = (
+	input: RequestInfo | URL,
+	init?: RequestInit,
+) => Promise<Response>;
+
+export async function requestRecentFurniResync(
+	fetcher: AdminFetcher,
+): Promise<RecentFurniResyncResult> {
+	const response = await fetcher(RECENT_FURNI_RESYNC_URL, { method: "POST" });
+	const payload = (await response.json()) as Record<string, unknown>;
+	if (!response.ok) {
+		throw new Error(
+			typeof payload.error === "string" ? payload.error : "Furni resync failed",
+		);
+	}
+
+	const errors = Array.isArray(payload.errors)
+		? payload.errors.filter(
+				(value): value is RecentFurniResyncError =>
+					typeof value === "object" &&
+					value !== null &&
+					typeof (value as RecentFurniResyncError).classname === "string" &&
+					typeof (value as RecentFurniResyncError).message === "string",
+			)
+		: [];
+
+	return {
+		examined: Number(payload.examined) || 0,
+		resynced: Number(payload.resynced) || 0,
+		failed: Number(payload.failed) || 0,
+		rconOk: payload.rconOk === true,
+		errors,
+	};
+}
+```
+
+- [ ] **Step 4: Run focused tests and verify GREEN**
+
+Run:
+
+```powershell
+pnpm exec vitest run --coverage=false src/lib/admin/recent-furni-resync.test.ts
+pnpm exec biome check --write src/lib/admin/recent-furni-resync.ts src/lib/admin/recent-furni-resync.test.ts
+```
+
+Expected: 2 tests pass and Biome reports no remaining errors.
+
+- [ ] **Step 5: Commit the tested contract**
+
+```powershell
+git add -- src/lib/admin/recent-furni-resync.ts src/lib/admin/recent-furni-resync.test.ts
+git commit -m "feat: add recent furni resync client contract"
+```
+
+### Task 2: Import Furni Tools action and result UI
+
+**Files:**
+- Modify: `src/app/admin/import/furni/import-furni-client.tsx`
+- Consume: `src/lib/admin/recent-furni-resync.ts`
+
+**Interfaces:**
+- Consumes: `requestRecentFurniResync(adminFetch): Promise<RecentFurniResyncResult>`.
+- Produces: a `Tools → Update imported furni` action, confirmation dialog, loading state, and dismissible result panel.
+
+- [ ] **Step 1: Add state and the guarded request handler**
+
+Import `DatabaseZap`, `RecentFurniResyncResult`, and
+`requestRecentFurniResync`. Add state alongside the existing reorganization
+state:
+
+```ts
+const [confirmRecentResync, setConfirmRecentResync] = useState(false);
+const [recentResyncing, setRecentResyncing] = useState(false);
+const [recentResyncResult, setRecentResyncResult] =
+	useState<RecentFurniResyncResult | null>(null);
+```
+
+Add the handler near `startReorganize`:
+
+```ts
+async function resyncRecentImports() {
+	setConfirmRecentResync(false);
+	setRecentResyncing(true);
+	setRecentResyncResult(null);
+	try {
+		const result = await requestRecentFurniResync(adminFetch);
+		setRecentResyncResult(result);
+		if (result.examined === 0) {
+			toast.info("No imported furni found in the last 7 days");
+		} else if (result.failed > 0 || !result.rconOk) {
+			toast.warning("Furni resync completed with warnings");
+		} else {
+			toast.success(`Updated ${result.resynced} imported furni`);
+		}
+		fetchStats();
+	} catch (error) {
+		toast.error(
+			error instanceof Error ? error.message : "Furni resync failed",
+		);
+	} finally {
+		setRecentResyncing(false);
+	}
+}
+```
+
+- [ ] **Step 2: Add the Tools entry and duplicate-submit guard**
+
+Insert before the Tools separator:
+
+```tsx
+<DropdownMenuItem
+	onClick={() => setConfirmRecentResync(true)}
+	disabled={recentResyncing}
+>
+	{recentResyncing ? (
+		<Loader2 className="mr-2 h-4 w-4 animate-spin" />
+	) : (
+		<DatabaseZap className="mr-2 h-4 w-4" />
+	)}
+	{recentResyncing ? "Updating imported furni..." : "Update imported furni"}
+</DropdownMenuItem>
+```
+
+- [ ] **Step 3: Add the confirmation dialog**
+
+Add a controlled dialog beside the existing batch confirmation dialogs:
+
+```tsx
+<Dialog open={confirmRecentResync} onOpenChange={setConfirmRecentResync}>
+	<DialogContent className="max-w-sm">
+		<DialogHeader>
+			<DialogTitle>Update imported furni?</DialogTitle>
+			<DialogDescription>
+				This updates FurnitureData for furni imported during the last 7 days,
+				then refreshes the emulator catalog and item caches. No database rows or
+				asset files are deleted.
+			</DialogDescription>
+		</DialogHeader>
+		<DialogFooter>
+			<Button variant="outline" onClick={() => setConfirmRecentResync(false)}>
+				Cancel
+			</Button>
+			<Button onClick={resyncRecentImports} disabled={recentResyncing}>
+				Update last 7 days
+			</Button>
+		</DialogFooter>
+	</DialogContent>
+</Dialog>
+```
+
+- [ ] **Step 4: Render a dismissible result panel**
+
+Place the panel after the existing error banner and before batch summaries:
+
+```tsx
+{recentResyncResult && (
+	<div className="rounded-lg border bg-card p-4 space-y-3">
+		<div className="flex items-center justify-between gap-3">
+			<h3 className="text-sm font-semibold">Imported Furni Update</h3>
+			<Button
+				variant="ghost"
+				size="sm"
+				onClick={() => setRecentResyncResult(null)}
+			>
+				Dismiss
+			</Button>
+		</div>
+		<div className="flex flex-wrap gap-4 text-sm">
+			<span>{recentResyncResult.examined} examined</span>
+			<span className="text-[var(--admin-success)]">
+				{recentResyncResult.resynced} updated
+			</span>
+			<span className={recentResyncResult.failed ? "text-destructive" : ""}>
+				{recentResyncResult.failed} failed
+			</span>
+			<span
+				className={
+					recentResyncResult.rconOk
+						? "text-[var(--admin-success)]"
+						: "text-[var(--admin-warning)]"
+				}
+			>
+				RCON {recentResyncResult.rconOk ? "refreshed" : "not refreshed"}
+			</span>
+		</div>
+		{recentResyncResult.errors.length > 0 && (
+			<details className="text-xs">
+				<summary className="cursor-pointer text-muted-foreground">
+					View errors
+				</summary>
+				<div className="mt-2 max-h-48 space-y-1 overflow-y-auto">
+					{recentResyncResult.errors.map((error) => (
+						<p key={`${error.classname}:${error.message}`}>
+							<span className="font-mono">{error.classname}</span>: {error.message}
+						</p>
+					))}
+				</div>
+			</details>
+		)}
+	</div>
+)}
+```
+
+- [ ] **Step 5: Run focused and static verification**
+
+```powershell
+pnpm exec biome check --write src/app/admin/import/furni/import-furni-client.tsx src/lib/admin/recent-furni-resync.ts src/lib/admin/recent-furni-resync.test.ts
+pnpm exec vitest run --coverage=false src/lib/admin/recent-furni-resync.test.ts src/lib/services/furni-data-paths.test.ts
+pnpm typecheck
+```
+
+Expected: Biome clean, focused tests pass, and TypeScript exits 0.
+
+- [ ] **Step 6: Run complete regression verification**
+
+```powershell
+pnpm test
+$env:NODE_ENV='production'
+$env:DATABASE_URL='mysql://test:test@localhost:3306/test?charset=utf8mb4'
+$env:AUTH_SECRET='ci-test-secret-key-that-is-long-enough'
+pnpm build
+```
+
+Expected: all tests pass and the production build exits 0. Redis/database
+availability warnings during static generation are acceptable in the local test
+environment; compilation or route-generation errors are not.
+
+- [ ] **Step 7: Commit the UI integration**
+
+```powershell
+git add -- src/app/admin/import/furni/import-furni-client.tsx
+git commit -m "feat: add manual recent furni resync action"
+```
+
+- [ ] **Step 8: Verify the final repository state**
+
+```powershell
+git status --short
+git log --oneline origin/main..HEAD
+```
+
+Expected: clean worktree and the design, plan, tested helper, and UI commits are
+ahead of `origin/main`, ready for an explicit push request.

docs/superpowers/plans/2026-08-02-production-furni-assets.md

@@ -0,0 +1,126 @@
+# Production Furni Assets Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make every furni import write the icon, Nitro bundle, and FurnitureData entry into the directories served by the production client under `/var/www/Gamedata`.
+
+**Architecture:** Extend the central furni asset resolver with a separate Gamedata layout while preserving CMS-local and Nitro-Files targets. Both import paths consume the same resolved targets; FurnitureData resolves the same Gamedata root independently so metadata and binary assets stay aligned.
+
+**Tech Stack:** TypeScript 7, Node.js filesystem APIs, Vitest 4, Next.js 16.
+
+## Global Constraints
+
+- Preserve all existing `nitro_files_root`, `furni_*_dir`, and `furni_data_mirror_path` behavior.
+- Auto-detect `/var/www/Gamedata` only when the directory exists; allow `gamedata_root` to override it.
+- Do not copy source SWFs into the Gamedata tree.
+- Report live mirror failures in the import warnings.
+- Use test-first development and run the production build before completion.
+
+---
+
+### Task 1: Resolve the production Gamedata layout
+
+**Files:**
+- Create: `src/lib/services/furni-asset-dirs.test.ts`
+- Modify: `src/lib/services/furni-asset-dirs.ts`
+- Modify: `src/lib/services/furni-data.ts`
+- Modify: `src/app/admin/settings/cms-settings-config.ts`
+
+**Interfaces:**
+- Produces: `getGamedataRoot(): Promise<string>`.
+- Produces: Gamedata mirror entries from `getFurniAssetWriteTargets()` with `<root>/icons` and `<root>/bundled/furniture`.
+- Consumes: `siteSettings.get("gamedata_root", "")` and `existsSync(DEFAULT_GAMEDATA_ROOT)`.
+
+- [ ] **Step 1: Write failing resolver tests**
+
+Mock `siteSettings.get` and `existsSync`, then assert that a configured Gamedata root produces:
+
+```ts
+expect(targets.mirrorDirs).toContainEqual({
+  swfDir: targets.swfDir,
+  iconDir: path.join(gamedataRoot, "icons"),
+  nitroDir: path.join(gamedataRoot, "bundled/furniture"),
+});
+```
+
+Also assert that an absent unconfigured root adds no Gamedata mirror and that a duplicate primary destination is de-duplicated.
+
+- [ ] **Step 2: Run the resolver test and verify RED**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/furni-asset-dirs.test.ts`
+
+Expected: FAIL because `gamedata_root` is not read and the Gamedata mirror is absent.
+
+- [ ] **Step 3: Implement the Gamedata resolver**
+
+Add `DEFAULT_GAMEDATA_ROOT`, `getGamedataRoot()`, and a pure Gamedata mapping that uses the primary `swfDir` while mapping icons and Nitro bundles to the live locations. Merge this candidate with the existing Nitro-Files candidate and remove identical directory triples.
+
+- [ ] **Step 4: Extend FurnitureData and the settings form**
+
+Make `getFurnitureDataWritePaths()` include `<gamedata_root>/config/FurnitureData.json`, after any explicit `furni_data_mirror_path`. Add a documented `gamedata_root` text setting with `/var/www/Gamedata` as the placeholder.
+
+- [ ] **Step 5: Run resolver tests and verify GREEN**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/furni-asset-dirs.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit Task 1**
+
+```text
+fix: map furni imports to production gamedata
+```
+
+### Task 2: Mirror manual Nitro uploads
+
+**Files:**
+- Create: `src/lib/services/upload-import.test.ts`
+- Modify: `src/lib/services/upload-import.ts`
+
+**Interfaces:**
+- Consumes: `getFurniAssetWriteTargets(): Promise<FurniAssetWriteTargets>`.
+- Produces: manual upload copies at every unique `mirrorDirs[].iconDir` and `mirrorDirs[].nitroDir`.
+
+- [ ] **Step 1: Write a failing manual-upload test**
+
+Mock the database and metadata dependencies, provide temporary primary and Gamedata directories, call `uploadSingleFurni`, and assert:
+
+```ts
+await expect(fs.readFile(path.join(liveNitroDir, "chair.nitro"))).resolves.toEqual(nitroBuffer);
+await expect(fs.readFile(path.join(liveIconDir, "chair_icon.png"))).resolves.toEqual(iconBuffer);
+```
+
+- [ ] **Step 2: Run the upload test and verify RED**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/upload-import.test.ts`
+
+Expected: FAIL because manual uploads currently write only to the primary CMS directories.
+
+- [ ] **Step 3: Implement manual mirroring**
+
+Resolve all write targets, create their directories through the existing `ensureDirectories()`, and copy the successfully written primary Nitro and optional icon files to each unique mirror. Catch each copy error separately and append a warning containing the destination path.
+
+- [ ] **Step 4: Run the upload test and verify GREEN**
+
+Run: `pnpm exec vitest run --coverage=false src/lib/services/upload-import.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Run focused and full verification**
+
+Run:
+
+```text
+pnpm exec vitest run --coverage=false src/lib/services/furni-asset-dirs.test.ts src/lib/services/upload-import.test.ts src/lib/services/furni-import.test.ts
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Expected: every command exits with status 0.
+
+- [ ] **Step 6: Commit Task 2**
+
+```text
+fix: mirror manual furni uploads to live assets
+```

docs/superpowers/plans/2026-09-06-catalog-operations.md

@@ -0,0 +1,21 @@
+# Catalog operations upgrade plan
+
+User approved bulk editing and complete category duplication, keeping Visual Manager in its button-opened modal.
+
+Use subagent-driven-development for the independent duplication task; root owns bulk operations and final review.
+
+- [x] Duplicate category subtree and offers atomically for normal/BC; preview counts, destination/name, fresh IDs, preserve furniture references; fail on stale source, invalid destination, cycles and insert failure. Shared permissions, single export/RCON outcome. UI in Visual Manager.
+- [x] Extend selected-offer operations to preview and atomically apply prices, currency, and destination. Visibility belongs to categories, so expose it separately with exact affected categories; no fictitious per-offer flag. Preserve unselected and unrelated fields; conflicts prevent overwriting concurrent changes.
+- [x] Meaningful domain/transaction/action tests, browser fixtures for modal preview/confirm, typecheck/Biome/i18n/Knip; review limits and commit exact scope.
+
+No production data mutations, added dependencies or schema migrations. Full category duplication shares existing items_base definitions and asset files. Repeated confirmations must be disabled while saving. Preview should be revalidated under locks before write. Existing direct save and permissions remain.
+
+## Implementation notes
+
+Bulk editing now works from selected normal-catalog offers and from selection across global searches. Only explicitly chosen prices/currency/destination fields change. Prices support set/add/percentage with integer rounding and range validation; 500 selected offers per transaction. Preview binds rows, changes and category names; concurrent changes reject confirmation. Category visibility remains on the existing category controls, not a fabricated offer property. BC has no offer pricing and does not expose that editor.
+
+Duplication copies up to 500 categories and 5000 offers, preserving bundle and asset references. New root starts disabled and hidden. Includes and internal offer IDs are remapped. Explicit normal offer IDs use the existing allocator and do not require AUTO_INCREMENT; database collisions roll back the whole copy. Preview binds destination siblings as well as source data so confirmed preview replay is rejected. Dirty editor state blocks copying saved data until drafts are saved/reset.
+
+No database migration or dependency added. Database transaction tests use mocks and do not prove live MariaDB locking behavior. Browser fixtures use real components with mocked actions, not production writes. Existing allocator is process-local; competing external imports may cause a safe rollback requiring a fresh preview. No automatic retry of uncertain copy commits.
+
+Verification complete: 1339 unit tests passed, 5 skipped. Typecheck/Knip/i18n and changed-file Biome checked. Real-component browser fixtures passed bulk selection, preview, conflicts, pending guards, mobile bounds and table refresh without phantom drafts; duplication nested inside actual manager verified menus, picker, preview and dirty-state guards. Fixed manager portal layering and invalid menu-label nesting uncovered by those tests. Browser actions are mocked; no live data written or deployment claimed.

docs/superpowers/plans/2026-09-06-catalog-refactor.md

@@ -0,0 +1,29 @@
+# Catalog refactor implementation plan
+
+> For agentic workers: use superpowers:subagent-driven-development for independent changes and review each deliverable.
+
+Goal: deliver the approved progressive catalog refactor while preserving current features.
+Architecture: shared domain validation and transactional commands behind existing action contracts; unified editor reuses current views and tools.
+Stack: Next, React, Drizzle/MariaDB, Zod, Vitest, Playwright; no added dependencies.
+Spec: docs/CATALOG_REFACTOR_PLAN.md
+Constraints: preserve normal/BC differences, direct save, real icons, permissions, existing routes, no favorites. No production data mutations for testing.
+
+- [x] Characterize compatibility and command rules with tests; capture baseline source map.
+- [x] Domain hierarchy/reorder validation and transactional page commands (normal/BC), deterministic locking, common updates/deletion.
+- [x] Offer update/reorder atomicity and safe numeric normalization, shared mutation contracts.
+- [x] Editor cancellation/dirty state protection (agent catalog_editor_state), review and browser verification.
+- [x] Promote editor as an in-page view with reversible classic view, URL context, responsive panels and coherent tool access.
+- [ ] Sync outcomes/diagnostics/history integration; safe retry and explicit limits.
+- [ ] Verify unit tests, database integration if runtime available, browser, typecheck, lint/i18n, full suite; review final scope and remaining environment-only checks.
+
+Execution notes: changes are progressive, no destructive migration. Existing UI adapters stay until functional parity is tested. Whole-program completion must not be claimed from the first deliverable.
+
+## First implementation delivery (2026-09-06)
+
+Completed: shared normal/BC page and offer commands; transactional page reorder/delete/move and offer create/update/reorder; hierarchy validation and optimistic page-save checks; embedded default manager with classic views retained; request cancellation, editor unsaved-change guards and URL selection; bounded global category/offer/furniture search; separate hotel/Git status and hotel retry; export-finalization failures no longer mask committed server actions. Existing permissions and direct-save behavior retained. No added dependency or DB migration.
+
+Verification: full unit suite 1308 passed / 5 skipped before final retry-classification regression; final focused catalog suite 96 passed. TypeScript, i18n static validation, Knip and Biome on all 54 changed source files pass. Browser fixtures cover editor loading races, retry failures, unsaved changes, URL history, read-only, normal/BC, search and 375px layout. Database calls and mutations are mocked in those fixtures. Full-repository formatter check reports pre-existing Windows CRLF formatting differences; unrelated files were not reformatted.
+
+Remaining roadmap: per-operation durable dispatch/outbox, category/offer snapshot history and conflict-aware undo, contextual maintenance diagnosis, pagination/performance measurement against representative real data, further decomposition of retained legacy views. Existing coarse audit/export infrastructure remains; the new status file is not a durable outbox and RCON socket success does not prove client application. External furni importer mutation internals remain outside shared editor commands.
+
+Environment checks still required: real MariaDB locking/rollback integration, staff-authenticated end-to-end smoke test and pipeline/deployment health. No production mutations performed; no production deployment claimed.

docs/superpowers/specs/2026-08-02-furni-import-hotel-source-design.md

@@ -0,0 +1,40 @@
+# Furni import hotel source
+
+## Problem
+
+The furni import already fetches furnidata through the CMS setting
+`habbo_gamedata_hotel`, but its public and internal language still refers to
+Habbo Italy. This makes the active source unclear and gives the impression
+that the importer is hardcoded to `habbo.it`.
+
+## Design
+
+The import page will read `habbo_gamedata_hotel` on the server and pass the
+normalized hotel value and label to the client. The page will display the
+active official furnidata source near the import controls, including the
+resolved `habbo.<hotel>` host.
+
+Import enrichment warnings will use the resolved hotel label rather than the
+literal `habbo.it`. Internal furnidata cache APIs and types will be renamed
+from Italy-specific names to generic official-Habbo names while retaining
+temporary aliases only where needed to avoid an unsafe all-at-once migration.
+
+Furniture SWF and icon downloads remain on `images.habbo.com`. That host is
+Habbo's global asset CDN and must not be derived from the gamedata locale.
+
+## Data flow
+
+1. Admin settings stores `habbo_gamedata_hotel`.
+2. Server-side import code normalizes the value through
+   `getHabboGamedataHotel()`.
+3. Furnidata and external texts use `www.habbo.<hotel>`.
+4. The import UI and enrichment messages display the same resolved hotel.
+5. The in-memory cache remains keyed by hotel, so changing the setting loads
+   the selected locale rather than reusing another locale's data.
+
+## Verification
+
+Tests will cover normalized locale URL generation, cache separation after a
+hotel change, dynamic enrichment text, and the source information passed to
+the import UI. Existing furni import tests, typecheck, full tests, and the
+production build must pass.

docs/superpowers/specs/2026-08-02-manual-recent-furni-resync-design.md

@@ -0,0 +1,70 @@
+# Manual Recent Furni Resync Design
+
+## Goal
+
+Add a safe manual command to the existing Admin Import Furni screen for
+refreshing furniture imported during the last seven days. The command must
+update the live FurnitureData metadata and emulator caches without deleting
+database rows or regenerating existing asset bundles.
+
+## User interface
+
+Add `Update imported furni` to the existing `Tools` dropdown on
+`/admin/import/furni`.
+
+Selecting it opens a confirmation dialog that states the fixed scope: furniture
+recorded by the admin audit log as imported during the last seven days. While
+the operation is running, the action and confirmation button are disabled and a
+loading state is shown to prevent duplicate requests.
+
+After completion, show a result panel containing:
+
+- examined item count;
+- successfully resynced item count;
+- failed item count;
+- emulator RCON refresh status;
+- returned per-item errors, when present.
+
+## Data flow
+
+The client sends an authenticated, CSRF-protected `POST` request through
+`adminFetch` to the existing endpoint:
+
+`/api/admin/import/furni/resync?days=7`
+
+The endpoint remains authoritative for selecting the targets. It reads only
+`ItemsBase` IDs referenced by `admin_audit_log` entries whose action is
+`furni_import`, target is `ItemsBase`, and timestamp falls within the last seven
+days.
+
+For each target, the existing resync logic rebuilds its FurnitureData entry,
+enriches it from the configured `habbo_gamedata_hotel`, and upserts it into the
+live `FurnitureData.json`. It then requests `updateCatalog` and `updateItems`
+through RCON.
+
+## Safety and permissions
+
+- Reuse the endpoint's `ASSETS_IMPORT` permission check and admin CSRF guard.
+- Do not expose a UI option for `all=1`.
+- Do not delete or recreate `items_base` or catalog rows.
+- Do not regenerate `.nitro`, SWF, or icon files.
+- Keep returned errors visible without treating an RCON failure as a successful
+  refresh.
+
+## Error handling
+
+Network or non-JSON failures produce an error toast and leave the command
+available for retry. A successful API response is rendered even when individual
+items failed, so the administrator can distinguish partial completion from a
+request failure.
+
+The result panel is dismissible. Running the command again replaces the prior
+result.
+
+## Verification
+
+- Unit-test the result normalization used by the UI, including partial failures
+  and RCON status.
+- Verify that the client calls exactly `resync?days=7` through `adminFetch`.
+- Run focused tests, Biome, TypeScript, the full test suite, and a production
+  build.

docs/superpowers/specs/2026-08-02-production-furni-assets-design.md

@@ -0,0 +1,55 @@
+# Production furni asset destinations
+
+## Problem
+
+The production Nitro client loads furniture icons from `/gamedata/icons`,
+furniture bundles from `/gamedata/bundled/furniture`, and furniture metadata
+from `/gamedata/config/FurnitureData.json`. The importer currently derives its
+mirror paths using the development `Nitro-Files` layout. On the production
+server this creates paths such as `swf/dcr/hof_furni/icons` and
+`nitro-assets/bundled/furniture` below the configured root, which are not the
+directories served by the live client. Manual `.nitro` uploads do not mirror
+assets at all.
+
+Files written only below the CMS `public` directory are also not durable: the
+deployment workflow cleans untracked files from the CMS checkout.
+
+## Design
+
+Keep the existing CMS-local and `Nitro-Files` destinations for compatibility,
+and add the deployed Gamedata tree as a distinct asset layout. In production,
+`/var/www/Gamedata` is detected automatically when it exists. A configurable
+`gamedata_root` setting can override that location for other installations.
+
+The Gamedata layout maps assets as follows:
+
+- icons: `<gamedata_root>/icons`
+- Nitro furniture: `<gamedata_root>/bundled/furniture`
+- FurnitureData: `<gamedata_root>/config/FurnitureData.json`
+- source SWFs: not copied into Gamedata because the Nitro client does not load
+  them; existing CMS-local and `Nitro-Files` SWF handling remains unchanged
+
+Both the normal Habbo importer and manual `.nitro` uploader use the same write
+target resolver. Duplicate destinations are removed before writing.
+
+## Error handling
+
+The CMS-local write remains the primary operation. Every configured or
+auto-detected live destination is treated as an expected mirror. Directory or
+copy failures are returned as import warnings containing the failed target,
+instead of being silently ignored. A successful import therefore cannot hide
+that the live client asset copy failed.
+
+## Compatibility
+
+Existing `nitro_files_root`, `furni_swf_dir`, `furni_icon_dir`,
+`furni_nitro_dir`, and `furni_data_mirror_path` behavior is preserved. The new
+Gamedata destination is additive, so Windows development using the
+`Nitro-Files` layout continues to work.
+
+## Verification
+
+Unit tests will cover Gamedata path derivation, automatic production-root
+detection through an injected root, destination de-duplication, and manual
+upload mirroring. Existing importer tests, type checks, and the production
+build must remain green.

docs/superpowers/specs/2026-08-10-public-avatar-currency-design.md

@@ -0,0 +1,69 @@
+# Public Avatar Thumbnail and Currency Icon Design
+
+## Goal
+
+Make avatar and currency presentation consistent across the public site:
+
+- user thumbnails in lists and compact cards show only the avatar head at a fixed 40 x 40 pixel size;
+- full-body avatars remain available on profile pages and deliberately large previews;
+- currency amounts use the existing graphical currency icons instead of placeholder letters such as `c`, `cr`, `du`, or `di`.
+
+## Scope
+
+The change covers public-facing pages and shared public components. It includes rankings, leaderboards, shop and badge-purchase currency rows, plus every other compact user list or card that currently renders an avatar directly.
+
+Admin-only screens are outside this visual cleanup unless they reuse a shared public component changed by this work. Profile hero avatars, the main current-user avatar, registration/login previews, and other intentionally large previews retain their full-avatar presentation.
+
+## Avatar Design
+
+Compact user representations will use one shared semantic thumbnail path rather than choosing imager options independently in each page.
+
+The thumbnail contract is:
+
+- request `headOnly: true` from the avatar imager;
+- render at 40 x 40 CSS and image dimensions;
+- preserve pixel-art rendering and contain the image without stretching;
+- prevent the thumbnail container from shrinking into adjacent text;
+- use the user's actual figure and the existing avatar URL fallback behavior;
+- keep useful alternative text based on the displayed username where that context is available.
+
+The existing shared avatar component will be extended with an explicit compact/head-thumbnail variant, or a narrowly focused wrapper will be added if that keeps call sites clearer. Public list and compact-card call sites will migrate to this shared contract. Large/profile call sites will remain explicit so they cannot be accidentally cropped by a global CSS rule.
+
+## Currency Design
+
+All public currency amount rows will use the existing `CurrencyIcon` component and the existing assets under `public/assets/images/icons/currency`.
+
+The mapping is:
+
+- credits: `credits.png`;
+- duckets: `duckets.png`;
+- diamonds/crystals: `diamonds.png`.
+
+Icons will be decorative when the surrounding UI already names the currency, using an empty alternative text to avoid repeated screen-reader announcements. The numeric amount and existing pill/layout styling remain unchanged. Icon size will be fixed consistently for compact amount rows, with no textual placeholder left visible.
+
+## Migration Strategy
+
+1. Add the shared compact avatar contract and focused tests.
+2. Inventory public avatar call sites and classify each as compact thumbnail or large/profile preview.
+3. Migrate every compact call site to the shared head-only 40 x 40 rendering.
+4. Replace textual and empty CSS currency markers in public amount rows with `CurrencyIcon` and the correct currency kind.
+5. Remove CSS rules that exist only to draw obsolete letter-based or background-only markers, while retaining layout classes still used by the amount pills.
+
+This semantic migration is preferred over a global CSS crop because it sends the correct head-only request to the imager and does not risk changing profile avatars.
+
+## Verification
+
+Verification will include:
+
+- automated tests for the compact avatar contract (`headOnly`, fixed dimensions, actual figure propagation);
+- source/component checks ensuring public currency rows use `CurrencyIcon` with the correct mapping and no placeholder letters remain;
+- the existing test, type-check, and build commands relevant to the changed files;
+- visual checks at desktop and narrow widths for rankings, leaderboard, shop, badge purchase, and representative user lists/cards;
+- explicit checks that profile pages and large avatar previews still render full avatars.
+
+## Non-goals
+
+- changing balances or currency business logic;
+- changing the avatar imager service itself;
+- redesigning profile hero sections;
+- modifying admin-only layouts that do not share the affected public components.

docs/superpowers/specs/2026-08-24-housekeeping-modernization-design.md

@@ -0,0 +1,438 @@
+# Housekeeping modernization design
+
+Date: 2026-08-24
+Status: approved in design review; awaiting review of this written specification
+
+## Purpose
+
+Replace the current administration experience with one coherent, role-adaptive Housekeeping (HK) at `/admin`.
+
+The new HK is a modular part of the existing Next.js application. It is built in parallel, validated against the current system, and exposed with one atomic cutover. It unifies the current `/admin` and `/mod` surfaces, removes duplicated workflows, and preserves reliable domain services without automatically preserving their current pages.
+
+This document is the master architecture for the program. It is deliberately not one giant implementation plan. Delivery is split into independently specified and verified subprojects, beginning with **Inventory & Foundation**.
+
+## Current-state findings
+
+- The repository currently contains 124 `page.tsx` files below `src/app/admin` and 13 below `src/app/mod`: 137 administration pages in total.
+- `src/lib/admin-nav.ts` currently exposes nine navigation groups and seven hub definitions.
+- `/admin` and `/mod` provide overlapping moderation, ticket, ban, team, and user workflows with separate shells.
+- `/admin/housekeeping` is a legacy permission archive/comparison/export surface, while `/admin/permissions` is the live permission-management surface.
+- The current dashboard reports useful counts but is not an operational work queue.
+- Page composition, localization, ACL checks, filtering, error handling, and action feedback are not yet uniform across the administration surface.
+
+The migration must therefore classify every current page. A visual refresh without workflow and boundary changes is insufficient.
+
+## Approved decisions
+
+| Area | Decision |
+| --- | --- |
+| Audience | One role-adaptive HK. Effective capabilities, not rank names alone, determine what an operator sees and can do. |
+| Entry point | `/admin` is the only administration entry point after cutover. `/mod` is removed. |
+| Layout | Command Deck: compact domain rail, contextual navigation, global command palette, operational workspace. |
+| Personalization | Hybrid: the system supplies mandatory capability-derived content; the operator may pin and reorder allowed shortcuts and optional widgets. |
+| Compatibility | Clean break. Old subroute compatibility and legacy UX are not preserved through redirects. |
+| Build strategy | Build the new HK in parallel, keep it unavailable to normal production operators, then switch atomically. |
+| Work queue | “Da fare ora” is derived from existing sources. It is not a second task database and never owns workflow state. |
+| Command palette | It navigates, searches entities, and executes only safe commands. Sensitive actions open a dedicated contextual flow. |
+| Architecture | Modular hybrid replacement inside the current application: reuse sound services, rebuild weak UI/workflows, merge duplicates, and remove obsolete surfaces. |
+
+## Goals
+
+1. Give each operator one clear, capability-appropriate place to work.
+2. Replace feature sprawl with six stable domains and consistent page contracts.
+3. Make urgent work visible without copying or diverging from source workflow state.
+4. Enforce authorization, validation, transaction boundaries, error semantics, and audit behavior server-side.
+5. Remove `/mod`, the legacy HK archive page, duplicate hubs, and manual navigation concepts that the new foundation owns.
+6. Reach explicit functional, authorization, audit, localization, accessibility, and data-parity gates before cutover.
+7. Keep rollback practical without exposing a mixed legacy/new experience.
+
+## Non-goals
+
+- Creating a separate HK application, microservice, or deployment.
+- Creating a new assignment/task system for the operational inbox.
+- Preserving every current page, route, component, or interaction.
+- Adding backward-compatible redirects for removed administration subroutes.
+- Providing full sensitive-workflow parity on phones. The target is desktop-first with usable tablet layouts.
+- Redesigning public CMS or game-client experiences as part of this program.
+- Replacing sound domain logic solely for architectural uniformity.
+
+## Architecture
+
+### Modular monolith
+
+The HK remains inside EpicNext CMS and uses the application's existing authentication, database, service, localization, and deployment infrastructure.
+
+The target source organization separates composition from behavior:
+
+```text
+src/app/admin/                         route composition only
+src/features/housekeeping/
+  foundation/                         shell, registry, ACL context, preferences
+  domains/
+    operations/                       derived inbox, global search, recent work
+    people/
+    content/
+    economy/
+    hotel/
+    system/
+src/lib/services/                     existing and extracted domain services
+```
+
+The exact filenames are an implementation-plan concern, but the boundaries are mandatory:
+
+- App Router files compose pages and bind route parameters; they do not own business rules.
+- The foundation owns cross-cutting HK behavior and does not mutate domain data.
+- Each domain owns its queries, commands, search providers, inbox providers, widgets, and page composition.
+- Domains do not import another domain's UI internals. Cross-domain interaction uses registered contracts or links to the owning route.
+- Existing reliable services are adapted behind domain contracts rather than copied into the new UI.
+
+### Module manifest and registry
+
+Every domain exports a manifest with stable identifiers for:
+
+- domain metadata and localized labels;
+- routes and contextual navigation;
+- required capabilities;
+- command-palette entries;
+- entity-search providers;
+- derived-inbox sources;
+- mandatory and optional dashboard widgets.
+
+The foundation composes these manifests into the rail, contextual navigation, palette, dashboard, and route metadata. Contract tests reject duplicate IDs, duplicate routes, missing localization keys, unknown capability slugs, and commands without an owner.
+
+The manifest registry replaces hand-maintained duplication between the sidebar, hubs, search, and dashboards. It is code-owned and reviewable. Operator preferences can alter presentation only within what the registry and capability context permit.
+
+### Capability context
+
+The server creates one request-scoped capability context from the authenticated operator and the existing ACL source.
+
+- Capability checks are based on effective permission slugs.
+- Super-administrator behavior remains explicit and testable.
+- Rank may help choose default presentation, but never grants access by itself.
+- Navigation filtering is a usability feature, not an authorization boundary.
+- Every query and command rechecks its capability on the server and defaults to deny.
+
+## Functional domains
+
+| Domain | Owns | Representative current areas |
+| --- | --- | --- |
+| Da fare & operations | Derived inbox, global search, recent work, favorites, operational summaries | Dashboard, selected alerts and cross-domain counts; projections only |
+| People & community | Users, online state, accounts, guilds, applications, staff directory, moderation, support | Users, multi-accounts, guilds, applications, CFH, moderation actions, bans, IP/VPN, word filter, tickets, help tickets, `/mod/*` |
+| Content & engagement | Public/editorial content and engagement workflows | Articles, photos, media, banners, ads, events, polls, help content, tags, prefixes, writable boxes, email content, branding/localization surfaces |
+| Economy & catalog | Products, value, commercial assets, and economic history | Catalog, items, import/maintenance, shop, marketplace, transactions, vouchers, subscriptions, rare values, badges, achievements, sounds |
+| Hotel & world | Live hotel surfaces and world-management tools | Rooms, navigator, radio, studio/runtime asset tools, contextual hotel actions |
+| System, access & observability | Configuration, authorization, diagnostics, and privileged operations | Permissions, access audit, settings, maintenance, emulator, command center, logs, analytics, alerts, DevOps |
+
+Where an existing feature spans two domains, responsibility follows the action rather than the old route. For example, the staff directory belongs to People, while the policy granting staff capabilities belongs to System and Access.
+
+Domain landing pages summarize their own workflows. They do not recreate the global dashboard or become a second source of state.
+
+## Operator experience
+
+### Command Deck shell
+
+The shared shell contains:
+
+1. A compact rail for the six domains.
+2. Contextual navigation generated from the active domain manifest.
+3. A global command/search field available by keyboard.
+4. A main workspace using consistent title, context, primary action, filters, content, and feedback regions.
+5. Operator identity, effective-capability context, notifications, and session controls.
+
+The shell is desktop-first, fully keyboard operable, and responsive for tablets. Phone layouts may support inspection and low-risk triage, but sensitive multi-step operations are not optimized for phone use.
+
+### Adaptive dashboard
+
+ACL and capability data determine:
+
+- visible domains and routes;
+- mandatory queues and warnings;
+- permitted metrics and widgets;
+- available commands and search providers.
+
+The operator may:
+
+- pin allowed routes and safe commands;
+- reorder shortcuts and optional widgets;
+- add or remove optional allowed widgets;
+- persist preferred filters and presentation density where supported.
+
+The operator may not hide mandatory warnings, reveal unauthorized data, or preserve a shortcut after its required capability is lost.
+
+Preferences are server-persisted, user-scoped, schema-versioned, and non-authoritative. If no suitable existing preference store exists, the foundation adds one additive `housekeeping_user_preferences` store containing presentation state only. It never stores task status or authorization decisions. Every preference is reconciled with the current manifest and capability context when read.
+
+### Standard page contract
+
+Every target page follows the same structural contract:
+
+- localized title, description, breadcrumb/context, and one clear primary action;
+- capability-derived actions with server authorization;
+- shared filtering, pagination, empty, loading, partial, and error states;
+- explicit unsaved-change behavior for editable forms;
+- consistent confirmation and outcome feedback;
+- stable deep links to owned entities and workflows;
+- responsive table-to-detail behavior without hiding critical fields;
+- audit context for mutations.
+
+## Operational inbox
+
+The inbox is a read model over domain-owned sources such as tickets, CFH reports, alerts, emulator errors, and detected anomalies.
+
+Each source emits normalized work items containing at least:
+
+- stable source and item IDs;
+- domain and required capability;
+- severity and source timestamp;
+- localized summary and optional context;
+- stable destination route and entity target;
+- deduplication key;
+- freshness/availability metadata.
+
+The aggregator:
+
+1. Requests sources independently with bounded timeouts.
+2. Filters every result against the operator's capability context.
+3. Deduplicates by stable source identity.
+4. Orders by severity, age, and domain policy.
+5. Returns both items and per-source availability.
+
+The aggregator never creates, assigns, dismisses, or completes work. Selecting an item opens the owning workflow. If that workflow supports assignment or resolution, those state changes occur there.
+
+A failed or timed-out source does not erase successful sources. The UI labels the missing source and the freshness of remaining data instead of presenting the whole system as healthy.
+
+## Global search and command palette
+
+The palette has three provider types:
+
+1. **Navigation providers** for permitted routes and favorites.
+2. **Entity providers** for capability-filtered entities such as users, rooms, tickets, articles, or catalog entries.
+3. **Safe command providers** for narrowly scoped, validated, idempotent or reversible actions.
+
+A mutation may run directly from the palette only when it is single-target, low impact, reviewable in the palette, protected by a specific capability, and safe against duplicate submission. It still uses the normal server command and audit path.
+
+Destructive, economic, moderation, permission, bulk, or otherwise sensitive actions return a navigation intent. The target page receives validated context and shows impact, current state, required reason, confirmation, and final outcome.
+
+## Data and command flow
+
+### Queries
+
+```text
+page or shell
+  -> request-scoped capability context
+  -> typed domain query
+  -> existing API/repository through an adapter
+  -> sanitized response
+```
+
+The UI does not query arbitrary tables or reproduce sensitive filter rules. Authorization-sensitive results are filtered at the query boundary. Short-lived caching may be used for operational counts, but authorization is applied after cache lookup and sensitive per-user results are not shared across capability contexts.
+
+### Commands
+
+```text
+intent
+  -> server capability check
+  -> schema validation
+  -> current-state/concurrency check
+  -> domain transaction or controlled external call
+  -> audit outcome
+  -> typed result and cache invalidation
+```
+
+Every command receives a server-issued action ID used as an idempotency key. Duplicate submissions return the original known outcome rather than repeating the mutation.
+
+For records with a revision or update timestamp, edits use optimistic concurrency. A stale edit returns a conflict result and current-state reference; it is not silently overwritten. Where a source cannot expose a revision, the command performs the strongest available transactional re-read before mutation.
+
+## Security and audit
+
+- Default-deny server checks protect every query and command.
+- Sensitive actions require a dedicated flow, an explicit target, an impact summary, confirmation, and a non-empty operator reason.
+- Domain validation occurs after authorization and before mutation.
+- Audit is append-only from the HK application: no HK route can edit or delete audit events.
+- Audit records include actor, target, command, reason, sanitized before/after details where appropriate, outcome, timestamp, action ID, and correlation ID.
+- Secrets, credentials, tokens, and unnecessary personal data are excluded from audit payloads.
+- When data and audit share a transactional store, a privileged mutation and its audit record commit together.
+- For external operations, an intent/pending audit record is written before dispatch and completed with success or failure afterward.
+- A privileged mutation fails closed if its required audit trail cannot be established.
+
+## Error model
+
+Domain boundaries return typed outcomes rather than leaking raw infrastructure errors:
+
+- validation failure;
+- authentication required;
+- capability denied;
+- not found;
+- stale/conflicting state;
+- dependency unavailable;
+- partial aggregate result;
+- unexpected internal failure.
+
+Expected outcomes have localized, actionable messages. Unexpected failures expose a correlation ID to the operator and retain technical detail only in server logs. Forms preserve safe input after recoverable failures. Lists and the operational dashboard distinguish empty results from unavailable data.
+
+## Migration inventory
+
+The first subproject creates a committed migration matrix covering all 137 current pages. Each row contains:
+
+- legacy path and source surface (`admin` or `mod`);
+- target domain and owning workflow;
+- target path;
+- decision: `REHOST`, `REBUILD`, `MERGE`, or `REMOVE`;
+- required read and mutation capabilities;
+- source queries and mutations;
+- audit requirement;
+- localization and accessibility status;
+- required unit, integration, and E2E coverage;
+- parity evidence and migration status.
+
+Decision meanings:
+
+- **REHOST**: the current UI and service are sound enough to enter the new shell after contract and ACL adaptation.
+- **REBUILD**: preserve the workflow and sound service logic, but reconstruct its interaction and page composition.
+- **MERGE**: combine duplicated routes or variants into one owning workflow with contextual views.
+- **REMOVE**: eliminate obsolete or foundation-owned behavior at cutover.
+
+Mandatory consolidations:
+
+- All 13 `/mod` pages merge into People and Community workflows. `/mod` does not redirect after cutover.
+- `/admin/housekeeping` ceases to exist as a named feature. Useful comparison/export history moves into System, Access, and Audit.
+- `/admin/permissions` remains the live policy editor under System and Access.
+- Legacy dashboard, hub, and manual HK-navigation concepts are removed when their responsibilities are supplied by the registry and Command Deck.
+
+No page is considered migrated merely because it renders in the new shell. Its matrix row closes only after data, actions, capability behavior, audit, localization, accessibility, and required tests pass.
+
+## Delivery decomposition
+
+This master design controls the program. For delivery purposes it is also the approved design specification for subproject 01. Subprojects 02 through 06 require their own scoped design specifications before their implementation plans. Subprojects are delivered in this order:
+
+### 01. Inventory & Foundation
+
+This is the first and only scope of the initial implementation plan.
+
+Deliverables:
+
+- the complete 137-page migration matrix;
+- HK manifest contracts and registry validation;
+- request-scoped capability context and server guard interfaces;
+- domain query, command, search, inbox, and widget contracts;
+- the Command Deck shell primitives and standard page-state contract;
+- six domain manifests with no migrated business workflow yet;
+- a non-production/test-only entry mechanism that cannot expose a mixed HK to normal production operators;
+- contract, capability, localization-key, accessibility-smoke, and shell tests.
+
+Explicit exclusions:
+
+- no current `/admin` or `/mod` route changes;
+- no production operator exposure;
+- no operational inbox aggregation;
+- no entity search implementation;
+- no domain mutation migration;
+- no legacy deletion.
+
+### 02. Access, audit & system core
+
+Implement the capability enforcement adapters, audit command path, error taxonomy, correlation IDs, and core observability used by every later vertical.
+
+### 03. People, moderation & support
+
+Deliver the first complete vertical and unify user, ticket, CFH, moderation-action, and ban workflows. This vertical proves the future removal of `/mod` without exposing a partial cutover.
+
+### 04. Command Deck operations
+
+Implement global search, safe commands, favorites, preferences, and the derived inbox against the sources available from completed verticals.
+
+### 05. Remaining domain verticals
+
+Deliver separate scoped specifications and plans for:
+
+1. Content and Engagement;
+2. Hotel and World;
+3. Economy and Catalog;
+4. remaining System, Access, and Observability pages.
+
+Economy and permission-affecting mutations receive the strictest confirmation, concurrency, and audit coverage.
+
+### 06. Parity, cutover & cleanup
+
+Close the migration matrix, run cross-role journeys and data comparisons, switch `/admin`, make `/mod` unreachable, observe the release, then delete unreachable legacy code and later remove obsolete schema safely.
+
+Subproject 01 uses this specification; every later subproject has its own spec, implementation plan, tests, review, and completion gate. A later subproject may not silently expand an earlier approved scope.
+
+## Verification strategy
+
+Every subproject runs proportionate checks from these layers:
+
+1. **Unit tests** for manifest parsing, normalizers, policy functions, reducers, and domain services.
+2. **Contract tests** for unique IDs/routes, capability declarations, localization keys, command ownership, and provider behavior.
+3. **Integration tests** against representative repository/API implementations, including transactions, external failures, idempotency, and conflicts.
+4. **ACL matrix tests** covering permitted, denied, capability-revoked, and super-administrator cases at both render and server boundaries.
+5. **E2E journeys** for moderation, support, editorial, economy, hotel operations, and administration roles defined by capabilities rather than rank labels.
+6. **Audit assertions** after every tested mutation.
+7. **Accessibility checks** for keyboard use, focus order, names, contrast, live feedback, dialogs, and table/detail transitions.
+8. **Localization checks** rejecting new hard-coded operator copy and missing translation keys.
+9. **Visual regression checks** for the shared shell and high-risk standard states.
+10. **Performance comparison** against a recorded legacy baseline using the same environment and dataset. Comparable new flows may not regress median or p95 response time by more than 10% without an explicit reviewed exception. Performance improvements are reported only from measurements.
+
+## Cutover gate
+
+The atomic switch is permitted only when all of the following are true:
+
+- all 137 migration rows are closed with evidence;
+- every exposed query and command has a declared and tested capability;
+- every mutation has validation and required audit coverage;
+- no blocking or critical defect remains open;
+- equivalent legacy/new counts and records have been compared for migrated read workflows;
+- role journeys for moderator, support operator, editor, economy operator, hotel operator, and administrator pass;
+- localization, accessibility, build, type, lint, test, and visual checks pass;
+- production-like smoke tests, backup verification, rollback procedure, and health checks have been rehearsed;
+- the new HK is not dependent on legacy UI routes;
+- communication and operator runbooks are ready for the clean break.
+
+## Cutover and rollback
+
+Before cutover, the new HK is exercised through test/staging or an explicit non-production mechanism. Read-only shadow comparisons may run against representative data. There is no production dual-write.
+
+At cutover:
+
+1. `/admin` changes to the new route composition in one release/flag transition.
+2. `/mod` and removed legacy subroutes become unreachable without compatibility redirects.
+3. Smoke tests verify authentication, capability filtering, representative reads, one controlled mutation per risk class, audit, and health signals.
+
+Database changes required before cutover are additive and backward-compatible for the emergency rollback window. A flag or previous release can temporarily restore the legacy application if the cutover fails. During normal operation, only one HK is exposed.
+
+After the agreed stability window, unreachable legacy code and flags are removed. Destructive schema cleanup is a later migration and is not coupled to the cutover release.
+
+## Success criteria
+
+The program is complete when:
+
+- `/admin` is the single role-adaptive administration surface;
+- `/mod` and the legacy Housekeeping archive surface are gone;
+- all 137 legacy pages have an evidenced migration decision;
+- all exposed data, navigation, commands, widgets, and inbox items are capability-correct;
+- the operational inbox derives live work without owning duplicate workflow state;
+- all mutations use the domain command, validation, concurrency, idempotency, and audit path appropriate to their risk;
+- no mixed legacy/new production experience exists;
+- measured performance meets the approved comparison gate;
+- rollback and eventual legacy cleanup are complete.
+
+## Rejected alternatives
+
+### Full greenfield rewrite
+
+Rejected because it would discard reliable existing services and maximize parity, timing, and regression risk across 137 pages.
+
+### Cosmetic refactor of the existing HK
+
+Rejected because it would preserve duplicated `/admin` and `/mod` workflows, inconsistent page boundaries, and manual navigation debt.
+
+### Separate HK service/application
+
+Rejected because the current requirement does not justify another deployment, authentication boundary, or distributed consistency problem.
+
+### Persistent cross-domain task database
+
+Rejected because it would duplicate ticket, moderation, alert, and anomaly state and create reconciliation failure modes.
+
+## Final design invariant
+
+The migration may be incremental internally, but the operator-facing product is not. Until the cutover gate passes, the current HK remains the only normal production surface. After cutover, the new HK is the only surface.

drizzle.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "drizzle-kit";
+
+// Schema source of truth for the query builder: src/db/schema.ts
+// (regenerated via `pnpm db:schema:generate` from the previous schema + live DB).
+//
+// This DB is shared with the Arcturus emulator — NEVER run `drizzle-kit migrate`
+// or `push` against it. CMS DDL stays in drizzle/migrations/*.sql applied by
+// `pnpm db:migrate`. Use `pnpm db:generate` only for draft SQL under drizzle/drafts/.
+export default defineConfig({
+	dialect: "mysql",
+	schema: "./src/db/schema.ts",
+	out: "./drizzle/drafts",
+	dbCredentials: {
+		url: process.env.DATABASE_URL ?? "",
+	},
+	strict: true,
+	verbose: true,
+});

drizzle/drafts/README.md

@@ -0,0 +1 @@
+Draft SQL from `pnpm db:generate` (drizzle-kit). Never apply these automatically — copy reviewed statements into drizzle/migrations/ as numbered CMS migrations, then `pnpm db:migrate`.

drizzle/drafts/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "mysql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "5",
+      "when": 1788791201804,
+      "tag": "0000_premium_spirit",
+      "breakpoints": true
+    }
+  ]
+}

drizzle/migrations/0020_performance_indexes.sql

@@ -0,0 +1,12 @@
+-- 0020_performance_indexes.sql
+-- Adds indexes for the hot CMS read paths (shared DB with the Arcturus
+-- emulator — additive only, no schema changes to emulator-owned columns).
+--
+--   users.credits                     → credits leaderboard (ORDER BY credits DESC LIMIT 20)
+--   users_currency(type, amount)      → duckets/diamonds leaderboard (WHERE type=? ORDER BY amount DESC LIMIT 20)
+--   users_settings.respects_received  → respects leaderboard (ORDER BY respects_received DESC LIMIT 20)
+--   camera_web.timestamp              → homepage recent photos (ORDER BY timestamp DESC LIMIT 4)
+CREATE INDEX IF NOT EXISTS `idx_users_credits` ON `users` (`credits`);
+CREATE INDEX IF NOT EXISTS `idx_users_currency_type_amount` ON `users_currency` (`type`, `amount`);
+CREATE INDEX IF NOT EXISTS `idx_users_settings_respects_received` ON `users_settings` (`respects_received`);
+CREATE INDEX IF NOT EXISTS `idx_camera_web_timestamp` ON `camera_web` (`timestamp`);

drizzle/migrations/0021_add_messenger_offline_user_id_index.sql

@@ -0,0 +1,4 @@
+-- 0021_add_messenger_offline_user_id_index.sql
+-- The /me dashboard counts unread offline messages with
+-- `WHERE user_id = ?`; messenger_offline previously had no index there.
+CREATE INDEX IF NOT EXISTS `idx_messenger_offline_user_id` ON `messenger_offline` (`user_id`);

drizzle/migrations/0022_add_terms_age_consent.sql

@@ -0,0 +1,4 @@
+-- Add terms/age consent columns expected by the users schema (register flow).
+ALTER TABLE `users`
+	ADD COLUMN `terms_accepted` TINYINT(1) NOT NULL DEFAULT 0,
+	ADD COLUMN `age_verified` TINYINT(1) NOT NULL DEFAULT 0;

drizzle/migrations/0023_theme_builder_scopes.sql

@@ -0,0 +1,37 @@
+-- Theme Builder: scoped theme system for per-route, per-module, and multi-site theming.
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS theme_scopes (
+  id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  name        VARCHAR(100) NOT NULL,
+  type        ENUM('global','site','module','route') NOT NULL,
+  parent_id   BIGINT UNSIGNED NULL,
+  site_domain VARCHAR(255) NULL,
+  route_path  VARCHAR(255) NULL,
+  module_id   VARCHAR(100) NULL,
+  is_active   TINYINT(1) NOT NULL DEFAULT 1,
+  sort_order  INT NOT NULL DEFAULT 0,
+  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  KEY theme_scopes_parent_idx (parent_id),
+  KEY theme_scopes_type_idx (type),
+  UNIQUE KEY theme_scopes_unique_lookup (type, site_domain, route_path, module_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS theme_scope_values (
+  id           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  scope_id     BIGINT UNSIGNED NOT NULL,
+  setting_key  VARCHAR(100) NOT NULL,
+  setting_val  VARCHAR(255) NOT NULL,
+  mode         ENUM('light','dark') NOT NULL DEFAULT 'light',
+  created_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  UNIQUE KEY theme_scope_values_unique (scope_id, setting_key, mode),
+  KEY theme_scope_values_scope_idx (scope_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Seed: create the global scope from existing website_settings theme data.
+INSERT IGNORE INTO theme_scopes (id, name, type, parent_id, is_active, sort_order)
+VALUES (1, 'Global', 'global', NULL, 1, 0);

drizzle/migrations/0024_housekeeping_preview_access.sql

@@ -0,0 +1,3 @@
+INSERT INTO `acl_permissions` (`slug`, `title`)
+VALUES ('housekeeping.preview.access', 'Access Housekeeping preview')
+ON DUPLICATE KEY UPDATE `title` = VALUES(`title`);

drizzle/migrations/0025_article_publication.sql

@@ -0,0 +1,7 @@
+-- Existing articles remain published. Preserve any publication settings already present.
+ALTER TABLE website_articles
+ ADD COLUMN IF NOT EXISTS status VARCHAR(20) NOT NULL DEFAULT 'published',
+ ADD COLUMN IF NOT EXISTS publish_at TIMESTAMP NULL DEFAULT NULL,
+ ADD COLUMN IF NOT EXISTS published_at TIMESTAMP NULL DEFAULT NULL;
+CREATE INDEX IF NOT EXISTS idx_website_articles_publication
+ ON website_articles (status, publish_at, created_at);

drizzle/migrations/0026_article_editor_recovery.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS website_article_drafts (
+ user_id BIGINT UNSIGNED NOT NULL,
+ article_key VARCHAR(32) NOT NULL,
+ version INT UNSIGNED NOT NULL,
+ payload LONGTEXT NOT NULL,
+ updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ PRIMARY KEY (user_id, article_key)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE IF NOT EXISTS website_article_revisions (
+ id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+ article_id BIGINT UNSIGNED NOT NULL,
+ user_id BIGINT UNSIGNED NOT NULL,
+ payload LONGTEXT NOT NULL,
+ created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ INDEX article_history (article_id, id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0027_catalog_packages.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS website_catalog_packages (
+ id VARCHAR(36) NOT NULL PRIMARY KEY,
+ name VARCHAR(128) NOT NULL,
+ version INT UNSIGNED NOT NULL,
+ status VARCHAR(16) NOT NULL,
+ mode VARCHAR(16) NOT NULL,
+ payload LONGTEXT NOT NULL,
+ updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ INDEX package_recent (updated_at, id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0028_history_snapshots.sql

@@ -0,0 +1,2 @@
+-- Preserve complete before/after snapshots for long news articles.
+ALTER TABLE admin_audit_log MODIFY COLUMN `before` MEDIUMTEXT NULL, MODIFY COLUMN `after` MEDIUMTEXT NULL;

drizzle/migrations/0029_admin_table_views.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS website_admin_table_views (
+ user_id INT NOT NULL,
+ path VARCHAR(191) NOT NULL,
+ name VARCHAR(60) NOT NULL,
+ state TEXT NOT NULL,
+ PRIMARY KEY (user_id, path, name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0030_profile_privacy.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS `website_profile_privacy` (
+ `user_id` int NOT NULL,
+ `wallet` boolean NOT NULL DEFAULT false,
+ `online` boolean NOT NULL DEFAULT true,
+ `friends` boolean NOT NULL DEFAULT true,
+ `photos` boolean NOT NULL DEFAULT true,
+ `registered` boolean NOT NULL DEFAULT true,
+ PRIMARY KEY (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

e2e/admin.spec.ts

@@ -1,14 +0,0 @@
-import { expect, test } from "@playwright/test";
-
-test.describe("Admin panel", () => {
-	test("admin login page redirects unauthenticated users", async ({ page }) => {
-		await page.goto("/admin");
-		await expect(page).toHaveURL(/login/);
-	});
-
-	test("admin page has login form", async ({ page }) => {
-		await page.goto("/admin");
-		await expect(page.locator('input[name="username"]')).toBeVisible();
-		await expect(page.locator('input[name="password"]')).toBeVisible();
-	});
-});

e2e/auth.spec.ts

@@ -1,32 +0,0 @@
-import { expect, test } from "@playwright/test";
-
-test.describe("Authentication flows", () => {
-	test("login form validates required fields", async ({ page }) => {
-		await page.goto("/login");
-		await page.click('button[type="submit"]');
-		await expect(page.locator("text=required")).toBeVisible({ timeout: 5000 });
-	});
-
-	test("login with invalid credentials shows error", async ({ page }) => {
-		await page.goto("/login");
-		await page.fill('input[name="username"]', "nonexistent");
-		await page.fill('input[name="password"]', "wrongpassword");
-		await page.click('button[type="submit"]');
-		await expect(page.locator("text=invalid")).toBeVisible({ timeout: 5000 });
-	});
-
-	test("register page has password confirmation field", async ({ page }) => {
-		await page.goto("/register");
-		await expect(page.locator('input[name="confirmPassword"]')).toBeVisible();
-	});
-
-	test("register form validates password match", async ({ page }) => {
-		await page.goto("/register");
-		await page.fill('input[name="password"]', "Password123!");
-		await page.fill('input[name="confirmPassword"]', "DifferentPass123!");
-		await page.click('button[type="submit"]');
-		await expect(page.locator("text=match|komen overeen|kloppen")).toBeVisible({
-			timeout: 5000,
-		});
-	});
-});

e2e/example.spec.ts

@@ -1,16 +0,0 @@
-import { expect, test } from "@playwright/test";
-
-test("homepage has title", async ({ page }) => {
-	await page.goto("/");
-	await expect(page).toHaveTitle(/Magic Hotel|Atom/i);
-});
-
-test("register page loads", async ({ page }) => {
-	await page.goto("/register");
-	await expect(page).toHaveTitle(/registreer|register|konto/i);
-});
-
-test("login page loads", async ({ page }) => {
-	await page.goto("/login");
-	await expect(page).toHaveTitle(/inloggen|login/i);
-});

e2e/navigation.spec.ts

@@ -1,24 +0,0 @@
-import { expect, test } from "@playwright/test";
-
-test.describe("Public navigation", () => {
-	test("homepage loads with expected elements", async ({ page }) => {
-		await page.goto("/");
-		await expect(page.locator("nav")).toBeVisible();
-		await expect(page.locator("footer")).toBeVisible();
-	});
-
-	test("community page loads", async ({ page }) => {
-		await page.goto("/community");
-		await expect(page).toHaveTitle(/community/i);
-	});
-
-	test("shop page loads", async ({ page }) => {
-		await page.goto("/shop");
-		await expect(page.locator("h1, h2").first()).toBeVisible();
-	});
-
-	test("404 page for unknown routes", async ({ page }) => {
-		const response = await page.goto("/this-page-does-not-exist");
-		expect(response?.status()).toBe(404);
-	});
-});

e2e/smoke.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from "@playwright/test";
+
+// Read-only production checks. Content mutation tests belong to a seeded staging DB.
+test("login remains usable on a narrow viewport", async ({ page }) => {
+	await page.setViewportSize({ width: 390, height: 720 });
+	const response = await page.goto("/login");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator('input[type="password"]').first()).toBeVisible();
+	await expect(page.locator('button[type="submit"]').first()).toBeVisible();
+	expect(
+		await page.evaluate(
+			() => document.documentElement.scrollWidth <= innerWidth + 1,
+		),
+	).toBe(true);
+	await expect(page.locator("body")).not.toContainText("Application error");
+});
+test("public news is rendered without a server error", async ({ page }) => {
+	const response = await page.goto("/news");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator("main").first()).toBeVisible();
+	await expect(page.locator("body")).not.toContainText("Application error");
+});
+test("staff page is available", async ({ page }) => {
+	const response = await page.goto("/staff");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator("main").first()).toBeVisible();
+});

e2e/ui/README.md

@@ -0,0 +1,10 @@
+# Isolated UI regression checks
+
+Run `pnpm test:ui` after `pnpm install --frozen-lockfile` and `pnpm exec playwright install chromium`.
+The fixture server bundles real CMS components with local HTTP/server-action fixtures. It does not use the database or production credentials. Production smoke tests remain in the separate `pnpm test:e2e` command.
+
+The suite covers accessible settings switches, news editor/preview, support-table filters, import history, attachment recovery and news/event recovery. Axe checks WCAG A/AA rules. The sandboxed preview cannot execute Axe; its accessible name and keyboard exit are checked separately. Automated checks do not replace a full accessibility audit.
+
+Visual references are committed under `__screenshots__/<platform>/<viewport>`. Normal runs compare references and must not update them. For an intentional UI change, use `pnpm test:ui:update`, inspect every changed PNG and commit only accepted references. Keep the Playwright browser version aligned with the lockfile. Linux references must be captured on the Linux runner; Windows references are not interchangeable.
+
+Fixtures contain synthetic data only. Do not add production requests, environment secrets, ignored local documents or database access to tests. CI retains test reports and failures as the `ui-results` artifact.