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

package/src/modules/workspace/__tests__/workspace.routes.download.test.ts

@@ -49,6 +49,8 @@ interface Harness {
   server: Server;
   baseUrl: string;
   canDownload: ReturnType<typeof vi.fn>;
+  canReadBatch: ReturnType<typeof vi.fn>;
+  canDownloadBatch: ReturnType<typeof vi.fn>;
   canWrite: ReturnType<typeof vi.fn>;
   createFolderZip: ReturnType<typeof vi.fn>;
 }
@@ -70,14 +72,21 @@ async function makeHarness(opts: {
     return opts.canDownload;
   });
   const canWrite = vi.fn();
+  // The /file/raw route now read-gates before the download gate; these tests
+  // exercise the download verb, so reads pass.
+  const canReadBatch = vi.fn(async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])));
+  // Every entry of a folder is judged for download too; by default each gets
+  // the folder's own verdict.
+  const canDownloadBatch = vi.fn(async (_w: string, _e: string, paths: string[]) =>
+    new Map(paths.map((p) => [p, opts.canDownload])),
+  );
   const accessControl: IAccessControl = {
     canWrite,
     canWriteBatch: vi.fn(),
-    // The /file/raw route now read-gates before the download gate; these tests
-    // exercise the download verb, so reads pass.
     canRead: vi.fn(async () => true),
-    canReadBatch: vi.fn(async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true]))),
+    canReadBatch,
     canDownload,
+    canDownloadBatch,
     eligibleWriters: vi.fn(),
     eligibleWriterEmails: vi.fn(),
     invalidate: vi.fn(),
@@ -152,7 +161,7 @@ async function makeHarness(opts: {
     throw new Error(`Unexpected server.address() shape: ${JSON.stringify(addr)}`);
   }
   const port = (addr as AddressInfo).port;
-  return { server, baseUrl: `http://127.0.0.1:${port}`, canDownload, canWrite, createFolderZip };
+  return { server, baseUrl: `http://127.0.0.1:${port}`, canDownload, canReadBatch, canDownloadBatch, canWrite, createFolderZip };
 }
 
 async function closeServer(server: Server): Promise<void> {
@@ -338,6 +347,8 @@ describe('GET /workspace/:id/folder/zip — gated on Download role', () => {
     expect(res.status).toBe(200);
     expect(res.headers.get('content-type')).toBe('application/zip');
     expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    // The archive holds one caller's verdicts, so a shared cache never keeps it.
+    expect(res.headers.get('cache-control')).toBe('private, no-store');
     const dispo = res.headers.get('content-disposition');
     expect(dispo).toBeTruthy();
     expect(dispo).toContain('attachment');
@@ -349,7 +360,43 @@ describe('GET /workspace/:id/folder/zip — gated on Download role', () => {
     // verb is resolved on its repo-relative form, and the service is handed the
     // repository path it was judged as.
     expect(h.canDownload).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, 'Knowledge/Sales');
-    expect(h.createFolderZip).toHaveBeenCalledWith(WORKSPACE_ID, `${KB}/Knowledge/Sales`);
+    expect(h.createFolderZip.mock.calls[0]!.slice(0, 2)).toEqual([WORKSPACE_ID, `${KB}/Knowledge/Sales`]);
+  });
+
+  it('judges every file the zip would pack: unreadable ones and undownloadable ones are left out', async () => {
+    h = await makeHarness({ canDownload: true });
+    // What the service finds under the folder; the route's filter decides.
+    const found = ['Knowledge/Sales/open.md', 'Knowledge/Sales/hidden.md', 'Knowledge/Sales/no-save.md'];
+    h.canReadBatch.mockImplementation(async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, p !== 'Knowledge/Sales/hidden.md'])),
+    );
+    h.canDownloadBatch.mockImplementation(async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, p !== 'Knowledge/Sales/no-save.md'])),
+    );
+    let packed: ReadonlySet<string> | null = null;
+    h.createFolderZip.mockImplementation(
+      async (_id: string, _p: string, include: (paths: string[]) => Promise<ReadonlySet<string>>) => {
+        packed = await include(found);
+        return ZIP_BYTES;
+      },
+    );
+
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Knowledge/Sales')}&download=1`,
+    );
+
+    expect(res.status).toBe(200);
+    expect([...packed!]).toEqual(['Knowledge/Sales/open.md']);
+    // Read first, then download on what is readable: a file the caller may
+    // not see is never asked about for download, so nothing about it is
+    // computed or counted.
+    expect(h.canReadBatch).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, found);
+    expect(h.canDownloadBatch).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, [
+      'Knowledge/Sales/open.md',
+      'Knowledge/Sales/no-save.md',
+    ]);
+    // The count covers the readable file left out, not the hidden one.
+    expect(res.headers.get('x-withheld-files')).toBe('1');
   });
 
   it('user without Download role gets 403 and no zip is built', async () => {

package/src/modules/workspace/__tests__/workspace.routes.folder-zip-access.test.ts

@@ -0,0 +1,190 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import express from 'express';
+import AdmZip from 'adm-zip';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { ICreatorAccess } from '../../access-model/creator.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { createWorkspaceRoutes } from '../workspace.routes.js';
+import { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * The folder download over the REAL resolver and the REAL zip builder.
+ *
+ * `download` on a folder let the caller ask for its zip, and the zip then
+ * packed every file under the folder: no file was judged against its own
+ * rules, so a caller got files whose frontmatter denied them `download`, files
+ * whose frontmatter denied them `read`, and whole sub-folders a nested
+ * access.md closed to them — files the per-file route refused and the file
+ * tree never showed (found 2026-10-07). The four cases below are the ones
+ * that were verified leaking; each must now be absent from the archive, and
+ * the one the caller may download must still be in it.
+ */
+
+const KB = 'knowledge-base';
+const WORKSPACE_ID = 'target-company-state';
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+let caller = { id: 'user-1', email: 'ana@x.io', name: 'Ana' };
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+`;
+
+/** The folder Ana may download, with the files the rules below decide over. */
+const FILES: Record<string, string> = {
+  'Shared/access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+  'Shared/Open.md': '# open\n',
+  'Shared/Node-Deny-Download.md': '---\ndownload:\n  - deny Ana <ana@x.io>\n---\n# no save\n',
+  'Shared/Node-Deny-Read.md': '---\nread:\n  - deny Ana <ana@x.io>\n---\n# hidden\n',
+  'Shared/Inner/access.md': '---\n---\nread:\n  - deny Ana <ana@x.io>\ndownload:\n  - deny Ana <ana@x.io>\n',
+  'Shared/Inner/Plan.md': '# hidden plan\n',
+};
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+}
+
+describe('GET /folder/zip judges every file it packs (real resolver, real zip)', () => {
+  let root: string;
+  let h: Harness | null = null;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-zip-access-'));
+    caller = { id: 'user-1', email: 'ana@x.io', name: 'Ana' };
+  });
+
+  afterEach(async () => {
+    if (h) {
+      await new Promise<void>((resolve, reject) => h!.server.close((e) => (e ? reject(e) : resolve())));
+      h = null;
+    }
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeHarness(files: Record<string, string>): Promise<Harness> {
+    const workspaceDir = path.join(root, WORKSPACE_ID);
+    const repo = path.join(workspaceDir, KB);
+    // A `.git` folder is what makes the service adopt the clone without cloning.
+    await fs.mkdir(path.join(repo, '.git'), { recursive: true });
+    for (const [rel, contents] of Object.entries({ 'roles.yaml': ROLES_YAML, ...files })) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+
+    const workspaceService = new WorkspaceService(
+      root,
+      'https://example.invalid/kb.git',
+      testKbContext({ kbDirName: KB }),
+      new NodeFs(),
+    );
+    const accessControl = new AccessControlService(workspaceService, KB, new NodeFs());
+    const authService = { getUserById: async () => caller } as unknown as AuthService;
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', (req, _res, next) => {
+      (req as unknown as { userId: string }).userId = caller.id;
+      next();
+    });
+    app.use(
+      '/api',
+      createWorkspaceRoutes(
+        workspaceService,
+        authService,
+        {} as unknown as IWorkflowService,
+        {} as unknown as WorkflowEventBus,
+        accessControl,
+        testKbContext({ kbDirName: KB }),
+        stubCreatorAccess,
+        { isAdmin: async () => false } as unknown as IAdminAccessService,
+        new NodeFs(),
+      ),
+    );
+    const server = await new Promise<Server>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const addr = server.address() as AddressInfo;
+    return { server, baseUrl: `http://127.0.0.1:${addr.port}` };
+  }
+
+  const zipOf = (base: string, folder: string) =>
+    fetch(`${base}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent(folder)}&download=1`);
+
+  const entriesOf = async (res: Response) =>
+    new AdmZip(Buffer.from(await res.arrayBuffer()))
+      .getEntries()
+      .map((e) => e.entryName)
+      .sort();
+
+  it('packs the file the caller may download, and none of the ones their own rules withhold', async () => {
+    h = await makeHarness(FILES);
+
+    const res = await zipOf(h.baseUrl, `${KB}/Shared`);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('application/zip');
+    // Ana's archive, with Ana's verdicts: never served to anyone else from a cache.
+    expect(res.headers.get('cache-control')).toBe('private, no-store');
+    expect(await entriesOf(res)).toEqual(['Shared/Open.md', 'Shared/access.md']);
+    // One file Ana can see but not save is counted; the two she cannot see
+    // and the closed folder are not — the count says nothing the tree does not.
+    expect(res.headers.get('x-withheld-files')).toBe('1');
+  });
+
+  it('the per-file route agrees on every one of them', async () => {
+    h = await makeHarness(FILES);
+    const raw = (p: string) =>
+      fetch(`${h!.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent(`${KB}/${p}`)}&download=1`);
+
+    expect((await raw('Shared/Open.md')).status).toBe(200);
+    expect((await raw('Shared/Node-Deny-Download.md')).status).toBe(403);
+    expect((await raw('Shared/Node-Deny-Read.md')).status).toBe(403);
+    expect((await raw('Shared/Inner/Plan.md')).status).toBe(403);
+  });
+
+  it('still refuses the folder itself to someone with no download grant', async () => {
+    h = await makeHarness(FILES);
+    caller = { id: 'user-2', email: 'mallory@x.io', name: 'Mallory' };
+
+    const res = await zipOf(h.baseUrl, `${KB}/Shared`);
+
+    expect(res.status).toBe(403);
+  });
+
+  // `access.md` itself stays in HERE: this fixture's declares nothing for
+  // itself (its frontmatter is empty), so the folder's rules — which admit
+  // the caller — admit the file too. That is not a guarantee: an `access.md`
+  // is judged like any file, by its own frontmatter and the folder chain, and
+  // one whose frontmatter denies the caller its read is left out of the
+  // archive exactly as the single-file route would refuse it.
+  it('answers an archive holding only the grant file, not an error, when every content file is withheld', async () => {
+    h = await makeHarness({
+      'Shared/access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+      'Shared/Only.md': '---\ndownload:\n  - deny Ana <ana@x.io>\n---\n# no save\n',
+    });
+
+    const res = await zipOf(h.baseUrl, `${KB}/Shared`);
+
+    expect(res.status).toBe(200);
+    expect(await entriesOf(res)).toEqual(['Shared/access.md']);
+    expect(res.headers.get('x-withheld-files')).toBe('1');
+  });
+});

package/src/modules/workspace/__tests__/workspace.routes.move-platform-files.test.ts

@@ -136,14 +136,14 @@ describe('a platform file stays in its folder', () => {
     await fs.rm(h.workspaceDir, { recursive: true, force: true });
   });
 
-  // Each of the four, at a place the platform reads it from. `access.md` and
-  // `.bevelignore` are read wherever they sit; `roles.yaml` and `AGENTS.md`
-  // are read from the repository root only.
+  // Each of the three, at a place the platform reads it from. `access.md` and
+  // `.bevelignore` are read wherever they sit; `roles.yaml` is read from the
+  // repository root only. (`AGENTS.md` is not among them: the agent guide is
+  // served from code, so a root `AGENTS.md` is the organisation's own page.)
   const PLATFORM_FILES = [
     { name: 'access.md', at: `${KB}/Sales/access.md` },
     { name: '.bevelignore', at: `${KB}/Sales/.bevelignore` },
     { name: 'roles.yaml', at: `${KB}/roles.yaml` },
-    { name: 'AGENTS.md', at: `${KB}/AGENTS.md` },
   ];
 
   it.each(PLATFORM_FILES)('refuses a rename of $name with the sentence', async ({ name, at }) => {
@@ -188,13 +188,12 @@ describe('a platform file stays in its folder', () => {
     },
   );
 
-  // The recovery move, for each of the four, from the place a misplaced copy
+  // The recovery move, for each of the three, from the place a misplaced copy
   // is actually found to the place the platform reads it.
   const RESTORES = [
     { name: 'access.md', from: `${KB}/Misplaced/access.md`, to: `${KB}/access.md`, dest: 'access.md' },
     { name: '.bevelignore', from: `${KB}/Misplaced/.bevelignore`, to: `${KB}/.bevelignore`, dest: '.bevelignore' },
     { name: 'roles.yaml', from: `${KB}/Misplaced/roles.yaml`, to: `${KB}/roles.yaml`, dest: 'roles.yaml' },
-    { name: 'AGENTS.md', from: `${KB}/Misplaced/AGENTS.md`, to: `${KB}/AGENTS.md`, dest: 'AGENTS.md' },
   ];
 
   it.each(RESTORES)(
@@ -265,6 +264,14 @@ describe('a platform file stays in its folder', () => {
 
     expect(h.moveEntry).not.toHaveBeenCalled();
     expect(h.acquireLock).not.toHaveBeenCalled();
+
+    // A root `AGENTS.md` is NOT a platform file any more — the guide is served
+    // from code — so a note renamed to it is an ordinary move that lands.
+    const guide = await move(h, `${KB}/Sales/deal.md`, `${KB}/AGENTS.md`);
+    expect(guide.status).toBe(200);
+    expect(guide.body).toEqual({ status: 'moved' });
+    expect(h.moveEntry).toHaveBeenCalledTimes(1);
+    expect(h.moveEntry).toHaveBeenCalledWith(WORKSPACE_ID, `${KB}/Sales/deal.md`, `${KB}/AGENTS.md`);
   });
 
   it('a destination that fills up after the access check is caught under the lock', async () => {
@@ -318,11 +325,15 @@ describe('a platform file stays in its folder', () => {
     }
   });
 
-  it('a nested roles.yaml or AGENTS.md is ordinary content and moves freely', async () => {
-    // They are read from the root and nowhere else, so a nested file of
-    // either name carries no platform meaning to protect.
+  it('a nested roles.yaml, and an AGENTS.md anywhere, are ordinary content and move freely', async () => {
+    // `roles.yaml` is read from the root and nowhere else, so a nested file
+    // of that name carries no platform meaning to protect. An `AGENTS.md` is
+    // never read as configuration: the platform's guide is served from code,
+    // so the organisation's own file moves and renames like any page, at the
+    // root included.
     expect((await move(h, `${KB}/Sales/roles.yaml`, `${KB}/Sales/old-roles.yaml`)).status).toBe(200);
     expect((await move(h, `${KB}/Sales/AGENTS.md`, `${KB}/Legal/AGENTS.md`)).status).toBe(200);
-    expect(h.moveEntry).toHaveBeenCalledTimes(2);
+    expect((await move(h, `${KB}/AGENTS.md`, `${KB}/Handbook/AGENTS.md`)).status).toBe(200);
+    expect(h.moveEntry).toHaveBeenCalledTimes(3);
   });
 });

package/src/modules/workspace/__tests__/workspace.service.forget-clone-races.test.ts

@@ -127,6 +127,13 @@ describe('a bootstrap in flight when the working copy is taken away', () => {
     const svc = service(runner);
     // Nothing on disk: this is a first clone, which is what takes seconds.
     const opening = svc.getOrCreateForBranch(BRANCH);
+    // Told, rather than handed a cached path to a working copy of the
+    // repository that was replaced — which every later read would ENOENT on,
+    // with nothing left to re-clone it. The expectation is attached NOW: the
+    // refusal lands somewhere inside the timer turns below, and a rejection
+    // with no handler on it across a turn is what Vitest reports as unhandled
+    // — a flake that failed the suite on CI with every test green.
+    const refused = expect(opening).rejects.toThrow(/replaced while the "main" working copy was being created/);
     await vi.waitFor(() => expect(calls.length).toBeGreaterThan(0));
 
     // The replacement lands while the clone runs.
@@ -139,9 +146,6 @@ describe('a bootstrap in flight when the working copy is taken away', () => {
       await new Promise((r) => setTimeout(r, 0));
     }
 
-    // Told, rather than handed a cached path to a working copy of the
-    // repository that was replaced — which every later read would ENOENT on,
-    // with nothing left to re-clone it.
-    await expect(opening).rejects.toThrow(/replaced while the "main" working copy was being created/);
+    await refused;
   });
 });

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -698,13 +698,55 @@ describe('WorkspaceService.createFolderZip', () => {
     }));
   }
 
+  /** The filter a caller with every permission passes: pack everything found. */
+  const ALL = async (paths: string[]) => new Set(paths);
+
+  it('packs only what the filter allows, and asks it once with every file as a repository path', async () => {
+    const dir = path.join(repoDir, 'judged');
+    await fs.mkdir(path.join(dir, 'inner'), { recursive: true });
+    await fs.writeFile(path.join(dir, 'open.md'), 'open');
+    await fs.writeFile(path.join(dir, 'withheld.md'), 'withheld');
+    await fs.writeFile(path.join(dir, 'inner', 'deep.md'), 'deep');
+    const asked: string[][] = [];
+    const include = async (paths: string[]) => {
+      asked.push([...paths].sort());
+      return new Set(paths.filter((p) => p !== 'judged/withheld.md'));
+    };
+
+    const buf = await svc.createFolderZip(workspaceId, 'judged', include);
+
+    // Asked once, with every file the walk found, keyed the way the access
+    // rules are: relative to the repository, not to the folder or the workspace.
+    expect(asked).toEqual([['judged/inner/deep.md', 'judged/open.md', 'judged/withheld.md']]);
+    const names = (await unzipEntries(buf)).map((e) => e.name).sort();
+    expect(names).toEqual(['judged/inner/deep.md', 'judged/open.md']);
+  });
+
+  it('keys the files the same way whether the folder is written with a trailing slash or not', async () => {
+    const dir = path.join(repoDir, 'slashed');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'a.md'), 'a');
+    const asked: string[][] = [];
+    const include = async (paths: string[]) => {
+      asked.push(paths);
+      return new Set(paths);
+    };
+
+    await svc.createFolderZip(workspaceId, 'slashed/', include);
+    await svc.createFolderZip(workspaceId, `${'knowledge-base'}/slashed//`, include);
+
+    // A `slashed//a.md` key would match no verdict, and the filter would
+    // withhold the whole folder without a word.
+    expect(asked).toEqual([['slashed/a.md'], ['slashed/a.md']]);
+  });
+
   it('zips a folder prefixing entries with the folder name', async () => {
     const dir = path.join(repoDir, 'docs');
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(path.join(dir, 'a.md'), 'alpha');
     await fs.writeFile(path.join(dir, 'b.md'), 'beta');
 
-    const buf = await svc.createFolderZip(workspaceId, 'docs');
+    const buf = await svc.createFolderZip(workspaceId, 'docs', ALL);
     const entries = await unzipEntries(buf);
     const names = entries.map((e) => e.name).sort();
     expect(names).toEqual(['docs/a.md', 'docs/b.md']);
@@ -719,7 +761,7 @@ describe('WorkspaceService.createFolderZip', () => {
     await fs.writeFile(path.join(dir, 'nested', 'mid.md'), 'mid');
     await fs.writeFile(path.join(dir, 'nested', 'deep', 'leaf.md'), 'leaf');
 
-    const buf = await svc.createFolderZip(workspaceId, 'tree');
+    const buf = await svc.createFolderZip(workspaceId, 'tree', ALL);
     const names = (await unzipEntries(buf)).map((e) => e.name).sort();
     expect(names).toEqual([
       'tree/nested/deep/leaf.md',
@@ -736,7 +778,7 @@ describe('WorkspaceService.createFolderZip', () => {
     await fs.writeFile(path.join(dir, '.gitkeep'), '');
     await fs.writeFile(path.join(dir, 'real.md'), 'real');
 
-    const buf = await svc.createFolderZip(workspaceId, 'mixed');
+    const buf = await svc.createFolderZip(workspaceId, 'mixed', ALL);
     const names = (await unzipEntries(buf)).map((e) => e.name).sort();
     expect(names).toEqual(['mixed/real.md']);
   });
@@ -748,7 +790,7 @@ describe('WorkspaceService.createFolderZip', () => {
     await fs.writeFile(path.join(dir, 'public.md'), 'pub');
     await fs.writeFile(path.join(dir, 'secret.md'), 'shh');
 
-    const buf = await svc.createFolderZip(workspaceId, 'with-ignore');
+    const buf = await svc.createFolderZip(workspaceId, 'with-ignore', ALL);
     const names = (await unzipEntries(buf)).map((e) => e.name).sort();
     expect(names).toContain('with-ignore/public.md');
     expect(names).not.toContain('with-ignore/secret.md');
@@ -756,17 +798,17 @@ describe('WorkspaceService.createFolderZip', () => {
 
   it('refuses to zip a file (not a directory)', async () => {
     await fs.writeFile(path.join(repoDir, 'lone.md'), 'one');
-    await expect(svc.createFolderZip(workspaceId, 'lone.md')).rejects.toThrow('Not a directory');
+    await expect(svc.createFolderZip(workspaceId, 'lone.md', ALL)).rejects.toThrow('Not a directory');
   });
 
   it('refuses a traversing path, and reads an unprefixed one as the repository folder', async () => {
-    await expect(svc.createFolderZip(workspaceId, '../escape')).rejects.toThrow(
+    await expect(svc.createFolderZip(workspaceId, '../escape', ALL)).rejects.toThrow(
       'is outside the knowledge base repository',
     );
     // The unprefixed spelling is the repository's own folder, so it zips.
     await fs.mkdir(path.join(repoDir, 'unprefixed'), { recursive: true });
     await fs.writeFile(path.join(repoDir, 'unprefixed', 'a.md'), 'a');
-    const buf = await svc.createFolderZip(workspaceId, 'unprefixed');
+    const buf = await svc.createFolderZip(workspaceId, 'unprefixed', ALL);
     expect((await unzipEntries(buf)).map((e) => e.name)).toEqual(['unprefixed/a.md']);
   });
 
@@ -796,7 +838,7 @@ describe('WorkspaceService.createFolderZip', () => {
       return result;
     });
     try {
-      await expect(svc.createFolderZip(workspaceId, 'too-big'))
+      await expect(svc.createFolderZip(workspaceId, 'too-big', ALL))
         .rejects.toBeInstanceOf(FolderTooLargeError);
     } finally {
       statSpy.mockRestore();

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -14,19 +15,18 @@ import { SpillStore } from '../spill-store.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
-import { sharedFileRulesSection, sharedRulesPointer } from '../../agent-instructions/shared-file-rules.js';
+import { sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
 
 /**
- * What the platform TELLS AN AGENT about the conventions file, under the
- * default name and under a deployment's own.
+ * What the platform TELLS AN AGENT about the guide.
  *
- * The conventions reminder and the platform-file list are SHARED RULES now —
- * stated in the handshake instructions and in the managed agent guide, once
- * each — so their wording is asserted against that one text. What each tool
- * description still has to get right is the POINTER at the end, which names the
- * guide by the name this deployment gave it; that is the only place a remote
- * agent learns which file to open, and it has no checkout, so no harness reads
- * that file for it.
+ * The conventions reminder and the platform-file list are SHARED RULES —
+ * stated in the handshake instructions and in the guide, once each — so their
+ * wording is asserted against that one text. What each tool description has
+ * to get right is its OPENING: the one sentence saying to call
+ * `get_agent_guide` first, which the catalog puts at the front of every tool
+ * (see tool-registry/guide-first.ts); a remote agent has no checkout, so that
+ * sentence and the rule are the only places it learns what to read first.
  */
 const KB_DIR = 'knowledge-base';
 /** The context the tools read; a case applies a deployment's own names to it. */
@@ -64,70 +64,48 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
 
 afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
-describe("what names the guide, under the default name and under a deployment's own", () => {
-  it('names AGENTS.md, and CLAUDE.md beside it, under the default name', () => {
+describe('what tells an agent to read the guide first', () => {
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with the same guide after the organisation\'s own', () => {
     const rules = sharedFileRulesSection(kb.layout);
-    expect(rules).toContain(
-      'read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed',
-    );
+    expect(rules).toContain("call `get_agent_guide` and read the platform's guide");
+    expect(rules).toContain('read_file on `AGENTS.md` at the KB root answers with the same guide');
+    expect(rules).toContain("after the organisation's own conventions file of that name");
+    expect(rules).toContain('`CLAUDE.md`');
+    // One name on every deployment: the rule names no other.
+    expect(rules).not.toContain('HEXIS.md');
   });
 
-  it("points every entrypoint at the section, by the guide's own name", async () => {
+  it('opens every entrypoint with the guide-first sentence, reads included', async () => {
     const byName = await descriptions();
-    // On EVERY entrypoint, reads included: any of them can be a session's first.
-    for (const name of ['grep', 'list_files', 'file_stat', 'write_file', 'move_file']) {
-      expect(byName.get(name), name).toContain('see "Working with files" in AGENTS.md.');
+    for (const name of ['grep', 'list_files', 'file_stat', 'read_file', 'write_file', 'move_file', 'start_session']) {
+      expect(byName.get(name)!.startsWith(`${GUIDE_FIRST_SENTENCE} `), name).toBe(true);
+      // Once, at the front — never again further down.
+      expect(byName.get(name)!.split(GUIDE_FIRST_SENTENCE), name).toHaveLength(2);
     }
   });
 
-  it("names the configured file first and the organisation's own AGENTS.md second", () => {
-    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    const note = sharedFileRulesSection(kb.layout);
-    expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
-    expect(note).toContain("the organisation's own conventions");
-    // Ours first: an agent that reads only one must read the platform's.
-    expect(note.indexOf('`HEXIS.md`')).toBeLessThan(note.indexOf('`AGENTS.md`'));
-    // The legacy name is still offered, for a KB seeded before the rename.
-    expect(note).toContain('`CLAUDE.md`');
-  });
-
-  it('lists the platform files under the configured name, and no longer under AGENTS.md', () => {
+  it('lists the guide under no name as a platform file, and ignores a name a deployment saved for it', () => {
     kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const rules = sharedFileRulesSection(kb.layout);
-    // Listed with the depth each one counts at — `access.md` and
-    // `.bevelignore` govern the folder they sit in, the other two are read from
-    // the root — because the names alone would have an agent refuse a nested
-    // `HEXIS.md` it may rename.
-    expect(rules).toContain('`access.md` or `.bevelignore` in any folder, `roles.yaml` or `HEXIS.md` at the repository root');
-    // The customer's file is content on such a deployment, so the rule that
-    // refuses a move must not claim it.
-    expect(rules.replace(/`AGENTS\.md` if it also exists/g, '')).not.toContain('`AGENTS.md`');
-  });
-
-  it('keeps naming AGENTS.md as a platform file under the default name', () => {
-    expect(sharedFileRulesSection(kb.layout)).toContain(
-      '`access.md` or `.bevelignore` in any folder, `roles.yaml` or `AGENTS.md` at the repository root',
-    );
+    expect(rules).toContain('`access.md` or `.bevelignore` in any folder, `roles.yaml` at the repository root');
+    expect(rules).not.toContain('HEXIS.md');
+    expect(rules).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
   });
 
   /**
    * First-run setup on a fresh deployment: the tools are mounted at boot, under
    * the defaults, and the save that COMPLETES setup applies the admin's names
-   * in that same request — without a restart, deliberately, so the KB phase it
-   * runs next scaffolds the names they chose. A catalog built once at boot
-   * would go on naming `AGENTS.md` to every agent that connected afterwards.
+   * in that same request — without a restart. Nothing in the opening sentence
+   * moves with a name, so what the catalog said at boot is what it says after.
    */
-  it('follows a layout applied after the tools were mounted', async () => {
+  it('says the same thing after a layout is applied as it did at the mount', async () => {
     const registry = new ToolRegistry();
     const atMount = await descriptions(registry);
-    expect(atMount.get('grep')).toContain('in AGENTS.md.');
-
-    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' });
     const now = await listed(registry);
     for (const name of ['grep', 'file_stat', 'delete_file', 'move_file']) {
-      expect(now.get(name), name).toContain(sharedRulesPointer(kb.layout));
-      expect(now.get(name), name).not.toContain('in AGENTS.md.');
+      expect(now.get(name)!.startsWith(GUIDE_FIRST_SENTENCE), name).toBe(true);
+      expect(now.get(name), name).toBe(atMount.get(name));
     }
   });
 });