@helyx/bot 0.4.39 → 0.4.40

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.40
+
+### Patch Changes
+
+- Refresh the packaged public guides and operational documentation shipped with the bot.
+
 ## 0.4.39
 
 ### Patch Changes

package/documentation/README.md

@@ -4,6 +4,11 @@ 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)
@@ -11,13 +16,25 @@ inside the matching `@helyx/bot` npm package.
 - [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 behavior remain inside that module.
+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
 

package/documentation/guides/getting-started.md

@@ -1,5 +1,13 @@
 # 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.
@@ -12,21 +20,25 @@ outside source control.
 
 ## Create the project
 
-Install the Helyx CLI, then generate a reviewed starter project using the
-release manifest supplied by Helyx:
+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
-npm install --global @helyx/cli
-helyx self-host init --manifest ./helyx-build.json --output ./helyx --install
+npx --yes @helyx/cli@latest self-host init --manifest ./helyx-build.json --output ./helyx --install
 cd helyx
-helyx setup
+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 login
+## Validate before Discord sign-in
 
 ```sh
 npm run doctor
@@ -47,5 +59,40 @@ 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

@@ -9,7 +9,7 @@ configuration, updates, monitoring, backups, and recovery testing.
 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 behavior.
+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
@@ -38,3 +38,53 @@ installation.
 
 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

@@ -4,6 +4,14 @@ 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:
@@ -14,7 +22,7 @@ Every module needs:
 - 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 behavior, and each declared
+- tests for manifest parity, loading, lifecycle behaviour, and each declared
   contribution.
 
 Dashboard fields need matching configuration validation. Manifest command IDs
@@ -31,7 +39,13 @@ 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 behavior must fail clearly when an optional
+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 behavior.
+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

@@ -25,3 +25,9 @@ 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

@@ -11,7 +11,7 @@ drifting away from executable contributions.
 ## Lifecycle
 
 Call `start`, `health`, and `stop` with a minimal SDK runtime context. Verify
-observable behavior and make both lifecycle functions safe for the runtime to
+observable behaviour and make both lifecycle functions safe for the runtime to
 call. Do not start network listeners or timers at import time.
 
 ## Dashboard
@@ -44,3 +44,9 @@ 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

@@ -3,6 +3,9 @@
 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.
@@ -40,3 +43,29 @@ 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

@@ -39,3 +39,24 @@ 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

@@ -1,5 +1,8 @@
 # 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
@@ -41,8 +44,34 @@ packages to simulate a rollback.
 
 ## Failed validation
 
-Leave the process stopped, retain sanitized logs, and determine whether the
+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.39",
+  "version": "0.4.40",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",