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

package/src/modules/access/admin-route-helpers.ts

@@ -3,7 +3,7 @@
  * groups-admin.routes) — one error shape, one input-coercion rule, so the two
  * surfaces can't drift apart again.
  *
- * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * Error shape: a sub-500 `VersionControlDomainError` renders as its own status +
  * message + payload; everything else — a raw error OR a 500-status domain
  * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
  * AccessMutationError, message included) — is an INTERNAL error: logged
@@ -14,7 +14,7 @@
 
 import type express from 'express';
 import { logger } from '../../shared/logging.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 
 /** One error shape for every access-family route. */
@@ -22,11 +22,11 @@ export function toHttpError(
   err: unknown,
   logTag: string,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError && err.status < 500) {
+  if (err instanceof VersionControlDomainError && err.status < 500) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   logger(logTag).error('route failure:', { err });
-  const status = err instanceof WorkflowDomainError ? err.status : 500;
+  const status = err instanceof VersionControlDomainError ? err.status : 500;
   return { status, body: { error: 'Internal error.' } };
 }
 
@@ -49,7 +49,7 @@ export function requireNonEmptyString(
   opts?: { trim?: boolean },
 ): string {
   if (typeof value !== 'string' || value.trim() === '') {
-    throw new WorkflowDomainError(`${field} must be a non-empty string`, 400);
+    throw new VersionControlDomainError(`${field} must be a non-empty string`, 400);
   }
   return opts?.trim ? value.trim() : value;
 }

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

@@ -1,6 +1,6 @@
 /**
  * Read-before-write: the gate every change passes on its way to the lock
- * (`WorkflowService.acquireLock`), on every branch. Contract and rationale in
+ * (`VersionControlService.acquireLock`), on every branch. Contract and rationale in
  * `access-model/change-gate.ts`; this is the service that answers.
  *
  * The verdict is taken against the WORKING TREE, not `HEAD` as the write gate

package/src/modules/access/groups-admin.service.ts

@@ -28,9 +28,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 { 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 { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -63,7 +63,7 @@ const ROLES_YAML = 'roles.yaml';
 
 /** A group mutation that cannot proceed. `payload.kind` distinguishes the
  *  mode refusal (`'idp-mode'`) for the UI. */
-export class GroupsAdminError extends WorkflowDomainError {
+export class GroupsAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'GroupsAdminError';
@@ -118,18 +118,18 @@ export class GroupsAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
     private readonly kbDirName: string,
     /** Live-binding thunk — see RolesAdminService's identical note. */
     private readonly defaultBranchOf: () => string,
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new GroupsAdminError(message, status, payload),

package/src/modules/access/reference-scan.ts

@@ -507,7 +507,7 @@ export function readableReferences(
 const SCAN_TTL_MS = 30_000;
 
 /**
- * The slice of the workflow event bus the scanner taps for cache
+ * The slice of the version-control event bus the scanner taps for cache
  * invalidation. Structural (not the concrete class) so test doubles and the
  * services' optional bus stay compatible.
  */

package/src/modules/access/roles-admin.service.ts

@@ -36,9 +36,9 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('roles.recover');
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { 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 { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -77,7 +77,7 @@ import { AdminLockedCommits } from './admin-locked-commit.js';
 import { KbReferenceScanner, readableReferences } from './reference-scan.js';
 
 /** A mutation that cannot proceed (invariant violation, contention, not found). */
-export class RolesAdminError extends WorkflowDomainError {
+export class RolesAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'RolesAdminError';
@@ -185,7 +185,7 @@ export class RolesAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
@@ -205,7 +205,7 @@ export class RolesAdminService {
      * a roles.yaml / access.md change is an access change, and without this an
      * open tab keeps a now-stale read verdict until a manual reload.
      */
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
     /**
      * This deployment's configured admins (`ADMIN_EMAIL`) — the same list the
      * resolver treats as `deploymentOwners`, so it serves two purposes here:
@@ -218,7 +218,7 @@ export class RolesAdminService {
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new RolesAdminError(message, status, payload),
@@ -293,7 +293,7 @@ export class RolesAdminService {
    * error is status-less and would surface as 500).
    */
   private async assertRolesUnlocked(workspaceId: string, actor: AuthUser): Promise<void> {
-    const held = await this.workflowService.getLock(
+    const held = await this.versionControlService.getLock(
       workspaceId,
       this.defaultBranch,
       `${this.kbDirName}/${ROLES_YAML}`,
@@ -422,7 +422,7 @@ export class RolesAdminService {
     // the fix never reaches it). Best-effort: if origin is unreachable we fall
     // back to the local state and still attempt the local fix.
     try {
-      await this.workflowService.resetToRemote(workspaceId, this.defaultBranch);
+      await this.versionControlService.resetToRemote(workspaceId, this.defaultBranch);
       this.accessControl.invalidate(workspaceId);
     } catch (err) {
       log.warn('could not sync with origin before recovery; proceeding with local state:', { err });

package/src/modules/access/synced-groups-committer.ts

@@ -2,14 +2,14 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
 import { SYNCED_GROUPS_YAML } from '../access-model/index.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
 import { LockingFilesystem } from '../kb-fs/index.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
 
@@ -27,9 +27,9 @@ import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
  */
 export function createSyncedGroupsCommitter(deps: {
   workspaceService: WorkspaceService;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   accessControl: AccessControlService;
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   kbDirName: string;
   bot: AuthUser;
   /** Thunk — DEFAULT_BRANCH is a live binding that stays empty until setup. */
@@ -37,7 +37,7 @@ export function createSyncedGroupsCommitter(deps: {
 }): Pick<SyncedGroupsWriterDeps, 'readCurrent' | 'persist' | 'onWritten'> {
   const {
     workspaceService,
-    workflowService,
+    versionControlService,
     accessControl,
     eventBus,
     kbDirName,
@@ -77,7 +77,7 @@ export function createSyncedGroupsCommitter(deps: {
       // roles admin's atomic writes use.
       const fsys = new LockingFilesystem(
         { basePath, contained: true },
-        { workflow: workflowService, workspaceId, branch, user: bot, kbDirName },
+        { versionControl: versionControlService, workspaceId, branch, user: bot, kbDirName },
       );
       try {
         await fsys.writeFiles(
@@ -115,19 +115,19 @@ export function createSyncedGroupsCommitter(deps: {
           // an operator (or any later write on the branch) pushes it.
           let armed = false;
           try {
-            await workflowService.releaseLock(workspaceId, branch, wsRelPath, bot);
+            await versionControlService.releaseLock(workspaceId, branch, wsRelPath, bot);
             armed = true;
           } catch (armErr) {
             const lockAlreadyReleased =
-              armErr instanceof WorkflowDomainError && armErr.payload?.kind === 'lock-not-held';
+              armErr instanceof VersionControlDomainError && armErr.payload?.kind === 'lock-not-held';
             if (lockAlreadyReleased) {
               try {
-                armed = await workflowService.hasQueuedCommit(workspaceId, branch, wsRelPath);
+                armed = await versionControlService.hasQueuedCommit(workspaceId, branch, wsRelPath);
                 if (!armed) {
                   // The row may already be gone because the worker WON the
                   // race: drained it and pushed. A branch with nothing left
                   // unpushed cannot be holding our landed commit hostage.
-                  armed = !(await workflowService.hasUnpushedCommits(workspaceId));
+                  armed = !(await versionControlService.hasUnpushedCommits(workspaceId));
                 }
               } catch (queueErr) {
                 log.warn('could not verify the pending-commit queue:', { err: queueErr });

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

@@ -43,7 +43,7 @@ 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 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);
@@ -66,7 +66,7 @@ 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 () => {
@@ -127,7 +127,7 @@ describe('the guide is composed from the platform\'s sections', () => {
     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) => {
@@ -192,6 +192,21 @@ describe('the guide is composed from the platform\'s sections', () => {
     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)),
@@ -211,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)),

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

@@ -44,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');

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

@@ -7,7 +7,7 @@ import {
   HEXIS_EXTENSION_NS,
   HEXIS_TOOLS_DIR,
   PERSONAL_PLUGIN_PREFIX,
-  PIPELINES_DIR,
+  WORKFLOWS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   PLUGIN_SKILLS_DIR,
@@ -217,7 +217,7 @@ describe('the guide names the folders and files kb-layout.ts defines', () => {
 
   it('names the platform files and reserved folders by their defined names', async () => {
     const guide = (await agentGuideSections(DEFAULT_KB_LAYOUT)).map((s) => s.body).join('\n');
-    for (const name of [...FIXED_PLATFORM_FILE_NAMES, GROUPS_YAML, SYNCED_GROUPS_YAML, PREAMBLE_FILE, BUNDLE_FILE, DATA_DIR, AGENTS_DIR, PIPELINES_DIR]) {
+    for (const name of [...FIXED_PLATFORM_FILE_NAMES, GROUPS_YAML, SYNCED_GROUPS_YAML, PREAMBLE_FILE, BUNDLE_FILE, DATA_DIR, AGENTS_DIR, WORKFLOWS_DIR]) {
       expect(guide, name).toContain(name);
     }
     // A lowercase `.yaml` or `.json` file the guide names is one of the

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

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