@promptbook/core 0.112.0-64 → 0.112.0-66

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('crypto-js'), require('crypto-js/enc-hex'), require('spacetrim'), require('crypto'), require('rxjs'), require('waitasecond'), require('crypto-js/sha256'), require('path'), require('mime-types'), require('papaparse'), require('moment'), require('colors'), require('@openai/agents'), require('bottleneck'), require('openai')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'crypto-js', 'crypto-js/enc-hex', 'spacetrim', 'crypto', 'rxjs', 'waitasecond', 'crypto-js/sha256', 'path', 'mime-types', 'papaparse', 'moment', 'colors', '@openai/agents', 'bottleneck', 'openai'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-core"] = {}, global.cryptoJs, global.hexEncoder, global.spacetrim, global.crypto, global.rxjs, global.waitasecond, global.sha256, global.path, global.mimeTypes, global.papaparse, global.moment, global.colors, global.agents, global.Bottleneck, global.OpenAI));
-})(this, (function (exports, cryptoJs, hexEncoder, spacetrim, crypto, rxjs, waitasecond, sha256, path, mimeTypes, papaparse, moment, colors, agents, Bottleneck, OpenAI) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('crypto-js'), require('crypto-js/enc-hex'), require('spacetrim'), require('path'), require('crypto'), require('rxjs'), require('waitasecond'), require('crypto-js/sha256'), require('mime-types'), require('papaparse'), require('moment'), require('colors'), require('@openai/agents'), require('bottleneck'), require('openai')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'crypto-js', 'crypto-js/enc-hex', 'spacetrim', 'path', 'crypto', 'rxjs', 'waitasecond', 'crypto-js/sha256', 'mime-types', 'papaparse', 'moment', 'colors', '@openai/agents', 'bottleneck', 'openai'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-core"] = {}, global.cryptoJs, global.hexEncoder, global.spacetrim, global.path, global.crypto, global.rxjs, global.waitasecond, global.sha256, global.mimeTypes, global.papaparse, global.moment, global.colors, global.agents, global.Bottleneck, global.OpenAI));
+})(this, (function (exports, cryptoJs, hexEncoder, spacetrim, path, crypto, rxjs, waitasecond, sha256, mimeTypes, papaparse, moment, colors, agents, Bottleneck, OpenAI) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -27,7 +27,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-64';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-66';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -946,6 +946,29 @@
     }
     // TODO: Maybe implement by mix+hsl
 
+    /**
+     * Relative directory name without the `./` prefix for Git ignore rules and glob patterns.
+     *
+     * @private internal utility for Promptbook-owned temp files
+     */
+    const PROMPTBOOK_TEMP_DIRECTORY_NAME = '.promptbook';
+    /**
+     * Builds one project-relative path inside the shared Promptbook working directory.
+     *
+     * @private internal utility for Promptbook-owned temp files
+     */
+    function getPromptbookTempPath(...pathSegments) {
+        return `./${getPromptbookTempPosixPath(...pathSegments)}`;
+    }
+    /**
+     * Builds one POSIX path fragment inside the shared Promptbook working directory for globs and generated text files.
+     *
+     * @private internal utility for Promptbook-owned temp files
+     */
+    function getPromptbookTempPosixPath(...pathSegments) {
+        return path.posix.join(PROMPTBOOK_TEMP_DIRECTORY_NAME, ...pathSegments);
+    }
+
     /**
      * Returns the same value that is passed as argument.
      * No side effects.
@@ -1216,7 +1239,6 @@
      */
     const DEFAULT_AGENTS_DIRNAME = './agents';
     // <- TODO: [🕝] Make also `AGENTS_DIRNAME_ALTERNATIVES`
-    // TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
     /**
      * Where to store the temporary downloads
      *
@@ -1224,7 +1246,7 @@
      *
      * @public exported from `@promptbook/core`
      */
-    const DEFAULT_DOWNLOAD_CACHE_DIRNAME = './.promptbook/download-cache';
+    const DEFAULT_DOWNLOAD_CACHE_DIRNAME = getPromptbookTempPath('download-cache');
     /**
      * Where to store the cache of executions for promptbook CLI
      *
@@ -1232,7 +1254,7 @@
      *
      * @public exported from `@promptbook/core`
      */
-    const DEFAULT_EXECUTION_CACHE_DIRNAME = './.promptbook/execution-cache';
+    const DEFAULT_EXECUTION_CACHE_DIRNAME = getPromptbookTempPath('execution-cache');
     /**
      * Where to store the scrape cache
      *
@@ -1240,7 +1262,7 @@
      *
      * @public exported from `@promptbook/core`
      */
-    const DEFAULT_SCRAPE_CACHE_DIRNAME = './.promptbook/scrape-cache';
+    const DEFAULT_SCRAPE_CACHE_DIRNAME = getPromptbookTempPath('scrape-cache');
     /**
      * Id of application for the CLI when using remote server
      *
@@ -12087,18 +12109,6 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
-    /**
-     * Name of the tool used by agents to search configured `KNOWLEDGE` sources.
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const KNOWLEDGE_SEARCH_TOOL_NAME = 'knowledge_search';
-    /**
-     * Title of the system-message section generated for `KNOWLEDGE` commitments.
-     *
-     * @private constant of `KnowledgeCommitmentDefinition`
-     */
-    const KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE = 'Knowledge Search';
     /**
      * KNOWLEDGE commitment definition
      *
@@ -12220,17 +12230,9 @@
                 knowledgeInfoEntries.push(`Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`);
             }
             if (knowledgeInfoEntries.length === 0) {
-                return addKnowledgeSearchToolAndSystemSection(nextRequirements);
+                return nextRequirements;
             }
-            return addKnowledgeSearchToolAndSystemSection(nextRequirements);
-        }
-        /**
-         * Gets human-readable titles for tool functions provided by this commitment.
-         */
-        getToolTitles() {
-            return {
-                [KNOWLEDGE_SEARCH_TOOL_NAME]: 'Knowledge search',
-            };
+            return this.appendToSystemMessage(nextRequirements, knowledgeInfoEntries.join('\n'), '\n\n');
         }
     }
     /**
@@ -12244,128 +12246,6 @@
         const significantText = contentWithoutUrls.replace(/[\s.,!?;:'"`()[\]{}<>/-]+/g, '');
         return significantText.length > 0;
     }
-    /**
-     * Adds the shared `knowledge_search` tool definition and the consolidated system-message section.
-     *
-     * @param requirements - Requirements after one `KNOWLEDGE` commitment was applied.
-     * @returns Requirements with the knowledge search instructions and tool definition.
-     *
-     * @private internal utility of `KnowledgeCommitmentDefinition`
-     */
-    function addKnowledgeSearchToolAndSystemSection(requirements) {
-        const nextRequirements = addKnowledgeSearchTool(requirements);
-        const section = createKnowledgeSearchSystemSection(nextRequirements);
-        const sectionHeader = `## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE}`;
-        if (nextRequirements.systemMessage.includes(sectionHeader)) {
-            return {
-                ...nextRequirements,
-                systemMessage: nextRequirements.systemMessage.replace(new RegExp(`## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?(?=\\n\\n##|$)`), section),
-            };
-        }
-        return {
-            ...nextRequirements,
-            systemMessage: nextRequirements.systemMessage.trim()
-                ? `${nextRequirements.systemMessage}\n\n${section}`
-                : section,
-        };
-    }
-    /**
-     * Adds the `knowledge_search` model tool when it is not already present.
-     *
-     * @param requirements - Current model requirements.
-     * @returns Requirements with the tool definition available to the model.
-     *
-     * @private internal utility of `KnowledgeCommitmentDefinition`
-     */
-    function addKnowledgeSearchTool(requirements) {
-        const existingTools = requirements.tools || [];
-        if (existingTools.some((tool) => tool.name === KNOWLEDGE_SEARCH_TOOL_NAME)) {
-            return requirements;
-        }
-        return {
-            ...requirements,
-            tools: [
-                ...existingTools,
-                {
-                    name: KNOWLEDGE_SEARCH_TOOL_NAME,
-                    description: spacetrim.spaceTrim(`
-                    Search the agent's configured knowledge sources and return relevant excerpts with citation ids.
-                    Use this before answering questions that may depend on the agent's KNOWLEDGE commitments.
-                `),
-                    parameters: {
-                        type: 'object',
-                        properties: {
-                            query: {
-                                type: 'string',
-                                description: 'The natural-language search query for the knowledge base.',
-                            },
-                            limit: {
-                                type: 'integer',
-                                description: 'Maximum number of matching source excerpts to return.',
-                            },
-                        },
-                        required: ['query'],
-                    },
-                },
-            ],
-        };
-    }
-    /**
-     * Creates the model-facing system-message section for knowledge search.
-     *
-     * @param requirements - Current model requirements.
-     * @returns Markdown system-message section.
-     *
-     * @private internal utility of `KnowledgeCommitmentDefinition`
-     */
-    function createKnowledgeSearchSystemSection(requirements) {
-        const sourceEntries = createKnowledgeSourceSystemEntries(requirements);
-        const sourceList = sourceEntries.length > 0 ? sourceEntries.map((entry) => `-   ${entry}`).join('\n') : '-   None';
-        return spacetrim.spaceTrim(`
-        ## ${KNOWLEDGE_SEARCH_SYSTEM_SECTION_TITLE}
-
-        -   Use \`${KNOWLEDGE_SEARCH_TOOL_NAME}\` to search the configured knowledge sources before answering questions that depend on this agent's knowledge base.
-        -   Base source-backed factual answers on the returned excerpts.
-        -   When you use a returned excerpt, include its citation marker in the answer body, for example \`[0:0]\`.
-        -   If the search returns no relevant information, say that the knowledge base did not contain the answer instead of inventing it.
-
-        Configured knowledge sources:
-        ${sourceList}
-    `);
-    }
-    /**
-     * Builds a stable list of configured knowledge sources for system-message diagnostics.
-     *
-     * @param requirements - Current model requirements.
-     * @returns Human-readable source entries.
-     *
-     * @private internal utility of `KnowledgeCommitmentDefinition`
-     */
-    function createKnowledgeSourceSystemEntries(requirements) {
-        var _a;
-        const entries = [];
-        const seenEntries = new Set();
-        for (const source of requirements.knowledgeSources || []) {
-            const entry = `Source URL: ${source} (processed for retrieval during chat)`;
-            if (seenEntries.has(entry)) {
-                continue;
-            }
-            seenEntries.add(entry);
-            entries.push(entry);
-        }
-        const inlineSources = (((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.inlineKnowledgeSources) || [])
-            .map((source) => source.filename)
-            .filter(Boolean);
-        for (const filename of inlineSources) {
-            const entry = `Knowledge Source Inline: ${filename} (Inline source: processed for retrieval during chat)`;
-            if (seenEntries.has(entry)) {
-                continue;
-            }
-            seenEntries.add(entry);
-            entries.push(entry);
-        }
-        return entries;
-    }
 
     /**
      * LANGUAGE commitment definition
@@ -14998,6 +14878,177 @@
         context.restore();
     }
 
+    /* eslint-disable no-magic-numbers */
+    /**
+     * Builds the seeded six-face texture pack used by the Minecraft-style head cuboid.
+     *
+     * @param random Seeded random generator.
+     * @param palette Derived avatar palette.
+     * @param hasHeadband Whether the generated avatar should include a colored headband.
+     * @returns Head cuboid textures.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function createMinecraftHeadTextures(random, palette, hasHeadband) {
+        const faceTexture = createMinecraftFaceTexture(random, palette, hasHeadband);
+        const hairColor = random() < 0.5 ? palette.primary : palette.secondary;
+        const skinColor = palette.highlight;
+        const headbandColor = hasHeadband ? palette.accent : hairColor;
+        const sideTexture = createFilledTexture(skinColor);
+        const backTexture = createFilledTexture(skinColor);
+        const topTexture = createFilledTexture(hairColor);
+        const bottomTexture = createFilledTexture(`${palette.shadow}cc`);
+        fillTextureRect(sideTexture, 0, 0, 8, 3, hairColor);
+        fillTextureRect(backTexture, 0, 0, 8, 5, hairColor);
+        fillTextureRect(backTexture, 1, 5, 6, 1, hairColor);
+        if (hasHeadband) {
+            fillTextureRect(sideTexture, 0, 2, 8, 1, headbandColor);
+            fillTextureRect(backTexture, 0, 2, 8, 1, headbandColor);
+            fillTextureRect(topTexture, 0, 4, 8, 1, headbandColor);
+        }
+        sideTexture[4][4] = `${palette.shadow}99`;
+        sideTexture[5][4] = `${palette.shadow}cc`;
+        backTexture[6][2] = `${palette.shadow}99`;
+        backTexture[6][5] = `${palette.shadow}99`;
+        return {
+            front: faceTexture,
+            back: backTexture,
+            left: sideTexture,
+            right: mirrorMinecraftTexture(sideTexture),
+            top: topTexture,
+            bottom: bottomTexture,
+        };
+    }
+    /**
+     * Builds the seeded six-face texture pack used by the Minecraft-style torso cuboid.
+     *
+     * @param random Seeded random generator.
+     * @param palette Derived avatar palette.
+     * @returns Torso cuboid textures.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function createMinecraftTorsoTextures(random, palette) {
+        const frontTexture = createMinecraftShirtTexture(random, palette);
+        const sideTexture = createFilledTexture(palette.primary);
+        const backTexture = createFilledTexture(palette.primary);
+        const topTexture = createFilledTexture(`${palette.highlight}dd`);
+        const bottomTexture = createFilledTexture(`${palette.shadow}dd`);
+        const stripeColor = random() < 0.5 ? palette.secondary : palette.highlight;
+        fillTextureRect(sideTexture, 0, 0, 8, 2, palette.shadow);
+        fillTextureRect(backTexture, 0, 0, 8, 2, palette.shadow);
+        fillTextureRect(backTexture, 3, 2, 2, 6, stripeColor);
+        fillTextureRect(sideTexture, 4, 2, 1, 6, stripeColor);
+        fillTextureRect(topTexture, 0, 0, 8, 2, palette.shadow);
+        fillTextureRect(topTexture, 2, 2, 4, 4, stripeColor);
+        return {
+            front: frontTexture,
+            back: backTexture,
+            left: sideTexture,
+            right: mirrorMinecraftTexture(sideTexture),
+            top: topTexture,
+            bottom: bottomTexture,
+        };
+    }
+    /**
+     * Mirrors one Minecraft texture horizontally.
+     *
+     * @param texture Source texture.
+     * @returns Mirrored texture copy.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function mirrorMinecraftTexture(texture) {
+        return texture.map((row) => [...row].reverse());
+    }
+    /**
+     * Creates the front-face pixel texture for the cube head.
+     *
+     * @param random Seeded random generator.
+     * @param palette Derived avatar palette.
+     * @param hasHeadband Whether the avatar should render a headband row.
+     * @returns 8x8 pixel texture.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function createMinecraftFaceTexture(random, palette, hasHeadband) {
+        const texture = createFilledTexture(palette.highlight);
+        const hairlineColor = random() < 0.5 ? palette.primary : palette.secondary;
+        const cheekColor = random() < 0.5 ? `${palette.accent}bb` : `${palette.secondary}bb`;
+        fillTextureRect(texture, 0, 0, 8, 2, hairlineColor);
+        texture[2][0] = hairlineColor;
+        texture[2][7] = hairlineColor;
+        texture[3][0] = hairlineColor;
+        texture[3][7] = hairlineColor;
+        if (hasHeadband) {
+            fillTextureRect(texture, 0, 2, 8, 1, palette.accent);
+        }
+        texture[3][2] = palette.ink;
+        texture[3][5] = palette.ink;
+        texture[4][2] = '#ffffff';
+        texture[4][5] = '#ffffff';
+        texture[5][1] = cheekColor;
+        texture[5][6] = cheekColor;
+        texture[5][3] = palette.shadow;
+        texture[5][4] = palette.shadow;
+        texture[6][3] = palette.shadow;
+        texture[6][4] = palette.shadow;
+        return texture;
+    }
+    /**
+     * Creates the front-face pixel texture for the torso.
+     *
+     * @param random Seeded random generator.
+     * @param palette Derived avatar palette.
+     * @returns 8x8 torso texture.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function createMinecraftShirtTexture(random, palette) {
+        const texture = createFilledTexture(palette.primary);
+        const stripeColor = random() < 0.5 ? palette.secondary : palette.highlight;
+        fillTextureRect(texture, 0, 0, 8, 2, palette.shadow);
+        for (let rowIndex = 2; rowIndex < 8; rowIndex++) {
+            texture[rowIndex][3] = stripeColor;
+            texture[rowIndex][4] = stripeColor;
+        }
+        texture[4][1] = palette.accent;
+        texture[4][6] = palette.accent;
+        texture[5][2] = palette.highlight;
+        texture[5][5] = palette.highlight;
+        return texture;
+    }
+    /**
+     * Creates one solid-color 8x8 Minecraft texture.
+     *
+     * @param color Fill color.
+     * @returns Filled 8x8 texture.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function createFilledTexture(color) {
+        return Array.from({ length: 8 }, () => Array.from({ length: 8 }, () => color));
+    }
+    /**
+     * Fills one rectangular area inside a mutable Minecraft texture.
+     *
+     * @param texture Mutable target texture.
+     * @param x Left texture coordinate.
+     * @param y Top texture coordinate.
+     * @param width Rectangle width.
+     * @param height Rectangle height.
+     * @param color Fill color.
+     *
+     * @private helper of the Minecraft avatar visuals
+     */
+    function fillTextureRect(texture, x, y, width, height, color) {
+        for (let rowIndex = y; rowIndex < y + height; rowIndex++) {
+            for (let columnIndex = x; columnIndex < x + width; columnIndex++) {
+                texture[rowIndex][columnIndex] = color;
+            }
+        }
+    }
+
     /* eslint-disable no-magic-numbers */
     /**
      * Minecraft-style 3D avatar visual.
@@ -15022,8 +15073,8 @@
             const bodyX = size * 0.33;
             const bodyY = headY + headSize * 0.96;
             const hasHeadband = random() < 0.5;
-            const faceTexture = createMinecraftFaceTexture(createRandom('minecraft-face'), palette, hasHeadband);
-            const shirtTexture = createMinecraftShirtTexture(createRandom('minecraft-shirt'), palette);
+            const headTextures = createMinecraftHeadTextures(createRandom('minecraft-face'), palette, hasHeadband);
+            const torsoTextures = createMinecraftTorsoTextures(createRandom('minecraft-shirt'), palette);
             drawAvatarFrame(context, size, palette);
             const spotlight = context.createRadialGradient(size * 0.5, size * 0.18, size * 0.05, size * 0.5, size * 0.18, size * 0.5);
             spotlight.addColorStop(0, `${palette.highlight}66`);
@@ -15043,7 +15094,7 @@
                 width: bodyWidth,
                 height: bodyHeight,
                 depth: bodyDepth,
-                frontTexture: shirtTexture,
+                frontTexture: torsoTextures.front,
                 topColor: `${palette.highlight}cc`,
                 sideColor: `${palette.secondary}dd`,
                 outlineColor: `${palette.shadow}aa`,
@@ -15054,7 +15105,7 @@
                 width: headSize,
                 height: headSize,
                 depth,
-                frontTexture: faceTexture,
+                frontTexture: headTextures.front,
                 topColor: `${palette.highlight}ee`,
                 sideColor: `${palette.secondary}ee`,
                 outlineColor: `${palette.shadow}cc`,
@@ -15119,72 +15170,505 @@
         context.closePath();
         context.stroke();
     }
+
+    /* eslint-disable no-magic-numbers */
     /**
-     * Creates the front-face pixel texture for the cube head.
+     * Fixed scene camera distance used for the proper-3D projection.
      *
-     * @param random Seeded random generator.
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    const CAMERA_DISTANCE_RATIO = 1.4;
+    /**
+     * Shared light direction used to shade projected cuboid faces.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    const LIGHT_DIRECTION = normalizeVector3({
+        x: 0.4,
+        y: -0.65,
+        z: 0.92,
+    });
+    /**
+     * Minecraft 3D 2 avatar visual.
+     *
+     * @private built-in avatar visual
+     */
+    const minecraft2AvatarVisual = {
+        id: 'minecraft2',
+        title: 'Minecraft 3D 2',
+        description: 'Proper 3D Minecraft-style portrait with textured cuboids and pointer-driven head turns.',
+        isAnimated: true,
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
+            const spotlightY = size * 0.22;
+            const headRandom = createRandom('minecraft2-head');
+            const hasHeadband = headRandom() < 0.5;
+            const headTextures = createMinecraftHeadTextures(createRandom('minecraft2-head-textures'), palette, hasHeadband);
+            const torsoTextures = createMinecraftTorsoTextures(createRandom('minecraft2-body-textures'), palette);
+            const bob = Math.sin(timeMs / 880) * size * 0.014;
+            const bodyYaw = -0.24 + Math.sin(timeMs / 2300) * 0.06 + interaction.bodyOffsetX * 0.16;
+            const bodyPitch = -0.12 + Math.cos(timeMs / 2800) * 0.02 - interaction.bodyOffsetY * 0.06;
+            const headYaw = -0.18 + Math.sin(timeMs / 1900 + 0.6) * 0.05 + interaction.gazeX * 0.62;
+            const headPitch = -0.12 + Math.cos(timeMs / 2400 + 1.1) * 0.03 - interaction.gazeY * 0.38;
+            const sceneCenterX = size * 0.5;
+            const sceneCenterY = size * 0.57;
+            const bodyWidth = size * 0.225;
+            const bodyHeight = size * 0.245;
+            const bodyDepth = size * 0.145;
+            const headSize = size * 0.24;
+            const headLift = size * 0.205;
+            const headForwardShift = interaction.intensity * size * 0.018;
+            const sceneCuboids = [
+                {
+                    center: {
+                        x: interaction.bodyOffsetX * size * 0.026,
+                        y: size * 0.05 + interaction.bodyOffsetY * size * 0.018 + bob,
+                        z: 0,
+                    },
+                    width: bodyWidth,
+                    height: bodyHeight,
+                    depth: bodyDepth,
+                    rotationX: bodyPitch,
+                    rotationY: bodyYaw,
+                    textures: torsoTextures,
+                    outlineColor: `${palette.shadow}cc`,
+                },
+                {
+                    center: {
+                        x: interaction.bodyOffsetX * size * 0.018 + interaction.gazeX * size * 0.016,
+                        y: -headLift + bob * 1.15,
+                        z: headForwardShift,
+                    },
+                    width: headSize,
+                    height: headSize,
+                    depth: headSize,
+                    rotationX: headPitch,
+                    rotationY: headYaw,
+                    textures: headTextures,
+                    outlineColor: `${palette.shadow}dd`,
+                },
+            ];
+            const visibleFaces = sceneCuboids
+                .flatMap((cuboid) => resolveVisibleCuboidFaces(cuboid, size, sceneCenterX, sceneCenterY))
+                .sort((firstFace, secondFace) => firstFace.averageDepth - secondFace.averageDepth);
+            drawAvatarFrame(context, size, palette);
+            drawMinecraftBackdrop(context, size, palette, sceneCenterX, spotlightY, interaction, timeMs);
+            drawMinecraftShadow(context, size, palette, interaction, timeMs);
+            for (const visibleFace of visibleFaces) {
+                drawTexturedProjectedFace(context, visibleFace);
+            }
+        },
+    };
+    /**
+     * Draws the shared background atmosphere behind the Minecraft 3D 2 portrait.
+     *
+     * @param context Canvas 2D context.
+     * @param size Canvas size in CSS pixels.
      * @param palette Derived avatar palette.
-     * @param hasHeadband Whether the avatar should render a headband row.
-     * @returns 8x8 pixel texture.
+     * @param sceneCenterX Horizontal scene center.
+     * @param spotlightY Vertical spotlight anchor.
+     * @param interaction Smoothed pointer-aware interaction state.
+     * @param timeMs Current animation time in milliseconds.
      *
-     * @private helper of `minecraftAvatarVisual`
+     * @private helper of `minecraft2AvatarVisual`
      */
-    function createMinecraftFaceTexture(random, palette, hasHeadband) {
-        const texture = Array.from({ length: 8 }, () => Array.from({ length: 8 }, () => palette.highlight));
-        const hairlineColor = random() < 0.5 ? palette.primary : palette.secondary;
-        const cheekColor = random() < 0.5 ? `${palette.accent}bb` : `${palette.secondary}bb`;
-        for (let rowIndex = 0; rowIndex < 2; rowIndex++) {
-            for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
-                texture[rowIndex][columnIndex] = hairlineColor;
+    function drawMinecraftBackdrop(context, size, palette, sceneCenterX, spotlightY, interaction, timeMs) {
+        const spotlightGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.08, spotlightY + interaction.gazeY * size * 0.05, size * 0.03, sceneCenterX, spotlightY, size * 0.52);
+        spotlightGradient.addColorStop(0, `${palette.highlight}66`);
+        spotlightGradient.addColorStop(0.42, `${palette.accent}1d`);
+        spotlightGradient.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = spotlightGradient;
+        context.fillRect(0, 0, size, size);
+        const rimGradient = context.createLinearGradient(0, size * 0.14, 0, size * 0.92);
+        rimGradient.addColorStop(0, `${palette.highlight}12`);
+        rimGradient.addColorStop(0.55, `${palette.secondary}0a`);
+        rimGradient.addColorStop(1, `${palette.shadow}00`);
+        context.fillStyle = rimGradient;
+        context.fillRect(0, 0, size, size);
+        context.save();
+        context.globalAlpha = 0.08 + interaction.intensity * 0.04;
+        context.fillStyle = palette.highlight;
+        context.beginPath();
+        context.arc(size * 0.72 + Math.sin(timeMs / 1600) * size * 0.03, size * 0.2 + Math.cos(timeMs / 1400) * size * 0.018, size * 0.025, 0, Math.PI * 2);
+        context.fill();
+        context.restore();
+    }
+    /**
+     * Draws the soft floor shadow used to anchor the cuboids in the frame.
+     *
+     * @param context Canvas 2D context.
+     * @param size Canvas size in CSS pixels.
+     * @param palette Derived avatar palette.
+     * @param interaction Smoothed pointer-aware interaction state.
+     * @param timeMs Current animation time in milliseconds.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function drawMinecraftShadow(context, size, palette, interaction, timeMs) {
+        context.save();
+        context.fillStyle = `${palette.shadow}66`;
+        context.filter = `blur(${size * 0.02}px)`;
+        context.beginPath();
+        context.ellipse(size * 0.5 + interaction.gazeX * size * 0.03, size * 0.85 + Math.sin(timeMs / 880) * size * 0.01, size * (0.16 + interaction.intensity * 0.015), size * 0.055, 0, 0, Math.PI * 2);
+        context.fill();
+        context.restore();
+    }
+    /**
+     * Resolves all visible projected faces for one scene cuboid.
+     *
+     * @param cuboid Scene cuboid definition.
+     * @param size Canvas size in CSS pixels.
+     * @param sceneCenterX Horizontal scene center.
+     * @param sceneCenterY Vertical scene center.
+     * @returns Visible faces sorted later by depth.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function resolveVisibleCuboidFaces(cuboid, size, sceneCenterX, sceneCenterY) {
+        const halfWidth = cuboid.width / 2;
+        const halfHeight = cuboid.height / 2;
+        const halfDepth = cuboid.depth / 2;
+        const faceDefinitions = [
+            {
+                texture: cuboid.textures.front,
+                corners: [
+                    { x: -halfWidth, y: -halfHeight, z: halfDepth },
+                    { x: halfWidth, y: -halfHeight, z: halfDepth },
+                    { x: halfWidth, y: halfHeight, z: halfDepth },
+                    { x: -halfWidth, y: halfHeight, z: halfDepth },
+                ],
+            },
+            {
+                texture: cuboid.textures.back,
+                corners: [
+                    { x: halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: -halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: -halfWidth, y: halfHeight, z: -halfDepth },
+                    { x: halfWidth, y: halfHeight, z: -halfDepth },
+                ],
+            },
+            {
+                texture: cuboid.textures.right,
+                corners: [
+                    { x: halfWidth, y: -halfHeight, z: halfDepth },
+                    { x: halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: halfWidth, y: halfHeight, z: -halfDepth },
+                    { x: halfWidth, y: halfHeight, z: halfDepth },
+                ],
+            },
+            {
+                texture: cuboid.textures.left,
+                corners: [
+                    { x: -halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: -halfWidth, y: -halfHeight, z: halfDepth },
+                    { x: -halfWidth, y: halfHeight, z: halfDepth },
+                    { x: -halfWidth, y: halfHeight, z: -halfDepth },
+                ],
+            },
+            {
+                texture: cuboid.textures.top,
+                corners: [
+                    { x: -halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: halfWidth, y: -halfHeight, z: -halfDepth },
+                    { x: halfWidth, y: -halfHeight, z: halfDepth },
+                    { x: -halfWidth, y: -halfHeight, z: halfDepth },
+                ],
+            },
+            {
+                texture: cuboid.textures.bottom,
+                corners: [
+                    { x: -halfWidth, y: halfHeight, z: halfDepth },
+                    { x: halfWidth, y: halfHeight, z: halfDepth },
+                    { x: halfWidth, y: halfHeight, z: -halfDepth },
+                    { x: -halfWidth, y: halfHeight, z: -halfDepth },
+                ],
+            },
+        ];
+        const visibleFaces = faceDefinitions
+            .map((faceDefinition) => {
+            const transformedCorners = faceDefinition.corners.map((corner) => transformScenePoint(corner, cuboid.center, cuboid.rotationX, cuboid.rotationY));
+            const faceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
+            if (faceNormal.z <= 0.02) {
+                return null;
             }
+            const projectedCorners = transformedCorners.map((corner) => projectScenePoint(corner, size, sceneCenterX, sceneCenterY));
+            return {
+                corners: projectedCorners,
+                texture: faceDefinition.texture,
+                averageDepth: transformedCorners.reduce((depthSum, corner) => depthSum + corner.z, 0) / transformedCorners.length,
+                lightIntensity: clampNumber$1(dotProduct3D(faceNormal, LIGHT_DIRECTION), -1, 1),
+                outlineColor: cuboid.outlineColor,
+            };
+        });
+        return visibleFaces.filter((visibleFace) => visibleFace !== null);
+    }
+    /**
+     * Draws one projected textured face by tessellating its texture cells into quads.
+     *
+     * @param context Canvas 2D context.
+     * @param face Visible projected face.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function drawTexturedProjectedFace(context, face) {
+        var _a;
+        const rows = face.texture.length;
+        const columns = ((_a = face.texture[0]) === null || _a === void 0 ? void 0 : _a.length) || 0;
+        if (rows === 0 || columns === 0) {
+            return;
         }
-        texture[2][0] = hairlineColor;
-        texture[2][7] = hairlineColor;
-        texture[3][0] = hairlineColor;
-        texture[3][7] = hairlineColor;
-        if (hasHeadband) {
-            for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
-                texture[2][columnIndex] = palette.accent;
+        for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+            for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
+                const startX = columnIndex / columns;
+                const endX = (columnIndex + 1) / columns;
+                const startY = rowIndex / rows;
+                const endY = (rowIndex + 1) / rows;
+                drawProjectedQuad(context, [
+                    interpolateProjectedQuad(face.corners, startX, startY),
+                    interpolateProjectedQuad(face.corners, endX, startY),
+                    interpolateProjectedQuad(face.corners, endX, endY),
+                    interpolateProjectedQuad(face.corners, startX, endY),
+                ], face.texture[rowIndex][columnIndex]);
             }
         }
-        texture[3][2] = palette.ink;
-        texture[3][5] = palette.ink;
-        texture[4][2] = '#ffffff';
-        texture[4][5] = '#ffffff';
-        texture[5][1] = cheekColor;
-        texture[5][6] = cheekColor;
-        texture[5][3] = palette.shadow;
-        texture[5][4] = palette.shadow;
-        texture[6][3] = palette.shadow;
-        texture[6][4] = palette.shadow;
-        return texture;
+        if (face.lightIntensity > 0) {
+            drawProjectedQuad(context, face.corners, `rgba(255, 255, 255, ${0.15 * face.lightIntensity})`);
+        }
+        else if (face.lightIntensity < 0) {
+            drawProjectedQuad(context, face.corners, `rgba(0, 0, 0, ${0.22 * Math.abs(face.lightIntensity)})`);
+        }
+        context.save();
+        context.beginPath();
+        context.moveTo(face.corners[0].x, face.corners[0].y);
+        for (let cornerIndex = 1; cornerIndex < face.corners.length; cornerIndex++) {
+            context.lineTo(face.corners[cornerIndex].x, face.corners[cornerIndex].y);
+        }
+        context.closePath();
+        context.strokeStyle = face.outlineColor;
+        context.lineWidth = Math.max(1.1, getProjectedQuadPerimeter(face.corners) * 0.0045);
+        context.lineJoin = 'round';
+        context.stroke();
+        context.restore();
     }
     /**
-     * Creates the front-face pixel texture for the torso.
+     * Draws one filled projected quad.
      *
-     * @param random Seeded random generator.
-     * @param palette Derived avatar palette.
-     * @returns 8x8 torso texture.
+     * @param context Canvas 2D context.
+     * @param corners Quad corners in clockwise order.
+     * @param fillStyle CSS fill style.
      *
-     * @private helper of `minecraftAvatarVisual`
+     * @private helper of `minecraft2AvatarVisual`
      */
-    function createMinecraftShirtTexture(random, palette) {
-        const texture = Array.from({ length: 8 }, () => Array.from({ length: 8 }, () => palette.primary));
-        const stripeColor = random() < 0.5 ? palette.secondary : palette.highlight;
-        for (let rowIndex = 0; rowIndex < 2; rowIndex++) {
-            for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
-                texture[rowIndex][columnIndex] = palette.shadow;
-            }
+    function drawProjectedQuad(context, corners, fillStyle) {
+        context.beginPath();
+        context.moveTo(corners[0].x, corners[0].y);
+        context.lineTo(corners[1].x, corners[1].y);
+        context.lineTo(corners[2].x, corners[2].y);
+        context.lineTo(corners[3].x, corners[3].y);
+        context.closePath();
+        context.fillStyle = fillStyle;
+        context.fill();
+    }
+    /**
+     * Interpolates one point inside a projected quad across both quad axes.
+     *
+     * @param corners Quad corners in clockwise order.
+     * @param horizontalRatio Horizontal ratio in the range `[0, 1]`.
+     * @param verticalRatio Vertical ratio in the range `[0, 1]`.
+     * @returns Interpolated projected point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function interpolateProjectedQuad(corners, horizontalRatio, verticalRatio) {
+        const topPoint = interpolateProjectedPoint(corners[0], corners[1], horizontalRatio);
+        const bottomPoint = interpolateProjectedPoint(corners[3], corners[2], horizontalRatio);
+        return interpolateProjectedPoint(topPoint, bottomPoint, verticalRatio);
+    }
+    /**
+     * Interpolates between two projected points.
+     *
+     * @param startPoint Start point.
+     * @param endPoint End point.
+     * @param ratio Interpolation ratio in the range `[0, 1]`.
+     * @returns Interpolated projected point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function interpolateProjectedPoint(startPoint, endPoint, ratio) {
+        return {
+            x: startPoint.x + (endPoint.x - startPoint.x) * ratio,
+            y: startPoint.y + (endPoint.y - startPoint.y) * ratio,
+            z: startPoint.z + (endPoint.z - startPoint.z) * ratio,
+        };
+    }
+    /**
+     * Projects one rotated scene point into canvas coordinates.
+     *
+     * @param point Scene point.
+     * @param size Canvas size in CSS pixels.
+     * @param sceneCenterX Horizontal scene center.
+     * @param sceneCenterY Vertical scene center.
+     * @returns Projected point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function projectScenePoint(point, size, sceneCenterX, sceneCenterY) {
+        const cameraDistance = size * CAMERA_DISTANCE_RATIO;
+        const perspectiveScale = cameraDistance / Math.max(cameraDistance - point.z, cameraDistance * 0.35);
+        return {
+            x: sceneCenterX + point.x * perspectiveScale,
+            y: sceneCenterY + point.y * perspectiveScale,
+            z: point.z,
+        };
+    }
+    /**
+     * Applies the local cuboid rotations and translation to one scene point.
+     *
+     * @param localPoint Point in cuboid-local space.
+     * @param center Cuboid center in scene space.
+     * @param rotationX Cuboid pitch in radians.
+     * @param rotationY Cuboid yaw in radians.
+     * @returns Transformed scene-space point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function transformScenePoint(localPoint, center, rotationX, rotationY) {
+        const yawedPoint = rotatePointAroundY(localPoint, rotationY);
+        const pitchedPoint = rotatePointAroundX(yawedPoint, rotationX);
+        return {
+            x: center.x + pitchedPoint.x,
+            y: center.y + pitchedPoint.y,
+            z: center.z + pitchedPoint.z,
+        };
+    }
+    /**
+     * Rotates one point around the local Y axis.
+     *
+     * @param point Source point.
+     * @param angle Rotation angle in radians.
+     * @returns Rotated point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function rotatePointAroundY(point, angle) {
+        const cosine = Math.cos(angle);
+        const sine = Math.sin(angle);
+        return {
+            x: point.x * cosine + point.z * sine,
+            y: point.y,
+            z: -point.x * sine + point.z * cosine,
+        };
+    }
+    /**
+     * Rotates one point around the local X axis.
+     *
+     * @param point Source point.
+     * @param angle Rotation angle in radians.
+     * @returns Rotated point.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function rotatePointAroundX(point, angle) {
+        const cosine = Math.cos(angle);
+        const sine = Math.sin(angle);
+        return {
+            x: point.x,
+            y: point.y * cosine - point.z * sine,
+            z: point.y * sine + point.z * cosine,
+        };
+    }
+    /**
+     * Subtracts one 3D point from another.
+     *
+     * @param leftPoint Left point.
+     * @param rightPoint Right point.
+     * @returns Difference vector.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function subtractPoint3D(leftPoint, rightPoint) {
+        return {
+            x: leftPoint.x - rightPoint.x,
+            y: leftPoint.y - rightPoint.y,
+            z: leftPoint.z - rightPoint.z,
+        };
+    }
+    /**
+     * Computes the 3D cross product of two vectors.
+     *
+     * @param leftVector Left vector.
+     * @param rightVector Right vector.
+     * @returns Cross product.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function crossProduct3D(leftVector, rightVector) {
+        return {
+            x: leftVector.y * rightVector.z - leftVector.z * rightVector.y,
+            y: leftVector.z * rightVector.x - leftVector.x * rightVector.z,
+            z: leftVector.x * rightVector.y - leftVector.y * rightVector.x,
+        };
+    }
+    /**
+     * Computes the 3D dot product of two vectors.
+     *
+     * @param leftVector Left vector.
+     * @param rightVector Right vector.
+     * @returns Dot product.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function dotProduct3D(leftVector, rightVector) {
+        return leftVector.x * rightVector.x + leftVector.y * rightVector.y + leftVector.z * rightVector.z;
+    }
+    /**
+     * Normalizes one 3D vector while keeping zero vectors stable.
+     *
+     * @param vector Source vector.
+     * @returns Normalized vector.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function normalizeVector3(vector) {
+        const length = Math.hypot(vector.x, vector.y, vector.z);
+        if (length === 0) {
+            return vector;
         }
-        for (let rowIndex = 2; rowIndex < 8; rowIndex++) {
-            texture[rowIndex][3] = stripeColor;
-            texture[rowIndex][4] = stripeColor;
+        return {
+            x: vector.x / length,
+            y: vector.y / length,
+            z: vector.z / length,
+        };
+    }
+    /**
+     * Clamps one number into the provided range.
+     *
+     * @param value Input value.
+     * @param minimumValue Inclusive lower bound.
+     * @param maximumValue Inclusive upper bound.
+     * @returns Clamped value.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function clampNumber$1(value, minimumValue, maximumValue) {
+        return Math.min(maximumValue, Math.max(minimumValue, value));
+    }
+    /**
+     * Measures the perimeter of one projected quad.
+     *
+     * @param corners Quad corners.
+     * @returns Perimeter length.
+     *
+     * @private helper of `minecraft2AvatarVisual`
+     */
+    function getProjectedQuadPerimeter(corners) {
+        let perimeter = 0;
+        for (let cornerIndex = 0; cornerIndex < corners.length; cornerIndex++) {
+            const currentCorner = corners[cornerIndex];
+            const nextCorner = corners[(cornerIndex + 1) % corners.length];
+            perimeter += Math.hypot(nextCorner.x - currentCorner.x, nextCorner.y - currentCorner.y);
         }
-        texture[4][1] = palette.accent;
-        texture[4][6] = palette.accent;
-        texture[5][2] = palette.highlight;
-        texture[5][5] = palette.highlight;
-        return texture;
+        return perimeter;
     }
 
     /* eslint-disable no-magic-numbers */
@@ -16789,6 +17273,7 @@
         octopus3AvatarVisual,
         asciiOctopusAvatarVisual,
         minecraftAvatarVisual,
+        minecraft2AvatarVisual,
         fractalAvatarVisual,
         orbAvatarVisual,
     ];
@@ -18091,7 +18576,11 @@
             // Create new system message with persona at the beginning
             // Format: "You are {agentName}\n{personaContent}"
             // The # PERSONA comment will be removed later by removeCommentsFromSystemMessage
-            const personaSection = `# PERSONA\nYou are ${agentName}\n${mergedPersonaContent}`; // <- TODO: Use spaceTrim
+            const personaSection = spacetrim.spaceTrim((block) => `
+                # PERSONA
+                You are ${agentName}
+                ${block(mergedPersonaContent)}
+            `);
             const newSystemMessage = cleanedMessage ? `${personaSection}\n\n${cleanedMessage}` : personaSection;
             return {
                 ...requirements,
@@ -18993,7 +19482,10 @@
      */
     function buildTeamToolDescription(entry) {
         const detailLines = collectTeamEntryDetails(entry).map(({ label, content }) => `${label}: ${content}`);
-        return [`Consult teammate ${entry.teammate.label}`, ...detailLines].join('\n');
+        return spacetrim.spaceTrim((block) => `
+            Consult teammate ${entry.teammate.label}
+            ${block(detailLines.join('\n'))}
+        `);
     }
     /**
      * Collects structured teammate details that should stay visible to the model.
@@ -24327,7 +24819,10 @@
         if (hiddenCount > 0) {
             summaryRows.push(`...and ${hiddenCount} more.`);
         }
-        return [`Found ${options.total} ${options.total === 1 ? 'timeout' : 'timeouts'}:`, ...summaryRows].join('\n');
+        return spacetrim.spaceTrim((block) => `
+            Found ${options.total} ${options.total === 1 ? 'timeout' : 'timeouts'}:
+            ${block(summaryRows.join('\n'))}
+        `);
     }
     /**
      * Formats one timeout row for assistant-visible timeout listings.
@@ -27698,6 +28193,791 @@
     //                  <- [🐱‍🚀] Buttons into genesis book
     // <- TODO: [🐱‍🚀] generateBookBoilerplate and deprecate `DEFAULT_BOOK`
 
+    /**
+     * Warning message used for unfinished commitments.
+     */
+    const UNFINISHED_COMMITMENT_MESSAGE = 'This commitment is unfinished and not ready to use. Be careful when using it.';
+    /**
+     * Low-level warning message used for low-level commitments.
+     */
+    const LOW_LEVEL_COMMITMENT_MESSAGE = 'This commitment is low-level and not used by most of the users. Be careful when using it.';
+    /**
+     * Short badge text used for deprecated commitments.
+     */
+    const DEPRECATED_COMMITMENT_BADGE_LABEL = 'Deprecated';
+    /**
+     * Short badge text used for unfinished and low-level commitments.
+     */
+    const LOW_LEVEL_COMMITMENT_BADGE_LABEL = 'Low-level';
+    /**
+     * Longer label used for deprecated commitments.
+     */
+    const DEPRECATED_COMMITMENT_DETAIL_LABEL = 'Deprecated commitment';
+    /**
+     * Longer label used for unfinished and low-level commitments.
+     */
+    const LOW_LEVEL_COMMITMENT_DETAIL_LABEL = 'Low-level commitment';
+    /**
+     * Prefix used when formatting replacement guidance.
+     */
+    const PREFERRED_REPLACEMENT_LABEL = 'Preferred replacement';
+    /**
+     * Formats preferred replacement guidance for deprecated commitments.
+     *
+     * @param replacedBy - Preferred replacement commitment keywords.
+     * @returns Optional replacement guidance sentence with leading space.
+     *
+     * @private internal utility of commitment catalog notices
+     */
+    function formatCommitmentReplacementText(replacedBy) {
+        if (!replacedBy || replacedBy.length === 0) {
+            return '';
+        }
+        return ` ${PREFERRED_REPLACEMENT_LABEL}: ${replacedBy.map((type) => `\`${type}\``).join(', ')}.`;
+    }
+    /**
+     * Resolves the notice metadata for deprecated, unfinished, or low-level commitments.
+     *
+     * @param definition - Commitment definition to inspect.
+     * @returns Notice metadata when the commitment should be surfaced with caution.
+     *
+     * @private internal utility of commitment catalog notices
+     */
+    function getCommitmentNoticeMetadata(definition) {
+        if (definition.isUnfinished) {
+            return {
+                kind: 'unfinished',
+                badgeLabel: LOW_LEVEL_COMMITMENT_BADGE_LABEL,
+                detailLabel: LOW_LEVEL_COMMITMENT_DETAIL_LABEL,
+                message: UNFINISHED_COMMITMENT_MESSAGE,
+            };
+        }
+        if (definition.isLowLevel) {
+            return {
+                kind: 'lowLevel',
+                badgeLabel: LOW_LEVEL_COMMITMENT_BADGE_LABEL,
+                detailLabel: LOW_LEVEL_COMMITMENT_DETAIL_LABEL,
+                message: LOW_LEVEL_COMMITMENT_MESSAGE,
+            };
+        }
+        if (definition.deprecation) {
+            return {
+                kind: 'deprecated',
+                badgeLabel: DEPRECATED_COMMITMENT_BADGE_LABEL,
+                detailLabel: DEPRECATED_COMMITMENT_DETAIL_LABEL,
+                message: definition.deprecation.message,
+            };
+        }
+        return null;
+    }
+
+    /**
+     * Common anti-patterns with practical fixes.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const bookLanguageCommonPitfalls = [
+        {
+            title: 'Too broad agent scope',
+            dont: 'One agent tries to be a lawyer, developer, marketer, and researcher at once.',
+            doInstead: 'Split into focused agents and orchestrate with TEAM or IMPORT.',
+        },
+        {
+            title: 'Unverifiable claims',
+            dont: 'The agent answers internet-dependent questions without tools or without citing sources.',
+            doInstead: 'Add `USE SEARCH ENGINE` / `USE BROWSER` and a citation-oriented `RULE`.',
+        },
+        {
+            title: 'Missing guardrails',
+            dont: 'Only persona is defined, with no behavioral constraints.',
+            doInstead: 'Add concrete `RULE` commitments for safety, scope, and tone.',
+        },
+        {
+            title: 'Overloaded inheritance',
+            dont: 'Using deep `FROM` chains without documenting why each parent is needed.',
+            doInstead: 'Keep inheritance shallow and use focused IMPORT/TEAM composition for reuse.',
+        },
+        {
+            title: 'Unsafe memory usage',
+            dont: 'Storing every detail in memory without boundaries.',
+            doInstead: 'Pair `MEMORY` with explicit rules about what is allowed to persist.',
+        },
+    ];
+
+    /**
+     * End-to-end examples used by the standalone Book language documentation.
+     *
+     * These are intentionally compact but complete, so they can be copy-pasted and
+     * used as practical starting points.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const bookLanguageDocumentationExamples = [
+        {
+            id: 'minimal-hello-world-agent',
+            title: 'Minimal hello-world agent',
+            goal: 'Create the smallest useful agent with identity and greeting.',
+            source: spacetrim.spaceTrim(`
+            Hello World Agent
+
+            GOAL Be a concise and friendly assistant.
+            INITIAL MESSAGE Hello! I am ready to help.
+            CLOSED
+        `),
+            walkthrough: [
+                'The first line (`Hello World Agent`) is the agent name.',
+                '`GOAL` defines the effective role and profile text.',
+                '`INITIAL MESSAGE` sets a deterministic first message for a new chat.',
+                '`CLOSED` prevents conversational self-modification.',
+            ],
+        },
+        {
+            id: 'tool-using-browser-search-agent',
+            title: 'Tool-using agent (Browser + Search engine)',
+            goal: 'Enable internet research with clear sourcing behavior.',
+            source: spacetrim.spaceTrim(`
+            Web Research Assistant
+
+            GOAL Research topics using fresh and verifiable information.
+            USE SEARCH ENGINE Prefer official sources and recent publications.
+            USE BROWSER
+            RULE Verify important claims across multiple sources when possible.
+            RULE Include source links in your final answer.
+            INITIAL MESSAGE Ask me what topic you want to research and how deep the report should be.
+        `),
+            walkthrough: [
+                '`USE SEARCH ENGINE` provides web search tooling and optional search instructions.',
+                '`USE BROWSER` enables URL fetching and interactive browsing tools.',
+                '`RULE` commitments make reliability behavior explicit and repeatable.',
+                'This pattern is ideal for current-events and fact-checking agents.',
+            ],
+        },
+        {
+            id: 'rule-and-knowledge-agent',
+            title: 'Agent with RULE and KNOWLEDGE',
+            goal: 'Ground responses in explicit constraints and curated sources.',
+            source: spacetrim.spaceTrim(`
+            Support Policy Assistant
+
+            GOAL Answer questions about support policy.
+            KNOWLEDGE Refunds are available within 30 days with proof of purchase.
+            KNOWLEDGE https://example.com/support-policy
+            RULE If a policy item is missing in available knowledge, say it explicitly.
+            RULE Never invent legal or policy statements.
+            INITIAL MESSAGE I can explain refund and support rules from provided knowledge.
+        `),
+            walkthrough: [
+                '`KNOWLEDGE` may be inline text or an external URL/document.',
+                '`RULE` commitments define non-negotiable behavior constraints.',
+                'Combining both creates predictable, grounded policy responses.',
+                'Use this pattern for compliance, support, and internal procedures.',
+            ],
+        },
+        {
+            id: 'memory-agent-with-long-term-memory',
+            title: 'MEMORY agent with long-term memory',
+            goal: 'Persist user preferences across conversations.',
+            source: spacetrim.spaceTrim(`
+            Customer Success Memory Agent
+
+            GOAL Support SaaS customers while remembering relevant setup and preference context.
+            MEMORY Remember product setup, user goals, and communication preferences.
+            RULE Store only user-approved preferences and project context.
+            RULE Never store secrets or sensitive data unless explicitly requested and allowed.
+            INITIAL MESSAGE I can remember your setup and preferences for future sessions.
+        `),
+            walkthrough: [
+                '`MEMORY` adds runtime memory tools and memory-specific system guidance.',
+                '`RULE` commitments narrow what should be remembered to reduce privacy risks.',
+                'In Agents Server, memory is runtime-backed and user-scoped.',
+                'Use this for assistants that must preserve context over time.',
+            ],
+        },
+        {
+            id: 'use-project-and-wallet-integration-agent',
+            title: 'USE PROJECT and WALLET external integration',
+            goal: 'Work with GitHub repositories and wallet-backed credentials.',
+            source: spacetrim.spaceTrim(`
+            Repository Maintainer
+
+            GOAL Maintain a GitHub repository and prepare safe pull requests.
+            USE PROJECT https://github.com/acme/website
+            WALLET Store credentials for repository operations.
+            RULE Before editing files, explain the planned change and impacted paths.
+            RULE Never reveal raw credentials in chat output.
+            INITIAL MESSAGE I can inspect the repository and help you prepare PR-ready changes.
+        `),
+            walkthrough: [
+                '`USE PROJECT` enables repository tools for listing, reading, editing files, and creating PRs.',
+                'Credentials are resolved from wallet records at runtime in Agents Server.',
+                '`WALLET` is kept here as a compatibility marker, but current Book 2.0 parsing treats it as deprecated/ignored.',
+                'In current runtime behavior, wallet-backed integrations are driven by commitments such as `USE PROJECT` and `USE EMAIL`.',
+            ],
+        },
+        {
+            id: 'use-calendar-integration-agent',
+            title: 'USE CALENDAR integration',
+            goal: 'Coordinate meetings and schedules through a connected Google Calendar.',
+            source: spacetrim.spaceTrim(`
+            Calendar Assistant
+
+            GOAL Schedule meetings and keep the calendar conflict-free.
+            USE CALENDAR https://calendar.google.com/calendar/u/0/r
+            SCOPES https://www.googleapis.com/auth/calendar
+            RULE Confirm destructive actions before deleting an event.
+            INITIAL MESSAGE Tell me the meeting details and I will schedule it in your calendar.
+        `),
+            walkthrough: [
+                '`USE CALENDAR` enables calendar tools for listing, reading, creating, updating, and deleting events.',
+                'The first calendar URL identifies which calendar integration should be used.',
+                '`SCOPES` can explicitly request required Google Calendar OAuth permissions.',
+                'Credentials are resolved from wallet-backed Google Calendar OAuth records at runtime in Agents Server.',
+            ],
+        },
+        {
+            id: 'agents-team-example',
+            title: 'Agents TEAM (with in-book teammates)',
+            goal: 'Delegate sub-tasks to specialized teammates.',
+            source: spacetrim.spaceTrim(`
+            Team Manager
+
+            GOAL Coordinate specialists and deliver one consolidated answer.
+            TEAM Ask {Legal Reviewer} for legal constraints and {Implementation Reviewer} for technical feasibility.
+            RULE Always summarize teammate outputs into one action plan.
+
+            ---
+
+            Legal Reviewer
+
+            FROM VOID
+            GOAL Review legal and compliance risk.
+            RULE Flag legal/compliance risk and uncertainty clearly.
+            CLOSED
+
+            ---
+
+            Implementation Reviewer
+
+            FROM VOID
+            GOAL Review implementation effort and delivery risk.
+            RULE Estimate complexity and identify blockers.
+            CLOSED
+        `),
+            walkthrough: [
+                'The main agent delegates via `TEAM` commitment.',
+                'References in `{...}` are resolved against embedded agents inside the same book (split by `---`).',
+                'Each teammate can be isolated with `FROM VOID` for deterministic specialization.',
+                'This pattern works well for multi-role review and decision support.',
+            ],
+        },
+    ];
+
+    /**
+     * Canonical commitment keyword for the open/closed family.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const OPEN_COMMITMENT_TYPE = 'OPEN';
+    /**
+     * Canonical commitment keyword for the open/closed family.
+     */
+    const CLOSED_COMMITMENT_TYPE = 'CLOSED';
+    /**
+     * Removes the top-level heading from one commitment documentation block.
+     *
+     * @param markdown - Original markdown source.
+     * @returns Markdown without the first `#` heading.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function removeLeadingTopLevelHeading(markdown) {
+        return markdown.replace(/^\s*#\s+[^\n]+\n*/u, '').trim();
+    }
+    /**
+     * Renders one subsection for the combined open/closed documentation family.
+     *
+     * @param title - Heading label for the subsection.
+     * @param documentation - Raw commitment documentation markdown.
+     * @returns Markdown subsection with a `####` heading.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function renderDocumentationSection(title, documentation) {
+        return `#### ${title}\n\n${removeLeadingTopLevelHeading(documentation)}`;
+    }
+    /**
+     * Renders the documentation body for one grouped commitment entry.
+     *
+     * `OPEN` and `CLOSED` are intentionally rendered together so the documentation
+     * surfaces present them as one conceptual switch instead of two isolated pages.
+     *
+     * @param group - Grouped commitment metadata.
+     * @returns Markdown body for the docs page/catalog entry.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function renderGroupedCommitmentDocumentationMarkdown(group) {
+        const commitmentTypes = new Set([group.primary.type, ...group.aliases]);
+        if (commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE)) {
+            const openCommitmentDefinition = getCommitmentDefinition(OPEN_COMMITMENT_TYPE);
+            const closedCommitmentDefinition = getCommitmentDefinition(CLOSED_COMMITMENT_TYPE);
+            if (openCommitmentDefinition && closedCommitmentDefinition) {
+                return spacetrim.spaceTrim((block) => `
+                    ${block(renderDocumentationSection(OPEN_COMMITMENT_TYPE, openCommitmentDefinition.documentation))}
+
+                    ${block(renderDocumentationSection(CLOSED_COMMITMENT_TYPE, closedCommitmentDefinition.documentation))}
+                `);
+            }
+        }
+        return removeLeadingTopLevelHeading(group.primary.documentation);
+    }
+
+    /**
+     * Commitment types that primarily model composition of multiple agents.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const COMPOSITION_COMMITMENT_TYPES = new Set(['FROM', 'IMPORT', 'IMPORTS', 'TEAM']);
+    /**
+     * Commitment types that expose tools/runtime capabilities.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const TOOLING_COMMITMENT_TYPES = new Set([
+        'USE BROWSER',
+        'USE DEEPSEARCH',
+        'USE SEARCH ENGINE',
+        'USE SEARCH',
+        'USE SPAWN',
+        'USE EMAIL',
+        'USE POPUP',
+        'USE TIME',
+        'USE USER LOCATION',
+        'USE PROJECT',
+        'USE CALENDAR',
+        'USE IMAGE GENERATOR',
+        'USE MCP',
+        'USE PRIVACY',
+        'MEMORY',
+        'MEMORIES',
+    ]);
+    /**
+     * Commitment types that primarily define agent profile metadata.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const PROFILE_COMMITMENT_TYPES = new Set([
+        'GOAL',
+        'GOALS',
+        'PERSONA',
+        'PERSONAE',
+        'META',
+        'META AVATAR',
+        'META IMAGE',
+        'META LINK',
+        'META DOMAIN',
+        'META DESCRIPTION',
+        'META DISCLAIMER',
+        'META INPUT PLACEHOLDER',
+        'META COLOR',
+        'META FONT',
+        'META VOICE',
+        'INITIAL MESSAGE',
+        'MODEL',
+        'MODELS',
+    ]);
+    /**
+     * Commitment types that primarily define behavioral constraints or prompt shaping.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    const BEHAVIOR_COMMITMENT_TYPES = new Set([
+        'RULE',
+        'RULES',
+        'KNOWLEDGE',
+        'GOAL',
+        'GOALS',
+        'STYLE',
+        'STYLES',
+        'LANGUAGE',
+        'LANGUAGES',
+        'FORMAT',
+        'FORMATS',
+        'TEMPLATE',
+        'TEMPLATES',
+        'WRITING SAMPLE',
+        'WRITING RULES',
+        'SAMPLE',
+        'EXAMPLE',
+        'SCENARIO',
+        'SCENARIOS',
+        'MESSAGE',
+        'MESSAGES',
+        'MESSAGE SUFFIX',
+        'USER MESSAGE',
+        'AGENT MESSAGE',
+        'INTERNAL MESSAGE',
+        'OPEN',
+        'CLOSED',
+    ]);
+    /**
+     * Creates one standalone markdown guide for Book language (Book 2.0 / agent language).
+     *
+     * The output intentionally combines:
+     * - static conceptual building blocks maintained in this repository
+     * - dynamically generated commitment catalog from runtime commitment definitions
+     * so docs stay up-to-date by design.
+     *
+     * @returns Full standalone markdown document.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function createStandaloneBookLanguageMarkdown() {
+        const groupedCommitments = getGroupedCommitmentDefinitions();
+        const generatedAtIso = new Date().toISOString();
+        const placeholderCommitmentCount = groupedCommitments.filter(({ primary }) => primary instanceof NotYetImplementedCommitmentDefinition).length;
+        const implementedCommitmentCount = groupedCommitments.length - placeholderCommitmentCount;
+        const allCommitmentKeywords = groupedCommitments.flatMap(({ primary, aliases }) => [primary.type, ...aliases]);
+        const toolingCommitments = groupedCommitments.filter(({ primary }) => TOOLING_COMMITMENT_TYPES.has(primary.type));
+        const profileCommitments = groupedCommitments.filter(({ primary }) => PROFILE_COMMITMENT_TYPES.has(primary.type));
+        const compositionCommitments = groupedCommitments.filter(({ primary }) => COMPOSITION_COMMITMENT_TYPES.has(primary.type));
+        const behaviorCommitments = groupedCommitments.filter(({ primary }) => BEHAVIOR_COMMITMENT_TYPES.has(primary.type));
+        return spacetrim.spaceTrim(
+        // [✨]
+        (block) => `
+            # Book Language blueprint
+
+            > Canonical standalone guide for Promptbook Book Agent language.  
+            > Generated from repository https://github.com/webgptorg/promptbook
+
+            - Book language version: \`${BOOK_LANGUAGE_VERSION}\`
+            - Generated at: \`${generatedAtIso}\`
+            - Commitment groups: \`${groupedCommitments.length}\`
+            - Implemented commitments: \`${implementedCommitmentCount}\`
+            - Placeholder commitments: \`${placeholderCommitmentCount}\`
+
+            ## <a id="table-of-contents"></a>Table of Contents
+
+            - [What Book language is](#what-book-language-is)
+            - [Execution and compilation model](#execution-and-compilation-model)
+            - [Mental model of an agent](#mental-model-of-an-agent)
+            - [How to structure good agents](#how-to-structure-good-agents)
+            - [Primitives and constructs reference](#primitives-and-constructs-reference)
+            - [Commitment catalog (all commitments)](#commitment-catalog-all-commitments)
+            - [End-to-end examples](#end-to-end-examples)
+            - [Do nots and common pitfalls](#do-nots-and-common-pitfalls)
+            - [Build an agent from scratch (offline tutorial)](#build-an-agent-from-scratch-offline-tutorial)
+
+            ## <a id="what-book-language-is"></a>What Book language is
+
+            Book language is a domain-specific language for defining **AI agents** as plain-text source.
+            It solves these problems:
+
+            - **One editable source of truth** for agent behavior, tools, memory, and profile metadata.
+            - **Composable agent architecture** through commitments like \`FROM\`, \`IMPORT\`, and \`TEAM\`.
+            - **Deterministic runtime preparation** where source is parsed and compiled into model requirements.
+            - **Portable agent definitions** that can be copied, versioned, and reviewed as text.
+
+            In this repository, "Book language" means **Book 2.0 agent language**.
+
+            ## <a id="execution-and-compilation-model"></a>Execution and compilation model
+
+            Promptbook and Agents Server use two core passes:
+
+            1. **Fast parse pass** (\`parseAgentSource\`):
+            It synchronously extracts agent profile/basic info (name, last goal/profile text, meta, capabilities, samples, references).
+            2. **Compilation pass** (\`createAgentModelRequirements\`):
+            It applies commitments in sequence and builds executable model requirements (system message, tools, memory/tool metadata, imports, etc.).
+
+            In Agents Server, the runtime flow typically includes:
+
+            1. Resolve scoped references (including in-book references like \`{Some Agent}\`).
+            2. Resolve inheritance/import chains into effective source.
+            3. Compile effective source into model requirements.
+            4. Execute chat turns with resolved tools and runtime adapters.
+
+            ## <a id="mental-model-of-an-agent"></a>Mental model of an agent
+
+            Think of one agent source as four layers:
+
+            1. **Identity/Profile layer**:
+            Agent name (first non-commitment line), the last \`GOAL\` (preferred) or deprecated \`PERSONA\`, and \`META*\` commitments.
+            2. **Behavior layer**:
+            \`RULE\`, \`KNOWLEDGE\`, \`WRITING SAMPLE\`, \`WRITING RULES\`, deprecated \`STYLE\`, \`FORMAT\`, \`TEMPLATE\`, \`LANGUAGE\`, \`GOAL\`, and related commitments.
+            3. **Capability layer**:
+            \`USE*\`, \`MEMORY\`, and other tooling commitments exposing runtime abilities.
+            4. **Composition layer**:
+            \`FROM\` inheritance, \`IMPORT\` reuse, and \`TEAM\` delegation.
+
+            Agent composition commitments in current runtime:
+
+            - Profile-centric commitments detected: ${profileCommitments
+        .map(({ primary }) => `\`${primary.type}\``)
+        .join(', ')}
+            - Behavior-centric commitments detected: ${behaviorCommitments
+        .map(({ primary }) => `\`${primary.type}\``)
+        .join(', ')}
+            - Tool/runtime commitments detected: ${toolingCommitments
+        .map(({ primary }) => `\`${primary.type}\``)
+        .join(', ')}
+            - Composition commitments detected: ${compositionCommitments
+        .map(({ primary }) => `\`${primary.type}\``)
+        .join(', ')}
+
+            ### META commitments and agent profile
+
+            \`META*\` commitments control profile data shown in UI (for example avatar visual, image, description, disclaimers, domain, input placeholder).
+            They generally shape presentation/metadata rather than tool behavior.
+
+            ### FROM inheritance
+
+            \`FROM\` points to a parent agent source. During inheritance resolution:
+
+            - Parent corpus is merged into effective source.
+            - \`FROM {Void}\` / \`FROM VOID\` means explicit "no parent".
+            - Missing references are surfaced as notes in resolved source.
+
+            ### TEAM and IMPORT
+
+            - \`TEAM\` registers teammate agents as callable tools.
+            - \`IMPORT\` injects imported agent/file content into current agent context.
+            - In Agents Server, compact references like \`{Legal Reviewer}\` can resolve to embedded in-book agents.
+
+            ### USE commitments
+
+            \`USE*\` commitments enable capabilities (search, browser, project integration, email, image generation, etc.).
+            They expose runtime tools and system-message guidance used during execution.
+
+            ## <a id="how-to-structure-good-agents"></a>How to structure good agents
+
+            Recommended patterns and tradeoffs:
+
+            1. **Single clear role first**:
+            Start with one narrow \`GOAL\`; use \`PERSONA\` only for backward-compatible legacy books.
+            Tradeoff: less initial flexibility, much higher reliability.
+            2. **Guardrails early**:
+            Add concrete \`RULE\` commitments before adding many tools.
+            Tradeoff: more upfront design, fewer runtime surprises.
+            3. **Grounding over improvisation**:
+            Prefer \`KNOWLEDGE\` + explicit citation rule for high-stakes answers.
+            Tradeoff: extra maintenance for sources, better factual control.
+            4. **Composition over monoliths**:
+            Use \`TEAM\`/\`IMPORT\` for specialized responsibilities.
+            Tradeoff: orchestration overhead, stronger modularity and reuse.
+            5. **Controlled memory**:
+            If using \`MEMORY\`, define what must and must not be remembered.
+            Tradeoff: stricter policy design, better privacy and signal quality.
+
+            ## <a id="primitives-and-constructs-reference"></a>Primitives and constructs reference
+
+            ### Core syntax primitives
+
+            1. **Agent title**:
+            First non-empty line that is not a commitment keyword.
+            2. **Commitment block**:
+            Starts with a commitment keyword and continues until the next commitment block or separator.
+            3. **Horizontal separator**:
+            Lines like \`---\` split sections; in Agents Server they can delimit embedded in-book agents.
+            4. **Code fences**:
+            Preserved inside commitment content; useful for examples/instructions.
+            5. **Parameters**:
+            Both \`@parameter\` and \`{parameter}\` notations are supported and parsed.
+
+            ### Reference tokens and pseudo-agents
+
+            - Compact references like \`{Agent Name}\` are resolved by Agents Server reference resolver.
+            - Pseudo-agent forms (for example \`{User}\`, \`{Void}\`) are supported in relevant commitments.
+            - \`{User}\` is intended for \`TEAM\`; \`{Void}\` is useful for explicit no-parent inheritance.
+
+            ### Commitment keywords currently recognized
+
+            ${block(getSafeCodeBlock(allCommitmentKeywords.join(', '), 'text'))}
+
+            ## <a id="commitment-catalog-all-commitments"></a>Commitment catalog (all commitments)
+
+            This section is generated from commitment definitions in \`src/commitments\`.
+            For each commitment group you get:
+
+            - semantics summary (description/icon/status)
+            - parsing schema (\`createTypeRegex\` and \`createRegex\`)
+            - canonical documentation block
+
+            ${block(groupedCommitments.map(renderCommitmentCatalogSection).join('\n\n'))}
+
+            ## <a id="end-to-end-examples"></a>End-to-end examples
+
+            ${block(bookLanguageDocumentationExamples.map(renderExampleSection).join('\n\n'))}
+
+            ## <a id="do-nots-and-common-pitfalls"></a>Do nots and common pitfalls
+
+            ${block(bookLanguageCommonPitfalls
+        .map((pitfall, index) => spacetrim.spaceTrim(`
+                            ${index + 1}. **${pitfall.title}**
+                            - Don't: ${pitfall.dont}
+                            - Do instead: ${pitfall.doInstead}
+                        `))
+        .join('\n'))}
+
+            ## <a id="build-an-agent-from-scratch-offline-tutorial"></a>Build an agent from scratch (offline tutorial)
+
+            This tutorial is sufficient without internet access.
+
+            1. **Define role and goal**
+            Create a short name line and one clear \`GOAL\`.
+            2. **Add behavioral constraints**
+            Add 3-6 specific \`RULE\` commitments covering scope, tone, and safety boundaries.
+            3. **Add grounding**
+            Add \`KNOWLEDGE\` commitments (inline text or local/importable sources).
+            4. **Add capabilities**
+            Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
+            5. **Set profile metadata**
+            Add \`META DESCRIPTION\`, \`META AVATAR\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
+            6. **Add first interaction**
+            Add \`INITIAL MESSAGE\` and optionally sample \`USER MESSAGE\` / \`AGENT MESSAGE\` pairs.
+            7. **Close for deterministic behavior (optional)**
+            Add \`CLOSED\` when you want stable non-self-modifying behavior.
+
+            Copy-paste template:
+
+            ${block(getSafeCodeBlock(spacetrim.spaceTrim(`
+                        Project Assistant
+
+                        GOAL Help the user turn project ideas into concrete deliverables with focused planning support.
+
+                        RULE Ask clarifying questions when requirements are ambiguous.
+                        RULE Provide concise, structured outputs with actionable steps.
+                        RULE If information is missing, state assumptions explicitly.
+                        RULE Do not invent facts.
+
+                        KNOWLEDGE Team works in two-week sprints and tracks tasks in Kanban.
+                        KNOWLEDGE Preferred output format: summary, plan, risks, next action.
+
+                        META DESCRIPTION Practical project-planning assistant.
+                        META INPUT PLACEHOLDER Describe your project goal or blocker...
+
+                        INITIAL MESSAGE Share your project goal and current blocker, and I will propose a concrete next-step plan.
+                        CLOSED
+                    `), 'book'))}
+
+            Validation checklist:
+
+            - Does each commitment have a clear purpose?
+            - Are there explicit constraints against hallucination and unsafe behavior?
+            - Are tools only enabled when genuinely needed?
+            - Is memory usage bounded by clear rules?
+            - Is composition (\`FROM\`/\`TEAM\`/\`IMPORT\`) justified and understandable?
+
+            ---
+
+            Generated from:
+
+            - Commitments registry and runtime docs in \`src/commitments\`
+            - Parser/compiler behavior in \`src/book-2.0/agent-source\`
+            - Agents Server reference/inheritance resolution in \`apps/agents-server/src/utils\`
+            - Standalone docs source blocks in \`apps/agents-server/src/utils/bookLanguageDocumentation\`
+        `);
+    }
+    /**
+     * Renders one commitment section in the generated catalog.
+     *
+     * @param groupedCommitment - Grouped commitment definition with aliases.
+     * @returns Markdown section for a single commitment.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function renderCommitmentCatalogSection(groupedCommitment) {
+        var _a;
+        const { primary, aliases } = groupedCommitment;
+        const notice = getCommitmentNoticeMetadata(primary);
+        const status = primary instanceof NotYetImplementedCommitmentDefinition
+            ? 'Placeholder (not fully implemented)'
+            : notice
+                ? `Implemented (${notice.detailLabel})`
+                : 'Implemented';
+        const aliasText = aliases.length === 0 ? 'None' : aliases.map((alias) => `\`${alias}\``).join(', ');
+        const noticeText = notice
+            ? notice.kind === 'deprecated'
+                ? `- **Deprecation:** ${notice.message}${formatCommitmentReplacementText((_a = primary.deprecation) === null || _a === void 0 ? void 0 : _a.replacedBy)}`
+                : `- **Low-level commitment:** ${notice.message}`
+            : '';
+        const documentationMarkdown = renderGroupedCommitmentDocumentationMarkdown(groupedCommitment);
+        return spacetrim.spaceTrim((block) => `
+            ### <a id="commitment-${toStableAnchorId(primary.type)}"></a>${primary.icon} ${primary.type}
+
+            - **Status:** ${status}
+            - **Aliases:** ${aliasText}
+            - **Semantics:** ${primary.description}
+            - **Type schema (\`createTypeRegex\`):** \`${stringifyRegex(primary.createTypeRegex())}\`
+            - **Block schema (\`createRegex\`):** \`${stringifyRegex(primary.createRegex())}\`
+            ${noticeText}
+
+            ${block(documentationMarkdown)}
+        `);
+    }
+    /**
+     * Renders one end-to-end example section.
+     *
+     * @param example - Example definition.
+     * @returns Markdown section for one example.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function renderExampleSection(example) {
+        return spacetrim.spaceTrim((block) => `
+            ### <a id="example-${toStableAnchorId(example.id)}"></a>${example.title}
+
+            **Goal:** ${example.goal}
+
+            **Full source**
+
+            ${block(getSafeCodeBlock(example.source, 'book'))}
+
+            **Walkthrough**
+
+            ${block(example.walkthrough.map((step, index) => `${index + 1}. ${step}`).join('\n'))}
+        `);
+    }
+    /**
+     * Converts a heading label into a stable markdown anchor id.
+     *
+     * @param value - Raw heading/identifier text.
+     * @returns Stable lowercase anchor id.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function toStableAnchorId(value) {
+        return value
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+    }
+    /**
+     * Converts a regular expression into a concise literal-like string.
+     *
+     * @param regex - Regex instance.
+     * @returns Printable regex pattern and flags.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function stringifyRegex(regex) {
+        return `/${regex.source}/${regex.flags}`;
+    }
+    /**
+     * Creates a safe markdown fenced code block even when content contains backticks.
+     *
+     * @param content - Raw code content.
+     * @param language - Optional info-string language label.
+     * @returns Fenced code block.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown`
+     */
+    function getSafeCodeBlock(content, language = 'markdown') {
+        const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));
+        const fence = '`'.repeat(Math.max(3, maxBacktickCount + 1));
+        return `${fence}${language}\n${content}\n${fence}`;
+    }
+
     /**
      * Generates an image for the agent to use as profile image
      *
@@ -29705,8 +30985,10 @@
      */
     const MatcherFormfactorDefinition = {
         name: 'EXPERIMENTAL_MATCHER',
-        description: `An evaluation system that determines whether content meets specific criteria or patterns.
-    Used for content validation, quality assessment, and intelligent filtering tasks. Currently in experimental phase.`,
+        description: spacetrim.spaceTrim(`
+        An evaluation system that determines whether content meets specific criteria or patterns.
+        Used for content validation, quality assessment, and intelligent filtering tasks. Currently in experimental phase.
+    `),
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/177`,
         pipelineInterface: {
             inputParameters: [
@@ -29763,9 +31045,11 @@
      */
     const TranslatorFormfactorDefinition = {
         name: 'TRANSLATOR',
-        description: `A text transformation system that converts input content into different forms,
-    including language translations, paraphrasing, style conversions, and tone adjustments.
-    This form factor takes one input and produces one transformed output.`,
+        description: spacetrim.spaceTrim(`
+        A text transformation system that converts input content into different forms,
+        including language translations, paraphrasing, style conversions, and tone adjustments.
+        This form factor takes one input and produces one transformed output.
+    `),
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/175`,
         pipelineInterface: {
             inputParameters: [
@@ -31125,12 +32409,21 @@
                     // <- TODO: [🧠] Make this dynamic, async, prepare-phase HLAs
                 ],
             });
-            // TODO: Use spaceTrim in multiline strings
             $pipelineJson.tasks.push({
                 taskType: 'PROMPT_TASK',
                 name: 'create-an-answer',
                 title: 'Create an answer',
-                content: 'Write a response to the user message:\n\n**Question from user**\n\n> {userMessage}\n\n**Previous conversation**\n\n> {previousConversationSummary}',
+                content: spacetrim.spaceTrim(`
+                    Write a response to the user message:
+
+                    **Question from user**
+
+                    > {userMessage}
+
+                    **Previous conversation**
+
+                    > {previousConversationSummary}
+                `),
                 resultingParameterName: 'chatbotResponse',
                 personaName,
                 dependentParameterNames: [
@@ -31142,7 +32435,26 @@
                 taskType: 'PROMPT_TASK',
                 name: 'summarize-the-conversation',
                 title: 'Summarize the conversation',
-                content: 'Summarize the conversation in a few words:\n\n## Rules\n\n-   Summarise the text of the conversation in a few words\n-   Convert the text to its basic idea\n-   Imagine you are writing the headline or subject line of an email\n-   Respond with a few words of summary only\n\n## Conversation\n\n**User:**\n\n> {userMessage}\n\n**You:**\n\n> {chatbotResponse}',
+                content: spacetrim.spaceTrim(`
+                    Summarize the conversation in a few words:
+
+                    ## Rules
+
+                    -   Summarise the text of the conversation in a few words
+                    -   Convert the text to its basic idea
+                    -   Imagine you are writing the headline or subject line of an email
+                    -   Respond with a few words of summary only
+
+                    ## Conversation
+
+                    **User:**
+
+                    > {userMessage}
+
+                    **You:**
+
+                    > {chatbotResponse}
+                `),
                 resultingParameterName: 'conversationSummary',
                 personaName,
                 expectations: {
@@ -33546,11 +34858,11 @@
         if (attachments.length === 0) {
             return '';
         }
-        return [
-            CHAT_ATTACHMENTS_HEADING,
-            ...attachments.map((attachment) => formatChatAttachmentLine(attachment)),
-            CHAT_ATTACHMENTS_INSTRUCTION,
-        ].join('\n');
+        return spacetrim.spaceTrim((block) => `
+            ${CHAT_ATTACHMENTS_HEADING}
+            ${block(attachments.map((attachment) => formatChatAttachmentLine(attachment)).join('\n'))}
+            ${CHAT_ATTACHMENTS_INSTRUCTION}
+        `);
     }
 
     /**
@@ -33791,24 +35103,24 @@
             : ''}`
             : null;
         const warningsLine = contentResolution.warnings.length > 0 ? `Warnings: ${contentResolution.warnings.join(' | ')}` : null;
-        if (!contentResolution.content) {
+        const metadataLines = [decodingLine, warningsLine].filter((line) => Boolean(line)).join('\n');
+        const resolvedContent = contentResolution.content;
+        if (!resolvedContent) {
             const reason = contentResolution.reason || 'content unavailable';
-            return [`- ${attachmentLabel}: ${reason}. URL: ${contentResolution.attachment.url}`, decodingLine, warningsLine]
-                .filter(Boolean)
-                .join('\n');
+            return spacetrim.spaceTrim((block) => `
+                - ${attachmentLabel}: ${reason}. URL: ${contentResolution.attachment.url}
+                ${block(metadataLines)}
+            `);
         }
         const truncatedLabel = contentResolution.isTruncated ? ' [truncated]' : '';
-        return [
-            `File: ${attachmentLabel}${truncatedLabel}`,
-            `URL: ${contentResolution.attachment.url}`,
-            decodingLine,
-            warningsLine,
-            '```text',
-            contentResolution.content,
-            '```',
-        ]
-            .filter(Boolean)
-            .join('\n');
+        return spacetrim.spaceTrim((block) => `
+            File: ${attachmentLabel}${truncatedLabel}
+            URL: ${contentResolution.attachment.url}
+            ${block(metadataLines)}
+            \`\`\`text
+            ${block(resolvedContent)}
+            \`\`\`
+        `);
     }
     /**
      * Formats inline attachment-content context section for the model.
@@ -33822,11 +35134,14 @@
         if (resolvedContents.length === 0) {
             return '';
         }
-        return [
-            CHAT_ATTACHMENT_CONTENT_HEADING,
-            CHAT_ATTACHMENT_CONTENT_INSTRUCTION,
-            ...resolvedContents.map((resolvedContent) => formatResolvedChatAttachmentContent(resolvedContent)),
-        ].join('\n\n');
+        return spacetrim.spaceTrim((block) => `
+            ${CHAT_ATTACHMENT_CONTENT_HEADING}
+            ${CHAT_ATTACHMENT_CONTENT_INSTRUCTION}
+
+            ${block(resolvedContents
+        .map((resolvedContent) => formatResolvedChatAttachmentContent(resolvedContent))
+        .join('\n\n'))}
+        `);
     }
 
     /**
@@ -34985,9 +36300,11 @@
          * Creates the retry-history error message shared by all OpenAI-compatible model variants.
          */
         createAttemptHistoryError(finalErrorMessage) {
-            return new PipelineExecutionError(`All attempts failed. Attempt history:\n` +
-                formatUnsupportedParameterAttemptHistory(this.attemptStack) +
-                `\nFinal error: ${finalErrorMessage}`);
+            return new PipelineExecutionError(spacetrim.spaceTrim((block) => `
+                    All attempts failed. Attempt history:
+                    ${block(formatUnsupportedParameterAttemptHistory(this.attemptStack))}
+                    Final error: ${finalErrorMessage}
+                `));
         }
     }
 
@@ -37581,7 +38898,7 @@
                 });
             }
             let vectorStoreId = cachedVectorStoreId;
-            if (this.isNativeKnowledgeSearchEnabled && !vectorStoreId && knowledgeSources && knowledgeSources.length > 0) {
+            if (!vectorStoreId && knowledgeSources && knowledgeSources.length > 0) {
                 const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
                     client: await this.getClient(),
                     name,
@@ -37590,19 +38907,13 @@
                 });
                 vectorStoreId = vectorStoreResult.vectorStoreId;
             }
-            else if (this.isNativeKnowledgeSearchEnabled && vectorStoreId && this.options.isVerbose) {
+            else if (vectorStoreId && this.options.isVerbose) {
                 console.info('[🤰]', 'Using cached vector store for AgentKit agent', {
                     name,
                     vectorStoreId,
                 });
             }
-            if (!this.isNativeKnowledgeSearchEnabled) {
-                vectorStoreId = undefined;
-            }
-            const agentKitTools = this.buildAgentKitTools({
-                tools,
-                vectorStoreId,
-            });
+            const agentKitTools = this.buildAgentKitTools({ tools, vectorStoreId });
             const openAiAgentKitAgent = new agents.Agent({
                 name,
                 model: this.agentKitModelName,
@@ -37621,7 +38932,7 @@
                     name,
                     model: this.agentKitModelName,
                     toolCount: agentKitTools.length,
-                    hasVectorStore: this.isNativeKnowledgeSearchEnabled && Boolean(vectorStoreId),
+                    hasVectorStore: Boolean(vectorStoreId),
                 });
             }
             return preparedAgent;
@@ -38120,12 +39431,6 @@
         get agentKitOptions() {
             return this.options;
         }
-        /**
-         * Returns true when hosted OpenAI vector-store search should back `knowledgeSources`.
-         */
-        get isNativeKnowledgeSearchEnabled() {
-            return this.agentKitOptions.isNativeKnowledgeSearchEnabled !== false;
-        }
         /**
          * Discriminant for type guards.
          */
@@ -42649,7 +43954,7 @@
      */
     async function prepareSdkTranspilerContext(book, options) {
         const { agentName } = await parseAgentSource(book);
-        const rawModelRequirements = await createAgentModelRequirements(book, undefined, undefined, undefined, {
+        const modelRequirements = await createAgentModelRequirements(book, undefined, undefined, undefined, {
             agentReferenceResolver: options === null || options === void 0 ? void 0 : options.agentReferenceResolver,
             inlineKnowledgeSourceUploader: options === null || options === void 0 ? void 0 : options.inlineKnowledgeSourceUploader,
             teammateProfileResolver: options === null || options === void 0 ? void 0 : options.teammateProfileResolver,
@@ -42659,12 +43964,7 @@
         const knowledgeContent = knowledgeCommitments.map((commitment) => commitment.content.trim());
         const directKnowledge = knowledgeContent.filter((content) => !isKnowledgeSourceUrl(content));
         const knowledgeSources = knowledgeContent.filter((content) => isKnowledgeSourceUrl(content));
-        const isKnowledgeHandledWithRetrieval = directKnowledge.join('\n').length > SDK_TRANSPILER_KNOWLEDGE_THRESHOLD ||
-            knowledgeSources.length > 0 ||
-            knowledgeCommitments.length > 0;
-        const modelRequirements = normalizeSdkTranspilerModelRequirements(rawModelRequirements, {
-            isKnowledgeHandledWithRetrieval,
-        });
+        const isKnowledgeHandledWithRetrieval = directKnowledge.join('\n').length > SDK_TRANSPILER_KNOWLEDGE_THRESHOLD || knowledgeSources.length > 0;
         const transpiledTeam = createTranspiledTeamExportForContext({
             agentName,
             agentSource: book,
@@ -42682,36 +43982,6 @@
             transpiledTeam,
         };
     }
-    /**
-     * Removes the runtime-only knowledge-search tool from SDK harnesses that provide
-     * their own generated retrieval scaffold.
-     *
-     * @param modelRequirements - Raw compiled model requirements.
-     * @param options - Knowledge handling mode selected for the generated harness.
-     * @returns Model requirements safe to embed into a standalone SDK export.
-     */
-    function normalizeSdkTranspilerModelRequirements(modelRequirements, options) {
-        var _a;
-        if (!options.isKnowledgeHandledWithRetrieval) {
-            return modelRequirements;
-        }
-        const tools = (_a = modelRequirements.tools) === null || _a === void 0 ? void 0 : _a.filter((tool) => tool.name !== KNOWLEDGE_SEARCH_TOOL_NAME);
-        return {
-            ...modelRequirements,
-            systemMessage: removeKnowledgeSearchSystemSection(modelRequirements.systemMessage),
-            ...(tools ? { tools } : {}),
-        };
-    }
-    /**
-     * Removes the generated `## Knowledge Search` instructions from SDK exports
-     * that answer with the transpiler's native retrieval scaffold instead.
-     *
-     * @param systemMessage - Raw system message from compiled model requirements.
-     * @returns System message without the runtime-only knowledge-search section.
-     */
-    function removeKnowledgeSearchSystemSection(systemMessage) {
-        return systemMessage.replace(/(?:^|\n\n)## Knowledge Search[\s\S]*?(?=\n\n##|$)/, '').trim();
-    }
     /**
      * Detects whether one knowledge commitment points to a URL instead of inline text.
      *
@@ -45455,7 +46725,6 @@
     exports.GenericFormfactorDefinition = GenericFormfactorDefinition;
     exports.HTTP_STATUS_CODES = HTTP_STATUS_CODES;
     exports.ImageGeneratorFormfactorDefinition = ImageGeneratorFormfactorDefinition;
-    exports.KNOWLEDGE_SEARCH_TOOL_NAME = KNOWLEDGE_SEARCH_TOOL_NAME;
     exports.KnowledgeScrapeError = KnowledgeScrapeError;
     exports.LIMITS = LIMITS;
     exports.LimitReachedError = LimitReachedError;
@@ -45551,6 +46820,7 @@
     exports.createPipelineCollectionFromUrl = createPipelineCollectionFromUrl;
     exports.createPipelineExecutor = createPipelineExecutor;
     exports.createPipelineSubcollection = createPipelineSubcollection;
+    exports.createStandaloneBookLanguageMarkdown = createStandaloneBookLanguageMarkdown;
     exports.embeddingVectorToString = embeddingVectorToString;
     exports.executionReportJsonToString = executionReportJsonToString;
     exports.extractParameterNamesFromTask = extractParameterNamesFromTask;