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

package/src/modules/workspace/startup/steps/groups-to-plugins.step.ts

@@ -5,7 +5,6 @@ import {
   HEXIS_EXTENSION_NS,
   HEXIS_TOOLS_DIR,
   LEGACY_GROUPS_DIR,
-  PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   PLUGIN_MCP_SCHEMA,
@@ -18,6 +17,7 @@ import { parseOwnAccessEntries } from '../../../access-model/access-grammar.js';
 import { containsVariableReference } from '../../../../shared/variable-refs.js';
 import { IGNORE_FILENAME, isAbsence, isSkippedEntry, type IFsProbe, type ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { withoutIgnoreLine } from './template-files.step.js';
 import { PluginLayout, hasManifestEntry } from './plugin-layout.js';
 
@@ -163,10 +163,18 @@ export class GroupsToPluginsStep implements OnServerStart {
   /** The plugin-shaped questions, answered the same way the manifests step answers them. */
   private readonly layout: PluginLayout;
 
-  constructor(private readonly disk: IFsProbe & ITreeWalker) {
+  constructor(
+    private readonly disk: IFsProbe & ITreeWalker,
+    /** Read per run, never captured: the setup-completing save may rename the plugins root first. */
+    private readonly kb: Pick<KbContext, 'layout'>,
+  ) {
     this.layout = new PluginLayout(disk);
   }
 
+  private get pluginsDir(): string {
+    return this.kb.layout.pluginsDir;
+  }
+
   async run(ctx: ServerStartContext): Promise<StepResult> {
     const refusals: string[] = [];
     for (const branch of await ctx.allBranches()) {
@@ -184,7 +192,7 @@ export class GroupsToPluginsStep implements OnServerStart {
   private async migrateBranch(branch: KbBranch, refusals: string[]): Promise<void> {
     const repoDir = await branch.repoDir();
     const legacyDir = path.join(repoDir, LEGACY_GROUPS_DIR);
-    const pluginsDir = path.join(repoDir, PLUGINS_DIR);
+    const pluginsDir = path.join(repoDir, this.pluginsDir);
 
     const hasLegacy = await this.disk.isDirectory(legacyDir);
     const hasPlugins = await this.disk.isDirectory(pluginsDir);
@@ -199,9 +207,9 @@ export class GroupsToPluginsStep implements OnServerStart {
     // template-files.step.ts's reserved-dir check).
     if (!hasPlugins && (await this.disk.exists(pluginsDir))) {
       throw new Error(
-        `Branch "${branch.name}": "${PLUGINS_DIR}" exists but is not a directory` +
-          (hasLegacy ? `, so ${LEGACY_GROUPS_DIR}/ cannot be renamed to ${PLUGINS_DIR}/` : '') +
-          `. Remove or rename the "${PLUGINS_DIR}" entry — the platform requires this name to be a folder.`,
+        `Branch "${branch.name}": "${this.pluginsDir}" exists but is not a directory` +
+          (hasLegacy ? `, so ${LEGACY_GROUPS_DIR}/ cannot be renamed to ${this.pluginsDir}/` : '') +
+          `. Remove or rename the "${this.pluginsDir}" entry — the platform requires this name to be a folder.`,
       );
     }
 
@@ -216,7 +224,7 @@ export class GroupsToPluginsStep implements OnServerStart {
     // branch with both roots (refused below) or neither (nothing to migrate)
     // is no less stale. Idempotent: nothing to drop, nothing declared.
     const changed = await this.retireIgnoreRootRules(repoDir, branch, details);
-    const retiredSubject = `Retire the stale ${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ ignore rules`;
+    const retiredSubject = `Retire the stale ${LEGACY_GROUPS_DIR}/ and ${this.pluginsDir}/ ignore rules`;
 
     if (hasLegacy && hasPlugins) {
       // Both present: somebody is mid-migration by hand, or two branches merged
@@ -226,12 +234,12 @@ export class GroupsToPluginsStep implements OnServerStart {
       // ops, only a note (which surfaces in a commit only if the ignore
       // retirement above, or a later step, dirties it).
       log.warn(
-        `${branch.name}: both ${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ exist — leaving both alone. ` +
-          `Merge ${LEGACY_GROUPS_DIR}/ into ${PLUGINS_DIR}/ by hand; nothing is being migrated automatically.`,
+        `${branch.name}: both ${LEGACY_GROUPS_DIR}/ and ${this.pluginsDir}/ exist — leaving both alone. ` +
+          `Merge ${LEGACY_GROUPS_DIR}/ into ${this.pluginsDir}/ by hand; nothing is being migrated automatically.`,
       );
       if (changed) branch.note(retiredSubject);
       branch.note(
-        `${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ both exist — merge by hand; nothing was migrated automatically`,
+        `${LEGACY_GROUPS_DIR}/ and ${this.pluginsDir}/ both exist — merge by hand; nothing was migrated automatically`,
       );
       for (const line of details) branch.note(line);
       return;
@@ -255,8 +263,8 @@ export class GroupsToPluginsStep implements OnServerStart {
     let migrated = false;
     if (hasLegacy) {
       // The Groups→Plugins root rename is ONE declared op, directory and all.
-      branch.move(LEGACY_GROUPS_DIR, PLUGINS_DIR);
-      details.push(`${LEGACY_GROUPS_DIR}/ → ${PLUGINS_DIR}/`);
+      branch.move(LEGACY_GROUPS_DIR, this.pluginsDir);
+      details.push(`${LEGACY_GROUPS_DIR}/ → ${this.pluginsDir}/`);
       migrated = true;
     }
 
@@ -284,9 +292,9 @@ export class GroupsToPluginsStep implements OnServerStart {
     // was not reorganised.
     branch.note(
       hasLegacy
-        ? `Move ${LEGACY_GROUPS_DIR}/ to ${PLUGINS_DIR}/ (Agent Plugins layout)`
+        ? `Move ${LEGACY_GROUPS_DIR}/ to ${this.pluginsDir}/ (Agent Plugins layout)`
         : migrated
-          ? `Reorganise ${PLUGINS_DIR}/ to the Agent Plugins layout`
+          ? `Reorganise ${this.pluginsDir}/ to the Agent Plugins layout`
           : retiredSubject,
     );
     for (const line of details) branch.note(line);
@@ -321,7 +329,7 @@ export class GroupsToPluginsStep implements OnServerStart {
       if (isAbsence(err)) return false;
       throw err;
     }
-    const stale = [`${LEGACY_GROUPS_DIR}/`, `${PLUGINS_DIR}/`];
+    const stale = [`${LEGACY_GROUPS_DIR}/`, `${this.pluginsDir}/`];
     const present = stale.filter((rule) => current.split('\n').some((l) => l.trim() === rule));
     if (present.length === 0) return false;
     // The same drop the template step makes, so a platform comment above a
@@ -344,7 +352,7 @@ export class GroupsToPluginsStep implements OnServerStart {
     details: string[],
     refusals: string[],
   ): Promise<boolean> {
-    const relPlugin = `${PLUGINS_DIR}/${folderName}`;
+    const relPlugin = `${this.pluginsDir}/${folderName}`;
     let changed = false;
 
     const entries = await this.disk.listDir(folderDir);

package/src/modules/workspace/startup/steps/personal-spaces.step.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { PLUGINS_DIR, isPersonalPluginFolder } from '@bevel-software/platform-shared';
+import { isPersonalPluginFolder } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import {
   EVERYONE_CANONICAL,
   KNOWN_VERBS,
@@ -41,7 +42,15 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
 export class PersonalSpacesStep implements OnServerStart {
   readonly name = 'personal-spaces';
 
-  constructor(private readonly disk: IFsProbe) {}
+  constructor(
+    private readonly disk: IFsProbe,
+    /** Read per run, never captured: the setup-completing save may rename the plugins root first. */
+    private readonly kb: Pick<KbContext, 'layout'>,
+  ) {}
+
+  private get pluginsDir(): string {
+    return this.kb.layout.pluginsDir;
+  }
 
   async run(ctx: ServerStartContext): Promise<StepResult> {
     for (const branch of await ctx.allBranches()) {
@@ -52,12 +61,12 @@ export class PersonalSpacesStep implements OnServerStart {
 
   private async closePersonalSpaces(branch: KbBranch): Promise<void> {
     const repoDir = await branch.repoDir();
-    const entries = await this.disk.listDir(path.join(repoDir, PLUGINS_DIR));
+    const entries = await this.disk.listDir(path.join(repoDir, this.pluginsDir));
     if (entries === null) return;
     const closed: string[] = [];
     for (const entry of entries) {
       if (!entry.isDirectory() || !isPersonalPluginFolder(entry.name)) continue;
-      const rel = `${PLUGINS_DIR}/${entry.name}/access.md`;
+      const rel = `${this.pluginsDir}/${entry.name}/access.md`;
       let text: string;
       try {
         text = await fs.readFile(path.join(repoDir, rel), 'utf8');
@@ -72,7 +81,7 @@ export class PersonalSpacesStep implements OnServerStart {
     }
     if (closed.length === 0) return;
     branch.note(`Keep ${closed.length === 1 ? 'a personal space' : `${closed.length} personal spaces`} private`);
-    for (const name of closed) branch.note(`${PLUGINS_DIR}/${name}/access.md: read denies everyone`);
+    for (const name of closed) branch.note(`${this.pluginsDir}/${name}/access.md: read denies everyone`);
   }
 }
 

package/src/modules/workspace/startup/steps/plugin-display-names.step.ts

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import {
-  PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
   pluginDisplayNameOf,
 } from '@bevel-software/platform-shared';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { hasManifestEntry } from './plugin-layout.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
@@ -52,7 +52,15 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
 export class PluginDisplayNamesStep implements OnServerStart {
   readonly name = 'plugin-display-names';
 
-  constructor(private readonly disk: IFsProbe & ITreeWalker) {}
+  constructor(
+    private readonly disk: IFsProbe & ITreeWalker,
+    /** Read per run, never captured: the setup-completing save may rename the plugins root first. */
+    private readonly kb: Pick<KbContext, 'layout'>,
+  ) {}
+
+  private get pluginsDir(): string {
+    return this.kb.layout.pluginsDir;
+  }
 
   async run(ctx: ServerStartContext): Promise<StepResult> {
     for (const branch of await ctx.allBranches()) {
@@ -63,7 +71,7 @@ export class PluginDisplayNamesStep implements OnServerStart {
 
   private async backfill(branch: KbBranch): Promise<void> {
     const repoDir = await branch.repoDir();
-    const root = path.join(repoDir, PLUGINS_DIR);
+    const root = path.join(repoDir, this.pluginsDir);
 
     // Plugin folders by the judgement discovery makes, entry for entry: a
     // manifest as a REGULAR file, and nothing beneath a plugin is a plugin.
@@ -119,7 +127,7 @@ export class PluginDisplayNamesStep implements OnServerStart {
       // the file for no change anyone can see.
       if (folderName === pluginDisplayNameOf(manifest)) continue;
       branch.write(
-        `${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`,
+        `${this.pluginsDir}/${rel}/${PLUGIN_MANIFEST_FILE}`,
         `${JSON.stringify(withDisplayName(manifest, folderName), null, 2)}\n`,
       );
       filled.push(rel);
@@ -131,7 +139,7 @@ export class PluginDisplayNamesStep implements OnServerStart {
         ? "Record a plugin's display name in its manifest"
         : `Record the display names of ${filled.length} plugins in their manifests`,
     );
-    for (const rel of filled) branch.note(`${PLUGINS_DIR}/${rel}: displayName "${path.posix.basename(rel)}"`);
+    for (const rel of filled) branch.note(`${this.pluginsDir}/${rel}: displayName "${path.posix.basename(rel)}"`);
   }
 }
 

package/src/modules/workspace/startup/steps/plugin-manifests.step.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
-import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, renderPluginManifest } from '@bevel-software/platform-shared';
+import { PLUGIN_MANIFEST_FILE, renderPluginManifest } from '@bevel-software/platform-shared';
 import type { ITreeWalker, WalkedEntry } from '../../../../shared/fs.contract.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { PluginLayout, hasManifestEntry } from './plugin-layout.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
@@ -39,10 +40,18 @@ export class PluginManifestsStep implements OnServerStart {
 
   private readonly layout: PluginLayout;
 
-  constructor(private readonly disk: ITreeWalker) {
+  constructor(
+    private readonly disk: ITreeWalker,
+    /** Read per run, never captured: the setup-completing save may rename the plugins root first. */
+    private readonly kb: Pick<KbContext, 'layout'>,
+  ) {
     this.layout = new PluginLayout(disk);
   }
 
+  private get pluginsDir(): string {
+    return this.kb.layout.pluginsDir;
+  }
+
   async run(ctx: ServerStartContext): Promise<StepResult> {
     for (const branch of await ctx.allBranches()) {
       await this.addManifests(branch);
@@ -52,7 +61,7 @@ export class PluginManifestsStep implements OnServerStart {
 
   private async addManifests(branch: KbBranch): Promise<void> {
     const repoDir = await branch.repoDir();
-    const root = path.join(repoDir, PLUGINS_DIR);
+    const root = path.join(repoDir, this.pluginsDir);
     const added: string[] = [];
 
     // A plugin is a folder whose OWN listing holds a manifest as a regular
@@ -78,13 +87,13 @@ export class PluginManifestsStep implements OnServerStart {
       // A grouping folder — plugins beneath it — is never a plugin itself.
       if (plugins.some((p) => p.startsWith(`${rel}/`))) continue;
       if (!(await this.layout.looksLikeLegacyPlugin(path.join(root, rel), entries))) continue;
-      branch.write(`${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`, renderPluginManifest(rel));
+      branch.write(`${this.pluginsDir}/${rel}/${PLUGIN_MANIFEST_FILE}`, renderPluginManifest(rel));
       added.push(rel);
     }
     if (added.length === 0) return;
     branch.note(
       `Add plugin manifests to ${added.length === 1 ? 'a legacy plugin folder' : `${added.length} legacy plugin folders`}`,
     );
-    for (const rel of added) branch.note(`${PLUGINS_DIR}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
+    for (const rel of added) branch.note(`${this.pluginsDir}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
   }
 }

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,11 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
-  AGENTS_FILE,
   LEGACY_AGENTS_FILE,
   renderKbLayoutPlaceholders,
 } from '@bevel-software/platform-shared';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import { reservedRootDirs } from './template-files.step.js';
 import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource } from './template-source.js';
@@ -36,11 +36,12 @@ export function buildSeedTree(
   templateDir: string,
   extraRootDirs: readonly string[],
   seedAdminEmails: readonly string[],
+  /** Read per seed, never captured: the setup-completing save may apply the layout after this builder was composed. */
+  kb: Pick<KbContext, 'layout'>,
 ): (dir: string) => Promise<string[]> {
-  // Validated eagerly; resolved per seed. The core roots are live bindings the
-  // setup-completing save may configure after this builder was composed.
-  reservedRootDirs(extraRootDirs);
-  const seeder = new KbSeedTree(disk, new TemplateSource(disk, templateDir), extraRootDirs, seedAdminEmails);
+  // Validated eagerly; resolved per seed.
+  reservedRootDirs(extraRootDirs, kb.layout);
+  const seeder = new KbSeedTree(disk, new TemplateSource(disk, templateDir, kb), extraRootDirs, seedAdminEmails, kb);
   return (dir) => seeder.seed(dir);
 }
 
@@ -58,6 +59,7 @@ class KbSeedTree {
     private readonly templates: TemplateSource,
     private readonly extraRootDirs: readonly string[],
     private readonly seedAdminEmails: readonly string[],
+    private readonly kb: Pick<KbContext, 'layout'>,
   ) {}
 
   /** Fill `dir` with a complete knowledge base; resolve to what was GENERATED. */
@@ -72,7 +74,7 @@ class KbSeedTree {
     // root never gets a pointless placeholder beside it.
     // Resolved NOW, not when the builder was composed: a seed that runs on the
     // save completing first-run setup must lay down the names that save applied.
-    for (const rootDir of reservedRootDirs(this.extraRootDirs)) {
+    for (const rootDir of reservedRootDirs(this.extraRootDirs, this.kb.layout)) {
       const abs = path.join(dir, rootDir);
       const found = await this.disk.lstatOrNull(abs);
       if (found) {
@@ -149,7 +151,7 @@ class KbSeedTree {
     // `AGENTS.md` this seed had just laid down — two commits saying opposite
     // things about a knowledge base nobody had used yet.
     if (relDir === '' && name === LEGACY_AGENTS_FILE) {
-      await this.copyTemplateFile(name, dest, AGENTS_FILE);
+      await this.copyTemplateFile(name, dest, this.kb.layout.agentsFile);
       return;
     }
     // TWO template entries, ONE destination. A custom template that happens to
@@ -161,7 +163,7 @@ class KbSeedTree {
     // is the file the platform owns, refreshes from the packaged template on
     // every start and tells every agent to read. The twin is skipped, on the
     // same reasoning as the packable spelling above.
-    if (relDir === '' && name === AGENTS_FILE && (await this.templates.carries(LEGACY_AGENTS_FILE))) {
+    if (relDir === '' && name === this.kb.layout.agentsFile && (await this.templates.carries(LEGACY_AGENTS_FILE))) {
       return;
     }
     await this.copyTemplateFile(relDir ? path.join(relDir, name) : name, dest);
@@ -190,7 +192,7 @@ class KbSeedTree {
     if (text === null) {
       await fs.copyFile(from, to);
     } else {
-      await fs.writeFile(to, renderKbLayoutPlaceholders(text), 'utf8');
+      await fs.writeFile(to, renderKbLayoutPlaceholders(text, this.kb.layout), 'utf8');
     }
     await fs.chmod(to, (await fs.stat(from)).mode & 0o777);
   }

package/src/modules/workspace/startup/steps/template-files.step.ts

@@ -1,18 +1,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
-  AGENTS_FILE,
-  KNOWLEDGE_BASE_DIR,
   LEGACY_AGENTS_FILE,
-  PLUGINS_DIR,
-  SKILLS_DIR,
   agentsFilePointerSentence,
   gitignoreLiteral,
   mentionsAgentsFile,
   retargetAgentsFilePointer,
   validateKbRootName,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
 import { TemplateSource } from './template-source.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
@@ -38,14 +36,14 @@ const PREAMBLE_IGNORE_PATTERN = `/${PREAMBLE_FILE}`;
  * generated from `ADMIN_EMAIL` (see roles-yaml.step.ts), so a repo can't be
  * seeded with a stale hard-coded Admin list.
  */
-export function requiredFiles(): readonly string[] {
+export function requiredFiles(layout: Required<KbLayout>): readonly string[] {
   return [
     'access.md',
     // The managed agent guide, under whatever this deployment calls it. The
     // PACKAGED template still carries it as `AGENTS.md` — one file, one
     // spelling in the tarball — so the write target and the template source
     // part company here and nowhere else (see {@link templateNameOf}).
-    AGENTS_FILE,
+    layout.agentsFile,
     '.bevelignore',
     '.gitignore',
     // The deployment preamble every connected agent is told at session start
@@ -61,8 +59,8 @@ export function requiredFiles(): readonly string[] {
  * name on disk is a deployment's choice while its name in the template is
  * fixed; everything else is spelled the same on both sides.
  */
-function templateNameOf(repoRel: string): string {
-  return repoRel === AGENTS_FILE ? LEGACY_AGENTS_FILE : repoRel;
+function templateNameOf(repoRel: string, agentsFile: string): string {
+  return repoRel === agentsFile ? LEGACY_AGENTS_FILE : repoRel;
 }
 
 /**
@@ -105,11 +103,11 @@ export const GENERATED_FILES: readonly string[] = ['roles.yaml'];
  * that has them still renders them as roots rather than folding them into
  * Knowledge.
  *
- * A function: the three names are deployment-configurable live bindings, and
+ * A function of the layout: the three names are deployment-configurable, and
  * a module-scope array would snapshot the defaults before configuration.
  */
-function coreRequiredDirs(): readonly string[] {
-  return [KNOWLEDGE_BASE_DIR, SKILLS_DIR, PLUGINS_DIR];
+function coreRequiredDirs(layout: Required<KbLayout>): readonly string[] {
+  return [layout.knowledgeBaseDir, layout.skillsDir, layout.pluginsDir];
 }
 
 /**
@@ -145,20 +143,20 @@ function assertRootSegment(dir: string): void {
  * base. Shared with the empty-remote seed builder (seed-tree.ts) so the two
  * paths can never disagree about what a deployment guarantees.
  */
-export function reservedRootDirs(extraRootDirs: readonly string[]): readonly string[] {
+export function reservedRootDirs(extraRootDirs: readonly string[], layout: Required<KbLayout>): readonly string[] {
   for (const dir of extraRootDirs) {
     assertRootSegment(dir);
     // A root named after a required OR generated FILE is a typo with a silent
     // outcome: the file is laid down first, so the dir check finds the path
     // taken and skips it, and the directory the caller asked for never appears
     // with nothing said about why.
-    if (requiredFiles().includes(dir) || GENERATED_FILES.includes(dir)) {
+    if (requiredFiles(layout).includes(dir) || GENERATED_FILES.includes(dir)) {
       throw new Error(
         `Reserved KB root "${dir}" collides with a required or generated file of the same name`,
       );
     }
   }
-  return [...coreRequiredDirs(), ...extraRootDirs];
+  return [...coreRequiredDirs(layout), ...extraRootDirs];
 }
 
 /**
@@ -195,15 +193,18 @@ export class TemplateFilesStep implements OnServerStart {
    */
   constructor(
     private readonly disk: IFsProbe,
+    /**
+     * Read per run, never captured: the save that completes first-run setup
+     * applies the admin's names after this step was built. A snapshot taken
+     * here scaffolded `Skills/` beside the `skills/` they had just chosen.
+     */
+    private readonly kb: Pick<KbContext, 'layout'>,
     private readonly extraRootDirs: readonly string[] = [],
     private readonly agentsFileLink: () => boolean = () => true,
   ) {
     // Validated NOW, so a bad extra fails at boot beside the rest of the
-    // wiring — but the list itself is NOT kept: the core roots are live
-    // bindings, and the save that completes first-run setup applies the
-    // admin's names after this step was built. A snapshot taken here
-    // scaffolded `Skills/` beside the `skills/` they had just chosen.
-    reservedRootDirs(extraRootDirs);
+    // wiring — but the list itself is NOT kept, for the reason `kb` says.
+    reservedRootDirs(extraRootDirs, kb.layout);
   }
 
   async run(ctx: ServerStartContext): Promise<StepResult> {
@@ -217,15 +218,16 @@ export class TemplateFilesStep implements OnServerStart {
     // The template directory is runtime data (the start context's), the disk
     // port is the injected dependency — bound together once here so nothing
     // below has to carry either as an argument.
-    const templates = new TemplateSource(this.disk, templateDir);
+    const templates = new TemplateSource(this.disk, templateDir, this.kb);
     const repoDir = await branch.repoDir();
     const added: string[] = [];
-    // Read ONCE per branch: the name is a live binding, and a value re-read
-    // between the write and the ignore rule could disagree with itself.
-    const agentsFile = AGENTS_FILE;
+    // Read ONCE per branch: a value re-read between the write and the ignore
+    // rule could disagree with itself.
+    const layout = this.kb.layout;
+    const agentsFile = layout.agentsFile;
     const renamed = agentsFile !== LEGACY_AGENTS_FILE;
 
-    for (const rel of requiredFiles()) {
+    for (const rel of requiredFiles(layout)) {
       // `lstat`, not `exists`: a DIRECTORY or SYMLINK squatting a required
       // file's name would read as "present", and a skip-if-present check
       // would then report success over a knowledge base whose root access
@@ -240,7 +242,7 @@ export class TemplateFilesStep implements OnServerStart {
             'Remove or rename it — the platform requires this name to be a readable file.',
         );
       }
-      let content = await templates.read(templateNameOf(rel));
+      let content = await templates.read(templateNameOf(rel, agentsFile));
       // The on-disk merge below only runs against an EXISTING ignore file; a
       // freshly-declared one was merely assumed to carry the guide's rule —
       // true of the packaged template, not necessarily of a distribution's
@@ -259,10 +261,14 @@ export class TemplateFilesStep implements OnServerStart {
         content = withPlatformIgnorePatternRespelled(content, PREAMBLE_FILE, PREAMBLE_IGNORE_PATTERN);
         content = withoutIgnoreLine(
           withoutPlatformIgnorePattern(
-            withIgnorePattern(withIgnorePattern(content, gitignoreLiteral(agentsFile)), PREAMBLE_IGNORE_PATTERN),
-            `${SKILLS_DIR}/`,
+            withIgnorePattern(
+              withIgnorePattern(content, gitignoreLiteral(agentsFile), agentsFile),
+              PREAMBLE_IGNORE_PATTERN,
+              agentsFile,
+            ),
+            `${layout.skillsDir}/`,
           ),
-          `${PLUGINS_DIR}/`,
+          `${layout.pluginsDir}/`,
         );
         // …and a template (a distribution's, a stale packaged one) still
         // hiding `AGENTS.md` while this deployment's guide is called something
@@ -316,8 +322,8 @@ export class TemplateFilesStep implements OnServerStart {
         // As a gitignore PATTERN: a guide name that reads as syntax there is
         // escaped, or the rule would hide nothing.
         add: [gitignoreLiteral(agentsFile), PREAMBLE_IGNORE_PATTERN],
-        drop: [`${SKILLS_DIR}/`],
-        dropEvery: [`${PLUGINS_DIR}/`],
+        drop: [`${this.kb.layout.skillsDir}/`],
+        dropEvery: [`${this.kb.layout.pluginsDir}/`],
         // The guide's rule FOLLOWS its name. Once the guide is `HEXIS.md`, the
         // root's `AGENTS.md` is the customer's own conventions file and they
         // must be able to see and edit it in the app — so the platform's own
@@ -472,7 +478,7 @@ export class TemplateFilesStep implements OnServerStart {
    */
   private async missingDirs(repoDir: string): Promise<string[]> {
     const missing: string[] = [];
-    for (const rootDir of reservedRootDirs(this.extraRootDirs)) {
+    for (const rootDir of reservedRootDirs(this.extraRootDirs, this.kb.layout)) {
       const found = await this.disk.lstatOrNull(path.join(repoDir, rootDir));
       if (found) {
         if (found.isDirectory()) continue;
@@ -547,7 +553,10 @@ export class TemplateFilesStep implements OnServerStart {
       (text, [from, to]) => withPlatformIgnorePatternRespelled(text, from, to),
       current,
     );
-    const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern), respelled);
+    const added = rules.add.reduce(
+      (text, pattern) => withIgnorePattern(text, pattern, this.kb.layout.agentsFile),
+      respelled,
+    );
     const dropped = (rules.dropEvery ?? []).reduce(
       (text, pattern) => withoutIgnoreLine(text, pattern),
       rules.drop.reduce((text, pattern) => withoutPlatformIgnorePattern(text, pattern), added),
@@ -796,7 +805,7 @@ function withPlatformIgnorePatternRespelled(text: string, from: string, to: stri
  * still standing here is the operator's: it already hides the file, and
  * appending the anchored rule beside it would say nothing they have not.
  */
-function withIgnorePattern(text: string, pattern: string): string {
+function withIgnorePattern(text: string, pattern: string, agentsFile: string): string {
   const lines = text.split('\n').map((l) => l.trim());
   const operatorPreambleRule =
     pattern === PREAMBLE_IGNORE_PATTERN &&
@@ -808,7 +817,7 @@ function withIgnorePattern(text: string, pattern: string): string {
   const comment =
     pattern === PREAMBLE_IGNORE_PATTERN
       ? PREAMBLE_RULE_COMMENT
-      : pattern === gitignoreLiteral(AGENTS_FILE)
+      : pattern === gitignoreLiteral(agentsFile)
         ? AGENTS_RULE_COMMENT
         : PLATFORM_RULE_COMMENT;
   return `${text}${separator}\n${comment}\n${pattern}\n`;

package/src/modules/workspace/startup/steps/template-source.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
-import { agentsFileOf, currentKbLayout, gitignoreLiteral, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
+import { gitignoreLiteral, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type EntryStat, type IFsProbe } from '../../../../shared/fs.contract.js';
+import type { KbContext } from '../../../../shared/kb-context.js';
 import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
 import { defaultKbTemplateDir } from '../../../../assets.js';
 import { logger } from '../../../../shared/logging.js';
@@ -57,6 +58,8 @@ export class TemplateSource {
   constructor(
     private readonly disk: IFsProbe,
     private readonly templateDir: string,
+    /** The layout the placeholders render as — read per file, so a name applied by setup is the one written. */
+    private readonly kb: Pick<KbContext, 'layout'>,
   ) {}
 
   /**
@@ -125,7 +128,7 @@ export class TemplateSource {
       );
       // The packaged copy, read the same way — it renders its own
       // placeholders and cannot fall back again (its guard is this one).
-      return new TemplateSource(this.disk, packaged).read(relPath);
+      return new TemplateSource(this.disk, packaged, this.kb).read(relPath);
     }
     // In the ignore file the guide's name is a PATTERN, and a name gitignore
     // reads as syntax (`#Guide.md`, `!Guide.md`, brackets) would hide nothing
@@ -133,11 +136,11 @@ export class TemplateSource {
     // placeholder is prose. ONE render, with the escaped name as the layout's
     // — a second pass over the rendered text would read a name that happens
     // to contain a placeholder as one.
+    const layout = this.kb.layout;
     if (relPath === IGNORE_FILENAME) {
-      const layout = currentKbLayout();
-      return renderKbLayoutPlaceholders(raw, { ...layout, agentsFile: gitignoreLiteral(agentsFileOf(layout)) });
+      return renderKbLayoutPlaceholders(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
     }
-    return renderKbLayoutPlaceholders(raw);
+    return renderKbLayoutPlaceholders(raw, layout);
   }
 
   /**