@bevel-software/platform-core-backend 0.33.0 → 0.34.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

@@ -367,6 +367,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 +375,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 [

package/src/modules/agent-guide/agent-guide.tools.ts

@@ -102,10 +102,21 @@ export function registerAgentGuideTool(
   router.post(
     `/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
     toolAuth,
-    toolHandler(async (args) => {
+    toolHandler(async (args, ctx) => {
       const list = await sections();
       const wanted = typeof args.section === 'string' ? args.section.trim() : '';
-      if (!wanted) return { guide: joinGuideSections(list), sections: list.map((s) => ({ id: s.id, title: s.title })) };
+      // A connection made as an agent configuration is told so at the top of the
+      // whole guide: the catalog it describes is narrowed to that agent.
+      // Everything is told nothing new, so its guide is the same text.
+      const connection = ctx.connectionScope?.describe() ?? null;
+      if (!wanted) {
+        const guide = joinGuideSections(list);
+        return {
+          guide: connection ? `> ${connection}\n\n${guide}` : guide,
+          sections: list.map((s) => ({ id: s.id, title: s.title })),
+          ...(connection ? { connection } : {}),
+        };
+      }
       const one = list.find((s) => s.id === wanted);
       if (!one) {
         throw new ToolError(

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -51,6 +51,7 @@ describe('the shared file rules are one text, in two places', () => {
     expect(rules.map((r) => r.id)).toEqual([
       'agent-guide',
       'content-kinds',
+      'workspace-tmp',
       'write-mode',
       'images-in-pages',
       'escape-sequences',

package/src/modules/agent-instructions/compose.ts

@@ -90,8 +90,10 @@ export function platformInstructions(layout: KbLayout): string {
  * own cap, and the preamble under its cap plus the marker a cut appends. The
  * test is what makes it a ceiling rather than a hope: a shared rule that grew
  * past it fails before it reaches an agent.
+ *
+ * 14,400 since the shared rules' own cap rose by 400 (the `__tmp__/` ref).
  */
-export const INSTRUCTIONS_CAP = 14_000;
+export const INSTRUCTIONS_CAP = 14_400;
 
 /** The one-line marker that replaces everything past the preamble cap. */
 export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -61,8 +61,12 @@ const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
  * of every call rather than of how to write one, and why large, escape-heavy
  * and binary content goes by upload, which three write tools each said in
  * full.
+ *
+ * 7,400 since the `__tmp__/` ref: four tools take it, so what it reaches and
+ * that it is read-only is said once here rather than in each description, and
+ * the section had no room left for it.
  */
-export const SHARED_FILE_RULES_CAP = 7_000;
+export const SHARED_FILE_RULES_CAP = 7_400;
 
 /** One shared rule: how the guide heads it, and the rule itself. */
 export interface SharedFileRule {
@@ -114,6 +118,18 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         '`{ image_omitted, note }` stub instead, so read an image outside a chain when you mean to look at it. Any other ' +
         'binary file reads as a one-line description rather than raw bytes.',
     },
+    {
+      // What `__tmp__/` reaches and what it does not (see
+      // `workspace/workspace-tmp.ts`) — four tools take the ref, so it is a
+      // shared rule rather than a sentence in each description.
+      id: 'workspace-tmp',
+      heading: "Files staged in the workspace's tmp folder",
+      body:
+        "`__tmp__/<path>` names ONE file YOU staged in the branch workspace's `tmp/` folder (chat attachments land " +
+        'there; nobody else\'s staged files are reachable). read_file, file_stat, grep (`path`) and copy_file (`src`) ' +
+        'read it as a repository file; it is read-only and never listed — copy_file it to a repository path to keep ' +
+        'it. An entry stays up to seven days.',
+    },
     {
       id: 'write-mode',
       heading: 'What a write may do at a path',