From 98034dae87017be07c3513078ab5d48e2f08ae5d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 22 Sep 2026 15:04:01 +0000 Subject: [PATCH] learn(skills/doctor-triage.md): triage a red doctor.sh before proposing a fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 2026-09-22 macOS onboarding thread burned an afternoon across four people because three distinct failures render identically in doctor's output, and the first confident answer — "install Studio Pro 10.24.18" — could not have fixed any of them. The skill separates the three classes (my environment is wrong / the toolkit's own self-check is wrong / this red does not apply in my lane), makes Step 1 establish what is actually on the machine (`file` on the exact path doctor printed, which installs exist, whether each carries a bundled `mx`), and pairs each rule with the wrong output it prevents: the Linux-ELF mxbuild answered with a Studio Pro version, and the false `fail (unreadable error file)` from the self-test bug fixed in c0ea53c — a string that means the gate is broken, on a healthy gate. Also covered: the three toolchain lanes (bundled `mx`, with macOS shipping one only from Mendix 11; the Linux-only CDN toolchain; the container lane, which is runtime-agnostic although doctor currently probes only `docker` — noted as a limitation, not fixed here), a derivation for which FAILs block instead of a list that rots, the N+M-lines-dispositioned completion bound, and the VM/arch caveat that makes a sandboxed session's findings non-transferable. Routing: new `diagnose` row in bin/lib/skill-routing.tsv, surfaces re-rendered with bin/render-routing.sh; `--check` clean (baseline 73341 words, budget 80000). No version lists or clone paths are cached in the skill — two people in that thread had the toolkit at different paths. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0187r9bQWkZAEppyEqrDevjK --- CHANGELOG.md | 1 + README.md | 1 + ROUTING.md | 1 + agents/architect-agent.md | 1 + agents/ba-agent.md | 1 + agents/gate-agent.md | 1 + agents/mdl-agent.md | 1 + agents/review-agent.md | 1 + agents/test-agent.md | 1 + bin/lib/skill-routing.tsv | 1 + skills/doctor-triage.md | 138 ++++++++++++++++++++++++++++++++++++++ 11 files changed, 148 insertions(+) create mode 100644 skills/doctor-triage.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8101999..f884edb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- learn(skills/doctor-triage.md): **"doctor.sh says red — what now?" is now on disk instead of in a Slack thread.** Three failures that render identically get separated: my environment is wrong / the toolkit's own self-check is wrong / this line does not apply in my lane. Check the machine before naming a fix — a wrong-arch binary, a missing one and a broken self-check all read the same, which is how *"install Studio Pro 10.24.18"* became the first confident answer to a Linux-ELF mxbuild on a Mac, and how a false `fail (unreadable error file)` (the self-test bug fixed in `c0ea53c`) sent people to audit their own machines. Also: the three toolchain lanes (bundled `mx` — macOS ships one only from Mendix 11 — the Linux-only CDN toolchain, and the container lane, runtime-agnostic although doctor still probes only `docker`), a derivation for which FAILs block rather than a list that rots, the N+M-lines-dispositioned bound, and the VM/arch caveat. From the macOS onboarding thread of 2026-09-22 — Yvann, and the four people in it - fix(bin/doctor.sh): **the gate self-test renamed the model in its scratch dir to `model.mpr` while copying `mprcontents/` verbatim beside it, so mxbuild bailed before writing any error file and the self-test reported `fail (unreadable error file)` — the F-042-class string that means "the gate itself is broken" — on a perfectly healthy gate.** `mprcontents/` carries an internal record of the model's real basename; the rename breaks the pair. The scratch copy now keeps the real basename (`$scratch/$(basename "$MPR")`), threaded through all four later references (baseline count, injection `exec -p`, known-bad count). **Not field-run** — reasoned and inspected only; needs one run of `doctor.sh --gate-selftest ` on a macOS machine with Studio Pro 11 and a real `.mpr` before the team is told to pull. Found by Yvann during Mac/sandbox onboarding — Yvann - docs(front door): **README and `toolkit-guide.html` now count five ways in, not three.** Both already listed migration, requirements-driven, greenfield and the à-la-carte no-pipeline route; only the headlines said "three", so sessions reading the headline reported three entry modes while the runbook and `CLAUDE.md` said three plus à-la-carte. Wording now: four pipeline entry modes plus one route with no pipeline — Maurits Visser - docs(testing): **Windows full test-run prompt.** `docs/windows-test-run.md` — a paste-able, unattended Claude Code prompt for a Git Bash machine: guards, both fixture suites, 27 Windows-relevant fixtures with their subjects, the committed inputs (`fixtures/app-analysis`, page-fidelity mocks, html-to-md capture) run directly, and a field run on a scratch copy of a real project incl. the two-tree and toolkit.env probes; one results file, facts only — Maurits Visser diff --git a/README.md b/README.md index 96d0a21..5629526 100644 --- a/README.md +++ b/README.md @@ -686,6 +686,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | `skills/bug-submission-checklist.md` | | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | `skills/upstream-feedback.md` | | A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause | `skills/empty-widget-triage.md` | +| doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | `skills/doctor-triage.md` | | Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model | `skills/sandbox-ab-tool-defect-probe.md` | | Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load | `skills/restart-sp-reopen-and-hang-detection.md` | | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | `skills/field-run.md` | diff --git a/ROUTING.md b/ROUTING.md index f77bbac..bca5d9a 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -242,6 +242,7 @@ picks the row up. That is the whole procedure — there is no second list to rem | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | `skills/bug-submission-checklist.md` | mdl,gate,review | 5,6 | ondemand | | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | `skills/upstream-feedback.md` | all | - | ondemand | | A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause | `skills/empty-widget-triage.md` | mdl,test,review | 5,6 | ondemand | +| doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | `skills/doctor-triage.md` | all | - | ondemand | | Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model | `skills/sandbox-ab-tool-defect-probe.md` | mdl,gate | - | ondemand | | Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load | `skills/restart-sp-reopen-and-hang-detection.md` | mdl,gate | - | ondemand | | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | `skills/field-run.md` | all | - | ondemand | diff --git a/agents/architect-agent.md b/agents/architect-agent.md index 18fe09b..09db2f5 100644 --- a/agents/architect-agent.md +++ b/agents/architect-agent.md @@ -73,6 +73,7 @@ You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you ne | `skills/workflow-structure-rules.md` | Designing or reviewing a Workflow's SHAPE before or after the MDL — where a path may end, boundary event vs event sub-process, parallel-split limits, outcome minimums, targeting from the sentence, multi-user decision methods, which edits break running instances; and any CE6689/CE1844/CE1845/MW0012 after a clean mxcli check | | `skills/mendix-epics-api.md` | Working with the Mendix Epics board programmatically — creating/reading stories and epics, updating workflow state, or integrating BRDs with the portal | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/field-run.md` | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | | `skills/learned-mdl-cannot-express.md` | Before a wireframe or a design commits to a WIDGET — and when a page script hits a parse error that looks like a syntax mistake: the short list of things MDL cannot write at all, and the four-minute probe that answers it at Stage 3 instead of at build time | | `skills/platform-link.md` | At project birth (before the first build script) and any time a model needs a platform home: creating the Team Server app, adopting an existing GitHub-born model into it without rewriting history, or deploying; also when the Platform SDK returns 403, git rejects the PAT, a deploy cannot be triggered from a PAT, or the app turns out to be a Free App | diff --git a/agents/ba-agent.md b/agents/ba-agent.md index c087ff7..04e7b03 100644 --- a/agents/ba-agent.md +++ b/agents/ba-agent.md @@ -86,6 +86,7 @@ You run discovery and the interview gates for {{PROJECT}}. You never touch the ` | `skills/agent-permission-friction.md` | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing | | `skills/mendix-epics-api.md` | Working with the Mendix Epics board programmatically — creating/reading stories and epics, updating workflow state, or integrating BRDs with the portal | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/corpus-extraction-integrity.md` | Extracting structured requirements from a large delivered document corpus into per-scope knowledge-base files | | `skills/field-run.md` | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | | `skills/gate-check-file-locations.md` | gate-check.sh reports a Stage 0 file not found that plainly exists — ANALYSIS_BASE falls back to project root until Stage 1; move the file, do not debug the script | diff --git a/agents/gate-agent.md b/agents/gate-agent.md index 3b14dc3..1e7dbfa 100644 --- a/agents/gate-agent.md +++ b/agents/gate-agent.md @@ -70,6 +70,7 @@ own bug log before running anything you have not run here before. | `skills/improvement-register.md` | Any review pass that runs more than once — module-review, coherence, monkey, wiring-sweep: findings accumulate across runs, a per-run report cannot show a trend | | `skills/bug-submission-checklist.md` | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/sandbox-ab-tool-defect-probe.md` | Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model | | `skills/restart-sp-reopen-and-hang-detection.md` | Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load | | `skills/field-run.md` | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md index 2525bce..3385121 100644 --- a/agents/mdl-agent.md +++ b/agents/mdl-agent.md @@ -90,6 +90,7 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa | `skills/bug-submission-checklist.md` | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | | `skills/empty-widget-triage.md` | A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/sandbox-ab-tool-defect-probe.md` | Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model | | `skills/restart-sp-reopen-and-hang-detection.md` | Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load | | `skills/learned-sidebar-collapse-icons.md` | Building or auditing a collapsible sidebar nav — Atlas Core's collapsed state needs icons assigned per menu item or it silently clips label text | diff --git a/agents/review-agent.md b/agents/review-agent.md index 6eda50d..74b6f50 100644 --- a/agents/review-agent.md +++ b/agents/review-agent.md @@ -88,6 +88,7 @@ protects: you have no Write or Edit tool, and you never run `mxcli exec`. | `skills/bug-submission-checklist.md` | Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | | `skills/empty-widget-triage.md` | A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/anonymize-client-app-for-demo.md` | Turning a client-derived Mendix app into a clean, shareable demo with zero client fingerprint — branding, data, custom widgets | | `skills/field-run.md` | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | | `skills/full-harness-audit.md` | The user asks for a full end-to-end test, a click-through proof, or does-everything-actually-work — or you are unsure which harness skill applies; this one routes you | diff --git a/agents/test-agent.md b/agents/test-agent.md index 6b86acf..4d83c47 100644 --- a/agents/test-agent.md +++ b/agents/test-agent.md @@ -62,6 +62,7 @@ and `"DESCRIBE ..."` reads are always fine, and are how you ground every name yo | `skills/wiring-sweep.md` | Every module before it is called done — does every clickable thing actually do something; run AFTER the happy-path journey is green, never before | | `skills/upstream-feedback.md` | About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to | | `skills/empty-widget-triage.md` | A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause | +| `skills/doctor-triage.md` | doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same | | `skills/field-run.md` | Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds | | `skills/learned-local-db-confusion.md` | A runtime test reads/writes data that then is not there, or vice versa — three local Postgres instances can answer on this box; resolve the real port from the project's own compose file first | | `skills/full-harness-audit.md` | The user asks for a full end-to-end test, a click-through proof, or does-everything-actually-work — or you are unsure which harness skill applies; this one routes you | diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index 63a46d5..9a63104 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -181,6 +181,7 @@ mendix-epics-api skills/mendix-epics-api.md Working with the Mendix Epics board bug-submission-checklist skills/bug-submission-checklist.md Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable mdl,gate,review 5,6 ondemand diagnose upstream-feedback skills/upstream-feedback.md About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to all - ondemand diagnose empty-widget-triage skills/empty-widget-triage.md A page/grid/combobox renders empty (blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause mdl,test,review 5,6 ondemand diagnose +doctor-triage skills/doctor-triage.md doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same all - ondemand diagnose sandbox-ab-tool-defect-probe skills/sandbox-ab-tool-defect-probe.md Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model mdl,gate - ondemand diagnose restart-sp-reopen-and-hang-detection skills/restart-sp-reopen-and-hang-detection.md Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load mdl,gate - ondemand diagnose learned-sidebar-collapse-icons skills/learned-sidebar-collapse-icons.md Building or auditing a collapsible sidebar nav — Atlas Core's collapsed state needs icons assigned per menu item or it silently clips label text mdl 5 ondemand build/pages diff --git a/skills/doctor-triage.md b/skills/doctor-triage.md new file mode 100644 index 0000000..8e4d1f5 --- /dev/null +++ b/skills/doctor-triage.md @@ -0,0 +1,138 @@ +# doctor.sh is red — triage before you propose a fix + +**Applies to:** any mxcli project, on any platform — macOS, Windows/Git Bash, Linux, container, cloud. +**Purpose:** turn a red `bin/doctor.sh` line into the right response. Three different things produce +red — *my environment is wrong*, *the toolkit's own self-check is wrong*, *this line does not apply +in my lane* — and they get conflated, because from the report text they look identical. + +**Why this file exists (field incident, 2026-09-22).** Four people spent an afternoon in one Slack +thread on macOS setup. Three distinct failures were treated as one, and the first confident answer +from a knowledgeable human — *"install Studio Pro 10.24.18"* — could not have fixed any of them. +Meanwhile one colleague was correctly shipping with two FAILs open, and nobody else knew which two +were ignorable, so everyone else read all red as blocking. + +--- + +## Step 1 — Read the machine, not the message + +The report text is a hypothesis about your machine. **A wrong-platform binary, a wrong-architecture +binary and a missing binary all render the same way** — `mxbuild not found/executable` versus +`mxbuild exists but cannot run (exit 126)` are one line apart in the output and worlds apart in the +fix. Never propose a fix from the string alone. + +Run the full report against the project (not `--quick`), keep the output, then establish the facts +it was guessing at. Find the actual things; do not recall them: + +```bash +bin/doctor.sh 2>&1 | tee /tmp/doctor.txt # the full report, kept +uname -sm # OS + arch of the machine RUNNING this +ls -d /Applications/Mendix\ Studio\ Pro*.app 2>/dev/null # macOS: which installs actually exist +ls -d "/c/Program Files/Mendix"/* 2>/dev/null # Git Bash: same question +``` + +Then, for each install found, ask whether it carries a bundled `mx` at all — `/Contents/modeler/mx` +on macOS, `/modeler/mx.exe` on Windows — and for every binary the report named a path for, +ask what kind of file it is: + +```bash +file "" # Mach-O / PE / "ELF ... aarch64" — the whole answer +``` + +**Done when:** for every FAIL and WARN in the report you can state three things — the exact path +doctor resolved, whether that path exists, and what `file` says it is. N red lines, N complete +answers. A line answered from the report wording is not answered. + +## Step 2 — Put each red line in one of three classes + +| Class | The tell | Response | +|---|---|---| +| **A — my environment is wrong** | The path doctor printed is absent, or `file` says a format this OS/arch cannot run | Fix the environment, in the lane you are actually on (Step 4) | +| **B — the check itself is wrong** | The message describes the *checker* failing, not the thing checked. Anything of the shape "the gate cannot read…", "cannot resolve…", "no answer within N s" | Do not touch your machine yet. Reproduce, then log it (`upstream-feedback.md`, `bug-submission-checklist.md`) | +| **C — does not apply in this lane** | The capability is genuinely unavailable *and unnecessary* here, or is provided by a different tool than the one probed | Record with the reason; change nothing | + +**Show the failure — Class B misread as Class A.** Until `c0ea53c`, doctor's gate self-test copied +the model into a scratch dir under a renamed basename while copying `mprcontents/` verbatim beside +it. `mprcontents/` carries an internal record of the real basename, so mxbuild bailed *before* +writing any error file, and the self-test printed: + +``` + FAIL gate self-test: gate cannot read mxbuild's error file (baseline run) — a real error would go unseen +``` + +That string means **the gate is broken**. The gate was fine; the self-test was broken. It sent +people to audit their Studio Pro, their Java and their model. + +**Show the failure — Class A answered by inference.** A Mac reported the standalone mxbuild as +unable to run. The answer *"install Studio Pro 10.24.18"* arrived in about two minutes, and no +Studio Pro version on earth would have fixed it: that binary is a Linux ELF (Step 4). One `file` +call would have closed the question before the thread started. **An instant confident answer to a +setup failure is the signature of inference from the message text.** + +## Step 3 — Decide which reds block you, and say so for all of them + +Do not keep a list of ignorable FAILs; it goes stale the next time doctor grows a section. Derive it +per line, with three questions: + +1. **What does this check protect?** Doctor states the consequence in its own `note` lines — read + them; they name what stops working, not what is missing. +2. **Is that on the critical path of my next stage action?** Not of the project — of the next thing + you are about to do. +3. **Does another lane give me the same guarantee?** (Step 4 — a bundled `mx`, a container build, + `mxcli docker check`.) If yes, this red is an inconvenience, not a block. + +No to (2) or yes to (3) → not blocking. **One exception that always blocks, regardless:** anything +that would make the mxbuild gate *skip silently* or read a broken model as clean. A gate that cannot +fail is worse than no gate, because it is counted as evidence. + +**Done when:** the report's own counts are matched line for line. If it ends `N FAIL, M WARN`, your +note carries N+M lines, each marked `blocking` / `not-blocking, because …` / `waived, because …`. +A line you did not mention is not "fine" — it is undispositioned. This is exactly what the 2026-09-22 +thread lacked: two FAILs were correctly ignored by the one person who knew why, and nothing on disk +said which two. + +## Step 4 — Know which of the three toolchain lanes you are on + +Every mxbuild/`mx` red belongs to exactly one lane, and the fix is lane-specific. + +| Lane | Where the binary comes from | Runs on | What red means | +|---|---|---|---| +| **Studio Pro bundled** | the install's own `modeler/mx` (`Contents/modeler/mx` on macOS, `modeler/mx.exe` on Windows) | macOS, Windows | The install is missing, or is a build that ships no bundled `mx` — list the installs and look for the file | +| **Standalone CDN toolchain** | `mxcli setup mxbuild` / `doctor.sh --install`, cached under `~/.mxcli/mxbuild/` | **Linux only** — it is an ELF | On macOS or Windows this lane is simply unavailable; no Mendix version changes that | +| **Container** | the same Linux toolchain, inside a container | anywhere a container runtime runs | See the limitation below before believing this one | + +**macOS: Mendix 11 is a platform requirement, not a toolkit preference.** macOS Studio Pro was Beta +throughout 10.x and those builds ship **no** bundled `mx`; Mendix 11 is the first macOS build that +carries one. So on a Mac, the bundled-`mx` lane does not exist below 11 — and the CDN lane never +existed there at all. Verify by listing the installs and testing for the file (Step 1), **never** +from a remembered version number: version lists rot, and two people in the 2026-09-22 thread had the +toolkit itself checked out at two different paths. + +**The container lane is runtime-agnostic; doctor's probe is not.** Docker, Podman, Rancher Desktop +and colima all serve this lane. This team cannot use Docker Desktop for licensing reasons and runs +Podman — and `doctor.sh` currently probes only the `docker` command, so such a machine gets +`WARN docker is not installed` while the lane is in fact available. Read that WARN as Class C, +confirm the lane by running your own runtime's `info`, and leave it: a separate in-flight fix is +widening the probe. **Do not patch doctor from inside a triage.** + +## Step 5 — Check that your findings are about the machine you mean + +If the session is running in a VM, container or mounted sandbox, every binary finding is about +*that* environment. Compare the `uname -sm` from Step 1 against the host you are actually setting +up; if OS or arch differ, **none of your binary findings transfer** — a missing or `exec format +error` `mx` inside a Linux ARM64 VM mounting a Mac folder says nothing about what the Mac can run. +That is precisely what one colleague hit in the 2026-09-22 thread. + +**Done when:** every finding you report carries the OS/arch it was measured on, or is not reported. + +## Step 6 — Write the disposition down + +Put the Step 3 list — all N+M lines — in the project's `PROJECT.md` or session notes, with the +toolkit commit the report came from. That is the artifact the next person reads instead of asking +the thread. A red line classed **B** additionally goes upstream per `upstream-feedback.md`; a red +line classed **C** carries its reason, because an unexplained ignored FAIL is indistinguishable from +an unnoticed one. + +**Related:** `tool-output-is-not-ground-truth.md` (the general form: run a control before reporting +an absence) · `cloud-dev-environment.md` (the container lane as a working setup) · +`handoff-to-studio-pro.md` (when a human has to open the model) · +`mpr-corruption-and-sp-load-errors.md` (the model is broken, not the toolchain).