@helyx/bot 1.5.4 → 1.7.0

package/dist/server-overview-routes.d.ts

@@ -0,0 +1,4 @@
+import { type ServerOverviewControl } from "@helyx/control-protocol";
+import type { FastifyInstance } from "fastify";
+export declare function registerServerOverviewControlRoutes(server: FastifyInstance, control: ServerOverviewControl): void;
+//# sourceMappingURL=server-overview-routes.d.ts.map

package/dist/server-overview-routes.js

@@ -0,0 +1,41 @@
+import { overviewReadInputSchema, overviewRevokeInputSchema, } from "@helyx/control-protocol";
+import { z } from "zod";
+import { BotControlTransportError } from "./control-errors.js";
+export function registerServerOverviewControlRoutes(server, control) {
+    const actor = z.string().regex(/^\d{17,20}$/u);
+    server.post("/v1/guilds/:guildId/overview", async (request) => {
+        const { guildId } = z
+            .object({ guildId: actor })
+            .strict()
+            .parse(request.params);
+        const raw = z
+            .object({ actorUserId: actor })
+            .passthrough()
+            .parse(request.body);
+        const { actorUserId, ...query } = raw;
+        const input = overviewReadInputSchema.parse({ ...query, guildId });
+        if (query.guildId !== undefined && query.guildId !== guildId)
+            throw new BotControlTransportError(400, "Server scope does not match");
+        if (!control.readServerOverview)
+            throw new BotControlTransportError(503, "Overview is unavailable");
+        return control.readServerOverview({ ...input, actorUserId });
+    });
+    server.post("/v1/guilds/:guildId/overview/invites/revoke", async (request) => {
+        const { guildId } = z
+            .object({ guildId: actor })
+            .strict()
+            .parse(request.params);
+        const raw = z
+            .object({ actorUserId: actor })
+            .passthrough()
+            .parse(request.body);
+        const { actorUserId, ...query } = raw;
+        const input = overviewRevokeInputSchema.parse({ ...query, guildId });
+        if (query.guildId !== undefined && query.guildId !== guildId)
+            throw new BotControlTransportError(400, "Server scope does not match");
+        if (!control.revokeServerOverviewInvite)
+            throw new BotControlTransportError(503, "Invite management is unavailable");
+        return control.revokeServerOverviewInvite({ ...input, actorUserId });
+    });
+}
+//# sourceMappingURL=server-overview-routes.js.map

package/dist/shard-contracts.d.ts

@@ -239,6 +239,28 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"guild.state.get">;
     guildId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    guildId: z.ZodString;
+    operation: z.ZodEnum<{
+        summary: "summary";
+        members: "members";
+        member: "member";
+        invites: "invites";
+    }>;
+    memberId: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodOptional<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    roleId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"guild.overview.read">;
+    actorUserId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    guildId: z.ZodString;
+    code: z.ZodString;
+    confirmed: z.ZodLiteral<true>;
+    kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+    actorUserId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     guildId: z.ZodString;
     userIds: z.ZodArray<z.ZodString>;
@@ -742,6 +764,28 @@ export declare const shardControlRequestSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        operation: z.ZodEnum<{
+            summary: "summary";
+            members: "members";
+            member: "member";
+            invites: "invites";
+        }>;
+        memberId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodOptional<z.ZodBoolean>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        search: z.ZodOptional<z.ZodString>;
+        roleId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"guild.overview.read">;
+        actorUserId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        code: z.ZodString;
+        confirmed: z.ZodLiteral<true>;
+        kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+        actorUserId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         guildId: z.ZodString;
         userIds: z.ZodArray<z.ZodString>;
@@ -1765,6 +1809,28 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"guild.state.get">;
         guildId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        operation: z.ZodEnum<{
+            summary: "summary";
+            members: "members";
+            member: "member";
+            invites: "invites";
+        }>;
+        memberId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodOptional<z.ZodBoolean>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        search: z.ZodOptional<z.ZodString>;
+        roleId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"guild.overview.read">;
+        actorUserId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        guildId: z.ZodString;
+        code: z.ZodString;
+        confirmed: z.ZodLiteral<true>;
+        kind: z.ZodLiteral<"guild.overview.invite.revoke">;
+        actorUserId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         guildId: z.ZodString;
         userIds: z.ZodArray<z.ZodString>;

package/dist/shard-contracts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { overviewReadInputSchema, overviewRevokeInputSchema, } from "@helyx/control-protocol";
 import { discordUserIdentityRequestSchema } from "@helyx/control-protocol/discord-user-identities";
 import { dashboardFieldValidationSchema } from "@helyx/control-protocol/field-validation";
 import { channelAuditModuleIdSchema, channelAuditInputSchema, channelAuditConfigurationSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
@@ -299,6 +300,14 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
     })
         .strict(),
     z.object({ kind: z.literal("guild.state.get"), guildId: snowflake }).strict(),
+    overviewReadInputSchema.safeExtend({
+        kind: z.literal("guild.overview.read"),
+        actorUserId: snowflake,
+    }),
+    overviewRevokeInputSchema.extend({
+        kind: z.literal("guild.overview.invite.revoke"),
+        actorUserId: snowflake,
+    }),
     discordUserIdentityRequestSchema.extend({
         kind: z.literal("guild.user-identities.read"),
     }),
@@ -1107,6 +1116,20 @@ export async function executeShardControlOperation(handler, operation) {
             });
         case "guild.state.get":
             return handler.getGuildState(operation.guildId);
+        case "guild.overview.read": {
+            if (!handler.readServerOverview)
+                throw new Error("Overview is unavailable");
+            const { kind: _kind, ...input } = operation;
+            void _kind;
+            return handler.readServerOverview(input);
+        }
+        case "guild.overview.invite.revoke": {
+            if (!handler.revokeServerOverviewInvite)
+                throw new Error("Invite management is unavailable");
+            const { kind: _kind, ...input } = operation;
+            void _kind;
+            return handler.revokeServerOverviewInvite(input);
+        }
         case "guild.user-identities.read": {
             if (!handler.resolveDiscordUserIdentities)
                 throw new Error("Discord identity lookup is unavailable");

package/dist/shard-coordinator.d.ts

@@ -5,9 +5,9 @@ declare const generationDescriptorSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     applicationId: z.ZodString;
     environment: z.ZodEnum<{
-        production: "production";
         development: "development";
         test: "test";
+        production: "production";
     }>;
     generation: z.ZodString;
     shardCount: z.ZodNumber;

package/dist/shard-router.d.ts

@@ -1,3 +1,4 @@
+import type { OverviewReadInput, OverviewRevokeInput, OverviewResponse } from "@helyx/control-protocol";
 import type { DiscordUserIdentityRequest, DiscordUserIdentityResponse } from "@helyx/control-protocol/discord-user-identities";
 import { type AutoModerationEnhancedResultOutcome, type CreatorOnboardingRequest, type CreatorOnboardingResponse } from "@helyx/sdk";
 import { type BotControlHandler } from "./control-server.js";
@@ -9,6 +10,14 @@ type LocalDispatcher = (shardId: number, request: ShardControlRequest) => Promis
 export declare class ShardControlRouter implements BotControlHandler {
     #private;
     private readonly input;
+    readServerOverview(input: OverviewReadInput & {
+        actorUserId: string;
+    }): Promise<OverviewResponse>;
+    revokeServerOverviewInvite(input: OverviewRevokeInput & {
+        actorUserId: string;
+    }): Promise<{
+        revoked: true;
+    }>;
     creatorOnboarding(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     constructor(input: {
         generation: string;

package/dist/shard-router.js

@@ -11,6 +11,12 @@ const LEASE_VALIDATION_TIMEOUT_MS = 3_000;
 const ECKO_RESULT_TIMEOUT_MS = AUTOMOD_SCANNER_LIMITS.resultAcknowledgementSeconds * 1_000;
 export class ShardControlRouter {
     input;
+    readServerOverview(input) {
+        return this.#route({ kind: "guild.overview.read", ...input });
+    }
+    revokeServerOverviewInvite(input) {
+        return this.#route({ kind: "guild.overview.invite.revoke", ...input });
+    }
     creatorOnboarding(input) {
         return this.#route({
             kind: "creator.onboarding",

package/dist/shard-supervisor.d.ts

@@ -22,7 +22,7 @@ export declare function shardHostedControlCallbacks(router: Pick<ShardControlRou
     deliverHostedServerLeave: (input: {
         operationId: string;
         guildId: string;
-    }) => Promise<"completed" | "requires_review" | "queued" | "not_currently_installed" | "accepted_for_retry">;
+    }) => Promise<"queued" | "completed" | "not_currently_installed" | "accepted_for_retry" | "requires_review">;
     refreshHostedServerOwner: (guildId: string) => Promise<{
         username: string;
         observedAt: string;

package/dist/shard-supervisor.js

@@ -36,6 +36,8 @@ import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
+import { createRuntimeHelpModule } from "./help-runtime.js";
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createPremiumActivationModule } from "./premium-activation-module.js";
 import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
@@ -248,6 +250,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule("shard supervisor");
+        const helpModule = createRuntimeHelpModule(environment);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -267,6 +271,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
+            helpModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -291,6 +297,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
+                    helpModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/shard-worker.d.ts

@@ -63,7 +63,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_OAUTH_ENABLED: boolean;
     HELYX_CLOUD_ENDPOINT: string;
     HELYX_OWNER_USER_IDS: string[];
-    HELYX_SHARD_MODE: "fixed" | "off" | "auto";
+    HELYX_SHARD_MODE: "off" | "auto" | "fixed";
     HELYX_SHARD_SCOPE: "local" | "coordinated";
     HELYX_CLOUD_AUDIT_RETENTION_DAYS: number;
     HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS: number;

package/dist/shard-worker.js

@@ -44,6 +44,8 @@ import { HostedBotInviteGateClient, HostedServerLeaveWorker, HostedServerModerat
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
+import { createRuntimeHelpModule } from "./help-runtime.js";
 import { HttpOAuthService } from "./oauth-service.js";
 import { createLocalScheduledTaskRoute, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
@@ -202,6 +204,8 @@ export async function startShardWorker(processEnvironment = process.env, identit
             : undefined;
         const supportModule = createSupportModule(cloudProxy);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule(`shard worker ${identity.shardId}`);
+        const helpModule = createRuntimeHelpModule(environment);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment
             ? undefined
@@ -221,6 +225,8 @@ export async function startShardWorker(processEnvironment = process.env, identit
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
+            helpModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -244,6 +250,8 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
+                    helpModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/verification-service.d.ts

@@ -21,6 +21,10 @@ export declare class HttpVerificationService implements VerificationService {
     }): Promise<{
         cancelled: number;
     }>;
+    countPendingAttempts(input: {
+        installationId: string;
+        guildId: string;
+    }): Promise<number>;
     listAttempts(input: DashboardAttemptQuery & {
         installationId: string;
         guildId: string;

package/dist/verification-service.js

@@ -82,6 +82,16 @@ export class HttpVerificationService {
         }
         return cancelled;
     }
+    async countPendingAttempts(input) {
+        const result = z
+            .object({ count: z.number().int().nonnegative() })
+            .strict()
+            .parse(await this.#request("/internal/v1/attempts/pending-count", {
+            method: "POST",
+            body: input,
+        }));
+        return result.count;
+    }
     async listAttempts(input) {
         const { installationId, guildId, ...query } = input;
         return dashboardAttemptPageSchema.parse(await this.#request("/internal/v1/attempts/query", {

package/documentation/README.md

@@ -18,6 +18,7 @@ and module guides.
 - [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)
+- [Use Help and optional online matching](guides/help-command.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)

package/documentation/examples/.env.example

@@ -1,89 +1,33 @@
-# REQUIRED — EDIT THESE VALUES
+# Helyx self-hosted environment
+# Keep this file private. Retain the encryption key when updating.
 
-HELYX_RUNTIME_PROFILE=self-hosted
-HELYX_DEPLOYMENT_ENVIRONMENT=self-hosted
+# Runtime
+HELYX_RUNTIME_PROFILE='self-hosted'
+HELYX_DEPLOYMENT_ENVIRONMENT='self-hosted'
+NODE_ENV='production'
 
 # Discord
-DISCORD_TOKEN=replace-me
-DISCORD_CLIENT_ID=12345678901234567
-# Explicit privileged gateway opt-in. Keep false unless a reviewed loaded module
-# requires message content and it is enabled in the Discord developer portal.
-HELYX_MESSAGE_CONTENT_ENABLED=false
-# Enable for loaded member workflows such as Welcome, Access Control or Levels,
-# with Server Members Intent also enabled in the Discord developer portal.
-HELYX_GUILD_MEMBERS_ENABLED=false
-# Database
-# Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.
-DATABASE_ENGINE=postgresql
-DATABASE_URL=postgresql://database:5432/helyx
-DATABASE_SSL=disable
-# Self-host startup applies pending migrations automatically (the default).
-# Hosted-only inspect mode is not a self-host setting; leave this commented.
-# HELYX_DATABASE_STARTUP_MODE=apply
-# Match your provider: disable=no TLS; require=TLS without certificate
-# verification; verify-full=TLS with certificate verification.
-
-# Included Docker database — both password values must match.
-PGUSER=helyx
-PGPASSWORD=replace-with-a-strong-password
-POSTGRES_DB=helyx
-POSTGRES_USER=helyx
-POSTGRES_PASSWORD=replace-with-a-strong-password
-
-# OPTIONAL EVERYDAY SETTINGS
-
-# Ready for dashboard linking, but remains unpaired until you use a one-use code.
-HELYX_CLOUD_CONNECT_ENABLED=true
-# Public dashboard origin used in bot-generated report links.
-# HELYX_DASHBOARD_PUBLIC_URL=https://app.helyx.gg
-# HELYX_OWNER_USER_IDS=12345678901234567
-
-# trace, debug, info, warn, error, fatal or silent
-LOG_LEVEL=info
-
-# SHARDING: OFF BY DEFAULT
-
-# `off` is the compatible self-host default. Keep shard-only values commented
-# in this mode; an empty value is still rejected as configured. MySQL must stay
-# off. Advanced PostgreSQL self-hosting may use `auto` under one
-# supervisor, or `fixed` with a deliberate total count. Local mode never needs
-# Redis. Coordinated multi-host self-hosting is outside the first release.
-HELYX_SHARD_MODE=off
-# HELYX_SHARD_SCOPE=local
-# HELYX_SHARD_COUNT=2
-# HELYX_SHARD_WORKERS_PER_REPLICA=2
-# HELYX_SHARD_REDIS_URL=rediss://private-redis.example:6379
-# HELYX_SHARD_REDIS_NAMESPACE=helyx.self-host
-# HELYX_SHARD_GENERATION=local-20260728
-# HELYX_SHARD_DATABASE_CONNECTION_BUDGET=10
-# HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX=2
-# HELYX_SHARD_WORKER_DATABASE_POOL_MAX=4
-# Redis URL and namespace are intentionally unsupported for the first
-# self-hosted release: do not uncomment them for local auto or fixed mode.
+DISCORD_CLIENT_ID='12345678901234567'
+DISCORD_TOKEN='replace-me'
+HELYX_GUILD_MEMBERS_ENABLED='false'
+HELYX_MESSAGE_CONTENT_ENABLED='false'
 
-# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
-
-# Additional reviewed module packages
-# HELYX_MODULE_PACKAGES=
-
-# Guild command writes remain off until explicitly enabled for known guild IDs.
-# For enabled-module server commands, set writes=true, retain allowlist scope,
-# add comma-separated Discord server IDs below, and use global mode platform-only.
-# See README.md before changing these defaults. Legacy mode still allows globals.
-HELYX_GUILD_COMMAND_WRITES_ENABLED=false
-HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
-# HELYX_GUILD_COMMAND_RELEASE_ID=
-HELYX_GLOBAL_COMMAND_MODE=legacy
-# HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=
-
-# DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT
-
-# Generated module selection
-HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
-
-# Generated privately by npm run setup. Required by Cloud Connect, Giveaways,
-# and Invite Tracking; retain it unchanged across restarts and deployments.
-# HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
-
-# Runtime mode
-NODE_ENV=production
+# Database
+DATABASE_ENGINE='postgresql'
+DATABASE_URL='postgresql://database:5432/helyx'
+DATABASE_SSL='disable'
+
+# Commands
+HELYX_GUILD_COMMAND_WRITES_ENABLED='true'
+HELYX_GUILD_COMMAND_WRITE_SCOPE='allowlist'
+HELYX_GLOBAL_COMMAND_MODE='platform-only'
+HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=''
+
+# Modules and dashboard
+HELYX_MODULE_CATALOGUE_PATH='./helyx.modules.json'
+HELYX_CLOUD_CONNECT_ENABLED='true'
+HELYX_SHARD_MODE='off'
+LOG_LEVEL='info'
+
+# Keep this key unchanged across restarts and updates
+HELYX_DATA_ENCRYPTION_KEY='replace-with-a-base64-encoded-32-byte-key'

package/documentation/guides/help-command.md

@@ -0,0 +1,62 @@
+# Help Command
+
+Use `/help question:your question` to search Helyx's saved FAQ answers. You can
+choose a module or documentation area to narrow the question, for example
+`/help module:Feedback question:The command is not visible`. Use `/help` for a
+short introduction. Replies are private, and Help is available without enabling
+a customer module or purchasing Premium.
+
+Help returns a stored answer, possible FAQ questions to choose from, or a
+documentation link when it cannot find a suitable match. You can also enter a
+six-digit FAQ ID. Answers retain their source and availability labels; a Planned
+or Testing answer does not mean that feature is available. Staff-authored shared
+and Custom answers are labelled separately. Help does not inspect your server
+settings, execute repairs or generate new answers.
+
+## Self-hosted installations
+
+The bot includes an approved FAQ snapshot for local search. Local Help needs no
+Helyx account, Cloud Connect, Cloudflare key, local AI model or internet service.
+The snapshot belongs to the installed release; update the bot to receive a newer
+one. Central suppression or editing cannot change an offline release already on
+your computer. When an enrolled online request fails, self-hosted Help labels
+its local fallback clearly.
+
+Online matching is optional. When available, open your Helyx account's
+self-hosting page and create a Help code. On the bot's host, from the generated
+project folder, run:
+
+```sh
+npx helyx help connect
+npx helyx help status
+npx helyx help disconnect
+```
+
+Read the connection notice and paste the single-use code at the prompt. Codes
+expire after ten minutes; do not put one in a command argument or screenshot.
+The project needs its existing data-encryption key and a writable `.helyx`
+directory. Help saves a separate encrypted credential there. Docker starters
+retain it in their private named volume. Preserve the encryption key when
+restarting; changing it makes the saved credential unreadable.
+
+Status reads only the local file. Disconnect revokes online access when the
+service is reachable and removes the local credential. If remote revocation
+fails, revoke the installation from the account dashboard. A replacement code
+rotates the credential when consumed; account revocation takes effect centrally.
+Neither action disables local Help or requires Cloud Connect.
+
+## Questions and privacy
+
+Online Help sends the question and selected area to Helyx; its embedding
+provider receives the public question text needed for meaning comparison.
+Do not include credentials, private messages or personal details. Self-host
+online requests use a Help installation identity and do not send Discord user
+or server IDs. Hosted requests use trusted member/server identities for limits.
+The service does not store a persistent history of member questions or completed
+question embeddings. Short-lived request counters and Help connection metadata
+are handled through Helyx's privacy system. Providers have their own processing
+terms. See [Privacy and support](privacy-and-support.md).
+
+Shared request and spending limits may make semantic matching temporarily
+unavailable. Hosted Help fails safely to documentation when it cannot verify
+the current collection; self-hosted Help can still use its labelled local copy.

package/documentation/reference/environment.md

@@ -4,7 +4,7 @@ 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.
+the compact `.env.example` contains only the standard installation settings.
 
 ## Required values
 
@@ -12,8 +12,9 @@ the comments in `.env.example` remain the version-matched field reference.
 `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
+provider. PostgreSQL Docker users can run `npm run envbuilder` and select the
+bundled database. That choice adds matching `PGPASSWORD` and `POSTGRES_PASSWORD`
+values and the Docker database/user settings. 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`
@@ -30,7 +31,7 @@ boundary and prevents Hosted-only Helyx Ecko calls from entering the local
 runtime.
 
 Privileged Discord intents, privacy execution, hosted OAuth, status reporting,
-guild command writes, and advanced sharding stay disabled until their complete
+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.
@@ -48,8 +49,8 @@ For enabled-module command builds in approved servers, set
 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.
+template uses `platform-only` and enables guild writes for the server IDs you
+provide. Enter those IDs before starting; leave the allowlist scope in place.
 Do not use the advanced `all` scope merely to bypass an allowlist error.
 
 `HELYX_AUTOMOD_EMBEDDED_WORKERS` controls only the in-process Self-Hosted

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

@@ -22,7 +22,10 @@ below.
 
 1. Download a starter ZIP, or generate it from the builder's reviewed manifest.
 2. Install its dependencies with `npm ci` unless generation used `--install`.
-3. Run `npm run setup`, then complete `.env`. A managed host may supply the
+3. Run `npm run envbuilder` to prepare `.env`, or use `npm run setup` and edit
+   the compact example. For the included Docker PostgreSQL service, use the
+   builder and choose **bundled** so its required database credentials are added.
+   A managed host may supply the
    required values through its protected variables panel instead. Keep the
    generated encryption key stable.
 4. Make the selected database reachable and run doctor through the matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.5.4",
+  "version": "1.7.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -51,15 +51,15 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=1.6.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.9.0 <0.10.0",
-    "@helyx/core": ">=0.2.0 <0.3.0",
-    "@helyx/database": ">=2.5.0 <3.0.0",
+    "@helyx/config": ">=1.7.0 <2.0.0",
+    "@helyx/control-protocol": ">=0.9.1 <0.10.0",
+    "@helyx/core": ">=0.2.3 <0.3.0",
+    "@helyx/database": ">=2.5.1 <3.0.0",
     "@helyx/database-contracts": ">=0.3.0 <0.4.0",
     "@helyx/framework": ">=0.2.0 <0.3.0",
     "@helyx/module-manifest": ">=0.14.0 <0.15.0",
     "@helyx/platform": ">=1.3.0 <2.0.0",
-    "@helyx/sdk": ">=0.17.0 <0.18.0",
+    "@helyx/sdk": ">=0.17.1 <0.18.0",
     "@helyx/status-client": ">=0.3.0 <0.4.0",
     "@helyx/verification-contracts": ">=0.5.0 <0.6.0",
     "discord.js": "14.27.0",