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

package/src/modules/access/user-access-removal.service.ts

@@ -37,9 +37,9 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { PushNeedsAgentResolutionError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   ADMIN_CANONICAL,
@@ -92,7 +92,7 @@ async function mapPooled<T, R>(items: readonly T[], limit: number, fn: (item: T)
 }
 
 /** A removal this service refuses (guard) or cannot run. */
-export class UserAccessRemovalError extends WorkflowDomainError {
+export class UserAccessRemovalError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'UserAccessRemovalError';
@@ -343,7 +343,7 @@ export class UserAccessRemovalService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    workflowService: IWorkflowService,
+    versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /**
      * The resolver's own walk. NOT `workspaceService.listFiles`: that honours
@@ -354,13 +354,13 @@ export class UserAccessRemovalService {
     private readonly kbDirName: string,
     /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
     private readonly defaultBranchOf: () => string,
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
     /** The deployment owner(s) (`ADMIN_EMAIL`) — never removed this way. */
     private readonly deploymentOwners: readonly string[] = [],
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new UserAccessRemovalError(message, status, payload),

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -145,7 +145,7 @@ describe('the access-frontmatter extension set', () => {
   it('throws on a malformed extension rather than skipping it', () => {
     // A typo would otherwise leave capability-granting files ungoverned, at
     // boot, with nothing to distinguish it from a successful registration.
-    expect(() => registerAccessFrontmatterExtensions(['pipeline'])).toThrow(/malformed/);
+    expect(() => registerAccessFrontmatterExtensions(['workflow'])).toThrow(/malformed/);
     expect(() => registerAccessFrontmatterExtensions(['.two.dots'])).toThrow(/malformed/);
     expect(() => registerAccessFrontmatterExtensions([''])).toThrow(/malformed/);
     expect(hasAccessFrontmatterExtension('x.pipeline_typo_guard')).toBe(false);
@@ -186,7 +186,7 @@ describe('the access-frontmatter extension set', () => {
 });
 
 describe('parseOwnAccessEntries — whole-document YAML the subset parser cannot read', () => {
-  // A `.tool` / `.pipeline` / `.agent` is one `---` fenced YAML document, and
+  // A `.tool` / `.workflow` / `.agent` is one `---` fenced YAML document, and
   // real ones use folded and literal scalars and nested maps. The subset
   // parser stops at the first such line; the verbs must still be read.
   const doc = [

package/src/modules/access-model/access-errors.ts

@@ -1,4 +1,4 @@
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 
 export interface AccessDeniedDetails {
@@ -55,7 +55,7 @@ export function unreadableRefusalSentence(repoRelative: string): string {
  * "you don't have permission to write to <path>; eligible: <roles + users>"
  * without a follow-up roundtrip.
  */
-export class AccessDeniedError extends WorkflowDomainError {
+export class AccessDeniedError extends VersionControlDomainError {
   readonly access: AccessDeniedDetails;
 
   constructor(details: AccessDeniedDetails) {
@@ -89,7 +89,7 @@ export class AccessDeniedError extends WorkflowDomainError {
  * 503 and the caller retries. Distinct from AccessConfigError (the config is
  * there and wrong) and AccessDeniedError (a real permission decision).
  */
-export class AccessUnreadableError extends WorkflowDomainError {
+export class AccessUnreadableError extends VersionControlDomainError {
   constructor(ref: string, relativePath: string) {
     super(
       `Access rules at ${ref} could not be read (git failed on ${relativePath}); nothing was decided. Try again.`,
@@ -105,7 +105,7 @@ export class AccessUnreadableError extends WorkflowDomainError {
  * or malformed at runtime — distinct from AccessDeniedError because the cause
  * is a config bug, not a permission decision.
  */
-export class AccessConfigError extends WorkflowDomainError {
+export class AccessConfigError extends VersionControlDomainError {
   readonly errors: string[];
 
   constructor(errors: string[]) {

package/src/modules/access-model/access-grammar.ts

@@ -285,8 +285,8 @@ const accessFrontmatterExtensions = new Set<string>(CORE_ACCESS_FRONTMATTER_EXTE
  */
 export function registerAccessFrontmatterExtensions(extensions: readonly string[]): void {
   // Validate EVERYTHING first, then apply. These registrations decide which
-  // files' edits carry enforced access grants, so a typo (`pipeline` for
-  // `.pipeline`) must THROW rather than be skipped — a silent skip makes a
+  // files' edits carry enforced access grants, so a typo (`workflow` for
+  // `.workflow`) must THROW rather than be skipped — a silent skip makes a
   // failed registration indistinguishable from a successful one, at boot,
   // where nobody is looking. And it must throw before the registry changes:
   // a list that is half-applied when it throws leaves later scans governing a
@@ -295,7 +295,7 @@ export function registerAccessFrontmatterExtensions(extensions: readonly string[
     const n = ext.trim().toLowerCase();
     if (!/^\.[a-z0-9]+$/.test(n)) {
       throw new Error(
-        `access frontmatter extension "${ext}" is malformed — expected a leading dot, e.g. ".pipeline"`,
+        `access frontmatter extension "${ext}" is malformed — expected a leading dot, e.g. ".workflow"`,
       );
     }
     return n;
@@ -313,7 +313,7 @@ export function accessFrontmatterExtensionList(): string[] {
  *
  * Case-SENSITIVE on the path, as it always was: `doc.MD` is not a node and
  * carries no enforced grant. Registered extensions are normalized to lowercase
- * so `.Pipeline` and `.pipeline` register the same thing, but which FILES are
+ * so `.Workflow` and `.workflow` register the same thing, but which FILES are
  * governed must not change because the set became registrable — widening it to
  * `X.MD` silently in a release would be an access-model change nobody asked
  * for, made in a refactor.

package/src/modules/access-model/change-gate.ts

@@ -2,7 +2,7 @@
  * The contract of the READ-BEFORE-WRITE gate: nothing is created, changed or
  * removed at a place its author cannot read. The service that answers
  * (filesystem stats, access checks) is `modules/access/change-read-gate.ts`;
- * this file carries only the types, so the workflow, kb-fs and tool modules
+ * this file carries only the types, so the version-control, kb-fs and tool modules
  * depend on the contract and never on the access module.
  *
  * Why `read`, when every write already needs `write`: on a draft branch no

package/src/modules/access-model/roles-yaml-guard.ts

@@ -24,7 +24,7 @@
 import type { FileContent } from '@mastra/core/workspace';
 import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
 import type { GroupsIndex } from './group-files.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
@@ -35,7 +35,7 @@ export const ROLES_YAML_BASENAME = 'roles.yaml';
  * the edit is refused and nothing is written. Carries the parser errors so the
  * editor / agent can show exactly what's wrong.
  */
-export class RolesYamlInvalidError extends WorkflowDomainError {
+export class RolesYamlInvalidError extends VersionControlDomainError {
   readonly errors: string[];
   constructor(errors: string[]) {
     super(
@@ -102,7 +102,7 @@ export const NEW_ROLE_GUIDANCE =
  * self-contained because a tool error reaches the agent as its message alone,
  * and the agent relays it to its user.
  */
-export class RolesYamlNewRoleError extends WorkflowDomainError {
+export class RolesYamlNewRoleError extends VersionControlDomainError {
   readonly roleNames: string[];
   constructor(roleNames: string[]) {
     const quoted = roleNames.map((n) => `'${n}'`).join(', ');
@@ -171,7 +171,7 @@ interface GroupEntry {
  * entry with only a log warning — the role silently reaches nobody — so it is
  * refused up front, naming each entry, in the same 422 shape as the others.
  */
-export class RolesYamlUnknownGroupError extends WorkflowDomainError {
+export class RolesYamlUnknownGroupError extends VersionControlDomainError {
   readonly entries: { role: string; entry: string }[];
   constructor(entries: { role: string; entry: string }[], sourceFile: string) {
     const listed = entries.map((e) => `'- ${e.entry}' under role '${e.role}'`).join(', ');

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

@@ -1,7 +1,7 @@
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { describe, expect, it } from 'vitest';
-import { mergeGroupsIntoRoles, parseRolesYaml } from '../../access-model/access-grammar.js';
-import { sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
+import { mergeGroupsIntoRoles, parseRolesYaml } from '../../access-model/index.js';
+import { sharedFileRulesSection } from '../../agent-instructions/index.js';
 import {
   CORE_SECTION_IDS,
   PLATFORM_GUIDE_SEPARATOR,
@@ -9,6 +9,7 @@ import {
   agentGuideSections,
   composeAgentGuide,
   coreAgentGuideSections,
+  guideStartText,
   isAgentGuidePath,
   isManagedGuide,
   joinGuideSections,
@@ -42,13 +43,10 @@ describe('the guide is composed from the platform\'s sections', () => {
     const sections = await coreAgentGuideSections(DEFAULT_KB_LAYOUT);
     expect(sections.map((s) => s.id)).toEqual(CORE_SECTION_IDS);
     const rules = sections.find((s) => s.id === WORKING_WITH_FILES_SECTION_ID)!;
-    expect(rules.body).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(rules.body).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
     expect(rules.literal).toBe(true);
-    // Every file section begins with its heading, so the guide reads as one document.
-    for (const s of sections) {
-      if (s.id === 'introduction') expect(s.body.startsWith('# Knowledge base')).toBe(true);
-      else expect(s.body.startsWith('## '), s.id).toBe(true);
-    }
+    // Every section begins with its heading, so the guide reads as one document.
+    for (const s of sections) expect(s.body.startsWith('## '), s.id).toBe(true);
     // The order of the composed guide is the order of the sections — pinned
     // exactly above by the id list, and by the join test below, which equates
     // the composed guide with the sections joined.
@@ -68,16 +66,17 @@ describe('the guide is composed from the platform\'s sections', () => {
     // never passed through the renderer again: a folder literally named like a
     // placeholder comes out as the folder it is.
     const odd = await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' });
-    expect(odd).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' }));
+    expect(odd).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' }, ''));
   });
 
   it('says it is served, not written, and names the one file it is read as', async () => {
-    const intro = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '# Knowledge base').replace(/\n> ?/g, ' ');
-    expect(intro).toContain('**This guide is served by the platform.**');
-    expect(intro).toContain('`get_agent_guide` returns it, whole or one section at a time');
-    expect(intro).toContain('`read_file` on `AGENTS.md` at the repository root');
-    expect(intro).toContain('`grep` searches it there too');
-    expect(intro).toContain('never write this text into it');
+    const guide0 = await composeAgentGuide(DEFAULT_KB_LAYOUT);
+    const start = section(guide0, '## Start here').replace(/\s+/g, ' ');
+    expect(start).toContain('`get_agent_guide({ body: { section: "all" } })` returns the whole guide');
+    // By id, not by heading: the section shows an AGENTS.md snippet whose own `##` heading sits in a code fence.
+    const finding = (await agentGuideSections(DEFAULT_KB_LAYOUT)).find((s) => s.id === 'how-agents-find-things')!.body.replace(/\s+/g, ' ');
+    expect(finding).toContain('`read_file` on `AGENTS.md` returns that file first, then the start of this guide');
+    expect(finding).toContain('never copy this guide into either: the platform serves it');
     // The old header, which proved a file on disk was the platform's, is gone
     // from the served text — or every read would look like a stale copy.
     expect(isManagedGuide(await composeAgentGuide(DEFAULT_KB_LAYOUT))).toBe(false);
@@ -95,7 +94,7 @@ describe('the guide is composed from the platform\'s sections', () => {
   it('serves the guide as sections with titles, the whole being the sections joined', async () => {
     const sections = await agentGuideSections(DEFAULT_KB_LAYOUT);
     expect(sections.map((s) => s.id)).toEqual(CORE_SECTION_IDS);
-    expect(sections.find((s) => s.id === 'introduction')!.title).toBe('Knowledge base');
+    expect(sections.find((s) => s.id === 'start-here')!.title).toBe('Start here');
     expect(sections.find((s) => s.id === 'where-a-new-file-goes')!.title).toBe('Where a new file goes');
     expect(sections.find((s) => s.id === 'skills')!.title).toContain('Skills (`Skills/');
     expect(joinGuideSections(sections)).toBe(await composeAgentGuide(DEFAULT_KB_LAYOUT));
@@ -120,15 +119,15 @@ describe('the guide is composed from the platform\'s sections', () => {
     const hook = (sections: readonly AgentGuideSection[]) => [
       ...sections
         .filter((s) => s.id !== 'conventions')
-        .map((s) => (s.id === 'finding-things' ? { ...s, body: '## Finding things\n\nAsk the graph.\n' } : s)),
+        .map((s) => (s.id === 'glossary' ? { ...s, body: '## Words used here\n\nAsk the graph.\n' } : s)),
       { id: 'knowledge-graph', body: '## Knowledge graph\n\nNodes live under `{{knowledgeBaseDir}}/<Ontology>/Knowledge/`.\n' },
     ];
     const guide = await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }, hook);
     expect(guide).not.toContain('## Conventions');
-    expect(section(guide, '## Finding things')).toContain('Ask the graph.');
-    expect(section(guide, '## Finding things')).not.toContain('grep');
+    expect(section(guide, '## Words used here')).toContain('Ask the graph.');
+    expect(section(guide, '## Words used here')).not.toContain('Plugin');
     expect(guide.trimEnd().endsWith('Nodes live under `Docs/<Ontology>/Knowledge/`.')).toBe(true);
-    expect(guide).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }));
+    expect(guide).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }, ''));
     // An async hook is awaited, and the layout it is handed is the resolved one.
     const seen: string[] = [];
     await composeAgentGuide({ knowledgeBaseDir: ' Docs ', skillsDir: 'Skills', pluginsDir: 'Plugins' }, async (sections, layout) => {
@@ -138,6 +137,76 @@ describe('the guide is composed from the platform\'s sections', () => {
     expect(seen).toEqual(['Docs', 'AGENTS.md']);
   });
 
+  it('routes the start section to a section a distribution adds, when that section says what it answers', async () => {
+    const hook = (sections: readonly AgentGuideSection[]) => [
+      ...sections,
+      { id: 'graph-rules', body: '## Graph rules\n\nNodes carry an id.\n', asks: 'How is a graph node written? Which | fields?' },
+      { id: 'quiet', body: '## Quiet\n\nNot routed.\n' },
+      // Already in the table: no second row.
+      { id: 'tools', body: '## Tools again\n\nA second copy.\n', asks: 'When can I use a tool?' },
+    ];
+    const start = (await agentGuideSections(DEFAULT_KB_LAYOUT, hook)).find((s) => s.id === 'start-here')!.body;
+    const rows = start.split('\n').filter((line) => line.startsWith('|'));
+    // After the table's last row, with a `|` in the question escaped.
+    expect(rows.at(-1)).toBe('| How is a graph node written? Which \\| fields? | `graph-rules` |');
+    expect(start).not.toContain('`quiet`');
+    expect(rows.filter((line) => line.endsWith('| `tools` |'))).toHaveLength(1);
+    // Core's own guide is left as it was.
+    const core = (await agentGuideSections(DEFAULT_KB_LAYOUT)).find((s) => s.id === 'start-here')!.body;
+    expect(core).not.toContain('graph-rules');
+  });
+
+  it('serves a distribution\'s own version of a core section in core\'s place, when the hook adds it under the same id', async () => {
+    const hook = (sections: readonly AgentGuideSection[]) => [
+      ...sections,
+      // The enterprise way: its own sections appended, two of them under core ids.
+      { id: 'html-views', body: '## Pages, our way\n\nOurs.\n' },
+      { id: 'start-here', body: '## Start here\n\nOurs first.\n\n| Question | Section |\n|---|---|\n| Pages? | `html-views` |\n' },
+      { id: 'graph', body: '## Graph\n\nNodes.\n', asks: 'How is the graph written?' },
+    ];
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT, hook);
+    const core = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    // One section per id, each where core's stood, the hook's text in it.
+    expect(sections.map((s) => s.id)).toEqual([...core.map((s) => s.id), 'graph']);
+    expect(sections.find((s) => s.id === 'html-views')!.body).toBe('## Pages, our way\n\nOurs.');
+    const start = sections.find((s) => s.id === 'start-here')!.body;
+    expect(start.startsWith('## Start here\n\nOurs first.')).toBe(true);
+    // The overriding start section is the one routed to: a row for the added section lands in ITS table.
+    expect(start).toContain('| How is the graph written? | `graph` |');
+    expect(start).not.toContain('`for-git-users`');
+    // The whole guide carries the override once, and never core's text under that id.
+    const guide = joinGuideSections(sections);
+    expect(guide.match(/^## Pages, our way$/gm)).toHaveLength(1);
+    expect(guide).not.toContain('## HTML views');
+  });
+
+  it('answers a read of AGENTS.md with the start section and every section by id, not the whole guide', async () => {
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT, undefined, { defaultBranch: 'main' });
+    const text = guideStartText(sections);
+    const start = sections.find((s) => s.id === 'start-here')!;
+    expect(text.startsWith(start.body)).toBe(true);
+    for (const s of sections) expect(text).toContain(`- \`${s.id}\`: ${s.title}`);
+    expect(text).not.toContain(sections.find((s) => s.id === 'access-control')!.body);
+    // A guide a distribution left without a start section is answered whole.
+    const without = sections.filter((s) => s.id !== 'start-here');
+    expect(guideStartText(without)).toBe(joinGuideSections(without));
+  });
+
+  it("refuses a hook that drops or empties the onboarding section, which the platform's onboard prompt points at", async () => {
+    await expect(
+      composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== 'onboarding')),
+    ).rejects.toThrow(/dropped the "onboarding" section, which the platform's `onboard` prompt points at/);
+    await expect(
+      composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.map((s) => (s.id === 'onboarding' ? { id: s.id, body: ' \n' } : s))),
+    ).rejects.toThrow(/emptied the "onboarding" section/);
+    // Replacing it under the same id is the hook's right: an organisation
+    // ships its own onboarding.
+    const own = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === 'onboarding' ? { id: s.id, body: '## Welcome\n\nOur own flow.' } : s)),
+    );
+    expect(own).toContain('Our own flow.');
+  });
+
   it('refuses a hook that drops or empties the shared file rules, which every file tool points at', async () => {
     await expect(
       composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== WORKING_WITH_FILES_SECTION_ID)),
@@ -157,7 +226,7 @@ describe('the guide is composed from the platform\'s sections', () => {
       { id: WORKING_WITH_FILES_SECTION_ID, body: '' },
       ...sections,
     ]);
-    expect(twice).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(twice).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
     // Replacing it under the same id is the hook's right.
     const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
       sections.map((s) => (s.id === WORKING_WITH_FILES_SECTION_ID ? { id: s.id, body: '## Working with files\n\nOurs.\n' } : s)),
@@ -250,8 +319,8 @@ describe('what the guide tells an agent', () => {
     expect(placement).toContain('Extensions/personal-<id>/');
     // A skill's own bundled files are part of the skill and stay welcome, so the
     // rule does not deter an agent from writing a COMPLETE skill.
-    expect(placement).toContain("each skill's own bundled files");
-    expect(placement).toContain("inside that skill's folder included");
+    expect(placement).toContain("each skill's own files");
+    expect(placement).toContain("in that skill's folder");
     expect(placement).toContain('never a note or any other document');
     // A private request gets a question and the restrictable folder, in the
     // deployment's own root name.
@@ -259,8 +328,8 @@ describe('what the guide tells an agent', () => {
     expect(placement).toContain('restricted so only they can read it');
     // And when the user insists, the agent declines, says why, and offers again.
     expect(placement).toContain('If they insist on the personal plugin, decline');
-    expect(placement).toContain('sits outside the knowledge graph, where it is never found as knowledge again');
-    expect(placement).toContain('offer a place under `Docs/` once more');
+    expect(placement).toContain('only they would ever find it, and never where the organisation looks for knowledge');
+    expect(placement).toContain('offer a place under `Docs/` again');
     // Nothing tells the agent to move or flag documents already filed there.
     expect(placement).not.toMatch(/\bmove (them|it|any)\b/);
   });
@@ -281,8 +350,8 @@ describe('what the guide tells an agent', () => {
       // The four places that introduce it: the `my_plugin` bullet, the sentence
       // on moving a skill, the placement rule, and the `everyone` note.
       const prose = guide.replace(/\s+/g, ' ');
-      expect(prose).toContain("`my_plugin` — your user's personal plugin, holding their own skills and tools");
-      expect(prose).toContain('A skill moves from a personal plugin into a shared plugin by moving its folder.');
+      expect(prose).toContain(`\`my_plugin\`: the user's personal plugin, \`${plugins}/personal-<id>/\`, created on first use.`);
+      expect(prose).toContain('A skill moves from a personal plugin to a shared one by moving its folder.');
       expect(prose).toContain("A person's private skill goes in their personal plugin");
       expect(prose).toContain(
         `A person's personal plugin (\`${plugins}/personal-<id>/\`) grants its owner access and denies \`everyone\` outright`,
@@ -299,8 +368,8 @@ describe('what the guide tells an agent', () => {
     expect(prose).toContain('add people to existing roles, and use a GROUP for a task- or team-scoped set of people');
   });
 
-  it('describes delete_branch where it says what an agent does with branches', async () => {
-    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### An agent proposes and syncs; a person merges');
+  it('describes delete_branch where it says what happens to a draft', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### When a draft goes away');
     const prose = text.replace(/\s+/g, ' ');
     expect(prose).toContain('`delete_branch`');
     expect(prose).toContain('Only its author');

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

@@ -2,15 +2,18 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
-import { TOOL_DESCRIPTION_CAP } from '../../tool-registry/description-length.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import type { ToolContext } from '../../tool-helpers/tool.contract.js';
-import { toolDef } from '../../tool-helpers/tool-def.js';
+import { GUIDE_FIRST_SENTENCE, TOOL_DESCRIPTION_CAP, ToolRegistry } from '../../tool-registry/index.js';
+import { createToolHandlerFactory } from '../../../__tests__/tool-wiring.js';
+import { toolDef, type ToolContext } from '../../tool-helpers/index.js';
 import { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from '../agent-guide.tools.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
-import { agentGuideSections, joinGuideSections, type RenderedGuideSection } from '../agent-guide.js';
+import {
+  START_HERE_SECTION_ID,
+  WHOLE_GUIDE_SECTION,
+  agentGuideSections,
+  joinGuideSections,
+  type RenderedGuideSection,
+} from '../agent-guide.js';
 
 let server: Server | null = null;
 
@@ -41,7 +44,7 @@ describe('get_agent_guide', () => {
         source: 'internal',
         abortSignal: new AbortController().signal,
         workspaceService: {} as never,
-        workflowService: {} as never,
+        versionControlService: {} as never,
         events: {} as never,
         getFilesystem: async () => {
           throw new Error('the guide reads no file');
@@ -84,8 +87,11 @@ describe('get_agent_guide', () => {
     for (const list of [registry.listExternal(), registry.listInternal()]) {
       const def = (await list).find((t) => t.name === GET_AGENT_GUIDE_TOOL);
       expect(def).toBeDefined();
-      expect(def!.description).toContain('ALWAYS call this first and read the guide before you do anything else');
-      expect(def!.description).toContain("`read_file` on `AGENTS.md` at the KB root");
+      expect(def!.description).toContain('ALWAYS call this first, before anything else in the platform.');
+      expect(def!.description).toContain('With no `section` it returns the start section');
+      expect(def!.description).toContain('only `"all"` returns the whole guide.');
+      // The read of the guide's name is the start too (`guideStartText`), never the whole guide.
+      expect(def!.description).toContain('`read_file` on `AGENTS.md` at the KB root answers with the same start section');
       // The sections, a distribution's own included, by id and title.
       expect(def!.description).toContain(
         'Sections: `introduction` (Knowledge base), `access-control` (Access control), `knowledge-graph` (Knowledge graph).',
@@ -176,7 +182,7 @@ describe('get_agent_guide', () => {
     const shown = (counted.match(/`[^`]+`(?=, |\.$)/g) ?? []).filter((id) => id.startsWith('`a-section-id') || id === '`introduction`' || id === '`access-control`' || id === '`knowledge-graph`');
     expect(shown.length).toBeGreaterThan(0);
     expect(shown.length).toBeLessThan(203);
-    expect(counted).toMatch(new RegExp(`and ${203 - shown.length} more, all named under \`sections\` in the whole-guide response\\.$`));
+    expect(counted).toMatch(new RegExp(`and ${203 - shown.length} more, all named under \`sections\` in the answer\\.$`));
     // No id is ever cut mid-way: every listed id is one of the guide's.
     const all = new Set([...SECTIONS, ...flood].map((s) => `\`${s.id}\``));
     for (const id of shown) expect(all.has(id), id).toBe(true);
@@ -188,6 +194,27 @@ describe('get_agent_guide', () => {
     expect(await describedAs()).toContain('`introduction` (Knowledge base)');
   });
 
+  it('answers a call without a section with the start section and every section, and `all` with the whole guide', async () => {
+    const { call, sectionsNow } = await serve();
+    const platform = await agentGuideSections(DEFAULT_KB_LAYOUT, undefined, { defaultBranch: 'production' });
+    sectionsNow([...platform]);
+    const index = platform.map((s) => ({ id: s.id, title: s.title }));
+    const start = platform.find((s) => s.id === START_HERE_SECTION_ID)!;
+    // The first call every description asks for costs the start section, not the guide.
+    expect(await call()).toEqual({
+      status: 200,
+      body: { guide: start.body, section: START_HERE_SECTION_ID, title: 'Start here', sections: index },
+    });
+    expect(start.body.replace(/\s+/g, ' ')).toContain('`production` is the default branch');
+    expect(await call({ section: WHOLE_GUIDE_SECTION })).toEqual({
+      status: 200,
+      body: { guide: joinGuideSections(platform), sections: index },
+    });
+    // A refusal says how to reach both.
+    const unknown = await call({ section: 'nope' });
+    expect(String(unknown.body.error)).toContain('Omit `section` for the start section, or pass `"all"` for the whole guide.');
+  });
+
   it('returns the platform\'s HTML views section on its own, and inside the whole guide', async () => {
     const { call, registry, sectionsNow } = await serve();
     const platform = await agentGuideSections(DEFAULT_KB_LAYOUT);
@@ -197,7 +224,7 @@ describe('get_agent_guide', () => {
       status: 200,
       body: { guide: html.body, section: 'html-views', title: 'HTML views' },
     });
-    const whole = await call();
+    const whole = await call({ section: 'all' });
     expect(whole.body.guide).toBe(joinGuideSections(platform));
     expect(String(whole.body.guide)).toContain('## HTML views');
     // The description lists it, so an agent knows it can ask for it.

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

@@ -0,0 +1,95 @@
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { toListedTool } from '@bevel-software/platform-mcp-core';
+import { describe, expect, it } from 'vitest';
+import { countTokens } from '../../../__tests__/tokens.js';
+import { hexisCatalog } from '../../../__tests__/hexis-catalog.js';
+import {
+  PREFIXED_TOOLS,
+  composeAgentInstructions,
+  platformInstructions,
+  prefixToolDescription,
+} from '../../agent-instructions/index.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/index.js';
+import { CORE_SECTION_IDS, START_HERE_SECTION_ID, agentGuideSections, joinGuideSections } from '../agent-guide.js';
+import {
+  INSTRUCTIONS_TOKEN_BUDGET,
+  SECTION_TOKEN_BUDGETS,
+  TOOL_LIST_TOKEN_BUDGET,
+  WHOLE_GUIDE_TOKEN_BUDGET,
+} from '../guide-budget.js';
+
+/**
+ * The budgets in `guide-budget.ts`, measured with a real tokenizer on the
+ * text an agent is actually handed: the sections as composed for a
+ * deployment (default layout, a default branch named `main`), the handshake's
+ * platform part, and the tool list as the hosted endpoint serves it. Each
+ * failure names what grew and by how much, so the next reader does not have
+ * to measure it by hand.
+ */
+
+const composed = () => agentGuideSections(DEFAULT_KB_LAYOUT, undefined, { defaultBranch: 'main' });
+
+describe('the guide fits its token budgets', () => {
+  it('gives every core section a budget, and no budget to a section that is gone', () => {
+    const budgeted = Object.keys(SECTION_TOKEN_BUDGETS);
+    expect(CORE_SECTION_IDS.filter((id) => !budgeted.includes(id)), 'sections without a budget').toEqual([]);
+    expect(budgeted.filter((id) => !CORE_SECTION_IDS.includes(id)), 'budgets for sections that do not exist').toEqual([]);
+  });
+
+  it('keeps each section within its budget, the start section the tightest', async () => {
+    const over = (await composed())
+      .map((s) => ({ id: s.id, tokens: countTokens(s.body), budget: SECTION_TOKEN_BUDGETS[s.id]! }))
+      .filter((s) => s.tokens > s.budget);
+    expect(over, over.map((s) => `${s.id}: ${s.tokens} tokens (budget ${s.budget})`).join('\n')).toEqual([]);
+    expect(SECTION_TOKEN_BUDGETS[START_HERE_SECTION_ID]).toBe(Math.min(...Object.values(SECTION_TOKEN_BUDGETS)));
+  });
+
+  it('keeps the whole guide within its budget', async () => {
+    const tokens = countTokens(joinGuideSections(await composed()));
+    expect(tokens, `the whole guide is ${tokens} tokens (budget ${WHOLE_GUIDE_TOKEN_BUDGET})`).toBeLessThanOrEqual(
+      WHOLE_GUIDE_TOKEN_BUDGET,
+    );
+  });
+
+  it('keeps the platform part of the handshake instructions within its budget', () => {
+    const tokens = countTokens(platformInstructions(DEFAULT_KB_LAYOUT));
+    expect(tokens, `the instructions are ${tokens} tokens (budget ${INSTRUCTIONS_TOKEN_BUDGET})`).toBeLessThanOrEqual(
+      INSTRUCTIONS_TOKEN_BUDGET,
+    );
+  });
+
+  it('keeps the tool list a client is served within its budget', async () => {
+    // As `mcp.service.ts` lists it: each tool through `toListedTool` (its
+    // `Call:` line and normalised schema), the purpose prefix on the four
+    // knowledge-base tools, and the meta-tools as built for the endpoint.
+    const { external, metaTools } = await hexisCatalog();
+    const { toolPrefix } = composeAgentInstructions(null, DEFAULT_KB_LAYOUT);
+    const listed = external.map((t) => {
+      const entry = toListedTool({
+        mcpName: t.name,
+        utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`,
+        description: t.description ?? '',
+        inputSchema: (t.inputs ?? {}) as never,
+        manualName: EXTERNAL_KB_MANUAL_NAME,
+      })!;
+      return PREFIXED_TOOLS.has(entry.name)
+        ? { ...entry, description: prefixToolDescription(toolPrefix, entry.description) }
+        : entry;
+    });
+    const served = [
+      ...metaTools.map((t) => ({ name: t.name, description: t.description ?? '', inputSchema: (t as { inputSchema?: unknown }).inputSchema })),
+      ...listed,
+    ];
+    const perTool = served.map((t) => ({
+      name: t.name,
+      tokens: countTokens(t.name) + countTokens(t.description ?? '') + countTokens(JSON.stringify(t.inputSchema ?? {})),
+    }));
+    const total = perTool.reduce((sum, t) => sum + t.tokens, 0);
+    const largest = [...perTool].sort((a, b) => b.tokens - a.tokens).slice(0, 5);
+    expect(
+      total,
+      `the tool list is ${total} tokens over ${served.length} tools (budget ${TOOL_LIST_TOKEN_BUDGET}); largest: ` +
+        largest.map((t) => `${t.name} ${t.tokens}`).join(', '),
+    ).toBeLessThanOrEqual(TOOL_LIST_TOKEN_BUDGET);
+  });
+});