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

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

@@ -263,6 +263,19 @@ export interface IAccessControl {
     relativePath: string,
   ): Promise<boolean>;
 
+  /**
+   * Batched `canDownload` — one config load per call, the same resolution
+   * as the single form, each path's own frontmatter `download:` rules
+   * included. A folder download judges every file it would pack through
+   * this, so a folder of a thousand files costs one model load, not a
+   * thousand.
+   */
+  canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>>;
+
   /**
    * True iff `userEmail` is an `owner` of `relativePath` per the current
    * access tree, resolved from the `owner:` lists alone (the `write` /
@@ -631,6 +644,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

@@ -1581,6 +1581,22 @@ export class AccessControlService implements IAccessControl {
     return hasPermissionResolved(model, 'download', userEmail, relativePath, own);
   }
 
+  async canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>> {
+    const model = await this.loadModel(workspaceId);
+    const repoDir = await this.repoDir(workspaceId);
+    // Parallel own-entries reads, memoized — same shape as `canWriteBatch`.
+    const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
+    const result = new Map<string, boolean>();
+    relativePaths.forEach((p, i) => {
+      result.set(p, hasPermissionResolved(model, 'download', userEmail, p, owns[i]));
+    });
+    return result;
+  }
+
   async canOwnerBatch(
     workspaceId: string,
     userEmail: string,
@@ -2103,6 +2119,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,

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

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

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

@@ -0,0 +1,386 @@
+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 {
+  CORE_SECTION_IDS,
+  PLATFORM_GUIDE_SEPARATOR,
+  WORKING_WITH_FILES_SECTION_ID,
+  agentGuideSections,
+  composeAgentGuide,
+  coreAgentGuideSections,
+  isAgentGuidePath,
+  isManagedGuide,
+  joinGuideSections,
+  withPlatformGuideAppended,
+  type AgentGuideSection,
+} from '../agent-guide.js';
+
+/**
+ * The guide is text the code owns, composed from sections when an agent asks
+ * for it. What is pinned here: that every section is there and in order, that
+ * the layout's names are rendered into it, that a distribution's hook shapes
+ * it, and what the guide says on the points agents have actually got wrong.
+ */
+
+/** The section of `guide` whose heading line starts with `heading`, up to the next heading of the same or a higher level. */
+function section(guide: string, heading: string): string {
+  const lines = guide.split('\n');
+  const at = lines.findIndex((line) => line.startsWith(heading));
+  expect(at, `the guide has no "${heading}" section`).toBeGreaterThan(-1);
+  const level = /^#+/.exec(heading)![0].length;
+  const body: string[] = [];
+  for (const line of lines.slice(at + 1)) {
+    if (new RegExp(`^#{1,${level}} `).test(line)) break;
+    body.push(line);
+  }
+  return body.join('\n');
+}
+
+describe('the guide is composed from the platform\'s sections', () => {
+  it('carries every core section, in order, the shared rules computed in their place', async () => {
+    const sections = await coreAgentGuideSections(DEFAULT_KB_LAYOUT);
+    expect(sections.map((s) => s.id)).toEqual(CORE_SECTION_IDS);
+    const rules = sections.find((s) => s.id === WORKING_WITH_FILES_SECTION_ID)!;
+    expect(rules.body).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(rules.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);
+    }
+    // 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.
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT);
+    expect(guide.endsWith('\n')).toBe(true);
+    expect(guide.endsWith('\n\n')).toBe(false);
+  });
+
+  it('renders the deployment\'s own root names and leaves no placeholder behind', async () => {
+    const guide = await composeAgentGuide({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    expect(guide).toContain('Extensions/<Plugin>/plugin.json');
+    expect(guide).toContain('`Docs/`');
+    expect(guide).toContain('`Abilities/`');
+    expect(guide).not.toContain('{{');
+    expect(guide).not.toContain('KnowledgeBase/');
+    // The shared rules are rendered once, by the code that builds them, and
+    // never passed through the renderer again: a folder literally named like a
+    // placeholder comes out as the folder it is.
+    const odd = await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' });
+    expect(odd).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' }));
+  });
+
+  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');
+    // 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);
+    // One name on every deployment: a name saved for the written guide changes nothing.
+    const stale = await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    expect(stale).not.toContain('HEXIS.md');
+    expect(stale).toBe(await composeAgentGuide(DEFAULT_KB_LAYOUT));
+    // And points at the preamble first, before the platform mechanics.
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT);
+    expect(guide.indexOf('mcp-description.md')).toBeLessThan(guide.indexOf('## Directory Structure'));
+    // One line ending throughout, whatever the checkout wrote the files with.
+    expect(guide).not.toContain('\r');
+  });
+
+  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 === '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));
+    // A heading closed with its own run of `#` is titled without it, and a
+    // section that opens with no heading is titled by its id.
+    const added = await agentGuideSections(DEFAULT_KB_LAYOUT, (all) => [
+      ...all,
+      { id: 'custom', body: '## Custom ##\n\nX.\n' },
+      { id: 'bare', body: 'No heading here.\n' },
+    ]);
+    expect(added.find((s) => s.id === 'custom')!.title).toBe('Custom');
+    expect(added.find((s) => s.id === 'bare')!.title).toBe('bare');
+  });
+
+  /**
+   * A distribution's hook sees the sections and returns the sections. The
+   * three things it can do — append, replace by id, drop — each with its
+   * placeholders rendered like core's own, and the computed section left as
+   * it was built.
+   */
+  it('lets a distribution append, replace and drop sections by id, rendering its text like core\'s', async () => {
+    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)),
+      { 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(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.
+    const seen: string[] = [];
+    await composeAgentGuide({ knowledgeBaseDir: ' Docs ', skillsDir: 'Skills', pluginsDir: 'Plugins' }, async (sections, layout) => {
+      seen.push(layout.knowledgeBaseDir, layout.agentsFile);
+      return sections;
+    });
+    expect(seen).toEqual(['Docs', 'AGENTS.md']);
+  });
+
+  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)),
+    ).rejects.toThrow(/dropped the "working-with-files" section/);
+    // Handing it back with nothing in it is the same loss: judged on the
+    // text that would be served, so whitespace counts as nothing.
+    for (const body of ['', '  \n\n']) {
+      await expect(
+        composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+          sections.map((s) => (s.id === WORKING_WITH_FILES_SECTION_ID ? { id: s.id, body } : s)),
+        ),
+      ).rejects.toThrow(/emptied the "working-with-files" section/);
+    }
+    // The id twice, one empty and one with the rules: judged over every
+    // section under the id, so the one with text satisfies it.
+    const twice = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => [
+      { id: WORKING_WITH_FILES_SECTION_ID, body: '' },
+      ...sections,
+    ]);
+    expect(twice).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    // Replacing it under the same id is the hook's right.
+    const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === WORKING_WITH_FILES_SECTION_ID ? { id: s.id, body: '## Working with files\n\nOurs.\n' } : s)),
+    );
+    expect(section(replaced, '## Working with files')).toContain('Ours.');
+  });
+
+  it('names the checkout folder this deployment uses, so the paths it shows are the paths the tools take', async () => {
+    const guide = await composeAgentGuide(DEFAULT_KB_LAYOUT, undefined, { kbDirName: 'repo' });
+    expect(guide).toContain('repository as the `repo/` folder');
+    expect(guide).toContain('`repo/KnowledgeBase/Foo.md`');
+    expect(guide).not.toContain('knowledge-base/');
+    expect(guide).not.toContain('{{kbDirName}}');
+    // Core's own default when none is given.
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain('`knowledge-base/KnowledgeBase/Foo.md`');
+  });
+
+  it('puts the knowledge base\'s own file first, then a separator, then the guide — and nothing before the guide when the file is empty', () => {
+    const joined = withPlatformGuideAppended('# Acme\r\n\r\nWrite tickets in the present tense.\r\n\r\n', 'THE GUIDE\n');
+    expect(joined).toBe(`# Acme\n\nWrite tickets in the present tense.\n\n${PLATFORM_GUIDE_SEPARATOR}\n\nTHE GUIDE\n`);
+    expect(PLATFORM_GUIDE_SEPARATOR.startsWith('---\n')).toBe(true);
+    // A file with nothing in it has nothing to put first.
+    expect(withPlatformGuideAppended('', 'THE GUIDE\n')).toBe('THE GUIDE\n');
+    expect(withPlatformGuideAppended('\n\n', 'THE GUIDE\n')).toBe('THE GUIDE\n');
+    // Their whitespace is markdown and stays: indentation is code, two
+    // trailing spaces are a hard break.
+    expect(withPlatformGuideAppended('    code\nline  \nnext\n', 'THE GUIDE\n')).toBe(
+      `    code\nline  \nnext\n\n${PLATFORM_GUIDE_SEPARATOR}\n\nTHE GUIDE\n`,
+    );
+  });
+
+  it('answers at AGENTS.md in the repository root, and nowhere else', () => {
+    expect(isAgentGuidePath('AGENTS.md')).toBe(true);
+    expect(isAgentGuidePath('/AGENTS.md')).toBe(true);
+    expect(isAgentGuidePath('Handbook/AGENTS.md')).toBe(false);
+    expect(isAgentGuidePath('agents.md')).toBe(false);
+    expect(isAgentGuidePath('HEXIS.md')).toBe(false);
+    expect(isAgentGuidePath('')).toBe(false);
+  });
+
+  it('recognises a copy an earlier release wrote to disk by its header line, and nothing else', () => {
+    // The header as every release wrote it: a blockquote under the title.
+    expect(isManagedGuide('# Knowledge base\n\n> **This file is managed by the platform.** It lives at…\n')).toBe(true);
+    expect(isManagedGuide('# Company Knowledge graph\n\nThis is a git-backed knowledge graph.\n\n> **This file is managed by the platform.** Every server restart\n> replaces it.\n')).toBe(true);
+    expect(isManagedGuide('# Acme conventions\n\nThis file is managed by us.\n')).toBe(false);
+    // The organisation's own note that QUOTES the platform's sentence in its
+    // body is theirs: the sentence is not in a header blockquote near the top.
+    expect(isManagedGuide('# On the old guide\n\nThe platform used to write a file that opened with **This file is managed by the platform.** and refreshed it.\n')).toBe(false);
+    const deep = `# Notes\n${'\n'.repeat(20)}> **This file is managed by the platform.** (quoted from the old guide)\n`;
+    expect(isManagedGuide(deep)).toBe(false);
+  });
+});
+
+/**
+ * What the guide says on the points agents have got wrong. Pinned on the
+ * served text, so a section that is dropped or rewritten fails here rather
+ * than in a deployment.
+ */
+describe('what the guide tells an agent', () => {
+  /**
+   * The placement rule. A tester's agent filed a ticket into a plugin folder
+   * and explained itself: it had found no convention saying where tickets go,
+   * and Plugins was where it already held write rights.
+   */
+  it('says where a new file goes, named for the deployment\'s roots', async () => {
+    const guide = await composeAgentGuide({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    const placement = section(guide, '## Where a new file goes');
+    expect(placement).toContain('`Docs/`');
+    expect(placement).toContain('`Abilities/`');
+    expect(placement).toContain('Extensions/<Plugin>/skills/<skill>/SKILL.md');
+    expect(placement).toContain('Extensions/<Plugin>/software.bevel.hexis/tools/');
+    for (const kind of ['notes', 'reports', 'tickets', 'mcp.json', 'plugin.json']) {
+      expect(placement, kind).toContain(kind);
+    }
+    expect(placement).toMatch(/never holds a document/);
+    expect(placement).toMatch(/\bask\b/);
+  });
+
+  /**
+   * The personal plugin, where the placement rule was being read backwards.
+   * Nothing under the plugins root is in the knowledge graph, and a personal
+   * plugin is readable only by its owner — so a note filed there is never found
+   * as knowledge again, by anyone. Agents asked to "save this for me" were
+   * taking "a personal space" as the place to put it.
+   */
+  it('says a personal plugin holds only skills and tools, and what to do when a user wants a note private', async () => {
+    const guide = await composeAgentGuide({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    const placement = section(guide, '## Where a new file goes').replace(/\s+/g, ' ');
+    expect(placement).toContain("A personal plugin holds only its owner's skills and tools");
+    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('never a note or any other document');
+    // A private request gets a question and the restrictable folder, in the
+    // deployment's own root name.
+    expect(placement).toContain('ask where under `Docs/` it should go');
+    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');
+    // Nothing tells the agent to move or flag documents already filed there.
+    expect(placement).not.toMatch(/\bmove (them|it|any)\b/);
+  });
+
+  /**
+   * Every agent-facing mention of the folder calls it the "personal plugin" —
+   * the name the app itself shows. The three phrases the guide used instead are
+   * what an agent matched "keep this private" against, so they are pinned out
+   * of the WHOLE guide rather than out of one section.
+   */
+  it('calls the folder the "personal plugin" everywhere, and no longer a "space"', async () => {
+    for (const layout of [DEFAULT_KB_LAYOUT, { knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' }]) {
+      const guide = await composeAgentGuide(layout);
+      for (const retired of ['personal space', 'private space', 'own space']) {
+        expect(guide, retired).not.toContain(retired);
+      }
+      const plugins = 'pluginsDir' in layout ? layout.pluginsDir : DEFAULT_KB_LAYOUT.pluginsDir;
+      // 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("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`,
+      );
+    }
+  });
+
+  it('says that roles are pre-set and a "new role" is usually a group', async () => {
+    const prose = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### Roles are pre-set').replace(/\s+/g, ' ');
+    expect(prose).toContain('A role in `roles.yaml` is an app role');
+    expect(prose).toContain('**Agents never create roles.**');
+    expect(prose).toContain('**Is it really a group?**');
+    expect(prose).toContain('**What to do instead.**');
+    expect(prose).toContain('add people to existing roles, and use a GROUP for a task- or team-scoped set of people');
+  });
+
+  it('describes delete_branch where it says what an agent does with branches', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### An agent proposes and syncs; a person merges');
+    const prose = text.replace(/\s+/g, ' ');
+    expect(prose).toContain('`delete_branch`');
+    expect(prose).toContain('Only its author');
+    expect(prose).toContain('`dryRun: true`');
+    expect(prose).toContain('`discardUnmerged: true`');
+    expect(prose).toContain('that proposes nothing is closed by the delete');
+    expect(prose).toContain('its author can withdraw it, or an Admin can decline it, in the app');
+    expect(prose).toContain('`lastCommit`');
+  });
+
+  it('documents giving a role to a group, with an example that parses as a valid roles.yaml', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### Giving a role to a group');
+    const prose = text.replace(/\s+/g, ' ');
+    expect(prose).toContain('`- group:<Name>`');
+    expect(prose).toContain('case- and whitespace-insensitively against the active group source');
+    expect(prose).toContain('validation error');
+    expect(prose).toContain("removes the role's contribution for everyone in the group");
+    expect(prose).toContain('`deny role/Reviewer`');
+    expect(prose).toContain('A group under `Admin` makes every member a full admin');
+    // A change request cannot carry a roles.yaml edit, so the guide says who
+    // changes roles and where, and never walks an agent through drafting one.
+    expect(prose).toContain('Only an Admin changes `roles.yaml`');
+    expect(prose).toContain('Do not propose one');
+    for (const tool of ['create_branch', 'commit_change', 'open_change_request']) {
+      expect(prose).not.toContain(`\`${tool}\``);
+    }
+    const example = /```yaml\n([\s\S]*?)```/.exec(text)?.[1] ?? '';
+    expect(example).toContain('- group:Platform Team');
+    const parsed = parseRolesYaml(example);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const groups = new Map([['platform team', { displayName: 'Platform Team', emails: new Set(['pat@example.com']) }]]);
+    expect(mergeGroupsIntoRoles(parsed.index, groups, 'groups.yaml')).toEqual([]);
+    expect(parsed.index.byEmail.get('pat@example.com')?.has('reviewer')).toBe(true);
+    expect(parsed.index.byEmail.get('pat@example.com')?.has('role/admin')).toBe(false);
+  });
+});
+
+/**
+ * The HTML views section: what an agent writing a live page is told about the
+ * frame. Its link rules are pinned against the renderer by core-frontend's
+ * `htmlViewsGuide.test.ts`, which reads the same file; what is pinned here is
+ * that it is served like every other section and that a distribution may
+ * reshape it.
+ */
+describe('the HTML views section', () => {
+  it('is served on its own, inside the whole guide, titled "HTML views"', async () => {
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    const html = sections.find((s) => s.id === 'html-views')!;
+    expect(html.title).toBe('HTML views');
+    expect(html.body).not.toContain('{{');
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(html.body);
+    // After the tool manuals, before the conventions.
+    const ids = sections.map((s) => s.id);
+    expect(ids.indexOf('html-views')).toBe(ids.indexOf('tool-manuals') + 1);
+  });
+
+  it('describes the frame, the two members core puts on window.bevel, and a fragment that scrolls the page', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    expect(text).toContain('**No network.**');
+    expect(text).toContain('**Inline scripts and styles only.**');
+    expect(text).toContain('**Scripts run as ES modules**');
+    expect(text).toContain('**No browser storage.**');
+    expect(text).toContain('**No host navigation.**');
+    expect(text).toContain('`window.bevel.openNode(href)`');
+    expect(text).toContain('`window.bevel.navigate(href)`');
+    expect(text).toContain('A distribution may add data members of its own to `window.bevel`');
+    expect(text).toContain('**A bare fragment scrolls the page.**');
+    // Rendered for the deployment's layout like every other section.
+    const docs = section(await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }), '## HTML views');
+    expect(docs).toContain('/workspace/main/Docs/Alice.md');
+  });
+
+  it('lets a distribution replace the section or drop it', async () => {
+    const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === 'html-views' ? { id: s.id, body: '## HTML views\n\nOurs, graph-aware.\n' } : s)),
+    );
+    expect(section(replaced, '## HTML views').trim()).toBe('Ours, graph-aware.');
+    const dropped = await agentGuideSections(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== 'html-views'));
+    expect(dropped.map((s) => s.id)).not.toContain('html-views');
+    expect(joinGuideSections(dropped)).not.toContain('## HTML views');
+  });
+});