docs: add version-awareness skill and review checklist for version compatibility

- New skill .claude/skills/version-awareness.md teaches agents to check
  SHOW FEATURES before generating MDL
- Add "Version compatibility" section to PR review checklist (registry
  entry, executor pre-check, test directives, skill updates)
- Reference version-awareness skill in "Before Writing MDL" section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/version-awareness.md

@@ -0,0 +1,52 @@
+# Version Awareness
+
+This skill teaches you to check the project's Mendix version before generating MDL, so you never write syntax the project can't support.
+
+## Before Generating MDL
+
+Always check the project's Mendix version before writing MDL:
+
+```sql
+SHOW STATUS;           -- shows connected project version
+SHOW FEATURES;         -- shows all features with availability for this version
+SHOW FEATURES IN integration;  -- filter by area
+```
+
+If you're not connected to a project, query any version directly:
+
+```sql
+SHOW FEATURES FOR VERSION 10.24;
+```
+
+## Version-Conditional Patterns
+
+If a feature shows "No" in the Available column, **do not use it**. Use the documented workaround instead.
+
+Common version gates:
+
+| Feature | Requires | Workaround for older versions |
+|---------|----------|-------------------------------|
+| VIEW ENTITY | 10.18+ | Regular entity with microflow data source |
+| Page parameters | 11.0+ | Pass data via non-persistent entity |
+| REST query params | 11.0+ | Build query string manually in microflow |
+| DB runtime connection | 11.0+ | Hardcode connection in Database Connector config |
+| Design properties v3 | 11.0+ | Use Atlas v2 design properties |
+
+The executor will reject commands that target unavailable features with an actionable error — but checking upfront avoids wasted work.
+
+## Upgrade Planning
+
+When migrating to a newer version:
+
+```sql
+SHOW FEATURES ADDED SINCE 10.24;    -- what's new if upgrading from 10.24
+```
+
+## Checklist
+
+Before writing any MDL for a connected project:
+
+1. Run `SHOW STATUS` to confirm the Mendix version
+2. If using view entities, page parameters, REST clients, or database queries — run `SHOW FEATURES` to verify availability
+3. If a feature is unavailable, use the workaround pattern
+4. Run `mxcli check script.mdl -p app.mpr --references` to validate before execution

CLAUDE.md

@@ -240,6 +240,13 @@ New or modified MDL syntax must follow the design guidelines:
 - [ ] **LLM-friendly** — one example is sufficient for an LLM to generate correct variants
 - [ ] **Diff-friendly** — adding one property is a one-line diff
 
+### Version compatibility
+New features that depend on a specific Mendix version must be version-gated:
+- [ ] **Registry entry** — feature added to `sdk/versions/mendix-{9,10,11}.yaml` with correct `min_version`
+- [ ] **Executor pre-check** — `checkFeature()` called before BSON writes, with actionable error and hint
+- [ ] **Test coverage** — version-gated tests use `-- @version:` directives or `requireMinVersion()`
+- [ ] **Skill updated** — `.claude/skills/version-awareness.md` updated if the feature has a workaround for older versions
+
 ### Full-stack consistency for MDL features
 New MDL commands or language features must be wired through the full pipeline:
 - [ ] **Grammar** — rule added to `MDLParser.g4` (and `MDLLexer.g4` if new tokens)
@@ -353,6 +360,7 @@ Regenerate after modifying `MDLLexer.g4` or `MDLParser.g4`: `make grammar`. See
 ## IMPORTANT: Before Writing MDL Scripts or Working with Data
 
 **Read the relevant skill files FIRST before writing any MDL, seeding data, or doing database/import work:**
+- `.claude/skills/version-awareness.md` - **CHECK project version first** - Run `SHOW FEATURES` before using version-gated syntax
 - `.claude/skills/design-mdl-syntax.md` - **READ before designing new MDL syntax** - Design principles, decision framework, anti-patterns, checklist
 - `.claude/skills/write-microflows.md` - Microflow syntax, common mistakes, validation checklist
 - `.claude/skills/create-page.md` - Page/widget syntax reference