collabmd 0.1.49 → 0.1.51

package/src/domain/excalidraw-room-codec.js

@@ -11,6 +11,7 @@ export const EXCALIDRAW_META_KEY = 'excalidraw-meta';
 export const EXCALIDRAW_ROOM_SCHEMA_VERSION = 1;
 export const EXCALIDRAW_ROOM_TEXT_KEY = 'codemirror';
 export const EXCALIDRAW_SCHEMA_VERSION_KEY = 'schemaVersion';
+export const EXCALIDRAW_REPLACE_GENERATION_KEY = 'replaceGeneration';
 
 function createEmptyScene() {
   return {
@@ -222,6 +223,15 @@ export function isExcalidrawRoomDocStructured(ydoc) {
   return Number(meta.get(EXCALIDRAW_SCHEMA_VERSION_KEY)) === EXCALIDRAW_ROOM_SCHEMA_VERSION;
 }
 
+export function readExcalidrawReplaceGeneration(ydoc) {
+  if (!ydoc) {
+    return 0;
+  }
+
+  const value = Number(ydoc.getMap(EXCALIDRAW_META_KEY).get(EXCALIDRAW_REPLACE_GENERATION_KEY));
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
 export function ensureExcalidrawRoomSchema(ydoc) {
   const meta = ydoc.getMap(EXCALIDRAW_META_KEY);
   if (Number(meta.get(EXCALIDRAW_SCHEMA_VERSION_KEY)) !== EXCALIDRAW_ROOM_SCHEMA_VERSION) {
@@ -295,7 +305,7 @@ export function replaceExcalidrawRoomScene(ydoc, rawScene, {
   }
 
   const scene = normalizeScene(rawScene);
-  ensureExcalidrawRoomSchema(ydoc);
+  const meta = ensureExcalidrawRoomSchema(ydoc);
 
   const elementsMap = ydoc.getMap(EXCALIDRAW_ELEMENTS_KEY);
   const filesMap = ydoc.getMap(EXCALIDRAW_FILES_KEY);
@@ -321,6 +331,7 @@ export function replaceExcalidrawRoomScene(ydoc, rawScene, {
   const nextAppState = normalizeAppState(scene.appState);
   appStateMap.set('gridSize', nextAppState.gridSize);
   appStateMap.set('viewBackgroundColor', nextAppState.viewBackgroundColor);
+  meta.set(EXCALIDRAW_REPLACE_GENERATION_KEY, readExcalidrawReplaceGeneration(ydoc) + 1);
 
   return scene;
 }

package/src/domain/literal-text-search.js

@@ -0,0 +1,13 @@
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
+
+function isWordCharacterAt(value, index) {
+  if (index < 0 || index >= value.length) return false;
+  let start = index;
+  const codeUnit = value.charCodeAt(index);
+  if (index > 0 && codeUnit >= 0xDC00 && codeUnit <= 0xDFFF) start -= 1;
+  return WORD_CHARACTER.test(String.fromCodePoint(value.codePointAt(start)));
+}
+
+export function isWholeWordMatch(value, start, end) {
+  return !isWordCharacterAt(value, start - 1) && !isWordCharacterAt(value, end);
+}

package/src/server/application/agent-content-service.js

@@ -10,14 +10,19 @@ import { listRenderableDiagrams, resolveRenderableDiagram } from '../../domain/d
 import { createEditableContentRevision } from '../../domain/editable-content-revision.js';
 import { normalizeEditableText } from '../../domain/editable-text.js';
 import { applyExactTextChanges, resolveExactTextChanges } from '../../domain/exact-text-edits.js';
-import { applyAgentExcalidrawEdits, createAgentExcalidrawScene } from '../../domain/excalidraw-agent-scene.js';
+import {
+  applyAgentExcalidrawEditsWithSummary,
+  createAgentExcalidrawScene,
+} from '../../domain/excalidraw-agent-scene.js';
 import { inspectAgentExcalidrawScene, renderAgentExcalidrawSvg } from '../../domain/excalidraw-agent-verification.js';
-import { getVaultFileKind } from '../../domain/file-kind.js';
+import { getVaultFileKind, isBaseFilePath } from '../../domain/file-kind.js';
+import { isWholeWordMatch } from '../../domain/literal-text-search.js';
 import { createWikiTargetIndex } from '../../domain/wiki-link-resolver.js';
 import {
   classifyPublicVideoEmbed,
   isPublicVideoEmbedCandidate,
 } from '../../domain/video-embed.js';
+import { isPlainObject, parseBaseSource } from '../domain/bases/base-definition.js';
 import {
   collectMarkdownImageSources,
   collectMarkdownReferences,
@@ -32,6 +37,35 @@ const MAX_REPLACEMENTS = 20;
 const MAX_REPLACEMENT_CHARACTERS = 50_000;
 const EMBEDDABLE_KINDS = new Set(['base', 'drawio', 'excalidraw', 'image', 'mermaid', 'plantuml']);
 
+function assertValidAgentBaseContent(path, content) {
+  if (!isBaseFilePath(path)) return;
+  try {
+    const raw = parseBaseSource(content);
+    if (raw != null && !isPlainObject(raw)) {
+      throw new Error('Base source must be a YAML object');
+    }
+  } catch (error) {
+    throw createAgentContentError('AGENT_INVALID_BASE', error.message || 'Base source is invalid', 400);
+  }
+}
+
+function toAgentBaseQueryResult(path, { columns, rows, view }, limit) {
+  return {
+    columns: columns.map(({ id, label }) => ({ id, label })),
+    path,
+    rows: rows.slice(0, limit).map((row) => ({
+      cells: Object.fromEntries(columns.map(({ id }) => [id, String(row.cells[id]?.text ?? '')])),
+      path: row.path,
+    })),
+    totalRows: rows.length,
+    truncated: rows.length > limit,
+    view: {
+      name: view.name,
+      type: view.type,
+    },
+  };
+}
+
 function createAgentContentError(code, message, statusCode = 400) {
   const error = new Error(message);
   error.code = code;
@@ -101,7 +135,7 @@ function createInlineExcalidrawVerification(scene, options, { deferRender = fals
   return verification;
 }
 
-function searchLiveText(content, query, maxSnippets = 5) {
+function searchLiveText(content, query, maxSnippets = 5, wholeWord = false) {
   const normalizedQuery = query.toLocaleLowerCase();
   const snippets = [];
   let matchCount = 0;
@@ -109,17 +143,19 @@ function searchLiveText(content, query, maxSnippets = 5) {
     const normalizedLine = lineText.toLocaleLowerCase();
     let start = normalizedLine.indexOf(normalizedQuery);
     while (start >= 0) {
-      matchCount += 1;
-      if (snippets.length < maxSnippets) {
-        const snippetStart = Math.max(0, start - 90);
-        const snippetEnd = Math.min(lineText.length, start + query.length + 90);
-        snippets.push({
-          column: start + 1,
-          line: lineIndex + 1,
-          matchEnd: start - snippetStart + query.length + (snippetStart > 0 ? 3 : 0),
-          matchStart: start - snippetStart + (snippetStart > 0 ? 3 : 0),
-          text: `${snippetStart > 0 ? '...' : ''}${lineText.slice(snippetStart, snippetEnd)}${snippetEnd < lineText.length ? '...' : ''}`,
-        });
+      if (!wholeWord || isWholeWordMatch(normalizedLine, start, start + normalizedQuery.length)) {
+        matchCount += 1;
+        if (snippets.length < maxSnippets) {
+          const snippetStart = Math.max(0, start - 90);
+          const snippetEnd = Math.min(lineText.length, start + query.length + 90);
+          snippets.push({
+            column: start + 1,
+            line: lineIndex + 1,
+            matchEnd: start - snippetStart + query.length + (snippetStart > 0 ? 3 : 0),
+            matchStart: start - snippetStart + (snippetStart > 0 ? 3 : 0),
+            text: `${snippetStart > 0 ? '...' : ''}${lineText.slice(snippetStart, snippetEnd)}${snippetEnd < lineText.length ? '...' : ''}`,
+          });
+        }
       }
       start = normalizedLine.indexOf(normalizedQuery, start + Math.max(query.length, 1));
     }
@@ -130,6 +166,7 @@ function searchLiveText(content, query, maxSnippets = 5) {
 export class AgentContentService {
   constructor({
     backlinkIndex = null,
+    baseQueryService = null,
     plantUmlRenderer = null,
     roomRegistry,
     searchService,
@@ -137,6 +174,7 @@ export class AgentContentService {
     workspaceMutationCoordinator,
   }) {
     this.backlinkIndex = backlinkIndex;
+    this.baseQueryService = baseQueryService;
     this.plantUmlRenderer = plantUmlRenderer;
     this.roomRegistry = roomRegistry;
     this.searchService = searchService;
@@ -214,31 +252,13 @@ export class AgentContentService {
     };
   }
 
-  async renderExcalidraw(actor, {
-    format = 'png',
-    padding = 32,
-    path,
-    scale = 1,
-  } = {}) {
-    const current = await this.readExcalidrawScene(actor, path);
-    const result = {
-      elementCount: current.scene.elements.filter((element) => !element.isDeleted).length,
-      format,
-      path: current.path,
-      revision: current.revision,
-      scene: current.scene,
-    };
-    if (actor.origin !== 'webmcp') {
-      Object.assign(result, renderAgentExcalidrawSvg(current.scene, { padding, scale }));
-    }
-    return result;
-  }
 
   async verifyExcalidraw(actor, {
     format = 'png',
     inspectOcclusion = true,
     padding = 32,
     path,
+    render = true,
     scale = 1,
   } = {}) {
     const current = await this.readExcalidrawScene(actor, path);
@@ -250,52 +270,45 @@ export class AgentContentService {
       elementCount: inspection.elementCount,
       format,
       inspection,
+      layout: inspection.layout,
       path: current.path,
       revision: current.revision,
-      scene: current.scene,
+      valid: inspection.valid,
     };
+    if (!render) return result;
+
+    result.scene = current.scene;
     if (actor.origin !== 'webmcp') {
       Object.assign(result, renderAgentExcalidrawSvg(current.scene, { padding, scale }));
     }
     return result;
   }
 
-  listDocuments(actor, { cursor = '', kinds = [], limit = 100, prefix = '' } = {}) {
+  listWorkspaceEntries(actor, {
+    cursor = '',
+    kinds = [],
+    limit = 100,
+    prefix = '',
+    pathQuery = '',
+  } = {}) {
     requireScope(actor, 'vault:read');
     const normalizedPrefix = normalizeWorkspacePath(prefix);
+    const normalizedPathQuery = String(pathQuery).trim().toLocaleLowerCase();
     const kindFilter = new Set(Array.isArray(kinds) ? kinds : []);
     const state = this.workspaceMutationCoordinator?.workspaceState;
-    const documents = Array.from(state?.entries?.values?.() ?? [])
-      .filter((entry) => entry.nodeType !== 'directory' && isAgentReadablePath(entry.path))
-      .filter((entry) => !normalizedPrefix || entry.path === normalizedPrefix || entry.path.startsWith(`${normalizedPrefix}/`))
-      .filter((entry) => kindFilter.size === 0 || kindFilter.has(getVaultFileKind(entry.path)))
-      .sort((left, right) => compareWorkspacePaths(left.path, right.path));
-    const start = cursor ? Math.max(0, documents.findIndex((entry) => entry.path === cursor) + 1) : 0;
-    const pageSize = clampInteger(limit, 100, 1, 200);
-    const page = documents.slice(start, start + pageSize).map((entry) => {
-      const metadata = state?.metadata?.get?.(entry.path);
-      return {
-        kind: getVaultFileKind(entry.path),
-        mtimeMs: Number(metadata?.mtimeMs ?? entry.mtimeMs ?? 0),
-        path: entry.path,
-        size: Number(metadata?.size ?? 0),
-      };
-    });
-    const truncated = start + page.length < documents.length;
-    return {
-      documents: page,
-      nextCursor: truncated ? page.at(-1)?.path ?? null : null,
-      truncated,
-    };
-  }
-  listWorkspaceEntries(actor, { cursor = '', limit = 100, prefix = '' } = {}) {
-    requireScope(actor, 'vault:read');
-    const normalizedPrefix = normalizeWorkspacePath(prefix);
-    const state = this.workspaceMutationCoordinator?.workspaceState;
     const entries = Array.from(state?.entries?.values?.() ?? [])
       .filter((entry) => !normalizedPrefix || entry.path === normalizedPrefix || entry.path.startsWith(`${normalizedPrefix}/`))
+      .filter((entry) => kindFilter.size === 0 || kindFilter.has(getVaultFileKind(entry.path)))
+      .filter((entry) => !normalizedPathQuery || entry.path.toLocaleLowerCase().includes(normalizedPathQuery))
       .sort((left, right) => compareWorkspacePaths(left.path, right.path));
-    const start = cursor ? Math.max(0, entries.findIndex((entry) => entry.path === cursor) + 1) : 0;
+    let start = 0;
+    if (cursor) {
+      const cursorIndex = entries.findIndex((entry) => entry.path === cursor);
+      if (cursorIndex < 0) {
+        throw createAgentContentError('AGENT_CURSOR_INVALID', 'Pagination cursor is no longer valid', 400);
+      }
+      start = cursorIndex + 1;
+    }
     const pageSize = clampInteger(limit, 100, 1, 200);
     const page = entries.slice(start, start + pageSize).map((entry) => {
       const isDirectory = entry.nodeType === 'directory';
@@ -322,21 +335,46 @@ export class AgentContentService {
   }
 
 
-  async searchVault(actor, { limit = 50, query = '', signal = null } = {}) {
+  async searchVault(actor, {
+    kinds = [],
+    limit = 50,
+    maxSnippetsPerFile = 5,
+    prefix = '',
+    query = '',
+    wholeWord = false,
+    signal = null,
+  } = {}) {
     requireScope(actor, 'vault:read');
     const normalizedQuery = String(query ?? '').trim().slice(0, 500);
-    const result = await this.searchService.search({ limit, query: normalizedQuery, signal });
+    const normalizedPrefix = normalizeWorkspacePath(prefix);
+    const kindFilter = new Set(Array.isArray(kinds) ? kinds : []);
+    const snippetLimit = clampInteger(maxSnippetsPerFile, 5, 1, 10);
+    const result = await this.searchService.search({
+      kinds: [...kindFilter],
+      limit,
+      maxSnippetsPerFile: snippetLimit,
+      prefix: normalizedPrefix,
+      query: normalizedQuery,
+      wholeWord,
+      signal,
+    });
     if (normalizedQuery.length < 2) return result;
 
     const liveFiles = [];
     for (const [path, room] of this.roomRegistry?.getRooms?.() ?? []) {
-      if (!isAgentReadablePath(path) || !room.isHydrated?.()) continue;
+      const kind = getVaultFileKind(path);
+      if (
+        !isAgentReadablePath(path)
+        || !room.isHydrated?.()
+        || (normalizedPrefix && path !== normalizedPrefix && !path.startsWith(`${normalizedPrefix}/`))
+        || (kindFilter.size > 0 && !kindFilter.has(kind))
+      ) continue;
       const content = room.readEditableContent?.();
       if (content === null || content === undefined) continue;
       if (content.length > MAX_AGENT_READ_SOURCE_CHARACTERS) continue;
-      const live = searchLiveText(content, normalizedQuery);
+      const live = searchLiveText(content, normalizedQuery, snippetLimit, wholeWord);
       if (live.matchCount > 0) {
-        liveFiles.push({ file: path, kind: getVaultFileKind(path), ...live });
+        liveFiles.push({ file: path, kind, ...live });
       }
     }
     if (liveFiles.length === 0) return result;
@@ -474,6 +512,32 @@ export class AgentContentService {
     };
   }
 
+  async queryBase(actor, { limit = 50, path, search = '', view = '' } = {}) {
+    requireScope(actor, 'vault:read');
+    const normalizedPath = normalizeWorkspacePath(path);
+    if (!isBaseFilePath(normalizedPath)) {
+      throw createAgentContentError('AGENT_UNSUPPORTED_DOCUMENT', 'Base queries require a .base path', 400);
+    }
+    const content = await this.readCurrentContent(normalizedPath);
+    if (!this.baseQueryService?.query) {
+      throw createAgentContentError('AGENT_BASE_QUERY_UNAVAILABLE', 'Bases query service is unavailable', 503);
+    }
+    const pageSize = clampInteger(limit, 50, 1, 200);
+    try {
+      const result = await this.baseQueryService.query({
+        basePath: normalizedPath,
+        search,
+        source: content,
+        sourcePath: normalizedPath,
+        view,
+      });
+      return toAgentBaseQueryResult(normalizedPath, result, pageSize);
+    } catch (error) {
+      if (error?.code?.startsWith('AGENT_')) throw error;
+      throw createAgentContentError('AGENT_BASE_QUERY_FAILED', error.message || 'Failed to query base', 400);
+    }
+  }
+
   async renderDiagram(actor, { format = 'png', path, startLine } = {}) {
     requireScope(actor, 'vault:read');
     const normalizedPath = normalizeWorkspacePath(path);
@@ -552,15 +616,14 @@ export class AgentContentService {
         error.code = error.code?.startsWith('EXACT_EDIT_') ? 'AGENT_REPLACEMENT_MISMATCH' : error.code;
         throw error;
       }
+      const nextContent = applyExactTextChanges(content, changes);
+      assertValidAgentBaseContent(normalizedPath, nextContent);
       const room = this.roomRegistry?.get?.(normalizedPath);
-      let nextContent;
       if (room) {
         room.applyExactTextChanges(changes, {
           origin: createCollaborationOrigin(actor),
         });
-        nextContent = room.readEditableContent();
       } else {
-        nextContent = applyExactTextChanges(content, changes);
         const result = await this.workspaceMutationCoordinator.writeEditableContent({
           content: nextContent,
           origin: getMutationOrigin(actor),
@@ -573,7 +636,7 @@ export class AgentContentService {
       return {
         path: normalizedPath,
         replacementCount: changes.length,
-        revision: await createEditableContentRevision(nextContent),
+        revision: await createEditableContentRevision(room ? room.readEditableContent() : nextContent),
       };
     });
   }
@@ -644,6 +707,7 @@ export class AgentContentService {
   async editExcalidraw(actor, {
     create = [],
     delete: remove = [],
+    normalizeTextPlacement,
     path,
     reorder = [],
     replace = [],
@@ -666,11 +730,12 @@ export class AgentContentService {
       if (revision !== await createEditableContentRevision(content)) {
         throw createAgentContentError('AGENT_REVISION_CONFLICT', 'Document changed; read it again before editing', 409);
       }
-      let scene;
+      let edit;
       try {
-        scene = applyAgentExcalidrawEdits(JSON.parse(content), {
+        edit = applyAgentExcalidrawEditsWithSummary(JSON.parse(content), {
           create,
           delete: remove,
+          normalizeTextPlacement,
           reorder,
           replace,
           update,
@@ -685,6 +750,7 @@ export class AgentContentService {
         }
         throw error;
       }
+      const { reflowed, scene } = edit;
       const room = this.roomRegistry?.get?.(normalizedPath);
       let nextContent;
       if (room) {
@@ -714,6 +780,7 @@ export class AgentContentService {
         elementCount: storedScene.elements.filter((element) => !element.isDeleted).length,
         path: normalizedPath,
         reordered: reorder.length,
+        reflowed,
         replaced: replace.length,
         revision: await createEditableContentRevision(nextContent),
         translated: translate?.ids?.length ?? 0,
@@ -738,6 +805,7 @@ export class AgentContentService {
     if (normalizedContent.length > MAX_DOCUMENT_CHARACTERS) {
       throw createAgentContentError('AGENT_DOCUMENT_TOO_LARGE', 'Document is too large for agent creation', 413);
     }
+    assertValidAgentBaseContent(normalizedPath, normalizedContent);
     return this.runForPath(normalizedPath, async () => {
       const result = await this.workspaceMutationCoordinator.createFile({
         content: normalizedContent,

package/src/server/config/env.js

@@ -1,4 +1,4 @@
-import { resolve } from 'path';
+import { basename, isAbsolute, relative, resolve } from 'path';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'url';
 
@@ -199,6 +199,94 @@ export function resolveCliVaultDir(positionals = [], env = process.env) {
   return resolve(positionals[0] || env.COLLABMD_VAULT_DIR || '.');
 }
 
+const VAULT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const VAULT_ID_HINT = 'Use letters, numbers, ".", "_", or "-" starting with a letter or number.';
+
+export function parseVaultList(rawValue) {
+  return normalizeCsvList(rawValue).map((entry) => {
+    const separatorIndex = entry.indexOf('=');
+    const hasName = separatorIndex > 0;
+    const rawDir = (hasName ? entry.slice(separatorIndex + 1) : entry).trim();
+    if (!rawDir) {
+      throw new Error(`Vault entry "${entry}" is missing a directory path.`);
+    }
+    const dir = resolve(rawDir);
+    const id = (hasName ? entry.slice(0, separatorIndex).trim() : basename(dir));
+    if (!VAULT_ID_PATTERN.test(id)) {
+      throw new Error(`Invalid vault id "${id}". ${VAULT_ID_HINT}`);
+    }
+    return { id, dir };
+  });
+}
+
+export function resolveConfiguredVaults(overrides = {}, env = process.env) {
+  if (Array.isArray(overrides.vaults)) {
+    return overrides.vaults.map(({ id, dir, repoUrl }) => {
+      if (!VAULT_ID_PATTERN.test(String(id ?? ''))) {
+        throw new Error(`Invalid vault id "${id}". ${VAULT_ID_HINT}`);
+      }
+      return { id, dir: resolve(dir), repoUrl: normalizeOptionalString(repoUrl) };
+    });
+  }
+  // ponytail: explicit directory (CLI positional) wins over the operator list
+  if (overrides.vaultDir) {
+    const dir = resolve(overrides.vaultDir);
+    return [{ id: basename(dir), dir }];
+  }
+  const rawList = normalizeOptionalString(env.COLLABMD_VAULTS);
+  if (!rawList) {
+    const dir = resolveConfiguredVaultDir(overrides, env);
+    return [{ id: basename(dir), dir }];
+  }
+  const vaults = parseVaultList(rawList);
+  const seenIds = new Set();
+  for (const vault of vaults) {
+    if (seenIds.has(vault.id)) {
+      throw new Error(`Duplicate vault id "${vault.id}" in COLLABMD_VAULTS.`);
+    }
+    seenIds.add(vault.id);
+  }
+  for (let i = 0; i < vaults.length; i += 1) {
+    for (let j = i + 1; j < vaults.length; j += 1) {
+      const between = relative(vaults[i].dir, vaults[j].dir);
+      if (between === '' || (!between.startsWith('..') && !isAbsolute(between))) {
+        throw new Error(`Vaults "${vaults[i].id}" and "${vaults[j].id}" overlap. Vault directories must not nest.`);
+      }
+    }
+  }
+  return vaults;
+}
+
+export function mangleVaultIdForEnv(vaultId) {
+  return String(vaultId ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
+// ponytail: explicit repoUrl wins, then COLLABMD_GIT_REPO_URL_<ID>, then the shared URL for the primary
+export function resolveVaultRepoUrls(vaultDefs = [], overrides = {}, env = process.env) {
+  const globalRepoUrl = normalizeOptionalString(overrides.remote?.repoUrl ?? overrides.git?.remote?.repoUrl ?? env.COLLABMD_GIT_REPO_URL);
+  const bySuffix = new Map();
+  for (const def of vaultDefs) {
+    const suffix = mangleVaultIdForEnv(def.id);
+    if (!bySuffix.has(suffix)) {
+      bySuffix.set(suffix, []);
+    }
+    bySuffix.get(suffix).push(def.id);
+  }
+  return vaultDefs.map((def, index) => {
+    if (def.repoUrl) {
+      return def;
+    }
+    const suffix = mangleVaultIdForEnv(def.id);
+    const varName = `COLLABMD_GIT_REPO_URL_${suffix}`;
+    const perVaultUrl = normalizeOptionalString(env[varName]);
+    if (perVaultUrl && bySuffix.get(suffix).length > 1) {
+      throw new Error(`Ambiguous git remote: vaults ${bySuffix.get(suffix).map((id) => `"${id}"`).join(' and ')} share ${varName}.`);
+    }
+    return { ...def, repoUrl: perVaultUrl || (index === 0 ? globalRepoUrl : '') };
+  });
+}
+
 function getDefaultHost(nodeEnv) {
   return nodeEnv === 'production' ? '0.0.0.0' : '127.0.0.1';
 }
@@ -208,7 +296,7 @@ function resolveOptionalPath(filePath) {
   return normalized ? resolve(normalized) : '';
 }
 
-function loadGitConfig(overrides = {}) {
+function loadGitConfig(overrides = {}, { vaultRepoUrls = [] } = {}) {
   const remoteOverrides = overrides.remote ?? {};
   const identityOverrides = overrides.identity ?? {};
   const enabled = overrides.enabled ?? (process.env.COLLABMD_GIT_ENABLED !== 'false');
@@ -240,7 +328,7 @@ function loadGitConfig(overrides = {}) {
     remoteOverrides.sshKnownHostsFile
     ?? process.env.COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE,
   );
-  const remoteEnabled = repoUrl.length > 0;
+  const remoteEnabled = repoUrl.length > 0 || vaultRepoUrls.some((entry) => String(entry ?? '').length > 0);
 
   if (remoteEnabled && !sshPrivateKeyFile && !sshPrivateKeyBase64) {
     throw new Error(
@@ -452,7 +540,9 @@ function resolvePublicDir(nodeEnv) {
 
 export function loadConfig(overrides = {}) {
   const nodeEnv = process.env.NODE_ENV || 'development';
-  const vaultDir = resolveConfiguredVaultDir(overrides);
+  const vaults = resolveVaultRepoUrls(resolveConfiguredVaults(overrides), overrides);
+  // ponytail: vaultDir stays the primary vault; other vaults resolve through the registry
+  const vaultDir = overrides.vaultDir || vaults[0].dir;
   const basePath = normalizeAppBasePath(process.env.BASE_PATH || '');
   const publicDir = resolvePublicDir(nodeEnv);
   const authOverrides = overrides.auth ?? {};
@@ -469,7 +559,7 @@ export function loadConfig(overrides = {}) {
   const oidc = authStrategy === AUTH_STRATEGY_OIDC
     ? loadOidcConfig(authOverrides.oidc, { basePath })
     : null;
-  const git = loadGitConfig(overrides.git);
+  const git = loadGitConfig(overrides.git, { vaultRepoUrls: vaults.map((vault) => vault.repoUrl) });
   const hosted = loadHostedConfig(overrides.hosted, { authStrategy, vaultDir });
   const agentAccess = loadAgentAccessConfig(overrides.agentAccess, {
     basePath,
@@ -531,6 +621,7 @@ export function loadConfig(overrides = {}) {
     plantumlServerUrl: process.env.PLANTUML_SERVER_URL || 'https://www.plantuml.com/plantuml',
     publicDir,
     vaultDir,
+    vaults,
     publicWsBaseUrl: process.env.PUBLIC_WS_BASE_URL || '',
     testWsRoomHydrateDelayMs: parsePositiveInt(process.env.TEST_WS_ROOM_HYDRATE_DELAY_MS, 0),
     wikiLinkAutoCreate: process.env.COLLABMD_WIKI_LINK_AUTO_CREATE !== 'false',