@bevel-software/platform-core-backend 0.35.0 → 0.37.0

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

@@ -41,6 +41,7 @@ import {
   resolveKbLayout,
   type KbLayout,
 } from '@bevel-software/platform-shared';
+import { ONBOARDING_GUIDE_SECTION_ID } from '@bevel-software/platform-mcp-core';
 import { agentGuideDir } from '../../assets.js';
 import { sharedFileRulesSection } from '../agent-instructions/index.js';
 
@@ -93,6 +94,19 @@ export type AgentGuideReader = () => Promise<string>;
 /** The computed section: the rules every file tool shares. */
 export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
 
+/**
+ * The sections a hook may neither drop nor empty, because something outside
+ * the guide points an agent at them by id (see `composeAgentGuide`).
+ */
+const REQUIRED_SECTIONS: readonly { id: string; pointedAtBy: string; content: string }[] = Object.freeze([
+  { id: WORKING_WITH_FILES_SECTION_ID, pointedAtBy: 'which every file tool points at', content: 'the rules' },
+  {
+    id: ONBOARDING_GUIDE_SECTION_ID,
+    pointedAtBy: "which the platform's `onboard` prompt points at",
+    content: 'an onboarding flow',
+  },
+]);
+
 /**
  * What to do on a knowledge base nobody has written in yet: the section the
  * `firstRun` note `start_session` answers with points at (see
@@ -116,6 +130,8 @@ export const WHOLE_GUIDE_SECTION = 'all';
  */
 export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
   START_HERE_SECTION_ID,
+  // Named in mcp-core, where the platform's `/onboard` prompt points at it.
+  ONBOARDING_GUIDE_SECTION_ID,
   'how-agents-find-things',
   'for-git-users',
   'glossary',
@@ -174,9 +190,10 @@ async function readCoreSectionFiles(): Promise<ReadonlyMap<string, string>> {
 /**
  * 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.
+ * is handed. `defaultBranch` is the branch the shared rules name (see
+ * {@link AgentGuideContext.defaultBranch}).
  */
-export async function coreAgentGuideSections(layout: KbLayout): Promise<AgentGuideSection[]> {
+export async function coreAgentGuideSections(layout: KbLayout, defaultBranch = ''): Promise<AgentGuideSection[]> {
   coreSectionFiles ??= readCoreSectionFiles();
   let files: ReadonlyMap<string, string>;
   try {
@@ -188,7 +205,7 @@ export async function coreAgentGuideSections(layout: KbLayout): Promise<AgentGui
   }
   return CORE_SECTION_IDS.map((id) =>
     id === WORKING_WITH_FILES_SECTION_ID
-      ? { id, body: sharedFileRulesSection(layout), literal: true }
+      ? { id, body: sharedFileRulesSection(layout, defaultBranch), literal: true }
       : { id, body: files.get(id)! },
   );
 }
@@ -205,8 +222,9 @@ export interface AgentGuideContext {
   /**
    * The knowledge base's default branch, rendered into `{{defaultBranch}}` so
    * the start section names the branch every file tool's `branch` takes for
-   * what is live. Read when the guide is composed: a fresh deployment gets its
-   * branch model from the setup screen after the services are built.
+   * what is live, and named by the shared file rules in the same sentence the
+   * MCP handshake carries. Read when the guide is composed: a fresh deployment
+   * gets its branch model from the setup screen after the services are built.
    */
   defaultBranch?: string;
 }
@@ -239,16 +257,19 @@ export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
  * its own under the same id, beside core's or in its place: of two sections
  * under one id the LAST is served, where the FIRST stood, so a distribution
  * overrides core's `start-here` or `html-views` by adding its own and the
- * guide keeps its order (see {@link oneSectionPerId}). 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.
+ * guide keeps its order (see {@link oneSectionPerId}). TWO exceptions, the
+ * sections something outside the guide points an agent at by id
+ * (`REQUIRED_SECTIONS`): the shared file rules
+ * ({@link WORKING_WITH_FILES_SECTION_ID}), which every file tool names — a
+ * client that drops the handshake instructions has the guide as the only
+ * place to read them — and the onboarding section
+ * ({@link ONBOARDING_GUIDE_SECTION_ID}), which the platform's `onboard`
+ * prompt sends an agent to. Each must come back WITH TEXT IN IT, as core's
+ * or as the hook's own replacement. A hook that drops one, 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,
@@ -256,7 +277,7 @@ export async function agentGuideSections(
   context: AgentGuideContext = {},
 ): Promise<RenderedGuideSection[]> {
   const resolved = resolveKbLayout(layout);
-  const core = await coreAgentGuideSections(resolved);
+  const core = await coreAgentGuideSections(resolved, context.defaultBranch);
   const sections = withRoutes(oneSectionPerId(hook ? await hook(core, resolved) : core));
   const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
   const defaultBranch = context.defaultBranch?.trim() || UNCONFIGURED_DEFAULT_BRANCH;
@@ -276,12 +297,17 @@ export async function agentGuideSections(
   // One section per id by now (`oneSectionPerId`), so a hook's own version
   // of the rules is what is judged, on what survives the empty-body filter
   // below.
-  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.',
-    );
+  // Two sections something outside the guide points at, so a hook may not
+  // take them away: the file tools name the rules, and the platform's
+  // `onboard` prompt sends an agent to the onboarding section by id.
+  for (const required of REQUIRED_SECTIONS) {
+    const found = rendered.filter((section) => section.id === required.id);
+    if (!found.some((section) => section.body.length > 0)) {
+      throw new Error(
+        `The agent guide hook ${found.length === 0 ? 'dropped' : 'emptied'} the "${required.id}" ` +
+          `section, ${required.pointedAtBy}. Keep it, or replace it under the same id with ${required.content} in it.`,
+      );
+    }
   }
   return rendered.filter((section) => section.body.length > 0);
 }

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

@@ -47,6 +47,7 @@ export const SECTION_TOKEN_BUDGET = 2_500;
  */
 export const SECTION_TOKEN_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'start-here': 1_200,
+  onboarding: SECTION_TOKEN_BUDGET,
   'how-agents-find-things': SECTION_TOKEN_BUDGET,
   'for-git-users': SECTION_TOKEN_BUDGET,
   glossary: SECTION_TOKEN_BUDGET,
@@ -66,8 +67,11 @@ export const SECTION_TOKEN_BUDGETS: Readonly<Record<string, number>> = Object.fr
   'new-knowledge-base': SECTION_TOKEN_BUDGET,
 });
 
-/** Every core section at once: what `section: "all"` returns. */
-export const WHOLE_GUIDE_TOKEN_BUDGET = 21_500;
+/**
+ * Every core section at once: what `section: "all"` returns. 23,000 since the
+ * `onboarding` section (about 1,200) was added; 21,500 before.
+ */
+export const WHOLE_GUIDE_TOKEN_BUDGET = 23_000;
 
 /** One task: the start section plus the sections it routes the task to. */
 export const TASK_TOKEN_BUDGET = 6_000;

package/src/modules/agent-instructions/__tests__/agent-instructions.route.test.ts

@@ -1,16 +1,15 @@
 import type { Server as HttpServer } from 'node:http';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { createManualAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
-import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../../tool-auth/internal-token.service.js';
-import type { AuthService } from '../../auth/auth.service.js';
+import { createManualAuthMiddleware } from '../../../__tests__/tool-wiring.js';
+import type { IExternalApiKeyService, InternalTokenService } from '../../tool-auth/index.js';
+import type { AuthService } from '../../auth/index.js';
 import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { TOOL_PREFIX_LINE, platformInstructions } from '../compose.js';
 
 /** The platform-owned text the route leads with: header + the shared file rules. */
-const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT, '');
 
 /**
  * `GET /agent/instructions` behind the REAL manual-auth gate, with the three

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

@@ -21,7 +21,7 @@ import {
  * The rules themselves are pinned in `shared-file-rules.test.ts`; here they are
  * only the fixed text the preamble follows.
  */
-const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT, '');
 
 describe('composeAgentInstructions: the handshake text', () => {
   it('sends the platform text alone — header and shared rules — for an absent, empty, whitespace or comment-only preamble', () => {

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

@@ -1,6 +1,10 @@
+import type { AddressInfo } from 'node:net';
+import type { Server as HttpServer } from 'node:http';
 import { DEFAULT_KB_LAYOUT, PREAMBLE_CAP } from '@bevel-software/platform-shared';
+import express from 'express';
 import { describe, expect, it } from 'vitest';
 import { composeAgentGuide } from '../../agent-guide/index.js';
+import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
 import {
   INSTRUCTIONS_CAP,
   PLATFORM_HEADER,
@@ -25,7 +29,7 @@ import {
 
 describe('the shared file rules are one text, in two places', () => {
   it('puts the identical section in the handshake instructions and in the agent guide', async () => {
-    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);
+    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT, '');
     expect(section.startsWith(`## ${SHARED_RULES_SECTION}\n\n`)).toBe(true);
 
     const instructions = composeAgentInstructions(null).instructions;
@@ -47,7 +51,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 = await composeAgentGuide(DEFAULT_KB_LAYOUT);
-    const rules = sharedFileRules(DEFAULT_KB_LAYOUT);
+    const rules = sharedFileRules(DEFAULT_KB_LAYOUT, '');
     expect(rules.map((r) => r.id)).toEqual([
       'agent-guide',
       'content-kinds',
@@ -104,8 +108,8 @@ describe('the shared file rules are one text, in two places', () => {
 
   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);
-    expect(section).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    const section = sharedFileRulesSection(layout, '');
+    expect(section).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
     expect(section).not.toContain('HEXIS.md');
     expect(composeAgentInstructions(null, layout).instructions).toContain(section);
     // The guide is not a platform file under any name: the list a move
@@ -115,8 +119,108 @@ describe('the shared file rules are one text, in two places', () => {
 
 });
 
+/**
+ * The guide's start names the deployment's default branch, but only to an
+ * agent that calls `get_agent_guide`; an agent left to guess guesses `main`,
+ * and on a deployment whose default is another branch writes where nobody
+ * reads. The conventions rule names it, on every channel the shared rules ride.
+ */
+describe('the default branch is named', () => {
+  const SENTENCE =
+    "This knowledge base's default branch is `target-company-state`: the branch people read and the usual target of a " +
+    'change request; pass it as `branch` unless you are working on a draft.';
+
+  /** The text under the "own conventions" heading, up to the next rule's heading. */
+  const conventions = (text: string): string => {
+    const start = text.indexOf("### This knowledge base's own conventions\n\n");
+    expect(start).toBeGreaterThanOrEqual(0);
+    const end = text.indexOf('\n### ', start + 1);
+    return text.slice(start, end);
+  };
+
+  it('says the name in one sentence under "This knowledge base\'s own conventions"', () => {
+    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT, 'target-company-state');
+    expect(conventions(section)).toContain(SENTENCE);
+    expect(section.split(SENTENCE)).toHaveLength(2);
+    expect(section).not.toContain('`main`');
+  });
+
+  it('says whatever the name is — `main` on a deployment that uses it', () => {
+    const rule = sharedFileRules(DEFAULT_KB_LAYOUT, 'main').find((r) => r.id === 'agent-guide')!.body;
+    expect(rule).toContain(SENTENCE.replace('target-company-state', 'main'));
+  });
+
+  it('names no branch while the deployment has none', () => {
+    const rule = sharedFileRules(DEFAULT_KB_LAYOUT, '').find((r) => r.id === 'agent-guide')!.body;
+    expect(rule).not.toContain('default branch is');
+  });
+
+  it('keeps a name holding a backtick inside one code span', () => {
+    // A valid ref name may carry a backtick; a plain span would end at it.
+    const rule = sharedFileRules(DEFAULT_KB_LAYOUT, 'release`candidate').find((r) => r.id === 'agent-guide')!.body;
+    expect(rule).toContain("default branch is ``release`candidate``: the branch");
+    const edge = sharedFileRules(DEFAULT_KB_LAYOUT, '`main`').find((r) => r.id === 'agent-guide')!.body;
+    expect(edge).toContain('default branch is `` `main` ``: the branch');
+  });
+
+  it('fits the caps with the longest branch name the platform accepts, so the caps are ceilings and not samples', () => {
+    // kb-fs refuses a branch name over 255 characters; the caps are measured
+    // with one of exactly that length, not with a typical name.
+    const longest = 'b'.repeat(255);
+    expect(sharedFileRulesSection(DEFAULT_KB_LAYOUT, longest).length).toBeLessThanOrEqual(SHARED_FILE_RULES_CAP);
+    expect(composeAgentInstructions('x'.repeat(PREAMBLE_CAP * 2), DEFAULT_KB_LAYOUT, longest).instructions.length).toBeLessThanOrEqual(
+      INSTRUCTIONS_CAP,
+    );
+  });
+
+  it('keeps a call that passes no branch working, naming none', () => {
+    // The helpers are exported: a caller written before the branch was named
+    // gets the text it got then, not a throw on an undefined name.
+    expect(sharedFileRules(DEFAULT_KB_LAYOUT)).toEqual(sharedFileRules(DEFAULT_KB_LAYOUT, ''));
+    expect(sharedFileRulesSection(DEFAULT_KB_LAYOUT)).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
+    expect(platformInstructions(DEFAULT_KB_LAYOUT)).toBe(platformInstructions(DEFAULT_KB_LAYOUT, ''));
+  });
+
+  it('carries the same sentence in the handshake instructions and in the managed guide', async () => {
+    const instructions = composeAgentInstructions(null, DEFAULT_KB_LAYOUT, 'target-company-state').instructions;
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT, undefined, { defaultBranch: 'target-company-state' });
+    expect(conventions(instructions)).toContain(SENTENCE);
+    expect(conventions(guide)).toContain(SENTENCE);
+    expect(instructions).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT, 'target-company-state'));
+    expect(guide).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT, 'target-company-state'));
+  });
+
+  it('names the renamed branch, and nothing else changes', async () => {
+    const before = composeAgentInstructions(null, DEFAULT_KB_LAYOUT, 'target-company-state').instructions;
+    const after = composeAgentInstructions(null, DEFAULT_KB_LAYOUT, 'company-state').instructions;
+    expect(after).toContain(SENTENCE.replace('target-company-state', 'company-state'));
+    expect(after).toBe(before.replaceAll('target-company-state', 'company-state'));
+  });
+
+  it('names the branch in effect on GET /agent/instructions, read per request', async () => {
+    let branch = 'target-company-state';
+    // Who may read the route is its own suite's question; here every caller passes.
+    const app = express();
+    app.use('/api', createAgentInstructionsRoutes((_req, _res, next) => next(), async () => null, undefined, () => branch));
+    const server = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    try {
+      const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/api/agent/instructions`;
+      const read = async () => ((await (await fetch(url)).json()) as { instructions: string }).instructions;
+      const before = await read();
+      expect(before).toBe(platformInstructions(DEFAULT_KB_LAYOUT, 'target-company-state'));
+      expect(conventions(before)).toContain(SENTENCE);
+      branch = 'company-state';
+      expect(await read()).toBe(before.replaceAll('target-company-state', 'company-state'));
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+});
+
 describe('the delete rule for platform files', () => {
-  const managedItems = (): string => sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'managed-items')!.body;
+  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();
@@ -131,7 +235,9 @@ describe('the delete rule for platform files', () => {
 
 describe('the handshake text stays inside the length it pins', () => {
   it('holds the shared section under its own cap', () => {
-    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);
+    // With a default branch named, as on every deployment past setup — the
+    // sentence naming it counts against the cap like any rule.
+    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT, 'target-company-state');
     expect(
       section.length,
       `the shared rules are ${section.length} characters (cap ${SHARED_FILE_RULES_CAP})`,
@@ -151,7 +257,7 @@ describe('the handshake text stays inside the length it pins', () => {
 
   it('hands the platform-owned text back as `header`, apart from the admin preamble', () => {
     const out = composeAgentInstructions('We sell permits.');
-    expect(out.header).toBe(platformInstructions(DEFAULT_KB_LAYOUT));
+    expect(out.header).toBe(platformInstructions(DEFAULT_KB_LAYOUT, ''));
     expect(out.header).toContain(PLATFORM_HEADER);
     expect(out.header).toContain(`## ${SHARED_RULES_SECTION}`);
     expect(out.preamble).toBe('We sell permits.');

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

@@ -27,12 +27,19 @@ export function createAgentInstructionsRoutes(
   manualAuth: RequestHandler,
   readPreamble: AgentPreambleReader,
   /**
-   * The layout in effect, read per request — the shared file rules name the
-   * 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`.
+   * The layout in effect, read per request — the shared file rules spell the
+   * root folders (`Skills/`, the knowledge folder) and the platform files by
+   * the names a deployment saved, which the setup save may change without a
+   * restart. Optional so a construction with no layout in hand gets the
+   * default layout. The guide itself is `AGENTS.md` on every deployment.
    */
   kbLayout?: () => KbLayout,
+  /**
+   * The default branch in effect, read per request, which the shared file
+   * rules name as the branch people read. Optional like the layout: without
+   * it the rules name no branch.
+   */
+  defaultBranch?: () => string,
 ): express.Router {
   const router = express.Router();
 
@@ -41,7 +48,7 @@ export function createAgentInstructionsRoutes(
     // successful one: the contract is on the route, not on the happy path.
     res.setHeader('Cache-Control', 'no-store');
     try {
-      res.json(composeAgentInstructions(await readPreamble(), kbLayout?.()));
+      res.json(composeAgentInstructions(await readPreamble(), kbLayout?.(), defaultBranch?.()));
     } catch (err) {
       log.error('reading mcp-description.md failed:', { err });
       res.status(500).json({ error: 'Failed to read the agent instructions' });

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

@@ -50,6 +50,13 @@ export const PLATFORM_HEADER =
   '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`. ' +
+  // Not said here: how to onboard someone new. The guide's start routes that
+  // question to the `onboarding` section, and that row is what the agents
+  // read (the agent-guide benchmark, 2026-10-29: every onboarding run reached
+  // the section through `start-here`, including the runs in clients that
+  // drop `instructions` — claude.ai on the web, the Agent SDK, Cline). The
+  // handshake stays the text an agent gets before it reads the guide, not a
+  // second copy of the guide's routing.
   // Said here as well as on the write tools: agents wrote to the default
   // branch without asking (the agent-guide benchmark, 2026-10-26), and this
   // text reaches an agent that never fetches the guide.
@@ -75,13 +82,13 @@ 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 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.
+ * A FUNCTION of the layout and the default branch, because the shared rules
+ * name the platform files by the root names a deployment chose (`Skills/`,
+ * `Plugins/`) and name the branch it reads from, 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)}`;
+export function platformInstructions(layout: KbLayout, defaultBranch = ''): string {
+  return `${PLATFORM_HEADER}\n\n${sharedFileRulesSection(layout, defaultBranch)}`;
 }
 
 /**
@@ -95,9 +102,11 @@ export function platformInstructions(layout: KbLayout): string {
  * test is what makes it a ceiling rather than a hope: a shared rule that grew
  * past it fails before it reaches an agent.
  *
- * 14,400 since the shared rules' own cap rose by 400 (the `__tmp__/` ref).
+ * 14,400 since the shared rules' own cap rose by 400 (the `__tmp__/` ref);
+ * 14,900 since it rose by 500 more (the sentence naming the default branch,
+ * measured with the longest name the platform accepts — see that cap).
  */
-export const INSTRUCTIONS_CAP = 14_400;
+export const INSTRUCTIONS_CAP = 14_900;
 
 /** The one-line marker that replaces everything past the preamble cap. */
 export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;
@@ -139,12 +148,18 @@ export interface ComposedAgentInstructions {
  * 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.
+ *
+ * `defaultBranch` is the branch the shared rules name as the one people read
+ * (`KbContext.defaultBranch`, read when composing). Without one — a caller
+ * with no knowledge base in hand, or a deployment not yet set up — the rules
+ * name no branch.
  */
 export function composeAgentInstructions(
   preamble: string | null,
   layout: KbLayout = DEFAULT_KB_LAYOUT,
+  defaultBranch = '',
 ): ComposedAgentInstructions {
-  const platform = platformInstructions(layout);
+  const platform = platformInstructions(layout, defaultBranch);
   const { text, unterminated } = stripHtmlComments(preamble ?? '');
   const normalized = text.replace(/\r\n?/g, '\n');
   const stripped = normalized.trim();

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

@@ -26,9 +26,11 @@
  * 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 name is a deployment
- * setting (an alias a deployment chose before the guide left the disk), so
- * nothing here may snapshot `AGENTS.md`.
+ * Pure text, a function of the layout and the default branch: both are
+ * deployment settings, so every caller passes the values in effect when it
+ * composes, and nothing here may snapshot a folder name or a branch name.
+ * The branch defaults to `''` (no branch named), so a caller that passes only
+ * the layout gets the text it got before the branch was named.
  */
 
 import {
@@ -65,8 +67,14 @@ const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
  * 7,400 since the `__tmp__/` ref: four tools take it, so what it reaches and
  * that it is read-only is said once here rather than in each description, and
  * the section had no room left for it.
+ *
+ * 7,900 since the conventions rule names the default branch: the guide's start
+ * names it too, but only to an agent that calls `get_agent_guide`, and the
+ * sentence is ~165 characters plus the name. A CEILING, not a sample: measured
+ * with the longest branch name the platform accepts (255 characters, the
+ * bound `kb-fs` enforces), so no deployment's name can push the rules past it.
  */
-export const SHARED_FILE_RULES_CAP = 7_400;
+export const SHARED_FILE_RULES_CAP = 7_900;
 
 /** One shared rule: how the guide heads it, and the rule itself. */
 export interface SharedFileRule {
@@ -87,12 +95,12 @@ export interface SharedFileRule {
  * than rewritten wherever the wording still reads outside its old tool — the
  * ones that said "this tool" or "this call" name the tools instead.
  */
-export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
+export function sharedFileRules(layout: KbLayout, defaultBranch = ''): readonly SharedFileRule[] {
   return [
     {
       id: 'agent-guide',
       heading: "This knowledge base's own conventions",
-      body: conventionsRule(),
+      body: conventionsRule(defaultBranch),
     },
     {
       id: 'content-kinds',
@@ -245,23 +253,57 @@ function platformFileList(layout: KbLayout): string {
  * named as a fallback because a knowledge base seeded before the rename may
  * still carry one its people edited.
  */
-function conventionsRule(): string {
-  return (
+function conventionsRule(defaultBranch: string): string {
+  const guide =
     "Before your first read or change in a workspace, call `get_agent_guide`: it answers the guide's start, " +
     "which names the default branch and the section for each question. " +
     `read_file on \`${LEGACY_AGENTS_FILE}\` at the KB root answers with ` +
     "that start, 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.`
+    `\`${PRE_RENAME_AGENTS_FILE}\` at the KB root is the organisation's own too; read it if it exists.`;
+  const branch = defaultBranchSentence(defaultBranch);
+  return branch ? `${guide}\n\n${branch}` : guide;
+}
+
+/**
+ * The one sentence naming the deployment's default branch. The guide's start
+ * names it too, but only once an agent calls `get_agent_guide`; every file
+ * tool asks for "the branch you are working on", and an agent left to guess
+ * guesses `main`, which on a deployment whose default is another branch
+ * writes where nobody reads. So the rules every channel carries name it.
+ *
+ * Empty while the deployment has no branch model (`KbContext.defaultBranch` is
+ * `''` until setup is answered): there is no name to give yet.
+ */
+function defaultBranchSentence(defaultBranch: string): string {
+  const name = defaultBranch.trim();
+  if (!name) return '';
+  return (
+    `This knowledge base's default branch is ${markdownCodeSpan(name)}: the branch people read and the usual target of a ` +
+    'change request; pass it as `branch` unless you are working on a draft.'
   );
 }
 
+/**
+ * `text` as one Markdown code span whatever it contains: a fence one backtick
+ * longer than the longest run inside it, padded with a space where the text
+ * starts or ends with a backtick (CommonMark strips one such space). A branch
+ * name may hold a backtick, and a plain `` `name` `` would end the span early
+ * and leave the rest of the sentence naming half a branch.
+ */
+function markdownCodeSpan(text: string): string {
+  const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = '`'.repeat(longestRun + 1);
+  const padded = text.startsWith('`') || text.endsWith('`') ? ` ${text} ` : text;
+  return `${fence}${padded}${fence}`;
+}
+
 /**
  * The shared rules as ONE markdown section — the string both channels carry,
  * byte for byte. A `##` section so it drops into the managed guide at that
  * level and still reads as a block in the instructions blob.
  */
-export function sharedFileRulesSection(layout: KbLayout): string {
-  const body = sharedFileRules(layout)
+export function sharedFileRulesSection(layout: KbLayout, defaultBranch = ''): string {
+  const body = sharedFileRules(layout, defaultBranch)
     .map((rule) => `### ${rule.heading}\n\n${rule.body}`)
     .join('\n\n');
   return `## ${SHARED_RULES_SECTION}\n\n${body}`;

package/src/modules/agent-scope/__tests__/agent-surfaces.connect-as.test.ts

@@ -133,7 +133,7 @@ async function start(opts: { agentScope?: boolean } = {}): Promise<string> {
   const resolve = createToolContextResolver({
     authService: { getUserById: async () => ADA } as never,
     workspaceService: {} as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     kbDirName: 'knowledge-base',
     creatorAccess: {} as never,