@dotdrelle/wiki-manager 0.15.26 → 0.15.28

package/src/core/agentEvents.test.js

@@ -1,6 +1,43 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { createAgentEvent, dispatchAgentEvent, reduceAgentEvents } from './agentEvents.js';
+import { conversationEventSequences, createAgentEvent, dispatchAgentEvent, reduceAgentEvents } from './agentEvents.js';
+
+function sequenced(events) {
+  return events.map((event, index) => ({ ...event, sequence: index + 1 }));
+}
+
+test('conversationEventSequences maps every entry back to the event that produced it', () => {
+  const events = sequenced([
+    createAgentEvent('user_message', { origin: 'user', payload: { content: 'first question' } }),
+    createAgentEvent('assistant_message', { origin: 'runtime', payload: { content: 'first answer' } }),
+    createAgentEvent('plan_set', { origin: 'tool', payload: { steps: ['do something'] } }),
+    createAgentEvent('user_message', { origin: 'user', payload: { content: 'second question' } }),
+    createAgentEvent('assistant_message', { origin: 'runtime', payload: { content: 'second answer' } }),
+  ]);
+
+  const projection = reduceAgentEvents(events);
+  const sequences = conversationEventSequences(events);
+
+  // One sequence per conversation entry, and the mapping is derived by the same
+  // applyEvent the projection uses, so it cannot drift from what is displayed.
+  assert.equal(sequences.length, projection.conversation.length);
+  assert.deepEqual(sequences, [1, 2, 4, 5]);
+  // Redo on "second question" (index 2) truncates after sequence 4: the plan
+  // event at 3 predates it and survives, the answer at 5 does not.
+  assert.equal(sequences[2], 4);
+});
+
+test('a streamed reply keeps the sequence of the delta that created it', () => {
+  const events = sequenced([
+    createAgentEvent('user_message', { origin: 'user', payload: { content: 'question' } }),
+    createAgentEvent('assistant_delta', { origin: 'runtime', payload: { delta: 'par' } }),
+    createAgentEvent('assistant_delta', { origin: 'runtime', payload: { delta: 'tial' } }),
+  ]);
+
+  // Deltas mutate the last entry in place instead of appending; the entry must
+  // not be re-stamped with every later delta or a redo would truncate too late.
+  assert.deepEqual(conversationEventSequences(events), [1, 2]);
+});
 
 test('reduceAgentEvents: run_started clears stale plan', () => {
   const projection = reduceAgentEvents([

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.15.26",
-  "commit": "1af3dea"
+  "version": "0.15.28",
+  "commit": "11b99e6"
 }

package/src/core/commandFailure.js

@@ -0,0 +1,81 @@
+// Docker and Compose speak to operators in their own vocabulary: exit codes,
+// interpolation warnings, daemon socket paths, the full command line with every
+// -f and --env-file. The ShellUI used to paste that verbatim into the
+// conversation, so a missing image and an unreadable workspace looked identical
+// — a wall of flags. Classify the failure into a stable reason code, hand the
+// reason to Donna, and keep the raw text for the runtime log lane only.
+
+const SIGNATURES = [
+  {
+    reason: 'docker-not-installed',
+    match: (text) => /docker: (command )?not found|'docker' is not recognized/i.test(text),
+  },
+  {
+    reason: 'docker-daemon-unavailable',
+    match: (text) => /cannot connect to the docker daemon|is the docker daemon running|docker daemon is not running/i.test(text),
+  },
+  {
+    reason: 'image-unavailable',
+    match: (text) => /manifest unknown|pull access denied|no such image|image .* not found|repository does not exist/i.test(text),
+  },
+  {
+    reason: 'port-already-in-use',
+    match: (text) => /port is already allocated|address already in use|bind: permission denied/i.test(text),
+  },
+  {
+    reason: 'unknown-service',
+    match: (text) => /no such service|has no service/i.test(text),
+  },
+  {
+    reason: 'permission-denied',
+    match: (text) => /permission denied while trying to connect|got permission denied|operation not permitted/i.test(text),
+  },
+  {
+    reason: 'workspace-path-unavailable',
+    match: (text) => /no such file or directory|is not a directory|invalid mount config/i.test(text),
+  },
+  {
+    reason: 'configuration-variable-missing',
+    // Compose interpolation: only a real failure when the variable is required
+    // (`${VAR:?...}`); the plain "not set" form is a warning we now avoid.
+    match: (text) => /required variable .* is missing|variable is not set/i.test(text),
+  },
+  {
+    reason: 'network-unreachable',
+    match: (text) => /network is unreachable|temporary failure in name resolution|tls handshake timeout|proxyconnect/i.test(text),
+  },
+];
+
+export function rawFailureText(err) {
+  return [err?.stderr, err?.stdout, err?.message]
+    .filter(Boolean)
+    .map(String)
+    .join('\n')
+    .trim();
+}
+
+export function classifyCommandFailure(err) {
+  if (err?.code === 'ENOENT') return 'command-not-found';
+  const text = rawFailureText(err);
+  if (!text) return 'unknown';
+  for (const { reason, match } of SIGNATURES) {
+    if (match(text)) return reason;
+  }
+  return 'unknown';
+}
+
+// The single line worth showing an operator when nothing matched: the last
+// non-empty output line, stripped of the command echo and of absolute paths
+// that only describe this machine's install layout.
+export function failureHint(err, { maxLength = 200 } = {}) {
+  const lines = rawFailureText(err)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => !/^command failed:/i.test(line))
+    .filter((line) => !/^time=".*"\s+level=warning/i.test(line))
+    .filter((line) => !/^docker compose /i.test(line));
+  const last = lines.at(-1) ?? '';
+  const hint = last.replace(/(^|\s)(\/[^\s]+)/g, (match, prefix, path) => `${prefix}${path.split('/').at(-1)}`);
+  return hint.length > maxLength ? `${hint.slice(0, maxLength - 1)}…` : hint;
+}

package/src/core/commandFailure.test.js

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyCommandFailure, failureHint, rawFailureText } from './commandFailure.js';
+import { localizedOperationFailure } from '../commands/slash.js';
+
+const COMPOSE_COMMAND = 'Command failed: docker compose -f /home/p/.nvm/versions/node/v24/lib/node_modules/@dotdrelle/wiki-manager/docker-compose.yml -p wiki-juno --env-file /mnt/c/Users/p/Documents/docker/llm-wiki/.env up -d';
+
+test('common docker failures map to a stable reason code', () => {
+  const cases = [
+    [{ message: `${COMPOSE_COMMAND}\ndocker: command not found` }, 'docker-not-installed'],
+    [{ message: 'Cannot connect to the Docker daemon at unix:///var/run/docker.sock.' }, 'docker-daemon-unavailable'],
+    [{ stderr: 'Error response from daemon: manifest unknown' }, 'image-unavailable'],
+    [{ stderr: 'Bind for 0.0.0.0:3100 failed: port is already allocated' }, 'port-already-in-use'],
+    [{ stderr: 'error while creating mount source path: no such file or directory' }, 'workspace-path-unavailable'],
+    [{ stderr: 'proxyconnect tcp: dial tcp 10.0.0.1:3128: i/o timeout' }, 'network-unreachable'],
+    [{ stderr: 'no such service: all' }, 'unknown-service'],
+    [{ code: 'ENOENT' }, 'command-not-found'],
+    [{ message: `${COMPOSE_COMMAND}\nsomething nobody has seen before` }, 'unknown'],
+  ];
+
+  for (const [error, expected] of cases) {
+    assert.equal(classifyCommandFailure(error), expected, `expected ${expected} for ${rawFailureText(error)}`);
+  }
+});
+
+test('the fallback hint drops the command echo, compose warnings and host paths', () => {
+  const error = {
+    message: [
+      COMPOSE_COMMAND,
+      'time="2026-07-28T11:37:41+02:00" level=warning msg="The \\"CONNECTORS_MCP_PORT\\" variable is not set."',
+      'error while creating mount source path /mnt/c/Users/p/Documents/docker/llm-wiki/workspaces/juno: denied',
+    ].join('\n'),
+  };
+
+  const hint = failureHint(error);
+  assert.doesNotMatch(hint, /Command failed/);
+  assert.doesNotMatch(hint, /level=warning/);
+  assert.doesNotMatch(hint, /--env-file|-f |docker compose/);
+  // Only the basename survives: absolute paths describe this machine's install
+  // layout and mean nothing to the person reading the answer.
+  assert.doesNotMatch(hint, /\/mnt\/c/);
+  assert.match(hint, /juno/);
+});
+
+test('a failed operation reaches Donna as facts, never as docker output', () => {
+  const error = { message: `${COMPOSE_COMMAND}\nCannot connect to the Docker daemon at unix:///var/run/docker.sock.` };
+  const result = localizedOperationFailure({ operation: 'start', target: 'workspace-services', error });
+
+  assert.equal(result.rawOutput, true);
+  assert.deepEqual(JSON.parse(result.output), {
+    operation: 'start',
+    target: 'workspace-services',
+    status: 'failed',
+    reason: 'docker-daemon-unavailable',
+  });
+  assert.doesNotMatch(result.output, /docker compose|--env-file|unix:\/\//);
+  assert.doesNotMatch(result.agentTrigger, /docker compose|--env-file|unix:\/\//);
+  assert.match(result.agentTrigger, /action concrète/);
+});
+
+test('an unclassified failure still carries a sanitized detail for Donna', () => {
+  const error = { message: `${COMPOSE_COMMAND}\nsomething nobody has seen before` };
+  const facts = JSON.parse(localizedOperationFailure({ operation: 'stop', target: 'agents', error }).output);
+
+  assert.equal(facts.reason, 'unknown');
+  assert.equal(facts.detail, 'something nobody has seen before');
+});

package/src/core/compose.js

@@ -5,7 +5,13 @@ import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { cacertEnv, ensureCacertComposeOverride } from './cacert.js';
 import { checkMissingDockerImages } from './dockerImages.js';
-import { managerEnvFile, managerMcpEndpointsFile, readEnvFile, resolveAgentsDataDir } from './env.js';
+import {
+  managerComposeOverrideFile,
+  managerEnvFile,
+  managerMcpEndpointsFile,
+  readEnvFile,
+  resolveAgentsDataDir,
+} from './env.js';
 import { managerRoot } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
@@ -98,6 +104,11 @@ function composeBaseArgs(session) {
   const compose = composeFile();
   const cacertOverride = ensureCacertComposeOverride(compose);
   const args = ['compose', '-f', compose];
+  // Same merge order as wiki-workspace: packaged file, then the user-owned
+  // override, then the generated CA override last so a --cacert change always
+  // wins over a stale hand-written CA path.
+  const userOverride = managerComposeOverrideFile();
+  if (existsSync(userOverride)) args.push('-f', userOverride);
   if (cacertOverride) args.push('-f', cacertOverride);
   args.push('-p', projectName(session));
   const managerEnvPath = managerEnvFile();
@@ -321,12 +332,18 @@ export async function stopService(session, service) {
 
 export async function serviceLogs(session, service, options = {}) {
   if (!service) throw new Error('Usage: /logs <service> [tail]');
+  // `all`, `ui`, `wiki`, `production` are aliases, not Compose services.
+  // start/stop resolved them; logs passed the word straight to Docker, so
+  // `/logs all` died with `no such service: all` — the one spelling the help
+  // text and the completion list both suggest.
+  const aliases = serviceAliases();
+  const targets = aliases[service] ?? [service];
   const tail = String(Number.isFinite(options.tail) ? options.tail : 120);
-  const output = await runCompose(session, ['logs', '--tail', tail, service], {
+  const output = await runCompose(session, ['logs', '--tail', tail, ...targets], {
     timeout: 60_000,
     maxBuffer: 1024 * 1024 * 8,
   });
-  return output || `No logs for ${service}.`;
+  return output || `No logs for ${targets.join(', ')}.`;
 }
 
 export async function runWikiCli(session, args, options = {}) {

package/src/core/composeOverrides.test.js

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import YAML from 'yaml';
+import { COMPOSE_OVERRIDES, ensureManagerScaffold, managerComposeOverrideFile } from './env.js';
+
+function withStateDir(run) {
+  const root = mkdtempSync(join(tmpdir(), 'wiki-manager-overrides-'));
+  const previous = process.env.WIKI_MANAGER_ENV_FILE;
+  process.env.WIKI_MANAGER_ENV_FILE = join(root, '.env');
+  try {
+    return run(root);
+  } finally {
+    if (previous === undefined) delete process.env.WIKI_MANAGER_ENV_FILE;
+    else process.env.WIKI_MANAGER_ENV_FILE = previous;
+  }
+}
+
+test('packaged override templates are valid compose files with an empty services map', async () => {
+  for (const { example } of COMPOSE_OVERRIDES) {
+    const raw = await readFile(new URL(`../../${example}`, import.meta.url), 'utf8');
+    const parsed = YAML.parse(raw);
+    assert.deepEqual(parsed?.services, {}, `${example} must parse to an empty services map`);
+    // A named service here would be merged into every deployment and become a
+    // phantom service as soon as the packaged file drops it.
+    assert.equal(Object.keys(parsed).length, 1, `${example} must declare nothing but services`);
+  }
+});
+
+test('scaffold seeds both compose overrides once and never rewrites them', () => {
+  withStateDir(() => {
+    const created = ensureManagerScaffold();
+    for (const { target } of COMPOSE_OVERRIDES) {
+      assert.ok(created.includes(target), `expected ${target} to be created`);
+    }
+
+    const edited = '# operator edit\nservices:\n  serve:\n    environment:\n      - HTTP_PROXY=http://proxy:3128\n';
+    const workspaceOverride = managerComposeOverrideFile('docker-compose.override.yml');
+    writeFileSync(workspaceOverride, edited, 'utf8');
+
+    const second = ensureManagerScaffold();
+    assert.equal(readFileSync(workspaceOverride, 'utf8'), edited, 'operator edits must survive re-scaffolding');
+    for (const { target } of COMPOSE_OVERRIDES) {
+      assert.ok(!second.includes(target), `${target} must not be recreated`);
+    }
+  });
+});
+
+test('the Node compose path merges the user override before the generated CA override', async () => {
+  const source = await readFile(new URL('./compose.js', import.meta.url), 'utf8');
+  const userOverrideIndex = source.indexOf("args.push('-f', userOverride)");
+  const cacertIndex = source.indexOf("args.push('-f', cacertOverride)");
+  assert.ok(userOverrideIndex > 0, 'composeBaseArgs must include the user override');
+  assert.ok(cacertIndex > userOverrideIndex, 'the CA override must be merged last');
+});
+
+test('wiki-workspace seeds the overrides once and merges them in both stacks', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /ensure_compose_override\(\) \{/);
+  // Seed-once contract: the opposite of cacert_compose_args, which always
+  // replaces its generated file.
+  assert.match(script, /\[\[ -f "\$target" \]\] && return 0/);
+  assert.match(script, /ensure_compose_override 'agents\.docker-compose\.override\.example\.yml' 'agents\.docker-compose\.override\.yml'/);
+  assert.match(script, /ensure_compose_override 'docker-compose\.override\.example\.yml' 'docker-compose\.override\.yml'/);
+  assert.match(script, /local user_override="\$MANAGER_STATE_DIR\/docker-compose\.override\.yml"/);
+  assert.match(
+    script,
+    /-f "\$ROOT_DIR\/docker-compose\.yml" \$\{override_args\[@\]\+"\$\{override_args\[@\]\}"\} \$\{cacert_args\[@\]\+"\$\{cacert_args\[@\]\}"\}/,
+  );
+});

package/src/core/dockerCompose.test.js

@@ -3,6 +3,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import YAML from 'yaml';
 import { configuredAgentImages } from './wikiSetup.js';
+import { REQUIRED_ENV_KEYS } from './env.js';
 
 test('workspace compose does not start a per-workspace agent runtime', async () => {
   const raw = await readFile(new URL('../../docker-compose.yml', import.meta.url), 'utf8');
@@ -18,6 +19,73 @@ test('workspace compose does not start a per-workspace agent runtime', async ()
   );
 });
 
+test('no compose service relies on a bare environment passthrough', async () => {
+  // `- VAR` makes Compose print `The "VAR" variable is not set. Defaulting to a
+  // blank string.` for every key the operator left as a commented placeholder —
+  // CONNECTORS_MCP_PORT once connectors were enabled. That warning reached the
+  // ShellUI looking like a failure. Every entry must carry its own default.
+  for (const file of ['../../docker-compose.yml', '../../agents.docker-compose.yml']) {
+    const compose = YAML.parse(await readFile(new URL(file, import.meta.url), 'utf8'));
+    for (const [name, service] of Object.entries(compose.services ?? {})) {
+      for (const entry of service.environment ?? []) {
+        assert.match(String(entry), /=/, `${file} ${name}: "${entry}" must be written as VAR=\${VAR:-default}`);
+      }
+    }
+  }
+
+  const workspace = YAML.parse(await readFile(new URL('../../docker-compose.yml', import.meta.url), 'utf8'));
+  assert.ok(workspace.services.serve.environment.includes('CONNECTORS_MCP_PORT=${CONNECTORS_MCP_PORT:-3338}'));
+});
+
+test('required .env keys agree with the compose defaults they mirror', async () => {
+  // Three files carry the same values: .env.example (what the operator reads),
+  // the compose default (what the container actually receives) and
+  // REQUIRED_ENV_KEYS (what a migration writes). A silent divergence is exactly
+  // the bug this pins: the documents agent called an endpoint the .env said
+  // nothing about.
+  const envExample = await readFile(new URL('../../.env.example', import.meta.url), 'utf8');
+  const composeFiles = await Promise.all(
+    ['../../agents.docker-compose.yml', '../../docker-compose.yml']
+      .map((file) => readFile(new URL(file, import.meta.url), 'utf8')),
+  );
+  const compose = composeFiles.join('\n');
+
+  for (const [key, value] of Object.entries(REQUIRED_ENV_KEYS)) {
+    assert.match(
+      envExample,
+      new RegExp(`^${key}=${value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'),
+      `.env.example must ship ${key} active with the same value`,
+    );
+    const composeDefault = compose.match(new RegExp(`\\$\\{${key}:-([^}]*)\\}`));
+    if (!composeDefault) continue;
+    assert.equal(composeDefault[1], value, `${key}: compose default and REQUIRED_ENV_KEYS disagree`);
+  }
+});
+
+test('no compose default points a deployment at an LLM provider it did not choose', async () => {
+  // A hardcoded `${DOCUMENT_LLM_BASE_URL:-https://…}` sent every install to a
+  // third-party endpoint the operator never saw, since the key ships commented.
+  // The .env is the only source; an empty value also neutralises the image's
+  // own ENV fallback.
+  const agents = await readFile(new URL('../../agents.docker-compose.yml', import.meta.url), 'utf8');
+  const envExample = await readFile(new URL('../../.env.example', import.meta.url), 'utf8');
+
+  for (const key of ['DOCUMENT_LLM_BASE_URL', 'DOCUMENT_LLM_MODEL', 'DOCUMENT_LLM_API_KEY']) {
+    assert.match(agents, new RegExp(`- ${key}=\\$\\{${key}:-\\}`), `${key} must have an empty compose default`);
+    assert.doesNotMatch(envExample, new RegExp(`^${key}=.+$`, 'm'), `${key} must stay commented in .env.example`);
+  }
+});
+
+test('log reading resolves service aliases like start and stop do', async () => {
+  // `/logs all` used to reach Docker verbatim and fail with `no such service:
+  // all` — while `all` is exactly what /help and the completion list suggest.
+  const source = await readFile(new URL('./compose.js', import.meta.url), 'utf8');
+  const logs = source.slice(source.indexOf('export async function serviceLogs'));
+  assert.match(logs, /const aliases = serviceAliases\(\);/);
+  assert.match(logs, /const targets = aliases\[service\] \?\? \[service\];/);
+  assert.match(logs, /\['logs', '--tail', tail, \.\.\.targets\]/);
+});
+
 test('agent compose services run as the host uid and gid', async () => {
   const workspaceRaw = await readFile(new URL('../../docker-compose.yml', import.meta.url), 'utf8');
   const workspaceCompose = YAML.parse(workspaceRaw);
@@ -31,8 +99,7 @@ test('agent compose services run as the host uid and gid', async () => {
   assert.deepEqual(agentsCompose.services.connectors.profiles, ['connectors']);
   assert.equal(agentsCompose.services.connectors.environment.includes('GOOGLE_OAUTH_CALLBACK_URL=${GOOGLE_OAUTH_CALLBACK_URL:-}'), true);
   assert.equal(agentsCompose.services.connectors.volumes.includes('${AGENTS_DATA_DIR:-./.agents-data}/connectors:/data'), true);
-  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);
+  // OCR endpoint, model and key carry no default — see the dedicated test.
   assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_API_KEY=${DOCUMENT_LLM_API_KEY:-}'), true);
 });
 

package/src/core/env.js

@@ -39,6 +39,51 @@ export function managerMcpEndpointsFile() {
   return join(managerStateDir(), 'mcp.endpoints.json');
 }
 
+// User-owned compose overrides, one per stack, next to the manager .env.
+// Deliberately NOT under .wiki/runtime: everything there is generated state
+// that every compose command rewrites (see cacert.js). These two are seeded
+// once and never touched again, so an operator has a supported place to fix a
+// deployment — proxy passthrough, extra mounts, optional agents — instead of
+// editing a generated file and losing the change on the next command.
+export const COMPOSE_OVERRIDES = [
+  { example: 'docker-compose.override.example.yml', target: 'docker-compose.override.yml' },
+  { example: 'agents.docker-compose.override.example.yml', target: 'agents.docker-compose.override.yml' },
+];
+
+export function managerComposeOverrideFile(target = 'docker-compose.override.yml') {
+  return join(managerStateDir(), target);
+}
+
+// Keys the deployment cannot work without. `.env.example` ships them active,
+// but the scaffold only copies that file on first run, so installs predating a
+// new required key never receive it — the same additive-migration gap the
+// endpoints file had.
+export const REQUIRED_ENV_KEYS = {
+  // `serve` runs in Docker and calls the host runtime through
+  // host.docker.internal. A runtime bound to 127.0.0.1 refuses that connection,
+  // and the workspace UI silently shows no runtime. Exposing the port always
+  // generates a token (see resolveRuntimeAuthToken), so this is not an
+  // unauthenticated bind.
+  WIKI_MANAGER_RUNTIME_HOST: '0.0.0.0',
+};
+
+function commentedAssignment(line, key) {
+  return new RegExp(`^\\s*#+\\s*${key}=`).test(line);
+}
+
+// Mirrors set_env_value in wiki-workspace: reuse the commented placeholder so
+// the value lands under the comment block that documents it, and never
+// overwrite an active assignment — that one is the operator's own choice.
+export function writeEnvValueIfMissing(filePath, key, value) {
+  const lines = readFileSync(filePath, 'utf8').split(/\r?\n/);
+  if (lines.some((line) => line.startsWith(`${key}=`))) return false;
+  const placeholder = lines.findIndex((line) => commentedAssignment(line, key));
+  if (placeholder >= 0) lines[placeholder] = `${key}=${value}`;
+  else lines.push(`${key}=${value}`);
+  writeFileSync(filePath, lines.join('\n'));
+  return true;
+}
+
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 // First-run scaffolding: a fresh install directory has neither
@@ -104,6 +149,20 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
       .replace(/^# WIKI_WORKSPACES_DIR=.*$/m, `WIKI_WORKSPACES_DIR=${workspacesRoot}`);
     writeFileSync(envFile, content);
     created.push('.env');
+  } else if (existsSync(envFile)) {
+    for (const [key, value] of Object.entries(REQUIRED_ENV_KEYS)) {
+      if (writeEnvValueIfMissing(envFile, key, value)) created.push(`.env ${key}=${value}`);
+    }
+  }
+  // Seed once, never rewrite: an existing file is the operator's, whatever it
+  // contains. Losing a hand-written proxy block on a package update is exactly
+  // the failure mode this scaffold exists to prevent.
+  for (const { example, target } of COMPOSE_OVERRIDES) {
+    const examplePath = join(packageRoot, example);
+    const targetPath = managerComposeOverrideFile(target);
+    if (!existsSync(examplePath) || existsSync(targetPath)) continue;
+    copyFileSync(examplePath, targetPath);
+    created.push(target);
   }
   if (created.length > 0) {
     log(`configuration initialized successfully in ${managerStateDir()} — created ${created.join(' and ')} from packaged defaults. Optional credentials can be added later for external services.`);

package/src/core/env.test.js

@@ -30,11 +30,43 @@ test('scaffold copies the packaged examples into a fresh directory', () => {
     assert.ok(endpoints.mcpServers);
     assert.ok(endpoints.chatAccess);
     const env = readFileSync(join(dir, '.env'), 'utf8');
-    assert.match(env, /^# WIKI_MANAGER_RUNTIME_HOST=0\.0\.0\.0$/m);
+    // Active, not commented: serve runs in Docker and reaches the runtime
+    // through host.docker.internal, which a loopback bind refuses.
+    assert.match(env, /^WIKI_MANAGER_RUNTIME_HOST=0\.0\.0\.0$/m);
     assert.match(env, /^# WIKI_MANAGER_RUNTIME_PORT=7788$/m);
   });
 });
 
+test('an install predating the required runtime host receives it on its placeholder', () => {
+  withTempManagerDir((dir) => {
+    const envFile = join(dir, '.env');
+    writeFileSync(envFile, [
+      'WORKSPACES_ROOT=/srv/workspaces',
+      '# WIKI_MANAGER_RUNTIME_PORT=7788',
+      '# WIKI_MANAGER_RUNTIME_HOST=0.0.0.0',
+      '',
+    ].join('\n'));
+
+    const created = ensureManagerScaffold();
+    assert.ok(created.some((item) => item.includes('WIKI_MANAGER_RUNTIME_HOST')));
+    const env = readFileSync(envFile, 'utf8');
+    assert.match(env, /^WIKI_MANAGER_RUNTIME_HOST=0\.0\.0\.0$/m);
+    assert.doesNotMatch(env, /^#\s*WIKI_MANAGER_RUNTIME_HOST=/m);
+    assert.match(env, /^WORKSPACES_ROOT=\/srv\/workspaces$/m);
+  });
+});
+
+test('an operator who deliberately kept the loopback bind is never overruled', () => {
+  withTempManagerDir((dir) => {
+    const envFile = join(dir, '.env');
+    writeFileSync(envFile, 'WIKI_MANAGER_RUNTIME_HOST=127.0.0.1\n');
+
+    const created = ensureManagerScaffold();
+    assert.ok(!created.some((item) => item.includes('WIKI_MANAGER_RUNTIME_HOST')));
+    assert.match(readFileSync(envFile, 'utf8'), /^WIKI_MANAGER_RUNTIME_HOST=127\.0\.0\.1$/m);
+  });
+});
+
 test('scaffold merges missing top-level keys into an existing endpoints file', () => {
   withTempManagerDir((dir) => {
     const endpointsFile = join(dir, 'mcp.endpoints.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.15.26';
+const WIKI_MANAGER_VERSION = '0.15.28';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/setEnvValue.test.js

@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const scriptPath = fileURLToPath(new URL('../../wiki-workspace', import.meta.url));
+
+// Extracts the pure env-file helpers from wiki-workspace and exercises them for
+// real: these functions rewrite the operator's .env in place, so a source-grep
+// assertion would not catch an off-by-one in the comment matching.
+function bashHelpers() {
+  const script = readFileSync(scriptPath, 'utf8');
+  return ['commented_assignment', 'set_env_value', 'env_value']
+    .map((name) => {
+      const start = script.indexOf(`\n${name}() {`);
+      assert.ok(start >= 0, `missing helper: ${name}`);
+      const end = script.indexOf('\n}\n', start);
+      assert.ok(end > start, `unterminated helper: ${name}`);
+      return script.slice(start, end + 3);
+    })
+    .join('\n');
+}
+
+function runHelpers(envContent, commands) {
+  const dir = mkdtempSync(join(tmpdir(), 'wiki-manager-setenv-'));
+  const envFile = join(dir, '.env');
+  const runner = join(dir, 'run.sh');
+  writeFileSync(envFile, envContent, 'utf8');
+  writeFileSync(runner, `set -euo pipefail\n${bashHelpers()}\nf="${envFile}"\n${commands}\n`, 'utf8');
+  execFileSync('bash', [runner], { encoding: 'utf8' });
+  return readFileSync(envFile, 'utf8');
+}
+
+test('a generated key reuses its commented placeholder instead of being appended', () => {
+  const result = runHelpers(
+    '# Generated automatically when missing.\n# OAUTH_STATE_SECRET=\n# OAUTH_START_TOKEN=\n',
+    'set_env_value "$f" OAUTH_STATE_SECRET aaa\n',
+  );
+
+  assert.match(result, /^OAUTH_STATE_SECRET=aaa$/m);
+  // The value must land on the placeholder's own line, under the comment block
+  // that documents it — not orphaned at the end of the file.
+  assert.doesNotMatch(result, /^#\s*OAUTH_STATE_SECRET=/m);
+  assert.ok(
+    result.indexOf('OAUTH_STATE_SECRET=aaa') < result.indexOf('# OAUTH_START_TOKEN='),
+    'the placeholder line must be replaced in place',
+  );
+  // A sibling placeholder nobody asked for stays commented.
+  assert.match(result, /^# OAUTH_START_TOKEN=$/m);
+});
+
+test('placeholder matching tolerates the spacing variants shipped in .env.example', () => {
+  const result = runHelpers(
+    '#GOOGLE_OAUTH_CALLBACK_URL=http://old\n##  WIKI_MANAGER_RUNTIME_TOKEN=\n',
+    'set_env_value "$f" GOOGLE_OAUTH_CALLBACK_URL http://new\nset_env_value "$f" WIKI_MANAGER_RUNTIME_TOKEN ccc\n',
+  );
+
+  assert.equal(result, 'GOOGLE_OAUTH_CALLBACK_URL=http://new\nWIKI_MANAGER_RUNTIME_TOKEN=ccc\n');
+});
+
+test('an active assignment wins and never gains a second uncommented twin', () => {
+  const result = runHelpers(
+    '# A prose comment mentioning NO_PROXY without assigning it\nNO_PROXY=keepme\n# NO_PROXY=should-stay-commented\n',
+    'set_env_value "$f" NO_PROXY localhost\n',
+  );
+
+  assert.match(result, /^NO_PROXY=localhost$/m);
+  assert.match(result, /^# NO_PROXY=should-stay-commented$/m);
+  assert.match(result, /^# A prose comment mentioning NO_PROXY without assigning it$/m);
+  assert.equal(result.match(/^NO_PROXY=/gm).length, 1);
+});
+
+test('a key absent from the file is still appended', () => {
+  const result = runHelpers('EXISTING=1\n', 'set_env_value "$f" BRAND_NEW_KEY zzz\n');
+
+  assert.match(result, /^EXISTING=1$/m);
+  assert.match(result, /^BRAND_NEW_KEY=zzz$/m);
+});
+
+test('commented placeholders stay unset for readers', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'wiki-manager-setenv-read-'));
+  const envFile = join(dir, '.env');
+  const runner = join(dir, 'run.sh');
+  writeFileSync(envFile, '# OAUTH_START_TOKEN=\nCME_MCP_AUTH_TOKEN=set\n', 'utf8');
+  writeFileSync(
+    runner,
+    `set -euo pipefail\n${bashHelpers()}\nenv_value "${envFile}" OAUTH_START_TOKEN "<unset>"\nenv_value "${envFile}" CME_MCP_AUTH_TOKEN "<unset>"\n`,
+    'utf8',
+  );
+  const output = execFileSync('bash', [runner], { encoding: 'utf8' });
+
+  assert.equal(output, '<unset>\nset\n');
+});