@helyx/bot 1.3.1 → 1.5.0

package/documentation/examples/.env.example

@@ -10,7 +10,8 @@ DISCORD_CLIENT_ID=12345678901234567
 # 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; increase only after measuring local CPU and memory.
+# 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.
@@ -18,13 +19,19 @@ HELYX_AUTOMOD_EMBEDDED_WORKERS=1
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES=67108864
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD=100
 # HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS=300
-# Enable only when member inspection modules are loaded and the Discord Server
-# Members Intent is enabled in the Discord developer portal.
+# 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
@@ -51,8 +58,8 @@ 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. Advanced local
-# self-hosting may use `auto` to obtain Discord's recommendation under one
+# 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
@@ -80,18 +87,15 @@ HELYX_SHARD_MODE=off
 HELYX_HOSTED_MODERATION_ENABLED=false
 
 # Guild command writes remain off until explicitly enabled for known guild IDs.
+# For enabled-module server commands, set writes=true, retain allowlist scope,
+# add comma-separated Discord server IDs below, and use global mode platform-only.
+# 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=
 
-# Privacy tooling ships with self-hosted Helyx but stays disabled until the
-# dedicated least-privilege executor connection has been configured.
-HELYX_PRIVACY_ENABLED=false
-# HELYX_PRIVACY_EXECUTOR_DATABASE_URL=<dedicated-privacy-executor-postgresql-url>
-# HELYX_PRIVACY_EXECUTOR_DATABASE_SSL=disable
-
 # 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

package/documentation/guides/getting-started.md

@@ -10,9 +10,9 @@ configuration and prove one module works in a private Discord server.
 
 ## Requirements
 
-- Node.js 24 or 26 and npm 11 or later.
+- Node.js `>=24 <27` and npm 11 or later for generation and direct operation.
 - A Discord application and bot token.
-- PostgreSQL with a database you can back up and restore.
+- A supported PostgreSQL or MySQL-compatible database you can back up and restore.
 - Permission to install the bot in the Discord servers you manage.
 
 Keep the bot token, database credentials, encryption keys, and control secrets
@@ -21,8 +21,8 @@ outside source control.
 ## Create the project
 
 The simplest path is to sign in at
-[app.helyx.gg/self-host](https://app.helyx.gg/self-host), choose the Live
-modules you need and download a complete starter ZIP. Extract it into a new
+[app.helyx.gg/self-host](https://app.helyx.gg/self-host), choose the database
+engine and Live modules you need, then download a complete starter ZIP. Extract it into a new
 private directory and read its generated `README.md`.
 
 For scripted generation, download a build manifest from the same builder and
@@ -34,9 +34,20 @@ cd helyx
 npm run setup
 ```
 
-`helyx setup` creates `.env` from `.env.example` only when `.env` does not
-already exist. Edit the required Discord and database values before continuing.
-See the [environment reference](../reference/environment.md).
+`helyx setup` creates `.env` from `.env.example` when needed and fills a missing,
+blank or example data-encryption key. It preserves other existing configuration
+and a non-placeholder key. Edit the required Discord and database values before
+continuing. Direct Node.js users must replace the Docker-only `database`
+hostname with their reachable database address. See the
+[environment reference](../reference/environment.md).
+
+Choose the generated README's Node.js, Docker Compose or managed-hosting path
+before validation. Managed hosts can supply variables without `.env`; generate
+and securely retain the required key once. Docker users build the image and run
+doctor inside Compose, as described in the
+[installation runbook](../runbooks/installation-and-upgrades.md#run-doctor-in-the-right-environment).
+The generated project uses compiled packages, so direct operation needs no
+source build command.
 
 ## Validate before Discord sign-in
 
@@ -44,9 +55,12 @@ See the [environment reference](../reference/environment.md).
 npm run doctor
 ```
 
-The doctor checks configuration, PostgreSQL connectivity, migration history,
-and installed module metadata without logging in to Discord or changing the
-database. Correct every reported error before starting.
+For direct Node.js, doctor checks configuration, selected-database connectivity,
+core migration history and installed module metadata without logging in to
+Discord or changing the database. It inspects module migrations once core
+migrations have no pending entries. Pending migrations on a new database are
+expected; startup applies them and probes server capabilities. Correct every
+reported error before starting.
 
 ## Start Helyx
 
@@ -54,6 +68,9 @@ database. Correct every reported error before starting.
 npm start
 ```
 
+Use this command for direct Node.js. Docker users follow the generated
+Compose start command; managed hosts use their configured `npm start` process.
+
 For a long-running host, use the service or container supervision provided by
 your operating system or hosting platform. Configure automatic restarts with a
 bounded delay, retain logs without secrets, and arrange database backups before
@@ -77,9 +94,9 @@ separate actions. Installed customer modules start disabled.
 
 ## Troubleshooting
 
-### Doctor cannot reach PostgreSQL
+### Doctor cannot reach the database
 
-Check the connection URL, credentials, network allowlist and `DATABASE_SSL`
+Check `DATABASE_ENGINE`, the connection URL, credentials, network allowlist and `DATABASE_SSL`
 against the provider's instructions. Do not paste the URL into a support
 request.
 

package/documentation/guides/privacy-and-support.md

@@ -6,7 +6,7 @@ route a request to the correct owner and ask for help without exposing secrets.
 ## Identify who controls the record
 
 - **Local Helyx Self-Hosted data:** the deployment owner controls the local
-  PostgreSQL database, module records, logs and backups.
+  PostgreSQL or MySQL-compatible database, module records, logs and backups.
 - **Cloud Connect and Helyx account data:** Helyx controls the bounded hosted
   installation, session, support and connector records it receives.
 - **Discord data:** Discord controls platform messages, roles, channels and
@@ -31,9 +31,10 @@ automatically reach local-only records.
 6. Record the outcome without copying unnecessary personal data into support
    logs.
 
-Self-host privacy tooling ships disabled until its dedicated least-privilege
-executor connection is configured. Do not grant the normal bot or a support
-account unrestricted database access as a shortcut.
+The Helyx-hosted **Request my data** export does not read the self-hosted
+database. Self-host operators must handle local-only requests through their
+own access and retention process. Do not grant a support account unrestricted
+database access as a shortcut.
 
 ## Use the Helyx Privacy Centre
 
@@ -70,7 +71,7 @@ administration remain outside the normal generated-project support boundary.
 ### The central export does not contain a local record
 
 This is expected when the record exists only in the deployment owner's
-PostgreSQL database. Contact that owner and follow the local request process.
+selected database. Contact that owner and follow the local request process.
 
 ### A support reply asks for more evidence
 

package/documentation/guides/self-hosting.md

@@ -1,13 +1,14 @@
 # Self-hosting responsibilities
 
 Self-hosting gives you control of the Helyx runtime and its data. It also makes
-you responsible for the host, PostgreSQL, Discord credentials, environment
+you responsible for the host, selected database, Discord credentials, environment
 configuration, updates, monitoring, backups, and recovery testing.
 
 ## Supported shape
 
-A normal installation contains one generated Helyx project, one PostgreSQL
-database, the reviewed core packages, and independently selected modules. Keep
+A normal installation contains one generated Helyx project, one PostgreSQL or
+supported MySQL-compatible database, the reviewed core packages, and
+independently selected modules. Keep
 module boundaries intact: a module must be installable, configurable, testable,
 and removable without relying on unrelated module behaviour.
 
@@ -26,7 +27,7 @@ installation.
 ### Enhanced Auto Moderation resources
 
 Enhanced Auto Moderation remains inside the existing bot process and uses the
-installation's existing PostgreSQL database. It does not require Helyx Ecko,
+installation's selected database. It does not require Helyx Ecko,
 Redis, another bot, another database, a public endpoint or a Premium heartbeat.
 Standard mode starts no scanning worker.
 
@@ -39,7 +40,7 @@ coverage; it does not make unsafe actions on delayed content. Use `npm run docto
 after environment changes and the dashboard module-health view for diagnosis.
 
 Every implemented catalogue entry carries a manifest-backed deployment label
-and credential-risk label. A planned entry without a canonical v0.4 manifest
+and credential-risk label. A planned entry without a classified supported manifest
 is explicitly `unclassified`; that label makes no promise about its future
 deployment support and it cannot be selected. The builder accepts only Live
 modules whose
@@ -56,7 +57,7 @@ downloaded manifest.
   deployment.
 - Rotate a Discord token or control secret if it may have been exposed.
 - Do not paste secret values into logs, issues, screenshots, or support chats.
-- Limit network access to PostgreSQL and private control endpoints.
+- Limit network access to the database and private control endpoints.
 
 ## Operating baseline
 
@@ -64,11 +65,13 @@ downloaded manifest.
 - Watch process health, database capacity, command deployment errors, and module
   health. When Enhanced Auto Moderation is active, also watch CPU, memory,
   scanner queue pressure and Standard-fallback guidance.
-- Back up both PostgreSQL and the environment or key material needed to decrypt
+- Back up both the selected database and the environment or key material needed to decrypt
   its records.
 - Test recovery in a disposable environment.
 - Apply compatible releases as one reviewed set; do not upgrade internal Helyx
-  packages independently.
+  packages independently. Check the
+  [fresh-install release boundary](../runbooks/installation-and-upgrades.md#check-the-release-boundary-first)
+  before using the updater on an existing database.
 
 Cloud Connect is optional. Enabling it does not transfer responsibility for the
 self-hosted process, database, secrets, or backups to Helyx.
@@ -97,7 +100,7 @@ must remain entirely local.
 1. Prove `npm run doctor` from the production environment.
 2. Test one stateful module in a private server.
 3. Restart the process and confirm settings remain available.
-4. Create and test a PostgreSQL restore in a disposable environment.
+4. Create and test a restore of the selected database in a disposable environment.
 5. Record package versions, log access, monitoring and the responsible owner.
 6. Document how local data access, correction, restriction and deletion will be
    handled.
@@ -113,8 +116,10 @@ fresh one-use code.
 ### A hosting provider cannot run the starter
 
 The provider must support the release's Node.js and npm versions, run
-`npm start`, preserve protected environment values and reach PostgreSQL. A
-provider that cannot meet those requirements is not a supported runtime path.
+`npm start`, preserve protected environment values and reach the selected
+database. MySQL-compatible deployments must also support unsharded operation
+with `HELYX_SHARD_MODE=off`. A provider that cannot meet those requirements is
+not a supported runtime path.
 
 ## Related guides
 

package/documentation/modules/auto-moderation.md

@@ -1,10 +1,10 @@
 # Auto Moderation module
 
-Auto Moderation is an unpublished Testing module that manages Helyx-owned Discord Auto Moderation rules and optional Enhanced matching. It supports Hosted and Self-Hosted Helyx, but version `1.0.0` must be explicitly included in a reviewed test composition and is not available from the public npm catalogue.
+Auto Moderation is a published module that manages Helyx-owned Discord Auto Moderation rules and optional Enhanced matching. It supports Hosted and Self-Hosted Helyx; include it in the selected self-host module composition before enabling its features.
 
 ## Supported Self-Hosted shape
 
-Use the same Helyx bot process and PostgreSQL database as the rest of the installation. Standard mode starts no content-scanning worker. Enhanced starts a bounded worker pool inside the bot process. Self-hosters do not deploy Helyx Ecko, Redis, a second bot connection or any Helyx-hosted scanner.
+Use the same Helyx bot process and configured PostgreSQL or MySQL-compatible database as the rest of the installation. Standard mode starts no content-scanning worker. Enhanced starts a bounded worker pool inside the bot process. Self-hosters do not deploy Helyx Ecko, Redis, a second bot connection or any Helyx-hosted scanner.
 
 The matching engine is the deliberate `@helyx/module-automod/engine` package export. Hosted Ecko and the embedded worker use the same versioned engine and result contract; module code remains free of Discord.js, database, network and environment access.
 
@@ -28,7 +28,7 @@ Size the bot for actual Enhanced traffic and begin with Balanced confidence. Wat
 
 ## Data and privacy
 
-PostgreSQL stores logical rules, Discord mapping/fingerprint, structural action receipts, durable enforcement claims and anonymous daily counts. It never stores matched content, matched terms, bodies, attachments, embeds or transient evidence. Native receipts expire after 90 days; settled claim/count history is bounded to 365 days.
+The selected database stores logical rules, Discord mapping/fingerprint, structural action receipts, durable enforcement claims and anonymous daily counts. It never stores matched content, matched terms, bodies, attachments, embeds or transient evidence. Native receipts expire after 90 days; settled claim/count history is bounded to 365 days.
 
 Discord native alerts and optional Moderation violation-thread evidence are Discord-owned content. Restrict those channels separately. Logging, Audit, metrics and traces must remain content-free.
 
@@ -40,8 +40,10 @@ The module is unhealthy when required records, configuration, installation, Disc
 
 ## Verify a test installation
 
-1. Confirm the private Testing module is present in the test catalogue.
-2. Apply migrations with the migration role and start the bot with Standard.
+1. Confirm the Live Auto Moderation module is selected in the installation's catalogue.
+2. Start the bot with Standard and verify its engine-matched module migrations
+   and health. Normal startup applies pending supported migrations; do not run
+   SQL manually or rewrite receipts to bypass a failure.
 3. Publish one fictional native rule and verify block/alert plus a content-free receipt.
 4. Enable Message Content, switch to Enhanced and test one obfuscated phrase plus one safe near-match.
 5. Restart the bot and confirm snapshots rebuild without retained message content.

package/documentation/modules/building-a-module.md

@@ -4,6 +4,12 @@ Start from the published `@helyx/module-example` package. It contains a
 self-contained TypeScript project, manifest, source, tests, and packaging
 allowlist that can be copied into a new repository or workspace.
 
+The current Example demonstrates the supported v0.4 compatibility contract.
+New modules must adopt the complete v0.5 contract described below; changing only
+`manifestVersion` is insufficient. Install dependencies in the copied project
+before building: use `npm install` if it has no lockfile, then retain the generated
+lockfile and use `npm ci` for repeatable installations.
+
 ## Before you begin
 
 - Use Node.js `>=24 <27` and npm `>=11`.
@@ -20,7 +26,8 @@ Every module needs:
 - a Helyx module manifest parsed by `@helyx/module-manifest`;
 - a default JavaScript export created with `defineModule` from `@helyx/sdk`;
 - explicit `start` and `stop` lifecycle functions;
-- a privacy declaration and provider, including when no personal data is held;
+- an explicit privacy declaration and matching executable provider, including
+  a zero-record provider when no personal data is retained;
 - compiled JavaScript and declarations matching the package exports;
 - tests for manifest parity, loading, lifecycle behaviour, and each declared
   contribution.
@@ -32,12 +39,20 @@ them.
 
 ## Deployment and credential policy
 
-Use manifest version `0.4` and make deployment eligibility explicit:
+Use manifest version `0.5` and make deployment eligibility explicit:
 
 - `deploymentSupport` is `hosted`, `self-hosted` or `both`;
 - `credentialRisk` is `none`, `low`, `medium`, `high` or `very-high`; and
 - `deploymentReason` is a short internal explanation with no secret values.
 
+Declare the module classification, `features` and `permissionOperations` too.
+A module without reviewed features uses an empty `features` array. A v0.5
+dashboard needs a declared `settingsMutationPermissionId`; settings need explicit
+`supportVisibility`, and actions need declared permission IDs. Keep executable
+permission defaults and handlers aligned with those declarations. Refer to the
+installed `@helyx/module-manifest` README and exported schema rather than copying
+an older manifest and changing its version string.
+
 The classification is a release decision, not a runtime guess. A hosted-only
 manifest is rejected from self-host selection and generated projects. A
 self-host-only manifest is rejected from hosted composition. The separate
@@ -49,6 +64,25 @@ must not require a provider credential or separate integration service. If a
 future design changes that boundary, review the deployment and credential risk
 before implementation; do not weaken the manifest to make composition pass.
 
+## Database support
+
+Declare the supported `databaseEngines` in the manifest, using `postgresql` and
+`mysql`. Do not advertise an engine before its migrations and runtime behaviour
+are supported. Deployment eligibility and database support are separate: adding
+MySQL support does not make a hosted-only module eligible for self-hosting.
+
+Use SDK database/record capabilities for portable runtime work, not private
+application repositories or a direct driver embedded in each module. Keep
+module-owned PostgreSQL migrations in `migrations/` and the MySQL equivalents
+in `migrations-mysql/`. Preserve the same field meanings, nullability and
+returned JavaScript types; equivalent SQL does not require identical SQL syntax.
+Keep engine-specific implementation details behind the adapter contract.
+
+Do not rewrite an already-applied migration. A fresh unpublished baseline can
+be consolidated only through the agreed release process, with clean/repeat
+installation evidence. See the database-backed section of
+[testing a module](testing-a-module.md) for ownership and selective test gates.
+
 ## Commands and dashboard policy
 
 Normal customer-module commands use
@@ -78,6 +112,18 @@ repository-relative configuration. Depend only on published packages with
 compatible version ranges. Module behaviour must fail clearly when an optional
 external service is unavailable.
 
+Keep `start` and `stop` even when they simply return resolved promises. The
+`health` hook is optional; implement it when there is meaningful owned runtime
+state or a dependency to report. A zero-personal-data module declares
+`containsPersonalData: false`, a provider version and an empty collection list;
+the bot loader still requires a matching executable provider. The Example leaves
+that contribution unregistered, so compose its supplied privacy helper into
+`defineModule` before a copied module is installed in the bot. Use
+`getModulePrivacyDeclaration` and `createPrivacyProvider` from the SDK to keep the
+provider identity, version and declaration in parity. The SDK supplies the
+zero-data `not_applicable` outcomes. A personal-data module must implement access
+and erasure for its retained records, including while disabled.
+
 See [testing a module](testing-a-module.md) before adding product behaviour.
 
 ## Related guides

package/documentation/modules/moderation.md

@@ -1,10 +1,10 @@
 # Moderation module
 
-Moderation is an unpublished Testing module for accountable Discord staff actions. It supports Hosted and Self-Hosted Helyx, but version `1.0.0` must be explicitly included in a reviewed test composition and is not available from the public npm catalogue.
+Moderation is a published module for accountable Discord staff actions. It supports Hosted and Self-Hosted Helyx; include it in the selected self-host module composition before enabling its features.
 
 ## Supported Self-Hosted shape
 
-Run the normal Helyx bot process and PostgreSQL only. Moderation needs no Redis, scanner service, Cloud Connect or Helyx-hosted dependency. Install its migrations through the normal reviewed module lifecycle; never run migration credentials in the bot process.
+Run the normal Helyx bot process with the configured PostgreSQL or MySQL-compatible database adapter. Moderation needs no Redis, scanner service, Cloud Connect or Helyx-hosted dependency. Normal startup applies its engine-matched migrations through the reviewed module lifecycle. Supply only the database privileges needed by the supported installation procedure; do not give the bot an unrelated provider administrator account.
 
 ## Discord setup
 
@@ -22,7 +22,7 @@ Kick, ban, demotion, unban and timeouts longer than 24 hours require an actor-bo
 
 The module creates a pending numbered case and immutable attempt before changing Discord. An ambiguous outcome enters Review and must be reconciled from current Discord state; do not blindly repeat the action. Warning DMs and violation-thread delivery are secondary and cannot roll back a successful case.
 
-PostgreSQL stores case, action, identity, safe outcome and Discord-reference metadata. It does not store offending message bodies. Transient evidence can be copied directly to a Discord-owned private thread with mentions disabled and is never persisted or queued.
+The selected database stores case, action, identity, safe outcome and Discord-reference metadata. It does not store offending message bodies. Transient evidence can be copied directly to a Discord-owned private thread with mentions disabled and is never persisted or queued.
 
 Settled retention is configurable from 30 to 730 days. Dashboard disassociation clears the subject and future repeat-count association while preserving an anonymous tombstone. It is not hard deletion or Privacy Service erasure.
 
@@ -32,8 +32,8 @@ Health is unhealthy while the module is stopped or a required platform boundary
 
 ## Verify a test installation
 
-1. Confirm the module is private, Testing and explicitly selected in the test catalogue.
-2. Apply the current database baseline and module migrations with the migration role.
+1. Confirm the Live Moderation module is selected in the installation's catalogue.
+2. Run doctor to check configuration, database access and migration history.
 3. Start the bot and verify module health.
 4. Test a warning, a confirmed high-impact action, a hierarchy rejection and a case history read with fictional accounts.
 5. Exercise channel inspection, one private violation thread, staff-control denial for the affected user and safe Close visibility.

package/documentation/modules/publishing-a-module.md

@@ -3,8 +3,9 @@
 This checklist prepares a package for review. It does not authorize publishing
 to npm or adding a module to the official Helyx catalogue.
 
-1. Choose a unique package name and keep the package version equal to the
-   manifest version.
+1. Choose a unique package name and keep `package.json`'s `version` equal to
+   `manifest.json`'s package `version`. That value is separate from the manifest
+   schema's `manifestVersion`, which is `0.5` for new modules.
 2. Use compatible ranges for `@helyx/module-manifest` and `@helyx/sdk`.
 3. Compile to `dist/` and expose both a JavaScript default entry and a `.d.ts`
    declaration entry.
@@ -13,8 +14,9 @@ to npm or adding a module to the official Helyx catalogue.
 5. Include `manifest.json`, `README.md`, `CHANGELOG.md`, and the licence that
    applies to your code.
 6. Run the complete test suite and `npm pack --dry-run` from a clean checkout.
-7. Extract the generated tarball into a temporary project and import its default
-   export under a supported Node.js version.
+7. Run `npm pack` to create a local `.tgz` file; `--dry-run` does not create one.
+   Install that file in a temporary project and import its default export under
+   a supported Node.js version. This does not publish to npm.
 8. Search the packed file list for `.env`, credentials, private URLs, logs,
    dumps, tests with fixtures containing real data, and repository-only notes.
 

package/documentation/modules/testing-a-module.md

@@ -10,9 +10,11 @@ drifting away from executable contributions.
 
 ## Lifecycle
 
-Call `start`, `health`, and `stop` with a minimal SDK runtime context. Verify
-observable behaviour and make both lifecycle functions safe for the runtime to
-call. Do not start network listeners or timers at import time.
+Call the required `start` and `stop` functions with a minimal SDK runtime context.
+Test `health` only when the module supplies that optional hook. Verify observable
+behaviour and make lifecycle functions safe for the runtime to call. No-op
+lifecycle functions are valid when the module owns no runtime resources. Do not
+start network listeners or timers at import time.
 
 ## Dashboard
 
@@ -41,12 +43,45 @@ stale command may still be visible during Discord reconciliation.
 
 ## Privacy and multi-worker behaviour
 
-Test the privacy declaration and executable provider together. A provider must
+For a zero-personal-data module, verify the explicit declaration and empty
+collection list together with its matching zero-record executable provider. The
+bot loader requires that contribution for manifest v0.2 and later, even though
+the Example source does not register it. Test provider identity, version and
+declaration parity before bot installation. For a module that retains personal
+data, test its declaration and executable provider together. A provider must
 find matching retained records even when its module is disabled, and a missing
 or failed provider must not be interpreted as an empty result. Stateful
 modules also test duplicate delivery, concurrent claims, retry, restart and
 stale-worker behaviour where those failures are possible.
 
+## Database-backed behaviour
+
+Keep tests with the module that owns the behaviour. For a module supporting both
+engines, use a shared, non-discovered `tests/database.contract.ts` and separate
+`tests/database.postgresql.integration.test.ts` and
+`tests/database.mysql.integration.test.ts` entry files. Adapter-specific tests
+belong to that adapter, not to another module or a batch-named test file.
+
+The shared contract should exercise important observable guarantees, such as a
+successful write/read, a revision conflict, duplicate delivery or a fenced
+refund. Do not copy every PostgreSQL SQL-text assertion into MySQL or repeat a
+module's entire contract in the core adapter suite. Keep engine-specific checks
+where the implementation genuinely differs, including MySQL interrupted-DDL
+receipts and PostgreSQL transaction or legacy-migration behaviour.
+
+Use a disposable test database on an explicitly authorised server. Integration
+fixtures can drop their tables; never point them at an active bot installation.
+Check clean and repeat migration application and the actual returned types:
+numbers, booleans, arrays, dates and nullable values must satisfy the same SDK
+contract on both engines. A MySQL-compatible server is accepted by the required
+capabilities, not by its vendor name. Oracle MySQL and MariaDB are reference
+gates, not an exhaustive compatibility promise.
+
+In the Helyx workspace, PostgreSQL and MySQL integration files run in separate
+`test:database:postgresql` and `test:database:mysql` suites. Run the narrow relevant suite first;
+reserve whole-workspace validation for cross-cutting or release gates. Add a
+test for a material unprotected guarantee, not merely because a file changed.
+
 ## Before packaging
 
 Run the module's build and test scripts, then inspect exactly what npm would

package/documentation/reference/environment.md

@@ -9,10 +9,18 @@ the comments in `.env.example` remain the version-matched field reference.
 ## Required values
 
 `DISCORD_TOKEN` is the bot token from the Discord developer portal.
-`DISCORD_CLIENT_ID` is the application's numeric ID. `DATABASE_URL` points to
-PostgreSQL; `DATABASE_SSL` must match the database provider. Docker users must
-also replace the example PostgreSQL password consistently in `PGPASSWORD` and
-`POSTGRES_PASSWORD`.
+`DISCORD_CLIENT_ID` is the application's numeric ID. `DATABASE_ENGINE` accepts
+`postgresql` or `mysql` and defaults to PostgreSQL when omitted. `DATABASE_URL`
+must match the selected engine, and `DATABASE_SSL` must match the database
+provider. PostgreSQL Docker users must also replace the example password
+consistently in `PGPASSWORD` and `POSTGRES_PASSWORD`. The MySQL Compose starter
+runs only the bot and connects to the external database in `DATABASE_URL`.
+
+Percent-encode special characters in URL credentials. `DATABASE_SSL=disable`
+uses no TLS; `require` encrypts without verifying the server certificate;
+`verify-full` also verifies the certificate. Prefer `verify-full` for remote
+connections when the provider's certificate is trusted. The MySQL template's
+initial `require` value is not proof of that provider's requirements.
 
 ## Safe defaults
 
@@ -27,6 +35,23 @@ requirements are deliberately configured. An empty variable still counts as a
 configured value in many environments, so leave unused optional lines
 commented.
 
+Enable privileged intents in the Discord Developer Portal as well as the bot
+environment when required: Counting needs Message Content, Welcome and Access
+Control need Guild Members, and Levels needs both. Access Control's Password
+Entry also needs Message Content. The corresponding variables are
+`HELYX_MESSAGE_CONTENT_ENABLED` and `HELYX_GUILD_MEMBERS_ENABLED`.
+
+For enabled-module command builds in approved servers, set
+`HELYX_GUILD_COMMAND_WRITES_ENABLED=true`, keep
+`HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist`, and set
+`HELYX_GUILD_COMMAND_WRITE_GUILD_IDS` to a non-empty comma-separated list of
+Discord server IDs. Use `HELYX_GLOBAL_COMMAND_MODE=platform-only` to retain global
+core/deployment commands while feature commands use per-server builds. Restart
+after changing these values and check the dashboard command-build status. The
+template's default `legacy` mode can still register compatible globals while
+guild writes are disabled; it does not mean that every command is disabled.
+Do not use the advanced `all` scope merely to bypass an allowlist error.
+
 `HELYX_AUTOMOD_EMBEDDED_WORKERS` controls only the in-process Self-Hosted
 Enhanced Auto Moderation pool. Keep the default of one unless local measurement
 justifies a value from two through four. Its queue settings may be lowered but
@@ -46,12 +71,19 @@ not a password reset.
 
 ## Verification
 
-After every environment change, run:
+After every environment change, run doctor in the same environment that will
+start the bot. For direct Node.js or a managed host console:
 
 ```sh
 npm run doctor
 ```
 
+For Compose, build the bot image and run
+`docker compose run --rm bot node node_modules/@helyx/cli/dist/cli.js doctor`
+with its database reachable. Container-only hostnames such as `database` are not
+host-shell addresses. See the
+[runtime-specific steps](../runbooks/installation-and-upgrades.md#run-doctor-in-the-right-environment).
+
 Never include the real `.env` file in an npm package, container image layer,
 source archive, or support bundle.
 
@@ -63,11 +95,13 @@ An empty environment variable counts as configured in many hosts. Remove
 unused optional values instead of setting them to an empty string. Replace all
 required placeholders with real protected values.
 
-### PostgreSQL works locally but not on the host
+### The database works locally but not on the host
 
-Check network access and `DATABASE_SSL` using the database provider's required
-mode. The Docker default is for the included private container network and must
-not be copied blindly to an Internet database.
+Check that `DATABASE_ENGINE` matches `DATABASE_URL`, then check network access
+and `DATABASE_SSL` using the database provider's required mode. The PostgreSQL
+Docker default is for the included private container network and must not be
+copied blindly to an Internet database. MySQL-compatible self-hosting requires
+`HELYX_SHARD_MODE=off`.
 
 ### Encrypted records fail after deployment