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

package/src/modules/workspace/workspace.tools.ts

@@ -249,6 +249,14 @@ const int = (description: string): JsonSchema => ({ type: 'integer', description
 
 const str = (description: string): JsonSchema => ({ type: 'string', description });
 
+/**
+ * A write to the default branch is live at once, so the agent asks first. Said on the four
+ * tools behind 87 of the 91 writes there in the agent-guide benchmark (2026-10-26); `start-here`
+ * says it for the other write tools.
+ */
+const ASK_BEFORE_DEFAULT_BRANCH =
+  ' On the default branch a write is live for everyone at once: unless the person already said where, ask them first whether to write there or propose it on a draft.';
+
 /**
  * The upload route, named on every tool that takes content as a JSON string.
  *
@@ -1113,8 +1121,9 @@ export function registerWorkspaceTools(
    */
   uploads?: AgentUploadStore,
   /**
-   * The platform's agent guide (see `modules/agent-guide`), which `read_file`
-   * and `file_stat` answer at the guide's name in the repository root — after
+   * The start of the platform's agent guide and the list of its sections
+   * (`guideStartText` in `modules/agent-guide`), which `read_file` and
+   * `file_stat` answer at the guide's name in the repository root — after
    * the knowledge base's own file of that name, when it has one. Optional for
    * the harnesses that are about the file primitives; without it the two
    * tools read the disk and nothing else.
@@ -2010,13 +2019,13 @@ export function registerWorkspaceTools(
   const startSessionDef = toolDef({
     name: 'start_session',
     description:
-      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id as `sessionId` on every later KnowledgeBase tool call, inside `call_tool_chain` too. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
+      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. Pass the returned id as `sessionId` to every tool whose arguments list it, inside `call_tool_chain` too; the others refuse it. Where the deployment offers an `ask` tool, hand it the SAME id: your reads and your questions are then one conversation. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
     path: '/api/agent/tools/start_session',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
       properties: {
-        sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.'),
+        sessionId: str('The minted session id — pass it as `sessionId` to the tools that take one, and to `ask` where there is one.'),
         firstRun: str(
           `Present only while the knowledge base holds nothing but its starter guide (and a starter pack's untouched pages): what to offer the person (the guide's \`${FIRST_RUN_SECTION_ID}\` section says how).`,
         ),
@@ -2234,7 +2243,7 @@ export function registerWorkspaceTools(
       'Read a workspace file as text. Returns `{ path, content, canWrite }`. Per the shared content rule: text as ' +
       'text, documents and email as extracted text, an image as the picture, anything else as a one-line ' +
       'description. Also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: it ' +
-      'belongs to no workspace, so `branch` is ignored and no `canWrite` comes back. `offset`/`limit` slice the ' +
+      'belongs to no workspace: any existing `branch` will do, and no `canWrite` comes back. `offset`/`limit` slice the ' +
       'content (characters; bytes for a spill ref; ignored for an image): page through large files and ' +
       'spills, never read multi-MB whole. `canWrite`: may you change this file directly on the default branch. ' +
       CAN_WRITE_CLAUSE,
@@ -2243,8 +2252,8 @@ export function registerWorkspaceTools(
       properties: {
         branch: BRANCH_INPUT,
         path: str(`Path to read, under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), with or without a leading slash — a path without that prefix is placed under \`${kbDirName}/\` — or a \`__tool_chain_spill__/…\` ref from a truncated \`call_tool_chain\`, or a \`__tmp__/…\` ref to a file you staged in the workspace's tmp folder.`),
-        offset: int('Start character index (default 0).'),
-        limit: int('Max characters to return from `offset`.'),
+        offset: int('Start character index (bytes for a spill ref; default 0).'),
+        limit: int('Max characters to return from `offset` (bytes for a spill ref).'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -2919,6 +2928,7 @@ export function registerWorkspaceTools(
     description:
       'Write a workspace TEXT file. The change is committed + pushed as you. Returns `{ path, bytes, outcome }`, where `outcome` is ' +
       '`created`, `replaced` or `updated`.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3009,6 +3019,7 @@ export function registerWorkspaceTools(
       '`created` / `replaced` / `updated` for a path it wrote, or `refused` with `error` (the code) and `message` (why) for a ' +
       'path it could not. `count` is how many were written. A path it refuses — the mode said no, or the file is not text — ' +
       'does not stop the others; read `files` to see what landed.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3046,7 +3057,7 @@ export function registerWorkspaceTools(
                 enum: ['created', 'replaced', 'updated', 'refused'],
                 description: 'What happened at this path. `refused` means nothing was written there and the file is untouched.',
               },
-              error: str('Present when `outcome` is `refused`: the refusal code — `exists`, `missing` or `binary_not_writable`.'),
+              error: str('Present when `outcome` is `refused`: the refusal code, such as `exists`, `missing`, `binary_not_writable` or a code of the deployment\'s own write check.'),
               message: str('Present when `outcome` is `refused`: the full refusal, the same one write_file would have given.'),
             },
             required: ['path', 'outcome'],
@@ -3181,6 +3192,7 @@ export function registerWorkspaceTools(
     gated: true,
     description:
       'Replace an exact string in a workspace TEXT file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
+      ASK_BEFORE_DEFAULT_BRANCH +
       UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
@@ -3260,7 +3272,8 @@ export function registerWorkspaceTools(
     name: 'delete_file',
     gated: true,
     description:
-      'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.',
+      'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.' +
+      ASK_BEFORE_DEFAULT_BRANCH,
     inputs: {
       type: 'object',
       properties: {
@@ -3484,10 +3497,11 @@ export function registerWorkspaceTools(
     description:
       'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Committed + pushed as you. ' +
       'The destination must not exist — a move never overwrites a file or merges into a folder. Access follows the ' +
-      'DESTINATION folder, so a move can change what you (and others) may do with the file: the dry run answers ' +
-      '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }`, where `access` is your ' +
-      'own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, ' +
-      'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`. ' +
+      'DESTINATION folder, so a move can change who may open or edit the file. You must be able to read what moves and the folder it lands in, ' +
+      'or it is refused as read_file refuses. The dry run answers ' +
+      '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, holderChanges?, allowed, reason? }`: your own ' +
+      'access at both ends, and who else loses or gains it. A move that changes either wants `confirm: true`; tell the person ' +
+      'who loses and who gains before you confirm. ' +
       'Links are rewritten by default, in one commit with the move: those in the moved files and those in other markdown files pointing at them (`links` reports them). `rewriteLinks: false` turns that off. Path mentions in plain prose or code are never changed.',
     inputs: {
       type: 'object',
@@ -3496,7 +3510,7 @@ export function registerWorkspaceTools(
         src: wsPath(kbDirName, 'Source path (file or folder)'),
         dest: wsPath(kbDirName, 'Destination path — the full new path; must not exist yet'),
         dryRun: { type: 'boolean', description: 'Answer with the impact and change nothing.' },
-        confirm: { type: 'boolean', description: 'Required when the move changes your access. Set it only after a dry run.' },
+        confirm: { type: 'boolean', description: 'Required when the move changes your access or anyone else\'s. Set it only after a dry run.' },
         rewriteLinks: { type: 'boolean', description: 'Rewrite the links into, out of and between the moved files (default true). `false` moves without touching any link.' },
         sessionId: SESSION_ID_INPUT,
       },
@@ -3510,8 +3524,14 @@ export function registerWorkspaceTools(
         dest: str('Destination path (echoes the input).'),
         kind: str('`file` or `folder`.'),
         descendants: int('Files that move: 1 for a file, the file count under a folder.'),
-        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`).' },
+        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`), with every `access.md` inside a moved folder counted at its new place.' },
         accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between `before` and `after`.' },
+        holderChanges: {
+          type: 'object',
+          description:
+            'Who loses and who gains opening (`read`) or editing (`write`) it once the move has landed: `{ lose, gain }`, each ' +
+            '`[{ kind, name, email?, verb }]` with `kind` `group`, `role`, `plugin` or `person`. Absent when nobody\'s access changes.',
+        },
         allowed: { type: 'boolean', description: 'Whether the move may run.' },
         reason: str('Why it may not, when `allowed` is false.'),
         dryRun: { type: 'boolean', description: 'True on a dry run.' },
@@ -3541,6 +3561,23 @@ export function registerWorkspaceTools(
       // source already deleted.
       await assertAgentWriteAllowed(agentAccessGate, ctx, branch, src);
       await assertAgentWriteAllowed(agentAccessGate, ctx, branch, dest);
+      // What moves and the folder it lands in must both be readable to the
+      // caller, refused as read_file refuses them, on every branch: a move
+      // preview reads both ends (the caller's own verdicts there, who else is
+      // affected), and the folder's rules are what the names are made of. The
+      // verdict comes BEFORE every other look, so neither end's existence is
+      // told to someone who may not know it. The deployment's read hook is
+      // asked first, as read_file asks it, and its refusal is the answer: a
+      // move the hook would not let read is not previewed at all, since even
+      // "this move asks for confirm" would tell what the comparison found. A
+      // folder the caller may read moves with everything in it, files they
+      // may not read included: those travel, they are not read.
+      const destFolder = dest.slice(0, dest.lastIndexOf('/'));
+      await notifyAgentRead(agentAccessGate, ctx, branch, src);
+      await notifyAgentRead(agentAccessGate, ctx, branch, destFolder);
+      const gate = readGateFor(branch, ctx);
+      await assertCanRead(gate, src);
+      await assertCanRead(gate, destFolder);
       const fs = await ctx.getFilesystem(branch);
       const root = await workspaceRoot(branch, ctx);
       // Before the kind check, which stats THROUGH a link: a dangling link at
@@ -3564,6 +3601,17 @@ export function registerWorkspaceTools(
         accessAfter(branch, ctx, src, dest),
       ]);
       const accessChanges = verbsDiffer(before, after);
+      // Who ELSE gains or loses opening or editing it: the lists the app's move
+      // confirmation shows people. The caller may read both ends (the hook and
+      // the rules, gated above, as the app's route gates), so the names go to
+      // them, and a change asks for `confirm`. Outside the repository no rules
+      // travel.
+      const fromRel = toKbRelative(src, kbDirName);
+      const toRel = toKbRelative(dest, kbDirName);
+      const changes = fromRel !== null && toRel !== null
+        ? await accessControl.prospectiveHolderChanges(workspaceIdForBranch(branch), fromRel, toRel)
+        : undefined;
+      const othersChange = changes !== undefined && (changes.lose.length > 0 || changes.gain.length > 0);
       // The placeholder moves with its folder, but it is never content.
       const descendants = srcFiles.filter((f) => !isFolderPlaceholder(f)).length;
       // Neither end may be the platform's own: a move neither takes a platform
@@ -3671,6 +3719,7 @@ export function registerWorkspaceTools(
         descendants,
         access: { before, after },
         accessChanges,
+        ...(othersChange ? { holderChanges: changes } : {}),
         allowed: moveReason === undefined,
         ...(moveReason !== undefined ? { reason: moveReason } : {}),
         ...(linkPlan ? { links: linkPlan.report } : {}),
@@ -3686,12 +3735,16 @@ export function registerWorkspaceTools(
       }
       if (collision) throw new ToolError(reason!, 409);
       if (linkPlan?.overCap !== undefined) throw new ToolError(linkPlan.overCap, 400);
-      if (accessChanges && a.confirm !== true) {
+      if ((accessChanges || othersChange) && a.confirm !== true) {
+        const why = [
+          ...(accessChanges ? [`your access at "${dest}" differs from "${src}"`] : []),
+          ...(othersChange ? ['it changes who else may open or edit it (`holderChanges`)'] : []),
+        ];
         return {
           ...impact,
           confirmationRequired: true,
           moved: false,
-          message: `Nothing was moved: your access at "${dest}" differs from "${src}", so this move requires confirm: true.`,
+          message: `Nothing was moved: ${why.join(', and ')}, so this move requires confirm: true.`,
         };
       }
       // The look above is what produces the sentence; the filesystem's own
@@ -3741,8 +3794,8 @@ export function registerWorkspaceTools(
     gated: true,
     description:
       'Copy a workspace FILE to a new path. The destination must not exist — like a move, a copy never overwrites a file or a folder; to change what is in a file that already exists, write it. Committed + pushed as you. `src` may be a `__tmp__/<path>` ref to a file you staged in the workspace\'s tmp folder: the copy is how such a file is kept, as a normal repository file. ' +
-      'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with every `access.md` inside a copied folder counted at its new place. ' +
-      'One exception to that shape: when the destination is one you may not write, the answer is the refusal alone — `allowed: false` with `reason`, and no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
+      'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with the copy\'s own rules counted at its new place. ' +
+      'One exception to that shape: when the destination is one you may not write, the answer is the refusal (`allowed: false` with `reason`, and the access figures) with no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
     inputs: {
       type: 'object',
       properties: {
@@ -4203,7 +4256,7 @@ export function registerWorkspaceTools(
         '`replaced` / `updated`, or `refused` with `error` (the code) and `message` (why). `count` is how many landed and ' +
         '`total` how many paths there were; `files` is cut to the first 25 unless you pass `all: true`. ' +
         'Every path is judged one by one — by your write access, the platform-file rules and what is already there — ' +
-        'exactly as `write_file` judges it, and a refused path does not stop the others. ' +
+        'as `write_file` judges it, except that platform files are refused and binary content is fine; a refused path does not stop the others. ' +
         'The token is single-use: it is spent by the apply that lands it, and refused if you use it twice, let it ' +
         'expire, or present one issued to somebody else. `mode` means what it means on `write_file`.',
       inputs: {
@@ -4287,7 +4340,7 @@ export function registerWorkspaceTools(
         'each one inside a folder too, is included only if you may read AND download that file. Returns ' +
         '`{ expiresAt, expiresInSeconds, files: [{ path, bytes, sha256, downloadUrl }], folders: [{ path, bytes, ' +
         'downloadUrl, files }], refused: [{ path, reason }] }`: a link per file, with its own content type, and per ' +
-        `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put every file back). ` +
+        `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put them back). ` +
         'Fetch with any HTTP client (`curl -o <name> "<downloadUrl>"`, or the address without its last segment and an ' +
         '`x-download-token` header). Each link works ONCE, for 15 minutes, and serves the files as they are now. ' +
         'Refused: `not found` (missing or named-but-unreadable; folders omit unreadable files), ' +

package/src/shared/__tests__/read-capped.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { readCapped } from '../read-capped.js';
+
+describe('readCapped', () => {
+  /**
+   * Counting a chunk against the budget after decoding it lets a provider that
+   * answers in one huge chunk put the whole thing through the decoder — the
+   * bound bypassed by exactly the party it exists to bound. Asserted on the
+   * reader directly because a caller's short snippet is identical either way.
+   */
+  it('holds one oversized chunk to the byte budget, not just the loop', async () => {
+    const oneHugeChunk = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('x'.repeat(5_000_000)));
+        controller.close();
+      },
+    });
+
+    const out = await readCapped(new Response(oneHugeChunk), 8 * 1024);
+
+    expect(out.length).toBe(8 * 1024);
+  });
+
+  it('stops pulling at the budget and cancels a stream that never ends', async () => {
+    // Without the cap this never returns: the stream has no end.
+    let pulls = 0;
+    let cancelled = false;
+    const endless = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        controller.enqueue(new TextEncoder().encode('z'.repeat(1024)));
+      },
+      cancel() {
+        cancelled = true;
+      },
+    });
+
+    const out = await readCapped(new Response(endless), 2048);
+
+    expect(out).toBe('z'.repeat(2048));
+    expect(pulls).toBe(2);
+    expect(cancelled).toBe(true);
+  });
+
+  it('returns at once on a body of exactly the budget whose stream stays open', async () => {
+    // Asking for one more byte here would wait on a chunk that never comes.
+    let pulls = 0;
+    const openAfterFill = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        if (pulls === 1) {
+          controller.enqueue(new TextEncoder().encode('a'.repeat(8)));
+          return undefined;
+        }
+        return new Promise<void>(() => {});
+      },
+    });
+    expect(await readCapped(new Response(openAfterFill), 8)).toBe('a'.repeat(8));
+    expect(pulls).toBe(1);
+  });
+
+  it('reads a stream-less response whole, cut to the budget', async () => {
+    const res = new Response('abcdef');
+    // Consume the stream so only `text()` is left, as a mocked response may be.
+    Object.defineProperty(res, 'body', { value: null });
+    expect(await readCapped(res, 4)).toBe('abcd');
+  });
+});

package/src/shared/oauth-token-error.ts

@@ -0,0 +1,46 @@
+/**
+ * The error codes a token endpoint may answer with, as RFC 6749 §5.2 and OIDC
+ * Core §3.1.2.6 define them. A finite list, on purpose: a code is taken from
+ * a refusing provider's body only when it is exactly one of these, so no other
+ * string a provider puts in that field (a secret, a secret with a suffix, free
+ * text) reaches a message, a verdict or a log.
+ *
+ * Shared, not a module's own: the OIDC configuration check reads a provider's
+ * refusal through it and the secrets vault a token endpoint's, and one list is
+ * the only way the two cannot disagree about which codes are standard. Each
+ * caller keeps its own sentence per code (what a tool owner should do differs
+ * from what a sign-in administrator should do); the set of codes is one.
+ */
+export const OAUTH_TOKEN_ERROR_CODES: readonly string[] = Object.freeze([
+  'invalid_request',
+  'invalid_client',
+  'invalid_grant',
+  'unauthorized_client',
+  'unsupported_grant_type',
+  'invalid_scope',
+  'access_denied',
+  'server_error',
+  'temporarily_unavailable',
+]);
+
+/** Whether `code` is one of the standard token-endpoint error codes, and so safe to echo. */
+export function isStandardTokenErrorCode(code: unknown): code is string {
+  return typeof code === 'string' && OAUTH_TOKEN_ERROR_CODES.includes(code);
+}
+
+/**
+ * The standard `error` code in a refusing token endpoint's JSON body, or null:
+ * when the body is not JSON, not an object, carries no string `error`, or
+ * carries one that is not a standard code.
+ */
+export function standardTokenErrorCode(bodyText: string): string | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(bodyText);
+  } catch {
+    return null;
+  }
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  const { error } = json as Record<string, unknown>;
+  return isStandardTokenErrorCode(error) ? error : null;
+}

package/src/shared/read-capped.ts

@@ -0,0 +1,40 @@
+/**
+ * At most `limit` bytes of a response body, decoded as text, the rest of the
+ * stream cancelled.
+ *
+ * Each CHUNK is sliced to the remaining budget before being decoded, not just
+ * counted against it: a provider that answers in one 5MB chunk would otherwise
+ * put the whole thing through the decoder before the loop noticed it was over,
+ * which is the bound bypassed by the very party it is meant to bound. Never a
+ * byte past the limit: once the budget is spent the read stops without asking
+ * for more, so a body of exactly `limit` bytes on a stream that stays open
+ * returns at once. And the read never falls back to `res.text()` on a live
+ * stream: a cap applied after that read bounds nothing.
+ *
+ * Shared, not a module's own: the connection probe reads a provider's
+ * rejection with it and the secrets vault a token endpoint's refusal, and one
+ * reader is the only way the two cannot disagree about what "bounded" means.
+ */
+export async function readCapped(res: Response, limit: number): Promise<string> {
+  const reader = res.body?.getReader();
+  // No stream (a mocked or already-consumed response): fall back to the whole
+  // body, which for those cases is ours and small.
+  if (!reader) return (await res.text()).slice(0, limit);
+  const decoder = new TextDecoder();
+  let out = '';
+  let read = 0;
+  try {
+    while (read < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const remaining = limit - read;
+      const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
+      read += chunk.byteLength;
+      out += decoder.decode(chunk, { stream: true });
+      if (chunk.byteLength < value.byteLength) break;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  return out;
+}

package/agent-guide/finding-things.md

@@ -1,7 +0,0 @@
-## Finding things
-
-- `grep` for keywords across `{{knowledgeBaseDir}}/`.
-- Follow markdown links: when you read `[Some Page](relative/path/Some Page.md)`,
-  that path is relative to the file you are reading.
-- `list_files` to see the shape of a folder before assuming where something
-  lives.

package/agent-guide/introduction.md

@@ -1,27 +0,0 @@
-# Knowledge base
-
-This is a git-backed knowledge base. You are the primary agent responsible for
-maintaining it.
-
-> **This guide is served by the platform.** It is not a file in the
-> repository: `get_agent_guide` returns it, whole or one section at a time,
-> and so does `read_file` on `AGENTS.md` at the repository root — after the
-> knowledge base's own `AGENTS.md`, when it has one; `grep` searches it there
-> too. An `AGENTS.md` you find on disk is the organisation's own conventions
-> file, written by its people; follow it, and never write this text into it.
-> Deployment- or team-specific conventions belong there, or in files of your
-> own anywhere under `{{knowledgeBaseDir}}/`, linked from wherever they are
-> needed.
-
-**Read `mcp-description.md` at the repository root first.** It says what this
-knowledge base contains and when to consult it. Agents connected over MCP
-receive the default branch's copy inline at the start of every session; a
-clone reads the copy on its own branch.
-
-**There is no required format for knowledge.** Write markdown the way the
-subject wants to be written: prose, tables, checklists, diagrams, whatever
-serves the reader. Nothing here parses your files into a schema or rejects a
-document for having the wrong shape. If a deployment layers a structured
-knowledge graph on top, it brings its own conventions, in sections of this
-guide of its own; what follows describes the platform underneath, which stores
-files and controls who may change them.