@operla-ai/sdk 0.3.4 → 0.3.6

package/dist/generated/types.gen.d.ts

@@ -50,12 +50,33 @@ export type ListResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Agents visible at the caller's scope.
+         */
         agents: Array<{
+            /**
+             * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+             */
             name: string;
+            /**
+             * Human-readable label shown in the dashboard.
+             */
             label: string;
+            /**
+             * Cascade level of this view (global / organization / entity).
+             */
             scope: {
+                /**
+                 * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+                 */
                 level: 'global' | 'organization' | 'entity';
+                /**
+                 * ID of the organization when `level` is `organization` or `entity`.
+                 */
                 organizationId?: string;
+                /**
+                 * ID of the entity when `level` is `entity`.
+                 */
                 entityId?: string;
             };
             /**
@@ -84,12 +105,58 @@ export type CreateData = {
          * Hard rules to attach to the agent at creation.
          */
         hardRules?: Array<{
+            /**
+             * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+             */
             name: string;
+            /**
+             * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+             */
             instruction: string;
-            triggers?: {
-                intents?: Array<string>;
-            };
+            /**
+             * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+             */
+            intents?: Array<string>;
+            /**
+             * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+             */
             priority?: number;
+            /**
+             * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+             */
+            disabled?: boolean;
+        }>;
+        /**
+         * Few-shot examples to attach to the agent at creation.
+         */
+        examples?: Array<{
+            /**
+             * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+             */
+            name?: string;
+            /**
+             * Short human-readable description of the scenario this example illustrates.
+             */
+            description: string;
+            /**
+             * User message used as the example input.
+             */
+            input: string;
+            /**
+             * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+             */
+            output?: unknown;
+            /**
+             * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+             */
+            context?: unknown;
+            /**
+             * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+             */
+            intents?: Array<string>;
+            /**
+             * Set on an override doc to filter out an inherited example of the same name at runtime.
+             */
             disabled?: boolean;
         }>;
     };
@@ -135,87 +202,317 @@ export type CreateResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+         */
         name: string;
+        /**
+         * Human-readable label shown in the dashboard.
+         */
         label: string;
+        /**
+         * Cascade level of this view (global / organization / entity).
+         */
         scope: {
+            /**
+             * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
         /**
          * The agent config the runtime sees at the request scope, after cascade resolution.
          */
         resolved: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
         /**
          * Override draft at this scope, when one exists.
          */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
     };
@@ -270,6 +567,9 @@ export type DeleteResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Confirmation message describing the deletion outcome.
+         */
         message: string;
     };
 };
@@ -328,87 +628,317 @@ export type GetResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+         */
         name: string;
+        /**
+         * Human-readable label shown in the dashboard.
+         */
         label: string;
+        /**
+         * Cascade level of this view (global / organization / entity).
+         */
         scope: {
+            /**
+             * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
         /**
          * The agent config the runtime sees at the request scope, after cascade resolution.
          */
         resolved: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
         /**
          * Override draft at this scope, when one exists.
          */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
     };
@@ -424,12 +954,58 @@ export type UpdateData = {
          * Constraints the agent must follow, injected into its prompt.
          */
         hardRules?: Array<{
+            /**
+             * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+             */
             name: string;
+            /**
+             * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+             */
             instruction: string;
-            triggers?: {
-                intents?: Array<string>;
-            };
+            /**
+             * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+             */
+            intents?: Array<string>;
+            /**
+             * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+             */
             priority?: number;
+            /**
+             * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+             */
+            disabled?: boolean;
+        }>;
+        /**
+         * Few-shot examples shown to the agent in its prompt. Use them to demonstrate input → output patterns.
+         */
+        examples?: Array<{
+            /**
+             * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+             */
+            name?: string;
+            /**
+             * Short human-readable description of the scenario this example illustrates.
+             */
+            description: string;
+            /**
+             * User message used as the example input.
+             */
+            input: string;
+            /**
+             * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+             */
+            output?: unknown;
+            /**
+             * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+             */
+            context?: unknown;
+            /**
+             * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+             */
+            intents?: Array<string>;
+            /**
+             * Set on an override doc to filter out an inherited example of the same name at runtime.
+             */
             disabled?: boolean;
         }>;
         /**
@@ -442,18 +1018,54 @@ export type UpdateData = {
          * Per-channel writing style. Editable on the response agent only.
          */
         responseConfig?: {
+            /**
+             * Writing style applied when the conversation channel is email.
+             */
             email?: {
+                /**
+                 * Greeting text to start the agent's response. The agent translates it into the user's language.
+                 */
                 greeting?: string;
+                /**
+                 * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                 */
                 signature?: string;
+                /**
+                 * Writing tone for this channel.
+                 */
                 tone?: 'empathetic' | 'formal' | 'friendly';
+                /**
+                 * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                 */
                 addressForm?: 'formal' | 'informal';
+                /**
+                 * Allow the agent to use one emoji per message. Defaults to `false`.
+                 */
                 allowEmojis?: boolean;
             };
+            /**
+             * Writing style applied when the conversation channel is chat.
+             */
             chat?: {
+                /**
+                 * Greeting text to start the agent's response. The agent translates it into the user's language.
+                 */
                 greeting?: string;
+                /**
+                 * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                 */
                 signature?: string;
+                /**
+                 * Writing tone for this channel.
+                 */
                 tone?: 'empathetic' | 'formal' | 'friendly';
+                /**
+                 * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                 */
                 addressForm?: 'formal' | 'informal';
+                /**
+                 * Allow the agent to use one emoji per message. Defaults to `false`.
+                 */
                 allowEmojis?: boolean;
             };
         };
@@ -514,87 +1126,317 @@ export type UpdateResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+         */
         name: string;
+        /**
+         * Human-readable label shown in the dashboard.
+         */
         label: string;
+        /**
+         * Cascade level of this view (global / organization / entity).
+         */
         scope: {
+            /**
+             * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
         /**
          * The agent config the runtime sees at the request scope, after cascade resolution.
          */
         resolved: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
         /**
          * Override draft at this scope, when one exists.
          */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
     };
@@ -654,6 +1496,9 @@ export type DeleteOverrideResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Confirmation message describing the deletion outcome.
+         */
         message: string;
     };
 };
@@ -717,87 +1562,317 @@ export type PublishResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+         */
         name: string;
+        /**
+         * Human-readable label shown in the dashboard.
+         */
         label: string;
+        /**
+         * Cascade level of this view (global / organization / entity).
+         */
         scope: {
+            /**
+             * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
         /**
          * The agent config the runtime sees at the request scope, after cascade resolution.
          */
         resolved: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
         /**
          * Override draft at this scope, when one exists.
          */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
     };
@@ -862,87 +1937,317 @@ export type RollbackResponses = {
      * Successful response
      */
     200: {
+        /**
+         * Machine name of the agent (e.g. `orchestrator`, `response`, `specialist_billing`).
+         */
         name: string;
+        /**
+         * Human-readable label shown in the dashboard.
+         */
         label: string;
+        /**
+         * Cascade level of this view (global / organization / entity).
+         */
         scope: {
+            /**
+             * Cascade level this config lives at — `global` (whole tenant), `organization` (per-org override), or `entity` (per-entity override).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
         /**
          * The agent config the runtime sees at the request scope, after cascade resolution.
          */
         resolved: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
         /**
          * Override draft at this scope, when one exists.
          */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot at its scope.
+             */
             version: number;
+            /**
+             * System prompt active in this snapshot. Omitted on override snapshots that inherit the prompt from the cascade.
+             */
             prompt?: string;
+            /**
+             * Resolved list of hard rules. On override snapshots, may be omitted when the override doesn't customise rules.
+             */
             hardRules?: Array<{
+                /**
+                 * Stable identifier for the rule. Also used as the merge key when this rule is overridden at a deeper scope (organization/entity).
+                 */
                 name: string;
+                /**
+                 * Plain-text instruction injected into the agent's prompt. The agent must always respect it.
+                 */
                 instruction: string;
-                triggers?: {
-                    intents?: Array<string>;
-                };
+                /**
+                 * Restrict the rule to specific intents. Empty array = the rule applies on every turn regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Relative priority within the agent's rule set (0–100, higher first). Use it to order conflicting rules; values are not absolute.
+                 */
                 priority?: number;
+                /**
+                 * Set on an override doc to filter out an inherited rule of the same name at runtime. The rule shape is kept so toggling back works.
+                 */
+                disabled?: boolean;
+            }>;
+            /**
+             * Resolved list of few-shot examples. On override snapshots, may be omitted when the override doesn't customise examples.
+             */
+            examples?: Array<{
+                /**
+                 * Stable identifier for the example. Also used as the merge key when this example is overridden at a deeper scope (organization/entity).
+                 */
+                name?: string;
+                /**
+                 * Short human-readable description of the scenario this example illustrates.
+                 */
+                description: string;
+                /**
+                 * User message used as the example input.
+                 */
+                input: string;
+                /**
+                 * Expected agent output. Shape depends on the agent type (structured JSON for orchestrator/specialist, plain text for response). Write outputs in English — the runtime LLM transposes them into the user's language.
+                 */
+                output?: unknown;
+                /**
+                 * Optional scenario context (user data, KB facts, previous decisions) attached to this example for the agent to read alongside the input.
+                 */
+                context?: unknown;
+                /**
+                 * Restrict the example to specific intents. Applied at runtime by specialist and response agents — the orchestrator ignores it since it runs before intent detection. Empty array = the example applies regardless of intent.
+                 */
+                intents?: Array<string>;
+                /**
+                 * Set on an override doc to filter out an inherited example of the same name at runtime.
+                 */
                 disabled?: boolean;
             }>;
+            /**
+             * Toggled user-context fields exposed to the agent.
+             */
             userContextConfig?: {
                 [key: string]: boolean;
             };
+            /**
+             * Per-channel writing style (response agent only).
+             */
             responseConfig?: {
+                /**
+                 * Writing style applied when the conversation channel is email.
+                 */
                 email?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
+                /**
+                 * Writing style applied when the conversation channel is chat.
+                 */
                 chat?: {
+                    /**
+                     * Greeting text to start the agent's response. The agent translates it into the user's language.
+                     */
                     greeting?: string;
+                    /**
+                     * Sign-off text appended to the agent's response. The agent translates it into the user's language.
+                     */
                     signature?: string;
+                    /**
+                     * Writing tone for this channel.
+                     */
                     tone?: 'empathetic' | 'formal' | 'friendly';
+                    /**
+                     * `formal` uses the polite pronoun in T-V languages (e.g. French "vous"); `informal` uses the familiar one. Defaults to `formal`.
+                     */
                     addressForm?: 'formal' | 'informal';
+                    /**
+                     * Allow the agent to use one emoji per message. Defaults to `false`.
+                     */
                     allowEmojis?: boolean;
                 };
             };
+            /**
+             * Optional release note attached when this version was published.
+             */
             message?: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
     };
@@ -1015,9 +2320,12 @@ export type List2Responses = {
              */
             conversationId: string;
             /**
-             * Organization linked to the conversation (when you use organizations).
+             * Organization the conversation is linked to (id + name); null when not tied to one.
              */
-            organizationId?: string;
+            organization: {
+                id: string;
+                name: string;
+            } | null;
             /**
              * Current lifecycle status of the conversation.
              */
@@ -1040,9 +2348,12 @@ export type List2Responses = {
                 resolved?: boolean;
             } | null;
             /**
-             * Entity linked to the conversation (when you use entities).
+             * Entity the conversation is linked to (id + name); null when not tied to one.
              */
-            entityId?: string;
+            entity: {
+                id: string;
+                name: string;
+            } | null;
             /**
              * Total number of messages exchanged so far (user + agent).
              */
@@ -1129,9 +2440,12 @@ export type Get2Responses = {
          */
         conversationId: string;
         /**
-         * Organization linked to the conversation (when you use organizations).
+         * Organization the conversation is linked to (id + name); null when not tied to one.
          */
-        organizationId?: string;
+        organization: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Current lifecycle status of the conversation.
          */
@@ -1160,9 +2474,12 @@ export type Get2Responses = {
             };
         } | null;
         /**
-         * Entity linked to the conversation (when you use entities).
+         * Entity the conversation is linked to (id + name); null when not tied to one.
          */
-        entityId?: string;
+        entity: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Total number of messages exchanged so far (user + agent).
          */
@@ -1319,9 +2636,12 @@ export type SendMessageResponses = {
          */
         conversationId: string;
         /**
-         * Organization linked to the conversation (when you use organizations).
+         * Organization the conversation is linked to (id + name); null when not tied to one.
          */
-        organizationId?: string;
+        organization: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Index of the user message that was just processed. Pass this to [`validateResponse`](#tag/conversations/POST/conversations/{conversationId}/validate-response) if `mode` is `copilot` and you need to validate the response later.
          */
@@ -1346,9 +2666,12 @@ export type SendMessageResponses = {
             };
         } | null;
         /**
-         * Entity linked to the conversation (when you use entities).
+         * Entity the conversation is linked to (id + name); null when not tied to one.
          */
-        entityId?: string;
+        entity: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * AI-generated response to the user message.
          */
@@ -1543,6 +2866,10 @@ export type List3Data = {
          * Number of items to skip for pagination.
          */
         offset?: number | null;
+        /**
+         * Substring match on name or id (case-insensitive).
+         */
+        search?: string;
     };
     url: '/entities';
 };
@@ -1589,7 +2916,13 @@ export type List3Responses = {
              * Entity ID (format: ent_xxxxxxxxxxxx).
              */
             id: string;
-            organizationId?: string | null;
+            /**
+             * Parent organization ref (id + name); null when not tied to one.
+             */
+            organization: {
+                id: string;
+                name: string;
+            } | null;
             /**
              * Human-readable name of the entity.
              */
@@ -1677,7 +3010,13 @@ export type Create2Responses = {
          * Entity ID (format: ent_xxxxxxxxxxxx).
          */
         id: string;
-        organizationId?: string | null;
+        /**
+         * Parent organization ref (id + name); null when not tied to one.
+         */
+        organization: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Human-readable name of the entity.
          */
@@ -1808,7 +3147,13 @@ export type Get3Responses = {
          * Entity ID (format: ent_xxxxxxxxxxxx).
          */
         id: string;
-        organizationId?: string | null;
+        /**
+         * Parent organization ref (id + name); null when not tied to one.
+         */
+        organization: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Human-readable name of the entity.
          */
@@ -1894,7 +3239,13 @@ export type Update2Responses = {
          * Entity ID (format: ent_xxxxxxxxxxxx).
          */
         id: string;
-        organizationId?: string | null;
+        /**
+         * Parent organization ref (id + name); null when not tied to one.
+         */
+        organization: {
+            id: string;
+            name: string;
+        } | null;
         /**
          * Human-readable name of the entity.
          */
@@ -1974,17 +3325,50 @@ export type List4Responses = {
      */
     200: {
         articles: Array<{
+            /**
+             * KB article ID (format: kb_xxxxxxxxxxxx).
+             */
             id: string;
+            /**
+             * Current published title of the article.
+             */
             title: string;
+            /**
+             * Intent IDs this article serves. Empty array = always-on within its scope.
+             */
             intents: Array<string>;
+            /**
+             * Cascade level at which this article was created.
+             */
             scope: {
+                /**
+                 * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+                 */
                 level: 'global' | 'organization' | 'entity';
+                /**
+                 * ID of the organization when `level` is `organization` or `entity`.
+                 */
                 organizationId?: string;
+                /**
+                 * ID of the entity when `level` is `entity`.
+                 */
                 entityId?: string;
             };
+            /**
+             * Version number of the published content.
+             */
             version: number;
+            /**
+             * True when an unpublished draft exists on this article.
+             */
             hasDraft: boolean;
+            /**
+             * ISO timestamp of the last publication.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last modification.
+             */
             updatedAt: string;
         }>;
         /**
@@ -2068,27 +3452,84 @@ export type Create3Responses = {
          * KB article ID (format: kb_xxxxxxxxxxxx).
          */
         id: string;
+        /**
+         * Cascade level at which this article was created.
+         */
         scope: {
+            /**
+             * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
+        /**
+         * Intent IDs this article serves. Empty array = always-on within its scope.
+         */
         intents: Array<string>;
+        /**
+         * Currently published content of the article.
+         */
         published: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * Pending draft content, when one exists. Promote it via `publish: true` on update.
+         */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * ISO timestamp when the article was created.
+         */
         createdAt: string;
+        /**
+         * ISO timestamp of the last modification (publish, draft edit, intents change).
+         */
         updatedAt: string;
     };
 };
@@ -2142,6 +3583,9 @@ export type Delete3Responses = {
      * Successful response
      */
     200: {
+        /**
+         * Confirmation message describing the deletion outcome.
+         */
         message: string;
     };
 };
@@ -2199,27 +3643,84 @@ export type Get4Responses = {
          * KB article ID (format: kb_xxxxxxxxxxxx).
          */
         id: string;
+        /**
+         * Cascade level at which this article was created.
+         */
         scope: {
+            /**
+             * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
+        /**
+         * Intent IDs this article serves. Empty array = always-on within its scope.
+         */
         intents: Array<string>;
+        /**
+         * Currently published content of the article.
+         */
         published: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * Pending draft content, when one exists. Promote it via `publish: true` on update.
+         */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * ISO timestamp when the article was created.
+         */
         createdAt: string;
+        /**
+         * ISO timestamp of the last modification (publish, draft edit, intents change).
+         */
         updatedAt: string;
     };
 };
@@ -2294,27 +3795,84 @@ export type Update3Responses = {
          * KB article ID (format: kb_xxxxxxxxxxxx).
          */
         id: string;
+        /**
+         * Cascade level at which this article was created.
+         */
         scope: {
+            /**
+             * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
+        /**
+         * Intent IDs this article serves. Empty array = always-on within its scope.
+         */
         intents: Array<string>;
+        /**
+         * Currently published content of the article.
+         */
         published: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * Pending draft content, when one exists. Promote it via `publish: true` on update.
+         */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * ISO timestamp when the article was created.
+         */
         createdAt: string;
+        /**
+         * ISO timestamp of the last modification (publish, draft edit, intents change).
+         */
         updatedAt: string;
     };
 };
@@ -2372,27 +3930,84 @@ export type Publish2Responses = {
          * KB article ID (format: kb_xxxxxxxxxxxx).
          */
         id: string;
+        /**
+         * Cascade level at which this article was created.
+         */
         scope: {
+            /**
+             * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
+        /**
+         * Intent IDs this article serves. Empty array = always-on within its scope.
+         */
         intents: Array<string>;
+        /**
+         * Currently published content of the article.
+         */
         published: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * Pending draft content, when one exists. Promote it via `publish: true` on update.
+         */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * ISO timestamp when the article was created.
+         */
         createdAt: string;
+        /**
+         * ISO timestamp of the last modification (publish, draft edit, intents change).
+         */
         updatedAt: string;
     };
 };
@@ -2455,27 +4070,84 @@ export type Rollback2Responses = {
          * KB article ID (format: kb_xxxxxxxxxxxx).
          */
         id: string;
+        /**
+         * Cascade level at which this article was created.
+         */
         scope: {
+            /**
+             * Cascade level this article lives at — `global` (whole tenant), `organization` (per-org), or `entity` (per-entity).
+             */
             level: 'global' | 'organization' | 'entity';
+            /**
+             * ID of the organization when `level` is `organization` or `entity`.
+             */
             organizationId?: string;
+            /**
+             * ID of the entity when `level` is `entity`.
+             */
             entityId?: string;
         };
+        /**
+         * Intent IDs this article serves. Empty array = always-on within its scope.
+         */
         intents: Array<string>;
+        /**
+         * Currently published content of the article.
+         */
         published: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * Pending draft content, when one exists. Promote it via `publish: true` on update.
+         */
         draft?: {
+            /**
+             * Monotonic version number of this snapshot.
+             */
             version: number;
+            /**
+             * Article title at this version.
+             */
             title: string;
+            /**
+             * Article body (Markdown) at this version.
+             */
             content: string;
+            /**
+             * ISO timestamp of the publication that produced this snapshot.
+             */
             publishedAt?: string;
+            /**
+             * ISO timestamp of the last draft edit (drafts only).
+             */
             updatedAt?: string;
         };
+        /**
+         * ISO timestamp when the article was created.
+         */
         createdAt: string;
+        /**
+         * ISO timestamp of the last modification (publish, draft edit, intents change).
+         */
         updatedAt: string;
     };
 };
@@ -2492,6 +4164,10 @@ export type List5Data = {
          * Number of items to skip for pagination.
          */
         offset?: number | null;
+        /**
+         * Substring match on name or id (case-insensitive).
+         */
+        search?: string;
     };
     url: '/organizations';
 };