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

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

@@ -1,14 +1,25 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
+  AGENTS_FILE,
   KNOWLEDGE_BASE_DIR,
+  LEGACY_AGENTS_FILE,
   PLUGINS_DIR,
   SKILLS_DIR,
-  renderKbLayoutPlaceholders,
+  agentsFilePointerSentence,
+  gitignoreLiteral,
+  mentionsAgentsFile,
+  retargetAgentsFilePointer,
   validateKbRootName,
 } from '@bevel-software/platform-shared';
-import { IGNORE_FILENAME } from '../../bevel-ignore.js';
+import { IGNORE_FILENAME, isAbsence, type IFsProbe } from '../../../../shared/fs.contract.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';
+import { hasGitInternalsSegment } from '../../../../shared/git-internals.js';
+
+/** Root-anchored so a knowledge folder may still contain an ordinary namesake. */
+const PREAMBLE_IGNORE_PATTERN = `/${PREAMBLE_FILE}`;
 
 /**
  * The **required scaffolding** — the minimum an operational KB needs. Any of
@@ -16,7 +27,7 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
  * sample ontology is NOT (it only seeds a fully-empty repo, see seed-tree.ts).
  *
  * Two kinds:
- *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
+ *  - {@link requiredFiles}: repo-root files added when the file is missing.
  *  - Reserved root dirs (core's two plus a distribution's `extraRootDirs`):
  *    when a dir is entirely absent it's created by adding its `<dir>/.gitkeep`.
  *    Keyed on the *directory's* existence, not the `.gitkeep` file — so a
@@ -27,27 +38,60 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
  * generated from `ADMIN_EMAIL` (see roles-yaml.step.ts), so a repo can't be
  * seeded with a stale hard-coded Admin list.
  */
-export const REQUIRED_FILES: readonly string[] = ['access.md', 'AGENTS.md', '.bevelignore', '.gitignore'];
+export function requiredFiles(): 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,
+    '.bevelignore',
+    '.gitignore',
+    // The deployment preamble every connected agent is told at session start
+    // (see modules/agent-instructions). Seeded ONCE and never refreshed: the
+    // content is the admin's, and the shipped template is one HTML comment, so
+    // a never-edited file sends nothing of its own.
+    PREAMBLE_FILE,
+  ];
+}
+
+/**
+ * The template's own name for a required file. The guide is the one file whose
+ * 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;
+}
+
+/**
+ * The sentence the managed guide carries about itself, and the ONLY thing that
+ * makes a root `AGENTS.md` provably the platform's rather than the customer's.
+ *
+ * Matched on this one phrase rather than on the whole header: the lines around
+ * it have changed between releases (they name the configured file now), and a
+ * knowledge base seeded by any of those releases is still ours to remove. A
+ * customer file would have to quote the platform's own claim about itself
+ * verbatim to be mistaken for one, and the consequence of the mistake is a
+ * deletion — which is why nothing looser will do.
+ */
+const MANAGED_GUIDE_MARKER = '**This file is managed by the platform.**';
+
+/** Whether `text` is a copy of the platform's managed guide, of any vintage. */
+export function isManagedGuide(text: string): boolean {
+  return text.includes(MANAGED_GUIDE_MARKER);
+}
 
 /**
  * Repo-root files the startup phase GENERATES rather than copies — today just
  * `roles.yaml`, rendered from `ADMIN_EMAIL` (see roles-yaml.step.ts and
  * seed-tree.ts). Reserved-root validation must treat these exactly like
- * {@link REQUIRED_FILES}: a root claiming a generated name is the same silent
+ * {@link requiredFiles}: a root claiming a generated name is the same silent
  * typo with the same silent outcome.
  */
 export const GENERATED_FILES: readonly string[] = ['roles.yaml'];
 
-/**
- * Destination name → the packable spelling the template may carry instead.
- * npm strips every file named `.gitignore` from a published tarball, so the
- * packaged template cannot ship one under its real name (see
- * {@link templateSource}).
- */
-export const TEMPLATE_SOURCE_FALLBACKS: Readonly<Record<string, string>> = {
-  '.gitignore': 'gitignore.template',
-};
-
 /**
  * The three roots CORE gives a knowledge base: the ontologies, the shared
  * skills, and the plugins that hold tools and link the skills.
@@ -83,11 +127,12 @@ function assertRootSegment(dir: string): void {
   if (!dir || dir === '.' || dir === '..' || dir.includes('/') || dir.includes('\\') || path.isAbsolute(dir)) {
     throw new Error(`Reserved KB root must be a single path segment (no separators, no ".."); got "${dir}"`);
   }
-  // `.git` can never be a KB root: writing `<dir>/.gitkeep` under it would
-  // corrupt the clone's own metadata. Any case — Windows filesystems treat
-  // `.GIT` as the same directory.
-  if (dir.toLowerCase() === '.git') {
-    throw new Error(`Reserved KB root must not be ".git" (any case); got "${dir}"`);
+  // The git folder can never be a KB root: writing `<dir>/.gitkeep` under it
+  // would corrupt the clone's own metadata. In ANY spelling that names it —
+  // any case, a trailing dot or space Windows collapses, a percent-encoded
+  // form — the one rule every path check uses (`shared/git-internals.ts`).
+  if (hasGitInternalsSegment(dir)) {
+    throw new Error(`Reserved KB root must not name the git folder (".git" in any spelling); got "${dir}"`);
   }
 }
 
@@ -107,7 +152,7 @@ export function reservedRootDirs(extraRootDirs: readonly string[]): readonly str
     // 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 (REQUIRED_FILES.includes(dir) || GENERATED_FILES.includes(dir)) {
+    if (requiredFiles().includes(dir) || GENERATED_FILES.includes(dir)) {
       throw new Error(
         `Reserved KB root "${dir}" collides with a required or generated file of the same name`,
       );
@@ -116,48 +161,11 @@ export function reservedRootDirs(extraRootDirs: readonly string[]): readonly str
   return [...coreRequiredDirs(), ...extraRootDirs];
 }
 
-/**
- * Where `relPath`'s template content actually lives. npm refuses to pack
- * files named `.gitignore` — every such file is silently stripped from the
- * published tarball — so the packaged template ships the KB's gitignore
- * under a packable name and the seeder writes it to its real one. A
- * template carrying the literal file (a distribution's own
- * KB_TEMPLATE_DIR, or this repo's tree in a Docker build) wins outright:
- * the mapping is a fallback, never a rename.
- */
-export async function templateSource(templateDir: string, relPath: string): Promise<string> {
-  const direct = path.join(templateDir, relPath);
-  if (await exists(direct)) return direct;
-  const packable = TEMPLATE_SOURCE_FALLBACKS[relPath];
-  if (packable !== undefined) {
-    const fallback = path.join(templateDir, packable);
-    if (await exists(fallback)) return fallback;
-  }
-  return direct; // let the ENOENT surface under the name the caller asked for
-}
-
-async function exists(p: string): Promise<boolean> {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** `lstat` without the throw — null when nothing is at `p`. */
-async function lstatOrNull(p: string): Promise<import('node:fs').Stats | null> {
-  try {
-    return await fs.lstat(p);
-  } catch {
-    return null;
-  }
-}
-
 /**
  * The template top-up as an {@link OnServerStart} step: add any missing base
- * scaffolding to every PROTECTED branch, and keep the managed AGENTS.md
- * current. Drafts are deliberately out of scope — whatever the protected
+ * scaffolding to every PROTECTED branch, and keep the managed agent guide
+ * current — under whatever this deployment calls it, and taking its own
+ * stale `AGENTS.md` with it when that name was handed back to the customer. Drafts are deliberately out of scope — whatever the protected
  * branches gain, drafts fork from; a scaffolding addition on a draft would
  * surface as noise in its change request's diff. (Unlike the Groups→Plugins
  * rename, a missing file diffs as one file, not the whole tree — so the
@@ -172,8 +180,6 @@ async function lstatOrNull(p: string): Promise<import('node:fs').Stats | null> {
 export class TemplateFilesStep implements OnServerStart {
   readonly name = 'template-files';
 
-  private readonly requiredDirs: readonly string[];
-
   /**
    * @param extraRootDirs Additional root folders this distribution reserves,
    *                      on top of core's two. Their `.gitkeep` is written
@@ -181,8 +187,23 @@ export class TemplateFilesStep implements OnServerStart {
    *                      claim a root without also shipping a template entry
    *                      for it.
    */
-  constructor(extraRootDirs: readonly string[] = []) {
-    this.requiredDirs = reservedRootDirs(extraRootDirs);
+  /**
+   * @param agentsFileLink Whether to keep the platform's pointer sentence in a
+   *                       customer-owned root `AGENTS.md` — a GETTER, because
+   *                       the setting behind it may be saved by the very
+   *                       first-run save that then runs this phase.
+   */
+  constructor(
+    private readonly disk: IFsProbe,
+    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);
   }
 
   async run(ctx: ServerStartContext): Promise<StepResult> {
@@ -193,16 +214,24 @@ export class TemplateFilesStep implements OnServerStart {
   }
 
   private async topUp(templateDir: string, branch: KbBranch): Promise<void> {
+    // 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 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;
+    const renamed = agentsFile !== LEGACY_AGENTS_FILE;
 
-    for (const rel of REQUIRED_FILES) {
+    for (const rel of requiredFiles()) {
       // `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
       // policy (say) cannot be read. Fail-closed, same as the reserved-root
       // squatting check below: this is a state a human must fix.
-      const found = await lstatOrNull(path.join(repoDir, rel));
+      const found = await this.disk.lstatOrNull(path.join(repoDir, rel));
       if (found) {
         if (found.isFile()) continue;
         throw new Error(
@@ -211,32 +240,52 @@ export class TemplateFilesStep implements OnServerStart {
             'Remove or rename it — the platform requires this name to be a readable file.',
         );
       }
-      let content = await readTemplate(templateDir, rel);
+      let content = await templates.read(templateNameOf(rel));
       // The on-disk merge below only runs against an EXISTING ignore file; a
-      // freshly-declared one was merely assumed to carry the AGENTS.md rule —
+      // freshly-declared one was merely assumed to carry the guide's rule —
       // true of the packaged template, not necessarily of a distribution's
       // custom one. Make it true here, so the managed conventions doc is
-      // hidden from the file tree from the first boot either way.
+      // hidden from the file tree from the first boot either way. The same is
+      // true of the deployment preamble: it is edited through External agent
+      // access, not as an ordinary knowledge-base document.
       // …and a template still shipping the skills rule an earlier release
       // had (a distribution's copy, a stale packaged one) must not declare
       // it: the on-disk reconciliation below never sees a file that was
       // absent, so the declared content is reconciled here instead.
       if (rel === IGNORE_FILENAME) {
-        content = withoutPlatformIgnorePattern(withIgnorePattern(content, 'AGENTS.md'), `${SKILLS_DIR}/`);
+        // A template still shipping the unanchored preamble rule an earlier
+        // release had is respelled first, so the guarantee below adds nothing
+        // beside it.
+        content = withPlatformIgnorePatternRespelled(content, PREAMBLE_FILE, PREAMBLE_IGNORE_PATTERN);
+        content = withoutIgnoreLine(
+          withoutPlatformIgnorePattern(
+            withIgnorePattern(withIgnorePattern(content, gitignoreLiteral(agentsFile)), PREAMBLE_IGNORE_PATTERN),
+            `${SKILLS_DIR}/`,
+          ),
+          `${PLUGINS_DIR}/`,
+        );
+        // …and a template (a distribution's, a stale packaged one) still
+        // hiding `AGENTS.md` while this deployment's guide is called something
+        // else would hide the CUSTOMER'S file from the first boot — the exact
+        // thing the rename exists to prevent.
+        if (renamed) content = withoutPlatformAgentsRule(content);
       }
       branch.write(rel, content);
       added.push(rel);
     }
 
-    // AGENTS.md left VISIBLE by a stale `.bevelignore` is closed here — and
+    // The guide or mcp-description.md left VISIBLE by a stale `.bevelignore`
+    // is closed here — and
     // UNCONDITIONALLY, not only when the file was just added: a KB whose
-    // AGENTS.md predates the CLAUDE.md→AGENTS.md rename has an ignore file
+    // guide predates the CLAUDE.md→AGENTS.md rename has an ignore file
     // that lists the old name and knows nothing of the new one, so the
-    // conventions doc shows up in the file tree and the agent view.
+    // conventions doc shows up in the file tree and the agent view. A KB
+    // whose deployment has just RENAMED the guide is the same story one
+    // rename later: the rule names a file that is now the customer's.
     // Idempotent: an ignore file already carrying the rule — or absent, in
     // which case the template's copy declared above arrives with the rule in
     // it — changes nothing and produces no note. Deliberately checked by
-    // LINE PRESENCE, not effective outcome: a later `!AGENTS.md` negation is
+    // LINE PRESENCE, not effective outcome: a later `!<guide>` negation is
     // the operator explicitly choosing to SHOW the file, and hiding it is a
     // default this step provides, not a mandate it re-imposes every boot.
     //
@@ -249,22 +298,64 @@ export class TemplateFilesStep implements OnServerStart {
     // it, for the same reason the negation above is kept: the file is
     // theirs. The Knowledge explorer never rendered the root and still does
     // not. Spelled with the CONFIGURED root name, since a deployment may
-    // have renamed it. ONE read-modify-write for both rules: two passes
-    // would each read the on-disk file and the second declared write would
-    // lose the first's.
-    added.push(...(await reconcileIgnoreRules(repoDir, branch, { add: ['AGENTS.md'], drop: [`${SKILLS_DIR}/`] })));
+    // have renamed it.
+    //
+    // The plugins root follows the skills root: the same sidebar now draws
+    // it as a file tree too, so the rule that hid it since the first seed
+    // comes out. That one has no comment to know it by — it was in the
+    // template body from the start — so every line spelling it goes,
+    // whoever wrote it (see `withoutIgnoreLine`). ONE read-modify-write for
+    // all the rules: separate passes would each read the on-disk file and
+    // a later declared write would lose an earlier one's.
+    added.push(
+      ...(await this.reconcileIgnoreRules(repoDir, branch, {
+        // The preamble rule is respelled before it is added: a knowledge base
+        // that booted the release shipping the unanchored spelling carries the
+        // platform's own line, and that line hides a nested namesake too.
+        respell: [[PREAMBLE_FILE, PREAMBLE_IGNORE_PATTERN]],
+        // 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}/`],
+        // 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
+        // line comes out, recognised the way the skills-root line was
+        // (see {@link withoutPlatformAgentsRule}); a rule an operator wrote by
+        // hand is theirs and stays.
+        dropAgentsRule: renamed,
+      })),
+    );
 
-    // AGENTS.md is MANAGED, not merely seeded: the platform owns its content,
+    // The guide is MANAGED, not merely seeded: the platform owns its content,
     // and a stale copy is replaced with the packaged template's every startup
     // phase. The file's own header says so, which is what makes overwriting
     // edits a stated contract instead of a surprise.
     let agentsRefreshed = false;
-    if (!added.includes('AGENTS.md') && (await templateDiffers(templateDir, repoDir, 'AGENTS.md'))) {
-      branch.write('AGENTS.md', await readTemplate(templateDir, 'AGENTS.md'));
-      added.push('AGENTS.md');
+    if (
+      !added.includes(agentsFile) &&
+      (await templates.differsFrom(repoDir, agentsFile, LEGACY_AGENTS_FILE))
+    ) {
+      branch.write(agentsFile, await templates.read(LEGACY_AGENTS_FILE));
+      added.push(agentsFile);
       agentsRefreshed = true;
     }
 
+    // What becomes of the `AGENTS.md` the platform used to own, now that the
+    // guide lives somewhere else. Nothing at all while the name is the default.
+    if (renamed) {
+      added.push(
+        ...(await this.reconcileLegacyGuide(repoDir, branch, {
+          agentsFile,
+          // Only on the boot the rename lands — the boot that first writes the
+          // guide under its new name. Said every boot after, the "kept" note
+          // would caption commits about other things forever.
+          announceKept: added.includes(agentsFile),
+        })),
+      );
+    }
+
     added.push(...this.ensureRequiredDirs(repoDir, branch, await this.missingDirs(repoDir)));
 
     if (added.length === 0) return;
@@ -272,11 +363,102 @@ export class TemplateFilesStep implements OnServerStart {
     // first to dirty the branch.
     branch.note(
       agentsRefreshed && added.length === 1
-        ? 'Update AGENTS.md to the current platform template'
+        ? `Update ${agentsFile} to the current platform template`
         : `Add missing KB scaffolding: ${added.join(', ')}`,
     );
   }
 
+  /**
+   * The root `AGENTS.md` on a deployment whose guide is called something else:
+   * removed when the platform can PROVE it wrote it, otherwise left alone —
+   * and, while the admin keeps the link setting on, given the one sentence
+   * that points at the guide beside it.
+   *
+   * Removal is gated on the managed header and nothing else. An admin who
+   * renames the guide on a knowledge base the platform seeded would otherwise
+   * be left with stale platform content sitting under the very name they
+   * wanted for their own file; an admin who renames it on a repository whose
+   * `AGENTS.md` is their own must find that file byte-for-byte untouched. The
+   * header is the one fact that tells the two apart, so it is the one thing
+   * asked.
+   *
+   * The pointer is bounded by three conditions, all of them the customer's to
+   * control: the admin keeps the setting on, the file exists (one is NEVER
+   * created for this), and the guide's name appears nowhere in the text. That
+   * last one is a plain content search on purpose — a mention in the
+   * customer's own words, a link, a heading, all count, and the platform stays
+   * out of a file it does not own.
+   *
+   * Returns the paths changed, for the note.
+   */
+  private async reconcileLegacyGuide(
+    repoDir: string,
+    branch: KbBranch,
+    opts: { agentsFile: string; announceKept: boolean },
+  ): Promise<string[]> {
+    const legacyPath = path.join(repoDir, LEGACY_AGENTS_FILE);
+    // `lstat` first, and a REGULAR FILE or nothing at all.
+    //
+    // Nothing there is the ordinary case: no customer file means nothing to
+    // remove and nothing to point at the guide — the platform never creates an
+    // `AGENTS.md` for this.
+    //
+    // Anything that is not a plain file is left exactly as it is. A SYMLINK is
+    // the case that matters: reading one follows it, so a link pointing at a
+    // knowledge base's managed guide — or at any other file carrying the
+    // header — would read as "ours" and the removal would take the customer's
+    // entry; writing one follows it too, and the pointer sentence would land
+    // in a file at the other end that nobody asked us to edit. Links are never
+    // followed anywhere else in the platform, and they are not followed here.
+    // A directory under the name is the same answer for the same reason.
+    const found = await this.disk.lstatOrNull(legacyPath);
+    if (found === null || !found.isFile()) return [];
+
+    let current: string;
+    try {
+      current = await this.disk.readTextFile(legacyPath);
+    } catch (err) {
+      // Gone between the probe and the read — a concurrent delete reads as the
+      // absence it is, on the same terms as the probe above.
+      if (isAbsence(err)) return [];
+      throw err;
+    }
+
+    if (isManagedGuide(current)) {
+      branch.remove(LEGACY_AGENTS_FILE);
+      branch.note(`Remove the platform-written AGENTS.md — the agent guide is now ${opts.agentsFile}`);
+      return [LEGACY_AGENTS_FILE];
+    }
+
+    if (opts.announceKept) {
+      branch.note('Keep AGENTS.md — it is not a platform template, so it is the knowledge base\'s own');
+    }
+    // The admin's consent gates every write below, this file being theirs.
+    if (!this.agentsFileLink()) return [];
+
+    // A sentence of OURS already in the file is updated rather than joined by
+    // a second one. The guide's name can be changed again, and after a second
+    // rename the sentence this step wrote last time points at a file that is
+    // no longer there — which asking "is the new name mentioned?" cannot see,
+    // because the old sentence does not mention it.
+    const retargeted = retargetAgentsFilePointer(current, opts.agentsFile);
+    if (retargeted !== null) {
+      if (retargeted === current) return [];
+      branch.write(LEGACY_AGENTS_FILE, retargeted);
+      branch.note(`Point the sentence in AGENTS.md at ${opts.agentsFile}`);
+      return [LEGACY_AGENTS_FILE];
+    }
+
+    // Nothing of ours in there, so the question is the customer's own text.
+    // Asked through the shared reading, not a raw `includes`: the sentence
+    // spells the name escaped and percent-encoded, so on a punctuated name the
+    // copy written last boot need not carry the raw name at all.
+    if (mentionsAgentsFile(current, opts.agentsFile)) return [];
+    branch.write(LEGACY_AGENTS_FILE, withPointerSentence(current, opts.agentsFile));
+    branch.note(`Add a pointer to ${opts.agentsFile} at the end of AGENTS.md`);
+    return [LEGACY_AGENTS_FILE];
+  }
+
   /**
    * Which reserved roots are absent — and which are SQUATTED. `lstat`, not
    * `exists`: `fs.access` answers "is there something here?", which is true of
@@ -290,8 +472,8 @@ export class TemplateFilesStep implements OnServerStart {
    */
   private async missingDirs(repoDir: string): Promise<string[]> {
     const missing: string[] = [];
-    for (const rootDir of this.requiredDirs) {
-      const found = await lstatOrNull(path.join(repoDir, rootDir));
+    for (const rootDir of reservedRootDirs(this.extraRootDirs)) {
+      const found = await this.disk.lstatOrNull(path.join(repoDir, rootDir));
       if (found) {
         if (found.isDirectory()) continue;
         throw new Error(
@@ -319,74 +501,194 @@ export class TemplateFilesStep implements OnServerStart {
     }
     return added;
   }
+
+  /**
+   * Reconcile the platform's OWN rules in `.bevelignore`: every `respell` pair
+   * rewritten in place, every `add` pattern guaranteed present as a line, every
+   * `drop` pattern taken out. Returns the paths changed, for the note.
+   *
+   * Never rewrites the rest. The file is the operator's, and every rule already
+   * in it is theirs to keep: adding puts one line under a comment saying where
+   * it came from, and dropping removes exactly the line (and the comment) an
+   * earlier release put there — never a line the operator wrote. Absent file is
+   * a no-op — it means the template's copy (declared in the same step, and
+   * reconciled the same way at declaration) arrives with the right rules in it.
+   *
+   * Matched line-wise rather than by substring: a rule for `Plugins/AGENTS.md`
+   * is not a rule for the root `AGENTS.md`, and treating it as one would leave
+   * the mismatch this exists to close.
+   */
+  private async reconcileIgnoreRules(
+    repoDir: string,
+    branch: KbBranch,
+    rules: {
+      add: string[];
+      drop: string[];
+      dropEvery?: string[];
+      /** `[from, to]` pairs: a rule an earlier release wrote, and its spelling now. */
+      respell?: ReadonlyArray<readonly [string, string]>;
+      /** Take out the platform's own `AGENTS.md` line — the guide is called something else now. */
+      dropAgentsRule?: boolean;
+    },
+  ): Promise<string[]> {
+    let current: string;
+    try {
+      current = await fs.readFile(path.join(repoDir, IGNORE_FILENAME), 'utf8');
+    } catch (err) {
+      // No ignore file — the copy declared from the template arrives with the
+      // right rules in it (guaranteed at declaration time, see the
+      // required-files loop above). A file that is there but cannot be read is
+      // NOT "no file": its rules may still be hiding the tree, so the hole is
+      // the step's failure, as it is for the migration's retirement.
+      if (!isAbsence(err)) throw err;
+      return [];
+    }
+    const respelled = (rules.respell ?? []).reduce(
+      (text, [from, to]) => withPlatformIgnorePatternRespelled(text, from, to),
+      current,
+    );
+    const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern), respelled);
+    const dropped = (rules.dropEvery ?? []).reduce(
+      (text, pattern) => withoutIgnoreLine(text, pattern),
+      rules.drop.reduce((text, pattern) => withoutPlatformIgnorePattern(text, pattern), added),
+    );
+    const merged = rules.dropAgentsRule ? withoutPlatformAgentsRule(dropped) : dropped;
+    if (merged === current) return [];
+    branch.write(IGNORE_FILENAME, merged);
+    return [IGNORE_FILENAME];
+  }
 }
 
 /**
- * The template's content for `relPath`, RENDERED: the managed files name the
- * three root folders, and a deployment may have renamed those, so the
- * placeholders the template carries (`{{pluginsDir}}` …) are filled with the
- * names in effect. Every required file is text; a template without
- * placeholders passes through unchanged.
+ * `text` without EVERY line that is exactly `pattern`, whoever wrote it, and
+ * without a platform comment sitting directly above one. The other drop keeps
+ * an operator's identical line; this one does not, and the difference is
+ * deliberate: the plugins-root rule was in the template from the first seed
+ * with no comment to know it by, so provenance cannot decide it — and the
+ * Skills & Tools sidebar now renders that root as a file tree read from the
+ * workspace tree, which the rule would empty. A `!pattern` negation is not
+ * the pattern and stays. A platform comment directly above a dropped line
+ * goes with it, and so does the blank line that opened an appended block —
+ * the same tidy-up `withoutPlatformIgnorePattern` does, so a file either
+ * step cleans reads the same afterwards.
+ *
+ * Exported for the Groups→Plugins step, which retires the same rules on the
+ * branches this step never visits (drafts).
  */
-async function readTemplate(templateDir: string, relPath: string): Promise<string> {
-  return renderKbLayoutPlaceholders(await fs.readFile(await templateSource(templateDir, relPath), 'utf8'));
+export function withoutIgnoreLine(text: string, pattern: string): string {
+  const lines = text.split('\n');
+  const kept: string[] = [];
+  for (const line of lines) {
+    if (line.trim() !== pattern) {
+      kept.push(line);
+      continue;
+    }
+    const above = kept[kept.length - 1];
+    if (above === undefined || !isPlatformRuleComment(above)) continue;
+    kept.pop();
+    if (above.trim() === PLATFORM_RULE_COMMENT && kept.length > 1 && kept[kept.length - 1]?.trim() === '') kept.pop();
+  }
+  return kept.join('\n');
 }
 
+/** The legacy comment `withIgnorePattern` wrote above the guide's rule. */
+const PLATFORM_RULE_COMMENT = '# Added by the platform: the conventions doc is not node content.';
+
+/** The comment the packaged template carries above the guide's rule. */
+const AGENTS_RULE_COMMENT = "# The platform's agent guide.";
+
 /**
- * Whether the repo's copy of `relPath` differs from the RENDERED template's,
- * modulo line endings — a CRLF checkout of identical content must read as
- * "same", or the managed-file refresh would commit churn on every boot
- * forever. Rendered, so a renamed root is compared against the guide that
- * names it, not against the placeholders.
+ * The repo-hygiene BLOCK of the packaged `.bevelignore`, exactly as every
+ * release that shipped a bare guide rule wrote it, in order, ending at the
+ * line that has always sat directly above that rule.
+ *
+ * It stands in for a comment on knowledge bases seeded before there was one.
+ * The guide's rule shipped in the template body from the first seed, bare,
+ * like the plugins-root rule did — but unlike that one it must not be dropped
+ * wholesale, because an operator who writes `AGENTS.md` into their own ignore
+ * file is saying something the platform has no business overruling.
+ *
+ * So provenance is the block the template put it in, and the WHOLE block is
+ * asked for. The single line above it is not enough: `.gitattributes` is an
+ * entry anyone might list, and a hand-written file that happens to name
+ * `AGENTS.md` under it would have had its rule read as the platform's and
+ * deleted. Three lines in the template's own order and wording are not
+ * something an operator arrives at by coincidence — and a file that does
+ * carry them carries the platform's block, however it got there.
  */
-async function templateDiffers(templateDir: string, repoDir: string, relPath: string): Promise<boolean> {
-  const norm = (text: string) => text.replace(/\r\n?/g, '\n');
-  const [current, template] = await Promise.all([
-    fs.readFile(path.join(repoDir, relPath), 'utf8'),
-    readTemplate(templateDir, relPath),
-  ]);
-  return norm(current) !== norm(template);
+const TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE: readonly string[] = [
+  '# Repo hygiene files that clutter the tree without being node content.',
+  '.gitignore',
+  '.gitattributes',
+];
+
+/** Whether the lines kept so far END with that block — i.e. the next line is the slot. */
+function followsTemplateHygieneBlock(kept: readonly string[]): boolean {
+  const block = TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE;
+  if (kept.length < block.length) return false;
+  return kept.slice(-block.length).every((line, i) => line.trim() === block[i]);
 }
 
 /**
- * Reconcile the platform's OWN rules in `.bevelignore`: every `add` pattern
- * guaranteed present as a line, every `drop` pattern taken out. Returns the
- * paths changed, for the note.
+ * `text` without the `AGENTS.md` line THE PLATFORM WROTE — under its own
+ * comment (either spelling), or in the slot at the end of the template's own
+ * repo-hygiene block ({@link TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE}) — and
+ * without that comment.
  *
- * Never rewrites the rest. The file is the operator's, and every rule already
- * in it is theirs to keep: adding puts one line under a comment saying where
- * it came from, and dropping removes exactly the line (and the comment) an
- * earlier release put there — never a line the operator wrote. Absent file is
- * a no-op — it means the template's copy (declared in the same step, and
- * reconciled the same way at declaration) arrives with the right rules in it.
- *
- * Matched line-wise rather than by substring: a rule for `Plugins/AGENTS.md`
- * is not a rule for the root `AGENTS.md`, and treating it as one would leave
- * the mismatch this exists to close.
+ * Called only when the guide has been renamed, which is what makes the line
+ * wrong: it hides a file the platform no longer owns. A `!AGENTS.md` negation
+ * is not the rule and stays, as everywhere else here.
  */
-async function reconcileIgnoreRules(
-  repoDir: string,
-  branch: KbBranch,
-  rules: { add: string[]; drop: string[] },
-): Promise<string[]> {
-  let current: string;
-  try {
-    current = await fs.readFile(path.join(repoDir, IGNORE_FILENAME), 'utf8');
-  } catch {
-    // No ignore file — the copy declared from the template arrives with the
-    // right rules in it (guaranteed at declaration time, see the
-    // required-files loop above).
-    return [];
+export function withoutPlatformAgentsRule(text: string): string {
+  const lines = text.split('\n');
+  const kept: string[] = [];
+  for (const line of lines) {
+    const above = kept[kept.length - 1];
+    const ours =
+      line.trim() === LEGACY_AGENTS_FILE &&
+      above !== undefined &&
+      (isPlatformRuleComment(above) || followsTemplateHygieneBlock(kept));
+    if (!ours) {
+      kept.push(line);
+      continue;
+    }
+    // The hygiene block above the rule is content, not a marker: those lines
+    // hide `.gitignore` and `.gitattributes` and stay. Only a comment the
+    // platform wrote goes with the rule it introduced.
+    if (!isPlatformRuleComment(above)) continue;
+    kept.pop();
+    // The blank line that opened an appended block goes with it; the template's
+    // own comment sits inline, with content above it, and nothing to tidy.
+    const appended = above.trim() === PLATFORM_RULE_COMMENT || above.trim() === AGENTS_RULE_COMMENT;
+    if (appended && kept.length > 1 && kept[kept.length - 1]?.trim() === '') kept.pop();
   }
-  const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern), current);
-  const merged = rules.drop.reduce((text, pattern) => withoutPlatformIgnorePattern(text, pattern), added);
-  if (merged === current) return [];
-  branch.write(IGNORE_FILENAME, merged);
-  return [IGNORE_FILENAME];
+  return kept.join('\n');
 }
 
-/** The comment `withIgnorePattern` writes above a line it appends. */
-const PLATFORM_RULE_COMMENT = '# Added by the platform: the conventions doc is not node content.';
+/**
+ * `text` with the platform's pointer sentence appended as its own paragraph.
+ *
+ * One blank line between the customer's last line and ours, whether or not
+ * their file ended in a newline: a sentence glued onto the end of their last
+ * paragraph would read as a continuation of something they wrote.
+ */
+export function withPointerSentence(text: string, agentsFile: string): string {
+  const body = text.replace(/\n+$/, '');
+  return `${body}\n\n${agentsFilePointerSentence(agentsFile)}\n`;
+}
+
+/** The comment written above the preamble rule on an existing knowledge base. */
+const PREAMBLE_RULE_COMMENT =
+  '# Added by the platform: agent instructions are edited from External agent access.';
+
+/**
+ * The line an earlier release shipped in the template above the UNANCHORED
+ * preamble rule. Recognised as the platform's own, on the same reasoning as
+ * the legacy skills line below: a rule under a comment the platform wrote is
+ * the platform's to respell, wherever the file came from.
+ */
+const LEGACY_PREAMBLE_TEMPLATE_COMMENT =
+  '# The deployment preamble is edited from External agent access, not as a KB page.';
 
 /**
  * The template line an earlier release shipped above the shared-skills rule,
@@ -409,7 +711,14 @@ const LEGACY_SKILLS_RULE_COMMENT_CLOSING = '/.';
  */
 function isPlatformRuleComment(line: string): boolean {
   const trimmed = line.trim();
-  if (trimmed === PLATFORM_RULE_COMMENT) return true;
+  if (
+    trimmed === PLATFORM_RULE_COMMENT ||
+    trimmed === AGENTS_RULE_COMMENT ||
+    trimmed === PREAMBLE_RULE_COMMENT ||
+    trimmed === LEGACY_PREAMBLE_TEMPLATE_COMMENT
+  ) {
+    return true;
+  }
   if (
     !trimmed.startsWith(LEGACY_SKILLS_RULE_COMMENT_OPENING) ||
     !trimmed.endsWith(LEGACY_SKILLS_RULE_COMMENT_CLOSING)
@@ -446,6 +755,31 @@ function withoutPlatformIgnorePattern(text: string, pattern: string): string {
   return kept.join('\n');
 }
 
+/**
+ * `text` with every `from` line THE PLATFORM WROTE respelled as `to`, its
+ * comment left where it is. Provenance is that comment, as everywhere else
+ * here: a bare rule the OPERATOR wrote is theirs and is not touched.
+ *
+ * This exists for one migration. An earlier release hid the preamble with the
+ * unanchored `mcp-description.md`, which also hides an ordinary knowledge
+ * page of that name anywhere in the tree; the rule the platform means is the
+ * root-anchored one. Respelling its own line is not the same as overruling an
+ * operator who chose the broad spelling, which is why the two are told apart.
+ */
+function withPlatformIgnorePatternRespelled(text: string, from: string, to: string): string {
+  const lines = text.split('\n');
+  return lines
+    .map((line, i) => {
+      if (line.trim() !== from) return line;
+      const above = lines[i - 1];
+      if (above === undefined || !isPlatformRuleComment(above)) return line;
+      // Function replacement: `to` is a pattern to `String.replace`, and a
+      // rule spelled with a `$` would otherwise be read as one.
+      return line.replace(from, () => to);
+    })
+    .join('\n');
+}
+
 /**
  * `text` with `pattern` guaranteed present as a LINE — appended under a
  * comment naming its origin when absent, returned unchanged when present.
@@ -455,10 +789,27 @@ function withoutPlatformIgnorePattern(text: string, pattern: string): string {
  * operator choosing to SHOW the file, and ordered matching means a positive
  * line appended after it would win and silently defeat the choice. Hiding
  * the conventions doc is a default this provides, never a mandate.
+ *
+ * The preamble rule reads its unanchored spelling the same way. By the time
+ * this runs, the platform's OWN legacy line has been respelled (see
+ * {@link withPlatformIgnorePatternRespelled}), so a bare `mcp-description.md`
+ * 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 {
   const lines = text.split('\n').map((l) => l.trim());
-  if (lines.includes(pattern) || lines.includes(`!${pattern}`)) return text;
+  const operatorPreambleRule =
+    pattern === PREAMBLE_IGNORE_PATTERN &&
+    (lines.includes(PREAMBLE_FILE) || lines.includes(`!${PREAMBLE_FILE}`));
+  if (lines.includes(pattern) || lines.includes(`!${pattern}`) || operatorPreambleRule) return text;
   const separator = text.endsWith('\n') ? '' : '\n';
-  return `${text}${separator}\n# Added by the platform: the conventions doc is not node content.\n${pattern}\n`;
+  // The guide's rule arrives as a gitignore literal (escaped where the name
+  // needs it), so it is recognised in that spelling.
+  const comment =
+    pattern === PREAMBLE_IGNORE_PATTERN
+      ? PREAMBLE_RULE_COMMENT
+      : pattern === gitignoreLiteral(AGENTS_FILE)
+        ? AGENTS_RULE_COMMENT
+        : PLATFORM_RULE_COMMENT;
+  return `${text}${separator}\n${comment}\n${pattern}\n`;
 }