fix(settings): add install onboarding links for unavailable local CLIs (#985)

* fix(settings): add install onboarding links for unavailable local CLIs * fix(settings): rename Claude config dir label to config directory --------- Co-authored-by: mrcfps <mrc@powerformer.com>
2026-06-01 03:14:35 +07:00 · 2026-05-09 09:49:44 -04:00 · 2026-05-09 09:49:44 -04:00 · 039cc3d674
commit 039cc3d674
parent 3bcb3547d1
25 changed files with 444 additions and 59 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@ -11,6 +11,10 @@ Run the full product locally.
 - **OS:** macOS, Linux, and WSL2 are the primary paths. Windows native should work for most flows, but WSL2 is the safer baseline.
 - **Optional local agent CLI:** Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, Qoder CLI, GitHub Copilot CLI, etc. If none are installed, use the BYOK API mode from Settings.

+### Local agent CLI and PATH
+
+The daemon scans your **`PATH`** (plus common user toolchain directories). If you install a CLI with **`npm install -g`** or **Homebrew** and Open Design still shows it as *not installed*, the GUI may be starting with a minimal `PATH` that does not include your global npm or Homebrew `bin` directory (common on macOS when the app is not launched from a full login shell). Ensure the executable’s directory is on `PATH` for the process that runs the daemon, then use **Rescan** in **Settings → Execution & model**.
+
 `nvm` / `fnm` are optional convenience tools, not required project setup. If you use one, install/select Node 24 before running pnpm:

 ```bash
--- a/apps/daemon/src/agents.ts
+++ b/apps/daemon/src/agents.ts
@ -108,6 +108,99 @@ const AGENT_BIN_ENV_KEYS = new Map([
  ['vibe', 'VIBE_BIN'],
 ]);

+/** HTTPS links for the web UI when `available` is false. Keys must match `AGENT_DEFS[].id`. */
+const AGENT_INSTALL_LINKS: Record<
+  string,
+  { installUrl?: string; docsUrl?: string }
+> = {
+  claude: {
+    installUrl: 'https://docs.anthropic.com/en/docs/claude-code/setup',
+    docsUrl: 'https://docs.anthropic.com/en/docs/claude-code',
+  },
+  codex: {
+    installUrl: 'https://github.com/openai/codex',
+    docsUrl: 'https://developers.openai.com/codex',
+  },
+  devin: {
+    installUrl: 'https://cli.devin.ai/docs',
+    docsUrl: 'https://docs.devin.ai',
+  },
+  gemini: {
+    installUrl: 'https://github.com/google-gemini/gemini-cli',
+    docsUrl: 'https://github.com/google-gemini/gemini-cli/blob/main/README.md',
+  },
+  opencode: {
+    installUrl: 'https://opencode.ai/docs',
+    docsUrl: 'https://github.com/sst/opencode',
+  },
+  hermes: {
+    installUrl: 'https://github.com/nexu-io/open-design/blob/main/docs/agent-adapters.md',
+    docsUrl: 'https://hermes-agent.nousresearch.com/docs/',
+  },
+  kimi: {
+    installUrl: 'https://github.com/MoonshotAI/kimi-cli',
+    docsUrl: 'https://www.kimi.com/code/docs/en/kimi-cli/guides/getting-started.html',
+  },
+  'cursor-agent': {
+    installUrl: 'https://cursor.com/docs/cli/overview',
+    docsUrl: 'https://docs.cursor.com/en/cli/overview',
+  },
+  qwen: {
+    installUrl: 'https://github.com/QwenLM/qwen-code',
+    docsUrl: 'https://qwenlm.github.io/qwen-code-docs/en/index',
+  },
+  qoder: {
+    installUrl: 'https://qoder.com/download',
+    docsUrl: 'https://docs.qoder.com',
+  },
+  copilot: {
+    installUrl: 'https://github.com/github/copilot-cli',
+    docsUrl: 'https://docs.github.com/en/copilot/how-tos/use-copilot-extensions/use-in-cli',
+  },
+  pi: {
+    installUrl: 'https://github.com/nexu-io/open-design/blob/main/docs/agent-adapters.md',
+    docsUrl: 'https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md',
+  },
+  kiro: {
+    installUrl: 'https://kiro.dev',
+    docsUrl: 'https://kiro.dev/docs/cli/',
+  },
+  kilo: {
+    installUrl: 'https://kilo.ai',
+    docsUrl: 'https://kilo.ai/docs/cli',
+  },
+  vibe: {
+    installUrl: 'https://docs.mistral.ai',
+    docsUrl: 'https://github.com/mistralai/vibe-acp',
+  },
+  deepseek: {
+    installUrl: 'https://github.com/deepseek-ai/DeepSeek-TUI',
+    docsUrl: 'https://github.com/deepseek-ai/DeepSeek-TUI/blob/main/README.md',
+  },
+};
+
+function installMetaForAgent(
+  agentId: string,
+): { installUrl?: string; docsUrl?: string } {
+  const meta = AGENT_INSTALL_LINKS[agentId];
+  if (!meta) return {};
+  const sanitize = (value: string | undefined): string | undefined => {
+    if (!value) return undefined;
+    try {
+      const parsed = new URL(value);
+      return parsed.protocol === 'https:' ? parsed.toString() : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  const installUrl = sanitize(meta.installUrl);
+  const docsUrl = sanitize(meta.docsUrl);
+  return {
+    ...(installUrl ? { installUrl } : {}),
+    ...(docsUrl ? { docsUrl } : {}),
+  };
+}
+
 // Map a user-picked reasoning effort to one the chosen model will accept.
 // Codex's CLI accepts `none | minimal | low | medium | high | xhigh`, but
 // real models support narrower subsets — gpt-5.2/5.3/5.4/5.5 reject
@ -1020,6 +1113,7 @@ async function probe(def, configuredEnv = {}) {
      ...stripFns(def),
      models: def.fallbackModels ?? [DEFAULT_MODEL_OPTION],
      available: false,
+      ...installMetaForAgent(def.id),
    };
  }
  const probeEnv = spawnEnvForAgent(
@ -1066,6 +1160,7 @@ async function probe(def, configuredEnv = {}) {
    available: true,
    path: resolved,
    version,
+    ...installMetaForAgent(def.id),
  };
 }

--- a/apps/web/src/components/SettingsDialog.tsx
+++ b/apps/web/src/components/SettingsDialog.tsx
@ -236,6 +236,16 @@ const API_PROTOCOL_LABELS: Record<ApiProtocol, string> = {
  ollama: 'Ollama Cloud API',
 };

+function sanitizeHttpsUrl(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'https:' ? parsed.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 const API_KEY_PLACEHOLDERS: Record<ApiProtocol, string> = {
  anthropic: 'sk-ant-...',
  openai: 'sk-...',
@ -1500,53 +1510,107 @@ export function SettingsDialog({
                  {t('settings.noAgentsDetected')}
                </div>
              ) : (
-                <div className="agent-grid">
-                  {agents.map((a) => {
-                    const active = cfg.agentId === a.id;
-                    return (
-                      <button
-                        type="button"
-                        key={a.id}
-                        className={
-                          'agent-card' +
-                          (active ? ' active' : '') +
-                          (a.available ? '' : ' disabled')
-                        }
-                        onClick={() =>
-                          a.available && setCfg((c) => ({ ...c, agentId: a.id }))
-                        }
-                        disabled={!a.available}
-                        aria-pressed={active}
-                      >
-                        <AgentIcon id={a.id} size={40} />
-                        <div className="agent-card-body">
-                          <div className="agent-card-name">{a.name}</div>
-                          <div className="agent-card-meta">
-                            {a.available ? (
-                              a.version ? (
-                                <span title={a.path ?? ''}>{a.version}</span>
-                              ) : (
-                                <span title={a.path ?? ''}>
-                                  {t('common.installed')}
-                                </span>
-                              )
-                            ) : (
+                <>
+                  <div className="agent-grid">
+                    {agents.map((a) => {
+                      const active = cfg.agentId === a.id;
+                      if (a.available) {
+                        return (
+                          <button
+                            type="button"
+                            key={a.id}
+                            className={
+                              'agent-card' + (active ? ' active' : '')
+                            }
+                            onClick={() =>
+                              setCfg((c) => ({ ...c, agentId: a.id }))
+                            }
+                            aria-pressed={active}
+                          >
+                            <AgentIcon id={a.id} size={40} />
+                            <div className="agent-card-body">
+                              <div className="agent-card-name">{a.name}</div>
+                              <div className="agent-card-meta">
+                                {a.version ? (
+                                  <span title={a.path ?? ''}>{a.version}</span>
+                                ) : (
+                                  <span title={a.path ?? ''}>
+                                    {t('common.installed')}
+                                  </span>
+                                )}
+                              </div>
+                            </div>
+                            <span
+                              className={
+                                'status-dot' + (active ? ' active' : '')
+                              }
+                              aria-hidden="true"
+                            />
+                          </button>
+                        );
+                      }
+                      const installUrl = sanitizeHttpsUrl(a.installUrl);
+                      const docsUrl = sanitizeHttpsUrl(a.docsUrl);
+                      const hasLinks = Boolean(installUrl || docsUrl);
+                      const cardLabel = `${a.name} · ${t('common.notInstalled')}`;
+                      return (
+                        <div
+                          key={a.id}
+                          className="agent-card disabled agent-card-unavailable"
+                          role="group"
+                          aria-label={cardLabel}
+                        >
+                          <AgentIcon id={a.id} size={40} />
+                          <div className="agent-card-body">
+                            <div className="agent-card-name">{a.name}</div>
+                            <div className="agent-card-meta">
                              <span className="muted">
                                {t('common.notInstalled')}
                              </span>
-                            )}
+                            </div>
+                            {hasLinks ? (
+                              <div className="agent-card-actions">
+                                {installUrl ? (
+                                  <a
+                                    href={installUrl}
+                                    target="_blank"
+                                    rel="noopener noreferrer"
+                                    className="agent-card-link"
+                                  >
+                                    {t('settings.agentInstall.install')}
+                                  </a>
+                                ) : null}
+                                {docsUrl ? (
+                                  <a
+                                    href={docsUrl}
+                                    target="_blank"
+                                    rel="noopener noreferrer"
+                                    className="agent-card-link"
+                                  >
+                                    {t('settings.agentInstall.docs')}
+                                  </a>
+                                ) : null}
+                              </div>
+                            ) : null}
                          </div>
                        </div>
-                        {a.available ? (
-                          <span
-                            className={'status-dot' + (active ? ' active' : '')}
-                            aria-hidden="true"
-                          />
-                        ) : null}
-                      </button>
-                    );
-                  })}
-                </div>
+                      );
+                    })}
+                  </div>
+                  {agents.some((x) => !x.available) ? (
+                    <div className="agent-install-guide">
+                      <p className="hint agent-install-path-hint">
+                        {t('settings.agentInstall.pathHint')}
+                      </p>
+                      <ol className="agent-install-steps">
+                        <li>{t('settings.agentInstall.stepOpenLinks')}</li>
+                        <li>{t('settings.agentInstall.stepAuth')}</li>
+                        <li>{t('settings.agentInstall.stepRescan')}</li>
+                        <li>{t('settings.agentInstall.stepSelect')}</li>
+                      </ol>
+                    </div>
+                  ) : null}
+                </>
              )}
              {(() => {
                const selected = agents.find(
--- a/apps/web/src/i18n/locales/ar.ts
+++ b/apps/web/src/i18n/locales/ar.ts
@ -85,6 +85,15 @@ export const ar: Dict = {
  'settings.testAgentMissing': '{agentName} غير مثبت أو ليس في PATH.',
  'settings.testAgentSpawn': 'تعذّر تشغيل {agentName}: {detail}.',
  'settings.testUnknown': 'فشل الاختبار: {detail}',
+  'settings.agentInstall.install': 'تثبيت',
+  'settings.agentInstall.docs': 'الوثائق',
+  'settings.agentInstall.pathHint':
+    'إذا ثبّتّ CLI باستخدام npm أو Homebrew وما زال يظهر كغير مثبت، فتأكد من أن مجلد bin للأداة موجود في PATH الذي يرثه daemon الخاص بـ Open Design (قد يختلف PATH بين Terminal وتطبيقات GUI على macOS). راجع QUICKSTART.md (قسم "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'افتح رابط التثبيت أو الوثائق للوكيل الذي تفضله.',
+  'settings.agentInstall.stepAuth':
+    'أكمِل المصادقة في CLI الخاص بالمزوّد (تسجيل الدخول أو إضافة بيانات اعتماد API) قبل العودة إلى Open Design.',
+  'settings.agentInstall.stepRescan': 'انقر إعادة المسح في هذا القسم.',
+  'settings.agentInstall.stepSelect': 'اختر بطاقة الوكيل عندما يظهر كأنه مثبت.',
  'settings.noAgentsDetected':
    'لم يتم اكتشاف أي وكلاء بعد. قم بتثبيت Claude Code أو Codex أو Devin أو Gemini CLI أو OpenCode أو Cursor Agent أو Qwen أو GitHub Copilot CLI، ثم اضغط على إعادة المسح.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const ar: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'مخصص (اكتب أدناه)...',
--- a/apps/web/src/i18n/locales/de.ts
+++ b/apps/web/src/i18n/locales/de.ts
@ -85,6 +85,15 @@ export const de: Dict = {
  'settings.testAgentMissing': '{agentName} ist nicht installiert oder nicht im PATH.',
  'settings.testAgentSpawn': '{agentName} konnte nicht gestartet werden: {detail}.',
  'settings.testUnknown': 'Test fehlgeschlagen: {detail}',
+  'settings.agentInstall.install': 'Installieren',
+  'settings.agentInstall.docs': 'Doku',
+  'settings.agentInstall.pathHint':
+    'Wenn Sie eine CLI mit npm oder Homebrew installiert haben und sie weiterhin als nicht installiert angezeigt wird, stellen Sie sicher, dass das Bin-Verzeichnis der CLI im PATH enthalten ist, den der Open-Design-Daemon erbt (Terminal und GUI-Apps koennen sich unter macOS unterscheiden). Siehe QUICKSTART.md (Abschnitt "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Oeffnen Sie Installieren oder Doku fuer den gewuenschten Agenten.',
+  'settings.agentInstall.stepAuth':
+    'Authentifizieren Sie sich mit der Anbieter-CLI (anmelden oder API-Zugangsdaten setzen), bevor Sie zu Open Design zurueckkehren.',
+  'settings.agentInstall.stepRescan': 'Klicken Sie in diesem Bereich auf Neu scannen.',
+  'settings.agentInstall.stepSelect': 'Waehlen Sie die Agent-Karte aus, sobald sie als installiert angezeigt wird.',
  'settings.noAgentsDetected':
    'Noch keine Agents erkannt. Installieren Sie Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen oder GitHub Copilot CLI und klicken Sie dann auf Neu scannen.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const de: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Benutzerdefiniert (unten eingeben)…',
--- a/apps/web/src/i18n/locales/en.ts
+++ b/apps/web/src/i18n/locales/en.ts
@ -83,6 +83,15 @@ export const en: Dict = {
  'settings.testAgentMissing': '{agentName} is not installed or not in PATH.',
  'settings.testAgentSpawn': 'Could not start {agentName}: {detail}.',
  'settings.testUnknown': 'Test failed: {detail}',
+  'settings.agentInstall.install': 'Install',
+  'settings.agentInstall.docs': 'Docs',
+  'settings.agentInstall.pathHint':
+    'If you installed a CLI with npm or Homebrew and it still shows as not installed, ensure the tool\'s bin directory is on the PATH the Open Design daemon inherits (Terminal vs GUI apps can differ on macOS). See QUICKSTART.md (section "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Open Install or Docs for your preferred agent.',
+  'settings.agentInstall.stepAuth':
+    'Authenticate with the vendor CLI (sign in or add API credentials) before returning to Open Design.',
+  'settings.agentInstall.stepRescan': 'Click Rescan in this section.',
+  'settings.agentInstall.stepSelect': 'Select the agent card once it appears as installed.',
  'settings.noAgentsDetected':
    'No agents detected yet. Install one of Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, or GitHub Copilot CLI, then click Rescan.',
  'settings.apiSection': 'Anthropic API',
@ -126,7 +135,7 @@ export const en: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Custom (type below)…',
--- a/apps/web/src/i18n/locales/es-ES.ts
+++ b/apps/web/src/i18n/locales/es-ES.ts
@ -85,6 +85,15 @@ export const esES: Dict = {
  'settings.testAgentMissing': '{agentName} no está instalado o no está en el PATH.',
  'settings.testAgentSpawn': 'No se pudo iniciar {agentName}: {detail}.',
  'settings.testUnknown': 'Prueba fallida: {detail}',
+  'settings.agentInstall.install': 'Instalar',
+  'settings.agentInstall.docs': 'Docs',
+  'settings.agentInstall.pathHint':
+    'Si instalaste una CLI con npm o Homebrew y sigue apareciendo como no instalada, asegúrate de que el directorio bin de la herramienta esté en el PATH que hereda el daemon de Open Design (Terminal y apps GUI pueden diferir en macOS). Consulta QUICKSTART.md (sección "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Abre Instalar o Docs para el agente que prefieras.',
+  'settings.agentInstall.stepAuth':
+    'Autentícate con la CLI del proveedor (inicia sesión o añade credenciales API) antes de volver a Open Design.',
+  'settings.agentInstall.stepRescan': 'Haz clic en Reescanear en esta sección.',
+  'settings.agentInstall.stepSelect': 'Selecciona la tarjeta del agente cuando aparezca como instalado.',
  'settings.noAgentsDetected':
    'Aún no se ha detectado ningún agente. Instala Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen o GitHub Copilot CLI y pulsa Reescanear.',
  'settings.apiSection': 'API de Anthropic',
@ -128,7 +137,7 @@ export const esES: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Personalizado (escribe abajo)…',
--- a/apps/web/src/i18n/locales/fa.ts
+++ b/apps/web/src/i18n/locales/fa.ts
@ -85,6 +85,15 @@ export const fa: Dict = {
  'settings.testAgentMissing': '{agentName} نصب نشده یا در PATH نیست.',
  'settings.testAgentSpawn': '{agentName} اجرا نشد: {detail}.',
  'settings.testUnknown': 'آزمایش ناموفق بود: {detail}',
+  'settings.agentInstall.install': 'نصب',
+  'settings.agentInstall.docs': 'مستندات',
+  'settings.agentInstall.pathHint':
+    'اگر CLI را با npm یا Homebrew نصب کرده‌اید اما هنوز به‌صورت نصب‌نشده نمایش داده می‌شود، مطمئن شوید پوشه bin ابزار در PATHای باشد که daemon اوپن دیزاین به ارث می‌برد (در macOS ممکن است PATH ترمینال و برنامه‌های GUI متفاوت باشد). بخش "Local agent CLI and PATH" در QUICKSTART.md را ببینید.',
+  'settings.agentInstall.stepOpenLinks': 'برای عامل موردنظر، لینک نصب یا مستندات را باز کنید.',
+  'settings.agentInstall.stepAuth':
+    'قبل از بازگشت به Open Design، در CLI ارائه‌دهنده احراز هویت کنید (ورود یا افزودن اطلاعات API).',
+  'settings.agentInstall.stepRescan': 'در این بخش روی اسکن مجدد کلیک کنید.',
+  'settings.agentInstall.stepSelect': 'وقتی عامل به‌صورت نصب‌شده نمایش داده شد، کارت آن را انتخاب کنید.',
  'settings.noAgentsDetected':
    'هنوز هیچ عاملی شناسایی نشده. یکی از Claude Code، Codex، Gemini CLI، OpenCode، Cursor Agent، Qwen یا GitHub Copilot CLI را نصب کنید، سپس روی اسکن مجدد کلیک کنید.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const fa: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'سفارشی (در زیر تایپ کنید)…',
--- a/apps/web/src/i18n/locales/fr.ts
+++ b/apps/web/src/i18n/locales/fr.ts
@ -85,6 +85,15 @@ export const fr: Dict = {
  'settings.testAgentMissing': '{agentName} n’est pas installé ou pas dans le PATH.',
  'settings.testAgentSpawn': 'Impossible de démarrer {agentName} : {detail}.',
  'settings.testUnknown': 'Échec du test : {detail}',
+  'settings.agentInstall.install': 'Installer',
+  'settings.agentInstall.docs': 'Docs',
+  'settings.agentInstall.pathHint':
+    'Si vous avez installé une CLI avec npm ou Homebrew et qu\'elle apparaît toujours comme non installée, vérifiez que le dossier bin de l\'outil est dans le PATH hérité par le daemon Open Design (Terminal et apps GUI peuvent différer sur macOS). Voir QUICKSTART.md (section "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Ouvrez Installer ou Docs pour l\'agent souhaité.',
+  'settings.agentInstall.stepAuth':
+    'Authentifiez-vous avec la CLI du fournisseur (connexion ou ajout des identifiants API) avant de revenir dans Open Design.',
+  'settings.agentInstall.stepRescan': 'Cliquez sur Réanalyser dans cette section.',
+  'settings.agentInstall.stepSelect': 'Sélectionnez la carte de l\'agent une fois qu\'elle apparaît comme installée.',
  'settings.noAgentsDetected':
    'Aucun agent détecté pour l\'instant. Installez Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen ou GitHub Copilot CLI, puis cliquez sur Réanalyser.',
  'settings.apiSection': 'API Anthropic',
@ -128,7 +137,7 @@ export const fr: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Personnalisé (saisir ci-dessous)…',
--- a/apps/web/src/i18n/locales/hu.ts
+++ b/apps/web/src/i18n/locales/hu.ts
@ -85,6 +85,15 @@ export const hu: Dict = {
  'settings.testAgentMissing': 'A(z) {agentName} nincs telepítve vagy nincs a PATH-ban.',
  'settings.testAgentSpawn': 'Nem sikerült elindítani: {agentName} — {detail}.',
  'settings.testUnknown': 'Sikertelen teszt: {detail}',
+  'settings.agentInstall.install': 'Telepítés',
+  'settings.agentInstall.docs': 'Dokumentáció',
+  'settings.agentInstall.pathHint':
+    'Ha npm-mel vagy Homebrew-val telepítettél egy CLI-t, de továbbra is nincs telepítve állapotban látszik, ellenőrizd, hogy az eszköz bin könyvtára benne van-e abban a PATH-ban, amit az Open Design daemon örököl (macOS-en a Terminal és a GUI appok PATH-ja eltérhet). Lásd a QUICKSTART.md "Local agent CLI and PATH" szakaszát.',
+  'settings.agentInstall.stepOpenLinks': 'Nyisd meg a Telepítés vagy Dokumentáció hivatkozást a kívánt ügynöknél.',
+  'settings.agentInstall.stepAuth':
+    'Hitelesíts a szolgáltató CLI-jében (bejelentkezés vagy API hitelesítő adatok megadása), mielőtt visszatérsz az Open Designhoz.',
+  'settings.agentInstall.stepRescan': 'Kattints az Újraellenőrzés gombra ebben a szakaszban.',
+  'settings.agentInstall.stepSelect': 'Válaszd ki az ügynök kártyáját, amint telepítettként jelenik meg.',
  'settings.noAgentsDetected':
    'Még nincs észlelt ügynök. Telepítsd a Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen vagy GitHub Copilot CLI valamelyikét, majd kattints az Újraellenőrzésre.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const hu: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Egyedi (gépeld be alább)…',
--- a/apps/web/src/i18n/locales/id.ts
+++ b/apps/web/src/i18n/locales/id.ts
@ -84,6 +84,15 @@ export const id: Dict = {
  'settings.testAgentMissing': '{agentName} tidak terpasang atau tidak ada di PATH.',
  'settings.testAgentSpawn': 'Tidak dapat memulai {agentName}: {detail}.',
  'settings.testUnknown': 'Tes gagal: {detail}',
+  'settings.agentInstall.install': 'Instal',
+  'settings.agentInstall.docs': 'Dokumentasi',
+  'settings.agentInstall.pathHint':
+    'Jika Anda memasang CLI dengan npm atau Homebrew tetapi masih tampil sebagai belum terpasang, pastikan direktori bin alat ada di PATH yang diwarisi daemon Open Design (PATH Terminal dan aplikasi GUI bisa berbeda di macOS). Lihat QUICKSTART.md (bagian "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Buka Instal atau Dokumentasi untuk agen pilihan Anda.',
+  'settings.agentInstall.stepAuth':
+    'Lakukan autentikasi di CLI vendor (masuk atau tambahkan kredensial API) sebelum kembali ke Open Design.',
+  'settings.agentInstall.stepRescan': 'Klik Pindai ulang di bagian ini.',
+  'settings.agentInstall.stepSelect': 'Pilih kartu agen setelah statusnya terpasang.',
  'settings.noAgentsDetected':
    'Belum ada agent terdeteksi. Pasang salah satu dari Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, atau GitHub Copilot CLI, lalu klik pindai ulang.',
  'settings.apiSection': 'Anthropic API',
--- a/apps/web/src/i18n/locales/ja.ts
+++ b/apps/web/src/i18n/locales/ja.ts
@ -85,6 +85,15 @@ export const ja: Dict = {
  'settings.testAgentMissing': '{agentName} がインストールされていないか、PATH にありません。',
  'settings.testAgentSpawn': '{agentName} を起動できませんでした: {detail}。',
  'settings.testUnknown': 'テストに失敗しました: {detail}',
+  'settings.agentInstall.install': 'インストール',
+  'settings.agentInstall.docs': 'ドキュメント',
+  'settings.agentInstall.pathHint':
+    'npm または Homebrew で CLI をインストールしたのに未インストールのまま表示される場合は、Open Design daemon が引き継ぐ PATH にツールの bin ディレクトリが含まれていることを確認してください（macOS では Terminal と GUI アプリで PATH が異なる場合があります）。QUICKSTART.md（"Local agent CLI and PATH" セクション）を参照してください。',
+  'settings.agentInstall.stepOpenLinks': '利用したいエージェントの「インストール」または「ドキュメント」を開きます。',
+  'settings.agentInstall.stepAuth':
+    'Open Design に戻る前に、ベンダー CLI で認証（サインインまたは API 資格情報の追加）を行います。',
+  'settings.agentInstall.stepRescan': 'このセクションで「再スキャン」をクリックします。',
+  'settings.agentInstall.stepSelect': 'インストール済みとして表示されたらエージェントカードを選択します。',
  'settings.noAgentsDetected':
    'エージェントが検出されませんでした。Claude Code、Codex、Gemini CLI、OpenCode、Cursor Agent、Qwen、または GitHub Copilot CLI のいずれかをインストールして、再スキャンをクリックしてください。',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const ja: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'カスタム（下に入力）…',
--- a/apps/web/src/i18n/locales/ko.ts
+++ b/apps/web/src/i18n/locales/ko.ts
@ -85,6 +85,15 @@ export const ko: Dict = {
  'settings.testAgentMissing': '{agentName}이(가) 설치되어 있지 않거나 PATH에 없습니다.',
  'settings.testAgentSpawn': '{agentName}을(를) 시작할 수 없습니다: {detail}.',
  'settings.testUnknown': '테스트 실패: {detail}',
+  'settings.agentInstall.install': '설치',
+  'settings.agentInstall.docs': '문서',
+  'settings.agentInstall.pathHint':
+    'npm 또는 Homebrew로 CLI를 설치했는데도 아직 미설치로 표시된다면, Open Design daemon이 상속받는 PATH에 도구의 bin 디렉터리가 포함되어 있는지 확인하세요(macOS에서는 Terminal과 GUI 앱의 PATH가 다를 수 있습니다). QUICKSTART.md("Local agent CLI and PATH" 섹션)를 참고하세요.',
+  'settings.agentInstall.stepOpenLinks': '원하는 에이전트 카드에서 설치 또는 문서 링크를 여세요.',
+  'settings.agentInstall.stepAuth':
+    'Open Design으로 돌아오기 전에 공급자 CLI에서 인증(로그인 또는 API 자격 증명 추가)을 완료하세요.',
+  'settings.agentInstall.stepRescan': '이 섹션에서 다시 스캔을 클릭하세요.',
+  'settings.agentInstall.stepSelect': '설치됨으로 표시되면 해당 에이전트 카드를 선택하세요.',
  'settings.noAgentsDetected':
    '에이전트가 감지되지 않았습니다. Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen 또는 GitHub Copilot CLI 중 하나를 설치한 후 다시 스캔을 클릭하세요.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const ko: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': '직접 입력…',
--- a/apps/web/src/i18n/locales/pl.ts
+++ b/apps/web/src/i18n/locales/pl.ts
@ -85,6 +85,15 @@ export const pl: Dict = {
  'settings.testAgentMissing': '{agentName} nie jest zainstalowany lub nie jest w PATH.',
  'settings.testAgentSpawn': 'Nie można uruchomić {agentName}: {detail}.',
  'settings.testUnknown': 'Test nieudany: {detail}',
+  'settings.agentInstall.install': 'Zainstaluj',
+  'settings.agentInstall.docs': 'Dokumentacja',
+  'settings.agentInstall.pathHint':
+    'Jeśli zainstalowano CLI przez npm lub Homebrew, ale nadal widnieje jako niezainstalowana, upewnij się, że katalog bin narzędzia jest w PATH dziedziczonym przez daemon Open Design (na macOS PATH w Terminalu i aplikacjach GUI może się różnić). Zobacz QUICKSTART.md (sekcja "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Otwórz Zainstaluj lub Dokumentacja dla wybranego agenta.',
+  'settings.agentInstall.stepAuth':
+    'Uwierzytelnij się w CLI dostawcy (zaloguj się lub dodaj dane API), zanim wrócisz do Open Design.',
+  'settings.agentInstall.stepRescan': 'Kliknij Ponów skanowanie w tej sekcji.',
+  'settings.agentInstall.stepSelect': 'Wybierz kartę agenta, gdy pojawi się jako zainstalowany.',
  'settings.noAgentsDetected':
      'Nie wykryto jeszcze żadnych agentów. Zainstaluj Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen lub GitHub Copilot CLI, a następnie kliknij Ponów skanowanie.',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const pl: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Własny (wpisz poniżej)…',
--- a/apps/web/src/i18n/locales/pt-BR.ts
+++ b/apps/web/src/i18n/locales/pt-BR.ts
@ -85,6 +85,15 @@ export const ptBR: Dict = {
  'settings.testAgentMissing': '{agentName} não está instalado ou não está no PATH.',
  'settings.testAgentSpawn': 'Não foi possível iniciar {agentName}: {detail}.',
  'settings.testUnknown': 'Falha no teste: {detail}',
+  'settings.agentInstall.install': 'Instalar',
+  'settings.agentInstall.docs': 'Docs',
+  'settings.agentInstall.pathHint':
+    'Se você instalou uma CLI com npm ou Homebrew e ela ainda aparece como não instalada, garanta que o diretório bin da ferramenta esteja no PATH herdado pelo daemon do Open Design (Terminal e apps GUI podem diferir no macOS). Veja QUICKSTART.md (seção "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Abra Instalar ou Docs para o agente desejado.',
+  'settings.agentInstall.stepAuth':
+    'Autentique-se na CLI do fornecedor (faça login ou adicione credenciais de API) antes de voltar ao Open Design.',
+  'settings.agentInstall.stepRescan': 'Clique em Reescanear nesta seção.',
+  'settings.agentInstall.stepSelect': 'Selecione o cartão do agente quando ele aparecer como instalado.',
  'settings.noAgentsDetected':
    'Nenhum agente detectado ainda. Instale Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen ou GitHub Copilot CLI e clique em Reescanear.',
  'settings.apiSection': 'API da Anthropic',
@ -128,7 +137,7 @@ export const ptBR: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Personalizado (digite abaixo)…',
--- a/apps/web/src/i18n/locales/ru.ts
+++ b/apps/web/src/i18n/locales/ru.ts
@ -85,6 +85,15 @@ export const ru: Dict = {
  'settings.testAgentMissing': '{agentName} не установлен или отсутствует в PATH.',
  'settings.testAgentSpawn': 'Не удалось запустить {agentName}: {detail}.',
  'settings.testUnknown': 'Тест не пройден: {detail}',
+  'settings.agentInstall.install': 'Установить',
+  'settings.agentInstall.docs': 'Документация',
+  'settings.agentInstall.pathHint':
+    'Если вы установили CLI через npm или Homebrew, но она всё ещё отмечена как не установленная, убедитесь, что bin-каталог инструмента есть в PATH, который наследует daemon Open Design (в macOS PATH у Terminal и GUI-приложений может отличаться). См. QUICKSTART.md (раздел "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Откройте Установить или Документация для нужного агента.',
+  'settings.agentInstall.stepAuth':
+    'Пройдите аутентификацию в CLI поставщика (вход или добавление API-ключей), затем вернитесь в Open Design.',
+  'settings.agentInstall.stepRescan': 'Нажмите «Пересканировать» в этом разделе.',
+  'settings.agentInstall.stepSelect': 'Выберите карточку агента, когда он появится как установленный.',
  'settings.noAgentsDetected':
    'Агенты ещё не обнаружены. Установите один из следующих инструментов: Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen или GitHub Copilot CLI, затем нажмите «Пересканировать».',
  'settings.apiSection': 'Anthropic API',
@ -128,7 +137,7 @@ export const ru: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Пользовательская (введите ниже)…',
--- a/apps/web/src/i18n/locales/th.ts
+++ b/apps/web/src/i18n/locales/th.ts
@ -83,6 +83,15 @@ export const th: Dict = {
  'settings.testAgentMissing': 'ยังไม่ได้ติดตั้ง {agentName} หรือไม่ได้อยู่ใน PATH',
  'settings.testAgentSpawn': 'ไม่สามารถเริ่ม {agentName} ได้: {detail}',
  'settings.testUnknown': 'การทดสอบล้มเหลว: {detail}',
+  'settings.agentInstall.install': 'ติดตั้ง',
+  'settings.agentInstall.docs': 'เอกสาร',
+  'settings.agentInstall.pathHint':
+    'หากคุณติดตั้ง CLI ด้วย npm หรือ Homebrew แล้วแต่ยังแสดงว่าไม่ได้ติดตั้ง โปรดตรวจสอบว่าโฟลเดอร์ bin ของเครื่องมือนั้นอยู่ใน PATH ที่ Open Design daemon ใช้งาน (บน macOS ค่า PATH ของ Terminal และแอป GUI อาจต่างกัน) ดู QUICKSTART.md (ส่วน "Local agent CLI and PATH")',
+  'settings.agentInstall.stepOpenLinks': 'เปิดลิงก์ติดตั้งหรือเอกสารสำหรับเอเจนต์ที่ต้องการ',
+  'settings.agentInstall.stepAuth':
+    'ยืนยันตัวตนกับ CLI ของผู้ให้บริการ (ลงชื่อเข้าใช้หรือเพิ่มข้อมูลรับรอง API) ก่อนกลับไปที่ Open Design',
+  'settings.agentInstall.stepRescan': 'คลิกสแกนใหม่ในส่วนนี้',
+  'settings.agentInstall.stepSelect': 'เลือกการ์ดเอเจนต์เมื่อแสดงว่าได้ติดตั้งแล้ว',
  'settings.noAgentsDetected': 'ยังไม่พบเอเจนต์ โปรดติดตั้งอย่างใดอย่างหนึ่ง: Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen หรือ GitHub Copilot CLI แล้วคลิกสแกนใหม่',
  'settings.apiSection': 'Anthropic API',
  'settings.quickFillProvider': 'เลือกผู้ให้บริการอย่างรวดเร็ว',
--- a/apps/web/src/i18n/locales/tr.ts
+++ b/apps/web/src/i18n/locales/tr.ts
@ -85,6 +85,15 @@ export const tr: Dict = {
  'settings.testAgentMissing': '{agentName} yüklü değil veya PATH\'te yok.',
  'settings.testAgentSpawn': '{agentName} başlatılamadı: {detail}.',
  'settings.testUnknown': 'Test başarısız: {detail}',
+  'settings.agentInstall.install': 'Yükle',
+  'settings.agentInstall.docs': 'Dokümanlar',
+  'settings.agentInstall.pathHint':
+    'Bir CLI\'yi npm veya Homebrew ile kurduysan ancak hâlâ kurulu değil olarak görünüyorsa, aracın bin dizininin Open Design daemon\'unun devraldığı PATH içinde olduğundan emin ol (macOS\'te Terminal ve GUI uygulamalarının PATH\'i farklı olabilir). QUICKSTART.md içindeki "Local agent CLI and PATH" bölümüne bak.',
+  'settings.agentInstall.stepOpenLinks': 'Tercih ettiğin ajan için Yükle veya Dokümanlar bağlantısını aç.',
+  'settings.agentInstall.stepAuth':
+    'Open Design\'a dönmeden önce sağlayıcı CLI\'sinde kimlik doğrulaması yap (oturum aç veya API kimlik bilgileri ekle).',
+  'settings.agentInstall.stepRescan': 'Bu bölümde Yeniden tara\'ya tıkla.',
+  'settings.agentInstall.stepSelect': 'Ajan yüklü olarak göründüğünde kartını seç.',
  'settings.noAgentsDetected':
    'Hiçbir ajan tespit edilemedi. Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, veya GitHub Copilot CLI’lardan birini kurun ve yeniden tarayın.',
  'settings.apiSection': 'Anthropic API',
--- a/apps/web/src/i18n/locales/uk.ts
+++ b/apps/web/src/i18n/locales/uk.ts
@ -86,6 +86,15 @@ export const uk: Dict = {
  'settings.testAgentMissing': '{agentName} не встановлено або не знайдено в PATH.',
  'settings.testAgentSpawn': 'Не вдалося запустити {agentName}: {detail}.',
  'settings.testUnknown': 'Тест не виконано: {detail}',
+  'settings.agentInstall.install': 'Встановити',
+  'settings.agentInstall.docs': 'Документація',
+  'settings.agentInstall.pathHint':
+    'Якщо ви встановили CLI через npm або Homebrew, але вона все ще відображається як не встановлена, переконайтеся, що bin-каталог інструмента є у PATH, який успадковує daemon Open Design (у macOS PATH у Terminal і GUI-застосунків може відрізнятися). Див. QUICKSTART.md (розділ "Local agent CLI and PATH").',
+  'settings.agentInstall.stepOpenLinks': 'Відкрийте Встановити або Документація для потрібного агента.',
+  'settings.agentInstall.stepAuth':
+    'Пройдіть автентифікацію у CLI постачальника (увійдіть або додайте API-облікові дані), потім поверніться до Open Design.',
+  'settings.agentInstall.stepRescan': 'Натисніть «Пересканувати» у цьому розділі.',
+  'settings.agentInstall.stepSelect': 'Виберіть картку агента, коли він з\'явиться як встановлений.',
  'settings.noAgentsDetected':
    'Агентів ще не виявлено. Встановіть один з: Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen або GitHub Copilot CLI, а потім натисніть Переканувати.',
  'settings.apiSection': 'Anthropic API',
@ -129,7 +138,7 @@ export const uk: Dict = {
  'settings.cliEnvTitle': 'CLI config locations',
  'settings.cliEnvHint':
    'Set non-secret config directories for packaged app runs and agent detection.',
-  'settings.cliEnvClaudeConfigDir': 'Claude Code config dir',
+  'settings.cliEnvClaudeConfigDir': 'Claude Code config directory',
  'settings.cliEnvCodexHome': 'Codex home',
  'settings.cliEnvCodexBin': 'Codex executable path',
  'settings.modelCustom': 'Власна (введіть нижче)…',
--- a/apps/web/src/i18n/locales/zh-CN.ts
+++ b/apps/web/src/i18n/locales/zh-CN.ts
@ -82,6 +82,15 @@ export const zhCN: Dict = {
  'settings.testAgentMissing': '{agentName} 未安装，或不在 PATH 中。',
  'settings.testAgentSpawn': '无法启动 {agentName}：{detail}。',
  'settings.testUnknown': '测试失败：{detail}',
+  'settings.agentInstall.install': '安装',
+  'settings.agentInstall.docs': '文档',
+  'settings.agentInstall.pathHint':
+    '如果你通过 npm 或 Homebrew 安装了 CLI，但仍显示为未安装，请确认该工具的 bin 目录已加入 Open Design daemon 继承的 PATH（在 macOS 上，Terminal 与 GUI 应用的 PATH 可能不同）。请参阅 QUICKSTART.md（“Local agent CLI and PATH” 章节）。',
+  'settings.agentInstall.stepOpenLinks': '在目标代理卡片上打开“安装”或“文档”链接。',
+  'settings.agentInstall.stepAuth':
+    '返回 Open Design 之前，请先在对应 CLI 中完成认证（登录或添加 API 凭据）。',
+  'settings.agentInstall.stepRescan': '在此区域点击“重新扫描”。',
+  'settings.agentInstall.stepSelect': '当代理显示为已安装后，选择该代理卡片。',
  'settings.noAgentsDetected':
    '尚未检测到任何代理。请安装 Claude Code、Codex、Gemini CLI、OpenCode、Cursor Agent、Qwen 或 GitHub Copilot CLI 中的一个，然后点击「重新扫描」。',
  'settings.apiSection': 'Anthropic API',
--- a/apps/web/src/i18n/locales/zh-TW.ts
+++ b/apps/web/src/i18n/locales/zh-TW.ts
@ -82,6 +82,15 @@ export const zhTW: Dict = {
  'settings.testAgentMissing': '{agentName} 未安裝，或不在 PATH 中。',
  'settings.testAgentSpawn': '無法啟動 {agentName}：{detail}。',
  'settings.testUnknown': '測試失敗：{detail}',
+  'settings.agentInstall.install': '安裝',
+  'settings.agentInstall.docs': '文件',
+  'settings.agentInstall.pathHint':
+    '如果你透過 npm 或 Homebrew 安裝了 CLI，但仍顯示為未安裝，請確認該工具的 bin 目錄已加入 Open Design daemon 繼承的 PATH（在 macOS 上，Terminal 與 GUI 應用的 PATH 可能不同）。請參閱 QUICKSTART.md（「Local agent CLI and PATH」章節）。',
+  'settings.agentInstall.stepOpenLinks': '在目標代理卡片上開啟「安裝」或「文件」連結。',
+  'settings.agentInstall.stepAuth':
+    '返回 Open Design 前，請先在對應 CLI 完成驗證（登入或新增 API 憑證）。',
+  'settings.agentInstall.stepRescan': '在此區域點擊「重新掃描」。',
+  'settings.agentInstall.stepSelect': '當代理顯示為已安裝後，選擇該代理卡片。',
  'settings.noAgentsDetected':
    '尚未偵測到任何代理。請安裝 Claude Code、Codex、Gemini CLI、OpenCode、Cursor Agent 或 Qwen 其中之一，然後點擊「重新掃描」。',
  'settings.apiSection': 'API 設定',
--- a/apps/web/src/i18n/types.ts
+++ b/apps/web/src/i18n/types.ts
@ -112,6 +112,13 @@ export interface Dict {
  'settings.testAgentMissing': string;
  'settings.testAgentSpawn': string;
  'settings.testUnknown': string;
+  'settings.agentInstall.install': string;
+  'settings.agentInstall.docs': string;
+  'settings.agentInstall.pathHint': string;
+  'settings.agentInstall.stepOpenLinks': string;
+  'settings.agentInstall.stepAuth': string;
+  'settings.agentInstall.stepRescan': string;
+  'settings.agentInstall.stepSelect': string;
  'settings.noAgentsDetected': string;
  'settings.apiSection': string;
  'settings.quickFillProvider': string;
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@ -3343,6 +3343,41 @@ code {
  opacity: 0.55;
  background: var(--bg-subtle);
 }
+.agent-card.disabled.agent-card-unavailable {
+  opacity: 0.72;
+}
+.agent-card-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 12px;
+  margin-top: 6px;
+}
+.agent-card-link {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--accent);
+  text-decoration: none;
+}
+.agent-card-link:hover {
+  text-decoration: underline;
+}
+.agent-install-path-hint {
+  margin-top: 10px;
+  margin-bottom: 0;
+}
+.agent-install-guide {
+  margin-top: 10px;
+}
+.agent-install-steps {
+  margin: 8px 0 0;
+  padding-left: 18px;
+  color: var(--text-muted);
+  font-size: 12px;
+  line-height: 1.45;
+}
+.agent-install-steps li + li {
+  margin-top: 4px;
+}
 .agent-card-body { display: flex; flex-direction: column; min-width: 0; flex: 1; }
 .agent-card-name {
  font-size: 13px; font-weight: 600; color: var(--text);
--- a/apps/web/tests/components/SettingsDialog.execution.test.tsx
+++ b/apps/web/tests/components/SettingsDialog.execution.test.tsx
@ -1,7 +1,8 @@
 // @vitest-environment jsdom

-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { en } from '../../src/i18n/locales/en';

 const {
  playSoundMock,
@ -499,6 +500,8 @@ describe('SettingsDialog execution settings Local CLI interactions', () => {
      available: false,
      version: null,
      models: [],
+      installUrl: 'https://github.com/google-gemini/gemini-cli',
+      docsUrl: 'https://github.com/google-gemini/gemini-cli/blob/main/README.md',
    };
    const { onPersist } = renderSettingsDialog(
      { mode: 'daemon', agentId: null },
@ -509,8 +512,19 @@ describe('SettingsDialog execution settings Local CLI interactions', () => {
    fireEvent.click(localCliTab);

    const codexCard = screen.getByRole('button', { name: /Codex CLI/i }) as HTMLButtonElement;
-    const geminiCard = screen.getByRole('button', { name: /Gemini CLI/i }) as HTMLButtonElement;
-    expect(geminiCard.disabled).toBe(true);
+    const geminiGroup = screen.getByRole('group', { name: /Gemini CLI/i });
+    expect(
+      (within(geminiGroup).getByRole('link', { name: en['settings.agentInstall.install'] }) as HTMLAnchorElement).getAttribute('href'),
+    ).toBe(
+      'https://github.com/google-gemini/gemini-cli',
+    );
+    expect(
+      screen.getByText(en['settings.agentInstall.stepAuth']),
+    ).toBeTruthy();
+    expect(
+      screen.getByText(en['settings.agentInstall.stepSelect']),
+    ).toBeTruthy();
+    expect(screen.getByText(en['settings.agentInstall.pathHint'])).toBeTruthy();

    fireEvent.click(codexCard);
    await waitForPersist(
@ -602,7 +616,7 @@ describe('SettingsDialog execution settings Local CLI interactions', () => {

    fireEvent.click(screen.getByRole('tab', { name: /Local CLI.*1 installed/i }));

-    fireEvent.change(screen.getByLabelText('Claude Code config dir'), {
+    fireEvent.change(screen.getByLabelText('Claude Code config directory'), {
      target: { value: '  ~/.claude-qa  ' },
    });
    fireEvent.change(screen.getByLabelText('Codex home'), {
--- a/packages/contracts/src/api/registry.ts
+++ b/packages/contracts/src/api/registry.ts
@ -12,6 +12,10 @@ export interface AgentInfo {
  version?: string | null;
  models?: AgentModelOption[];
  reasoningOptions?: AgentModelOption[];
+  /** HTTPS URL to install or download the CLI (vendor docs, GitHub README, npm). */
+  installUrl?: string;
+  /** Optional HTTPS URL for configuration / auth / usage docs. */
+  docsUrl?: string;
 }

 export interface AgentsResponse {