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

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

@@ -12,6 +12,7 @@ import type { IPluginIndexService, PluginCatalogEntry } from '../../plugins/plug
 import type { PluginSource, Discovery } from '../../plugins/discovery/plugin-source.js';
 import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
 import { ToolDeleteError, ToolDeleteService } from '../tool-delete.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Deleting one tool, over a real temp KB: the two shapes a tool comes in (a
@@ -147,7 +148,7 @@ function build(
     pluginIndex,
     opts.source ?? discovery([]),
     vault as never,
-    KB,
+    testKbContext({ kbDirName: KB }),
     new NodeFs(),
   );
 }

package/src/modules/tool-manuals/__tests__/tool-manuals.archive.route.test.ts

@@ -11,6 +11,7 @@ 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 type { IToolManualService } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `GET /agent/plugins/:folder/archive` — error taxonomy of the plugin-folder
@@ -47,7 +48,7 @@ async function baseUrl(pluginIndex?: { catalog(): Promise<{ name: string; folder
       {} as unknown as IToolManualService,
       manualAuth,
       async () => 'ali@example.com',
-      { workspaceService, accessControl, kbDirName: KB, disk: new NodeFs(), pluginIndex: pluginIndex as never },
+      { workspaceService, accessControl, kb: testKbContext({ kbDirName: KB }), disk: new NodeFs(), pluginIndex: pluginIndex as never },
     ),
   );
   httpServer = await new Promise<HttpServer>((resolve) => {

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

@@ -15,6 +15,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { utcpNamespacePrefix } from '../../../shared/utcp-namespace.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);
@@ -146,7 +147,7 @@ describe('a shell `.tool` in a workspace', () => {
   afterEach(() => rm(root, { recursive: true, force: true }));
 
   test('is listed to local consumers and withheld from remote ones', async () => {
-    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 })));
     // `list_local_tools` names it, so the local server knows to materialize it.
     expect(await svc.listLocalOnly('user@x.eu')).toEqual([{ slug: 'git', name: 'git', path: 'Plugins/git.tool' }]);
     // The hosted proxy's manual set excludes it entirely.
@@ -157,7 +158,7 @@ describe('a shell `.tool` in a workspace', () => {
   test('its embedded cli tools survive manual serialization', async () => {
     // The whole point of registering the serializer: without it the manual body
     // fails validation and the local server gets nothing to run.
-    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 })));
     const manual = await svc.resolveInlineManual('user@x.eu', 'git');
     expect(manual).not.toBeNull();
     const tools = (manual as { tools: { name: string; tool_call_template: { call_template_type: string } }[] }).tools;
@@ -206,7 +207,7 @@ describe('manual namespaces are unique, not merely manual names', () => {
   }
 
   const names = async (): Promise<string[]> =>
-    (await new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk)).listAllSummaries()).map((m) => m.name).sort();
+    (await new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR }))).listAllSummaries()).map((m) => m.name).sort();
 
   it('keeps two manuals whose namespaces genuinely differ', async () => {
     // Underscore-doubling is injective, so `a_b` (a__b_) and `a__b` (a____b_)
@@ -243,7 +244,7 @@ describe('manual namespaces are unique, not merely manual names', () => {
     await writeMcpServer('Vendor', 'a-b');
     await writeTool('a.tool', 'a_b');
     await writeTool('c.tool', 'other');
-    const kept = await new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk)).listAllSummaries();
+    const kept = await new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR }))).listAllSummaries();
     const namespaces = kept.map((m) => utcpNamespacePrefix(m.name));
     expect(new Set(namespaces).size).toBe(namespaces.length);
   });

package/src/modules/tool-manuals/__tests__/tool-manuals.detail.route.test.ts

@@ -16,6 +16,7 @@ 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 type { IToolManualService, ToolManualDetail } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `GET /api/tools/:slug` — the browser tool page's detail read. Two halves:
@@ -165,7 +166,7 @@ describe('ToolManualService.getDetail — capabilities + access', () => {
     canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
   } 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 })));
 
   /** Write one `.tool` into a fresh temp KB and return the service over it. */
   async function withTool(file: string, content: string): Promise<void> {

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

@@ -13,6 +13,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';
 
 /**
  * THE TWO HTTP SURFACES, over a real catalog.
@@ -80,9 +81,9 @@ async function baseUrlAs(email: string | undefined): Promise<{ base: string; ser
   const service = new ToolManualService(
     workspaceService,
     accessControl,
-    KB_DIR,
+    testKbContext({ kbDirName: KB_DIR }),
     disk,
-    new KbPluginSource(disk),
+    new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })),
     () => clock,
   );
   const app = express();
@@ -98,6 +99,7 @@ async function baseUrlAs(email: string | undefined): Promise<{ base: string; ser
   app.use(
     '/api',
     createSecretsVaultRoutes({
+      kb: testKbContext({ kbDirName: KB_DIR }),
       secretsVault: { statusFor: async () => [] } as unknown as Parameters<
         typeof createSecretsVaultRoutes
       >[0]['secretsVault'],

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) {