@helyx/bot 0.4.38 → 0.4.40

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.40
+
+### Patch Changes
+
+- Refresh the packaged public guides and operational documentation shipped with the bot.
+
+## 0.4.39
+
+### Patch Changes
+
+- 38c70f7: Ship maintained public documentation with the bot package and point newly generated self-host projects to its version-matched offline copy.
+
 ## 0.4.38
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,11 @@
 
 The Helyx Discord runtime validates its environment, verifies and migrates PostgreSQL, validates explicitly configured module packages, applies their migrations, composes platform services, synchronises guild installations and commands, logs in with the non-privileged Guilds intent, and shuts down Discord, modules, and PostgreSQL safely.
 
+Version-matched public guides, operator runbooks, environment reference
+material, and module-authoring instructions ship at `documentation/README.md`
+inside this npm package. Repository-only `docs/` and `docs-old/` content is not
+published.
+
 Command contributions use an explicit registration policy: platform commands
 remain global, migrated customer commands are projected into enabled guilds,
 deployment commands stay with their deployment, and internal commands are

package/documentation/README.md

@@ -0,0 +1,49 @@
+# Helyx public documentation
+
+This is the portable, versioned documentation set for Helyx operators and
+module authors. It contains only material intended for public release and ships
+inside the matching `@helyx/bot` npm package.
+
+Use the copy shipped with your installed bot when a command, environment value
+or package boundary must match that release. Use
+[docs.helyx.gg](https://docs.helyx.gg/) for the current Hosted Helyx dashboard
+and module guides.
+
+## Start here
+
+- [Install a self-hosted Helyx instance](guides/getting-started.md)
+- [Understand the self-hosting boundary](guides/self-hosting.md)
+- [Configure the environment](reference/environment.md)
+- [Operate installations and upgrades](runbooks/installation-and-upgrades.md)
+- [Plan backup and recovery](runbooks/backup-and-recovery.md)
+- [Handle privacy and support](guides/privacy-and-support.md)
+- [Build an independent module](modules/building-a-module.md)
+- [Test a module](modules/testing-a-module.md)
+- [Prepare a module package](modules/publishing-a-module.md)
+
+The complete working example is published separately as
+`@helyx/module-example`. It is intentionally independent: module-specific
+commands, settings, tests, and lifecycle behaviour remain inside that module.
+
+## Choose the right path
+
+- **Running the generated starter:** begin with
+  [Getting started](guides/getting-started.md), then read the environment,
+  backup and upgrade guides before production use.
+- **Operating local data:** read
+  [Privacy and support](guides/privacy-and-support.md) and document the provider,
+  retention and access controls chosen for your deployment.
+- **Building a module:** start from `@helyx/module-example`, then follow the
+  build, test and packaging guides without importing another module's source.
+
+## Publication boundary
+
+The repository's `docs/` and `docs-old/` trees are internal engineering and
+historical material. They are not part of the bot package. The hosted website
+is also a separate private build workspace. The release process copies only
+this `documentation/` tree into the bot tarball.
+
+Do not place credentials, private infrastructure addresses, incident evidence,
+unannounced plans, or internal deployment instructions here. Before a release,
+run `npm run documentation:check` and `npm run release:dry-run` from the Helyx
+repository root.

package/documentation/examples/.env.example

@@ -0,0 +1,117 @@
+# REQUIRED — EDIT THESE VALUES
+
+# 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 only when member inspection modules are loaded and the Discord Server
+# Members Intent is 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_URL=postgresql://database:5432/helyx
+DATABASE_SSL=disable
+
+# Included Docker database — both password values must match.
+PGUSER=helyx
+PGPASSWORD=replace-with-a-strong-password
+POSTGRES_DB=helyx
+POSTGRES_USER=helyx
+POSTGRES_PASSWORD=replace-with-a-strong-password
+
+# OPTIONAL EVERYDAY SETTINGS
+
+# Ready for dashboard linking, but remains unpaired until you use a one-use code.
+HELYX_CLOUD_CONNECT_ENABLED=true
+# Public dashboard origin used in bot-generated report links.
+# HELYX_DASHBOARD_PUBLIC_URL=https://app.helyx.gg
+# HELYX_OWNER_USER_IDS=12345678901234567
+
+# trace, debug, info, warn, error, fatal or silent
+LOG_LEVEL=info
+
+# Guild-scoped development commands only
+# DISCORD_INTERNAL_GUILD_ID=12345678901234567
+# APPROVED_ROLES=12345678901234567,12345678901234568
+
+# SHARDING: OFF BY DEFAULT
+
+# `off` is the compatible self-host default. Keep shard-only values commented
+# in this mode; an empty value is still rejected as configured. Advanced local
+# self-hosting may use `auto` to obtain Discord's recommendation under one
+# supervisor, or `fixed` with a deliberate total count. Local mode never needs
+# Redis. Coordinated multi-host self-hosting is outside the first release.
+HELYX_SHARD_MODE=off
+# HELYX_SHARD_SCOPE=local
+# HELYX_SHARD_COUNT=2
+# HELYX_SHARD_WORKERS_PER_REPLICA=2
+# HELYX_SHARD_REDIS_URL=rediss://private-redis.example:6379
+# HELYX_SHARD_REDIS_NAMESPACE=helyx.self-host
+# HELYX_SHARD_GENERATION=local-20260728
+# HELYX_SHARD_DATABASE_CONNECTION_BUDGET=10
+# HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX=2
+# HELYX_SHARD_WORKER_DATABASE_POOL_MAX=4
+# Redis URL and namespace are intentionally unsupported for the first
+# self-hosted release: do not uncomment them for local auto or fixed mode.
+
+# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
+
+# Additional reviewed module packages
+# HELYX_MODULE_PACKAGES=
+
+# Private dashboard control endpoint — configure both together
+# HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
+# HELYX_BOT_CONTROL_PORT=3001
+# HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS=900
+
+# Guild command writes remain off until explicitly enabled for known guild IDs.
+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
+
+# Hosted OAuth bridge. Keep disabled unless the API and bot share this secret.
+HELYX_OAUTH_ENABLED=false
+# HELYX_OAUTH_INTERNAL_SECRET=replace-with-a-base64-encoded-32-byte-key
+
+# DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT
+
+# Generated module selection
+HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
+
+# Generated privately by npm run setup. Never change it while Cloud Connect is
+# enrolled or a checkpointed Giveaways draw is in progress.
+# HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
+
+# Official Cloud Connect endpoints
+# HELYX_CLOUD_API_URL=https://api.helyx.gg
+# HELYX_CLOUD_ENDPOINT=wss://connect.helyx.gg/v1/connect
+
+# Security audit retention
+# HELYX_CLOUD_AUDIT_RETENTION_DAYS=90
+# HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS=365
+
+# Optional public status reporting. Keep disabled unless this installation has
+# its own approved Helyx status credentials.
+HELYX_STATUS_ENABLED=false
+# HELYX_STATUS_URL=https://status.helyx.gg
+# HELYX_STATUS_HEARTBEAT_SECRET=replace-with-a-base64-encoded-32-byte-key
+# HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS=60
+# CF_ACCESS_CLIENT_ID=replace-with-access-client-id
+# CF_ACCESS_CLIENT_SECRET=replace-with-access-client-secret
+
+# Runtime mode
+NODE_ENV=production

package/documentation/guides/getting-started.md

@@ -0,0 +1,98 @@
+# Getting started with self-hosted Helyx
+
+Use this guide to generate a reviewed Helyx Self-Hosted project, validate its
+configuration and prove one module works in a private Discord server.
+
+> **Availability:** use the builder as the source of truth. If it does not offer
+> a starter or manifest download, no production Helyx Self-Hosted release is
+> available through the supported flow. Do not assemble one by installing
+> packages manually.
+
+## Requirements
+
+- Node.js 24 or 26 and npm 11 or later.
+- A Discord application and bot token.
+- PostgreSQL with a 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
+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
+private directory and read its generated `README.md`.
+
+For scripted generation, download a build manifest from the same builder and
+use the current CLI:
+
+```sh
+npx --yes @helyx/cli@latest self-host init --manifest ./helyx-build.json --output ./helyx --install
+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).
+
+## Validate before Discord sign-in
+
+```sh
+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.
+
+## Start Helyx
+
+```sh
+npm start
+```
+
+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
+inviting production traffic.
+
+## Complete the Discord setup
+
+1. Create or select an application in the Discord Developer Portal and add its
+   bot user.
+2. Put the application ID and bot token in the protected environment.
+3. Add the bot with the `bot` and `applications.commands` scopes.
+4. Grant only the Discord permissions required by selected modules; Helyx core
+   does not require Administrator.
+5. Start Helyx and wait for its ready result.
+6. Run `/helyx modules` in a private test server where you can manage Helyx.
+7. Enable and configure one installed module, then restart once to confirm its
+   saved state remains available.
+
+Installing a module package and enabling its feature for a Discord server are
+separate actions. Installed customer modules start disabled.
+
+## Troubleshooting
+
+### Doctor cannot reach PostgreSQL
+
+Check the connection URL, credentials, network allowlist and `DATABASE_SSL`
+against the provider's instructions. Do not paste the URL into a support
+request.
+
+### The bot starts but a module is unavailable
+
+Confirm the package appears in `helyx.modules.json`, its installed metadata
+passes `npm run doctor` and it is enabled for that Discord server.
+
+### Helyx cannot act on a channel or role
+
+Check the exact channel/category overrides and place Helyx's role above roles
+it must manage. Administrator is optional and should not be used to hide a
+narrow permission or hierarchy problem.
+
+Next read the [self-hosting guide](self-hosting.md) and the
+[installation and upgrade runbook](../runbooks/installation-and-upgrades.md).

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

@@ -0,0 +1,86 @@
+# Privacy and support for Helyx Self-Hosted
+
+Use this guide to separate locally controlled records from Helyx-hosted data,
+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.
+- **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
+  account records separately.
+
+Cloud Connect does not provide Helyx with unrestricted access to the local
+database. A request submitted to the Helyx Privacy Centre therefore does not
+automatically reach local-only records.
+
+## Handle a local request
+
+1. Confirm the requester through an authorised route without asking them to
+   send a password, token or unrelated identity document.
+2. Record the request scope and the exact local deployment concerned.
+3. Identify the module providers and local operational records that can contain
+   the subject's Discord user ID.
+4. Preserve another person's data, required security evidence and auditable
+   server actions while applying the supported access, correction, restriction
+   or deletion operation.
+5. Include active data and backups in the deployment's documented retention
+   process.
+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.
+
+## Use the Helyx Privacy Centre
+
+For records held by Helyx, use
+[app.helyx.gg/privacy](https://app.helyx.gg/privacy). If Discord sign-in is
+unavailable, email `privacy@helyx.gg`. The central workflow can prepare an
+access export, start erasure with a seven-day cancellation period, accept a
+display-name correction or route a restriction, objection, portability request
+or complaint for review.
+
+## Contact support safely
+
+For an ordinary product or Self-Hosted question, open
+[Helyx Support](https://app.helyx.gg/support). Include the installed Helyx and
+module versions, safe error text, approximate time with timezone, expected
+result and repeatable steps.
+
+Never include:
+
+- `.env` or a database URL;
+- Discord, OAuth, Cloud Connect or status credentials;
+- the data-encryption key;
+- database dumps or unrestricted logs; or
+- unrelated member content.
+
+For a repeatable product fault, use
+[Report a bug](https://app.helyx.gg/report-bug). For a suspected vulnerability,
+use the [private security route](https://helyx.gg/security/) and follow its safe
+testing rules. Modified source, unsupported package combinations and provider
+administration remain outside the normal generated-project support boundary.
+
+## Troubleshooting
+
+### 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.
+
+### A support reply asks for more evidence
+
+Provide the smallest redacted item that answers the question. Do not transmit a
+secret or complete database dump; ask for an authorised route if a file is
+genuinely required.
+
+## Related guides
+
+- [Self-hosting responsibilities](self-hosting.md)
+- [Environment reference](../reference/environment.md)
+- [Backup and recovery](../runbooks/backup-and-recovery.md)
+- [Online Helyx data guides](https://docs.helyx.gg/your-data/)

package/documentation/guides/self-hosting.md

@@ -0,0 +1,90 @@
+# 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
+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
+module boundaries intact: a module must be installable, configurable, testable,
+and removable without relying on unrelated module behaviour.
+
+Helyx supports Docker Compose and direct Node.js operation. The generated
+project is the source of truth for its pinned public packages and module
+catalogue. Do not copy source trees from the Helyx repository into an
+installation.
+
+## Secrets and access
+
+- Store `.env` outside version control and restrict who can read it.
+- Use a dedicated database user and the least privileges supported by your
+  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.
+
+## Operating baseline
+
+- Run `npm run doctor` after configuration or package changes.
+- Watch process health, database capacity, command deployment errors, and module
+  health.
+- Back up both PostgreSQL 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.
+
+Cloud Connect is optional. Enabling it does not transfer responsibility for the
+self-hosted process, database, secrets, or backups to Helyx.
+
+Cloud Connect enrolment is available only when the dashboard offers the
+one-use-code control for a compatible release. Setting the local environment
+switch does not make an unavailable hosted service available.
+
+## Cloud Connect boundary
+
+Generated configuration is ready for Cloud Connect by default but remains
+unpaired. A configured deployment owner or Discord application owner or team
+member creates a one-use code in the Helyx dashboard and enters it with
+`/helyx cloud connect`. Check the result with `/helyx cloud status`.
+
+The connector sends bounded capabilities, health and dashboard
+request/response data over an outbound authenticated connection. It does not
+send the Discord token, database URL or data-encryption key. Local Discord
+features continue if the hosted dashboard is temporarily unavailable.
+
+Set `HELYX_CLOUD_CONNECT_ENABLED=false` before startup when the installation
+must remain entirely local.
+
+## Before production use
+
+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.
+5. Record package versions, log access, monitoring and the responsible owner.
+6. Document how local data access, correction, restriction and deletion will be
+   handled.
+
+## Troubleshooting
+
+### Cloud Connect cannot decrypt its local identity
+
+Restore the original `HELYX_DATA_ENCRYPTION_KEY`. If it cannot be recovered,
+revoke the old installation in the dashboard and enrol a new identity with a
+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.
+
+## Related guides
+
+- [Getting started](getting-started.md)
+- [Environment reference](../reference/environment.md)
+- [Backup and recovery](../runbooks/backup-and-recovery.md)
+- [Privacy and support](privacy-and-support.md)

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

@@ -0,0 +1,51 @@
+# Building an independent Helyx module
+
+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.
+
+## Before you begin
+
+- Use Node.js `>=24 <27` and npm `>=11`.
+- Choose a unique package name and module ID.
+- Decide whether the module is one independently useful feature; do not combine
+  unrelated functions to reduce file count.
+- Choose and state the licence that will govern your independent module.
+
+## Required parts
+
+Every module needs:
+
+- a unique npm package name and semantic version;
+- 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;
+- compiled JavaScript and declarations matching the package exports;
+- tests for manifest parity, loading, lifecycle behaviour, and each declared
+  contribution.
+
+Dashboard fields need matching configuration validation. Manifest command IDs
+must exactly match executable command contributions. Declare Discord
+permissions and privileged capabilities only when the module actually needs
+them.
+
+## Preserve modularity
+
+A module owns its commands, configuration, data, migrations, health, and tests.
+Do not merge unrelated features into one module merely to share code. Put
+reusable contracts in a support package when necessary, and keep each module
+independently installable and usable.
+
+Do not import private Helyx applications, another module's source files, or
+repository-relative configuration. Depend only on published packages with
+compatible version ranges. Module behaviour must fail clearly when an optional
+external service is unavailable.
+
+See [testing a module](testing-a-module.md) before adding product behaviour.
+
+## Related guides
+
+- [Test a module](testing-a-module.md)
+- [Prepare a module for npm](publishing-a-module.md)
+- [`@helyx/module-example` on npm](https://www.npmjs.com/package/@helyx/module-example)

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

@@ -0,0 +1,33 @@
+# Preparing a module for npm
+
+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.
+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.
+4. Use an explicit `files` allowlist. Exclude source maps and TypeScript build
+   caches.
+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.
+8. Search the packed file list for `.env`, credentials, private URLs, logs,
+   dumps, tests with fixtures containing real data, and repository-only notes.
+
+Third-party modules choose and clearly state their own licence. Do not copy the
+Helyx Source Available Licence notice into a third-party module unless that
+licence actually governs the module.
+
+Publishing a package does not make it an official or reviewed Helyx module.
+Catalogue inclusion, security review, permissions, privacy declarations, and
+release support are separate decisions.
+
+## Related guides
+
+- [Build an independent module](building-a-module.md)
+- [Test a module](testing-a-module.md)
+- [`@helyx/module-example` on npm](https://www.npmjs.com/package/@helyx/module-example)

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

@@ -0,0 +1,52 @@
+# Testing a Helyx module
+
+The `@helyx/module-example` suite demonstrates four compatibility layers.
+
+## Manifest and export
+
+Parse `manifest.json`, import the module's default export, and assert that the
+runtime manifest equals the packaged manifest. This prevents metadata from
+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.
+
+## Dashboard
+
+Parse the complete manifest with `@helyx/module-manifest`. Test valid defaults,
+boundary values, wrong types, and missing required settings against the
+module's configuration contribution. Each dashboard setting key must have one
+matching validator field.
+
+## Slash commands
+
+Assert that manifest command IDs and executable command names are identical.
+Build the command with the same Discord.js builders used by Helyx, inspect the
+generated application-command payload, and execute the handler with a fake SDK
+context. Test acknowledgement, context, integration type, option limits, and a
+representative response without contacting Discord.
+
+## Before packaging
+
+Run the module's build and test scripts, then inspect exactly what npm would
+include:
+
+```sh
+npm run build
+npm test
+npm pack --dry-run
+```
+
+The tarball needs compiled exports, declarations, the manifest, instructions,
+licence, and any source or tests deliberately offered as a template. It must
+not contain credentials, logs, source maps, build caches, or internal Helyx
+documentation.
+
+## Related guides
+
+- [Build an independent module](building-a-module.md)
+- [Prepare a module for npm](publishing-a-module.md)
+- [`@helyx/module-example` on npm](https://www.npmjs.com/package/@helyx/module-example)

package/documentation/reference/environment.md

@@ -0,0 +1,71 @@
+# Environment reference
+
+Start from [the published example](../examples/.env.example). The example is a
+copy of the starter emitted by the supported CLI and is checked for drift.
+
+This page explains the ownership and safe defaults of the generated variables;
+the comments in `.env.example` remain the version-matched field reference.
+
+## 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`.
+
+## Safe defaults
+
+Privileged Discord intents, privacy execution, hosted OAuth, status reporting,
+guild command writes, and advanced sharding stay disabled until their complete
+requirements are deliberately configured. An empty variable still counts as a
+configured value in many environments, so leave unused optional lines
+commented.
+
+`HELYX_CLOUD_CONNECT_ENABLED=true` makes an installation ready to be paired; it
+does not pair the installation by itself. Keep official endpoint overrides
+commented unless Helyx support directs otherwise.
+
+## Generated values
+
+The CLI owns `HELYX_MODULE_CATALOGUE_PATH` and may generate
+`HELYX_DATA_ENCRYPTION_KEY`. Preserve generated key material for the lifetime of
+the encrypted data. Losing it can make records unrecoverable; replacing it is
+not a password reset.
+
+## Verification
+
+After every environment change, run:
+
+```sh
+npm run doctor
+```
+
+Never include the real `.env` file in an npm package, container image layer,
+source archive, or support bundle.
+
+## Common failures
+
+### A variable is present but still rejected
+
+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
+
+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.
+
+### Encrypted records fail after deployment
+
+Restore the original `HELYX_DATA_ENCRYPTION_KEY`. Generate it once and preserve
+it; replacing it is not a password reset.
+
+## Related guides
+
+- [Getting started](../guides/getting-started.md)
+- [Self-hosting responsibilities](../guides/self-hosting.md)
+- [Backup and recovery](../runbooks/backup-and-recovery.md)
+- [Privacy and support](../guides/privacy-and-support.md)

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

@@ -0,0 +1,62 @@
+# Backup and recovery runbook
+
+A usable Helyx backup includes PostgreSQL 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.
+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.
+5. Apply a documented retention schedule to both active and backup data.
+
+Never commit a database dump or real environment file to Git and never place it
+inside an npm package.
+
+## Test recovery
+
+At a regular interval:
+
+1. Create a disposable network and a separate empty database.
+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.
+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.
+
+## Incident recovery
+
+Stop writes before a destructive restore. Preserve evidence needed to
+understand the incident, select a known-good backup, restore into a new database
+when possible, validate it, then deliberately switch the runtime. Do not test a
+restore over the only production database.
+
+## Troubleshooting
+
+### PostgreSQL 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
+hide the mismatch.
+
+### Doctor reports a migration checksum mismatch
+
+Restore the reviewed package files that supplied the migration. Never edit an
+applied migration or its history. Preserve the safe migration name and checksum
+for support.
+
+## Related guides
+
+- [Environment reference](../reference/environment.md)
+- [Installation and upgrades](installation-and-upgrades.md)
+- [Self-hosting responsibilities](../guides/self-hosting.md)
+- [Privacy and support](../guides/privacy-and-support.md)

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

@@ -0,0 +1,77 @@
+# Installation and upgrade runbook
+
+Use this runbook for the first start of a generated project and for a reviewed
+release-set update that preserves the local environment and database.
+
+## First installation
+
+1. Generate the project with `helyx self-host init` and a reviewed build
+   manifest.
+2. Copy and complete `.env` with `helyx setup`.
+3. Install dependencies with `npm ci` if they were not installed during
+   generation.
+4. Run `npm run doctor` and resolve every error.
+5. Start the process and confirm database, Discord, and module health.
+6. Exercise one low-risk command in a test server before production use.
+
+## Upgrade
+
+1. Read the release notes and confirm the supported Node.js and npm versions.
+2. Create a current PostgreSQL backup and preserve the existing project
+   metadata and environment file.
+3. Stop the Helyx process cleanly.
+4. Preview the compatible release set:
+
+   ```sh
+   helyx self-host update --check
+   ```
+
+5. Apply it only after reviewing the complete change:
+
+   ```sh
+   helyx self-host update --confirm
+   npm ci
+   npm run doctor
+   ```
+
+6. Start Helyx and verify health, command availability, and one representative
+   workflow for every upgraded module.
+
+The updater backs up managed project metadata under `.helyx/backups` and does
+not change `.env` or customer database data. Database migrations can be
+forward-only. Never edit migration history or downgrade individual Helyx
+packages to simulate a rollback.
+
+## Failed validation
+
+Leave the process stopped, retain sanitised logs, and determine whether the
+failure is configuration, package integrity, database connectivity, or module
+compatibility. If the updater restored managed files, rerun `npm ci` and
+`npm run doctor` before restarting the previous version. Restore data only from
+a tested backup and only when the incident specifically requires it.
+
+## Troubleshooting
+
+### The updater reports an incompatible module
+
+Keep the current working release set. Do not update core, CLI or modules
+independently. Return to the Helyx Self-Hosted builder, keep every current
+module selected and review which compatible set is available.
+
+### The previous managed files were restored
+
+Leave the bot stopped. Run `npm ci` and `npm run doctor` against the restored
+metadata. Restart the previous version only after doctor succeeds; restore data
+only when a tested compatible backup is specifically required.
+
+### A newly installed package is not available in Discord
+
+Confirm it is included in `helyx.modules.json` and enabled for that Discord
+server. Package installation and per-server module activation are separate.
+
+## Related guides
+
+- [Getting started](../guides/getting-started.md)
+- [Environment reference](../reference/environment.md)
+- [Backup and recovery](backup-and-recovery.md)
+- [Privacy and support](../guides/privacy-and-support.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.38",
+  "version": "0.4.40",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -32,6 +32,7 @@
     "dist",
     "!dist/*.tsbuildinfo",
     "!dist/**/*.map",
+    "documentation",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -44,6 +45,7 @@
   },
   "scripts": {
     "build": "tsc -b",
+    "prepack": "node ../../scripts/public-documentation.mjs --sync-bot",
     "dev": "node --env-file-if-exists=../../.env --import tsx src/index.ts",
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },