@dotdrelle/wiki-manager 0.14.9 → 0.14.12

package/src/core/startupCheck.test.js

@@ -4,7 +4,7 @@ import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { runChecks } from './startupCheck.js';
+import { checkInternetConnectivity, checkMcpConnections, runChecks, runPreflightChecks, withRuntimePreflight } from './startupCheck.js';
 
 async function withWorkspace(wikircLines, fn) {
   const root = await mkdtemp(join(tmpdir(), 'wiki-manager-startup-check-'));
@@ -44,7 +44,13 @@ test('runChecks treats default LLM config without baseUrl as incomplete', async
     '  vector:',
     '    enabled: true',
   ], async () => {
-    const gaps = await runChecks();
+    const gaps = await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async () => ({ ok: true, detail: 'running' }),
+      mcpCheck: async () => ({ ok: true, detail: 'connected' }),
+    });
     assert.equal(hasGap(gaps, 'llm'), true);
   });
 });
@@ -60,7 +66,188 @@ test('runChecks treats default LLM config with provider, baseUrl, apiKey and mod
     '  vector:',
     '    enabled: true',
   ], async () => {
-    const gaps = await runChecks();
+    const gaps = await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async () => ({ ok: true, detail: 'running' }),
+      mcpCheck: async () => ({ ok: true, detail: 'connected' }),
+    });
     assert.equal(hasGap(gaps, 'llm'), false);
   });
 });
+
+test('runChecks reports and probes every registered workspace', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'wiki-manager-multi-startup-'));
+  const registryRoot = join(root, 'registry');
+  for (const name of ['alpha', 'beta']) {
+    const registryPath = join(registryRoot, name);
+    const workspacePath = join(root, name);
+    mkdirSync(registryPath, { recursive: true });
+    mkdirSync(workspacePath, { recursive: true });
+    writeFileSync(join(registryPath, '.env'), `WORKSPACE_NAME=${name}\nWIKI_WORKSPACE_PATH=${workspacePath}\n`, 'utf8');
+    writeFileSync(join(workspacePath, '.wikirc.yaml'), [
+      'llm:',
+      '  provider: openai-compatible',
+      '  baseUrl: http://localhost:8000/v1',
+      '  apiKey: key',
+      '  model: chat-model',
+      '',
+    ].join('\n'), 'utf8');
+  }
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  process.env.WIKI_WORKSPACES_DIR = registryRoot;
+  try {
+    const containerCalls = [];
+    const mcpCalls = [];
+    const reports = [];
+    await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async (workspace) => {
+        containerCalls.push(workspace.name);
+        return {
+          ok: false,
+          pending: true,
+          detail: 'to start',
+          context: { unavailable: ['serve', 'mcp-http', 'production-mcp'], command: `wiki-workspace up ${workspace.name}` },
+        };
+      },
+      mcpCheck: async (workspace) => {
+        mcpCalls.push(workspace.name);
+        return { ok: true, detail: 'connected', context: { endpoints: [{ name: 'wiki', status: 'connected' }] } };
+      },
+      onCheck: (check) => reports.push(check),
+    });
+    assert.deepEqual(containerCalls, ['alpha', 'beta']);
+    assert.deepEqual(mcpCalls, ['alpha', 'beta']);
+    const workspaceReport = reports.find((check) => check.kind === 'workspace');
+    assert.equal(workspaceReport.detail, '2 registered: alpha, beta');
+    assert.equal(
+      reports.find((check) => check.kind === 'containers').detail,
+      '2/2 workspaces to start: alpha, beta — services: serve, mcp-http, production-mcp',
+    );
+    assert.match(reports.find((check) => check.kind === 'mcp').detail, /2 workspace\(s\) checked/);
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});
+
+test('runChecks executes Docker before Internet and reports both failures in order', async () => {
+  const calls = [];
+  const reports = [];
+  const gaps = await runChecks({
+    dockerCheck: async () => { calls.push('docker'); return { ok: false, context: { dockerUnavailable: true } }; },
+    internetCheck: async () => { calls.push('internet'); return { ok: false, context: { error: 'offline' } }; },
+    agentsCheck: async () => { calls.push('agents'); return null; },
+    onCheck: (check) => reports.push(check.kind),
+  });
+  assert.deepEqual(calls, ['docker', 'internet']);
+  assert.deepEqual(reports.slice(0, 3), ['docker', 'internet', 'agents']);
+  assert.deepEqual(gaps.slice(0, 2).map((gap) => gap.kind), ['agents', 'network']);
+});
+
+test('MCP preflight distinguishes authentication failure and skips remote endpoints while offline', async () => {
+  const workspace = { name: 'demo', workspacePath: '/tmp/demo', envFile: '/tmp/demo.env', env: {} };
+  const result = await checkMcpConnections(workspace, {
+    internetAvailable: false,
+    buildStatus: () => ({
+      local: { status: 'configured', url: 'http://127.0.0.1:3333/mcp' },
+      remote: { status: 'configured', url: 'https://mcp.example.test', external: true },
+    }),
+    discover: async (endpoints) => ({
+      local: { ...endpoints.local, status: 'configured', tools: [], toolError: '401 Unauthorized' },
+    }),
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.context.endpoints.map(({ name, status, reason }) => ({ name, status, reason })), [
+    { name: 'local', status: 'failed', reason: 'authentication' },
+    { name: 'remote', status: 'skipped', reason: 'internet unavailable' },
+  ]);
+});
+
+test('MCP preflight reports invalid endpoint configuration without aborting startup', async () => {
+  const result = await checkMcpConnections({ name: 'demo', workspacePath: '/tmp/demo', env: {} }, {
+    buildStatus: () => { throw new Error('Unexpected token in mcp.endpoints.json'); },
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.detail, 'MCP configuration invalid');
+  assert.match(result.context.error, /mcp\.endpoints\.json/);
+});
+
+test('preflight status is setup_required without a valid workspace and runtime failure only degrades', async () => {
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  const root = await mkdtemp(join(tmpdir(), 'wiki-manager-empty-startup-'));
+  process.env.WIKI_WORKSPACES_DIR = root;
+  try {
+    const preflight = await runPreflightChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+    });
+    assert.equal(preflight.status, 'setup_required');
+    assert.equal(withRuntimePreflight(preflight, { error: 'offline' }).status, 'setup_required');
+    const ready = { gaps: [], status: 'ready', checks: [{ kind: 'docker', ok: true }] };
+    assert.equal(withRuntimePreflight(ready, { error: 'offline' }).status, 'degraded');
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});
+
+test('runChecks presents Internet failure before stopped agents after Docker succeeds', async () => {
+  const gaps = await runChecks({
+    dockerCheck: async () => ({ ok: true }),
+    internetCheck: async () => ({ ok: false, context: { error: 'offline' } }),
+    agentsCheck: async () => ({ kind: 'agents', context: { downServices: ['documents'] } }),
+    workspaceContainersCheck: async () => ({ ok: false, detail: 'stopped' }),
+    mcpCheck: async () => ({ ok: false, detail: 'unavailable' }),
+  });
+  assert.deepEqual(gaps.slice(0, 2).map((gap) => gap.kind), ['network', 'agents']);
+});
+
+test('runChecks still probes MCP endpoints when Docker is unavailable', async () => {
+  await withWorkspace([
+    'llm:',
+    '  provider: openai-compatible',
+    '  baseUrl: http://localhost:8000/v1',
+    '  apiKey: key',
+    '  model: chat-model',
+  ], async () => {
+    const calls = [];
+    await runChecks({
+      dockerCheck: async () => ({ ok: false, context: { dockerUnavailable: true } }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => { calls.push('agents'); return null; },
+      workspaceContainersCheck: async () => { calls.push('containers'); return { ok: true }; },
+      mcpCheck: async () => { calls.push('mcp'); return { ok: true, detail: 'remote connected' }; },
+    });
+    assert.deepEqual(calls, ['mcp']);
+  });
+});
+
+test('checkInternetConnectivity uses a fresh Node process with proxy and CA environment', async () => {
+  const calls = [];
+  const previousProxy = process.env.HTTPS_PROXY;
+  const previousProxyFlag = process.env.NODE_USE_ENV_PROXY;
+  process.env.HTTPS_PROXY = 'http://proxy.test:8080';
+  process.env.NODE_USE_ENV_PROXY = '1';
+  try {
+    const result = await checkInternetConnectivity({
+      url: 'https://connectivity.test/ping',
+      exec: async (...args) => { calls.push(args); return { stdout: '' }; },
+    });
+    assert.equal(result.ok, true);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][1].at(-1), 'https://connectivity.test/ping');
+    assert.equal(calls[0][2].env.HTTPS_PROXY, 'http://proxy.test:8080');
+    assert.equal(result.context.proxyEnabled, true);
+  } finally {
+    if (previousProxy === undefined) delete process.env.HTTPS_PROXY;
+    else process.env.HTTPS_PROXY = previousProxy;
+    if (previousProxyFlag === undefined) delete process.env.NODE_USE_ENV_PROXY;
+    else process.env.NODE_USE_ENV_PROXY = previousProxyFlag;
+  }
+});

package/src/core/wikiSetup.js

@@ -1,13 +1,32 @@
 import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
+import YAML from 'yaml';
+import { checkMissingDockerImages } from './dockerImages.js';
 import { patchWikircProfile } from './wikirc.js';
 import { managerEnvFile, managerMcpEndpointsFile } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
 
+async function missingAgentImages() {
+  const composeFiles = [
+    join(managerRoot(), 'agents.docker-compose.yml'),
+    join(dirname(managerEnvFile()), 'agents.docker-compose.override.yml'),
+  ].filter(existsSync);
+  const images = [...new Set(composeFiles.flatMap((filePath) => {
+    try {
+      const config = YAML.parse(readFileSync(filePath, 'utf8')) ?? {};
+      return Object.values(config.services ?? {}).map((service) => service?.image).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }))];
+  return checkMissingDockerImages(images);
+}
+
 function wrapDockerError(err) {
   if (err?.code === 'ENOENT') {
     return new Error('wiki-workspace script not found. Reinstall wiki-manager.');
@@ -35,6 +54,8 @@ function wrapDockerError(err) {
 
 export async function startAgents(options = {}) {
   try {
+    const absentImages = await missingAgentImages();
+    if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
     const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'up'], {
       cwd: managerRoot(),
       env: {
@@ -51,7 +72,10 @@ export async function startAgents(options = {}) {
       timeout: options.timeout ?? 180_000,
       maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,
     });
-    return [stdout, stderr].filter(Boolean).join('\n').trim();
+    return {
+      output: [stdout, stderr].filter(Boolean).join('\n').trim(),
+      missingImages: absentImages,
+    };
   } catch (err) {
     throw wrapDockerError(err);
   }

package/src/core/wikiWorkspace.test.js

@@ -22,3 +22,12 @@ test('wiki-workspace checks runtime pid command before killing', async () => {
   assert.match(script, /if ! runtime_pid_matches; then\n        printf 'refusing to stop pid/);
   assert.match(script, /kill "\$\(cat "\$pid_file"\)"/);
 });
+
+test('wiki-workspace regenerates CA compose overrides instead of retaining removed services', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.doesNotMatch(script, /if \[\[ ! -f "\$override_path" \]\]; then/);
+  assert.match(script, /local tmp_override="\$override_path\.tmp\.\$\$"/);
+  assert.match(script, /mv "\$tmp_override" "\$override_path"/);
+  assert.match(script, /Changes are overwritten on the next compose command/);
+});

package/src/runtime/lifecycle.js

@@ -83,7 +83,7 @@ export async function ensureRuntime({
     if (!forceRestart && !stale && actualCacertPath === expectedCacertPath) {
       return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
     }
-    if (stale) console.error('runtime: source changed since start — restarting for fresh code.');
+    if (stale) console.log('\x1b[32mruntime: source changed since start — restarting for fresh code.\x1b[0m');
     await postRuntimeShutdown({ url, token: auth.token });
     await waitForRuntimeShutdown(url, auth.token, 2500);
   }

package/src/shell/LeftPane.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 import { For, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
 import { colorForRenderedLine, helpCommandParts, keyValueParts, renderPlainMarkdown } from './renderer';
+import { httpLinkParts, wrapHttpLinks } from './externalLinks.js';
 
 const LEGACY_DONNA_ROLE = 'do' + 't';
 
@@ -47,7 +48,7 @@ function wrapLine(line: string, width: number) {
   return out;
 }
 
-type Segment = { text: string; color: string; width?: number; bg?: string };
+type Segment = { text: string; color: string; width?: number; bg?: string; url?: string };
 type RenderedLine = {
   segments: Segment[];
   status?: boolean;
@@ -300,6 +301,16 @@ function renderMarkdownLines(lines: Array<{ text: string; isCode: boolean }>, ro
     const rendered = renderPlainMarkdown(text);
     const isCmdDesc = splitCmdDesc(rendered) !== null;
     const fallback = isCmdDesc ? '#FFFFFF' : colorForRenderedLine(rendered, role);
+    if (httpLinkParts(rendered).some((part: { url?: string }) => part.url)) {
+      output.push(...wrapHttpLinks(rendered, columns).map((parts: Array<{ text: string; url?: string }>) => ({
+        segments: parts.map((part) => ({
+          text: part.text || ' ',
+          color: part.url ? '#5DADE2' : fallback,
+          url: part.url,
+        })),
+      })));
+      continue;
+    }
     output.push(...wrapLine(rendered, columns).map((piece, idx) => ({
       segments: idx === 0
         ? segmentsForLine(piece, role, columns)
@@ -489,7 +500,11 @@ export function ConversationView(props: {
           ) : (
             <box height={1} flexDirection="row" overflow="hidden">
               <For each={line.segments}>
-                {(seg: Segment) => <text width={seg.width} fg={seg.color} bg={seg.bg}>{seg.text}</text>}
+                {(seg: Segment) => (
+                  <text width={seg.width} fg={seg.color} bg={seg.bg}>
+                    {seg.url ? <a href={seg.url}>{seg.text}</a> : seg.text}
+                  </text>
+                )}
               </For>
             </box>
           )

package/src/shell/RightPane.tsx

@@ -20,6 +20,7 @@ type LogLineParts = { time: string | null; message: string };
 // wrapped status/error), so fewer, readable entries beat more, truncated ones.
 const ACTIVITY_SLOTS = Array.from({ length: 4 }, (_, index) => index);
 const LOG_SLOTS = Array.from({ length: 24 }, (_, index) => index);
+const PLAN_VIEWPORT_ROWS = 12;
 
 function wrapLine(value: string, width: number) {
   const max = Math.max(8, width);
@@ -131,29 +132,45 @@ function queueSummary(item: QueueItem) {
 }
 
 export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: string }) {
-  const lineWidth = () => Math.max(8, props.width - 2);
+  // Keep one column for the native vertical scrollbar when the plan is long.
+  const lineWidth = () => Math.max(8, props.width - 3);
   const firstPending = () => props.plan.find((s) => s.status === 'pending')?.step ?? null;
   const icon = (status: string) =>
     status === 'done' ? '[✓]' : status === 'failed' ? '[✗]' : status === 'running' ? '[…]' : '[ ]';
-  const title = () => props.jobName ? `Plan : ${props.jobName}` : 'Plan';
+  const visualRows = createMemo(() => props.plan.reduce((total, step) =>
+    total + wrapLine(`${icon(step.status)} ${step.step}. ${step.description}`, lineWidth()).slice(0, 2).length, 0));
+  const title = () => {
+    const label = props.jobName ? `Plan : ${props.jobName}` : 'Plan';
+    return visualRows() > PLAN_VIEWPORT_ROWS ? `${label} (${props.plan.length}) · scroll` : label;
+  };
+  const viewportRows = () => Math.min(PLAN_VIEWPORT_ROWS, Math.max(1, visualRows()));
   return (
     <box flexShrink={0} flexDirection="column" padding={1}>
       <text width={lineWidth()} fg="#D6DEE8" content={fit(title(), lineWidth())} />
-      <Index each={props.plan}>
-        {(step) => {
-          // Wrap step descriptions over up to 2 lines instead of truncating —
-          // "Ingest des 39 documents raw/untrac…" hid the actual target.
-          const lines = () => wrapLine(`${icon(step().status)} ${step().step}. ${step().description}`, lineWidth()).slice(0, 2);
-          return (
-            <box flexDirection="column">
-              <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={lines()[0]} />
-              <Show when={lines()[1]}>
-                <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={`    ${fit(lines()[1], Math.max(8, lineWidth() - 4))}`} />
-              </Show>
-            </box>
-          );
-        }}
-      </Index>
+      <scrollbox
+        height={viewportRows()}
+        scrollY={true}
+        scrollX={false}
+        stickyStart="top"
+        viewportCulling={true}
+        verticalScrollbarOptions={{ visible: visualRows() > PLAN_VIEWPORT_ROWS }}
+      >
+        <Index each={props.plan}>
+          {(step) => {
+            // Wrap step descriptions over up to 2 lines instead of truncating —
+            // "Ingest des 39 documents raw/untrac…" hid the actual target.
+            const lines = () => wrapLine(`${icon(step().status)} ${step().step}. ${step().description}`, lineWidth()).slice(0, 2);
+            return (
+              <box flexShrink={0} flexDirection="column">
+                <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={lines()[0]} />
+                <Show when={lines()[1]}>
+                  <text width={lineWidth()} fg={planStepColor(step(), firstPending())} content={`    ${fit(lines()[1], Math.max(8, lineWidth() - 4))}`} />
+                </Show>
+              </box>
+            );
+          }}
+        </Index>
+      </scrollbox>
     </box>
   );
 }

package/src/shell/SetupWizard.tsx

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { useKeyboard, usePaste } from '@opentui/solid';
 import { createEffect, createMemo, createSignal, For, Show } from 'solid-js';
 import { fallbackModels, normalizeProvider } from '../core/modelFetch.js';
+import { checkInternetConnectivity } from '../core/startupCheck.js';
 import {
   createNewWorkspace,
   deleteWorkspaceAndFiles,
@@ -17,13 +18,13 @@ import {
 import { listWorkspaces, workspacesDir } from '../core/workspaces.js';
 import { loadWikircProfile } from '../core/wikirc.js';
 
-type Gap = { kind: 'agents' | 'workspace' | 'llm' | 'vector'; context?: Record<string, any> };
+type Gap = { kind: 'agents' | 'network' | 'workspace' | 'llm' | 'vector'; context?: Record<string, any> };
 type Mode = 'startup' | 'setup';
 type Step =
   | { kind: 'menu'; title: string; items: Array<{ label: string; value: string; muted?: boolean }> }
   | { kind: 'confirm'; title: string; message: string; yesLabel: string; noLabel: string }
   | { kind: 'select'; title: string; label: string; options: string[]; note?: string }
-  | { kind: 'text'; title: string; label: string; placeholder?: string; prefill?: string; secret?: boolean }
+  | { kind: 'text'; title: string; label: string; note?: string; placeholder?: string; prefill?: string; secret?: boolean }
   | { kind: 'done' };
 type LogEntry = { icon: string; label: string; detail?: string };
 
@@ -195,6 +196,20 @@ export function SetupWizard(props: {
         noLabel: 'Skip',
       };
     }
+    if (currentRoute === 'network') {
+      const context = currentGap()?.context ?? {};
+      const transport = context.proxyUrl
+        ? `Proxy: ${context.proxyEnabled ? context.proxyUrl : `${context.proxyUrl} (NODE_USE_ENV_PROXY is not enabled)`}`
+        : 'Proxy: direct connection';
+      const certificate = context.cacertPath ? `CA: ${context.cacertPath}` : 'CA: system trust store';
+      return {
+        kind: 'confirm',
+        title: 'Internet connectivity',
+        message: `Could not reach ${context.url ?? 'the connectivity endpoint'}.\n${transport}\n${certificate}\n${context.error ?? ''}`.trim(),
+        yesLabel: 'Retry',
+        noLabel: 'Skip',
+      };
+    }
     if (currentRoute === 'workspace-confirm') {
       return { kind: 'confirm', title: 'Workspace', message: 'No workspace configured.', yesLabel: 'Create', noLabel: 'Skip' };
     }
@@ -219,21 +234,32 @@ export function SetupWizard(props: {
       };
     }
     if (currentRoute === 'llm-baseurl') {
-      const baseUrl = llm().baseUrl || defaultBaseUrl(llm().provider);
-      return { kind: 'text', title: 'LLM configuration', label: 'Base URL', prefill: baseUrl, placeholder: baseUrl };
+      const example = defaultBaseUrl(llm().provider);
+      return {
+        kind: 'text',
+        title: 'LLM configuration',
+        label: `Base URL${example ? ` (example: ${example})` : ''}`,
+        prefill: llm().baseUrl || '',
+      };
     }
     if (currentRoute === 'llm-apikey') {
       return { kind: 'text', title: 'LLM configuration', label: 'API key (required)', secret: true };
     }
     if (currentRoute === 'llm-model') {
-      const defaultModel = llm().model || fallbackModels(llm().provider)[0] || '';
-      return { kind: 'text', title: 'LLM configuration', label: 'Model', prefill: defaultModel };
+      const example = fallbackModels(llm().provider)[0] || 'provider-agentic-model';
+      return {
+        kind: 'text',
+        title: 'LLM configuration',
+        label: `Model (example: ${example})`,
+        note: 'Required: an agentic model with tool/function calling support.',
+        prefill: llm().model || '',
+      };
     }
     if (currentRoute === 'vector-confirm') {
       return { kind: 'confirm', title: 'Vector search', message: 'Configure vector search?', yesLabel: 'Enable', noLabel: 'Skip' };
     }
     if (currentRoute === 'vector-baseurl') {
-      const baseUrl = vector().baseUrl || llm().baseUrl || defaultBaseUrl(llm().provider);
+      const baseUrl = vector().baseUrl || llm().baseUrl;
       return { kind: 'text', title: 'Vector search', label: 'Embeddings/rerank base URL', prefill: baseUrl, placeholder: baseUrl };
     }
     if (currentRoute === 'vector-apikey') {
@@ -326,6 +352,7 @@ export function SetupWizard(props: {
   function startupRoute(gap?: Gap) {
     if (!gap) return 'done';
     if (gap.kind === 'agents') return 'agents';
+    if (gap.kind === 'network') return 'network';
     if (gap.kind === 'workspace') return 'workspace-confirm';
     if (gap.kind === 'llm') return 'llm-provider';
     if (gap.kind === 'vector') return 'vector-confirm';
@@ -462,7 +489,10 @@ export function SetupWizard(props: {
     if (currentRoute === 'llm-provider') {
       const provider = normalizeProvider(value);
       setLlm((old: any) => {
-        const baseUrl = (old.provider === provider && old.baseUrl) ? old.baseUrl : defaultBaseUrl(provider);
+        const asksForBaseUrl = provider === 'ollama' || provider === 'openai-compatible';
+        const baseUrl = (old.provider === provider && old.baseUrl)
+          ? old.baseUrl
+          : asksForBaseUrl ? '' : defaultBaseUrl(provider);
         return { ...old, provider, baseUrl, ...(provider === 'ollama' && !old.apiKey ? { apiKey: 'ollama' } : {}) };
       });
       if (provider === 'ollama' || provider === 'openai-compatible') return navigate('llm-baseurl');
@@ -513,6 +543,14 @@ export function SetupWizard(props: {
       });
       return;
     }
+    if (currentRoute === 'network') {
+      await runAction(async () => {
+        const result = await checkInternetConnectivity();
+        if (!result.ok) throw new Error(result.context?.error ?? 'Internet connectivity check failed.');
+        nextStartup('Internet connectivity verified');
+      });
+      return;
+    }
     if (currentRoute === 'workspace-confirm') return navigate('workspace-name');
     if (currentRoute === 'vector-rerank') return navigate('vector-rerank-model');
     if (currentRoute === 'vector-confirm') {
@@ -560,7 +598,8 @@ export function SetupWizard(props: {
       return;
     }
     if (currentRoute === 'llm-baseurl') {
-      setLlm((old: any) => ({ ...old, baseUrl: value || old.baseUrl || defaultBaseUrl(old.provider) }));
+      if (!value) return setError('Base URL is required.');
+      setLlm((old: any) => ({ ...old, baseUrl: value }));
       if (llm().provider === 'ollama') return navigate('llm-model');
       return navigate('llm-apikey');
     }
@@ -570,7 +609,8 @@ export function SetupWizard(props: {
       return navigate('llm-model');
     }
     if (currentRoute === 'vector-baseurl') {
-      const baseUrl = value || vector().baseUrl || llm().baseUrl || defaultBaseUrl(llm().provider);
+      const baseUrl = value || vector().baseUrl || llm().baseUrl;
+      if (!baseUrl) return setError('Embeddings/rerank base URL is required.');
       setVector((old: any) => ({ ...old, provider: llm().provider, baseUrl }));
       return navigate('vector-apikey');
     }
@@ -750,6 +790,9 @@ export function SetupWizard(props: {
       <Show when={(step() as any).message || (step() as any).label}>
         <text height={1} fg="#D6DEE8">{(step() as any).message ?? (step() as any).label}</text>
       </Show>
+      <Show when={(step() as any).note}>
+        <text height={1} fg="#9CA3AF">{(step() as any).note}</text>
+      </Show>
       <Show when={step().kind === 'text'}>
         <box
           height={5}