<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
30-49	The rule
50-78	Scripts are mdl 1 — upgrade a headerless file before you edit it
79-95	Which document types have alter
96-113	Types with no alter: microflows, nanoflows, menus, Java actions

<!-- /skill-index -->

Choose the Edit Mode by Who Owns the Document

MDL has two ways to change a document, and each is safe in a different situation.

	Declarative	Patch
Statement	create or modify <type> X ( … ) { … }, the whole definition	alter <type> X …, only the change
Source of truth	your .mdl scripts	the stored model
Use for	new apps and modules; documents your scripts created and nobody has edited since	documents made or edited in Studio Pro; marketplace modules
Risk	drops whatever the statement does not say, including content MDL cannot express	none for what it does not mention

The rule

1. New app, new module, new document: write declarative MDL. There is nothing to read and nothing to preserve.
2. Existing Studio Pro document: change it with alter. An alter leaves every element it does not name untouched. Measured: alter page … set Caption changed one string and byte-preserved every other translation on the page.
3. describe → edit → create or modify only for documents mxcli created and whose stored state is still what your script produced (nobody has changed them in Studio Pro since). On a Studio Pro-authored document this path is lossy even when you change nothing. On real projects it has flipped association storage from table to column, dropped page translations, dropped nanoflow annotation links, changed export levels, and dropped a snippet's type. mxcli diff runs the script on a scratch copy and lists every unit it would write, so run it first and expect "exec would write nothing" for a document you did not mean to change.
4. Never drop and re-create an existing document to change it. The new document gets new identities. For an entity, the runtime then drops its table and its rows.

Not sure who owns it? Treat it as Studio Pro-owned.

Scripts are mdl 1 — upgrade a headerless file before you edit it

Every script you write starts with mdl 1;. A project script without that header is mdl 0, the alpha language: some statements mean something else there (limit 1, a reassignment without set, a backslash in a string) and some spellings mdl 1 refuses. So never mix dialects in one file. Adding mdl 1 statements to a headerless file runs them under mdl 0 rules, and typing the header in by hand changes the meaning of the lines already there.

Before you edit a headerless project script, upgrade that file:

./mxcli fmt --upgrade --header -p app.mpr -w script.mdl   # rewrite to mdl 1 and add the header
./mxcli check script.mdl -p app.mpr                       # reports what exec would refuse

fmt rewrites every spelling and construct whose meaning the header changes, and declines the header for the file when a construct has no mechanical rewrite or when exec would then refuse a statement — it names each one. Fix those by hand, or leave that file at mdl 0 and put the new work in a new file that starts with mdl 1;.

Then edit, exec, and exec the same script a second time: the second run must write nothing — every statement reported unchanged, or "already in sync". That needs re-runnable statements: create or modify, or create … if not exists, not a bare create, which refuses an existing document. A write on the second run means the script and the stored model disagree — find out why before you hand the change over.

Which document types have alter

./bin/mxcli syntax is authoritative. At the time of writing:

Document	Patch statement
Entity, attribute, index	alter entity (add / rename / modify / drop attribute, set …)
Association	alter association … set …
Enumeration	alter enumeration (add / rename / modify / drop value)
Page, snippet, layout	alter page / alter snippet / alter layout { set / insert / drop / replace }
Workflow	alter workflow { set / insert before / after / into / drop / replace } — activities by name or 'caption'
Settings, security	alter settings, alter app security, grant / revoke
Many pages at once	update widgets … where … (see bulk-widget-updates)
Microflow, nanoflow	none yet
Navigation profile	create or modify navigation with only the clauses to change — an omitted clause keeps its stored value; a { } menu block replaces the whole menu
Menu, Java action	none

Types with no alter: microflows, nanoflows, menus, Java actions

The only way to change one is to re-emit the whole document with create or modify. On a Studio Pro-authored microflow that rebuild renumbers element IDs, removes merges and resets connector curves, even for a one-line change. So:

• Prefer adding over editing. Put new logic in a new sub-microflow that you create declaratively, and limit the change to the existing flow to the one call that reaches it.
• Keep the change minimal. Start from fresh describe output, change only the lines you must, and do not reformat, reorder or tidy anything else.
• Review the result before you hand it over. Commit (or copy the .mpr) first. After exec, describe the document again and diff it against the original output. On an MPR v2 project, also check that git status mprcontents/ lists only the units you meant to change (mxcli diff-local shows them as MDL). Anything else that changed is a loss, not your edit.
• If the flow is large or the change is broad, tell the user and suggest making the change in Studio Pro.