fix(flow): clarify conversational route/handler name collision errors (#6825)

* fix(flow): clarify route/handler name collision validation errors

When @listen(...) includes the handler's own name, FlowDefinition validation
fails. This change improves the error text and how it surfaces for Python
Flow classes.

What changed
- _self_listen_error in flow_definition.py: two message variants (conversational
  vs default), both include the listen condition
- build_flow_definition in dsl/_utils.py: wraps FlowDefinition ValidationError
  with the Python Flow class name
- Tests for declarative and DSL-built flows; docs follow in a separate commit

When each error surfaces

1. Conversational message — FlowDefinition validation when
   conversational.enabled is true and listen references the handler name.
   Example: @listen("create_video") on def create_video in a conversational flow.
   Surfaces via:
   - FlowDefinition.from_declaration(dict/yaml) → pydantic ValidationError for
     FlowDefinition (Value error, methods.create_video.listen listen condition...)
   - MyFlow.flow_definition() / MyFlow() → ValueError Invalid flow definition
     for MyFlow: ... (wrapped by pydantic as ValidationError for MyFlow on
     instantiation)

2. Default (non-conversational) message — same trigger check when the flow is
   not conversational. Example: @listen("publish") on def publish.
   Surfaces via the same paths as (1).

3. Class-name wrapper — only on the Python DSL path when build_flow_definition
   catches FlowDefinition ValidationError. Prepends Invalid flow definition for
   {ClassName}: to the underlying message from (1) or (2). Does not apply to
   from_declaration without a Flow class.

* docs(flow): explain conversational handler naming vs route labels

Document why @listen route labels must differ from handler method names and
recommend the handle_* naming pattern.

* docs(cli): warn against matching @listen labels to handler names

Add AGENTS.md guidance for crew and flow scaffolding so coding assistants
do not name handlers the same as their @listen route or event labels.

* docs(cli): clarify @listen self-reference fails at validation

Document that matching @listen labels to handler names raises a validation
error at flow instantiation, and that the runtime loop only occurs if
validation is bypassed.

docs/edge/en/guides/flows/conversational-flows.mdx

@@ -376,6 +376,27 @@ def handle_internet_search(self) -> str:
     ...
 ```
 
+### Naming handlers
+
+The string in `@listen("…")` is a **router route label** (an event name), not the Python method name. Route labels and method completion events share one trigger namespace, so naming a handler the same as its route causes the handler to re-trigger itself in a loop.
+
+Use a different method name — the docs examples use a `handle_*` prefix:
+
+```python
+@listen("create_video")
+def handle_create_video(self) -> str:
+    """User wants a new video."""
+    ...
+```
+
+Do **not** mirror the route label on the method:
+
+```python
+@listen("create_video")
+def create_video(self) -> str:  # rejected at flow instantiation
+    ...
+```
+
 …and the router LLM sees:
 
 ```