@helyx/cli 1.6.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.8.0
+
+### Minor Changes
+
+- Add helyx help connect, status and disconnect for opt-in online Help, encrypted local credentials and credential revocation. Package the compatible bot and updated self-host catalogue while retaining offline Help without enrolment.
+
+## 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

package/dist/cli.js

@@ -7,6 +7,7 @@ import { resolveDatabaseAdapter } from "@helyx/database/adapters";
 import { formatCommandError } from "./errors.js";
 import { runSelfHostCommand } from "./self-host/command.js";
 import { loadLocalEnvironment, setupSelfHostEnvironment } from "./setup.js";
+import { runHelpCommand } from "./help-command.js";
 const command = process.argv[2];
 try {
     if (command === "start") {
@@ -31,6 +32,9 @@ try {
     else if (command === "self-host") {
         await runSelfHostCommand(process.argv.slice(3));
     }
+    else if (command === "help" && process.argv[3]) {
+        await runHelpCommand(process.argv.slice(3));
+    }
     else if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
     }
@@ -149,6 +153,8 @@ Commands:
   start    Start the Helyx Discord bot
   migrate  Apply core migrations for the selected database engine and exit
   doctor   Validate environment, database schema and module packages
+  help connect|status|disconnect [--project <path>] [--confirm]
+           Manage optional Help-only online access; local Help needs no account
   self-host init --manifest <path> [--output <path>] [--install]
            Generate a self-hosted starter project from a reviewed manifest
   self-host update --check [--project <path>]

package/dist/help-command.d.ts

@@ -0,0 +1,8 @@
+export declare function runHelpCommand(args: readonly string[], options?: {
+    cwd?: string;
+    environment?: NodeJS.ProcessEnv;
+    question?: (prompt: string) => Promise<string>;
+    write?: (message: string) => void;
+    fetch?: typeof fetch;
+}): Promise<void>;
+//# sourceMappingURL=help-command.d.ts.map

package/dist/help-command.js

@@ -0,0 +1,71 @@
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { HelpCredentialStore, exchangeHelpEnrolment, revokeHelpCredential, } from "@helyx/bot";
+import { loadLocalEnvironment } from "./setup.js";
+export async function runHelpCommand(args, options = {}) {
+    const [action, ...rest] = args;
+    let directory = resolve(options.cwd ?? process.cwd()), confirm = false;
+    if (!["connect", "status", "disconnect"].includes(action ?? ""))
+        throw new Error("Use: helyx help connect|status|disconnect [--project <path>] [--confirm]");
+    for (let index = 0; index < rest.length; index++) {
+        if (rest[index] === "--project" && rest[index + 1])
+            directory = resolve(directory, rest[++index]);
+        else if (rest[index] === "--confirm")
+            confirm = true;
+        else
+            throw new Error("Unsupported Help option. Paste enrolment codes at the prompt, not in command arguments.");
+    }
+    const environment = { ...(options.environment ?? process.env) };
+    await loadLocalEnvironment(directory, environment);
+    if (!environment.HELYX_DATA_ENCRYPTION_KEY)
+        throw new Error("Set up the local HELYX_DATA_ENCRYPTION_KEY before managing online Help. Local Help remains available.");
+    if (action === "connect" &&
+        environment.HELYX_RUNTIME_PROFILE !== "self-hosted")
+        throw new Error("Online Help enrolment is for a self-hosted installation. Set HELYX_RUNTIME_PROFILE=self-hosted in that project's environment.");
+    const store = new HelpCredentialStore(directory, environment.HELYX_DATA_ENCRYPTION_KEY), write = options.write ?? console.log;
+    if (action === "status") {
+        const credential = await store.read();
+        write(!credential
+            ? "Help: local bundled FAQs. No online credential saved."
+            : `Help: ${Date.parse(credential.expiresAt) > Date.now() ? "online credential saved" : "credential expired; local FAQs remain available"}. Installation ${credential.installationId}. Expires ${credential.expiresAt}.`);
+        return;
+    }
+    if (action === "disconnect") {
+        const credential = await store.read();
+        let remote = true;
+        if (credential && Date.parse(credential.expiresAt) > Date.now())
+            try {
+                await revokeHelpCredential(credential.token, options.fetch);
+            }
+            catch {
+                remote = false;
+            }
+        await store.remove();
+        write(remote
+            ? "Online Help disconnected. Local bundled FAQs remain available."
+            : "Online Help disconnected locally. Revoke its credential from your dashboard when the service is available.");
+        return;
+    }
+    const reader = options.question
+        ? null
+        : createInterface({ input: process.stdin, output: process.stdout }), question = options.question ?? ((prompt) => reader.question(prompt));
+    try {
+        write("Optional online Help sends your public Helyx question to Helyx and its embedding provider. It does not connect guild settings or require Cloud Connect.");
+        if (!confirm &&
+            (await question("Type CONNECT to save an encrypted Help-only credential: ")).trim() !== "CONNECT") {
+            write("Cancelled. Local Help remains available.");
+            return;
+        }
+        const code = (await question("Paste the one-time Help code from your self-host dashboard: ")).trim();
+        const credential = await exchangeHelpEnrolment(code, options.fetch);
+        await store.save(credential);
+        write(`Online Help connected for installation ${credential.installationId}. Credential expires ${credential.expiresAt}.`);
+    }
+    catch {
+        throw new Error("Online Help could not be connected. Check the one-time code, service availability, local encryption key and write permissions. No credential value was printed.");
+    }
+    finally {
+        reader?.close();
+    }
+}
+//# sourceMappingURL=help-command.js.map

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";
 export * from "./setup.js";
+export * from "./help-command.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,4 +6,5 @@ export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";
 export * from "./setup.js";
+export * from "./help-command.js";
 //# sourceMappingURL=index.js.map

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.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,7 +186,7 @@ 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")
@@ -190,10 +202,10 @@ function validateEnvironmentTemplate(template, databaseEngine) {
             ? 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}`);
         }
@@ -333,7 +345,7 @@ 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 },
@@ -348,71 +360,44 @@ export const selfHostEnvironmentContract = {
     HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS: { omit: true },
     DISCORD_INTERNAL_GUILD_ID: { omit: true },
     APPROVED_ROLES: { omit: true },
-    HELYX_MODULE_PACKAGES: {
-        value: "",
-        optional: 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_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: "false", optional: false },
+    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: { omit: true },
     HELYX_CLOUD_ENROLMENT_FILE: { omit: true },
     HELYX_DATA_ENCRYPTION_KEY: {
         value: "replace-with-a-base64-encoded-32-byte-key",
-        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: {
-        value: "12345678901234567",
-        optional: 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_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 },

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.1",
+  "version": "1.8.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -52,9 +52,9 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@helyx/bot": ">=1.5.2 <2.0.0",
-    "@helyx/config": ">=1.6.0 <2.0.0",
-    "@helyx/database": ">=2.5.0 <3.0.0",
+    "@helyx/bot": ">=1.7.0 <2.0.0",
+    "@helyx/config": ">=1.7.0 <2.0.0",
+    "@helyx/database": ">=2.5.1 <3.0.0",
     "semver": "7.8.5",
     "zod": "4.6.7"
   },

package/self-host-catalogue.json

@@ -1,21 +1,21 @@
 {
   "schemaVersion": 2,
-  "catalogueVersion": 87,
+  "catalogueVersion": 89,
   "core": {
     "package": "@helyx/bot",
-    "version": "1.5.4",
+    "version": "1.7.0",
     "availability": "published"
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "1.6.1",
+    "version": "1.8.0",
     "command": "helyx",
     "availability": "published"
   },
   "databaseAdapters": [
     {
       "package": "@helyx/database",
-      "version": "2.5.0"
+      "version": "2.5.1"
     },
     {
       "package": "@helyx/database-mysql",
@@ -273,7 +273,7 @@
     {
       "id": "helyx.account-gate",
       "package": "@helyx/module-account-gate",
-      "version": "2.1.2",
+      "version": "2.1.3",
       "name": "Access Control",
       "description": "Require new members to complete configurable Discord interaction checks before gaining access.",
       "category": "Safety",
@@ -558,7 +558,7 @@
     {
       "id": "helyx.reactionroles",
       "package": "@helyx/module-reactionroles",
-      "version": "1.1.2",
+      "version": "1.1.3",
       "name": "Reaction Roles",
       "description": "Let members select approved roles themselves.",
       "category": "Automation",
@@ -938,7 +938,7 @@
     {
       "id": "helyx.achievements",
       "package": "@helyx/module-achievements",
-      "version": "2.1.3",
+      "version": "2.1.4",
       "name": "Achievements",
       "description": "Configurable member milestones, scores and optional rewards.",
       "category": "Gaming",

package/templates/self-host/.env.example

@@ -1,89 +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
-# 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
-
-# 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.
+DISCORD_CLIENT_ID='12345678901234567'
+DISCORD_TOKEN='replace-me'
+HELYX_GUILD_MEMBERS_ENABLED='false'
+HELYX_MESSAGE_CONTENT_ENABLED='false'
 
-# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
-
-# Additional reviewed module packages
-# HELYX_MODULE_PACKAGES=
-
-# 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=
-
-# 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
-
-# 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/Dockerfile

@@ -9,6 +9,7 @@ COPY helyx.modules.json ./
 
 ENV HELYX_MODULE_CATALOGUE_PATH=/app/helyx.modules.json
 ENV NODE_ENV=production
+RUN mkdir -p /app/.helyx && chown node:node /app/.helyx
 
 USER node
 

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/compose.mysql.yaml

@@ -4,3 +4,8 @@ services:
     restart: unless-stopped
     env_file:
       - .env
+    volumes:
+      - helyx-private:/app/.helyx
+
+volumes:
+  helyx-private:

package/templates/self-host/compose.yaml

@@ -4,6 +4,8 @@ services:
     restart: unless-stopped
     env_file:
       - .env
+    volumes:
+      - helyx-private:/app/.helyx
     depends_on:
       database:
         condition: service_healthy
@@ -25,3 +27,4 @@ services:
 
 volumes:
   helyx-database:
+  helyx-private:

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,116 +194,148 @@ export function updateEnvironment(content, changes) {
 
 const environmentGroups = [
   [
-    "INSTALLATION",
-    /^(?:HELYX_RUNTIME_PROFILE|HELYX_DEPLOYMENT_ENVIRONMENT|NODE_ENV)$/u,
+    "Runtime",
+    ["HELYX_RUNTIME_PROFILE", "HELYX_DEPLOYMENT_ENVIRONMENT", "NODE_ENV"],
   ],
-  ["DISCORD BOT", /^(?:DISCORD_TOKEN|DISCORD_CLIENT_ID)$/u],
   [
-    "DISCORD SERVER COMMANDS",
-    /^(?:HELYX_GUILD_COMMAND_|HELYX_GLOBAL_COMMAND_MODE)/u,
+    "Discord",
+    [
+      "DISCORD_CLIENT_ID",
+      "DISCORD_TOKEN",
+      "HELYX_GUILD_MEMBERS_ENABLED",
+      "HELYX_MESSAGE_CONTENT_ENABLED",
+    ],
   ],
+  ["Database", ["DATABASE_ENGINE", "DATABASE_URL", "DATABASE_SSL"]],
   [
-    "DISCORD GATEWAY INTENTS",
-    /^HELYX_(?:MESSAGE_CONTENT_ENABLED|GUILD_MEMBERS_ENABLED)$/u,
+    "Commands",
+    [
+      "HELYX_GUILD_COMMAND_WRITES_ENABLED",
+      "HELYX_GUILD_COMMAND_WRITE_SCOPE",
+      "HELYX_GLOBAL_COMMAND_MODE",
+      "HELYX_GUILD_COMMAND_WRITE_GUILD_IDS",
+    ],
   ],
-  ["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,
+    "Modules and dashboard",
+    [
+      "HELYX_MODULE_CATALOGUE_PATH",
+      "HELYX_CLOUD_CONNECT_ENABLED",
+      "HELYX_SHARD_MODE",
+      "LOG_LEVEL",
+    ],
   ],
-  ["DATA ENCRYPTION - KEEP THIS KEY", /^HELYX_DATA_ENCRYPTION_KEY$/u],
-  ["LOGGING", /^LOG_LEVEL$/u],
-  ["SHARDING - ADVANCED", /^HELYX_SHARD_/u],
-  ["MODULE SELECTION", /^HELYX_MODULE_/u],
-  ["CUSTOM SETTINGS", /./u],
+  ["Keep this key unchanged across restarts and updates", [encryptionKey]],
 ];
-const omittedExampleSetting =
-  /^(?:HELYX_AUTOMOD_|HELYX_BOT_CONTROL_|HELYX_HOSTED_MODERATION_ENABLED$|HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS$|HELYX_CLOUD_(?!CONNECT_ENABLED$)|HELYX_OAUTH_|HELYX_STATUS_|CF_ACCESS_|DISCORD_INTERNAL_GUILD_ID$|APPROVED_ROLES$)/u;
+const standardKeys = new Set(environmentGroups.flatMap(([, keys]) => keys));
 const oldHeadings = new Set([
+  "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",
-  "Discord",
-  "Database",
+  "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, { 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 && omittedExampleSetting.test(key) && (template || !record.key)) {
+    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 (omittedExampleSetting.test(key)) delete before[key];
+      if (!standardKeys.has(key)) delete before[key];
   const after = parseEnv(formatted);
   if (
     Object.keys(before).length !== Object.keys(after).length ||
@@ -443,6 +481,7 @@ export async function runWizard({
       validate = () => {},
       fallback,
       optional = false,
+      normalize = (value) => value,
     } = {},
   ) => {
     const current = fallback ?? values[key] ?? "";
@@ -456,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.",
@@ -466,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);
@@ -490,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 (;;) {
@@ -543,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)",
       {
@@ -555,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.",
     );
@@ -687,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),