From 31bce204f6f8834683c167d660e17d04959daf8f Mon Sep 17 00:00:00 2001 From: engalar Date: Fri, 27 Mar 2026 18:53:39 +0800 Subject: [PATCH 1/2] docs: add mxbuild setup & mx tool skill for end users Addresses common agent mistakes when guiding users through mxbuild setup and mx tool usage, particularly incorrect mx create-project syntax and missing mxcli docker check as the preferred validation wrapper. --- .claude/skills/mendix/mxbuild-setup.md | 90 ++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 .claude/skills/mendix/mxbuild-setup.md diff --git a/.claude/skills/mendix/mxbuild-setup.md b/.claude/skills/mendix/mxbuild-setup.md new file mode 100644 index 0000000..a8e5bb0 --- /dev/null +++ b/.claude/skills/mendix/mxbuild-setup.md @@ -0,0 +1,90 @@ +# mxbuild Setup & mx Tool Skill + +This skill covers downloading mxbuild and using the `mx` tool for project validation and creation. + +## When to Use This Skill + +Use this when: +- The user needs to validate a project with `mx check` +- The user wants to create a blank Mendix project from scratch +- The user encounters "mx not found" or mxbuild-related errors +- You need to run `mx check` after modifying an MPR file via MDL + +## Setup: Download mxbuild + +mxbuild is downloaded once and cached at `~/.mxcli/mxbuild/{version}/`. + +```bash +# Auto-detect version from project (recommended) +./mxcli setup mxbuild -p app.mpr + +# Or specify version explicitly +./mxcli setup mxbuild --version 11.6.3 +``` + +After download, the `mx` binary is at: `~/.mxcli/mxbuild/{version}/modeler/mx` + +## Validate a Project + +**Preferred** — use the mxcli wrapper (auto-resolves mx binary): + +```bash +./mxcli docker check -p app.mpr +``` + +**Direct** — call mx binary explicitly: + +```bash +~/.mxcli/mxbuild/11.6.3/modeler/mx check /path/to/app.mpr +``` + +Reports errors (CE-codes), warnings, and deprecations. Non-zero exit on errors. + +## Create a Blank Project + +**IMPORTANT:** `mx create-project` uses `--app-name` and outputs `App.mpr` in the **current directory**. It does NOT accept an output path argument. + +```bash +# 1. Ensure mxbuild is available +./mxcli setup mxbuild --version 11.6.3 + +# 2. Create project directory and cd into it +mkdir /tmp/my-project && cd /tmp/my-project + +# 3. Create blank project (outputs App.mpr in current directory) +~/.mxcli/mxbuild/11.6.3/modeler/mx create-project --app-name MyApp +``` + +Takes ~29 seconds. Creates an MPR v2 project with standard module structure. + +**Caveat:** Blank projects have no demo users — login will fail until you configure security via MDL or Studio Pro. See `manage-security.md` for setting up demo users. + +## Common Workflow: Modify and Validate + +```bash +# 1. Download mxbuild (once) +./mxcli setup mxbuild -p app.mpr + +# 2. Make changes via MDL +./mxcli exec changes.mdl -p app.mpr + +# 3. Validate +./mxcli docker check -p app.mpr +``` + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| `mx: not found` | Run `./mxcli setup mxbuild -p app.mpr` | +| Wrong Mendix version | Use `--version` flag or check project version with `./mxcli -p app.mpr -c "SHOW VERSION"` | +| arm64 download fails | Some older versions lack arm64 builds; use Docker or Rosetta | +| `mx check` CE errors | See `cheatsheet-errors.md` for common error codes | +| `mx create-project` hangs | Ensure sufficient disk space; ~29s is normal | + +## Related Skills + +- [docker-workflow.md](./docker-workflow.md) — Full Docker build and run workflow +- [run-app.md](./run-app.md) — Running the app after validation +- [check-syntax.md](./check-syntax.md) — MDL syntax validation before `mx check` +- [manage-security.md](./manage-security.md) — Setting up demo users for blank projects From 260d18ddd9b149b941d42ee37db04db85da40b77 Mon Sep 17 00:00:00 2001 From: engalar Date: Mon, 30 Mar 2026 14:07:47 +0800 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20address=20review=20=E2=80=94=20remov?= =?UTF-8?q?e=20overlapping=20mxbuild-setup=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove mxbuild-setup.md (content already covered by docker-workflow.md) and fold the non-overlapping caveat about blank projects lacking demo users into docker-workflow.md. Fixes factual error: mxbuild-setup.md incorrectly claimed mx create-project does not accept --output-dir (verified it does in mx v11.6.4). --- .claude/skills/mendix/docker-workflow.md | 2 + .claude/skills/mendix/mxbuild-setup.md | 90 ------------------------ 2 files changed, 2 insertions(+), 90 deletions(-) delete mode 100644 .claude/skills/mendix/mxbuild-setup.md diff --git a/.claude/skills/mendix/docker-workflow.md b/.claude/skills/mendix/docker-workflow.md index e7e4ad2..8b39cef 100644 --- a/.claude/skills/mendix/docker-workflow.md +++ b/.claude/skills/mendix/docker-workflow.md @@ -65,6 +65,8 @@ mkdir -p /path/to/my-app The `mx create-project` command creates an MPR v2 project with the standard Mendix module structure. You can then use the Docker workflow to build and run it. +**Caveat:** Blank projects have no demo users — login will fail until you configure security via MDL or Studio Pro. See `manage-security.md` for setting up demo users. + ## Step-by-Step Workflow If you prefer more control, use the individual commands: diff --git a/.claude/skills/mendix/mxbuild-setup.md b/.claude/skills/mendix/mxbuild-setup.md deleted file mode 100644 index a8e5bb0..0000000 --- a/.claude/skills/mendix/mxbuild-setup.md +++ /dev/null @@ -1,90 +0,0 @@ -# mxbuild Setup & mx Tool Skill - -This skill covers downloading mxbuild and using the `mx` tool for project validation and creation. - -## When to Use This Skill - -Use this when: -- The user needs to validate a project with `mx check` -- The user wants to create a blank Mendix project from scratch -- The user encounters "mx not found" or mxbuild-related errors -- You need to run `mx check` after modifying an MPR file via MDL - -## Setup: Download mxbuild - -mxbuild is downloaded once and cached at `~/.mxcli/mxbuild/{version}/`. - -```bash -# Auto-detect version from project (recommended) -./mxcli setup mxbuild -p app.mpr - -# Or specify version explicitly -./mxcli setup mxbuild --version 11.6.3 -``` - -After download, the `mx` binary is at: `~/.mxcli/mxbuild/{version}/modeler/mx` - -## Validate a Project - -**Preferred** — use the mxcli wrapper (auto-resolves mx binary): - -```bash -./mxcli docker check -p app.mpr -``` - -**Direct** — call mx binary explicitly: - -```bash -~/.mxcli/mxbuild/11.6.3/modeler/mx check /path/to/app.mpr -``` - -Reports errors (CE-codes), warnings, and deprecations. Non-zero exit on errors. - -## Create a Blank Project - -**IMPORTANT:** `mx create-project` uses `--app-name` and outputs `App.mpr` in the **current directory**. It does NOT accept an output path argument. - -```bash -# 1. Ensure mxbuild is available -./mxcli setup mxbuild --version 11.6.3 - -# 2. Create project directory and cd into it -mkdir /tmp/my-project && cd /tmp/my-project - -# 3. Create blank project (outputs App.mpr in current directory) -~/.mxcli/mxbuild/11.6.3/modeler/mx create-project --app-name MyApp -``` - -Takes ~29 seconds. Creates an MPR v2 project with standard module structure. - -**Caveat:** Blank projects have no demo users — login will fail until you configure security via MDL or Studio Pro. See `manage-security.md` for setting up demo users. - -## Common Workflow: Modify and Validate - -```bash -# 1. Download mxbuild (once) -./mxcli setup mxbuild -p app.mpr - -# 2. Make changes via MDL -./mxcli exec changes.mdl -p app.mpr - -# 3. Validate -./mxcli docker check -p app.mpr -``` - -## Troubleshooting - -| Problem | Solution | -|---------|----------| -| `mx: not found` | Run `./mxcli setup mxbuild -p app.mpr` | -| Wrong Mendix version | Use `--version` flag or check project version with `./mxcli -p app.mpr -c "SHOW VERSION"` | -| arm64 download fails | Some older versions lack arm64 builds; use Docker or Rosetta | -| `mx check` CE errors | See `cheatsheet-errors.md` for common error codes | -| `mx create-project` hangs | Ensure sufficient disk space; ~29s is normal | - -## Related Skills - -- [docker-workflow.md](./docker-workflow.md) — Full Docker build and run workflow -- [run-app.md](./run-app.md) — Running the app after validation -- [check-syntax.md](./check-syntax.md) — MDL syntax validation before `mx check` -- [manage-security.md](./manage-security.md) — Setting up demo users for blank projects