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

package/dist/modules/access-model/roles-yaml-guard.js

@@ -21,7 +21,7 @@
  * a direct git push, a pre-guard commit) lives in `roles-admin.service.ts`.
  */
 import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
 export const ROLES_YAML_BASENAME = 'roles.yaml';
 /**
@@ -29,7 +29,7 @@ export const ROLES_YAML_BASENAME = 'roles.yaml';
  * the edit is refused and nothing is written. Carries the parser errors so the
  * editor / agent can show exactly what's wrong.
  */
-export class RolesYamlInvalidError extends WorkflowDomainError {
+export class RolesYamlInvalidError extends VersionControlDomainError {
     errors;
     constructor(errors) {
         super(`roles.yaml would be invalid and was not saved: ${errors.join('; ')}`, 422, { kind: 'roles-yaml-invalid', rolesYamlErrors: errors });
@@ -86,7 +86,7 @@ export const NEW_ROLE_GUIDANCE = 'App roles are pre-set — add people to existi
  * self-contained because a tool error reaches the agent as its message alone,
  * and the agent relays it to its user.
  */
-export class RolesYamlNewRoleError extends WorkflowDomainError {
+export class RolesYamlNewRoleError extends VersionControlDomainError {
     roleNames;
     constructor(roleNames) {
         const quoted = roleNames.map((n) => `'${n}'`).join(', ');
@@ -137,7 +137,7 @@ export function assertNoNewRoles(current, candidate) {
  * entry with only a log warning — the role silently reaches nobody — so it is
  * refused up front, naming each entry, in the same 422 shape as the others.
  */
-export class RolesYamlUnknownGroupError extends WorkflowDomainError {
+export class RolesYamlUnknownGroupError extends VersionControlDomainError {
     entries;
     constructor(entries, sourceFile) {
         const listed = entries.map((e) => `'- ${e.entry}' under role '${e.role}'`).join(', ');

package/dist/modules/access-model/roles-yaml-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"roles-yaml-guard.js","sourceRoot":"","sources":["../../../src/modules/access-model/roles-yaml-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"roles-yaml-guard.js","sourceRoot":"","sources":["../../../src/modules/access-model/roles-yaml-guard.ts"],"names":[],"mappings":"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"}

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

@@ -20,10 +20,17 @@
  * 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.
+ * `{{agentsFile}}`), the checkout folder's `{{kbDirName}}` and the default
+ * branch's `{{defaultBranch}}`. 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.
+ *
+ * The guide is LAYERED (see openspec/changes/agent-guide-layers/design.md):
+ * `get_agent_guide` with no section answers with the short start section
+ * ({@link START_HERE_SECTION_ID}), which says which section answers which
+ * question, and an agent fetches the others by id when a task needs them.
+ * Each section has a token budget (`guide-budget.ts`), held by a test.
  */
 import { type KbLayout } from '@bevel-software/platform-shared';
 /** One section of the guide. */
@@ -48,6 +55,13 @@ export interface AgentGuideSection {
      * could only misread a folder name it STATES as a placeholder.
      */
     literal?: boolean;
+    /**
+     * The question this section answers, as a row of the start section's
+     * "which section answers what" table. Core's sections are in that table
+     * already; a distribution sets it on a section it adds, so an agent that
+     * reads only the start section is routed to it.
+     */
+    asks?: string;
 }
 /**
  * A distribution's say over the guide. Called with core's sections, in order,
@@ -67,6 +81,14 @@ export declare const WORKING_WITH_FILES_SECTION_ID = "working-with-files";
  * workspace/first-run.ts, which names it by this constant).
  */
 export declare const NEW_KNOWLEDGE_BASE_SECTION_ID = "new-knowledge-base";
+/**
+ * The first-contact section: what `get_agent_guide` answers when no section is
+ * named. Short on purpose, and the one place that maps each question to the
+ * section answering it, so an agent fetches one section rather than the guide.
+ */
+export declare const START_HERE_SECTION_ID = "start-here";
+/** The `section` that asks `get_agent_guide` for every section at once. */
+export declare const WHOLE_GUIDE_SECTION = "all";
 /**
  * Core's sections, in reading order. Every id but the shared-rules one names
  * a file in the package's `agent-guide/` folder.
@@ -77,9 +99,10 @@ export declare function isManagedGuide(text: string): boolean;
 /**
  * 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.
+ * is handed. `defaultBranch` is the branch the shared rules name (see
+ * {@link AgentGuideContext.defaultBranch}).
  */
-export declare function coreAgentGuideSections(layout: KbLayout): Promise<AgentGuideSection[]>;
+export declare function coreAgentGuideSections(layout: KbLayout, defaultBranch?: string): Promise<AgentGuideSection[]>;
 /** What the guide is composed for, beyond the layout. */
 export interface AgentGuideContext {
     /**
@@ -89,6 +112,14 @@ export interface AgentGuideContext {
      * deployment's tools report back.
      */
     kbDirName?: string;
+    /**
+     * The knowledge base's default branch, rendered into `{{defaultBranch}}` so
+     * the start section names the branch every file tool's `branch` takes for
+     * what is live, and named by the shared file rules in the same sentence the
+     * MCP handshake carries. Read when the guide is composed: a fresh deployment
+     * gets its branch model from the setup screen after the services are built.
+     */
+    defaultBranch?: string;
 }
 /** One section of the guide as an agent reads it: rendered, with the heading's text as its title. */
 export interface RenderedGuideSection {
@@ -106,16 +137,23 @@ export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
  * 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.
+ * A hook may append, replace and drop sections. It replaces one by returning
+ * its own under the same id, beside core's or in its place: of two sections
+ * under one id the LAST is served, where the FIRST stood, so a distribution
+ * overrides core's `start-here` or `html-views` by adding its own and the
+ * guide keeps its order (see {@link oneSectionPerId}). TWO exceptions, the
+ * sections something outside the guide points an agent at by id
+ * (`REQUIRED_SECTIONS`): the shared file rules
+ * ({@link WORKING_WITH_FILES_SECTION_ID}), which every file tool names — a
+ * client that drops the handshake instructions has the guide as the only
+ * place to read them — and the onboarding section
+ * ({@link ONBOARDING_GUIDE_SECTION_ID}), which the platform's `onboard`
+ * prompt sends an agent to. Each must come back WITH TEXT IN IT, as core's
+ * or as the hook's own replacement. A hook that drops one, 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 declare function agentGuideSections(layout: KbLayout, hook?: AgentGuideHook, context?: AgentGuideContext): Promise<RenderedGuideSection[]>;
 /**
@@ -123,16 +161,23 @@ export declare function agentGuideSections(layout: KbLayout, hook?: AgentGuideHo
  * ending in one newline.
  */
 export declare function composeAgentGuide(layout: KbLayout, hook?: AgentGuideHook, context?: AgentGuideContext): Promise<string>;
+/**
+ * What a `read_file` of the guide's name answers: the start section and the
+ * list of every section, the same as `get_agent_guide` with no `section`, so
+ * no read hands an agent the whole guide unless it asks for it. A guide
+ * without a start section (a distribution dropped it) is answered whole.
+ */
+export declare function guideStartText(sections: readonly RenderedGuideSection[]): string;
 /** The sections as one document, the way `composeAgentGuide` joins them. */
 export declare function joinGuideSections(sections: readonly RenderedGuideSection[]): string;
 /**
  * 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
+ * saying what follows, then the start of 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 declare 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 declare const PLATFORM_GUIDE_SEPARATOR = "---\n\n_The text above is this knowledge base's own conventions file. The start of the platform's guide follows; `get_agent_guide` with a `section` returns the rest._";
 export declare function withPlatformGuideAppended(ownText: string, guide: string): string;
 /** The one name the guide is read by: `AGENTS.md` at the repository root, the name coding agents look for. */
 export declare const AGENT_GUIDE_FILE = "AGENTS.md";

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

@@ -1 +1 @@
-{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAIzC,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,KACvB,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;AAE1E,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;AAErD,8DAA8D;AAC9D,eAAO,MAAM,6BAA6B,uBAAuB,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,uBAAuB,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAY5C,CAAC;AAmBH,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpD;AAiBD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe3F;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0FAA0F;AAC1F,MAAM,MAAM,wBAAwB,GAAG,MAAM,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,QAAQ,EAChB,IAAI,CAAC,EAAE,cAAc,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAuBjC;AAaD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,QAAQ,EAChB,IAAI,CAAC,EAAE,cAAc,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CAEnF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,kJAC4G,CAAC;AAElJ,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAShF;AAED,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAGlE"}
+{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.ts"],"names":[],"mappings":"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"}

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

@@ -20,39 +20,73 @@
  * 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.
+ * `{{agentsFile}}`), the checkout folder's `{{kbDirName}}` and the default
+ * branch's `{{defaultBranch}}`. 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.
+ *
+ * The guide is LAYERED (see openspec/changes/agent-guide-layers/design.md):
+ * `get_agent_guide` with no section answers with the short start section
+ * ({@link START_HERE_SECTION_ID}), which says which section answers which
+ * question, and an agent fetches the others by id when a task needs them.
+ * Each section has a token budget (`guide-budget.ts`), held by a test.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { renderKbLayoutPlaceholders, resolveKbLayout, } from '@bevel-software/platform-shared';
+import { ONBOARDING_GUIDE_SECTION_ID } from '@bevel-software/platform-mcp-core';
 import { agentGuideDir } from '../../assets.js';
 import { sharedFileRulesSection } from '../agent-instructions/index.js';
 /** The computed section: the rules every file tool shares. */
 export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
+/**
+ * The sections a hook may neither drop nor empty, because something outside
+ * the guide points an agent at them by id (see `composeAgentGuide`).
+ */
+const REQUIRED_SECTIONS = Object.freeze([
+    { id: WORKING_WITH_FILES_SECTION_ID, pointedAtBy: 'which every file tool points at', content: 'the rules' },
+    {
+        id: ONBOARDING_GUIDE_SECTION_ID,
+        pointedAtBy: "which the platform's `onboard` prompt points at",
+        content: 'an onboarding flow',
+    },
+]);
 /**
  * What to do on a knowledge base nobody has written in yet: the section the
  * `firstRun` note `start_session` answers with points at (see
  * workspace/first-run.ts, which names it by this constant).
  */
 export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
+/**
+ * The first-contact section: what `get_agent_guide` answers when no section is
+ * named. Short on purpose, and the one place that maps each question to the
+ * section answering it, so an agent fetches one section rather than the guide.
+ */
+export const START_HERE_SECTION_ID = 'start-here';
+/** The `section` that asks `get_agent_guide` for every section at once. */
+export const WHOLE_GUIDE_SECTION = 'all';
 /**
  * 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',
+    START_HERE_SECTION_ID,
+    // Named in mcp-core, where the platform's `/onboard` prompt points at it.
+    ONBOARDING_GUIDE_SECTION_ID,
+    'how-agents-find-things',
+    'for-git-users',
+    'glossary',
     'directory-structure',
     'where-a-new-file-goes',
     WORKING_WITH_FILES_SECTION_ID,
     'access-control',
+    'drafts-and-change-requests',
     'skills',
+    'tools',
     'tool-manuals',
     'html-views',
     'conventions',
-    'finding-things',
     NEW_KNOWLEDGE_BASE_SECTION_ID,
 ]);
 /**
@@ -89,9 +123,10 @@ async function readCoreSectionFiles() {
 /**
  * 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.
+ * is handed. `defaultBranch` is the branch the shared rules name (see
+ * {@link AgentGuideContext.defaultBranch}).
  */
-export async function coreAgentGuideSections(layout) {
+export async function coreAgentGuideSections(layout, defaultBranch = '') {
     coreSectionFiles ??= readCoreSectionFiles();
     let files;
     try {
@@ -103,48 +138,114 @@ export async function coreAgentGuideSections(layout) {
         throw err;
     }
     return CORE_SECTION_IDS.map((id) => id === WORKING_WITH_FILES_SECTION_ID
-        ? { id, body: sharedFileRulesSection(layout), literal: true }
+        ? { id, body: sharedFileRulesSection(layout, defaultBranch), 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';
+/** What `{{defaultBranch}}` reads as when no branch is configured yet: a name no branch can have. */
+const UNCONFIGURED_DEFAULT_BRANCH = '<the default branch>';
 /**
  * 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.
+ * A hook may append, replace and drop sections. It replaces one by returning
+ * its own under the same id, beside core's or in its place: of two sections
+ * under one id the LAST is served, where the FIRST stood, so a distribution
+ * overrides core's `start-here` or `html-views` by adding its own and the
+ * guide keeps its order (see {@link oneSectionPerId}). TWO exceptions, the
+ * sections something outside the guide points an agent at by id
+ * (`REQUIRED_SECTIONS`): the shared file rules
+ * ({@link WORKING_WITH_FILES_SECTION_ID}), which every file tool names — a
+ * client that drops the handshake instructions has the guide as the only
+ * place to read them — and the onboarding section
+ * ({@link ONBOARDING_GUIDE_SECTION_ID}), which the platform's `onboard`
+ * prompt sends an agent to. Each must come back WITH TEXT IN IT, as core's
+ * or as the hook's own replacement. A hook that drops one, 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 core = await coreAgentGuideSections(resolved, context.defaultBranch);
+    const sections = withRoutes(oneSectionPerId(hook ? await hook(core, resolved) : core));
     const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
+    const defaultBranch = context.defaultBranch?.trim() || UNCONFIGURED_DEFAULT_BRANCH;
     const rendered = sections.map((section) => {
         const body = (section.literal
             ? section.body
-            : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)).trim();
+            : renderKbLayoutPlaceholders(section.body
+                .replaceAll('{{kbDirName}}', () => kbDirName)
+                .replaceAll('{{defaultBranch}}', () => defaultBranch), 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.');
+    // One section per id by now (`oneSectionPerId`), so a hook's own version
+    // of the rules is what is judged, on what survives the empty-body filter
+    // below.
+    // Two sections something outside the guide points at, so a hook may not
+    // take them away: the file tools name the rules, and the platform's
+    // `onboard` prompt sends an agent to the onboarding section by id.
+    for (const required of REQUIRED_SECTIONS) {
+        const found = rendered.filter((section) => section.id === required.id);
+        if (!found.some((section) => section.body.length > 0)) {
+            throw new Error(`The agent guide hook ${found.length === 0 ? 'dropped' : 'emptied'} the "${required.id}" ` +
+                `section, ${required.pointedAtBy}. Keep it, or replace it under the same id with ${required.content} in it.`);
+        }
     }
     return rendered.filter((section) => section.body.length > 0);
 }
+/**
+ * One section per id. A hook that returns an id twice (its own version of a
+ * core section, added beside core's) means the later one: it is served in
+ * the earlier one's place, so a distribution overrides a section by adding
+ * its own under the same id, and the guide keeps core's order. Without this
+ * the whole guide carried both and `get_agent_guide` served the first, which
+ * was always core's.
+ */
+function oneSectionPerId(sections) {
+    const at = new Map();
+    const out = [];
+    for (const section of sections) {
+        const index = at.get(section.id);
+        if (index === undefined) {
+            at.set(section.id, out.length);
+            out.push(section);
+        }
+        else {
+            out[index] = section;
+        }
+    }
+    return out;
+}
+/**
+ * Adds a row to the start section's routing table for every section that
+ * says what it {@link AgentGuideSection.asks} and is not routed there yet.
+ * The rows go after the table's last row. A start section without the table
+ * (a distribution replaced it) is left as it is.
+ */
+function withRoutes(sections) {
+    const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+    if (!start)
+        return sections;
+    const routed = sections.filter((section) => section.asks?.trim() && !start.body.includes(`| \`${section.id}\` |`));
+    if (routed.length === 0)
+        return sections;
+    const lines = start.body.split('\n');
+    const header = lines.findIndex((line) => /^\|\s*Question\s*\|\s*Section\s*\|/.test(line));
+    if (header < 0)
+        return sections;
+    let last = header;
+    while (last + 1 < lines.length && lines[last + 1].startsWith('|'))
+        last += 1;
+    const rows = routed.map((section) => `| ${section.asks.trim().replaceAll('|', '\\|')} | \`${section.id}\` |`);
+    lines.splice(last + 1, 0, ...rows);
+    const body = lines.join('\n');
+    return sections.map((section) => (section === start ? { ...start, body } : section));
+}
 /**
  * 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
@@ -162,6 +263,19 @@ function titleOf(body, id) {
 export async function composeAgentGuide(layout, hook, context = {}) {
     return joinGuideSections(await agentGuideSections(layout, hook, context));
 }
+/**
+ * What a `read_file` of the guide's name answers: the start section and the
+ * list of every section, the same as `get_agent_guide` with no `section`, so
+ * no read hands an agent the whole guide unless it asks for it. A guide
+ * without a start section (a distribution dropped it) is answered whole.
+ */
+export function guideStartText(sections) {
+    const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+    if (!start)
+        return joinGuideSections(sections);
+    const list = sections.map((section) => `- \`${section.id}\`: ${section.title}`).join('\n');
+    return `${start.body}\n\n### Every section\n\n${list}\n`;
+}
 /** The sections as one document, the way `composeAgentGuide` joins them. */
 export function joinGuideSections(sections) {
     return `${sections.map((section) => section.body).join('\n\n')}\n`;
@@ -169,11 +283,11 @@ export function joinGuideSections(sections) {
 /**
  * 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
+ * saying what follows, then the start of 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 const PLATFORM_GUIDE_SEPARATOR = "---\n\n_The text above is this knowledge base's own conventions file. The start of the platform's guide follows; `get_agent_guide` with a `section` returns the rest._";
 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

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

@@ -1 +1 @@
-{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../../../src/modules/agent-guide/agent-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAgDxE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAElE;;;GAGG;AACH,MAAM,iBAAiB,GAAoE,MAAM,CAAC,MAAM,CAAC;IACvG,EAAE,EAAE,EAAE,6BAA6B,EAAE,WAAW,EAAE,iCAAiC,EAAE,OAAO,EAAE,WAAW,EAAE;IAC3G;QACE,EAAE,EAAE,2BAA2B;QAC/B,WAAW,EAAE,iDAAiD;QAC9D,OAAO,EAAE,oBAAoB;KAC9B;CACF,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAElE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAElD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC/D,qBAAqB;IACrB,0EAA0E;IAC1E,2BAA2B;IAC3B,wBAAwB;IACxB,eAAe;IACf,UAAU;IACV,qBAAqB;IACrB,uBAAuB;IACvB,6BAA6B;IAC7B,gBAAgB;IAChB,4BAA4B;IAC5B,QAAQ;IACR,OAAO;IACP,cAAc;IACd,YAAY;IACZ,aAAa;IACb,6BAA6B;CAC9B,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;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAgB,EAAE,aAAa,GAAG,EAAE;IAC/E,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,EAAE,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;QAC5E,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAE,EAAE,CACjC,CAAC;AACJ,CAAC;AAqBD,0EAA0E;AAC1E,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAE7C,qGAAqG;AACrG,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAc3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACvF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,mBAAmB,CAAC;IACnE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,2BAA2B,CAAC;IACnF,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,CACxB,OAAO,CAAC,IAAI;iBACT,UAAU,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC;iBAC5C,UAAU,CAAC,mBAAmB,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,EACvD,QAAQ,CACT,CACN,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,yEAAyE;IACzE,yEAAyE;IACzE,SAAS;IACT,wEAAwE;IACxE,oEAAoE;IACpE,mEAAmE;IACnE,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACb,wBAAwB,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,SAAS,QAAQ,CAAC,EAAE,IAAI;gBACxF,YAAY,QAAQ,CAAC,WAAW,mDAAmD,QAAQ,CAAC,OAAO,SAAS,CAC/G,CAAC;QACJ,CAAC;IACH,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;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,QAAsC;IAC7D,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,QAAsC;IACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,qBAAqB,CAAC,CAAC;IAC/E,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACnH,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1F,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,OAAO,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,CAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,IAAI,IAAI,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,IAAK,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/G,KAAK,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACvF,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;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAyC;IACtE,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,qBAAqB,CAAC,CAAC;IAC/E,IAAI,CAAC,KAAK;QAAE,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,OAAO,CAAC,EAAE,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3F,OAAO,GAAG,KAAK,CAAC,IAAI,4BAA4B,IAAI,IAAI,CAAC;AAC3D,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,wKAAwK,CAAC;AAE3K,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

@@ -5,8 +5,12 @@ import type { ToolHandlerFactory } from '../tool-helpers/index.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
+ * The one tool that returns the guide on its own: the start section when no
+ * section is named, one section by id, or the whole guide (`all`). Start
+ * section by default because this is the call every tool description tells
+ * an agent, and each sub-agent it starts, to make first: answering it with
+ * the whole guide made the most-read text the platform has also its longest.
+ * 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

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

@@ -1 +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,2BAA2B,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAwB,MAAM,2BAA2B,CAAC;AAEvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,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,CAmGN"}
+{"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,2BAA2B,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAwB,MAAM,2BAA2B,CAAC;AAEvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAKL,KAAK,wBAAwB,EAC9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;GAmBG;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,CA2GN"}