@dotdrelle/wiki-manager 0.6.26 → 0.6.30

package/README.md

@@ -33,7 +33,7 @@ and a *replaceable* toolbox of *external* MCP servers — to produce the **core
 wiki** outputs, all driven by an agentic, multi-model orchestrator and grounded
 in isolated workspaces.
 
-![wikiLLM functional diagram — inputs, MCP calls and outputs around the agentic orchestrator and workspaces](docs/architecture.svg)
+![wikiLLM functional diagram — inputs, MCP calls and outputs around the agentic orchestrator and workspaces](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/architecture.svg)
 
 ## Quick start — your first wiki in ~5 minutes
 
@@ -56,7 +56,7 @@ mkdir -p ~/llm-wiki && cd ~/llm-wiki      # all manager state lives here
 **2 — Set the environment.**
 Copy the template and keep the defaults — nothing is mandatory for the local
 demo (tokens/credentials are only needed when you connect real sources, see
-[docs/usage.md](docs/usage.md)). The `mcp.endpoints.json` file is created
+[docs/usage.md](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/usage.md)). The `mcp.endpoints.json` file is created
 automatically on the first command.
 
 ```bash
@@ -137,20 +137,10 @@ wiki-workspace wiki demo build            # or, in the shell: /skills run pipeli
 ```
 
 That's the whole loop. Next: the four ways to use it and how to configure the
-external agents (CME & co.) live in [docs/usage.md](docs/usage.md); the detailed
+external agents (CME & co.) live in [docs/usage.md](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/usage.md); the detailed
 story is in [The journey](#the-journey-from-first-launch-to-first-result); and
 installing from source is in [Initial Setup](#initial-setup).
 
-## The 4 ways to use it & agent configuration
-
-The same system has four faces — the **web interface** (explore with the mouse),
-**scripting** (let it run on its own), the **`donna` shell** (talk in plain
-language), and the **shared external agents** (the common toolbox). Each external
-agent (Confluence export with **CME**, document conversion, mail) also needs a
-little setup the first time.
-
-Both are covered in **[docs/usage.md](docs/usage.md)**.
-
 ## The journey: from first launch to first result
 
 Follow this little story in order. By the end you'll have seen it all: the
@@ -353,6 +343,30 @@ ingest -> build -> export -> polish
 The legacy copy step is only for deployments that explicitly configure external
 import mappings.
 
+## Configuration overview
+
+wikiLLM is configured by **four files** held together by two families of keys:
+**MCP keys** (Bearer tokens that authenticate *who connects to whom*) and **LLM
+keys** (`apiKey` + `baseUrl` that *reach a model*).
+
+![wikiLLM configuration keys — MCP vs LLM, where each key is configured](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/config-keys.svg)
+
+| File | Owner | Scope | Holds |
+| --- | --- | --- | --- |
+| `.env` | manager | global | shared secrets: agent MCP tokens, MailerSend, OCR LLM, port overrides |
+| `mcp.endpoints.json` | manager | global | where each external agent lives + which `Bearer`/header to send |
+| `workspaces/<name>/.env` | manager | per workspace | ports, workspace path, the wiki's own MCP tokens |
+| `workspaces/<name>/.wikirc.yaml` (+ `.wikirc.yaml.<profile>`) | workspace | per workspace | LLM & vector keys (provider/model/apiKey/baseUrl/retrieval) |
+
+Donna reaches the external agents and the internal wiki MCP through Bearer
+tokens; the wiki then uses its `.wikirc.yaml` LLM keys to call models and
+embeddings. Because every MCP server is an HTTP endpoint, remote MCP clients can
+connect to the same surfaces with the same tokens. **MCP keys** are set in the
+root `.env`; the wiki's **LLM keys** live in each workspace `.wikirc.yaml`.
+
+See the full, field-by-field reference in
+**[docs/configuration.md](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/configuration.md)**.
+
 ## Initial Setup
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.6.26",
+  "version": "0.6.30",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",

package/src/agent/graph.js

@@ -322,8 +322,8 @@ export function buildAgentSystemPrompt(state) {
     skills,
     'You can call MCP tools directly using the provided tool functions.',
     '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 CME configuration/setup/update requests, if a matching CME tool such as cme_setup is connected and the required arguments are known, call it immediately. If the CME server or tool is not connected, say which CME capability is missing and recommend the exact service/status primitive to inspect it. Do not invent a pending CME action in plain text.',
-    'For workspace-scoped external MCP tools, the orchestrator enforces workspace injection. When calling documents_* conversion tools or cme_* configuration/source/export tools, use the active workspace only. cme_export_status(job_id=...) and cme_export_cancel(job_id=...) can be used from any active workspace.',
+    '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>.',
     '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.',
     [

package/src/commands/slash.js

@@ -658,7 +658,11 @@ export async function handleSlashCommand(line, context) {
       context.session.workspacePath = workspace.workspacePath;
       context.session.workspaceEnv = workspace.env;
       context.session.workspaceEnvFile = workspace.envFile;
-      context.session.mcp = buildMcpStatus(context.session);
+      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…`);
@@ -702,6 +706,7 @@ export async function handleSlashCommand(line, context) {
         }
         try {
           const summary = loadSessionWikirc(context.session, profileName);
+          await refreshMcpRuntimeStatus(context.session);
           return {
             output: [
               'Active wikirc:',

package/src/core/mcp.js

@@ -2,10 +2,12 @@ import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
 function envValue(key) {
-  if (key in process.env) return process.env[key];
   const filePath = managerEnvFile();
-  if (!existsSync(filePath)) return undefined;
-  return readEnvFile(filePath)[key];
+  if (existsSync(filePath)) {
+    const fileValue = readEnvFile(filePath)[key];
+    if (fileValue !== undefined) return fileValue;
+  }
+  return process.env[key];
 }
 
 function interpolateEnv(value) {
@@ -75,16 +77,20 @@ const MCP_SERVICE_MAP = {
 
 export function buildMcpStatus(session) {
   const workspaceEnv = session.workspaceEnv ?? {};
+  const wikiMcpToken = session.wikircConfig?.mcp?.accessKey;
+  const wikiMcpDetail = workspaceEnv.WIKI_MCP_PORT
+    ? (wikiMcpToken ? `:${workspaceEnv.WIKI_MCP_PORT}` : `:${workspaceEnv.WIKI_MCP_PORT} (mcp.accessKey missing in active wikirc)`)
+    : '';
   const external = readExternalMcpEndpoints();
 
   return {
     wiki: {
       ...endpointStatus(
-        workspaceEnv.WIKI_MCP_PORT && workspaceEnv.WIKI_MCP_AUTH_TOKEN,
-        workspaceEnv.WIKI_MCP_PORT ? `:${workspaceEnv.WIKI_MCP_PORT}` : '',
+        workspaceEnv.WIKI_MCP_PORT && wikiMcpToken,
+        wikiMcpDetail,
       ),
       url: workspaceEnv.WIKI_MCP_PORT ? `http://127.0.0.1:${workspaceEnv.WIKI_MCP_PORT}/mcp` : null,
-      token: workspaceEnv.WIKI_MCP_AUTH_TOKEN || null,
+      token: wikiMcpToken || null,
     },
     production: {
       ...endpointStatus(
@@ -205,7 +211,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.6.26' },
+            clientInfo: { name: 'wiki-manager', version: '0.6.30' },
           },
         }),
       });
@@ -295,6 +301,7 @@ export async function discoverMcpTools(mcpStatus) {
       const message = err instanceof Error ? err.message : String(err);
       next[name] = {
         ...value,
+        status: value.status === 'connected' ? 'configured' : value.status,
         tools: [],
         toolError: message,
       };

package/src/core/mcp.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { buildMcpStatus, callMcpTool } from './mcp.js';
+import { buildMcpStatus, callMcpTool, discoverMcpTools } from './mcp.js';
 
 test('buildMcpStatus reads external MCP endpoints from mcp.endpoints.json', async () => {
   const originalCwd = process.cwd();
@@ -87,6 +87,82 @@ test('buildMcpStatus interpolates external endpoints from manager .env', async (
   }
 });
 
+test('buildMcpStatus reloads external endpoint keys changed in manager .env', async () => {
+  const originalCwd = process.cwd();
+  const originalToken = process.env.TEST_EXTERNAL_TOKEN;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-mcp-env-reload-'));
+  await writeFile(
+    path.join(root, '.env'),
+    'TEST_EXTERNAL_TOKEN=first-token\n',
+    'utf8',
+  );
+  await writeFile(
+    path.join(root, 'mcp.endpoints.json'),
+    JSON.stringify({
+      mcpServers: {
+        external: {
+          url: 'http://127.0.0.1:9999/mcp/',
+          headers: {
+            Authorization: 'Bearer ${TEST_EXTERNAL_TOKEN}',
+          },
+        },
+      },
+    }),
+    'utf8',
+  );
+  process.env.TEST_EXTERNAL_TOKEN = 'first-token';
+
+  try {
+    process.chdir(root);
+    await writeFile(
+      path.join(root, '.env'),
+      'TEST_EXTERNAL_TOKEN=second-token\n',
+      'utf8',
+    );
+    const status = buildMcpStatus({ workspaceEnv: {} });
+    assert.deepEqual(status.external.headers, {
+      authorization: 'Bearer second-token',
+    });
+  } finally {
+    process.chdir(originalCwd);
+    if (originalToken === undefined) delete process.env.TEST_EXTERNAL_TOKEN;
+    else process.env.TEST_EXTERNAL_TOKEN = originalToken;
+  }
+});
+
+test('buildMcpStatus does not use workspace env token for wiki MCP without active wikirc accessKey', () => {
+  const status = buildMcpStatus({
+    workspaceEnv: {
+      WIKI_MCP_PORT: '3101',
+      WIKI_MCP_AUTH_TOKEN: 'wiki-token-2',
+      PRODUCTION_MCP_PORT: '3102',
+      PRODUCTION_MCP_AUTH_TOKEN: 'production-token-2',
+    },
+  });
+
+  assert.equal(status.wiki.status, 'missing');
+  assert.equal(status.wiki.token, null);
+  assert.match(status.wiki.detail, /mcp\.accessKey missing/);
+  assert.equal(status.production.token, 'production-token-2');
+});
+
+test('buildMcpStatus uses active wikirc mcp.accessKey for wiki MCP', () => {
+  const status = buildMcpStatus({
+    workspaceEnv: {
+      WIKI_MCP_PORT: '3101',
+      WIKI_MCP_AUTH_TOKEN: 'env-wiki-token',
+    },
+    wikircConfig: {
+      mcp: {
+        accessKey: 'wikirc-wiki-token',
+      },
+    },
+  });
+
+  assert.equal(status.wiki.status, 'configured');
+  assert.equal(status.wiki.token, 'wikirc-wiki-token');
+});
+
 test('callMcpTool injects active configPath for production_start_job', async () => {
   const originalFetch = globalThis.fetch;
   let requestBody = null;
@@ -193,6 +269,32 @@ test('callMcpTool sends configured endpoint headers', async () => {
   }
 });
 
+test('discoverMcpTools downgrades connected endpoint when tool discovery fails', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: false,
+    status: 401,
+    headers: { get: () => null },
+    text: async () => '{"error":"invalid or missing bearer token"}',
+  });
+
+  try {
+    const status = await discoverMcpTools({
+      wiki: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3201/mcp',
+        token: 'token',
+      },
+    });
+
+    assert.equal(status.wiki.status, 'configured');
+    assert.equal(status.wiki.tools.length, 0);
+    assert.match(status.wiki.toolError, /401/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('callMcpTool parses SSE responses after keepalive comments', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = async () => ({