Multi-version pluggable widgets: resolve CE0463 generically, add widget describe, docs

.claude/skills/debug-bson.md

@@ -37,12 +37,14 @@ Note the exact error code (CE0463, CE0642, etc.) and which widget triggers it.
 
 ### Step 2: Get a Known-Good Reference
 
-Create a working example in Studio Pro and update it:
+Create a working example in Studio Pro and update it. **Do this on a COPY** — both
+commands below mutate the project, and `update-widgets` converts an MPRv2 project to
+single-file v1 (deletes `mprcontents/`):
 
 ```bash
-# Convert project to latest format and update widget definitions
-reference/mxbuild/modeler/mx convert -p /path/to/app.mpr
-reference/mxbuild/modeler/mx update-widgets /path/to/app.mpr
+# Convert project to latest format and update widget definitions (mutates in place)
+reference/mxbuild/modeler/mx convert -p /path/to/copy.mpr
+reference/mxbuild/modeler/mx update-widgets /path/to/copy.mpr
 ```
 
 Then extract the widget's BSON to compare against your generated output.
@@ -323,7 +325,7 @@ for t, props in crash_props.items():
 
 **Investigation methodology used for v0.10 CE0463 fixes** — see [WIDGET_BSON_VERSION_COMPATIBILITY.md](../../docs/03-development/WIDGET_BSON_VERSION_COMPATIBILITY.md) for the full case study and version-resilience model.
 
-**Quick workaround** (if you can't fix the root cause): Run `mx update-widgets` after creating pages.
+**Quick workaround** (if you can't fix the root cause): normalize with `mxcli docker check`/`build`, which run the widget update **and preserve MPRv2 storage** (they snapshot/restore `.mpr` + `mprcontents/`). Do **not** run bare `mx update-widgets` on a v2 project you care about — it converts to single-file v1 and deletes `mprcontents/` (corrupts git, breaks `mxcli run --local`). Raw `mx update-widgets` is fine only on a throwaway diagnostic copy or a v1 project.
 
 ### CE0642: Property X Is Required
 
@@ -388,7 +390,7 @@ for _, pm := range a.ParameterMappings {
 
 2. **Mode-dependent properties must be consistent**: When changing a mode-switching property (e.g., `showContentAs`), all dependent properties must be updated to match.
 
-3. **`mx update-widgets` is the safety net**: Running this post-processing step normalizes all widget Objects to match mpk definitions. Use it as a fallback.
+3. **Widget normalization is the safety net — via `mxcli docker check`/`build`**: they run the update-widgets normalization *and* preserve MPRv2 storage (snapshot/restore). Bare `mx update-widgets` does the same normalization but rewrites a v2 project to v1 and deletes `mprcontents/` — only use it on a v1 project or a throwaway diagnostic copy.
 
 4. **The mpk is the source of truth**: The XML schema defines property types/defaults, the editorConfig.js defines visibility rules. Together they specify the complete expected Object structure.
 

.claude/skills/fix-issue.md

@@ -79,6 +79,8 @@ to the symptom table below, so the next similar issue costs fewer reads.
 | CE0463 on a pluggable widget whose TextTemplate property is *conditionally hidden* by an enum/boolean toggle (VideoPlayer `videoUrl`/`posterUrl` when `type=expression`; Timeline `title`/`description`/`timeIndication` when `customVisualization=true`) — engine clones the template's populated `ClientTemplate` for a property Studio Pro hides and nulls | Engine has no per-property visibility metadata; the hide rules live in the widget's compiled `editorConfig.js` (`hidePropertyIn`/`hidePropertiesIn`), not `widget.xml` | `mdl/executor/widget_defs.go` `widgetVisibilityRules` table + `mdl/backend/mpr/widget_builder.go` `ApplyPropertyVisibility` | Extract the widget's `.mpk` `*.editorConfig.js` (`unzip` + grep `hidePropertiesIn`), transcribe the rule into `widgetVisibilityRules[widgetID]` as `{propertyKey, hiddenWhen:{propertyKey, operator eq/ne/truthy/falsy, value}}`; the engine nulls hidden TextTemplate-typed props at build time. Bump `WidgetDefGeneratorVersion` so stale project `.def.json` auto-refresh. Issue #574 |
 | CE0463 on a `datagrid` whose column uses `ColumnWidth: manual` + `Size: N` — Studio Pro resets the column `size` to `1` | The MDL `ColumnWidth:` keyword isn't mapped to the schema `width` enum, so `width` stays at its `autoFill` default; `size` only applies when `width=manual`, so the value is inconsistent. Regression from the Stream B keyword-path consolidation (the deleted `datagrid_builder.go` did `colPropString(col.Properties, "ColumnWidth", "autoFill")`) | `mdl/executor/widget_defs.go` `itemPropertyAliases` | Add the MDL→schema alias under `[datagrid]["columns"]`: `"width": {"ColumnWidth"}`. Bump `WidgetDefGeneratorVersion` so stale `.def.json` regenerate. General rule when a column/object-list property's MDL keyword differs from the `.mpk` schema key (not just case), add it to `itemPropertyAliases`; cross-check against the pre-B3 `datagrid_builder.go` `colProp*` calls for any other dropped mappings |
 | CE0463 on an MDL-created **Combobox** (or other platform widget) at `mxcli docker build/check` time — but the SAME widget passes `mx check` on a project whose installed `.mpk` matches mxcli's embedded template (Mendix 11.6 / combobox 2.5.0). NOT the old incomplete-template bug (#112, fixed — a matching-version combobox is clean) | Widget-VERSION mismatch: mxcli emits the embedded 2.5.0-shaped PropertyTypes, but the project has a NEWER combobox (e.g. 2.8.1) that reorders/regroups properties. `augmentFromMPK` patches presence + enum values but can't restructure the baseline; `GenerateFromMPK` is less faithful still (fails even on a matching version). The designed remediation is `mx update-widgets` (docker build/check runs it before `mx check`) | `cmd/mxcli/docker/check.go` + `build.go` (`updateWidgetsPathArg`) — the update-widgets *invocation*, not the widget emission | The real trap was that `mx update-widgets <bare-app.mpr>` **crashed** (`AddProjectDirAsAllowedPath` → `Path.GetDirectoryName("app.mpr")` = "" → `System.ArgumentNullException`) and some mx builds exit 0 after printing it, so the migration silently no-op'd and CE0463 survived. Pass an **absolute** path to update-widgets (always has a directory component). `mx check` is unaffected. Diagnosis: run the bundled `mx update-widgets <bare.mpr>` yourself — if it throws ArgumentNullException on AddProjectDirAsAllowedPath, the path lacks a dir. Faithful multi-version widget emission is the larger fix (#529). Issue #112; repro `mdl-examples/bug-tests/112-combobox-enum-ce0463-widget-version.mdl` |
+| **CE0463 "widget definition changed" at an `Image` widget** on Mendix 11.7+ (`mx check` without `update-widgets`) — a plain mxcli-authored Image, no custom config. `update-widgets` clears it (and on v2 destroys `mprcontents/`, so it's a data-loss trap) | NOT a version stamp, Type `$ID`s, property order, or missing properties (all ruled out empirically). The embedded `image.json` carried a **spurious default value**: a `WidgetValue.Image` pointing at `Atlas_Core.Content.Mendix` (Atlas's Mendix logo), captured when the template was extracted from a project that had it set. The installed 11.12 Image widget expects that field empty, so MxBuild flags the definition as changed | `modelsdk/widgets/templates/mendix-11.6/image.json` + `sdk/widgets/templates/mendix-11.6/image.json` (line ~63) | Clear the stale default: `"Image": "Atlas_Core.Content.Mendix"` → `"Image": ""` in both engine templates. **Diagnosis method for this whole CE0463 class**: dump the widget BSON, `mx update-widgets` on a COPY, dump again, diff the `CustomWidgets$CustomWidget` subtree **order-independently** (canonicalise key order + mask `$ID`/`TypePointer` blobs). Reordering and generic instance chrome (`LabelTemplate`, `Appearance.DesignProperties`) are cosmetic — a *passing* widget gets reordered/those-added too; the real cause is whatever value/structure survives that normalisation. Other hand-extracted templates likely hide similar stale defaults (audit with the same diff). Repro `mdl-examples/bug-tests/image-ce0463-stale-default.mdl`. DataGrid2 custom-content CE0463 (#600) is a *separate*, more complex delta — same method, own fix |
+| `mxcli docker check`/`build` (or a bare `mx update-widgets`) **silently deletes `mprcontents/`** and rewrites an MPRv2 project into single-file v1 — `check` reports **0 errors** and looks successful, but the git working tree diverges from tracked files, a running `mxcli run --local` loop breaks (it watches `mprcontents/`), and Studio Pro may crash on open (`LibGit2RepositoryProvider.WriteBaseFile`). Triggered by following the CE0463 remediation on a `mxcli new` (always v2) project | The pre-check `mx update-widgets` step (run to suppress false CE0463) **performs the conversion**: it inlines every unit into the `.mpr` (`Unit.Contents` column) and deletes `mprcontents/`. The `check` itself is read-only; `update-widgets` is the mutator. docker check/build invoked it with no storage-format protection | `cmd/mxcli/docker/check.go` (`snapshotStorageFormat` / `copyFile` / `copyDir`) + `build.go` | Snapshot `.mpr` + `mprcontents/` to a temp dir before `update-widgets`, `defer restore()` after the check (restore removes the post-conversion single-file `.mpr` residue and puts the v2 tree back); MPRv1 projects need no protection. The check still runs against the widget-normalized model, so CE0463 stays suppressed — only the on-disk format is preserved. **Never tell an agent to run bare `mx update-widgets` on a v2 project** — the synced skills (`create-page.md`, `custom-widgets.md`, `migrate-design-prototype.md`, `download-marketplace-content.md`) + dev `debug-bson.md` route to `mxcli docker check`/`build` (v2-safe) instead. Issue #763 / PR #764 |
 | Nightly `mx check` reports `CE0117 "Error(s) in expression." at Log message activity 'Log message (warning)'` on Mendix 10.24.19+ but not 10.24.16 or 11.x | Mendix 10.24.19 tightened expression validation: `toString(<string>)` is now a type error (toString expects a non-string input). An example called `toString($OrderNumber)` where `$OrderNumber` was already a string parameter | The offending `log warning ... with ({1} = toString($stringVar))` — find via `~/.mxcli/mxbuild/{ver}/modeler/mx check`, then bisect with `drop microflow ...` until CE0117 disappears | Remove the redundant `toString()` wrapper around already-string values. Only wrap non-string values (integers, decimals, dates, enums) in `toString()`. The Mendix 11.x parser is more lenient and lets this slide, but 10.24.19+ rejects it |
 | A page-level property can't be set — `ALTER PAGE X { SET PopupWidth = 800; }` (or any page-level prop other than Title/Url) fails with `unsupported page-level property: …` | The page-level SET handler only special-cased a couple of properties; everything else fell through to the default error | `mdl/backend/pagemutator/mutator.go` → `applyPageLevelSetMut` (shared by both engines) | Add a `case` writing the field at the top level of the Forms$Page doc via `dSetOrAppend` with the on-disk BSON type (int64 for PopupWidth/PopupHeight, bool for PopupResizable — verify against a Studio Pro page with `mxcli bson dump --format bson`). Page-level prop names are **case-sensitive**. For DESCRIBE roundtrip, emit the values back in the CREATE PAGE header. CREATE-time support: add a generic `IDENTIFIER COLON propertyValueV3` to `pageHeaderPropertyV3` (regen grammar), recognize the keys in `parsePageHeaderV3` (`applyGenericPageHeaderProp`, error on unknown), carry `*int`/`*bool` on `CreatePageStmtV3`, default to 600/600/false in `buildPageV3`, and have both writers honour `page.Popup*` (legacy `sdk/mpr/writer_pages.go` int64; codec `mdl/backend/modelsdk/page_write.go` int32 via gen — tolerated by mx check). The MCP backend has its **own** `mcpPageMutator` (pg content tree, not raw BSON) — page-level SET there reaches `SetWidgetProperty("")`; map it or reject honestly (it rejects, pending a `pg_read_page` probe of the pop-up keys). Issue #661 |
 | `PopupWidth: 0` / `PopupHeight: 0` rejected ("must be a positive number") on CREATE or ALTER PAGE; user can't make an auto-size pop-up | 0 is actually Studio Pro's **default** for pop-up dimensions (auto-size) — verified live on 11.12: a pg-created PopupLayout page stores 0/0 and `mx check` = 0 errors. Two validators rejected ≤0, and both writers coerced ≤0→600, so even an allowed 0 became 600 | `mdl/visitor/visitor_page_v3.go` (`popupDimensionValue`) + `mdl/backend/pagemutator/mutator.go` (`coercePopupDimension`) + `mdl/executor/cmd_pages_builder_v3.go` (builder default) + `sdk/mpr/writer_pages.go` & `mdl/backend/modelsdk/page_write.go` (`popupDimension`) + `mdl/executor/cmd_pages_describe.go` | Relax both validators to reject only **negative**; default the builder to **0** (not 600, matching Studio Pro); drop the `≤0→600` coercion in both writers (clamp only negatives to 0); have DESCRIBE suppress only the real default 0 (emit an explicit 600). No `*int` needed — 0 is a valid stored value. Bug-test `mdl-examples/bug-tests/713-popup-zero-dimensions.mdl`. Issue #713 |

.claude/skills/mendix/create-page.md

@@ -831,9 +831,16 @@ Notes:
   PieChart use the same `series` shape.
 - **CE0463 at `mx check`**: charts can report "widget definition changed" from
   widget-version drift (embedded template vs the installed `Charts.mpk`), even for a
-  chart with no series. `mxcli docker check`/`build` fix this automatically by
-  running `mx update-widgets` first; if you invoke `mx check` directly, run
-  `mx update-widgets <app.mpr>` (absolute path) beforehand.
+  chart with no series. Clear it with **`mxcli docker check`/`build`**, which normalize
+  the widgets and preserve your storage format.
+  **Do NOT run bare `mx update-widgets` on an MPRv2 project** (one with an
+  `mprcontents/` folder — everything `mxcli new` creates). `mx update-widgets` rewrites
+  the project into the single-file v1 format and **deletes `mprcontents/`**, which
+  corrupts a git working tree, breaks a running `mxcli run --local` loop, and can leave
+  Studio Pro unable to open the project. `mxcli docker check`/`build` snapshot and
+  restore the v2 files around the normalization, so they are safe; raw
+  `mx update-widgets` is only safe on a v1 project (or on a throwaway copy used purely
+  for diagnosis).
 - LineChart/BubbleChart/HeatMap (the `line`/`scalecolor` object-lists) are not yet
   authorable via MDL — use Studio Pro for those.
 

.claude/skills/mendix/custom-widgets.md

@@ -123,10 +123,16 @@ MDL032).
 
 **CE0463 "update this widget" is EXPECTED after generating charts.** mxcli writes
 the WidgetType from an embedded 11.6 baseline; the installed Charts.mpk is a
-different version, so Studio Pro/mxbuild flags drift. Clear it with
-`mx update-widgets` (or just use `mxcli docker check`/`build`, which run it first)
-before `mx check`. The whole `mdl-examples/doctype-tests/34-chart-widget-examples.mdl`
-builds **0 errors** after update-widgets.
+different version, so Studio Pro/mxbuild flags drift. Clear it with **`mxcli docker
+check`/`build`** (they normalize the widgets and preserve your storage format). The
+whole `mdl-examples/doctype-tests/34-chart-widget-examples.mdl` builds **0 errors**
+after normalization.
+**Do NOT run bare `mx update-widgets` on an MPRv2 project** (an `mprcontents/`-folder
+project — what `mxcli new` creates): it converts the project to single-file v1 and
+**deletes `mprcontents/`**, corrupting git, breaking a running `mxcli run --local`
+loop, and sometimes making the project unopenable in Studio Pro. `mxcli docker
+check`/`build` snapshot/restore the v2 files around the normalization; raw
+`mx update-widgets` is only safe on a v1 project or a throwaway diagnostic copy.
 
 **DESCRIBE round-trips** series/line/scalecolor object-lists (item names are
 synthesized, e.g. `series1`); a Pie/HeatMap's widget-level `SeriesName`/datasource

.claude/skills/mendix/download-marketplace-content.md

@@ -60,7 +60,7 @@ mxcli marketplace install <content-id> -p app.mpr [--version X.Y.Z]
 
 | Content type | Behavior |
 |---|---|
-| **Widget** | Copied into `widgets/` (overwrites on update). Reload in Studio Pro or run `mx update-widgets`. |
+| **Widget** | Copied into `widgets/` (overwrites on update). Reload in Studio Pro, or run `mxcli docker check`/`build` to normalize (v2-safe). Do **not** run bare `mx update-widgets` on an `mprcontents/` project — it converts to v1 and deletes `mprcontents/`. |
 | **Module** (new) | Imported via `mx module-import` — needs a matching mxbuild (`mxcli setup mxbuild -p app.mpr`). |
 | **Module** (already present) | **Reported, not modified** — see the caveat below. |
 | Theme / Starter App / Sample | Downloaded with import instructions (import via Studio Pro). |

.claude/skills/mendix/migrate-design-prototype.md

@@ -256,7 +256,9 @@ too — each `series`/`line` binds its own OQL-view datasource + X/Y attributes;
 Pie/HeatMap bind at the widget level (`ValueAttribute:`, Pie needs `SeriesName:`).
 See **[Custom & Pluggable Widgets → Charts](custom-widgets.md)** for the chart-type
 → id table, per-chart required-property gotchas (TimeSeries needs a datetime X,
-Bubble needs a size attribute), and the **CE0463 → `mx update-widgets`** step.
+Bubble needs a size attribute), and the **CE0463 → `mxcli docker check`/`build`** step
+(these normalize widgets *and* preserve MPRv2 storage — never run bare
+`mx update-widgets` on a `mxcli new` project; it deletes `mprcontents/`).
 `mdl-examples/doctype-tests/34-chart-widget-examples.mdl` is the full showcase.
 
 **Pluggable-widget gotchas:**
@@ -502,8 +504,9 @@ the fast index so a design migration doesn't rediscover them.
   (`Charts.mpk`: column/bar/line/area/pie)** now author via MDL — each `series` (an object-list
   item inside the chart) binds a datasource plus X/Y attributes:
   `series s1 (staticDataSource: database from Module.View, staticXAttribute: "X", staticYAttribute: "Y")`
-  (a per-series OQL view works too). `mxcli docker check`/`build` run `mx update-widgets`, which
-  clears the widget-version-drift CE0463. Still lighter when the design allows: a **CSS-background
+  (a per-series OQL view works too). `mxcli docker check`/`build` clear the
+  widget-version-drift CE0463 (they normalize the widgets and preserve MPRv2 storage —
+  do not run bare `mx update-widgets`, which deletes `mprcontents/`). Still lighter when the design allows: a **CSS-background
   SVG** container (or `HTMLElement`) for sparklines/trends — no datasource — and `ProgressCircle`
   (`type: expression`, `expressionCurrentValue: '$currentObject/Rate'`, min `'0'` / max `'100'`,
   `labelType: percentage`) for a single-value gauge.

CLAUDE.md

@@ -417,7 +417,7 @@ go build -o bin/mxcli ./cmd/mxcli
 | **Diff local** | `mxcli diff-local -p app.mpr --ref head` | Git diff for MPR v2 projects |
 | **Diff revisions** | `mxcli diff-local -p app.mpr --ref main..feature` | Compare two arbitrary git revisions |
 | **OQL** | `mxcli oql -p app.mpr "select ..."` | Query running Mendix runtime |
-| **Widgets** | `show widgets`, `update widgets set ...` | Widget discovery and bulk updates (experimental) |
+| **Widgets** | `show widgets`, `update widgets set ...`, `mxcli widget describe <id>` | Widget discovery, bulk updates (experimental), and inspecting a widget's discovered properties + dynamic rules |
 | **External SQL** | `sql connect`, `sql <alias> select ...`, `mxcli sql` | Direct SQL queries against PostgreSQL, Oracle, SQL Server (credential isolation) |
 | **Data import** | `import from <alias> query '...' into Module.Entity map (...)` | Import from external DB into Mendix app PostgreSQL (batch insert with ID generation) |
 | **Connector gen** | `sql <alias> generate connector into <module> [tables (...)] [views (...)] [exec]` | Auto-generate Database Connector MDL from discovered schema |