@promptbook/cli 0.114.0-1 → 0.114.0-3

package/esm/src/llm-providers/openai/utils/loadOpenAiAgentsModule.d.ts

@@ -0,0 +1,203 @@
+/// <reference types="node" />
+/**
+ * Loads the OpenAI AgentKit SDK (`@openai/agents`) on demand
+ *
+ * Note: [🐌] The AgentKit SDK is one of the heaviest dependencies of Promptbook, loading it eagerly would slow down
+ *       every single run of the `ptbk` CLI utility even when no AgentKit agent is used
+ *
+ * @private internal utility of `@promptbook/openai`
+ */
+export declare const loadOpenAiAgentsModule: () => Promise<{
+    default: typeof import("@openai/agents");
+    applyPatchTool: typeof import("@openai/agents").applyPatchTool;
+    shellTool: typeof import("@openai/agents").shellTool;
+    realtime: typeof import("@openai/agents-realtime");
+    RuntimeEventEmitter: typeof import("events");
+    Agent: typeof import("@openai/agents").Agent;
+    AgentsError: typeof import("@openai/agents").AgentsError;
+    GuardrailExecutionError: typeof import("@openai/agents").GuardrailExecutionError;
+    InputGuardrailTripwireTriggered: typeof import("@openai/agents").InputGuardrailTripwireTriggered;
+    MaxTurnsExceededError: typeof import("@openai/agents").MaxTurnsExceededError;
+    ModelBehaviorError: typeof import("@openai/agents").ModelBehaviorError;
+    OutputGuardrailTripwireTriggered: typeof import("@openai/agents").OutputGuardrailTripwireTriggered;
+    ToolInputGuardrailTripwireTriggered: typeof import("@openai/agents").ToolInputGuardrailTripwireTriggered;
+    ToolOutputGuardrailTripwireTriggered: typeof import("@openai/agents").ToolOutputGuardrailTripwireTriggered;
+    ToolCallError: typeof import("@openai/agents").ToolCallError;
+    ToolTimeoutError: typeof import("@openai/agents").ToolTimeoutError;
+    UserError: typeof import("@openai/agents").UserError;
+    SystemError: typeof import("@openai/agents").SystemError;
+    RunAgentUpdatedStreamEvent: typeof import("@openai/agents").RunAgentUpdatedStreamEvent;
+    RunRawModelStreamEvent: typeof import("@openai/agents").RunRawModelStreamEvent;
+    RunItemStreamEvent: typeof import("@openai/agents").RunItemStreamEvent;
+    defineOutputGuardrail: typeof import("@openai/agents").defineOutputGuardrail;
+    ToolGuardrailFunctionOutputFactory: {
+        allow(outputInfo?: any): import("@openai/agents").ToolGuardrailFunctionOutput;
+        rejectContent(message: string, outputInfo?: any): import("@openai/agents").ToolGuardrailFunctionOutput;
+        throwException(outputInfo?: any): import("@openai/agents").ToolGuardrailFunctionOutput;
+    };
+    defineToolInputGuardrail: typeof import("@openai/agents").defineToolInputGuardrail;
+    defineToolOutputGuardrail: typeof import("@openai/agents").defineToolOutputGuardrail;
+    resolveToolInputGuardrails: typeof import("@openai/agents").resolveToolInputGuardrails;
+    resolveToolOutputGuardrails: typeof import("@openai/agents").resolveToolOutputGuardrails;
+    getHandoff: typeof import("@openai/agents").getHandoff;
+    getTransferMessage: typeof import("@openai/agents").getTransferMessage;
+    Handoff: typeof import("@openai/agents").Handoff;
+    handoff: typeof import("@openai/agents").handoff;
+    assistant: typeof import("@openai/agents").assistant;
+    system: typeof import("@openai/agents").system;
+    user: typeof import("@openai/agents").user;
+    extractAllTextOutput: typeof import("@openai/agents").extractAllTextOutput;
+    RunHandoffCallItem: typeof import("@openai/agents").RunHandoffCallItem;
+    RunHandoffOutputItem: typeof import("@openai/agents").RunHandoffOutputItem;
+    RunMessageOutputItem: typeof import("@openai/agents").RunMessageOutputItem;
+    RunReasoningItem: typeof import("@openai/agents").RunReasoningItem;
+    RunToolApprovalItem: typeof import("@openai/agents").RunToolApprovalItem;
+    RunToolCallItem: typeof import("@openai/agents").RunToolCallItem;
+    RunToolCallOutputItem: typeof import("@openai/agents").RunToolCallOutputItem;
+    AgentHooks: typeof import("@openai/agents").AgentHooks;
+    getLogger: typeof import("@openai/agents").getLogger;
+    applyDiff: typeof import("@openai/agents").applyDiff;
+    getAllMcpTools: typeof import("@openai/agents").getAllMcpTools;
+    invalidateServerToolsCache: typeof import("@openai/agents").invalidateServerToolsCache;
+    mcpToFunctionTool: typeof import("@openai/agents").mcpToFunctionTool;
+    MCPServerStdio: typeof import("@openai/agents").MCPServerStdio;
+    MCPServerStreamableHttp: typeof import("@openai/agents").MCPServerStreamableHttp;
+    MCPServerSSE: typeof import("@openai/agents").MCPServerSSE;
+    MCPServers: typeof import("@openai/agents").MCPServers;
+    connectMcpServers: typeof import("@openai/agents").connectMcpServers;
+    createMCPToolStaticFilter: typeof import("@openai/agents").createMCPToolStaticFilter;
+    OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME: "OPENAI_DEFAULT_MODEL";
+    gpt5ReasoningSettingsRequired: typeof import("@openai/agents").gpt5ReasoningSettingsRequired;
+    getDefaultModel: typeof import("@openai/agents").getDefaultModel;
+    getDefaultModelSettings: typeof import("@openai/agents").getDefaultModelSettings;
+    isGpt5Default: typeof import("@openai/agents").isGpt5Default;
+    setDefaultModelProvider: typeof import("@openai/agents").setDefaultModelProvider;
+    RunResult: typeof import("@openai/agents").RunResult;
+    StreamedRunResult: typeof import("@openai/agents").StreamedRunResult;
+    run: typeof import("@openai/agents").run;
+    Runner: typeof import("@openai/agents").Runner;
+    RunContext: typeof import("@openai/agents").RunContext;
+    RunState: typeof import("@openai/agents").RunState;
+    computerTool: typeof import("@openai/agents").computerTool;
+    hostedMcpTool: typeof import("@openai/agents").hostedMcpTool;
+    tool: typeof import("@openai/agents").tool;
+    invokeFunctionTool: typeof import("@openai/agents").invokeFunctionTool;
+    getGlobalTraceProvider: typeof import("@openai/agents").getGlobalTraceProvider;
+    TraceProvider: typeof import("@openai/agents").TraceProvider;
+    runToolInputGuardrails: typeof import("@openai/agents").runToolInputGuardrails;
+    runToolOutputGuardrails: typeof import("@openai/agents").runToolOutputGuardrails;
+    RequestUsage: typeof import("@openai/agents").RequestUsage;
+    Usage: typeof import("@openai/agents").Usage;
+    isOpenAIResponsesCompactionAwareSession: typeof import("@openai/agents").isOpenAIResponsesCompactionAwareSession;
+    MemorySession: typeof import("@openai/agents").MemorySession;
+    protocol: typeof import("@openai/agents-core/dist/types/protocol");
+    addTraceProcessor(processor: import("@openai/agents").TracingProcessor): void;
+    setTraceProcessors(processors: import("@openai/agents").TracingProcessor[]): void;
+    setTracingDisabled(disabled: boolean): void;
+    startTraceExportLoop(): void;
+    getCurrentSpan: typeof import("@openai/agents").getCurrentSpan;
+    getCurrentTrace: typeof import("@openai/agents").getCurrentTrace;
+    getOrCreateTrace: typeof import("@openai/agents").getOrCreateTrace;
+    resetCurrentSpan: typeof import("@openai/agents").resetCurrentSpan;
+    setCurrentSpan: typeof import("@openai/agents").setCurrentSpan;
+    withTrace: typeof import("@openai/agents").withTrace;
+    BatchTraceProcessor: typeof import("@openai/agents").BatchTraceProcessor;
+    ConsoleSpanExporter: typeof import("@openai/agents").ConsoleSpanExporter;
+    NoopSpan: typeof import("@openai/agents").NoopSpan;
+    Span: typeof import("@openai/agents").Span;
+    NoopTrace: typeof import("@openai/agents").NoopTrace;
+    Trace: typeof import("@openai/agents").Trace;
+    generateGroupId: typeof import("@openai/agents").generateGroupId;
+    generateSpanId: typeof import("@openai/agents").generateSpanId;
+    generateTraceId: typeof import("@openai/agents").generateTraceId;
+    createResponseSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").ResponseSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").ResponseSpanData>;
+    createAgentSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").AgentSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").AgentSpanData>;
+    createFunctionSpan(options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").FunctionSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").FunctionSpanData>;
+    createHandoffSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").HandoffSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").HandoffSpanData>;
+    createGenerationSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").GenerationSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").GenerationSpanData>;
+    createCustomSpan(options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").CustomSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").CustomSpanData>;
+    createGuardrailSpan(options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").GuardrailSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").GuardrailSpanData>;
+    createTranscriptionSpan(options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").TranscriptionSpanData>> & {
+        data: {
+            input: {
+                data: string;
+                format: (string & {}) | "pcm";
+            };
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").TranscriptionSpanData>;
+    createSpeechSpan(options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").SpeechSpanData>> & {
+        data: {
+            output: {
+                data: string;
+                format: (string & {}) | "pcm";
+            };
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").SpeechSpanData>;
+    createSpeechGroupSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").SpeechGroupSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").SpeechGroupSpanData>;
+    createMCPListToolsSpan(options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").MCPListToolsSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined): import("@openai/agents").Span<import("@openai/agents").MCPListToolsSpanData>;
+    withResponseSpan: <TOutput>(fn: (span: import("@openai/agents").Span<import("@openai/agents").ResponseSpanData>) => Promise<TOutput>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").ResponseSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput>;
+    withAgentSpan: <TOutput_1>(fn: (span: import("@openai/agents").Span<import("@openai/agents").AgentSpanData>) => Promise<TOutput_1>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").AgentSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_1>;
+    withFunctionSpan: <TOutput_2>(fn: (span: import("@openai/agents").Span<import("@openai/agents").FunctionSpanData>) => Promise<TOutput_2>, options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").FunctionSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_2>;
+    withHandoffSpan: <TOutput_3>(fn: (span: import("@openai/agents").Span<import("@openai/agents").HandoffSpanData>) => Promise<TOutput_3>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").HandoffSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_3>;
+    withGenerationSpan: <TOutput_4>(fn: (span: import("@openai/agents").Span<import("@openai/agents").GenerationSpanData>) => Promise<TOutput_4>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").GenerationSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_4>;
+    withCustomSpan: <TOutput_5>(fn: (span: import("@openai/agents").Span<import("@openai/agents").CustomSpanData>) => Promise<TOutput_5>, options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").CustomSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_5>;
+    withGuardrailSpan: <TOutput_6>(fn: (span: import("@openai/agents").Span<import("@openai/agents").GuardrailSpanData>) => Promise<TOutput_6>, options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").GuardrailSpanData>> & {
+        data: {
+            name: string;
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_6>;
+    withTranscriptionSpan: <TOutput_7>(fn: (span: import("@openai/agents").Span<import("@openai/agents").TranscriptionSpanData>) => Promise<TOutput_7>, options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").TranscriptionSpanData>> & {
+        data: {
+            input: {
+                data: string;
+                format: (string & {}) | "pcm";
+            };
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_7>;
+    withSpeechSpan: <TOutput_8>(fn: (span: import("@openai/agents").Span<import("@openai/agents").SpeechSpanData>) => Promise<TOutput_8>, options: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").SpeechSpanData>> & {
+        data: {
+            output: {
+                data: string;
+                format: (string & {}) | "pcm";
+            };
+        };
+    }, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_8>;
+    withSpeechGroupSpan: <TOutput_9>(fn: (span: import("@openai/agents").Span<import("@openai/agents").SpeechGroupSpanData>) => Promise<TOutput_9>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").SpeechGroupSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_9>;
+    withMCPListToolsSpan: <TOutput_10>(fn: (span: import("@openai/agents").Span<import("@openai/agents").MCPListToolsSpanData>) => Promise<TOutput_10>, options?: import("@openai/agents-core/types").DeepPartial<import("@openai/agents-core/dist/tracing/provider").CreateSpanOptions<import("@openai/agents").MCPListToolsSpanData>> | undefined, parent?: import("@openai/agents").Trace | import("@openai/agents").Span<any> | undefined) => Promise<TOutput_10>;
+    OpenAIProvider: typeof import("@openai/agents").OpenAIProvider;
+    OpenAIResponsesModel: typeof import("@openai/agents").OpenAIResponsesModel;
+    OpenAIChatCompletionsModel: typeof import("@openai/agents").OpenAIChatCompletionsModel;
+    setDefaultOpenAIClient: typeof import("@openai/agents").setDefaultOpenAIClient;
+    setOpenAIAPI: typeof import("@openai/agents").setOpenAIAPI;
+    setDefaultOpenAIKey: typeof import("@openai/agents").setDefaultOpenAIKey;
+    setTracingExportApiKey: typeof import("@openai/agents").setTracingExportApiKey;
+    setDefaultOpenAITracingExporter: typeof import("@openai/agents").setDefaultOpenAITracingExporter;
+    OpenAITracingExporter: typeof import("@openai/agents").OpenAITracingExporter;
+    webSearchTool: typeof import("@openai/agents").webSearchTool;
+    fileSearchTool: typeof import("@openai/agents").fileSearchTool;
+    codeInterpreterTool: typeof import("@openai/agents").codeInterpreterTool;
+    imageGenerationTool: typeof import("@openai/agents").imageGenerationTool;
+    OpenAIConversationsSession: typeof import("@openai/agents").OpenAIConversationsSession;
+    startOpenAIConversationsSession: typeof import("@openai/agents").startOpenAIConversationsSession;
+    OpenAIResponsesCompactionSession: typeof import("@openai/agents").OpenAIResponsesCompactionSession;
+}>;

package/esm/src/llm-providers/openai/utils/uploadFilesToOpenAi.d.ts

@@ -1,4 +1,4 @@
-import OpenAI from 'openai';
+import type OpenAI from 'openai';
 /**
  * Uploads files to OpenAI and returns their IDs
  *

package/esm/src/utils/misc/createLazyModuleLoader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Creates a loader which imports one module on the first call and reuses the very same module afterwards
+ *
+ * Note: [🐌] Heavy third-party dependencies are imported lazily to keep the startup of the Promptbook CLI fast.
+ *       A statically imported dependency is loaded every single time the bundle is loaded, even when the running
+ *       command never touches it. A lazily imported dependency is loaded only when the feature is really used.
+ *
+ * @example
+ * const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+ * const { JSDOM } = await loadJsdomModule();
+ *
+ * @private internal utility of Promptbook
+ */
+export declare function createLazyModuleLoader<TModule>(importModule: () => Promise<TModule>): () => Promise<TModule>;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.113.1-0`).
+ * It follows semantic versioning (e.g., `0.114.0-2`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-1",
+    "version": "0.114.0-3",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/book-2.0/book-language-documentation/BookLanguageManualDictionary.ts

@@ -98,9 +98,7 @@ export type BookLanguageManualDictionary = {
     readonly metadataLabels: {
         readonly bookLanguageVersion: string;
         readonly generatedAt: string;
-        readonly commitmentGroups: string;
-        readonly implementedCommitments: string;
-        readonly placeholderCommitments: string;
+        readonly commitmentCount: string;
     };
 
     /**
@@ -144,7 +142,6 @@ export type BookLanguageManualDictionary = {
     readonly primitivesSections: {
         readonly coreSyntax: BookLanguageManualChapter;
         readonly references: BookLanguageManualChapter;
-        readonly keywordsTitle: string;
     };
 
     /**
@@ -159,18 +156,7 @@ export type BookLanguageManualDictionary = {
      * Labels used in every commitment catalog entry.
      */
     readonly commitmentLabels: {
-        readonly status: string;
         readonly aliases: string;
-        readonly semantics: string;
-        readonly typeSchema: string;
-        readonly blockSchema: string;
-        readonly lowLevelNotice: string;
-        readonly usage: string;
-        readonly usageOccurrence: string;
-        readonly usageOccurrences: string;
-        readonly statusImplemented: string;
-        readonly statusPlaceholder: string;
-        readonly noAliases: string;
     };
 
     /**

package/src/book-2.0/book-language-documentation/bookLanguageDocumentationExamples.ts

@@ -60,13 +60,12 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
         `),
     },
     {
-        id: 'use-project-and-wallet-integration-agent',
+        id: 'use-project-integration-agent',
         source: 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.

package/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.ts

@@ -1,5 +1,4 @@
 import { spaceTrim } from 'spacetrim';
-import { NotYetImplementedCommitmentDefinition } from '../../commitments/_base/NotYetImplementedCommitmentDefinition';
 import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
 import { parseAgentSourceWithCommitments } from '../agent-source/parseAgentSourceWithCommitments';
 import type { string_book } from '../agent-source/string_book';
@@ -172,14 +171,10 @@ export function createStandaloneBookLanguageMarkdown(
         : [];
     const manualCommitments = [...catalogCommitments, ...lowLevelCommitments];
     const generatedAtIso = new Date().toISOString();
-    const placeholderCommitmentCount = manualCommitments.filter(
-        ({ primary }) => primary instanceof NotYetImplementedCommitmentDefinition,
-    ).length;
     const catalogTitleSuffix = isServerSpecificManual
         ? dictionary.commitmentCatalogTitleSuffixes.usedFirst
         : dictionary.commitmentCatalogTitleSuffixes.all;
-
-    const allCommitmentKeywords = manualCommitments.flatMap(({ primary, aliases }) => [primary.type, ...aliases]);
+    const commitmentSectionAnchorByType = createCommitmentSectionAnchorByType(manualCommitments);
 
     return spaceTrim(
         // [✨]
@@ -190,11 +185,7 @@ export function createStandaloneBookLanguageMarkdown(
 
             - ${dictionary.metadataLabels.bookLanguageVersion}: \`${BOOK_LANGUAGE_VERSION}\`
             - ${dictionary.metadataLabels.generatedAt}: \`${generatedAtIso}\`
-            - ${dictionary.metadataLabels.commitmentGroups}: \`${manualCommitments.length}\`
-            - ${dictionary.metadataLabels.implementedCommitments}: \`${
-            manualCommitments.length - placeholderCommitmentCount
-        }\`
-            - ${dictionary.metadataLabels.placeholderCommitments}: \`${placeholderCommitmentCount}\`
+            - ${dictionary.metadataLabels.commitmentCount}: \`${manualCommitments.length}\`
 
             ## <a id="table-of-contents"></a>${dictionary.tableOfContentsTitle}
 
@@ -203,14 +194,18 @@ export function createStandaloneBookLanguageMarkdown(
             - [${dictionary.chapters.howToStructure.title}](#how-to-structure-good-agents)
             - [${dictionary.chapters.primitives.title}](#primitives-and-constructs-reference)
             - [${dictionary.chapters.commitmentCatalog.title}${catalogTitleSuffix}](#commitment-catalog)
+            ${block(renderCommitmentCatalogTableOfContents(catalogCommitments))}
             - [${dictionary.chapters.examples.title}](#end-to-end-examples)
             - [${dictionary.chapters.pitfalls.title}](#do-nots-and-common-pitfalls)
             - [${dictionary.chapters.tutorial.title}](#build-an-agent-from-scratch-offline-tutorial)
-            ${
+            ${block(
                 isLowLevelCommitmentsIncluded
-                    ? `- [${dictionary.chapters.lowLevelCommitments.title}](#low-level-commitments)`
-                    : ''
-            }
+                    ? spaceTrim(`
+                        - [${dictionary.chapters.lowLevelCommitments.title}](#low-level-commitments)
+                        ${renderCommitmentCatalogTableOfContents(lowLevelCommitments)}
+                    `)
+                    : '',
+            )}
 
             ## <a id="what-book-language-is"></a>${dictionary.chapters.whatIs.title}
 
@@ -254,25 +249,23 @@ export function createStandaloneBookLanguageMarkdown(
 
             ${block(dictionary.primitivesSections.references.body)}
 
-            ### ${dictionary.primitivesSections.keywordsTitle}
-
-            ${block(getSafeCodeBlock(allCommitmentKeywords.join(', '), 'text'))}
-
-            <a id="commitment-catalog-all-commitments"></a>
-
             ## <a id="commitment-catalog"></a>${dictionary.chapters.commitmentCatalog.title}${catalogTitleSuffix}
 
             ${block(dictionary.chapters.commitmentCatalog.body)}
 
-            ${block(renderCommitmentCatalogSections(catalogCommitments, commitmentUsageByType, dictionary))}
+            ${block(renderCommitmentCatalogSections(catalogCommitments, dictionary))}
 
             ## <a id="end-to-end-examples"></a>${dictionary.chapters.examples.title}
 
             ${block(
                 isServerSpecificManual
-                    ? selectedAgents.map((agent) => renderBakedAgentExampleSection(agent, dictionary)).join('\n\n')
+                    ? selectedAgents
+                          .map((agent) =>
+                              renderBakedAgentExampleSection(agent, dictionary, commitmentSectionAnchorByType),
+                          )
+                          .join('\n\n')
                     : bookLanguageDocumentationExamples
-                          .map((example) => renderExampleSection(example, dictionary))
+                          .map((example) => renderExampleSection(example, dictionary, commitmentSectionAnchorByType))
                           .join('\n\n'),
             )}
 
@@ -296,7 +289,7 @@ export function createStandaloneBookLanguageMarkdown(
 
             ${block(
                 isLowLevelCommitmentsIncluded
-                    ? renderLowLevelCommitmentsChapter(lowLevelCommitments, commitmentUsageByType, dictionary)
+                    ? renderLowLevelCommitmentsChapter(lowLevelCommitments, dictionary)
                     : '',
             )}
 
@@ -345,7 +338,6 @@ function renderDetectedCommitmentList(
  * Renders every commitment section of one catalog chapter.
  *
  * @param commitmentGroups - Commitment groups to render, in final order.
- * @param commitmentUsageByType - Selected-agent occurrence counts by primary type.
  * @param dictionary - Translated labels of the manual.
  * @returns Markdown sections joined by blank lines.
  *
@@ -353,14 +345,12 @@ function renderDetectedCommitmentList(
  */
 function renderCommitmentCatalogSections(
     commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
-    commitmentUsageByType: ReadonlyMap<string, number>,
     dictionary: BookLanguageManualDictionary,
 ): string {
     return commitmentGroups
         .map((groupedCommitment) =>
             renderCommitmentCatalogSection({
                 groupedCommitment,
-                usageCount: commitmentUsageByType.get(groupedCommitment.primary.type) || 0,
                 dictionary,
             }),
         )
@@ -371,7 +361,6 @@ function renderCommitmentCatalogSections(
  * Renders the closing chapter documenting low-level commitments.
  *
  * @param commitmentGroups - Low-level commitment groups, in final order.
- * @param commitmentUsageByType - Selected-agent occurrence counts by primary type.
  * @param dictionary - Translated labels of the manual.
  * @returns Markdown chapter for low-level commitments.
  *
@@ -379,7 +368,6 @@ function renderCommitmentCatalogSections(
  */
 function renderLowLevelCommitmentsChapter(
     commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
-    commitmentUsageByType: ReadonlyMap<string, number>,
     dictionary: BookLanguageManualDictionary,
 ): string {
     return spaceTrim(
@@ -388,11 +376,55 @@ function renderLowLevelCommitmentsChapter(
 
             ${block(dictionary.chapters.lowLevelCommitments.body)}
 
-            ${block(renderCommitmentCatalogSections(commitmentGroups, commitmentUsageByType, dictionary))}
+            ${block(renderCommitmentCatalogSections(commitmentGroups, dictionary))}
         `,
     );
 }
 
+/**
+ * Renders links from the manual table of contents to the commitment sections.
+ *
+ * @param commitmentGroups - Commitment sections included in the manual.
+ * @returns Indented markdown links ordered like the catalog.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function renderCommitmentCatalogTableOfContents(
+    commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
+): string {
+    return commitmentGroups
+        .map(
+            ({ primary }) =>
+                `    - [${primary.icon} \`${primary.type}\`](#commitment-${toStableAnchorId(primary.type)})`,
+        )
+        .join('\n');
+}
+
+/**
+ * Maps every recognized spelling of a documented commitment to its stable section anchor.
+ *
+ * @param commitmentGroups - Commitment sections included in the manual.
+ * @returns Canonical anchor id by parsed commitment type.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function createCommitmentSectionAnchorByType(
+    commitmentGroups: ReadonlyArray<BookLanguageManualCommitmentGroup>,
+): ReadonlyMap<string, string> {
+    const anchorByType = new Map<string, string>();
+
+    for (const { primary, aliases } of commitmentGroups) {
+        const anchorId = `commitment-${toStableAnchorId(primary.type)}`;
+        anchorByType.set(primary.type, anchorId);
+
+        for (const alias of aliases) {
+            anchorByType.set(alias, anchorId);
+        }
+    }
+
+    return anchorByType;
+}
+
 /**
  * Renders the "don't vs do" list of common authoring pitfalls.
  *
@@ -523,11 +555,12 @@ function prioritizeGroupedCommitments(
 function renderBakedAgentExampleSection(
     agent: BookLanguageDocumentationAgent,
     dictionary: BookLanguageManualDictionary,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
 ): string {
     const usedCommitmentTypes = Array.from(
         new Set(parseAgentSourceWithCommitments(agent.agentSource).commitments.map((commitment) => commitment.type)),
     );
-    const usedCommitmentsMarkdown = usedCommitmentTypes.map((type) => `\`${type}\``).join(', ');
+    const usedCommitmentsMarkdown = renderCommitmentSectionLinks(usedCommitmentTypes, commitmentSectionAnchorByType);
 
     return spaceTrim(
         (block) => `
@@ -556,6 +589,7 @@ function renderBakedAgentExampleSection(
 function renderExampleSection(
     example: BookLanguageDocumentationExample,
     dictionary: BookLanguageManualDictionary,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
 ): string {
     const exampleText = dictionary.exampleTexts[example.id];
 
@@ -569,6 +603,11 @@ function renderExampleSection(
 
             **${dictionary.exampleLabels.goal}:** ${exampleText.goal}
 
+            **${dictionary.exampleLabels.commitmentsUsed}:** ${renderCommitmentSectionLinks(
+            parseAgentSourceWithCommitments(example.source as string_book).commitments.map((commitment) => commitment.type),
+            commitmentSectionAnchorByType,
+        )}
+
             **${dictionary.exampleLabels.fullSource}**
 
             ${block(getSafeCodeBlock(example.source, 'book'))}
@@ -579,3 +618,24 @@ function renderExampleSection(
         `,
     );
 }
+
+/**
+ * Renders unique commitment links used by an end-to-end example.
+ *
+ * @param commitmentTypes - Commitment types in their source order.
+ * @param commitmentSectionAnchorByType - Documented commitment anchors by parsed type.
+ * @returns Comma-separated markdown links, or an empty string when none are documented.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+function renderCommitmentSectionLinks(
+    commitmentTypes: ReadonlyArray<string>,
+    commitmentSectionAnchorByType: ReadonlyMap<string, string>,
+): string {
+    return Array.from(new Set(commitmentTypes))
+        .flatMap((type) => {
+            const anchorId = commitmentSectionAnchorByType.get(type);
+            return anchorId ? [`[\`${type}\`](#${anchorId})`] : [];
+        })
+        .join(', ');
+}