@bevel-software/platform-core-backend 0.26.0 → 0.28.0

package/src/modules/access/access-control.interface.ts

@@ -263,6 +263,19 @@ export interface IAccessControl {
     relativePath: string,
   ): Promise<boolean>;
 
+  /**
+   * Batched `canDownload` — one config load per call, the same resolution
+   * as the single form, each path's own frontmatter `download:` rules
+   * included. A folder download judges every file it would pack through
+   * this, so a folder of a thousand files costs one model load, not a
+   * thousand.
+   */
+  canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>>;
+
   /**
    * True iff `userEmail` is an `owner` of `relativePath` per the current
    * access tree, resolved from the `owner:` lists alone (the `write` /
@@ -665,6 +678,16 @@ export interface IAccessControl {
    */
   holdsAdminRootWrite(workspaceId: string, userEmail: string): Promise<boolean>;
 
+  /**
+   * Every address the resolver treats as an Admin in the working-tree model,
+   * each once: the Admin role's members — through a group too — and the
+   * deployment owners. The same membership answer {@link holdsAdminRootWrite}
+   * gives one address at a time, enumerated. When the model cannot be loaded
+   * (a `roles.yaml` that does not parse makes nobody an Admin), the
+   * deployment owners alone.
+   */
+  adminEmails(workspaceId: string): Promise<string[]>;
+
   /**
    * Whether `userEmail` may put a misplaced platform file back at
    * `destinationRelativePath` — the ONE write that is allowed to land on a

package/src/modules/access/access-control.service.ts

@@ -1581,6 +1581,22 @@ export class AccessControlService implements IAccessControl {
     return hasPermissionResolved(model, 'download', userEmail, relativePath, own);
   }
 
+  async canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>> {
+    const model = await this.loadModel(workspaceId);
+    const repoDir = await this.repoDir(workspaceId);
+    // Parallel own-entries reads, memoized — same shape as `canWriteBatch`.
+    const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
+    const result = new Map<string, boolean>();
+    relativePaths.forEach((p, i) => {
+      result.set(p, hasPermissionResolved(model, 'download', userEmail, p, owns[i]));
+    });
+    return result;
+  }
+
   async canOwnerBatch(
     workspaceId: string,
     userEmail: string,
@@ -2148,6 +2164,25 @@ export class AccessControlService implements IAccessControl {
     return isAdminEmail(model, canonicalEmail(userEmail));
   }
 
+  async adminEmails(workspaceId: string): Promise<string[]> {
+    let model: AccessModel;
+    try {
+      model = await this.loadModel(workspaceId);
+    } catch (err) {
+      // As canRestorePlatformFile: with no model to ask, the deployment owners
+      // are the only admins left. A `roles.yaml` that does not parse is that
+      // by design; anything else (a clone being read, the disk) is said, so a
+      // list that names fewer admins than there are is diagnosable.
+      if (!(err instanceof AccessConfigError)) {
+        log.warn('the access model could not be loaded; the admins list names the deployment owners only:', { err });
+      }
+      return [...this.deploymentOwners];
+    }
+    const candidates = new Set<string>(model.deploymentOwners);
+    for (const email of model.roles.byEmail.keys()) candidates.add(email);
+    return [...candidates].filter((email) => isAdminEmail(model, email));
+  }
+
   async canRestorePlatformFile(
     workspaceId: string,
     userEmail: string,

package/src/modules/access/access.routes.ts

@@ -21,6 +21,7 @@ import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService } from '../auth/auth.service.js';
+import type { IAccountSwitchGuard } from '../auth/account-switch-guard.js';
 import type { WorkflowService } from '../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
@@ -51,6 +52,7 @@ import { RolesAdminService } from './roles-admin.service.js';
 import type { Principal } from '../access-model/access-splice.js';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import '../auth/auth.middleware.js';
 
 /** Verbs the share UI may grant. Verbs are independent — `download` is grantable on its own. */
@@ -85,6 +87,8 @@ export function createAccessRoutes(
   accessControl: IAccessControl,
   workspaceService: WorkspaceService,
   authService: AuthService,
+  /** Auth's switch-off coordination, for the invite's promotion (`ifActive`). */
+  switchGuard: IAccountSwitchGuard,
   workflowService: WorkflowService,
   eventBus: WorkflowEventBus,
   db: Database,
@@ -431,12 +435,15 @@ export function createAccessRoutes(
 
   /**
    * POST /api/workspace/:id/access/batch
-   * Body: `{ paths: string[], verb?: 'write' | 'owner' }`. Returns
+   * Body: `{ paths: string[], verb?: 'write' | 'owner' | 'read' }`. Returns
    * `{ results: { [path]: boolean } }`.
    *
    * `verb` defaults to `write`, the question every existing caller asks.
    * `owner` answers from the `owner:` lists alone — no admin rescue, and a
-   * writer is not an owner — which is what an Owner pill has to mean.
+   * writer is not an owner — which is what an Owner pill has to mean. `read`
+   * is the verdict the single lookup's `canRead` gives, for many paths at
+   * once: what New page asks on a draft branch, where a page may go wherever
+   * its author may read, of every Knowledge folder in one request.
    */
   router.post('/workspace/:id/access/batch', async (req, res) => {
     const user = await requireUser(req, res);
@@ -451,13 +458,18 @@ export function createAccessRoutes(
       res.status(400).json({ error: 'paths cannot exceed 500 entries per request' });
       return;
     }
-    if (verb !== 'write' && verb !== 'owner') {
-      res.status(400).json({ error: 'verb must be "write" or "owner"' });
+    if (verb !== 'write' && verb !== 'owner' && verb !== 'read') {
+      res.status(400).json({ error: 'verb must be "write", "owner" or "read"' });
       return;
     }
 
     try {
-      const batch = verb === 'owner' ? accessControl.canOwnerBatch : accessControl.canWriteBatch;
+      const batch =
+        verb === 'owner'
+          ? accessControl.canOwnerBatch
+          : verb === 'read'
+            ? accessControl.canReadBatch
+            : accessControl.canWriteBatch;
       const result = await batch.call(
         accessControl,
         req.params.id,
@@ -1228,6 +1240,39 @@ export function createAccessRoutes(
     }
   });
 
+  // Who the admins are, for anyone signed in: the top bar tells someone who
+  // is not an admin to ask one, and names them. Names and emails ONLY — the
+  // roster above (every role, its members, groups and references) stays
+  // admin-only. Names come from the accounts table; an admin with no account
+  // yet (a deployment admin before first sign-in, say) is named by address.
+  // A role member whose account is switched off cannot sign in to invite
+  // anyone, so is left out; a deployment admin is not (it signs in with the
+  // environment's password regardless).
+  router.get('/access/admins', async (req, res) => {
+    const user = await requireUser(req, res);
+    if (!user) return;
+    try {
+      const emails = await rolesAdmin.getAdminEmails();
+      const rows =
+        emails.length === 0
+          ? []
+          : await db
+              .select({ email: users.email, name: users.name, deactivatedAt: users.deactivatedAt })
+              .from(users)
+              .where(inArray(users.emailBidx, emails));
+      const names = new Map(rows.map((r) => [canonicalEmail(r.email), r.name?.trim() ?? '']));
+      const off = new Set(rows.filter((r) => r.deactivatedAt).map((r) => canonicalEmail(r.email)));
+      const admins = emails
+        .filter((email) => !off.has(email) || rolesAdmin.isFixedAdmin(email))
+        .map((email) => ({ name: names.get(email) || email, email }))
+        .sort((a, b) => a.name.localeCompare(b.name) || a.email.localeCompare(b.email));
+      res.json({ admins });
+    } catch (err) {
+      const { status, body } = toHttpError(err);
+      res.status(status).json(body);
+    }
+  });
+
   // NOTE: POST /access/roles (create), PATCH /access/roles/:canonical
   // (rename), and DELETE /access/roles/:canonical are GONE — roles are
   // app-defined capabilities, not user-editable objects.
@@ -1239,7 +1284,23 @@ export function createAccessRoutes(
       await assertRolesAdmin(user.email);
       const canonical = canonicalRoleName(req.params.canonical);
       const email = requireNonEmptyString((req.body ?? {}).email, 'email');
-      res.json({ roles: await rolesAdmin.addMember(user, canonical, email) });
+      // `ifActive`: the invite's promotion, which leaves a switched-off
+      // account unchanged. Inside the roles file's lock, auth reads the
+      // account under the address's switch lock and keeps that transaction
+      // open until roles.yaml is written and committed
+      // (`IAccountSwitchGuard.whileSwitchedOn`). So a switch-off either committed
+      // before the read (the promotion is refused) or waits until the
+      // promotion is written (it lands after, as for any Admin switched off
+      // later: the place in roles stays, the credentials stop being honoured).
+      const ifActive = (req.body ?? {}).ifActive;
+      if (ifActive !== undefined && typeof ifActive !== 'boolean') {
+        res.status(400).json({ error: 'ifActive must be a boolean' });
+        return;
+      }
+      const whileSwitchedOn = (write: () => Promise<void>): Promise<void> => switchGuard.whileSwitchedOn(email, write);
+      res.json({
+        roles: await rolesAdmin.addMember(user, canonical, email, ifActive ? { aroundWrite: whileSwitchedOn } : undefined),
+      });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

package/src/modules/access/directory-sync-bot.ts

@@ -35,7 +35,7 @@ export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
     .returning();
   if (inserted.length > 0) {
     const row = inserted[0];
-    log.info(`created sync-bot user id=${row.id} email=${row.email}`);
+    log.info(`created sync-bot user id=${row.id}`);
     return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
   }
   const [row] = await db

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

@@ -103,6 +103,13 @@ export interface RoleRosterEntry {
    * email once, as fixed.
    */
   fixedMembers: string[];
+  /**
+   * The note the page prints beside {@link fixedMembers}, and the sentence
+   * both Admin-membership refusals lead with. Sent with the roster so the
+   * page keeps no copy of the wording. Null when the role has no fixed
+   * members.
+   */
+  fixedMembersNote: string | null;
   /** Canonical names of groups this role is assigned to (`group:` members). */
   groups: string[];
   isAdmin: boolean;
@@ -165,11 +172,12 @@ export class RolesAdminService {
   private readonly fixedAdminEmails: readonly string[];
   /**
    * The one explanation both Admin-role refusals carry, verbatim: the note the
-   * page prints beside a fixed member. Kept as a named constant so the refusal
-   * an API caller reads and the note a UI reader sees cannot drift apart.
+   * page prints beside a fixed member, which it reads from the roster's
+   * `fixedMembersNote`. One constant, so the refusal an API caller reads and
+   * the note a UI reader sees cannot drift apart.
    */
   private static readonly FIXED_ADMIN_NOTE =
-    'Deployment admin, set in the server configuration; cannot be removed here';
+    'Owner; cannot be removed here';
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
@@ -227,9 +235,10 @@ export class RolesAdminService {
   /**
    * Is `email` a deployment admin — an address the server configuration makes
    * an Admin, ahead of `roles.yaml`? Drives both the fixed member rows and
-   * the add/remove refusals on the Admin role.
+   * the add/remove refusals on the Admin role, and keeps a switched-off
+   * deployment admin among the admins people are told to ask.
    */
-  private isFixedAdmin(email: string): boolean {
+  isFixedAdmin(email: string): boolean {
     return this.fixedAdminEmails.includes(canonicalEmail(email));
   }
 
@@ -326,6 +335,8 @@ export class RolesAdminService {
         // Only Admin has fixed members: `deploymentOwners` is an Admin rescue
         // in the resolver, never a general grant, so no other role gains one.
         fixedMembers: isAdmin ? [...this.fixedAdminEmails] : [],
+        fixedMembersNote:
+          isAdmin && this.fixedAdminEmails.length > 0 ? RolesAdminService.FIXED_ADMIN_NOTE : null,
         groups: role.members
           .filter(isGroupRefMember)
           .map((m) => canonicalRoleName(m.slice(GROUP_REF_PREFIX.length))),
@@ -342,6 +353,18 @@ export class RolesAdminService {
     return out;
   }
 
+  /**
+   * The addresses the app treats as an Admin, each once — the resolver's own
+   * membership answer ({@link IAccessControl.adminEmails}), so who this names
+   * and who the admin gates admit cannot drift apart. Nothing else about
+   * roles: this backs a read any signed-in person may make (who to ask for an
+   * invite), unlike the roster.
+   */
+  async getAdminEmails(): Promise<string[]> {
+    const workspaceId = await this.ensureWorkspace();
+    return this.accessControl.adminEmails(workspaceId);
+  }
+
   /**
    * Whether the default-branch roles.yaml parses. Drives the "roles file
    * corrupted" banner. Auth-only (never admin-gated): a corrupted file resolves
@@ -446,10 +469,24 @@ export class RolesAdminService {
    * admits it ahead of `roles.yaml` — so the write would add a row that means
    * nothing, next to the fixed row the page already shows. Other roles are
    * unaffected: a deployment admin is an ordinary member of "Sales".
+   *
+   * `aroundWrite`, when given, runs once the roles file's lock is held and
+   * is handed the edit itself (read, check, write, commit) to run. What it
+   * does around that call brackets the whole write: the invite holds the
+   * address's account-switch lock (a transaction-scoped advisory lock keyed
+   * on the canonical email, see `AuthService.whileSwitchedOn`) across it, so
+   * a switch-off cannot commit in between, whether or not the account exists
+   * yet (see the members route). It may throw instead of calling `write`;
+   * nothing is written then.
    */
-  async addMember(actor: AuthUser, canonical: string, email: string): Promise<RoleRosterEntry[]> {
+  async addMember(
+    actor: AuthUser,
+    canonical: string,
+    email: string,
+    opts?: { aroundWrite?: (write: () => Promise<void>) => Promise<void> },
+  ): Promise<RoleRosterEntry[]> {
     this.assertNotFixedAdmin(canonical, email);
-    await this.runEdit(actor, (text) => editAddMember(text, canonical, email));
+    await this.runEdit(actor, (text) => editAddMember(text, canonical, email), opts?.aroundWrite);
     return this.getRoster();
   }
 
@@ -682,17 +719,20 @@ export class RolesAdminService {
    * `pre` produces the candidate (and may throw RolesAdminError for invariant
    * violations before any write). Skips on a no-op. Every candidate passes
    * the resolver's own parser (assertLoadable) plus the pre-disk validator
-   * before a byte lands.
+   * before a byte lands. `aroundWrite` wraps the locked edit (see
+   * {@link addMember}).
    */
   private async runEdit(
     actor: AuthUser,
     pre: (currentText: string) => EditResult,
+    aroundWrite?: (write: () => Promise<void>) => Promise<void>,
   ): Promise<void> {
     const workspaceId = await this.ensureWorkspace();
     await this.assertRolesUnlocked(workspaceId, actor);
-    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () =>
-      this.runEditLocked(workspaceId, actor, pre),
-    );
+    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () => {
+      const write = () => this.runEditLocked(workspaceId, actor, pre);
+      return aroundWrite ? aroundWrite(write) : write();
+    });
   }
 
   private async runEditLocked(

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

@@ -492,7 +492,7 @@ export class UserAccessRemovalService {
   /** Why `email` may not be removed from access files, or null when it may. */
   private blockedReason(rolesText: string | undefined, email: string): string | null {
     if (this.deploymentOwners.some((o) => canonicalEmail(o) === email)) {
-      return 'This is the deployment owner (ADMIN_EMAIL); their access cannot be removed here.';
+      return 'The owner stays in roles and access rules.';
     }
     const admin = rolesText
       ? (() => {

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

@@ -299,6 +299,18 @@ 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');
+    const prose = text.replace(/\s+/g, ' ');
+    expect(prose).toContain('`delete_branch`');
+    expect(prose).toContain('Only its author');
+    expect(prose).toContain('`dryRun: true`');
+    expect(prose).toContain('`discardUnmerged: true`');
+    expect(prose).toContain('that proposes nothing is closed by the delete');
+    expect(prose).toContain('its author can withdraw it, or an Admin can decline it, in the app');
+    expect(prose).toContain('`lastCommit`');
+  });
+
   it('documents giving a role to a group, with an example that parses as a valid roles.yaml', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### Giving a role to a group');
     const prose = text.replace(/\s+/g, ' ');
@@ -326,3 +338,49 @@ describe('what the guide tells an agent', () => {
     expect(parsed.index.byEmail.get('pat@example.com')?.has('role/admin')).toBe(false);
   });
 });
+
+/**
+ * The HTML views section: what an agent writing a live page is told about the
+ * frame. Its link rules are pinned against the renderer by core-frontend's
+ * `htmlViewsGuide.test.ts`, which reads the same file; what is pinned here is
+ * that it is served like every other section and that a distribution may
+ * reshape it.
+ */
+describe('the HTML views section', () => {
+  it('is served on its own, inside the whole guide, titled "HTML views"', async () => {
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    const html = sections.find((s) => s.id === 'html-views')!;
+    expect(html.title).toBe('HTML views');
+    expect(html.body).not.toContain('{{');
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(html.body);
+    // After the tool manuals, before the conventions.
+    const ids = sections.map((s) => s.id);
+    expect(ids.indexOf('html-views')).toBe(ids.indexOf('tool-manuals') + 1);
+  });
+
+  it('describes the frame, the two members core puts on window.bevel, and a fragment that scrolls the page', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    expect(text).toContain('**No network.**');
+    expect(text).toContain('**Inline scripts and styles only.**');
+    expect(text).toContain('**Scripts run as ES modules**');
+    expect(text).toContain('**No browser storage.**');
+    expect(text).toContain('**No host navigation.**');
+    expect(text).toContain('`window.bevel.openNode(href)`');
+    expect(text).toContain('`window.bevel.navigate(href)`');
+    expect(text).toContain('A distribution may add data members of its own to `window.bevel`');
+    expect(text).toContain('**A bare fragment scrolls the page.**');
+    // Rendered for the deployment's layout like every other section.
+    const docs = section(await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }), '## HTML views');
+    expect(docs).toContain('/workspace/main/Docs/Alice.md');
+  });
+
+  it('lets a distribution replace the section or drop it', async () => {
+    const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === 'html-views' ? { id: s.id, body: '## HTML views\n\nOurs, graph-aware.\n' } : s)),
+    );
+    expect(section(replaced, '## HTML views').trim()).toBe('Ours, graph-aware.');
+    const dropped = await agentGuideSections(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== 'html-views'));
+    expect(dropped.map((s) => s.id)).not.toContain('html-views');
+    expect(joinGuideSections(dropped)).not.toContain('## HTML views');
+  });
+});

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

@@ -9,7 +9,8 @@ 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 { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from '../agent-guide.tools.js';
-import type { RenderedGuideSection } from '../agent-guide.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { agentGuideSections, joinGuideSections, type RenderedGuideSection } from '../agent-guide.js';
 
 let server: Server | null = null;
 
@@ -186,4 +187,21 @@ describe('get_agent_guide', () => {
     sectionsNow(SECTIONS);
     expect(await describedAs()).toContain('`introduction` (Knowledge base)');
   });
+
+  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);
+    sectionsNow([...platform]);
+    const html = platform.find((s) => s.id === 'html-views')!;
+    expect(await call({ section: 'html-views' })).toEqual({
+      status: 200,
+      body: { guide: html.body, section: 'html-views', title: 'HTML views' },
+    });
+    const whole = await call();
+    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.
+    const def = (await registry.listExternal()).find((t) => t.name === GET_AGENT_GUIDE_TOOL)!;
+    expect(def.description).toContain('`html-views`');
+  });
 });

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

@@ -79,6 +79,13 @@ export type AgentGuideReader = () => Promise<string>;
 /** The computed section: the rules every file tool shares. */
 export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
 
+/**
+ * What to do on a knowledge base nobody has written in yet: the section the
+ * `firstRun` note `start_session` answers with points at (see
+ * workspace/first-run.ts, which names it by this constant).
+ */
+export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
+
 /**
  * Core's sections, in reading order. Every id but the shared-rules one names
  * a file in the package's `agent-guide/` folder.
@@ -91,8 +98,10 @@ export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
   'access-control',
   'skills',
   'tool-manuals',
+  'html-views',
   'conventions',
   'finding-things',
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
 ]);
 
 /**

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

@@ -1,6 +1,7 @@
 export {
   AGENT_GUIDE_FILE,
   CORE_SECTION_IDS,
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
   PLATFORM_GUIDE_SEPARATOR,
   WORKING_WITH_FILES_SECTION_ID,
   agentGuideSections,

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

@@ -114,6 +114,20 @@ describe('the shared file rules are one text, in two places', () => {
 
 });
 
+describe('the delete rule for platform files', () => {
+  const managedItems = (): string => sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'managed-items')!.body;
+
+  it('says a nested access.md is deleted by whoever may write it, and the root\'s platform files by nobody', async () => {
+    const body = managedItems();
+    expect(body).toContain('delete_file deletes a nested `access.md` for whoever may write it');
+    expect(body).toContain("its folder then follows its parent's rules");
+    expect(body).toContain("the repository root's `access.md` and `roles.yaml` are deleted by nobody");
+    // The sentence the refusal actually carries, as the tools and the app say it.
+    expect(body).toContain("\"<name> is the repository's own file and cannot be deleted.\"");
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(body);
+  });
+});
+
 describe('the handshake text stays inside the length it pins', () => {
   it('holds the shared section under its own cap', () => {
     const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);

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

@@ -30,6 +30,7 @@ import {
   stripHtmlComments,
   type KbLayout,
 } from '@bevel-software/platform-shared';
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
 import { sharedFileRulesSection } from './shared-file-rules.js';
 
 export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
@@ -48,7 +49,13 @@ export const PLATFORM_HEADER =
   'Before answering a question about the organisation, its people, customers, products, processes, projects or internal terms, ' +
   'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
   'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
-  'Skills are available as prompts and through `list_skills` and `get_skill`.';
+  'Skills are available as prompts and through `list_skills` and `get_skill`. ' +
+  // There is no one calling shape to state: the knowledge-base tools take
+  // their arguments under `body`, a tool that calls another service takes them
+  // flat, and an agent told one rule for all of them sends a GET with a body.
+  // The per-tool `Call:` line is generated from each tool's own input schema,
+  // so pointing at it is both shorter and always right.
+  'Tools do not share one calling shape: call each tool exactly as the `Call:` line at the top of its description shows.';
 
 /**
  * The fixed first line of the tool prefix. It always leads, so an admin's
@@ -167,9 +174,17 @@ export function composeAgentInstructions(
  * A tool description with the prefix ahead of it: the prefix, a blank line,
  * then the original. Purpose line first, because claude.ai cuts descriptions
  * near 500 characters.
+ *
+ * Except for the `Call:` line, which stays the very first line whatever else
+ * is prepended: it is how an agent learns the shape this tool's arguments take,
+ * and a description that opens with the purpose prefix instead would bury the
+ * one line the refusal for a wrong call points back to.
  */
 export function prefixToolDescription(toolPrefix: string, description: string | undefined): string {
-  return description ? `${toolPrefix}\n\n${description}` : toolPrefix;
+  if (!description) return toolPrefix;
+  const { call, rest } = splitCallLine(description);
+  if (call === null) return `${toolPrefix}\n\n${description}`;
+  return rest === '' ? `${call}\n\n${toolPrefix}` : `${call}\n\n${toolPrefix}\n\n${rest}`;
 }
 
 /** An ATX heading line: `#` to `######`, then a space or the end. */

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

@@ -145,15 +145,15 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       // that take content as a JSON string names the route in one sentence of
       // its own; WHY a file should go that way, and how, is here.
       id: 'upload-route',
-      heading: 'Large, escape-heavy and binary content goes by upload',
+      heading: 'Large, escape-heavy and binary content: upload in, download out',
       body:
-        'write_file, write_files and edit_file take content as a JSON string you have to type out in full, so a long ' +
-        'file is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and ' +
-        'an image, a PDF or a zip cannot be sent at all. For any of those: call `request_file_upload`, POST the file — ' +
-        'or one zip holding many files — to the address it answers with any HTTP client ' +
-        '(`curl -X POST --data-binary @<file> "<uploadUrl>?filename=<name>"`), then `apply_file_upload` to land it on ' +
-        'a branch in one commit. The bytes never pass through the conversation, so nothing is cut or mangled on the ' +
-        'way. A person can also use Upload in the app.',
+        'write_file, write_files and edit_file take content as a JSON string you type out in full, so a long file ' +
+        'is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and an ' +
+        'image, a PDF or a zip cannot be sent at all. For those, call `request_file_upload`, POST the file (or one ' +
+        'zip of many) with any HTTP client (`curl -X POST --data-binary @<file> ' +
+        '"<uploadUrl>?filename=<name>"`), then `apply_file_upload` lands it in one commit. To take copies OUT, ' +
+        '`request_file_download` answers a one-time link per file and a zip per folder (`curl -o <name> ' +
+        '"<downloadUrl>"`). Either way no bytes pass through the conversation.',
     },
     {
       id: 'dry-run-confirm',
@@ -163,22 +163,22 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
         'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
         'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
-        'dry-run, check the impact, then confirm. delete_file takes neither: it removes the one file you named, so ' +
-        'check it first with file_stat (`deletable`) if you are unsure.',
+        'dry-run, check the impact, then confirm. delete_file takes neither: check it first with file_stat ' +
+        '(`deletable`) if you are unsure. delete_branch has its own `dryRun`.',
     },
     {
       id: 'managed-items',
       heading: 'What these tools never move or delete',
       body:
-        `A platform file (${platformFileList(layout)}) is refused with ` +
-        '"<name> is a platform file and stays in its folder." — a folder that moves ' +
-        'takes its own platform files along, still in their folder, and a folder that is deleted takes them with it in ' +
-        'the same one change, so its files are never left ungoverned part-way. A platform folder (the repository root ' +
-        `or a reserved root folder such as \`${layout.knowledgeBaseDir}/\`) and git metadata are refused, and so is creating a ` +
-        'platform file or folder at a destination (renaming a note to `access.md` is refused). A path that is, or goes ' +
-        'through, a symbolic link is refused: links are never followed or removed. On a protected branch you must be ' +
-        'able to write everything the call touches — for a folder, every file under it, at its old and its new path. ' +
-        'file_stat reports `managed`, `movable` and `deletable` so you can tell before the call.',
+        `A platform file (${platformFileList(layout)}) is never moved: "<name> is a platform file and stays in its folder." ` +
+        'A folder moved or deleted takes its own along, in one change. delete_file deletes a nested `access.md` for ' +
+        "whoever may write it (its folder then follows its parent's rules) and refuses `.bevelignore`; the repository " +
+        "root's `access.md` and `roles.yaml` are deleted by nobody: \"<name> is the repository's own file and cannot be " +
+        'deleted." A platform folder (the root, or a reserved one like ' +
+        `\`${layout.knowledgeBaseDir}/\`), git metadata, and making a platform file or folder at a destination are ` +
+        'refused; so is a path that is or crosses a symlink: links are never followed or removed. On a protected ' +
+        'branch you must be able to write all a call touches — for a folder, every file under it, at its old and new ' +
+        'path. file_stat reports `managed`, `movable` and `deletable` up front.',
     },
     {
       id: 'refused-for-permissions',