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

package/src/modules/access/synced-groups-writer.ts

@@ -72,7 +72,7 @@ export interface SyncedGroupsSource {
 
 // Name safety is the SHARED predicate in `group-files.ts` (`unsafeNameReason`)
 // — the same rules the manual group editor asserts, including the reserved
-// `role/` prefix. Here the name arrives from the IdP, so an unsafe group is
+// `role/` and `group/` prefixes. Here the name arrives from the IdP, so an unsafe group is
 // SKIPPED with a warning instead of erroring (fail-closed: an unrepresentable
 // group grants nothing).
 

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -6,8 +6,44 @@ import {
   accessFrontmatterExtensionList,
   parseOwnAccessEntries,
   parseRolesYaml,
+  parseAccessEntry,
+  mergeGroupsIntoRoles,
 } from '../access-grammar.js';
-import { parseGroupsFile } from '../group-files.js';
+import { parseGroupsFile, unsafeNameReason } from '../group-files.js';
+
+describe('principal spellings — a bare name is the role, group/<Name> the group', () => {
+  it('parses group/<Name> into the canonical group token, spacing normalised', () => {
+    const r = parseAccessEntry('group/ Product  Team');
+    expect(r).toEqual({ ok: true, entry: { kind: 'role', role: 'group/product team', displayRole: 'group/ Product  Team', deny: false } });
+    const d = parseAccessEntry('deny group/Admin');
+    expect(d.ok && d.entry.kind === 'role' && d.entry.role).toBe('group/admin');
+    expect(parseAccessEntry('group/').ok).toBe(false);
+  });
+
+  it('reserves the group/ prefix for roles and groups alike', () => {
+    const roles = parseRolesYaml('roles:\n  Admin:\n    - a@x.io\n  group/Ops:\n    - b@x.io\n');
+    expect(roles.ok).toBe(false);
+    if (!roles.ok) expect(roles.errors.join(' ')).toMatch(/reserved 'group\/' prefix/);
+    expect(unsafeNameReason('group/Ops')).toMatch(/group\//);
+  });
+
+  it('merging keeps the bare key for the role and registers group/ for every group', () => {
+    const parsed = parseRolesYaml('roles:\n  Admin:\n    - admin@x.io\n');
+    if (!parsed.ok) throw new Error('roles');
+    const groups = parseGroupsFile('groups:\n  Admin:\n    - mallory@x.io\n  Sales:\n    - sam@x.io\n', 'groups.yaml');
+    if (!groups.ok) throw new Error('groups');
+    const warnings = mergeGroupsIntoRoles(parsed.index, groups.groups, 'groups.yaml');
+    const idx = parsed.index.byCanonical;
+    expect(idx.get('admin')?.kind).toBe('role');
+    expect(idx.get('role/admin')).toBe(idx.get('admin'));
+    expect(idx.get('group/admin')?.kind).toBe('group');
+    expect(idx.get('sales')?.kind).toBe('group');
+    expect(idx.get('group/sales')).toBe(idx.get('sales'));
+    // The group's member holds only the group's keys, never the role's.
+    expect([...(parsed.index.byEmail.get('mallory@x.io') ?? [])]).toEqual(['group/admin']);
+    expect(warnings.join(' ')).toMatch(/resolves to the ROLE; use 'group\/admin'/);
+  });
+});
 
 describe('parseYamlSubset — inline empty collections', () => {
   it('reads `key: []` as an empty list, not the scalar "[]"', () => {
@@ -103,6 +139,7 @@ describe('the access-frontmatter extension set', () => {
     expect(accessFrontmatterExtensionList()).toHaveLength(after);
     expect(accessFrontmatterExtensionList()).toContain('.md');
     expect(accessFrontmatterExtensionList()).toContain('.tool');
+    expect(accessFrontmatterExtensionList()).not.toContain('.agent');
   });
 
   it('throws on a malformed extension rather than skipping it', () => {

package/src/modules/access-model/__tests__/access-splice.test.ts

@@ -302,12 +302,13 @@ describe('round-trip — every granted entry parses back', () => {
   });
 });
 
-describe('token-kind family — exact-token grants, shadow-aware revokes', () => {
-  // One name, two spellings, two possible principals: the bare token is the
-  // GROUP's whenever a group shadows the name (group-first precedence), the
-  // `role/` token is always the ROLE's. Grants must be exact-token idempotent;
-  // revokes are alias-tolerant ONLY when unshadowed (the caller passes
-  // tokenMatch: 'exact' when a group owns the bare name).
+describe('token-kind family — exact-token grants, kind-aware revokes', () => {
+  // One name, three spellings, two possible principals: `role/` is always the
+  // ROLE's, `group/` always the GROUP's, and the bare token is the role's when
+  // one exists, else the group's. Grants must be exact-token idempotent;
+  // revokes are alias-tolerant (explicit + bare, never the other kind's
+  // explicit spelling) only when the bare name is the principal's — the
+  // caller passes tokenMatch: 'exact' otherwise.
   const SHARED = `---
 write:
   - role/Sales
@@ -360,10 +361,51 @@ write:
     expect(lines).not.toContain('  - Sales');
   });
 
-  it("REVOKE unshadowed bare principal (group since vanished): 'name' matching strips both spellings", () => {
+  it("REVOKE bare principal: 'name' matching strips both role spellings", () => {
     const r = spliceRevoke(SHARED, 'write', { kind: 'role', role: 'Sales' });
     expect(r.changed).toBe(true);
-    expect(r.text).not.toContain('Sales'); // bare token falls back to the role — same principal
+    expect(r.text).not.toContain('Sales'); // the bare token is the role — same principal
+  });
+
+  const ALL = `---
+write:
+  - role/Sales
+  - Sales
+  - group/Sales
+  - Admin
+---
+`;
+
+  it('GRANT is exact-token: a group/<Name> grant goes through beside the bare and role/ spellings', () => {
+    const md = '---\nwrite:\n  - role/Sales\n  - Sales\n---\n';
+    const r = spliceGrant(md, 'write', { kind: 'role', role: 'group/Sales' });
+    expect(r.changed).toBe(true);
+    expect(r.text.split('\n')).toContain('  - group/Sales');
+    expect(spliceGrant(ALL, 'write', { kind: 'role', role: 'group/Sales' }).changed).toBe(false);
+  });
+
+  it("REVOKE 'name' never crosses kinds: the role's revoke keeps group/, the group's keeps role/", () => {
+    const asRole = spliceRevoke(ALL, 'write', { kind: 'role', role: 'role/Sales' });
+    expect(asRole.text.split('\n')).toEqual(['---', 'write:', '  - group/Sales', '  - Admin', '---', '']);
+
+    // The service asks 'name' for a GROUP only while no role shares the name
+    // (with one, as in ALL, it picks 'exact' — the last test below), so the
+    // group's case is a file where the bare token can only be the group.
+    const GROUP_ONLY = '---\nwrite:\n  - Sales\n  - group/Sales\n  - Admin\n---\n';
+    const asGroup = spliceRevoke(GROUP_ONLY, 'write', { kind: 'role', role: 'group/Sales' });
+    expect(asGroup.text.split('\n')).toEqual(['---', 'write:', '  - Admin', '---', '']);
+  });
+
+  it('REVOKE matches a spaced `group/ <Name>` request against the parsed `group/<name>` entry', () => {
+    const r = spliceRevoke(ALL, 'write', { kind: 'role', role: 'group/ Sales' }, { tokenMatch: 'exact' });
+    expect(r.text.split('\n')).toEqual(['---', 'write:', '  - role/Sales', '  - Sales', '  - Admin', '---', '']);
+    const md = '---\nwrite:\n  - group/ Sales\n---\n';
+    expect(spliceRevoke(md, 'write', { kind: 'role', role: 'group/Sales' }).changed).toBe(true);
+  });
+
+  it("REVOKE 'exact' of group/<Name> strips only that spelling", () => {
+    const r = spliceRevoke(ALL, 'write', { kind: 'role', role: 'group/Sales' }, { tokenMatch: 'exact' });
+    expect(r.text.split('\n')).toEqual(['---', 'write:', '  - role/Sales', '  - Sales', '  - Admin', '---', '']);
   });
 });
 

package/src/modules/access-model/access-grammar.ts

@@ -92,14 +92,47 @@ export const DENY_PREFIX = 'deny ';
 export const GROUP_REF_PREFIX = 'group:';
 /**
  * Explicit ROLE token prefix in access.md entries: `role/<Name>` resolves to
- * the roles.yaml role only, never a group. A BARE name resolves GROUP-FIRST
- * and falls back to the role — so `role/` is the escape hatch when a group
- * shares the role's name. The prefix is reserved in the group name-safety
- * rules (a group may never be named `role/...`), and every role is also
- * registered in the principal index under its `role/<canonical>` alias.
+ * the roles.yaml role only, never a group. A BARE name resolves ROLE-FIRST
+ * and falls back to the group, so a group that shares a role's name is
+ * reached only as `group/<Name>` (see `GROUP_TOKEN_PREFIX`) — a group named
+ * `Admin` never takes over the grants written for the Admin role. The prefix
+ * is reserved in the group name-safety rules (a group may never be named
+ * `role/...`), and every role is also registered in the principal index under
+ * its `role/<canonical>` alias.
  */
 export const ROLE_TOKEN_PREFIX = 'role/';
 
+/**
+ * Explicit GROUP token prefix in access.md entries: `group/<Name>` resolves
+ * to the active source's group only, never a role. Every group is registered
+ * in the principal index under its `group/<canonical>` alias; the bare name
+ * reaches the group only while no role of that name exists. The share dialog
+ * and the access API always write groups this way. Reserved in the group
+ * name-safety rules and in roles.yaml like `role/`.
+ */
+export const GROUP_TOKEN_PREFIX = 'group/';
+
+/**
+ * A canonical role-shaped token split into its explicit kind prefix and its
+ * bare name: `role/admin` → `{ prefix: 'role', name: 'admin' }`, `group/admin`
+ * → `{ prefix: 'group', name: 'admin' }`, anything else (a bare name, a
+ * plugin token, `everyone`) → `{ prefix: null, name: <token> }`. A prefixed
+ * name is canonicalised again, so `group/ admin` splits like `group/admin`
+ * (as `parseAccessEntry` reads it).
+ */
+export function splitPrincipalToken(canonical: string): {
+  prefix: 'role' | 'group' | null;
+  name: string;
+} {
+  if (canonical.startsWith(ROLE_TOKEN_PREFIX)) {
+    return { prefix: 'role', name: canonicalRoleName(canonical.slice(ROLE_TOKEN_PREFIX.length)) };
+  }
+  if (canonical.startsWith(GROUP_TOKEN_PREFIX)) {
+    return { prefix: 'group', name: canonicalRoleName(canonical.slice(GROUP_TOKEN_PREFIX.length)) };
+  }
+  return { prefix: null, name: canonical };
+}
+
 /**
  * PLUGIN-principal token prefix in access.md entries: `plugin/<Name>/<verb>`
  * names everyone who holds `<verb>` on the plugin folder `Plugins/<Name>` —
@@ -585,6 +618,11 @@ export function parseAccessEntry(
     const suffix = canonicalRoleName(role.slice(ROLE_TOKEN_PREFIX.length));
     if (!suffix) return { ok: false, error: `entry '${body}' names no role after '${ROLE_TOKEN_PREFIX}'` };
     role = `${ROLE_TOKEN_PREFIX}${suffix}`;
+  } else if (role.startsWith(GROUP_TOKEN_PREFIX)) {
+    // Explicit group token, normalised the same way to `group/<canonicalName>`.
+    const suffix = canonicalRoleName(role.slice(GROUP_TOKEN_PREFIX.length));
+    if (!suffix) return { ok: false, error: `entry '${body}' names no group after '${GROUP_TOKEN_PREFIX}'` };
+    role = `${GROUP_TOKEN_PREFIX}${suffix}`;
   } else if (role.startsWith(PLUGIN_TOKEN_PREFIX)) {
     // `plugin/<Name>/<verb>`: the name is canonicalised to the plugin's
     // manifest slug, the verb must be one of the three. Anything else is a
@@ -649,6 +687,12 @@ export function parseRolesYaml(
       );
       continue;
     }
+    if (canonical.startsWith(GROUP_TOKEN_PREFIX)) {
+      errors.push(
+        `roles.yaml: role '${displayName}' starts with the reserved '${GROUP_TOKEN_PREFIX}' prefix — that spelling is the explicit group token in access entries`,
+      );
+      continue;
+    }
     // A role spelled `plugin/…` would be overwritten by the synthesised plugin
     // principal of the same key while its members kept the token — plugin
     // access for people who are not plugin members. Refused at parse time,
@@ -730,15 +774,17 @@ export function parseRolesYaml(
  *
  * Rules (the grant-grammar precedence):
  *   - Every role is ALSO registered under its explicit `role/<canonical>`
- *     alias — the token that always resolves to the role.
- *   - A BARE name resolves GROUP-FIRST: when a group's canonical name
- *     collides with a role's, the bare key resolves to the GROUP (warned);
- *     the role stays reachable via `role/<canonical>`.
+ *     alias, and every group under its explicit `group/<canonical>` alias —
+ *     the tokens that always resolve to that kind.
+ *   - A BARE name resolves ROLE-FIRST: when a group's canonical name
+ *     collides with a role's, the bare key stays the ROLE's (warned); the
+ *     group is reachable only via `group/<canonical>`. So a group named
+ *     `Admin` — whoever proposed it — never gains what `Admin` is granted.
  *   - Role `group:<Name>` refs — Admin's included — expand against the
  *     merged groups; an unknown ref contributes nothing (warned).
  *   - `byEmail` is rebuilt so each member holds exactly the tokens that
  *     resolve to a principal they belong to (bare + `role/` alias for roles,
- *     bare for groups).
+ *     `group/` alias plus the bare name when the group owns it for groups).
  */
 export function mergeGroupsIntoRoles(
   index: RolesIndex,
@@ -765,19 +811,18 @@ export function mergeGroupsIntoRoles(
     }
   }
 
-  // 2. Bare-name precedence: groups win the bare token; the role keeps its
-  //    `role/<canonical>` alias registered below.
+  // 2. Bare-name precedence: roles keep the bare token; every group gets its
+  //    `group/<canonical>` alias, and the bare key only when no role owns it.
   for (const [canonical, def] of groups) {
+    const group = { displayName: def.displayName, emails: new Set(def.emails), kind: 'group' as const };
+    index.byCanonical.set(`${GROUP_TOKEN_PREFIX}${canonical}`, group);
     if (roleRecords.has(canonical)) {
       warnings.push(
-        `${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name now resolves to the GROUP; use '${ROLE_TOKEN_PREFIX}${canonical}' to reference the role`,
+        `${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name resolves to the ROLE; use '${GROUP_TOKEN_PREFIX}${canonical}' to reference the group`,
       );
+      continue;
     }
-    index.byCanonical.set(canonical, {
-      displayName: def.displayName,
-      emails: new Set(def.emails),
-      kind: 'group',
-    });
+    index.byCanonical.set(canonical, group);
   }
 
   // 3. Explicit `role/<canonical>` alias for every role (same record — the
@@ -788,8 +833,8 @@ export function mergeGroupsIntoRoles(
   }
 
   // 4. Rebuild the email → tokens map from the final index so membership
-  //    reflects the post-precedence keys (a collided role's members no longer
-  //    hold the bare token unless the group also contains them).
+  //    reflects the post-precedence keys (a collided group's members hold
+  //    only its `group/` alias, never the role's bare token).
   index.byEmail.clear();
   for (const [key, principal] of index.byCanonical) {
     for (const email of principal.emails) {

package/src/modules/access-model/access-splice.ts

@@ -33,6 +33,7 @@ import {
   canonicalEmail,
   canonicalRoleName,
   accessMdDeclaresBodyRules,
+  splitPrincipalToken,
 } from './access-grammar.js';
 import { freshAccessMd } from './access-template.js';
 import { scanFrontmatter } from './frontmatter-lines.js';
@@ -149,15 +150,18 @@ export function validatePrincipal(p: Principal): Principal {
 /**
  * How a role-shaped principal's TOKEN is compared against a file entry:
  *
- *  - `'exact'`: the entry must carry the SAME spelling — a bare token and a
- *    `role/<name>` token are DIFFERENT principals (bare = whoever owns the
- *    bare key under group-first precedence, `role/` = the role). Grants
- *    always use this: granting the group `X` while `role/X` is present (or
- *    vice versa) must NOT be treated as already-granted, or the other
- *    principal silently never receives the grant.
- *  - `'name'`: both spellings of the name match. Revokes use this ONLY when
- *    no group shadows the bare name — then both spellings resolve to the
- *    role, and revoking the role must also remove legacy bare spellings.
+ *  - `'exact'`: the entry must carry the SAME spelling — a bare token, a
+ *    `role/<name>` token and a `group/<name>` token can be DIFFERENT
+ *    principals (bare = the role when one exists, else the group). Grants
+ *    always use this: granting `group/X` while `role/X` or a bare `X` is
+ *    present must NOT be treated as already-granted, or the group silently
+ *    never receives the grant.
+ *  - `'name'`: the principal's explicit spelling AND the bare name match —
+ *    `role/X` (or a bare `X`) matches `X` and `role/X`; `group/X` matches
+ *    `X` and `group/X`. Never across kinds: a role's revoke never touches
+ *    `group/X`, a group's never `role/X`. Revokes use this only when the
+ *    bare name is this principal's (AccessMutationService decides), so
+ *    revoking also removes the legacy bare spelling.
  */
 export type TokenMatch = 'exact' | 'name';
 
@@ -169,11 +173,14 @@ export type TokenMatch = 'exact' | 'name';
 function entryMatches(entry: ParsedEntry, p: Principal, tokenMatch: TokenMatch): boolean {
   if (p.kind === 'user') return entry.kind === 'user' && entry.email === canonicalEmail(p.email);
   if (entry.kind !== 'role') return false;
-  const canonicalPrincipal = canonicalRoleName(p.role);
-  if (tokenMatch === 'exact') return entry.role === canonicalPrincipal;
-  const strip = (token: string): string =>
-    token.startsWith('role/') ? canonicalRoleName(token.slice('role/'.length)) : token;
-  return strip(entry.role) === strip(canonicalPrincipal);
+  // Compare split, canonical halves: `group/ Product` in the request names the
+  // same principal as the `group/product` the parser reads from the file.
+  const own = splitPrincipalToken(canonicalRoleName(p.role));
+  const theirs = splitPrincipalToken(entry.role);
+  if (theirs.name !== own.name) return false;
+  if (tokenMatch === 'exact') return theirs.prefix === own.prefix;
+  // Same family only: a bare principal stands for the role, as `role/` does.
+  return theirs.prefix === null || theirs.prefix === (own.prefix ?? 'role');
 }
 
 // ---------------------------------------------------------------------------
@@ -344,10 +351,10 @@ function blockEntries(fm: string[], block: VerbBlock): { entry: ParsedEntry; lin
  * Add `principal` under `verb`. Idempotent: if an entry with the EXACT same
  * token spelling already exists with the SAME deny-ness (a grant when
  * granting, a deny when denying), returns `changed: false`. Idempotency is
- * deliberately exact-token, never name-level: a bare token and a `role/`
- * token are different principals (group-first precedence gives the bare key
- * to a same-named group), so a bare-`X` GROUP grant must go through even when
- * `role/X` is present, and vice versa. Creates the verb key (and the
+ * deliberately exact-token, never name-level: a bare token, a `role/` token
+ * and a `group/` token can be different principals (the bare key is the
+ * role's when one exists), so a `group/X` grant must go through even when a
+ * bare `X` or `role/X` is present, and vice versa. Creates the verb key (and the
  * frontmatter fence, for a fresh file) as needed. Preserves everything else
  * byte-for-byte.
  *
@@ -445,11 +452,12 @@ export function spliceGrant(
  * Preserves everything else.
  *
  * Token matching for role-shaped principals is `tokenMatch` (default `'name'`:
- * BOTH spellings — revoking the role removes legacy bare spellings too).
- * Callers pass `'exact'` when a GROUP shadows the principal's bare name: the
- * bare token then belongs to the group and the `role/` token to the role, so a
- * revoke of one must never strip the other (see AccessMutationService, which
- * derives the flag from the merged principal index).
+ * the explicit spelling and the bare one — revoking removes legacy bare
+ * spellings too). Callers pass `'exact'` when the bare name belongs to the
+ * OTHER kind (a group revoke while a same-named role owns the bare key, or a
+ * role revoke while only a group of that name exists), so a revoke of one
+ * never strips the other (see AccessMutationService, which derives the flag
+ * from the merged principal index).
  */
 export function spliceRevoke(
   text: string,

package/src/modules/access-model/group-files.ts

@@ -4,6 +4,7 @@ import {
   RESERVED_ROLE_NAMES,
   PLUGIN_TOKEN_PREFIX,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
   canonicalEmail,
   canonicalRoleName,
   parseYamlSubset,
@@ -58,6 +59,7 @@ export const SYNCED_GROUPS_YAML = 'synced-groups.yaml';
  *   \x00-\x1f  control chars / newlines break line structure outright
  *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
  *              entries — a group carrying it could never be referenced.
+ *   `group/…`  reserved likewise: the EXPLICIT group token.
  */
 export function unsafeNameReason(displayName: string): string | null {
   const trimmed = displayName.trim();
@@ -69,6 +71,9 @@ export function unsafeNameReason(displayName: string): string | null {
   if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
     return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
   }
+  if (canonicalRoleName(trimmed).startsWith(GROUP_TOKEN_PREFIX)) {
+    return `starts with the reserved '${GROUP_TOKEN_PREFIX}' prefix (the explicit group token in access entries)`;
+  }
   if (canonicalRoleName(trimmed).startsWith(PLUGIN_TOKEN_PREFIX)) {
     return `starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix (the plugin-principal token in access entries)`;
   }

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');
@@ -367,6 +421,7 @@ describe('the HTML views section', () => {
     expect(text).toContain('**No host navigation.**');
     expect(text).toContain('`window.bevel.openNode(href)`');
     expect(text).toContain('`window.bevel.navigate(href)`');
+    expect(text).toContain('`window.bevel.branch` — the branch the page is viewed on');
     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.
@@ -374,6 +429,36 @@ describe('the HTML views section', () => {
     expect(docs).toContain('/workspace/main/Docs/Alice.md');
   });
 
+  // A dashboard that painted one "Loading…" line and then swapped in the whole
+  // board read as broken on a cold load (2026-10-20). These rules are what
+  // agents write pages from; the reference page under them is run by
+  // core-frontend's `liveDataReferencePage.test.ts`.
+  it('tells page authors how a page loads live data without changing shape', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    expect(text).toContain('### Live data: a page that stays still while it loads');
+    expect(text).toContain('**Render the final page shell in the markup, before any data.**');
+    expect(text).toContain('The loading treatment — placeholder rows, `aria-busy="true"` — sits **inside** the data regions.');
+    expect(text).toContain('**Publish one consistent dataset at a time.**');
+    expect(text).toContain('Until then show no counts, no cards and no empty columns');
+    expect(text).toContain('**Refresh keeps the current board.**');
+    expect(text).toContain('**A failed read fails the whole load, visibly.**');
+    expect(text).toContain('offer a Retry button that runs the same load again');
+    expect(text).toContain('**Read in bounded parallel once the paths are known.**');
+    expect(text).toContain('**Load with `callTool`, not `callToolChain`.**');
+    expect(text).toContain("**The reads are the viewer's own.**");
+    expect(text).toContain('**Link to what the tools named by the path they answered.**');
+    expect(text).toContain('Never put the checkout folder in front of a path a tool answered: it is already there.');
+    expect(text).toContain('plain HTML and one inline script, no build step and no framework');
+    // The rule names the deployment's own checkout folder; the page links on its branch by the tool's path.
+    const docs = section(await composeAgentGuide(DEFAULT_KB_LAYOUT, undefined, { kbDirName: 'kb' }), '## HTML views');
+    expect(docs.replace(/\s+/g, ' ')).toContain('starts with the checkout folder, `kb/Data/Tickets/A.md`');
+    // Each segment of the tool's path encoded on its own, so a name carrying `#` stays a name.
+    expect(docs).toContain(
+      "link.href = '/workspace/' + encodeURIComponent(BRANCH) + '/' + ticket.path.split('/').map(encodeURIComponent).join('/');",
+    );
+    expect(docs).not.toContain('{{');
+  });
+
   it('documents window.bevel.tools: its four functions, the null check, the consent rule and requireTools with its card', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
     for (const member of [