@dotdrelle/wiki-manager 0.14.10 → 0.14.12

package/.env.example

@@ -27,6 +27,8 @@ WORKSPACES_ROOT=/path/to/workspaces
 # 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 ──────────────────────────────────────────────────────────
 #
@@ -51,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.10",
+  "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/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",
+    "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';
@@ -1085,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 });
@@ -1222,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');
@@ -1234,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/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.10",
-  "commit": "79503aa"
+  "version": "0.14.12",
+  "commit": "621830d"
 }

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/env.js

@@ -51,9 +51,33 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
   const created = [];
   const endpointsFile = managerMcpEndpointsFile();
   const endpointsExample = join(packageRoot, 'mcp.endpoints.example.json');
-  if (!existsSync(endpointsFile) && existsSync(endpointsExample)) {
-    copyFileSync(endpointsExample, endpointsFile);
-    created.push('mcp.endpoints.json');
+  if (existsSync(endpointsExample)) {
+    if (!existsSync(endpointsFile)) {
+      copyFileSync(endpointsExample, endpointsFile);
+      created.push('mcp.endpoints.json');
+    } else {
+      // Additive migration: the scaffold only copies the example on first run,
+      // so installs that predate a new top-level key (e.g. chatAccess) never
+      // receive it and the feature stays silently disabled. Merge ONLY the
+      // top-level keys missing from the operator's file; existing keys —
+      // including a hand-edited chatAccess — are never touched. To disable a
+      // feature key permanently, set it to null instead of deleting it: null is
+      // "present", so the merge preserves it and readers treat it as absent.
+      try {
+        const current = JSON.parse(readFileSync(endpointsFile, 'utf8'));
+        const example = JSON.parse(readFileSync(endpointsExample, 'utf8'));
+        if (current && typeof current === 'object' && !Array.isArray(current)) {
+          const missing = Object.keys(example).filter((key) => !(key in current));
+          if (missing.length > 0) {
+            for (const key of missing) current[key] = example[key];
+            writeFileSync(endpointsFile, `${JSON.stringify(current, null, 2)}\n`);
+            created.push(`mcp.endpoints.json keys: ${missing.join(', ')}`);
+          }
+        }
+      } catch {
+        // Unreadable or invalid JSON: leave the operator's file strictly alone.
+      }
+    }
   }
   const envFile = managerEnvFile();
   const envExample = join(packageRoot, '.env.example');

package/src/core/env.test.js

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ensureManagerScaffold } from './env.js';
+
+// ensureManagerScaffold resolves the manager state dir from
+// WIKI_MANAGER_ENV_FILE — point it at a temp dir for each test.
+function withTempManagerDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'wiki-manager-env-test-'));
+  const previous = process.env.WIKI_MANAGER_ENV_FILE;
+  process.env.WIKI_MANAGER_ENV_FILE = join(dir, '.env');
+  try {
+    return fn(dir);
+  } finally {
+    if (previous === undefined) delete process.env.WIKI_MANAGER_ENV_FILE;
+    else process.env.WIKI_MANAGER_ENV_FILE = previous;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('scaffold copies the packaged examples into a fresh directory', () => {
+  withTempManagerDir((dir) => {
+    const created = ensureManagerScaffold();
+    assert.ok(created.includes('mcp.endpoints.json'));
+    assert.ok(created.includes('.env'));
+    const endpoints = JSON.parse(readFileSync(join(dir, 'mcp.endpoints.json'), 'utf8'));
+    assert.ok(endpoints.mcpServers);
+    assert.ok(endpoints.chatAccess);
+  });
+});
+
+test('scaffold merges missing top-level keys into an existing endpoints file', () => {
+  withTempManagerDir((dir) => {
+    const endpointsFile = join(dir, 'mcp.endpoints.json');
+    // Pre-chatAccess install: only mcpServers, with operator edits.
+    writeFileSync(endpointsFile, JSON.stringify({
+      mcpServers: { custom: { url: 'http://localhost:9999/mcp/' } },
+    }, null, 2));
+    const created = ensureManagerScaffold();
+    assert.ok(created.some((item) => item.includes('chatAccess')));
+    const merged = JSON.parse(readFileSync(endpointsFile, 'utf8'));
+    // Operator's servers untouched; new key added from the example.
+    assert.deepEqual(merged.mcpServers, { custom: { url: 'http://localhost:9999/mcp/' } });
+    assert.ok(merged.chatAccess?.servers?.wiki);
+  });
+});
+
+test('scaffold never overwrites an existing chatAccess, including explicit null', () => {
+  withTempManagerDir((dir) => {
+    const endpointsFile = join(dir, 'mcp.endpoints.json');
+    writeFileSync(endpointsFile, JSON.stringify({
+      mcpServers: {},
+      chatAccess: null,
+    }, null, 2));
+    ensureManagerScaffold();
+    const after = JSON.parse(readFileSync(endpointsFile, 'utf8'));
+    // null means "deliberately disabled" — the merge must preserve it.
+    assert.equal(after.chatAccess, null);
+  });
+});
+
+test('scaffold leaves an invalid endpoints file strictly alone', () => {
+  withTempManagerDir((dir) => {
+    const endpointsFile = join(dir, 'mcp.endpoints.json');
+    writeFileSync(endpointsFile, '{ not json');
+    ensureManagerScaffold();
+    assert.equal(readFileSync(endpointsFile, 'utf8'), '{ not json');
+  });
+});

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.14.10';
+const WIKI_MANAGER_VERSION = '0.14.12';
 
 function envValue(key) {
   const filePath = managerEnvFile();