@bevel-software/platform-core-backend 0.34.0 → 0.36.1

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'],
       },
@@ -104,24 +119,27 @@ export function registerAgentGuideTool(
     toolAuth,
     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() : '';
-      // A connection made as an agent configuration is told so at the top 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.
+      // 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;
-      if (!wanted) {
-        const guide = joinGuideSections(list);
-        return {
-          guide: connection ? `> ${connection}\n\n${guide}` : guide,
-          sections: list.map((s) => ({ id: s.id, title: s.title })),
-          ...(connection ? { connection } : {}),
-        };
-      }
+      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';
@@ -34,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';
 
@@ -59,6 +67,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;
 }
 
 /**
@@ -79,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
@@ -86,21 +114,37 @@ 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,
+  // 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',
   '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,
 ]);
 
@@ -146,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 {
@@ -160,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)! },
   );
 }
@@ -174,11 +219,22 @@ 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, 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;
 }
 
 /** 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,16 +253,23 @@ 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
- * 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.
+ * 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}). 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,
@@ -214,29 +277,86 @@ export async function agentGuideSections(
   context: AgentGuideContext = {},
 ): Promise<RenderedGuideSection[]> {
   const resolved = resolveKbLayout(layout);
-  const core = await coreAgentGuideSections(resolved);
-  const sections = hook ? await hook(core, resolved) : core;
+  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;
   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.
-  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.',
-    );
+  // 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.
+  // 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);
 }
 
+/**
+ * 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 +380,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 +401,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,77 @@
+/**
+ * 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,
+  onboarding: SECTION_TOKEN_BUDGET,
+  '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. 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-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__/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', () => {