[One workflow] CommonTrigerDef properties required

src/platform/plugins/shared/workflows_extensions/README.md

@@ -30,7 +30,7 @@ This separation ensures that:
 
 The trigger registry follows the same pattern as steps:
 
-- **Server-side registry**: Stores trigger definitions (`id`, `eventSchema`, title, description, documentation, snippets). Other plugins register the shared **common** definition during `setup()`.
+- **Server-side registry**: Stores trigger definitions (`id`, `eventSchema`, title, description, and optional documentation/snippets). Other plugins register the shared **common** definition during `setup()`.
 - **Public-side registry**: Spreads the same common definition and adds **icon** (and optional async loader) for the workflows UI.
 
 **Async registration (public only):** The public trigger registry accepts either a definition or a **loader function** `() => Promise<PublicTriggerDefinition>`. Using a loader (e.g. `() => import('./my_trigger').then(m => m.myTriggerDefinition)`) keeps trigger modules and heavy deps out of your plugin's main bundle. Loaders are resolved in the background; `workflowsExtensions.isReady()` waits for both step and trigger loaders before the workflows UI renders.

src/platform/plugins/shared/workflows_extensions/common/trigger_registry/types.ts

@@ -42,7 +42,7 @@ export interface TriggerSnippets {
  * - id: globally unique, namespaced format <solution>.<event>
  * - eventSchema: must be a Zod object schema that rejects unknown fields
  *
- * Server and agent tooling read title, description, documentation, and snippets from here.
+ * Server and agent tooling read title and description from here; documentation and snippets are optional.
  * Public definitions spread this object and add UI-only fields (e.g. icon).
  */
 export interface CommonTriggerDefinition<EventSchema extends z.ZodType = z.ZodType> {
@@ -57,11 +57,11 @@ export interface CommonTriggerDefinition<EventSchema extends z.ZodType = z.ZodTy
   /**
    * Short human-readable name for this trigger (UI and agent catalog label).
    */
-  title?: string;
+  title: string;
   /**
    * User-facing description of when this trigger is emitted.
    */
-  description?: string;
+  description: string;
   /**
    * Documentation (details + YAML examples), aligned with step definitions.
    */

src/platform/plugins/shared/workflows_extensions/dev_docs/TRIGGERS.md

@@ -6,7 +6,7 @@ This section provides a complete guide for contributors who want to add event-dr
 
 **Quick checklist:**
 
-1. Define common trigger (id + eventSchema) in your plugin
+1. Define common trigger (id, eventSchema, title, description; optional documentation and snippets) in your plugin
 2. Register on server and public in plugin `setup()`
 3. Emit events via request context or direct `emitEvent`
 4. Add to approved list and get workflows-eng approval
@@ -20,11 +20,12 @@ Trigger IDs use the following convention:
 - ⚠️ Allowed: Inherited forms from OpenAPI/connectors/platform-owned contracts
 - ❌ Bad: `"my_trigger"` (no namespace), `"custom_trigger"` (event not camelCase)
 
-### Step 1: Define common trigger (id + eventSchema)
+### Step 1: Define common trigger (id, eventSchema, title, description; optional documentation and snippets)
 
-Create a shared definition (e.g. `common/triggers/my_trigger.ts`) in your plugin:
+Create a shared definition (e.g. `common/triggers/my_trigger.ts`) in your plugin. **title** and **description** are required. **documentation** (details + YAML examples) and **snippets** (e.g. a default `on.condition`) are optional but strongly recommended so the YAML editor, hover docs, and agent tools can guide users (aligned with custom steps):
 
 ```typescript
+import { i18n } from '@kbn/i18n';
 import { z } from '@kbn/zod/v4';
 import type { CommonTriggerDefinition } from '@kbn/workflows-extensions/common';
 
@@ -42,15 +43,28 @@ export type MyTriggerEvent = z.infer<typeof myTriggerEventSchema>;
 export const commonMyTriggerDefinition: CommonTriggerDefinition = {
   id: MY_TRIGGER_ID,
   eventSchema: myTriggerEventSchema,
+  title: i18n.translate('myPlugin.myTrigger.title', { defaultMessage: 'My trigger' }),
+  description: i18n.translate('myPlugin.myTrigger.description', {
+    defaultMessage: 'Emitted when something happens.',
+  }),
+  documentation: {
+    details: 'Filter when this workflow runs using KQL on event properties (e.g. event.category, event.message).',
+    examples: [
+      `## Match by category\n\`\`\`yaml\ntriggers:\n  - type: ${MY_TRIGGER_ID}\n    on:\n      condition: 'event.category: "alerts"'\n\`\`\``,
+    ],
+  },
+  snippets: { condition: 'event.category: "alerts"' },
 };
 ```
 
 - Use `.describe()` on schema fields so the UI and docs show helpful text.
 - `eventSchema` must be a Zod object schema; payloads are validated at emit time.
+- When you provide `documentation.examples`, each example must only reference fields present on `eventSchema` (agents pattern-match YAML examples).
+- When you provide `snippets.condition`, it must be valid KQL using only `event.*` fields from `eventSchema` (validated at registration).
 
 ### Step 2: Register on server
 
-In your plugin's server `setup()`, register the common definition (id + eventSchema only):
+In your plugin's server `setup()`, register the **same** common definition:
 
 ```typescript
 import type { WorkflowsExtensionsServerPluginSetup } from '@kbn/workflows-extensions/server';
@@ -68,30 +82,18 @@ Reference: `examples/workflows_extensions_example/server/triggers/index.ts`.
 
 ### Step 3: Register on public
 
-Create a public definition with UI metadata and register it in your plugin's public `setup()`:
+Spread the common definition and add **icon** only (browser-only UI):
 
 ```typescript
 import type { PublicTriggerDefinition } from '@kbn/workflows-extensions/public';
-import { i18n } from '@kbn/i18n';
 import React from 'react';
-import { MY_TRIGGER_ID, commonMyTriggerDefinition } from '../common/triggers/my_trigger';
+import { commonMyTriggerDefinition } from '../common/triggers/my_trigger';
 
 export const myTriggerPublicDefinition: PublicTriggerDefinition = {
   ...commonMyTriggerDefinition,
-  title: i18n.translate('myPlugin.myTrigger.title', { defaultMessage: 'My trigger' }),
-  description: i18n.translate('myPlugin.myTrigger.description', {
-    defaultMessage: 'Emitted when something happens. Use in workflow triggers to run on this event.',
-  }),
   icon: React.lazy(() =>
     import('@elastic/eui/es/components/icon/assets/star').then(({ icon }) => ({ default: icon }))
   ),
-  documentation: {
-    details: 'Filter when this workflow runs using KQL on event properties (e.g. event.category, event.message).',
-    examples: [
-      `## Match by category\n\`\`\`yaml\ntriggers:\n  - type: ${MY_TRIGGER_ID}\n    on:\n      condition: 'event.category: "alerts"'\n\`\`\``,
-    ],
-  },
-  snippets: { condition: 'event.category: "alerts"' },
 };
 
 // In public plugin setup():

src/platform/plugins/shared/workflows_extensions/server/trigger_registry/trigger_registry.test.ts

@@ -21,6 +21,8 @@ const createValidDefinition = (
   overrides: Partial<ServerTriggerDefinition> = {}
 ): ServerTriggerDefinition => ({
   id: 'cases.updated',
+  title: 'Case updated',
+  description: 'Fired when a case is updated.',
   eventSchema: validEventSchema,
   ...overrides,
 });

src/platform/plugins/shared/workflows_management/common/build_trigger_definitions_for_agent.test.ts

@@ -146,6 +146,8 @@ describe('lookupTriggerDefinitionsForAgent', () => {
         {
           id: 'example.minimal',
           eventSchema: z.object({ value: z.string() }),
+          title: 'Minimal trigger',
+          description: 'Minimal trigger for testing.',
         },
       ],
       triggerType: 'example.minimal',