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

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

@@ -3,13 +3,23 @@ import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
 import { GET_AGENT_GUIDE_TOOL, TOOL_DESCRIPTION_CAP } from '../tool-registry/index.js';
 import { ToolError, toolDef } from '../tool-helpers/index.js';
 import type { ToolHandlerFactory } from '../tool-helpers/index.js';
-import { AGENT_GUIDE_FILE, joinGuideSections, type AgentGuideSectionsReader } from './agent-guide.js';
+import {
+  AGENT_GUIDE_FILE,
+  START_HERE_SECTION_ID,
+  WHOLE_GUIDE_SECTION,
+  joinGuideSections,
+  type AgentGuideSectionsReader,
+} from './agent-guide.js';
 
 export { GET_AGENT_GUIDE_TOOL };
 
 /**
- * The one tool that returns the guide on its own — whole, or one section by
- * id. It takes nothing else: the guide is the platform's text for this
+ * The one tool that returns the guide on its own: the start section when no
+ * section is named, one section by id, or the whole guide (`all`). Start
+ * section by default because this is the call every tool description tells
+ * an agent, and each sub-agent it starts, to make first: answering it with
+ * the whole guide made the most-read text the platform has also its longest.
+ * It takes nothing else: the guide is the platform's text for this
  * deployment, the same for every caller and every branch, and reading it
  * touches no file — so no `branch`, no `sessionId`, and no access gate. The
  * other way to the same text is a `read_file` of `AGENTS.md` at the
@@ -33,27 +43,30 @@ export function registerAgentGuideTool(
   const build = async (): Promise<UtcpTool> => {
     const list = await sections();
     const describe = (sectionList: string) =>
-      "The platform's guide to this knowledge base: its layout, where a new file goes, the rules every file tool " +
-      'shares, access control, skills and tool manuals. ALWAYS call this first and read the guide before you do ' +
-      'anything else in the platform. Returns `{ guide }` as markdown: the whole guide, or one section when ' +
-      '`section` names one. The same text comes back from `read_file` on `' +
+      "The platform's guide to this knowledge base. ALWAYS call this first, before anything else in the " +
+      'platform. With no `section` it returns the start section: the default branch every file tool takes, the ' +
+      'first-call rules, and which section answers which question. Then fetch only the section a task needs, by ' +
+      '`section`; only `"' +
+      WHOLE_GUIDE_SECTION +
+      '"` returns the whole guide. `read_file` on `' +
       AGENT_GUIDE_FILE +
-      "` at the KB root, after the knowledge base's own " +
+      "` at the KB root answers with the same start section (after the knowledge base's own " +
       AGENT_GUIDE_FILE +
-      ` when it has one. Sections: ${sectionList}.`;
+      ` when it has one). Returns \`{ guide }\` as markdown. Sections: ${sectionList}.`;
     // The description stays under the cap WHATEVER a distribution adds, in
     // three steps: every id with its title; every id alone; as many ids as
     // fit and a count of the rest. An id a client cut off the end would be a
     // section an agent cannot ask for — so nothing is ever cut: the one
-    // complete list of sections is `sections` on the whole-guide response,
-    // which the description names when it cannot carry them all itself.
+    // complete list of sections is `sections` on the answer to a call
+    // without one, which the description names when it cannot carry them
+    // all itself.
     const titled = describe(list.map((s) => `\`${s.id}\` (${s.title})`).join(', '));
     const ids = list.map((s) => `\`${s.id}\``);
     const counted = (shown: number) =>
       describe(
         shown === 0
-          ? `${ids.length}, named under \`sections\` in the whole-guide response`
-          : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the whole-guide response`].join(', '),
+          ? `${ids.length}, named under \`sections\` in the answer`
+          : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the answer`].join(', '),
       );
     let description = titled.length <= TOOL_DESCRIPTION_CAP ? titled : describe(ids.join(', '));
     for (let shown = ids.length; description.length > TOOL_DESCRIPTION_CAP && shown > 0; shown--) {
@@ -69,8 +82,10 @@ export function registerAgentGuideTool(
           section: {
             type: 'string',
             description:
-              'Optional: the id of one section to read instead of the whole guide (the ids are listed in this ' +
-              'description, and every one under `sections` in the whole-guide response). Omit it for the whole guide.',
+              'Optional: the id of one section to read (the ids are listed in this description, and every one under ' +
+              '`sections` in the answer), or `"' +
+              WHOLE_GUIDE_SECTION +
+              '"` for the whole guide. Omit it for the start section.',
           },
         },
         additionalProperties: false,
@@ -78,18 +93,18 @@ export function registerAgentGuideTool(
       outputs: {
         type: 'object',
         properties: {
-          guide: { type: 'string', description: 'The guide, or the one section asked for, as markdown.' },
+          guide: { type: 'string', description: 'The section asked for (the start section by default), or the whole guide, as markdown.' },
           sections: {
             type: 'array',
-            description: 'Without `section`: every section of the guide, in order, by id and heading — the complete list.',
+            description: `Without \`section\`, or with \`"${WHOLE_GUIDE_SECTION}"\`: every section of the guide, in order, by id and heading — the complete list.`,
             items: {
               type: 'object',
               properties: { id: { type: 'string' }, title: { type: 'string' } },
               required: ['id', 'title'],
             },
           },
-          section: { type: 'string', description: 'With `section`: the id of the section returned.' },
-          title: { type: 'string', description: 'With `section`: its heading.' },
+          section: { type: 'string', description: 'The id of the one section returned.' },
+          title: { type: 'string', description: 'Its heading.' },
         },
         required: ['guide'],
       },
@@ -102,15 +117,29 @@ export function registerAgentGuideTool(
   router.post(
     `/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
     toolAuth,
-    toolHandler(async (args) => {
+    toolHandler(async (args, ctx) => {
       const list = await sections();
+      const index = list.map((s) => ({ id: s.id, title: s.title }));
       const wanted = typeof args.section === 'string' ? args.section.trim() : '';
-      if (!wanted) return { guide: joinGuideSections(list), sections: list.map((s) => ({ id: s.id, title: s.title })) };
+      // A distribution that dropped the start section gets the whole guide by
+      // default, as before there was one: never an answer with nothing in it.
+      const start = list.find((s) => s.id === START_HERE_SECTION_ID);
+      // A connection made as an agent configuration is told so at the top of
+      // the guide's first answer and of the whole guide: the catalog it
+      // describes is narrowed to that agent. Everything is told nothing new,
+      // so its guide is the same text.
+      const connection = ctx.connectionScope?.describe() ?? null;
+      const told = (guide: string) => ({
+        guide: connection ? `> ${connection}\n\n${guide}` : guide,
+        ...(connection ? { connection } : {}),
+      });
+      if (wanted === WHOLE_GUIDE_SECTION || (!wanted && !start)) return { ...told(joinGuideSections(list)), sections: index };
+      if (!wanted) return { ...told(start!.body), section: start!.id, title: start!.title, sections: index };
       const one = list.find((s) => s.id === wanted);
       if (!one) {
         throw new ToolError(
           `The guide has no section "${wanted}". Sections: ${list.map((s) => `\`${s.id}\``).join(', ')}. ` +
-            'Omit `section` for the whole guide.',
+            `Omit \`section\` for the start section, or pass \`"${WHOLE_GUIDE_SECTION}"\` for the whole guide.`,
           400,
         );
       }

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

@@ -20,10 +20,17 @@
  * 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.
+ * `{{agentsFile}}`), the checkout folder's `{{kbDirName}}` and the default
+ * branch's `{{defaultBranch}}`. 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.
+ *
+ * The guide is LAYERED (see openspec/changes/agent-guide-layers/design.md):
+ * `get_agent_guide` with no section answers with the short start section
+ * ({@link START_HERE_SECTION_ID}), which says which section answers which
+ * question, and an agent fetches the others by id when a task needs them.
+ * Each section has a token budget (`guide-budget.ts`), held by a test.
  */
 
 import fs from 'node:fs/promises';
@@ -59,6 +66,13 @@ export interface AgentGuideSection {
    * could only misread a folder name it STATES as a placeholder.
    */
   literal?: boolean;
+  /**
+   * The question this section answers, as a row of the start section's
+   * "which section answers what" table. Core's sections are in that table
+   * already; a distribution sets it on a section it adds, so an agent that
+   * reads only the start section is routed to it.
+   */
+  asks?: string;
 }
 
 /**
@@ -86,21 +100,35 @@ export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
  */
 export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
 
+/**
+ * The first-contact section: what `get_agent_guide` answers when no section is
+ * named. Short on purpose, and the one place that maps each question to the
+ * section answering it, so an agent fetches one section rather than the guide.
+ */
+export const START_HERE_SECTION_ID = 'start-here';
+
+/** The `section` that asks `get_agent_guide` for every section at once. */
+export const WHOLE_GUIDE_SECTION = 'all';
+
 /**
  * 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',
+  START_HERE_SECTION_ID,
+  'how-agents-find-things',
+  'for-git-users',
+  'glossary',
   'directory-structure',
   'where-a-new-file-goes',
   WORKING_WITH_FILES_SECTION_ID,
   'access-control',
+  'drafts-and-change-requests',
   'skills',
+  'tools',
   'tool-manuals',
   'html-views',
   'conventions',
-  'finding-things',
   NEW_KNOWLEDGE_BASE_SECTION_ID,
 ]);
 
@@ -174,11 +202,21 @@ export interface AgentGuideContext {
    * deployment's tools report back.
    */
   kbDirName?: string;
+  /**
+   * 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.
+   */
+  defaultBranch?: string;
 }
 
 /** The checkout folder's name when none is given — core's own default. */
 const DEFAULT_KB_DIR_NAME = 'knowledge-base';
 
+/** What `{{defaultBranch}}` reads as when no branch is configured yet: a name no branch can have. */
+const UNCONFIGURED_DEFAULT_BRANCH = '<the default branch>';
+
 /** One section of the guide as an agent reads it: rendered, with the heading's text as its title. */
 export interface RenderedGuideSection {
   id: string;
@@ -197,7 +235,11 @@ export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
  * 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
+ * A hook may append, replace and drop sections. It replaces one by returning
+ * 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
@@ -215,18 +257,25 @@ export async function agentGuideSections(
 ): Promise<RenderedGuideSection[]> {
   const resolved = resolveKbLayout(layout);
   const core = await coreAgentGuideSections(resolved);
-  const sections = hook ? await hook(core, resolved) : core;
+  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;
   const rendered = sections.map((section) => {
     const body = (
       section.literal
         ? section.body
-        : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)
+        : renderKbLayoutPlaceholders(
+            section.body
+              .replaceAll('{{kbDirName}}', () => kbDirName)
+              .replaceAll('{{defaultBranch}}', () => defaultBranch),
+            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.
+  // 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(
@@ -237,6 +286,51 @@ export async function agentGuideSections(
   return rendered.filter((section) => section.body.length > 0);
 }
 
+/**
+ * One section per id. A hook that returns an id twice (its own version of a
+ * core section, added beside core's) means the later one: it is served in
+ * the earlier one's place, so a distribution overrides a section by adding
+ * its own under the same id, and the guide keeps core's order. Without this
+ * the whole guide carried both and `get_agent_guide` served the first, which
+ * was always core's.
+ */
+function oneSectionPerId(sections: readonly AgentGuideSection[]): readonly AgentGuideSection[] {
+  const at = new Map<string, number>();
+  const out: AgentGuideSection[] = [];
+  for (const section of sections) {
+    const index = at.get(section.id);
+    if (index === undefined) {
+      at.set(section.id, out.length);
+      out.push(section);
+    } else {
+      out[index] = section;
+    }
+  }
+  return out;
+}
+
+/**
+ * Adds a row to the start section's routing table for every section that
+ * says what it {@link AgentGuideSection.asks} and is not routed there yet.
+ * The rows go after the table's last row. A start section without the table
+ * (a distribution replaced it) is left as it is.
+ */
+function withRoutes(sections: readonly AgentGuideSection[]): readonly AgentGuideSection[] {
+  const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+  if (!start) return sections;
+  const routed = sections.filter((section) => section.asks?.trim() && !start.body.includes(`| \`${section.id}\` |`));
+  if (routed.length === 0) return sections;
+  const lines = start.body.split('\n');
+  const header = lines.findIndex((line) => /^\|\s*Question\s*\|\s*Section\s*\|/.test(line));
+  if (header < 0) return sections;
+  let last = header;
+  while (last + 1 < lines.length && lines[last + 1]!.startsWith('|')) last += 1;
+  const rows = routed.map((section) => `| ${section.asks!.trim().replaceAll('|', '\\|')} | \`${section.id}\` |`);
+  lines.splice(last + 1, 0, ...rows);
+  const body = lines.join('\n');
+  return sections.map((section) => (section === start ? { ...start, body } : section));
+}
+
 /**
  * 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
@@ -260,6 +354,19 @@ export async function composeAgentGuide(
   return joinGuideSections(await agentGuideSections(layout, hook, context));
 }
 
+/**
+ * What a `read_file` of the guide's name answers: the start section and the
+ * list of every section, the same as `get_agent_guide` with no `section`, so
+ * no read hands an agent the whole guide unless it asks for it. A guide
+ * without a start section (a distribution dropped it) is answered whole.
+ */
+export function guideStartText(sections: readonly RenderedGuideSection[]): string {
+  const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+  if (!start) return joinGuideSections(sections);
+  const list = sections.map((section) => `- \`${section.id}\`: ${section.title}`).join('\n');
+  return `${start.body}\n\n### Every section\n\n${list}\n`;
+}
+
 /** 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`;
@@ -268,12 +375,12 @@ export function joinGuideSections(sections: readonly RenderedGuideSection[]): st
 /**
  * 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
+ * saying what follows, then the start of 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._";
+  "---\n\n_The text above is this knowledge base's own conventions file. The start of the platform's guide follows; `get_agent_guide` with a `section` returns the rest._";
 
 export function withPlatformGuideAppended(ownText: string, guide: string): string {
   // Their text as they wrote it, line endings normalised and the trailing

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

@@ -0,0 +1,73 @@
+/**
+ * How much each layer of what an agent is told may cost, in tokens.
+ *
+ * Three layers (openspec/changes/agent-guide-layers/design.md): what every
+ * connection carries (the handshake instructions and the tool list), what an
+ * agent reads on first contact (the start section `get_agent_guide` answers
+ * with), and what it fetches only when a task needs it (every other section).
+ * A line in the first layer costs every conversation and every sub-agent; a
+ * line in the last costs only the tasks that fetch it. The budgets are what
+ * keeps the guide from growing into a document every agent loads whole and
+ * reads little of, which is what a customer's agent did fifteen times in one
+ * day.
+ *
+ * Counted with the `o200k_base` encoding by `__tests__/guide-budget.test.ts`.
+ * It is a real tokenizer that runs offline; it is not Claude's own, which
+ * usually counts somewhat more for the same text, so these are ceilings to
+ * compare against each other and over time rather than a model's bill.
+ *
+ * Every number is one a reviewer may move. The point of pinning them is that
+ * growing the guide is a decision someone takes, not a paragraph someone
+ * appends: a section that needs more room says why in the pull request that
+ * raises its line here.
+ */
+
+/** The encoding the budgets are counted in. */
+export const GUIDE_TOKEN_ENCODING = 'o200k_base';
+
+/** The platform's part of the handshake instructions: the header and the shared file rules. */
+export const INSTRUCTIONS_TOKEN_BUDGET = 2_000;
+
+/**
+ * The platform's own tools as the hosted endpoint lists them to an MCP client:
+ * each name, description (with its `Call:` line and, on the four
+ * knowledge-base tools, the purpose prefix) and input schema. Measured over
+ * every registrar the root mounts, the change-request readers and `open_page`
+ * included: 46 tools, 17,278 tokens at 0.35.0 (an earlier figure of 15,710
+ * left those five out).
+ */
+export const TOOL_LIST_TOKEN_BUDGET = 17_500;
+
+/** The ceiling for a section a distribution adds, which core's checks cannot see: the same as core's own. */
+export const SECTION_TOKEN_BUDGET = 2_500;
+
+/**
+ * Each core section's budget, by id. A section without a line here fails the
+ * budget test: a new section starts by saying what it may cost.
+ */
+export const SECTION_TOKEN_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
+  'start-here': 1_200,
+  'how-agents-find-things': SECTION_TOKEN_BUDGET,
+  'for-git-users': SECTION_TOKEN_BUDGET,
+  glossary: SECTION_TOKEN_BUDGET,
+  'directory-structure': SECTION_TOKEN_BUDGET,
+  'where-a-new-file-goes': SECTION_TOKEN_BUDGET,
+  'working-with-files': SECTION_TOKEN_BUDGET,
+  'access-control': SECTION_TOKEN_BUDGET,
+  'drafts-and-change-requests': SECTION_TOKEN_BUDGET,
+  skills: SECTION_TOKEN_BUDGET,
+  tools: SECTION_TOKEN_BUDGET,
+  'tool-manuals': SECTION_TOKEN_BUDGET,
+  // The page contract is long by nature (the frame, the bridge, the link
+  // rules, pages that load live data), and an agent fetches it only to build
+  // a page.
+  'html-views': 5_500,
+  conventions: SECTION_TOKEN_BUDGET,
+  'new-knowledge-base': SECTION_TOKEN_BUDGET,
+});
+
+/** Every core section at once: what `section: "all"` returns. */
+export const WHOLE_GUIDE_TOKEN_BUDGET = 21_500;
+
+/** One task: the start section plus the sections it routes the task to. */
+export const TASK_TOKEN_BUDGET = 6_000;

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

@@ -3,10 +3,13 @@ export {
   CORE_SECTION_IDS,
   NEW_KNOWLEDGE_BASE_SECTION_ID,
   PLATFORM_GUIDE_SEPARATOR,
+  START_HERE_SECTION_ID,
+  WHOLE_GUIDE_SECTION,
   WORKING_WITH_FILES_SECTION_ID,
   agentGuideSections,
   composeAgentGuide,
   coreAgentGuideSections,
+  guideStartText,
   isAgentGuidePath,
   isManagedGuide,
   joinGuideSections,
@@ -19,4 +22,13 @@ export {
   type RenderedGuideSection,
 } from './agent-guide.js';
 export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export {
+  GUIDE_TOKEN_ENCODING,
+  INSTRUCTIONS_TOKEN_BUDGET,
+  SECTION_TOKEN_BUDGET,
+  SECTION_TOKEN_BUDGETS,
+  TASK_TOKEN_BUDGET,
+  TOOL_LIST_TOKEN_BUDGET,
+  WHOLE_GUIDE_TOKEN_BUDGET,
+} from './guide-budget.js';
 export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/index.js';

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

@@ -1,6 +1,6 @@
 import { DEFAULT_KB_LAYOUT, PREAMBLE_CAP } from '@bevel-software/platform-shared';
 import { describe, expect, it } from 'vitest';
-import { composeAgentGuide } from '../../agent-guide/agent-guide.js';
+import { composeAgentGuide } from '../../agent-guide/index.js';
 import {
   INSTRUCTIONS_CAP,
   PLATFORM_HEADER,
@@ -51,6 +51,7 @@ describe('the shared file rules are one text, in two places', () => {
     expect(rules.map((r) => r.id)).toEqual([
       'agent-guide',
       'content-kinds',
+      'workspace-tmp',
       'write-mode',
       'images-in-pages',
       'escape-sequences',
@@ -92,10 +93,10 @@ describe('the shared file rules are one text, in two places', () => {
    * 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', () => {
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with that start 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("call `get_agent_guide`: it answers the guide's start, which names the default branch");
+    expect(rule).toContain('read_file on `AGENTS.md` at the KB root answers with that start');
     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`');

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

@@ -50,6 +50,10 @@ 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`. ' +
+  // 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.
+  'A write to the default branch is live for everyone: unless the person said where, ask first whether to write there or on a draft. ' +
   // 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.
@@ -90,8 +94,10 @@ export function platformInstructions(layout: KbLayout): string {
  * own cap, and the preamble under its cap plus the marker a cut appends. The
  * 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).
  */
-export const INSTRUCTIONS_CAP = 14_000;
+export const INSTRUCTIONS_CAP = 14_400;
 
 /** 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}]`;

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

@@ -61,8 +61,12 @@ const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
  * of every call rather than of how to write one, and why large, escape-heavy
  * and binary content goes by upload, which three write tools each said in
  * full.
+ *
+ * 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.
  */
-export const SHARED_FILE_RULES_CAP = 7_000;
+export const SHARED_FILE_RULES_CAP = 7_400;
 
 /** One shared rule: how the guide heads it, and the rule itself. */
 export interface SharedFileRule {
@@ -114,6 +118,18 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         '`{ image_omitted, note }` stub instead, so read an image outside a chain when you mean to look at it. Any other ' +
         'binary file reads as a one-line description rather than raw bytes.',
     },
+    {
+      // What `__tmp__/` reaches and what it does not (see
+      // `workspace/workspace-tmp.ts`) — four tools take the ref, so it is a
+      // shared rule rather than a sentence in each description.
+      id: 'workspace-tmp',
+      heading: "Files staged in the workspace's tmp folder",
+      body:
+        "`__tmp__/<path>` names ONE file YOU staged in the branch workspace's `tmp/` folder (chat attachments land " +
+        'there; nobody else\'s staged files are reachable). read_file, file_stat, grep (`path`) and copy_file (`src`) ' +
+        'read it as a repository file; it is read-only and never listed — copy_file it to a repository path to keep ' +
+        'it. An entry stays up to seven days.',
+    },
     {
       id: 'write-mode',
       heading: 'What a write may do at a path',
@@ -161,10 +177,10 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       body:
         'move_file, copy_file and delete_folder take `dryRun: true`: it changes nothing and answers the impact — ' +
         '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 ' +
+        'move that changes anyone\'s 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: check it first with file_stat ' +
-        '(`deletable`) if you are unsure. delete_branch has its own `dryRun`.',
+        '(`deletable`). delete_branch has its own `dryRun`.',
     },
     {
       id: 'managed-items',
@@ -184,7 +200,7 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       id: 'refused-for-permissions',
       heading: 'When a write is refused for permissions',
       body:
-        'A refusal is not necessarily the end of the road: the `write-denied` error says whether you may propose the ' +
+        'The `write-denied` error says whether you may propose the ' +
         'change instead (create a branch from this one, repeat the call on it, then `open_change_request` into this ' +
         'branch) and lists those steps.',
     },
@@ -222,17 +238,19 @@ function platformFileList(layout: KbLayout): string {
  * The conventions reminder — where the platform's guide is, that the
  * organisation's own conventions file comes with it, and to read both first.
  *
- * 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.
+ * The guide's start is read by name at the repository root, where coding
+ * agents look for an `AGENTS.md` by convention, and `get_agent_guide` returns
+ * it or any one section.
  * 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(): string {
   return (
-    "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 " +
+    "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.`
   );
 }