@underpostnet/cyberia 3.2.80

package/docker-compose.yml

@@ -0,0 +1,434 @@
+# Cyberia ecosystem Docker Compose stack — canonical custom workflow.
+#
+# Orchestrates the entire Cyberia MMORPG on the underpost platform base
+# (MongoDB + Valkey + IPFS), then the Cyberia content-authority engine and its
+# per-instance server/client tiers, fronted by an nginx reverse proxy.
+#
+# Canonical location (custom docker-compose workflow):
+#   engine-private/conf/dd-cyberia/docker-compose/cyberia/
+#     ├── docker-compose.yml     (this file — the ENTIRE stack, single source)
+#     ├── compose.env            (working env-file, used as-is — not generated)
+#     ├── nginx.conf             (GENERATED: per-variant sub-path routing)
+#     └── mongodb/entrypoint.sh  (GENERATED infra: replica-set bootstrap)
+# All bind mounts below are relative to this directory: the CLI runs compose with
+# `--project-directory` pinned here (see src/cli/docker-compose.js).
+#
+# Multi-instance: one engine-cyberia (content + asset authority) feeds three
+# cyberia-server + three cyberia-client tiers, one per conf.instances.json
+# multiInstance variant (amethyst-strata-expansion "/", FOREST "/FOREST",
+# TEST "/TEST"). nginx.conf routes each host sub-path to its tier and is
+# generated from that same topology; keep the services below in sync with it.
+#
+# Startup is a strict health-gated chain — each tier waits for the previous to
+# be healthy:
+#   mongodb + valkey  ->  engine-cyberia  ->  3x cyberia-server  ->  3x cyberia-client  ->  proxy
+#
+# Architecture boundaries (see CLAUDE.md "Cyberia architecture boundaries"):
+#   engine-cyberia  — content, validation, persistence, gRPC(:50051)+REST(:4005)
+#                     data services, asset metadata. The authority layer.
+#   cyberia-server  — authoritative real-time simulation / tick processing (Go).
+#   cyberia-client  — rendering, input, prediction, presentation (WASM bundle).
+#
+# Usage:
+#   underpost docker-compose --up --deploy-id dd-cyberia --docker-compose-id cyberia
+#   (or the docker:cyberia:* npm scripts). The engine-cyberia image bakes the
+#   dd-cyberia build at image-build time, so no private-repo credentials are
+#   required at container start.
+
+name: dd-cyberia
+
+services:
+  # === Tier 1: platform base (no dependencies) =============================
+
+  # --- MongoDB -------------------------------------------------------------
+  # replSet rs0, keyFile cluster auth, replica-set + root-user init over the
+  # loopback localhost exception. Uses ./mongodb/entrypoint.sh, generated into
+  # this dir by `underpost docker-compose --generate --docker-compose-id cyberia`.
+  mongodb:
+    image: ${MONGO_IMAGE:-mongo:latest}
+    container_name: dd-cyberia-mongodb
+    entrypoint: ['bash', '/docker-init/entrypoint.sh']
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MONGO_INITDB_ROOT_USERNAME:?set MONGO_INITDB_ROOT_USERNAME in compose.env}
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD:?set MONGO_INITDB_ROOT_PASSWORD in compose.env}
+      DB_REPLICA_SET: ${DB_REPLICA_SET:-rs0}
+    volumes:
+      - ./mongodb:/docker-init:ro
+      - mongodb-keyfile:/opt/keyfile
+      - mongodb-data:/data/db
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '27017'
+    ports:
+      - '${MONGO_HOST_PORT:-27017}:27017'
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >
+          mongosh --quiet -u "$$MONGO_INITDB_ROOT_USERNAME" -p "$$MONGO_INITDB_ROOT_PASSWORD"
+          --authenticationDatabase admin --eval "db.hello().isWritablePrimary" | grep -q true
+      interval: 10s
+      timeout: 5s
+      retries: 20
+      start_period: 60s
+    restart: unless-stopped
+
+  # --- Valkey --------------------------------------------------------------
+  valkey-service:
+    image: ${VALKEY_IMAGE:-valkey/valkey:latest}
+    container_name: dd-cyberia-valkey
+    command: ['valkey-server', '--port', '6379', '--bind', '0.0.0.0', '--protected-mode', 'no']
+    volumes:
+      - valkey-data:/data
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '6379'
+    ports:
+      - '${VALKEY_NODEPORT:-32079}:6379'
+    healthcheck:
+      test: ['CMD', 'valkey-cli', '-p', '6379', 'ping']
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+    restart: unless-stopped
+
+  # --- IPFS (Kubo daemon) --------------------------------------------------
+  # Content plane: add / pin / cat / files (MFS). The engine reaches it at
+  # http://ipfs:5001 (RPC) and http://ipfs:8080 (gateway). The init hook binds
+  # the API/gateway to 0.0.0.0 so the engine and ipfs-cluster can reach it.
+  ipfs:
+    image: ${IPFS_IMAGE:-ipfs/kubo:latest}
+    container_name: dd-cyberia-ipfs
+    volumes:
+      - ./ipfs/configure-ipfs.sh:/container-init.d/001-configure-ipfs.sh:ro
+      - ipfs-data:/data/ipfs
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '5001'
+      - '8080'
+      - '4001'
+    ports:
+      - '${IPFS_API_PORT:-5001}:5001'
+      - '${IPFS_GATEWAY_PORT:-8080}:8080'
+    healthcheck:
+      test: ['CMD-SHELL', 'ipfs --api=/ip4/127.0.0.1/tcp/5001 id >/dev/null 2>&1 || exit 1']
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 40s
+    restart: unless-stopped
+
+  # --- IPFS Cluster (pin orchestration) ------------------------------------
+  # Serves the Cluster REST API on :9094 (engine IPFS_CLUSTER_API_URL). Drives
+  # the shared Kubo daemon and starts only once Kubo is healthy.
+  ipfs-cluster:
+    image: ${IPFS_CLUSTER_IMAGE:-ipfs/ipfs-cluster:latest}
+    container_name: dd-cyberia-ipfs-cluster
+    depends_on:
+      ipfs:
+        condition: service_healthy
+    environment:
+      CLUSTER_PEERNAME: dd-cyberia-cluster
+      # 32-byte hex shared secret. Fixed dev default keeps the cluster identity
+      # stable across restarts; override in compose.env for anything shared.
+      CLUSTER_SECRET: ${CLUSTER_SECRET:-0e1d2c3b4a59687778695a4b3c2d1e0f0e1d2c3b4a59687778695a4b3c2d1e0f}
+      CLUSTER_IPFSHTTP_NODEMULTIADDRESS: /dns4/ipfs/tcp/5001
+      CLUSTER_RESTAPI_HTTPLISTENMULTIADDRESS: /ip4/0.0.0.0/tcp/9094
+      CLUSTER_CRDT_TRUSTEDPEERS: '*'
+    volumes:
+      - ipfs-cluster-data:/data/ipfs-cluster
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '9094'
+      - '9096'
+    ports:
+      - '${IPFS_CLUSTER_API_PORT:-9094}:9094'
+    healthcheck:
+      test: ['CMD-SHELL', 'ipfs-cluster-ctl --host /ip4/127.0.0.1/tcp/9094 id >/dev/null 2>&1 || exit 1']
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 40s
+    restart: unless-stopped
+
+  # === Tier 2: content authority (waits for mongo + valkey + ipfs) =========
+
+  # --- engine-cyberia ------------------------------------------------------
+  # The single shared underpost engine for deploy dd-cyberia: content authority
+  # and asset provider for EVERY instance. Its boot imports every multiInstance
+  # variant that has local content (amethyst + FOREST; TEST has none yet, so its
+  # server starts but rejects connections until seeded). Serves REST/WS on 4005
+  # and the engine gRPC data service on 50051.
+  engine-cyberia:
+    image: ${ENGINE_CYBERIA_IMAGE:-underpost/engine-cyberia-dev}:${ENGINE_CYBERIA_TAG:-v3.2.80}
+    container_name: dd-cyberia-engine
+    command:
+      - /bin/sh
+      - -c
+      - >
+        node bin/cyberia run-workflow import-default-items &&
+        underpost start --run dd-cyberia development
+    env_file:
+      - ./compose.env
+    environment:
+      NODE_ENV: ${NODE_ENV:-development}
+      DB_PROVIDER: ${DB_PROVIDER:-mongoose}
+      DB_HOST: ${DB_HOST:-mongodb://mongodb:27017}
+      DB_REPLICA_SET: ${DB_REPLICA_SET:-rs0}
+      DB_AUTH_SOURCE: ${DB_AUTH_SOURCE:-admin}
+      DB_USER: ${MONGO_INITDB_ROOT_USERNAME:?}
+      DB_PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD:?}
+      VALKEY_HOST: ${VALKEY_HOST:-valkey-service}
+      VALKEY_PORT: ${VALKEY_PORT:-6379}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '4005'
+      - '50051'
+    ports:
+      - '${ENGINE_CYBERIA_REST_PORT:-4005}:4005'
+      - '${ENGINE_CYBERIA_GRPC_PORT:-50051}:50051'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/4005' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      # The dd-cyberia build is baked into the image; start just runs the
+      # engine, so a moderate start_period covers DB connect + multi-import.
+      start_period: 180s
+    depends_on:
+      mongodb:
+        condition: service_healthy
+      valkey-service:
+        condition: service_healthy
+      ipfs:
+        condition: service_healthy
+      ipfs-cluster:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # === Tier 3: authoritative simulation, one per variant ===================
+  # All three share engine-cyberia (content + gRPC) and differ only by
+  # INSTANCE_CODE — the world each loads. Each waits for engine-cyberia healthy.
+  # The default variant publishes host port 8081; the rest are internal-only
+  # (reached through nginx sub-path routing).
+
+  cyberia-server:
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.80}
+    container_name: dd-cyberia-server
+    environment:
+      INSTANCE_CODE: amethyst-strata-expansion
+      ENGINE_API_BASE_URL: ${ENGINE_API_BASE_URL:-http://engine-cyberia:4005}
+      ENGINE_PUBLIC_URL: ${ENGINE_PUBLIC_URL:-http://localhost:4005}
+      ENGINE_GRPC_ADDRESS: ${ENGINE_GRPC_ADDRESS:-engine-cyberia:50051}
+      ENGINE_GRPC_RELOAD_INTERVAL_SEC: ${ENGINE_GRPC_RELOAD_INTERVAL_SEC:-300}
+      STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
+      APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
+      LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    ports:
+      - '${CYBERIA_SERVER_PORT:-8081}:8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    depends_on:
+      engine-cyberia:
+        condition: service_healthy
+    restart: unless-stopped
+
+  cyberia-server-forest:
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.80}
+    container_name: dd-cyberia-server-forest
+    environment:
+      INSTANCE_CODE: FOREST
+      ENGINE_API_BASE_URL: ${ENGINE_API_BASE_URL:-http://engine-cyberia:4005}
+      ENGINE_PUBLIC_URL: ${ENGINE_PUBLIC_URL:-http://localhost:4005}
+      ENGINE_GRPC_ADDRESS: ${ENGINE_GRPC_ADDRESS:-engine-cyberia:50051}
+      ENGINE_GRPC_RELOAD_INTERVAL_SEC: ${ENGINE_GRPC_RELOAD_INTERVAL_SEC:-300}
+      STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
+      APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
+      LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    depends_on:
+      engine-cyberia:
+        condition: service_healthy
+    restart: unless-stopped
+
+  cyberia-server-test:
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.80}
+    container_name: dd-cyberia-server-test
+    environment:
+      INSTANCE_CODE: TEST
+      ENGINE_API_BASE_URL: ${ENGINE_API_BASE_URL:-http://engine-cyberia:4005}
+      ENGINE_PUBLIC_URL: ${ENGINE_PUBLIC_URL:-http://localhost:4005}
+      ENGINE_GRPC_ADDRESS: ${ENGINE_GRPC_ADDRESS:-engine-cyberia:50051}
+      ENGINE_GRPC_RELOAD_INTERVAL_SEC: ${ENGINE_GRPC_RELOAD_INTERVAL_SEC:-300}
+      STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
+      APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
+      LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    depends_on:
+      engine-cyberia:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # === Tier 4: presentation, one per variant ===============================
+  # One WASM bundle serves every variant; the instance is resolved from the URL
+  # sub-path (docker-driver injects CYBERIA_WS_ORIGIN / _ENGINE_API_ORIGIN /
+  # _DEFAULT_INSTANCE). Each client waits ONLY for its own server, so the three
+  # server->client pipelines advance independently (in parallel) once the shared
+  # engine-cyberia is healthy:
+  #   cyberia-server        -> cyberia-client
+  #   cyberia-server-forest -> cyberia-client-forest
+  #   cyberia-server-test   -> cyberia-client-test
+
+  cyberia-client:
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.80}
+    container_name: dd-cyberia-client
+    environment:
+      CYBERIA_PORT: '8081'
+      CYBERIA_INSTANCE_CODE: amethyst-strata-expansion
+      CYBERIA_BASE_PATH: /
+      CYBERIA_DEFAULT_INSTANCE: ${CYBERIA_DEFAULT_INSTANCE:-amethyst-strata-expansion}
+      CYBERIA_WS_ORIGIN: ${CYBERIA_WS_ORIGIN:-ws://server.cyberiaonline.com}
+      CYBERIA_ENGINE_API_ORIGIN: ${CYBERIA_ENGINE_API_ORIGIN:-http://www.cyberiaonline.com}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    ports:
+      - '${CYBERIA_CLIENT_PORT:-8082}:8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+    depends_on:
+      cyberia-server:
+        condition: service_healthy
+    restart: unless-stopped
+
+  cyberia-client-forest:
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.80}
+    container_name: dd-cyberia-client-forest
+    environment:
+      CYBERIA_PORT: '8081'
+      CYBERIA_INSTANCE_CODE: FOREST
+      CYBERIA_BASE_PATH: /FOREST
+      CYBERIA_DEFAULT_INSTANCE: ${CYBERIA_DEFAULT_INSTANCE:-amethyst-strata-expansion}
+      CYBERIA_WS_ORIGIN: ${CYBERIA_WS_ORIGIN:-ws://server.cyberiaonline.com}
+      CYBERIA_ENGINE_API_ORIGIN: ${CYBERIA_ENGINE_API_ORIGIN:-http://www.cyberiaonline.com}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+    depends_on:
+      cyberia-server-forest:
+        condition: service_healthy
+    restart: unless-stopped
+
+  cyberia-client-test:
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.80}
+    container_name: dd-cyberia-client-test
+    environment:
+      CYBERIA_PORT: '8081'
+      CYBERIA_INSTANCE_CODE: TEST
+      CYBERIA_BASE_PATH: /TEST
+      CYBERIA_DEFAULT_INSTANCE: ${CYBERIA_DEFAULT_INSTANCE:-amethyst-strata-expansion}
+      CYBERIA_WS_ORIGIN: ${CYBERIA_WS_ORIGIN:-ws://server.cyberiaonline.com}
+      CYBERIA_ENGINE_API_ORIGIN: ${CYBERIA_ENGINE_API_ORIGIN:-http://www.cyberiaonline.com}
+    networks:
+      - dd-cyberia-internal
+    expose:
+      - '8081'
+    healthcheck:
+      test: ['CMD-SHELL', "timeout 2 bash -c '</dev/tcp/127.0.0.1/8081' || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+    depends_on:
+      cyberia-server-test:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # === Tier 5: reverse proxy (waits for all clients) =======================
+  # Routes the three cyberiaonline.com hosts to their per-variant upstreams with
+  # websocket upgrade. Config source of truth: ./nginx.conf (generated from the
+  # multiInstance topology). Fronts the stack only once every tier is healthy.
+  proxy:
+    image: ${PROXY_IMAGE:-nginx:stable-alpine}
+    container_name: dd-cyberia-proxy
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
+    networks:
+      - dd-cyberia-internal
+    ports:
+      - '${PROXY_HTTP_PORT:-80}:80'
+    healthcheck:
+      test: ['CMD', 'wget', '-q', '-O', '-', 'http://127.0.0.1/healthz']
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      cyberia-client:
+        condition: service_healthy
+      cyberia-client-forest:
+        condition: service_healthy
+      cyberia-client-test:
+        condition: service_healthy
+    restart: unless-stopped
+
+networks:
+  dd-cyberia-internal:
+    name: dd-cyberia-internal
+    driver: bridge
+
+volumes:
+  mongodb-data:
+    name: dd-cyberia-mongodb-data
+  mongodb-keyfile:
+    name: dd-cyberia-mongodb-keyfile
+  valkey-data:
+    name: dd-cyberia-valkey-data
+  ipfs-data:
+    name: dd-cyberia-ipfs-data
+  ipfs-cluster-data:
+    name: dd-cyberia-ipfs-cluster-data

package/examples/static-page/README.md

@@ -0,0 +1,150 @@
+# Static Page Example
+
+Generate static HTML pages using the `underpost static` CLI.
+
+## Quick Start
+
+```sh
+# From the project root directory:
+underpost static --page ./examples/static-page/ssr-components/CustomPage.js \
+                 --output-path ./public/default.net/example.html
+```
+
+## Using a Config File
+
+A JSON config file lets you define all options in one place instead of passing CLI flags.
+
+**Generate a starter config:**
+
+```sh
+underpost static --generate-config ./static-config.json
+```
+
+**Build from the included example config:**
+
+```sh
+underpost static --config-file ./examples/static-page/static-config-example.json
+```
+
+## Preview with Static Server
+
+Use `--run-sv` to start a standalone Express static file server that serves the build output directory, so you can preview your generated pages in a browser.
+
+```sh
+# Build and serve on default port 5000:
+underpost static --page ./examples/static-page/ssr-components/CustomPage.js \
+                 --output-path ./dist/index.html \
+                 --run-sv
+
+# Build and serve on a custom port:
+underpost static --page ./examples/static-page/ssr-components/CustomPage.js \
+                 --output-path ./dist/index.html \
+                 --run-sv 3000
+
+# Serve an existing build directory without rebuilding:
+underpost static --output-path ./dist/index.html --run-sv
+
+# Serve the current working directory:
+underpost static --run-sv 8080
+```
+
+When `--output-path` is provided, the server serves the directory containing the output file (e.g. `./dist/`). Otherwise it serves the current working directory.
+
+## Config File Reference
+
+See [`static-config-example.json`](./static-config-example.json) for a complete working example.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `page` | `string` | Path to the SSR component to render |
+| `outputPath` | `string` | Output HTML file path |
+| `buildPath` | `string` | Base path for static documents or assets (default: `"/"`) |
+| `env` | `string` | `"production"` or `"development"` |
+| `minify` | `boolean` | Minify HTML output |
+| `lang` | `string` | HTML `lang` attribute |
+| `dir` | `string` | HTML `dir` attribute (`ltr`/`rtl`) |
+| `metadata` | `object` | SEO metadata (title, description, keywords, author, themeColor, canonicalURL, thumbnail, locale, siteName) |
+| `scripts` | `object` | `{ head: [...], body: [...] }` — inline or external scripts |
+| `styles` | `array` | Inline (`content`) or external (`href`) stylesheets |
+| `icons` | `object` | `favicon`, `appleTouchIcon`, `manifest` paths |
+| `headComponents` | `array` | SSR component paths injected into `<head>` |
+| `bodyComponents` | `array` | SSR component paths injected into `<body>` |
+| `microdata` | `array` | JSON-LD structured data objects |
+| `customPayload` | `object` | Arbitrary data injected into the render payload |
+
+## CLI Flags
+
+Flags override config file values when both are provided.
+
+### Build & Output
+
+```sh
+underpost static --page <path>                  # SSR component path
+                 --output-path <path>           # Output file
+                 --build-path <path>            # Base path for assets (default: "/")
+                 --config-file <path>           # JSON config file
+                 --generate-config [path]       # Generate a template config file
+                 --env <env>                    # production | development
+                 --minify / --no-minify         # Toggle minification
+                 --lang <lang>                  # HTML lang attribute (default: en)
+                 --dir <dir>                    # HTML dir attribute (default: ltr)
+                 --dev                          # Development mode
+```
+
+### Metadata & SEO
+
+```sh
+                 --title <title>                # Page title (deprecated: use --config-file)
+                 --description <text>           # Meta description
+                 --keywords <a,b,c>             # Comma-separated keywords
+                 --author <name>                # Meta author
+                 --theme-color <color>          # Theme color for mobile browsers
+                 --canonical-url <url>          # Canonical URL for SEO
+                 --thumbnail <url>              # Open Graph thumbnail image URL
+                 --locale <locale>              # Page locale (default: en-US)
+                 --site-name <name>             # Site name for Open Graph
+```
+
+### Scripts & Styles
+
+```sh
+                 --head-scripts <paths>         # Comma-separated script paths for <head>
+                 --body-scripts <paths>         # Comma-separated script paths for <body>
+                 --styles <paths>               # Comma-separated stylesheet paths
+```
+
+### Icons
+
+```sh
+                 --favicon <path>               # Favicon path
+                 --apple-touch-icon <path>      # Apple touch icon path
+                 --manifest <path>              # Web manifest path
+```
+
+### SSR Components
+
+```sh
+                 --head-components <paths>      # Comma-separated SSR head component paths
+                 --body-components <paths>      # Comma-separated SSR body component paths
+```
+
+### Static Server
+
+```sh
+                 --run-sv [port]                # Start Express static server (default port: 5000)
+```
+
+## SSR Component
+
+The page content is defined in an SSR component file. See [`ssr-components/CustomPage.js`](./ssr-components/CustomPage.js) for an example.
+
+A component exports an `SrrComponent` function that returns an HTML template literal:
+
+```js
+SrrComponent = () => html`
+  <div>
+    <h1>Hello World</h1>
+    <p>Your page content here.</p>
+  </div>
+`;
+```