@promptbook/utils 0.112.0-54 → 0.112.0-56

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-54';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-56';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/_packages/cli.index.d.ts

@@ -30,7 +30,12 @@ import { _PdfScraperRegistration } from '../scrapers/pdf/register-constructor';
 import { _PdfScraperMetadataRegistration } from '../scrapers/pdf/register-metadata';
 import { _WebsiteScraperRegistration } from '../scrapers/website/register-constructor';
 import { _WebsiteScraperMetadataRegistration } from '../scrapers/website/register-metadata';
+import { _AgentOsTranspilerRegistration } from '../transpilers/agent-os/register';
+import { _AnthropicClaudeManagedTranspilerRegistration } from '../transpilers/anthropic-claude-managed/register';
+import { _AnthropicClaudeSdkTranspilerRegistration } from '../transpilers/anthropic-claude-sdk/register';
+import { _E2BTranspilerRegistration } from '../transpilers/e2b/register';
 import { _FormattedBookInMarkdownTranspilerRegistration } from '../transpilers/formatted-book-in-markdown/register';
+import { _OpenAiAgentsTranspilerRegistration } from '../transpilers/openai-agents/register';
 import { _OpenAiSdkTranspilerRegistration } from '../transpilers/openai-sdk/register';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
 export { _CLI };
@@ -64,5 +69,10 @@ export { _PdfScraperRegistration };
 export { _PdfScraperMetadataRegistration };
 export { _WebsiteScraperRegistration };
 export { _WebsiteScraperMetadataRegistration };
+export { _AgentOsTranspilerRegistration };
+export { _AnthropicClaudeManagedTranspilerRegistration };
+export { _AnthropicClaudeSdkTranspilerRegistration };
+export { _E2BTranspilerRegistration };
 export { _FormattedBookInMarkdownTranspilerRegistration };
+export { _OpenAiAgentsTranspilerRegistration };
 export { _OpenAiSdkTranspilerRegistration };

package/esm/src/_packages/core.index.d.ts

@@ -18,6 +18,7 @@ import { createPipelineCollectionFromPromise } from '../collection/pipeline-coll
 import { createPipelineCollectionFromUrl } from '../collection/pipeline-collection/constructors/createPipelineCollectionFromUrl';
 import { createPipelineSubcollection } from '../collection/pipeline-collection/constructors/createPipelineSubcollection';
 import { pipelineCollectionToJson } from '../collection/pipeline-collection/pipelineCollectionToJson';
+import type { CommitmentDefinition } from '../commitments/_base/CommitmentDefinition';
 import { createEmptyAgentModelRequirements } from '../commitments/_base/createEmptyAgentModelRequirements';
 import { createBasicAgentModelRequirements } from '../commitments/_base/createEmptyAgentModelRequirements';
 import { NotYetImplementedCommitmentDefinition } from '../commitments/_base/NotYetImplementedCommitmentDefinition';
@@ -196,7 +197,12 @@ import { BlackholeStorage } from '../storage/blackhole/BlackholeStorage';
 import { MemoryStorage } from '../storage/memory/MemoryStorage';
 import { PrefixStorage } from '../storage/utils/PrefixStorage';
 import { $bookTranspilersRegister } from '../transpilers/_common/register/$bookTranspilersRegister';
+import { AgentOsTranspiler } from '../transpilers/agent-os/AgentOsTranspiler';
+import { AnthropicClaudeManagedTranspiler } from '../transpilers/anthropic-claude-managed/AnthropicClaudeManagedTranspiler';
+import { AnthropicClaudeSdkTranspiler } from '../transpilers/anthropic-claude-sdk/AnthropicClaudeSdkTranspiler';
+import { E2BTranspiler } from '../transpilers/e2b/E2BTranspiler';
 import { FormattedBookInMarkdownTranspiler } from '../transpilers/formatted-book-in-markdown/FormattedBookInMarkdownTranspiler';
+import { OpenAiAgentsTranspiler } from '../transpilers/openai-agents/OpenAiAgentsTranspiler';
 import { OpenAiSdkTranspiler } from '../transpilers/openai-sdk/OpenAiSdkTranspiler';
 import { MODEL_VARIANTS } from '../types/ModelVariant';
 import { NonTaskSectionTypes } from '../types/SectionType';
@@ -236,6 +242,7 @@ export { createPipelineCollectionFromPromise };
 export { createPipelineCollectionFromUrl };
 export { createPipelineSubcollection };
 export { pipelineCollectionToJson };
+export type { CommitmentDefinition };
 export { createEmptyAgentModelRequirements };
 export { createBasicAgentModelRequirements };
 export { NotYetImplementedCommitmentDefinition };
@@ -414,7 +421,12 @@ export { BlackholeStorage };
 export { MemoryStorage };
 export { PrefixStorage };
 export { $bookTranspilersRegister };
+export { AgentOsTranspiler };
+export { AnthropicClaudeManagedTranspiler };
+export { AnthropicClaudeSdkTranspiler };
+export { E2BTranspiler };
 export { FormattedBookInMarkdownTranspiler };
+export { OpenAiAgentsTranspiler };
 export { OpenAiSdkTranspiler };
 export { MODEL_VARIANTS };
 export { NonTaskSectionTypes };

package/esm/src/_packages/types.index.d.ts

@@ -222,6 +222,10 @@ import type { FileCacheStorageOptions } from '../storage/file-cache-storage/File
 import type { IndexedDbStorageOptions } from '../storage/local-storage/utils/IndexedDbStorageOptions';
 import type { BookTranspiler } from '../transpilers/_common/BookTranspiler';
 import type { BookTranspilerOptions } from '../transpilers/_common/BookTranspilerOptions';
+import type { TranspiledTeamAgentModelRequirements } from '../transpilers/_common/TranspiledTeamExport';
+import type { TranspiledTeamTeammate } from '../transpilers/_common/TranspiledTeamExport';
+import type { TranspiledTeamAgent } from '../transpilers/_common/TranspiledTeamExport';
+import type { TranspiledTeamExport } from '../transpilers/_common/TranspiledTeamExport';
 import type { IntermediateFilesStrategy } from '../types/IntermediateFilesStrategy';
 import type { LlmCall } from '../types/LlmCall';
 import type { LlmToolDefinition } from '../types/LlmToolDefinition';
@@ -651,6 +655,10 @@ export type { FileCacheStorageOptions };
 export type { IndexedDbStorageOptions };
 export type { BookTranspiler };
 export type { BookTranspilerOptions };
+export type { TranspiledTeamAgentModelRequirements };
+export type { TranspiledTeamTeammate };
+export type { TranspiledTeamAgent };
+export type { TranspiledTeamExport };
 export type { IntermediateFilesStrategy };
 export type { LlmCall };
 export type { LlmToolDefinition };

package/esm/src/_packages/wizard.index.d.ts

@@ -29,7 +29,12 @@ import { _PdfScraperRegistration } from '../scrapers/pdf/register-constructor';
 import { _PdfScraperMetadataRegistration } from '../scrapers/pdf/register-metadata';
 import { _WebsiteScraperRegistration } from '../scrapers/website/register-constructor';
 import { _WebsiteScraperMetadataRegistration } from '../scrapers/website/register-metadata';
+import { _AgentOsTranspilerRegistration } from '../transpilers/agent-os/register';
+import { _AnthropicClaudeManagedTranspilerRegistration } from '../transpilers/anthropic-claude-managed/register';
+import { _AnthropicClaudeSdkTranspilerRegistration } from '../transpilers/anthropic-claude-sdk/register';
+import { _E2BTranspilerRegistration } from '../transpilers/e2b/register';
 import { _FormattedBookInMarkdownTranspilerRegistration } from '../transpilers/formatted-book-in-markdown/register';
+import { _OpenAiAgentsTranspilerRegistration } from '../transpilers/openai-agents/register';
 import { _OpenAiSdkTranspilerRegistration } from '../transpilers/openai-sdk/register';
 import { wizard } from '../wizard/wizard';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
@@ -63,6 +68,11 @@ export { _PdfScraperRegistration };
 export { _PdfScraperMetadataRegistration };
 export { _WebsiteScraperRegistration };
 export { _WebsiteScraperMetadataRegistration };
+export { _AgentOsTranspilerRegistration };
+export { _AnthropicClaudeManagedTranspilerRegistration };
+export { _AnthropicClaudeSdkTranspilerRegistration };
+export { _E2BTranspilerRegistration };
 export { _FormattedBookInMarkdownTranspilerRegistration };
+export { _OpenAiAgentsTranspilerRegistration };
 export { _OpenAiSdkTranspilerRegistration };
 export { wizard };

package/esm/src/avatars/index.d.ts

@@ -2,6 +2,6 @@ export { Avatar } from './Avatar';
 export { AvatarOrImage } from './AvatarOrImage';
 export { renderAvatarVisual } from './renderAvatarVisual';
 export { createAvatarDefinitionFromAgentBasicInformation } from './avatarRenderingUtils';
-export { AVATAR_VISUALS, getAvatarVisualById } from './visuals/avatarVisualRegistry';
+export { AVATAR_VISUALS, getAvatarVisualById, resolveAvatarVisualId } from './visuals/avatarVisualRegistry';
 export type { AvatarDefinition } from './types/AvatarDefinition';
 export type { AvatarInteractionState, AvatarPalette, AvatarPointerType, AvatarProps, AvatarVisual, AvatarVisualDefinition, AvatarVisualId, AvatarVisualRenderContext, RenderAvatarVisualOptions, } from './types/AvatarVisualDefinition';

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -6,7 +6,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'ascii-octopus' | 'minecraft' | 'fractal';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'ascii-octopus' | 'minecraft' | 'fractal' | 'orb';
 /**
  * Derived color palette used by avatar visuals.
  *

package/esm/src/avatars/visuals/avatarVisualRegistry.d.ts

@@ -14,3 +14,15 @@ export declare const AVATAR_VISUALS: ReadonlyArray<AvatarVisualDefinition>;
  * @private shared registry for the avatar rendering system
  */
 export declare function getAvatarVisualById(visualId: AvatarVisualId): AvatarVisualDefinition;
+/**
+ * Resolves a user-facing avatar visual value to a supported built-in visual id.
+ *
+ * The lookup is derived from `AVATAR_VISUALS`, so new visuals become selectable by
+ * adding them to the registry rather than updating parser-specific option lists.
+ *
+ * @param value Raw visual id/title, for example `PIXEL_ART`, `pixel art`, or `pixel-art`.
+ * @returns Matching visual id or `null` when the value is empty/unknown.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+export declare function resolveAvatarVisualId(value: string | null | undefined): AvatarVisualId | null;

package/esm/src/avatars/visuals/orbAvatarVisual.d.ts

@@ -0,0 +1,48 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Orb family labels used to keep the silhouette circle-based while still varying the rendering style.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+type OrbFamily = 'pearl' | 'nebula' | 'ember' | 'glacier';
+/**
+ * Deterministic orb profile used to keep the orb recognizable while still varying its motion and shape.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+type OrbMorphologyProfile = {
+    family: OrbFamily;
+    baseRadiusRatio: number;
+    horizontalStretch: number;
+    verticalStretch: number;
+    wobbleAmplitude: number;
+    wobbleFrequencyOne: number;
+    wobbleFrequencyTwo: number;
+    wobbleFrequencyThree: number;
+    ringCount: number;
+    sparkleCount: number;
+    haloCount: number;
+    coreShiftX: number;
+    coreShiftY: number;
+    highlightAngle: number;
+    bandRotation: number;
+    pulseSpeed: number;
+    haloBlurRatio: number;
+    sheenStrength: number;
+};
+/**
+ * Built-in Orb avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const orbAvatarVisual: AvatarVisualDefinition;
+/**
+ * Builds the deterministic orb profile from the seeded avatar random factory.
+ *
+ * @param createRandom Seeded random factory.
+ * @returns Stable orb morphology profile.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+export declare function createOrbMorphologyProfile(createRandom: (salt: string) => () => number): OrbMorphologyProfile;
+export {};

package/esm/src/avatars/visuals/orbAvatarVisual.test.d.ts

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

package/esm/src/book-2.0/agent-source/AgentBasicInformation.d.ts

@@ -1,4 +1,5 @@
 import type { string_agent_hash, string_agent_name, string_agent_permanent_id, string_agent_url, string_color, string_fonts, string_url_image } from '../../types/typeAliases';
+import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
 /**
  * Unified parameter representation that supports two different notations:
  * 1. @Parameter - single word parameter starting with @
@@ -87,6 +88,7 @@ export type AgentBasicInformation = {
         inputPlaceholder?: string;
         messageSuffix?: string;
         image?: string_url_image;
+        avatar?: AvatarVisualId;
         domain?: string;
         font?: string_fonts;
         color?: string_color;

package/esm/src/book-2.0/agent-source/parseAgentSourceWithCommitments.use.test.d.ts

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

package/esm/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.d.ts

@@ -1,10 +1,10 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 /**
- * Monaco diagnostic shape used by deprecated-commitment warnings.
+ * Monaco diagnostic shape used by deprecated, unfinished, and low-level commitment warnings.
  *
  * @private internal type of `BookEditorMonaco`
  */
-type DeprecatedCommitmentDiagnostic = {
+type CommitmentNoticeDiagnostic = {
     readonly startLineNumber: number;
     readonly startColumn: number;
     readonly endLineNumber: number;
@@ -14,16 +14,17 @@ type DeprecatedCommitmentDiagnostic = {
     readonly severity: 'warning';
 };
 /**
- * Creates Book editor diagnostics for deprecated commitment keywords.
+ * Creates Book editor diagnostics for deprecated, unfinished, and low-level commitment keywords.
  *
- * The deprecation metadata is UI-only. This helper surfaces it in Monaco so
- * legacy commitments remain functional while still guiding authors toward
- * preferred replacements.
+ * The notice metadata is UI-only. This helper surfaces it in Monaco so legacy,
+ * unfinished, and low-level commitments remain functional while still guiding
+ * authors toward preferred replacements or cautioning them about low-level
+ * usage.
  *
  * @param agentSource - Current editor content.
- * @returns Warning markers for deprecated commitment keywords.
+ * @returns Warning markers for deprecated, unfinished, and low-level commitment keywords.
  *
  * @private internal utility of `BookEditorMonaco`
  */
-export declare function createDeprecatedCommitmentDiagnostics(agentSource?: string_book): ReadonlyArray<DeprecatedCommitmentDiagnostic>;
+export declare function createDeprecatedCommitmentDiagnostics(agentSource?: string_book): ReadonlyArray<CommitmentNoticeDiagnostic>;
 export {};

package/esm/src/commitments/ACTION/ACTION.d.ts

@@ -3,8 +3,8 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * ACTION commitment definition
  *
- * The ACTION commitment defines specific actions or capabilities that the agent can perform.
- * This helps define what the agent is capable of doing and how it should approach tasks.
+ * Deprecated legacy commitment for broad capability notes.
+ * New books should prefer the appropriate `USE*` commitment instead.
  *
  * Example usage in agent source:
  *
@@ -21,6 +21,12 @@ export declare class ActionCommitmentDefinition extends BaseCommitmentDefinition
      * Short one-line description of ACTION.
      */
     get description(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): {
+        readonly message: "Use a concrete `USE*` commitment instead.";
+    };
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/ACTION/ACTION.test.d.ts

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

package/esm/src/commitments/DELETE/DELETE.d.ts

@@ -3,9 +3,9 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * DELETE commitment definition
  *
- * The DELETE commitment (and its aliases CANCEL, DISCARD, REMOVE) is used to
- * remove or disregard certain information or context. This can be useful for
- * overriding previous commitments or removing unwanted behaviors.
+ * The DELETE commitment (and its aliases CANCEL, DISCARD, REMOVE) is a low-level
+ * unfinished commitment used to remove or disregard certain information or context.
+ * It is intentionally surfaced with caution because it is not ready for broad use yet.
  *
  * Example usage in agent source:
  *
@@ -24,6 +24,10 @@ export declare class DeleteCommitmentDefinition extends BaseCommitmentDefinition
      * Short one-line description of DELETE/CANCEL/DISCARD/REMOVE.
      */
     get description(): string;
+    /**
+     * Marks DELETE as unfinished and not ready to use.
+     */
+    get isUnfinished(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/DELETE/DELETE.test.d.ts

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

package/esm/src/commitments/FORMAT/FORMAT.d.ts

@@ -3,11 +3,10 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * FORMAT commitment definition
  *
- * The FORMAT commitment defines the specific output structure and formatting
- * that the agent should use in its responses. This includes data formats,
- * response templates, and structural requirements.
+ * Deprecated legacy commitment for output formatting and response structure.
+ * New books should prefer `WRITING SAMPLE` and `WRITING RULES`.
  *
- * Example usage in agent source:
+ * Legacy example usage in agent source:
  *
  * ```book
  * FORMAT Always respond in JSON format with 'status' and 'data' fields
@@ -22,6 +21,13 @@ export declare class FormatCommitmentDefinition extends BaseCommitmentDefinition
      * Short one-line description of FORMAT.
      */
     get description(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): {
+        readonly message: "Use `WRITING SAMPLE` and `WRITING RULES` instead.";
+        readonly replacedBy: readonly ["WRITING SAMPLE", "WRITING RULES"];
+    };
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/FORMAT/FORMAT.test.d.ts

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

package/esm/src/commitments/GOAL/GOAL.d.ts

@@ -22,6 +22,10 @@ export declare class GoalCommitmentDefinition extends BaseCommitmentDefinition<'
      * Short one-line description of GOAL.
      */
     get description(): string;
+    /**
+     * Marks GOAL as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/KNOWLEDGE/KNOWLEDGE.d.ts

@@ -24,6 +24,10 @@ export declare class KnowledgeCommitmentDefinition extends BaseCommitmentDefinit
      * Short one-line description of KNOWLEDGE.
      */
     get description(): string;
+    /**
+     * Marks KNOWLEDGE as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/META/META.d.ts

@@ -4,6 +4,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * META commitment definition
  *
  * The META commitment handles all meta-information about the agent such as:
+ * - META AVATAR: Sets the agent's built-in default avatar visual
  * - META IMAGE: Sets the agent's avatar/profile image URL
  * - META LINK: Provides profile/source links for the person the agent models
  * - META DOMAIN: Sets the canonical custom domain/host of the agent
@@ -18,6 +19,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * Example usage in agent source:
  *
  * ```book
+ * META AVATAR pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com

package/esm/src/commitments/META_AVATAR/META_AVATAR.d.ts

@@ -0,0 +1,26 @@
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * META AVATAR commitment definition
+ *
+ * The `META AVATAR` commitment sets the built-in default avatar visual used when
+ * the agent does not provide an explicit `META IMAGE`.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'META AVATAR'> {
+    constructor();
+    /**
+     * Short one-line description of META AVATAR.
+     */
+    get description(): string;
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for META AVATAR commitment.
+     */
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+}

package/esm/src/commitments/MODEL/MODEL.d.ts

@@ -31,6 +31,10 @@ export declare class ModelCommitmentDefinition extends BaseCommitmentDefinition<
      * Short one-line description of MODEL.
      */
     get description(): string;
+    /**
+     * Marks MODEL as a low-level commitment surfaced with caution.
+     */
+    get isLowLevel(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/MODEL/MODEL.test.d.ts

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

package/esm/src/commitments/RULE/RULE.d.ts

@@ -21,6 +21,10 @@ export declare class RuleCommitmentDefinition extends BaseCommitmentDefinition<'
      * Short one-line description of RULE/RULES.
      */
     get description(): string;
+    /**
+     * Marks RULE as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/TEAM/TEAM.d.ts

@@ -22,6 +22,10 @@ export declare class TeamCommitmentDefinition extends BaseCommitmentDefinition<'
      * Short one-line description of TEAM.
      */
     get description(): string;
+    /**
+     * Marks TEAM as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant(): boolean;
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/TEMPLATE/TEMPLATE.d.ts

@@ -3,11 +3,10 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * TEMPLATE commitment definition
  *
- * The TEMPLATE commitment enforces a specific response structure or template
- * that the agent must follow when generating responses. This helps ensure
- * consistent message formatting across all agent interactions.
+ * Deprecated legacy commitment for response templates and output structure.
+ * New books should prefer `WRITING SAMPLE` and `WRITING RULES`.
  *
- * Example usage in agent source:
+ * Legacy example usage in agent source:
  *
  * ```book
  * TEMPLATE Always structure your response with: 1) Summary, 2) Details, 3) Next steps
@@ -25,6 +24,13 @@ export declare class TemplateCommitmentDefinition extends BaseCommitmentDefiniti
      * Short one-line description of TEMPLATE.
      */
     get description(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): {
+        readonly message: "Use `WRITING SAMPLE` and `WRITING RULES` instead.";
+        readonly replacedBy: readonly ["WRITING SAMPLE", "WRITING RULES"];
+    };
     /**
      * Icon for this commitment.
      */

package/esm/src/commitments/_base/BaseCommitmentDefinition.d.ts

@@ -28,6 +28,18 @@ export declare abstract class BaseCommitmentDefinition<TBookCommitment extends s
      * It should be a single emoji.
      */
     abstract get icon(): string;
+    /**
+     * Whether this commitment should be prioritized in menus, documentation, and intellisense.
+     */
+    get isImportant(): boolean;
+    /**
+     * Whether this commitment is unfinished and not ready to use.
+     */
+    get isUnfinished(): boolean;
+    /**
+     * Whether this commitment is low-level and should be surfaced with caution.
+     */
+    get isLowLevel(): boolean;
     /**
      * Human-readable markdown documentation for this commitment, available at runtime.
      * Must be implemented by each concrete commitment.

package/esm/src/commitments/_base/CommitmentDefinition.d.ts

@@ -17,11 +17,13 @@ type CommitmentDeprecation = {
     readonly replacedBy?: ReadonlyArray<string>;
 };
 /**
- * Definition of a commitment that can be applied to agent model requirements
+ * Definition of a commitment that can be applied to agent model requirements.
  *
  * Each commitment is self-contained and manages its own logic for:
  * - Creating regex patterns for parsing
  * - Applying its effects to agent model requirements
+ *
+ * @public exported from `@promptbook/core`
  */
 export type CommitmentDefinition = {
     /**
@@ -38,6 +40,24 @@ export type CommitmentDefinition = {
      * It should be a single emoji.
      */
     readonly icon: string;
+    /**
+     * Whether this commitment should be prioritized in menus, documentation, and intellisense.
+     */
+    readonly isImportant: boolean;
+    /**
+     * Whether this commitment is unfinished and not ready to use.
+     *
+     * Unfinished commitments are surfaced with low-level caution in the UI,
+     * documentation, and editor diagnostics.
+     */
+    readonly isUnfinished: boolean;
+    /**
+     * Whether this commitment is low-level and should be surfaced with caution.
+     *
+     * Low-level commitments are fully implemented, but they are intended for
+     * advanced use and are not used by most users.
+     */
+    readonly isLowLevel: boolean;
     /**
      * Human-readable markdown documentation for this commitment.
      * Should explain what the commitment does and include example usage.

package/esm/src/commitments/_common/getAllCommitmentDefinitions.test.d.ts

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

package/esm/src/commitments/_common/getCommitmentNoticeMetadata.d.ts

@@ -0,0 +1,51 @@
+import type { CommitmentDefinition } from '../_base/CommitmentDefinition';
+/**
+ * Type of commitment notice surfaced in docs and editor UI.
+ *
+ * @private internal type of commitment catalog presentation
+ */
+export type CommitmentNoticeMetadata = {
+    /**
+     * Machine-readable notice kind.
+     */
+    readonly kind: 'deprecated' | 'unfinished' | 'lowLevel';
+    /**
+     * Short badge label shown in documentation and menus.
+     */
+    readonly badgeLabel: string;
+    /**
+     * Longer label used in documentation bodies and editor details.
+     */
+    readonly detailLabel: string;
+    /**
+     * Human-readable notice message shown in editor and documentation callouts.
+     */
+    readonly message: string;
+};
+/**
+ * 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
+ */
+export declare function formatCommitmentReplacementText(replacedBy?: ReadonlyArray<string>): string;
+/**
+ * Returns true when one commitment notice should be rendered with low-visibility styling.
+ *
+ * @param notice - Commitment notice metadata or null.
+ * @returns True for unfinished and low-level notices.
+ *
+ * @private internal utility of commitment catalog notices
+ */
+export declare function isLowVisibilityCommitmentNotice(notice: CommitmentNoticeMetadata | null): boolean;
+/**
+ * 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
+ */
+export declare function getCommitmentNoticeMetadata(definition: Pick<CommitmentDefinition, 'deprecation'> & Partial<Pick<CommitmentDefinition, 'isUnfinished' | 'isLowLevel'>>): CommitmentNoticeMetadata | null;

package/esm/src/commitments/_common/getCommitmentNoticeMetadata.test.d.ts

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

package/esm/src/commitments/_common/getGroupedCommitmentDefinitions.openClosed.test.d.ts

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

package/esm/src/commitments/_common/getGroupedCommitmentDefinitions.order.test.d.ts

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

package/esm/src/commitments/_common/getGroupedCommitmentDefinitions.use.test.d.ts

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