Docs: retrieve uses `sort by` (not `order by`); surface entity event handler MDL syntax

[ako]

Summary

Two documentation gaps surfaced from AI-agent MDL generation. Both are cases where the tool already does the right thing but the (synced) skills steer agents wrong.

1. retrieve uses sort by, not order by

In a microflow retrieve, sorting is sort by:

retrieve $List from Mod.Entity
  where (...)
  sort by Mod.Entity.Name asc
  limit $Lim offset $Off;

order by produces a parse error on retrieve — it is reserved for catalog queries (select ... from CATALOG.x). Also note limit/offset accept variables and expressions (e.g. limit $Lim), not only literals — contrary to a common assumption.

The write-microflows skill does not clearly document the retrieve … sort by / limit / offset clause. Add it so agents stop emitting order by.

2. Entity event handlers ARE supported in MDL

Binding a microflow to an entity event works today:

alter entity Mod.Entity
  add event handler on before commit call Mod.ACT_Validate($currentObject) raise error;

(and inside create entity). It's in docs/01-project/MDL_QUICK_REFERENCE.md:80-81 and generate-domain-model.md, but it is not surfaced in the synced microflow/domain skills, so agents fall back to the manual EVT_* + Studio-Pro-mapping workaround. Make this discoverable in the skills.

Reported via external user feedback.

[github-actions]

Issue Triage

Summary:
The issue requests that the mxcli documentation/skills be updated to reflect the correct MDL syntax for retrieve (using sort by, not order by) and to surface the supported entity‑event‑handler MDL construct.

Checklist for feature request completeness

Required info	Present?	Notes
Use case – why the feature is needed / what problem it solves	✅	Describes AI‑agent MDL generation producing incorrect syntax due to missing docs.
Proposed syntax or behavior (if applicable)	✅	Shows correct retrieve … sort by … limit … offset and alter entity … add event handler … examples.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix versions the documentation applies to.

What’s missing:
Please add the Mendix version(s) for which these documentation updates are relevant (e.g., “applies to Mendix 10.x and later” or specify any version constraints).

If you can provide that detail, the issue will be complete. Thanks for the clear description!

---

Automated triage via OpenRouter — workflow source