Cover the image widget in the mx check gate, and fix the layout reference docs

[ako]

Follow-up to the authorable-layouts arc (#304). Two gaps it left behind: the CI gate builds no image widget, and the user manual for layouts was never updated.

No behaviour changes — one test-coverage commit and one docs commit.

1. The doctype gate built zero image widgets

03-page-examples.mdl said "No pluggable replacement exists. Image examples are therefore not included in this test file." That was wrong — image routes to com.mendix.widget.web.image.Image, and only the built-in staticimage/dynamicimage are deprecated (CE0582).

The consequence: the gate ran green through two separate image defects, both fixed in 597db1b with nothing here to catch a regression. bug-tests/ documents them, but TestMxCheck_DoctypeScripts only executes doctype-tests/*.mdl — that is what CI runs.

Three variants, chosen so the coverage is not a smoke test:

Widget	Why
pixels / 36	width is a visible property, taking the authored value by the ordinary route
default units	width/height are hidden under auto — the path that actually regressed
imageUrl mode	source lives in a text template, not the Image field

The middle one is the point. A hidden property must be written with its declared default rather than skipped; skipping leaves whatever the widget template captured, and image.json was extracted from a 48px logo — 48 against a declared 100 is CE0463 on every image widget. Nothing in the authored MDL distinguishes the two behaviours, which is why it needs a gate rather than a test asserting what the script says.

Non-vacuity measured, not assumed. With hiddenUnnamedProperties' default-writing stubbed back to the pre-597db1b2 skip, the gate reports CE0463 on all three widgets; with it in place, 0 errors. Omitting the Image: line likewise turns mx check red with "No image selected.".

Full gate run: green (578s).

2. The layout reference on the site was wrong, not just thin

docs-site/ was the one artifact the layouts arc never updated. create-layout.md predated all of it:

• Its synopsis does not work. It documented CREATE LAYOUT module.Name { widget_tree } — no header. Run verbatim: Error: layout needs a layouttype.
• class was absent, and it is load-bearing: Atlas scopes its layout rules to .layout-atlas, so a layout without one builds cleanly, passes mx check, and renders with no topbar bar and no sidebar rail.
• Missing entirely: OR REPLACE, the scrollcontainer / region / placeholder / navigationtree vocabulary, and the Marketplace refusal.
• It sent readers away: "For advanced layout customization, use Mendix Studio Pro" — for something mxcli has done since feat(pages): authorable layouts — CREATE, ALTER, repoint, and a scaffold for new projects #304.
• Neither "Example" was a CREATE LAYOUT. Both were CREATE PAGE statements naming an Atlas layout.

alter-layout.md is new — ALTER LAYOUT and the bulk ALTER PAGES … SET LAYOUT migration form had no page on the site at all. It covers addressing a region by slot, why ALTER beats CREATE OR REPLACE for a layout you did not write, and the guard's refusal semantics.

alter-page.md already documented the single-page SET Layout correctly, so it gains only the placeholder-guard note and a pointer.

Also: layout is a real top-level syntax path but was missing from the hand-maintained topic list in help.go, so mxcli syntax layout worked only if you already knew the word.

Everything documented was executed

Every code block ran against a real 11.13 project (result: 0 errors), and every quoted error message was produced by running the case that raises it — the Marketplace refusal, the unknown-header-property error, the no-placeholder refusal, and the placeholder guard with its MAP remedy.

That caught one claim I would otherwise have written from memory: a cross-platform layouttype is not refused. layouttype: 'Popup' is accepted and creates a native Popup layout, because the platform is inferred from the type. The page says "inferred", because that is what happens.

Testing

• Unit suite: green
• TestMxCheck_DoctypeScripts (integration): green, 578s
• Every documented statement exec'd against a real project → mx check 0 errors
• Controls: pre-fix engine behaviour → 3× CE0463; missing Image: → "No image selected."

Note on scope

An earlier version of this branch also carried a fix for the image defects. It turned out to be redundant — 597db1b2 had already fixed both on main, by a better route (changing the hidden-property invariant for every widget rather than editing one template's values). That work was dropped and the branch restarted from current main; only the coverage and docs remain.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JEZmExJUvn2nWTWE9mrd4i

---

Generated by Claude Code