@helyx/cli 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.7.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.
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/bot@1.6.0
+
+## 1.6.1
+
+### 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.6.0
 
 ### Minor Changes

package/dist/self-host/manifest.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { type SelfHostEnvironmentBuilder } from "./environment-builders.js";
 import { type SelfHostCatalogue, type SelfHostDatabaseEngine } from "./catalogue.js";
+export declare const selfHostProviderSchema: z.ZodEnum<{
+    standard: "standard";
+    pebblehost: "pebblehost";
+}>;
 export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     environmentBuilder: z.ZodOptional<z.ZodEnum<{
@@ -10,6 +14,10 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
         unix: "unix";
         all: "all";
     }>>;
+    provider: z.ZodOptional<z.ZodEnum<{
+        standard: "standard";
+        pebblehost: "pebblehost";
+    }>>;
     catalogueVersion: z.ZodNumber;
     core: z.ZodObject<{
         package: z.ZodString;
@@ -33,6 +41,10 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
         unix: "unix";
         all: "all";
     }>>;
+    provider: z.ZodOptional<z.ZodEnum<{
+        standard: "standard";
+        pebblehost: "pebblehost";
+    }>>;
     databaseEngine: z.ZodOptional<z.ZodEnum<{
         postgresql: "postgresql";
         mysql: "mysql";
@@ -67,6 +79,6 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }, z.core.$strict>>;
 }, z.core.$strict>], "schemaVersion">;
 export type SelfHostBuildManifest = z.infer<typeof selfHostBuildManifestSchema>;
-export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine, environmentBuilder?: SelfHostEnvironmentBuilder): SelfHostBuildManifest;
+export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine, environmentBuilder?: SelfHostEnvironmentBuilder, provider?: z.infer<typeof selfHostProviderSchema>): SelfHostBuildManifest;
 export declare function parseSelfHostBuildManifest(input: unknown, catalogue: SelfHostCatalogue): SelfHostBuildManifest;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/self-host/manifest.js

@@ -11,6 +11,7 @@ const officialModulePackage = z
     .string()
     .regex(/^@helyx\/module-[a-z0-9][a-z0-9-]*$/u);
 const moduleId = z.string().regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u);
+export const selfHostProviderSchema = z.enum(["standard", "pebblehost"]);
 const buildComponentSchema = z
     .object({ package: officialPackage, version: exactVersion })
     .strict();
@@ -25,6 +26,7 @@ const selfHostBuildManifestV1Schema = z
     .object({
     schemaVersion: z.literal(1),
     environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
+    provider: selfHostProviderSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
     generator: buildComponentSchema,
@@ -51,6 +53,7 @@ const selfHostBuildManifestV2Schema = z
     .object({
     schemaVersion: z.literal(2),
     environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
+    provider: selfHostProviderSchema.optional(),
     databaseEngine: selfHostDatabaseEngineSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
@@ -85,16 +88,17 @@ export const selfHostBuildManifestSchema = z
         packages.add(module.package);
     }
 });
-export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql", environmentBuilder = "none") {
+export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql", environmentBuilder = "none", provider = "standard") {
     selfHostDatabaseEngineSchema.parse(databaseEngine);
     selfHostEnvironmentBuilderSchema.parse(environmentBuilder);
+    selfHostProviderSchema.parse(provider);
     assertPublishedComponent(catalogue.core, "Helyx runtime");
     assertPublishedComponent(catalogue.generator, "Helyx generator");
     if (new Set(selectedModuleIds).size !== selectedModuleIds.length) {
         throw new Error("Self-host selection contains duplicate module IDs");
     }
     if (catalogue.schemaVersion === 2) {
-        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder);
+        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder, provider);
     }
     if (databaseEngine !== "postgresql") {
         throw new Error("Legacy self-host catalogue supports PostgreSQL only");
@@ -119,6 +123,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
     });
     return {
         schemaVersion: 1,
+        ...(provider !== "standard" ? { provider } : {}),
         ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         catalogueVersion: catalogue.catalogueVersion,
         core: {
@@ -132,7 +137,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
         modules,
     };
 }
-function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder = "none") {
+function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder = "none", provider = "standard") {
     const byId = new Map(catalogue.modules.map((module) => [module.id, module]));
     const explicitlySelected = new Set(selectedModuleIds);
     const modules = [];
@@ -194,6 +199,7 @@ function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEng
         include(id);
     return {
         schemaVersion: 2,
+        ...(provider !== "standard" ? { provider } : {}),
         ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         ...(databaseEngine === "mysql" ? { databaseEngine } : {}),
         catalogueVersion: catalogue.catalogueVersion,
@@ -224,9 +230,10 @@ export function parseSelfHostBuildManifest(input, catalogue) {
         const selectedModuleIds = manifest.modules
             .filter(({ moduleKind }) => moduleKind === "customer_feature")
             .map(({ id }) => id);
-        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql", manifest.environmentBuilder ?? "none");
+        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql", manifest.environmentBuilder ?? "none", manifest.provider ?? "standard");
         if (!isDeepStrictEqual({
             ...manifest,
+            provider: manifest.provider === "standard" ? undefined : manifest.provider,
             environmentBuilder: manifest.environmentBuilder === "none"
                 ? undefined
                 : manifest.environmentBuilder,
@@ -235,6 +242,7 @@ export function parseSelfHostBuildManifest(input, catalogue) {
                 : manifest.databaseEngine,
         }, {
             ...expected,
+            provider: expected.provider,
             databaseEngine: expected.databaseEngine,
             environmentBuilder: expected.environmentBuilder,
         })) {

package/dist/self-host/project-generator.d.ts

@@ -22,6 +22,8 @@ type HostedOnlyBotEnvironment = "HELYX_PRIVACY_ENABLED" | "HELYX_PRIVACY_EXECUTO
 type EnvironmentExample = Record<Exclude<keyof BotEnvironmentInput, HostedOnlyBotEnvironment>, {
     value: string;
     optional: boolean;
+} | {
+    omit: true;
 }>;
 export declare const selfHostEnvironmentContract: EnvironmentExample;
 export {};

package/dist/self-host/project-generator.js

@@ -63,6 +63,9 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
     const databaseEngine = "databaseEngine" in manifest
         ? (manifest.databaseEngine ?? "postgresql")
         : "postgresql";
+    const databaseSsl = manifest.provider === "pebblehost" || databaseEngine === "postgresql"
+        ? "disable"
+        : "require";
     const dependencyEntries = [
         [manifest.core.package, manifest.core.version],
         [manifest.generator.package, manifest.generator.version],
@@ -90,6 +93,12 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
         },
         dependencies,
     };
+    if (manifest.provider === "pebblehost") {
+        const cli = "node node_modules/@helyx/cli/dist/cli.js";
+        for (const key of Object.keys(packageJson.scripts)) {
+            packageJson.scripts[key] = packageJson.scripts[key].replace(/^helyx /u, `${cli} `);
+        }
+    }
     const moduleCatalogue = {
         schemaVersion: 1,
         packages: manifest.modules.map((module) => module.package),
@@ -105,12 +114,12 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
             ? mysqlComposeTemplateUrl()
             : templateUrl(fileName), "utf8");
         const rendered = fileName === ".env.example"
-            ? renderEnvironmentExample(template, databaseEngine)
+            ? renderEnvironmentExample(template, databaseEngine, databaseSsl)
             : fileName === "README.md"
                 ? renderReadme(template, manifest, catalogue, databaseEngine)
                 : template;
         if (fileName === ".env.example")
-            validateEnvironmentTemplate(rendered, databaseEngine);
+            validateEnvironmentTemplate(rendered, databaseEngine, databaseSsl);
         const content = fileName.endsWith(".sh")
             ? rendered.replaceAll("\r\n", "\n")
             : normalizeCrLf(rendered);
@@ -120,15 +129,13 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
         });
     }
 }
-function renderEnvironmentExample(template, databaseEngine) {
-    if (databaseEngine === "postgresql")
-        return template;
+function renderEnvironmentExample(template, databaseEngine, databaseSsl) {
     return template
-        .replaceAll("\r\n", "\n")
-        .replace("# Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.\nDATABASE_ENGINE=postgresql\nDATABASE_URL=postgresql://database:5432/helyx", "# Use the MySQL-compatible database URL supplied by your provider.\n# The included Compose file runs only the bot; it never starts a second database.\nDATABASE_ENGINE=mysql\nDATABASE_URL=mysql://user:password@host:3306/helyx")
-        .replace(/# Included Docker database[^\n]*\nPGUSER=helyx\nPGPASSWORD=replace-with-a-strong-password\nPOSTGRES_DB=helyx\nPOSTGRES_USER=helyx\nPOSTGRES_PASSWORD=replace-with-a-strong-password\n\n/u, "")
-        .replace("HELYX_SHARD_MODE=off\n", "# MySQL-compatible self-hosting currently supports only this unsharded mode.\nHELYX_SHARD_MODE=off\n")
-        .replace("DATABASE_SSL=disable", "DATABASE_SSL=require");
+        .replace("DATABASE_ENGINE='postgresql'", `DATABASE_ENGINE='${databaseEngine}'`)
+        .replace("DATABASE_URL='postgresql://database:5432/helyx'", databaseEngine === "mysql"
+        ? "DATABASE_URL='mysql://user:password@host:3306/helyx'"
+        : "DATABASE_URL='postgresql://database:5432/helyx'")
+        .replace("DATABASE_SSL='disable'", `DATABASE_SSL='${databaseSsl}'`);
 }
 function renderReadme(template, manifest, catalogue, databaseEngine) {
     const modulesById = new Map(catalogue.modules.map((module) => [module.id, module]));
@@ -146,11 +153,16 @@ function renderReadme(template, manifest, catalogue, databaseEngine) {
     let rendered = template
         .replaceAll("\r\n", "\n")
         .replace("{{SELECTED_MODULES}}", selected);
+    if (manifest.provider === "pebblehost") {
+        rendered =
+            "# PebbleHost setup\n\nThis starter uses the PebbleHost npm scripts. Extract the ZIP directly into the server root, select Node.js 24.7.0 and set Bot Start File to `package.json`. Create your `.env` at https://helyx.gg/env-builder/?provider=pebblehost and upload it before pressing Start. Follow the complete guide at https://docs.helyx.gg/self-host/providers/pebblehost/. PebbleHost's application console cannot run npm installation commands or the terminal Env Builder.\n\n" +
+                rendered;
+    }
     if (databaseEngine === "mysql") {
         rendered = rendered
             .replace("3. Edit `.env`, replace every placeholder, set `DATABASE_ENGINE` to `postgresql` or `mysql`, and set the matching `DATABASE_URL`. Omitting `DATABASE_ENGINE` selects PostgreSQL.", "3. Edit `.env`, replace every placeholder, keep `DATABASE_ENGINE=mysql` and `HELYX_SHARD_MODE=off`, and set `DATABASE_URL` to the MySQL-compatible URL supplied by your provider. Percent-encode special characters in URL credentials.")
             .replace("Use this path when Docker with Compose support is available. The included configuration runs both Helyx and PostgreSQL 17.", "Use this path when Docker with Compose support is available. The included configuration runs only Helyx; it connects to your existing MySQL-compatible database and does not create a second database service.")
-            .replace("2. Edit `.env` and replace all placeholder credentials and passwords.\n3. Keep `DATABASE_ENGINE=postgresql` with the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.\n4. Run `docker compose up --build -d`.\n5. Review startup with `docker compose logs -f bot`.\n6. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.", "2. Edit `.env` and replace all placeholder credentials. Keep `DATABASE_ENGINE=mysql` and supply your provider's reachable `DATABASE_URL` and required `DATABASE_SSL` setting.\n3. Run `docker compose up --build -d`.\n4. Review startup with `docker compose logs -f bot`.\n5. Stop the bot with `docker compose down`. Your external database is not managed by this Compose file.");
+            .replace("1. Run `npm ci`, then `npm run envbuilder`. Choose **bundled** Docker PostgreSQL when asked for the database source. The wizard adds only the Docker credentials needed for that choice and creates the encryption key.\n2. Enter your Discord credentials and server ID, then save `.env`. The bot itself will run in Docker.\n3. Keep `DATABASE_ENGINE=postgresql` with the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.\n4. Run `docker compose up --build -d`.\n5. Review startup with `docker compose logs -f bot`.\n6. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.", "1. Run `npm ci`, then `npm run envbuilder` to enter your Discord and external MySQL connection details and save `.env`.\n2. Keep `DATABASE_ENGINE=mysql` and supply your provider's reachable `DATABASE_URL` and required `DATABASE_SSL` setting.\n3. Run `docker compose up --build -d`.\n4. Review startup with `docker compose logs -f bot`.\n5. Stop the bot with `docker compose down`. Your external database is not managed by this Compose file.");
     }
     return rendered;
 }
@@ -174,20 +186,26 @@ function normalizeCrLf(value) {
         .replaceAll("\r", "\n")
         .replaceAll("\n", "\r\n");
 }
-function validateEnvironmentTemplate(template, databaseEngine) {
+function validateEnvironmentTemplate(template, databaseEngine, databaseSsl) {
     const lines = new Set(template
         .replaceAll("\r\n", "\n")
         .split("\n")
         .map((line) => line.trim()));
     for (const [key, definition] of Object.entries(selfHostEnvironmentContract)) {
+        if ("omit" in definition) {
+            const setting = new RegExp(`^(?:#\\s*)?${key}\\s*=`, "u");
+            if ([...lines].some((line) => setting.test(line)))
+                throw new Error(`Self-host environment template contains an omitted setting: ${key}`);
+            continue;
+        }
         const value = key === "DATABASE_ENGINE"
             ? databaseEngine
             : key === "DATABASE_URL" && databaseEngine === "mysql"
                 ? "mysql://user:password@host:3306/helyx"
-                : key === "DATABASE_SSL" && databaseEngine === "mysql"
-                    ? "require"
+                : key === "DATABASE_SSL"
+                    ? databaseSsl
                     : definition.value;
-        const expected = `${definition.optional ? "# " : ""}${key}=${value}`;
+        const expected = `${definition.optional ? "# " : ""}${key}='${value}'`;
         if (!lines.has(expected)) {
             throw new Error(`Self-host environment template does not match the bot contract: ${key}`);
         }
@@ -327,146 +345,67 @@ export const selfHostEnvironmentContract = {
         optional: false,
     },
     DATABASE_SSL: { value: "disable", optional: false },
-    HELYX_DATABASE_STARTUP_MODE: { value: "apply", optional: true },
+    HELYX_DATABASE_STARTUP_MODE: { omit: true },
     HELYX_RUNTIME_PROFILE: { value: "self-hosted", optional: false },
     HELYX_DEPLOYMENT_ENVIRONMENT: { value: "self-hosted", optional: false },
     DISCORD_TOKEN: { value: "replace-me", optional: false },
     DISCORD_CLIENT_ID: { value: "12345678901234567", optional: false },
     HELYX_MESSAGE_CONTENT_ENABLED: { value: "false", optional: false },
-    HELYX_AUTOMOD_EMBEDDED_WORKERS: { value: "1", optional: false },
-    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS: { value: "5000", optional: true },
-    HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES: { value: "67108864", optional: true },
-    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD: {
-        value: "100",
-        optional: true,
-    },
-    HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS: {
-        value: "300",
-        optional: true,
-    },
-    DISCORD_INTERNAL_GUILD_ID: {
-        value: "12345678901234567",
-        optional: true,
-    },
-    APPROVED_ROLES: {
-        value: "12345678901234567,12345678901234568",
-        optional: true,
-    },
-    HELYX_MODULE_PACKAGES: {
-        value: "",
-        optional: true,
-    },
+    // Advanced self-host options use runtime defaults; internal/hosted settings
+    // are deliberately absent from the customer example.
+    HELYX_AUTOMOD_EMBEDDED_WORKERS: { omit: true },
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS: { omit: true },
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES: { omit: true },
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD: { omit: true },
+    HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS: { omit: true },
+    DISCORD_INTERNAL_GUILD_ID: { omit: true },
+    APPROVED_ROLES: { omit: true },
+    HELYX_MODULE_PACKAGES: { omit: true },
     HELYX_MODULE_CATALOGUE_PATH: {
         value: "./helyx.modules.json",
         optional: false,
     },
-    HELYX_DASHBOARD_PUBLIC_URL: {
-        value: "https://app.helyx.gg",
-        optional: true,
-    },
-    HELYX_BOT_CONTROL_SECRET: {
-        value: "replace-with-a-base64-encoded-32-byte-key",
-        optional: true,
-    },
-    HELYX_BOT_CONTROL_PORT: { value: "3001", optional: true },
-    HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS: {
-        value: "900",
-        optional: true,
-    },
-    HELYX_HOSTED_MODERATION_ENABLED: { value: "false", optional: false },
-    HELYX_GUILD_COMMAND_WRITES_ENABLED: { value: "false", optional: false },
+    HELYX_DASHBOARD_PUBLIC_URL: { omit: true },
+    HELYX_BOT_CONTROL_SECRET: { omit: true },
+    HELYX_BOT_CONTROL_PORT: { omit: true },
+    HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS: { omit: true },
+    HELYX_HOSTED_MODERATION_ENABLED: { omit: true },
+    HELYX_GUILD_COMMAND_WRITES_ENABLED: { value: "true", optional: false },
     HELYX_GUILD_COMMAND_WRITE_SCOPE: { value: "allowlist", optional: false },
-    HELYX_GUILD_COMMAND_RELEASE_ID: { value: "", optional: true },
-    HELYX_GLOBAL_COMMAND_MODE: { value: "legacy", optional: false },
-    HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: { value: "", optional: true },
+    HELYX_GUILD_COMMAND_RELEASE_ID: { omit: true },
+    HELYX_GLOBAL_COMMAND_MODE: { value: "platform-only", optional: false },
+    HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: { value: "", optional: false },
     HELYX_GUILD_MEMBERS_ENABLED: { value: "false", optional: false },
     HELYX_CLOUD_CONNECT_ENABLED: { value: "true", optional: false },
-    HELYX_CLOUD_ENROLMENT_TOKEN: {
-        value: "replace-with-a-short-lived-enrolment-code",
-        optional: true,
-    },
-    HELYX_CLOUD_ENROLMENT_FILE: {
-        value: "./helyx.cloud-enrolment.json",
-        optional: true,
-    },
+    HELYX_CLOUD_ENROLMENT_TOKEN: { omit: true },
+    HELYX_CLOUD_ENROLMENT_FILE: { omit: true },
     HELYX_DATA_ENCRYPTION_KEY: {
         value: "replace-with-a-base64-encoded-32-byte-key",
-        optional: true,
-    },
-    HELYX_CLOUD_API_URL: {
-        value: "https://api.helyx.gg",
-        optional: true,
-    },
-    HELYX_OAUTH_ENABLED: { value: "false", optional: false },
-    HELYX_OAUTH_INTERNAL_SECRET: {
-        value: "replace-with-a-base64-encoded-32-byte-key",
-        optional: true,
-    },
-    HELYX_CLOUD_ENDPOINT: {
-        value: "wss://connect.helyx.gg/v1/connect",
-        optional: true,
-    },
-    HELYX_OWNER_USER_IDS: {
-        value: "12345678901234567",
-        optional: true,
+        optional: false,
     },
+    HELYX_CLOUD_API_URL: { omit: true },
+    HELYX_OAUTH_ENABLED: { omit: true },
+    HELYX_OAUTH_INTERNAL_SECRET: { omit: true },
+    HELYX_CLOUD_ENDPOINT: { omit: true },
+    HELYX_OWNER_USER_IDS: { omit: true },
     HELYX_SHARD_MODE: { value: "off", optional: false },
-    HELYX_SHARD_COUNT: { value: "2", optional: true },
-    HELYX_SHARD_SCOPE: { value: "local", optional: true },
-    HELYX_SHARD_WORKERS_PER_REPLICA: { value: "2", optional: true },
-    HELYX_SHARD_REDIS_URL: {
-        value: "rediss://private-redis.example:6379",
-        optional: true,
-    },
-    HELYX_SHARD_REDIS_NAMESPACE: {
-        value: "helyx.self-host",
-        optional: true,
-    },
-    HELYX_SHARD_GENERATION: {
-        value: "local-20260728",
-        optional: true,
-    },
-    HELYX_SHARD_DATABASE_CONNECTION_BUDGET: {
-        value: "10",
-        optional: true,
-    },
-    HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX: {
-        value: "2",
-        optional: true,
-    },
-    HELYX_SHARD_WORKER_DATABASE_POOL_MAX: {
-        value: "4",
-        optional: true,
-    },
-    HELYX_CLOUD_AUDIT_RETENTION_DAYS: {
-        value: "90",
-        optional: true,
-    },
-    HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS: {
-        value: "365",
-        optional: true,
-    },
-    HELYX_STATUS_ENABLED: { value: "false", optional: false },
-    HELYX_STATUS_URL: {
-        value: "https://status.helyx.gg",
-        optional: true,
-    },
-    HELYX_STATUS_HEARTBEAT_SECRET: {
-        value: "replace-with-a-base64-encoded-32-byte-key",
-        optional: true,
-    },
-    HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS: {
-        value: "60",
-        optional: true,
-    },
-    CF_ACCESS_CLIENT_ID: {
-        value: "replace-with-access-client-id",
-        optional: true,
-    },
-    CF_ACCESS_CLIENT_SECRET: {
-        value: "replace-with-access-client-secret",
-        optional: true,
-    },
+    HELYX_SHARD_COUNT: { omit: true },
+    HELYX_SHARD_SCOPE: { omit: true },
+    HELYX_SHARD_WORKERS_PER_REPLICA: { omit: true },
+    HELYX_SHARD_REDIS_URL: { omit: true },
+    HELYX_SHARD_REDIS_NAMESPACE: { omit: true },
+    HELYX_SHARD_GENERATION: { omit: true },
+    HELYX_SHARD_DATABASE_CONNECTION_BUDGET: { omit: true },
+    HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX: { omit: true },
+    HELYX_SHARD_WORKER_DATABASE_POOL_MAX: { omit: true },
+    HELYX_CLOUD_AUDIT_RETENTION_DAYS: { omit: true },
+    HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS: { omit: true },
+    HELYX_STATUS_ENABLED: { omit: true },
+    HELYX_STATUS_URL: { omit: true },
+    HELYX_STATUS_HEARTBEAT_SECRET: { omit: true },
+    HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS: { omit: true },
+    CF_ACCESS_CLIENT_ID: { omit: true },
+    CF_ACCESS_CLIENT_SECRET: { omit: true },
     LOG_LEVEL: { value: "info", optional: false },
     NODE_ENV: { value: "production", optional: false },
 };

package/dist/setup.js

@@ -40,15 +40,14 @@ async function ensureDataEncryptionKey(environmentPath, createKey) {
     const content = await readFile(environmentPath, "utf8");
     const activeKeyPattern = new RegExp(`^[\\t ]*${dataEncryptionKeyName}[\\t ]*=[\\t ]*([^\\r\\n]*?)[\\t ]*(?=\\r?$)`, "mu");
     const activeKey = activeKeyPattern.exec(content);
-    if (activeKey &&
-        activeKey[1] !== undefined &&
-        activeKey[1] !== "" &&
-        activeKey[1] !== dataEncryptionKeyPlaceholder) {
+    const currentKey = parseEnv(content)[dataEncryptionKeyName];
+    if (currentKey && currentKey !== dataEncryptionKeyPlaceholder) {
         await chmod(environmentPath, 0o600);
         return false;
     }
     const key = createKey();
-    const replacement = `${dataEncryptionKeyName}=${key}`;
+    const quoted = activeKey?.[1]?.startsWith("'") || activeKey?.[1]?.startsWith('"');
+    const replacement = `${dataEncryptionKeyName}=${quoted ? `'${key}'` : key}`;
     let updated;
     if (activeKey) {
         updated = content.replace(activeKeyPattern, replacement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -52,7 +52,7 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@helyx/bot": ">=1.5.2 <2.0.0",
+    "@helyx/bot": ">=1.6.0 <2.0.0",
     "@helyx/config": ">=1.6.0 <2.0.0",
     "@helyx/database": ">=2.5.0 <3.0.0",
     "semver": "7.8.5",

package/self-host-catalogue.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 2,
-  "catalogueVersion": 86,
+  "catalogueVersion": 88,
   "core": {
     "package": "@helyx/bot",
-    "version": "1.5.3",
+    "version": "1.6.0",
     "availability": "published"
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "command": "helyx",
     "availability": "published"
   },

package/templates/self-host/.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/templates/self-host/README.md

@@ -76,8 +76,8 @@ Complete setup and credentials first. Before the start command below, run the
 container doctor preflight that follows the numbered steps; a host-shell doctor
 cannot normally resolve a container-only hostname such as `database`.
 
-1. Run `npm ci`, then `npm run setup`. This creates the local configuration and data-encryption key safely; the bot itself will still run in Docker.
-2. Edit `.env` and replace all placeholder credentials and passwords.
+1. Run `npm ci`, then `npm run envbuilder`. Choose **bundled** Docker PostgreSQL when asked for the database source. The wizard adds only the Docker credentials needed for that choice and creates the encryption key.
+2. Enter your Discord credentials and server ID, then save `.env`. The bot itself will run in Docker.
 3. Keep `DATABASE_ENGINE=postgresql` with the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.
 4. Run `docker compose up --build -d`.
 5. Review startup with `docker compose logs -f bot`.
@@ -151,10 +151,10 @@ Command registration is global or guild-scoped according to each reviewed comman
 
 ### Server-scoped module commands
 
-The template keeps guild command writes disabled and uses
-`HELYX_GLOBAL_COMMAND_MODE=legacy`. This does not disable all commands: core and
-compatible legacy commands can still register globally. However, server-scoped
-module command builds cannot be applied while guild writes are disabled.
+The compact template enables guild command writes with allowlist scope and
+`HELYX_GLOBAL_COMMAND_MODE=platform-only`. Enter your Discord server IDs before
+starting. Core commands remain global; feature commands are built for the
+enabled modules in each approved server.
 
 To use enabled-module command builds in servers you explicitly approve, set:
 

package/templates/self-host/env-builder.mjs

@@ -120,6 +120,12 @@ export function validateDatabaseUrl(value, engine) {
   }
 }
 
+export function normalizeDatabaseUrl(value, engine) {
+  return engine === "mysql"
+    ? value.replace(/^jdbc:(?=mysql:\/\/)/iu, "")
+    : value;
+}
+
 // Use single quotes to retain #, $, spaces and backslashes literally in Node
 // and Compose. Unusual mixed-quote values require manual editing, not guessing.
 export function encodeValue(value) {
@@ -188,113 +194,148 @@ export function updateEnvironment(content, changes) {
 
 const environmentGroups = [
   [
-    "INSTALLATION",
-    /^(?:HELYX_RUNTIME_PROFILE|HELYX_DEPLOYMENT_ENVIRONMENT|NODE_ENV)$/u,
-  ],
-  ["DISCORD BOT", /^(?:DISCORD_TOKEN|DISCORD_CLIENT_ID)$/u],
-  [
-    "DISCORD SERVER COMMANDS",
-    /^(?:HELYX_GUILD_COMMAND_|HELYX_GLOBAL_COMMAND_MODE)/u,
+    "Runtime",
+    ["HELYX_RUNTIME_PROFILE", "HELYX_DEPLOYMENT_ENVIRONMENT", "NODE_ENV"],
   ],
   [
-    "DISCORD GATEWAY INTENTS",
-    /^HELYX_(?:MESSAGE_CONTENT_ENABLED|GUILD_MEMBERS_ENABLED)$/u,
-  ],
-  ["DATABASE CONNECTION", /^DATABASE_|^HELYX_DATABASE_STARTUP_MODE$/u],
-  ["BUNDLED DOCKER POSTGRESQL", /^(?:PGUSER|PGPASSWORD|POSTGRES_)/u],
-  [
-    "DASHBOARD AND OWNERS",
-    /^(?:HELYX_CLOUD_CONNECT_ENABLED|HELYX_DASHBOARD_PUBLIC_URL|HELYX_OWNER_USER_IDS)$/u,
+    "Discord",
+    [
+      "DISCORD_CLIENT_ID",
+      "DISCORD_TOKEN",
+      "HELYX_GUILD_MEMBERS_ENABLED",
+      "HELYX_MESSAGE_CONTENT_ENABLED",
+    ],
   ],
-  ["DATA ENCRYPTION - KEEP THIS KEY", /^HELYX_DATA_ENCRYPTION_KEY$/u],
-  ["LOGGING", /^LOG_LEVEL$/u],
-  ["AUTO MODERATION", /^HELYX_AUTOMOD_/u],
-  ["SHARDING - ADVANCED", /^HELYX_SHARD_/u],
-  ["MODULE SELECTION", /^HELYX_MODULE_/u],
+  ["Database", ["DATABASE_ENGINE", "DATABASE_URL", "DATABASE_SSL"]],
   [
-    "PRIVATE CONTROL - ADVANCED",
-    /^HELYX_BOT_CONTROL_|^HELYX_HOSTED_MODERATION_ENABLED$|^HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS$/u,
+    "Commands",
+    [
+      "HELYX_GUILD_COMMAND_WRITES_ENABLED",
+      "HELYX_GUILD_COMMAND_WRITE_SCOPE",
+      "HELYX_GLOBAL_COMMAND_MODE",
+      "HELYX_GUILD_COMMAND_WRITE_GUILD_IDS",
+    ],
   ],
-  ["CLOUD CONNECT - ADVANCED", /^HELYX_CLOUD_/u],
-  ["OAUTH - ADVANCED", /^HELYX_OAUTH_/u],
-  ["STATUS REPORTING - OPTIONAL", /^HELYX_STATUS_|^CF_ACCESS_/u],
   [
-    "INTERNAL DEVELOPMENT - OPTIONAL",
-    /^(?:DISCORD_INTERNAL_GUILD_ID|APPROVED_ROLES)$/u,
+    "Modules and dashboard",
+    [
+      "HELYX_MODULE_CATALOGUE_PATH",
+      "HELYX_CLOUD_CONNECT_ENABLED",
+      "HELYX_SHARD_MODE",
+      "LOG_LEVEL",
+    ],
   ],
-  ["CUSTOM SETTINGS", /./u],
+  ["Keep this key unchanged across restarts and updates", [encryptionKey]],
 ];
+const standardKeys = new Set(environmentGroups.flatMap(([, keys]) => keys));
 const oldHeadings = new Set([
-  "REQUIRED — EDIT THESE VALUES",
-  "Discord",
-  "Database",
+  "INSTALLATION",
+  "DISCORD BOT",
+  "DISCORD SERVER COMMANDS",
+  "DISCORD GATEWAY INTENTS",
+  "DATABASE CONNECTION",
+  "BUNDLED DOCKER POSTGRESQL",
+  "DASHBOARD AND OWNERS",
+  "DATA ENCRYPTION - KEEP THIS KEY",
+  "LOGGING",
+  "SHARDING - ADVANCED",
+  "MODULE SELECTION",
+  "CUSTOM SETTINGS",
+  "AUTO MODERATION",
+  "PRIVATE CONTROL - ADVANCED",
+  "CLOUD CONNECT - ADVANCED",
+  "OAUTH - ADVANCED",
+  "STATUS REPORTING - OPTIONAL",
+  "INTERNAL DEVELOPMENT - OPTIONAL",
+  "REQUIRED ? EDIT THESE VALUES",
   "OPTIONAL EVERYDAY SETTINGS",
   "SHARDING: OFF BY DEFAULT",
-  "ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED",
-  "DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT",
+  "ADVANCED INTEGRATIONS ? EDIT ONLY WHEN NEEDED",
+  "DANGER ZONE ? HELYX-MANAGED VALUES, DO NOT EDIT",
   "Runtime mode",
   "Helyx self-hosted environment",
   "Keep this file private. Lines starting with # are comments.",
+  "Keep this file private. Retain the encryption key when updating.",
+  "Bundled Docker database",
+  "Custom settings",
+  ...environmentGroups.map(([title]) => title),
 ]);
 
-export function formatEnvironment(content) {
+export function formatEnvironment(content, { template = false } = {}) {
   const newline = content.includes("\r\n") ? "\r\n" : "\n";
-  const groups = environmentGroups.map(() => []);
+  const sections = [
+    ...environmentGroups,
+    ["Bundled Docker database", []],
+    ["Custom settings", []],
+  ];
+  const groups = sections.map(() => []);
   let pending = [];
   let previousGroup;
-  const append = (index, lines) => {
-    const text = lines.join("\n").trim();
-    if (!text) return;
-    if (
-      groups[index].length &&
-      text.startsWith("#") &&
-      !/^#\s*[A-Za-z_][A-Za-z0-9_]*\s*=/u.test(text)
-    )
-      groups[index].push("");
-    groups[index].push(text);
-  };
   for (const record of records(content)) {
     const text = record.text.replace(/\r\n/gu, "\n").replace(/\n$/u, "");
     const heading = text.match(/^#\s*(.*?)\s*$/u)?.[1];
     if (
       heading !== undefined &&
-      (oldHeadings.has(heading) ||
-        /^=+$/u.test(heading) ||
-        environmentGroups.some(([title]) => heading === title))
+      (template || oldHeadings.has(heading) || /^=+$/u.test(heading))
     )
       continue;
     const key =
       record.key ?? text.match(/^\s*#\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/u)?.[1];
+    if (key && (!record.key || (template && !standardKeys.has(key)))) {
+      pending = [];
+      continue;
+    }
     if (!key) {
       if (!text.trim() && pending.length && previousGroup !== undefined) {
-        append(previousGroup, pending);
+        groups[previousGroup].push({ key: "", text: pending.join("\n") });
         pending = [];
-      } else if (text.trim()) pending.push(text);
+      } else if (text.trim() && !template) pending.push(text);
       continue;
     }
-    const group = environmentGroups.findIndex(([, pattern]) =>
-      pattern.test(key),
+    const standardGroup = environmentGroups.findIndex(([, keys]) =>
+      keys.includes(key),
     );
-    append(group, [...pending, text]);
+    const group =
+      standardGroup >= 0
+        ? standardGroup
+        : /^(?:PGUSER|PGPASSWORD|POSTGRES_)/u.test(key)
+          ? environmentGroups.length
+          : environmentGroups.length + 1;
+    // Standard fields use the same compact quoting as the website. Keep custom
+    // records verbatim, including multiline values and their comments.
+    const assignment =
+      standardGroup >= 0
+        ? `${key}=${encodeValue(parseEnv(record.text)[key])}${record.comment}`
+        : text;
+    groups[group].push({ key, text: [...pending, assignment].join("\n") });
     pending = [];
     previousGroup = group;
   }
-  if (pending.length) append(previousGroup ?? groups.length - 1, pending);
-  const divider =
-    "# ============================================================================";
-  const output =
+  if (pending.length)
+    groups[previousGroup ?? groups.length - 1].push({
+      key: "",
+      text: pending.join("\n"),
+    });
+  const formatted = (
     [
-      "# Helyx self-hosted environment\n# Keep this file private. Lines starting with # are comments.",
-      ...groups.flatMap((lines, index) =>
-        lines.length
-          ? [
-              `${divider}\n# ${environmentGroups[index][0]}\n${divider}\n\n${lines.join("\n")}`,
-            ]
-          : [],
-      ),
-    ].join("\n\n\n") + "\n";
-  const formatted = output.replace(/\n/gu, newline);
+      "# Helyx self-hosted environment\n# Keep this file private. Retain the encryption key when updating.",
+      ...groups.flatMap((lines, index) => {
+        if (!lines.length) return [];
+        const keys = sections[index][1];
+        if (keys.length)
+          lines.sort(
+            (left, right) => keys.indexOf(left.key) - keys.indexOf(right.key),
+          );
+        return [
+          `# ${sections[index][0]}\n${lines.map(({ text }) => text).join("\n")}`,
+        ];
+      }),
+    ].join("\n\n") + "\n"
+  ).replace(/\n/gu, newline);
   const before = parseEnv(content);
+  if (template)
+    for (const key of Object.keys(before))
+      if (!standardKeys.has(key)) delete before[key];
   const after = parseEnv(formatted);
   if (
     Object.keys(before).length !== Object.keys(after).length ||
@@ -420,7 +461,10 @@ export async function runWizard({
       "Choose a downloaded Helyx starter folder containing package.json and .env.example.",
     );
   const original = await optionalRead(join(directory, ".env"));
-  const template = await readFile(join(directory, ".env.example"), "utf8");
+  const template = formatEnvironment(
+    await readFile(join(directory, ".env.example"), "utf8"),
+    { template: true },
+  );
   const existing = parseEnv(original ?? "");
   const defaults = parseEnv(template);
   const values = { ...defaults, ...existing };
@@ -437,6 +481,7 @@ export async function runWizard({
       validate = () => {},
       fallback,
       optional = false,
+      normalize = (value) => value,
     } = {},
   ) => {
     const current = fallback ?? values[key] ?? "";
@@ -450,8 +495,10 @@ export async function runWizard({
         `${label} [${display}]${optional ? " (Enter keeps; - clears)" : " (Enter keeps)"}: `,
         { secret: secret && !visibleInput },
       );
-      const value = optional && answer === "-" ? "" : answer || current;
       try {
+        const value = normalize(
+          optional && answer === "-" ? "" : answer || current,
+        );
         if (placeholder.test(value))
           throw new WizardError(
             "Replace the example placeholder with your own value.",
@@ -460,7 +507,14 @@ export async function runWizard({
         encodeValue(value);
         validate(value);
         values[key] = value;
-        if (value !== existing[key]) changes[key] = value;
+        if (
+          value !== existing[key] &&
+          (!optional ||
+            value ||
+            existing[key] !== undefined ||
+            standardKeys.has(key))
+        )
+          changes[key] = value;
         return value;
       } catch (error) {
         io.print(error.message);
@@ -484,8 +538,7 @@ export async function runWizard({
   const bundledAvailable =
     engine === "postgresql" &&
     defaults.DATABASE_ENGINE === "postgresql" &&
-    (await optionalRead(join(directory, "compose.yaml"))) !== null &&
-    Boolean(defaults.POSTGRES_PASSWORD);
+    (await optionalRead(join(directory, "compose.yaml"))) !== null;
   let databaseMode = "external";
   if (bundledAvailable) {
     for (;;) {
@@ -537,7 +590,11 @@ export async function runWizard({
       DATABASE_SSL: "disable",
     });
   } else {
-    await askValue(
+    if (engine === "mysql")
+      io.print(
+        "Paste a MySQL URL or JDBC connection string. The jdbc: prefix is removed automatically; missing login details are requested next.",
+      );
+    const connection = await askValue(
       "DATABASE_URL",
       "Database connection URL (typing and paste visible)",
       {
@@ -549,8 +606,30 @@ export async function runWizard({
             ? ""
             : values.DATABASE_URL,
         validate: (value) => validateDatabaseUrl(value, engine),
+        normalize: (value) => normalizeDatabaseUrl(value, engine),
       },
     );
+    if (engine === "mysql") {
+      const url = new URL(connection);
+      for (const field of ["username", "password"]) {
+        while (!url[field]) {
+          const value = await io.ask(`Database ${field}: `, {
+            secret: field === "password",
+          });
+          if (!value || /[\p{Cc}\p{Cf}]/u.test(value)) {
+            io.print("Enter a single-line value.");
+            continue;
+          }
+          url[field] = encodeURIComponent(value).replace(
+            /[!'()*]/gu,
+            (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+          );
+        }
+      }
+      values.DATABASE_URL = url.href.replaceAll("'", "%27");
+      if (values.DATABASE_URL !== existing.DATABASE_URL)
+        changes.DATABASE_URL = values.DATABASE_URL;
+    }
     io.print(
       "SSL: disable = no TLS; require = TLS without certificate verification; verify-full = TLS with certificate verification. Use your provider's requirement.",
     );
@@ -681,6 +760,17 @@ export async function runWizard({
     HELYX_RUNTIME_PROFILE: "self-hosted",
     HELYX_DEPLOYMENT_ENVIRONMENT: "self-hosted",
   });
+  for (const [key, value] of Object.entries({
+    NODE_ENV: "production",
+    HELYX_MODULE_CATALOGUE_PATH: "./helyx.modules.json",
+    HELYX_SHARD_MODE: "off",
+    LOG_LEVEL: "info",
+    HELYX_GLOBAL_COMMAND_MODE: "platform-only",
+    HELYX_GUILD_COMMAND_WRITE_SCOPE: "allowlist",
+  })) {
+    if (existing[key] === undefined && changes[key] === undefined)
+      changes[key] = value;
+  }
   if (engine === "mysql") Object.assign(changes, { HELYX_SHARD_MODE: "off" });
   const updated = formatEnvironment(
     updateEnvironment(original ?? template, changes),