@bevel-software/platform-core-backend 0.25.2 → 0.26.0

package/src/modules/agent-guide/agent-guide.ts

@@ -0,0 +1,291 @@
+/**
+ * The platform's agent guide: what every agent is told to read before its
+ * first read or change in a knowledge base — the layout, where a new file
+ * goes, the rules every file tool shares, access control, skills and tool
+ * manuals.
+ *
+ * It is TEXT THE CODE OWNS, not a file in the repository. It used to be
+ * written to every protected branch as `AGENTS.md` and refreshed on every
+ * start, which had three costs: a repository that already had an `AGENTS.md`
+ * of its own lost it or had to rename ours; a distribution that wanted to add
+ * to the guide had to fork the whole file and then drifted from every change
+ * made here; and the file sat in git history on every branch, hidden from the
+ * tree by an ignore rule it had to keep writing. Now the guide is composed
+ * from SECTIONS at the moment an agent asks for it — `get_agent_guide`, or a
+ * `read_file` of the guide's name at the repository root — and a distribution
+ * shapes it with a hook that sees the sections and returns the sections it
+ * wants (append, replace or drop by id), so what Hexis says reaches it without
+ * a copy to maintain.
+ *
+ * The sections ship as markdown files in the package's `agent-guide/` folder
+ * (see `assets.ts`), one per section, with the layout placeholders the old
+ * template carried (`{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`,
+ * `{{agentsFile}}`). ONE section is computed rather than read: the rules every
+ * file tool shares, which the MCP handshake also sends — the same string in
+ * both places, from `shared-file-rules.ts`, so a rule cannot be changed in one
+ * and left stale in the other.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+
+  renderKbLayoutPlaceholders,
+  resolveKbLayout,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { agentGuideDir } from '../../assets.js';
+import { sharedFileRulesSection } from '../agent-instructions/shared-file-rules.js';
+
+/** One section of the guide. */
+export interface AgentGuideSection {
+  /**
+   * Stable id, so a distribution's hook can replace or drop a section by name
+   * and a test can say which one went missing. Core's ids are the
+   * {@link CORE_SECTION_IDS}.
+   */
+  id: string;
+  /**
+   * The section's markdown, heading included (`## …`). May carry the layout
+   * placeholders; they are rendered with the names in effect when the guide is
+   * composed, so a section can name the knowledge folder without knowing what
+   * this deployment calls it.
+   */
+  body: string;
+  /**
+   * The body is FINAL: already rendered, and not to be passed through the
+   * placeholder renderer. Set on the computed shared-rules section, which is
+   * rendered for the layout by the code that builds it; rendering it again
+   * could only misread a folder name it STATES as a placeholder.
+   */
+  literal?: boolean;
+}
+
+/**
+ * A distribution's say over the guide. Called with core's sections, in order,
+ * and the layout in effect; returns the sections the guide is composed from.
+ * Append to the array to add sections, map over it to replace one by id,
+ * filter it to drop one. Called on every composition, so a hook that reads
+ * something live (a feature flag, a setting) is read each time.
+ */
+export type AgentGuideHook = (
+  sections: readonly AgentGuideSection[],
+  layout: Required<KbLayout>,
+) => readonly AgentGuideSection[] | Promise<readonly AgentGuideSection[]>;
+
+/** Composes the guide for the layout in effect — the shape every consumer reads. */
+export type AgentGuideReader = () => Promise<string>;
+
+/** The computed section: the rules every file tool shares. */
+export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
+
+/**
+ * Core's sections, in reading order. Every id but the shared-rules one names
+ * a file in the package's `agent-guide/` folder.
+ */
+export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
+  'introduction',
+  'directory-structure',
+  'where-a-new-file-goes',
+  WORKING_WITH_FILES_SECTION_ID,
+  'access-control',
+  'skills',
+  'tool-manuals',
+  'conventions',
+  'finding-things',
+]);
+
+/**
+ * The one line that proves a root guide file is the platform's and not the
+ * customer's: the blockquote the packaged guide opened with for as long as
+ * the guide was a file, under every release. Asked for WHERE the header put
+ * it — a blockquote line among the first lines of the file — and not anywhere
+ * in the text: a note of the organisation's own that quotes the platform's
+ * sentence in its body must not read as ours, because the consequence of the
+ * mistake is a deletion. Still read on every start, to take the copies
+ * earlier releases wrote out of the repository (see template-files.step.ts),
+ * and on every read of the guide's name, so a copy still on a draft is not
+ * served twice.
+ */
+const MANAGED_GUIDE_HEADER_LINE = '> **This file is managed by the platform.**';
+
+/** How far down a file the header's blockquote can sit: under the title and a sentence or two, never further. */
+const MANAGED_GUIDE_HEADER_WITHIN_LINES = 12;
+
+/** Whether `text` is a copy of the guide a release wrote to disk, of any vintage. */
+export function isManagedGuide(text: string): boolean {
+  return text
+    .split('\n', MANAGED_GUIDE_HEADER_WITHIN_LINES)
+    .some((line) => line.trimStart().startsWith(MANAGED_GUIDE_HEADER_LINE));
+}
+
+/** The raw section files, read once per process: the package does not change while it runs. */
+let coreSectionFiles: Promise<ReadonlyMap<string, string>> | null = null;
+
+async function readCoreSectionFiles(): Promise<ReadonlyMap<string, string>> {
+  const dir = agentGuideDir();
+  const entries = await Promise.all(
+    CORE_SECTION_IDS.filter((id) => id !== WORKING_WITH_FILES_SECTION_ID).map(
+      // Line endings normalised: a checkout on Windows may carry CRLF, and the
+      // guide is one text with one ending wherever it is served from.
+      async (id) => [id, (await fs.readFile(path.join(dir, `${id}.md`), 'utf8')).replace(/\r\n?/g, '\n')] as const,
+    ),
+  );
+  return new Map(entries);
+}
+
+/**
+ * Core's sections for `layout`: the files, placeholders unrendered, with the
+ * shared-rules section computed and in its place. What a distribution's hook
+ * is handed.
+ */
+export async function coreAgentGuideSections(layout: KbLayout): Promise<AgentGuideSection[]> {
+  coreSectionFiles ??= readCoreSectionFiles();
+  let files: ReadonlyMap<string, string>;
+  try {
+    files = await coreSectionFiles;
+  } catch (err) {
+    // A failed read is not cached: the next composition tries the disk again.
+    coreSectionFiles = null;
+    throw err;
+  }
+  return CORE_SECTION_IDS.map((id) =>
+    id === WORKING_WITH_FILES_SECTION_ID
+      ? { id, body: sharedFileRulesSection(layout), literal: true }
+      : { id, body: files.get(id)! },
+  );
+}
+
+/** What the guide is composed for, beyond the layout. */
+export interface AgentGuideContext {
+  /**
+   * The name of the repository's checkout folder inside a workspace, which
+   * the file tools take paths under (`knowledge-base/` by default). Rendered
+   * into `{{kbDirName}}` so the paths the guide shows are the paths this
+   * deployment's tools report back.
+   */
+  kbDirName?: string;
+}
+
+/** The checkout folder's name when none is given — core's own default. */
+const DEFAULT_KB_DIR_NAME = 'knowledge-base';
+
+/** One section of the guide as an agent reads it: rendered, with the heading's text as its title. */
+export interface RenderedGuideSection {
+  id: string;
+  /** The heading line's text, without its `#`s — what the tool lists the section as. */
+  title: string;
+  /** The section's markdown, heading included, rendered for the layout. */
+  body: string;
+}
+
+/** Composes the guide's sections for the layout in effect — what the guide tool reads. */
+export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
+
+/**
+ * The guide's sections as an agent reads them: core's sections through the
+ * distribution's hook (when there is one), rendered for the layout, each
+ * with its title. The whole guide is these joined (see
+ * {@link composeAgentGuide}); `get_agent_guide` also serves one at a time.
+ *
+ * A hook may append, replace and drop sections, with ONE exception: the
+ * shared file rules ({@link WORKING_WITH_FILES_SECTION_ID}) must come back
+ * WITH TEXT IN THEM, as core's or as the hook's own replacement. A client
+ * that drops the handshake instructions has the guide as the only place to
+ * read the rules — a guide without them would leave agents nothing to read.
+ * A hook that drops the section, or hands it back empty, is a composition
+ * error, thrown rather than served. Judged on what would be SERVED — the
+ * rendered, trimmed body — so a replacement of whitespace is caught like a
+ * missing one, rather than passing the check and vanishing with the other
+ * empty sections below.
+ */
+export async function agentGuideSections(
+  layout: KbLayout,
+  hook?: AgentGuideHook,
+  context: AgentGuideContext = {},
+): Promise<RenderedGuideSection[]> {
+  const resolved = resolveKbLayout(layout);
+  const core = await coreAgentGuideSections(resolved);
+  const sections = hook ? await hook(core, resolved) : core;
+  const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
+  const rendered = sections.map((section) => {
+    const body = (
+      section.literal
+        ? section.body
+        : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)
+    ).trim();
+    return { id: section.id, title: titleOf(body, section.id), body };
+  });
+  // Judged over EVERY section under the id — a hook may return the id twice
+  // — on what survives the empty-body filter below: one with text is enough.
+  const rules = rendered.filter((section) => section.id === WORKING_WITH_FILES_SECTION_ID);
+  if (!rules.some((section) => section.body.length > 0)) {
+    throw new Error(
+      `The agent guide hook ${rules.length === 0 ? 'dropped' : 'emptied'} the "${WORKING_WITH_FILES_SECTION_ID}" ` +
+        'section, which every file tool points at. Keep it, or replace it under the same id with the rules in it.',
+    );
+  }
+  return rendered.filter((section) => section.body.length > 0);
+}
+
+/**
+ * The heading's text, or the id when the section opens with no heading. An
+ * ATX heading may close with a run of `#` of its own (`## Custom ##`); that
+ * is a delimiter, not part of the title.
+ */
+function titleOf(body: string, id: string): string {
+  const first = body.split('\n', 1)[0] ?? '';
+  const heading = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(first);
+  return heading ? heading[1]!.trim() : id;
+}
+
+/**
+ * The guide as an agent reads it whole: the sections joined by blank lines,
+ * ending in one newline.
+ */
+export async function composeAgentGuide(
+  layout: KbLayout,
+  hook?: AgentGuideHook,
+  context: AgentGuideContext = {},
+): Promise<string> {
+  return joinGuideSections(await agentGuideSections(layout, hook, context));
+}
+
+/** The sections as one document, the way `composeAgentGuide` joins them. */
+export function joinGuideSections(sections: readonly RenderedGuideSection[]): string {
+  return `${sections.map((section) => section.body).join('\n\n')}\n`;
+}
+
+/**
+ * What a `read_file` of the guide's name answers when the knowledge base has an
+ * `AGENTS.md` of its own: their text first, whole, then a rule and one line
+ * saying what follows, then the platform's guide. Theirs first because it is
+ * the more specific of the two, and the line between so neither is read as
+ * part of the other.
+ */
+export const PLATFORM_GUIDE_SEPARATOR =
+  "---\n\n_The text above is this knowledge base's own conventions file. The platform's guide follows; `get_agent_guide` returns it on its own._";
+
+export function withPlatformGuideAppended(ownText: string, guide: string): string {
+  // Their text as they wrote it, line endings normalised and the trailing
+  // newlines folded into the one blank line before the separator. Nothing
+  // else is touched: leading indentation and trailing spaces are markdown.
+  const own = ownText.replace(/\r\n?/g, '\n').replace(/\n+$/, '');
+  // A file with nothing in it has nothing to put first, and a separator
+  // above nothing would claim a conventions file that says nothing.
+  if (own.trim().length === 0) return guide;
+  return `${own}\n\n${PLATFORM_GUIDE_SEPARATOR}\n\n${guide}`;
+}
+
+/** The one name the guide is read by: `AGENTS.md` at the repository root, the name coding agents look for. */
+export const AGENT_GUIDE_FILE = 'AGENTS.md';
+
+/**
+ * Whether a repository-relative path is where the guide is read — `AGENTS.md`
+ * at the repository root, exactly spelled, like every platform path. One
+ * name on every deployment: there is no setting for it any more.
+ */
+export function isAgentGuidePath(repoRelativePath: string): boolean {
+  const norm = repoRelativePath.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+  return norm === AGENT_GUIDE_FILE;
+}

package/src/modules/agent-guide/index.ts

@@ -0,0 +1,21 @@
+export {
+  AGENT_GUIDE_FILE,
+  CORE_SECTION_IDS,
+  PLATFORM_GUIDE_SEPARATOR,
+  WORKING_WITH_FILES_SECTION_ID,
+  agentGuideSections,
+  composeAgentGuide,
+  coreAgentGuideSections,
+  isAgentGuidePath,
+  isManagedGuide,
+  joinGuideSections,
+  withPlatformGuideAppended,
+  type AgentGuideContext,
+  type AgentGuideHook,
+  type AgentGuideReader,
+  type AgentGuideSection,
+  type AgentGuideSectionsReader,
+  type RenderedGuideSection,
+} from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -1,14 +1,6 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import {
-  DEFAULT_KB_LAYOUT,
-  LEGACY_AGENTS_FILE,
-  PREAMBLE_CAP,
-  renderKbLayoutPlaceholders,
-} from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT, PREAMBLE_CAP } from '@bevel-software/platform-shared';
 import { describe, expect, it } from 'vitest';
-import { defaultKbTemplateDir } from '../../../assets.js';
-import { renderTemplateText, SHARED_FILE_RULES_PLACEHOLDER } from '../../workspace/startup/steps/template-source.js';
+import { composeAgentGuide } from '../../agent-guide/agent-guide.js';
 import {
   INSTRUCTIONS_CAP,
   PLATFORM_HEADER,
@@ -17,37 +9,29 @@ import {
   platformInstructions,
 } from '../compose.js';
 import {
-  POINTER_GUIDE_NAME_BUDGET,
   SHARED_FILE_RULES_CAP,
-  SHARED_RULES_POINTER_MAX,
   SHARED_RULES_SECTION,
   sharedFileRules,
   sharedFileRulesSection,
-  sharedRulesPointer,
 } from '../shared-file-rules.js';
 
 /**
  * The rules every file tool shares are stated in TWO places — the handshake
- * `instructions` and the platform-managed agent guide — and in neither tool
+ * `instructions` and the platform's agent guide — and in neither tool
  * description. These tests are what makes "stated once" true: the two places
  * carry the SAME string, built from one text, so a rule cannot be changed in one
  * and left stale in the other.
  */
 
-/** The packaged template's agent guide, as it ships (placeholders unrendered). */
-async function guideTemplate(): Promise<string> {
-  return readFile(path.join(defaultKbTemplateDir(), LEGACY_AGENTS_FILE), 'utf8');
-}
-
 describe('the shared file rules are one text, in two places', () => {
-  it('puts the identical section in the handshake instructions and in the managed guide', async () => {
+  it('puts the identical section in the handshake instructions and in the agent guide', async () => {
     const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);
     expect(section.startsWith(`## ${SHARED_RULES_SECTION}\n\n`)).toBe(true);
 
     const instructions = composeAgentInstructions(null).instructions;
     expect(instructions).toContain(section);
 
-    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT);
     expect(guide).toContain(section);
 
     // Byte-for-byte the same text in both, which is the whole point: neither is
@@ -62,7 +46,7 @@ describe('the shared file rules are one text, in two places', () => {
 
   it('states every rule in both places, and the content rule exactly once in each', async () => {
     const instructions = composeAgentInstructions(null).instructions;
-    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT);
     const rules = sharedFileRules(DEFAULT_KB_LAYOUT);
     expect(rules.map((r) => r.id)).toEqual([
       'agent-guide',
@@ -87,7 +71,7 @@ describe('the shared file rules are one text, in two places', () => {
   });
 
   it('carries the whole content rule — the refused families, the byte tools and the upload path', async () => {
-    for (const text of [composeAgentInstructions(null).instructions, renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT)]) {
+    for (const text of [composeAgentInstructions(null).instructions, await composeAgentGuide(DEFAULT_KB_LAYOUT)]) {
       expect(text).toContain('`binary_not_writable`');
       expect(text).toContain('copy_file, move_file and delete_file act on bytes of any kind');
       expect(text).toContain('unzip extracts the entries of a `.zip`');
@@ -102,109 +86,32 @@ describe('the shared file rules are one text, in two places', () => {
     }
   });
 
-  it('names the guide under the name this deployment gave it, in both places and in the pointer', async () => {
+  /**
+   * The guide is no file: it is reached by one name at the KB root and by one
+   * tool, on every deployment. The first rule says so, and names the
+   * organisation's own conventions file beside it — which is what a
+   * `read_file` of that name serves first.
+   */
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with the same guide after the organisation\'s own', () => {
+    const rule = sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'agent-guide')!.body;
+    expect(rule).toContain("call `get_agent_guide` and read the platform's guide");
+    expect(rule).toContain('read_file on `AGENTS.md` at the KB root answers with the same guide');
+    expect(rule).toContain("after the organisation's own conventions file of that name");
+    // The pre-rename name is still offered, for a knowledge base that kept one.
+    expect(rule).toContain('`CLAUDE.md`');
+  });
+
+  it('names one guide on every deployment, whatever name a deployment once saved for the written one', () => {
     const layout = { ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' };
     const section = sharedFileRulesSection(layout);
-    // Ours first, then the organisation's own AGENTS.md, then the pre-rename name.
-    expect(section).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
-    expect(section).toContain('`CLAUDE.md` on a knowledge base seeded before it was renamed');
-    // The platform files a move refuses list the guide under its own name too.
-    expect(section).toContain('`HEXIS.md`');
+    expect(section).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(section).not.toContain('HEXIS.md');
     expect(composeAgentInstructions(null, layout).instructions).toContain(section);
-    expect(renderTemplateText(await guideTemplate(), layout)).toContain(section);
-    expect(sharedRulesPointer(layout)).toBe(` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in HEXIS.md.`);
-  });
-
-  it('keeps the pointer bounded whatever the guide is called', () => {
-    // The pointer rides on every file tool, so its length is not the guide's
-    // business: `validateFilename` allows a 255-byte name, and an unbounded
-    // pointer would reach 318 characters and push `file_stat` past the
-    // description cap — on a renamed deployment only, which no measurement
-    // taken under the default layout would ever show.
-    const nameOfLength = (n: number): string => `${'x'.repeat(n - 3)}.md`;
-    for (const length of [9, POINTER_GUIDE_NAME_BUDGET, POINTER_GUIDE_NAME_BUDGET + 1, 120, 255]) {
-      const pointer = sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: nameOfLength(length) });
-      expect(pointer.length, `a ${length}-character name`).toBeLessThanOrEqual(SHARED_RULES_POINTER_MAX);
-    }
-    // Up to the budget the file is NAMED, which is the better sentence.
-    const named = nameOfLength(POINTER_GUIDE_NAME_BUDGET);
-    expect(sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: named })).toContain(named);
-    // Past it the guide is named by its role instead — a sentence that still
-    // says where to look, rather than a catalog entry the client cuts.
-    const tooLong = nameOfLength(POINTER_GUIDE_NAME_BUDGET + 1);
-    const fallback = sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: tooLong });
-    expect(fallback).not.toContain(tooLong);
-    expect(fallback).toBe(` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in the agent guide at the KB root.`);
-    // Either way the section's first rule still names the file, so the name is
-    // never actually lost.
-    expect(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, agentsFile: tooLong })).toContain(tooLong);
-  });
-
-  it('points at the section with one short sentence under the default name', () => {
-    expect(sharedRulesPointer(DEFAULT_KB_LAYOUT)).toBe(
-      ' Shared rules for all file tools: see "Working with files" in AGENTS.md.',
-    );
-    // An unset guide name means the default, as it does everywhere else.
-    expect(sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: undefined })).toBe(
-      sharedRulesPointer(DEFAULT_KB_LAYOUT),
-    );
-  });
-});
-
-describe('the guide template asks for the rules rather than repeating them', () => {
-  it('carries the placeholder once, and no rule text of its own', async () => {
-    const template = await guideTemplate();
-    expect(template.split(SHARED_FILE_RULES_PLACEHOLDER)).toHaveLength(2);
-    // The rules are not ALSO written into the template — that is the copy that
-    // would drift. Checked on a fragment of each rule rather than on the whole.
-    for (const rule of sharedFileRules(DEFAULT_KB_LAYOUT)) {
-      expect(template, rule.id).not.toContain(rule.body.slice(0, 60));
-    }
-  });
-
-  it('renders the placeholder nowhere else, so other managed files are untouched', async () => {
-    const access = await readFile(path.join(defaultKbTemplateDir(), 'access.md'), 'utf8');
-    expect(access).not.toContain(SHARED_FILE_RULES_PLACEHOLDER);
-    // So rendering it gains no rule text: whatever the layout renderer does to
-    // its own tokens, the section is nowhere in the result.
-    const rendered = renderTemplateText(access, DEFAULT_KB_LAYOUT);
-    expect(rendered).not.toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
-    expect(rendered).not.toContain(`## ${SHARED_RULES_SECTION}`);
-  });
-
-  it('leaves no placeholder behind once rendered', async () => {
-    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
-    expect(guide).not.toContain('{{');
+    // The guide is not a platform file under any name: the list a move
+    // refuses does not carry it.
+    expect(section).toContain('`access.md` or `.bevelignore` in any folder, `roles.yaml` at the repository root');
   });
 
-  it('renders the layout tokens first, then injects the rules — so the rules are never re-rendered', async () => {
-    // A layout the two orders DISAGREE on, which an ordinary one does not: the
-    // section states the knowledge-base folder's name, so a deployment whose
-    // folder is literally called `{{skillsDir}}` puts a layout token inside the
-    // rendered section. Injecting first would then rewrite it on the second
-    // pass and the guide would name the skills folder where the rule means the
-    // knowledge-base one. Pathological on purpose: it is the only kind of input
-    // on which the order is observable at all, which is why a test that pins
-    // the order has to use one.
-    const layout = { ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' };
-    const section = sharedFileRulesSection(layout);
-    expect(section).toContain('{{skillsDir}}/');
-
-    const template = `Skills live in {{skillsDir}}/.\n\n${SHARED_FILE_RULES_PLACEHOLDER}\n`;
-    const rendered = renderTemplateText(template, layout);
-    // The author's token is rendered, and the section survives byte for byte.
-    expect(rendered).toBe(`Skills live in Playbooks/.\n\n${section}\n`);
-
-    // And the other order really does differ on this input, so the assertion
-    // above is load-bearing rather than true of both.
-    const injectedFirst = renderKbLayoutPlaceholders(
-      template.replaceAll(SHARED_FILE_RULES_PLACEHOLDER, () => section),
-      layout,
-    );
-    expect(injectedFirst).not.toBe(rendered);
-    expect(injectedFirst).not.toContain(section);
-    expect(injectedFirst).toContain('`Playbooks/`) and git metadata are refused');
-  });
 });
 
 describe('the handshake text stays inside the length it pins', () => {

package/src/modules/agent-instructions/agent-instructions.routes.ts

@@ -28,8 +28,9 @@ export function createAgentInstructionsRoutes(
   readPreamble: AgentPreambleReader,
   /**
    * The layout in effect, read per request — the shared file rules name the
-   * managed guide, whose name the setup save may change without a restart.
-   * Optional so a construction with no layout in hand gets `AGENTS.md`.
+   * guide by the name a deployment saved for it, which the setup save may
+   * change without a restart. Optional so a construction with no layout in
+   * hand gets `AGENTS.md`.
    */
   kbLayout?: () => KbLayout,
 ): express.Router {

package/src/modules/agent-instructions/compose.ts

@@ -64,8 +64,10 @@ export const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it b
  * `header` field carries and what the card shows as fixed and not editable;
  * the admin's preamble follows it.
  *
- * A FUNCTION of the layout, because the shared rules name the managed guide
- * and its file name is a deployment setting.
+ * A FUNCTION of the layout, because the shared rules name the platform files
+ * by the root names a deployment chose (`Skills/`, `Plugins/`), which are
+ * deployment settings. The guide's name is not one of them: it is `AGENTS.md`
+ * everywhere.
  */
 export function platformInstructions(layout: KbLayout): string {
   return `${PLATFORM_HEADER}\n\n${sharedFileRulesSection(layout)}`;
@@ -119,10 +121,11 @@ export interface ComposedAgentInstructions {
  * unterminated `<!--` strips everything after it, so the most likely editing
  * slip withholds text rather than leaking it.
  *
- * `layout` decides only the guide's name inside the shared rules, and defaults
- * to the standard one — a caller with no layout in hand (a test, a surface that
- * predates the setting) gets `AGENTS.md`, which is what an unset name means
- * everywhere else.
+ * `layout` decides the root names the shared rules spell (`Skills/`,
+ * `Plugins/`, the knowledge folder) and defaults to the standard ones — a
+ * caller with no layout in hand (a test, a surface that predates the setting)
+ * gets the defaults. The guide's name is not among them: it is `AGENTS.md` on
+ * every deployment.
  */
 export function composeAgentInstructions(
   preamble: string | null,

package/src/modules/agent-instructions/index.ts

@@ -13,13 +13,10 @@ export {
   type ComposedAgentInstructions,
 } from './compose.js';
 export {
-  POINTER_GUIDE_NAME_BUDGET,
   SHARED_FILE_RULES_CAP,
-  SHARED_RULES_POINTER_MAX,
   SHARED_RULES_SECTION,
   sharedFileRules,
   sharedFileRulesSection,
-  sharedRulesPointer,
   type SharedFileRule,
 } from './shared-file-rules.js';
 export { readAgentPreamble, type AgentPreambleReader, type PreambleWorkspace } from './read-preamble.js';