refactor

pkg/flow/hooks.go

@@ -13,9 +13,17 @@ import (
 // (structured log line) and "webhook" (HTTP POST of the event). Domain packages
 // register their own hooks (e.g. "amqp_emit") on the same registry.
 func RegisterBuiltinHooks(reg *Registry) {
-	reg.Hook("log", logHook)
-	reg.Hook("noop", func(context.Context, *State, HookInfo, json.RawMessage) error { return nil })
-	reg.Hook("webhook", webhookHook(&http.Client{Timeout: 10 * time.Second}))
+	reg.HookWithMeta("log", logHook, CapabilityMeta{
+		Description:   "Write a structured log line for the current step and phase.",
+		ExampleParams: json.RawMessage(`{"message":"payment captured"}`),
+	})
+	reg.HookWithMeta("noop", func(context.Context, *State, HookInfo, json.RawMessage) error { return nil }, CapabilityMeta{
+		Description: "Do nothing. Useful as a placeholder while shaping a flow.",
+	})
+	reg.HookWithMeta("webhook", webhookHook(&http.Client{Timeout: 10 * time.Second}), CapabilityMeta{
+		Description:   "POST the flow event payload to an external HTTP endpoint.",
+		ExampleParams: json.RawMessage(`{"url":"https://example.test/order-events","headers":{"X-Flow":"place-and-pay"}}`),
+	})
 }
 
 // logHook emits a structured log line for the step/phase. Params (optional):