@epilot/cli 0.1.151 → 0.1.153

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.151 — CLI for epilot APIs
+epilot v0.1.153 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/app.json

@@ -511,6 +511,7 @@
           }
         ],
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
@@ -1974,6 +1975,7 @@
         }
       },
       "InstallRequest": {
+        "required": true,
         "content": {
           "application/json": {
             "schema": {
@@ -2254,7 +2256,7 @@
           "code": {
             "type": "string",
             "maxLength": 307200,
-            "description": "JavaScript code to execute. Must declare a top-level `async function handler(input, context)`. Maximum size: 300KB (hard limit). Security restrictions: eval() and Function() constructor are not allowed.\n"
+            "description": "JavaScript code to execute. Must declare a top-level `async function handler(input, context)`. Maximum size: 300KB (hard limit). Security restrictions: dynamic code evaluation via `eval` or the `Function` constructor is not allowed.\n"
           },
           "schedule": {
             "type": "string",
@@ -3417,7 +3419,7 @@
           "intervals": {
             "type": "array",
             "deprecated": true,
-            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n`custom` marks a period-based consumption source: records carry the `period` they cover instead of sitting on a fixed grid, and the portal shows the whole data range as one bar per record.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -3425,7 +3427,8 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             }
           },
@@ -3529,7 +3532,7 @@
           "intervals": {
             "type": "array",
             "deprecated": true,
-            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n`custom` marks a period-based consumption source: records carry the `period` they cover instead of sitting on a fixed grid, and the portal shows the whole data range as one bar per record.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -3537,7 +3540,8 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             }
           },
@@ -3716,7 +3720,7 @@
         "additionalProperties": false
       },
       "PortalExtensionHookVisualizationMetadata": {
-        "description": "Hook that returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). It is invoked by the portal before fetching data, with the same context the data hook would receive, so that the discovery shape can vary per meter/contract. The expected response to the call is:\n  - 200 with a JSON body of shape:\n    {\n      \"type_options\": [\n        { \"id\": \"ht\", \"label\": { \"en\": \"High tariff\" }, \"aggregation_group\": \"consumption\", \"statistical_method\": \"sum\", \"unit\": \"kWh\", \"color\": \"primary\", \"precision\": 2 },\n        ...\n      ],\n      \"intervals\": [\"PT15M\", \"PT1H\", \"P1D\", \"P1M\", \"P1Y\"],\n      \"data_range\": { \"from\": \"2024-01-01T00:00:00Z\", \"to\": \"2026-05-01T00:00:00Z\" }\n    }\n  Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.\n  Each type option may also customize its rendering: `color` picks a Spark palette color (`primary`, `slate`, `mauve`, `orange`, `red`, `tomato`, `amber`, `green`, `blue`) used to draw the type's series; `precision` sets the number of decimal places to show for that type's values (axis labels, tooltips, summaries). Both are optional — the consumer falls back to its own defaults when they are omitted.\n  `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):\n    - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.\n    - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.\n  All fields are optional; the consumer falls back to its defaults for whatever the hook does not return.\nThe portal looks up this hook implicitly per extension (one `visualizationMetadata` hook per extension) — there is no need for a data-retrieval hook to reference it explicitly.\n",
+        "description": "Hook that returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). It is invoked by the portal before fetching data, with the same context the data hook would receive, so that the discovery shape can vary per meter/contract. The expected response to the call is:\n  - 200 with a JSON body of shape:\n    {\n      \"type_options\": [\n        { \"id\": \"ht\", \"label\": { \"en\": \"High tariff\" }, \"aggregation_group\": \"consumption\", \"statistical_method\": \"sum\", \"unit\": \"kWh\", \"color\": \"primary\", \"precision\": 2 },\n        ...\n      ],\n      \"intervals\": [\"PT15M\", \"PT1H\", \"P1D\", \"P1M\", \"P1Y\", \"custom\"],\n      \"data_range\": { \"from\": \"2024-01-01T00:00:00Z\", \"to\": \"2026-05-01T00:00:00Z\" }\n    }\n  Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.\n  Each type option may also customize its rendering: `color` picks a Spark palette color (`primary`, `slate`, `mauve`, `orange`, `red`, `tomato`, `amber`, `green`, `blue`) used to draw the type's series; `precision` sets the number of decimal places to show for that type's values (axis labels, tooltips, summaries). Both are optional — the consumer falls back to its own defaults when they are omitted.\n  `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):\n    - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.\n    - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.\n  All fields are optional; the consumer falls back to its defaults for whatever the hook does not return.\nThe portal looks up this hook implicitly per extension (one `visualizationMetadata` hook per extension) — there is no need for a data-retrieval hook to reference it explicitly.\n",
         "type": "object",
         "properties": {
           "id": {
@@ -3833,7 +3837,7 @@
           "intervals": {
             "type": "array",
             "deprecated": true,
-            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n`custom` marks a period-based consumption source: records carry the `period` they cover instead of sitting on a fixed grid, and the portal shows the whole data range as one bar per record.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -3841,7 +3845,8 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             }
           },
@@ -5276,10 +5281,6 @@
               }
             }
           },
-          "use_static_ips": {
-            "type": "boolean",
-            "description": "If set, requests are sent from epilot's static egress IPs. Mutually exclusive with secure_proxy."
-          },
           "secure_proxy": {
             "$ref": "#/components/schemas/PortalExtensionSecureProxy"
           }

package/definitions/customer-portal.json

@@ -543,10 +543,7 @@
                   },
                   "language": {
                     "type": "string",
-                    "enum": [
-                      "de",
-                      "en"
-                    ]
+                    "example": "de"
                   }
                 }
               }
@@ -962,11 +959,12 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             },
             "required": true,
-            "description": "Interval between consumption data points (e.g., PT15M for 15 minutes, PT1H for hourly). Not all intervals have to be supported."
+            "description": "Interval between consumption data points (e.g., PT15M for 15 minutes, PT1H for hourly). Not all intervals have to be supported. `custom` is period-based retrieval for sources that advertise it in their `visualizationMetadata.intervals`: the App returns one record per period it has data for within `from`..`to`, each carrying `period`, and the portal renders every record as its own bar.\n"
           },
           {
             "in": "query",
@@ -1020,6 +1018,30 @@
                               "en": "Billing period 1",
                               "de": "Abrechnungszeitraum 1"
                             }
+                          },
+                          "period": {
+                            "type": "object",
+                            "description": "The date range this value covers. Required for period-based sources (`interval=custom`), whose records don't sit on a fixed time grid: the portal renders one bar per record, orders them by `period.from`, and — unless `label` is set — labels each bar with the formatted `from` - `to` range. Ignored for interval-based retrieval.\n",
+                            "properties": {
+                              "from": {
+                                "type": "string",
+                                "format": "date-time",
+                                "description": "Start of the covered period."
+                              },
+                              "to": {
+                                "type": "string",
+                                "format": "date-time",
+                                "description": "End of the covered period. Shown as given in the fallback label, so pass the date the period visibly ends on (consecutive periods may share this boundary).\n"
+                              }
+                            },
+                            "required": [
+                              "from",
+                              "to"
+                            ],
+                            "example": {
+                              "from": "2024-01-03T00:00:00.000Z",
+                              "to": "2025-01-05T00:00:00.000Z"
+                            }
                           }
                         },
                         "required": [
@@ -11537,6 +11559,46 @@
           }
         }
       },
+      "TooManyRequests": {
+        "description": "The upstream service rate-limited the request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "BadGateway": {
+        "description": "The upstream service failed to process the request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "ServiceUnavailable": {
+        "description": "The requested feature is not configured",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "GatewayTimeout": {
+        "description": "The upstream service timed out",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
       "ConfirmUserInvalidRequest": {
         "description": "The request could not be validated",
         "content": {
@@ -12571,6 +12633,17 @@
               "new_design": {
                 "type": "boolean",
                 "description": "Enable or disable the new design for the portal"
+              },
+              "mcp_enabled": {
+                "type": "boolean",
+                "description": "Enable the MCP (AI agent) connector channel for this portal"
+              },
+              "mcp_grant_version": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "readOnly": true,
+                "description": "Server-managed generation used to invalidate MCP grants after the connector is disabled or re-enabled"
               }
             }
           },
@@ -15959,7 +16032,7 @@
           },
           "q": {
             "type": "string",
-            "description": "Keyword search query",
+            "description": "Free-text keyword search. This is plain text, **not** a query language: punctuation separates words rather than carrying any special meaning, and every word has to match. Use `q_fields` to restrict which fields are searched, and `filters`/`targets` for structured filtering. Overly long input is trimmed, and input with no words in it is ignored — the remaining parameters still apply.",
             "example": "contract"
           },
           "q_fields": {
@@ -16597,7 +16670,7 @@
           },
           "intervals": {
             "type": "array",
-            "description": "Intervals supported for the current context. If omitted, all intervals are assumed supported.",
+            "description": "Intervals supported for the current context. If omitted, all intervals are assumed supported. `custom` marks a period-based consumption source: the portal requests the whole `data_range` once with `interval=custom` and renders one bar per returned record (see `period` on the consumption data point) instead of offering interval / date navigation or period comparison. When `custom` is present it takes precedence over any fixed intervals also listed.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -16605,7 +16678,8 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             }
           },
@@ -19219,6 +19293,17 @@
               "new_design": {
                 "type": "boolean",
                 "description": "Enable or disable the new design for the portal"
+              },
+              "mcp_enabled": {
+                "type": "boolean",
+                "description": "Enable the MCP (AI agent) connector channel for this portal"
+              },
+              "mcp_grant_version": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "readOnly": true,
+                "description": "Server-managed generation used to invalidate MCP grants after the connector is disabled or re-enabled"
               }
             }
           },
@@ -19877,6 +19962,10 @@
             "type": "boolean",
             "description": "Whether the org is in canary mode"
           },
+          "is_legacy_design": {
+            "type": "boolean",
+            "description": "Whether the portal still runs the old design (the `new_design` feature setting is off). Legacy portals are always served the frozen legacy bundle, even when the org is in canary."
+          },
           "redirect_to": {
             "type": "string",
             "description": "The URL to redirect to",
@@ -19934,6 +20023,157 @@
             "example": true
           }
         }
+      },
+      "SupportReportType": {
+        "type": "string",
+        "enum": [
+          "bug",
+          "feedback"
+        ]
+      },
+      "SupportRequestAttachment": {
+        "type": "object",
+        "required": [
+          "filename",
+          "mime_type",
+          "contents"
+        ],
+        "properties": {
+          "filename": {
+            "type": "string",
+            "maxLength": 255,
+            "example": "screenshot.png"
+          },
+          "mime_type": {
+            "type": "string",
+            "example": "image/png"
+          },
+          "contents": {
+            "type": "string",
+            "description": "Base64-encoded file, optionally as a data URL"
+          }
+        }
+      },
+      "CleverPvContext": {
+        "type": "object",
+        "properties": {
+          "screen": {
+            "type": "string",
+            "maxLength": 256,
+            "description": "Current Clever PV screen identifier"
+          },
+          "version": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Clever PV application version"
+          },
+          "connection_state": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Device connectivity at the time of the report"
+          },
+          "locale": {
+            "type": "string",
+            "maxLength": 32,
+            "description": "App locale at the time of the report"
+          },
+          "timezone": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "App timezone at the time of the report"
+          },
+          "firmware_version": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Device firmware version when known"
+          },
+          "build": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "App build identifier when known"
+          },
+          "trace_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Client-generated correlation id for the report"
+          },
+          "device": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional device snapshot from the portal. Attached as a JSON file on\nthe original Zendesk comment. Must include id when present. Serialized\nJSON is limited to 256 KiB.\n"
+          },
+          "vendor": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "description": "Optional onboarding vendor id and name. Included in the Zendesk\ncomment. Not a portal entity.\n"
+          }
+        }
+      },
+      "CreateSupportRequest": {
+        "type": "object",
+        "required": [
+          "report_type",
+          "description",
+          "submission_id"
+        ],
+        "properties": {
+          "report_type": {
+            "$ref": "#/components/schemas/SupportReportType"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8000
+          },
+          "submission_id": {
+            "type": "string",
+            "minLength": 8,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9._-]+$",
+            "description": "Client-generated id for correlating the request"
+          },
+          "site_id": {
+            "$ref": "#/components/schemas/EntityId"
+          },
+          "device_id": {
+            "$ref": "#/components/schemas/EntityId"
+          },
+          "clever_pv": {
+            "$ref": "#/components/schemas/CleverPvContext"
+          },
+          "attachments": {
+            "type": "array",
+            "maxItems": 5,
+            "items": {
+              "$ref": "#/components/schemas/SupportRequestAttachment"
+            }
+          }
+        }
+      },
+      "SupportRequestResult": {
+        "type": "object",
+        "required": [
+          "reference",
+          "status"
+        ],
+        "properties": {
+          "reference": {
+            "type": "string",
+            "example": "12345"
+          },
+          "status": {
+            "type": "string",
+            "example": "new"
+          }
+        }
       }
     }
   },

package/definitions/event-catalog.json

@@ -52,7 +52,7 @@
       "post": {
         "operationId": "createCustomEvent",
         "summary": "createCustomEvent",
-        "description": "Reserve an org-scoped custom event name and persist its immutable v1.0 draft definition.",
+        "description": "Reserve an org-scoped custom event name and persist its immutable v1.0 draft definition. Custom events are always projected from an entity graph: entity_graph is required and, in guided mapping mode, every schema field needs a graph_source expression. Caller-supplied trigger fields are ignored for custom events.",
         "tags": [
           "Event Catalog"
         ],
@@ -159,6 +159,58 @@
           }
         }
       },
+      "put": {
+        "operationId": "replaceCustomEventDraft",
+        "summary": "replaceCustomEventDraft",
+        "description": "Replace the complete v1.0 definition of an org-scoped custom event while it is still an\nunpublished draft. Drafts have no consumers, so their definition is not yet immutable;\nthe event name is the identity and cannot change. Publication remains a separate action.\n",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateCustomEventPayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated draft event configuration",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventConfig"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Definition is invalid or the body event_name differs from the path"
+          },
+          "404": {
+            "description": "Custom event not found"
+          },
+          "409": {
+            "description": "Event is built-in or no longer an unpublished draft"
+          },
+          "422": {
+            "description": "Definition could not be stored"
+          }
+        }
+      },
       "delete": {
         "operationId": "deprecateCustomEvent",
         "summary": "deprecateCustomEvent",
@@ -775,16 +827,19 @@
             "default": false,
             "example": true
           },
+          "api_trigger": {
+            "type": "boolean",
+            "default": true,
+            "description": "Allows explicit API-source triggering, not HTTP transport. Automation also uses HTTP. Automation-only events always disable this source."
+          },
           "automation_trigger_only": {
             "type": "boolean",
-            "readOnly": true,
             "description": "Whether explicit triggering is restricted to Automation. When true, callers must pass\n`_trigger_source_type: automation` and a stable `_trigger_source`. The trigger uses\nstrict entity readiness validation and the durable Automation outbox.\nRequires `automation_trigger: true` and cannot be combined with `entity_operation`.\n",
             "default": false,
             "example": true
           },
           "automation_trigger_seed_node": {
             "type": "string",
-            "readOnly": true,
             "description": "Required entity-graph seed node for an Automation-only trigger. When configured, an\nexplicit trigger using any other node is rejected before hydration.\n",
             "example": "ticket"
           },
@@ -840,7 +895,7 @@
       },
       "CreateCustomEventPayload": {
         "type": "object",
-        "description": "Complete immutable custom-event v1.0 definition. Publication is a separate conditional action.",
+        "description": "Complete immutable custom-event v1.0 definition projected from a required entity graph. Publication is a separate conditional action.",
         "properties": {
           "event_name": {
             "type": "string",
@@ -877,6 +932,21 @@
             "type": "boolean",
             "default": true
           },
+          "api_trigger": {
+            "type": "boolean",
+            "default": true,
+            "description": "Allows API-source triggering independently of Automation (which also uses HTTP). Must be false for Automation-only events."
+          },
+          "automation_trigger_only": {
+            "type": "boolean",
+            "default": false,
+            "description": "Restricts triggering to Automation with durable delivery and strict readiness. Requires automation_trigger true, api_trigger false, and no entity_operation."
+          },
+          "automation_trigger_seed_node": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required cardinality-one graph seed for an Automation-only event. Inherited restrictions cannot be changed."
+          },
           "mapping": {
             "$ref": "#/components/schemas/EventMapping"
           },
@@ -891,7 +961,8 @@
         "required": [
           "event_name",
           "event_title",
-          "schema_fields"
+          "schema_fields",
+          "entity_graph"
         ]
       },
       "EventMapping": {
@@ -918,7 +989,7 @@
       },
       "CustomEventLineage": {
         "type": "object",
-        "description": "Optional catalog lineage to a separately named base event. It does not replace the base event.",
+        "description": "Optional catalog lineage to a separately named base event. Built-in inheritance is validated against this exact registered version; its trigger restrictions cannot be removed or replaced. It does not replace the base event.",
         "properties": {
           "base_event_name": {
             "type": "string"
@@ -1038,7 +1109,7 @@
           },
           "graph_source": {
             "type": "string",
-            "description": "Optional JSONata expression to extract the field value from the hydrated entity graph.\n\nThe expression has access to all hydrated graph nodes by their node ID.\nIf not specified, the field value must be provided as input when triggering the event.\n\nExamples:\n  - \"ticket.meter_reading_value\" (simple path)\n  - \"contact.email[0].email\" (nested/array access)\n  - \"ticket.reading_timestamp ?? $now()\" (with fallback)\n  - \"$number(meter_counter.reading_value)\" (type coercion)\n",
+            "description": "JSONata expression to extract the field value from the hydrated entity graph.\n\nThe expression has access to all hydrated graph nodes by their node ID.\nOptional for built-in events, where an unset value must be provided as input when\ntriggering the event. Required for custom events in guided mapping mode.\n\nExamples:\n  - \"ticket.meter_reading_value\" (simple path)\n  - \"contact.email[0].email\" (nested/array access)\n  - \"ticket.reading_timestamp ?? $now()\" (with fallback)\n  - \"$number(meter_counter.reading_value)\" (type coercion)\n",
             "example": "ticket.meter_reading_value"
           }
         },
@@ -1080,7 +1151,7 @@
         ]
       },
       "CustomSchemaField": {
-        "description": "Custom v1 fields support JSON Schema values and context entities; attachment semantics are built-in-only.",
+        "description": "Custom v1 fields support graph-projected JSON Schema values and context entities; attachment semantics are built-in-only.",
         "oneOf": [
           {
             "$ref": "#/components/schemas/PrimitiveField"
@@ -1585,7 +1656,7 @@
           },
           "attribute": {
             "type": "array",
-            "description": "Optional list of entity attributes to track for changes.\nIf specified, the event only triggers when these attributes are affected.\n- On createEntity: attribute must be defined in the entity payload\n- On updateEntity: attribute must be in diff.added, diff.updated, or diff.deleted\nIf not specified, all changes to matching entities will trigger the event.\n",
+            "description": "Optional list of entity attributes to track for changes.\nIf specified, the event only triggers when these attributes are affected.\n- On createEntity: attribute must be defined in the entity payload\n- On updateEntity: attribute must be in diff.added, diff.updated, or diff.deleted\nIf not specified, all changes to matching entities will trigger the event.\nDerived built-in triggers retain every inherited attribute; additions are OR alternatives.\nAn inherited unfiltered trigger cannot be narrowed by adding attribute filters.\n",
             "items": {
               "type": "string"
             },
@@ -1597,7 +1668,7 @@
           },
           "purpose": {
             "type": "array",
-            "description": "Optional list of purpose names to filter by.\nThe entity must have at least one matching purpose in its _purpose array.\nPurpose names are matched against the taxonomy classification names (e.g., \"Kündigung\", \"Umzug/Auszug\").\nIf not specified, the event triggers regardless of entity purpose.\n",
+            "description": "Optional list of purpose names to filter by.\nThe entity must have at least one matching purpose in its _purpose array.\nPurpose names are matched against the taxonomy classification names (e.g., \"Kündigung\", \"Umzug/Auszug\").\nFor custom events, names are allowed only when inherited unchanged from the actual\npinned built-in lineage version. New purposes must use stable purpose_filters IDs.\nNames and stable IDs are OR alternatives; operation/schema/attribute conditions still apply.\nIf neither purpose nor purpose_filters is specified, the event triggers regardless of purpose.\n",
             "items": {
               "type": "string"
             },
@@ -1608,7 +1679,7 @@
           },
           "purpose_filters": {
             "type": "array",
-            "description": "Stable purpose IDs plus immutable display-name snapshots for custom events.",
+            "description": "Stable purpose IDs plus immutable display-name snapshots for custom events. Additive to inherited purpose names (OR). Inherited unfiltered triggers cannot be narrowed.",
             "items": {
               "$ref": "#/components/schemas/PurposeFilterSnapshot"
             }
@@ -1734,7 +1805,7 @@
           },
           "fields": {
             "type": "object",
-            "description": "Input field values for the event. Keys must match the event's\nschema_fields definitions. Values are validated against each\nfield's JSON Schema.\n",
+            "description": "Input field values for built-in events. Keys must match the event's\nschema_fields definitions. Values are validated against each\nfield's JSON Schema. Ignored for custom events, whose fields are\nalways projected from the entity graph.\n",
             "additionalProperties": true
           },
           "skip_hydration": {