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

package/src/modules/settings/deployment-settings.service.ts

@@ -15,6 +15,7 @@ import {
 import { createHmac } from 'node:crypto';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertKbDirNameFree } from '../kb-fs/repo-path.js';
+import { parseRetentionWindow } from '../audit/audit.contract.js';
 import { normalizeIssuerUrl } from './oidc-check.js';
 
 /**
@@ -39,7 +40,7 @@ export interface SettingDef {
    */
   envVar?: string;
   /** Which block of the setup screen it belongs to. */
-  section: 'knowledge-base' | 'sign-in';
+  section: 'knowledge-base' | 'sign-in' | 'audit';
   secret?: boolean;
   /** Applied on save; the message is shown against the field. */
   validate?(value: string): string | null;
@@ -49,6 +50,14 @@ export interface SettingDef {
    * was copied into a service at construction is not.
    */
   restartToApply?: boolean;
+  /**
+   * A blank field on save CLEARS the stored value, putting the default back.
+   * The rule everywhere else is that blank means "leave it alone" — a stray
+   * Enter must not unconfigure a repository — and that stays the rule; this
+   * is for a setting whose readers already treat "unset" as its default, so
+   * clearing it is the one way back to that default and never a loss.
+   */
+  blankMeansDefault?: boolean;
   /**
    * What an UNSET setting already means to the code that reads it — the
    * layout's defaults, the pointer consent's "on unless turned off".
@@ -172,7 +181,9 @@ export const CORE_SETTINGS: SettingDef[] = [
      */
     key: 'agentsFile',
     section: 'knowledge-base',
-    validate: (v) => validateAgentsFileName(v),
+    // Judged against the default roots here; the quartet check in `plan`
+    // judges it against the roots the same save puts in effect.
+    validate: (v) => validateAgentsFileName(v, DEFAULT_KB_LAYOUT),
     restartToApply: true,
     unsetMeans: DEFAULT_KB_LAYOUT.agentsFile,
   },
@@ -285,6 +296,23 @@ export const CORE_SETTINGS: SettingDef[] = [
     section: 'sign-in',
     restartToApply: true,
   },
+
+  {
+    /**
+     * How long the Audit log keeps an agent's events: a number of days, or
+     * — blank, zero, negative — forever. Read at every prune, so it applies
+     * without a restart. The window's rule lives with the audit service and
+     * is applied here on save and there on every read, so the environment
+     * variable is held to exactly what the Deployment page is. A blanked
+     * field clears the stored value, which is how "forever" is chosen back.
+     */
+    key: 'auditRetentionDays',
+    envVar: 'AUDIT_RETENTION_DAYS',
+    section: 'audit',
+    blankMeansDefault: true,
+    validate: (v) =>
+      parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
+  },
 ];
 
 /**
@@ -396,11 +424,23 @@ export class DeploymentSettingsService {
   private stored = new Map<string, string>();
   private readonly crypto: TokenCrypto | null;
 
+  /**
+   * The environment the env-first layer reads. The process's own for a
+   * single-tenant deployment; a host serving several knowledge bases hands
+   * each graph one built from its tenant record, so a variable set on the
+   * host process can never leak into every tenant, and a record's values
+   * behave exactly as environment-pinned ones do (they win over the setup
+   * screen and the screen shows them as such).
+   */
+  private readonly env: NodeJS.ProcessEnv;
+
   constructor(
     private readonly db: Database,
     private readonly secretsEncKey: string,
     defs: SettingDef[] = CORE_SETTINGS,
+    options: { env?: NodeJS.ProcessEnv } = {},
   ) {
+    this.env = options.env ?? process.env;
     for (const def of defs) this.defs.set(def.key, def);
     // No key configured means secrets cannot be stored — surfaced when someone
     // tries, rather than pretended away by writing plaintext.
@@ -444,7 +484,7 @@ export class DeploymentSettingsService {
   resolve(key: string): string {
     const def = this.defs.get(key);
     if (!def) return '';
-    const fromEnv = def.envVar ? (process.env[def.envVar] ?? '').trim() : '';
+    const fromEnv = def.envVar ? (this.env[def.envVar] ?? '').trim() : '';
     if (fromEnv) return fromEnv;
     return (this.stored.get(key) ?? '').trim();
   }
@@ -495,7 +535,7 @@ export class DeploymentSettingsService {
    */
   async importLegacyLayoutEnv(): Promise<void> {
     for (const [key, envVar] of Object.entries(LEGACY_LAYOUT_ENV_VARS)) {
-      const fromEnv = (process.env[envVar] ?? '').trim();
+      const fromEnv = (this.env[envVar] ?? '').trim();
       if (!fromEnv) continue;
       const saved = (this.stored.get(key) ?? '').trim();
       if (saved) {
@@ -533,7 +573,7 @@ export class DeploymentSettingsService {
     // A setting with no variable can never read `env`, whatever the process
     // environment happens to hold — which is what makes the layout fields
     // editable in the app on a deployment that still sets the old variables.
-    if (def.envVar && (process.env[def.envVar] ?? '').trim()) return 'env';
+    if (def.envVar && (this.env[def.envVar] ?? '').trim()) return 'env';
     return (this.stored.get(key) ?? '').trim() ? 'stored' : 'unset';
   }
 
@@ -577,10 +617,13 @@ export class DeploymentSettingsService {
     entries: Record<string, string>,
     updatedBy: string | null,
   ): Promise<{ restartRequired: boolean; restartKeys: string[] }> {
-    const toWrite = this.plan(entries);
+    const { toWrite, toClear } = this.plan(entries);
 
     /** The settings this save changed that a running server cannot pick up. */
     const restartKeys: string[] = [];
+    // A blanked blank-means-default setting: its row goes, and its readers
+    // are back on the default from the next read.
+    for (const key of toClear) await this.clear(key);
     for (const { key, value, def } of toWrite) {
       // Compared against the EFFECTIVE value: a setting that was unset was
       // already running on whatever its readers make of "unset" — the layout
@@ -600,10 +643,9 @@ export class DeploymentSettingsService {
       this.stored.set(key, value);
     }
 
-    // The git token is consumed through the environment (the credential helper
-    // reads `$GITHUB_TOKEN` at call time, so it never appears in argv). Putting
-    // it there is what makes a token saved here work without a restart.
-    this.syncGitTokenEnv();
+    // A token saved here is in effect at once: the git runner's credentials
+    // read `resolve('gitToken')` on every call, so nothing is published to
+    // the process environment and no restart is needed.
     return { restartRequired: restartKeys.length > 0, restartKeys };
   }
 
@@ -615,14 +657,19 @@ export class DeploymentSettingsService {
    * before letting the save happen.
    */
   resolveAfter(entries: Record<string, string>): (key: string) => string {
-    const toWrite = this.plan(entries);
-    return (key) => toWrite.find((w) => w.key === key)?.value ?? this.resolve(key);
+    const { toWrite, toClear } = this.plan(entries);
+    return (key) =>
+      toClear.includes(key) ? '' : (toWrite.find((w) => w.key === key)?.value ?? this.resolve(key));
   }
 
-  /** Validate a batch and return the writes it amounts to; throws on any problem. */
-  private plan(entries: Record<string, string>): { key: string; value: string; def: SettingDef }[] {
+  /** Validate a batch and return the writes (and the clears) it amounts to; throws on any problem. */
+  private plan(entries: Record<string, string>): {
+    toWrite: { key: string; value: string; def: SettingDef }[];
+    toClear: string[];
+  } {
     const problems: Record<string, string> = {};
     const toWrite: { key: string; value: string; def: SettingDef }[] = [];
+    const toClear: string[] = [];
 
     for (const [key, raw] of Object.entries(entries)) {
       const def = this.defs.get(key);
@@ -638,7 +685,12 @@ export class DeploymentSettingsService {
       // An empty field means "leave it alone", not "erase it". Clearing a
       // setting is not something the setup screen offers, and treating a blank
       // input as a delete would let a stray Enter unconfigure a deployment.
-      if (!value) continue;
+      // The one exception is a setting that SAYS a blank is its default (see
+      // `SettingDef.blankMeansDefault`): for it a blank clears the stored row.
+      if (!value) {
+        if (def.blankMeansDefault) toClear.push(key);
+        continue;
+      }
       const problem = def.validate?.(value);
       if (problem) {
         problems[key] = problem;
@@ -722,7 +774,7 @@ export class DeploymentSettingsService {
     }
 
     if (Object.keys(problems).length > 0) throw new SettingsValidationError(problems);
-    return toWrite;
+    return { toWrite, toClear };
   }
 
   /** Drop stored rows for settings this build no longer defines. */
@@ -738,18 +790,6 @@ export class DeploymentSettingsService {
     }
   }
 
-  /**
-   * Publish the resolved git token as `GITHUB_TOKEN`, the name the credential
-   * helper and every redaction path already read. Only when the environment did
-   * not supply one — otherwise this would overwrite the operator's value with
-   * a stored fallback, inverting the precedence everything else here obeys.
-   */
-  syncGitTokenEnv(): void {
-    if (this.sourceOf('gitToken') !== 'stored') return;
-    const token = this.resolve('gitToken');
-    if (token) process.env.GITHUB_TOKEN = token;
-  }
-
   /** The single sign-on values in effect, issuer normalized the way the provider uses it. */
   resolveOidcCredentials(): OidcCredentials {
     return {

package/src/modules/settings/setup.routes.ts

@@ -23,13 +23,11 @@ import {
   type RepositoryConnection,
 } from './connection-check.js';
 import {
-  configureBranchModel,
-  configureKbLayout,
-  isBranchModelConfigured,
   isDefaultKbLayout,
   validateBranchModel,
   validateKbLayout,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { failureOf, type GitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { listRootFolders, pickListingBranch } from './git-root-folders.js';
@@ -105,6 +103,12 @@ export function createSetupRoutes(
     /** That failure classified, for the setup screen; absent, the message is read instead. */
     lastFailureKind?(): GitFailure | null;
   },
+  /**
+   * The knowledge base's context as the running graph holds it: the save
+   * that completes setup applies the branch model and the layout to it, so
+   * every service reads the admin's answer without a restart.
+   */
+  kb: KbContext,
   /**
    * The remote-sync facts the Deployment page shows beside the sync secret:
    * the address a webhook or pipeline must call, and what the last call did.
@@ -180,7 +184,7 @@ export function createSetupRoutes(
   };
   /** The app-gate answer: settings complete AND the KB phase settled clean, whoever ran it. */
   const kbReady = () =>
-    isComplete(settings) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+    isComplete(settings, kb) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
 
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
@@ -215,7 +219,7 @@ export function createSetupRoutes(
     }
     res.json({
       complete: kbReady(),
-      awaitingRestart: awaitingRestart(settings),
+      awaitingRestart: awaitingRestart(settings, kb),
       isAdmin: true,
       settings: settings.describe(),
       oidcVerification: await settings.oidcVerification(),
@@ -261,7 +265,7 @@ export function createSetupRoutes(
       // save that flips it false→true — whichever field arrives last — is the
       // one that must run the KB startup phase, regardless of which save
       // configured the branch model.
-      const wasComplete = isComplete(settings);
+      const wasComplete = isComplete(settings, kb);
       if (!(await connectionHoldsFor(entries, wasComplete, res))) return;
       const oidc = await signInHoldsFor(entries, res);
       if (!oidc) return;
@@ -292,13 +296,13 @@ export function createSetupRoutes(
        * capturing it at construction, which is what makes applying it here
        * enough.
        */
-      if (!isBranchModelConfigured()) {
+      if (!kb.isBranchModelConfigured()) {
         const model = {
           defaultBranch: settings.resolve('defaultBranch'),
           protectedBranches: settings.resolve('protectedBranches'),
         };
         if (!validateBranchModel(model)) {
-          configureBranchModel(model);
+          kb.applyBranchModel(model);
           branchModelApplied = true;
         }
       }
@@ -316,7 +320,7 @@ export function createSetupRoutes(
        * on a re-save of a complete, healthy setup: with the gate open,
        * sessions may be live and that is no longer a quiet moment.
        */
-      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings)) {
+      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings, kb)) {
         /**
          * The folder names, applied BEFORE the phase for the same reason as
          * the branch model above: they are otherwise applied once at boot, so
@@ -327,10 +331,10 @@ export function createSetupRoutes(
          * the names an earlier setup save applied before a run that failed:
          * the gate never opened, so the retry initializes what is saved now.
          */
-        if (isDefaultKbLayout() || (kbInit !== null && layoutAppliedBySetup)) {
+        if (isDefaultKbLayout(kb.layout) || (kbInit !== null && layoutAppliedBySetup)) {
           const layout = settings.resolveKbLayout();
           if (!validateKbLayout(layout)) {
-            configureKbLayout(layout);
+            kb.applyLayout(layout);
             layoutApplied = true;
             layoutAppliedBySetup = true;
           }
@@ -382,7 +386,7 @@ export function createSetupRoutes(
               )
             : restartRequired,
         complete: kbReady(),
-        awaitingRestart: awaitingRestart(settings),
+        awaitingRestart: awaitingRestart(settings, kb),
         settings: settings.describe(),
         oidcVerification: await settings.oidcVerification(),
       });
@@ -784,11 +788,17 @@ export function settingsAnswered(settings: DeploymentSettingsService): boolean {
  * that puts it there. {@link awaitingRestart} is what tells the screen to ask
  * for one rather than claim a field is missing.
  */
-export function isComplete(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && isBranchModelConfigured();
+export function isComplete(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+): boolean {
+  return settingsAnswered(settings) && kb.isBranchModelConfigured();
 }
 
 /** Answered, but not yet in effect: everything is stored, the process is stale. */
-export function awaitingRestart(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && !isBranchModelConfigured();
+export function awaitingRestart(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+): boolean {
+  return settingsAnswered(settings) && !kb.isBranchModelConfigured();
 }

package/src/modules/skills/__tests__/allowed-tools-check.test.ts

@@ -7,6 +7,7 @@ import {
 } from '../allowed-tools-check.js';
 import type { UtcpTool } from '../../tool-registry/tool.contract.js';
 import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const visible: VisibleTools = {
   core: ['read_file', 'get_skill', 'list_skills'],
@@ -110,10 +111,10 @@ describe('checkAllowedTools', () => {
 
 describe('skillFileRepoPath', () => {
   test('recognises skill files under the plugin and skills roots only', () => {
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', './knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Data/SKILL.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'./knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Data/SKILL.md')).toBeNull();
   });
 });
 
@@ -138,7 +139,7 @@ describe('AllowedToolsChecker', () => {
           }
         : null,
   };
-  const checker = new AllowedToolsChecker(registry, manuals, 'knowledge-base');
+  const checker = new AllowedToolsChecker(registry, manuals, testKbContext());
 
   const skill = (tools: string) => `---\nname: rfi\ndescription: RFI.\nallowed-tools: ${tools}\n---\n\n# RFI\n`;
 
@@ -160,7 +161,7 @@ describe('AllowedToolsChecker', () => {
     const broken = new AllowedToolsChecker(
       { listExternal: async () => { throw new Error('down'); } },
       manuals,
-      'knowledge-base',
+      testKbContext(),
     );
     await expect(
       broken.checkSave('a@x.com', 'knowledge-base/Plugins/Sales/rfi/SKILL.md', skill('hubspot.serch')),
@@ -168,7 +169,7 @@ describe('AllowedToolsChecker', () => {
   });
 
   test('a capped capability list is treated as unknown, never as proof of absence', async () => {
-    const capped = new AllowedToolsChecker(registry, manuals, 'knowledge-base', 1);
+    const capped = new AllowedToolsChecker(registry, manuals, testKbContext(), 1);
     expect(await capped.check('a@x.com', ['hubspot.whatever'])).toEqual([]);
   });
 
@@ -179,7 +180,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(entries(await spying.check('alice@example.com', ['hubspot.serch']))).toEqual(['hubspot.serch']);
     expect(listExternal).toHaveBeenCalledWith({ userEmail: 'alice@example.com' });
@@ -193,7 +194,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     const results = await spying.checkSaves('a@x.com', [
       { path: 'knowledge-base/Plugins/Sales/rfi/SKILL.md', content: skill('hubspot.serch') },
@@ -214,7 +215,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(await spying.check('a@x.com', ['Bash', 'Read', 'Bash(git:*)', 'mcp__github__create_issue', 'shell'])).toEqual([]);
     expect(listExternal).not.toHaveBeenCalled();

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -19,6 +19,7 @@ import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/too
 import { registerSkillsTools } from '../skills.tools.js';
 import type { ISkillService } from '../skills.contract.js';
 import { AllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The agent surfaces end to end: a SKILL.md written through the file tools
@@ -41,7 +42,7 @@ const checker = new AllowedToolsChecker(
       capabilities: [{ name: 'search', description: null }],
     }),
   },
-  KB_DIR,
+  testKbContext({ kbDirName: KB_DIR }),
 );
 
 /** What the tool handed the service on its last `getSkill` — the tool's one job is to pass it on. */
@@ -109,8 +110,8 @@ async function start(): Promise<string> {
   const router = express.Router();
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
-    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-    { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+    { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
     new RoutineWritePolicyService(),
     {} as never,
     checker,

package/src/modules/skills/__tests__/pending-skills.service.test.ts

@@ -5,6 +5,7 @@ import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService, SkillSummary } from '../skills.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The half of the catalog that is NOT on the default branch.
@@ -77,7 +78,7 @@ function harness(opts: {
     listChangeRequests: async () => opts.crs,
   } as unknown as IWorkflowService;
 
-  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow);
+  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow, testKbContext());
 }
 
 const ADMIN_WRITES = {
@@ -210,6 +211,7 @@ describe('PendingSkillsService', () => {
       {} as unknown as IAccessControl,
       { listSkills: async () => [] } as unknown as ISkillService,
       workflow,
+      testKbContext(),
     );
     await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);
   });

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -11,6 +11,7 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { JoinRequestsService } from '../../plugins/join-requests.service.js';
 import type { ISkillService } from '../skills.contract.js';
 import { createSkillAccessRequestRoutes } from '../skill-access-requests.routes.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The branch probe behind an access request: the listing is used to PROVE a
@@ -52,7 +53,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
       workflow,
       workspaceService,
       joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
-      kbDirName: KB,
+      kb: testKbContext({ kbDirName: KB }),
       resolveUser: async () => MIA,
     }),
   );

package/src/modules/skills/__tests__/skills.routes.warnings.test.ts

@@ -5,6 +5,7 @@ import '../../auth/auth.middleware.js'; // Express Request.userEmail augmentatio
 import { createSkillsRoutes } from '../skills.routes.js';
 import type { ISkillService } from '../skills.contract.js';
 import type { IAllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The browser's skill read carries the same `allowed-tools` warnings as
@@ -42,7 +43,7 @@ async function start(checker?: IAllowedToolsChecker): Promise<string> {
     req.userEmail = EMAIL;
     next();
   });
-  app.use('/api', createSkillsRoutes(skillService, undefined, undefined, undefined, checker));
+  app.use('/api', createSkillsRoutes(skillService, testKbContext(), undefined, undefined, undefined, checker));
   server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -13,6 +13,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { GitService } from '../../workflow/git/git.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -53,7 +54,7 @@ describe('SkillService', () => {
   } as unknown as IAccessControl;
 
   const svc = (access: IAccessControl = allowAll) =>
-    new SkillService(workspaceService, access, KB_DIR, new NodeFs());
+    new SkillService(workspaceService, access, testKbContext({ kbDirName: KB_DIR }), new NodeFs());
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
@@ -377,7 +378,7 @@ describe('SkillService', () => {
 
     const versioned = (access: IAccessControl = allowAll) => {
       const service = svc(access);
-      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), KB_DIR));
+      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), testKbContext({ kbDirName: KB_DIR })));
       return service;
     };
 

package/src/modules/skills/allowed-tools-check.ts

@@ -1,5 +1,5 @@
-import { PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IToolRegistry } from '../tool-registry/tool.contract.js';
 import {
   EXTERNAL_KB_MANUAL_NAME,
@@ -236,11 +236,12 @@ function editDistance(a: string, b: string): number {
  * Accepts the workspace spelling (`<kbDirName>/Plugins/…`) the save
  * surfaces receive.
  */
-export function skillFileRepoPath(kbDirName: string, workspacePath: string): string | null {
+export function skillFileRepoPath(kb: Pick<KbContext, 'kbDirName' | 'layout'>, workspacePath: string): string | null {
   const parts = workspacePath.split('/').filter((p) => p && p !== '.');
-  if (parts[0] === kbDirName) parts.shift();
+  if (parts[0] === kb.kbDirName) parts.shift();
   if (parts.length < 3 || parts[parts.length - 1] !== 'SKILL.md') return null;
-  return parts[0] === PLUGINS_DIR || parts[0] === SKILLS_DIR ? parts.join('/') : null;
+  const { pluginsDir, skillsDir } = kb.layout;
+  return parts[0] === pluginsDir || parts[0] === skillsDir ? parts.join('/') : null;
 }
 
 /** What the save surfaces and `get_skill` depend on. */
@@ -267,7 +268,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
   constructor(
     private readonly registry: Pick<IToolRegistry, 'listExternal'>,
     private readonly manuals: Pick<IToolManualService, 'listAccessible' | 'getDetail'>,
-    private readonly kbDirName: string,
+    private readonly kb: Pick<KbContext, 'kbDirName' | 'layout'>,
     /**
      * The cap `getDetail` applies to a manual's capabilities. Taken from the
      * projection itself: a copy of the number here would silently start
@@ -300,7 +301,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
    * fail because a check could not run).
    */
   private declaredTools(workspacePath: string, content: string): readonly string[] | undefined {
-    if (skillFileRepoPath(this.kbDirName, workspacePath) === null) return undefined;
+    if (skillFileRepoPath(this.kb, workspacePath) === null) return undefined;
     try {
       return parseSkillFrontmatter(content).allowedTools;
     } catch (err) {

package/src/modules/skills/pending-skills.service.ts

@@ -1,9 +1,7 @@
-import {
-  PLUGINS_DIR,
-  SKILLS_DIR,
-} from '@bevel-software/platform-shared';
+import type { KbLayout } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
 import { visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
@@ -40,6 +38,7 @@ export class PendingSkillsService implements IPendingSkillService {
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
     private readonly workflow: IWorkflowService,
+    private readonly kb: KbContext,
   ) {}
 
   async listPendingSkills(userEmail: string): Promise<PendingSkill[]> {
@@ -54,14 +53,16 @@ export class PendingSkillsService implements IPendingSkillService {
       return [];
     }
 
+    const layout = this.kb.layout;
     const proposed = await visibleProposedFiles(
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
         workflow: this.workflow,
+        kb: this.kb,
       },
       userEmail,
-      (p) => isSkillDoc(p) && !released.has(folderOf(p)),
+      (p) => isSkillDoc(p, layout) && !released.has(folderOf(p)),
     );
 
     const out: PendingSkill[] = proposed.map(({ cr, path, content, isAuthor }) => {
@@ -96,12 +97,12 @@ export class PendingSkillsService implements IPendingSkillService {
  * catalog already supports. `Plugins/<plugin>/SKILL.md` is NOT a skill — a plugin
  * folder is not itself one.
  */
-function isSkillDoc(repoRelPath: string): boolean {
+function isSkillDoc(repoRelPath: string, layout: KbLayout): boolean {
   const segments = repoRelPath.split('/');
   if (segments[segments.length - 1] !== SKILL_DOC) return false;
   // Under `Skills/` a skill may sit directly below the root: `Skills/<skill>/SKILL.md`.
-  if (segments[0] === SKILLS_DIR) return segments.length >= 3;
-  return segments.length >= 4 && segments[0] === PLUGINS_DIR;
+  if (segments[0] === layout.skillsDir) return segments.length >= 3;
+  return segments.length >= 4 && segments[0] === layout.pluginsDir;
 }
 
 /** The skill folder holding a SKILL.md. */