@dotdrelle/wiki-manager 0.6.31 → 0.6.34

package/README.md

@@ -551,8 +551,9 @@ The TUI uses a two-pane layout:
 Useful primitives:
 
 ```text
-/workspaces
-/new <name> [path]
+/workspace list
+/new <name> [path]              # interactive TUI wizard
+/workspace init <name> [path]   # low-level non-interactive creation
 /use <workspace>
 /config list
 /config use <name>

package/bin/wiki-manager.js

@@ -81,7 +81,7 @@ async function main() {
   // exports these before Bun starts.
   if (parsed.cacert) Object.assign(process.env, cacertEnvVars(parsed.cacert));
   await import('@opentui/solid/preload');
-  const interactive = process.stdout.isTTY && process.stdin.isTTY && !argv.includes('--headless') && !argv.includes('--once') && !argv.includes('--version') && !argv.includes('-v') && !argv.includes('--help') && !argv.includes('-h');
+  const interactive = process.stdout.isTTY && process.stdin.isTTY && !argv.includes('--setup-wizard') && !argv.includes('--headless') && !argv.includes('--once') && !argv.includes('--version') && !argv.includes('-v') && !argv.includes('--help') && !argv.includes('-h');
   if (interactive) process.stdout.write('Starting wiki-manager…\r');
   const { runCli } = await import('../src/cli/wiki-manager.js');
   await runCli(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.6.31",
+  "version": "0.6.34",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -9,6 +9,11 @@
     "wiki-manager": "bin/wiki-manager",
     "wiki-workspace": "wiki-workspace"
   },
+  "scripts": {
+    "start": "bun ./bin/wiki-manager.js",
+    "test": "node --test src/core/activity.test.js src/core/agentEvents.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/commands/slash.test.js",
+    "check": "bun ./bin/wiki-manager.js --version && bun ./bin/wiki-manager.js --help && bun ./bin/wiki-manager.js --once \"verifie le mode agent\""
+  },
   "engines": {
     "node": ">=22.0.0",
     "bun": ">=1.2.0"
@@ -35,6 +40,7 @@
     "orchestration",
     "cli"
   ],
+  "packageManager": "pnpm@10.29.2",
   "dependencies": {
     "@langchain/langgraph": "^1.3.2",
     "@opentui/core": "^0.3.2",
@@ -47,10 +53,5 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0"
-  },
-  "scripts": {
-    "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/core/activity.test.js src/core/agentEvents.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js",
-    "check": "bun ./bin/wiki-manager.js --version && bun ./bin/wiki-manager.js --help && bun ./bin/wiki-manager.js --once \"verifie le mode agent\""
   }
-}
+}

package/src/agent/graph.js

@@ -17,8 +17,6 @@ const MAX_SPINNER_ARG_LENGTH = 96;
 const AGENT_SLASH_COMMANDS = new Set([
   'help',
   'version',
-  'workspaces',
-  'new',
   'workspace',
   'use',
   'config',
@@ -36,8 +34,8 @@ const SHELL_RUN_COMMAND_TOOL = {
     name: 'shell__run_command',
     description: [
       'Run a deterministic wiki-manager slash command inside the current shell session.',
-      'Allowed commands: /workspaces, /new <name> [path], /use <workspace>, /config, /status, /services, /skills, /skills show <name>, /skills run <name>, /upload <path>, /upload convert <id|pending>, /uploads.',
-      'Do not use for arbitrary system shell commands, /mcp call, /wiki run, /start, /stop, /logs, or /exit.',
+      'Allowed commands: /workspace list, /workspace init <name> [path], /use <workspace>, /config, /status, /services, /skills, /skills show <name>, /skills run <name>, /upload <path>, /upload convert <id|pending>, /uploads.',
+      'Do not use for arbitrary system shell commands, /workspace delete, /mcp call, /wiki run, /start, /stop, /logs, or /exit.',
     ].join(' '),
     parameters: {
       type: 'object',
@@ -45,7 +43,7 @@ const SHELL_RUN_COMMAND_TOOL = {
       properties: {
         command: {
           type: 'string',
-          description: 'Slash command to run, for example "/workspaces", "/new demo", or "/use juno".',
+          description: 'Slash command to run, for example "/workspace list", "/workspace init demo", or "/use juno".',
         },
       },
       required: ['command'],
@@ -217,9 +215,6 @@ function assertAgentSlashCommandAllowed(commandLine) {
   if (!AGENT_SLASH_COMMANDS.has(command)) {
     throw new Error(`Command is not available to the agent: /${command}`);
   }
-  if (command === 'new' && parts.length < 2) {
-    throw new Error('Usage: /new <name> [path].');
-  }
   if (command === 'workspace' && parts[1] !== 'init') {
     throw new Error('Only /workspace init is available to the agent.');
   }
@@ -324,7 +319,7 @@ export function buildAgentSystemPrompt(state) {
     'When the user asks for an action that can be performed with connected MCP tools or safe primitives, do not answer with future intent such as "I will call...", "I am going to run...", or "launching..." unless you also call the tool in the same turn. Either call the tool now, ask for the exact missing required arguments, or explain the concrete blocker.',
     'For connector configuration/setup/update requests, if a matching setup/configuration tool is connected and the required arguments are known, call it immediately. If the connector or tool is not connected, say which concrete capability is missing and recommend the exact service/status primitive to inspect it. Do not invent a pending connector action in plain text.',
     'For workspace-scoped external MCP tools, the orchestrator enforces workspace injection. Use the active workspace for configuration, source, import, export, conversion, and generation tools unless a tool is explicitly job-scoped and only requires a job id.',
-    'You can call shell__run_command for safe manager slash commands such as /workspaces, /new <name> [path], /use <workspace>, /config, /status, /services, /skills, /skills show <name>, and /skills run <name>.',
+    'You can call shell__run_command for safe manager slash commands such as /workspace list, /workspace init <name> [path], /use <workspace>, /config, /status, /services, /skills, /skills show <name>, and /skills run <name>.',
     'Skills are workflow instructions, not executable code. When a user asks to run a skill, inspect it, propose the concrete primitive/tool plan, and ask for confirmation before costly or mutating actions.',
     [
       state.session.headless ? 'HEADLESS MODE ACTIVE. Execute the requested skill or task autonomously using available safe primitives and MCP tools. Do not ask for interactive confirmation unless the request is genuinely ambiguous or outside the loaded workspace.' : null,
@@ -361,7 +356,7 @@ export function buildAgentSystemPrompt(state) {
     'For ingest/build/export/polish/pipeline workflows, use production MCP tools. Do not route these through direct /wiki shortcuts. To chain multiple sequential steps (e.g. build then polish), always use a single production_start_job call with type="pipeline" and steps=["build","polish"] — never start them as separate jobs: the first job is asynchronous and the second would run before it completes. For existing deliverables where content stability matters, pass stabilize:true so the build step preserves unchanged sections; keep polish in the pipeline when publication output is requested. Do not ask the user to confirm between steps; start the pipeline call directly.',
     'Long-running MCP jobs: do not call the same status tool more than once consecutively. When chaining jobs sequentially: (1) start the job, report job/activity id and status; (2) check status once — if done, proceed to the next step immediately; (3) if still running, report status, list the remaining steps, and return control; (4) when re-invoked, check status first, then proceed. Do not spin-poll (status → status → status with no new action between). The shell activity panel monitors non-terminal jobs automatically.',
     'If production_start_job is returned as queued/waiting by the manager, report that it is waiting in the local queue and return control. Do not continue as if the production job has started.',
-    'For diagnostics, use /wiki run doctor when the user asks for doctor. Use /new <name> [path] to create/configure a new workspace. Use /wiki for index, or /wiki run index through the explicit backup hatch. Use /wiki run init only for explicit current-workspace llm-wiki init.',
+    'For diagnostics, use /wiki run doctor when the user asks for doctor. Use /workspace init <name> [path] for low-level non-interactive workspace creation. In the interactive TUI, /new <name> opens the setup wizard. Use /wiki for index, or /wiki run index through the explicit backup hatch. Use /wiki run init only for explicit current-workspace llm-wiki init.',
     'If an action requires tools or skills not available yet, explain the limitation and name the expected primitive.',
   ].join('\n');
 

package/src/cli/wiki-manager.js

@@ -7,6 +7,7 @@ loadManagerEnv();
 import { createAgentGraph, buildAgentSystemPrompt, buildLimitedAgentResponse } from '../agent/graph.js';
 import { handleSlashCommand, printHelp, printVersion } from '../commands/slash.js';
 import { runShell } from '../shell/repl.js';
+import { runChecks } from '../core/startupCheck.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { extractActivity, parseJsonText, sessionActivities } from '../core/activity.js';
 import { extractHeadlessPlan, syncActivitiesToPlan, formatPlanStatus, formatCompletedActivities } from '../core/plan.js';
@@ -15,7 +16,7 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = resolve(__dirname, '../../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-const SHELL_COMMANDS = ['help', 'version', 'exit', 'workspaces', 'new', 'use', 'config', 'status', 'services', 'start', 'stop', 'logs', 'mcp', 'wiki', 'skills', 'clear', 'chat', 'agent'];
+const SHELL_COMMANDS = ['help', 'version', 'exit', 'workspace', 'new', 'use', 'config', 'status', 'services', 'start', 'stop', 'logs', 'mcp', 'wiki', 'skills', 'clear', 'chat', 'agent'];
 
 function valueAfter(argv, flag) {
   const index = argv.indexOf(flag);
@@ -345,6 +346,18 @@ async function runHeadless(argv, agent) {
 }
 
 export async function runCli(argv) {
+  if (argv.includes('--setup-wizard')) {
+    if (!process.versions.bun) {
+      throw new Error('Setup wizard requires Bun. Run: bun ./bin/wiki-manager.js --setup-wizard');
+    }
+    const { runSetupWizard } = await import('../shell/tui.tsx');
+    await runSetupWizard({
+      workspaceName: valueAfter(argv, '--workspace-name'),
+      workspacePath: valueAfter(argv, '--workspace-path') ?? null,
+    });
+    return;
+  }
+
   if (argv.includes('--version') || argv.includes('-v')) {
     printVersion(packageJson);
     return;
@@ -380,7 +393,9 @@ export async function runCli(argv) {
     if (!process.versions.bun) {
       throw new Error('Interactive TUI requires Bun. Run: bun ./bin/wiki-manager.js');
     }
-    const { runOpenTuiShell } = await import('../shell/tui.tsx');
+    const { runOpenTuiShell, runStartupWizard } = await import('../shell/tui.tsx');
+    const gaps = await runChecks();
+    if (gaps.length > 0) await runStartupWizard(gaps);
     await runOpenTuiShell({ agent, packageJson });
     return;
   }

package/src/commands/slash.js

@@ -30,6 +30,7 @@ import {
   resolveWikircProfile,
   summarizeWikircConfig,
 } from '../core/wikirc.js';
+import { deleteWorkspaceAndFiles, startAgents, stopAgents } from '../core/wikiSetup.js';
 import {
   cleanDocumentUploads,
   convertPendingDocumentUploads,
@@ -433,8 +434,7 @@ async function createWorkspaceCommand(context, workspaceName, targetPath) {
       output: [
         'Usage: /new <name> [path]',
         '',
-        'Creates/configures a new workspace through wiki-workspace config.',
-        'Legacy form: /workspace init <name> [path].',
+        'Creates and registers a workspace via wiki-workspace config.',
         'For llm-wiki init inside the current workspace, use /wiki run init.',
       ].join('\n'),
     };
@@ -456,6 +456,7 @@ async function createWorkspaceCommand(context, workspaceName, targetPath) {
   }
 }
 
+
 function formatMcpCallActivity(serverName, toolName, resultText) {
   if (serverName === 'production') return null;
   return formatActivitySummary(serverName, toolName, resultText);
@@ -551,6 +552,47 @@ function loadSessionWikirc(session, profileName = 'default') {
   return summarizeWikircConfig(loaded.profile, loaded.config);
 }
 
+function clearWorkspaceSession(session) {
+  session.workspace = null;
+  session.workspacePath = null;
+  session.workspaceEnv = null;
+  session.workspaceEnvFile = null;
+  session.wikirc = null;
+  session.wikircConfig = null;
+  session.language = null;
+  session.llm = null;
+  session.mcp = null;
+  session.systemPrompt = null;
+}
+
+function formatWorkspaceList(workspaces, session = null) {
+  if (workspaces.length === 0) return 'No workspace configured.';
+  return [
+    'Workspaces',
+    '',
+    ...workspaces.flatMap((workspace) => {
+      const active = workspace.name === session?.workspace ? 'active' : 'available';
+      return [
+        `${workspace.name}\t${active}`,
+        `  path\t${workspace.workspacePath}`,
+        `  use\t/use ${workspace.name}`,
+        `  delete\t/workspace delete ${workspace.name}`,
+        '',
+      ];
+    }),
+  ].join('\n').trimEnd();
+}
+
+function workspaceDeletePrompt(workspaces) {
+  if (workspaces.length === 0) return 'No workspace configured.';
+  return [
+    'Delete a workspace:',
+    ...workspaces.map((workspace) => `  /workspace delete ${workspace.name}\t${workspace.workspacePath}`),
+    '',
+    'The next step asks for confirmation before deleting files.',
+  ].join('\n');
+}
+
 export function helpText(packageJson) {
   return `wiki-manager ${packageJson.version}
 
@@ -576,12 +618,12 @@ Options:
 
 Interactive shell:
 ${helpPair('/help', 'Help', '/version', 'Version')}
-${helpPair('/workspaces', 'Workspaces', '/new <n> [path]', 'New workspace')}
+${helpPair('/workspace list', 'Workspaces', '/new <n> [path]', 'New workspace')}
 ${helpPair('/use <workspace>', 'Use workspace', '/status', 'Session status')}
 ${helpPair('/config list', 'Config profiles', '/config use <n>', 'Use config')}
-${helpPair('/config edit <n>', 'Edit config', '/config status', 'Active config')}
-${helpPair('/services', 'Services', '/start [service]', 'Start service(s)')}
-${helpPair('/stop [service]', 'Stop service(s)', '/logs <service>', 'Service logs')}
+${helpPair('/config edit <n>', 'Edit config', '/workspace delete <n>', 'Delete workspace')}
+${helpPair('/services', 'Services', '/start [service|agents]', 'Start service(s)')}
+${helpPair('/stop [service|agents]', 'Stop service(s)', '/logs <service>', 'Service logs')}
 ${helpPair('/skills', 'List skills', '/skills show <n>', 'Show skill')}
 ${helpPair('/skills run <n>', 'Run skill guide', '/skills edit <n>', 'Edit skill')}
 ${helpPair('/mcp status', 'MCP status', '/mcp endpoints', 'MCP endpoints')}
@@ -618,6 +660,16 @@ export async function handleSlashCommand(line, context) {
   const args = line.slice(1).trim().split(/\s+/).filter(Boolean);
   const [command] = args;
   const step = context.onStep ?? (() => {});
+  const runAgentCommand = async (fn, verb) => {
+    try {
+      step(`Agents: ${verb}ing external agents…`);
+      const output = await fn();
+      return { output: output || `Agents ${verb}ed.` };
+    } catch (err) {
+      step(formatActivityError('agents', verb, err));
+      return { output: err instanceof Error ? err.message : String(err) };
+    }
+  };
 
   switch (command) {
     case '':
@@ -631,17 +683,6 @@ export async function handleSlashCommand(line, context) {
     case 'agent':
       context.session.chatMode = false;
       return { setMode: 'agent', output: 'Mode: agent' };
-    case 'workspaces': {
-      const workspaces = listWorkspaces();
-      if (workspaces.length === 0) {
-        return { output: 'No workspace configured.' };
-      }
-      return {
-        output: workspaces
-          .map((workspace) => `${workspace.name}\t${workspace.workspacePath}`)
-          .join('\n'),
-      };
-    }
     case 'status': {
       step('Shell: refreshing workspace, services and MCP status…');
       return { output: await statusText(context.session) };
@@ -655,15 +696,11 @@ export async function handleSlashCommand(line, context) {
       if (!workspace) {
         return { output: `Workspace not found: ${workspaceName}` };
       }
+      clearWorkspaceSession(context.session);
       context.session.workspace = workspace.name;
       context.session.workspacePath = workspace.workspacePath;
       context.session.workspaceEnv = workspace.env;
       context.session.workspaceEnvFile = workspace.envFile;
-      context.session.wikirc = null;
-      context.session.wikircConfig = null;
-      context.session.language = null;
-      context.session.llm = null;
-      context.session.mcp = null;
       context.session.systemPrompt = loadWorkspaceSystemPrompt(workspace.workspacePath);
       try {
         step(`Workspace: loading ${workspace.name} config…`);
@@ -778,6 +815,7 @@ export async function handleSlashCommand(line, context) {
     }
     case 'start': {
       const service = args[1];
+      if (service === 'agents') return runAgentCommand(startAgents, 'start');
       try {
         step(`Services: starting ${service ?? 'workspace services'}…`);
         const output = await startService(context.session, service);
@@ -792,6 +830,7 @@ export async function handleSlashCommand(line, context) {
     }
     case 'stop': {
       const service = args[1];
+      if (service === 'agents') return runAgentCommand(stopAgents, 'stop');
       try {
         step(`Services: stopping ${service ?? 'workspace services'}…`);
         const output = await stopService(context.session, service);
@@ -955,12 +994,50 @@ export async function handleSlashCommand(line, context) {
     case 'new': {
       return createWorkspaceCommand(context, args[1], args[2] ?? null);
     }
-    case 'workspace': {
-      const subcommand = args[1];
-      if (subcommand !== 'init') {
-        return { output: 'Usage: /new <name> [path]\nLegacy: /workspace init <name> [path]' };
+    case 'workspace':
+    case 'workplace': {
+      const subcommand = args[1] ?? 'list';
+      if (subcommand === 'list') {
+        return { output: formatWorkspaceList(listWorkspaces(), context.session) };
+      }
+      if (subcommand === 'delete') {
+        const workspaceName = args[2];
+        const confirmed = args.includes('--confirm');
+        const workspaces = listWorkspaces();
+        if (!workspaceName) return { output: workspaceDeletePrompt(workspaces) };
+        const workspace = workspaces.find((item) => item.name === workspaceName);
+        if (!workspace) return { output: `Workspace not found: ${workspaceName}` };
+        if (!confirmed) {
+          return {
+            output: [
+              `Confirm workspace deletion: ${workspace.name}`,
+              `Path: ${workspace.workspacePath}`,
+              'This removes the registry entry and deletes the workspace files.',
+              '',
+              `Run: /workspace delete ${workspace.name} --confirm`,
+            ].join('\n'),
+          };
+        }
+        try {
+          step(`Workspace: deleting ${workspace.name}…`);
+          const result = await deleteWorkspaceAndFiles(workspace, workspace.workspacePath);
+          const wasCurrent = context.session.workspace === workspace.name
+            || context.session.workspacePath === workspace.workspacePath;
+          if (wasCurrent) clearWorkspaceSession(context.session);
+          return {
+            output: [
+              `Deleted workspace: ${workspace.name}`,
+              `Removed registry entry and files at: ${result.deletedPath}`,
+              wasCurrent ? 'Current session cleared. Use /use <workspace> or /workspace init <name> [path].' : null,
+            ].filter(Boolean).join('\n'),
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { output: message };
+        }
       }
-      return createWorkspaceCommand(context, args[2], args[3] ?? null);
+      if (subcommand === 'init') return createWorkspaceCommand(context, args[2], args[3] ?? null);
+      return { output: 'Usage: /workspace <list|delete <name> --confirm|init <name> [path]>' };
     }
     case 'wiki': {
       const subcommand = args[1];

package/src/commands/slash.test.js

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { handleSlashCommand } from './slash.js';
+
+test('/workspace delete removes files and clears current session context after confirmation', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'wiki-manager-delete-workspace-'));
+  const registryRoot = join(root, 'registry');
+  const registryPath = join(registryRoot, 'demo');
+  const workspacePath = join(root, 'workspace');
+  mkdirSync(registryPath, { recursive: true });
+  mkdirSync(workspacePath, { recursive: true });
+  writeFileSync(join(registryPath, '.env'), [
+    'WORKSPACE_NAME=demo',
+    `WIKI_WORKSPACE_PATH=${workspacePath}`,
+    '',
+  ].join('\n'), 'utf8');
+
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  process.env.WIKI_WORKSPACES_DIR = registryRoot;
+  const session = {
+    workspace: 'demo',
+    workspacePath,
+    workspaceEnv: { WORKSPACE_NAME: 'demo' },
+    workspaceEnvFile: join(registryPath, '.env'),
+    wikirc: { profile: 'default' },
+    wikircConfig: {},
+    language: 'en-US',
+    llm: {},
+    mcp: {},
+    systemPrompt: 'prompt',
+  };
+
+  try {
+    const prompt = await handleSlashCommand('/workspace delete demo', {
+      packageJson: { version: 'test' },
+      session,
+    });
+    assert.match(prompt.output, /Confirm workspace deletion: demo/);
+    assert.equal(existsSync(workspacePath), true);
+    assert.equal(session.workspace, 'demo');
+
+    const result = await handleSlashCommand('/workspace delete demo --confirm', {
+      packageJson: { version: 'test' },
+      session,
+    });
+    assert.match(result.output, /Deleted workspace: demo/);
+    assert.equal(session.workspace, null);
+    assert.equal(session.workspacePath, null);
+    assert.equal(session.llm, null);
+    assert.equal(session.mcp, null);
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});
+
+test('/new without a name shows usage', async () => {
+  const result = await handleSlashCommand('/new', {
+    packageJson: { version: 'test' },
+    session: {},
+  });
+
+  assert.match(result.output ?? '', /Usage/i);
+});

package/src/core/compose.js

@@ -238,7 +238,7 @@ export async function composePs(session) {
   return runCompose(session, ['ps'], { timeout: 30_000 });
 }
 
-function parseComposePsJson(output) {
+export function parseComposePsJson(output) {
   const text = output.trim();
   if (!text) return [];
   try {

package/src/core/mcp.js

@@ -211,7 +211,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.6.31' },
+            clientInfo: { name: 'wiki-manager', version: '0.6.34' },
           },
         }),
       });

package/src/core/modelFetch.js

@@ -0,0 +1,97 @@
+const FALLBACK_MODELS = {
+  openai: ['gpt-5.4', 'gpt-5.4-mini', 'gpt-4.1', 'gpt-4.1-mini'],
+  anthropic: ['claude-sonnet-4-5', 'claude-opus-4-1', 'claude-3-7-sonnet-latest'],
+  ollama: ['llama3.2', 'qwen2.5', 'mistral', 'nomic-embed-text'],
+  'openai-compatible': ['gpt-4.1-mini', 'llama3.2'],
+  other: ['gpt-4.1-mini', 'llama3.2'],
+};
+
+const FALLBACK_EMBEDDINGS = {
+  openai: ['text-embedding-3-small', 'text-embedding-3-large'],
+  anthropic: ['text-embedding-3-small'],
+  ollama: ['nomic-embed-text', 'mxbai-embed-large'],
+  'openai-compatible': ['BAAI/bge-m3', 'text-embedding-3-small', 'nomic-embed-text'],
+  other: ['text-embedding-3-small', 'nomic-embed-text'],
+};
+
+export function normalizeProvider(provider) {
+  const value = String(provider ?? '').toLowerCase();
+  if (value.includes('compatible') || value.includes('other')) return 'openai-compatible';
+  if (value.includes('anthropic')) return 'anthropic';
+  if (value.includes('ollama')) return 'ollama';
+  if (value.includes('openai')) return 'openai';
+  return 'openai-compatible';
+}
+
+function fallbackFor(provider, kind) {
+  const normalized = normalizeProvider(provider);
+  const source = kind === 'embedding' ? FALLBACK_EMBEDDINGS : FALLBACK_MODELS;
+  return source[normalized] ?? source.other;
+}
+
+function endpointFor(provider, baseUrl) {
+  const normalized = normalizeProvider(provider);
+  if (normalized === 'anthropic') return 'https://api.anthropic.com/v1/models';
+  const root = String(baseUrl || (normalized === 'ollama' ? 'http://localhost:11434' : 'https://api.openai.com')).replace(/\/+$/g, '');
+  return normalized === 'ollama' ? `${root}/api/tags` : `${root}/v1/models`;
+}
+
+function headersFor(provider, apiKey) {
+  const normalized = normalizeProvider(provider);
+  if (normalized === 'ollama') return {};
+  if (normalized === 'anthropic') {
+    return {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    };
+  }
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+function parseModelNames(provider, payload) {
+  const normalized = normalizeProvider(provider);
+  const items = normalized === 'ollama' ? payload?.models : payload?.data;
+  if (!Array.isArray(items)) return [];
+  return items
+    .map((item) => item?.id ?? item?.name ?? item?.model)
+    .filter(Boolean)
+    .map(String)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+export async function fetchModels(provider, baseUrl, apiKey, options = {}) {
+  const normalized = normalizeProvider(provider);
+  if (normalized === 'anthropic') {
+    return { ok: false, models: fallbackFor(normalized, options.kind), source: 'fallback', error: 'Anthropic model listing is not supported' };
+  }
+  const timeoutMs = options.timeoutMs ?? 10000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    if (normalized !== 'ollama' && !apiKey) {
+      throw new Error('API key is required to fetch remote models');
+    }
+    const response = await fetch(endpointFor(normalized, baseUrl), {
+      headers: headersFor(normalized, apiKey),
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const payload = await response.json();
+    const models = parseModelNames(normalized, payload);
+    if (models.length === 0) throw new Error('No models returned');
+    return { ok: true, models, source: 'remote' };
+  } catch (err) {
+    return {
+      ok: false,
+      models: fallbackFor(normalized, options.kind),
+      source: 'fallback',
+      error: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function fallbackModels(provider, kind) {
+  return fallbackFor(provider, kind);
+}

package/src/core/modelFetch.test.js

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { fallbackModels, fetchModels } from './modelFetch.js';
+
+test('fetchModels returns remote OpenAI-compatible model ids', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    json: async () => ({ data: [{ id: 'b-model' }, { id: 'a-model' }] }),
+  });
+  try {
+    const result = await fetchModels('openai', 'http://models.local', 'key', { timeoutMs: 100 });
+    assert.deepEqual(result, { ok: true, models: ['a-model', 'b-model'], source: 'remote' });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('fetchModels falls back on invalid remote response', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    json: async () => ({ data: [] }),
+  });
+  try {
+    const result = await fetchModels('openai', 'http://models.local', 'key', { timeoutMs: 100 });
+    assert.equal(result.ok, false);
+    assert.equal(result.source, 'fallback');
+    assert.ok(result.models.includes('gpt-5.4-mini'));
+    assert.match(result.error, /No models returned/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('fallbackModels leaves custom-model to the wizard append action', () => {
+  assert.deepEqual(fallbackModels('openai-compatible'), ['gpt-4.1-mini', 'llama3.2']);
+});