@dotdrelle/wiki-manager 0.14.9 → 0.14.12

package/.env.example

@@ -16,6 +16,20 @@ WORKSPACES_ROOT=/path/to/workspaces
 # Defaults to .agents-data/ next to wiki-workspace.
 # AGENTS_DATA_DIR=/path/to/.agents-data
 
+# ── VPN / outbound HTTP proxy (optional) ──────────────────────────────────────
+#
+# Node fetch does not use HTTP_PROXY / HTTPS_PROXY unless environment proxy
+# support is enabled. This matters for the manager runtime's own LLM calls
+# (including runtime.delegate objective resolution) behind a corporate VPN.
+# Keep these lines commented when no proxy is required.
+# NODE_USE_ENV_PROXY=1
+# HTTPS_PROXY=http://proxy.example:11011
+# HTTP_PROXY=http://proxy.example:11011
+# Always bypass the proxy for the local runtime, local MCPs, and Docker host.
+# NO_PROXY=localhost,127.0.0.1,host.docker.internal
+# Optional organization-approved HTTPS endpoint for the ShellUI startup probe.
+# WIKI_MANAGER_CONNECTIVITY_URL=https://registry.npmjs.org/-/ping
+
 # ── Agent auth tokens ──────────────────────────────────────────────────────────
 #
 # Each agent has its own bearer token. Set the matching Authorization header
@@ -39,7 +53,7 @@ DOCUMENTS_MCP_AUTH_TOKEN=
 # All image OCR is delegated to an OpenAI-compatible vision LLM. The default
 # Default target is the Albert API (etalab); set DOCUMENT_LLM_API_KEY.
 # DOCUMENT_LLM_BASE_URL=https://albert.api.etalab.gouv.fr/v1
-# DOCUMENT_LLM_MODEL=LightOnOCR-2-1B
+# DOCUMENT_LLM_MODEL=lightonai/LightOnOCR-2-1B
 # DOCUMENT_LLM_API_KEY=
 # DOCUMENT_LLM_TIMEOUT_SECONDS=120
 

package/README.md

@@ -8,7 +8,7 @@ endpoints, and provides the `donna` shell: an agent-first terminal UI that can
 inspect workspaces, run safe manager commands, call MCP tools, guide production
 jobs, and run one-shot headless tasks.
 
-Current coordinated release: **0.14.5**. Managed `llm-wiki` services expose
+Current coordinated release: **0.14.11**. Managed `llm-wiki` services expose
 the Wiki Graph v2 browser and APIs; rebuild the `llm-wiki` image when deploying
 this release through Docker.
 
@@ -86,6 +86,27 @@ npm install --global --allow-scripts=bun @dotdrelle/wiki-manager
 In both modes, launch the commands from the directory that should hold the
 manager state (`workspaces/`, `.env`, and `mcp.endpoints.json`).
 
+At interactive ShellUI startup, the manager checks Docker availability first,
+then outbound HTTPS connectivity, followed by agent and workspace
+configuration, workspace containers, MCP handshakes (`tools/list`), and the
+Donna runtime. The connectivity probe uses the configured HTTP(S) proxy and
+custom CA settings. MCP diagnostics distinguish configuration, authentication,
+reachability, and protocol failures. Remote MCPs are skipped when Internet is
+offline, while local endpoints are still checked; MCPs are also checked when
+Docker is unavailable because they may run elsewhere.
+
+The startup screen reports **Ready**, **Degraded**, or **Setup required** and
+keeps the shell usable in degraded mode. It offers **Retry pending checks**,
+**Start services**, and **Open diagnostics** (service logs plus detailed MCP
+status). Set
+`WIKI_MANAGER_CONNECTIVITY_URL` only when the default npm-registry ping endpoint
+must be replaced by an organization-approved HTTPS endpoint.
+
+After a workspace is loaded, ShellUI displays `/status` automatically as the
+first operational view. When **Open workspace** also starts services, the status
+snapshot is produced afterwards so it reflects their current container and MCP
+state.
+
 ## Functional overview
 
 The diagram below shows the whole picture at a glance: how **inputs** (external
@@ -664,7 +685,18 @@ Original files are stored under
 the documents agent to `<workspace>/raw/untracked/`. If the documents agent is
 down, the upload remains stored and can be converted later.
 Image files, scanned PDFs, and images detected inside PDF or Office documents
-are sent through LLM OCR automatically.
+are sent through LLM OCR automatically. The bundled agent stack defaults to
+the Albert-compatible endpoint and
+[`lightonai/LightOnOCR-2-1B`](https://huggingface.co/lightonai/LightOnOCR-2-1B);
+configure it with `DOCUMENT_LLM_BASE_URL`, `DOCUMENT_LLM_MODEL`, and the
+dedicated `DOCUMENT_LLM_API_KEY` (an ambient `OPENAI_API_KEY` is not used).
+
+In the served web Chat, a successful conversion also adds the new
+`raw/untracked/*.md` path as a document-context badge. Up to five wiki or
+pending Markdown documents can be selected. Only their paths are sent to
+Donna; she reads the relevant documents through the configured read-only MCP
+tools when the question refers to them. This does not ingest the document:
+`wiki ingest` remains the explicit transition into the durable wiki.
 
 ## The `donna` Shell
 
@@ -701,6 +733,14 @@ The TUI uses a two-pane layout:
   `Ctrl+Q` toggles the tabs; clicking `Plan` or `Queue (N)` selects that tab
   directly. MCP connection details remain available through `/mcp status`.
 
+In the served browser Activity panel, `Clear` is a per-tab display cleanup and
+`Clear all` applies it to Plan, Local activity, Runtime activity, and Logs. It
+does not delete a plan. **Reset plan** is the confirmed destructive operation:
+it stops active work and purges the workspace runtime plan, activities, logs,
+queue, and persisted runtime state. Donna can perform the same operation when
+the user explicitly asks to delete, reset, abandon, or replace the current
+plan. A request that only says to stop or cancel remains non-purging.
+
 Useful primitives:
 
 ```text

package/agents.docker-compose.yml

@@ -13,7 +13,7 @@
 #   CME_MCP_AUTH_TOKEN     — bearer token for cme agent (empty = no auth)
 #   DOCUMENTS_MCP_AUTH_TOKEN — bearer token for documents agent (empty = no auth)
 #   DOCUMENT_LLM_BASE_URL  — https://albert.api.etalab.gouv.fr/v1
-#   DOCUMENT_LLM_MODEL     — LightOnOCR-2-1B
+#   DOCUMENT_LLM_MODEL     — lightonai/LightOnOCR-2-1B
 #   DOCUMENT_LLM_API_KEY   — OpenAI/OpenAI-compatible API key for document OCR
 #   DOCUMENT_LLM_TIMEOUT_SECONDS — 120
 #
@@ -63,9 +63,9 @@ services:
       - DOCUMENT_OUTPUT_DIR=/documents/output
       - WORKSPACES_ROOT=/workspaces
       - DOCUMENT_MAX_UPLOAD_BYTES=${DOCUMENT_MAX_UPLOAD_BYTES:-52428800}
-      - DOCUMENT_LLM_BASE_URL=${DOCUMENT_LLM_BASE_URL:-https://api.openai.com/v1}
-      - DOCUMENT_LLM_MODEL=${DOCUMENT_LLM_MODEL:-gpt-5.4-mini}
-      - DOCUMENT_LLM_API_KEY=${DOCUMENT_LLM_API_KEY:-${OPENAI_API_KEY:-}}
+      - DOCUMENT_LLM_BASE_URL=${DOCUMENT_LLM_BASE_URL:-https://albert.api.etalab.gouv.fr/v1}
+      - DOCUMENT_LLM_MODEL=${DOCUMENT_LLM_MODEL:-lightonai/LightOnOCR-2-1B}
+      - DOCUMENT_LLM_API_KEY=${DOCUMENT_LLM_API_KEY:-}
       - DOCUMENT_LLM_TIMEOUT_SECONDS=${DOCUMENT_LLM_TIMEOUT_SECONDS:-120}
       # HTTPS — uncomment and place cert files in AGENTS_DATA_DIR/certs/
       #- MCP_SSL_CERTFILE=/certs/server.crt
@@ -76,4 +76,3 @@ services:
       - ${WORKSPACES_ROOT:?Set WORKSPACES_ROOT to the directory containing all workspace folders}:/workspaces
       #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped
-

package/mcp.endpoints.example.json

@@ -27,9 +27,9 @@
     }
   },
   "chatAccess": {
-    "maxToolIterations": 6,
+    "maxToolIterations": 8,
     "servers": {
-      "wiki":       { "allow": ["help_list", "help_read"] },
+      "wiki":       { "allow": ["help_list", "help_read", "wiki_workspace_status", "wiki_list_pages", "wiki_read_page", "wiki_read_pages", "wiki_search_context", "wiki_collect_context", "wiki_read_ingested_source"] },
       "production": { "allow": ["production_job_status", "production_jobs_list"] },
       "cme":        { "allow": ["cme_status", "cme_sources_list", "cme_export_status"] }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.14.9",
+  "version": "0.14.12",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/env.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/cacert.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
     "check-versions": "node scripts/check-versions.js",
     "prepack": "node scripts/check-versions.js",
     "prepublishOnly": "node scripts/check-versions.js",

package/src/agent/graph.js

@@ -120,7 +120,10 @@ const RUNTIME_KILL_TOOL = {
   function: {
     name: 'runtime__kill',
     description: 'Hard-stop the workspace runtime: abort the active run, cancel its agent jobs, mark persisted runs interrupted and purge the control queue. Use when the user asks to remove/kill/clean the current run, its jobs or the queue.',
-    parameters: { type: 'object', additionalProperties: false, properties: { runId: { type: 'string', description: 'Optional specific run id; omit to kill everything active in the workspace.' } } },
+    parameters: { type: 'object', additionalProperties: false, properties: {
+      runId: { type: 'string', description: 'Optional specific run id; omit to kill everything active in the workspace.' },
+      purge: { type: 'boolean', description: 'Set true only when the user explicitly asks to delete/reset/replace the current plan and runtime history.' },
+    } },
   },
 };
 
@@ -694,8 +697,8 @@ async function handleRuntimeControlTool(session, tool, args = {}) {
   const workspace = session.workspace ?? null;
   try {
     if (tool === 'kill') {
-      const result = await postRuntimeKill({ url, workspace, runId: args.runId ?? null });
-      return `Runtime killed: ${result.runs ?? 0} run(s) interrupted, ${result.tasks ?? 0} task(s) cancelled, ${result.queued ?? 0} queued control request(s) purged.`;
+      const result = await postRuntimeKill({ url, workspace, runId: args.runId ?? null, purge: args.purge === true });
+      return `Runtime killed: ${result.runs ?? 0} run(s) interrupted, ${result.tasks ?? 0} task(s) cancelled, ${result.queued ?? 0} queued control request(s) purged${result.purged ? `; runtime state reset (${result.purged.events ?? 0} event(s))` : ''}.`;
     }
     if (tool === 'cancel') {
       const result = await postRuntimeCancel({ url, workspace });
@@ -942,7 +945,7 @@ export function buildAgentSystemPrompt(state) {
     workspaceProfile
       ? `Workspace profile (.wiki/profile.md) — durable user preferences, apply these to every reply (tone, tutoiement/vouvoiement, formatting, etc.):\n${workspaceProfile}`
       : null,
-    'Runtime control: you have runtime__status, runtime__cancel, runtime__kill, runtime__approve and runtime__enqueue. When the user asks to stop, remove, clean or kill the current run, its jobs or the queue ("supprime le job et la queue", "arr\u00eate tout"), call runtime__kill (or runtime__cancel for a soft stop of just the run) and confirm what was stopped. For questions about what is running or queued, call runtime__status and answer from its data. When the user consents to a pending approval in any phrasing ("vas-y", "ok pour l\'export"), call runtime__approve. When the user asks for a NEW action while a run is active, do not execute it: propose runtime__enqueue (run it after) or, if they insist it replaces the current work, runtime__kill then the new action.',
+    'Runtime control: you have runtime__status, runtime__cancel, runtime__kill, runtime__approve and runtime__enqueue. When the user asks to stop, remove, clean or kill the current run, its jobs or the queue ("supprime le job et la queue", "arr\u00eate tout"), call runtime__kill (or runtime__cancel for a soft stop of just the run) and confirm what was stopped. When the user explicitly asks to delete, reset, abandon or replace the current plan, call runtime__kill with purge=true; never set purge=true for a simple stop. For questions about what is running or queued, call runtime__status and answer from its data. When the user consents to a pending approval in any phrasing ("vas-y", "ok pour l\'export"), call runtime__approve. When the user asks for a NEW action while a run is active, do not execute it: propose runtime__enqueue (run it after) or, if they insist it replaces the current work, runtime__kill then the new action.',
     'Report every runtime control outcome exactly as the tool returned it \u2014 never embellish. If runtime__kill reports 0 run(s)/0 task(s)/0 purged, say there was nothing active to stop or purge; do NOT claim a run, plan, pending approval or queue item was removed. If runtime__status returns an error or could not be read, say the runtime state could not be retrieved and do not describe a state you never obtained. Never assert that something was cleaned, cancelled, approved or purged unless that specific tool result confirms it.',
     'Durable profile updates are actions in this stabilized version: delegate them instead of writing directly.',
   ].filter(Boolean).join('\n');
@@ -1005,7 +1008,7 @@ function toolsForClassification(classification, writeTools, session = null) {
   return [SHELL_READ_COMMAND_TOOL, ...controlTools, ...capabilityRunTools, ...writeTools];
 }
 
-const DONNA_READ_VERBS = new Set(['status', 'list', 'search', 'read', 'get', 'fetch']);
+const DONNA_READ_VERBS = new Set(['status', 'list', 'search', 'read', 'get', 'fetch', 'collect']);
 
 export function isDonnaReadTool(item) {
   const name = String(item?.function?.name ?? '');

package/src/agent/graph.test.js

@@ -1349,11 +1349,14 @@ test('Donna interprets a cleanup request and calls runtime__kill herself', async
     runtime: { url: 'http://runtime.test' },
     agentProjection: { status: 'running', activities: [], conversation: [] },
     llm: {
-      async completeWithTools({ tools }) {
+      async completeWithTools({ tools, system }) {
         calls += 1;
         if (calls === 1) {
           const names = tools.map((tool) => tool.function.name);
           assert.ok(names.includes('runtime__kill'), 'control tools must be bound during an active run');
+          const killTool = tools.find((tool) => tool.function.name === 'runtime__kill');
+          assert.equal(killTool.function.parameters.properties.purge.type, 'boolean');
+          assert.match(system, /delete, reset, abandon or replace the current plan/);
           return {
             content: null,
             message: { role: 'assistant', content: null },

package/src/cli/wiki-manager.js

@@ -7,7 +7,7 @@ loadManagerEnv();
 import { createAgentGraph } from '../agent/graph.js';
 import { handleSlashCommand, printHelp, printVersion, refreshMcpRuntimeStatus } from '../commands/slash.js';
 import { runShell, runHeadlessChatTurn } from '../shell/repl.js';
-import { runChecks } from '../core/startupCheck.js';
+import { runPreflightChecks, withRuntimePreflight } from '../core/startupCheck.js';
 import { applySessionWikircProfile } from '../core/sessionConfig.js';
 import { listWikircProfiles } from '../core/wikirc.js';
 import { callMcpTool, formatMcpToolResult, readChatAccessConfig } from '../core/mcp.js';
@@ -31,6 +31,22 @@ function valueAfter(argv, flag) {
   return argv[index + 1];
 }
 
+function errorDiagnostic(err) {
+  const parts = [];
+  let current = err;
+  const seen = new Set();
+  while (current && !seen.has(current) && parts.length < 4) {
+    seen.add(current);
+    const name = current?.name && current.name !== 'Error' ? String(current.name) : '';
+    const code = current?.code ? String(current.code) : '';
+    const message = current instanceof Error ? current.message : String(current);
+    const detail = [name, code, message].filter(Boolean).join(' ');
+    if (detail && !parts.includes(detail)) parts.push(detail);
+    current = current?.cause;
+  }
+  return parts.join(' <- ') || 'unknown error';
+}
+
 function unavailableRuntime(err) {
   const reason = err instanceof Error ? err.message : String(err);
   return { url: null, error: reason };
@@ -787,27 +803,42 @@ async function runRuntime(argv, agent) {
     const { resolveObjective } = await import('../orchestrator/objectiveResolver.js');
     const { validateFragment } = await import('../orchestrator/planValidator.js');
     const session = context.session;
-    const selection = await resolveObjective(objective, session);
+    let selection;
+    try {
+      selection = await resolveObjective(objective, session);
+    } catch (err) {
+      throw new Error(`Delegation failed during objective_resolution: ${errorDiagnostic(err)}`, { cause: err });
+    }
     const provider = selection.provider;
-    const fragment = parseJsonText(formatMcpToolResult(await callMcpTool(
-      session.mcp,
-      provider.serverName,
-      'agent_plan',
-      {
-        capability: selection.capability,
-        operation: selection.operation,
-        objective,
-        workspace: { revision: String(Date.now()) },
-        constraints: {
-          maxConcurrency: resolveCapabilityConcurrency(
-            provider,
-            undefined,
-            process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
-          ),
-          requireApprovalForMutations: true,
+    let planResult;
+    try {
+      planResult = await callMcpTool(
+        session.mcp,
+        provider.serverName,
+        'agent_plan',
+        {
+          capability: selection.capability,
+          operation: selection.operation,
+          objective,
+          workspace: { revision: String(Date.now()) },
+          constraints: {
+            maxConcurrency: resolveCapabilityConcurrency(
+              provider,
+              undefined,
+              process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
+            ),
+            requireApprovalForMutations: true,
+          },
         },
-      },
-    )));
+      );
+    } catch (err) {
+      const endpoint = session.mcp?.[provider.serverName]?.url ?? 'unknown endpoint';
+      throw new Error(
+        `Delegation failed during agent_plan: provider=${provider.serverName} endpoint=${endpoint} ${errorDiagnostic(err)}`,
+        { cause: err },
+      );
+    }
+    const fragment = parseJsonText(formatMcpToolResult(planResult));
     if (!Array.isArray(fragment?.tasks) || fragment.tasks.length === 0) {
       throw new Error(fragment?.summary?.initialSynthesis?.[0] ?? `No task was planned for ${selection.capability}/${selection.operation}.`);
     }
@@ -1054,6 +1085,9 @@ async function runRuntime(argv, agent) {
       response = await runHeadlessChatTurn(ephemeral, input, {
         history,
         onStep: ephemeral._onStep,
+        // UI context from `wiki serve`: up to five selected wiki or raw
+        // documents. Only paths are prompted; Donna reads through tools.
+        openWikiPages: body.context?.openWikiPages ?? body.context?.openWikiPage,
       });
     } else {
       response = await runAgentTurn(agent, ephemeral, input, { messages, signal });
@@ -1191,8 +1225,23 @@ export async function runCli(argv) {
     // in a random cwd must not litter files.
     const scaffolded = ensureManagerScaffold({ log: (message) => console.log(`[wiki-manager] ${message}`) });
     if (scaffolded.length > 0) loadManagerEnv();
-    const gaps = await runChecks();
-    if (gaps.length > 0) await runStartupWizard(gaps);
+    const reportCheck = ({ kind, ok, detail, context, skipped, pending }) => {
+      const labels = { docker: 'Docker', internet: 'Internet', agents: 'Agent containers', workspace: 'Workspaces', containers: 'Workspace containers', mcp: 'MCP' };
+      const label = labels[kind] ?? kind;
+      const instruction = !ok && context?.command ? ` — command: ${context.command}` : '';
+      const suffix = detail ? ` — ${detail}` : ` — ${context?.error ?? context?.dockerError ?? 'waiting'}`;
+      const color = ok ? '\x1b[32m' : '\x1b[33m';
+      const state = ok ? 'ready' : pending || skipped ? 'waiting' : 'needs attention';
+      const icon = ok ? '✓' : pending || skipped ? '◐' : '✗';
+      console.log(`${color}${icon} configuration: ${label} ${state}${suffix}${instruction}\x1b[0m`);
+    };
+    let preflight = await runPreflightChecks({ onCheck: reportCheck });
+    if (preflight.gaps.length > 0) {
+      await runStartupWizard(preflight.gaps);
+      // The wizard may have created a workspace, started agents or repaired
+      // configuration. Re-read everything before drawing the home screen.
+      preflight = await runPreflightChecks();
+    }
     let runtime = null;
     try {
       const { ensureRuntime } = await import('../runtime/lifecycle.js');
@@ -1203,11 +1252,12 @@ export async function runCli(argv) {
       runtime = unavailableRuntime(err);
       console.error(`Runtime unavailable: ${runtime.error}`);
     }
+    preflight = withRuntimePreflight(preflight, runtime);
     // The owned-runtime shutdown happens inside the TUI's own exit paths
     // (see tui.tsx onShellExit): render() resolves at MOUNT, so anything
     // after this await would run while the shell is still on screen —
     // 0.12.9 shipped exactly that bug and killed the runtime under the user.
-    await runOpenTuiShell({ agent, packageJson, runtime });
+    await runOpenTuiShell({ agent, packageJson, runtime, preflight });
     return;
   }
 

package/src/commands/slash.js

@@ -627,7 +627,7 @@ ${helpPair('/mcp tools [mcp]', 'MCP tools', '/mcp call ...', 'Call MCP tool')}
 ${helpPair('/upload <path>', 'Upload document', '/uploads', 'Uploaded docs')}
 ${helpPair('/upload convert pending', 'Convert pending', '/uploads clean', 'Clean uploads')}
 ${helpPair('/wiki', 'Run wiki index', '/wiki run <args>', 'Raw wiki CLI')}
-${helpPair('/chat', 'Chat mode', '/agent', 'Agent mode')}
+${helpPair('/chat', 'Chat mode', '/agent [question]', 'Agent mode / one-shot')}
 ${helpPair('/openui', 'Open web UI in browser', '', '')}
 ${helpPair('/run status', 'Runtime status', '/run kill', 'Kill runtime run(s)')}
 ${helpPair('/run capability <id>', 'Deterministic capability run', '/approve', 'Grant pending approval')}
@@ -678,8 +678,31 @@ function rawCommandResult(command, output) {
   };
 }
 
-export function localizedOperationResult({ operation, target, status = 'succeeded' }) {
-  const facts = JSON.stringify({ operation, target, status });
+// Shared by every deterministic command that can trigger an on-demand
+// `docker pull` (agents up, service start): reports the images as they're
+// found missing and hands back the final list for localizedOperationResult.
+async function collectMissingImages(step, fn) {
+  let missingImages = [];
+  await fn({
+    onImagesMissing: (images) => {
+      missingImages = images;
+      step(`Donna: downloading and installing missing components: ${images.join(', ')}…`);
+    },
+  });
+  return missingImages;
+}
+
+function componentInstallAction(missingImages) {
+  return missingImages.length > 0 ? 'downloaded-and-installed-missing-components' : null;
+}
+
+export function localizedOperationResult({ operation, target, status = 'succeeded', componentAction = null, images = [] }) {
+  const facts = JSON.stringify({
+    operation,
+    target,
+    status,
+    ...(componentAction ? { componentAction, images } : {}),
+  });
   return {
     output: facts,
     rawOutput: true,
@@ -730,10 +753,12 @@ export async function handleSlashCommand(line, context) {
   const runAgentCommand = async (fn, verb) => {
     try {
       step(`Agents: ${verb}ing external agents…`);
-      await fn();
+      const missingImages = await collectMissingImages(step, fn);
       return localizedOperationResult({
         operation: verb,
         target: 'agents',
+        componentAction: componentInstallAction(missingImages),
+        images: missingImages,
       });
     } catch (err) {
       step(formatActivityError('agents', verb, err));
@@ -893,15 +918,17 @@ export async function handleSlashCommand(line, context) {
       // do not remap it to undefined, that bypasses any custom "all" target list and always
       // falls back to the hardcoded COMPOSE_SERVICES constant instead.
       const service = args[1];
-      if (service === 'agents') return runAgentCommand(startAgents, 'start');
+      if (service === 'agents' || service === 'agent') return runAgentCommand(startAgents, 'start');
       try {
         step(`Services: starting ${service ?? 'workspace services'}…`);
-        await startService(context.session, service);
+        const missingImages = await collectMissingImages(step, (opts) => startService(context.session, service, opts));
         step('Services: refreshing MCP runtime…');
         await refreshMcpRuntimeStatus(context.session);
         return localizedOperationResult({
           operation: 'start',
           target: service || 'workspace-services',
+          componentAction: componentInstallAction(missingImages),
+          images: missingImages,
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/src/commands/slash.test.js

@@ -15,6 +15,23 @@ test('deterministic operation results ask Donna to localize compact facts withou
   assert.doesNotMatch(result.agentTrigger, /\/start|Docker|compose/);
 });
 
+test('start result tells Donna when missing container components were installed', () => {
+  const result = localizedOperationResult({
+    operation: 'start',
+    target: 'all',
+    componentAction: 'downloaded-and-installed-missing-components',
+    images: ['dotdrelle/llm-wiki:latest'],
+  });
+  assert.deepEqual(JSON.parse(result.output), {
+    operation: 'start',
+    target: 'all',
+    status: 'succeeded',
+    componentAction: 'downloaded-and-installed-missing-components',
+    images: ['dotdrelle/llm-wiki:latest'],
+  });
+  assert.match(result.agentTrigger, /downloaded-and-installed-missing-components/);
+});
+
 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');

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.9",
-  "commit": "768fb25"
+  "version": "0.14.12",
+  "commit": "621830d"
 }

package/src/core/cacert.js

@@ -40,18 +40,15 @@ function composeOverrideContent(cacertPath, services) {
     services: serviceEntries,
   };
   return [
-    '# Generated by wiki-manager. Edit freely; delete to regenerate.',
+    '# Generated by wiki-manager. Changes are overwritten on the next compose command.',
     YAML.stringify(doc).trimEnd(),
     '',
   ].join('\n');
 }
 
-let _cacertOverrideCache;
-
 export function ensureCacertComposeOverride(composeFilePath, fileName = 'cacert.compose.yml') {
-  if (_cacertOverrideCache !== undefined) return _cacertOverrideCache;
   const cacertPath = activeCacertPath();
-  if (!cacertPath) return (_cacertOverrideCache = null);
+  if (!cacertPath) return null;
   if (!existsSync(cacertPath)) {
     throw new Error(`--cacert file not found: ${cacertPath}`);
   }
@@ -60,8 +57,14 @@ export function ensureCacertComposeOverride(composeFilePath, fileName = 'cacert.
   const runtimeDir = managerRuntimeDir();
   mkdirSync(runtimeDir, { recursive: true });
   const overridePath = join(runtimeDir, fileName);
-  if (!existsSync(overridePath)) {
-    writeFileSync(overridePath, composeOverrideContent(cacertPath, services), 'utf8');
+  const content = composeOverrideContent(cacertPath, services);
+  // The override is generated state, not user configuration. Always compare
+  // it with the active CLI value: keeping an existing file here left Docker
+  // mounting yesterday's CA after --cacert changed, despite all CA
+  // environment variables looking right.
+  const existing = existsSync(overridePath) ? readFileSync(overridePath, 'utf8') : null;
+  if (existing !== content) {
+    writeFileSync(overridePath, content, 'utf8');
   }
-  return (_cacertOverrideCache = overridePath);
+  return overridePath;
 }

package/src/core/cacert.test.js

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { ensureCacertComposeOverride } from './cacert.js';
+
+test('cacert compose override follows the active certificate path', () => {
+  const root = mkdtempSync(join(tmpdir(), 'wiki-manager-cacert-'));
+  const compose = join(root, 'compose.yml');
+  const firstCa = join(root, 'first.pem');
+  const secondCa = join(root, 'second.pem');
+  writeFileSync(compose, 'services:\n  serve:\n    image: example\n', 'utf8');
+  writeFileSync(firstCa, 'first', 'utf8');
+  writeFileSync(secondCa, 'second', 'utf8');
+  const previousCa = process.env.WIKI_MANAGER_CACERT_PATH;
+  const previousEnvFile = process.env.WIKI_MANAGER_ENV_FILE;
+  process.env.WIKI_MANAGER_ENV_FILE = join(root, '.env');
+  try {
+    process.env.WIKI_MANAGER_CACERT_PATH = firstCa;
+    const override = ensureCacertComposeOverride(compose, 'test-cacert.compose.yml');
+    assert.match(readFileSync(override, 'utf8'), new RegExp(firstCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+
+    process.env.WIKI_MANAGER_CACERT_PATH = secondCa;
+    ensureCacertComposeOverride(compose, 'test-cacert.compose.yml');
+    const updated = readFileSync(override, 'utf8');
+    assert.match(updated, new RegExp(secondCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    assert.doesNotMatch(updated, new RegExp(firstCa.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  } finally {
+    if (previousCa === undefined) delete process.env.WIKI_MANAGER_CACERT_PATH;
+    else process.env.WIKI_MANAGER_CACERT_PATH = previousCa;
+    if (previousEnvFile === undefined) delete process.env.WIKI_MANAGER_ENV_FILE;
+    else process.env.WIKI_MANAGER_ENV_FILE = previousEnvFile;
+  }
+});

package/src/core/compose.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { cacertEnv, ensureCacertComposeOverride } from './cacert.js';
+import { checkMissingDockerImages } from './dockerImages.js';
 import { managerEnvFile, readEnvFile, resolveAgentsDataDir } from './env.js';
 import { managerRoot } from './workspaces.js';
 
@@ -281,11 +282,28 @@ export async function serviceStates(session) {
   return states;
 }
 
-export async function startService(session, service) {
+export async function missingServiceImages(service) {
   const aliases = serviceAliases();
   const targets = service ? (aliases[service] ?? [service]) : COMPOSE_SERVICES;
-  const output = await runCompose(session, ['up', '-d', ...targets], { timeout: 180_000 });
-  return [`Started: ${targets.join(', ')}`, output].filter(Boolean).join('\n');
+  const config = readComposeConfig();
+  const images = targets.map((target) => config.services?.[target]?.image).filter(Boolean);
+  return checkMissingDockerImages(images);
+}
+
+export async function startService(session, service, options = {}) {
+  const aliases = serviceAliases();
+  const targets = service ? (aliases[service] ?? [service]) : COMPOSE_SERVICES;
+  const absentImages = await missingServiceImages(service);
+  if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
+  const output = await runCompose(session, ['up', '-d', ...targets], {
+    timeout: 180_000,
+    onOutput: options.onOutput,
+  });
+  return {
+    output: [`Started: ${targets.join(', ')}`, output].filter(Boolean).join('\n'),
+    targets,
+    missingImages: absentImages,
+  };
 }
 
 export async function stopService(session, service) {

package/src/core/dockerCompose.test.js

@@ -22,6 +22,9 @@ test('agent compose services run as the host uid and gid', async () => {
   const agentsCompose = YAML.parse(agentsRaw);
   assert.equal(agentsCompose.services.cme.user, '${UID:-1000}:${GID:-1000}');
   assert.equal(agentsCompose.services.documents.user, '${UID:-1000}:${GID:-1000}');
+  assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_BASE_URL=${DOCUMENT_LLM_BASE_URL:-https://albert.api.etalab.gouv.fr/v1}'), true);
+  assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_MODEL=${DOCUMENT_LLM_MODEL:-lightonai/LightOnOCR-2-1B}'), true);
+  assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_API_KEY=${DOCUMENT_LLM_API_KEY:-}'), true);
   // MailerSend was an external-connector experiment — removed from the
   // default stack (the agent repo still exists for ad-hoc use).
   assert.equal(agentsCompose.services.mailer, undefined);

package/src/core/dockerImages.js

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function checkMissingDockerImages(images) {
+  const unique = [...new Set(images.filter(Boolean))];
+  const checks = await Promise.all(unique.map(async (image) => {
+    try {
+      await execFileAsync('docker', ['image', 'inspect', image], {
+        timeout: 30_000,
+        maxBuffer: 1024 * 1024,
+      });
+      return null;
+    } catch (err) {
+      const detail = [err?.stderr, err?.stdout, err?.message].filter(Boolean).join('\n');
+      if (/no such (?:image|object)/i.test(detail)) return image;
+      throw err;
+    }
+  }));
+  return checks.filter(Boolean);
+}