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

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,108 +86,45 @@ 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.`);
+    // 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('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('{{');
-  });
-
-  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 delete rule for platform files', () => {
+  const managedItems = (): string => sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'managed-items')!.body;
+
+  it('says a nested access.md is deleted by whoever may write it, and the root\'s platform files by nobody', async () => {
+    const body = managedItems();
+    expect(body).toContain('delete_file deletes a nested `access.md` for whoever may write it');
+    expect(body).toContain("its folder then follows its parent's rules");
+    expect(body).toContain("the repository root's `access.md` and `roles.yaml` are deleted by nobody");
+    // The sentence the refusal actually carries, as the tools and the app say it.
+    expect(body).toContain("\"<name> is the repository's own file and cannot be deleted.\"");
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(body);
   });
 });
 

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

@@ -30,6 +30,7 @@ import {
   stripHtmlComments,
   type KbLayout,
 } from '@bevel-software/platform-shared';
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
 import { sharedFileRulesSection } from './shared-file-rules.js';
 
 export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
@@ -48,7 +49,13 @@ export const PLATFORM_HEADER =
   'Before answering a question about the organisation, its people, customers, products, processes, projects or internal terms, ' +
   'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
   'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
-  'Skills are available as prompts and through `list_skills` and `get_skill`.';
+  'Skills are available as prompts and through `list_skills` and `get_skill`. ' +
+  // There is no one calling shape to state: the knowledge-base tools take
+  // their arguments under `body`, a tool that calls another service takes them
+  // flat, and an agent told one rule for all of them sends a GET with a body.
+  // The per-tool `Call:` line is generated from each tool's own input schema,
+  // so pointing at it is both shorter and always right.
+  'Tools do not share one calling shape: call each tool exactly as the `Call:` line at the top of its description shows.';
 
 /**
  * The fixed first line of the tool prefix. It always leads, so an admin's
@@ -64,8 +71,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 +128,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,
@@ -164,9 +174,17 @@ export function composeAgentInstructions(
  * A tool description with the prefix ahead of it: the prefix, a blank line,
  * then the original. Purpose line first, because claude.ai cuts descriptions
  * near 500 characters.
+ *
+ * Except for the `Call:` line, which stays the very first line whatever else
+ * is prepended: it is how an agent learns the shape this tool's arguments take,
+ * and a description that opens with the purpose prefix instead would bury the
+ * one line the refusal for a wrong call points back to.
  */
 export function prefixToolDescription(toolPrefix: string, description: string | undefined): string {
-  return description ? `${toolPrefix}\n\n${description}` : toolPrefix;
+  if (!description) return toolPrefix;
+  const { call, rest } = splitCallLine(description);
+  if (call === null) return `${toolPrefix}\n\n${description}`;
+  return rest === '' ? `${call}\n\n${toolPrefix}` : `${call}\n\n${toolPrefix}\n\n${rest}`;
 }
 
 /** An ATX heading line: `#` to `######`, then a space or the end. */

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';

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

@@ -14,24 +14,24 @@
  *
  *  - the MCP `instructions` of the initialize handshake (see `compose.ts`),
  *    which Claude Code, Claude Desktop and Cursor put in the system prompt;
- *  - the platform-managed agent guide at the repository root (`AGENTS.md` by
- *    default), rendered from `{{sharedFileRules}}` in the template — claude.ai
- *    on the web, the Agent SDK and Cline drop `instructions`, and a guide the
- *    agent is told to read before its first action is always available.
+ *  - the platform's agent guide, which `get_agent_guide` returns and a
+ *    `read_file` of the guide's name serves (see `modules/agent-guide`) —
+ *    claude.ai on the web, the Agent SDK and Cline drop `instructions`, and a
+ *    guide the agent is told to read before its first action is always
+ *    available.
  *
  * Both places get the SAME string, from {@link sharedFileRulesSection} — not
  * two hand-mirrored copies. A rule written twice is a rule that drifts, and a
  * drifted rule is worse than a repeated one, because the agent cannot tell
- * which copy is current. Each description ends instead with
- * {@link sharedRulesPointer}, one sentence naming the section and the file.
+ * which copy is current. Each description opens instead with the one
+ * sentence sending the agent to the guide (`tool-registry/guide-first.ts`).
  *
- * Pure text, a function of the layout only: the guide's file name is a
- * deployment setting, so nothing here may snapshot `AGENTS.md`.
+ * Pure text, a function of the layout only: the guide's name is a deployment
+ * setting (an alias a deployment chose before the guide left the disk), so
+ * nothing here may snapshot `AGENTS.md`.
  */
 
 import {
-  DEFAULT_KB_LAYOUT,
-  agentsFileOf,
   LEGACY_AGENTS_FILE,
   platformFilesByDepth,
   type KbLayout,
@@ -43,9 +43,9 @@ export const SHARED_RULES_SECTION = 'Working with files';
 
 /**
  * The guide's name on a knowledge base seeded before it was renamed to
- * {@link LEGACY_AGENTS_FILE}. Named in the conventions rule because the seeder
- * never deletes a file it did not expect, so such a knowledge base still
- * carries one.
+ * {@link LEGACY_AGENTS_FILE}, back when the guide was a file. The platform's
+ * own copy is taken out at startup now (see template-files.step.ts); one that
+ * stays is a file the organisation edited, so it is theirs and still named.
  */
 const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
 
@@ -84,12 +84,11 @@ export interface SharedFileRule {
  * ones that said "this tool" or "this call" name the tools instead.
  */
 export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
-  const agentsFile = agentsFileOf(layout);
   return [
     {
       id: 'agent-guide',
       heading: "This knowledge base's own conventions",
-      body: conventionsRule(agentsFile),
+      body: conventionsRule(),
     },
     {
       id: 'content-kinds',
@@ -146,15 +145,15 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       // that take content as a JSON string names the route in one sentence of
       // its own; WHY a file should go that way, and how, is here.
       id: 'upload-route',
-      heading: 'Large, escape-heavy and binary content goes by upload',
+      heading: 'Large, escape-heavy and binary content: upload in, download out',
       body:
-        'write_file, write_files and edit_file take content as a JSON string you have to type out in full, so a long ' +
-        'file is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and ' +
-        'an image, a PDF or a zip cannot be sent at all. For any of those: call `request_file_upload`, POST the file — ' +
-        'or one zip holding many files — to the address it answers with any HTTP client ' +
-        '(`curl -X POST --data-binary @<file> "<uploadUrl>?filename=<name>"`), then `apply_file_upload` to land it on ' +
-        'a branch in one commit. The bytes never pass through the conversation, so nothing is cut or mangled on the ' +
-        'way. A person can also use Upload in the app.',
+        'write_file, write_files and edit_file take content as a JSON string you type out in full, so a long file ' +
+        'is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and an ' +
+        'image, a PDF or a zip cannot be sent at all. For those, call `request_file_upload`, POST the file (or one ' +
+        'zip of many) with any HTTP client (`curl -X POST --data-binary @<file> ' +
+        '"<uploadUrl>?filename=<name>"`), then `apply_file_upload` lands it in one commit. To take copies OUT, ' +
+        '`request_file_download` answers a one-time link per file and a zip per folder (`curl -o <name> ' +
+        '"<downloadUrl>"`). Either way no bytes pass through the conversation.',
     },
     {
       id: 'dry-run-confirm',
@@ -164,22 +163,22 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
         'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
         'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
-        'dry-run, check the impact, then confirm. delete_file takes neither: it removes the one file you named, so ' +
-        'check it first with file_stat (`deletable`) if you are unsure.',
+        'dry-run, check the impact, then confirm. delete_file takes neither: check it first with file_stat ' +
+        '(`deletable`) if you are unsure. delete_branch has its own `dryRun`.',
     },
     {
       id: 'managed-items',
       heading: 'What these tools never move or delete',
       body:
-        `A platform file (${platformFileList(layout)}) is refused with ` +
-        '"<name> is a platform file and stays in its folder." — a folder that moves ' +
-        'takes its own platform files along, still in their folder, and a folder that is deleted takes them with it in ' +
-        'the same one change, so its files are never left ungoverned part-way. A platform folder (the repository root ' +
-        `or a reserved root folder such as \`${layout.knowledgeBaseDir}/\`) and git metadata are refused, and so is creating a ` +
-        'platform file or folder at a destination (renaming a note to `access.md` is refused). A path that is, or goes ' +
-        'through, a symbolic link is refused: links are never followed or removed. On a protected branch you must be ' +
-        'able to write everything the call touches — for a folder, every file under it, at its old and its new path. ' +
-        'file_stat reports `managed`, `movable` and `deletable` so you can tell before the call.',
+        `A platform file (${platformFileList(layout)}) is never moved: "<name> is a platform file and stays in its folder." ` +
+        'A folder moved or deleted takes its own along, in one change. delete_file deletes a nested `access.md` for ' +
+        "whoever may write it (its folder then follows its parent's rules) and refuses `.bevelignore`; the repository " +
+        "root's `access.md` and `roles.yaml` are deleted by nobody: \"<name> is the repository's own file and cannot be " +
+        'deleted." A platform folder (the root, or a reserved one like ' +
+        `\`${layout.knowledgeBaseDir}/\`), git metadata, and making a platform file or folder at a destination are ` +
+        'refused; so is a path that is or crosses a symlink: links are never followed or removed. On a protected ' +
+        'branch you must be able to write all a call touches — for a folder, every file under it, at its old and new ' +
+        'path. file_stat reports `managed`, `movable` and `deletable` up front.',
     },
     {
       id: 'refused-for-permissions',
@@ -204,15 +203,14 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
 
 /**
  * The platform files as the rules list them — from the one function that knows
- * which they are, so the list cannot drift from what actually refuses a move,
- * and the guide appears under this deployment's name for it.
+ * which they are, so the list cannot drift from what actually refuses a move.
  *
  * WITH THE DEPTH each name counts at, because the name alone is half the rule:
  * `access.md` governs the folder it sits in and `.bevelignore` layers, so both
- * are platform files wherever they are; `roles.yaml` and the guide are read
- * from the repository root only, so a nested copy of either is ordinary
- * content that moves and deletes like any page. An agent told only the names
- * refuses a rename it may make, and trusts a nested `access.md` it may not.
+ * are platform files wherever they are; `roles.yaml` is read from the
+ * repository root only, so a nested copy is ordinary content that moves and
+ * deletes like any page. An agent told only the names refuses a rename it may
+ * make, and trusts a nested `access.md` it may not.
  */
 function platformFileList(layout: KbLayout): string {
   const { anyDepth, rootOnly } = platformFilesByDepth(layout);
@@ -221,30 +219,21 @@ function platformFileList(layout: KbLayout): string {
 }
 
 /**
- * The conventions reminder — which file holds the author's own rules for this
- * knowledge base, and to read it first.
+ * The conventions reminder — where the platform's guide is, that the
+ * organisation's own conventions file comes with it, and to read both first.
  *
- * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
- * rename still carry one. WHEN THE GUIDE HAS BEEN RENAMED the sentence names
- * two files, ours first: the second is the organisation's OWN `AGENTS.md`,
- * which on such a deployment is ordinary content the platform never touches —
- * and which no harness reads for a remote agent, because a remote agent has no
- * checkout. Under the default name the wording collapses to the one file it
- * has always named.
+ * The guide is read by name at the repository root, where coding agents look
+ * for an `AGENTS.md` by convention, and `get_agent_guide` returns it alone.
+ * One name on every deployment, so the rule takes no layout. `CLAUDE.md` is
+ * named as a fallback because a knowledge base seeded before the rename may
+ * still carry one its people edited.
  */
-function conventionsRule(agentsFile: string): string {
-  if (agentsFile === LEGACY_AGENTS_FILE) {
-    return (
-      `Before your first read or change in a workspace, read \`${LEGACY_AGENTS_FILE}\` at the KB root — or ` +
-      `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed — if either exists: it holds ` +
-      "the author's conventions for this knowledge base, and you should follow them."
-    );
-  }
+function conventionsRule(): string {
   return (
-    `Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
-    `\`${LEGACY_AGENTS_FILE}\` if it also exists (the organisation's own conventions) — or ` +
-    `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed: together they hold the ` +
-    'conventions for this knowledge base, and you should follow them.'
+    "Before your first read or change in a workspace, call `get_agent_guide` and read the platform's guide " +
+    `(whole, or one section). read_file on \`${LEGACY_AGENTS_FILE}\` at the KB root answers with the same ` +
+    "guide, after the organisation's own conventions file of that name when it has one: follow both. A " +
+    `\`${PRE_RENAME_AGENTS_FILE}\` at the KB root is the organisation's own too; read it if it exists.`
   );
 }
 
@@ -260,55 +249,4 @@ export function sharedFileRulesSection(layout: KbLayout): string {
   return `## ${SHARED_RULES_SECTION}\n\n${body}`;
 }
 
-/**
- * The longest guide file name the pointer sentence spells out. Beyond this it
- * names the guide by its ROLE instead (see {@link sharedRulesPointer}).
- *
- * There has to be a bound somewhere, because the pointer rides on every file
- * tool and a file name is not a fixed cost: `validateFilename` allows a name
- * of up to 255 bytes, so an unbounded pointer could reach 318 characters and
- * push `file_stat` to 1,428 — over the description cap, recreating on a
- * renamed deployment exactly the truncation this module exists to prevent, and
- * invisibly, because every measurement is taken under the default layout.
- *
- * 40 is well past any name a deployment plausibly picks
- * (`ENGINEERING-AGENT-CONVENTIONS.md` is 32) and the fallback below is only
- * reachable past it.
- */
-export const POINTER_GUIDE_NAME_BUDGET = 40;
-
-/**
- * The one sentence a tool description ends with, in place of the paragraphs it
- * used to carry. Short on purpose: it costs every description the same ~100
- * characters at worst, and its whole job is to name the section and the file
- * to read.
- *
- * BOUNDED BY CONSTRUCTION, which is what lets the description cap mean
- * something on a deployment that renamed its guide: a name within
- * {@link POINTER_GUIDE_NAME_BUDGET} is spelled out, and a longer one gets the
- * generic wording. Naming the file is the better sentence and wins whenever it
- * fits; a name past the budget is pathological, and there the choice is between
- * a sentence that says where to look and a catalog entry the client cuts. The
- * guide's own name is still in the section's first rule either way.
- *
- * An absent layout means the default one, as it does in
- * `composeAgentInstructions`: a caller reading the layout from configuration
- * gets `undefined` when none is set, and the pointer must still name a file.
- */
-export function sharedRulesPointer(layout: KbLayout = DEFAULT_KB_LAYOUT): string {
-  const agentsFile = agentsFileOf(layout);
-  const where =
-    agentsFile.length <= POINTER_GUIDE_NAME_BUDGET ? agentsFile : 'the agent guide at the KB root';
-  return ` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in ${where}.`;
-}
 
-/**
- * The most the pointer can ever cost a description, over every layout. What the
- * description cap is measured against, the way the tool prefix is measured at
- * ITS cap rather than at whatever the current admin wrote: a description that
- * only fits beside the short default guide name does not really fit.
- */
-export const SHARED_RULES_POINTER_MAX = Math.max(
-  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET - 3)}.md` }).length,
-  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET + 10)}.md` }).length,
-);