@promptbook/cli 0.114.0-0 → 0.114.0-2

package/esm/scripts/run-agent-chat/runCoderPing.d.ts

@@ -0,0 +1,48 @@
+import type { ThinkingLevel } from '../../src/cli/cli-commands/coder/ThinkingLevel';
+import type { PromptRunnerHarnessName } from '../../src/cli/cli-commands/common/promptRunnerCliOptions';
+/**
+ * Options for one `ptbk coder ping` execution.
+ */
+export type RunCoderPingOptions = {
+    /**
+     * Harness used for the disposable turn.
+     */
+    readonly agentName: PromptRunnerHarnessName;
+    /**
+     * Optional model passed to the harness.
+     */
+    readonly model?: string;
+    /**
+     * Optional reasoning effort passed to the harness.
+     */
+    readonly thinkingLevel?: ThinkingLevel;
+    /**
+     * Whether the harness should receive the shared no-UI option.
+     */
+    readonly isUiDisabled: boolean;
+    /**
+     * Whether the harness may spend credits when its quota is exhausted.
+     */
+    readonly isCreditsAllowed: boolean;
+};
+/**
+ * Result of one `ptbk coder ping` execution.
+ */
+export type CoderPingResult = {
+    /**
+     * Text returned by the harness after the dummy task.
+     */
+    readonly result: string;
+    /**
+     * Time spent executing the disposable harness turn in milliseconds.
+     */
+    readonly elapsedTimeMs: number;
+};
+/**
+ * Runs one small harness/model turn in a disposable temporary project.
+ *
+ * The temporary project is outside the caller's repository, so even a harness
+ * that writes files cannot change the project from which `ptbk coder ping` was
+ * started.
+ */
+export declare function runCoderPing(options: RunCoderPingOptions): Promise<CoderPingResult>;

package/esm/scripts/run-codex-prompts/prompts/findNextTodoPrompt.d.ts

@@ -1,7 +1,8 @@
 import type { PromptFile } from './types/PromptFile';
 import type { PromptSelection } from './types/PromptSelection';
+import type { PromptRunnerIdentity } from './isPromptCompatibleWithRunner';
 import type { PriorityFilter } from './priorityFilter';
 /**
  * Selects the next runnable prompt based on priority.
  */
-export declare function findNextTodoPrompt(files: PromptFile[], priorityFilter?: PriorityFilter): PromptSelection | undefined;
+export declare function findNextTodoPrompt(files: PromptFile[], priorityFilter?: PriorityFilter, promptRunnerIdentity?: PromptRunnerIdentity): PromptSelection | undefined;

package/esm/scripts/run-codex-prompts/prompts/isPromptCompatibleWithRunner.d.ts

@@ -0,0 +1,27 @@
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSection } from './types/PromptSection';
+/**
+ * Names of the harness and model currently selected for a coder run.
+ */
+export type PromptRunnerIdentity = {
+    /**
+     * Stable harness identifier, for example `github-copilot`.
+     */
+    readonly harnessName?: string;
+    /**
+     * Effective model identifier, for example `gpt-5.5`.
+     */
+    readonly modelName?: string;
+};
+/**
+ * Checks whether a prompt is unrestricted or matches the selected harness/model.
+ *
+ * A prompt status line can contain one or more backtick-delimited model or harness
+ * names. Matching is intentionally based on normalized substrings so a token such as
+ * `gpt` selects any `gpt-*` model and `opus` selects a `claude-opus-*` model.
+ */
+export declare function isPromptCompatibleWithRunner(file: PromptFile, section: PromptSection, promptRunnerIdentity?: PromptRunnerIdentity): boolean;
+/**
+ * Extracts model and harness tokens from a prompt status line.
+ */
+export declare function extractPromptRunnerTokens(statusLine: string): string[];

package/esm/scripts/run-codex-prompts/prompts/listRunnablePrompts.d.ts

@@ -1,7 +1,8 @@
 import type { PromptFile } from './types/PromptFile';
 import type { PromptSelection } from './types/PromptSelection';
+import { type PromptRunnerIdentity } from './isPromptCompatibleWithRunner';
 import type { PriorityFilter } from './priorityFilter';
 /**
  * Lists todo prompts that are ready to run (no authoring placeholders).
  */
-export declare function listRunnablePrompts(files: PromptFile[], priorityFilter?: PriorityFilter): PromptSelection[];
+export declare function listRunnablePrompts(files: PromptFile[], priorityFilter?: PriorityFilter, promptRunnerIdentity?: PromptRunnerIdentity): PromptSelection[];

package/esm/scripts/run-codex-prompts/prompts/listUpcomingTasks.d.ts

@@ -1,7 +1,8 @@
 import type { PromptFile } from './types/PromptFile';
 import type { UpcomingTask } from './types/UpcomingTask';
+import type { PromptRunnerIdentity } from './isPromptCompatibleWithRunner';
 import type { PriorityFilter } from './priorityFilter';
 /**
  * Lists upcoming tasks that are ready to run (no authoring placeholders).
  */
-export declare function listUpcomingTasks(files: PromptFile[], priorityFilter?: PriorityFilter): UpcomingTask[];
+export declare function listUpcomingTasks(files: PromptFile[], priorityFilter?: PriorityFilter, promptRunnerIdentity?: PromptRunnerIdentity): UpcomingTask[];

package/esm/scripts/run-codex-prompts/prompts/replacePromptTodoStatusLine.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Replaces the complete todo status line while preserving its indentation.
+ *
+ * The complete line is replaced because a todo status can contain a required
+ * model/harness token in addition to priority markers.
+ */
+export declare function replacePromptTodoStatusLine(line: string, replacementStatusLine: string): string;

package/esm/scripts/run-codex-prompts/testing/TestBeforeMode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Modes supported by `ptbk coder run --test-before`.
+ */
+export declare const TEST_BEFORE_MODE_VALUES: readonly ["no", "yes-and-fail", "yes-and-fix"];
+/**
+ * Behavior requested for the pre-coding verification run.
+ */
+export type TestBeforeMode = (typeof TEST_BEFORE_MODE_VALUES)[number];
+/**
+ * Default verification command used when a pre-coding mode is enabled without an explicit `--test` command.
+ */
+export declare const DEFAULT_CODER_TEST_COMMAND = "npm test";
+/**
+ * Checks whether a value is a supported `--test-before` mode.
+ */
+export declare function isTestBeforeMode(value: string): value is TestBeforeMode;

package/esm/scripts/run-codex-prompts/testing/createTestBeforeRepairPrompt.d.ts

@@ -0,0 +1,9 @@
+import type { PromptSelection } from '../prompts/types/PromptSelection';
+/**
+ * Creates the one queue prompt used to repair a pre-existing test failure.
+ */
+export declare function createTestBeforeRepairPrompt(options: {
+    readonly projectPath: string;
+    readonly testCommand: string;
+    readonly testOutput: string;
+}): Promise<PromptSelection>;

package/esm/scripts/run-codex-prompts/testing/limitTestOutput.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Limits test output while keeping the end of the output, where test runners usually print the failure summary.
+ */
+export declare function limitTestOutput(testOutput: string): string;

package/esm/scripts/run-codex-prompts/testing/runPromptTestCommand.d.ts

@@ -1,7 +1,7 @@
 /**
  * Options for running one verification command after a coding attempt.
  */
-type RunPromptTestCommandOptions = {
+export type RunPromptTestCommandOptions = {
     command: string;
     projectPath: string;
     scriptPath: string;
@@ -12,4 +12,3 @@ type RunPromptTestCommandOptions = {
  * Runs the configured verification command inside the project root and returns its output.
  */
 export declare function runPromptTestCommand(options: RunPromptTestCommandOptions): Promise<string>;
-export {};

package/esm/scripts/run-codex-prompts/testing/runTestBefore.d.ts

@@ -0,0 +1,24 @@
+import type { WaitForCoderRunPauseCheckpoint } from '../common/CoderRunPauseCheckpoint';
+import { runPromptTestCommand } from './runPromptTestCommand';
+/**
+ * Result of the verification command executed before coding starts.
+ */
+export type TestBeforeResult = {
+    /**
+     * Whether the verification command completed successfully.
+     */
+    readonly isPassed: boolean;
+    /**
+     * Combined output produced by the verification command.
+     */
+    readonly testOutput: string;
+};
+/**
+ * Runs the configured verification command before the first coding prompt.
+ */
+export declare function runTestBefore(options: {
+    readonly testCommand: string;
+    readonly projectPath: string;
+    readonly waitForPauseCheckpoint?: WaitForCoderRunPauseCheckpoint;
+    readonly runPromptTestCommandExecutor?: typeof runPromptTestCommand;
+}): Promise<TestBeforeResult>;

package/esm/scripts/run-codex-prompts/ui/buildRunUiFrameShared.d.ts

@@ -67,6 +67,7 @@ export declare function buildControlPills(options: {
  * Builds the coder-run control pills shown in the footer box.
  */
 export declare function buildCoderRunControlPills(options: {
+    readonly phase: CoderRunPhase;
     readonly pauseControl: string;
     readonly pendingEnterLabel: string | undefined;
     readonly isEndAfterCurrentPromptRequested: boolean;

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

@@ -86,9 +86,7 @@ export type BookLanguageManualDictionary = {
     readonly metadataLabels: {
         readonly bookLanguageVersion: string;
         readonly generatedAt: string;
-        readonly commitmentGroups: string;
-        readonly implementedCommitments: string;
-        readonly placeholderCommitments: string;
+        readonly commitmentCount: string;
     };
     /**
      * Heading of the table of contents.
@@ -128,7 +126,6 @@ export type BookLanguageManualDictionary = {
     readonly primitivesSections: {
         readonly coreSyntax: BookLanguageManualChapter;
         readonly references: BookLanguageManualChapter;
-        readonly keywordsTitle: string;
     };
     /**
      * Suffixes distinguishing a server-specific catalog from the portable one.
@@ -141,18 +138,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;
     };
     /**
      * Labels used by end-to-end example sections.

package/esm/src/book-2.0/book-language-documentation/getBookLanguageManualCommitmentGroups.d.ts

@@ -16,7 +16,7 @@ export type BookLanguageManualCommitmentGroups = {
      */
     readonly documented: ReadonlyArray<BookLanguageManualCommitmentGroup>;
     /**
-     * Low-level and unfinished commitments documented in their own closing chapter.
+     * Low-level commitments documented in their own closing chapter.
      */
     readonly lowLevel: ReadonlyArray<BookLanguageManualCommitmentGroup>;
 };

package/esm/src/book-2.0/book-language-documentation/renderCommitmentCatalogSection.d.ts

@@ -10,10 +10,6 @@ export type RenderCommitmentCatalogSectionOptions = {
      * Grouped commitment definition with aliases.
      */
     readonly groupedCommitment: BookLanguageManualCommitmentGroup;
-    /**
-     * Number of uses across the selected server agents.
-     */
-    readonly usageCount: number;
     /**
      * Translated labels of the manual.
      */

package/esm/src/book-components/Chat/utils/renderMarkdown.d.ts

@@ -25,6 +25,13 @@ export type MarkdownInlineReference = {
      * Link target for the rendered reference.
      */
     readonly href: string;
+    /**
+     * Markdown link destination prefixes that should render as this reference as well.
+     *
+     * This supports legacy links such as an Agents Server project file URL while keeping
+     * `reference` as the canonical `[[project]]` token.
+     */
+    readonly sourceHrefPrefixes?: ReadonlyArray<string>;
     /**
      * Optional hover title for the rendered reference.
      */

package/esm/src/cli/cli-commands/coder/agentCodingFile.d.ts

@@ -1,3 +1,4 @@
+import { string_markdown } from '../../../types/typeAliases';
 /**
  * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
  *
@@ -9,6 +10,4 @@ export declare const AGENT_CODING_FILE_PATH = "AGENT_CODING.md";
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function getDefaultCoderAgentCodingFileContent({ packageJsonScripts, }: {
-    readonly packageJsonScripts: Readonly<Record<string, string>>;
-}): string;
+export declare function getDefaultCoderAgentCodingFileContent(): string_markdown;

package/esm/src/cli/cli-commands/coder/ping.d.ts

@@ -0,0 +1,13 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder ping` command for Promptbook CLI utilities.
+ *
+ * The command makes one small, isolated harness/model call, prints its result
+ * and reports how long the harness/model turn took.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderPingCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/ping.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/coder.d.ts

@@ -8,6 +8,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-0",
+    "version": "0.114.0-2",
     "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(', ');
+}