@underpostnet/cyberia 3.3.0 → 3.3.73

package/CLI-HELP.md

@@ -1,6 +1,6 @@
 ## Underpost CLI
 
-> underpost ci/cd cli v3.3.0
+> underpost ci/cd cli v3.3.73
 
 **Usage:** `underpost [options] [command]`
 
@@ -9,6 +9,7 @@
 | Option | Description |
 | --- | --- |
 | `-V, --version` | output the version number |
+| `--profile <profile>` | Execution profile. One of: LIVE_CLUSTER, HERMETIC_BUILD, OFFLINE_DRY_RUN. LIVE_CLUSTER Full access: cluster and host mutation permitted. HERMETIC_BUILD Build outputs only: no cluster, host or network side effects. OFFLINE_DRY_RUN Nothing executes; every command is reported as intent. |
 | `-h, --help` | display help for command |
 
 ### Commands
@@ -22,30 +23,33 @@
 | [`pull`](#underpost-pull) | Pulls the latest changes from a specified GitHub repository. |
 | [`cmt`](#underpost-cmt) | Manages commits to a GitHub repository, supporting various commit types and options. |
 | [`push`](#underpost-push) | Pushes committed changes from a local repository to a remote GitHub repository. |
-| [`env`](#underpost-env) | Sets environment variables and configurations related to a specific deployment ID. |
 | [`static`](#underpost-static) | Manages static build of page, bundles, and documentation with comprehensive customization options. |
-| [`config`](#underpost-config) | Manages Underpost configurations using various operators. |
 | [`root`](#underpost-root) | Displays the root path of the npm installation. |
 | [`ip`](#underpost-ip) | Displays the current public machine IP addresses. |
 | [`cluster`](#underpost-cluster) | Manages Kubernetes clusters, defaulting to Kind cluster initialization. |
 | [`deploy`](#underpost-deploy) | Manages application deployments, defaulting to deploying development pods. |
-| [`secret`](#underpost-secret) | Manages secrets for various platforms. |
+| [`secret`](#underpost-secret) | Workload secret store: SOPS/Age encrypted credentials projected as Kubernetes Secrets. |
+| [`host`](#underpost-host) | Host configuration: the node-level operational environment shared by the cluster. |
+| [`app`](#underpost-app) | Application environment: one deployment's runtime configuration. |
+| [`state`](#underpost-state) | Runtime state: live container execution state, health and metrics, exported off-cluster. |
 | [`image`](#underpost-image) | Manages Docker images, including building, saving, and loading into Kubernetes clusters. |
 | [`install`](#underpost-install) | Quickly imports Underpost npm dependencies by copying them. |
 | [`db`](#underpost-db) | Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration. |
 | [`metadata`](#underpost-metadata) | Manages cluster metadata operations, including import and export. |
 | [`cron`](#underpost-cron) | Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests. |
 | [`fs`](#underpost-fs) | Manages file storage, defaulting to file upload operations. |
-| [`test`](#underpost-test) | Manages and runs tests, defaulting to the current Underpost default test suite. |
-| [`monitor`](#underpost-monitor) | Manages health server monitoring for specified deployments. |
-| [`ssh`](#underpost-ssh) | Manages SSH credentials and sessions for remote access to cluster nodes or services. |
+| [`monitor`](#underpost-monitor) | Manages health server monitoring, the cluster observability stack, and host dashboards. |
+| [`event`](#underpost-event) | Dispatches operational events and provisions the monitoring rules that trigger them. |
+| [`ssh`](#underpost-ssh) | Manages cluster scoped SSH credentials and sessions for remote access to cluster nodes or services. Users are registered in engine-private/deploy/conf.users.json and keys are stored in engine-private/deploy/users/<user>. |
 | [`wireguard`](#underpost-wireguard) | Manages the WireGuard L3 hub-and-spoke transport and the HAProxy edge gateway in front of it. |
 | [`haproxy`](#underpost-haproxy) | Manages the HAProxy edge gateway over the WireGuard transport (same subsystem as `underpost wireguard`). |
 | [`vultr`](#underpost-vultr) | Meters the edge VPS bandwidth against its Vultr plan quota and blocks egress before overage accrues. |
 | [`run`](#underpost-run) | Runs specified scripts using various runners. |
+| [`test`](#underpost-test) | Runs the test tiers locally, inside deployment pods, or as a cluster Job with Allure reporting. |
 | [`docker-compose`](#underpost-docker-compose) | General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack). |
 | [`lxd`](#underpost-lxd) | Manages LXD virtual machines as K3s nodes (control plane or workers). |
 | [`baremetal`](#underpost-baremetal) | Manages baremetal server operations, including installation, database setup, commissioning, and user management. |
+| [`package`](#underpost-package) | Generates the package manifests a deploy id owns, from the engine manifest and the deploy's product catalog, and installs the dependencies that catalog pins. |
 | [`release`](#underpost-release) | Release orchestrator for building new versions and deploying releases of the Underpost CLI. |
 
 ## Command reference
@@ -68,12 +72,12 @@ Initializes a new Underpost project, service, or configuration.
 | --- | --- |
 | `--deploy-id <deploy-id>` | Create deploy ID conf env files |
 | `--sub-conf <sub-conf>` | Create sub conf env files |
-| `--cluster` | Create deploy ID cluster files and sync to current cluster |
+| `--cluster` | Initialize the base cluster deploy folder engine-private/deploy from ./conf.js |
 | `--build-repos` | Create deploy ID repositories |
 | `--build` | Build the deployment to pwa-microservices-template (requires --deploy-id) |
 | `--clean-template` | Clean the build directory (pwa-microservices-template) |
 | `--sync-conf` | Sync configuration to private repositories (requires --deploy-id) |
-| `--sync-start` | Sync start scripts in deploy ID package.json with root package.json (use 'dd' as --deploy-id to sync all dd.router) |
+| `--sync-start` | Sync start scripts in deploy ID package.json with root package.json (use 'dd' as --deploy-id to sync all dd.routes) |
 | `--purge` | Remove deploy ID conf and all related repositories (requires --deploy-id) |
 | `--dev` | Sets the development cli context |
 | `--default-conf` | Create default deploy ID conf env files |
@@ -110,6 +114,8 @@ Builds client assets, single replicas, and/or syncs environment ports.
 | `--lite-build` | Skip full build (default is full build) |
 | `--icons-build` | Build icons |
 | `--ssr` | Rebuild only SSR views defined in conf.ssr.json, leaving client assets untouched |
+| `--env <env>` | Target environment for the build (e.g. "production", "development"). Falls back to --dev, then NODE_ENV. |
+| `--dev` | Sets the development cli context (shorthand for --env development). |
 | `-h, --help` | display help for command |
 
 ---
@@ -134,7 +140,8 @@ Initiates application servers, build pipelines, or other defined services based
 | `--run` | Starts application servers and monitors their health. |
 | `--build` | Triggers the client-side application build process. |
 | `--underpost-quickly-install` | Uses Underpost Quickly Install for dependency installation. |
-| `--skip-pull-base` | Skips cloning repositories, uses current workspace code directly. |
+| `--skip-pull-repo-base` | Skips cloning the engine source repository, uses current workspace code directly. |
+| `--skip-pull-private-repo` | Skips cloning the private configuration repository, uses the engine-private already in the workspace. |
 | `--skip-full-build` | Skips the full client bundle build during deployment. |
 | `--pull-bundle` | Downloads the pre-built client bundle from Cloudinary via pull-bundle before starting. Use together with --skip-full-build to skip the local build entirely. |
 | `--private-test-repo` | During --build, clone the private test source repo (engine-test-<id>) instead of the production engine-<id> repo. |
@@ -218,11 +225,12 @@ Manages commits to a GitHub repository, supporting various commit types and opti
 | `--hashes <hashes>` | Comma-separated list of specific file hashes of commits. |
 | `--extension <extension>` | specific file extensions of commits. |
 | `--changelog` | Print the plain changelog of the last N commits (see --from-n-commit, default 1). |
-| `--changelog-build` | Builds a CHANGELOG.md file based on the commit history |
+| `--changelog-build` | Builds a CHANGELOG.md from the latest five versions |
 | `--changelog-min-version <version>` | Sets the minimum version limit for --changelog-build (default: 2.85.0) |
 | `--changelog-no-hash` | Excludes commit hashes from the generated changelog entries (used with --changelog-build). |
 | `--changelog-msg` | Print the sanitized, commit-ready changelog message of the last N commits (see --from-n-commit, default 1). Empty when there are no tagged entries. |
 | `--from-n-commit <n>` | Number of latest commits to include in --changelog/--changelog-msg (default: 1). |
+| `--propagate-msg` | Prints the changelog payload carried by the propagation chain, read from the PROPAGATED_MESSAGE environment variable and stripped of the commit subject wrapper. Falls back to --changelog-msg over the last N commits (see --from-n-commit) when nothing was propagated. |
 | `--unpush` | With --log, automatically sets range to unpushed commits ahead of remote. |
 | `-b` | Shows the current Git branch name. |
 | `-p [branch]` | Shows the reflog for the specified branch. |
@@ -259,28 +267,6 @@ Pushes committed changes from a local repository to a remote GitHub repository.
 
 ---
 
-### underpost env
-
-Sets environment variables and configurations related to a specific deployment ID.
-
-**Usage:** `underpost env [options] [deploy-id] [env] [subConf]`
-
-#### Arguments
-
-| Argument | Description |
-| --- | --- |
-| `deploy-id` | The deployment configuration ID. Use 'clean' to restore default environment settings. Use 'root' to load underpost root env. Use 'current' to get plain current deploy Id. |
-| `env` | Optional: The environment to set (e.g., "production", "development"). Defaults to "production". |
-| `subConf` | Optional: The sub configuration to set. |
-
-#### Options
-
-| Option | Description |
-| --- | --- |
-| `-h, --help` | display help for command |
-
----
-
 ### underpost static
 
 Manages static build of page, bundles, and documentation with comprehensive customization options.
@@ -324,33 +310,6 @@ Manages static build of page, bundles, and documentation with comprehensive cust
 
 ---
 
-### underpost config
-
-Manages Underpost configurations using various operators.
-
-**Usage:** `underpost config [options] <operator> [key] [value]`
-
-#### Arguments
-
-| Argument | Description |
-| --- | --- |
-| `operator` | The configuration operation to perform. Options: set, delete, get, list, clean, isInsideContainer. |
-| `key` | Optional: The specific configuration key to manage. |
-| `value` | Optional: The value to set for the configuration key. |
-
-#### Options
-
-| Option | Description |
-| --- | --- |
-| `--plain` | Prints the configuration value in plain text. |
-| `--filter <keyword>` | Filters the list by matching key or value (only for list operation). |
-| `--deploy-id <deploy-id>` | Sets the deployment configuration ID for the operation context. |
-| `--build` | Sets the build context for the operation. |
-| `--copy` | Copies the configuration value to the clipboard (only for get operation). |
-| `-h, --help` | display help for command |
-
----
-
 ### underpost root
 
 Displays the root path of the npm installation.
@@ -397,6 +356,8 @@ Displays the current public machine IP addresses.
 | `--unblock-all-egress` | Unblocks all outbound traffic and restores default ACCEPT policy. |
 | `--block-all-ingress` | Blocks all new inbound traffic to this host (keeps established/related connections). |
 | `--unblock-all-ingress` | Unblocks all inbound traffic and restores default ACCEPT policy. |
+| `--block-ingress-port <ports>` | Blocks new inbound traffic on comma-separated TCP ports, leaving the management path reachable. |
+| `--unblock-ingress-port <ports>` | Withdraws the port rules --block-ingress-port installed. |
 | `--mac` | Prints the MAC address of the main network interface. |
 | `-h, --help` | display help for command |
 
@@ -433,15 +394,15 @@ Manages Kubernetes clusters, defaulting to Kind cluster initialization.
 | `--gateway-class <name>` | GatewayClass name to provision (default "eg"). |
 | `--ingress-node <node-name>` | Dedicated node for underpost-ingress when both routing stacks coexist. Workload placement flags do not move it. |
 | `--node-port` | Exposes enabled ready services (e.g. MongoDB 4.4, Valkey) to the host/public network via their NodePort Service manifest. |
-| `--node-selector <k8s-node-name>` | Pins the just-deployed StatefulSet (MongoDB 4.4 / Valkey) to the given Kubernetes node once it is ready (via a kubernetes.io/hostname nodeSelector). |
+| `--node-name <k8s-node-name>` | Pins the just-deployed workload (MongoDB 4.4 / Valkey StatefulSets, the observability Deployments) to the given Kubernetes node once it is ready, via a kubernetes.io/hostname nodeSelector. |
 | `--cert-manager` | Initializes the cluster with a Let's Encrypt production ClusterIssuer. |
 | `--dedicated-gpu` | Initializes the cluster with dedicated GPU base resources and environment settings. |
 | `--ns-use <ns-name>` | Switches the current Kubernetes context to the specified namespace (creates if it doesn't exist). |
 | `--kubeadm` | Initializes the cluster using kubeadm for control plane management. |
 | `--pod-network-cidr <cidr>` | Sets custom pod network CIDR for kubeadm cluster initialization (defaults to "192.168.0.0/16"). |
 | `--control-plane-endpoint <endpoint>` | Sets custom control plane endpoint for kubeadm cluster initialization (defaults to "localhost:6443"). |
-| `--grafana` | Initializes the cluster with a Grafana deployment. |
-| `--prom [hosts]` | Initializes the cluster with a Prometheus Operator deployment and monitor scrap for specified hosts. |
+| `--grafana` | Initializes the cluster with the observability stack (Prometheus, Alertmanager, Blackbox Exporter, Grafana). Equivalent to --prom; both converge the one stack. |
+| `--prom [hosts]` | Initializes the cluster with the observability stack. Scrape targets are derived from each deploy conf.server.json; the optional comma-separated hosts are scraped at /metrics in addition to them. |
 | `--dev` | Initializes a development-specific cluster configuration. |
 | `--list-pods` | Displays detailed information about all pods. |
 | `--pull-image` | Sets an optional associated image to pull during initialization. |
@@ -521,36 +482,110 @@ Manages application deployments, defaulting to deploying development pods.
 
 ### underpost secret
 
-Manages secrets for various platforms.
+Workload secret store: SOPS/Age encrypted credentials projected as Kubernetes Secrets.
+
+**Usage:** `underpost secret [options] <action>`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `action` | Action to run. One of: setup, load, publish, apply, status, rotate, clean. setup Onboards the domain: provisions whatever it needs, then converges it. Idempotent. load Loads the durable source into the local runtime environment. publish Writes the local runtime environment into the durable source. apply Projects the durable source into the live cluster. status Read-only report of the domain: sources, keys, and drift from the cluster. rotate Replaces the current projection or encryption identity. clean Withdraws the domain traces from the local filesystem. |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--env <env>` | Target environment: development \| production \| test (default: production). |
+| `--namespace <namespace>` | Kubernetes namespace to act on (default: default). |
+| `--args <key=value-list>` | Comma-separated domain parameters, e.g. `names=postgres-secret`, `recipient=age1...`, `sub-conf=nexodev`. |
+| `--dry-run` | Reports what the action would change without changing anything. |
+| `--force` | Confirms the irreversible variant of the action. |
+| `-h, --help` | display help for command |
+
+---
+
+### underpost host
 
-**Usage:** `underpost secret [options] [platform]`
+Host configuration: the node-level operational environment shared by the cluster.
+
+**Usage:** `underpost host [options] <action> [key] [value]`
 
 #### Arguments
 
 | Argument | Description |
 | --- | --- |
-| `platform` | The secret management platform. Options: underpost, sops, sanitizeSecretEnvFile, globalSecretClean. Defaults to "sops". (default: "sops") |
+| `action` | Action to run. One of: setup, load, publish, apply, status, rotate, clean, get, set, delete, list. setup Onboards the domain: provisions whatever it needs, then converges it. Idempotent. load Loads the durable source into the local runtime environment. publish Writes the local runtime environment into the durable source. apply Projects the durable source into the live cluster. status Read-only report of the domain: sources, keys, and drift from the cluster. rotate Replaces the current projection or encryption identity. clean Withdraws the domain traces from the local filesystem. get\|set\|delete\|list Key-level access to the store this domain owns. |
+| `key` | Key to act on, for the key-level operators. |
+| `value` | Value to write, for the `set` operator. |
 
 #### Options
 
 | Option | Description |
 | --- | --- |
-| `--init` | Initializes the secrets platform environment. |
-| `--create-from-file <path-env-file>` | Creates secrets from a specified environment file. |
-| `--create-from-env` | Creates secrets from container environment variables (envFrom: secretRef). |
-| `--global-clean` | Removes all filesystem traces of secrets (engine-private, .env, conf cache). |
-| `--list` | Lists all available secrets for the platform. |
-| `--encrypt <plaintext-path>` | Encrypts a plaintext Secret manifest into the Git-tracked SOPS store and shreds the source (sops platform). |
-| `--apply` | Decrypts stored SOPS manifests and streams them into kubectl apply, without writing plaintext to disk (sops platform). |
-| `--namespace <namespace>` | Kubernetes namespace for secret operations (defaults to "default"). |
-| `--install-tools` | Installs the sops and age host binaries only, without running a full cluster host initialization. |
-| `--rotate` | Re-keys every stored SOPS manifest onto --recipient. Secret values are unchanged, so no workload restart is needed. |
-| `--recipient <age-public-key>` | Incoming Age public recipient for --rotate. |
-| `--prune-recipients` | With --rotate, makes --recipient the only recipient, revoking every previous key (use after a key compromise). Requires --force, and revokes CI/CD keys too unless they are named in --keep-recipients. |
-| `--keep-recipients <age-public-keys>` | Comma-separated recipients to retain while --prune-recipients revokes the rest (e.g. the CI/CD key). |
-| `--purge <secret-name>` | Emergency removal: deletes the live Kubernetes Secret and takes its encrypted manifest out of the store. |
-| `--force` | Confirms the irreversible variant: deletes the manifest instead of archiving it (--purge), revokes recipients (--rotate --prune-recipients), or replaces an existing manifest (--encrypt). |
-| `--dry-run` | Reports what --apply, --rotate, or --purge would do without changing anything. |
+| `--env <env>` | Target environment: development \| production \| test (default: production). |
+| `--namespace <namespace>` | Kubernetes namespace to act on (default: default). |
+| `--args <key=value-list>` | Comma-separated domain parameters, e.g. `names=postgres-secret`, `recipient=age1...`, `sub-conf=nexodev`. |
+| `--dry-run` | Reports what the action would change without changing anything. |
+| `--force` | Confirms the irreversible variant of the action. |
+| `--plain` | Prints the value in plain text (get). |
+| `--filter <keyword>` | Filters by matching key or value (list). |
+| `--copy` | Copies the value to the clipboard (get). |
+| `-h, --help` | display help for command |
+
+---
+
+### underpost app
+
+Application environment: one deployment's runtime configuration.
+
+**Usage:** `underpost app [options] <action>`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `action` | Action to run. One of: setup, load, publish, apply, status, rotate, clean. setup Onboards the domain: provisions whatever it needs, then converges it. Idempotent. load Loads the durable source into the local runtime environment. publish Writes the local runtime environment into the durable source. apply Projects the durable source into the live cluster. status Read-only report of the domain: sources, keys, and drift from the cluster. rotate Replaces the current projection or encryption identity. clean Withdraws the domain traces from the local filesystem. |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--env <env>` | Target environment: development \| production \| test (default: production). |
+| `--namespace <namespace>` | Kubernetes namespace to act on (default: default). |
+| `--args <key=value-list>` | Comma-separated domain parameters, e.g. `names=postgres-secret`, `recipient=age1...`, `sub-conf=nexodev`. |
+| `--dry-run` | Reports what the action would change without changing anything. |
+| `--force` | Confirms the irreversible variant of the action. |
+| `-h, --help` | display help for command |
+
+---
+
+### underpost state
+
+Runtime state: live container execution state, health and metrics, exported off-cluster.
+
+**Usage:** `underpost state [options] <action> [key] [value]`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `action` | Action to run. One of: setup, load, publish, apply, status, rotate, clean, get, set, delete, list. setup Onboards the domain: provisions whatever it needs, then converges it. Idempotent. load Loads the durable source into the local runtime environment. publish Writes the local runtime environment into the durable source. apply Projects the durable source into the live cluster. status Read-only report of the domain: sources, keys, and drift from the cluster. rotate Replaces the current projection or encryption identity. clean Withdraws the domain traces from the local filesystem. get\|set\|delete\|list Key-level access to the store this domain owns. |
+| `key` | Key to act on, for the key-level operators. |
+| `value` | Value to write, for the `set` operator. |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--env <env>` | Target environment: development \| production \| test (default: production). |
+| `--namespace <namespace>` | Kubernetes namespace to act on (default: default). |
+| `--args <key=value-list>` | Comma-separated domain parameters, e.g. `names=postgres-secret`, `recipient=age1...`, `sub-conf=nexodev`. |
+| `--dry-run` | Reports what the action would change without changing anything. |
+| `--force` | Confirms the irreversible variant of the action. |
+| `--plain` | Prints the value in plain text (get). |
+| `--filter <keyword>` | Filters by matching key or value (list). |
+| `--copy` | Copies the value to the clipboard (get). |
 | `-h, --help` | display help for command |
 
 ---
@@ -624,7 +659,6 @@ Manages database operations with support for MariaDB and MongoDB, including impo
 | `--pod-name <pod-name>` | Comma-separated list of pod names or patterns (supports wildcards like "mariadb-*"). |
 | `--all-pods` | Target all matching pods instead of just the first one. |
 | `--primary-pod` | Automatically detect and use MongoDB primary pod (MongoDB only). |
-| `--primary-pod-ensure <pod-name>` | Ensure setup of MongoDB replica set primary pod before operations. |
 | `--stats` | Display database statistics (collection/table names with document/row counts). |
 | `--collections <collections>` | Comma-separated list of database collections to operate on. |
 | `--out-path <out-path>` | Specifies a custom output path for backups. |
@@ -698,7 +732,7 @@ Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manif
 | `--setup-start` | Updates deploy-list package.json start script and generates+applies its K8s CronJob manifests. |
 | `--namespace <namespace>` | Kubernetes namespace for the CronJob resources (default: "default"). |
 | `--image <image>` | Custom container image for the CronJob pods. |
-| `--node-name <node-name>` | Pins the CronJob pods to this node via a kubernetes.io/hostname nodeSelector. |
+| `--node-name <node-name>` | Pins the CronJob pods to this node via a kubernetes.io/hostname nodeSelector. With --apply, defaults to this machine when the cluster knows it as a node, because the pods mount its checkout. |
 | `--git` | Pass --git flag to cron job execution. |
 | `--cmd <cmd>` | Optional pre-script commands to run before cron execution. |
 | `--dev` | Use local ./ base path instead of global underpost installation. |
@@ -739,43 +773,17 @@ Manages file storage, defaulting to file upload operations.
 
 ---
 
-### underpost test
-
-Manages and runs tests, defaulting to the current Underpost default test suite.
-
-**Usage:** `underpost test [options] [deploy-list]`
-
-#### Arguments
-
-| Argument | Description |
-| --- | --- |
-| `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). |
-
-#### Options
-
-| Option | Description |
-| --- | --- |
-| `--itc` | Executes tests within the container execution context. |
-| `--sh` | Copies the container entrypoint shell command to the clipboard. |
-| `--logs` | Displays container logs for test debugging. |
-| `--pod-name <pod-name>` | Optional: Specifies the pod name for test execution. |
-| `--pod-status <pod-status>` | Optional: Filters tests by pod status. |
-| `--kind-type <kind-type>` | Optional: Specifies the Kind cluster type for tests. |
-| `-h, --help` | display help for command |
-
----
-
 ### underpost monitor
 
-Manages health server monitoring for specified deployments.
+Manages health server monitoring, the cluster observability stack, and host dashboards.
 
-**Usage:** `underpost monitor [options] <deploy-id> [env]`
+**Usage:** `underpost monitor [options] [deploy-id] [env]`
 
 #### Arguments
 
 | Argument | Description |
 | --- | --- |
-| `deploy-id` | The deployment configuration ID to monitor. |
+| `deploy-id` | The deployment configuration ID to monitor. With the observability flags it selects which deploys are scraped; "dd" covers every deploy in dd.routes. (default: "dd") |
 | `env` | Optional: The environment to monitor (e.g., "development", "production"). Defaults to "development". |
 
 #### Options
@@ -797,13 +805,70 @@ Manages health server monitoring for specified deployments.
 | `--versions <deployment-versions>` | Specifies the deployment versions to monitor. eg. "blue,green", "green" |
 | `--ready-deployment` | Run in ready deployment monitor mode. |
 | `--promote` | Promotes the deployment after monitoring. |
+| `--observability` | Deploys or converges the cluster observability stack (Prometheus, Alertmanager, Blackbox Exporter, Grafana), ensuring the Gateway API metrics source and local-path storage provisioner are ready. |
+| `--sync-prom` | Regenerates the scrape configuration, alert rules and Alertmanager route from the live deploy configuration and event registry, applies Grafana admin credentials, then reloads or rolls only the affected component. |
+| `--events <event-ids>` | Comma-separated event ids to provision; empty provisions every registered event. |
+| `--webhook-url <url>` | URL Alertmanager delivers events to (defaults to the node address of `event --serve`). |
+| `--extra-targets <targets>` | Comma-separated additional "host:port" scrape targets. |
+| `--metrics-server` | Installs the Kubernetes metrics-server (kubectl top / HPA resource API). Skipped on K3s, which bundles its own, unless --force. |
+| `--cockpit` | Installs and enables the Cockpit KVM dashboard on this host (cockpit, cockpit-machines, libvirt) and opens its firewall service. |
+| `--cockpit-stop` | Stops and disables the Cockpit KVM dashboard and closes its firewall service. |
+| `--grafana-host <host>` | Publishes Grafana at https://<host>/grafana through the edge Gateway that already serves that hostname. |
+| `--node-port` | Publishes Grafana on the node's LAN address (port 32300). |
+| `--expose-grafana` | Republishes Grafana with --grafana-host / --node-port without redeploying the stack. |
+| `--webhook-token` | Prints the shared event webhook token, to persist as UNDERPOST_EVENT_TOKEN in the cron deploy env. |
+| `--node-name <k8s-node-name>` | Pins every monitoring workload to this node; moving Grafana deletes and recreates its node-local data. |
+| `--kubeadm` | Treats the cluster as kubeadm when resolving node and host addresses. |
+| `--kind` | Treats the cluster as Kind (Docker nodes) when resolving node and host addresses. |
+| `--k3s` | Treats the cluster as K3s when resolving node and host addresses. |
+| `--force` | Confirms an install that would replace a bundled component (e.g. --metrics-server on K3s). |
+| `--dev` | Sets the development cli context (scrapes over HTTP, defaults the cluster type to Kind). |
+| `-h, --help` | display help for command |
+
+---
+
+### underpost event
+
+Dispatches operational events and provisions the monitoring rules that trigger them.
+
+**Usage:** `underpost event [options] [event-id]`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `event-id` | The operational event to dispatch. Options: wireguard-server-down,wireguard-spoke-down,public-ingress-down,node-cpu-limit-exceeded,node-memory-limit-exceeded,hub-bandwidth-limit-exceeded,node-disk-limit-exceeded,node-network-traffic-exceeded. |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--deploy` | Merges the event into the set already deployed in the cluster and republishes the monitoring configuration. |
+| `--undeploy` | Removes the event from the deployed set and republishes without it. |
+| `--suspend-events <state-file>` | Saves the exact deployed event set and temporarily republishes observability without event probes or alerts. |
+| `--resume-events <state-file>` | Restores and resynchronizes the exact event set saved by --suspend-events, then removes the state file. |
+| `--serve` | Runs the Alertmanager webhook receiver in the foreground (use --service to supervise it). |
+| `--service` | Installs the receiver on a WireGuard control node as the underpost-event systemd unit. It remains available while the tunnel is down. |
+| `--service-stop` | Stops, disables and removes the underpost-event systemd unit. |
+| `--service-status` | Reports whether the underpost-event unit is active and enabled. |
+| `--list` | Lists the registered events with their resolved probe targets. |
+| `--port <port>` | Listening port for --serve and the generated unit (default: 39099). |
+| `--cooldown-ms <ms>` | Minimum interval between two dispatches of one event in --serve (default: 300000). |
+| `--spoke <spoke-id>` | Spoke to remediate when dispatching wireguard-spoke-down by hand; a webhook takes it from the alert labels. |
+| `--nodes <node-names>` | Comma-separated node documents to act on — hubs for wireguard-server-down, peers for wireguard-spoke-down. Empty covers every registered hub, or every peer of this node hub. |
+| `--namespace <namespace>` | Kubernetes namespace holding the observability stack. Defaults to "default". |
+| `--webhook-url <url>` | URL Alertmanager delivers to, written into the generated route with --deploy. |
+| `--dev` | Sets the development cli context. |
+| `--dry-run` | Reports the remediation the event would run without executing it. |
+| `--no-notify` | Skips the operational alert declared in engine-private/deploy/conf.event.json. |
+| `--e2e-test` | Rehearses the event against the live edge: breaks the real subject, waits for the probe to fail, runs the remediation, and verifies the notification was actually sent. |
 | `-h, --help` | display help for command |
 
 ---
 
 ### underpost ssh
 
-Manages SSH credentials and sessions for remote access to cluster nodes or services.
+Manages cluster scoped SSH credentials and sessions for remote access to cluster nodes or services. Users are registered in engine-private/deploy/conf.users.json and keys are stored in engine-private/deploy/users/<user>.
 
 **Usage:** `underpost ssh [options]`
 
@@ -811,7 +876,6 @@ Manages SSH credentials and sessions for remote access to cluster nodes or servi
 
 | Option | Description |
 | --- | --- |
-| `--deploy-id <deploy-id>` | Sets deploy id context for ssh operations. |
 | `--generate` | Generates new ssh credential and stores it in current private keys file storage. |
 | `--user <user>` | Sets custom ssh user |
 | `--password <password>` | Sets custom ssh password |
@@ -830,8 +894,6 @@ Manages SSH credentials and sessions for remote access to cluster nodes or servi
 | `--key-test` | Tests the SSH key using ssh-keygen. |
 | `--stop` | Stops the SSH service. |
 | `--status` | Checks the status of the SSH service. |
-| `--connect-uri` | Displays the connection URI. |
-| `--copy` | Copies the connection URI to clipboard. |
 | `-h, --help` | display help for command |
 
 ---
@@ -846,35 +908,51 @@ Manages the WireGuard L3 hub-and-spoke transport and the HAProxy edge gateway in
 
 | Option | Description |
 | --- | --- |
-| `--deploy-id <deploy-id>` | Deploy IDs whose conf.server.json/conf.instances.json define the routes. Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.router, because the edge holds one pair of map files for the whole cluster. |
+| `--deploy-id <deploy-id>` | Deploy IDs whose conf.server.json/conf.instances.json define the routes. Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.routes, because the edge holds one pair of map files for the whole cluster. |
 | `--interface <name>` | WireGuard interface name (default: "wg0"). |
 | `--wireguard-install` | Installs the wireguard-tools, haproxy and iptables host packages. |
 | `--wireguard-setup` | Generates keys, builds the interface config, and applies local network rules. |
-| `--server` | Configures this node as the hub endpoint accepting inbound tunnel traffic. |
-| `--client` | Configures this node as a spoke endpoint maintaining an outbound tunnel. |
+| `--node-config` | Writes a node identity under deploy/nodes, named after the machine it describes. |
+| `--node-name <node-name>` | Node record to write; defaults to this hostname, which is what runtime commands resolve their identity by. |
+| `--node-role <role>` | Machine role: control, worker, or hub. |
+| `--hub-host <ipv4>` | Static public IPv4 key of the hub topology this node belongs to. |
 | `--port <port>` | WireGuard UDP listening port (default: 51820). |
-| `--cidr <cidr>` | Hub interface address with prefix when used with --server (e.g. "10.0.0.1/24"); the overlay subnet a spoke routes back through the hub when used with --client (default: "10.0.0.0/24"). |
-| `--peer-ip <ip>` | Tunnel address of the target spoke. Required with --client and --peer-add. |
-| `--endpoint <host:port>` | Hub host and port a spoke dials. Required with --client. |
-| `--public-key <key>` | Hub public key with --client; spoke public key with --peer-add. |
+| `--cidr <cidr>` | Hub interface address on a hub; overlay subnet routed through the hub on control and worker nodes. |
+| `--peer-ip <ip>` | Tunnel address used by --peer-add or to update the selected node during setup. |
+| `--peer-id <peer-id>` | Topology peer represented by a control or worker node identity. |
+| `--public-key <key>` | Public key used by off-host topology authoring or --peer-add. |
 | `--peer-add <peer-id>` | Registers a spoke and applies it to the running hub without a restart. |
-| `--peer-remove <peer-id>` | Removes a spoke from the registry and from the running hub. |
+| `--peer-remove <peer-id>` | Removes a peer from the selected topology and running hub. |
 | `--allowed-ips <cidrs>` | Comma-separated CIDRs routed to the spoke (e.g. "10.0.0.2/32,192.168.10.0/24"). |
 | `--hosts <hosts>` | Comma-separated hostnames bound to the spoke, overriding instance resolution. |
 | `--instances <instances>` | Comma-separated conf.instances.json ids bound to the spoke. |
+| `--management-host <host>` | Stable LAN or management address used to repair this peer when its tunnel address is unavailable. |
 | `--default` | Marks the spoke as the fallback for hostnames that match no other binding. |
 | `--haproxy-setup` | Installs HAProxy, publishes the current routes, and enables the daemon. |
 | `--haproxy-sync` | Recompiles the SNI/Host maps from deploy config and hot-reloads HAProxy. |
 | `--status` | Prints the whole edge context without changing anything: role, interface, tunnel address, public key, daemon states, peers with their bindings and link health, and the resolved routing. |
-| `--build-conf` | Writes only engine-private/deploy/conf.wireguard.json and touches no host state. Combine with --wireguard-setup / --peer-add / --peer-remove to author the topology off-box; alone it normalizes and validates the existing registry. |
+| `--build-conf` | Writes only engine-private/deploy/conf.wireguard.json and touches no host state. Combine with --wireguard-setup / --peer-add / --peer-remove to author the topology off-box; alone it normalizes and validates the existing topology. |
 | `--forward-proxy-server` | Ensures the hub HTTP/CONNECT forward proxy runs as the underpost-forward-proxy systemd service, bound to the tunnel address only (default port 1080), and returns. Authenticates every request with FORWARD_PROXY_API_KEY, so spokes can reach the internet through the VPS public address. Idempotent: re-running converges on the one service and restarts it only when the unit actually changed. |
-| `--forward-proxy-server-host <host>` | Address the forward proxy binds, overriding the hub tunnel address from the registry. |
+| `--forward-proxy-server-host <host>` | Address the forward proxy binds, overriding the selected hub tunnel address. |
 | `--forward-proxy-server-port <port>` | Port the forward proxy binds (default: 1080). |
-| `--ssh-forward-port <port>` | Publishes the default spoke SSH port on this public TCP port of the hub, so CI with no fixed address can reach the cluster node (e.g. 2222). "0" closes it. Stored in the registry. |
+| `--ssh-forward-port <port>` | Publishes the default spoke SSH port on this public TCP port of the hub, so CI with no fixed address can reach the cluster node (e.g. 2222). "0" closes it. Stored in hub topology. |
+| `--sync` | Brings every registered node engine checkout up to date over its SSH identity: clean, pull, fix and install. |
+| `--nodes <node-names>` | Comma-separated node documents --sync, --cmd, --node-exporter and --connect-uri act on. Empty covers every hub and every peer of this node hub. |
+| `--connect-uri` | Prints the SSH command that reaches each node named by --nodes, joining the node document under engine-private/deploy/nodes to the management address it is registered under in engine-private/deploy/conf.users.json. Empty --nodes lists the whole fleet. |
+| `--copy` | Copies the --connect-uri output to the clipboard instead of printing it. |
+| `--cmd <command-list>` | Comma-separated custom commands to run on the selected nodes over their SSH identity. Given with --sync, only these run in place of the sync steps. |
+| `--node-exporter` | Provisions the host metrics collector as a systemd service on the selected hub nodes, bound to their tunnel address, so machines outside the cluster report hardware metrics like every cluster node. |
+| `--repo-engine <repo>` | Engine repository --sync pulls from, as owner/repo or a clone URL. Defaults to the configured account engine. |
+| `--repo-engine-private <repo>` | Private engine repository --sync pulls from, as owner/repo or a clone URL. Defaults to the configured private repo derived from --repo-engine. |
 | `--wireguard-start` | Enables and starts wg-quick@<interface> and the QUIC forward. |
+| `--wireguard-restart` | Restarts wg-quick@<interface> and restores the hub QUIC forward. |
 | `--wireguard-stop` | Tears down the interface and removes its transient packet rules. |
-| `--wireguard-reset` | Removes generated configs and packet rules, keeping the key pair and registry. |
-| `--wireguard-reinstall` | Full purge, package reinstall and re-key; every spoke must re-register. |
+| `--check` | Waits for an active interface and a fresh handshake with its required peer. |
+| `--check-timeout <seconds>` | Maximum wait for --check (default: 30). |
+| `--expected-role <role>` | Refuses restart/check unless this host has the expected node role. |
+| `--expected-id <peer-id>` | Refuses restart/check unless this node represents the expected peer id. |
+| `--wireguard-reset` | Removes generated host state, keeping keys, topology and node identity. |
+| `--wireguard-reinstall` | Full purge, package reinstall and re-key; updates the selected topology key. |
 | `--dry-run` | Prints the files and commands the run would apply, without touching the host. |
 | `-h, --help` | display help for command |
 
@@ -890,35 +968,51 @@ Manages the HAProxy edge gateway over the WireGuard transport (same subsystem as
 
 | Option | Description |
 | --- | --- |
-| `--deploy-id <deploy-id>` | Deploy IDs whose conf.server.json/conf.instances.json define the routes. Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.router, because the edge holds one pair of map files for the whole cluster. |
+| `--deploy-id <deploy-id>` | Deploy IDs whose conf.server.json/conf.instances.json define the routes. Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.routes, because the edge holds one pair of map files for the whole cluster. |
 | `--interface <name>` | WireGuard interface name (default: "wg0"). |
 | `--wireguard-install` | Installs the wireguard-tools, haproxy and iptables host packages. |
 | `--wireguard-setup` | Generates keys, builds the interface config, and applies local network rules. |
-| `--server` | Configures this node as the hub endpoint accepting inbound tunnel traffic. |
-| `--client` | Configures this node as a spoke endpoint maintaining an outbound tunnel. |
+| `--node-config` | Writes a node identity under deploy/nodes, named after the machine it describes. |
+| `--node-name <node-name>` | Node record to write; defaults to this hostname, which is what runtime commands resolve their identity by. |
+| `--node-role <role>` | Machine role: control, worker, or hub. |
+| `--hub-host <ipv4>` | Static public IPv4 key of the hub topology this node belongs to. |
 | `--port <port>` | WireGuard UDP listening port (default: 51820). |
-| `--cidr <cidr>` | Hub interface address with prefix when used with --server (e.g. "10.0.0.1/24"); the overlay subnet a spoke routes back through the hub when used with --client (default: "10.0.0.0/24"). |
-| `--peer-ip <ip>` | Tunnel address of the target spoke. Required with --client and --peer-add. |
-| `--endpoint <host:port>` | Hub host and port a spoke dials. Required with --client. |
-| `--public-key <key>` | Hub public key with --client; spoke public key with --peer-add. |
+| `--cidr <cidr>` | Hub interface address on a hub; overlay subnet routed through the hub on control and worker nodes. |
+| `--peer-ip <ip>` | Tunnel address used by --peer-add or to update the selected node during setup. |
+| `--peer-id <peer-id>` | Topology peer represented by a control or worker node identity. |
+| `--public-key <key>` | Public key used by off-host topology authoring or --peer-add. |
 | `--peer-add <peer-id>` | Registers a spoke and applies it to the running hub without a restart. |
-| `--peer-remove <peer-id>` | Removes a spoke from the registry and from the running hub. |
+| `--peer-remove <peer-id>` | Removes a peer from the selected topology and running hub. |
 | `--allowed-ips <cidrs>` | Comma-separated CIDRs routed to the spoke (e.g. "10.0.0.2/32,192.168.10.0/24"). |
 | `--hosts <hosts>` | Comma-separated hostnames bound to the spoke, overriding instance resolution. |
 | `--instances <instances>` | Comma-separated conf.instances.json ids bound to the spoke. |
+| `--management-host <host>` | Stable LAN or management address used to repair this peer when its tunnel address is unavailable. |
 | `--default` | Marks the spoke as the fallback for hostnames that match no other binding. |
 | `--haproxy-setup` | Installs HAProxy, publishes the current routes, and enables the daemon. |
 | `--haproxy-sync` | Recompiles the SNI/Host maps from deploy config and hot-reloads HAProxy. |
 | `--status` | Prints the whole edge context without changing anything: role, interface, tunnel address, public key, daemon states, peers with their bindings and link health, and the resolved routing. |
-| `--build-conf` | Writes only engine-private/deploy/conf.wireguard.json and touches no host state. Combine with --wireguard-setup / --peer-add / --peer-remove to author the topology off-box; alone it normalizes and validates the existing registry. |
+| `--build-conf` | Writes only engine-private/deploy/conf.wireguard.json and touches no host state. Combine with --wireguard-setup / --peer-add / --peer-remove to author the topology off-box; alone it normalizes and validates the existing topology. |
 | `--forward-proxy-server` | Ensures the hub HTTP/CONNECT forward proxy runs as the underpost-forward-proxy systemd service, bound to the tunnel address only (default port 1080), and returns. Authenticates every request with FORWARD_PROXY_API_KEY, so spokes can reach the internet through the VPS public address. Idempotent: re-running converges on the one service and restarts it only when the unit actually changed. |
-| `--forward-proxy-server-host <host>` | Address the forward proxy binds, overriding the hub tunnel address from the registry. |
+| `--forward-proxy-server-host <host>` | Address the forward proxy binds, overriding the selected hub tunnel address. |
 | `--forward-proxy-server-port <port>` | Port the forward proxy binds (default: 1080). |
-| `--ssh-forward-port <port>` | Publishes the default spoke SSH port on this public TCP port of the hub, so CI with no fixed address can reach the cluster node (e.g. 2222). "0" closes it. Stored in the registry. |
+| `--ssh-forward-port <port>` | Publishes the default spoke SSH port on this public TCP port of the hub, so CI with no fixed address can reach the cluster node (e.g. 2222). "0" closes it. Stored in hub topology. |
+| `--sync` | Brings every registered node engine checkout up to date over its SSH identity: clean, pull, fix and install. |
+| `--nodes <node-names>` | Comma-separated node documents --sync, --cmd, --node-exporter and --connect-uri act on. Empty covers every hub and every peer of this node hub. |
+| `--connect-uri` | Prints the SSH command that reaches each node named by --nodes, joining the node document under engine-private/deploy/nodes to the management address it is registered under in engine-private/deploy/conf.users.json. Empty --nodes lists the whole fleet. |
+| `--copy` | Copies the --connect-uri output to the clipboard instead of printing it. |
+| `--cmd <command-list>` | Comma-separated custom commands to run on the selected nodes over their SSH identity. Given with --sync, only these run in place of the sync steps. |
+| `--node-exporter` | Provisions the host metrics collector as a systemd service on the selected hub nodes, bound to their tunnel address, so machines outside the cluster report hardware metrics like every cluster node. |
+| `--repo-engine <repo>` | Engine repository --sync pulls from, as owner/repo or a clone URL. Defaults to the configured account engine. |
+| `--repo-engine-private <repo>` | Private engine repository --sync pulls from, as owner/repo or a clone URL. Defaults to the configured private repo derived from --repo-engine. |
 | `--wireguard-start` | Enables and starts wg-quick@<interface> and the QUIC forward. |
+| `--wireguard-restart` | Restarts wg-quick@<interface> and restores the hub QUIC forward. |
 | `--wireguard-stop` | Tears down the interface and removes its transient packet rules. |
-| `--wireguard-reset` | Removes generated configs and packet rules, keeping the key pair and registry. |
-| `--wireguard-reinstall` | Full purge, package reinstall and re-key; every spoke must re-register. |
+| `--check` | Waits for an active interface and a fresh handshake with its required peer. |
+| `--check-timeout <seconds>` | Maximum wait for --check (default: 30). |
+| `--expected-role <role>` | Refuses restart/check unless this host has the expected node role. |
+| `--expected-id <peer-id>` | Refuses restart/check unless this node represents the expected peer id. |
+| `--wireguard-reset` | Removes generated host state, keeping keys, topology and node identity. |
+| `--wireguard-reinstall` | Full purge, package reinstall and re-key; updates the selected topology key. |
 | `--dry-run` | Prints the files and commands the run would apply, without touching the host. |
 | `-h, --help` | display help for command |
 
@@ -967,7 +1061,7 @@ Runs specified scripts using various runners.
 
 | Argument | Description |
 | --- | --- |
-| `runner-id` | The runner ID to run. Options: status,expose,dev-cluster,metadata,ipfs-expose,svc-ls,svc-rm,node-move,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,tz,get-traffic,restore-mongo,ingress-refresh,instance-promote,instance,deploy-key,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,gateway-status,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,sh,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,pull-rocky-image,rmi,kill,generate-pass,sops-setup,sops-status,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,kubeadm-wireguard,build-cluster-deployment-manifests,monitor-ui,shared-dir,shared-dir-add-user. |
+| `runner-id` | The runner ID to run. Options: status,expose,dev-cluster,metadata,ipfs-expose,svc-ls,svc-rm,node-move,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,ssh-deploy,ide,crypto-policy,sync,net-tables,stop,tz,get-traffic,restore-mongo,ingress-refresh,instance-promote,instance,deploy-key,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,cluster,gateway-status,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,kill,generate-pass,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,kubeadm-wireguard,build-cluster-deployment-manifests,monitor-ui,shared-dir,shared-dir-add-user. |
 | `path` | The input value, identifier, or path for the operation. |
 
 #### Options
@@ -992,6 +1086,9 @@ Runs specified scripts using various runners.
 | `--volume-mount-path <volume-mount-path>` | Optional: Specifies the volume mount path for test execution. |
 | `--volume-type <volume-type>` | Optional: Specifies the volume type for test execution. |
 | `--image-name <image-name>` | Optional: Specifies the image name for test execution. |
+| `--image <image>` | Container image the deployment pulls and runs (sync). |
+| `--runtime-image <name>` | src/runtime/<name> image family the cluster runner brings up (default "express"). |
+| `--versions <deployment-versions>` | Comma-separated blue/green deployment versions (sync); unset resolves the next colour. |
 | `--container-name <container-name>` | Optional: Specifies the container name for test execution. |
 | `--namespace <namespace>` | Optional: Specifies the namespace for test execution. |
 | `--tty` | Enables TTY for the container in deploy-job. |
@@ -1038,6 +1135,7 @@ Runs specified scripts using various runners.
 | `--gateway-class <name>` | GatewayClass name for generated Gateway manifests (default "eg"). |
 | `--disable-http3` | Omits the QUIC/HTTP3 listener config and the Alt-Svc advertisement from Gateway API manifests. |
 | `--quic-port <port>` | UDP port advertised for QUIC/HTTP3 in generated Gateway API manifests (default 443). |
+| `--repo-engine-private <repo>` | Private configuration repository the pull runner checks out, as owner/repo or a clone URL. Defaults to the private repo derived from the engine source. |
 | `--disable-private-conf-update` | Disables updates to private configuration during execution. |
 | `--logs` | Streams logs during the runner execution. |
 | `--monitor-status <status>` | Sets the status to monitor for pod/resource (default: "Running"). |
@@ -1058,6 +1156,42 @@ Runs specified scripts using various runners.
 
 ---
 
+### underpost test
+
+Runs the test tiers locally, inside deployment pods, or as a cluster Job with Allure reporting.
+
+**Usage:** `underpost test [options] [suite]`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `suite` | A comma-separated list of suites or tiers to run. Suites: unit, infra, app, cyberia, contracts, all. Tiers: unit, infra:1-security, infra:2-network, infra:3-cluster, infra:4-ingress, infra:5-observability, app, cyberia, contracts. Defaults to every tier, in tier order. (default: "") |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--itc` | Runs in this execution context instead of dispatching into deployment pods. |
+| `--deploy-list <deploy-list>` | A comma-separated list of deployment IDs to run the suite inside. |
+| `--grep <pattern>` | Runs only tests whose name matches the pattern. |
+| `--watch` | Keeps the runner open and re-runs affected suites on change. |
+| `--no-coverage` | Skips coverage instrumentation and reporters. |
+| `--allure` | Writes Allure results for the cluster dashboard alongside the run. |
+| `--dashboard` | Applies the Allure dashboard to the cluster and exits. |
+| `--job` | Runs the selected suite on the cluster as a Kubernetes Job (requires --image). |
+| `--image <image>` | Image carrying the engine and its dependencies, for --job. |
+| `--node-name <node-name>` | Pins the --job pod to this node. |
+| `--host <host>` | Hostname to route the --dashboard sub-path on. |
+| `--namespace <namespace>` | Kubernetes namespace for --dashboard, --job and --deploy-list. |
+| `--dry-run` | Renders the --dashboard or --job manifests without applying them. |
+| `--pod-name <pod-name>` | Waits for this cluster object to reach --pod-status instead of running tests. |
+| `--pod-status <pod-status>` | Status --pod-name waits for (default: "Running"). |
+| `--kind-type <kind-type>` | Kind --pod-name queries (default: "pods"). |
+| `-h, --help` | display help for command |
+
+---
+
 ### underpost docker-compose
 
 General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).
@@ -1185,9 +1319,9 @@ Manages baremetal server operations, including installation, database setup, com
 | `--no-remote-install` | Skips the controller-side remote install orchestration over SSH. |
 | `--worker` | Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane. |
 | `--control <ip>` | Control-plane IP the worker node joins (used with --worker for kubeadm infra setup). |
-| `--ssh-key-dir <dir>` | Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~. |
-| `--deploy-id <deploy-id>` | Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command. |
-| `--user <user>` | SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user. |
+| `--ssh-key-dir <dir>` | Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy/users/<user> for a non-root --user, otherwise engine-private/deploy. Supports a leading ~. |
+| `--deploy-id <deploy-id>` | Deployment ID used to resolve the private engine repo cloned onto the node (engine-<suffix>-private. |
+| `--user <user>` | SSH user whose cluster scoped key pair is used (engine-private/deploy/users/<user>/id_rsa) and the login user on an existing control-plane (defaults to root, whose key is engine-private/deploy/id_rsa). Mirrors the ssh command --user. |
 | `--engine-repo <url>` | Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine). |
 | `--engine-branch <branch>` | Branch of the engine repo to clone on the node. |
 | `--engine-private-repo <url>` | Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private). |
@@ -1219,6 +1353,31 @@ Manages baremetal server operations, including installation, database setup, com
 
 ---
 
+### underpost package
+
+Generates the package manifests a deploy id owns, from the engine manifest and the deploy's product catalog, and installs the dependencies that catalog pins.
+
+**Usage:** `underpost package [options] [deploy-id]`
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| `deploy-id` | Deploy id, or a comma-separated list, to act on. Defaults to every deploy id in the private configuration tree. |
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--sync` | Regenerates each deploy manifest from the engine manifest and the deploy catalog (default). |
+| `--install` | Installs the dependencies the deploy catalog pins into this checkout. |
+| `--rename <name>` | Renames this checkout's package, in its manifest and its lockfile. |
+| `--set-repo <owner/repo>` | Points this checkout's package at a repository. |
+| `--dry-run` | For --sync: resolves the manifests without writing them. |
+| `-h, --help` | display help for command |
+
+---
+
 ### underpost release
 
 Release orchestrator for building new versions and deploying releases of the Underpost CLI.