@bevel-software/platform-core-backend 0.20.0 → 0.21.0

package/src/modules/tool-manuals/__tests__/tool-manuals.invalid.test.ts

@@ -11,6 +11,7 @@ import { setLogger } from '../../../shared/logging.js';
 import type { ILogger } from '../../../shared/logger.contract.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * ONE BAD `.tool` COSTS ONE TOOL.
@@ -92,7 +93,14 @@ describe('a malformed `.tool` is isolated, named, and forgotten the moment it is
   } as unknown as IAccessControl;
 
   const svc = (access: IAccessControl = allowAll) =>
-    new ToolManualService(workspaceService, access, KB_DIR, disk, new KbPluginSource(disk), () => clock);
+    new ToolManualService(
+      workspaceService,
+      access,
+      testKbContext({ kbDirName: KB_DIR }),
+      disk,
+      new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })),
+      () => clock,
+    );
 
   /**
    * The refused half of the catalog. There is no way to ask for it alone: both
@@ -512,9 +520,9 @@ describe('a malformed `.tool` is isolated, named, and forgotten the moment it is
     const service = new ToolManualService(
       workspaceService,
       countingAccess,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       countingDisk,
-      new KbPluginSource(countingDisk),
+      new KbPluginSource(countingDisk, testKbContext({ kbDirName: KB_DIR })),
       () => clock,
     );
 
@@ -546,9 +554,9 @@ describe('a malformed `.tool` is isolated, named, and forgotten the moment it is
     const service = new ToolManualService(
       workspaceService,
       allowAll,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       countingDisk,
-      new KbPluginSource(countingDisk),
+      new KbPluginSource(countingDisk, testKbContext({ kbDirName: KB_DIR })),
       () => clock,
     );
 

package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts

@@ -12,6 +12,7 @@ import { ToolManualService, type McpAuthDiscoveryPort } from '../tool-manuals.se
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
 const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
@@ -62,7 +63,7 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
   });
 
   function svcWith(discovery: McpAuthDiscoveryPort) {
-    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk));
+    const svc = new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
     svc.setMcpAuthDiscovery(discovery);
     return svc;
   }

package/src/modules/tool-manuals/__tests__/tool-manuals.restart.test.ts

@@ -20,6 +20,7 @@ import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.j
 import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { registerToolManualsTools } from '../tool-manuals.tools.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * A server restart must not cost a tool or a sign-in. Everything a registered
@@ -188,7 +189,13 @@ describe('external tools and their sign-ins across a restart', () => {
         ),
     } as unknown as WorkspaceService;
     const vault = vaultOver(rows);
-    const catalog = new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk));
+    const catalog = new ToolManualService(
+      workspaceService,
+      allowAll,
+      testKbContext({ kbDirName: KB_DIR }),
+      disk,
+      new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })),
+    );
     catalog.setMcpAuthDiscovery(new McpOAuthDiscoveryService({ secretsVault: vault, redirectUri: REDIRECT_URI, fetchFn }));
 
     const internalToken = new InternalTokenService({ secret: 'test-secret' });
@@ -212,6 +219,7 @@ describe('external tools and their sign-ins across a restart', () => {
     registerToolManualsTools(new ToolRegistry(), router, createToolAuthMiddleware(apiKeys, internalToken), toolHandler, catalog, {
       accessControl: allowAll,
       variableStatus: vault,
+      kb: testKbContext({ kbDirName: KB_DIR }),
     });
     app.use('/api', router);
     const server = await new Promise<HttpServer>((r) => {

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -12,6 +12,7 @@ import { ToolManualService } from '../tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
 const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
@@ -69,7 +70,7 @@ describe('ToolManualService', () => {
       new Map(paths.map((p) => [p, !p.includes('weather')])),
   } as unknown as IAccessControl;
 
-  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, KB_DIR, disk, new KbPluginSource(disk));
+  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'tools-'));
@@ -760,7 +761,7 @@ describe('ToolManualService.listDeclaredOnlyOnBranch', () => {
     await rm(root, { recursive: true, force: true });
   });
 
-  const svc = () => new ToolManualService(workspaceService, readGate, KB_DIR, disk, new KbPluginSource(disk));
+  const svc = () => new ToolManualService(workspaceService, readGate, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
 
   test('names only the readable declarations the default branch does not serve', async () => {
     expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT)).toEqual([

package/src/modules/tool-manuals/__tests__/tool-manuals.tools.test.ts

@@ -8,6 +8,7 @@ import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { registerToolManualsTools } from '../tool-manuals.tools.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `list_tool_setup` MUST respect the same access controls as every other tool
@@ -114,6 +115,7 @@ async function start(): Promise<string> {
   registerToolManualsTools(registry, router, toolAuth, toolHandler, toolManualService, {
     accessControl,
     variableStatus: { statusFor },
+    kb: testKbContext(),
   });
   app.use('/api', router);
 

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -2,7 +2,7 @@ import {
   HEXIS_EXTENSION_NS,
   PLUGIN_MCP_FILE,
   PLUGIN_MANIFEST_FILE,
-  PLUGINS_DIR,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 import type { ToolManualDescriptor, ToolVariable } from './tool-manuals.contract.js';
 import { logger } from '../../shared/logging.js';
@@ -317,12 +317,14 @@ export function descriptorsFromMcpJson(
   pluginFolder: string,
   mcpJsonText: string,
   pluginJsonText: string | null,
+  layout: KbLayout,
 ): ToolManualDescriptor[] {
+  const { pluginsDir } = layout;
   let mcp: unknown;
   try {
     mcp = JSON.parse(mcpJsonText);
   } catch {
-    log.warn(`${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MCP_FILE} is not valid JSON — skipped.`);
+    log.warn(`${pluginsDir}/${pluginFolder}/${PLUGIN_MCP_FILE} is not valid JSON — skipped.`);
     return [];
   }
   if (!isRecord(mcp) || !isRecord(mcp.mcpServers)) return [];
@@ -336,13 +338,13 @@ export function descriptorsFromMcpJson(
       // servers themselves — they are still listed, as the spec's own
       // "invalid components are skipped, valid ones load" posture suggests.
       log.warn(
-        `${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MANIFEST_FILE} is not valid JSON — ` +
+        `${pluginsDir}/${pluginFolder}/${PLUGIN_MANIFEST_FILE} is not valid JSON — ` +
           'its mcp-server auth/variable declarations are ignored.',
       );
     }
   }
   const extensions = extensionServers(manifest);
-  const mcpJsonPath = `${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
+  const mcpJsonPath = `${pluginsDir}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
 
   const out: ToolManualDescriptor[] = [];
   for (const [name, rawEntry] of Object.entries(mcp.mcpServers)) {

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -1,15 +1,13 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
-  DEFAULT_BRANCH,
   HEXIS_EXTENSION_NS,
-  PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { validatedVariables } from './mcp-json-discovery.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { containsVariableReference, findReservedVariableRef } from '../../shared/variable-refs.js';
@@ -127,10 +125,14 @@ export class McpServerEditService {
     private readonly commits: CommitDriver,
     private readonly accessControl: IAccessControl,
     private readonly toolManuals: IToolManualService,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: IFsProbe,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /**
    * The merged view of one server, or null when unknown — including when
    * `mcp.json` is absent, is not a JSON object, or has no object entry for it
@@ -385,9 +387,9 @@ export class McpServerEditService {
     // One folder-scoped commit, ungated beyond the caller's own write access —
     // both files or neither. The catalog cache is stale the moment it lands.
     await this.commits.runPendingCommit(
-      workspaceIdForBranch(DEFAULT_BRANCH),
-      DEFAULT_BRANCH,
-      `${this.kbDirName}/${PLUGINS_DIR}/${folder}`,
+      this.kb.defaultWorkspaceId(),
+      this.kb.defaultBranch,
+      `${this.kbDirName}/${this.kb.layout.pluginsDir}/${folder}`,
       user,
     );
     this.toolManuals.invalidate();
@@ -408,7 +410,7 @@ export class McpServerEditService {
     return {
       folder,
       name: found.name,
-      wsId: workspaceIdForBranch(DEFAULT_BRANCH),
+      wsId: this.kb.defaultWorkspaceId(),
       mcpJsonPath: found.path,
     };
   }
@@ -419,10 +421,10 @@ export class McpServerEditService {
     mcpAbs: string;
     manifestAbs: string;
   }> {
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-    await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
+    await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch);
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    const pluginDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR, folder);
+    const pluginDir = path.join(wsDir, this.kbDirName, this.kb.layout.pluginsDir, folder);
     const mcpAbs = path.join(pluginDir, PLUGIN_MCP_FILE);
     const manifestAbs = path.join(pluginDir, PLUGIN_MANIFEST_FILE);
     return {

package/src/modules/tool-manuals/pending-tools.service.ts

@@ -1,14 +1,13 @@
 import {
-  PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
-  DEFAULT_BRANCH,
   pluginOfPath,
   type ChangeRequest,
   type IWorkflowService,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { readAt, visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
@@ -56,6 +55,7 @@ export class PendingToolsService implements IPendingToolService {
     private readonly accessControl: IAccessControl,
     private readonly toolManuals: Pick<IToolManualService, 'listAllSummaries'>,
     private readonly workflow: IWorkflowService,
+    private readonly kb: KbContext,
   ) {}
 
   async listPendingTools(userEmail: string): Promise<PendingTool[]> {
@@ -72,19 +72,21 @@ export class PendingToolsService implements IPendingToolService {
       return [];
     }
 
+    const layout = this.kb.layout;
     const proposed = await visibleProposedFiles(
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
         workflow: this.workflow,
+        kb: this.kb,
       },
       userEmail,
-      isToolDeclaration,
+      (p) => isToolDeclaration(p, layout),
     );
 
     const out: PendingTool[] = [];
     for (const { cr, path, content, isAuthor } of proposed) {
-      for (const descriptor of await this.declarationsIn(cr, path, content)) {
+      for (const descriptor of await this.declarationsIn(cr, path, content, layout)) {
         if (released.has(utcpNamespacePrefix(descriptor.name))) continue;
         out.push({
           slug: descriptor.slug,
@@ -92,7 +94,7 @@ export class PendingToolsService implements IPendingToolService {
           path: descriptor.path,
           type: descriptor.type,
           ...(descriptor.description ? { description: descriptor.description } : {}),
-          plugin: pluginOfPath(descriptor.path),
+          plugin: pluginOfPath(descriptor.path, layout),
           changeRequestNumber: cr.number,
           branch: cr.branch,
           authorName: cr.appAuthor?.name ?? cr.author.name ?? 'Someone',
@@ -118,8 +120,9 @@ export class PendingToolsService implements IPendingToolService {
     cr: ChangeRequest,
     path: string,
     content: string,
+    layout: KbLayout,
   ): Promise<ToolManualDescriptor[]> {
-    if (!isMcpJson(path)) {
+    if (!isMcpJson(path, layout)) {
       let descriptor: ToolManualDescriptor;
       try {
         descriptor = normalizeToolManual(baseName(path), path, content);
@@ -140,22 +143,22 @@ export class PendingToolsService implements IPendingToolService {
     // missing manifest costs a sentence, not the card. No separate access
     // check: this caller already passed the write gate on the `mcp.json`
     // beside it, which is the plugin folder's own verdict.
-    const pluginFolder = path.slice(`${PLUGINS_DIR}/`.length, -(PLUGIN_MCP_FILE.length + 1));
+    const pluginFolder = path.slice(`${layout.pluginsDir}/`.length, -(PLUGIN_MCP_FILE.length + 1));
     const manifest = await readAt(
       this.workspaceService,
-      workspaceIdForBranch(DEFAULT_BRANCH),
+      this.kb.defaultWorkspaceId(),
       cr.branch,
-      `${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MANIFEST_FILE}`,
+      `${layout.pluginsDir}/${pluginFolder}/${PLUGIN_MANIFEST_FILE}`,
     );
-    return descriptorsFromMcpJson(pluginFolder, content, manifest);
+    return descriptorsFromMcpJson(pluginFolder, content, manifest, layout);
   }
 }
 
 /** `Plugins/<…>/mcp.json` — a plugin's MCP server declarations. */
-function isMcpJson(repoRelPath: string): boolean {
+function isMcpJson(repoRelPath: string, layout: KbLayout): boolean {
   const segments = repoRelPath.split('/');
   return (
-    segments[0] === PLUGINS_DIR &&
+    segments[0] === layout.pluginsDir &&
     segments.length >= 3 &&
     segments[segments.length - 1] === PLUGIN_MCP_FILE
   );
@@ -169,11 +172,11 @@ function isMcpJson(repoRelPath: string): boolean {
  * or a plugin's `mcp.json`. `Plugins/mcp.json` is not one: there is no plugin
  * there for its servers to belong to.
  */
-function isToolDeclaration(repoRelPath: string): boolean {
+function isToolDeclaration(repoRelPath: string, layout: KbLayout): boolean {
   const segments = repoRelPath.split('/');
-  if (segments[0] !== PLUGINS_DIR || segments.length < 2) return false;
+  if (segments[0] !== layout.pluginsDir || segments.length < 2) return false;
   const last = segments[segments.length - 1] ?? '';
   // Case-insensitive, matching the catalog's own walk.
   if (last.toLowerCase().endsWith('.tool')) return true;
-  return isMcpJson(repoRelPath);
+  return isMcpJson(repoRelPath, layout);
 }

package/src/modules/tool-manuals/tool-delete.service.ts

@@ -2,14 +2,13 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import {
-  DEFAULT_BRANCH,
   HEXIS_EXTENSION_NS,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import type { IFsProbe } from '../../shared/fs.contract.js';
@@ -122,10 +121,14 @@ export class ToolDeleteService {
     private readonly pluginIndex: IPluginIndexService,
     private readonly source: PluginSource,
     private readonly vault: Pick<ISecretsVaultService, 'countNamespace' | 'removeNamespace'>,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: IFsProbe,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /** What deleting `slug` would affect. Owner-gated like the delete itself. */
   async dependents(userEmail: string, slug: string): Promise<ToolDependents> {
     const { tool, source, plugin, folder } = await this.authorize(userEmail, slug);
@@ -154,8 +157,8 @@ export class ToolDeleteService {
       // removing its file here would be undone by the next sync, or worse.
       throw new ToolDeleteError("This tool's plugin is managed in another format — delete it there.", 422);
     }
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-    await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
+    await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch);
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
     if (source === 'manual') await this.deleteManual(user, wsId, kbRoot, tool);
@@ -205,7 +208,7 @@ export class ToolDeleteService {
       }
     }
     if (!best) return null;
-    const owner = await this.accessControl.canOwner(workspaceIdForBranch(DEFAULT_BRANCH), userEmail, best.folder);
+    const owner = await this.accessControl.canOwner(this.kb.defaultWorkspaceId(), userEmail, best.folder);
     return owner ? best : null;
   }
 
@@ -263,10 +266,10 @@ export class ToolDeleteService {
     folder: string,
     home: PluginCatalogEntry,
   ): Promise<ToolDependents['plugins']> {
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
     let discovered;
     try {
-      await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+      await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch);
       const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
       discovered = await this.source.discover(kbRoot);
     } catch (err) {
@@ -320,7 +323,7 @@ export class ToolDeleteService {
     const parked = path.join(path.dirname(abs), `.deleting-${randomUUID()}`);
     await fs.rename(abs, parked);
     try {
-      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${tool.path}`, user, {
+      await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, `${this.kbDirName}/${tool.path}`, user, {
         // The route authorized the delete with the owner verb; see class note.
         systemAuthorized: true,
       });
@@ -393,7 +396,7 @@ export class ToolDeleteService {
     // Commit-stage failures propagate as-is: the pipeline may already hold a
     // local commit, and rewriting the tree under it is the state its own
     // recovery misreads (same contract as McpServerEditService).
-    await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${folder}`, user, {
+    await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, `${this.kbDirName}/${folder}`, user, {
       systemAuthorized: true,
     });
   }

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -5,9 +5,8 @@ const log = logger('tool-manuals');
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import AdmZip from 'adm-zip';
-import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe, type ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import type { IPluginIndexService } from '../plugins/plugins.contract.js';
@@ -54,7 +53,8 @@ export function createToolManualsAgentRoutes(
   archiveDeps?: {
     workspaceService: WorkspaceService;
     accessControl: IAccessControl;
-    kbDirName: string;
+    /** The checkout folder, the released branch, and the layout that names the plugins root. */
+    kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId' | 'layout'>;
     disk: ITreeWalker & IFsProbe;
     /**
      * Resolves a plugin IDENTITY (its manifest name) to its folder, so a
@@ -110,17 +110,19 @@ export function createToolManualsAgentRoutes(
       if (!folder || folder === '.' || folder === '..' || /[/\\]/.test(folder)) {
         return void res.status(422).json({ error: 'Not a plugin folder name' });
       }
-      const { workspaceService, accessControl, kbDirName, disk, pluginIndex } = archiveDeps;
-      const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-      await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+      const { workspaceService, accessControl, kb, disk, pluginIndex } = archiveDeps;
+      const { kbDirName } = kb;
+      const pluginsDir = kb.layout.pluginsDir;
+      const wsId = kb.defaultWorkspaceId();
+      await workspaceService.getOrCreateForBranch(kb.defaultBranch);
       const wsDir = await workspaceService.getWorkspacePath(wsId);
       // The name is a folder directly under the root, as it always was — or,
       // when no such folder exists, a plugin's IDENTITY, which the index maps
       // to its folder at any depth (`Plugins/departments/eng/ado`). Identity
       // second, so a folder that spells a nested plugin's name keeps meaning
       // the folder.
-      let pluginRel = `${PLUGINS_DIR}/${folder}`;
-      let pluginDir = path.join(wsDir, kbDirName, PLUGINS_DIR, folder);
+      let pluginRel = `${pluginsDir}/${folder}`;
+      let pluginDir = path.join(wsDir, kbDirName, pluginsDir, folder);
       if (pluginIndex && (await disk.lstatOrNull(pluginDir))?.isDirectory() !== true) {
         const byIdentity = (await pluginIndex.catalog()).find((p) => p.name === folder)?.folders[0];
         if (byIdentity) {

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -16,13 +16,10 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
-import {
-  DEFAULT_BRANCH,
-  PLUGINS_DIR,
-} from '@bevel-software/platform-shared';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import type { PluginSource } from '../plugins/discovery/plugin-source.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
@@ -265,7 +262,7 @@ export class ToolManualService implements IToolManualService {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: ITreeWalker,
     /** Where plugins (and their MCP servers) come from — the one discovery every catalog shares. */
     private readonly source: PluginSource,
@@ -274,6 +271,10 @@ export class ToolManualService implements IToolManualService {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /**
    * Wire the MCP OAuth auto-discovery (setter injection: the discovery service
    * depends on the vault, which is constructed after this service — the same
@@ -329,7 +330,7 @@ export class ToolManualService implements IToolManualService {
     userEmail: string,
     branch: string,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]> {
-    if (!branch || branch === DEFAULT_BRANCH) return [];
+    if (!branch || branch === this.kb.defaultBranch) return [];
     // Only a draft this process already holds a clone of — the one the caller
     // wrote the declaration on. `scanDisk` would otherwise BOOTSTRAP any branch
     // name a caller sends, before the read gate below has had a say: a clone
@@ -456,7 +457,7 @@ export class ToolManualService implements IToolManualService {
   async resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null> {
     const found = (await this.scan()).manuals.find((m) => m.slug === slug);
     if (!found || found.type !== 'inline') return null;
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
     if (!(await this.accessControl.canRead(wsId, userEmail, found.path))) return null;
     try {
       return manualSerializer.validateDict({
@@ -582,7 +583,7 @@ export class ToolManualService implements IToolManualService {
   private async accessibleScan(userEmail: string): Promise<ScanResult> {
     const { manuals, invalid } = await this.scan();
     if (manuals.length === 0 && invalid.length === 0) return emptyScan();
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
     const allowed = await this.accessControl.canReadBatch(wsId, userEmail, [
       ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path)]),
     ]);
@@ -859,7 +860,7 @@ export class ToolManualService implements IToolManualService {
    * calls: a refusal lives only in the scan it came from, so a fixed file is a
    * valid manual on the very next scan.
    */
-  private async scanDisk(branch: string = DEFAULT_BRANCH): Promise<ScanResult> {
+  private async scanDisk(branch: string = this.kb.defaultBranch): Promise<ScanResult> {
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
@@ -870,9 +871,10 @@ export class ToolManualService implements IToolManualService {
 
     // A `.tool` sits under `Plugins/`, beside the skills that use it.
     const files: { abs: string; rel: string }[] = [];
-    const root = path.join(kbRoot, PLUGINS_DIR);
+    const layout = this.kb.layout;
+    const root = path.join(kbRoot, layout.pluginsDir);
     for (const rel of await this.disk.walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
-      files.push({ abs: path.join(root, rel), rel: `${PLUGINS_DIR}/${rel}` });
+      files.push({ abs: path.join(root, rel), rel: `${layout.pluginsDir}/${rel}` });
     }
 
     // MCP servers come from each plugin's mcp.json — the AUTHORITATIVE source
@@ -891,7 +893,7 @@ export class ToolManualService implements IToolManualService {
       // (a URL, a header, an added or dropped server, a `local: true` flip)
       // moves every server's digest — which is correct, if slightly generous.
       const from = sourceDigest(plugin.mcpJsonText + '\u0000' + (plugin.manifestText ?? ''));
-      for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText)) {
+      for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText, layout)) {
         d.sourceRevision = from;
         parsed.push(d);
       }
@@ -974,7 +976,7 @@ export class ToolManualService implements IToolManualService {
     // Only the CATALOG's scan talks. `listDeclaredOnlyOnBranch` re-scans a
     // draft workspace, and a draft's half-written `.tool` is not news about the
     // served catalog — it would also flap the log every time an agent saves.
-    if (branch === DEFAULT_BRANCH) this.logInvalidOnChange(invalid);
+    if (branch === this.kb.defaultBranch) this.logInvalidOnChange(invalid);
     return { manuals, invalid };
   }
 }

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -1,11 +1,10 @@
 import type { Router, RequestHandler } from 'express';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from './tool-manuals.contract.js';
 
@@ -42,6 +41,8 @@ export function registerToolManualsTools(
   deps: {
     accessControl: IAccessControl;
     variableStatus: VariableStatusPort;
+    /** Which branch tools are served from, and its clone. */
+    kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>;
   },
 ): void {
   registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
@@ -57,9 +58,9 @@ export function registerToolManualsTools(
 
   // A FUNCTION, not a constant — this factory runs at boot, and on a
   // setup-screen deployment the branch model is applied AFTER boot. Only a
-  // read inside a handler body sees the configured `DEFAULT_BRANCH`; a
+  // read inside a handler body sees the configured default branch; a
   // construction-time capture would hold the empty pre-setup id until restart.
-  const defaultWs = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const defaultWs = () => deps.kb.defaultWorkspaceId();
   const varKey = (manualName: string, varName: string) => utcpNamespacedKey(manualName, varName);
 
   const listSetupDef = toolDef({
@@ -235,9 +236,9 @@ export function registerToolManualsTools(
         onBranchOnly,
         note:
           `${onBranchOnly.map((p) => `\`${p.name}\``).join(', ')} ${onBranchOnly.length === 1 ? 'is' : 'are'} declared on ` +
-          `\`${branch}\` only. Tools are served from \`${DEFAULT_BRANCH}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
+          `\`${branch}\` only. Tools are served from \`${deps.kb.defaultBranch}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
           'unlisted, uncallable and without a sign-in until that branch is merged: open a change request with ' +
-          `\`open_change_request\` (target \`${DEFAULT_BRANCH}\`), then ask the user to review and merge it in the app.`,
+          `\`open_change_request\` (target \`${deps.kb.defaultBranch}\`), then ask the user to review and merge it in the app.`,
       };
     }),
   );

package/src/modules/workflow/__tests__/apply-failure.test.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import type { AuthUser, FileApprovalState, IWorkflowService, WorkflowEvent } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
@@ -382,7 +383,7 @@ function service(
     {} as IAccessControl,
     {} as FileLockService,
     {} as PendingCommitsService,
-    'knowledge-base',
+    testKbContext(),
     openChangeGate(),
     { emit } as unknown as WorkflowEventBus,
   );