@dotdrelle/wiki-manager 0.12.9 → 0.12.10

package/.env.example

@@ -23,33 +23,28 @@ WORKSPACES_ROOT=/path/to/workspaces
 #
 #   "cme":       { "headers": { "Authorization": "Bearer <CME_MCP_AUTH_TOKEN>" } }
 #   "documents": { "headers": { "Authorization": "Bearer <DOCUMENTS_MCP_AUTH_TOKEN>" } }
-#   "mailer":    { "headers": { "Authorization": "Bearer <MAILER_MCP_AUTH_TOKEN>" } }
 #
 # Leave empty to disable authentication on that agent (not recommended in production).
 
 CME_MCP_AUTH_TOKEN=
 DOCUMENTS_MCP_AUTH_TOKEN=
-MAILER_MCP_AUTH_TOKEN=
 
 # ── Mailer (MailerSend) ────────────────────────────────────────────────────────
 
-MAILERSEND_API_KEY=
-MAILERSEND_FROM_EMAIL=no-reply@example.com
-MAILERSEND_FROM_NAME=Donna
 
 # ── Documents LLM OCR / Mermaid (optional) ─────────────────────────────────────
 
 # All image OCR is delegated to an OpenAI-compatible vision LLM. The default
-# base URL is OpenAI; set DOCUMENT_LLM_API_KEY or OPENAI_API_KEY.
-# DOCUMENT_LLM_BASE_URL=https://api.openai.com/v1
-# DOCUMENT_LLM_MODEL=gpt-5.4-mini
+# 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_API_KEY=
 # DOCUMENT_LLM_TIMEOUT_SECONDS=120
 
 # ── Optional external MCP providers ────────────────────────────────────────────
-
-# Used by mcp.endpoints.json when the Exa MCP endpoint is enabled.
-EXA_MCP_API_KEY=
+# Doctrine: every variable an external MCP endpoint needs (API key, token…)
+# lives HERE and is referenced from mcp.endpoints.json as ${VAR_NAME}.
+# Add your own entries when you declare additional endpoints.
 
 # ── MCP retry policy (optional) ────────────────────────────────────────────────
 
@@ -75,4 +70,3 @@ EXA_MCP_API_KEY=
 
 # CME_MCP_PORT=3336
 # DOCUMENTS_MCP_PORT=3337
-# MAILER_MCP_PORT=3335

package/README.md

@@ -125,7 +125,7 @@ cp .env.example .env
 ```
 
 **3 — Start the shared agents.**
-Start the common toolbox once (Confluence export `cme`, `documents`, `mailer`).
+Start the common toolbox once (Confluence export `cme`, `documents`).
 They run in the background and serve every workspace.
 
 ```bash
@@ -223,7 +223,7 @@ Start the common toolbox once and for all (Confluence, documents, e-mail,
 production). These agents run in the background and serve **all your projects**:
 
 ```bash
-wiki-workspace agents up        # start cme, documents, mailer…
+wiki-workspace agents up        # start cme, documents…
 wiki-workspace agents status    # check they respond
 ```
 
@@ -368,7 +368,7 @@ of you in the browser (create → configure → start the agents → open).
 | [`agent-cme`](https://github.com/dotdrelle/agent-cme) | Global Confluence to Markdown MCP exporter; workspace injected automatically by Donna |
 | [`agent-wiki-production`](https://github.com/dotdrelle/agent-wiki-production) | Workspace-scoped production jobs: ingest, build, export, polish, pipeline |
 | [`agent-wiki-documents`](https://github.com/dotdrelle/agent-wiki-documents) | Document conversion MCP: PDF/Office/HTML/images → Markdown (OCR-capable) |
-| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint |
+| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint (user-side override, not in the default stack) |
 
 ## Workspace Model
 
@@ -414,7 +414,7 @@ keys** (`apiKey` + `baseUrl` that *reach a model*).
 
 | File | Owner | Scope | Holds |
 | --- | --- | --- | --- |
-| `.env` | manager | global | shared secrets: agent MCP tokens, MailerSend, OCR LLM, port overrides |
+| `.env` | manager | global | shared secrets: agent MCP tokens, OCR LLM, port overrides, variables for any user-declared external MCP |
 | `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) |
@@ -462,7 +462,7 @@ cp .env.example .env
 
 The `.env` file is loaded automatically by both `wiki-manager` (Node/Bun process)
 and `wiki-workspace` (Docker Compose). It sets `WORKSPACES_ROOT`, per-agent auth
-tokens, mailer credentials, and optional port overrides.
+tokens and optional port overrides; credentials of optional connectors you enable via the user override.
 
 ### External MCP endpoints
 
@@ -538,16 +538,40 @@ than tracking its own state.
 
 ### Starting external agents
 
-Start CME, documents, and mailer once for all workspaces:
+Start CME and documents once for all workspaces:
 
 ```bash
 wiki-workspace agents up
 ```
 
-This uses the packaged `agents.docker-compose.yml`. `WORKSPACES_ROOT` is resolved
+This uses the packaged `agents.docker-compose.yml` (it lives inside the npm
+package — never edit it, updates overwrite it). On first run, `agents up`
+generates the missing agent auth tokens into your manager `.env` and seeds
+`mcp.endpoints.json` from the packaged example. `WORKSPACES_ROOT` is resolved
 automatically from the manager workspaces directory. Agent state is stored under
 `./.agents-data/` unless `AGENTS_DATA_DIR` is set.
 
+#### Optional agents and user overrides
+
+Anything beyond the default stack (for example the MailerSend agent) is an
+external connector operated at the user's charge — built and published, but
+not part of the delivery. To enable one, create a file named
+`agents.docker-compose.override.yml` **next to your `.env`**:
+
+```bash
+cp "$(npm root -g)/@dotdrelle/wiki-manager/agents.docker-compose.mailer.example.yml" \
+   agents.docker-compose.override.yml
+```
+
+`agents up` includes it automatically when present (standard Docker Compose
+merge: new services are added, same-name keys override the defaults — you can
+also use it to pin a port or a variable of a default agent). The file is
+yours: wiki-manager never generates or overwrites it. Complete the setup by
+adding the connector's variables to your `.env` and its endpoint block to
+your `mcp.endpoints.json` — every variable an external MCP endpoint needs
+lives in the `.env` and is referenced as `${VAR_NAME}` from
+`mcp.endpoints.json`. Detailed steps are in the example file header.
+
 Workspace-native MCP servers (`llm-wiki`, `production`) stay configured through
 each workspace `.env`. External agents are workspace-agnostic: the active
 `/use <workspace>` is injected automatically on every CME and documents tool

package/agents.docker-compose.mailer.example.yml

@@ -0,0 +1,36 @@
+# agents.docker-compose.mailer.example.yml — optional MailerSend agent
+#
+# The mailer agent is NOT part of the default delivery: it is an external
+# MCP connector operated at the user's charge. To enable it:
+#
+#   1. Copy this file NEXT TO YOUR .env (the directory where you run
+#      wiki-manager) under the name:  agents.docker-compose.override.yml
+#      That file is yours — wiki-manager never generates or overwrites it,
+#      and `wiki-workspace agents up` includes it automatically when present.
+#   2. Add to your .env:
+#        MAILER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
+#        MAILERSEND_API_KEY=...
+#        MAILERSEND_FROM_EMAIL=...
+#   3. Declare the endpoint in your mcp.endpoints.json:
+#        "mailer": {
+#          "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
+#          "headers": { "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}" }
+#        }
+#
+services:
+  mailer:
+    image: dotdrelle/agent-mailer-api:latest
+    user: "${UID:-1000}:${GID:-1000}"
+    ports:
+      - "${MAILER_MCP_PORT:-3335}:8080"
+    environment:
+      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
+      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
+      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
+      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
+      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
+      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
+      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
+      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
+      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
+    restart: unless-stopped

package/agents.docker-compose.yml

@@ -1,6 +1,6 @@
 # agents.docker-compose.yml — external agent stack
 #
-# Starts cme, documents, and mailer as workspace-agnostic global services.
+# Starts cme and documents as workspace-agnostic global services.
 # All workspace paths are resolved at tool-call time via the `workspace` param.
 #
 # Required:
@@ -10,18 +10,12 @@
 #   AGENTS_DATA_DIR        — persistent state for stateful agents (default: ./.agents-data)
 #   CME_MCP_PORT           — 3336
 #   DOCUMENTS_MCP_PORT     — 3337
-#   MAILER_MCP_PORT        — 3335
 #   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://api.openai.com/v1
-#   DOCUMENT_LLM_MODEL     — gpt-5.4-mini
+#   DOCUMENT_LLM_BASE_URL  — https://albert.api.etalab.gouv.fr/v1
+#   DOCUMENT_LLM_MODEL     — LightOnOCR-2-1B
 #   DOCUMENT_LLM_API_KEY   — OpenAI/OpenAI-compatible API key for document OCR
 #   DOCUMENT_LLM_TIMEOUT_SECONDS — 120
-#   MAILER_MCP_AUTH_TOKEN  — bearer token for mailer agent (empty = no auth)
-#   MAILERSEND_API_KEY
-#   MAILERSEND_FROM_EMAIL
-#   MAILERSEND_FROM_NAME
-#   MAILERSEND_CA_CERT    — optional CA bundle path inside the container
 #
 # Set these variables in a .env file at the directory where you run wiki-workspace,
 # or export them in your shell before running wiki-workspace agents up.
@@ -83,22 +77,3 @@ services:
       #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped
 
-  mailer:
-    image: dotdrelle/agent-mailer-api:latest
-    user: "${UID:-1000}:${GID:-1000}"
-    ports:
-      - "${MAILER_MCP_PORT:-3335}:8080"
-    environment:
-      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
-      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
-      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
-      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
-      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
-      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
-      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
-      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
-      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
-    # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
-    # volumes:
-    #   - ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
-    restart: unless-stopped

package/docker-compose.yml

@@ -51,10 +51,8 @@ services:
       - PRODUCTION_MCP_PORT
       - CME_MCP_PORT
       - DOCUMENTS_MCP_PORT
-      - MAILER_MCP_PORT
       - CME_MCP_AUTH_TOKEN
       - DOCUMENTS_MCP_AUTH_TOKEN
-      - MAILER_MCP_AUTH_TOKEN
       - WORKSPACE_NAME
       - DOCUMENT_INPUT_DIR=/documents/input
       - DOCUMENT_UPLOADS_DIR=/documents/uploads

package/mcp.endpoints.example.json

@@ -24,12 +24,6 @@
       "headers": {
         "Authorization": "Bearer ${DOCUMENTS_MCP_AUTH_TOKEN}"
       }
-    },
-    "mailer": {
-      "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
-      "headers": {
-        "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}"
-      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -27,6 +27,7 @@
     "wiki-workspace",
     "docker-compose.yml",
     "agents.docker-compose.yml",
+    "agents.docker-compose.mailer.example.yml",
     "mcp.endpoints.example.json",
     ".env.example",
     "tsconfig.json",

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.9",
-  "commit": "286bec2"
+  "version": "0.12.10",
+  "commit": "e256e16"
 }

package/src/core/dockerCompose.test.js

@@ -22,5 +22,7 @@ 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.mailer.user, '${UID:-1000}:${GID:-1000}');
+  // 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

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -51,7 +51,14 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
   const envFile = managerEnvFile();
   const envExample = join(packageRoot, '.env.example');
   if (!existsSync(envFile) && existsSync(envExample)) {
-    copyFileSync(envExample, envFile);
+    // Substitute the documentation placeholders with real paths: a copied
+    // WORKSPACES_ROOT=/path/to/workspaces silently broke agents compose
+    // mounts until manually edited.
+    const workspacesRoot = join(managerStateDir(), 'workspaces');
+    const content = readFileSync(envExample, 'utf8')
+      .replace(/^WORKSPACES_ROOT=.*$/m, `WORKSPACES_ROOT=${workspacesRoot}`)
+      .replace(/^# WIKI_WORKSPACES_DIR=.*$/m, `WIKI_WORKSPACES_DIR=${workspacesRoot}`);
+    writeFileSync(envFile, content);
     created.push('.env');
   }
   if (created.length > 0) {

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.12.9';
+const WIKI_MANAGER_VERSION = '0.12.10';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/shell/tui.tsx

@@ -393,10 +393,13 @@ export async function runOpenTuiShell({
   packageJson: Record<string, unknown>;
   runtime?: any;
 }) {
-  await render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
-    exitOnCtrlC: false,
-    useMouse: true,
-    targetFps: 30,
+  await new Promise<void>((resolve, reject) => {
+    render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
+      exitOnCtrlC: false,
+      useMouse: true,
+      targetFps: 30,
+      onDestroy: resolve,
+    }).catch(reject);
   });
   return {};
 }

package/wiki-workspace

@@ -86,7 +86,7 @@ Commands:
   up <workspace> [--open]           Start workspace stack: wiki + production
   list                              List configured workspaces
 
-  agents up [--pull]                Start all external agents (cme, documents, mailer)
+  agents up [--pull]                Start all external agents (cme, documents)
   agents down                       Stop all external agents
   agents logs [args...]             Follow external agent logs
   agents pull                       Pull latest external agent images
@@ -215,9 +215,15 @@ agents_compose() {
     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"
+    # User-owned override: optional external agents (e.g. mailer) live in a
+    # file the user maintains NEXT TO the .env — never generated, never
+    # overwritten by package updates.
+    local override_args=()
+    local user_override="$MANAGER_STATE_DIR/agents.docker-compose.override.yml"
+    [[ -f "$user_override" ]] && override_args+=(-f "$user_override")
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
+        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${override_args[@]+"${override_args[@]}"} ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
   }
 
   case "$subcommand" in
@@ -245,8 +251,9 @@ agents_compose() {
       printf 'Workspaces root: %s\n' "$workspaces_root"
       printf 'Agents data:     %s\n' "$agents_data_dir"
       [[ -z "$CACERT_PATH" ]] || printf 'CA cert:         %s -> /wiki-manager-ca.pem\n' "$CACERT_PATH"
-      printf 'Agents: cme=:%s  documents=:%s  mailer=:%s\n' \
-        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}" "${MAILER_MCP_PORT:-3335}"
+      printf 'Agents: cme=:%s  documents=:%s\n' \
+        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}"
+      [[ ! -f "$MANAGER_STATE_DIR/agents.docker-compose.override.yml" ]] || printf 'User override: agents.docker-compose.override.yml included\n'
       ;;
     down)
       [[ $# -eq 0 ]] || die "agents down does not take arguments"
@@ -389,12 +396,12 @@ ensure_runtime_node() {
 }
 
 ensure_agent_tokens() {
-  # The external agents (cme, documents, mailer) authenticate with tokens
+  # The external agents (cme, documents) authenticate with tokens
   # from the manager .env — generate any missing one, exactly like the
   # workspace and runtime tokens are generated. Leaving them empty made a
   # fresh install start agents nobody could talk to.
   local key token
-  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN MAILER_MCP_AUTH_TOKEN; do
+  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN; do
     token="$(env_value "$MANAGER_ENV_FILE" "$key" "")"
     if [[ -z "$token" ]]; then
       token="$(generate_token)"