@helyx/bot 1.3.0 → 1.4.0

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
 

package/documentation/runbooks/backup-and-recovery.md

@@ -1,14 +1,15 @@
 # Backup and recovery runbook
 
-A usable Helyx backup includes PostgreSQL plus the environment and generated
+A usable Helyx backup includes the selected PostgreSQL or MySQL-compatible database plus the environment and generated
 key material required to read encrypted records. A copy of the generated
 project without its database is not a complete backup.
 
 ## Back up
 
-1. Record the installed package lockfile and Helyx release versions.
-2. Create a consistent PostgreSQL backup with your database provider or
-   PostgreSQL tooling.
+1. Preserve `package.json`, `package-lock.json`, `helyx.modules.json` and the
+   matching Helyx release versions. Record the selected database engine.
+2. Create a consistent backup with your database provider or the appropriate
+   engine-specific tooling.
 3. Back up `.env` and generated enrollment or encryption material separately.
 4. Encrypt backups, restrict access, and store at least one copy away from the
    running host.
@@ -25,14 +26,32 @@ At a regular interval:
 2. Restore a selected backup without overwriting production.
 3. Restore the matching environment and key material through the host's secret
    mechanism.
-4. Run `npm ci` and `npm run doctor`.
-5. Confirm a stateful module can read its configuration and records.
+4. Restore the matching project metadata and install that exact release with
+   `npm ci`, or build its Docker image. Run doctor in the disposable environment;
+   Compose users run
+   `docker compose run --rm bot node node_modules/@helyx/cli/dist/cli.js doctor`.
+5. Start the restored bot only with an explicitly authorised test Discord
+   identity and private server. Do not run a second copy with the active bot's
+   token. Confirm a stateful module can read its configuration and records.
 6. Destroy the disposable environment using the same controls as production.
 
 Record the recovery time, the backup generation used, the checks performed,
 and any corrective action. Treat restored data with the same access controls
 and deletion obligations as production data.
 
+Restore into the same database engine with compatible server capabilities.
+Changing `DATABASE_ENGINE` selects an adapter; it does not convert a dump, schema
+or existing installation from PostgreSQL to MySQL or the reverse. Preserve the
+engine identity and migration receipts together with the data.
+
+Use the packages that match the backup's migration history. The current
+fresh-install baselines are not an upgrade path for an older restored database.
+[Contact Helyx support](../guides/privacy-and-support.md#contact-support-safely)
+before attempting that transition; no approved procedure is available yet.
+An updater backup under `.helyx/backups` contains managed project metadata only;
+it cannot restore database contents, encryption keys, container images or
+installed `node_modules`.
+
 ## Incident recovery
 
 Stop writes before a destructive restore. Preserve evidence needed to
@@ -42,7 +61,7 @@ restore over the only production database.
 
 ## Troubleshooting
 
-### PostgreSQL restored but Cloud Connect or protected records fail
+### The database restored but Cloud Connect or protected records fail
 
 Confirm the restored runtime uses the matching data-encryption key and any
 generated enrolment material. Do not replace the key or delete affected rows to