cli-jaw 2.2.10 → 2.2.12

package/public/js/features/settings-slack.ts

@@ -1,22 +1,78 @@
 // ── Slack Settings ──
-import { apiJson } from '../api.js';
+import { api, apiJson } from '../api.js';
+import { openSetupGuideIfUnconfigured } from './channel-setup-guide.js';
+import { hasSlackBotTokenPrefix, hasSlackAppTokenPrefix } from './channel-setup-rules.js';
+import { t } from './i18n.js';
 import type { SettingsData } from './settings-types.js';
 
+// ── Guided setup card ──
+// One-time bindings for the Slack setup card in settings: manifest copy,
+// app-page shortcut, and inline token-prefix validation (error below the
+// field, cleared once the value looks right — form-patterns on-blur timing).
+let setupGuideBound = false;
+
+export function initSlackSetupGuide(): void {
+    if (setupGuideBound) return;
+    setupGuideBound = true;
+
+    document.getElementById('slack-copy-manifest')?.addEventListener('click', async (ev) => {
+        const btn = ev.currentTarget as HTMLButtonElement;
+        try {
+            const json = await api<{ yaml?: string }>('/api/slack/manifest');
+            const yaml = json?.yaml || '';
+            if (!yaml) throw new Error('empty manifest');
+            await navigator.clipboard.writeText(yaml);
+            const original = btn.textContent || '';
+            btn.textContent = t('settings.slack.guide.copyManifestDone');
+            setTimeout(() => { btn.textContent = original; }, 2000);
+        } catch {
+            btn.textContent = t('settings.slack.guide.copyManifestFail');
+            setTimeout(() => { btn.textContent = t('settings.slack.guide.copyManifest'); }, 2500);
+        }
+    });
+
+    document.getElementById('slack-open-apps')?.addEventListener('click', () => {
+        window.open('https://api.slack.com/apps?new_app=1', '_blank', 'noopener');
+    });
+
+    bindPrefixValidation('slBotToken', 'slack-bot-token-error', hasSlackBotTokenPrefix);
+    bindPrefixValidation('slAppToken', 'slack-app-token-error', hasSlackAppTokenPrefix);
+}
+
+function bindPrefixValidation(inputId: string, errorId: string, valid: (v: string) => boolean): void {
+    const input = document.getElementById(inputId) as HTMLInputElement | null;
+    const error = document.getElementById(errorId);
+    if (!input || !error) return;
+    const check = (): void => {
+        const bad = input.value.trim().length > 0 && !valid(input.value);
+        error.style.display = bad ? '' : 'none';
+        input.classList.toggle('input-error', bad);
+    };
+    // On blur only until the first error appears; then live, so correcting
+    // the paste clears the error immediately.
+    input.addEventListener('blur', check);
+    input.addEventListener('input', () => {
+        if (error.style.display !== 'none') check();
+    });
+}
+
 export async function saveSlackSettings(): Promise<void> {
     const botToken = (document.getElementById('slBotToken') as HTMLInputElement)?.value.trim() || '';
     const appToken = (document.getElementById('slAppToken') as HTMLInputElement)?.value.trim() || '';
     const teamId = (document.getElementById('slTeamId') as HTMLInputElement)?.value.trim() || '';
     const channelIdsRaw = (document.getElementById('slChannelIds') as HTMLInputElement)?.value.trim() || '';
+    const attachPort = (document.getElementById('slAttachPort') as HTMLInputElement)?.value.trim() || '';
     const channelIds = channelIdsRaw
         ? channelIdsRaw.split(',').map(s => s.trim()).filter(Boolean)
         : [];
-    await apiJson('/api/settings', 'PUT', { slack: { botToken, appToken, teamId, channelIds } });
+    await apiJson('/api/settings', 'PUT', { slack: { botToken, appToken, teamId, channelIds, attachPort } });
 }
 
 export async function setSlack(enabled: boolean): Promise<void> {
     document.getElementById('slOn')?.classList.toggle('active', enabled);
     document.getElementById('slOff')?.classList.toggle('active', !enabled);
     await apiJson('/api/settings', 'PUT', { slack: { enabled } });
+    if (enabled) openSetupGuideIfUnconfigured('slack');
 }
 
 export async function setSlackForwardAll(enabled: boolean): Promise<void> {
@@ -56,6 +112,8 @@ export function loadSlackSettings(s: SettingsData): void {
     if (sc.teamId && teamId) teamId.value = sc.teamId;
     const channelIds = document.getElementById('slChannelIds') as HTMLInputElement | null;
     if (sc.channelIds?.length && channelIds) channelIds.value = sc.channelIds.join(', ');
+    const attachPort = document.getElementById('slAttachPort') as HTMLInputElement | null;
+    if (attachPort) attachPort.value = sc.attachPort || '';
     const fwdOn = sc.forwardAll !== false;
     document.getElementById('slForwardOn')?.classList.toggle('active', fwdOn);
     document.getElementById('slForwardOff')?.classList.toggle('active', !fwdOn);

package/public/js/features/settings-telegram.ts

@@ -1,5 +1,6 @@
 // ── Telegram Settings ──
 import { apiJson } from '../api.js';
+import { openSetupGuideIfUnconfigured } from './channel-setup-guide.js';
 import type { SettingsData } from './settings-types.js';
 
 export async function saveTelegramSettings(): Promise<void> {
@@ -15,6 +16,7 @@ export async function setTelegram(enabled: boolean): Promise<void> {
     document.getElementById('tgOn')?.classList.toggle('active', enabled);
     document.getElementById('tgOff')?.classList.toggle('active', !enabled);
     await apiJson('/api/settings', 'PUT', { telegram: { enabled } });
+    if (enabled) openSetupGuideIfUnconfigured('telegram');
 }
 
 export async function setForwardAll(enabled: boolean): Promise<void> {

package/public/js/features/settings-types.ts

@@ -5,7 +5,7 @@ export interface TelegramConfig { enabled?: boolean; token?: string; allowedChat
 export interface DiscordConfig { enabled?: boolean; token?: string; guildId?: string; channelIds?: string[]; forwardAll?: boolean; allowBots?: boolean; mentionOnly?: boolean; }
 // Slack needs TWO distinctly-scoped tokens: the bot token drives the Web API,
 // the app-level token opens the Socket Mode connection for inbound events.
-export interface SlackConfig { enabled?: boolean; botToken?: string; appToken?: string; teamId?: string; channelIds?: string[]; forwardAll?: boolean; allowBots?: boolean; mentionOnly?: boolean; replyInThread?: boolean; }
+export interface SlackConfig { enabled?: boolean; botToken?: string; appToken?: string; teamId?: string; channelIds?: string[]; forwardAll?: boolean; allowBots?: boolean; mentionOnly?: boolean; replyInThread?: boolean; attachPort?: string; }
 export interface QuotaWindow {
     label: string;
     percent: number;

package/public/js/features/settings.ts

@@ -2,7 +2,7 @@
 export { loadSettings, updateSettings, setPerm, getModelValue, handleModelSelect, applyCustomModel, onPerCliProviderChange, onCliChange, saveActiveCliSettings, savePerCli, onFlushCliChange, loadFlushAgentSidebar } from './settings-core.js';
 export { setTelegram, setForwardAll, setTelegramMentionOnly, saveTelegramSettings } from './settings-telegram.js';
 export { setDiscord, setDiscordForwardAll, setDiscordAllowBots, setDiscordMentionOnly, saveDiscordSettings } from './settings-discord.js';
-export { setSlack, setSlackForwardAll, setSlackAllowBots, setSlackMentionOnly, setSlackReplyInThread, saveSlackSettings } from './settings-slack.js';
+export { setSlack, setSlackForwardAll, setSlackAllowBots, setSlackMentionOnly, setSlackReplyInThread, saveSlackSettings, initSlackSetupGuide } from './settings-slack.js';
 export { setActiveChannel, loadFallbackOrder, saveFallbackOrder } from './settings-channel.js';
 export { loadMcpServers, syncMcpServers, installMcpGlobal, openMcpModal, initMcpModal } from './settings-mcp.js';
 export { loadCliStatus, scheduleCliStatusRefresh, setCliStatusInterval } from './settings-cli-status.js';

package/public/js/features/transport-status-row.ts

@@ -64,9 +64,13 @@ function renderTransportBlock(
     const chips = transportChipLabels(status)
         .map(text => `<span class="transport-status-chip">${escapeHtml(text)}</span>`)
         .join('');
-    const hint = showHint && status.configured && status.sendCapable && !status.activeInbound
-        ? `<p class="transport-status-hint">${escapeHtml(t('settings.channel.sendOnlyHint'))}</p>`
-        : '';
+    // not_attach_instance: tokens exist but another instance owns the socket —
+    // say so, or the guarded instance just reads as silently broken.
+    const hint = status.reason === 'not_attach_instance'
+        ? `<p class="transport-status-hint">${escapeHtml(t('settings.channel.notAttachInstanceHint'))}</p>`
+        : showHint && status.configured && status.sendCapable && !status.activeInbound
+            ? `<p class="transport-status-hint">${escapeHtml(t('settings.channel.sendOnlyHint'))}</p>`
+            : '';
     return `
         <div class="transport-status-block">
             <div class="transport-status-label">${escapeHtml(label)}</div>

package/public/js/main.ts

@@ -56,10 +56,11 @@ import {
     initCliStatusToggle, initCliStatusPreviewHooks, isCliStatusExpanded, expandCliStatus, isEmbeddedPreviewFrame,
     setTelegram, setForwardAll, setTelegramMentionOnly, saveTelegramSettings,
     setDiscord, setDiscordForwardAll, setDiscordAllowBots, setDiscordMentionOnly, saveDiscordSettings, setActiveChannel,
-    setSlack, setSlackForwardAll, setSlackAllowBots, setSlackMentionOnly, setSlackReplyInThread, saveSlackSettings,
+    setSlack, setSlackForwardAll, setSlackAllowBots, setSlackMentionOnly, setSlackReplyInThread, saveSlackSettings, initSlackSetupGuide,
     saveFallbackOrder,
     openTemplateModal, saveTemplateFromModal, closeTemplateModal, templateGoBack, toggleDevMode
 } from './features/settings.js';
+import { initChannelOnboarding } from './features/channel-onboarding.js';
 const {
     loadEmployees, addEmployee, deleteEmployee, updateEmployee,
     onEmpCliChange, onEmpRoleChange
@@ -300,6 +301,9 @@ document.getElementById('slBotToken')?.addEventListener('change', saveSlackSetti
 document.getElementById('slAppToken')?.addEventListener('change', saveSlackSettings);
 document.getElementById('slTeamId')?.addEventListener('change', saveSlackSettings);
 document.getElementById('slChannelIds')?.addEventListener('change', saveSlackSettings);
+document.getElementById('slAttachPort')?.addEventListener('change', saveSlackSettings);
+initChannelOnboarding();
+initSlackSetupGuide();
 
 document.getElementById('fallbackOrderList')?.addEventListener('change', saveFallbackOrder);
 

package/public/locales/en.json

@@ -516,7 +516,7 @@
     "help.slack.link.portal": "Open the Slack app dashboard",
     "help.slack.link.docs": "Socket Mode documentation",
     "help.slack.example.1": "@cli-jaw run the tests for this repo",
-    "help.slack.howTo.1": "Create an app at api.slack.com/apps (a manifest is easiest).",
+    "help.slack.howTo.1": "Click \"Copy manifest\" in the guide card below, then create the app at api.slack.com/apps → Create an App → From an app manifest.",
     "help.slack.howTo.2": "Enable Socket Mode and generate an app-level token (xapp-) with connections:write.",
     "help.slack.howTo.3": "Install to the workspace to obtain the bot token (xoxb-).",
     "help.slack.howTo.4": "Paste each token into its own field below — do not swap them.",
@@ -823,5 +823,67 @@
     "help.keyboardShortcuts.subcmd.2": "/help <command> — Show detailed help for a specific command",
     "help.keyboardShortcuts.subcmd.3": "/commands — Open command palette (alias: /cmd)",
     "bgtask.title": "Background",
-    "tg.elicitationExpired": "Selection expired. Please reply with text."
-}
+    "tg.elicitationExpired": "Selection expired. Please reply with text.",
+    "settings.slack.guide.step1Title": "Create the Slack app",
+    "settings.slack.guide.step1Desc": "Create an App → From an app manifest → pick workspace → paste",
+    "settings.slack.guide.copyManifest": "Copy manifest",
+    "settings.slack.guide.copyManifestDone": "Copied — paste it into Slack",
+    "settings.slack.guide.copyManifestFail": "Copy failed — use jaw slack manifest",
+    "settings.slack.guide.openApps": "Open apps page",
+    "settings.slack.guide.step2Title": "Paste the bot token",
+    "settings.slack.guide.step3Title": "App-level token for inbound (optional)",
+    "settings.slack.guide.step3Desc": "Leave empty for outbound-only operation",
+    "settings.slack.guide.botTokenError": "Must be a bot token starting with xoxb- — swapped with the app token?",
+    "settings.slack.guide.appTokenError": "Must be an app-level token starting with xapp- — swapped with the bot token?",
+    "settings.slack.advanced": "Advanced settings",
+    "settings.slack.attachPort": "Attach instance port",
+    "settings.channel.notAttachInstanceHint": "Another instance owns this Slack connection (check the attach instance port)",
+    "settings.slack.guide.step2Desc": "App settings → OAuth & Permissions → Install to Workspace → copy Bot User OAuth Token",
+    "settings.slack.guide.step3Location": "App settings → Basic Information → App-Level Tokens → Generate Token (connections:write)",
+    "slack.progress.start": "Gathering context...",
+    "slack.progress.working": "Working",
+    "onboarding.open": "Setup wizard",
+    "onboarding.optional": "optional",
+    "onboarding.validate": "Validate",
+    "onboarding.save": "Save",
+    "onboarding.close": "Close",
+    "onboarding.valid": "Verified: {identity}",
+    "onboarding.title.telegram": "Connect Telegram",
+    "onboarding.title.discord": "Connect Discord",
+    "onboarding.title.slack": "Connect Slack",
+    "onboarding.guide.telegram": "Open @BotFather in Telegram, send /newbot, pick a name and username, and copy the bot token it returns. Paste it below and press Validate.",
+    "onboarding.guide.discord": "At discord.com/developers/applications choose New Application, then Bot, then Reset Token. Enable MESSAGE CONTENT INTENT under Privileged Gateway Intents. Get the server ID by enabling Developer Mode in Discord, then right-click the server and copy its ID.",
+    "onboarding.guide.slack": "At api.slack.com/apps use Create an App, From an app manifest. Then get the bot token (xoxb-) from OAuth & Permissions, Install to Workspace, and the app-level token (xapp-, connections:write) from Basic Information, App-Level Tokens.",
+    "onboarding.token.botToken": "Bot token",
+    "onboarding.token.appToken": "App-level token",
+    "onboarding.token.guildId": "Server ID",
+    "onboarding.next.telegram": "Saved. Send any message to your bot in Telegram and the chat ID is stored automatically.",
+    "onboarding.next.discord": "Saved. Invite the bot to your server and confirm MESSAGE CONTENT INTENT is enabled.",
+    "onboarding.next.slack": "Saved. Run /invite @cli-jaw in each channel the bot should read.",
+    "onboarding.error.token_required": "Enter a token.",
+    "onboarding.error.invalid_token": "That token was rejected. Check it and try again.",
+    "onboarding.error.invalid_app_token": "The app-level token was rejected (check the connections:write scope).",
+    "onboarding.error.guild_required": "Enter the server ID.",
+    "onboarding.error.bot_prefix": "The bot token must start with xoxb-.",
+    "onboarding.error.app_prefix": "The app-level token must start with xapp-.",
+    "onboarding.error.unknown_channel": "Unsupported channel.",
+    "onboarding.error.network": "Validation failed because of a network error.",
+    "onboarding.next": "Next",
+    "onboarding.back": "Back",
+    "onboarding.step.1": "1. Where to get it",
+    "onboarding.step.2": "2. Paste what you received",
+    "onboarding.step.3": "3. Verify the connection",
+    "onboarding.step.4": "4. Save",
+    "onboarding.validating": "Checking...",
+    "onboarding.validateHint": "Press Validate to check the real connection. It must pass before saving.",
+    "onboarding.saveHint": "Validation passed. Saving applies the settings and connects the channel right away.",
+    "onboarding.error.validation_required": "Validation has to pass first.",
+    "onboarding.openIssuer": "Open the issuing page",
+    "onboarding.error.missing_scopes": "The token works, but the app is missing OAuth scopes. Add the ones below under OAuth & Permissions, then reinstall the app.",
+    "onboarding.hint.telegram.botToken": "The value @BotFather returned after /newbot.",
+    "onboarding.hint.discord.botToken": "Generated with Reset Token on the Bot tab.",
+    "onboarding.hint.discord.guildId": "Enable Developer Mode, right-click the server, copy ID.",
+    "onboarding.hint.slack.botToken": "Bot User OAuth Token from OAuth & Permissions (starts with xoxb-).",
+    "onboarding.hint.slack.appToken": "Basic Information, App-Level Tokens (xapp-, connections:write).",
+    "onboarding.progressLabel": "Step {step} of {total}"
+}

package/public/locales/ja.json

@@ -505,7 +505,7 @@
     "help.slack.link.portal": "Open the Slack app dashboard",
     "help.slack.link.docs": "Socket Mode documentation",
     "help.slack.example.1": "@cli-jaw run the tests for this repo",
-    "help.slack.howTo.1": "Create an app at api.slack.com/apps (a manifest is easiest).",
+    "help.slack.howTo.1": "下のガイドカードの「マニフェストをコピー」を押し、api.slack.com/apps → Create an App → From an app manifest に貼り付けてアプリを作成します。",
     "help.slack.howTo.2": "Enable Socket Mode and generate an app-level token (xapp-) with connections:write.",
     "help.slack.howTo.3": "Install to the workspace to obtain the bot token (xoxb-).",
     "help.slack.howTo.4": "Paste each token into its own field below — do not swap them.",
@@ -812,5 +812,78 @@
     "help.keyboardShortcuts.subcmd.2": "/help <command> — 特定コマンドの詳細ヘルプを表示します",
     "help.keyboardShortcuts.subcmd.3": "/commands — コマンドパレットを開きます（エイリアス: /cmd）",
     "bgtask.title": "バックグラウンド",
-    "tg.elicitationExpired": "選択セッションの有効期限が切れました。テキストで返信してください。"
-}
+    "tg.elicitationExpired": "選択セッションの有効期限が切れました。テキストで返信してください。",
+    "settings.slack.guide.step1Title": "Slack アプリを作成",
+    "settings.slack.guide.step1Desc": "Create an App → From an app manifest → ワークスペース選択 → 貼り付け",
+    "settings.slack.guide.copyManifest": "マニフェストをコピー",
+    "settings.slack.guide.copyManifestDone": "コピーしました — Slack に貼り付けてください",
+    "settings.slack.guide.copyManifestFail": "コピー失敗 — jaw slack manifest を使用",
+    "settings.slack.guide.openApps": "アプリページを開く",
+    "settings.slack.guide.step2Title": "ボットトークンを貼り付け",
+    "settings.slack.guide.step3Title": "受信用アプリトークン（任意）",
+    "settings.slack.guide.step3Desc": "空のままなら送信専用（outbound-only）で動作します",
+    "settings.slack.guide.botTokenError": "xoxb- で始まるボットトークンが必要です — アプリトークンと入れ替わっていませんか？",
+    "settings.slack.guide.appTokenError": "xapp- で始まるアプリレベルトークンが必要です — ボットトークンと入れ替わっていませんか？",
+    "settings.slack.advanced": "詳細設定",
+    "settings.slack.attachPort": "接続インスタンスのポート",
+    "settings.channel.notAttachInstanceHint": "別のインスタンスがこの Slack 接続を所有しています（接続インスタンスのポートを確認）",
+    "settings.slack.guide.step2Desc": "アプリ設定 → OAuth & Permissions → Install to Workspace → Bot User OAuth Token をコピー",
+    "settings.slack.guide.step3Location": "アプリ設定 → Basic Information → App-Level Tokens → Generate Token (connections:write)",
+    "slack.progress.start": "情報を収集中...",
+    "slack.progress.working": "作業中",
+    "onboarding.open": "セットアップウィザード",
+    "onboarding.optional": "任意",
+    "onboarding.validate": "検証",
+    "onboarding.save": "保存",
+    "onboarding.close": "閉じる",
+    "onboarding.valid": "確認済み: {identity}",
+    "onboarding.title.telegram": "Telegram に接続",
+    "onboarding.title.discord": "Discord に接続",
+    "onboarding.title.slack": "Slack に接続",
+    "onboarding.guide.telegram": "Open @BotFather in Telegram, send /newbot, pick a name and username, and copy the bot token it returns. Paste it below and press Validate.",
+    "onboarding.guide.discord": "At discord.com/developers/applications choose New Application, then Bot, then Reset Token. Enable MESSAGE CONTENT INTENT under Privileged Gateway Intents. Get the server ID by enabling Developer Mode in Discord, then right-click the server and copy its ID.",
+    "onboarding.guide.slack": "At api.slack.com/apps use Create an App, From an app manifest. Then get the bot token (xoxb-) from OAuth & Permissions, Install to Workspace, and the app-level token (xapp-, connections:write) from Basic Information, App-Level Tokens.",
+    "onboarding.token.botToken": "ボットトークン",
+    "onboarding.token.appToken": "アプリレベルトークン",
+    "onboarding.token.guildId": "サーバー ID",
+    "onboarding.next.telegram": "Saved. Send any message to your bot in Telegram and the chat ID is stored automatically.",
+    "onboarding.next.discord": "Saved. Invite the bot to your server and confirm MESSAGE CONTENT INTENT is enabled.",
+    "onboarding.next.slack": "Saved. Run /invite @cli-jaw in each channel the bot should read.",
+    "onboarding.error.token_required": "Enter a token.",
+    "onboarding.error.invalid_token": "That token was rejected. Check it and try again.",
+    "onboarding.error.invalid_app_token": "The app-level token was rejected (check the connections:write scope).",
+    "onboarding.error.guild_required": "Enter the server ID.",
+    "onboarding.error.bot_prefix": "The bot token must start with xoxb-.",
+    "onboarding.error.app_prefix": "The app-level token must start with xapp-.",
+    "onboarding.error.unknown_channel": "Unsupported channel.",
+    "onboarding.error.network": "Validation failed because of a network error.",
+    "onboarding.next": "次へ",
+    "onboarding.back": "戻る",
+    "onboarding.step.1": "1. 取得場所の確認",
+    "onboarding.step.2": "2. 取得した値を貼り付け",
+    "onboarding.step.3": "3. 接続の検証",
+    "onboarding.step.4": "4. 保存",
+    "onboarding.validating": "確認中...",
+    "onboarding.validateHint": "「検証」を押して実際の接続を確認してください。通過しないと保存に進めません。",
+    "onboarding.saveHint": "検証に成功しました。保存すると設定に反映され、チャンネルがすぐ接続されます。",
+    "onboarding.error.validation_required": "先に検証を通す必要があります。",
+    "onboarding.openIssuer": "発行ページを開く",
+    "onboarding.error.missing_scopes": "トークンは有効ですが、アプリの権限（スコープ）が不足しています。OAuth & Permissions で以下を追加し、アプリを再インストールしてください。",
+    "onboarding.hint.telegram.botToken": "@BotFather が /newbot の後に返した値です。",
+    "onboarding.hint.discord.botToken": "Bot タブの Reset Token で生成した値です。",
+    "onboarding.hint.discord.guildId": "開発者モードを有効にし、サーバーを右クリックして ID をコピー。",
+    "onboarding.hint.slack.botToken": "OAuth & Permissions の Bot User OAuth Token（xoxb- で始まる）。",
+    "onboarding.hint.slack.appToken": "Basic Information → App-Level Tokens（xapp-, connections:write）。",
+    "cmd.memory.embed.estimate": "埋め込み推定",
+    "cmd.memory.embed.status": "埋め込み状態",
+    "settings.channel.activeInbound": "受信チャンネル",
+    "settings.channel.configured": "設定済み",
+    "settings.channel.notConfigured": "未設定",
+    "settings.channel.sendCapable": "送信可能",
+    "settings.channel.sendOnlyHint": "受信チャンネルではありませんが、設定済みなら送信は可能です。",
+    "settings.channel.statusTitle": "送信状態",
+    "settings.channel.testSend": "テスト送信",
+    "settings.channel.testSendFail": "送信失敗: {error}",
+    "settings.channel.testSendOk": "送信成功",
+    "onboarding.progressLabel": "{total} ステップ中 {step} ステップ目"
+}

package/public/locales/ko.json

@@ -516,7 +516,7 @@
     "help.slack.link.portal": "Slack 앱 관리 페이지 열기",
     "help.slack.link.docs": "Socket Mode 문서",
     "help.slack.example.1": "@cli-jaw 이 저장소 테스트 돌려줘",
-    "help.slack.howTo.1": "api.slack.com/apps 에서 앱을 만듭니다 (매니페스트 사용 권장).",
+    "help.slack.howTo.1": "아래 가이드 카드의 \"매니페스트 복사\"를 눌러 api.slack.com/apps → Create an App → From an app manifest에 붙여넣어 앱을 만듭니다.",
     "help.slack.howTo.2": "Socket Mode를 켜고 connections:write 범위의 app-level 토큰(xapp-)을 발급합니다.",
     "help.slack.howTo.3": "워크스페이스에 설치해 봇 토큰(xoxb-)을 받습니다.",
     "help.slack.howTo.4": "두 토큰을 아래 입력란에 각각 붙여넣습니다 — 서로 바꿔 넣지 않도록 주의하세요.",
@@ -823,5 +823,67 @@
     "help.keyboardShortcuts.subcmd.2": "/help <command> — 특정 명령어의 상세 도움말을 표시합니다",
     "help.keyboardShortcuts.subcmd.3": "/commands — 명령 팔레트를 엽니다 (별칭: /cmd)",
     "bgtask.title": "백그라운드",
-    "tg.elicitationExpired": "선택 세션이 만료되었습니다. 텍스트로 답해주세요."
-}
+    "tg.elicitationExpired": "선택 세션이 만료되었습니다. 텍스트로 답해주세요.",
+    "settings.slack.guide.step1Title": "Slack 앱 만들기",
+    "settings.slack.guide.step1Desc": "Create an App → From an app manifest → 워크스페이스 선택 → 붙여넣기",
+    "settings.slack.guide.copyManifest": "매니페스트 복사",
+    "settings.slack.guide.copyManifestDone": "복사됨 — Slack에 붙여넣으세요",
+    "settings.slack.guide.copyManifestFail": "복사 실패 — jaw slack manifest 사용",
+    "settings.slack.guide.openApps": "앱 페이지 열기",
+    "settings.slack.guide.step2Title": "봇 토큰 붙여넣기",
+    "settings.slack.guide.step3Title": "수신용 앱 토큰 (선택)",
+    "settings.slack.guide.step3Desc": "비워두면 전송 전용(outbound-only)으로 동작합니다",
+    "settings.slack.guide.botTokenError": "xoxb-로 시작하는 봇 토큰이어야 합니다 — 앱 토큰과 바꿔 넣지 않았나요?",
+    "settings.slack.guide.appTokenError": "xapp-로 시작하는 앱 레벨 토큰이어야 합니다 — 봇 토큰과 바꿔 넣지 않았나요?",
+    "settings.slack.advanced": "고급 설정",
+    "settings.slack.attachPort": "연결 인스턴스 포트",
+    "settings.channel.notAttachInstanceHint": "다른 인스턴스가 이 Slack 연결을 소유하고 있습니다 (연결 인스턴스 포트 확인)",
+    "settings.slack.guide.step2Desc": "앱 설정 → OAuth & Permissions → Install to Workspace → Bot User OAuth Token 복사",
+    "settings.slack.guide.step3Location": "앱 설정 → Basic Information → App-Level Tokens → Generate Token (connections:write)",
+    "slack.progress.start": "정보 수집 중...",
+    "slack.progress.working": "작업 중",
+    "onboarding.open": "설정 마법사",
+    "onboarding.optional": "선택",
+    "onboarding.validate": "검증",
+    "onboarding.save": "저장",
+    "onboarding.close": "닫기",
+    "onboarding.valid": "확인됨: {identity}",
+    "onboarding.title.telegram": "Telegram 연결",
+    "onboarding.title.discord": "Discord 연결",
+    "onboarding.title.slack": "Slack 연결",
+    "onboarding.guide.telegram": "텔레그램에서 @BotFather 를 열고 /newbot 을 보낸 뒤, 이름과 username을 정하면 봇 토큰이 나옵니다. 그 토큰을 아래에 붙여넣고 검증을 누르세요.",
+    "onboarding.guide.discord": "discord.com/developers/applications 에서 New Application → Bot → Reset Token 으로 토큰을 만들고, Privileged Gateway Intents 의 MESSAGE CONTENT INTENT 를 켜세요. 서버 ID는 Discord 설정에서 개발자 모드를 켠 뒤 서버 우클릭 → ID 복사로 얻습니다.",
+    "onboarding.guide.slack": "api.slack.com/apps 에서 Create an App → From an app manifest 로 앱을 만든 뒤, OAuth & Permissions → Install to Workspace 에서 봇 토큰(xoxb-), Basic Information → App-Level Tokens 에서 앱 토큰(xapp-, connections:write)을 발급받으세요.",
+    "onboarding.token.botToken": "봇 토큰",
+    "onboarding.token.appToken": "앱 레벨 토큰",
+    "onboarding.token.guildId": "서버 ID",
+    "onboarding.next.telegram": "저장했습니다. 이제 텔레그램에서 봇에게 아무 메시지나 보내면 채팅 ID가 자동 저장됩니다.",
+    "onboarding.next.discord": "저장했습니다. 봇을 서버에 초대하고 MESSAGE CONTENT INTENT 가 켜져 있는지 확인하세요.",
+    "onboarding.next.slack": "저장했습니다. 봇이 읽을 채널에서 /invite @cli-jaw 로 초대하세요.",
+    "onboarding.error.token_required": "토큰을 입력하세요.",
+    "onboarding.error.invalid_token": "토큰이 유효하지 않습니다. 다시 확인해 주세요.",
+    "onboarding.error.invalid_app_token": "앱 레벨 토큰이 유효하지 않습니다 (connections:write 범위 확인).",
+    "onboarding.error.guild_required": "서버 ID를 입력하세요.",
+    "onboarding.error.bot_prefix": "봇 토큰은 xoxb- 로 시작해야 합니다.",
+    "onboarding.error.app_prefix": "앱 레벨 토큰은 xapp- 로 시작해야 합니다.",
+    "onboarding.error.unknown_channel": "지원하지 않는 채널입니다.",
+    "onboarding.error.network": "네트워크 오류로 검증하지 못했습니다.",
+    "onboarding.next": "다음",
+    "onboarding.back": "이전",
+    "onboarding.step.1": "1. 어디서 받는지 확인",
+    "onboarding.step.2": "2. 발급받은 값 붙여넣기",
+    "onboarding.step.3": "3. 연결 검증",
+    "onboarding.step.4": "4. 저장",
+    "onboarding.validating": "확인하는 중...",
+    "onboarding.validateHint": "검증을 눌러 실제 연결을 확인하세요. 통과해야 저장으로 넘어갑니다.",
+    "onboarding.saveHint": "검증을 통과했습니다. 저장을 누르면 설정에 반영되고 채널이 바로 연결됩니다.",
+    "onboarding.error.validation_required": "먼저 검증을 통과해야 합니다.",
+    "onboarding.openIssuer": "발급 페이지 열기",
+    "onboarding.error.missing_scopes": "토큰은 유효하지만 앱에 권한(스코프)이 부족합니다. OAuth & Permissions에서 아래 항목을 추가하고 앱을 재설치하세요.",
+    "onboarding.hint.telegram.botToken": "@BotFather가 /newbot 후 알려준 값입니다.",
+    "onboarding.hint.discord.botToken": "Bot 탭의 Reset Token으로 새로 만든 값입니다.",
+    "onboarding.hint.discord.guildId": "개발자 모드를 켠 뒤 서버를 우클릭해 ID 복사.",
+    "onboarding.hint.slack.botToken": "OAuth & Permissions의 Bot User OAuth Token (xoxb-로 시작).",
+    "onboarding.hint.slack.appToken": "Basic Information → App-Level Tokens (xapp-, connections:write).",
+    "onboarding.progressLabel": "{total}단계 중 {step}단계"
+}

package/public/locales/zh.json

@@ -505,7 +505,7 @@
     "help.slack.link.portal": "Open the Slack app dashboard",
     "help.slack.link.docs": "Socket Mode documentation",
     "help.slack.example.1": "@cli-jaw run the tests for this repo",
-    "help.slack.howTo.1": "Create an app at api.slack.com/apps (a manifest is easiest).",
+    "help.slack.howTo.1": "点击下方指南卡中的“复制清单”，然后在 api.slack.com/apps → Create an App → From an app manifest 粘贴以创建应用。",
     "help.slack.howTo.2": "Enable Socket Mode and generate an app-level token (xapp-) with connections:write.",
     "help.slack.howTo.3": "Install to the workspace to obtain the bot token (xoxb-).",
     "help.slack.howTo.4": "Paste each token into its own field below — do not swap them.",
@@ -812,5 +812,78 @@
     "help.keyboardShortcuts.subcmd.2": "/help <command> — 显示特定命令的详细帮助",
     "help.keyboardShortcuts.subcmd.3": "/commands — 打开命令面板（别名: /cmd）",
     "bgtask.title": "后台任务",
-    "tg.elicitationExpired": "选择会话已过期，请用文字回复。"
-}
+    "tg.elicitationExpired": "选择会话已过期，请用文字回复。",
+    "settings.slack.guide.step1Title": "创建 Slack 应用",
+    "settings.slack.guide.step1Desc": "Create an App → From an app manifest → 选择工作区 → 粘贴",
+    "settings.slack.guide.copyManifest": "复制清单",
+    "settings.slack.guide.copyManifestDone": "已复制 — 请粘贴到 Slack",
+    "settings.slack.guide.copyManifestFail": "复制失败 — 请使用 jaw slack manifest",
+    "settings.slack.guide.openApps": "打开应用页面",
+    "settings.slack.guide.step2Title": "粘贴机器人令牌",
+    "settings.slack.guide.step3Title": "接收用应用令牌（可选）",
+    "settings.slack.guide.step3Desc": "留空则仅可发送（outbound-only）",
+    "settings.slack.guide.botTokenError": "需要以 xoxb- 开头的机器人令牌 — 是否与应用令牌填反了？",
+    "settings.slack.guide.appTokenError": "需要以 xapp- 开头的应用级令牌 — 是否与机器人令牌填反了？",
+    "settings.slack.advanced": "高级设置",
+    "settings.slack.attachPort": "连接实例端口",
+    "settings.channel.notAttachInstanceHint": "另一个实例拥有此 Slack 连接（请检查连接实例端口）",
+    "settings.slack.guide.step2Desc": "应用设置 → OAuth & Permissions → Install to Workspace → 复制 Bot User OAuth Token",
+    "settings.slack.guide.step3Location": "应用设置 → Basic Information → App-Level Tokens → Generate Token (connections:write)",
+    "slack.progress.start": "正在收集信息...",
+    "slack.progress.working": "处理中",
+    "onboarding.open": "设置向导",
+    "onboarding.optional": "可选",
+    "onboarding.validate": "验证",
+    "onboarding.save": "保存",
+    "onboarding.close": "关闭",
+    "onboarding.valid": "已验证：{identity}",
+    "onboarding.title.telegram": "连接 Telegram",
+    "onboarding.title.discord": "连接 Discord",
+    "onboarding.title.slack": "连接 Slack",
+    "onboarding.guide.telegram": "Open @BotFather in Telegram, send /newbot, pick a name and username, and copy the bot token it returns. Paste it below and press Validate.",
+    "onboarding.guide.discord": "At discord.com/developers/applications choose New Application, then Bot, then Reset Token. Enable MESSAGE CONTENT INTENT under Privileged Gateway Intents. Get the server ID by enabling Developer Mode in Discord, then right-click the server and copy its ID.",
+    "onboarding.guide.slack": "At api.slack.com/apps use Create an App, From an app manifest. Then get the bot token (xoxb-) from OAuth & Permissions, Install to Workspace, and the app-level token (xapp-, connections:write) from Basic Information, App-Level Tokens.",
+    "onboarding.token.botToken": "机器人令牌",
+    "onboarding.token.appToken": "应用级令牌",
+    "onboarding.token.guildId": "服务器 ID",
+    "onboarding.next.telegram": "Saved. Send any message to your bot in Telegram and the chat ID is stored automatically.",
+    "onboarding.next.discord": "Saved. Invite the bot to your server and confirm MESSAGE CONTENT INTENT is enabled.",
+    "onboarding.next.slack": "Saved. Run /invite @cli-jaw in each channel the bot should read.",
+    "onboarding.error.token_required": "Enter a token.",
+    "onboarding.error.invalid_token": "That token was rejected. Check it and try again.",
+    "onboarding.error.invalid_app_token": "The app-level token was rejected (check the connections:write scope).",
+    "onboarding.error.guild_required": "Enter the server ID.",
+    "onboarding.error.bot_prefix": "The bot token must start with xoxb-.",
+    "onboarding.error.app_prefix": "The app-level token must start with xapp-.",
+    "onboarding.error.unknown_channel": "Unsupported channel.",
+    "onboarding.error.network": "Validation failed because of a network error.",
+    "onboarding.next": "下一步",
+    "onboarding.back": "上一步",
+    "onboarding.step.1": "1. 确认获取位置",
+    "onboarding.step.2": "2. 粘贴获取的值",
+    "onboarding.step.3": "3. 验证连接",
+    "onboarding.step.4": "4. 保存",
+    "onboarding.validating": "正在检查...",
+    "onboarding.validateHint": "点击验证以检查实际连接。通过后才能保存。",
+    "onboarding.saveHint": "验证通过。保存后将写入设置并立即连接该渠道。",
+    "onboarding.error.validation_required": "需要先通过验证。",
+    "onboarding.openIssuer": "打开签发页面",
+    "onboarding.error.missing_scopes": "令牌有效，但应用缺少 OAuth 权限（scope）。请在 OAuth & Permissions 中添加下列项并重新安装应用。",
+    "onboarding.hint.telegram.botToken": "@BotFather 在 /newbot 之后返回的值。",
+    "onboarding.hint.discord.botToken": "在 Bot 标签页用 Reset Token 生成的值。",
+    "onboarding.hint.discord.guildId": "启用开发者模式后右键服务器并复制 ID。",
+    "onboarding.hint.slack.botToken": "OAuth & Permissions 中的 Bot User OAuth Token（以 xoxb- 开头）。",
+    "onboarding.hint.slack.appToken": "Basic Information → App-Level Tokens（xapp-, connections:write）。",
+    "cmd.memory.embed.estimate": "嵌入估算",
+    "cmd.memory.embed.status": "嵌入状态",
+    "settings.channel.activeInbound": "接收渠道",
+    "settings.channel.configured": "已配置",
+    "settings.channel.notConfigured": "未配置",
+    "settings.channel.sendCapable": "可发送",
+    "settings.channel.sendOnlyHint": "虽不是接收渠道，但已配置时仍可发送。",
+    "settings.channel.statusTitle": "传输状态",
+    "settings.channel.testSend": "测试发送",
+    "settings.channel.testSendFail": "发送失败：{error}",
+    "settings.channel.testSendOk": "发送成功",
+    "onboarding.progressLabel": "第 {step} 步，共 {total} 步"
+}

package/public/manager/src/settings/pages/Agent.tsx

@@ -17,6 +17,8 @@ import {
     optionList,
     runtimeEffortFor,
     runtimeModelFor,
+    coerceEffortForModel,
+    effortChoicesForModel,
     type ActiveOverride,
     type CliMeta,
     type PerCliEntry,
@@ -193,8 +195,8 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
         ? optionList(activeMeta.modelsByProvider?.[activeProvider] || activeMeta.models, draft.model)
         : optionList(activeMeta.models, draft.model);
     const activeEffortOptions = hasProviders
-        ? (activeMeta.effortsByProvider?.[activeProvider] || activeMeta.efforts)
-        : activeMeta.efforts;
+        ? effortChoicesForModel(activeMeta, draft.model, activeMeta.effortsByProvider?.[activeProvider] || activeMeta.efforts, activeProvider)
+        : effortChoicesForModel(activeMeta, draft.model);
     const workingDirError = draft.workingDir.trim() ? null : 'Required';
 
     if (state.kind === 'loading') return <PageLoading />;
@@ -248,7 +250,9 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
                     const models = activeMeta.modelsByProvider?.[next] || [];
                     const efforts = activeMeta.effortsByProvider?.[next] || [];
                     const nextModel = models.includes(draft.model) ? draft.model : (models[0] || '');
-                    const nextEffort = efforts.includes(draft.effort) ? draft.effort : '';
+                    // Resolve against the NEW provider+model pair: the same model
+                    // id can allow different efforts per provider.
+                    const nextEffort = coerceEffortForModel(activeMeta, nextModel, draft.effort, efforts, next);
                     setRuntimeDraft({ ...draft, provider: next, model: nextModel, effort: nextEffort });
                     setEntry(`perCli.${draft.cli}.provider`, {
                         value: next,
@@ -267,12 +271,29 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
                     });
                 }}
                 onModelChange={(next) => {
-                    setRuntimeDraft({ ...draft, model: next });
+                    // Efforts are per-model on a live opencodex catalog, so a
+                    // model switch can strand an effort the new model does not
+                    // support — and that value would reach the wire verbatim.
+                    const nextEffort = coerceEffortForModel(
+                        activeMeta,
+                        next,
+                        draft.effort,
+                        hasProviders ? (activeMeta.effortsByProvider?.[activeProvider] || activeMeta.efforts) : undefined,
+                        hasProviders ? activeProvider : undefined,
+                    );
+                    setRuntimeDraft({ ...draft, model: next, effort: nextEffort });
                     setEntry(`activeOverrides.${draft.cli}.model`, {
                         value: next,
                         original: runtimeModelFor(draft.cli, perCli, activeOverrides),
                         valid: next.trim().length > 0,
                     });
+                    if (nextEffort !== draft.effort) {
+                        setEntry(`activeOverrides.${draft.cli}.effort`, {
+                            value: nextEffort,
+                            original: runtimeEffortFor(draft.cli, perCli, activeOverrides),
+                            valid: true,
+                        });
+                    }
                 }}
                 onEffortChange={(next) => {
                     setRuntimeDraft({ ...draft, effort: next });