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

package/src/modules/access/__tests__/access.routes.prospective.test.ts

@@ -3,15 +3,14 @@ import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
-import type { IAccessControl, ProspectiveHolders } from '../access-control.interface.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { AuthService } from '../../auth/auth.service.js';
-import type { WorkflowService } from '../../workflow/workflow.service.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
-import type { Database } from '../../database/connection.js';
+import type { HolderChanges, IAccessControl, ProspectiveHolders } from '../access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { AuthService } from '../../auth/index.js';
+import type { WorkflowEventBus, WorkflowService } from '../../workflow/index.js';
+import type { Database } from '../../database/index.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 
 /**
  * HTTP contract for `GET /access/prospective` — what the move confirmation
@@ -41,17 +40,28 @@ const HOLDERS: ProspectiveHolders = {
   },
 };
 
+/** What the resolver judges changed: Engineering loses editing, Ali gains opening. */
+const CHANGES: HolderChanges = {
+  lose: [{ kind: 'group', name: 'Engineering', verb: 'write' }],
+  gain: [{ kind: 'person', name: 'ali@bevel.software', email: 'ali@bevel.software', verb: 'read' }],
+};
+
 interface Harness {
   server: Server;
   baseUrl: string;
   canRead: ReturnType<typeof vi.fn>;
   prospectiveHolders: ReturnType<typeof vi.fn>;
+  prospectiveHolderChanges: ReturnType<typeof vi.fn>;
 }
 
-async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
-  const canRead = vi.fn(async () => opts.canRead ?? true);
+/** `canRead` answers `opts.canRead` for every path, or per path through `opts.readable`. */
+async function makeHarness(opts: { canRead?: boolean; readable?: (path: string) => boolean } = {}): Promise<Harness> {
+  const canRead = vi.fn(async (_ws: string, _email: string, path: string) =>
+    opts.readable ? opts.readable(path) : (opts.canRead ?? true),
+  );
   const prospectiveHolders = vi.fn(async () => HOLDERS);
-  const accessControl = { canRead, prospectiveHolders } as unknown as IAccessControl;
+  const prospectiveHolderChanges = vi.fn(async () => CHANGES);
+  const accessControl = { canRead, prospectiveHolders, prospectiveHolderChanges } as unknown as IAccessControl;
 
   const app = express();
   app.use(express.json());
@@ -70,7 +80,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,
       testKbContext({ kbDirName: KB }),
-      new NodeFs(),
+      realDisk(),
     ),
   );
 
@@ -78,7 +88,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
     const s = app.listen(0, () => resolve(s));
   });
   const addr = server.address() as AddressInfo;
-  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, canRead, prospectiveHolders };
+  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, canRead, prospectiveHolders, prospectiveHolderChanges };
 }
 
 function close(s: Server): Promise<void> {
@@ -110,6 +120,13 @@ describe('GET /access/prospective', () => {
       'Knowledge/Legal/contract.md',
       'Knowledge/Sales/contract.md',
     );
+    // The resolver's own changes ride along: the one answer the move dialog
+    // renders, and the same the agent's `move_file` gives.
+    expect(h.prospectiveHolderChanges).toHaveBeenCalledWith(
+      WS,
+      'Knowledge/Legal/contract.md',
+      'Knowledge/Sales/contract.md',
+    );
     expect(await res.json()).toEqual({
       before: {
         read: [{ kind: 'group', name: 'Engineering' }],
@@ -122,9 +139,32 @@ describe('GET /access/prospective', () => {
         ],
         write: [],
       },
+      changes: CHANGES,
     });
   });
 
+  it('refuses a caller who cannot read the destination folder, resolving nothing: the lists and changes are that folder\'s rules read back', async () => {
+    h = await makeHarness({ readable: (path) => path !== 'Knowledge/Sales' });
+
+    const res = await get(
+      `from=${encodeURIComponent('Knowledge/Legal/contract.md')}&toDir=${encodeURIComponent('Knowledge/Sales')}`,
+    );
+
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({ error: 'You do not have access to this folder.' });
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Knowledge/Sales');
+    expect(h.prospectiveHolders).not.toHaveBeenCalled();
+    expect(h.prospectiveHolderChanges).not.toHaveBeenCalled();
+  });
+
+  it('asks the read gate about the repo root when the destination is the root', async () => {
+    h = await makeHarness();
+
+    await get(`from=${encodeURIComponent('Knowledge/Legal/contract.md')}&toDir=`);
+
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, '');
+  });
+
   it('strips the workspace-relative kb prefix from both ends', async () => {
     h = await makeHarness();
 

package/src/modules/access/__tests__/holder-changes.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { realDisk } from '../../../__tests__/real-disk.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import { AccessControlService } from '../access-control.service.js';
+
+/**
+ * `prospectiveHolderChanges`: who loses and who gains opening or editing a
+ * file or folder in a move, over a real on-disk tree. The holder lists name
+ * grants, so these tests are about the cases a list comparison gets wrong: a
+ * group still covered by `everyone` where it lands, and someone a rule there
+ * denies by name, even when their only access before was `everyone`.
+ */
+
+const KB_DIR = 'knowledge-base';
+const rules = (body: string) => `---\n${body}---\n`;
+
+describe('AccessControlService.prospectiveHolderChanges', () => {
+  let root: string;
+  let repo: string;
+  const workspaceId = 'ws-holder-changes';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-holder-changes-'));
+    repo = path.join(root, workspaceId, KB_DIR);
+  });
+  afterEach(async () => {
+    if (root) await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function write(files: Record<string, string>): Promise<void> {
+    for (const [rel, contents] of Object.entries(files)) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+  }
+
+  const service = () =>
+    new AccessControlService(
+      {
+        getWorkspacePath: async () => path.join(root, workspaceId),
+        ensureRemotesFetched: async () => undefined,
+      } as unknown as WorkspaceService,
+      KB_DIR,
+      realDisk(),
+    );
+
+  /** Everyone reads; Support and Operations each edit their own folder. */
+  const BASE = {
+    'roles.yaml': 'roles:\n  Admin:\n    - admin@x.io\n',
+    'groups.yaml': 'groups:\n  Support:\n    - bea@x.io\n  Operations:\n    - jonas@x.io\n',
+    'access.md': rules('read:\n  - everyone\n'),
+    'Support/access.md': rules('write:\n  - Support\n'),
+    'Support/Runbooks/Warranty claim.md': '# Warranty claim\n',
+    'Operations/access.md': rules('write:\n  - Operations\n'),
+  };
+
+  it('a folder handed to another team: the old team loses editing, the new one gains it, and nobody loses opening it', async () => {
+    await write(BASE);
+    const changes = await service().prospectiveHolderChanges(workspaceId, 'Support/Runbooks', 'Operations/Runbooks');
+    expect(changes).toEqual({
+      lose: [{ kind: 'group', name: 'Support', verb: 'write' }],
+      gain: [{ kind: 'group', name: 'Operations', verb: 'write' }],
+    });
+  });
+
+  it('a person the destination denies by name loses access, though everyone may still read there', async () => {
+    await write({
+      ...BASE,
+      'Team/access.md': rules('write:\n  - Ana <ana@x.io>\n'),
+      'Team/plan.md': '# Plan\n',
+      'Closed/access.md': rules('read:\n  - everyone\n  - deny Ana <ana@x.io>\n'),
+    });
+    const changes = await service().prospectiveHolderChanges(workspaceId, 'Team/plan.md', 'Closed/plan.md');
+    expect(changes.lose).toEqual(
+      expect.arrayContaining([
+        { kind: 'person', name: 'ana@x.io', email: 'ana@x.io', verb: 'read' },
+        { kind: 'person', name: 'ana@x.io', email: 'ana@x.io', verb: 'write' },
+      ]),
+    );
+  });
+
+  it('a person whose only access was everyone, and whom the destination denies by name, loses it', async () => {
+    await write({
+      ...BASE,
+      'Closed/access.md': rules('read:\n  - everyone\n  - deny Leo <leo@x.io>\n'),
+    });
+    const changes = await service().prospectiveHolderChanges(workspaceId, 'Support/Runbooks', 'Closed/Runbooks');
+    expect(changes.lose).toContainEqual({ kind: 'person', name: 'leo@x.io', email: 'leo@x.io', verb: 'read' });
+  });
+
+  it('a group whose only read was everyone, and which the destination denies, loses it', async () => {
+    await write({
+      ...BASE,
+      'Closed/access.md': rules('read:\n  - everyone\n  - deny Operations\n'),
+    });
+    const changes = await service().prospectiveHolderChanges(workspaceId, 'Support/Runbooks', 'Closed/Runbooks');
+    expect(changes.lose).toContainEqual({ kind: 'group', name: 'Operations', verb: 'read' });
+  });
+
+  it('a group the destination denies loses opening it, though everyone may still read there', async () => {
+    await write({
+      ...BASE,
+      'Closed/access.md': rules('read:\n  - everyone\n  - deny Support\n'),
+    });
+    const changes = await service().prospectiveHolderChanges(workspaceId, 'Support/Runbooks', 'Closed/Runbooks');
+    expect(changes.lose).toEqual(
+      expect.arrayContaining([
+        { kind: 'group', name: 'Support', verb: 'read' },
+        { kind: 'group', name: 'Support', verb: 'write' },
+      ]),
+    );
+  });
+
+  it('a rename that carries its own rules changes nobody', async () => {
+    await write({
+      ...BASE,
+      'Sales/access.md': rules('read:\n  - Support\nwrite:\n  - Support\n'),
+      'Sales/deal.md': '# Deal\n',
+    });
+    expect(await service().prospectiveHolderChanges(workspaceId, 'Sales', 'Revenue')).toEqual({ lose: [], gain: [] });
+  });
+});

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

@@ -92,6 +92,17 @@ export type PathHolders = { read: HolderList; write: HolderList };
  */
 export type ProspectiveHolders = { before: PathHolders; after: PathHolders };
 
+/** One principal that loses or gains one verb in a move. A person is named by their address when they have no display name. */
+export type HolderChange = {
+  kind: 'group' | 'role' | 'plugin' | 'person';
+  name: string;
+  email?: string;
+  verb: 'read' | 'write';
+};
+
+/** Who loses and who gains opening or editing a file or folder in a move — see {@link IAccessControl.prospectiveHolderChanges}. */
+export type HolderChanges = { lose: HolderChange[]; gain: HolderChange[] };
+
 /** One caller's own verdict per access verb on one path. */
 export type PathVerbs = { read: boolean; write: boolean; download: boolean; owner: boolean };
 
@@ -420,6 +431,21 @@ export interface IAccessControl {
     toPath: string,
   ): Promise<ProspectiveHolders>;
 
+  /**
+   * Who loses and who gains `read` or `write` on one file or folder if a move
+   * puts it at `toPath`, over the same relocation as
+   * {@link IAccessControl.prospectiveHolders}. A holder on one side loses (or
+   * gains) the verb only when it does not hold it on the other side: the
+   * lists name grants, so a group no rule names at the destination may still
+   * read there through `everyone`, and one a rule denies there may not.
+   * Writes nothing and moves nothing.
+   */
+  prospectiveHolderChanges(
+    workspaceId: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<HolderChanges>;
+
   /**
    * The CALLER'S OWN `{ read, write, download, owner }` at `toPath` as they
    * will be once `fromPath` has been moved (`sourceRemains: false`, the

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

@@ -22,6 +22,8 @@ import type {
   GrantSources,
   PathHolders,
   PathVerbs,
+  HolderChange,
+  HolderChanges,
   ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.js';
@@ -1354,6 +1356,70 @@ function eligibleHoldersResolved(
   return { principals, roles, users };
 }
 
+/** One side of a move: the access model, the path, and the rules the file carries there. */
+type MoveSide = { model: AccessModel; path: string; own: OwnEntries | null };
+
+/** The key set behind one entry of an eligible-holders list, read back from its name and kind. */
+function keysOfHolder(model: AccessModel, holder: ResolvedPrincipal): ReadonlySet<string> {
+  for (const [canonical, record] of model.roles.byCanonical) {
+    if (record.kind === holder.kind && record.displayName === holder.name) return principalKeysOfToken(model, canonical);
+  }
+  return principalKeysOfToken(model, canonicalRoleName(holder.name));
+}
+
+/**
+ * Who loses and who gains `verb` between the two sides of a move. The
+ * candidates are every principal and person a rule on either side names for
+ * the verb, as a grant or as a denial, and every holder either side lists;
+ * each is put to both sides' resolvers as the gates would put it. The holder
+ * lists alone are not enough: they name grants, so they miss a group still
+ * covered by `everyone`, and they cannot show someone whose only access was
+ * `everyone` and whom a rule on the far side denies by name.
+ */
+function holderChangesFor(verb: 'read' | 'write', here: MoveSide, there: MoveSide): HolderChanges {
+  const collectives = new Map<string, { holder: ResolvedPrincipal; keys: ReadonlySet<string> }>();
+  const people = new Set<string>();
+  const addCollective = (holder: ResolvedPrincipal, keys: ReadonlySet<string>) => {
+    const id = `${holder.kind}\0${holder.name.toLowerCase()}`;
+    if (!collectives.has(id)) collectives.set(id, { holder, keys });
+  };
+  for (const side of [here, there]) {
+    const held = eligibleHoldersResolved(side.model, verb, side.path, side.own);
+    for (const holder of held.principals) addCollective(holder, keysOfHolder(side.model, holder));
+    for (const user of held.users) people.add(user.email);
+    const { byRole, byEmail } = resolveAtPath(side.model, verb, side.path, side.own);
+    for (const token of byRole.keys()) {
+      const record = side.model.roles.byCanonical.get(token);
+      addCollective(
+        { name: record ? record.displayName : token, kind: record?.kind ?? 'role' },
+        principalKeysOfToken(side.model, token),
+      );
+    }
+    for (const email of byEmail.keys()) people.add(email);
+  }
+  const lose: HolderChange[] = [];
+  const gain: HolderChange[] = [];
+  const record = (had: boolean, has: boolean, change: HolderChange) => {
+    if (had && !has) lose.push(change);
+    if (!had && has) gain.push(change);
+  };
+  for (const { holder, keys } of collectives.values()) {
+    record(
+      hasPermissionForKeys(here.model, verb, keys, here.path, here.own),
+      hasPermissionForKeys(there.model, verb, keys, there.path, there.own),
+      { kind: holder.kind, name: holder.name, verb },
+    );
+  }
+  for (const email of [...people].sort()) {
+    record(
+      hasPermissionResolved(here.model, verb, email, here.path, here.own),
+      hasPermissionResolved(there.model, verb, email, there.path, there.own),
+      { kind: 'person', name: email, email, verb },
+    );
+  }
+  return { lose, gain };
+}
+
 /**
  * Every individual the model names: `roles.yaml` members, emails named inline
  * at this path's scope, and the deployment owner (bound by every rule that
@@ -1928,6 +1994,32 @@ export class AccessControlService implements IAccessControl {
     };
   }
 
+  /** Who loses and who gains `read` or `write` in a move (see the interface). */
+  async prospectiveHolderChanges(
+    workspaceId: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<HolderChanges> {
+    const model = await this.loadModel(workspaceId);
+    const repoDir = await this.repoDir(workspaceId);
+    const { isFolder, ownHere, ownThere, landing } =
+      await this.relocationSubject(repoDir, fromPath, toPath);
+    const here: MoveSide = { model, path: fromPath, own: ownHere };
+    const there: MoveSide = {
+      model: withRelocatedAccessFiles(model, fromPath, toPath, { sourceRemains: false, sourceIsFolder: isFolder, landing }),
+      path: toPath,
+      own: ownThere,
+    };
+    const lose: HolderChange[] = [];
+    const gain: HolderChange[] = [];
+    for (const verb of ['read', 'write'] as const) {
+      const changes = holderChangesFor(verb, here, there);
+      lose.push(...changes.lose);
+      gain.push(...changes.gain);
+    }
+    return { lose, gain };
+  }
+
   /**
    * The caller's own verbs at `toPath` as they will be once `fromPath` has
    * been moved or copied there (see the interface).

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

@@ -414,9 +414,20 @@ export function createAccessRoutes(
    * nothing is moved.
    *
    * Gated like the sibling `overrides` route rather than the permissive
-   * `GET /access`: the caller must resolve read on the thing being moved. The
-   * lists name people, and someone who cannot see it has no business
-   * learning who can.
+   * `GET /access`: the caller must resolve read on the thing being moved AND
+   * on the destination folder. The lists name people, and someone who cannot
+   * see a thing has no business learning who can; the `after` lists and the
+   * `changes` are the destination folder's rules read back (whom it grants,
+   * whom it denies by name), so a folder the caller may not open tells them
+   * nothing either.
+   *
+   * `changes` is who loses and who gains `read` or `write` in the move, as the
+   * resolver judges each candidate on both sides
+   * (`prospectiveHolderChanges`) — the one answer the move dialog and the
+   * agent's `move_file` both show. The two lists are not that answer: they
+   * name grants, so a writer leaving a folder everyone reads shows as losing
+   * `read` it keeps, and a person the destination denies by name is on
+   * neither list.
    */
   router.get('/workspace/:id/access/prospective', async (req, res) => {
     const user = await requireUser(req, res);
@@ -445,13 +456,21 @@ export function createAccessRoutes(
         res.status(403).json({ error: 'You do not have access to this file.' });
         return;
       }
+      if (!(await accessControl.canRead(req.params.id, user.email, toDir))) {
+        res.status(403).json({ error: 'You do not have access to this folder.' });
+        return;
+      }
 
       const name = from.slice(from.lastIndexOf('/') + 1);
       const to = toDir ? `${toDir}/${name}` : name;
-      const { before, after } = await accessControl.prospectiveHolders(req.params.id, from, to);
+      const [{ before, after }, changes] = await Promise.all([
+        accessControl.prospectiveHolders(req.params.id, from, to),
+        accessControl.prospectiveHolderChanges(req.params.id, from, to),
+      ]);
       res.json({
         before: { read: holderPrincipals(before.read), write: holderPrincipals(before.write) },
         after: { read: holderPrincipals(after.read), write: holderPrincipals(after.write) },
+        changes,
       });
     } catch (err) {
       const { status, body } = toHttpError(err);

package/src/modules/access/index.ts

@@ -5,7 +5,7 @@
  */
 export type { IAccessControl } from './access-control.interface.js';
 // Reached by other modules; exported here so they stop importing the files.
-export type { AccessDecisionSource, AccessTargetKind } from './access-control.interface.js';
+export type { AccessDecisionSource, AccessTargetKind, HolderChange, HolderChanges } from './access-control.interface.js';
 export { accessMdPathForFolder, fileCarriesAccessRules, governingFolderOf } from './access-mutation.service.js';
 export type { AccessMutationService, IAccessMutation, TargetKind } from './access-mutation.service.js';
 export { folderTarget, rulesFileFor } from './access-requests.contract.js';

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

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