@bevel-software/platform-core-backend 0.25.0 → 0.26.0

package/dist/modules/agent-guide/agent-guide.js

@@ -0,0 +1,191 @@
+/**
+ * The platform's agent guide: what every agent is told to read before its
+ * first read or change in a knowledge base — the layout, where a new file
+ * goes, the rules every file tool shares, access control, skills and tool
+ * manuals.
+ *
+ * It is TEXT THE CODE OWNS, not a file in the repository. It used to be
+ * written to every protected branch as `AGENTS.md` and refreshed on every
+ * start, which had three costs: a repository that already had an `AGENTS.md`
+ * of its own lost it or had to rename ours; a distribution that wanted to add
+ * to the guide had to fork the whole file and then drifted from every change
+ * made here; and the file sat in git history on every branch, hidden from the
+ * tree by an ignore rule it had to keep writing. Now the guide is composed
+ * from SECTIONS at the moment an agent asks for it — `get_agent_guide`, or a
+ * `read_file` of the guide's name at the repository root — and a distribution
+ * shapes it with a hook that sees the sections and returns the sections it
+ * wants (append, replace or drop by id), so what Hexis says reaches it without
+ * a copy to maintain.
+ *
+ * The sections ship as markdown files in the package's `agent-guide/` folder
+ * (see `assets.ts`), one per section, with the layout placeholders the old
+ * template carried (`{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`,
+ * `{{agentsFile}}`). ONE section is computed rather than read: the rules every
+ * file tool shares, which the MCP handshake also sends — the same string in
+ * both places, from `shared-file-rules.ts`, so a rule cannot be changed in one
+ * and left stale in the other.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { renderKbLayoutPlaceholders, resolveKbLayout, } from '@bevel-software/platform-shared';
+import { agentGuideDir } from '../../assets.js';
+import { sharedFileRulesSection } from '../agent-instructions/shared-file-rules.js';
+/** The computed section: the rules every file tool shares. */
+export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
+/**
+ * Core's sections, in reading order. Every id but the shared-rules one names
+ * a file in the package's `agent-guide/` folder.
+ */
+export const CORE_SECTION_IDS = Object.freeze([
+    'introduction',
+    'directory-structure',
+    'where-a-new-file-goes',
+    WORKING_WITH_FILES_SECTION_ID,
+    'access-control',
+    'skills',
+    'tool-manuals',
+    'conventions',
+    'finding-things',
+]);
+/**
+ * The one line that proves a root guide file is the platform's and not the
+ * customer's: the blockquote the packaged guide opened with for as long as
+ * the guide was a file, under every release. Asked for WHERE the header put
+ * it — a blockquote line among the first lines of the file — and not anywhere
+ * in the text: a note of the organisation's own that quotes the platform's
+ * sentence in its body must not read as ours, because the consequence of the
+ * mistake is a deletion. Still read on every start, to take the copies
+ * earlier releases wrote out of the repository (see template-files.step.ts),
+ * and on every read of the guide's name, so a copy still on a draft is not
+ * served twice.
+ */
+const MANAGED_GUIDE_HEADER_LINE = '> **This file is managed by the platform.**';
+/** How far down a file the header's blockquote can sit: under the title and a sentence or two, never further. */
+const MANAGED_GUIDE_HEADER_WITHIN_LINES = 12;
+/** Whether `text` is a copy of the guide a release wrote to disk, of any vintage. */
+export function isManagedGuide(text) {
+    return text
+        .split('\n', MANAGED_GUIDE_HEADER_WITHIN_LINES)
+        .some((line) => line.trimStart().startsWith(MANAGED_GUIDE_HEADER_LINE));
+}
+/** The raw section files, read once per process: the package does not change while it runs. */
+let coreSectionFiles = null;
+async function readCoreSectionFiles() {
+    const dir = agentGuideDir();
+    const entries = await Promise.all(CORE_SECTION_IDS.filter((id) => id !== WORKING_WITH_FILES_SECTION_ID).map(
+    // Line endings normalised: a checkout on Windows may carry CRLF, and the
+    // guide is one text with one ending wherever it is served from.
+    async (id) => [id, (await fs.readFile(path.join(dir, `${id}.md`), 'utf8')).replace(/\r\n?/g, '\n')]));
+    return new Map(entries);
+}
+/**
+ * Core's sections for `layout`: the files, placeholders unrendered, with the
+ * shared-rules section computed and in its place. What a distribution's hook
+ * is handed.
+ */
+export async function coreAgentGuideSections(layout) {
+    coreSectionFiles ??= readCoreSectionFiles();
+    let files;
+    try {
+        files = await coreSectionFiles;
+    }
+    catch (err) {
+        // A failed read is not cached: the next composition tries the disk again.
+        coreSectionFiles = null;
+        throw err;
+    }
+    return CORE_SECTION_IDS.map((id) => id === WORKING_WITH_FILES_SECTION_ID
+        ? { id, body: sharedFileRulesSection(layout), literal: true }
+        : { id, body: files.get(id) });
+}
+/** The checkout folder's name when none is given — core's own default. */
+const DEFAULT_KB_DIR_NAME = 'knowledge-base';
+/**
+ * The guide's sections as an agent reads them: core's sections through the
+ * distribution's hook (when there is one), rendered for the layout, each
+ * with its title. The whole guide is these joined (see
+ * {@link composeAgentGuide}); `get_agent_guide` also serves one at a time.
+ *
+ * A hook may append, replace and drop sections, with ONE exception: the
+ * shared file rules ({@link WORKING_WITH_FILES_SECTION_ID}) must come back
+ * WITH TEXT IN THEM, as core's or as the hook's own replacement. A client
+ * that drops the handshake instructions has the guide as the only place to
+ * read the rules — a guide without them would leave agents nothing to read.
+ * A hook that drops the section, or hands it back empty, is a composition
+ * error, thrown rather than served. Judged on what would be SERVED — the
+ * rendered, trimmed body — so a replacement of whitespace is caught like a
+ * missing one, rather than passing the check and vanishing with the other
+ * empty sections below.
+ */
+export async function agentGuideSections(layout, hook, context = {}) {
+    const resolved = resolveKbLayout(layout);
+    const core = await coreAgentGuideSections(resolved);
+    const sections = hook ? await hook(core, resolved) : core;
+    const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
+    const rendered = sections.map((section) => {
+        const body = (section.literal
+            ? section.body
+            : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)).trim();
+        return { id: section.id, title: titleOf(body, section.id), body };
+    });
+    // Judged over EVERY section under the id — a hook may return the id twice
+    // — on what survives the empty-body filter below: one with text is enough.
+    const rules = rendered.filter((section) => section.id === WORKING_WITH_FILES_SECTION_ID);
+    if (!rules.some((section) => section.body.length > 0)) {
+        throw new Error(`The agent guide hook ${rules.length === 0 ? 'dropped' : 'emptied'} the "${WORKING_WITH_FILES_SECTION_ID}" ` +
+            'section, which every file tool points at. Keep it, or replace it under the same id with the rules in it.');
+    }
+    return rendered.filter((section) => section.body.length > 0);
+}
+/**
+ * The heading's text, or the id when the section opens with no heading. An
+ * ATX heading may close with a run of `#` of its own (`## Custom ##`); that
+ * is a delimiter, not part of the title.
+ */
+function titleOf(body, id) {
+    const first = body.split('\n', 1)[0] ?? '';
+    const heading = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(first);
+    return heading ? heading[1].trim() : id;
+}
+/**
+ * The guide as an agent reads it whole: the sections joined by blank lines,
+ * ending in one newline.
+ */
+export async function composeAgentGuide(layout, hook, context = {}) {
+    return joinGuideSections(await agentGuideSections(layout, hook, context));
+}
+/** The sections as one document, the way `composeAgentGuide` joins them. */
+export function joinGuideSections(sections) {
+    return `${sections.map((section) => section.body).join('\n\n')}\n`;
+}
+/**
+ * What a `read_file` of the guide's name answers when the knowledge base has an
+ * `AGENTS.md` of its own: their text first, whole, then a rule and one line
+ * saying what follows, then the platform's guide. Theirs first because it is
+ * the more specific of the two, and the line between so neither is read as
+ * part of the other.
+ */
+export const PLATFORM_GUIDE_SEPARATOR = "---\n\n_The text above is this knowledge base's own conventions file. The platform's guide follows; `get_agent_guide` returns it on its own._";
+export function withPlatformGuideAppended(ownText, guide) {
+    // Their text as they wrote it, line endings normalised and the trailing
+    // newlines folded into the one blank line before the separator. Nothing
+    // else is touched: leading indentation and trailing spaces are markdown.
+    const own = ownText.replace(/\r\n?/g, '\n').replace(/\n+$/, '');
+    // A file with nothing in it has nothing to put first, and a separator
+    // above nothing would claim a conventions file that says nothing.
+    if (own.trim().length === 0)
+        return guide;
+    return `${own}\n\n${PLATFORM_GUIDE_SEPARATOR}\n\n${guide}`;
+}
+/** The one name the guide is read by: `AGENTS.md` at the repository root, the name coding agents look for. */
+export const AGENT_GUIDE_FILE = 'AGENTS.md';
+/**
+ * Whether a repository-relative path is where the guide is read — `AGENTS.md`
+ * at the repository root, exactly spelled, like every platform path. One
+ * name on every deployment: there is no setting for it any more.
+ */
+export function isAgentGuidePath(repoRelativePath) {
+    const norm = repoRelativePath.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+    return norm === AGENT_GUIDE_FILE;
+}
+//# sourceMappingURL=agent-guide.js.map

package/dist/modules/agent-guide/agent-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAEL,0BAA0B,EAC1B,eAAe,GAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAyCpF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC/D,cAAc;IACd,qBAAqB;IACrB,uBAAuB;IACvB,6BAA6B;IAC7B,gBAAgB;IAChB,QAAQ;IACR,cAAc;IACd,aAAa;IACb,gBAAgB;CACjB,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,yBAAyB,GAAG,6CAA6C,CAAC;AAEhF,iHAAiH;AACjH,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAE7C,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,EAAE,iCAAiC,CAAC;SAC9C,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,+FAA+F;AAC/F,IAAI,gBAAgB,GAAgD,IAAI,CAAC;AAEzE,KAAK,UAAU,oBAAoB;IACjC,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,gBAAgB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,6BAA6B,CAAC,CAAC,GAAG;IACvE,yEAAyE;IACzE,gEAAgE;IAChE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAU,CAC7G,CACF,CAAC;IACF,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAgB;IAC3D,gBAAgB,KAAK,oBAAoB,EAAE,CAAC;IAC5C,IAAI,KAAkC,CAAC;IACvC,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,gBAAgB,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,gBAAgB,GAAG,IAAI,CAAC;QACxB,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CACjC,EAAE,KAAK,6BAA6B;QAClC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;QAC7D,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAE,EAAE,CACjC,CAAC;AACJ,CAAC;AAaD,0EAA0E;AAC1E,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAc7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAgB,EAChB,IAAqB,EACrB,UAA6B,EAAE;IAE/B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,mBAAmB,CAAC;IACnE,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACxC,MAAM,IAAI,GAAG,CACX,OAAO,CAAC,OAAO;YACb,CAAC,CAAC,OAAO,CAAC,IAAI;YACd,CAAC,CAAC,0BAA0B,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CACpG,CAAC,IAAI,EAAE,CAAC;QACT,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACpE,CAAC,CAAC,CAAC;IACH,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,6BAA6B,CAAC,CAAC;IACzF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,wBAAwB,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,SAAS,6BAA6B,IAAI;YAC1G,0GAA0G,CAC7G,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,IAAY,EAAE,EAAU;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,MAAM,OAAO,GAAG,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAgB,EAChB,IAAqB,EACrB,UAA6B,EAAE;IAE/B,OAAO,iBAAiB,CAAC,MAAM,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,QAAyC;IACzE,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,+IAA+I,CAAC;AAElJ,MAAM,UAAU,yBAAyB,CAAC,OAAe,EAAE,KAAa;IACtE,wEAAwE;IACxE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChE,sEAAsE;IACtE,kEAAkE;IAClE,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,GAAG,GAAG,OAAO,wBAAwB,OAAO,KAAK,EAAE,CAAC;AAC7D,CAAC;AAED,8GAA8G;AAC9G,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE5C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,gBAAwB;IACvD,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzE,OAAO,IAAI,KAAK,gBAAgB,CAAC;AACnC,CAAC"}

package/dist/modules/agent-guide/agent-guide.tools.d.ts

@@ -0,0 +1,24 @@
+import type { Router, RequestHandler } from 'express';
+import type { IToolRegistry } from '../tool-registry/tool.contract.js';
+import { GET_AGENT_GUIDE_TOOL } from '../tool-registry/guide-first.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import { type AgentGuideSectionsReader } from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL };
+/**
+ * The one tool that returns the guide on its own — whole, or one section by
+ * id. It takes nothing else: the guide is the platform's text for this
+ * deployment, the same for every caller and every branch, and reading it
+ * touches no file — so no `branch`, no `sessionId`, and no access gate. The
+ * other way to the same text is a `read_file` of `AGENTS.md` at the
+ * repository root, which also carries the knowledge base's own `AGENTS.md`
+ * when it has one (see `agent-guide.ts`).
+ *
+ * Registered as a PROVIDER on both surfaces, so the description names the
+ * sections the guide has NOW — a distribution's hook may add its own — and
+ * the in-process agent and an external one are told the same thing to read
+ * first. This is the one tool the catalog does not open with "call
+ * get_agent_guide first" (see `tool-registry/guide-first.ts`): it is what
+ * that sentence points at, and says so itself.
+ */
+export declare function registerAgentGuideTool(registry: IToolRegistry, router: Router, toolAuth: RequestHandler, toolHandler: ToolHandlerFactory, sections: AgentGuideSectionsReader): void;
+//# sourceMappingURL=agent-guide.tools.d.ts.map

package/dist/modules/agent-guide/agent-guide.tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.tools.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAIvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAuC,KAAK,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEtG,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,EAAE,wBAAwB,GACjC,IAAI,CAwFN"}

package/dist/modules/agent-guide/agent-guide.tools.js

@@ -0,0 +1,100 @@
+import { GET_AGENT_GUIDE_TOOL } from '../tool-registry/guide-first.js';
+import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import { AGENT_GUIDE_FILE, joinGuideSections } from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL };
+/**
+ * The one tool that returns the guide on its own — whole, or one section by
+ * id. It takes nothing else: the guide is the platform's text for this
+ * deployment, the same for every caller and every branch, and reading it
+ * touches no file — so no `branch`, no `sessionId`, and no access gate. The
+ * other way to the same text is a `read_file` of `AGENTS.md` at the
+ * repository root, which also carries the knowledge base's own `AGENTS.md`
+ * when it has one (see `agent-guide.ts`).
+ *
+ * Registered as a PROVIDER on both surfaces, so the description names the
+ * sections the guide has NOW — a distribution's hook may add its own — and
+ * the in-process agent and an external one are told the same thing to read
+ * first. This is the one tool the catalog does not open with "call
+ * get_agent_guide first" (see `tool-registry/guide-first.ts`): it is what
+ * that sentence points at, and says so itself.
+ */
+export function registerAgentGuideTool(registry, router, toolAuth, toolHandler, sections) {
+    const build = async () => {
+        const list = await sections();
+        const describe = (sectionList) => "The platform's guide to this knowledge base: its layout, where a new file goes, the rules every file tool " +
+            'shares, access control, skills and tool manuals. ALWAYS call this first and read the guide before you do ' +
+            'anything else in the platform. Returns `{ guide }` as markdown: the whole guide, or one section when ' +
+            '`section` names one. The same text comes back from `read_file` on `' +
+            AGENT_GUIDE_FILE +
+            "` at the KB root, after the knowledge base's own " +
+            AGENT_GUIDE_FILE +
+            ` when it has one. Sections: ${sectionList}.`;
+        // The description stays under the cap WHATEVER a distribution adds, in
+        // three steps: every id with its title; every id alone; as many ids as
+        // fit and a count of the rest. An id a client cut off the end would be a
+        // section an agent cannot ask for — so nothing is ever cut: the one
+        // complete list of sections is `sections` on the whole-guide response,
+        // which the description names when it cannot carry them all itself.
+        const titled = describe(list.map((s) => `\`${s.id}\` (${s.title})`).join(', '));
+        const ids = list.map((s) => `\`${s.id}\``);
+        const counted = (shown) => describe(shown === 0
+            ? `${ids.length}, named under \`sections\` in the whole-guide response`
+            : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the whole-guide response`].join(', '));
+        let description = titled.length <= TOOL_DESCRIPTION_CAP ? titled : describe(ids.join(', '));
+        for (let shown = ids.length; description.length > TOOL_DESCRIPTION_CAP && shown > 0; shown--) {
+            description = counted(shown - 1);
+        }
+        return toolDef({
+            name: GET_AGENT_GUIDE_TOOL,
+            description,
+            path: `/api/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
+            inputs: {
+                type: 'object',
+                properties: {
+                    section: {
+                        type: 'string',
+                        description: 'Optional: the id of one section to read instead of the whole guide (the ids are listed in this ' +
+                            'description, and every one under `sections` in the whole-guide response). Omit it for the whole guide.',
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputs: {
+                type: 'object',
+                properties: {
+                    guide: { type: 'string', description: 'The guide, or the one section asked for, as markdown.' },
+                    sections: {
+                        type: 'array',
+                        description: 'Without `section`: every section of the guide, in order, by id and heading — the complete list.',
+                        items: {
+                            type: 'object',
+                            properties: { id: { type: 'string' }, title: { type: 'string' } },
+                            required: ['id', 'title'],
+                        },
+                    },
+                    section: { type: 'string', description: 'With `section`: the id of the section returned.' },
+                    title: { type: 'string', description: 'With `section`: its heading.' },
+                },
+                required: ['guide'],
+            },
+            tags: ['workspace'],
+        });
+    };
+    registry.registerInternalTool(build);
+    registry.registerExternalTool(build);
+    router.post(`/agent/tools/${GET_AGENT_GUIDE_TOOL}`, toolAuth, toolHandler(async (args) => {
+        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 })) };
+        const one = list.find((s) => s.id === wanted);
+        if (!one) {
+            throw new ToolError(`The guide has no section "${wanted}". Sections: ${list.map((s) => `\`${s.id}\``).join(', ')}. ` +
+                'Omit `section` for the whole guide.', 400);
+        }
+        return { guide: one.body, section: one.id, title: one.title };
+    }));
+}
+//# sourceMappingURL=agent-guide.tools.js.map

package/dist/modules/agent-guide/agent-guide.tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.tools.js","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.tools.ts"],"names":[],"mappings":"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"}

package/dist/modules/agent-guide/index.d.ts

@@ -0,0 +1,4 @@
+export { AGENT_GUIDE_FILE, CORE_SECTION_IDS, PLATFORM_GUIDE_SEPARATOR, WORKING_WITH_FILES_SECTION_ID, agentGuideSections, composeAgentGuide, coreAgentGuideSections, isAgentGuidePath, isManagedGuide, joinGuideSections, withPlatformGuideAppended, type AgentGuideContext, type AgentGuideHook, type AgentGuideReader, type AgentGuideSection, type AgentGuideSectionsReader, type RenderedGuideSection, } from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/agent-guide/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-guide/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/modules/agent-guide/index.js

@@ -0,0 +1,4 @@
+export { AGENT_GUIDE_FILE, CORE_SECTION_IDS, PLATFORM_GUIDE_SEPARATOR, WORKING_WITH_FILES_SECTION_ID, agentGuideSections, composeAgentGuide, coreAgentGuideSections, isAgentGuidePath, isManagedGuide, joinGuideSections, withPlatformGuideAppended, } from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/agent-guide/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-guide/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,yBAAyB,GAO1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/modules/agent-instructions/agent-instructions.routes.d.ts

@@ -21,8 +21,9 @@ import type { AgentPreambleReader } from './read-preamble.js';
 export declare function createAgentInstructionsRoutes(manualAuth: RequestHandler, readPreamble: AgentPreambleReader, 
 /**
  * The layout in effect, read per request — the shared file rules name the
- * managed guide, whose name the setup save may change without a restart.
- * Optional so a construction with no layout in hand gets `AGENTS.md`.
+ * guide by the name a deployment saved for it, which the setup save may
+ * change without a restart. Optional so a construction with no layout in
+ * hand gets `AGENTS.md`.
  */
 kbLayout?: () => KbLayout): express.Router;
 //# sourceMappingURL=agent-instructions.routes.d.ts.map

package/dist/modules/agent-instructions/agent-instructions.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-instructions.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAKhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,cAAc,EAC1B,YAAY,EAAE,mBAAmB;AACjC;;;;GAIG;AACH,QAAQ,CAAC,EAAE,MAAM,QAAQ,GACxB,OAAO,CAAC,MAAM,CAgBhB"}
+{"version":3,"file":"agent-instructions.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAKhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,cAAc,EAC1B,YAAY,EAAE,mBAAmB;AACjC;;;;;GAKG;AACH,QAAQ,CAAC,EAAE,MAAM,QAAQ,GACxB,OAAO,CAAC,MAAM,CAgBhB"}

package/dist/modules/agent-instructions/agent-instructions.routes.js

@@ -22,8 +22,9 @@ import { composeAgentInstructions } from './compose.js';
 export function createAgentInstructionsRoutes(manualAuth, readPreamble, 
 /**
  * The layout in effect, read per request — the shared file rules name the
- * managed guide, whose name the setup save may change without a restart.
- * Optional so a construction with no layout in hand gets `AGENTS.md`.
+ * guide by the name a deployment saved for it, which the setup save may
+ * change without a restart. Optional so a construction with no layout in
+ * hand gets `AGENTS.md`.
  */
 kbLayout) {
     const router = express.Router();

package/dist/modules/agent-instructions/agent-instructions.routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-instructions.routes.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAgC,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAA0B,EAC1B,YAAiC;AACjC;;;;GAIG;AACH,QAAyB;IAEzB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChE,uEAAuE;QACvE,uEAAuE;QACvE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,MAAM,YAAY,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,oCAAoC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACzD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"agent-instructions.routes.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAgC,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAA0B,EAC1B,YAAiC;AACjC;;;;;GAKG;AACH,QAAyB;IAEzB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChE,uEAAuE;QACvE,uEAAuE;QACvE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,MAAM,YAAY,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,oCAAoC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACzD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modules/agent-instructions/compose.d.ts

@@ -39,8 +39,10 @@ export declare const TOOL_PREFIX_LINE = "This organisation's knowledge base. Sea
  * `header` field carries and what the card shows as fixed and not editable;
  * the admin's preamble follows it.
  *
- * A FUNCTION of the layout, because the shared rules name the managed guide
- * and its file name is a deployment setting.
+ * A FUNCTION of the layout, because the shared rules name the platform files
+ * by the root names a deployment chose (`Skills/`, `Plugins/`), which are
+ * deployment settings. The guide's name is not one of them: it is `AGENTS.md`
+ * everywhere.
  */
 export declare function platformInstructions(layout: KbLayout): string;
 /**
@@ -88,10 +90,11 @@ export interface ComposedAgentInstructions {
  * unterminated `<!--` strips everything after it, so the most likely editing
  * slip withholds text rather than leaking it.
  *
- * `layout` decides only the guide's name inside the shared rules, and defaults
- * to the standard one — a caller with no layout in hand (a test, a surface that
- * predates the setting) gets `AGENTS.md`, which is what an unset name means
- * everywhere else.
+ * `layout` decides the root names the shared rules spell (`Skills/`,
+ * `Plugins/`, the knowledge folder) and defaults to the standard ones — a
+ * caller with no layout in hand (a test, a surface that predates the setting)
+ * gets the defaults. The guide's name is not among them: it is `AGENTS.md` on
+ * every deployment.
  */
 export declare function composeAgentInstructions(preamble: string | null, layout?: KbLayout): ComposedAgentInstructions;
 /**

package/dist/modules/agent-instructions/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,EAEL,YAAY,EACZ,aAAa,EACb,eAAe,EAEf,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAAiE,CAAC;AAEjH;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAMkD,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,gFAAgF,CAAC;AAE9G;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,QAAyG,CAAC;AAEjJ,MAAM,WAAW,yBAAyB;IACxC,qGAAqG;IACrG,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,GAAE,QAA4B,GACnC,yBAAyB,CA+B3B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjG"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,EAEL,YAAY,EACZ,aAAa,EACb,eAAe,EAEf,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAAiE,CAAC;AAEjH;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAMkD,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,gFAAgF,CAAC;AAE9G;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,QAAyG,CAAC;AAEjJ,MAAM,WAAW,yBAAyB;IACxC,qGAAqG;IACrG,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,GAAE,QAA4B,GACnC,yBAAyB,CA+B3B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjG"}

package/dist/modules/agent-instructions/compose.js

@@ -50,8 +50,10 @@ export const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it b
  * `header` field carries and what the card shows as fixed and not editable;
  * the admin's preamble follows it.
  *
- * A FUNCTION of the layout, because the shared rules name the managed guide
- * and its file name is a deployment setting.
+ * A FUNCTION of the layout, because the shared rules name the platform files
+ * by the root names a deployment chose (`Skills/`, `Plugins/`), which are
+ * deployment settings. The guide's name is not one of them: it is `AGENTS.md`
+ * everywhere.
  */
 export function platformInstructions(layout) {
     return `${PLATFORM_HEADER}\n\n${sharedFileRulesSection(layout)}`;
@@ -76,10 +78,11 @@ export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP
  * unterminated `<!--` strips everything after it, so the most likely editing
  * slip withholds text rather than leaking it.
  *
- * `layout` decides only the guide's name inside the shared rules, and defaults
- * to the standard one — a caller with no layout in hand (a test, a surface that
- * predates the setting) gets `AGENTS.md`, which is what an unset name means
- * everywhere else.
+ * `layout` decides the root names the shared rules spell (`Skills/`,
+ * `Plugins/`, the knowledge folder) and defaults to the standard ones — a
+ * caller with no layout in hand (a test, a surface that predates the setting)
+ * gets the defaults. The guide's name is not among them: it is `AGENTS.md` on
+ * every deployment.
  */
 export function composeAgentInstructions(preamble, layout = DEFAULT_KB_LAYOUT) {
     const platform = platformInstructions(layout);

package/dist/modules/agent-instructions/compose.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/compose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/compose.ts"],"names":[],"mappings":"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"}

package/dist/modules/agent-instructions/index.d.ts

@@ -1,5 +1,5 @@
 export { composeAgentInstructions, prefixToolDescription, platformInstructions, INSTRUCTIONS_CAP, PLATFORM_HEADER, TOOL_PREFIX_LINE, PREAMBLE_CAP, TOOL_PREFIX_CAP, PREAMBLE_FILE, PREFIXED_TOOLS, PREAMBLE_TRUNCATION_MARKER, type ComposedAgentInstructions, } from './compose.js';
-export { POINTER_GUIDE_NAME_BUDGET, SHARED_FILE_RULES_CAP, SHARED_RULES_POINTER_MAX, SHARED_RULES_SECTION, sharedFileRules, sharedFileRulesSection, sharedRulesPointer, type SharedFileRule, } from './shared-file-rules.js';
+export { SHARED_FILE_RULES_CAP, SHARED_RULES_SECTION, sharedFileRules, sharedFileRulesSection, type SharedFileRule, } from './shared-file-rules.js';
 export { readAgentPreamble, type AgentPreambleReader, type PreambleWorkspace } from './read-preamble.js';
 export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/agent-instructions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/modules/agent-instructions/index.js

@@ -1,5 +1,5 @@
 export { composeAgentInstructions, prefixToolDescription, platformInstructions, INSTRUCTIONS_CAP, PLATFORM_HEADER, TOOL_PREFIX_LINE, PREAMBLE_CAP, TOOL_PREFIX_CAP, PREAMBLE_FILE, PREFIXED_TOOLS, PREAMBLE_TRUNCATION_MARKER, } from './compose.js';
-export { POINTER_GUIDE_NAME_BUDGET, SHARED_FILE_RULES_CAP, SHARED_RULES_POINTER_MAX, SHARED_RULES_SECTION, sharedFileRules, sharedFileRulesSection, sharedRulesPointer, } from './shared-file-rules.js';
+export { SHARED_FILE_RULES_CAP, SHARED_RULES_SECTION, sharedFileRules, sharedFileRulesSection, } from './shared-file-rules.js';
 export { readAgentPreamble } from './read-preamble.js';
 export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';
 //# sourceMappingURL=index.js.map

package/dist/modules/agent-instructions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,GAE3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GAEnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAoD,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,GAE3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAoD,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/modules/agent-instructions/shared-file-rules.d.ts

@@ -14,19 +14,21 @@
  *
  *  - the MCP `instructions` of the initialize handshake (see `compose.ts`),
  *    which Claude Code, Claude Desktop and Cursor put in the system prompt;
- *  - the platform-managed agent guide at the repository root (`AGENTS.md` by
- *    default), rendered from `{{sharedFileRules}}` in the template — claude.ai
- *    on the web, the Agent SDK and Cline drop `instructions`, and a guide the
- *    agent is told to read before its first action is always available.
+ *  - the platform's agent guide, which `get_agent_guide` returns and a
+ *    `read_file` of the guide's name serves (see `modules/agent-guide`) —
+ *    claude.ai on the web, the Agent SDK and Cline drop `instructions`, and a
+ *    guide the agent is told to read before its first action is always
+ *    available.
  *
  * Both places get the SAME string, from {@link sharedFileRulesSection} — not
  * two hand-mirrored copies. A rule written twice is a rule that drifts, and a
  * drifted rule is worse than a repeated one, because the agent cannot tell
- * which copy is current. Each description ends instead with
- * {@link sharedRulesPointer}, one sentence naming the section and the file.
+ * which copy is current. Each description opens instead with the one
+ * sentence sending the agent to the guide (`tool-registry/guide-first.ts`).
  *
- * Pure text, a function of the layout only: the guide's file name is a
- * deployment setting, so nothing here may snapshot `AGENTS.md`.
+ * Pure text, a function of the layout only: the guide's name is a deployment
+ * setting (an alias a deployment chose before the guide left the disk), so
+ * nothing here may snapshot `AGENTS.md`.
  */
 import { type KbLayout } from '@bevel-software/platform-shared';
 /** The heading the rules live under, in both places and in the pointer sentence. */
@@ -70,46 +72,4 @@ export declare function sharedFileRules(layout: KbLayout): readonly SharedFileRu
  * level and still reads as a block in the instructions blob.
  */
 export declare function sharedFileRulesSection(layout: KbLayout): string;
-/**
- * The longest guide file name the pointer sentence spells out. Beyond this it
- * names the guide by its ROLE instead (see {@link sharedRulesPointer}).
- *
- * There has to be a bound somewhere, because the pointer rides on every file
- * tool and a file name is not a fixed cost: `validateFilename` allows a name
- * of up to 255 bytes, so an unbounded pointer could reach 318 characters and
- * push `file_stat` to 1,428 — over the description cap, recreating on a
- * renamed deployment exactly the truncation this module exists to prevent, and
- * invisibly, because every measurement is taken under the default layout.
- *
- * 40 is well past any name a deployment plausibly picks
- * (`ENGINEERING-AGENT-CONVENTIONS.md` is 32) and the fallback below is only
- * reachable past it.
- */
-export declare const POINTER_GUIDE_NAME_BUDGET = 40;
-/**
- * The one sentence a tool description ends with, in place of the paragraphs it
- * used to carry. Short on purpose: it costs every description the same ~100
- * characters at worst, and its whole job is to name the section and the file
- * to read.
- *
- * BOUNDED BY CONSTRUCTION, which is what lets the description cap mean
- * something on a deployment that renamed its guide: a name within
- * {@link POINTER_GUIDE_NAME_BUDGET} is spelled out, and a longer one gets the
- * generic wording. Naming the file is the better sentence and wins whenever it
- * fits; a name past the budget is pathological, and there the choice is between
- * a sentence that says where to look and a catalog entry the client cuts. The
- * guide's own name is still in the section's first rule either way.
- *
- * An absent layout means the default one, as it does in
- * `composeAgentInstructions`: a caller reading the layout from configuration
- * gets `undefined` when none is set, and the pointer must still name a file.
- */
-export declare function sharedRulesPointer(layout?: KbLayout): string;
-/**
- * The most the pointer can ever cost a description, over every layout. What the
- * description cap is measured against, the way the tool prefix is measured at
- * ITS cap rather than at whatever the current admin wrote: a description that
- * only fits beside the short default guide name does not really fit.
- */
-export declare const SHARED_RULES_POINTER_MAX: number;
 //# sourceMappingURL=shared-file-rules.d.ts.map