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

package/dist/shared/hidden-tools.js

@@ -0,0 +1,13 @@
+/**
+ * A connected tool Hexis keeps off every agent surface because its input
+ * schema is not valid JSON Schema as its server sent it — and the read port
+ * the surfaces that SHOW that to the server's owner use.
+ *
+ * Here rather than in either module because two of them meet over it: the MCP
+ * proxy finds these when a server's tools are loaded (`modules/mcp`), and the
+ * tool catalog reports them to the people who manage the server
+ * (`modules/tool-manuals`, on the tool page and in `list_tool_setup`). Neither
+ * has any business importing the other.
+ */
+export {};
+//# sourceMappingURL=hidden-tools.js.map

package/dist/shared/hidden-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-tools.js","sourceRoot":"","sources":["../../src/shared/hidden-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/kb-template/.bevelignore

@@ -11,13 +11,8 @@
 # Repo hygiene files that clutter the tree without being node content.
 .gitignore
 .gitattributes
-# The platform's agent guide.
-{{agentsFile}}
 # The deployment preamble is edited from External agent access, not as a KB page.
 /mcp-description.md
-# The pre-rename name. Listed so a knowledge base carrying both files hides
-# both — top-up adds AGENTS.md but never deletes the CLAUDE.md beside it.
-CLAUDE.md
 
 # Empty-folder placeholders used only for committing empty dirs.
 **/.gitkeep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,6 +23,7 @@
     "src",
     "migrations",
     "kb-template",
+    "agent-guide",
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
@@ -52,8 +53,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.25.2",
-    "@bevel-software/platform-shared": "0.25.2"
+    "@bevel-software/platform-mcp-core": "0.26.0",
+    "@bevel-software/platform-shared": "0.26.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/kb-layout-config.test.ts

@@ -5,15 +5,12 @@ import {
   KNOWLEDGE_BASE_DIR,
   PLUGINS_DIR,
   SKILLS_DIR,
-  agentsFilePointerSentence,
   configureKbLayout,
   currentKbLayout,
   isPlatformFile,
-  mentionsAgentsFile,
   platformFileNames,
   pluginOfPath,
   renderKbLayoutPlaceholders,
-  retargetAgentsFilePointer,
   reservedRootDirNames,
   validateAgentsFileName,
   validateKbLayout,
@@ -193,106 +190,19 @@ describe('KB layout — the agent guide\'s file name', () => {
     expect(renderKbLayoutPlaceholders('see {{agentsFile}}', DEFAULT_KB_LAYOUT)).toBe('see AGENTS.md');
   });
 
-  test('the platform-file gate follows the name: ours is managed, theirs is content', () => {
-    expect(platformFileNames(DEFAULT_KB_LAYOUT)).toEqual([
-      'access.md',
-      'roles.yaml',
-      '.bevelignore',
-      'AGENTS.md',
-    ]);
-    expect(platformFile('AGENTS.md')).toBe(true);
-
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
-    // The guide the platform writes is immovable and undeletable…
-    expect(platformFile('HEXIS.md')).toBe(true);
-    // …and the customer's own AGENTS.md is a page like any other.
+  test('the guide is no platform file under any name: a root AGENTS.md is the organisation\'s own page', () => {
+    // The platform's guide is served from code and never written to the
+    // repository, so nothing under its name is the platform's to protect.
+    expect(platformFileNames(DEFAULT_KB_LAYOUT)).toEqual(['access.md', 'roles.yaml', '.bevelignore']);
     expect(platformFile('AGENTS.md')).toBe(false);
-    // Still root-only, as `roles.yaml` is: a nested copy is content.
-    expect(platformFile('KnowledgeBase/HEXIS.md')).toBe(false);
-  });
+    expect(platformFile('roles.yaml')).toBe(true);
 
-  test('the pointer sentence is one sentence, naming the guide twice, from one place', () => {
-    expect(agentsFilePointerSentence('HEXIS.md')).toBe(
-      'Read [HEXIS.md](./HEXIS.md) before working in this knowledge base — ' +
-        "it is the platform's guide to its layout, files and rules.",
-    );
+    // A name a deployment saved for the written guide is a read alias now,
+    // not a file, and makes no platform file either.
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(agentsFilePointerSentence(currentKbLayout().agentsFile)).toContain('HEXIS.md');
-  });
-
-  /**
-   * A guide name is a FILE NAME: spaces, brackets, parentheses, `#` and `%`
-   * all pass `validateFilename`, and every one of them means something in an
-   * inline link. The label must not end early and the destination must still
-   * point at the file.
-   */
-  test('the pointer sentence links correctly for a name full of markdown punctuation', () => {
-    const name = 'Our [Agent] Guide (v2).md';
-    expect(validateGuideName(name)).toBeNull();
-    const sentence = agentsFilePointerSentence(name);
-    // The label cannot end early: the brackets in it are escaped…
-    expect(sentence).toContain('[Our \\[Agent\\] Guide (v2).md]');
-    // …and the destination is percent-encoded, parentheses included — a bare
-    // `)` would close the link half way through the name.
-    expect(sentence).toContain('(./Our%20%5BAgent%5D%20Guide%20%28v2%29.md)');
-    // The ordinary name reads as it always has — no escapes, nothing encoded.
-    expect(agentsFilePointerSentence('AGENTS.md')).toContain('[AGENTS.md](./AGENTS.md)');
-  });
-
-  test('the pointer sentence encodes a name that would otherwise open a URL fragment', () => {
-    // `#` is legal in a filename and opens a fragment in a URL: `./#2 Guide.md`
-    // links to the customer's OWN file with a fragment, not to the guide.
-    expect(validateGuideName('#2 Guide.md')).toBeNull();
-    expect(agentsFilePointerSentence('#2 Guide.md')).toContain('(./%232%20Guide.md)');
-    // `%` is legal too, and an unencoded one is a malformed escape.
-    expect(agentsFilePointerSentence('100%.md')).toContain('(./100%25.md)');
-  });
-
-  /**
-   * The startup step asks this before appending, and it has to recognise the
-   * sentence the LAST boot wrote — whose spelling of the name is escaped in
-   * the label and encoded in the destination. Asking for the raw name alone
-   * would append a second copy on every boot after the first.
-   */
-  test('a file already carrying the pointer sentence counts as mentioning the guide', () => {
-    for (const name of ['AGENTS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md', '100%.md']) {
-      const appended = `# Acme\n\n${agentsFilePointerSentence(name)}\n`;
-      expect(mentionsAgentsFile(appended, name), name).toBe(true);
-    }
-    // A file that says nothing about the guide still reads as silent…
-    expect(mentionsAgentsFile('# Acme\n\nWrite tickets in the present tense.\n', 'HEXIS.md')).toBe(false);
-    // …and the customer's own plain mention counts, in their own words.
-    expect(mentionsAgentsFile('See HEXIS.md for the platform.', 'HEXIS.md')).toBe(true);
-  });
-
-  /**
-   * A second rename. The sentence written for the previous guide points at a
-   * file that is no longer there, and the new name appears nowhere in the
-   * text — so it has to be recognised by its SHAPE and aimed again.
-   */
-  test('a pointer sentence the platform wrote is retargeted, whatever guide it named', () => {
-    for (const before of ['HEXIS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md']) {
-      const text = `# Acme\n\n${agentsFilePointerSentence(before)}\n`;
-      expect(retargetAgentsFilePointer(text, 'GUIDE.md'), before).toBe(
-        `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`,
-      );
-    }
-    // Already aimed right: ours, and unchanged — which is not the same answer
-    // as "none of ours here", and the caller tells them apart.
-    const current = `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`;
-    expect(retargetAgentsFilePointer(current, 'GUIDE.md')).toBe(current);
+    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore']);
+    expect(platformFile('HEXIS.md')).toBe(false);
+    expect(platformFile('AGENTS.md')).toBe(false);
   });
 
-  test('leaves a file holding nothing of the platform\'s alone', () => {
-    // Null, not the text: there is nothing of ours to aim, so the caller goes
-    // on to ask whether the customer mentioned the guide themselves.
-    expect(retargetAgentsFilePointer('# Acme\n\nWrite tickets in the present tense.\n', 'GUIDE.md')).toBeNull();
-    // Their own link to their own file is not our sentence.
-    expect(retargetAgentsFilePointer('Read [notes](./notes.md) before working here.', 'GUIDE.md')).toBeNull();
-    // Our opening words, their sentence.
-    expect(
-      retargetAgentsFilePointer('Read [HEXIS.md](./HEXIS.md) when you have a moment.', 'GUIDE.md'),
-    ).toBeNull();
-  });
 });

package/src/__tests__/packaged-assets-ship.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir } from '../assets.js';
+
+/**
+ * Every asset folder this package reads at run time has to reach the places
+ * the package is shipped from: the npm tarball (`files` in package.json) and
+ * the Docker image (the runtime stage of the repository's Dockerfile, which
+ * copies each folder by name).
+ *
+ * The second list is the one nothing else checks. `agent-guide/` was added to
+ * `assets.ts` and to `files`, but not to the Dockerfile, and no test or CI job
+ * builds the image: the folder was simply absent from every image built from
+ * dev. It is read while the tool list is composed, so the first request for
+ * any tool on the deployment failed, and every agent surface with it
+ * (2026-10-06). A folder named here and missing from either list fails this
+ * test instead.
+ */
+const packageRoot = fileURLToPath(new URL('../..', import.meta.url));
+const repoRoot = path.resolve(packageRoot, '..', '..');
+
+/** The folders assets.ts locates, as names under the package root. */
+const ASSET_DIRS = [coreMigrationsDir(), defaultKbTemplateDir(), agentGuideDir()].map((dir) =>
+  path.basename(dir),
+);
+
+describe('the asset folders this package reads at run time', () => {
+  it('are the three assets.ts names', () => {
+    expect(ASSET_DIRS.sort()).toEqual(['agent-guide', 'kb-template', 'migrations']);
+  });
+
+  it('exist in the source tree', () => {
+    for (const dir of ASSET_DIRS) {
+      expect(fs.statSync(path.join(packageRoot, dir)).isDirectory(), dir).toBe(true);
+    }
+  });
+
+  it('are in the npm tarball', () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as { files: string[] };
+    for (const dir of ASSET_DIRS) {
+      expect(pkg.files, `${dir} missing from package.json "files"`).toContain(dir);
+    }
+  });
+
+  it('are copied into the Docker image by the runtime stage', () => {
+    const dockerfile = fs.readFileSync(path.join(repoRoot, 'Dockerfile'), 'utf8');
+    for (const dir of ASSET_DIRS) {
+      const line = `COPY --from=builder /app/packages/core-backend/${dir} packages/core-backend/${dir}`;
+      expect(dockerfile, `Dockerfile does not copy ${dir} into the image`).toContain(line);
+    }
+  });
+});

package/src/assets.ts

@@ -23,3 +23,13 @@ export function coreMigrationsDir(): string {
 export function defaultKbTemplateDir(): string {
   return path.join(packageRoot(), 'kb-template');
 }
+
+/**
+ * The sections of the platform's agent guide, one markdown file each — the
+ * text `get_agent_guide` and a `read_file` of the guide's name serve, composed
+ * by `modules/agent-guide`. Beside `kb-template/` rather than under `src/`,
+ * so a build and the published source find it at the same place.
+ */
+export function agentGuideDir(): string {
+  return path.join(packageRoot(), 'agent-guide');
+}

package/src/core/core-ports.ts

@@ -9,6 +9,7 @@ import type { IErasureParticipant } from '../modules/auth/account-erasure.servic
 import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
+import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
 
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
@@ -100,6 +101,16 @@ export interface CorePorts {
    * contract each step signs up to). Core default: `[]`.
    */
   kbStartupSteps?: readonly OnServerStart[];
+  /**
+   * THIS distribution's say over the agent guide — the text `get_agent_guide`
+   * and a `read_file` of the guide's name serve. Called with core's sections
+   * and the layout in effect on every composition; returns the sections the
+   * guide is made of, so a distribution appends its own, replaces one of
+   * core's by id, or drops one, and every change core makes to the rest still
+   * reaches it. Core default: core's sections as they are. See
+   * `modules/agent-guide`.
+   */
+  agentGuide?: AgentGuideHook;
   /**
    * Mirror this composition's branch model and knowledge-base layout onto the
    * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,

package/src/core/create-core-server.ts

@@ -26,7 +26,9 @@ import {
   registerToolManualsTools,
 } from '../modules/tool-manuals/index.js';
 import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
+import { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
+import { registerAgentGuideTool } from '../modules/agent-guide/index.js';
 import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
 import {
   registerSkillsTools,
@@ -456,7 +458,13 @@ export async function createCoreServer(
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore);
+  // The five read tools over change requests. Separate from the workflow tools
+  // because they are the only ones that gate their whole payload on the
+  // caller's read access, so they take the access service and nothing else.
+  registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide);
+  // The guide on its own, beside the file tools that serve it by name.
+  registerAgentGuideTool(core.toolRegistry, toolsRouter, ta, th, core.agentGuideSections);
   // The agent upload route, on the same router as the tool endpoints so it
   // mounts ahead of the JWT `/api` mounts below — but WITHOUT `toolAuth`: its
   // whole credential is the single-use token in its path, which is the point
@@ -467,13 +475,16 @@ export async function createCoreServer(
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
-  registerPluginsTools(core.toolRegistry);
+  registerPluginsTools(core.toolRegistry, core.kb);
   registerToolManualsTools(core.toolRegistry, toolsRouter, ta, th, core.toolManualService, {
     accessControl: core.accessControl,
     // The vault satisfies the module's local VariableStatusPort — `list_tool_setup`
     // reports configuration booleans only; secret values never ride through tools.
     variableStatus: core.secretsVaultService,
     kb: core.kb,
+    // What the proxy's schema check found when each server's tools were last
+    // loaded — reported to a caller who may write the tool, nobody else.
+    hiddenTools: core.mcpService.hiddenTools,
   });
   // Overlay tool registrations (defs + module-hosted endpoints).
   ext.tools?.({

package/src/core/create-core-services.ts

@@ -138,6 +138,12 @@ import { unmeteredLlmUsage, type ILlmUsageMeter } from '../modules/tool-auth/llm
 import { McpService } from '../modules/mcp/mcp.service.js';
 import { AgentAuditService, retentionDaysFrom } from '../modules/audit/agent-audit.service.js';
 import { readAgentPreamble, type AgentPreambleReader } from '../modules/agent-instructions/index.js';
+import {
+  agentGuideSections,
+  joinGuideSections,
+  type AgentGuideReader,
+  type AgentGuideSectionsReader,
+} from '../modules/agent-guide/index.js';
 import { createMcpAuthMiddleware } from '../modules/mcp/mcp-auth.middleware.js';
 import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js';
 import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
@@ -239,6 +245,14 @@ export interface CoreServices {
    * and `GET /api/agent/instructions`. See modules/agent-instructions.
    */
   readAgentPreamble: AgentPreambleReader;
+  /**
+   * Composes the platform's agent guide for the layout in effect, through
+   * the distribution's hook when it passed one: what `get_agent_guide` and a
+   * `read_file` of the guide's name answer. See modules/agent-guide.
+   */
+  agentGuide: AgentGuideReader;
+  /** The same guide as its sections, each with its title — what `get_agent_guide` lists and serves one of. */
+  agentGuideSections: AgentGuideSectionsReader;
   mcpServerEditService: McpServerEditService;
   /** Deleting one tool — the owner's verb (see ToolDeleteService). */
   toolDeleteService: ToolDeleteService;
@@ -606,10 +620,7 @@ export async function createCoreServices(
     // backfill would walk a tree still missing those manifests.
     new PluginDisplayNamesStep(disk, kb),
     new PersonalSpacesStep(disk, kb),
-    // A getter, not a value: the step is built here, while the process may
-    // still hold the defaults, and the save that completes first-run setup
-    // applies the admin's answer afterwards.
-    new TemplateFilesStep(disk, kb, extraDirs, () => settings.resolveAgentsFileLink()),
+    new TemplateFilesStep(disk, kb, extraDirs),
     new RolesYamlStep(disk, [config.adminEmail]),
     ...(ports.kbStartupSteps ?? []),
   ];
@@ -1168,6 +1179,12 @@ export async function createCoreServices(
   // the proxy below composes in-process per request; the agent-facing route
   // serves the same composition to the local bridge and the frontend card.
   const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kb, disk);
+  // The guide every agent is told to read first, composed when asked for —
+  // the layout is read per call, so a name the setup save applies lands
+  // without a restart, and the distribution's hook sees every composition.
+  const agentGuideSectionsReader: AgentGuideSectionsReader = () =>
+    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName });
+  const agentGuide: AgentGuideReader = async () => joinGuideSections(await agentGuideSectionsReader());
   // The Audit log. Records through the proxy below (every call an external
   // agent makes), reads keys through the key service so their shape is
   // defined once, and prunes past the retention setting — read per sweep, so
@@ -1214,6 +1231,11 @@ export async function createCoreServices(
   // so a just-repaired credential is retried on the very next request instead
   // of waiting out the failure memo's TTL, and pooled downstream connections.
   secretsVaultService.onMutation((changedUserId) => mcpService.onSecretsChanged(changedUserId));
+  // The proxy is the one place a connected server's tools are loaded, so it is
+  // the one place their schemas are checked — and the tool catalog is where the
+  // people who manage a server read what it found. Setter injection, like the
+  // OAuth discovery above: the proxy is constructed after the catalog.
+  toolManualService.setHiddenTools(mcpService.hiddenTools);
   // MCP OAuth 2.1 authorization server (our own AS): lets MCP clients with no
   // pre-shared connection key connect via the standard 401 → discovery → DCR →
   // authorize (PKCE) flow. The authorize step routes the browser to /connect
@@ -1440,6 +1462,8 @@ export async function createCoreServices(
     toolManualService,
     pendingToolsService,
     readAgentPreamble: readPreamble,
+    agentGuide,
+    agentGuideSections: agentGuideSectionsReader,
     pluginIndexService,
     pluginProvisionService,
     joinRequestsService,

package/src/index.ts

@@ -47,8 +47,8 @@ export {
   type LeasedWorker,
 } from './core/lifecycle.js';
 
-// Packaged assets (migrations/, kb-template/) + the migration runners.
-export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+// Packaged assets (migrations/, kb-template/, agent-guide/) + the migration runners.
+export { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
 export {
   runCoreMigrations,
   runEnterpriseMigrations,

package/src/modules/access/__tests__/access-control.atref-batch.test.ts

@@ -25,6 +25,8 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
   let svc: AccessControlService;
   const workspaceId = 'ws-atref-1';
   const admin = 'razvan@bevel.software';
+  /** In no role and named nowhere — read is default-deny for them. */
+  const stranger = 'mia@bevel.software';
 
   async function git(...args: string[]): Promise<void> {
     await execFileAsync('git', ['-C', repo, ...args]);
@@ -44,6 +46,10 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
       '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
     );
     await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
+    // For the read batch: a folder the whole organisation may open.
+    await fs.mkdir(path.join(repo, 'Knowledge/shared'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Knowledge/shared/access.md'), '---\nread:\n  - everyone\n---\n');
+    await fs.writeFile(path.join(repo, 'Knowledge/shared/note.md'), '# shared\n');
 
     await execFileAsync('git', ['init', '-b', 'main', repo]);
     await git('config', 'user.email', 'test@example.com');
@@ -96,4 +102,56 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
     expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
     expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
   });
+
+  /**
+   * The read side of the same batch, used by the change-request read tools to
+   * decide which of a request's files their caller may see. The verdicts must
+   * be identical to the single-path `canReadAtRef` the app's own content routes
+   * gate on — a batch that answered even one path differently would show an
+   * agent a file the app refuses to open.
+   */
+  it('canReadBatchAtRef answers default-deny, an `everyone` grant, and write-implies-read in one pass', async () => {
+    const paths = [
+      'Knowledge/plain.md',
+      'Knowledge/shared/note.md',
+      'Knowledge/with space.md',
+      'Knowledge/not-there.md',
+    ];
+    const forStranger = await svc.canReadBatchAtRef(workspaceId, 'main', stranger, paths);
+    expect(forStranger).not.toBeNull();
+    // Nothing names them, so read is refused — except where the folder says everyone.
+    expect(forStranger!.get('Knowledge/plain.md')).toBe(false);
+    expect(forStranger!.get('Knowledge/shared/note.md')).toBe(true);
+    expect(forStranger!.get('Knowledge/with space.md')).toBe(false);
+    expect(forStranger!.get('Knowledge/not-there.md')).toBe(false);
+
+    // The Admin write grant folds into read.
+    const forAdmin = await svc.canReadBatchAtRef(workspaceId, 'main', admin, paths);
+    expect([...forAdmin!.values()]).toEqual([true, true, true, true]);
+  });
+
+  it('canReadBatchAtRef matches the single-path read verdict on every path', async () => {
+    const paths = [
+      'Knowledge/plain.md',
+      'Knowledge/shared/note.md',
+      'Knowledge/with space.md',
+      'Knowledge/not-there.md',
+    ];
+    for (const who of [admin, stranger]) {
+      const batch = await svc.canReadBatchAtRef(workspaceId, 'main', who, paths);
+      for (const path of paths) {
+        const single = await svc.canReadAtRef(workspaceId, 'main', who, path);
+        expect(batch!.get(path), `${who} on ${path}`).toBe(single);
+      }
+    }
+  });
+
+  it('canReadBatchAtRef answers an empty map for no paths, and null for a ref it cannot resolve', async () => {
+    expect(await svc.canReadBatchAtRef(workspaceId, 'main', admin, [])).toEqual(new Map());
+    expect(await svc.canReadBatchAtRef(workspaceId, 'no-such-ref', admin, ['Knowledge/plain.md'])).toBeNull();
+    // The null-semantics hold for the empty set too: the ref is validated
+    // whatever was asked about, so no caller can read an empty map as proof
+    // that the ref resolved.
+    expect(await svc.canReadBatchAtRef(workspaceId, 'no-such-ref', admin, [])).toBeNull();
+  });
 });

package/src/modules/access/__tests__/access-control.platform-restore.test.ts

@@ -67,9 +67,10 @@ describe('restoring a platform file', () => {
     // only because it is the file that says who the admin is — the repository
     // that lost that one too is the last case in this file.
     const svc = service();
-    for (const name of ['.bevelignore', 'AGENTS.md']) {
-      expect(await svc.canRestorePlatformFile(WS, ADMIN, name)).toBe(true);
-    }
+    expect(await svc.canRestorePlatformFile(WS, ADMIN, '.bevelignore')).toBe(true);
+    // The agent guide is not a platform file: it is served from code, never
+    // written to the root, so a root `AGENTS.md` is content and no restore.
+    expect(await svc.canRestorePlatformFile(WS, ADMIN, 'AGENTS.md')).toBe(false);
     // Nothing is missing at `roles.yaml`: the root has one. A move is a rename
     // on disk, so landing another there would REPLACE the admin model rather
     // than put it back, and no exception carries that.
@@ -95,9 +96,9 @@ describe('restoring a platform file', () => {
     expect(await svc.canRestorePlatformFile(WS, ENGINEER, 'Sales/Legal/access.md')).toBe(false);
   });
 
-  it('the three root-only names are a restore at the root and nowhere else', async () => {
+  it('the root-only names are a restore at the root and nowhere else', async () => {
     const svc = service();
-    for (const dest of ['Sales/roles.yaml', 'Sales/.bevelignore', 'Sales/AGENTS.md']) {
+    for (const dest of ['Sales/roles.yaml', 'Sales/.bevelignore']) {
       expect(await svc.canRestorePlatformFile(WS, ADMIN, dest)).toBe(false);
     }
   });
@@ -113,14 +114,14 @@ describe('restoring a platform file', () => {
 
   it('a non-admin never gets the exception, wherever it would land', async () => {
     const svc = service();
-    for (const dest of ['roles.yaml', '.bevelignore', 'AGENTS.md', 'access.md', 'Legal/access.md']) {
+    for (const dest of ['roles.yaml', '.bevelignore', 'access.md', 'Legal/access.md']) {
       expect(await svc.canRestorePlatformFile(WS, ENGINEER, dest)).toBe(false);
     }
   });
 
   it('the deployment owner is an admin for it, and an ordinary destination is not a restore for anyone', async () => {
     const svc = service();
-    expect(await svc.canRestorePlatformFile(WS, OWNER, 'AGENTS.md')).toBe(true);
+    expect(await svc.canRestorePlatformFile(WS, OWNER, '.bevelignore')).toBe(true);
     for (const email of [ADMIN, OWNER]) {
       expect(await svc.canRestorePlatformFile(WS, email, 'Sales/deal.md')).toBe(false);
       expect(await svc.canRestorePlatformFile(WS, email, 'Sales/notes.md')).toBe(false);

package/src/modules/access/__tests__/access-personal-plugin.test.ts

@@ -7,7 +7,6 @@ import os from 'node:os';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
 import { personalAccessMd, pluginAccessMd } from '../../plugins/plugin-provision.service.js';
-import { defaultKbTemplateDir } from '../../../assets.js';
 import { closePersonalSpaceRules } from '../../workspace/startup/steps/personal-spaces.step.js';
 
 /**
@@ -17,10 +16,7 @@ import { closePersonalSpaceRules } from '../../workspace/startup/steps/personal-
  *  - a personal space must stay private even after an administrator opens
  *    the repository root with `read: everyone` (the usual way to let a new
  *    joiner read anything), while its owner keeps reading it — and Admin,
- *    who reads everything else, does not;
- *  - the managed AGENTS.md must be readable by every signed-in person even
- *    when the root grants read to nobody, because agents are told to read
- *    it before their first action.
+ *    who reads everything else, does not.
  */
 
 const KB_DIR = 'knowledge-base';
@@ -137,17 +133,4 @@ describe('the seeded access templates, resolved', () => {
     expect(await svc.canRead(workspaceId, 'admin@x.io', skill)).toBe(false);
   });
 
-  it('the packaged AGENTS.md is readable by a non-admin even when the root grants read to nobody', async () => {
-    const template = await fs.readFile(path.join(defaultKbTemplateDir(), 'AGENTS.md'), 'utf8');
-    const svc = await makeService({
-      'roles.yaml': ROLES_YAML,
-      'access.md': '---\nowner:\n  - Admin\n---\nwrite:\n  - Admin\n',
-      'AGENTS.md': template,
-      'KnowledgeBase/Notes.md': '# Notes\n',
-    });
-    const bob = await svc.canReadBatch(workspaceId, 'bob@x.io', ['AGENTS.md', 'KnowledgeBase/Notes.md']);
-    expect(bob.get('AGENTS.md')).toBe(true);
-    // The grant is the FILE's own, not a widening of the root.
-    expect(bob.get('KnowledgeBase/Notes.md')).toBe(false);
-  });
 });

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

@@ -631,6 +631,21 @@ export interface IAccessControl {
     relativePaths: string[],
   ): Promise<Map<string, boolean> | null>;
 
+  /**
+   * Batched variant of `canReadAtRef`, with the same null-semantics (the whole
+   * call returns null when the ref or its `roles.yaml` can't be resolved, and
+   * the caller must read that as deny). One access-tree load and one
+   * `git cat-file --batch` for the path set, the way `canWriteBatchAtRef`
+   * does it — a change request with forty files would otherwise cost forty
+   * single-path lookups to decide which of them its reader may see.
+   */
+  canReadBatchAtRef(
+    workspaceId: string,
+    ref: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean> | null>;
+
   /**
    * The set of principals with `write` on this path as of `ref`. Used by PR
    * reviewer routing and the per-file approval UI rendered against the PR

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

@@ -2103,6 +2103,27 @@ export class AccessControlService implements IAccessControl {
     return result;
   }
 
+  async canReadBatchAtRef(
+    workspaceId: string,
+    ref: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean> | null> {
+    // No shortcut for an empty path set: the null-semantics are the contract,
+    // so an unresolvable ref must answer null however many paths were asked
+    // about. Returning an empty map early would tell a caller the ref resolved.
+    const loaded = await this.loadModelAtRef(workspaceId, ref);
+    if (!loaded) return null;
+    const repoDir = await this.repoDir(workspaceId);
+    // One `git cat-file --batch` for the whole set — see canWriteBatchAtRef.
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const result = new Map<string, boolean>();
+    for (const p of relativePaths) {
+      result.set(p, canReadResolved(loaded.model, userEmail, p, owns.get(p) ?? null));
+    }
+    return result;
+  }
+
   async eligibleWritersAtRef(
     workspaceId: string,
     ref: string,