@dotdrelle/wiki-manager 0.6.27 → 0.6.31

package/README.md

@@ -141,16 +141,6 @@ external agents (CME & co.) live in [docs/usage.md](https://raw.githubuserconten
 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](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/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/bin/wiki-manager

@@ -1,6 +1,44 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+CACERT_PATH="${WIKI_MANAGER_CACERT_PATH:-}"
+ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cacert)
+      [[ $# -ge 2 ]] || { printf 'Error: --cacert requires a file path\n' >&2; exit 2; }
+      CACERT_PATH="$2"
+      shift 2
+      ;;
+    *)
+      ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+absolute_file_path() {
+  local value="$1"
+  local dir base
+  if [[ "$value" = /* ]]; then
+    printf '%s\n' "$value"
+    return
+  fi
+  dir="$(dirname "$value")"
+  base="$(basename "$value")"
+  printf '%s/%s\n' "$(cd "$dir" && pwd)" "$base"
+}
+
+if [[ -n "$CACERT_PATH" ]]; then
+  CACERT_PATH="$(absolute_file_path "$CACERT_PATH")"
+  [[ -f "$CACERT_PATH" ]] || { printf 'Error: --cacert file not found: %s\n' "$CACERT_PATH" >&2; exit 2; }
+  export WIKI_MANAGER_CACERT_PATH="$CACERT_PATH"
+  export NODE_EXTRA_CA_CERTS="$CACERT_PATH"
+  export SSL_CERT_FILE="$CACERT_PATH"
+  export REQUESTS_CA_BUNDLE="$CACERT_PATH"
+  export CURL_CA_BUNDLE="$CACERT_PATH"
+fi
+
 BUN_BIN="$(command -v bun 2>/dev/null || true)"
 if [[ -z "$BUN_BIN" && -n "${BUN_INSTALL:-}" && -x "$BUN_INSTALL/bin/bun" ]]; then
   BUN_BIN="$BUN_INSTALL/bin/bun"
@@ -27,4 +65,4 @@ while [[ -L "$SCRIPT_SOURCE" ]]; do
 done
 BIN_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
 
-exec "$BUN_BIN" "$BIN_DIR/wiki-manager.js" "$@"
+exec "$BUN_BIN" "$BIN_DIR/wiki-manager.js" "${ARGS[@]}"

package/bin/wiki-manager.js

@@ -1,6 +1,59 @@
 #!/usr/bin/env bun
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 
-import '@opentui/solid/preload';
+function valueAfter(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return undefined;
+  return argv[index + 1];
+}
+
+function stripOptionWithValue(argv, flag) {
+  const result = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === flag) {
+      index += 1;
+      continue;
+    }
+    result.push(argv[index]);
+  }
+  return result;
+}
+
+function cacertEnvVars(cacert) {
+  return {
+    WIKI_MANAGER_CACERT_PATH: cacert,
+    NODE_EXTRA_CA_CERTS: cacert,
+    SSL_CERT_FILE: cacert,
+    REQUESTS_CA_BUNDLE: cacert,
+    CURL_CA_BUNDLE: cacert,
+  };
+}
+
+function resolveCacert(argv) {
+  const cacert = valueAfter(argv, '--cacert');
+  if (!cacert) return { argv, cacert: null };
+  const absolute = resolve(cacert);
+  if (!existsSync(absolute)) {
+    throw new Error(`--cacert file not found: ${absolute}`);
+  }
+  return {
+    argv: stripOptionWithValue(argv, '--cacert'),
+    cacert: absolute,
+  };
+}
+
+async function reexecWithCacertIfNeeded(argv, cacert) {
+  if (!cacert || process.env.WIKI_MANAGER_CACERT_BOOTSTRAPPED === '1') return;
+  const { spawnSync } = await import('node:child_process');
+  const env = { ...process.env, WIKI_MANAGER_CACERT_BOOTSTRAPPED: '1', ...cacertEnvVars(cacert) };
+  const result = spawnSync(process.execPath, [process.argv[1], ...argv], {
+    env,
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
 
 function formatStartupError(err) {
   const message = err instanceof Error ? err.message : String(err);
@@ -21,7 +74,13 @@ function formatStartupError(err) {
 }
 
 async function main() {
-  const argv = process.argv.slice(2);
+  const parsed = resolveCacert(process.argv.slice(2));
+  const argv = parsed.argv;
+  await reexecWithCacertIfNeeded(argv, parsed.cacert);
+  // Fallback for already-bootstrapped direct invocations; the shell wrapper
+  // exports these before Bun starts.
+  if (parsed.cacert) Object.assign(process.env, cacertEnvVars(parsed.cacert));
+  await import('@opentui/solid/preload');
   const interactive = process.stdout.isTTY && process.stdin.isTTY && !argv.includes('--headless') && !argv.includes('--once') && !argv.includes('--version') && !argv.includes('-v') && !argv.includes('--help') && !argv.includes('-h');
   if (interactive) process.stdout.write('Starting wiki-manager…\r');
   const { runCli } = await import('../src/cli/wiki-manager.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.6.27",
+  "version": "0.6.31",
   "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

@@ -562,6 +562,7 @@ Usage:
 Options:
   -v, --version        Print version
   -h, --help           Print help
+  --cacert <path>      Trust a local CA; Docker must be able to read this host path
   --once <prompt>      Run one agent turn and exit
   --headless           Run a workspace task non-interactively
   --workspace <name>   Workspace for --headless
@@ -658,7 +659,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 +707,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/cacert.js

@@ -0,0 +1,66 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import YAML from 'yaml';
+import { managerRuntimeDir } from './env.js';
+
+export const CACERT_CONTAINER_PATH = '/wiki-manager-ca.pem';
+export const CACERT_ENV_KEYS = [
+  'NODE_EXTRA_CA_CERTS',
+  'SSL_CERT_FILE',
+  'REQUESTS_CA_BUNDLE',
+  'CURL_CA_BUNDLE',
+];
+
+export function activeCacertPath() {
+  const value = process.env.WIKI_MANAGER_CACERT_PATH;
+  return value ? resolve(value) : null;
+}
+
+export function cacertEnv(path = activeCacertPath(), targetPath = path) {
+  if (!path) return {};
+  return Object.fromEntries(CACERT_ENV_KEYS.map((key) => [key, targetPath]));
+}
+
+function parseComposeServices(composeFilePath) {
+  const parsed = YAML.parse(readFileSync(composeFilePath, 'utf8')) ?? {};
+  return Object.keys(parsed.services ?? {}).filter(Boolean);
+}
+
+function composeOverrideContent(cacertPath, services) {
+  const serviceEntries = Object.fromEntries(
+    services.map((service) => [
+      service,
+      {
+        volumes: [`${cacertPath}:${CACERT_CONTAINER_PATH}:ro`],
+        environment: cacertEnv(cacertPath, CACERT_CONTAINER_PATH),
+      },
+    ]),
+  );
+  const doc = {
+    services: serviceEntries,
+  };
+  return [
+    '# Generated by wiki-manager. Safe to delete.',
+    '# Rewritten when --cacert is used with a Docker 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 (!existsSync(cacertPath)) {
+    throw new Error(`--cacert file not found: ${cacertPath}`);
+  }
+  const services = parseComposeServices(composeFilePath);
+  if (services.length === 0) return null;
+  const runtimeDir = managerRuntimeDir();
+  mkdirSync(runtimeDir, { recursive: true });
+  const overridePath = join(runtimeDir, fileName);
+  writeFileSync(overridePath, composeOverrideContent(cacertPath, services), 'utf8');
+  return (_cacertOverrideCache = overridePath);
+}

package/src/core/compose.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import YAML from 'yaml';
+import { cacertEnv, ensureCacertComposeOverride } from './cacert.js';
 import { managerEnvFile, readEnvFile } from './env.js';
 import { managerRoot } from './workspaces.js';
 
@@ -93,14 +94,14 @@ function projectName(session) {
 }
 
 function composeBaseArgs(session) {
-  const args = ['compose', '-f', composeFile(), '-p', projectName(session)];
+  const compose = composeFile();
+  const cacertOverride = ensureCacertComposeOverride(compose);
+  const args = ['compose', '-f', compose];
+  if (cacertOverride) args.push('-f', cacertOverride);
+  args.push('-p', projectName(session));
   const managerEnvPath = managerEnvFile();
-  if (existsSync(managerEnvPath)) {
-    args.push('--env-file', managerEnvPath);
-  }
-  if (session.workspaceEnvFile && existsSync(session.workspaceEnvFile)) {
-    args.push('--env-file', session.workspaceEnvFile);
-  }
+  if (existsSync(managerEnvPath)) args.push('--env-file', managerEnvPath);
+  if (session.workspaceEnvFile && existsSync(session.workspaceEnvFile)) args.push('--env-file', session.workspaceEnvFile);
   return args;
 }
 
@@ -109,6 +110,7 @@ function composeEnv(session) {
     ...process.env,
     ...readManagerEnv(),
     ...(session.workspaceEnv ?? {}),
+    ...cacertEnv(),
     WORKSPACE_NAME: session.workspace,
     WIKI_WORKSPACE_PATH: session.workspacePath,
   };

package/src/core/env.js

@@ -1,18 +1,28 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 export function userManagerDir() {
   return process.cwd();
 }
 
+export function managerStateDir() {
+  return process.env.WIKI_MANAGER_ENV_FILE
+    ? dirname(resolve(process.env.WIKI_MANAGER_ENV_FILE))
+    : userManagerDir();
+}
+
+export function managerRuntimeDir() {
+  return join(managerStateDir(), '.wiki-manager');
+}
+
 export function managerEnvFile() {
   return process.env.WIKI_MANAGER_ENV_FILE
     ? resolve(process.env.WIKI_MANAGER_ENV_FILE)
-    : join(userManagerDir(), '.env');
+    : join(managerStateDir(), '.env');
 }
 
 export function managerMcpEndpointsFile() {
-  return join(userManagerDir(), 'mcp.endpoints.json');
+  return join(managerStateDir(), 'mcp.endpoints.json');
 }
 
 function parseEnvValue(value) {

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.27' },
+            clientInfo: { name: 'wiki-manager', version: '0.6.31' },
           },
         }),
       });
@@ -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 () => ({

package/wiki-workspace

@@ -16,10 +16,66 @@ DEFAULT_MANAGER_DIR="$PWD"
 WORKSPACES_DIR="${WIKI_WORKSPACES_DIR:-$DEFAULT_MANAGER_DIR/workspaces}"
 MANAGER_ENV_FILE="${WIKI_MANAGER_ENV_FILE:-$DEFAULT_MANAGER_DIR/.env}"
 MANAGER_ENDPOINTS_FILE="${WIKI_MANAGER_ENDPOINTS_FILE:-$DEFAULT_MANAGER_DIR/mcp.endpoints.json}"
+MANAGER_STATE_DIR="$(cd "$(dirname "$MANAGER_ENV_FILE")" && pwd)"
+MANAGER_RUNTIME_DIR="$MANAGER_STATE_DIR/.wiki-manager"
+CACERT_PATH="${WIKI_MANAGER_CACERT_PATH:-}"
+
+normalize_path() {
+  local value="$1"
+  if command -v wslpath >/dev/null 2>&1 && [[ "$value" =~ ^[A-Za-z]:[\\/] ]]; then
+    wslpath -u "$value"
+    return
+  fi
+  printf '%s\n' "$value"
+}
+
+absolute_path() {
+  local value="$1"
+  local base="${2:-$ROOT_DIR}"
+  value="$(normalize_path "$value")"
+  if [[ "$value" = /* ]]; then
+    printf '%s\n' "$value"
+  else
+    printf '%s\n' "$base/$value"
+  fi
+}
+
+parse_global_options() {
+  local parsed=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --cacert)
+        [[ $# -ge 2 ]] || { printf 'Error: --cacert requires a file path\n' >&2; exit 2; }
+        CACERT_PATH="$2"
+        shift 2
+        ;;
+      *)
+        parsed+=("$1")
+        shift
+        ;;
+    esac
+  done
+  if [[ -n "$CACERT_PATH" ]]; then
+    CACERT_PATH="$(absolute_path "$CACERT_PATH" "$PWD")"
+    [[ -f "$CACERT_PATH" ]] || { printf 'Error: --cacert file not found: %s\n' "$CACERT_PATH" >&2; exit 2; }
+    export WIKI_MANAGER_CACERT_PATH="$CACERT_PATH"
+    export NODE_EXTRA_CA_CERTS="$CACERT_PATH"
+    export SSL_CERT_FILE="$CACERT_PATH"
+    export REQUESTS_CA_BUNDLE="$CACERT_PATH"
+    export CURL_CA_BUNDLE="$CACERT_PATH"
+  fi
+  set -- "${parsed[@]}"
+  PARSED_ARGS=("$@")
+}
+
+PARSED_ARGS=()
+parse_global_options "$@"
+set -- "${PARSED_ARGS[@]}"
 
 usage() {
   cat <<'EOF'
 Usage:
+  wiki-workspace [--cacert <path>] <command> ...
   wiki-workspace config <workspace> [path]
   wiki-workspace up <workspace>
   wiki-workspace wiki <workspace> <command> [args...]
@@ -50,6 +106,7 @@ Commands:
 Configuration:
   workspaces/<workspace>/.env
   Override directory: WIKI_WORKSPACES_DIR=/path/to/dir
+  Local CA: --cacert /absolute/path/to/ca.pem (Docker must be able to read this host path)
 EOF
 }
 
@@ -58,26 +115,6 @@ die() {
   exit 1
 }
 
-normalize_path() {
-  local value="$1"
-  if command -v wslpath >/dev/null 2>&1 && [[ "$value" =~ ^[A-Za-z]:[\\/] ]]; then
-    wslpath -u "$value"
-    return
-  fi
-  printf '%s\n' "$value"
-}
-
-absolute_path() {
-  local value="$1"
-  local base="${2:-$ROOT_DIR}"
-  value="$(normalize_path "$value")"
-  if [[ "$value" = /* ]]; then
-    printf '%s\n' "$value"
-  else
-    printf '%s\n' "$base/$value"
-  fi
-}
-
 workspace_env_file() {
   local workspace="$1"
   printf '%s/%s/.env\n' "$WORKSPACES_DIR" "$workspace"
@@ -169,9 +206,12 @@ agents_compose() {
   [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
 
   _agents_dc() {
+    local cacert_args=()
+    WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
+      read_lines_into_array cacert_args cacert_compose_args "$agents_compose_file" "agents.cacert.compose.yml"
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-        "${compose_env_args[@]}" -f "$agents_compose_file" -p wiki-agents "$@"
+        "${compose_env_args[@]}" -f "$agents_compose_file" "${cacert_args[@]}" -p wiki-agents "$@"
   }
 
   case "$subcommand" in
@@ -444,13 +484,19 @@ compose_for_workspace() {
   local compose_env_args=()
   [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
   compose_env_args+=(--env-file "$workspace_env")
+  local cacert_args=()
+  WIKI_WORKSPACE_PATH="$ws_path" \
+  WIKI_SERVE_PORT="$serve_port" \
+  WIKI_MCP_PORT="$mcp_port" \
+  PRODUCTION_MCP_PORT="$prod_port" \
+    read_lines_into_array cacert_args cacert_compose_args "$ROOT_DIR/docker-compose.yml" "cacert.compose.yml"
 
   WIKI_WORKSPACE_PATH="$ws_path" \
   WIKI_SERVE_PORT="$serve_port" \
   WIKI_MCP_PORT="$mcp_port" \
   PRODUCTION_MCP_PORT="$prod_port" \
   docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-    "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" -p "$project" "$@"
+    "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" "${cacert_args[@]}" -p "$project" "$@"
 }
 
 logs_args() {
@@ -474,6 +520,48 @@ read_lines_into_array() {
   done < <("$@")
 }
 
+cacert_compose_args() {
+  local compose_file="$1"
+  local override_name="$2"
+  [[ -n "$CACERT_PATH" ]] || return 0
+  command -v node >/dev/null 2>&1 || die "--cacert requires node to generate Docker Compose overrides"
+
+  local services
+  services="$(
+    ROOT_DIR="$ROOT_DIR" _WIKI_COMPOSE_FILE_PATH="$compose_file" node <<'NODE'
+const { createRequire } = require('node:module');
+const fs = require('node:fs');
+const requireFromPackage = createRequire(`${process.env.ROOT_DIR}/package.json`);
+const YAML = requireFromPackage('yaml');
+const parsed = YAML.parse(fs.readFileSync(process.env._WIKI_COMPOSE_FILE_PATH, 'utf8')) ?? {};
+for (const service of Object.keys(parsed.services ?? {})) {
+  console.log(service);
+}
+NODE
+  )"
+  [[ -n "$services" ]] || return 0
+
+  mkdir -p "$MANAGER_RUNTIME_DIR"
+  local override_path="$MANAGER_RUNTIME_DIR/$override_name"
+  {
+    printf '# Generated by wiki-manager. Safe to delete.\n'
+    printf '# Rewritten when --cacert is used with a Docker Compose command.\n'
+    printf 'services:\n'
+    while IFS= read -r service || [[ -n "$service" ]]; do
+      [[ -n "$service" ]] || continue
+      printf '  %s:\n' "$service"
+      printf '    volumes:\n'
+      printf '      - %s:/wiki-manager-ca.pem:ro\n' "$CACERT_PATH"
+      printf '    environment:\n'
+      printf '      NODE_EXTRA_CA_CERTS: /wiki-manager-ca.pem\n'
+      printf '      SSL_CERT_FILE: /wiki-manager-ca.pem\n'
+      printf '      REQUESTS_CA_BUNDLE: /wiki-manager-ca.pem\n'
+      printf '      CURL_CA_BUNDLE: /wiki-manager-ca.pem\n'
+    done <<< "$services"
+  } > "$override_path"
+  printf '%s\n' -f "$override_path"
+}
+
 run_wiki() {
   local workspace="$1"
   shift
@@ -623,12 +711,17 @@ config_workspace() {
   local compose_env_args=()
   [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
   compose_env_args+=(--env-file "$env_file")
+  local cacert_args=()
+  WIKI_WORKSPACE_PATH="$target_path" \
+  WIKI_SERVE_PORT="$serve_port" \
+  WIKI_MCP_PORT="$mcp_port" \
+    read_lines_into_array cacert_args cacert_compose_args "$ROOT_DIR/docker-compose.yml" "cacert.compose.yml"
 
   WIKI_WORKSPACE_PATH="$target_path" \
   WIKI_SERVE_PORT="$serve_port" \
   WIKI_MCP_PORT="$mcp_port" \
     docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-      "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" run --rm wiki init
+      "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" "${cacert_args[@]}" run --rm wiki init
 
   printf 'Workspace ready: %s\n' "$target_path"
   printf 'Start with:      wiki-workspace up %s\n' "$workspace"