mixdog 0.7.4 → 0.7.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Claude Code all-in-one agent plugin — autonomous agents, continuous memory, cost-aware sub-agents, and syntax-aware code editing.",
   "hooks": "./hooks/hooks.json",
   "mcpServers": {

package/README.md

@@ -48,6 +48,20 @@ as JSON you can diff.
 
 ## Install
 
+**From npm (terminal):**
+
+```bash
+npx mixdog setup          # register plugin + run the setup wizard
+npm i -g mixdog           # then launch Claude Code with mixdog pre-loaded:
+mixdog                    # → claude --dangerously-load-development-channels plugin:mixdog@trib-plugin
+mixdog --dangerously-skip-permissions   # extra Claude flags pass through
+```
+
+`mixdog` (no subcommand) starts Claude Code with mixdog pre-loaded; the `claude`
+CLI must be on your PATH.
+
+**Inside Claude Code (slash commands):**
+
 ```
 /plugin marketplace add trib-plugin/mixdog
 /plugin install mixdog@trib-plugin

package/hooks/hooks.json

@@ -7,17 +7,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=rules",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=rules",
             "timeout": 30
           },
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=core",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=core",
             "timeout": 130
           },
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=recap",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=recap",
             "timeout": 130
           }
         ]
@@ -29,7 +29,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\"",
             "timeout": 10
           }
         ]
@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --kind=post-tool",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --kind=post-tool",
             "timeout": 5
           }
         ]
@@ -70,4 +70,4 @@
       }
     ]
   }
-}
+}

package/hooks/shim-launcher.cjs

@@ -0,0 +1,51 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SHIM_ARCH_ALIAS = Object.freeze({
+  x64: 'x86_64',
+  arm64: 'aarch64',
+  ia32: 'i686',
+});
+
+function shimBinExt() {
+  return process.platform === 'win32' ? '.exe' : '';
+}
+
+function shimArchTag() {
+  const arch = SHIM_ARCH_ALIAS[process.arch] || process.arch;
+  const os = process.platform === 'win32' ? 'windows'
+    : process.platform === 'darwin' ? 'macos'
+    : 'linux';
+  return `${os}-${arch}`;
+}
+
+function resolveShim(pluginRoot) {
+  const ext = shimBinExt();
+  const name = 'mixdog-shim' + ext;
+  const candidates = [
+    path.join(pluginRoot, 'native', 'mixdog-shim', 'target', 'release', name),
+    path.join(pluginRoot, 'native', 'prebuilt', shimArchTag(), name),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+if (!pluginRoot) process.exit(0);
+
+const shimPath = resolveShim(pluginRoot);
+if (!shimPath) process.exit(0);
+
+const child = spawnSync(shimPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+process.exit(child.status ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Claude Code all-in-one bridge plugin: role-based bridge workers, continuous memory, and syntax-aware code editing.",
   "author": "mixdog contributors <dev@tribgames.com>",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "bin": {
     "mcfg": "./setup/launch.mjs",
     "mixdog-install": "./setup/install.mjs",
-    "mixdog": "./setup/install.mjs"
+    "mixdog": "./setup/mixdog-cli.mjs"
   },
   "engines": {
     "bun": ">=1.1.0"

package/setup/install.mjs

@@ -2,8 +2,8 @@
 // install.mjs — one-shot bootstrapper that registers the mixdog plugin in the
 // user's Claude Code settings so it auto-loads on the next session start.
 //
-// Run via:  npx -p mixdog mixdog-install   (after the package is published)
-//       or:  node setup/install.mjs          (from a checkout)
+// Run via:  npx mixdog setup | mixdog-install   (after the package is published)
+//       or:  node setup/install.mjs             (from a checkout)
 //
 // It merges two keys into the user-scope settings file (preserving everything
 // else that is already there):
@@ -22,6 +22,8 @@ import {
 } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { spawn } from 'node:child_process';
 import { DEFAULT_MARKETPLACE, DEFAULT_PLUGIN } from '../src/shared/plugin-paths.mjs';
@@ -31,9 +33,23 @@ const PLUGIN_REF = `${DEFAULT_PLUGIN}@${DEFAULT_MARKETPLACE}`;
 const REPO = 'trib-plugin/mixdog';        // github owner/repo
 const REPO_URL = 'https://github.com/trib-plugin/mixdog';
 
+/** Claude config root — matches Claude Code (settings + plugins tree). */
+export function claudeConfigBaseDir() {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+
 // Claude Code honours CLAUDE_CONFIG_DIR; otherwise the user scope is ~/.claude.
 function settingsDir() {
-  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+  return claudeConfigBaseDir();
+}
+
+export function defaultPluginDataDir() {
+  return join(
+    claudeConfigBaseDir(),
+    'plugins',
+    'data',
+    `${DEFAULT_PLUGIN}-${MARKETPLACE}`,
+  );
 }
 
 function loadSettings(file) {
@@ -91,17 +107,14 @@ function registerPluginInSettings() {
   console.log(`\nNext: restart Claude Code (or run /reload-plugins). mixdog loads automatically.`);
 }
 
-async function main() {
+export async function runInstall() {
   registerPluginInSettings();
 
   // npx / node setup/install.mjs runs outside Claude Code — config.mjs needs a data dir.
-  process.env.CLAUDE_PLUGIN_DATA = join(
-    homedir(),
-    '.claude',
-    'plugins',
-    'data',
-    'mixdog-trib-plugin',
-  );
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+  if (!pluginData || !String(pluginData).trim()) {
+    process.env.CLAUDE_PLUGIN_DATA = defaultPluginDataDir();
+  }
 
   const { runSetupWizard } = await import('./wizard.mjs');
   await runSetupWizard();
@@ -134,7 +147,21 @@ function openRepo() {
   }
 }
 
-main().catch((err) => {
-  console.error(err?.stack || err?.message || String(err));
-  process.exit(1);
-});
+function isInstallerEntry() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const self = realpathSync(fileURLToPath(import.meta.url));
+    const invoked = realpathSync(entry);
+    return self === invoked;
+  } catch {
+    return false;
+  }
+}
+
+if (isInstallerEntry()) {
+  runInstall().catch((err) => {
+    console.error(err?.stack || err?.message || String(err));
+    process.exit(1);
+  });
+}

package/setup/mixdog-cli.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// mixdog-cli.mjs — `mixdog` bin dispatcher: launch Claude Code with the dev
+// plugin load flags, or run setup/install on demand.
+
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { constants as osConstants } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_MARKETPLACE, DEFAULT_PLUGIN } from '../src/shared/plugin-paths.mjs';
+import { runInstall } from './install.mjs';
+
+const PLUGIN_LOAD_ARG = `plugin:${DEFAULT_PLUGIN}@${DEFAULT_MARKETPLACE}`;
+const CLAUDE_PREFIX = ['--dangerously-load-development-channels', PLUGIN_LOAD_ARG];
+
+function isSetupCommand(first) {
+  return first === 'setup' || first === 'install';
+}
+
+export function buildClaudeLaunchArgv(passthrough = []) {
+  return [...CLAUDE_PREFIX, ...passthrough];
+}
+
+export function resolveClaudeExecutable() {
+  const win32 = process.platform === 'win32';
+  try {
+    const cmd = win32 ? 'where' : 'which';
+    const out = execFileSync(cmd, ['claude'], { encoding: 'utf8', windowsHide: true }).trim();
+    const first = out.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+    if (first && existsSync(first)) return first;
+  } catch { /* PATH scan */ }
+
+  const pathSep = win32 ? ';' : ':';
+  const dirs = String(process.env.PATH || '').split(pathSep).filter(Boolean);
+  const pathext = win32
+    ? String(process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';').map((e) => e.toLowerCase())
+    : [''];
+  const bases = win32 ? ['claude'] : ['claude'];
+  for (const dir of dirs) {
+    for (const base of bases) {
+      if (win32) {
+        for (const ext of pathext) {
+          const candidate = join(dir, base + ext);
+          if (existsSync(candidate)) return candidate;
+        }
+        const bare = join(dir, base);
+        if (existsSync(bare)) return bare;
+      } else {
+        const candidate = join(dir, base);
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+export async function dispatchMixdogCli(argv = process.argv.slice(2)) {
+  const [first] = argv;
+  if (isSetupCommand(first)) {
+    if (process.env.MIXDOG_CLI_DRY_RUN === '1') {
+      process.stdout.write('mixdog-cli: route=setup\n');
+      return 0;
+    }
+    await runInstall();
+    return 0;
+  }
+
+  const claudeArgs = buildClaudeLaunchArgv(argv);
+  if (process.env.MIXDOG_CLI_DRY_RUN === '1') {
+    process.stdout.write(`mixdog-cli: claude ${JSON.stringify(claudeArgs)}\n`);
+    return 0;
+  }
+
+  const claudePath = resolveClaudeExecutable();
+  if (!claudePath) {
+    process.stderr.write(
+      '\n✗ `claude` was not found on PATH. Install Claude Code first: https://docs.anthropic.com/en/docs/claude-code\n',
+    );
+    return 127;
+  }
+
+  return launchClaude(claudePath, claudeArgs);
+}
+
+function launchClaude(claudePath, claudeArgs) {
+  return new Promise((resolve) => {
+    const win32 = process.platform === 'win32';
+    const needsShell = win32 && /\.(cmd|bat)$/i.test(claudePath);
+    const child = spawn(claudePath, claudeArgs, {
+      stdio: 'inherit',
+      shell: needsShell,
+      windowsHide: true,
+    });
+
+    child.on('error', (err) => {
+      process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+      resolve(1);
+    });
+
+    child.on('close', (code, signal) => {
+      if (signal) {
+        const sigNum = osConstants.signals?.[signal] ?? 0;
+        resolve(128 + sigNum);
+        return;
+      }
+      resolve(code ?? 0);
+    });
+  });
+}
+
+function isDirectCliEntry() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const self = realpathSync(fileURLToPath(import.meta.url));
+    const invoked = realpathSync(entry);
+    return self === invoked;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectCliEntry()) {
+  dispatchMixdogCli()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(err?.stack || err?.message || String(err));
+      process.exit(1);
+    });
+}

package/setup/wizard.mjs

@@ -6,14 +6,22 @@
  * module (install.mjs does that) so src/shared/config.mjs can resolve paths.
  */
 import { createInterface } from 'node:readline';
+import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { defaultPluginDataDir } from './install.mjs';
 import {
   mergeAgentConfig,
   mergeMemoryConfig,
   mergeConfig,
+  mergeSearchConfig,
 } from './config-merge.mjs';
+import { DEFAULT_MODELS } from '../src/search/lib/config.mjs';
+
+let _linuxSecretsCapable;
+const KEYTAR_SERVICE = 'mixdog';
+const KEYTAR_PROBE_TIMEOUT_MS = 8000;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = join(__dirname, '..');
@@ -32,14 +40,77 @@ const AG_API_PROVIDERS = [
 
 const WORKFLOW_ROLES = ['worker', 'reviewer', 'debugger', 'tester'];
 
+/** Raw SERP API keys (setup.html SR_KEY_PROVIDERS) — independent of active provider. */
+const SEARCH_RAW_KEY_PROVIDERS = [
+  { id: 'firecrawl', name: 'Firecrawl' },
+  { id: 'tavily', name: 'Tavily' },
+  { id: 'exa', name: 'Exa' },
+];
+const SEARCH_OAUTH_PROVIDERS = new Set(['anthropic-oauth', 'openai-oauth', 'grok-oauth']);
+const OPENAI_SEARCH_EFFORT_VALUES = new Set(['low', 'medium', 'high']);
+const SEARCH_OAUTH_ALIASES = Object.freeze({
+  'anthropic-oauth': 'anthropic-oauth',
+  anthropic: 'anthropic-oauth',
+  'openai-oauth': 'openai-oauth',
+  openai: 'openai-oauth',
+  'grok-oauth': 'grok-oauth',
+  grok: 'grok-oauth',
+});
 function pluginDataDir() {
   const dir = process.env.CLAUDE_PLUGIN_DATA;
-  if (!dir || typeof dir !== 'string' || !String(dir).trim()) {
-    throw new Error(
-      'CLAUDE_PLUGIN_DATA must be set before running the setup wizard (install.mjs sets it unconditionally)',
-    );
+  if (dir && typeof dir === 'string' && String(dir).trim()) {
+    return String(dir).trim();
   }
-  return String(dir).trim();
+  return defaultPluginDataDir();
+}
+
+/** One-time Linux preflight: optional keytar must load before any secret prompt. */
+export function resetLinuxSecretsCapableCache() {
+  _linuxSecretsCapable = undefined;
+}
+
+function runLinuxKeytarOperationalProbe() {
+  const script = [
+    'try {',
+    'const keytar = require("keytar");',
+    'if (process.env.MIXDOG_KEYTAR_PROBE_INJECT_FAIL === "1") process.exit(3);',
+    `keytar.findCredentials(${JSON.stringify(KEYTAR_SERVICE)})`,
+    '  .then(() => process.exit(0))',
+    '  .catch((e) => { process.stderr.write(String(e && e.message ? e.message : e)); process.exit(1); });',
+    '} catch (e) { process.stderr.write(String(e && e.message ? e.message : e)); process.exit(2); }',
+  ].join(' ');
+  const r = spawnSync(process.execPath, ['-e', script], {
+    env: { ...process.env },
+    encoding: 'utf8',
+    timeout: KEYTAR_PROBE_TIMEOUT_MS,
+    windowsHide: true,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  if (r.error) return false;
+  return r.status === 0;
+}
+
+/**
+ * @param {{ treatAsLinux?: boolean }} [probeOptions] — .scratch harness only (operational probe).
+ */
+export function probeLinuxSecretsCapable(probeOptions = null) {
+  const isLinux = probeOptions?.treatAsLinux === true || process.platform === 'linux';
+  if (!isLinux) return true;
+  if (_linuxSecretsCapable !== undefined) return _linuxSecretsCapable;
+  _linuxSecretsCapable = runLinuxKeytarOperationalProbe();
+  return _linuxSecretsCapable;
+}
+
+export function linuxKeychainUnavailableMessage() {
+  return [
+    '',
+    '⚠ Linux keychain unavailable (optional `keytar` not installed or libsecret missing).',
+    '  Secret prompts are skipped; non-secret setup continues. Install keytar later, then use the Mixdog UI:',
+    '    Debian/Ubuntu: sudo apt install libsecret-1-dev   then: npm install keytar',
+    '    Fedora/RHEL:   sudo dnf install libsecret-devel then: npm install keytar',
+    '    Arch:          sudo pacman -S libsecret         then: npm install keytar',
+    '',
+  ].join('\n');
 }
 
 function sanitizeName(n) {
@@ -121,11 +192,11 @@ function readHiddenLine(prompt) {
 async function loadConfigModules() {
   const { ensureDataSeeds } = await import('../src/shared/seed.mjs');
   const { readSection, updateSection } = await import('../src/shared/config.mjs');
-  const { DEFAULT_PRESETS } = await import('../src/agent/orchestrator/config.mjs');
+  const { DEFAULT_PRESETS, DEFAULT_MAINTENANCE } = await import('../src/agent/orchestrator/config.mjs');
   const dataDir = pluginDataDir();
   mkdirSync(dataDir, { recursive: true });
   ensureDataSeeds(dataDir);
-  return { readSection, updateSection, DEFAULT_PRESETS, dataDir };
+  return { readSection, updateSection, DEFAULT_PRESETS, DEFAULT_MAINTENANCE, dataDir };
 }
 
 function readUserWorkflow(dataDir) {
@@ -175,18 +246,66 @@ function presetIdsFromAgent(agentSection) {
   return presets.map((p) => p.id || p.name).filter(Boolean);
 }
 
-async function stepDiscordToken(io, { updateSection }) {
-  io.say('\n── Step 2/7: Discord bot token ──');
-  io.say('Paste your Discord bot token (hidden). Enter to skip.');
-  const token = (await io.askSecret('Discord bot token: ')).trim();
-  if (isSkippableAnswer(token)) {
-    io.say('• Skipped Discord token.');
-    return false;
+export async function stepDiscordToken(io, { updateSection, readSection, secretsCapable = true }) {
+  const { hasStoredSecret, SECRET_ACCOUNTS, getDiscordToken } = await import('../src/shared/config.mjs');
+  io.say('\n── Step 2/9: Discord ──');
+  io.say('Bot token (keychain), application ID, and optional main channel.');
+
+  let hadStoredToken = false;
+  let token = '';
+  let enteredToken = false;
+  if (!secretsCapable) {
+    io.say('• Discord bot token: skipped (Linux keychain unavailable).');
+  } else {
+    hadStoredToken = hasStoredSecret(SECRET_ACCOUNTS.discordToken);
+    const tokenPrompt = hadStoredToken
+      ? 'Discord bot token (stored, Enter=keep): '
+      : 'Discord bot token [hidden] (Enter=skip whole step): ';
+    token = (await io.askSecret(tokenPrompt)).trim();
+    enteredToken = !isSkippableAnswer(token);
+    if (!enteredToken && !hadStoredToken) {
+      io.say('• Skipped Discord setup.');
+      return false;
+    }
   }
+
+  const channels = readSection('channels') || {};
+  const curDiscord = channels.discord && typeof channels.discord === 'object' ? channels.discord : {};
+  const curAppId = String(curDiscord.applicationId || '').trim();
+  const appIdBase = 'Application ID';
+  const appIdPrompt = curAppId
+    ? `${appIdBase} (current: ${curAppId}, Enter=keep): `
+    : `${appIdBase}: `;
+  const appIdRaw = await io.ask(appIdPrompt);
+  const appIdToSet = isSkippableAnswer(appIdRaw) ? '' : String(appIdRaw).trim();
+  // The main channel is conventionally named "main" with interactive mode;
+  // only the channel ID varies, so we ask just that. Extra channels and
+  // monitor mode are configured later in the UI.
+  const chIdRaw = await io.ask('Main channel ID (Enter=skip channel): ');
+  const channelId = isSkippableAnswer(chIdRaw) ? '' : String(chIdRaw).trim();
+  const channelName = 'main';
+  const mode = 'interactive';
   const secrets = {};
-  updateSection('channels', (current) => mergeConfig(current, { discord: { token } }, secrets));
-  io.say('• Discord token saved to keychain.');
-  return true;
+  updateSection('channels', (current) => {
+    const payload = {};
+    const discord = {};
+    if (enteredToken) discord.token = token;
+    if (appIdToSet) discord.applicationId = appIdToSet;
+    if (Object.keys(discord).length > 0) payload.discord = discord;
+    if (channelId) {
+      const existingCfg = current.channelsConfig && typeof current.channelsConfig === 'object'
+        ? { ...current.channelsConfig }
+        : {};
+      existingCfg[channelName] = { channelId, mode };
+      payload.channelsConfig = existingCfg;
+      payload.mainChannel = channelName;
+    }
+    return mergeConfig(current, payload, secrets);
+  });
+  if (enteredToken) io.say('• Discord token saved to keychain.');
+  if (appIdToSet) io.say('• Application ID saved.');
+  if (channelId) io.say(`• Main channel "${channelName}" configured (${mode}).`);
+  return enteredToken || hadStoredToken || !!getDiscordToken();
 }
 
 function formatVoiceProgress(p) {
@@ -221,7 +340,7 @@ async function installVoiceRuntime(dataDir, io) {
 /** Mirrors setup.html channels save: `voice` via POST /config → mergeConfig. */
 async function stepVoiceTranscription(io, ctx, discordTokenSaved) {
   if (!discordTokenSaved) return;
-  io.say('\n── Step 2a/7: Voice transcription (음성 전사) ──');
+  io.say('\n── Step 2a/9: Voice transcription (음성 전사) ──');
   io.say('Install local Speech-to-text (whisper.cpp) for Discord voice messages.');
   const raw = await io.ask('Enable voice transcription? [y/N] (Enter=skip): ');
   if (isSkippableAnswer(raw)) {
@@ -247,7 +366,7 @@ async function stepVoiceTranscription(io, ctx, discordTokenSaved) {
 }
 
 async function stepAddressForm(io, { updateSection, readSection }) {
-  io.say('\n── Step 1/7: Address form (호칭) ──');
+  io.say('\n── Step 1/9: Address form (호칭) ──');
   const memory = readSection('memory');
   const curTitle = memory?.user?.title || '';
   const curName = memory?.user?.name || '';
@@ -267,8 +386,8 @@ async function stepAddressForm(io, { updateSection, readSection }) {
   io.say('• Saved memory.user (title/name).');
 }
 
-export async function stepWebhookReceiver(io, { updateSection, readSection }) {
-  io.say('\n── Step 3/7: Inbound webhooks (ngrok receiver) ──');
+export async function stepWebhookReceiver(io, { updateSection, readSection, secretsCapable = true }) {
+  io.say('\n── Step 3/9: Inbound webhooks (ngrok receiver) ──');
   io.say('Global webhook tunnel for inbound HTTP (channels.webhook). Per-endpoint registration is configured later in the UI.');
   const enableRaw = await io.ask('Enable inbound webhooks? [y/N]: ');
   if (isSkippableAnswer(enableRaw)) {
@@ -294,17 +413,27 @@ export async function stepWebhookReceiver(io, { updateSection, readSection }) {
   if (!isSkippableAnswer(domainRaw)) {
     webhook.domain = String(domainRaw).trim();
   }
-  const authPrompt = hasStoredSecret(SECRET_ACCOUNTS.webhookAuth)
-    ? 'Auth Token (stored, Enter=keep): '
-    : 'ngrok Auth Token [hidden]: ';
-  webhook.authtoken = (await io.askSecret(authPrompt)).trim();
+  if (secretsCapable) {
+    const authPrompt = hasStoredSecret(SECRET_ACCOUNTS.webhookAuth)
+      ? 'Auth Token (stored, Enter=keep): '
+      : 'ngrok Auth Token [hidden]: ';
+    webhook.authtoken = (await io.askSecret(authPrompt)).trim();
+  } else {
+    io.say('• ngrok Auth Token: skipped (Linux keychain unavailable).');
+  }
   const secrets = {};
   updateSection('channels', (current) => mergeConfig(current, { webhook }, secrets));
-  io.say('• Inbound webhook receiver saved (channels.webhook enabled/domain; authtoken in keychain).');
+  io.say(secretsCapable
+    ? '• Inbound webhook receiver saved (channels.webhook enabled/domain; authtoken in keychain).'
+    : '• Inbound webhook receiver saved (channels.webhook enabled/domain; authtoken not collected).');
 }
 
-async function stepProviderKeys(io, { updateSection }) {
-  io.say('\n── Step 4/7: Provider API keys ──');
+async function stepProviderKeys(io, { updateSection, secretsCapable = true }) {
+  io.say('\n── Step 4/9: Provider API keys ──');
+  if (!secretsCapable) {
+    io.say('• Skipped provider API keys (Linux keychain unavailable).');
+    return;
+  }
   io.say('Optional API keys (hidden). Enter to skip a provider.');
   const providers = {};
   for (const p of AG_API_PROVIDERS) {
@@ -323,7 +452,7 @@ async function stepProviderKeys(io, { updateSection }) {
 }
 
 async function stepPresets(io, { readSection, updateSection, DEFAULT_PRESETS }) {
-  io.say('\n── Step 5/7: Agent presets ──');
+  io.say('\n── Step 5/9: Agent presets ──');
   const agent = readSection('agent');
   const existing = presetIdsFromAgent(agent);
   if (existing.length > 0) {
@@ -350,11 +479,11 @@ async function stepPresets(io, { readSection, updateSection, DEFAULT_PRESETS })
 }
 
 async function stepRolePresetMapping(io, { readSection, dataDir }) {
-  io.say('\n── Step 6/7: Role → preset mapping ──');
+  io.say('\n── Step 6/9: Role → preset mapping ──');
   const agent = readSection('agent');
   const presetIds = presetIdsFromAgent(agent);
   if (presetIds.length === 0) {
-    io.say('No presets on disk — run step 4 first or configure presets in the Mixdog UI later.');
+    io.say('No presets on disk — run step 5 first or configure presets in the Mixdog UI later.');
     return;
   }
   io.say(`Available presets: ${presetIds.join(', ')}`);
@@ -384,21 +513,179 @@ async function stepRolePresetMapping(io, { readSection, dataDir }) {
   io.say('• Role → preset mapping saved to user-workflow.json.');
 }
 
+function resolveSearchBackendInput(raw) {
+  if (isSkippableAnswer(raw)) return null;
+  const key = String(raw).trim().toLowerCase();
+  return SEARCH_OAUTH_ALIASES[key] || null;
+}
+
+function parseYesNo(raw) {
+  if (isSkippableAnswer(raw)) return null;
+  const v = String(raw).trim().toLowerCase();
+  if (v === 'y' || v === 'yes' || v === 'true' || v === '1') return true;
+  if (v === 'n' || v === 'no' || v === 'false' || v === '0') return false;
+  return undefined;
+}
+
+/** Mirrors POST /search/config → mergeSearchConfig. */
+export async function stepSearchBackend(io, { updateSection, readSection, secretsCapable = true }) {
+  io.say('\n── Step 7/9: Search backend ──');
+  io.say('Active provider: anthropic-oauth | openai-oauth | grok-oauth (OAuth — uses Agent credentials).');
+  const { hasStoredSecret, SECRET_ACCOUNTS, getSearchApiKey } = await import('../src/shared/config.mjs');
+  const search = readSection('search') || {};
+  const curProvider = String(search.provider || 'anthropic-oauth').trim() || 'anthropic-oauth';
+  const backendRaw = await io.ask(`Search provider [${curProvider}]: `);
+  let provider = curProvider;
+  if (!isSkippableAnswer(backendRaw)) {
+    const resolved = resolveSearchBackendInput(backendRaw);
+    if (!resolved) {
+      io.say(`  ! Unknown provider "${String(backendRaw).trim()}" — keeping ${curProvider}.`);
+    } else if (!SEARCH_OAUTH_PROVIDERS.has(resolved)) {
+      io.say(`  ! Provider "${resolved}" is not a supported OAuth backend — keeping ${curProvider}.`);
+    } else {
+      provider = resolved;
+    }
+  }
+
+  const payload = {};
+  if (provider !== curProvider) payload.provider = provider;
+
+  const searchProviders = {};
+  if (secretsCapable) {
+    for (const p of SEARCH_RAW_KEY_PROVIDERS) {
+      const hadKey = hasStoredSecret(SECRET_ACCOUNTS.searchApiKey(p.id));
+      const keyPrompt = hadKey
+        ? `${p.name} API key (stored, Enter=keep): `
+        : `${p.name} API key [hidden] (Enter=skip): `;
+      const key = (await io.askSecret(keyPrompt)).trim();
+      if (!isSkippableAnswer(key)) {
+        searchProviders[p.id] = key;
+      }
+    }
+  } else {
+    io.say('• Search provider API keys: skipped (Linux keychain unavailable).');
+  }
+  if (Object.keys(searchProviders).length) payload.searchProviders = searchProviders;
+
+  if (provider === 'openai-oauth') {
+    const curModel = (search.models && search.models.openai)
+      || DEFAULT_MODELS.openai
+      || '';
+    const modelRaw = await io.ask(`OpenAI model [${curModel}] (Enter=keep): `);
+    if (!isSkippableAnswer(modelRaw)) {
+      const model = String(modelRaw).trim();
+      if (model) payload.models = { ...(payload.models || {}), openai: model };
+    }
+    const curEffort = String(search.modelOptions?.openai?.effort || 'medium').trim() || 'medium';
+    const effortRaw = await io.ask(`OpenAI effort (low/medium/high) [${curEffort}] (Enter=keep): `);
+    if (!isSkippableAnswer(effortRaw)) {
+      const effort = String(effortRaw).trim().toLowerCase();
+      if (!OPENAI_SEARCH_EFFORT_VALUES.has(effort)) {
+        io.say(`  ! Unknown effort "${effortRaw.trim()}" — keeping ${curEffort}.`);
+      } else {
+        const openaiOpts = { ...(search.modelOptions?.openai || {}), effort };
+        payload.modelOptions = { ...(payload.modelOptions || {}), openai: openaiOpts };
+      }
+    }
+    const curFast = !!search.modelOptions?.openai?.fast;
+    const fastRaw = await io.ask(`OpenAI Fast mode [${curFast ? 'y' : 'N'}] (y/N, Enter=keep): `);
+    const fastParsed = parseYesNo(fastRaw);
+    if (fastParsed === undefined && !isSkippableAnswer(fastRaw)) {
+      io.say('  ! Fast mode: answer y or n — keeping current.');
+    } else if (fastParsed !== null) {
+      const base = payload.modelOptions?.openai || search.modelOptions?.openai || {};
+      const openaiOpts = { ...base };
+      if (fastParsed) openaiOpts.fast = true;
+      else delete openaiOpts.fast;
+      // Write even an empty object: mergeSearchConfig treats an empty per-family
+      // entry as "clear this family", which is how an explicit Fast=n drops a
+      // lone fast flag (no effort left to keep the object non-empty).
+      payload.modelOptions = { ...(payload.modelOptions || {}), openai: openaiOpts };
+    }
+  } else if (provider === 'grok-oauth') {
+    const curModel = (search.models && search.models.xai)
+      || DEFAULT_MODELS.xai
+      || '';
+    const modelRaw = await io.ask(`xAI model [${curModel}] (Enter=keep): `);
+    if (!isSkippableAnswer(modelRaw)) {
+      const model = String(modelRaw).trim();
+      if (model) payload.models = { ...(payload.models || {}), xai: model };
+    }
+  }
+
+  const secrets = {};
+  updateSection('search', (current) => mergeSearchConfig(current, payload, secrets));
+  const after = readSection('search') || {};
+  const savedProvider = after.provider || curProvider;
+  io.say(`• Search provider: ${savedProvider}.`);
+  for (const p of SEARCH_RAW_KEY_PROVIDERS) {
+    io.say(`• ${p.name} API key: ${getSearchApiKey(p.id) ? 'stored' : 'not set'}.`);
+  }
+  if (savedProvider === 'openai-oauth' && after.models?.openai) {
+    io.say(`• OpenAI model: ${after.models.openai}.`);
+  }
+  if (savedProvider === 'grok-oauth' && after.models?.xai) {
+    io.say(`• xAI model: ${after.models.xai}.`);
+  }
+  if (savedProvider === 'openai-oauth' && after.modelOptions?.openai?.effort) {
+    io.say(`• OpenAI effort: ${after.modelOptions.openai.effort}.`);
+  }
+  if (savedProvider === 'openai-oauth' && after.modelOptions?.openai?.fast) {
+    io.say('• OpenAI Fast mode: on.');
+  }
+}
+
+/** Mirrors POST /agent/maintenance for the explore slot. */
+export async function stepExplorerPreset(io, { readSection, updateSection, DEFAULT_PRESETS, DEFAULT_MAINTENANCE }) {
+  io.say('\n── Step 8/9: Explorer model (explore tool) ──');
+  const agent = readSection('agent') || {};
+  const presetIds = presetIdsFromAgent(agent);
+  const validIds = new Set([
+    ...presetIds,
+    ...DEFAULT_PRESETS.map((p) => p.id).filter(Boolean),
+  ]);
+  const curExplore = String(agent.maintenance?.explore || DEFAULT_MAINTENANCE.explore || 'haiku').trim() || 'haiku';
+  if (validIds.size > 0) {
+    io.say(`Available presets: ${[...validIds].join(', ')}`);
+  }
+  const raw = await io.ask(`Preset for explorer (explore tool) [${curExplore}]: `);
+  if (isSkippableAnswer(raw)) {
+    io.say(`• Explorer preset unchanged (${curExplore}).`);
+    return;
+  }
+  const preset = String(raw).trim();
+  if (!validIds.has(preset)) {
+    io.say(`  ! Unknown preset "${preset}" — keeping ${curExplore}.`);
+    return;
+  }
+  updateSection('agent', (current) => ({
+    ...current,
+    maintenance: { ...(current.maintenance || {}), explore: preset },
+  }));
+  io.say(`• Explorer maintenance preset: ${preset}.`);
+}
+
 /**
  * @param {object} [ioOverride]
  * @param {boolean} [ioOverride.interactive]
  * @param {(prompt:string)=>Promise<string>} [ioOverride.ask]
  * @param {(prompt:string)=>Promise<string>} [ioOverride.askSecret]
  * @param {(line:string)=>void} [ioOverride.say]
+ * @param {object} [options]
+ * @param {boolean} [options.secretsCapable] — override Linux keytar preflight (tests).
  */
-export async function runSetupWizard(ioOverride = null) {
+export async function runSetupWizard(ioOverride = null, options = {}) {
   const io = ioOverride ? { ...defaultIo(), ...ioOverride } : defaultIo();
   if (!io.interactive) return { skipped: true };
 
+  const secretsCapable = options.secretsCapable ?? probeLinuxSecretsCapable();
+  if (!secretsCapable) io.say(linuxKeychainUnavailableMessage());
+
   io.say('\nMixdog setup wizard — configure before opening Claude Code.');
   io.say('Press Enter on any step to skip it.\n');
 
   const ctx = await loadConfigModules();
+  ctx.secretsCapable = secretsCapable;
   try {
     await stepAddressForm(io, ctx);
     const discordSaved = await stepDiscordToken(io, ctx);
@@ -407,6 +694,8 @@ export async function runSetupWizard(ioOverride = null) {
     await stepProviderKeys(io, ctx);
     await stepPresets(io, ctx);
     await stepRolePresetMapping(io, ctx);
+    await stepSearchBackend(io, ctx);
+    await stepExplorerPreset(io, ctx);
     io.say('\n✓ Wizard complete. Restart Claude Code (or /reload-plugins) to load mixdog.');
   } catch (err) {
     io.say(`\n✗ Wizard error: ${err?.message || err}`);