@helyx/bot 1.5.2 → 1.5.4

package/dist/shard-supervisor.js

@@ -1,15 +1,19 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InstallationRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, InteractionSessionRepository, EckoOperationsRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
-import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
-import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createPlatformServices, createPostgresCommandRestrictionRecovery, createPostgresNexusCommandRecovery, createPostgresCommandCatalogueRecovery, createPostgresCommandPolicyDelivery, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, collectReservedCommandNames, } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
 import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
+import { loadBundledCommandCatalogue } from "./command-root-catalogue.js";
+import { completeShardCommandStartup, shardStartupCatalogueReady, } from "./shard-command-startup.js";
 import { join } from "node:path";
 import pino, {} from "pino";
 import { synchroniseApplicationCommands, } from "./command-sync.js";
-import { CloudConnectorController, } from "./cloud-connector.js";
+import { CloudConnectorController } from "./cloud-connector.js";
+import { commandPolicyLeaderIsCurrent, captureShardedCommandPolicyAdmission, shardCommandPolicyScope, } from "./command-policy-runtime.js";
+import { allocateShardDeploymentOrder, prepareShardDeploymentOrder, } from "./shard-core-readiness.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, createBotControlServer, mapBotControlError, } from "./control-server.js";
 import { createManagementModule } from "./management-module.js";
@@ -131,6 +135,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let numericRegistrations = [];
     let leaderLease;
     let cloudConnector;
+    let commandPolicyRuntime;
     let cloudStarted = false;
     let maintainingLeases = false;
     let rebalancingShards = false;
@@ -164,6 +169,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let guildCommandReleasePromise;
     let scheduledModules = [];
     let commandModules = [];
+    let commandCatalogue;
     let workersRoutable = false;
     let promoteToLeader = () => Promise.resolve(false);
     try {
@@ -173,6 +179,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const featureModules = modulePackages.map(({ definition }) => definition);
         assertReviewedPremiumCatalogue(featureModules);
+        const bundledCommandCatalogue = featureModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+            ? await loadBundledCommandCatalogue()
+            : null;
+        const catalogueIdentity = bundledCommandCatalogue
+            ? {
+                revision: bundledCommandCatalogue.revision,
+                fingerprint: bundledCommandCatalogue.fingerprint,
+            }
+            : null;
         const gateway = await fetchGatewayBotInformation(environment.DISCORD_TOKEN);
         shardCount =
             environment.HELYX_SHARD_MODE === "fixed"
@@ -301,11 +316,57 @@ export async function startShardSupervisor(environment, processEnvironment, work
             listAvailabilityModules: () => availabilityCatalogue(availabilityModules, statusModules, runtimeAvailability),
         };
         const initialiseLeader = async () => {
-            await runLeaderStartup(database, environment, modulePackages, modules, logger);
+            let commandPolicyAdmission;
+            let policyLeader;
+            let policyOwnerCurrent;
+            await runLeaderStartup(database, environment, modulePackages, modules, logger, {
+                catalogue: catalogueIdentity,
+                assertOwnership: assertStartupLeaseHealthy,
+                captureCommandPolicy: async () => {
+                    if (environment.HELYX_RUNTIME_PROFILE !== "self-hosted")
+                        return;
+                    const leader = leaderLease;
+                    if (!leader)
+                        throw new Error("Command policy requires the current shard leader");
+                    const delivery = createPostgresCommandPolicyDelivery(database, {
+                        applicationId: environment.DISCORD_CLIENT_ID,
+                        scope: shardCommandPolicyScope(generation, deploymentOrder),
+                    });
+                    policyLeader = leader;
+                    policyOwnerCurrent = coordinator
+                        ? () => withTimeout(commandPolicyLeaderIsCurrent({
+                            coordinator: coordinator,
+                            descriptor: generationDescriptor,
+                            deploymentOrder,
+                            leader,
+                        }), LEASE_VALIDATION_TIMEOUT_MS)
+                        : () => Promise.resolve(true);
+                    commandPolicyAdmission = await captureShardedCommandPolicyAdmission(delivery, leader.supervisorId);
+                },
+                prepareCommandPolicy: async () => {
+                    if (environment.HELYX_RUNTIME_PROFILE !== "self-hosted")
+                        return;
+                    if (!commandPolicyAdmission || !policyLeader || !policyOwnerCurrent)
+                        throw new Error("Command policy admission was not captured at database readiness");
+                    commandPolicyRuntime = await commandPolicyAdmission.claim(String(policyLeader.fencingToken), policyOwnerCurrent);
+                    await cloudConnector?.setCommandPolicyDelivery(commandPolicyRuntime);
+                },
+                publishCatalogue: async () => {
+                    if (!bundledCommandCatalogue)
+                        return;
+                    commandCatalogue = createPostgresCommandCatalogueRecovery(database, environment.DISCORD_CLIENT_ID);
+                    await commandCatalogue.publish(bundledCommandCatalogue);
+                },
+            });
             assertStartupLeaseHealthy();
             privacyDatabase = await createPrivacyDatabase(environment, database);
             assertStartupLeaseHealthy();
-            const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
+            const services = new Map(createPlatformServices(database, publicModules, {
+                ...platformServiceOptions(environment, publicModules),
+                ...(commandPolicyRuntime
+                    ? { commandPolicyDeliveryScope: commandPolicyRuntime.owner.scope }
+                    : {}),
+            }));
             runtimeAvailability = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
             leaderScannerRegistry = new BotAutoModerationScannerRegistry(publicModules, new ServiceRegistry(services), "hosted", undefined, environment.HELYX_DEPLOYMENT_ENVIRONMENT);
             if (numericWriteBehind)
@@ -350,9 +411,9 @@ export async function startShardSupervisor(environment, processEnvironment, work
             environment: environment.NODE_ENV,
             generation,
             shardCount,
-            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID, environment.HELYX_GLOBAL_COMMAND_MODE),
+            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID, environment.HELYX_GLOBAL_COMMAND_MODE, bundledCommandCatalogue?.fingerprint),
         };
-        deploymentOrder = await nextShardDeploymentOrder(database);
+        deploymentOrder = await prepareShardDeploymentOrder(database, environment.HELYX_DATABASE_STARTUP_MODE);
         if (environment.HELYX_SHARD_SCOPE === "coordinated") {
             coordinator = new RedisShardCoordinator(environment.HELYX_SHARD_REDIS_URL, environment.HELYX_SHARD_REDIS_NAMESPACE, {
                 onError: (error) => logger.error({ event: "shard.redis_error", error: safeError(error) }, "Shard coordination failed"),
@@ -417,7 +478,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             await initialiseLeader();
         }
         else {
-            await waitForLeaderStartup(database, generation);
+            await waitForLeaderStartup(database, generation, catalogueIdentity);
             assertStartupLeaseHealthy();
         }
         const router = new ShardControlRouter({
@@ -484,6 +545,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 : undefined;
             controlServer = await createBotControlServer({
                 service: router,
+                ...(commandModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                    ? {
+                        nexusCommandRecovery: createPostgresNexusCommandRecovery(database, {
+                            applicationId: environment.DISCORD_CLIENT_ID,
+                            persistedCommandCatalogue: true,
+                            reservedCommandNames: collectReservedCommandNames(commandModules),
+                        }),
+                    }
+                    : {}),
                 secret: environment.HELYX_BOT_CONTROL_SECRET,
                 ...shardHostedControlCallbacks(router),
                 logger: { level: environment.LOG_LEVEL },
@@ -1218,6 +1288,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
         }
         if (!guildCommandWorker) {
             guildCommandWorker = new GuildCommandWorker({
+                ...(commandPolicyRuntime
+                    ? { commandPolicyDelivery: commandPolicyRuntime.delivery }
+                    : {}),
+                ...(commandCatalogue ? { commandCatalogue } : {}),
+                ...(commandModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                    ? {
+                        commandRestrictions: createPostgresCommandRestrictionRecovery(database, environment.DISCORD_CLIENT_ID),
+                    }
+                    : {}),
                 database,
                 modules: commandModules,
                 logger,
@@ -1540,7 +1619,10 @@ export function splitNumericCommittedBatch(batch, index) {
         results: [result],
     };
 }
-async function runLeaderStartup(database, environment, modulePackages, modules, logger) {
+async function runLeaderStartup(database, environment, modulePackages, modules, logger, commandStartup) {
+    // Core readiness and durable order were established before election. Capture
+    // admission before any further migration/owner startup can wait asynchronously.
+    await commandStartup.captureCommandPolicy();
     const moduleMigrationSources = modulePackages.map(({ definition, packageRoot }) => ({
         moduleId: definition.manifest.id,
         moduleVersion: definition.manifest.version,
@@ -1566,23 +1648,36 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
         await runCoreMigrations(database);
         await runConfiguredModuleMigrations(database, moduleMigrationSources);
     }
+    await commandStartup.prepareCommandPolicy();
     await enforcePremiumCatalogue(database, logger);
     const repository = new RuntimeStateRepository(database);
-    await synchroniseApplicationCommands({
-        applicationId: environment.DISCORD_CLIENT_ID,
-        token: environment.DISCORD_TOKEN,
-        modules,
-        globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
-        ...(environment.DISCORD_INTERNAL_GUILD_ID
-            ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
-            : {}),
-        // Worker-owned guild collections stay untouched while command writes are off.
-        synchroniseInternalGuild: false,
-        state: new RuntimeCommandHashStore(repository),
-    });
-    await setRuntimeState(repository, `shards:${environment.HELYX_SHARD_GENERATION ?? "local"}:startup`, {
-        ready: true,
-        completedAt: new Date().toISOString(),
+    await completeShardCommandStartup({
+        assertOwnership: () => commandStartup.assertOwnership(),
+        publishCatalogue: () => commandStartup.publishCatalogue(),
+        synchronise: async () => {
+            await synchroniseApplicationCommands({
+                applicationId: environment.DISCORD_CLIENT_ID,
+                token: environment.DISCORD_TOKEN,
+                modules,
+                globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                // Worker-owned guild collections stay untouched while command writes are off.
+                synchroniseInternalGuild: false,
+                state: new RuntimeCommandHashStore(repository),
+            });
+        },
+        markReady: () => setRuntimeState(repository, `shards:${environment.HELYX_SHARD_GENERATION ?? "local"}:startup`, {
+            ready: true,
+            completedAt: new Date().toISOString(),
+            commandCatalogue: commandStartup.catalogue
+                ? {
+                    revision: commandStartup.catalogue.revision,
+                    fingerprint: commandStartup.catalogue.fingerprint,
+                }
+                : null,
+        }),
     });
     logger.info({ event: "shard.singleton_startup_complete" }, "Shard singleton startup complete");
 }
@@ -1619,15 +1714,12 @@ async function setRuntimeState(repository, key, value) {
     if (!updated)
         throw new Error("Runtime state changed concurrently");
 }
-async function waitForLeaderStartup(database, generation) {
+async function waitForLeaderStartup(database, generation, catalogue) {
     const deadline = Date.now() + STARTUP_WAIT_MS;
     while (Date.now() < deadline) {
         try {
             const state = await new RuntimeStateRepository(database).get(`shards:${generation}:startup`);
-            if (typeof state?.value === "object" &&
-                state.value !== null &&
-                !Array.isArray(state.value) &&
-                state.value.ready === true)
+            if (shardStartupCatalogueReady(state?.value, catalogue))
                 return;
         }
         catch {
@@ -1741,11 +1833,12 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         HELYX_SHARD_RESTART_COUNT: String(restartCount),
     };
 }
-export function shardRuntimeCompositionHash(modules, internalGuildId, globalCommandMode = "legacy") {
+export function shardRuntimeCompositionHash(modules, internalGuildId, globalCommandMode = "legacy", commandCatalogueFingerprint) {
     const commands = buildApplicationCommandDefinitions(modules, internalGuildId, globalCommandMode);
     return createHash("sha256")
         .update(JSON.stringify({
         botVersion: botVersion(),
+        ...(commandCatalogueFingerprint ? { commandCatalogueFingerprint } : {}),
         modules: modules
             .map(({ manifest }) => ({
             id: manifest.id,
@@ -1990,19 +2083,7 @@ function sameShardLease(left, right) {
         left.fencingToken === right.fencingToken);
 }
 export async function nextShardDeploymentOrder(database) {
-    let value;
-    try {
-        value = await new RuntimeStateRepository(database).nextShardDeploymentOrder();
-    }
-    catch (error) {
-        if (error.code !== "42P01")
-            throw error;
-        return 1;
-    }
-    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
-        throw new Error("Shard deployment order exceeds the safe runtime range");
-    }
-    return Number(value);
+    return allocateShardDeploymentOrder(database);
 }
 export async function renewStartupOwnership(coordinator, descriptor, deploymentOrder, leaderLease) {
     if (!(await coordinator.refreshGeneration(descriptor, deploymentOrder)))

package/dist/shard-worker.js

@@ -1,4 +1,5 @@
 import { parseBotEnvironment } from "@helyx/config";
+import { shardCommandPolicyScope } from "./command-policy-runtime.js";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, InstallationRepository, } from "@helyx/database";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
@@ -264,6 +265,11 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const serviceOptions = platformServiceOptions(environment, publicModules);
         for (const [name, service] of createPlatformServices(database, publicModules, {
             ...serviceOptions,
+            ...(environment.HELYX_RUNTIME_PROFILE === "self-hosted"
+                ? {
+                    commandPolicyDeliveryScope: shardCommandPolicyScope(identity.generation, identity.deploymentOrder),
+                }
+                : {}),
             recordRecoveryOwnership: {
                 mode: "shard",
                 shardId: identity.shardId,
@@ -391,21 +397,24 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 shardCount: identity.shardCount,
             })
             : undefined;
-        const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
-            ...(environment.DISCORD_INTERNAL_GUILD_ID
-                ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
-                : {}),
-            prepare: prepareGuilds,
-            ...(operationsModule
-                ? { operationsModuleId: operationsModule.manifest.id }
-                : {}),
-            supportModuleId: supportModule.manifest.id,
-            diagnosticModuleId: diagnosticModule.manifest.id,
-            ...(premiumActivationModule
-                ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
-                : {}),
-            ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
-        }), logger, serviceAccess);
+        const commandsReady = installInteractions(client, modules, {
+            ...shardWorkerCommandRegistration({
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                prepare: prepareGuilds,
+                ...(operationsModule
+                    ? { operationsModuleId: operationsModule.manifest.id }
+                    : {}),
+                supportModuleId: supportModule.manifest.id,
+                diagnosticModuleId: diagnosticModule.manifest.id,
+                ...(premiumActivationModule
+                    ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
+                    : {}),
+                ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
+            }),
+            resolveGuildCommandName: (input) => guildCommandReads.resolveInteractionCommand(input),
+        }, logger, serviceAccess);
         moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess, {
             runtimeProfile: environment.HELYX_RUNTIME_PROFILE,
             evidenceStore: moderationPlatformServices.evidenceStore,
@@ -669,6 +678,7 @@ async function handleControl(identity, service, hostedOwnerObserver, client, hos
                 ok: false,
                 status: mapped?.status ?? 500,
                 message: mapped?.message ?? "The owning shard rejected the request",
+                ...(mapped?.fieldError ? { fieldError: mapped.fieldError } : {}),
             };
         }
     }

package/documentation/README.md

@@ -13,6 +13,7 @@ and module guides.
 
 - [Install a self-hosted Helyx instance](guides/getting-started.md)
 - [Understand the self-hosting boundary](guides/self-hosting.md)
+- [Understand upcoming shared Nexus command names](guides/self-hosting.md#nexus-command-names-upcoming)
 - [Configure the environment](reference/environment.md)
 - [Operate installations and upgrades](runbooks/installation-and-upgrades.md)
 - [Plan backup and recovery](runbooks/backup-and-recovery.md)

package/documentation/examples/.env.example

@@ -9,16 +9,6 @@ DISCORD_CLIENT_ID=12345678901234567
 # Explicit privileged gateway opt-in. Keep false unless a reviewed loaded module
 # requires message content and it is enabled in the Discord developer portal.
 HELYX_MESSAGE_CONTENT_ENABLED=false
-# Enhanced Auto Moderation stays inside this bot process. One worker is the
-# recommended default (range 1-4); increase only after measuring CPU and memory.
-# Hosted scanning uses the separate Helyx Ecko service, not these settings.
-HELYX_AUTOMOD_EMBEDDED_WORKERS=1
-# Optional conservative queue overrides (hard ceilings: 5000 items, 64 MiB,
-# 100 items per server). Defaults are used when these remain commented.
-# HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS=5000
-# HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES=67108864
-# HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD=100
-# HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS=300
 # Enable for loaded member workflows such as Welcome, Access Control or Levels,
 # with Server Members Intent also enabled in the Discord developer portal.
 HELYX_GUILD_MEMBERS_ENABLED=false
@@ -51,10 +41,6 @@ HELYX_CLOUD_CONNECT_ENABLED=true
 # trace, debug, info, warn, error, fatal or silent
 LOG_LEVEL=info
 
-# Guild-scoped development commands only
-# DISCORD_INTERNAL_GUILD_ID=12345678901234567
-# APPROVED_ROLES=12345678901234567,12345678901234568
-
 # SHARDING: OFF BY DEFAULT
 
 # `off` is the compatible self-host default. Keep shard-only values commented
@@ -80,12 +66,6 @@ HELYX_SHARD_MODE=off
 # Additional reviewed module packages
 # HELYX_MODULE_PACKAGES=
 
-# Private dashboard control endpoint — configure both together
-# HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
-# HELYX_BOT_CONTROL_PORT=3001
-# HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS=900
-HELYX_HOSTED_MODERATION_ENABLED=false
-
 # Guild command writes remain off until explicitly enabled for known guild IDs.
 # For enabled-module server commands, set writes=true, retain allowlist scope,
 # add comma-separated Discord server IDs below, and use global mode platform-only.
@@ -96,14 +76,6 @@ HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
 HELYX_GLOBAL_COMMAND_MODE=legacy
 # HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=
 
-# Alternative Cloud Connect enrolment — the Discord command is preferred
-# HELYX_CLOUD_ENROLMENT_TOKEN=replace-with-a-short-lived-enrolment-code
-# HELYX_CLOUD_ENROLMENT_FILE=./helyx.cloud-enrolment.json
-
-# Hosted OAuth bridge. Keep disabled unless the API and bot share this secret.
-HELYX_OAUTH_ENABLED=false
-# HELYX_OAUTH_INTERNAL_SECRET=replace-with-a-base64-encoded-32-byte-key
-
 # DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT
 
 # Generated module selection
@@ -113,22 +85,5 @@ HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
 # and Invite Tracking; retain it unchanged across restarts and deployments.
 # HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
 
-# Official Cloud Connect endpoints
-# HELYX_CLOUD_API_URL=https://api.helyx.gg
-# HELYX_CLOUD_ENDPOINT=wss://connect.helyx.gg/v1/connect
-
-# Security audit retention
-# HELYX_CLOUD_AUDIT_RETENTION_DAYS=90
-# HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS=365
-
-# Optional public status reporting. Keep disabled unless this installation has
-# its own approved Helyx status credentials.
-HELYX_STATUS_ENABLED=false
-# HELYX_STATUS_URL=https://status.helyx.gg
-# HELYX_STATUS_HEARTBEAT_SECRET=replace-with-a-base64-encoded-32-byte-key
-# HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS=60
-# CF_ACCESS_CLIENT_ID=replace-with-access-client-id
-# CF_ACCESS_CLIENT_SECRET=replace-with-access-client-secret
-
 # Runtime mode
 NODE_ENV=production

package/documentation/guides/self-hosting.md

@@ -95,6 +95,60 @@ features continue if the hosted dashboard is temporarily unavailable.
 Set `HELYX_CLOUD_CONNECT_ENABLED=false` before startup when the installation
 must remain entirely local.
 
+## Nexus command names (upcoming)
+
+Nexus Rewards and Nexus Economy keep `/nexus` as their default command in this
+guide. Custom command naming is an upcoming feature, held until the current name
+policy is configured and controlled acceptance is complete. Having a compatible
+package or enabling Cloud Connect does not activate it.
+
+The shared Nexus settings own one command name per Discord server. When offered
+by an approved release, the same **Slash command name** will appear under either
+**Modules > Nexus Rewards > Settings** or **Modules > Nexus Economy > Settings**.
+Changing currency terminology does not change that command. A new root uses
+1-10 lowercase ASCII letters, digits, hyphens or underscores, excluding `/`, and
+must pass the current restricted-word and full command-reservation checks.
+Reservations include commands from disabled modules.
+
+In a supporting Self-Hosted release, Cloud Connect must verify the current
+centrally managed name policy before a new custom name can be accepted. An
+unpaired, disconnected or unsupported connection holds custom-name changes;
+reconnection checks the latest policy before making them available again. A
+previously stored list alone does not establish current verification. Existing
+confirmed commands and ordinary Nexus settings remain usable. **Restore nexus**
+can stage the default name while custom-name editing is held, subject to the
+same confirmation, cooldown and unresolved-update checks described below.
+
+A changed-name save requires **Confirm** or **Cancel**. Cancel, Escape or closing
+the dialog restores only the root draft without saving the other fields.
+Confirmation warns about the rolling 24-hour restriction, including a return to
+`nexus`, and Discord command permission overrides which must be reapplied after
+the update. Invalid/rejected requests create no future rename queue. Ordinary
+settings saves, unchanged names and delivery retries do not extend the timer.
+
+An accepted setting and a confirmed Discord command are different states. While
+an update is pending or failed, use the previously confirmed command in Discord;
+another customer rename remains blocked until the update is resolved, even after
+the timer expires. If no Nexus commands are enabled, a selected name can remain
+saved without an active slash command. Once a custom name is confirmed, replace
+only `/nexus` in examples: a confirmed `coins` root makes `/nexus balance` become
+`/coins balance`, with the same subcommands and access rules.
+
+A new reserved command or restricted-list update can select `nexus` again without
+extending the existing expiry or changing unrelated settings. Check the reset's
+pending/confirmed state and reapply Discord command permission overrides after
+the update.
+
+Private command-history inspection, timer reset and rename override by Helyx staff
+are a Hosted-only support path. Remote Self-Hosted and Cloud-connected
+installations do not have that recovery capability. Keep custom-name activation
+held when the required policy or recovery path is unavailable; do not bypass it
+by changing stored records or registering a competing command manually. Check
+your release, `npm run doctor`, module health and the current Discord command
+picker, then use the supported [privacy and support routes](privacy-and-support.md)
+without sharing credentials. Hosted dashboard workflow details are in the
+[shared Nexus Settings guide](https://docs.helyx.gg/modules/nexus-rewards/settings/).
+
 ## Before production use
 
 1. Prove `npm run doctor` from the production environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -30,6 +30,7 @@
   "type": "module",
   "files": [
     "dist",
+    "command-root-catalogue.json",
     "!dist/*.tsbuildinfo",
     "!dist/**/*.map",
     "documentation",
@@ -50,31 +51,31 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=1.4.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.8.0 <0.9.0",
+    "@helyx/config": ">=1.6.0 <2.0.0",
+    "@helyx/control-protocol": ">=0.9.0 <0.10.0",
     "@helyx/core": ">=0.2.0 <0.3.0",
-    "@helyx/database": ">=2.4.1 <3.0.0",
-    "@helyx/database-contracts": ">=0.2.0 <0.3.0",
+    "@helyx/database": ">=2.5.0 <3.0.0",
+    "@helyx/database-contracts": ">=0.3.0 <0.4.0",
     "@helyx/framework": ">=0.2.0 <0.3.0",
-    "@helyx/module-manifest": ">=0.13.0 <0.14.0",
+    "@helyx/module-manifest": ">=0.14.0 <0.15.0",
     "@helyx/platform": ">=1.3.0 <2.0.0",
-    "@helyx/sdk": ">=0.16.0 <0.17.0",
+    "@helyx/sdk": ">=0.17.0 <0.18.0",
     "@helyx/status-client": ">=0.3.0 <0.4.0",
-    "@helyx/verification-contracts": ">=0.4.0 <0.5.0",
+    "@helyx/verification-contracts": ">=0.5.0 <0.6.0",
     "discord.js": "14.27.0",
     "fastify": "5.12.7",
-    "pino": "10.3.1",
-    "redis": "6.1.0",
-    "undici": "6.29.0",
-    "ws": "8.21.1",
-    "zod": "4.4.3"
+    "pino": "10.4.0",
+    "redis": "6.3.0",
+    "undici": "6.29.1",
+    "ws": "8.22.0",
+    "zod": "4.6.7"
   },
   "optionalDependencies": {
-    "@helyx/database-mysql": ">=0.2.1 <0.3.0"
+    "@helyx/database-mysql": ">=0.3.0 <0.4.0"
   },
   "peerDependencies": {
-    "@helyx/module-automod": ">=1.1.1 <2.0.0",
-    "@helyx/module-moderation": ">=1.1.1 <2.0.0"
+    "@helyx/module-automod": ">=1.1.2 <2.0.0",
+    "@helyx/module-moderation": ">=1.1.2 <2.0.0"
   },
   "peerDependenciesMeta": {
     "@helyx/module-automod": {
@@ -85,6 +86,6 @@
     }
   },
   "devDependencies": {
-    "@types/ws": "8.18.1"
+    "@types/ws": "8.18.2"
   }
 }