[Feat] Add customizable account-linking help

apps/api/src/handlers/account-link-help.ts

@@ -0,0 +1,17 @@
+import { getDeploymentAccountLinkHelpText } from '@roomote/db/server';
+
+import { apiLogger } from '../logging.js';
+
+export async function appendAccountLinkHelpText(
+  baseMessage: string,
+): Promise<string> {
+  try {
+    const helpText = await getDeploymentAccountLinkHelpText();
+    return helpText ? `${baseMessage} ${helpText}` : baseMessage;
+  } catch (error) {
+    apiLogger.warn(
+      `[account-link] Failed to load deployment help text: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return baseMessage;
+  }
+}

apps/api/src/handlers/ado/handleComment.ts

@@ -313,7 +313,7 @@ export async function handleAdoComment(
     const body =
       targetsResult.status === 'error' &&
       targetsResult.code === 'account_link_required'
-        ? buildSourceControlAccountLinkRequiredMessage('ado')
+        ? await buildSourceControlAccountLinkRequiredMessage('ado')
         : buildReviewerGateMissComment();
 
     await postMentionResponseComment({

apps/api/src/handlers/ado/handleWorkItemComment.ts

@@ -454,7 +454,7 @@ export async function handleAdoWorkItemComment(
     await postWorkItemMentionResponseComment({
       project: projectName,
       workItemId,
-      body: buildSourceControlAccountLinkRequiredMessage('ado'),
+      body: await buildSourceControlAccountLinkRequiredMessage('ado'),
     });
 
     return { status: 'ok', message: 'account_link_required' };

apps/api/src/handlers/bitbucket/handleComment.ts

@@ -261,7 +261,7 @@ export async function handleBitbucketComment(
     await postMentionResponseComment({
       ...mentionResponseTarget,
       body: requiresAccountLink
-        ? buildSourceControlAccountLinkRequiredMessage('bitbucket')
+        ? await buildSourceControlAccountLinkRequiredMessage('bitbucket')
         : requiresEnvironment
           ? buildSourceControlEnvironmentRequiredMessage('bitbucket')
           : buildReviewerGateMissComment(),

apps/api/src/handlers/discord/account-link.ts

@@ -8,6 +8,7 @@ import { Env } from '@roomote/env';
 import { getRedis } from '@roomote/redis';
 
 import { apiLogger } from '../../logging.js';
+import { appendAccountLinkHelpText } from '../account-link-help.js';
 import { replyToDiscordEvent } from './replies.js';
 import type { DiscordChannelContext } from './task-launch.js';
 
@@ -34,17 +35,21 @@ export function buildDiscordAccountLinkFallbackInstruction(): string {
   return `Generate a code under ${formatDiscordLinkedAccountsPath()}, then ${DISCORD_LINK_CODE_INSTRUCTION}.`;
 }
 
-export function buildDiscordLinkRequiredMessage(): string {
-  return `Link your Discord account to Roomote before starting tasks. ${buildDiscordAccountLinkFallbackInstruction()}`;
+export async function buildDiscordLinkRequiredMessage(): Promise<string> {
+  return appendAccountLinkHelpText(
+    `Link your Discord account to Roomote before starting tasks. ${buildDiscordAccountLinkFallbackInstruction()}`,
+  );
 }
 
-export function buildDiscordChannelAutoStartLinkMessage(
+export async function buildDiscordChannelAutoStartLinkMessage(
   channelName: string,
-): string {
-  return [
-    `Roomote watches **#${channelName}** and starts a task for each new message, but your Discord account is not linked to a Roomote account yet, so your message did not start one.`,
-    `Generate a code under ${formatDiscordLinkedAccountsPath()} in Roomote, then reply here with \`/link code:<code>\`.`,
-  ].join('\n\n');
+): Promise<string> {
+  return appendAccountLinkHelpText(
+    [
+      `Roomote watches **#${channelName}** and starts a task for each new message, but your Discord account is not linked to a Roomote account yet, so your message did not start one.`,
+      `Generate a code under ${formatDiscordLinkedAccountsPath()} in Roomote, then reply here with \`/link code:<code>\`.`,
+    ].join('\n\n'),
+  );
 }
 
 // One link DM per user per day across every entry path (mentions, slash
@@ -243,7 +248,7 @@ export async function promptDiscordAccountLink(input: {
       applicationId: input.applicationId,
       channel: input.channel,
       ...(input.interaction ? { interaction: input.interaction } : {}),
-      text: buildDiscordLinkRequiredMessage(),
+      text: await buildDiscordLinkRequiredMessage(),
       ...(input.replyToMessageId
         ? { replyToMessageId: input.replyToMessageId }
         : {}),
@@ -296,7 +301,7 @@ export async function promptDiscordAccountLink(input: {
       );
       await input.provider.postMessage({
         channelId: dmChannel.id,
-        text: buildDiscordLinkRequiredMessage(),
+        text: await buildDiscordLinkRequiredMessage(),
       });
       dmPromptSent = true;
       if (slot === 'claimed') {
@@ -332,7 +337,9 @@ export async function promptDiscordAccountLink(input: {
     text: buildAccountLinkThreadReplyText({
       dmPromptSent,
       accountLabel: DISCORD_ACCOUNT_LABEL,
-      fallbackInstruction: buildDiscordAccountLinkFallbackInstruction(),
+      fallbackInstruction: await appendAccountLinkHelpText(
+        buildDiscordAccountLinkFallbackInstruction(),
+      ),
     }),
     ...(input.replyToMessageId
       ? { replyToMessageId: input.replyToMessageId }

apps/api/src/handlers/discord/channel-auto-start.ts

@@ -81,7 +81,7 @@ async function sendLinkNudgeBestEffort(input: {
     );
     await input.provider.postMessage({
       channelId: dmChannel.id,
-      text: buildDiscordChannelAutoStartLinkMessage(input.channelName),
+      text: await buildDiscordChannelAutoStartLinkMessage(input.channelName),
     });
     await markAccountLinkDmSent(input.discordUserId);
   } catch (error) {

apps/api/src/handlers/gitea/handleComment.ts

@@ -369,7 +369,7 @@ async function handleGiteaIssueComment({
       body:
         targetsResult.status === 'error' &&
         targetsResult.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('gitea')
+          ? await buildSourceControlAccountLinkRequiredMessage('gitea')
           : buildIssueGateMissComment(),
     });
 
@@ -465,7 +465,7 @@ async function handleGiteaPullRequestComment({
       body:
         targetsResult.status === 'error' &&
         targetsResult.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('gitea')
+          ? await buildSourceControlAccountLinkRequiredMessage('gitea')
           : targetsResult.status === 'error' &&
               targetsResult.message.includes('no environment mapping')
             ? buildSourceControlEnvironmentRequiredMessage('gitea')

apps/api/src/handlers/github/handleGitHubIssueComment.ts

@@ -180,7 +180,7 @@ export async function handleGitHubIssueComment(
       ...replyTarget,
       body:
         commenterGate.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('github')
+          ? await buildSourceControlAccountLinkRequiredMessage('github')
           : buildGateMissComment(),
     });
 
@@ -198,7 +198,7 @@ export async function handleGitHubIssueComment(
   if (!target?.properties.userId) {
     await postIssueComment({
       ...replyTarget,
-      body: buildSourceControlAccountLinkRequiredMessage('github'),
+      body: await buildSourceControlAccountLinkRequiredMessage('github'),
     });
 
     return { status: 'ok', message: 'account_link_required' };

apps/api/src/handlers/github/handlePrComment.ts

@@ -1195,7 +1195,7 @@ export async function handlePrComment(
       target: mentionResponseTarget,
       body:
         reviewerGate.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('github')
+          ? await buildSourceControlAccountLinkRequiredMessage('github')
           : buildReviewerGateMissComment(),
     });
 

apps/api/src/handlers/gitlab/handleNote.ts

@@ -293,7 +293,7 @@ async function handleGitLabIssueNote({
       body:
         targetsResult.status === 'error' &&
         targetsResult.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('gitlab')
+          ? await buildSourceControlAccountLinkRequiredMessage('gitlab')
           : buildIssueGateMissNote(),
     });
 
@@ -383,7 +383,7 @@ async function handleGitLabMergeRequestNote({
       body:
         targetsResult.status === 'error' &&
         targetsResult.code === 'account_link_required'
-          ? buildSourceControlAccountLinkRequiredMessage('gitlab')
+          ? await buildSourceControlAccountLinkRequiredMessage('gitlab')
           : buildReviewerGateMissNote(),
     });