@helyx/bot 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.6.0
+
+### Minor Changes
+
+- Add public `/proc` process information for hosted and self-hosted bots, replacing
+  the private `/dev proc` path. Keep the reply private and independent of database
+  availability.
+
+  Add a PebbleHost starter profile with direct Node CLI scripts, flat starter ZIPs,
+  compact quoted environment examples and matching guided environment builder
+  output. Preserve existing custom settings and encryption keys when rebuilding
+  an environment file, and recognize quoted placeholders during setup.
+
+## 1.5.4
+
+### Patch Changes
+
+- Remove unused internal development, status reporting, OAuth, private control,
+  advanced Cloud Connect and Auto Moderation tuning examples from the self-host
+  environment template and portable documentation. The environment builder also
+  omits these examples from older templates while preserving existing active
+  custom settings. Keep Discord intent settings, basic Cloud Connect and data
+  encryption configuration; runtime defaults and scanning behavior are unchanged.
+
 ## 1.5.3
 
 ### Patch Changes

package/README.md

@@ -164,8 +164,11 @@ paths are read-only:
 
 - `/dev shards` reports bounded shard health, including the unsharded
   compatibility baseline;
-- `/dev bot` reports the bot build and bounded installed-module versions;
-- `/dev proc` reports safe metrics for the process handling the command.
+- `/dev bot` reports the bot build and bounded installed-module versions.
+
+The public `/proc` command reports the same safe process metrics on hosted and
+self-hosted bots, in a server or bot DM. Anyone can run it; replies are ephemeral.
+It works independently of database and module enablement checks.
 
 On the official hosted bot only,
 `HELYX_HOSTED_MODERATION_ENABLED=true` adds `/dev leave` and `/dev blacklist`.

package/command-root-catalogue.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "revision": 2,
+  "revision": 3,
   "roots": [
     { "name": "access", "type": 1, "ownerModuleId": "helyx.account-gate" },
     { "name": "access", "type": 1, "ownerModuleId": "helyx.verification" },
@@ -26,6 +26,7 @@
     { "name": "mod", "type": 1, "ownerModuleId": "helyx.moderation" },
     { "name": "nexus", "type": 1, "ownerModuleId": "helyx.nexus-core" },
     { "name": "poll", "type": 1, "ownerModuleId": "helyx.polls" },
+    { "name": "proc", "type": 1, "ownerModuleId": "helyx.process-info" },
     { "name": "profile", "type": 1, "ownerModuleId": "helyx.achievements" },
     { "name": "profile", "type": 1, "ownerModuleId": "helyx.levels" },
     { "name": "submit", "type": 1, "ownerModuleId": "helyx.feedback" },
@@ -96,6 +97,13 @@
         "sourcePath": "apps/bot/src/privacy-module.ts",
         "version": "0.1.0"
       },
+      {
+        "commands": ["proc"],
+        "moduleId": "helyx.process-info",
+        "releaseStatus": "live",
+        "sourcePath": "apps/bot/src/process-info-module.ts",
+        "version": "0.1.0"
+      },
       {
         "commands": ["helyx.bug"],
         "moduleId": "helyx.support",
@@ -448,5 +456,5 @@
       }
     ]
   },
-  "fingerprint": "a33abb53dd9862ee73e43515eae7fa049cd62e8c170473f82bd268878621d55e"
+  "fingerprint": "70fb5cb9554c8fdb723ff8139a9e1b0ae2128d256b12a6146d5674c63774c42a"
 }

package/dist/command-registration-policy.js

@@ -6,6 +6,7 @@ const platformGlobalModuleIds = new Set([
     "helyx.oauth",
     "helyx.permissions",
     "helyx.privacy",
+    "helyx.process-info",
     "helyx.premium-activation",
 ]);
 const deploymentModuleIds = new Set(["helyx.cloud-connect"]);

package/dist/developer-operations-module.js

@@ -27,7 +27,6 @@ export function createDeveloperOperationsModule(input) {
                 "dev.shards",
                 "dev.bot",
                 "dev.modules",
-                "dev.proc",
                 "dev.trivia-data",
                 "dev.leave",
                 "dev.blacklist",
@@ -166,41 +165,6 @@ export function createDeveloperOperationsModule(input) {
                                 });
                             },
                         },
-                        {
-                            name: "proc",
-                            permissionId: "dev.proc",
-                            description: "Show safe process resource and uptime information",
-                            acknowledgement: "immediate-response",
-                            authorization: "self-authorized",
-                            async execute(context) {
-                                if (!(await authorizeDeveloperCommand(context)))
-                                    return;
-                                const memory = process.memoryUsage();
-                                const cpu = process.cpuUsage();
-                                await context.reply({
-                                    ephemeral: true,
-                                    componentsV2: {
-                                        accentColor: 0x2563eb,
-                                        text: [
-                                            {
-                                                content: [
-                                                    "## Process information",
-                                                    `Runtime: ${input.processLabel}`,
-                                                    `Uptime: ${formatDuration(process.uptime())}`,
-                                                    `RSS memory: ${formatBytes(memory.rss)}`,
-                                                    `Heap: ${formatBytes(memory.heapUsed)} used / ${formatBytes(memory.heapTotal)} allocated`,
-                                                    `External memory: ${formatBytes(memory.external)}`,
-                                                    `CPU time: ${formatCpu(cpu.user)} user / ${formatCpu(cpu.system)} system`,
-                                                    `Node: ${safeInlineCode(process.version)}`,
-                                                    `Platform: ${safeInlineCode(`${process.platform}/${process.arch}`)}`,
-                                                    `PID: ${process.pid}`,
-                                                ].join("\n"),
-                                            },
-                                        ],
-                                    },
-                                });
-                            },
-                        },
                         {
                             name: "trivia-data",
                             permissionId: "dev.trivia-data",
@@ -411,25 +375,6 @@ function categoryLabel(category) {
         .join(" ")
         .replace("And", "and");
 }
-function formatBytes(value) {
-    return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
-}
-function formatCpu(microseconds) {
-    return `${(microseconds / 1_000_000).toFixed(2)}s`;
-}
-function formatDuration(seconds) {
-    const total = Math.max(0, Math.floor(seconds));
-    const days = Math.floor(total / 86_400);
-    const hours = Math.floor((total % 86_400) / 3_600);
-    const minutes = Math.floor((total % 3_600) / 60);
-    const remainder = total % 60;
-    return [
-        ...(days > 0 ? [`${days}d`] : []),
-        ...(days > 0 || hours > 0 ? [`${hours}h`] : []),
-        `${minutes}m`,
-        `${remainder}s`,
-    ].join(" ");
-}
 export class WorkerShardHealthProvider {
     #pending = new Map();
     getHealth() {

package/dist/diagnostic-command.js

@@ -22,6 +22,7 @@ const CORE_MODULE_IDS = new Set([
     "helyx.support",
     "helyx.oauth",
     "helyx.privacy",
+    "helyx.process-info",
     "helyx.cloud-connect",
     "helyx.premium-activation",
     "helyx.developer-operations",

package/dist/discord-guild-health.js

@@ -8,6 +8,7 @@ const INTERNAL_HELYX_MODULE_IDS = new Set([
     "helyx.management",
     "helyx.permissions",
     "helyx.support",
+    "helyx.process-info",
 ]);
 export function moduleCatalogueMatches(packagedManifest, executableManifest) {
     return (packagedManifest !== null &&

package/dist/index.js

@@ -35,6 +35,7 @@ import { shardHealthSnapshotSchema, } from "./shard-contracts.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
 import { installModerationPlatformServices } from "./moderation-platform-services.js";
 import { EckoEvidenceReceiver } from "./ecko-evidence-receiver.js";
 import { EckoTransportAuthenticator } from "./ecko-transport-auth.js";
@@ -361,6 +362,7 @@ async function startUnshardedBot(processEnvironment) {
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule("unsharded bot process");
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment || !database
             ? undefined
@@ -380,6 +382,7 @@ async function startUnshardedBot(processEnvironment) {
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -458,6 +461,7 @@ async function startUnshardedBot(processEnvironment) {
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/process-info-module.d.ts

@@ -0,0 +1,3 @@
+/** Local process metrics remain available without database or installation checks. */
+export declare function createProcessInfoModule(processLabel: string): import("@helyx/sdk").ModuleDefinition;
+//# sourceMappingURL=process-info-module.d.ts.map

package/dist/process-info-module.js

@@ -0,0 +1,97 @@
+import { defineModule } from "@helyx/sdk";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
+const everyonePolicy = {
+    everyone: true,
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+/** Local process metrics remain available without database or installation checks. */
+export function createProcessInfoModule(processLabel) {
+    return defineModule({
+        manifest: {
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
+            releaseStatus: "live",
+            id: "helyx.process-info",
+            name: "Helyx Process Information",
+            version: "0.1.0",
+            description: "Reports safe resource and uptime information for the running bot.",
+            entry: "./dist/process-info-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["proc"], events: [] },
+        },
+        defaultPermissions: {
+            module: everyonePolicy,
+            commands: { proc: everyonePolicy },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "proc",
+                    permissionId: "proc",
+                    description: "Show safe process resource and uptime information",
+                    acknowledgement: "immediate-response",
+                    registrationPolicy: "platform-global",
+                    contexts: ["guild", "bot_dm"],
+                    integrationTypes: ["guild_install"],
+                    authorization: "public",
+                    async execute(context) {
+                        const memory = process.memoryUsage();
+                        const cpu = process.cpuUsage();
+                        await context.reply({
+                            ephemeral: true,
+                            componentsV2: {
+                                accentColor: 0x2563eb,
+                                text: [
+                                    {
+                                        content: [
+                                            "## Process information",
+                                            `Runtime: ${processLabel}`,
+                                            `Uptime: ${formatDuration(process.uptime())}`,
+                                            `RSS memory: ${formatBytes(memory.rss)}`,
+                                            `Heap: ${formatBytes(memory.heapUsed)} used / ${formatBytes(memory.heapTotal)} allocated`,
+                                            `External memory: ${formatBytes(memory.external)}`,
+                                            `CPU time: ${formatCpu(cpu.user)} user / ${formatCpu(cpu.system)} system`,
+                                            `Node: ${safeInlineCode(process.version)}`,
+                                            `Platform: ${safeInlineCode(`${process.platform}/${process.arch}`)}`,
+                                            `PID: ${process.pid}`,
+                                        ].join("\n"),
+                                    },
+                                ],
+                            },
+                        });
+                    },
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    });
+}
+function safeInlineCode(value) {
+    return `\`${value.replaceAll("`", "'").slice(0, 120)}\``;
+}
+function formatBytes(value) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
+}
+function formatCpu(microseconds) {
+    return `${(microseconds / 1_000_000).toFixed(2)}s`;
+}
+function formatDuration(seconds) {
+    const total = Math.max(0, Math.floor(seconds));
+    const days = Math.floor(total / 86_400);
+    const hours = Math.floor((total % 86_400) / 3_600);
+    const minutes = Math.floor((total % 3_600) / 60);
+    const remainder = total % 60;
+    return [
+        ...(days > 0 ? [`${days}d`] : []),
+        ...(days > 0 || hours > 0 ? [`${hours}h`] : []),
+        `${minutes}m`,
+        `${remainder}s`,
+    ].join(" ");
+}
+//# sourceMappingURL=process-info-module.js.map

package/dist/shard-supervisor.js

@@ -36,6 +36,7 @@ import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createPremiumActivationModule } from "./premium-activation-module.js";
 import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
@@ -248,6 +249,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule("shard supervisor");
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -267,6 +269,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -291,6 +294,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/shard-worker.js

@@ -44,6 +44,7 @@ import { HostedBotInviteGateClient, HostedServerLeaveWorker, HostedServerModerat
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
 import { HttpOAuthService } from "./oauth-service.js";
 import { createLocalScheduledTaskRoute, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
@@ -202,6 +203,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             : undefined;
         const supportModule = createSupportModule(cloudProxy);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule(`shard worker ${identity.shardId}`);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -221,6 +223,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -244,6 +247,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/documentation/examples/.env.example

@@ -1,134 +1,33 @@
-# REQUIRED — EDIT THESE VALUES
+# Helyx self-hosted environment
+# Keep this file private. Retain the encryption key when updating.
 
-HELYX_RUNTIME_PROFILE=self-hosted
-HELYX_DEPLOYMENT_ENVIRONMENT=self-hosted
+# Runtime
+HELYX_RUNTIME_PROFILE='self-hosted'
+HELYX_DEPLOYMENT_ENVIRONMENT='self-hosted'
+NODE_ENV='production'
 
 # Discord
-DISCORD_TOKEN=replace-me
-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
-# Database
-# Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.
-DATABASE_ENGINE=postgresql
-DATABASE_URL=postgresql://database:5432/helyx
-DATABASE_SSL=disable
-# Self-host startup applies pending migrations automatically (the default).
-# Hosted-only inspect mode is not a self-host setting; leave this commented.
-# HELYX_DATABASE_STARTUP_MODE=apply
-# Match your provider: disable=no TLS; require=TLS without certificate
-# verification; verify-full=TLS with certificate verification.
-
-# Included Docker database — both password values must match.
-PGUSER=helyx
-PGPASSWORD=replace-with-a-strong-password
-POSTGRES_DB=helyx
-POSTGRES_USER=helyx
-POSTGRES_PASSWORD=replace-with-a-strong-password
-
-# OPTIONAL EVERYDAY SETTINGS
-
-# Ready for dashboard linking, but remains unpaired until you use a one-use code.
-HELYX_CLOUD_CONNECT_ENABLED=true
-# Public dashboard origin used in bot-generated report links.
-# HELYX_DASHBOARD_PUBLIC_URL=https://app.helyx.gg
-# HELYX_OWNER_USER_IDS=12345678901234567
-
-# 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
-# in this mode; an empty value is still rejected as configured. MySQL must stay
-# off. Advanced PostgreSQL self-hosting may use `auto` under one
-# supervisor, or `fixed` with a deliberate total count. Local mode never needs
-# Redis. Coordinated multi-host self-hosting is outside the first release.
-HELYX_SHARD_MODE=off
-# HELYX_SHARD_SCOPE=local
-# HELYX_SHARD_COUNT=2
-# HELYX_SHARD_WORKERS_PER_REPLICA=2
-# HELYX_SHARD_REDIS_URL=rediss://private-redis.example:6379
-# HELYX_SHARD_REDIS_NAMESPACE=helyx.self-host
-# HELYX_SHARD_GENERATION=local-20260728
-# HELYX_SHARD_DATABASE_CONNECTION_BUDGET=10
-# HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX=2
-# HELYX_SHARD_WORKER_DATABASE_POOL_MAX=4
-# Redis URL and namespace are intentionally unsupported for the first
-# self-hosted release: do not uncomment them for local auto or fixed mode.
-
-# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
-
-# 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
+DISCORD_CLIENT_ID='12345678901234567'
+DISCORD_TOKEN='replace-me'
+HELYX_GUILD_MEMBERS_ENABLED='false'
+HELYX_MESSAGE_CONTENT_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.
-# See README.md before changing these defaults. Legacy mode still allows globals.
-HELYX_GUILD_COMMAND_WRITES_ENABLED=false
-HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
-# HELYX_GUILD_COMMAND_RELEASE_ID=
-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
-HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
-
-# Generated privately by npm run setup. Required by Cloud Connect, Giveaways,
-# 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
+# Database
+DATABASE_ENGINE='postgresql'
+DATABASE_URL='postgresql://database:5432/helyx'
+DATABASE_SSL='disable'
+
+# Commands
+HELYX_GUILD_COMMAND_WRITES_ENABLED='true'
+HELYX_GUILD_COMMAND_WRITE_SCOPE='allowlist'
+HELYX_GLOBAL_COMMAND_MODE='platform-only'
+HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=''
+
+# Modules and dashboard
+HELYX_MODULE_CATALOGUE_PATH='./helyx.modules.json'
+HELYX_CLOUD_CONNECT_ENABLED='true'
+HELYX_SHARD_MODE='off'
+LOG_LEVEL='info'
+
+# Keep this key unchanged across restarts and updates
+HELYX_DATA_ENCRYPTION_KEY='replace-with-a-base64-encoded-32-byte-key'

package/documentation/reference/environment.md

@@ -4,7 +4,7 @@ Start from [the published example](../examples/.env.example). The example is a
 copy of the starter emitted by the supported CLI and is checked for drift.
 
 This page explains the ownership and safe defaults of the generated variables;
-the comments in `.env.example` remain the version-matched field reference.
+the compact `.env.example` contains only the standard installation settings.
 
 ## Required values
 
@@ -12,8 +12,9 @@ the comments in `.env.example` remain the version-matched field reference.
 `DISCORD_CLIENT_ID` is the application's numeric ID. `DATABASE_ENGINE` accepts
 `postgresql` or `mysql` and defaults to PostgreSQL when omitted. `DATABASE_URL`
 must match the selected engine, and `DATABASE_SSL` must match the database
-provider. PostgreSQL Docker users must also replace the example password
-consistently in `PGPASSWORD` and `POSTGRES_PASSWORD`. The MySQL Compose starter
+provider. PostgreSQL Docker users can run `npm run envbuilder` and select the
+bundled database. That choice adds matching `PGPASSWORD` and `POSTGRES_PASSWORD`
+values and the Docker database/user settings. The MySQL Compose starter
 runs only the bot and connects to the external database in `DATABASE_URL`.
 
 Percent-encode special characters in URL credentials. `DATABASE_SSL=disable`
@@ -30,7 +31,7 @@ boundary and prevents Hosted-only Helyx Ecko calls from entering the local
 runtime.
 
 Privileged Discord intents, privacy execution, hosted OAuth, status reporting,
-guild command writes, and advanced sharding stay disabled until their complete
+and advanced sharding stay disabled until their complete
 requirements are deliberately configured. An empty variable still counts as a
 configured value in many environments, so leave unused optional lines
 commented.
@@ -48,8 +49,8 @@ For enabled-module command builds in approved servers, set
 Discord server IDs. Use `HELYX_GLOBAL_COMMAND_MODE=platform-only` to retain global
 core/deployment commands while feature commands use per-server builds. Restart
 after changing these values and check the dashboard command-build status. The
-template's default `legacy` mode can still register compatible globals while
-guild writes are disabled; it does not mean that every command is disabled.
+template uses `platform-only` and enables guild writes for the server IDs you
+provide. Enter those IDs before starting; leave the allowlist scope in place.
 Do not use the advanced `all` scope merely to bypass an allowlist error.
 
 `HELYX_AUTOMOD_EMBEDDED_WORKERS` controls only the in-process Self-Hosted

package/documentation/runbooks/installation-and-upgrades.md

@@ -22,7 +22,10 @@ below.
 
 1. Download a starter ZIP, or generate it from the builder's reviewed manifest.
 2. Install its dependencies with `npm ci` unless generation used `--install`.
-3. Run `npm run setup`, then complete `.env`. A managed host may supply the
+3. Run `npm run envbuilder` to prepare `.env`, or use `npm run setup` and edit
+   the compact example. For the included Docker PostgreSQL service, use the
+   builder and choose **bundled** so its required database credentials are added.
+   A managed host may supply the
    required values through its protected variables panel instead. Keep the
    generated encryption key stable.
 4. Make the selected database reachable and run doctor through the matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",