diff --git a/docs/15-testing/agent-editor-test-cases.md b/docs/15-testing/agent-editor-test-cases.md
new file mode 100644
index 00000000..6b7fa86b
--- /dev/null
+++ b/docs/15-testing/agent-editor-test-cases.md
@@ -0,0 +1,1320 @@
+# Agent, Model, Knowledge Base & Consumed MCP Service Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Agents | Models | KBs | MCP Services |
+|-----|-----------|--------|--------|-----|--------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show agents;" > /tmp/show-agents.mdl
+  mxcli exec /tmp/show-agents.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N agents)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations (CREATE, DROP) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Dropped documents cannot be recovered — there is no undo.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW AGENTS
+
+### 1.1 List all agents
+
+```
+show agents;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Usage | Model | Tools | KBs`. Summary line `(N agents)`. Sorted alphabetically.
+
+### 1.2 List agents in a module
+
+```
+show agents in MyModule;
+```
+
+**Expected:** Only agents from `MyModule`. Same column format.
+
+### 1.3 Empty module
+
+```
+show agents in NonExistentModule;
+```
+
+**Expected:** Error or empty result with `(0 agents)`.
+
+---
+
+## 2. DESCRIBE AGENT
+
+### 2.1 Basic agent
+
+```
+describe agent MyModule.ChatAgent;
+```
+
+**Expected:** Full MDL output with all properties:
+
+```mdl
+create agent MyModule.ChatAgent (
+  UsageType: chat,
+  Description: 'A helpful chat agent',
+  Model: MyModule.GPT4o,
+  Entity: MyModule.ChatContext,
+  Variables: 'userInput',
+  MaxTokens: 4096,
+  ToolChoice: auto,
+  Temperature: 0.7,
+  TopP: 0.9,
+  SystemPrompt: $$You are a helpful assistant.$$,
+  UserPrompt: $$Answer the user's question: {userInput}$$
+);
+```
+
+### 2.2 Agent with tools
+
+```
+describe agent MyModule.ToolAgent;
+```
+
+**Expected:** MDL includes tool blocks:
+
+```mdl
+create agent MyModule.ToolAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$You can use tools.$$
+)
+tool FetchData {
+  ToolType: microflow,
+  Document: MyModule.ACT_FetchData,
+  Enabled: true,
+  Description: 'Fetches data from the database'
+}
+tool Summarize {
+  ToolType: microflow,
+  Document: MyModule.ACT_Summarize,
+  Enabled: true,
+  Description: 'Summarizes text input'
+};
+```
+
+### 2.3 Agent with MCP services
+
+```
+describe agent MyModule.McpAgent;
+```
+
+**Expected:** MDL includes MCP service blocks:
+
+```mdl
+create agent MyModule.McpAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Use external services.$$
+)
+mcp service MyModule.ExternalSvc {
+  Enabled: true,
+  Description: 'External data provider'
+};
+```
+
+### 2.4 Agent with knowledge bases
+
+```
+describe agent MyModule.KbAgent;
+```
+
+**Expected:** MDL includes knowledge base blocks:
+
+```mdl
+create agent MyModule.KbAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Use knowledge bases to answer.$$
+)
+knowledge base Docs {
+  Source: MyModule.DocumentationKB,
+  Collection: 'docs-collection-id',
+  MaxResults: 10,
+  Description: 'Product documentation',
+  Enabled: true
+};
+```
+
+### 2.5 Agent with all block types
+
+Find or create an agent with tools, MCP services, and knowledge bases. Verify all three block types appear in `describe` output.
+
+### 2.6 Dollar-quoted prompts
+
+Verify `SystemPrompt` and `UserPrompt` use `$$...$$` quoting. Prompts with single quotes, newlines, and special characters must survive roundtrip.
+
+### 2.7 Non-existent agent
+
+```
+describe agent Fake.Missing;
+```
+
+**Expected:** Error — agent not found.
+
+---
+
+## 3. CREATE AGENT
+
+### 3.1 Minimal agent
+
+```
+create agent MyModule.SimpleAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Hello.$$
+);
+```
+
+**Expected:** Agent created. `show agents` lists it. `describe` matches input.
+
+### 3.2 Full agent with all properties
+
+```
+create agent MyModule.FullAgent (
+  UsageType: chat,
+  Description: 'Full-featured test agent',
+  Model: MyModule.GPT4o,
+  Entity: MyModule.AgentContext,
+  Variables: 'input, context',
+  MaxTokens: 8192,
+  ToolChoice: auto,
+  Temperature: 0.5,
+  TopP: 0.95,
+  SystemPrompt: $$You are an expert assistant.
+You have access to tools and knowledge bases.$$,
+  UserPrompt: $$Process this request: {input}
+Context: {context}$$
+);
+```
+
+**Expected:** Agent created with all properties preserved. `describe` output matches.
+
+### 3.3 Agent with tool blocks
+
+```
+create agent MyModule.TooledAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Use tools when needed.$$
+)
+tool LookupCustomer {
+  ToolType: microflow,
+  Document: MyModule.ACT_LookupCustomer,
+  Enabled: true,
+  Description: 'Finds customer by name'
+}
+tool CreateOrder {
+  ToolType: microflow,
+  Document: MyModule.ACT_CreateOrder,
+  Enabled: true,
+  Description: 'Creates a new order'
+};
+```
+
+**Expected:** Agent created with two tools. `describe` shows both tool blocks.
+
+### 3.4 Agent with MCP service blocks
+
+```
+create agent MyModule.McpAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Connect to external services.$$
+)
+mcp service MyModule.WeatherSvc {
+  Enabled: true,
+  Description: 'Weather data provider'
+};
+```
+
+**Expected:** Agent created with MCP service reference. `describe` shows the block.
+
+### 3.5 Agent with knowledge base blocks
+
+```
+create agent MyModule.KbAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Answer from knowledge.$$
+)
+knowledge base FAQ {
+  Source: MyModule.FaqKB,
+  Collection: 'faq-collection',
+  MaxResults: 5,
+  Description: 'Frequently asked questions',
+  Enabled: true
+};
+```
+
+**Expected:** Agent created with knowledge base reference. `describe` shows the block.
+
+### 3.6 Agent with all block types
+
+```
+create agent MyModule.CompleteAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Full agent with everything.$$
+)
+tool Search {
+  ToolType: microflow,
+  Document: MyModule.ACT_Search,
+  Enabled: true,
+  Description: 'Search tool'
+}
+mcp service MyModule.ExternalAPI {
+  Enabled: true,
+  Description: 'External API service'
+}
+knowledge base Docs {
+  Source: MyModule.DocsKB,
+  Collection: 'docs-id',
+  MaxResults: 10,
+  Description: 'Documentation KB',
+  Enabled: true
+};
+```
+
+**Expected:** Agent created with tool, MCP service, and knowledge base blocks. `describe` shows all three.
+
+### 3.7 Auto-create module
+
+```
+create agent NewModule.Agent1 (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Test.$$
+);
+```
+
+**Expected:** `NewModule` auto-created if it does not exist. Agent created inside it.
+
+### 3.8 Model reference resolution
+
+```
+create agent MyModule.RefTest (
+  UsageType: chat,
+  Model: OtherModule.SomeModel,
+  SystemPrompt: $$Test.$$
+);
+```
+
+**Expected:** Resolves `OtherModule.SomeModel` to existing model document. Error if model not found.
+
+### 3.9 Entity reference resolution
+
+```
+create agent MyModule.EntityRef (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  Entity: MyModule.ChatSession,
+  SystemPrompt: $$Test.$$
+);
+```
+
+**Expected:** Resolves `MyModule.ChatSession` to existing entity. Error if entity not found.
+
+### 3.10 KB reference resolution in agent
+
+```
+create agent MyModule.KbRef (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Test.$$
+)
+knowledge base KB1 {
+  Source: MyModule.NonExistentKB,
+  Collection: 'id',
+  MaxResults: 5,
+  Description: 'Test',
+  Enabled: true
+};
+```
+
+**Expected:** Error — knowledge base `MyModule.NonExistentKB` not found.
+
+### 3.11 MCP service reference resolution in agent
+
+```
+create agent MyModule.McpRef (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Test.$$
+)
+mcp service MyModule.NonExistentSvc {
+  Enabled: true,
+  Description: 'Test'
+};
+```
+
+**Expected:** Error — consumed MCP service `MyModule.NonExistentSvc` not found.
+
+### 3.12 Duplicate agent
+
+```
+create agent MyModule.SimpleAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Duplicate.$$
+);
+```
+
+**Expected:** Error — agent already exists.
+
+---
+
+## 4. DROP AGENT
+
+### 4.1 Drop existing agent
+
+```
+drop agent MyModule.SimpleAgent;
+```
+
+**Expected:** Agent removed. `show agents` no longer lists it.
+
+### 4.2 Drop non-existent agent
+
+```
+drop agent MyModule.NonExistent;
+```
+
+**Expected:** Error — agent not found.
+
+---
+
+## 5. SHOW MODELS
+
+### 5.1 List all models
+
+```
+show models;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Provider | Key Constant | Display Name`. Summary line `(N models)`. Sorted alphabetically.
+
+### 5.2 List models in a module
+
+```
+show models in MyModule;
+```
+
+**Expected:** Only models from `MyModule`. Same column format.
+
+### 5.3 Empty module
+
+```
+show models in NonExistentModule;
+```
+
+**Expected:** Error or empty result with `(0 models)`.
+
+---
+
+## 6. DESCRIBE MODEL
+
+### 6.1 Basic model
+
+```
+describe model MyModule.GPT4o;
+```
+
+**Expected:** MDL output:
+
+```mdl
+create model MyModule.GPT4o (
+  Provider: MxCloudGenAI,
+  Key: MyModule.OpenAIKey,
+  DisplayName: 'GPT-4o'
+);
+```
+
+### 6.2 Model with all properties
+
+Find a model with additional properties beyond Provider, Key, and DisplayName. Verify all appear in `describe` output.
+
+### 6.3 Non-existent model
+
+```
+describe model Fake.Missing;
+```
+
+**Expected:** Error — model not found.
+
+---
+
+## 7. CREATE MODEL
+
+### 7.1 Minimal model (default provider)
+
+```
+create model MyModule.BasicModel (
+  Key: MyModule.ApiKey,
+  DisplayName: 'Basic Model'
+);
+```
+
+**Expected:** Model created. Provider defaults to `MxCloudGenAI`. `describe` matches.
+
+### 7.2 Explicit provider
+
+```
+create model MyModule.CustomModel (
+  Provider: MxCloudGenAI,
+  Key: MyModule.ApiKey,
+  DisplayName: 'Custom Model'
+);
+```
+
+**Expected:** Model created with explicit provider.
+
+### 7.3 Constant reference resolution
+
+```
+create model MyModule.RefModel (
+  Key: MyModule.NonExistentConst,
+  DisplayName: 'Test'
+);
+```
+
+**Expected:** Error — constant `MyModule.NonExistentConst` not found.
+
+### 7.4 Auto-create module
+
+```
+create model NewModule.Model1 (
+  Key: MyModule.ApiKey,
+  DisplayName: 'New Module Model'
+);
+```
+
+**Expected:** `NewModule` auto-created if it does not exist.
+
+### 7.5 Duplicate model
+
+```
+create model MyModule.BasicModel (
+  Key: MyModule.ApiKey,
+  DisplayName: 'Duplicate'
+);
+```
+
+**Expected:** Error — model already exists.
+
+---
+
+## 8. DROP MODEL
+
+### 8.1 Drop existing model
+
+```
+drop model MyModule.BasicModel;
+```
+
+**Expected:** Model removed. `show models` no longer lists it.
+
+### 8.2 Drop non-existent model
+
+```
+drop model MyModule.NonExistent;
+```
+
+**Expected:** Error — model not found.
+
+---
+
+## 9. SHOW KNOWLEDGE BASES
+
+### 9.1 List all knowledge bases
+
+```
+show knowledge bases;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Provider | Key Constant | Embedding Model`. Summary line `(N knowledge bases)`. Sorted alphabetically.
+
+### 9.2 List knowledge bases in a module
+
+```
+show knowledge bases in MyModule;
+```
+
+**Expected:** Only knowledge bases from `MyModule`. Same column format.
+
+### 9.3 Empty module
+
+```
+show knowledge bases in NonExistentModule;
+```
+
+**Expected:** Error or empty result with `(0 knowledge bases)`.
+
+---
+
+## 10. DESCRIBE KNOWLEDGE BASE
+
+### 10.1 Basic knowledge base
+
+```
+describe knowledge base MyModule.DocumentationKB;
+```
+
+**Expected:** MDL output:
+
+```mdl
+create knowledge base MyModule.DocumentationKB (
+  Provider: MxCloudGenAI,
+  Key: MyModule.KBKey,
+  ModelDisplayName: 'text-embedding-ada-002',
+  ModelName: 'text-embedding-ada-002'
+);
+```
+
+### 10.2 Knowledge base with all properties
+
+Find a knowledge base with additional properties. Verify all appear in `describe` output.
+
+### 10.3 Non-existent knowledge base
+
+```
+describe knowledge base Fake.Missing;
+```
+
+**Expected:** Error — knowledge base not found.
+
+---
+
+## 11. CREATE KNOWLEDGE BASE
+
+### 11.1 Minimal knowledge base
+
+```
+create knowledge base MyModule.TestKB (
+  Key: MyModule.KBKey,
+  ModelDisplayName: 'text-embedding-ada-002',
+  ModelName: 'text-embedding-ada-002'
+);
+```
+
+**Expected:** Knowledge base created. `describe` matches.
+
+### 11.2 Explicit provider
+
+```
+create knowledge base MyModule.FullKB (
+  Provider: MxCloudGenAI,
+  Key: MyModule.KBKey,
+  ModelDisplayName: 'text-embedding-3-small',
+  ModelName: 'text-embedding-3-small'
+);
+```
+
+**Expected:** Knowledge base created with explicit provider.
+
+### 11.3 Constant reference resolution
+
+```
+create knowledge base MyModule.BadKB (
+  Key: MyModule.NonExistentConst,
+  ModelDisplayName: 'test',
+  ModelName: 'test'
+);
+```
+
+**Expected:** Error — constant `MyModule.NonExistentConst` not found.
+
+### 11.4 Auto-create module
+
+```
+create knowledge base NewModule.KB1 (
+  Key: MyModule.KBKey,
+  ModelDisplayName: 'test',
+  ModelName: 'test'
+);
+```
+
+**Expected:** `NewModule` auto-created if it does not exist.
+
+### 11.5 Duplicate knowledge base
+
+```
+create knowledge base MyModule.TestKB (
+  Key: MyModule.KBKey,
+  ModelDisplayName: 'test',
+  ModelName: 'test'
+);
+```
+
+**Expected:** Error — knowledge base already exists.
+
+---
+
+## 12. DROP KNOWLEDGE BASE
+
+### 12.1 Drop existing knowledge base
+
+```
+drop knowledge base MyModule.TestKB;
+```
+
+**Expected:** Knowledge base removed. `show knowledge bases` no longer lists it.
+
+### 12.2 Drop non-existent knowledge base
+
+```
+drop knowledge base MyModule.NonExistent;
+```
+
+**Expected:** Error — knowledge base not found.
+
+---
+
+## 13. SHOW CONSUMED MCP SERVICES
+
+### 13.1 List all consumed MCP services
+
+```
+show consumed mcp services;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Protocol | Version | Timeout`. Summary line `(N consumed mcp services)`. Sorted alphabetically.
+
+### 13.2 List consumed MCP services in a module
+
+```
+show consumed mcp services in MyModule;
+```
+
+**Expected:** Only services from `MyModule`. Same column format.
+
+### 13.3 Empty module
+
+```
+show consumed mcp services in NonExistentModule;
+```
+
+**Expected:** Error or empty result with `(0 consumed mcp services)`.
+
+---
+
+## 14. DESCRIBE CONSUMED MCP SERVICE
+
+### 14.1 Basic consumed MCP service
+
+```
+describe consumed mcp service MyModule.ExternalSvc;
+```
+
+**Expected:** MDL output:
+
+```mdl
+create consumed mcp service MyModule.ExternalSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30,
+  Documentation: 'External data provider for weather information'
+);
+```
+
+### 14.2 Service with all properties
+
+Find a consumed MCP service with all available properties. Verify all appear in `describe` output.
+
+### 14.3 Non-existent consumed MCP service
+
+```
+describe consumed mcp service Fake.Missing;
+```
+
+**Expected:** Error — consumed MCP service not found.
+
+---
+
+## 15. CREATE CONSUMED MCP SERVICE
+
+### 15.1 Minimal consumed MCP service
+
+```
+create consumed mcp service MyModule.WeatherSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30
+);
+```
+
+**Expected:** Service created. `describe` matches.
+
+### 15.2 With documentation
+
+```
+create consumed mcp service MyModule.DataSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '2.0.0',
+  ConnectionTimeoutSeconds: 60,
+  Documentation: 'Provides access to external data sources'
+);
+```
+
+**Expected:** Service created with documentation. `describe` shows `Documentation` property.
+
+### 15.3 Auto-create module
+
+```
+create consumed mcp service NewModule.Svc1 (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30
+);
+```
+
+**Expected:** `NewModule` auto-created if it does not exist.
+
+### 15.4 Duplicate consumed MCP service
+
+```
+create consumed mcp service MyModule.WeatherSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30
+);
+```
+
+**Expected:** Error — consumed MCP service already exists.
+
+---
+
+## 16. DROP CONSUMED MCP SERVICE
+
+### 16.1 Drop existing consumed MCP service
+
+```
+drop consumed mcp service MyModule.WeatherSvc;
+```
+
+**Expected:** Service removed. `show consumed mcp services` no longer lists it.
+
+### 16.2 Drop non-existent consumed MCP service
+
+```
+drop consumed mcp service MyModule.NonExistent;
+```
+
+**Expected:** Error — consumed MCP service not found.
+
+---
+
+## 17. ROUNDTRIP
+
+Test that CREATE → DESCRIBE → CREATE (from output) produces identical results.
+
+### 17.1 Agent roundtrip
+
+```
+create agent RtTest.Agent1 (
+  UsageType: chat,
+  Description: 'Roundtrip test agent',
+  Model: RtTest.Model1,
+  MaxTokens: 4096,
+  Temperature: 0.7,
+  SystemPrompt: $$You are a test agent with 'quotes' and
+newlines in the prompt.$$,
+  UserPrompt: $$User said: {input}$$
+)
+tool Search {
+  ToolType: microflow,
+  Document: RtTest.ACT_Search,
+  Enabled: true,
+  Description: 'Search tool'
+}
+knowledge base Docs {
+  Source: RtTest.DocsKB,
+  Collection: 'docs-id',
+  MaxResults: 5,
+  Description: 'Documentation',
+  Enabled: true
+};
+```
+
+1. Run `describe agent RtTest.Agent1`
+2. Copy output
+3. Drop agent: `drop agent RtTest.Agent1`
+4. Execute copied MDL
+5. Run `describe` again
+
+**Expected:** Output identical between step 1 and step 5.
+
+### 17.2 Model roundtrip
+
+```
+create model RtTest.Model1 (
+  Provider: MxCloudGenAI,
+  Key: RtTest.ApiKey,
+  DisplayName: 'Test Model'
+);
+```
+
+1. `describe model RtTest.Model1`
+2. Drop: `drop model RtTest.Model1`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+### 17.3 Knowledge base roundtrip
+
+```
+create knowledge base RtTest.DocsKB (
+  Provider: MxCloudGenAI,
+  Key: RtTest.KBKey,
+  ModelDisplayName: 'text-embedding-ada-002',
+  ModelName: 'text-embedding-ada-002'
+);
+```
+
+1. `describe knowledge base RtTest.DocsKB`
+2. Drop: `drop knowledge base RtTest.DocsKB`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+### 17.4 Consumed MCP service roundtrip
+
+```
+create consumed mcp service RtTest.ExternalSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30,
+  Documentation: 'Test service'
+);
+```
+
+1. `describe consumed mcp service RtTest.ExternalSvc`
+2. Drop: `drop consumed mcp service RtTest.ExternalSvc`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+---
+
+## 18. MULTI-STEP WORKFLOWS
+
+### 18.1 Full agent stack creation
+
+Create all supporting documents, then an agent referencing them all.
+
+```
+-- Step 1: Create constant for API key
+create constant MyModule.AgentApiKey type String default 'sk-test-key';
+
+-- Step 2: Create model referencing the constant
+create model MyModule.TestModel (
+  Provider: MxCloudGenAI,
+  Key: MyModule.AgentApiKey,
+  DisplayName: 'Test GPT-4o'
+);
+
+-- Step 3: Create constant for KB key
+create constant MyModule.KBApiKey type String default 'kb-key';
+
+-- Step 4: Create knowledge base referencing the constant
+create knowledge base MyModule.TestKB (
+  Provider: MxCloudGenAI,
+  Key: MyModule.KBApiKey,
+  ModelDisplayName: 'text-embedding-ada-002',
+  ModelName: 'text-embedding-ada-002'
+);
+
+-- Step 5: Create consumed MCP service
+create consumed mcp service MyModule.TestMcpSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30,
+  Documentation: 'Test MCP service'
+);
+
+-- Step 6: Create agent referencing model, KB, and MCP service
+create agent MyModule.TestAgent (
+  UsageType: chat,
+  Description: 'Agent with all references',
+  Model: MyModule.TestModel,
+  MaxTokens: 4096,
+  Temperature: 0.7,
+  SystemPrompt: $$You have tools, knowledge, and services.$$
+)
+mcp service MyModule.TestMcpSvc {
+  Enabled: true,
+  Description: 'Test MCP'
+}
+knowledge base KB {
+  Source: MyModule.TestKB,
+  Collection: 'test-collection',
+  MaxResults: 10,
+  Description: 'Test knowledge base',
+  Enabled: true
+};
+
+-- Step 7: Verify
+describe agent MyModule.TestAgent;
+```
+
+**Expected:** All six create statements succeed. `describe` output shows model reference, MCP service block, and knowledge base block.
+
+### 18.2 Cross-module references
+
+```
+create constant ModA.Key type String default 'key';
+create model ModA.SharedModel (Key: ModA.Key, DisplayName: 'Shared');
+create agent ModB.CrossAgent (
+  UsageType: chat,
+  Model: ModA.SharedModel,
+  SystemPrompt: $$Cross-module test.$$
+);
+describe agent ModB.CrossAgent;
+```
+
+**Expected:** Agent in `ModB` references model in `ModA`. `describe` shows fully qualified model name.
+
+---
+
+## 19. FAILURE MODES & ERROR RECOVERY
+
+### 19.1 Not connected
+
+Run any command without `-p` flag or REPL session.
+
+**Expected:** Error — not connected to a project.
+
+### 19.2 Agent already exists
+
+```
+create agent MyModule.TestAgent (...);
+create agent MyModule.TestAgent (...);
+```
+
+**Expected:** Second create fails — agent already exists.
+
+### 19.3 Model not found during agent creation
+
+```
+create agent MyModule.BadAgent (
+  UsageType: chat,
+  Model: MyModule.NonExistentModel,
+  SystemPrompt: $$Test.$$
+);
+```
+
+**Expected:** Error — model `MyModule.NonExistentModel` not found.
+
+### 19.4 KB not found during agent creation
+
+```
+create agent MyModule.BadAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Test.$$
+)
+knowledge base KB1 {
+  Source: MyModule.NonExistentKB,
+  Collection: 'id',
+  MaxResults: 5,
+  Description: 'Test',
+  Enabled: true
+};
+```
+
+**Expected:** Error — knowledge base not found.
+
+### 19.5 MCP service not found during agent creation
+
+```
+create agent MyModule.BadAgent (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Test.$$
+)
+mcp service MyModule.NonExistentSvc {
+  Enabled: true,
+  Description: 'Test'
+};
+```
+
+**Expected:** Error — consumed MCP service not found.
+
+### 19.6 Constant not found during model creation
+
+```
+create model MyModule.BadModel (
+  Key: MyModule.FakeConst,
+  DisplayName: 'Bad'
+);
+```
+
+**Expected:** Error — constant not found.
+
+### 19.7 Constant not found during KB creation
+
+```
+create knowledge base MyModule.BadKB (
+  Key: MyModule.FakeConst,
+  ModelDisplayName: 'test',
+  ModelName: 'test'
+);
+```
+
+**Expected:** Error — constant not found.
+
+### 19.8 Drop model referenced by agent
+
+```
+drop model MyModule.TestModel;
+```
+
+**Expected:** Warning about agent references. Model dropped (agent may have dangling reference).
+
+---
+
+## 20. BOUNDARY & STRESS
+
+### 20.1 Agent with many tools (10+)
+
+Create an agent with 10+ tool blocks. Verify `describe` lists all tools.
+
+### 20.2 Agent with many knowledge bases (5+)
+
+Create an agent with 5+ knowledge base blocks. Verify `describe` lists all.
+
+### 20.3 Long dollar-quoted prompt
+
+Create an agent with a `SystemPrompt` exceeding 4000 characters. Verify `describe` preserves full text.
+
+### 20.4 Special characters in prompts
+
+```
+create agent MyModule.SpecialChars (
+  UsageType: chat,
+  Model: MyModule.GPT4o,
+  SystemPrompt: $$Prompt with 'single quotes', "double quotes",
+backslash \, dollar $, and unicode: café résumé$$
+);
+```
+
+**Expected:** All characters preserved in `describe` output.
+
+### 20.5 Long service documentation
+
+```
+create consumed mcp service MyModule.DocSvc (
+  ProtocolVersion: 2024-11-05,
+  Version: '1.0.0',
+  ConnectionTimeoutSeconds: 30,
+  Documentation: 'Very long documentation string...(1000+ chars)'
+);
+```
+
+**Expected:** Full documentation preserved in `describe`.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW AGENTS | x | x | x |
+| DESCRIBE AGENT | x | x | x |
+| CREATE AGENT | x | | |
+| DROP AGENT | x | | |
+| SHOW MODELS | x | x | x |
+| DESCRIBE MODEL | x | x | |
+| CREATE MODEL | x | | |
+| DROP MODEL | x | | |
+| SHOW KNOWLEDGE BASES | x | x | x |
+| DESCRIBE KNOWLEDGE BASE | x | x | |
+| CREATE KNOWLEDGE BASE | x | | |
+| DROP KNOWLEDGE BASE | x | | |
+| SHOW CONSUMED MCP SERVICES | x | x | x |
+| DESCRIBE CONSUMED MCP SERVICE | x | x | |
+| CREATE CONSUMED MCP SERVICE | x | | |
+| DROP CONSUMED MCP SERVICE | x | | |
+
+Read operations tested on all projects. Write operations on copies of one project.
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW AGENTS | Mock tests | |
+| 2. DESCRIBE AGENT | Mock tests | All block types |
+| 3. CREATE AGENT | Mock + roundtrip | Reference resolution |
+| 4. DROP AGENT | Mock tests | |
+| 5. SHOW MODELS | Mock tests | |
+| 6. DESCRIBE MODEL | Mock tests | |
+| 7. CREATE MODEL | Mock tests | Constant resolution |
+| 8. DROP MODEL | Mock tests | |
+| 9. SHOW KNOWLEDGE BASES | Mock tests | |
+| 10. DESCRIBE KNOWLEDGE BASE | Mock tests | |
+| 11. CREATE KNOWLEDGE BASE | Mock tests | Constant resolution |
+| 12. DROP KNOWLEDGE BASE | Mock tests | |
+| 13. SHOW CONSUMED MCP SERVICES | Mock tests | |
+| 14. DESCRIBE CONSUMED MCP SERVICE | Mock tests | |
+| 15. CREATE CONSUMED MCP SERVICE | Mock tests | |
+| 16. DROP CONSUMED MCP SERVICE | Mock tests | |
+| 17. Roundtrip | Roundtrip tests | Complex agents |
+| 18. Multi-step | | All manual |
+| 19. Failure modes | Partial | Edge cases |
+| 20. Boundary | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW AGENTS | List all | | | | |
+| 1.2 | SHOW AGENTS | Filter by module | | | | |
+| 1.3 | SHOW AGENTS | Empty module | | | | |
+| 2.1 | DESCRIBE AGENT | Basic | | | | |
+| 2.2 | DESCRIBE AGENT | With tools | | | | |
+| 2.3 | DESCRIBE AGENT | With MCP services | | | | |
+| 2.4 | DESCRIBE AGENT | With KBs | | | | |
+| 2.5 | DESCRIBE AGENT | All block types | | | | |
+| 2.6 | DESCRIBE AGENT | Dollar-quoted prompts | | | | |
+| 2.7 | DESCRIBE AGENT | Not found | | | | |
+| 3.1 | CREATE AGENT | Minimal | | | | |
+| 3.2 | CREATE AGENT | Full properties | | | | |
+| 3.3 | CREATE AGENT | With tools | | | | |
+| 3.4 | CREATE AGENT | With MCP services | | | | |
+| 3.5 | CREATE AGENT | With KBs | | | | |
+| 3.6 | CREATE AGENT | All block types | | | | |
+| 3.7 | CREATE AGENT | Auto-create module | | | | |
+| 3.8 | CREATE AGENT | Model reference | | | | |
+| 3.9 | CREATE AGENT | Entity reference | | | | |
+| 3.10 | CREATE AGENT | KB not found | | | | |
+| 3.11 | CREATE AGENT | MCP not found | | | | |
+| 3.12 | CREATE AGENT | Duplicate error | | | | |
+| 4.1 | DROP AGENT | Existing | | | | |
+| 4.2 | DROP AGENT | Non-existent | | | | |
+| 5.1 | SHOW MODELS | List all | | | | |
+| 5.2 | SHOW MODELS | Filter by module | | | | |
+| 5.3 | SHOW MODELS | Empty module | | | | |
+| 6.1 | DESCRIBE MODEL | Basic | | | | |
+| 6.2 | DESCRIBE MODEL | All properties | | | | |
+| 6.3 | DESCRIBE MODEL | Not found | | | | |
+| 7.1 | CREATE MODEL | Minimal (default provider) | | | | |
+| 7.2 | CREATE MODEL | Explicit provider | | | | |
+| 7.3 | CREATE MODEL | Constant not found | | | | |
+| 7.4 | CREATE MODEL | Auto-create module | | | | |
+| 7.5 | CREATE MODEL | Duplicate error | | | | |
+| 8.1 | DROP MODEL | Existing | | | | |
+| 8.2 | DROP MODEL | Non-existent | | | | |
+| 9.1 | SHOW KBS | List all | | | | |
+| 9.2 | SHOW KBS | Filter by module | | | | |
+| 9.3 | SHOW KBS | Empty module | | | | |
+| 10.1 | DESCRIBE KB | Basic | | | | |
+| 10.2 | DESCRIBE KB | All properties | | | | |
+| 10.3 | DESCRIBE KB | Not found | | | | |
+| 11.1 | CREATE KB | Minimal | | | | |
+| 11.2 | CREATE KB | Explicit provider | | | | |
+| 11.3 | CREATE KB | Constant not found | | | | |
+| 11.4 | CREATE KB | Auto-create module | | | | |
+| 11.5 | CREATE KB | Duplicate error | | | | |
+| 12.1 | DROP KB | Existing | | | | |
+| 12.2 | DROP KB | Non-existent | | | | |
+| 13.1 | SHOW MCP | List all | | | | |
+| 13.2 | SHOW MCP | Filter by module | | | | |
+| 13.3 | SHOW MCP | Empty module | | | | |
+| 14.1 | DESCRIBE MCP | Basic | | | | |
+| 14.2 | DESCRIBE MCP | All properties | | | | |
+| 14.3 | DESCRIBE MCP | Not found | | | | |
+| 15.1 | CREATE MCP | Minimal | | | | |
+| 15.2 | CREATE MCP | With documentation | | | | |
+| 15.3 | CREATE MCP | Auto-create module | | | | |
+| 15.4 | CREATE MCP | Duplicate error | | | | |
+| 16.1 | DROP MCP | Existing | | | | |
+| 16.2 | DROP MCP | Non-existent | | | | |
+| 17.1 | ROUNDTRIP | Agent | | | | |
+| 17.2 | ROUNDTRIP | Model | | | | |
+| 17.3 | ROUNDTRIP | Knowledge base | | | | |
+| 17.4 | ROUNDTRIP | Consumed MCP service | | | | |
+| 18.1 | MULTI-STEP | Full agent stack | | | | |
+| 18.2 | MULTI-STEP | Cross-module refs | | | | |
+| 19.1 | FAILURE | Not connected | | | | |
+| 19.2 | FAILURE | Already exists | | | | |
+| 19.3 | FAILURE | Model not found | | | | |
+| 19.4 | FAILURE | KB not found | | | | |
+| 19.5 | FAILURE | MCP not found | | | | |
+| 19.6 | FAILURE | Constant not found (model) | | | | |
+| 19.7 | FAILURE | Constant not found (KB) | | | | |
+| 19.8 | FAILURE | Drop referenced model | | | | |
+| 20.1 | BOUNDARY | Many tools | | | | |
+| 20.2 | BOUNDARY | Many KBs | | | | |
+| 20.3 | BOUNDARY | Long prompt | | | | |
+| 20.4 | BOUNDARY | Special characters | | | | |
+| 20.5 | BOUNDARY | Long documentation | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/business-event-test-cases.md b/docs/15-testing/business-event-test-cases.md
new file mode 100644
index 00000000..5bd04e00
--- /dev/null
+++ b/docs/15-testing/business-event-test-cases.md
@@ -0,0 +1,576 @@
+# Business Event Service Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Business Event Services |
+|-----|-----------|------------------------|
+| Lato Enquiry Management | 11.4.0 | — |
+| Evora - Factory Management | 10.24.15 | — |
+| Lato Product Inventory | 11.2.0 | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show business event services;" > /tmp/show-bes.mdl
+  mxcli exec /tmp/show-bes.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N business event services)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations (CREATE, DROP) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Dropped services cannot be recovered — there is no undo.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW BUSINESS EVENT SERVICES
+
+### 1.1 List all services
+
+```
+show business event services;
+```
+
+**Expected:** Table with columns `Module | QualifiedName | Service | Messages | Publish | Subscribe`. Summary line `(N business event services)`. Sorted alphabetically.
+
+### 1.2 Filter by module
+
+```
+show business event services in MyModule;
+```
+
+**Expected:** Only services from `MyModule`. Same column format.
+
+### 1.3 Empty result
+
+```
+show business event services in NonExistentModule;
+```
+
+**Expected:** `No business event services found.`
+
+---
+
+## 2. SHOW BUSINESS EVENTS
+
+### 2.1 List all business events
+
+```
+show business events;
+```
+
+**Expected:** Table with columns `Service | Message | Operation | Entity | Attributes`. `Operation` values are `PUBLISH` or `SUBSCRIBE`. Summary line `(N business events)`.
+
+### 2.2 Filter by module
+
+```
+show business events in MyModule;
+```
+
+**Expected:** Only events from `MyModule`. Same column format.
+
+### 2.3 Empty module
+
+```
+show business events in NonExistentModule;
+```
+
+**Expected:** Empty result or `No business events found.`
+
+---
+
+## 3. DESCRIBE BUSINESS EVENT SERVICE
+
+### 3.1 Service with publish message
+
+```
+describe business event service MyModule.OrderEvents;
+```
+
+**Expected:** Full MDL output:
+```
+create business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order'
+  message OrderCreated (
+    OrderId: Long,
+    CustomerName: String,
+    Total: Decimal
+  ) publish entity MyModule.OrderCreatedEvent
+/
+```
+
+### 3.2 Service with subscribe message
+
+```
+describe business event service MyModule.PaymentEvents;
+```
+
+**Expected:** MDL includes `subscribe` keyword with entity and microflow references:
+```
+create business event service MyModule.PaymentEvents
+  event_name_prefix 'com.example.payment'
+  message PaymentReceived (
+    PaymentId: Long,
+    Amount: Decimal,
+    Currency: String
+  ) subscribe entity MyModule.PaymentReceivedEvent microflow MyModule.OnPaymentReceived
+/
+```
+
+### 3.3 Service with multiple messages
+
+```
+describe business event service MyModule.InventoryEvents;
+```
+
+**Expected:** Multiple `message` blocks in output. Each has its own attribute list, operation keyword, and entity reference.
+
+### 3.4 All attribute types
+
+Verify described output includes attributes of each supported type:
+
+| Type | Example |
+|------|---------|
+| Long | `OrderId: Long` |
+| String | `Name: String` |
+| Integer | `Count: Integer` |
+| Boolean | `IsActive: Boolean` |
+| DateTime | `Timestamp: DateTime` |
+| Decimal | `Amount: Decimal` |
+
+### 3.5 Non-existent service
+
+```
+describe business event service MyModule.Fake;
+```
+
+**Expected:** Error — service not found.
+
+---
+
+## 4. CREATE BUSINESS EVENT SERVICE
+
+> **Note:** The `event_name_prefix` and `message` keywords cause parse errors in the current build. The CREATE BUSINESS EVENT SERVICE grammar may not be fully implemented. Tests in this section may fail at the parser level rather than at execution.
+
+### 4.1 Minimal publish service
+
+```
+create business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order'
+  message OrderCreated (
+    OrderId: Long,
+    Description: String
+  ) publish entity MyModule.OrderCreatedEvent;
+```
+
+**Expected:** Service created. `describe business event service MyModule.OrderEvents` matches input.
+
+### 4.2 Subscribe service with microflow
+
+```
+create business event service MyModule.PaymentEvents
+  event_name_prefix 'com.example.payment'
+  message PaymentReceived (
+    PaymentId: Long,
+    Amount: Decimal,
+    Currency: String
+  ) subscribe entity MyModule.PaymentReceivedEvent microflow MyModule.OnPaymentReceived;
+```
+
+**Expected:** Service created. `describe` shows `subscribe` keyword, entity, and microflow references.
+
+### 4.3 Multiple messages
+
+```
+create business event service MyModule.InventoryEvents
+  event_name_prefix 'com.example.inventory'
+  message StockUpdated (
+    ProductId: Long,
+    NewQuantity: Integer
+  ) publish entity MyModule.StockUpdatedEvent
+  message StockDepleted (
+    ProductId: Long,
+    WarehouseId: String
+  ) subscribe entity MyModule.StockDepletedEvent microflow MyModule.OnStockDepleted;
+```
+
+**Expected:** Service created with two messages. `describe` shows both message blocks.
+
+### 4.4 All attribute types
+
+```
+create business event service MyModule.TypeTest
+  event_name_prefix 'com.example.typetest'
+  message AllTypes (
+    Id: Long,
+    Name: String,
+    Count: Integer,
+    Active: Boolean,
+    Timestamp: DateTime,
+    Amount: Decimal
+  ) publish entity MyModule.AllTypesEvent;
+```
+
+**Expected:** Service created. `describe` preserves all six attribute types.
+
+### 4.5 `create or replace` variant
+
+```
+create or replace business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order.v2'
+  message OrderCreatedV2 (
+    OrderId: Long,
+    Description: String,
+    Priority: Integer
+  ) publish entity MyModule.OrderCreatedV2Event;
+```
+
+**Expected:** Drops existing service and recreates. `describe` shows updated prefix and message.
+
+### 4.6 `in folder` clause
+
+```
+create business event service MyModule.FolderTest
+  event_name_prefix 'com.example.foldertest'
+  in folder 'Events/Inbound'
+  message TestMsg (
+    Value: String
+  ) publish entity MyModule.TestMsgEvent;
+```
+
+**Expected:** Service created in specified folder. Folder auto-created if missing.
+
+### 4.7 Export level defaults to Hidden
+
+```
+create business event service MyModule.HiddenCheck
+  event_name_prefix 'com.example.hidden'
+  message Msg (
+    X: Integer
+  ) publish entity MyModule.HiddenCheckEvent;
+```
+
+**Expected:** Service created. Export level defaults to `Hidden`. Verify via `describe` output or model inspection.
+
+### 4.8 Duplicate service (without `or replace`)
+
+```
+create business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order'
+  message OrderCreated (
+    OrderId: Long
+  ) publish entity MyModule.OrderCreatedEvent;
+```
+
+**Expected:** Error — service already exists.
+
+---
+
+## 5. DROP BUSINESS EVENT SERVICE
+
+### 5.1 Drop existing service
+
+```
+drop business event service MyModule.OrderEvents;
+```
+
+**Expected:** Service removed. `describe business event service MyModule.OrderEvents` returns error.
+
+### 5.2 Drop non-existent service
+
+```
+drop business event service MyModule.Fake;
+```
+
+**Expected:** Error — service not found.
+
+---
+
+## 6. ROUNDTRIP
+
+### 6.1 Publish service roundtrip
+
+```
+create business event service RtTest.Events
+  event_name_prefix 'com.example.rt'
+  message Created (
+    Id: Long,
+    Name: String,
+    Amount: Decimal
+  ) publish entity RtTest.CreatedEvent;
+```
+
+1. Run `describe business event service RtTest.Events`
+2. Copy output
+3. Drop: `drop business event service RtTest.Events`
+4. Execute copied MDL
+5. Run `describe` again
+
+**Expected:** Output identical between step 1 and step 5.
+
+### 6.2 Subscribe service roundtrip
+
+```
+create business event service RtTest.SubEvents
+  event_name_prefix 'com.example.rtsub'
+  message Received (
+    PaymentId: Long,
+    Status: String
+  ) subscribe entity RtTest.ReceivedEvent microflow RtTest.OnReceived;
+```
+
+1. `describe business event service RtTest.SubEvents`
+2. Drop: `drop business event service RtTest.SubEvents`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+---
+
+## 7. MULTI-STEP WORKFLOWS
+
+### 7.1 Create entity → create publish service → verify events
+
+```
+create persistent entity MyModule.InvoiceCreatedEvent (
+  InvoiceId: Long,
+  CustomerName: String,
+  TotalAmount: Decimal
+);
+
+create business event service MyModule.InvoiceEvents
+  event_name_prefix 'com.example.invoice'
+  message InvoiceCreated (
+    InvoiceId: Long,
+    CustomerName: String,
+    TotalAmount: Decimal
+  ) publish entity MyModule.InvoiceCreatedEvent;
+
+show business events in MyModule;
+```
+
+**Expected:** All statements succeed. `show business events` lists `InvoiceCreated` with operation `PUBLISH` and entity `MyModule.InvoiceCreatedEvent`.
+
+### 7.2 Create entity → create subscribe service → verify events
+
+```
+create persistent entity MyModule.ShipmentReceivedEvent (
+  ShipmentId: Long,
+  Carrier: String
+);
+
+create business event service MyModule.ShipmentEvents
+  event_name_prefix 'com.example.shipment'
+  message ShipmentReceived (
+    ShipmentId: Long,
+    Carrier: String
+  ) subscribe entity MyModule.ShipmentReceivedEvent microflow MyModule.OnShipmentReceived;
+
+show business events in MyModule;
+```
+
+**Expected:** `show business events` lists `ShipmentReceived` with operation `SUBSCRIBE`.
+
+### 7.3 Create → replace → verify
+
+```
+create business event service MyModule.Lifecycle
+  event_name_prefix 'com.example.lc.v1'
+  message Ping (
+    Seq: Integer
+  ) publish entity MyModule.PingEvent;
+
+create or replace business event service MyModule.Lifecycle
+  event_name_prefix 'com.example.lc.v2'
+  message Ping (
+    Seq: Integer,
+    Timestamp: DateTime
+  ) publish entity MyModule.PingEvent;
+
+describe business event service MyModule.Lifecycle;
+```
+
+**Expected:** Final `describe` shows v2 prefix and `Timestamp` attribute.
+
+---
+
+## 8. FAILURE MODES & ERROR RECOVERY
+
+### 8.1 Not connected to project
+
+```
+show business event services;
+```
+
+(Run without `-p` flag or before opening a project.)
+
+**Expected:** Error — not connected to a project.
+
+### 8.2 Service not found
+
+```
+describe business event service MyModule.DoesNotExist;
+```
+
+**Expected:** Error — service not found.
+
+### 8.3 Service already exists
+
+```
+create business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order'
+  message Msg (X: Integer) publish entity MyModule.MsgEvent;
+create business event service MyModule.OrderEvents
+  event_name_prefix 'com.example.order'
+  message Msg (X: Integer) publish entity MyModule.MsgEvent;
+```
+
+**Expected:** First succeeds. Second returns error — already exists.
+
+### 8.4 Module not found
+
+```
+show business event services in FakeModule;
+```
+
+**Expected:** `No business event services found.` or error — module not found.
+
+### 8.5 Missing entity reference
+
+```
+create business event service MyModule.BadRef
+  event_name_prefix 'com.example.badref'
+  message Msg (X: Integer) publish entity MyModule.NonExistentEntity;
+```
+
+**Expected:** Error — entity not found.
+
+### 8.6 Invalid attribute type
+
+```
+create business event service MyModule.BadType
+  event_name_prefix 'com.example.badtype'
+  message Msg (X: InvalidType) publish entity MyModule.SomeEvent;
+```
+
+**Expected:** Error — unknown type. No service created.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW BUSINESS EVENT SERVICES | x | x | x |
+| SHOW BUSINESS EVENTS | x | x | x |
+| DESCRIBE BUSINESS EVENT SERVICE | x | x | |
+| CREATE BUSINESS EVENT SERVICE | x | | |
+| DROP BUSINESS EVENT SERVICE | x | | |
+
+Read operations tested on all projects. Write operations on copies of one project.
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW BUSINESS EVENT SERVICES | Mock tests | |
+| 2. SHOW BUSINESS EVENTS | Mock tests | |
+| 3. DESCRIBE BUSINESS EVENT SERVICE | Mock tests | |
+| 4. CREATE BUSINESS EVENT SERVICE | Mock tests | Folder, export level |
+| 5. DROP BUSINESS EVENT SERVICE | Mock tests | |
+| 6. Roundtrip | Roundtrip tests | Complex services |
+| 7. Multi-step | | All manual |
+| 8. Failure modes | Partial | Edge cases |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW BE SERVICES | List all | | | | |
+| 1.2 | SHOW BE SERVICES | Filter by module | | | | |
+| 1.3 | SHOW BE SERVICES | Empty result | | | | |
+| 2.1 | SHOW BE | List all | | | | |
+| 2.2 | SHOW BE | Filter by module | | | | |
+| 2.3 | SHOW BE | Empty module | | | | |
+| 3.1 | DESCRIBE BE SERVICE | Publish message | | | | |
+| 3.2 | DESCRIBE BE SERVICE | Subscribe message | | | | |
+| 3.3 | DESCRIBE BE SERVICE | Multiple messages | | | | |
+| 3.4 | DESCRIBE BE SERVICE | All attribute types | | | | |
+| 3.5 | DESCRIBE BE SERVICE | Not found | | | | |
+| 4.1 | CREATE BE SERVICE | Minimal publish | | | | |
+| 4.2 | CREATE BE SERVICE | Subscribe with microflow | | | | |
+| 4.3 | CREATE BE SERVICE | Multiple messages | | | | |
+| 4.4 | CREATE BE SERVICE | All attribute types | | | | |
+| 4.5 | CREATE BE SERVICE | create or replace | | | | |
+| 4.6 | CREATE BE SERVICE | in folder | | | | |
+| 4.7 | CREATE BE SERVICE | Export level hidden | | | | |
+| 4.8 | CREATE BE SERVICE | Duplicate error | | | | |
+| 5.1 | DROP BE SERVICE | Existing | | | | |
+| 5.2 | DROP BE SERVICE | Non-existent | | | | |
+| 6.1 | ROUNDTRIP | Publish service | | | | |
+| 6.2 | ROUNDTRIP | Subscribe service | | | | |
+| 7.1 | MULTI-STEP | Entity + publish + verify | | | | |
+| 7.2 | MULTI-STEP | Entity + subscribe + verify | | | | |
+| 7.3 | MULTI-STEP | Create + replace + verify | | | | |
+| 8.1 | FAILURE | Not connected | | | | |
+| 8.2 | FAILURE | Service not found | | | | |
+| 8.3 | FAILURE | Already exists | | | | |
+| 8.4 | FAILURE | Module not found | | | | |
+| 8.5 | FAILURE | Missing entity ref | | | | |
+| 8.6 | FAILURE | Invalid attribute type | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/catalog-test-cases.md b/docs/15-testing/catalog-test-cases.md
new file mode 100644
index 00000000..b7c05f91
--- /dev/null
+++ b/docs/15-testing/catalog-test-cases.md
@@ -0,0 +1,584 @@
+# Catalog & Code Navigation Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Modules | Entities | Microflows |
+|-----|-----------|---------|----------|------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 11.8.0 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Build catalog (required for most tests)
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+Then inside REPL:
+```
+refresh catalog full source;
+```
+
+This builds the complete catalog with all tables including activities, widgets, refs, strings, and MDL source.
+
+> **IMPORTANT:** Multi-step tests (§13) create and drop entities. Always run these against a **copy** of the project folder.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. REFRESH CATALOG
+
+### 1.1 Fast mode (default)
+
+```
+refresh catalog;
+```
+
+**Expected:** Builds core tables (modules, entities, attributes, microflows, etc.). Output shows per-table row count + "Catalog ready (Xs)".
+
+### 1.2 Full mode
+
+```
+refresh catalog full;
+```
+
+**Expected:** Adds activities, widgets, refs, strings, permissions tables.
+
+### 1.3 Full with source
+
+```
+refresh catalog full source;
+```
+
+**Expected:** Adds source table (MDL text for each document).
+
+### 1.4 Force rebuild
+
+```
+refresh catalog force;
+```
+
+**Expected:** Ignores cached catalog, rebuilds from scratch.
+
+### 1.5 Background build
+
+```
+refresh catalog background;
+```
+
+**Expected:** Returns immediately; catalog built in background goroutine.
+
+### 1.6 Caching behavior
+
+1. Run `refresh catalog full;`
+2. Exit and re-open same project
+3. Run `refresh catalog;`
+
+**Expected:** Second run uses cached `.mxcli/catalog.db` (fast — no rebuild needed).
+
+---
+
+## 2. SHOW CATALOG TABLES
+
+### 2.1 List tables
+
+```
+show catalog tables;
+```
+
+**Expected:** Table with columns `Table | Count`. Lists 35+ tables including: modules, entities, attributes, microflows, nanoflows, pages, snippets, layouts, enumerations, activities, widgets, xpath_expressions, refs, permissions, workflows, odata_clients, odata_services, etc.
+
+### 2.2 Tables require appropriate build mode
+
+Verify tables marked as full-only show 0 rows if only fast catalog was built.
+
+---
+
+## 3. SHOW CATALOG STATUS
+
+### 3.1 Catalog status
+
+```
+show catalog status;
+```
+
+**Expected:** Cache path, build mode, build time, build duration, Mendix version, validity status.
+
+---
+
+## 4. DESCRIBE CATALOG TABLE
+
+### 4.1 Describe entities table
+
+```
+describe catalog.entities;
+```
+
+**Expected:** Column names, types, PK markers + required refresh mode.
+
+### 4.2 Describe activities table
+
+```
+describe catalog.activities;
+```
+
+**Expected:** Schema for full-mode table.
+
+---
+
+## 5. SELECT FROM CATALOG
+
+### 5.1 Basic select
+
+```
+select * from catalog.entities where ModuleName = 'Administration';
+```
+
+**Expected:** Row count + table result with entity data from Administration module.
+
+### 5.2 Select with multiple conditions
+
+```
+select QualifiedName, EntityType from catalog.entities where EntityType = 'PERSISTENT' and ModuleName = 'FactoryManagement';
+```
+
+**Expected:** Filtered results.
+
+### 5.3 Aggregate query
+
+```
+select ModuleName, count(*) as cnt from catalog.entities group by ModuleName order by cnt desc;
+```
+
+**Expected:** Entity counts per module.
+
+### 5.4 Join across tables
+
+```
+select e.QualifiedName, count(a.Name) as attrs
+from catalog.entities e
+join catalog.attributes a on e.QualifiedName = a.EntityQualifiedName
+group by e.QualifiedName
+having attrs > 10;
+```
+
+**Expected:** Entities with more than 10 attributes.
+
+### 5.5 Full-only table without full build
+
+```
+refresh catalog;
+select * from catalog.activities;
+```
+
+**Expected:** Warning about insufficient build mode. Empty or error.
+
+### 5.6 FTS search on strings table
+
+```
+select * from catalog.strings where strings match 'factory';
+```
+
+**Expected:** Full-text search results with matching snippets. (Note: use a term present in your test project; `'factory'` works with Evora Factory Management.)
+
+---
+
+## 6. SEARCH
+
+### 6.1 Basic search
+
+```
+search 'customer';
+```
+
+**Expected:** String matches with columns: `QualifiedName | ObjectType | Match | StringContext | ModuleName`. Match shows `>>>...<<<` highlighting.
+
+### 6.2 Search with special characters
+
+```
+search 'user.name';
+```
+
+**Expected:** Special chars (`.`, `/`, `-`, `:`) treated as spaces (AND semantics).
+
+### 6.3 Search requiring source mode
+
+If source table exists, additional source matches appear in output.
+
+### 6.4 Search with no results
+
+```
+search 'xyznonexistent123';
+```
+
+**Expected:** Empty result.
+
+---
+
+## 7. SHOW CALLERS
+
+### 7.1 Direct callers
+
+```
+show callers of Administration.ACT_CreateAccount;
+```
+
+**Expected:** Table with columns `Caller | Depth`. Shows microflows/pages that call this microflow.
+
+### 7.2 Transitive callers
+
+```
+show callers of Administration.ACT_CreateAccount transitive;
+```
+
+**Expected:** Recursive callers up to depth 10.
+
+### 7.3 No callers
+
+```
+show callers of <Module.UnusedMicroflow>;
+```
+
+**Expected:** Empty result.
+
+---
+
+## 8. SHOW CALLEES
+
+### 8.1 Direct callees
+
+```
+show callees of <Module.OrchestratorMicroflow>;
+```
+
+**Expected:** Microflows called by this microflow.
+
+### 8.2 Transitive callees
+
+```
+show callees of <Module.Flow> transitive;
+```
+
+**Expected:** Recursive callees up to depth 10.
+
+---
+
+## 9. SHOW REFERENCES
+
+### 9.1 Entity references
+
+```
+show references to Administration.Account;
+```
+
+**Expected:** Table with columns `SourceType | SourceName | RefKind`. Shows all documents referencing this entity.
+
+### 9.2 Microflow references
+
+```
+show references to <Module.Microflow>;
+```
+
+**Expected:** Documents referencing this microflow.
+
+---
+
+## 10. SHOW IMPACT
+
+### 10.1 Entity impact
+
+```
+show impact of Administration.Account;
+```
+
+**Expected:** Summary (count by type) + detailed table of impacted documents.
+
+### 10.2 Microflow impact
+
+```
+show impact of <Module.Microflow>;
+```
+
+**Expected:** Summary + detail table.
+
+---
+
+## 11. SHOW CONTEXT
+
+### 11.1 Microflow context
+
+```
+show context of Administration.ACT_CreateAccount;
+```
+
+**Expected:** Markdown output: definition (name, return, params, activities) + entities used + pages shown + called microflows + direct callers.
+
+### 11.2 Entity context
+
+```
+show context of Administration.Account;
+```
+
+**Expected:** Definition (type, generalization, attributes, indexes) + microflows using it + pages displaying it + related entities.
+
+> **Known issue (BUG-010):** Entity definition section is empty in `show context` output.
+
+### 11.3 Page context
+
+```
+show context of <Module.Page>;
+```
+
+**Expected:** Definition (title, URL, layout, widgets) + entities used + microflows called + shown by.
+
+### 11.4 Context with depth
+
+```
+show context of Administration.ACT_CreateAccount depth 3;
+```
+
+**Expected:** Deeper recursive resolution of called microflows.
+
+### 11.5 Non-existent document
+
+```
+show context of Fake.Missing;
+```
+
+**Expected:** Error or empty — document not found in catalog.
+
+---
+
+## 12. SHOW STRUCTURE
+
+### 12.1 Default structure (depth 2)
+
+```
+show structure;
+```
+
+**Expected:** Module names + element type counts (entities, enums, microflows, etc.). Skips system/marketplace modules. Default depth is 2 (element names with signatures).
+
+> **Note:** To get depth-1 output (counts only), use `show structure depth 1` explicitly.
+
+### 12.2 Depth 2
+
+```
+show structure depth 2;
+```
+
+**Expected:** Element names with signatures — entity attributes, microflow params → return, enum values.
+
+### 12.3 Depth 3
+
+```
+show structure depth 3;
+```
+
+**Expected:** Attribute types, parameter names, association delete behavior, constant defaults.
+
+### 12.4 Module filter
+
+```
+show structure in Administration;
+```
+
+**Expected:** Only `Administration` module structure.
+
+> **Note:** Marketplace and system modules are filtered by default. Use `show structure in <Module> all` to include them, or test with a non-marketplace module.
+
+### 12.5 Include system modules
+
+```
+show structure all;
+```
+
+**Expected:** All modules including System, Atlas_Core, etc.
+
+---
+
+## 13. MULTI-STEP WORKFLOWS
+
+### 13.1 Create entity → refresh → query catalog
+
+```
+create persistent entity MyModule.Indexed (
+  Name: string(200) not null
+);
+refresh catalog;
+select * from catalog.entities where QualifiedName = 'MyModule.Indexed';
+```
+
+**Expected:** New entity appears in catalog after refresh.
+
+### 13.2 Impact analysis before drop
+
+```
+show impact of MyModule.Customer;
+drop entity MyModule.Customer;
+```
+
+**Expected:** Impact shows affected documents before destructive operation.
+
+---
+
+## 14. FAILURE MODES & ERROR RECOVERY
+
+### 14.1 Query without catalog
+
+Open project, do NOT refresh catalog:
+```
+select * from catalog.entities;
+```
+
+**Expected:** mxcli auto-builds a fast catalog on demand and returns results. No manual `refresh catalog` required.
+
+### 14.2 Invalid SQL
+
+```
+select * from catalog.nonexistent;
+```
+
+**Expected:** SQL error — no such table.
+
+### 14.3 Search without full catalog
+
+```
+refresh catalog;
+search 'test';
+```
+
+**Expected:** mxcli auto-upgrades to a full catalog build on demand and returns search results. No manual `refresh catalog full` required.
+
+### 14.4 Callers without refs table
+
+```
+refresh catalog;
+show callers of MyModule.Flow;
+```
+
+**Expected:** mxcli auto-upgrades to a full catalog build on demand and returns caller results. No manual `refresh catalog full` required.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| REFRESH CATALOG | x | x | x |
+| SHOW CATALOG TABLES | x | | |
+| SHOW CATALOG STATUS | x | | |
+| DESCRIBE CATALOG | x | | |
+| SELECT FROM CATALOG | x | x | x |
+| SEARCH | x | x | |
+| SHOW CALLERS | x | x | |
+| SHOW CALLEES | x | x | |
+| SHOW REFERENCES | x | x | |
+| SHOW IMPACT | x | | |
+| SHOW CONTEXT | x | x | |
+| SHOW STRUCTURE | x | x | x |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. REFRESH CATALOG | Unit tests | Caching, background |
+| 2. SHOW TABLES | Unit tests | |
+| 3. SHOW STATUS | | All manual |
+| 4. DESCRIBE TABLE | | All manual |
+| 5. SELECT | Unit tests | Complex queries |
+| 6. SEARCH | Unit tests | Edge cases |
+| 7. CALLERS | Unit tests | Transitive depth |
+| 8. CALLEES | Unit tests | |
+| 9. REFERENCES | Unit tests | |
+| 10. IMPACT | Unit tests | |
+| 11. CONTEXT | Unit tests | Deep depth |
+| 12. STRUCTURE | Unit tests | |
+| 13. Multi-step | | All manual |
+| 14. Failure modes | Partial | |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | REFRESH | Fast mode | | | | |
+| 1.2 | REFRESH | Full mode | | | | |
+| 1.3 | REFRESH | Full + source | | | | |
+| 1.4 | REFRESH | Force | | | | |
+| 1.5 | REFRESH | Background | | | | |
+| 1.6 | REFRESH | Caching | | | | |
+| 2.1 | TABLES | List tables | | | | |
+| 2.2 | TABLES | Build mode check | | | | |
+| 3.1 | STATUS | Show status | | | | |
+| 4.1 | DESCRIBE | Entities table | | | | |
+| 4.2 | DESCRIBE | Activities table | | | | |
+| 5.1 | SELECT | Basic | | | | |
+| 5.2 | SELECT | Multiple conditions | | | | |
+| 5.3 | SELECT | Aggregate | | | | |
+| 5.4 | SELECT | Join | | | | |
+| 5.5 | SELECT | Full-only warning | | | | |
+| 5.6 | SELECT | FTS search | | | | |
+| 6.1 | SEARCH | Basic | | | | |
+| 6.2 | SEARCH | Special chars | | | | |
+| 6.3 | SEARCH | Source mode | | | | |
+| 6.4 | SEARCH | No results | | | | |
+| 7.1 | CALLERS | Direct | | | | |
+| 7.2 | CALLERS | Transitive | | | | |
+| 7.3 | CALLERS | None | | | | |
+| 8.1 | CALLEES | Direct | | | | |
+| 8.2 | CALLEES | Transitive | | | | |
+| 9.1 | REFERENCES | Entity | | | | |
+| 9.2 | REFERENCES | Microflow | | | | |
+| 10.1 | IMPACT | Entity | | | | |
+| 10.2 | IMPACT | Microflow | | | | |
+| 11.1 | CONTEXT | Microflow | | | | |
+| 11.2 | CONTEXT | Entity | | | | |
+| 11.3 | CONTEXT | Page | | | | |
+| 11.4 | CONTEXT | Depth 3 | | | | |
+| 11.5 | CONTEXT | Not found | | | | |
+| 12.1 | STRUCTURE | Depth 1 | | | | |
+| 12.2 | STRUCTURE | Depth 2 | | | | |
+| 12.3 | STRUCTURE | Depth 3 | | | | |
+| 12.4 | STRUCTURE | Module filter | | | | |
+| 12.5 | STRUCTURE | All modules | | | | |
+| 13.1 | MULTI-STEP | Create + refresh + query | | | | |
+| 13.2 | MULTI-STEP | Impact before drop | | | | |
+| 14.1 | FAILURE | No catalog | | | | |
+| 14.2 | FAILURE | Invalid SQL | | | | |
+| 14.3 | FAILURE | Search no full | | | | |
+| 14.4 | FAILURE | Callers no full | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/cli-commands-test-cases.md b/docs/15-testing/cli-commands-test-cases.md
new file mode 100644
index 00000000..cd0c7824
--- /dev/null
+++ b/docs/15-testing/cli-commands-test-cases.md
@@ -0,0 +1,755 @@
+# CLI Commands Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+Covers: docker, test, playwright, eval, init, setup, auth, marketplace, widget, bson, fmt, new, serve, lsp, tui, check, report.
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | CLI features exercised |
+|-----|-----------|------------------------|
+| Lato Enquiry Management | 11.4.0 | docker, test, check, bson, fmt |
+| Evora - Factory Management | 10.24.15 | docker, playwright, report, widget |
+| Lato Product Inventory | 11.2.0 | test, check, bson, lsp |
+
+---
+
+## Setup
+
+### 1. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 2. Ensure Docker
+
+```bash
+docker info
+```
+
+Docker Desktop must be running. Commands `docker`, `test`, and `playwright` require it.
+
+### 3. Set environment
+
+```bash
+export APPS_DIR=<path-to-extracted-apps>
+export MPR="$APPS_DIR/EnquiriesManagement/EnquiriesManagement.mpr"
+```
+
+> **IMPORTANT:** Commands `docker`, `test`, `fmt`, and `new` modify project files. Always run against a **copy** of the project folder.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> export MPR="MyProject-test/MyProject.mpr"
+> ```
+
+---
+
+## 1. mxcli docker
+
+### 1.1 Init Docker configuration
+
+```bash
+mxcli docker init -p "$MPR"
+```
+
+**Expected:** Creates `.docker/docker-compose.yml`, `.env.example`, and `.env` in the project directory. Exit code `0`.
+
+### 1.2 Build Docker image
+
+```bash
+mxcli docker build -p "$MPR"
+```
+
+**Expected:** Builds image from generated Dockerfile. Exit code `0`.
+
+### 1.3 Run container
+
+```bash
+mxcli docker run -p "$MPR" --port 8080 --admin-port 8090
+```
+
+**Expected:** Starts Mendix runtime container. App reachable at `http://localhost:8080`. Admin at `http://localhost:8090`. Exit code `0`.
+
+### 1.4 Docker Compose up
+
+```bash
+mxcli docker up -p "$MPR"
+```
+
+**Expected:** Starts services via `docker-compose up -d`. Exit code `0`.
+
+### 1.5 Docker Compose down
+
+```bash
+mxcli docker down -p "$MPR"
+```
+
+**Expected:** Stops and removes containers. Exit code `0`.
+
+### 1.6 Run MxBuild project validation
+
+```bash
+mxcli docker check -p "$MPR"
+```
+
+**Expected:** Runs `mx check` (MxBuild project validation) inside Docker. Prints errors and warnings. Exit code `0` if no errors, `1` if errors found.
+
+### 1.7 View logs
+
+```bash
+mxcli docker logs -p "$MPR"
+```
+
+**Expected:** Streams container logs to stdout. Exit code `0`.
+
+### 1.8 Container status
+
+```bash
+mxcli docker status -p "$MPR"
+```
+
+**Expected:** Prints container state, ports, uptime. Exit code `0`.
+
+### 1.9 Open shell
+
+```bash
+mxcli docker shell -p "$MPR"
+```
+
+**Expected:** Opens interactive shell inside the running container.
+
+### 1.10 Reload runtime
+
+```bash
+mxcli docker reload -p "$MPR"
+```
+
+**Expected:** Rebuilds and restarts the runtime without recreating the container. Exit code `0`.
+
+---
+
+## 2. mxcli test
+
+### 2.1 Run all tests in directory
+
+```bash
+mxcli test tests/ -p "$MPR"
+```
+
+**Expected:** Discovers `.test.mdl` and `.test.md` files. Injects TestRunner microflow, builds via MxBuild, runs in Docker. Prints pass/fail summary. Exit code `0` if all pass, `1` if any fail.
+
+### 2.2 Run single test file
+
+```bash
+mxcli test tests/my-flow.test.mdl -p "$MPR"
+```
+
+**Expected:** Runs only the specified test file. Exit code `0` on pass.
+
+### 2.3 List tests without running
+
+```bash
+mxcli test tests/ -p "$MPR" --list
+```
+
+**Expected:** Prints test names from `@test`/`@expect` annotations. Does not build or run. Exit code `0`.
+
+### 2.4 JUnit output
+
+```bash
+mxcli test tests/ -p "$MPR" --junit report.xml
+```
+
+**Expected:** Writes JUnit XML to `report.xml`. Exit code reflects pass/fail.
+
+### 2.5 Skip build
+
+```bash
+mxcli test tests/ -p "$MPR" --skip-build
+```
+
+**Expected:** Skips MxBuild step. Uses existing build artifacts. Exit code `0` on pass.
+
+### 2.6 Verbose output
+
+```bash
+mxcli test tests/ -p "$MPR" --verbose
+```
+
+**Expected:** Prints detailed output per test case including microflow execution logs.
+
+### 2.7 Custom timeout
+
+```bash
+mxcli test tests/ -p "$MPR" --timeout 120
+```
+
+**Expected:** Fails tests that exceed 120 seconds. Exit code `1` on timeout.
+
+### 2.8 Color output
+
+```bash
+mxcli test tests/ -p "$MPR" --color
+```
+
+**Expected:** Forces colored output even when piped. Green for pass, red for fail.
+
+---
+
+## 3. mxcli playwright verify
+
+### 3.1 Run verification scripts
+
+```bash
+mxcli playwright verify tests/e2e/ -p "$MPR"
+```
+
+**Expected:** Discovers `.test.sh` scripts. Launches app in Docker, runs each script. Captures screenshots on failure. Exit code `0` if all pass.
+
+### 3.2 List verification scripts
+
+```bash
+mxcli playwright verify tests/e2e/ -p "$MPR" --list
+```
+
+**Expected:** Prints discovered `.test.sh` filenames. Does not run. Exit code `0`.
+
+### 3.3 JUnit output
+
+```bash
+mxcli playwright verify tests/e2e/ -p "$MPR" --junit pw-report.xml
+```
+
+**Expected:** Writes JUnit XML. Screenshots attached as test artifacts.
+
+### 3.4 Verbose mode
+
+```bash
+mxcli playwright verify tests/e2e/ -p "$MPR" --verbose
+```
+
+**Expected:** Prints browser console logs and script output per test.
+
+---
+
+## 4. mxcli eval
+
+### 4.1 Check evaluation results
+
+```bash
+mxcli eval check
+```
+
+**Expected:** Runs AI correctness evaluation. Prints pass/fail per check. Exit code `0` if all pass.
+
+### 4.2 List evaluations
+
+```bash
+mxcli eval list
+```
+
+**Expected:** Lists available evaluation suites. Exit code `0`.
+
+---
+
+## 5. mxcli init
+
+### 5.1 Scaffold AI/IDE config
+
+```bash
+mxcli init -p "$MPR"
+```
+
+**Expected:** Creates `CLAUDE.md`, `.vscode/settings.json`, and other AI config files in the project directory. Exit code `0`.
+
+### 5.2 Init in empty directory
+
+```bash
+mkdir /tmp/empty-project && mxcli init -p /tmp/empty-project
+```
+
+**Expected:** Exit code `0`. The `-p` flag does not validate that the path contains an `.mpr` file — command succeeds regardless. **Known behavior:** no MPR validation on init.
+
+---
+
+## 6. mxcli setup
+
+### 6.1 Setup MxBuild
+
+```bash
+mxcli setup mxbuild
+```
+
+**Expected:** Downloads and installs MxBuild for the project's Studio Pro version. Exit code `0`.
+
+### 6.2 Setup MxRuntime
+
+```bash
+mxcli setup mxruntime
+```
+
+**Expected:** Downloads and installs MxRuntime. Exit code `0`.
+
+### 6.3 Setup mxcli itself
+
+```bash
+mxcli setup mxcli
+```
+
+**Expected:** Updates mxcli to latest version. Exit code `0`.
+
+---
+
+## 7. mxcli auth
+
+### 7.1 Login
+
+```bash
+mxcli auth login
+```
+
+**Expected:** Opens browser for Mendix SSO. Stores token locally. Prints "Logged in as <email>". Exit code `0`.
+
+### 7.2 Check status
+
+```bash
+mxcli auth status
+```
+
+**Expected:** Prints current auth state (logged in/out, username, token expiry). Exit code `0` if authenticated, `1` if not authenticated.
+
+### 7.3 List accounts
+
+```bash
+mxcli auth list
+```
+
+**Expected:** Lists stored credentials. Exit code `0`.
+
+### 7.4 Logout
+
+```bash
+mxcli auth logout
+```
+
+**Expected:** Removes stored token. Prints confirmation. Exit code `0`.
+
+### 7.5 Status after logout
+
+```bash
+mxcli auth logout && mxcli auth status
+```
+
+**Expected:** Status reports "Not logged in". Exit code `1`.
+
+---
+
+## 8. mxcli marketplace
+
+> **Prerequisite:** Requires authentication (`mxcli auth login`). Commands fail with "no credential" error without auth.
+
+### 8.1 Search modules
+
+```bash
+mxcli marketplace search "email"
+```
+
+**Expected:** Prints matching marketplace modules with name, version, compatibility. Exit code `0`.
+
+### 8.2 Module info
+
+```bash
+mxcli marketplace info "Email Connector"
+```
+
+**Expected:** Prints module details: description, author, latest version, supported Studio Pro versions. Exit code `0`.
+
+### 8.3 List versions
+
+```bash
+mxcli marketplace versions "Email Connector"
+```
+
+**Expected:** Prints version history with release dates. Exit code `0`.
+
+### 8.4 Search with no results
+
+```bash
+mxcli marketplace search "zzzznonexistent"
+```
+
+**Expected:** Prints "No results found." Exit code `0`.
+
+---
+
+## 9. mxcli widget
+
+### 9.1 List widgets
+
+```bash
+mxcli widget list -p "$MPR"
+```
+
+**Expected:** Lists all custom widgets in the project with name and version. Exit code `0`.
+
+### 9.2 Extract widget
+
+```bash
+mxcli widget extract --mpk path/to/widget.mpk
+```
+
+**Expected:** Extracts widget package contents. Exit code `0`.
+
+### 9.3 Init new widget
+
+```bash
+mxcli widget init MyNewWidget
+```
+
+**Expected:** Scaffolds widget project structure. Exit code `0`.
+
+### 9.4 Generate widget docs
+
+```bash
+mxcli widget docs -p "$MPR"
+```
+
+**Expected:** Generates documentation for all custom widgets. Exit code `0`.
+
+---
+
+## 10. mxcli bson
+
+### 10.1 Dump MPR contents
+
+```bash
+mxcli bson dump -p "$MPR" --list
+mxcli bson dump -p "$MPR" --object "Name"
+```
+
+**Expected:** `--list` prints object names in the MPR. `--object` dumps a specific named object. There is no simple "dump all" mode. Exit code `0`.
+
+### 10.2 Discover document types
+
+```bash
+mxcli bson discover "$MPR"
+```
+
+**Expected:** Lists all document types and counts found in the MPR. Exit code `0`.
+
+### 10.3 Compare objects within or across projects
+
+```bash
+# Compare objects within the same project by type
+mxcli bson compare -p "$MPR" --type DomainModels$DomainModel
+
+# Compare across two projects
+mxcli bson compare -p "$MPR" --p2 "$APPS_DIR/FactoryManagement/FactoryManagement.mpr"
+```
+
+**Expected:** Prints structural diff. Exit code `0` if identical, `1` if different.
+
+### 10.4 Dump nonexistent file
+
+```bash
+mxcli bson dump /tmp/nonexistent.mpr
+```
+
+**Expected:** Error: file not found. Exit code `1`.
+
+---
+
+## 11. mxcli fmt
+
+### 11.1 Format MDL file
+
+```bash
+mxcli fmt myfile.mdl
+```
+
+**Expected:** Outputs formatted MDL to stdout (does NOT write in-place). Exit code `0`.
+
+> **Known issue (BUG-012):** No `-w` flag for in-place write. Output goes to stdout only.
+
+### 11.2 Format already-formatted file
+
+```bash
+mxcli fmt myfile.mdl
+```
+
+**Expected:** No changes. Exit code `0`.
+
+### 11.3 Format invalid file
+
+```bash
+mxcli fmt broken.txt
+```
+
+**Expected:** Exit code `0`. Input is echoed unchanged to stdout (no parse error).
+
+> **Known issue (BUG-012):** No `-w` flag, so invalid input passes through without error.
+
+---
+
+## 12. mxcli new
+
+### 12.1 Create a new Mendix project
+
+```bash
+mxcli new my-app --version 10.24.15
+```
+
+**Expected:** Scaffolds a complete Mendix project named `my-app` for the specified Studio Pro version. Exit code `0`.
+
+### 12.2 Create project without version
+
+```bash
+mxcli new my-app
+```
+
+**Expected:** Creates project using the latest available Studio Pro version. Exit code `0`.
+
+---
+
+## 13. mxcli serve
+
+### 13.1 Start HTTP server
+
+```bash
+mxcli serve -p "$MPR" --port 9000 &
+curl -s http://localhost:9000/
+kill %1
+```
+
+**Expected:** Server starts and serves project visualization at root `/`. Exit code `0` on clean shutdown.
+
+### 13.2 Port conflict
+
+```bash
+mxcli serve -p "$MPR" --port 9000 &
+mxcli serve -p "$MPR" --port 9000
+```
+
+**Expected:** Second instance fails with "port already in use". Exit code `1`.
+
+---
+
+## 14. mxcli lsp
+
+### 14.1 Start LSP server
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | mxcli lsp
+```
+
+**Expected:** Returns JSON-RPC `initialize` response with server capabilities (completion, hover, diagnostics, documentSymbol, foldingRange). Exit code `0`.
+
+### 14.2 Verify capabilities
+
+Inspect the `initialize` response `capabilities` object:
+
+| Capability | Expected |
+|------------|----------|
+| `completionProvider` | Present |
+| `hoverProvider` | `true` |
+| `diagnosticProvider` | Present |
+| `documentSymbolProvider` | `true` |
+| `foldingRangeProvider` | `true` |
+
+---
+
+## 15. mxcli tui
+
+### 15.1 Launch TUI
+
+```bash
+mxcli tui -p "$MPR"
+```
+
+**Expected:** Opens terminal UI explorer. Displays project tree. Arrow keys navigate. `q` exits. Exit code `0`.
+
+### 15.2 TUI without project
+
+```bash
+mxcli tui
+```
+
+**Expected:** Error: `-p` flag required. Exit code `1`.
+
+---
+
+## 16. mxcli check
+
+### 16.1 Validate MDL script syntax
+
+```bash
+mxcli check script.mdl
+```
+
+**Expected:** Validates MDL script syntax (not the project itself — use `docker check` for project validation). Prints errors and warnings. Exit code `0` if no errors, `1` if errors found.
+
+### 16.2 SARIF output
+
+```bash
+mxcli check script.mdl --format sarif > results.sarif
+```
+
+**Expected:** Writes SARIF JSON to stdout. Exit code reflects validation result.
+
+### 16.3 Check nonexistent file
+
+```bash
+mxcli check /tmp/nonexistent.mdl
+```
+
+**Expected:** Error: file not found. Exit code `1`.
+
+---
+
+## 17. mxcli report
+
+### 17.1 Markdown report
+
+```bash
+mxcli report -p "$MPR" --format markdown
+```
+
+**Expected:** Prints project report in Markdown to stdout. Exit code `0`.
+
+### 17.2 JSON report
+
+```bash
+mxcli report -p "$MPR" --format json
+```
+
+**Expected:** Prints valid JSON report. Exit code `0`.
+
+> **Known issue (BUG-011):** `--format json` hangs after catalog load.
+
+### 17.3 HTML report
+
+```bash
+mxcli report -p "$MPR" --format html -o report.html
+```
+
+**Expected:** Writes HTML report to `report.html`. Exit code `0`.
+
+> **Known issue (BUG-011):** `--format html` hangs after catalog load.
+
+---
+
+## Failure Modes
+
+| Scenario | Command | Expected error | Exit code |
+|----------|---------|---------------|-----------|
+| Missing `-p` flag | `mxcli test tests/` | "required flag: -p" | `1` |
+| Invalid MPR path | `mxcli check -p /bad/path.mpr` | "file not found" | `1` |
+| Docker not running | `mxcli docker run -p "$MPR"` | "cannot connect to Docker daemon" | `1` |
+| MxBuild not installed | `mxcli check -p "$MPR"` | "MxBuild not found — run mxcli setup mxbuild" | `1` |
+| Auth token expired | `mxcli marketplace search "x"` | "token expired — run mxcli auth login" | `1` |
+| Port conflict | `mxcli serve --port <in-use>` | "address already in use" | `1` |
+| Invalid test file | `mxcli test bad.txt -p "$MPR"` | "unsupported test file format" | `1` |
+| Timeout exceeded | `mxcli test --timeout 1` | "test timed out after 1s" | `1` |
+| BSON corrupt file | `mxcli bson dump corrupt.mpr` | "invalid BSON data" | `1` |
+
+> **Note:** Several commands return exit `0` on error instead of `1`: `bson dump` (missing args), `docker build` (build failure), `docker check` (in some failure modes), `marketplace search` (auth failure), `serve` (port conflict), `fmt` (invalid input). Do not rely solely on exit codes for pass/fail in automation.
+
+---
+
+## Test Project Coverage Matrix
+
+| Command | Subcommands | Happy path | Error path | Flags tested |
+|---------|-------------|:----------:|:----------:|:------------:|
+| `docker` | run, build, check, init, up, down, logs, status, shell, reload | 10 | 1 | -p, --port, --admin-port |
+| `test` | — | 8 | 2 | -p, --list, --junit, --skip-build, --verbose, --color, --timeout |
+| `playwright verify` | — | 4 | 0 | -p, --list, --junit, --verbose |
+| `eval` | check, list | 2 | 0 | — |
+| `init` | — | 1 | 1 | -p |
+| `setup` | mxbuild, mxruntime, mxcli | 3 | 0 | — |
+| `auth` | login, logout, status, list | 5 | 0 | — |
+| `marketplace` | search, info, versions | 4 | 0 | — |
+| `widget` | extract, list, init, docs | 4 | 0 | -p |
+| `bson` | dump, discover, compare | 3 | 2 | — |
+| `fmt` | — | 2 | 1 | — |
+| `new` | — | 2 | 0 | --version |
+| `serve` | — | 1 | 1 | -p, --port |
+| `lsp` | — | 2 | 0 | — |
+| `tui` | — | 1 | 1 | -p |
+| `check` | — | 2 | 1 | --format |
+| `report` | — | 3 | 0 | -p, --format, -o |
+
+**Total: 56 happy-path + 11 error-path = 67 test cases**
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**mxcli version:** _______________
+
+| # | Command | Case | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | `docker init` | Init Docker config | | | | |
+| 1.2 | `docker build` | Build image | | | | |
+| 1.3 | `docker run` | Run container | | | | |
+| 1.4 | `docker check` | Runtime check | | | | |
+| 1.5 | `docker up` | Compose up | | | | |
+| 1.6 | `docker down` | Compose down | | | | |
+| 1.7 | `docker logs` | View logs | | | | |
+| 1.8 | `docker status` | Container status | | | | |
+| 1.9 | `docker shell` | Interactive shell | | | | |
+| 1.10 | `docker reload` | Hot reload | | | | |
+| 2.1 | `test` | Run all tests | | | | |
+| 2.2 | `test` | Single file | | | | |
+| 2.3 | `test --list` | List tests | | | | |
+| 2.4 | `test --junit` | JUnit output | | | | |
+| 2.5 | `test --skip-build` | Skip build | | | | |
+| 2.6 | `test --verbose` | Verbose output | | | | |
+| 2.7 | `test --color` | Colored output | | | | |
+| 2.8 | `test --timeout` | Custom timeout | | | | |
+| 3.1 | `playwright` | Run scripts | | | | |
+| 3.2 | `playwright --list` | List scripts | | | | |
+| 3.3 | `playwright --junit` | JUnit output | | | | |
+| 3.4 | `playwright --verbose` | Verbose output | | | | |
+| 4.1 | `eval check` | Check correctness | | | | |
+| 4.2 | `eval list` | List evaluations | | | | |
+| 5.1 | `init` | Init AI config | | | | |
+| 6.1 | `setup mxbuild` | Install MxBuild | | | | |
+| 6.2 | `setup mxruntime` | Install runtime | | | | |
+| 6.3 | `setup mxcli` | Self-update | | | | |
+| 7.1 | `auth login` | Login flow | | | | |
+| 7.2 | `auth logout` | Logout | | | | |
+| 7.3 | `auth status` | Auth status | | | | |
+| 7.4 | `auth list` | List accounts | | | | |
+| 7.5 | `auth` | Token refresh | | | | |
+| 8.1 | `marketplace search` | Search modules | | | | |
+| 8.2 | `marketplace info` | Module info | | | | |
+| 8.3 | `marketplace versions` | List versions | | | | |
+| 8.4 | `marketplace` | Install module | | | | |
+| 9.1 | `widget extract` | Extract widget | | | | |
+| 9.2 | `widget list` | List widgets | | | | |
+| 9.3 | `widget init` | Init widget project | | | | |
+| 9.4 | `widget docs` | Generate docs | | | | |
+| 10.1 | `bson dump` | Dump MPR | | | | |
+| 10.2 | `bson discover` | Discover structure | | | | |
+| 10.3 | `bson compare` | Compare MPRs | | | | |
+| 11.1 | `fmt` | Format file | | | | |
+| 11.2 | `fmt` | Format directory | | | | |
+| 12.1 | `new` | Create project | | | | |
+| 13.1 | `serve` | Start server | | | | |
+| 14.1 | `lsp` | Start LSP | | | | |
+| 14.2 | `lsp` | Diagnostics | | | | |
+| 15.1 | `tui` | Terminal UI | | | | |
+| 16.1 | `check` | Validate project | | | | |
+| 16.2 | `check --sarif` | SARIF output | | | | |
+| 17.1 | `report` | Markdown report | | | | |
+| 17.2 | `report --format json` | JSON report | | | | |
+| 17.3 | `report -o` | Output to file | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/entity-test-cases.md b/docs/15-testing/entity-test-cases.md
new file mode 100644
index 00000000..99303fe2
--- /dev/null
+++ b/docs/15-testing/entity-test-cases.md
@@ -0,0 +1,1401 @@
+# Entity, Association & Constant Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Entities | Associations | Constants |
+|-----|-----------|----------|--------------|-----------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+> **Note:** `MyModule` will be auto-created on first CREATE statement — no manual setup needed.
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show entities;" > /tmp/show-ent.mdl
+  mxcli exec /tmp/show-ent.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N entities)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations (CREATE, ALTER, DROP) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Dropped entities, associations, and constants cannot be recovered — there is no undo.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW ENTITIES
+
+### 1.1 List all entities
+
+```
+show entities;
+```
+
+**Expected:** Table with columns `Entity | Type | Attrs | Assocs | Validations | Indexes | Events | AccessRules`. Summary line `(N entities)`. Sorted alphabetically.
+
+### 1.2 List entities in a module
+
+```
+show entities in Administration;
+```
+
+**Expected:** Only entities from `Administration` module. Same column format.
+
+### 1.3 Generalization column
+
+```
+show entities;
+```
+
+**Expected:** If any entity has a generalization, an `Extends` column appears between `Type` and `Attrs`. System entities (referenced via generalization) show `-` for counts.
+
+### 1.4 Empty module
+
+```
+show entities in NonExistentModule;
+```
+
+**Expected:** Error or empty result with `(0 entities)`.
+
+### 1.5 Entity types
+
+Verify `Type` column values across projects:
+
+| Type | Example |
+|------|---------|
+| Persistent | Most domain entities |
+| Non-Persistent | Transient/helper entities |
+| External | OData/external entities |
+| System | System.User, System.Session |
+
+---
+
+## 2. SHOW ENTITY (single)
+
+### 2.1 Persistent entity
+
+```
+show entity Administration.Account;
+```
+
+**Expected:** Markdown-style output:
+```
+**Entity: Administration.Account**
+
+- Persistable: true
+- Extends: System.User
+
+| Attribute | Type        |
+| --------- | ----------- |
+| ...       | ...         |
+
+(N attributes)
+```
+
+### 2.2 Non-persistent entity
+
+```
+show entity <Module.NonPersistentEntity>;
+```
+
+**Expected:** `Persistable: false`. No `Extends` if no generalization.
+
+### 2.3 Non-existent entity
+
+```
+show entity Fake.Entity;
+```
+
+**Expected:** Error message (not found).
+
+---
+
+## 3. DESCRIBE ENTITY
+
+### 3.1 Basic entity
+
+```
+describe entity Administration.Account;
+```
+
+**Expected:** Roundtrippable MDL output:
+```
+create or modify persistent entity Administration.Account extends System.User (
+  FullName: string(200),
+  IsLocalUser: boolean,
+  ...
+)
+/
+```
+
+### 3.2 Entity with all features
+
+Find an entity with indexes, events, validation rules, and access rules. Verify output includes:
+- `/** documentation */` block (if documented)
+- `@Position(x, y)` annotation
+- Attribute types and constraints (`not null error '...'`, `unique error '...'`)
+- System pseudo-attributes (`Owner: AutoOwner`, etc.)
+- `index (col1, col2 desc)` lines
+- `on before|after create|commit|delete|rollback call Module.Mf($currentObject) [raise error]` events
+- `grant Role1, Role2 on Module.Entity (create, delete, read *, write (Col1, Col2)) [where 'xpath']` access rules
+
+### 3.3 View entity
+
+```
+describe entity <Module.ViewEntity>;
+```
+
+**Expected:** Output ends with `as (` followed by indented OQL query, then `)`.
+
+### 3.4 Non-existent entity
+
+```
+describe entity Fake.Missing;
+```
+
+**Expected:** Error message (not found).
+
+---
+
+## 4. CREATE ENTITY
+
+### 4.1 Minimal persistent entity
+
+```
+create persistent entity MyModule.SimpleTag (
+  Name: string(50)
+);
+```
+
+**Expected:** Entity created. `show entity MyModule.SimpleTag` shows 1 attribute.
+
+### 4.2 All attribute types
+
+```
+create persistent entity MyModule.AllTypes (
+  ProductId: autonumber default 1,
+  Name: string(200) not null error 'Name is required',
+  Code: string(50) unique error 'Code must be unique',
+  Price: decimal not null error 'Price required' default 0.00,
+  Stock: integer default 0,
+  IsActive: boolean default true,
+  ReleaseDate: date,
+  CreatedAt: datetime,
+  ProductImage: binary,
+  Status: enumeration(MyModule.Status)
+);
+```
+
+**Expected:** Entity created with 10 attributes. Types and constraints preserved in `describe`.
+
+> **Note:** `default 0.00` is normalized to `default 0` for decimals.
+
+### 4.3 Entity with generalization
+
+```
+create persistent entity MyModule.SpecialUser extends System.User (
+  Department: string(100)
+);
+```
+
+**Expected:** Entity created. `show entity` shows `Extends: System.User`.
+
+### 4.4 Non-persistent entity
+
+```
+create non-persistent entity MyModule.SearchParams (
+  SearchTerm: string(200),
+  IncludeInactive: boolean default false
+);
+```
+
+**Expected:** Entity created. `Persistable: false`.
+
+### 4.5 Entity with indexes
+
+```
+create persistent entity MyModule.Order (
+  OrderNumber: string(50) not null unique,
+  CustomerId: integer,
+  OrderDate: datetime
+)
+index (OrderNumber),
+index (CustomerId asc),
+index (OrderDate desc);
+```
+
+**Expected:** Entity created. `describe` shows 3 index definitions.
+
+### 4.6 Entity with event handlers
+
+```
+create persistent entity MyModule.BankAccount (
+  IBAN: string(34) not null
+)
+on before commit call MyModule.ACT_ValidateIBAN($currentObject) raise error;
+```
+
+**Expected:** Entity created. `describe` shows event handler.
+
+> **Prerequisite:** Event handlers and calculated-by microflows require the target microflow to exist. Create the microflow before the entity/alter statement.
+
+### 4.7 Entity with system attributes
+
+```
+create or modify persistent entity MyModule.AuditedRecord (
+  Title: string(200) not null,
+  Owner: autoowner,
+  ChangedBy: autochangedby,
+  CreatedDate: autocreateddate,
+  ChangedDate: autochangeddate
+);
+```
+
+**Expected:** Entity created with system attributes. `describe` shows pseudo-attributes.
+
+### 4.8 `create or modify` — new entity
+
+```
+create or modify persistent entity MyModule.Fresh (
+  Value: integer
+);
+```
+
+**Expected:** Creates entity (same as without `or modify`).
+
+### 4.9 `create or modify` — existing entity
+
+```
+create or modify persistent entity MyModule.Fresh (
+  Value: integer,
+  Extra: string(100)
+);
+```
+
+**Expected:** Updates entity — adds `Extra` attribute, preserves entity ID.
+
+### 4.10 Duplicate entity (without `or modify`)
+
+```
+create persistent entity MyModule.SimpleTag (
+  Name: string(50)
+);
+```
+
+**Expected:** Error — entity already exists.
+
+### 4.11 View entity with OQL
+
+```
+create view entity MyModule.ActiveProducts (
+  Name: string(200),
+  Price: decimal
+) as
+  select p.Name as Name, p.Price as Price
+  from MyModule.Product as p
+  where p.IsActive = true;
+```
+
+**Expected:** View entity created. `describe` shows OQL source.
+
+### 4.12 `create or replace` view entity
+
+```
+create or replace view entity MyModule.ActiveProducts (
+  Name: string(200),
+  Price: decimal,
+  Stock: integer
+) as
+  select p.Name, p.Price, p.Stock
+  from MyModule.Product as p
+  where p.IsActive = true;
+```
+
+**Expected:** Drops and recreates view entity (new ID).
+
+### 4.13 Position annotation
+
+```
+@position(300, 400)
+create persistent entity MyModule.Positioned (
+  Label: string(100)
+);
+```
+
+**Expected:** Entity created at position (300, 400). `describe` shows `@Position(300, 400)`.
+
+---
+
+## 5. ALTER ENTITY
+
+### 5.1 Add attribute
+
+```
+alter entity MyModule.SimpleTag add attribute Description: string(500);
+```
+
+**Expected:** Attribute added. `describe` shows both `Name` and `Description`.
+
+### 5.2 Rename attribute
+
+```
+alter entity MyModule.SimpleTag rename attribute Name to TagName;
+```
+
+**Expected:** Attribute renamed. `describe` shows `TagName`.
+
+### 5.3 Modify attribute type
+
+```
+alter entity MyModule.SimpleTag modify attribute TagName: string(200);
+```
+
+**Expected:** Attribute type updated to `string(200)`.
+
+### 5.4 Drop attribute
+
+```
+alter entity MyModule.SimpleTag drop attribute Description;
+```
+
+**Expected:** Attribute removed. Validation rules, index refs, and MemberAccess entries cleaned up.
+
+### 5.5 Set documentation
+
+```
+alter entity MyModule.SimpleTag set documentation 'A simple tag entity for testing';
+```
+
+**Expected:** `describe` shows `/** A simple tag entity for testing */`.
+
+### 5.6 Set position
+
+```
+alter entity MyModule.SimpleTag set position (150, 250);
+```
+
+**Expected:** `describe` shows `@Position(150, 250)`.
+
+### 5.7 Add index
+
+```
+alter entity MyModule.SimpleTag add index (TagName);
+```
+
+**Expected:** `describe` shows `index (TagName)`.
+
+### 5.8 Drop index
+
+```
+alter entity MyModule.SimpleTag drop index idx1;
+```
+
+**Expected:** Index removed.
+
+### 5.9 Add event handler
+
+```
+alter entity MyModule.SimpleTag
+  add event handler on before commit call MyModule.ACT_ValidateTag($currentObject) raise error;
+```
+
+**Expected:** Event handler added to entity.
+
+> **Prerequisite:** Event handlers and calculated-by microflows require the target microflow to exist. Create the microflow before the entity/alter statement.
+
+### 5.10 Drop event handler
+
+```
+alter entity MyModule.SimpleTag drop event handler on before commit;
+```
+
+**Expected:** Event handler removed.
+
+### 5.11 Multiple actions
+
+```
+alter entity MyModule.SimpleTag
+  add attribute Priority: integer default 0
+  add index (Priority)
+  set documentation 'Updated tag entity';
+```
+
+**Expected:** All three changes applied in one statement.
+
+### 5.12 Drop system pseudo-attribute
+
+```
+alter entity MyModule.AuditedRecord drop attribute owner;
+```
+
+**Expected:** Clears `HasOwner` flag on entity. `describe` no longer shows `Owner: AutoOwner`.
+
+### 5.13 Make attribute calculated
+
+```
+alter entity MyModule.SimpleTag modify attribute TagName: string(200) calculated by MyModule.CalcTagName;
+```
+
+**Expected:** Attribute marked as calculated. `describe` shows `calculated by MyModule.CalcTagName`.
+
+> **Prerequisite:** Event handlers and calculated-by microflows require the target microflow to exist. Create the microflow before the entity/alter statement.
+
+---
+
+## 6. DROP ENTITY
+
+### 6.1 Drop existing entity
+
+```
+drop entity MyModule.SimpleTag;
+```
+
+**Expected:** Entity removed. `show entity MyModule.SimpleTag` returns error.
+
+### 6.2 Drop non-existent entity
+
+```
+drop entity MyModule.NonExistent;
+```
+
+**Expected:** Error — entity not found.
+
+### 6.3 Drop view entity
+
+```
+drop entity MyModule.ActiveProducts;
+```
+
+**Expected:** View entity and its ViewEntitySourceDocument removed.
+
+### 6.4 Drop entity with references
+
+```
+drop entity MyModule.Order;
+```
+
+**Expected:** Entity with references is dropped without warning. No warning issued.
+
+---
+
+## 7. SHOW ASSOCIATIONS
+
+### 7.1 List all associations
+
+```
+show associations;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Parent | Child | Type | Owner | Storage`. Summary `(N associations)`.
+
+### 7.2 List associations in a module
+
+```
+show associations in MyModule;
+```
+
+**Expected:** Only associations from `MyModule`. Same format.
+
+### 7.3 Cross-module associations
+
+```
+show associations;
+```
+
+**Expected:** Cross-module associations listed with full qualified names for both parent and child entities.
+
+---
+
+## 8. SHOW ASSOCIATION (single)
+
+### 8.1 Basic association
+
+```
+show association MyModule.Order_Customer;
+```
+
+**Expected:**
+```
+Association: MyModule.Order_Customer
+  Type: Reference
+  Owner: Default
+  Storage: Column
+```
+
+### 8.2 Cross-module association
+
+```
+show association <Module.CrossModuleAssoc>;
+```
+
+**Expected:** Shows `(cross-module)` and full child entity path.
+
+### 8.3 Non-existent association
+
+```
+show association Fake.Missing;
+```
+
+**Expected:** Error — association not found.
+
+---
+
+## 9. DESCRIBE ASSOCIATION
+
+### 9.1 Reference association
+
+```
+describe association MyModule.Order_Customer;
+```
+
+**Expected:**
+```
+create association MyModule.Order_Customer
+from MyModule.Order to MyModule.Customer
+type Reference
+owner Default
+delete_behavior DELETE_BUT_KEEP_REFERENCES;
+/
+```
+
+### 9.2 ReferenceSet association
+
+```
+describe association MyModule.Project_Employees;
+```
+
+**Expected:** `type ReferenceSet`, `owner Both`.
+
+> **Note:** Owner depends on existing project data; may show `owner Default`.
+
+### 9.3 Association with documentation
+
+Find an association with a doc comment. Verify `/** ... */` appears in output.
+
+---
+
+## 10. CREATE ASSOCIATION
+
+### 10.1 Basic reference (many-to-one)
+
+```
+create association MyModule.Order_Customer
+from MyModule.Order to MyModule.Customer
+type reference
+owner default
+delete_behavior DELETE_BUT_KEEP_REFERENCES;
+```
+
+**Expected:** Association created. `describe` matches input.
+
+### 10.2 ReferenceSet (many-to-many)
+
+```
+create association MyModule.Project_Employees
+from MyModule.Project to MyModule.Employee
+type referenceset
+owner both;
+```
+
+**Expected:** Association created with `type ReferenceSet`, `owner Both`.
+
+### 10.3 Self-referencing association
+
+```
+create association MyModule.Category_Parent
+from MyModule.Category to MyModule.Category
+type reference
+owner default
+delete_behavior DELETE_BUT_KEEP_REFERENCES;
+```
+
+**Expected:** Association created. Parent and child are same entity.
+
+### 10.4 Cross-module association
+
+```
+create association MyModule.Account_User
+from MyModule.Account to Administration.Account
+type reference
+owner default;
+```
+
+**Expected:** Association created spanning two modules.
+
+### 10.5 With explicit storage
+
+```
+create association MyModule.Tag_Item
+from MyModule.Tag to MyModule.Item
+type reference
+owner default
+storage table;
+```
+
+**Expected:** Association uses table storage instead of column.
+
+> **Note:** `describe` omits `storage table` (only `show` reveals storage info).
+
+### 10.6 Delete behavior — CASCADE
+
+```
+create association MyModule.Parent_Child
+from MyModule.Parent to MyModule.Child
+type reference
+owner default
+delete_behavior CASCADE;
+```
+
+**Expected:** `describe` shows `DELETE_CASCADE`.
+
+> **Note:** `describe` outputs `DELETE_CASCADE` but parser accepts `CASCADE`. See BUG-001.
+
+### 10.7 Delete behavior — IF_NO_REFERENCES
+
+```
+create association MyModule.Strict_Ref
+from MyModule.A to MyModule.B
+type reference
+owner default
+delete_behavior DELETE_IF_NO_REFERENCES;
+```
+
+**Expected:** `describe` shows `DELETE_IF_NO_REFERENCES`.
+
+### 10.8 Duplicate association
+
+```
+create association MyModule.Order_Customer
+from MyModule.Order to MyModule.Customer
+type reference
+owner default;
+```
+
+**Expected:** **Known issue (BUG-002):** No duplicate detection for associations. Second create silently succeeds.
+
+---
+
+## 11. ALTER ASSOCIATION
+
+### 11.1 Change delete behavior
+
+```
+alter association MyModule.Order_Customer set delete_behavior CASCADE;
+```
+
+**Expected:** `describe` shows updated behavior (`DELETE_CASCADE` in output).
+
+### 11.2 Change owner
+
+```
+alter association MyModule.Order_Customer set owner both;
+```
+
+**Expected:** `describe` shows `owner Both`.
+
+### 11.3 Change storage
+
+```
+alter association MyModule.Order_Customer set storage table;
+```
+
+**Expected:** `describe` shows `storage table`.
+
+### 11.4 Set comment
+
+```
+alter association MyModule.Order_Customer set comment 'Links orders to customers';
+```
+
+**Expected:** `describe` shows documentation comment.
+
+---
+
+## 12. DROP ASSOCIATION
+
+### 12.1 Drop existing association
+
+```
+drop association MyModule.Order_Customer;
+```
+
+**Expected:** Association removed. `show association MyModule.Order_Customer` returns error.
+
+### 12.2 Drop non-existent association
+
+```
+drop association MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+### 12.3 Drop cross-module association
+
+```
+drop association MyModule.Account_User;
+```
+
+**Expected:** Cross-module association removed.
+
+---
+
+## 13. SHOW CONSTANTS
+
+### 13.1 List all constants
+
+```
+show constants;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Folder | Type | Default | Exposed`. Sorted alphabetically.
+
+### 13.2 List constants in a module
+
+```
+show constants in MyModule;
+```
+
+**Expected:** Only constants from `MyModule`.
+
+### 13.3 Empty module
+
+```
+show constants in NonExistentModule;
+```
+
+**Expected:** `No constants found.` or error.
+
+---
+
+## 14. SHOW CONSTANT VALUES
+
+### 14.1 All constant values
+
+```
+show constant values;
+```
+
+**Expected:** Table with columns `Constant | Configuration | Value`. One row per constant for `(default)`, additional rows per configuration override. Values truncated to 60 chars.
+
+### 14.2 Constants in a module
+
+```
+show constant values in MyModule;
+```
+
+**Expected:** Only constants from `MyModule`. Same format.
+
+---
+
+## 15. DESCRIBE CONSTANT
+
+### 15.1 String constant
+
+```
+describe constant MyModule.ServiceEndpoint;
+```
+
+**Expected:**
+```
+create or modify constant MyModule.ServiceEndpoint
+  type String
+  default 'https://api.example.com/v1'
+;
+/
+```
+
+### 15.2 Boolean constant
+
+```
+describe constant MyModule.EnableDebug;
+```
+
+**Expected:** `default true` or `default false` (unquoted).
+
+### 15.3 Constant with folder and comment
+
+```
+describe constant MyModule.MaxRetries;
+```
+
+**Expected:** Output includes `folder 'path/to/folder'` and `comment 'text'` if present.
+
+### 15.4 Exposed constant
+
+```
+describe constant MyModule.ExposedConst;
+```
+
+**Expected:** Output includes `exposed to client`.
+
+---
+
+## 16. CREATE CONSTANT
+
+### 16.1 String constant
+
+```
+create constant MyModule.ServiceEndpoint type String default 'https://api.example.com/v1';
+```
+
+**Expected:** Constant created. `describe` matches.
+
+### 16.2 Integer constant
+
+```
+create constant MyModule.MaxRetries type Integer default 3;
+```
+
+**Expected:** Constant created with integer type and value.
+
+### 16.3 Long constant
+
+```
+create constant MyModule.MaxFileSize type Long default 10485760 comment 'Max upload 10MB';
+```
+
+**Expected:** Constant with comment.
+
+> **Note:** Long type maps to Integer. No distinct Long constant type exists.
+
+### 16.4 Decimal constant
+
+```
+create constant MyModule.TaxRate type Decimal default 0.21;
+```
+
+**Expected:** Decimal value preserved.
+
+### 16.5 Boolean constant
+
+```
+create constant MyModule.EnableDebug type Boolean default false;
+```
+
+**Expected:** Boolean constant created.
+
+### 16.6 DateTime constant
+
+```
+create constant MyModule.LaunchDate type DateTime default '[%BeginOfCurrentDay%]';
+```
+
+**Expected:** DateTime constant with token expression.
+
+### 16.7 Enumeration constant
+
+```
+create constant MyModule.DefaultStatus type Enumeration(MyModule.Status) default 'Active';
+```
+
+**Expected:** Constant with enumeration type.
+
+### 16.8 With folder
+
+```
+create constant MyModule.Nested type String default 'value' folder 'Config/SubFolder';
+```
+
+**Expected:** Constant placed in specified folder. Folder auto-created if missing.
+
+### 16.9 Exposed to client
+
+```
+create constant MyModule.ClientConst type String default 'visible' exposed to client;
+```
+
+**Expected:** `describe` shows `exposed to client`.
+
+### 16.10 `create or modify` — existing constant
+
+```
+create or modify constant MyModule.MaxRetries type Integer default 5 comment 'Updated';
+```
+
+**Expected:** Updates existing constant value and comment.
+
+### 16.11 Duplicate constant (without `or modify`)
+
+```
+create constant MyModule.MaxRetries type Integer default 3;
+```
+
+**Expected:** Error — constant already exists.
+
+### 16.12 With documentation comment
+
+```
+/** Maximum number of API retry attempts */
+create constant MyModule.ApiRetries type Integer default 3;
+```
+
+**Expected:** Constant created with doc comment.
+
+---
+
+## 17. DROP CONSTANT
+
+### 17.1 Drop existing constant
+
+```
+drop constant MyModule.ServiceEndpoint;
+```
+
+**Expected:** Constant removed.
+
+### 17.2 Drop non-existent constant
+
+```
+drop constant MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 18. ROUNDTRIP (BSON)
+
+Test that CREATE → DESCRIBE → CREATE (from output) produces identical results.
+
+### 18.1 Entity roundtrip
+
+```
+create persistent entity RtTest.Employee (
+  Name: string(200) not null,
+  Salary: decimal default 0.00,
+  Active: boolean default true
+)
+index (Name);
+```
+
+1. Run `describe entity RtTest.Employee`
+2. Copy output (removing leading `create or modify` → just `create`)
+3. Drop entity: `drop entity RtTest.Employee`
+4. Execute copied MDL
+5. Run `describe` again
+
+**Expected:** Output identical between step 1 and step 5.
+
+### 18.2 Association roundtrip
+
+```
+create association RtTest.Emp_Dept
+from RtTest.Employee to RtTest.Department
+type reference
+owner default
+delete_behavior DELETE_CASCADE;
+```
+
+1. `describe association RtTest.Emp_Dept`
+2. Drop: `drop association RtTest.Emp_Dept`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+> **Known issue (BUG-001):** Association roundtrip broken. `describe` outputs `DELETE_CASCADE` but parser only accepts `CASCADE`.
+
+### 18.3 Constant roundtrip
+
+```
+create constant RtTest.ApiKey type String default 'sk-test-123' comment 'Test key' exposed to client;
+```
+
+1. `describe constant RtTest.ApiKey`
+2. Drop: `drop constant RtTest.ApiKey`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Identical output.
+
+---
+
+## 19. CATALOG INTEGRATION
+
+### 19.1 Entity in catalog
+
+```
+refresh catalog;
+select * from CATALOG.ENTITIES where name = 'Account';
+```
+
+**Expected:** Entity appears in catalog with correct module, type, attribute count.
+
+> **Known issue (BUG-003):** Catalog SELECT currently returns empty results.
+
+### 19.2 Association in catalog
+
+```
+select * from CATALOG.ASSOCIATIONS where parent_entity = 'MyModule.Order';
+```
+
+**Expected:** Empty result or error — table not implemented.
+
+### 19.3 References for entity
+
+```
+show references to Administration.Account;
+```
+
+**Expected:** Lists microflows, pages, and other documents referencing this entity.
+
+> **Known issue (BUG-003):** Catalog SELECT currently returns empty results.
+
+---
+
+## 20. MULTI-STEP WORKFLOWS
+
+### 20.1 Create entity → add association → grant access
+
+```
+create persistent entity MyModule.Product (
+  Name: string(200) not null,
+  Price: decimal default 0
+);
+
+create persistent entity MyModule.Category (
+  Label: string(100)
+);
+
+create association MyModule.Product_Category
+from MyModule.Product to MyModule.Category
+type reference
+owner default;
+
+create module role MyModule.Manager;
+grant Manager on MyModule.Product (create, delete, read *, write *);
+grant Manager on MyModule.Category (read *);
+```
+
+**Expected:** All statements succeed. `show entities in MyModule` shows both entities with correct association count.
+
+### 20.2 Create constant → modify → verify
+
+```
+create constant MyModule.Timeout type Integer default 30;
+create or modify constant MyModule.Timeout type Integer default 60 comment 'Increased timeout';
+describe constant MyModule.Timeout;
+```
+
+**Expected:** Final `describe` shows `default 60` and comment.
+
+---
+
+## 21. FAILURE MODES & ERROR RECOVERY
+
+### 21.1 Invalid attribute type
+
+```
+create persistent entity MyModule.Bad (
+  Value: invalidtype
+);
+```
+
+**Expected:** Unknown types are silently interpreted as enumeration references (BUG-009). No error raised.
+
+### 21.2 Missing module qualification
+
+```
+create persistent entity UnqualifiedName (
+  X: integer
+);
+```
+
+**Expected:** Error — module name required.
+
+### 21.3 Alter non-existent attribute
+
+```
+alter entity MyModule.Product drop attribute FakeAttr;
+```
+
+**Expected:** Error — attribute not found.
+
+### 21.4 Create association with missing entity
+
+```
+create association MyModule.Bad_Ref
+from MyModule.Nonexistent to MyModule.Product
+type reference
+owner default;
+```
+
+**Expected:** Error — parent entity not found.
+
+### 21.5 Invalid OQL in view entity
+
+```
+create view entity MyModule.BadView (
+  X: integer
+) as
+  select invalid syntax here;
+```
+
+**Expected:** Entity created (OQL not validated at create time). View entity stored with invalid OQL as raw text.
+
+### 21.6 Drop entity referenced by association
+
+```
+drop entity MyModule.Customer;
+```
+
+**Expected:** Entity silently dropped without warning. Associations may become orphaned.
+
+---
+
+## 22. BOUNDARY & STRESS
+
+### 22.1 Entity with many attributes (50+)
+
+Create an entity with 50 attributes. Verify `show` and `describe` handle large attribute lists.
+
+### 22.2 Long attribute names
+
+```
+create persistent entity MyModule.LongNames (
+  ThisIsAVeryLongAttributeNameThatExceedsNormalLength: string(200)
+);
+```
+
+**Expected:** Created and displayed correctly.
+
+### 22.3 String constant with special characters
+
+```
+create constant MyModule.Special type String default 'it''s a "test" with\nnewlines';
+```
+
+**Expected:** Escaped characters preserved in describe output.
+
+### 22.4 Maximum string length
+
+```
+create persistent entity MyModule.MaxLen (
+  BigText: string(1048576)
+);
+```
+
+**Expected:** Entity created (or error if max exceeded).
+
+### 22.5 Many associations on one entity
+
+Create 10+ associations from one entity to different targets. Verify `show associations` and entity describe handle them.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW ENTITIES | x | x | x |
+| SHOW ENTITY | x | x | x |
+| DESCRIBE ENTITY | x | x | x |
+| CREATE ENTITY | x | | |
+| ALTER ENTITY | x | | |
+| DROP ENTITY | x | | |
+| SHOW ASSOCIATIONS | x | x | x |
+| DESCRIBE ASSOCIATION | x | x | |
+| CREATE ASSOCIATION | x | | |
+| ALTER ASSOCIATION | x | | |
+| DROP ASSOCIATION | x | | |
+| SHOW CONSTANTS | x | x | x |
+| SHOW CONSTANT VALUES | x | x | |
+| DESCRIBE CONSTANT | x | x | |
+| CREATE CONSTANT | x | | |
+| DROP CONSTANT | x | | |
+
+Read operations tested on all projects. Write operations on copies of one project.
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW ENTITIES | Mock tests | |
+| 2. SHOW ENTITY | Mock tests | |
+| 3. DESCRIBE ENTITY | Mock tests | |
+| 4. CREATE ENTITY | Mock + roundtrip | |
+| 5. ALTER ENTITY | Mock tests | Multi-action |
+| 6. DROP ENTITY | Mock tests | |
+| 7–9. SHOW/DESCRIBE ASSOCIATION | Mock tests | |
+| 10. CREATE ASSOCIATION | Mock tests | Cross-module |
+| 11. ALTER ASSOCIATION | Mock tests | |
+| 12. DROP ASSOCIATION | Mock tests | |
+| 13–14. SHOW CONSTANTS | Mock tests | |
+| 15. DESCRIBE CONSTANT | Mock tests | |
+| 16. CREATE CONSTANT | Mock tests | |
+| 17. DROP CONSTANT | Mock tests | |
+| 18. Roundtrip | Roundtrip tests | Complex entities |
+| 19. Catalog | | All manual |
+| 20. Multi-step | | All manual |
+| 21. Failure modes | Partial | Edge cases |
+| 22. Boundary | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW ENTITIES | List all | | | | |
+| 1.2 | SHOW ENTITIES | Filter by module | | | | |
+| 1.3 | SHOW ENTITIES | Generalization column | | | | |
+| 1.4 | SHOW ENTITIES | Empty module | | | | |
+| 1.5 | SHOW ENTITIES | Entity types | | | | |
+| 2.1 | SHOW ENTITY | Persistent | | | | |
+| 2.2 | SHOW ENTITY | Non-persistent | | | | |
+| 2.3 | SHOW ENTITY | Not found | | | | |
+| 3.1 | DESCRIBE | Basic | | | | |
+| 3.2 | DESCRIBE | All features | | | | |
+| 3.3 | DESCRIBE | View entity | | | | |
+| 3.4 | DESCRIBE | Not found | | | | |
+| 4.1 | CREATE | Minimal persistent | | | | |
+| 4.2 | CREATE | All types | | | | |
+| 4.3 | CREATE | Generalization | | | | |
+| 4.4 | CREATE | Non-persistent | | | | |
+| 4.5 | CREATE | With indexes | | | | |
+| 4.6 | CREATE | Event handlers | | | | |
+| 4.7 | CREATE | System attributes | | | | |
+| 4.8 | CREATE | create or modify (new) | | | | |
+| 4.9 | CREATE | create or modify (update) | | | | |
+| 4.10 | CREATE | Duplicate error | | | | |
+| 4.11 | CREATE | View entity | | | | |
+| 4.12 | CREATE | create or replace view | | | | |
+| 4.13 | CREATE | Position annotation | | | | |
+| 5.1 | ALTER | Add attribute | | | | |
+| 5.2 | ALTER | Rename attribute | | | | |
+| 5.3 | ALTER | Modify type | | | | |
+| 5.4 | ALTER | Drop attribute | | | | |
+| 5.5 | ALTER | Set documentation | | | | |
+| 5.6 | ALTER | Set position | | | | |
+| 5.7 | ALTER | Add index | | | | |
+| 5.8 | ALTER | Drop index | | | | |
+| 5.9 | ALTER | Add event handler | | | | |
+| 5.10 | ALTER | Drop event handler | | | | |
+| 5.11 | ALTER | Multiple actions | | | | |
+| 5.12 | ALTER | Drop pseudo-attribute | | | | |
+| 5.13 | ALTER | Make calculated | | | | |
+| 6.1 | DROP ENTITY | Existing | | | | |
+| 6.2 | DROP ENTITY | Non-existent | | | | |
+| 6.3 | DROP ENTITY | View entity | | | | |
+| 6.4 | DROP ENTITY | With references | | | | |
+| 7.1 | SHOW ASSOC | List all | | | | |
+| 7.2 | SHOW ASSOC | Filter module | | | | |
+| 7.3 | SHOW ASSOC | Cross-module | | | | |
+| 8.1 | SHOW ASSOC | Single basic | | | | |
+| 8.2 | SHOW ASSOC | Single cross-module | | | | |
+| 8.3 | SHOW ASSOC | Not found | | | | |
+| 9.1 | DESCRIBE ASSOC | Reference | | | | |
+| 9.2 | DESCRIBE ASSOC | ReferenceSet | | | | |
+| 9.3 | DESCRIBE ASSOC | With documentation | | | | |
+| 10.1 | CREATE ASSOC | Basic reference | | | | |
+| 10.2 | CREATE ASSOC | ReferenceSet | | | | |
+| 10.3 | CREATE ASSOC | Self-referencing | | | | |
+| 10.4 | CREATE ASSOC | Cross-module | | | | |
+| 10.5 | CREATE ASSOC | Explicit storage | | | | |
+| 10.6 | CREATE ASSOC | DELETE_CASCADE | | | | |
+| 10.7 | CREATE ASSOC | DELETE_IF_NO_REFERENCES | | | | |
+| 10.8 | CREATE ASSOC | Duplicate error | | | | |
+| 11.1 | ALTER ASSOC | Delete behavior | | | | |
+| 11.2 | ALTER ASSOC | Change owner | | | | |
+| 11.3 | ALTER ASSOC | Change storage | | | | |
+| 11.4 | ALTER ASSOC | Set comment | | | | |
+| 12.1 | DROP ASSOC | Existing | | | | |
+| 12.2 | DROP ASSOC | Non-existent | | | | |
+| 12.3 | DROP ASSOC | Cross-module | | | | |
+| 13.1 | SHOW CONST | List all | | | | |
+| 13.2 | SHOW CONST | Filter module | | | | |
+| 13.3 | SHOW CONST | Empty module | | | | |
+| 14.1 | CONST VALUES | All values | | | | |
+| 14.2 | CONST VALUES | Filter module | | | | |
+| 15.1 | DESCRIBE CONST | String | | | | |
+| 15.2 | DESCRIBE CONST | Boolean | | | | |
+| 15.3 | DESCRIBE CONST | With folder/comment | | | | |
+| 15.4 | DESCRIBE CONST | Exposed | | | | |
+| 16.1 | CREATE CONST | String | | | | |
+| 16.2 | CREATE CONST | Integer | | | | |
+| 16.3 | CREATE CONST | Long | | | | |
+| 16.4 | CREATE CONST | Decimal | | | | |
+| 16.5 | CREATE CONST | Boolean | | | | |
+| 16.6 | CREATE CONST | DateTime | | | | |
+| 16.7 | CREATE CONST | Enumeration | | | | |
+| 16.8 | CREATE CONST | With folder | | | | |
+| 16.9 | CREATE CONST | Exposed | | | | |
+| 16.10 | CREATE CONST | create or modify | | | | |
+| 16.11 | CREATE CONST | Duplicate error | | | | |
+| 16.12 | CREATE CONST | Doc comment | | | | |
+| 17.1 | DROP CONST | Existing | | | | |
+| 17.2 | DROP CONST | Non-existent | | | | |
+| 18.1 | ROUNDTRIP | Entity | | | | |
+| 18.2 | ROUNDTRIP | Association | | | | |
+| 18.3 | ROUNDTRIP | Constant | | | | |
+| 19.1 | CATALOG | Entity in catalog | | | | |
+| 19.2 | CATALOG | Association in catalog | | | | |
+| 19.3 | CATALOG | Callers | | | | |
+| 20.1 | MULTI-STEP | Entity + assoc + access | | | | |
+| 20.2 | MULTI-STEP | Constant modify chain | | | | |
+| 21.1 | FAILURE | Invalid type | | | | |
+| 21.2 | FAILURE | Missing module | | | | |
+| 21.3 | FAILURE | Alter non-existent attr | | | | |
+| 21.4 | FAILURE | Missing entity in assoc | | | | |
+| 21.5 | FAILURE | Invalid OQL | | | | |
+| 21.6 | FAILURE | Drop referenced entity | | | | |
+| 22.1 | BOUNDARY | Many attributes | | | | |
+| 22.2 | BOUNDARY | Long names | | | | |
+| 22.3 | BOUNDARY | Special characters | | | | |
+| 22.4 | BOUNDARY | Max string length | | | | |
+| 22.5 | BOUNDARY | Many associations | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/enumeration-test-cases.md b/docs/15-testing/enumeration-test-cases.md
new file mode 100644
index 00000000..1f35cc1d
--- /dev/null
+++ b/docs/15-testing/enumeration-test-cases.md
@@ -0,0 +1,525 @@
+# Enumeration Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Enumerations |
+|-----|-----------|--------------|
+| Lato Enquiry Management | 11.4.0 | 74 |
+| Evora - Factory Management | 10.24.15 | 113 |
+| Lato Product Inventory | 11.2.0 | 92 |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show enumerations;" > /tmp/show-enum.mdl
+  mxcli exec /tmp/show-enum.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N enumerations)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Dropped enumerations cannot be recovered.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW ENUMERATIONS
+
+### 1.1 List all enumerations
+
+```
+show enumerations;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Folder | Values`. Summary `(N enumerations)`. Sorted alphabetically.
+
+### 1.2 List enumerations in a module
+
+```
+show enumerations in Administration;
+```
+
+**Expected:** Only enumerations from `Administration` module.
+
+> (Note: Administration may have 0 enumerations. Use a module with enumerations like `AgentCommons` for a more illustrative test.)
+
+### 1.3 Empty module
+
+```
+show enumerations in NonExistentModule;
+```
+
+**Expected:** Empty result or `(0 enumerations)`.
+
+---
+
+## 2. DESCRIBE ENUMERATION
+
+### 2.1 Basic enumeration
+
+Use any existing enumeration in the project (e.g., `AgentCore.Enum_StatusGeneral`):
+
+```
+describe enumeration AgentCore.Enum_StatusGeneral;
+```
+
+**Expected:** `create or modify enumeration ...` block with value names and captions, terminated by `/`.
+
+### 2.2 Enumeration with documentation
+
+> **Note:** Create a documented enumeration first (see §3.2), then describe it. No test project has pre-existing documented enumerations.
+
+**Expected:** Output starts with `/** ... */` documentation block.
+
+### 2.3 Enumeration with value documentation
+
+> **Note:** Create a documented enumeration first (see §3.2), then describe it. No test project has pre-existing documented enumerations.
+
+**Expected:** Per-value doc comments: `/** Order received, awaiting processing */` above value.
+
+### 2.4 Non-existent enumeration
+
+```
+describe enumeration Fake.Missing;
+```
+
+**Expected:** Error — enumeration not found.
+
+---
+
+## 3. CREATE ENUMERATION
+
+### 3.1 Simple enumeration
+
+```
+create enumeration MyModule.Color (
+  RED 'Red',
+  GREEN 'Green',
+  BLUE 'Blue'
+);
+```
+
+**Expected:** `Created enumeration: MyModule.Color`. `show enumerations in MyModule` includes it with `Values: 3`.
+
+### 3.2 Enumeration with documentation
+
+```
+/** Priority levels for task ordering */
+create enumeration MyModule.Priority (
+  /** Highest urgency */
+  CRITICAL 'Critical',
+  HIGH 'High',
+  MEDIUM 'Medium',
+  LOW 'Low'
+);
+```
+
+**Expected:** Created. `describe` shows documentation blocks.
+
+> **Known issue (BUG-004):** Documentation blocks (`/** */`) are NOT preserved on roundtrip. Describe output omits documentation.
+
+### 3.3 Single-value enumeration
+
+```
+create enumeration MyModule.YesNo (
+  YES 'Yes'
+);
+```
+
+**Expected:** Created with 1 value.
+
+### 3.4 Quoted identifier (reserved word)
+
+```
+create enumeration MyModule.UserType (
+  "user" 'Standard User',
+  ADMIN 'Administrator'
+);
+```
+
+**Expected:** Created. Value name `user` (reserved word) accepted when quoted.
+
+### 3.5 Reserved word — unquoted
+
+```
+create enumeration MyModule.BadEnum (
+  class 'Class Value'
+);
+```
+
+**Expected:** Error (CE7247) — `enumeration value 'class' is a reserved word`.
+
+### 3.6 Other reserved words
+
+Test these unquoted values trigger CE7247:
+
+> **Note:** Error messages may append a spurious hint: `"hint: ... is defined later in this script"` even for single statements. Ignore this hint.
+
+| Value | Reserved |
+|-------|----------|
+| `null` | Java keyword |
+| `true` | Java keyword |
+| `enum` | Java keyword |
+| `context` | Mendix reserved |
+| `guid` | Mendix reserved |
+| `changeddate` | Mendix reserved |
+| `currentuser` | Mendix reserved |
+
+### 3.7 `create or modify` — new enumeration
+
+```
+create or modify enumeration MyModule.Fresh (
+  A 'Alpha',
+  B 'Beta'
+);
+```
+
+**Expected:** Creates enumeration (same as without `or modify`).
+
+### 3.8 `create or modify` — existing enumeration
+
+```
+create or modify enumeration MyModule.Color (
+  RED 'Red',
+  GREEN 'Green',
+  BLUE 'Blue',
+  YELLOW 'Yellow'
+);
+```
+
+**Expected:** Replaces existing enumeration. Output says `Created enumeration: MyModule.Color`. `describe` shows 4 values.
+
+> **Note:** `create or modify` outputs "Created enumeration:" for both new and update operations.
+
+### 3.9 Duplicate (without `or modify`)
+
+```
+create enumeration MyModule.Color (
+  X 'X'
+);
+```
+
+**Expected:** Error — `enumeration already exists: MyModule.Color (use create or modify to update)`.
+
+### 3.10 Module auto-creation
+
+```
+create enumeration NewModule.Status (
+  ACTIVE 'Active'
+);
+```
+
+**Expected:** Both module and enumeration created.
+
+---
+
+## 4. DROP ENUMERATION
+
+### 4.1 Drop existing enumeration
+
+```
+drop enumeration MyModule.Color;
+```
+
+**Expected:** `Dropped enumeration: MyModule.Color`.
+
+### 4.2 Drop non-existent enumeration
+
+```
+drop enumeration MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+### 4.3 Drop by name only (no module qualifier)
+
+```
+drop enumeration Color;
+```
+
+**Expected:** Matches by name if unambiguous. Error if multiple enumerations share name.
+
+#### 4.3.1 Ambiguous unqualified name
+
+**Setup:**
+
+```
+create enumeration ModuleA.Status (
+  ACTIVE 'Active',
+  INACTIVE 'Inactive'
+);
+
+create enumeration ModuleB.Status (
+  OPEN 'Open',
+  CLOSED 'Closed'
+);
+```
+
+**Test:**
+
+```
+drop enumeration Status;
+```
+
+> **Known issue (BUG-006):** Ambiguous unqualified name silently drops first match instead of erroring.
+
+---
+
+## 5. ROUNDTRIP (BSON)
+
+### 5.1 Enumeration roundtrip
+
+```
+create enumeration RtTest.Status (
+  ACTIVE 'Active',
+  INACTIVE 'Inactive',
+  ARCHIVED 'Archived'
+);
+```
+
+1. `describe enumeration RtTest.Status`
+2. Drop: `drop enumeration RtTest.Status`
+3. Execute described MDL (change `create or modify` to `create`)
+4. `describe` again
+
+**Expected:** Output identical between step 1 and step 4.
+
+### 5.2 Roundtrip with documentation
+
+```
+/** Payment status tracking */
+create enumeration RtTest.PayStatus (
+  /** Awaiting payment */
+  PENDING 'Pending',
+  PAID 'Paid',
+  REFUNDED 'Refunded'
+);
+```
+
+1. `describe` → drop → recreate from output → `describe`
+
+**Expected:** Documentation preserved through roundtrip.
+
+> **Known issue (BUG-004):** Documentation lost on roundtrip.
+
+---
+
+## 6. MULTI-STEP WORKFLOWS
+
+### 6.1 Create enumeration → use in entity
+
+```
+create enumeration MyModule.TaskStatus (
+  TODO 'To Do',
+  IN_PROGRESS 'In Progress',
+  DONE 'Done'
+);
+
+create persistent entity MyModule.Task (
+  Title: string(200) not null,
+  Status: enumeration(MyModule.TaskStatus) default MyModule.TaskStatus.TODO
+);
+```
+
+**Expected:** Both created. Entity attribute references enumeration. `describe entity` shows `enumeration(MyModule.TaskStatus)`.
+
+### 6.2 Replace enumeration → verify entity still works
+
+```
+create or modify enumeration MyModule.TaskStatus (
+  TODO 'To Do',
+  IN_PROGRESS 'In Progress',
+  DONE 'Done',
+  BLOCKED 'Blocked'
+);
+
+describe entity MyModule.Task;
+```
+
+**Expected:** Entity still references `MyModule.TaskStatus`. New value `BLOCKED` available.
+
+---
+
+## 7. FAILURE MODES & ERROR RECOVERY
+
+### 7.1 Empty value list
+
+```
+create enumeration MyModule.Empty ();
+```
+
+**Expected:** Error — at least one value required (or parser error).
+
+### 7.2 Duplicate value names
+
+```
+create enumeration MyModule.Dup (
+  A 'First',
+  A 'Second'
+);
+```
+
+**Expected:** Error — duplicate value name.
+
+> **Known issue (BUG-005):** Duplicate value names accepted without error. Both values stored.
+
+### 7.3 Drop enumeration used by entity attribute
+
+```
+drop enumeration MyModule.TaskStatus;
+```
+
+**Expected:** Enumeration dropped (no referential integrity enforcement — may leave entity attribute orphaned). Verify `describe entity MyModule.Task` still works but shows broken reference or generic type.
+
+### 7.4 Case sensitivity in reserved word check
+
+```
+create enumeration MyModule.CaseTest (
+  NULL 'Null Value',
+  True 'True Value'
+);
+```
+
+**Expected:** Error — reserved word check is case-insensitive.
+
+---
+
+## 8. BOUNDARY & STRESS
+
+### 8.1 Many values (50+)
+
+Create an enumeration with 50 values. Verify `show` and `describe` handle it.
+
+### 8.2 Long captions
+
+```
+create enumeration MyModule.LongCaptions (
+  VAL1 'This is a very long caption that exceeds what would normally be displayed in a UI dropdown'
+);
+```
+
+**Expected:** Created and described correctly.
+
+### 8.3 Special characters in captions
+
+```
+create enumeration MyModule.Special (
+  A 'It''s a "test" value',
+  B 'Line1\nLine2'
+);
+```
+
+**Expected:** Escaped characters preserved in describe output.
+
+> **Known issue (BUG-007):** Single quotes in captions not escaped in describe output (`It's` instead of `It''s`). Breaks roundtrip.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW ENUMERATIONS | x | x | x |
+| DESCRIBE ENUMERATION | x | x | x |
+| CREATE ENUMERATION | x | | |
+| DROP ENUMERATION | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW ENUMERATIONS | Mock tests | |
+| 2. DESCRIBE ENUMERATION | Mock tests | |
+| 3. CREATE ENUMERATION | Mock tests | Reserved words, quoted identifiers |
+| 4. DROP ENUMERATION | Mock tests | |
+| 5. Roundtrip | | All manual |
+| 6. Multi-step | | All manual |
+| 7. Failure modes | Partial (reserved) | Empty list, duplicates |
+| 8. Boundary | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW | List all | | | | |
+| 1.2 | SHOW | Filter module | | | | |
+| 1.3 | SHOW | Empty module | | | | |
+| 2.1 | DESCRIBE | Basic | | | | |
+| 2.2 | DESCRIBE | With documentation | | | | |
+| 2.3 | DESCRIBE | Value documentation | | | | |
+| 2.4 | DESCRIBE | Not found | | | | |
+| 3.1 | CREATE | Simple | | | | |
+| 3.2 | CREATE | With documentation | | | | |
+| 3.3 | CREATE | Single value | | | | |
+| 3.4 | CREATE | Quoted reserved word | | | | |
+| 3.5 | CREATE | Unquoted reserved word | | | | |
+| 3.6 | CREATE | Other reserved words | | | | |
+| 3.7 | CREATE | create or modify (new) | | | | |
+| 3.8 | CREATE | create or modify (update) | | | | |
+| 3.9 | CREATE | Duplicate error | | | | |
+| 3.10 | CREATE | Module auto-creation | | | | |
+| 4.1 | DROP | Existing | | | | |
+| 4.2 | DROP | Non-existent | | | | |
+| 4.3 | DROP | By name only | | | | |
+| 5.1 | ROUNDTRIP | Basic | | | | |
+| 5.2 | ROUNDTRIP | With documentation | | | | |
+| 6.1 | MULTI-STEP | Create + use in entity | | | | |
+| 6.2 | MULTI-STEP | Replace + verify entity | | | | |
+| 7.1 | FAILURE | Empty value list | | | | |
+| 7.2 | FAILURE | Duplicate values | | | | |
+| 7.3 | FAILURE | Drop used enumeration | | | | |
+| 7.4 | FAILURE | Case-insensitive reserved | | | | |
+| 8.1 | BOUNDARY | Many values | | | | |
+| 8.2 | BOUNDARY | Long captions | | | | |
+| 8.3 | BOUNDARY | Special characters | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/image-collection-test-cases.md b/docs/15-testing/image-collection-test-cases.md
new file mode 100644
index 00000000..c8b352a8
--- /dev/null
+++ b/docs/15-testing/image-collection-test-cases.md
@@ -0,0 +1,468 @@
+# Image Collection Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Image Collections |
+|-----|------------|--------------------|
+| Lato Enquiry Management | 11.4.0 | — |
+| Evora - Factory Management | 10.24.15 | — |
+| Lato Product Inventory | 11.2.0 | — |
+
+---
+
+## Setup
+
+### 1. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 2. Prepare test images
+
+```bash
+mkdir -p /tmp/mxcli-test-images
+convert -size 32x32 xc:red /tmp/mxcli-test-images/logo.png
+convert -size 32x32 xc:blue /tmp/mxcli-test-images/icon.png
+echo '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"/>' > /tmp/mxcli-test-images/vector.svg
+```
+
+### 3. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Dropped image collections cannot be recovered.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW IMAGE COLLECTION
+
+### 1.1 List all image collections
+
+```
+show image collections;
+```
+
+**Expected:** Table with columns `Image Collection | Export Level | Images`. Summary `(N image collections)`.
+
+### 1.2 Filter by module
+
+```
+show image collections in Administration;
+```
+
+**Expected:** Only image collections from `Administration` module.
+
+### 1.3 Empty module
+
+```
+show image collections in NonExistentModule;
+```
+
+**Expected:** Empty result or `(0 image collections)`.
+
+---
+
+## 2. DESCRIBE IMAGE COLLECTION
+
+### 2.1 Basic describe
+
+```
+describe image collection MyModule.Icons;
+```
+
+**Expected:**
+```
+create or replace image collection MyModule.Icons export level 'Public' (
+  image logo from file 'logo.png',
+  image icon from file 'icon.svg'
+);
+/
+```
+
+### 2.2 Image extraction to disk
+
+```
+describe image collection MyModule.Icons;
+```
+
+**Expected:** Images extracted to `/tmp/mxcli-preview/MyModule.Icons/`. Each image file present with original format.
+
+### 2.3 Supported formats
+
+Verify `describe` correctly identifies format for each type:
+
+| Extension | Format |
+|-----------|--------|
+| `.png` | Png (default) |
+| `.svg` | Svg |
+| `.gif` | Gif |
+| `.jpg` | Jpg |
+| `.bmp` | Bmp |
+| `.webp` | Webp |
+
+### 2.4 Non-existent image collection
+
+```
+describe image collection Fake.Missing;
+```
+
+**Expected:** Error — image collection not found.
+
+---
+
+## 3. CREATE IMAGE COLLECTION
+
+### 3.1 Empty collection
+
+```
+create image collection MyModule.EmptyIcons;
+```
+
+**Expected:** `Created image collection: MyModule.EmptyIcons`. `show image collections in MyModule` lists it with `Images: 0`.
+
+### 3.2 Collection with images
+
+```
+create image collection MyModule.AppIcons export level 'Public' comment 'Application icons' (
+  image logo from file '/tmp/mxcli-test-images/logo.png',
+  image icon from file '/tmp/mxcli-test-images/vector.svg'
+);
+```
+
+**Expected:** Created with 2 images. `describe` shows both images with correct formats.
+
+### 3.3 Hidden export level (default)
+
+```
+create image collection MyModule.HiddenIcons (
+  image logo from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Created. `show image collections` shows `Export Level: Hidden`.
+
+### 3.4 Public export level
+
+```
+create image collection MyModule.PublicIcons export level 'Public' (
+  image logo from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Created. `show image collections` shows `Export Level: Public`.
+
+### 3.5 Format auto-detection from extension
+
+Create collections with each supported format. Verify `describe` output shows correct format.
+
+| File | Detected Format |
+|------|-----------------|
+| `image.png` | Png |
+| `image.svg` | Svg |
+| `image.gif` | Gif |
+| `image.jpg` | Jpg |
+| `image.bmp` | Bmp |
+| `image.webp` | Webp |
+
+### 3.6 `create or replace` — new collection
+
+```
+create or replace image collection MyModule.Fresh (
+  image a from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Creates collection (same as without `or replace`).
+
+### 3.7 `create or replace` — existing collection
+
+```
+create or replace image collection MyModule.Fresh (
+  image a from file '/tmp/mxcli-test-images/logo.png',
+  image b from file '/tmp/mxcli-test-images/icon.png'
+);
+```
+
+**Expected:** Replaces existing collection. `describe` shows 2 images.
+
+### 3.8 Duplicate (without `or replace`)
+
+```
+create image collection MyModule.Fresh (
+  image x from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Error — image collection already exists.
+
+### 3.9 Module auto-creation
+
+```
+create image collection NewModule.Icons (
+  image logo from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Both module and image collection created.
+
+---
+
+## 4. DROP IMAGE COLLECTION
+
+### 4.1 Drop existing collection
+
+```
+drop image collection MyModule.AppIcons;
+```
+
+**Expected:** `Dropped image collection: MyModule.AppIcons`.
+
+### 4.2 Drop non-existent collection
+
+```
+drop image collection MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 5. ROUNDTRIP
+
+### 5.1 Create → Describe → Recreate
+
+1. Create collection with images (3.2)
+2. `describe image collection MyModule.AppIcons` — save output
+3. `drop image collection MyModule.AppIcons`
+4. Execute saved describe output (change `create or replace` to `create`)
+5. `describe` again
+
+**Expected:** Output identical between step 2 and step 5. Extracted image files match.
+
+---
+
+## 6. FAILURE MODES
+
+### 6.1 Not connected
+
+Run any command without `-p` or `connect`.
+
+**Expected:** Error — not connected to a project.
+
+### 6.2 File not found
+
+```
+create image collection MyModule.Bad (
+  image missing from file '/tmp/does-not-exist.png'
+);
+```
+
+**Expected:** Error — file not found.
+
+### 6.3 Invalid image format
+
+```
+create image collection MyModule.Bad (
+  image broken from file '/tmp/mxcli-test-images/notanimage.txt'
+);
+```
+
+**Expected:** Error — unsupported image format.
+
+### 6.4 Backend create failure
+
+Simulate backend failure (e.g., corrupt MPR, disk full).
+
+**Expected:** Error from backend layer with descriptive message.
+
+### 6.5 Preview directory creation failure
+
+If `/tmp/mxcli-preview/` is not writable:
+
+```
+describe image collection MyModule.Icons;
+```
+
+**Expected:** Error creating preview directory.
+
+---
+
+## 7. BOUNDARY & STRESS
+
+### 7.1 Large image file
+
+Create a collection with a large image (10 MB+ PNG).
+
+```
+create image collection MyModule.LargeIcons (
+  image big from file '/tmp/mxcli-test-images/large-10mb.png'
+);
+```
+
+**Expected:** Collection created. `describe` extracts image correctly. Verify file size preserved.
+
+### 7.2 Many images in one collection
+
+Create a collection with 50+ images.
+
+```
+create image collection MyModule.ManyIcons (
+  image img001 from file '/tmp/mxcli-test-images/logo.png',
+  image img002 from file '/tmp/mxcli-test-images/icon.png',
+  ...
+  image img050 from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** All 50 images stored. `show image collections` reports correct count. `describe` extracts all files.
+
+### 7.3 Image with special characters in name
+
+```
+create image collection MyModule.SpecialIcons (
+  image my_icon_v2 from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Image name with underscores accepted. Verify no name sanitization issues.
+
+### 7.4 Empty image file
+
+Create a 0-byte file and attempt to import:
+
+```bash
+touch /tmp/mxcli-test-images/empty.png
+```
+
+```
+create image collection MyModule.EmptyFile (
+  image empty from file '/tmp/mxcli-test-images/empty.png'
+);
+```
+
+**Expected:** Error or warning about empty/invalid image data.
+
+### 7.5 Duplicate image names in one collection
+
+```
+create image collection MyModule.DupeIcons (
+  image logo from file '/tmp/mxcli-test-images/logo.png',
+  image logo from file '/tmp/mxcli-test-images/icon.png'
+);
+```
+
+**Expected:** Error — duplicate image name within collection.
+
+### 7.6 All supported formats in one collection
+
+```
+create image collection MyModule.AllFormats export level 'Public' (
+  image png_img from file '/tmp/mxcli-test-images/test.png',
+  image svg_img from file '/tmp/mxcli-test-images/test.svg',
+  image gif_img from file '/tmp/mxcli-test-images/test.gif',
+  image jpg_img from file '/tmp/mxcli-test-images/test.jpg',
+  image bmp_img from file '/tmp/mxcli-test-images/test.bmp',
+  image webp_img from file '/tmp/mxcli-test-images/test.webp'
+);
+```
+
+**Expected:** All 6 formats accepted. `describe` shows correct format for each.
+
+### 7.7 Replace collection with different image set
+
+```
+create or replace image collection MyModule.Evolving (
+  image v1 from file '/tmp/mxcli-test-images/logo.png'
+);
+create or replace image collection MyModule.Evolving (
+  image v2a from file '/tmp/mxcli-test-images/icon.png',
+  image v2b from file '/tmp/mxcli-test-images/logo.png'
+);
+```
+
+**Expected:** Second `create or replace` fully replaces. `describe` shows only `v2a` and `v2b`.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Inventory |
+|-----------|:---:|:---:|:---:|
+| SHOW IMAGE COLLECTION | x | x | x |
+| DESCRIBE IMAGE COLLECTION | x | x | x |
+| CREATE IMAGE COLLECTION | x | | |
+| DROP IMAGE COLLECTION | x | | |
+| ROUNDTRIP | x | | |
+| BOUNDARY & STRESS | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW | Mock tests | |
+| 2. DESCRIBE | Mock tests | Image extraction to disk |
+| 3. CREATE | Mock tests | Format auto-detection |
+| 4. DROP | Mock tests | |
+| 5. Roundtrip | | All manual |
+| 6. Failure modes | Partial | Backend, preview dir |
+| 7. Boundary & stress | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW | List all | | | | |
+| 1.2 | SHOW | Filter module | | | | |
+| 1.3 | SHOW | Empty module | | | | |
+| 2.1 | DESCRIBE | Basic | | | | |
+| 2.2 | DESCRIBE | Image extraction | | | | |
+| 2.3 | DESCRIBE | Supported formats | | | | |
+| 2.4 | DESCRIBE | Not found | | | | |
+| 3.1 | CREATE | Empty collection | | | | |
+| 3.2 | CREATE | With images | | | | |
+| 3.3 | CREATE | Hidden (default) | | | | |
+| 3.4 | CREATE | Public export level | | | | |
+| 3.5 | CREATE | Format auto-detection | | | | |
+| 3.6 | CREATE | create or replace (new) | | | | |
+| 3.7 | CREATE | create or replace (update) | | | | |
+| 3.8 | CREATE | Duplicate error | | | | |
+| 3.9 | CREATE | Module auto-creation | | | | |
+| 4.1 | DROP | Existing | | | | |
+| 4.2 | DROP | Non-existent | | | | |
+| 5.1 | ROUNDTRIP | Create → Describe → Recreate | | | | |
+| 6.1 | FAILURE | Not connected | | | | |
+| 6.2 | FAILURE | File not found | | | | |
+| 6.3 | FAILURE | Invalid format | | | | |
+| 6.4 | FAILURE | Backend create failure | | | | |
+| 6.5 | FAILURE | Preview dir failure | | | | |
+| 7.1 | BOUNDARY | Large image (10 MB+) | | | | |
+| 7.2 | BOUNDARY | Many images (50+) | | | | |
+| 7.3 | BOUNDARY | Special chars in name | | | | |
+| 7.4 | BOUNDARY | Empty image file | | | | |
+| 7.5 | BOUNDARY | Duplicate image names | | | | |
+| 7.6 | BOUNDARY | All formats in one | | | | |
+| 7.7 | BOUNDARY | Replace with different set | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/integration-test-cases.md b/docs/15-testing/integration-test-cases.md
new file mode 100644
index 00000000..cafc54ed
--- /dev/null
+++ b/docs/15-testing/integration-test-cases.md
@@ -0,0 +1,2019 @@
+# Integration Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+Covers: OData Clients, OData Services, External Entities, Published REST Services, REST Clients, JSON Structures.
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Integration features |
+|-----|-----------|----------------------|
+| Lato Enquiry Management | 11.4.0 | OData, REST, JSON structures |
+| Evora - Factory Management | 10.24.15 | OData services, external entities |
+| Lato Product Inventory | 11.2.0 | Published REST, consumed OData |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show odata clients;" > /tmp/show-int.mdl
+  mxcli exec /tmp/show-int.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations (CREATE, DROP, GRANT/REVOKE) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory,
+> and objects that are DROPped cannot be recovered — there is no undo, no git history,
+> and no Studio Pro autosave for `.mpr` files.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW ODATA CLIENTS
+
+### 1.1 List all OData clients
+
+```
+show odata clients;
+```
+
+**Expected:** All consumed OData services listed. Count matches Studio Pro.
+
+### 1.2 Filter by module
+
+```
+show odata clients in MyModule;
+```
+
+**Expected:** Only OData clients from `MyModule`.
+
+### 1.3 Empty module
+
+```
+show odata clients in ModuleWithNoClients;
+```
+
+**Expected:** Empty result, no error.
+
+### 1.4 Non-existent module
+
+```
+show odata clients in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 2. DESCRIBE ODATA CLIENT
+
+### 2.1 Describe existing client
+
+```
+describe odata client MyModule.MyODataClient;
+```
+
+**Expected:** Valid `create or modify odata client` MDL output. Includes Version, ODataVersion, MetadataUrl, Timeout, ProxyType, ServiceUrl, Authentication, Headers.
+
+### 2.2 Non-existent client
+
+```
+describe odata client MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+### 2.3 All properties present
+
+Pick a client with all properties configured. Verify DESCRIBE output includes:
+
+| Property | Format |
+|----------|--------|
+| Version | String literal |
+| ODataVersion | `3` or `4` |
+| MetadataUrl | URL string |
+| Timeout | Integer (seconds) |
+| ProxyType | `default` / `none` / `custom` |
+| ServiceUrl | `@ConstantName` reference |
+| Authentication | `none` / `basic` / `custom` |
+| Headers | Block with key-value pairs |
+
+---
+
+## 3. CREATE ODATA CLIENT
+
+### 3.1 Full property set
+
+```
+create odata client MyModule.NewClient (
+  Version: '1.0',
+  ODataVersion: 4,
+  MetadataUrl: 'https://api.example.com/odata/v4/$metadata',
+  Timeout: 300,
+  ProxyType: default,
+  ServiceUrl: @MyModule.ServiceUrlConstant,
+  Authentication: none,
+  Headers:
+    'X-Custom-Header' = 'value1',
+    'Accept' = 'application/json'
+  end headers
+);
+```
+
+**Expected:** Created. Listed in `show odata clients`. DESCRIBE matches input.
+
+### 3.2 Minimal client
+
+```
+create odata client MyModule.MinimalClient (
+  MetadataUrl: 'https://api.example.com/odata/$metadata'
+);
+```
+
+**Expected:** Created with defaults for omitted properties.
+
+### 3.3 With basic authentication
+
+```
+create odata client MyModule.AuthClient (
+  MetadataUrl: 'https://api.example.com/odata/$metadata',
+  Authentication: basic
+);
+```
+
+**Expected:** Authentication set to basic. Roundtrips via DESCRIBE.
+
+### 3.4 Duplicate without OR MODIFY
+
+```
+create odata client MyModule.NewClient (
+  MetadataUrl: 'https://api.example.com/$metadata'
+);
+create odata client MyModule.NewClient (
+  MetadataUrl: 'https://api.example.com/$metadata'
+);
+```
+
+**Expected:** Second CREATE fails with "already exists" error.
+
+### 3.5 Target module must exist
+
+```
+create odata client NewModule.TestClient (
+  MetadataUrl: 'https://api.example.com/$metadata'
+);
+```
+
+**Expected:** Error if `NewModule` does not exist. Modules must be created beforehand.
+
+### 3.6 Write guard
+
+Attempt CREATE without opening a project for writing.
+
+**Expected:** Error about not being connected.
+
+---
+
+## 4. CREATE OR MODIFY ODATA CLIENT
+
+### 4.1 Upsert — new client
+
+```
+create or modify odata client MyModule.UpsertClient (
+  MetadataUrl: 'https://api.example.com/$metadata',
+  Timeout: 60
+);
+```
+
+**Expected:** Created. No error.
+
+### 4.2 Upsert — existing client
+
+```
+create or modify odata client MyModule.UpsertClient (
+  MetadataUrl: 'https://api.example.com/v2/$metadata',
+  Timeout: 120
+);
+```
+
+**Expected:** Updated. ID reused. DESCRIBE shows new values.
+
+---
+
+## 5. ALTER ODATA CLIENT
+
+### 5.1 Set single property
+
+```
+alter odata client MyModule.ExistingClient set timeout = 600;
+```
+
+**Expected:** Only timeout changed. Other properties unchanged.
+
+### 5.2 Set metadata URL
+
+```
+alter odata client MyModule.ExistingClient set MetadataUrl = 'https://new.example.com/$metadata';
+```
+
+**Expected:** URL updated. DESCRIBE confirms.
+
+### 5.3 Alter non-existent client
+
+```
+alter odata client MyModule.DoesNotExist set timeout = 60;
+```
+
+**Expected:** Clear error.
+
+---
+
+## 6. DROP ODATA CLIENT
+
+### 6.1 Drop existing client
+
+```
+create odata client MyModule.ToDrop (
+  MetadataUrl: 'https://example.com/$metadata'
+);
+drop odata client MyModule.ToDrop;
+```
+
+**Expected:** Removed. Not in `show odata clients`.
+
+### 6.2 Cascade — deletes external entities
+
+1. CREATE odata client
+2. CREATE external entity from that client
+3. DROP odata client
+
+**Expected:** External entities sourced from this client also removed.
+
+### 6.3 Drop non-existent client
+
+```
+drop odata client MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error.
+
+### 6.4 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 7. SHOW ODATA SERVICES
+
+### 7.1 List all published OData services
+
+```
+show odata services;
+```
+
+**Expected:** All published OData services listed. Count matches Studio Pro.
+
+### 7.2 Filter by module
+
+```
+show odata services in MyModule;
+```
+
+**Expected:** Only OData services from `MyModule`.
+
+### 7.3 Empty module
+
+```
+show odata services in ModuleWithNoServices;
+```
+
+**Expected:** Empty result, no error.
+
+### 7.4 Non-existent module
+
+```
+show odata services in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 8. DESCRIBE ODATA SERVICE
+
+### 8.1 Describe existing service
+
+```
+describe odata service MyModule.MyODataService;
+```
+
+**Expected:** Valid `create or modify odata service` MDL output. Includes Path, Version, ODataVersion, Namespace, Authentication, published entities with expose blocks.
+
+### 8.2 Non-existent service
+
+```
+describe odata service MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+### 8.3 Published entity details
+
+Verify DESCRIBE output for a service with published entities includes:
+
+| Property | Format |
+|----------|--------|
+| PUBLISH ENTITY | Qualified entity name |
+| EXPOSE block | Attribute list with types |
+| ReadMode | `default` / `fromDatabase` / `fromMicroflow` |
+| InsertMode | `default` / `fromMicroflow` |
+| UpdateMode | `default` / `fromMicroflow` |
+| DeleteMode | `default` / `fromMicroflow` |
+| UsePaging | `true` / `false` |
+| PageSize | Integer |
+
+---
+
+## 9. CREATE ODATA SERVICE
+
+### 9.1 Full service with published entity
+
+```
+create odata service MyModule.NewService (
+  Path: '/odata/v1/myservice',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.myservice',
+  Authentication: none
+)
+  publish entity MyModule.Customer
+    expose
+      Name,
+      Email,
+      PhoneNumber
+    end expose
+    ReadMode: default,
+    InsertMode: default,
+    UpdateMode: default,
+    DeleteMode: default,
+    UsePaging: true,
+    PageSize: 20;
+```
+
+**Expected:** Created. Listed in `show odata services`. DESCRIBE matches input.
+
+### 9.2 Multiple published entities
+
+```
+create odata service MyModule.MultiEntityService (
+  Path: '/odata/v1/multi',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.multi',
+  Authentication: none
+)
+  publish entity MyModule.Customer
+    expose Name, Email end expose
+    ReadMode: default,
+    UsePaging: true,
+    PageSize: 50
+  publish entity MyModule.Order
+    expose OrderNumber, TotalAmount end expose
+    ReadMode: default,
+    UsePaging: true,
+    PageSize: 100;
+```
+
+**Expected:** Both entities published. DESCRIBE lists both.
+
+### 9.3 Duplicate without OR MODIFY
+
+```
+create odata service MyModule.NewService (
+  Path: '/odata/v1/svc',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example'
+);
+create odata service MyModule.NewService (
+  Path: '/odata/v1/svc',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example'
+);
+```
+
+**Expected:** Second CREATE fails with "already exists" error.
+
+### 9.4 Target module must exist
+
+```
+create odata service NewModule.TestService (
+  Path: '/odata/v1/test',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.test'
+);
+```
+
+**Expected:** Error if `NewModule` does not exist. Modules must be created beforehand.
+
+### 9.5 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 10. CREATE OR MODIFY ODATA SERVICE
+
+### 10.1 Upsert — new service
+
+```
+create or modify odata service MyModule.UpsertService (
+  Path: '/odata/v1/upsert',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.upsert'
+);
+```
+
+**Expected:** Created. No error.
+
+### 10.2 Upsert — existing service
+
+```
+create or modify odata service MyModule.UpsertService (
+  Path: '/odata/v2/upsert',
+  Version: '2.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.upsert.v2'
+);
+```
+
+**Expected:** Updated. ID reused. DESCRIBE shows new values.
+
+---
+
+## 11. ALTER ODATA SERVICE
+
+### 11.1 Set single property
+
+```
+alter odata service MyModule.ExistingService set version = '2.0.0';
+```
+
+**Expected:** Only version changed. Other properties unchanged.
+
+### 11.2 Set path
+
+```
+alter odata service MyModule.ExistingService set path = '/odata/v2/updated';
+```
+
+**Expected:** Path updated. DESCRIBE confirms.
+
+### 11.3 Alter non-existent service
+
+```
+alter odata service MyModule.DoesNotExist set version = '1.0.0';
+```
+
+**Expected:** Clear error.
+
+---
+
+## 12. DROP ODATA SERVICE
+
+### 12.1 Drop existing service
+
+```
+create odata service MyModule.ToDrop (
+  Path: '/odata/v1/drop',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example.drop'
+);
+drop odata service MyModule.ToDrop;
+```
+
+**Expected:** Removed. Not in `show odata services`.
+
+### 12.2 Drop non-existent service
+
+```
+drop odata service MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error.
+
+### 12.3 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 13. GRANT / REVOKE ACCESS ON ODATA SERVICE
+
+### 13.1 Grant to single role
+
+```
+grant access on odata service MyModule.MyService to MyModule.User;
+```
+
+**Expected:** Role granted. Verifiable via DESCRIBE or show access.
+
+### 13.2 Grant to multiple roles
+
+```
+grant access on odata service MyModule.MyService to MyModule.User, MyModule.Admin;
+```
+
+**Expected:** Both roles added.
+
+### 13.3 Idempotent grant
+
+Grant same role twice.
+
+**Expected:** No duplicate entries on second grant.
+
+### 13.4 Revoke from role
+
+```
+revoke access on odata service MyModule.MyService from MyModule.User;
+```
+
+**Expected:** Role removed.
+
+### 13.5 Grant on non-existent service
+
+**Expected:** Clear error.
+
+### 13.6 Grant with non-existent role
+
+**Expected:** Clear error.
+
+---
+
+## 14. SHOW EXTERNAL ENTITIES
+
+### 14.1 List all external entities
+
+```
+show external entities;
+```
+
+**Expected:** All external entities listed. Count matches Studio Pro.
+
+### 14.2 Filter by module
+
+```
+show external entities in MyModule;
+```
+
+**Expected:** Only external entities from `MyModule`.
+
+### 14.3 Empty module
+
+```
+show external entities in ModuleWithNoExternals;
+```
+
+**Expected:** Empty result, no error.
+
+### 14.4 Non-existent module
+
+```
+show external entities in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 15. SHOW EXTERNAL ACTIONS
+
+### 15.1 List all external actions
+
+```
+show external actions;
+```
+
+**Expected:** All external actions listed. Count matches Studio Pro.
+
+---
+
+## 16. DESCRIBE EXTERNAL ENTITY
+
+### 16.1 Describe existing external entity
+
+```
+describe external entity MyModule.MyExternalEntity;
+```
+
+**Expected:** Valid MDL output. Includes source OData client, EntitySet, RemoteName, attributes, Countable, Creatable, Deletable, Updatable flags.
+
+### 16.2 Non-existent external entity
+
+```
+describe external entity MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+### 16.3 All properties present
+
+Verify DESCRIBE output includes:
+
+| Property | Format |
+|----------|--------|
+| EntitySet | String |
+| RemoteName | String |
+| Countable | `true` / `false` |
+| Creatable | `true` / `false` |
+| Deletable | `true` / `false` |
+| Updatable | `true` / `false` |
+| Attributes | Name + type list |
+
+---
+
+## 17. CREATE EXTERNAL ENTITY FROM ODATA CLIENT
+
+### 17.1 Single entity with full properties
+
+```
+create external entity MyModule.ExternalCustomer from odata client MyModule.MyODataClient (
+  EntitySet: 'Customers',
+  RemoteName: 'Customer',
+  Countable: true,
+  Creatable: true,
+  Deletable: false,
+  Updatable: true
+) (
+  Name: String(200),
+  Email: String(200),
+  Age: Integer,
+  Active: Boolean
+);
+```
+
+**Expected:** Created. Listed in `show external entities`. DESCRIBE matches input.
+
+### 17.2 Minimal entity
+
+```
+create external entity MyModule.ExternalOrder from odata client MyModule.MyODataClient (
+  EntitySet: 'Orders',
+  RemoteName: 'Order'
+) (
+  OrderId: Integer,
+  Total: Decimal
+);
+```
+
+**Expected:** Created with defaults for omitted boolean flags.
+
+### 17.3 Non-existent source client
+
+```
+create external entity MyModule.BadSource from odata client MyModule.NonExistentClient (
+  EntitySet: 'Items',
+  RemoteName: 'Item'
+) (
+  Id: Integer
+);
+```
+
+**Expected:** Error — source OData client not found.
+
+### 17.4 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 18. CREATE OR MODIFY EXTERNAL ENTITY
+
+### 18.1 Upsert — new entity
+
+```
+create or modify external entity MyModule.UpsertExternal from odata client MyModule.MyODataClient (
+  EntitySet: 'Products',
+  RemoteName: 'Product'
+) (
+  ProductId: Integer,
+  Name: String(200)
+);
+```
+
+**Expected:** Created. No error.
+
+### 18.2 Upsert — existing entity
+
+```
+create or modify external entity MyModule.UpsertExternal from odata client MyModule.MyODataClient (
+  EntitySet: 'Products',
+  RemoteName: 'Product',
+  Countable: true
+) (
+  ProductId: Integer,
+  Name: String(200),
+  Price: Decimal
+);
+```
+
+**Expected:** Updated. ID reused. DESCRIBE shows new attributes.
+
+---
+
+## 19. CREATE EXTERNAL ENTITIES FROM CLIENT (bulk import)
+
+> **Not implemented (#423):** The `create external entities from odata client` syntax is not yet implemented. These test cases document the expected behavior for when it lands.
+
+### 19.1 Bulk import all entities
+
+```
+create external entities from odata client MyModule.MyODataClient;
+```
+
+**Expected:** All entities from the OData service metadata imported. Each listed in `show external entities`.
+
+### 19.2 Selective import into target module
+
+```
+create or modify external entities
+  from odata client MyModule.MyODataClient
+  entities (Customer, Order, Product)
+  into TargetModule;
+```
+
+**Expected:** Only Customer, Order, Product imported. Placed in `TargetModule`.
+
+### 19.3 Non-existent entity name in list
+
+```
+create or modify external entities
+  from odata client MyModule.MyODataClient
+  entities (Customer, NonExistentEntity)
+  into TargetModule;
+```
+
+**Expected:** Error for NonExistentEntity. Customer may or may not be created depending on fail-fast behavior.
+
+### 19.4 Non-existent source client
+
+```
+create external entities from odata client MyModule.NonExistent;
+```
+
+**Expected:** Clear error.
+
+---
+
+## 20. SHOW PUBLISHED REST SERVICES
+
+> **Feature gate:** Mendix 10.0+. Test against Evora (10.24.15) and Lato Enquiry (11.4.0).
+
+### 20.1 List all published REST services
+
+```
+show published rest services;
+```
+
+**Expected:** All published REST services listed. Count matches Studio Pro.
+
+### 20.2 Filter by module
+
+```
+show published rest services in MyModule;
+```
+
+**Expected:** Only REST services from `MyModule`.
+
+### 20.3 Empty module
+
+```
+show published rest services in ModuleWithNoREST;
+```
+
+**Expected:** Empty result, no error.
+
+### 20.4 Non-existent module
+
+```
+show published rest services in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 21. DESCRIBE PUBLISHED REST SERVICE
+
+### 21.1 Describe existing service
+
+```
+describe published rest service MyModule.MyRestService;
+```
+
+**Expected:** Valid `create or replace published rest service` MDL output. Includes Path, Version, ServiceName, resource blocks with HTTP methods and microflow references.
+
+### 21.2 Non-existent service
+
+```
+describe published rest service MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+### 21.3 Resource detail
+
+Verify DESCRIBE includes for each resource:
+
+| Property | Format |
+|----------|--------|
+| Resource path | String |
+| HTTP method | `GET` / `POST` / `PUT` / `PATCH` / `DELETE` |
+| Microflow | Qualified `Module.Microflow` reference |
+| Deprecated | `deprecated` keyword if applicable |
+
+---
+
+## 22. CREATE PUBLISHED REST SERVICE
+
+### 22.1 Full service with resources
+
+```
+create published rest service MyModule.CustomerAPI (
+  Path: '/api/v1/customers',
+  Version: '1.0.0',
+  ServiceName: 'CustomerAPI'
+)
+  resource '/customers' {
+    get microflow MyModule.GetCustomers;
+    post microflow MyModule.CreateCustomer;
+  }
+  resource '/customers/{id}' {
+    get microflow MyModule.GetCustomerById;
+    put microflow MyModule.UpdateCustomer;
+    delete microflow MyModule.DeleteCustomer;
+  };
+```
+
+**Expected:** Created. Listed in `show published rest services`. DESCRIBE matches input.
+
+> **Note (#429):** The `end resource` syntax causes a crash. Always use brace syntax `resource 'path' { ... }` instead.
+
+### 22.2 Single resource, single method
+
+```
+create published rest service MyModule.SimpleAPI (
+  Path: '/api/v1/health',
+  Version: '1.0.0',
+  ServiceName: 'HealthCheck'
+)
+  resource '/health' {
+    get microflow MyModule.HealthCheck;
+  };
+```
+
+**Expected:** Created with minimal configuration.
+
+### 22.3 Deprecated resource method
+
+```
+create published rest service MyModule.LegacyAPI (
+  Path: '/api/v1/legacy',
+  Version: '1.0.0',
+  ServiceName: 'LegacyAPI'
+)
+  resource '/old-endpoint' {
+    deprecated get microflow MyModule.OldEndpoint;
+  };
+```
+
+**Expected:** Deprecated flag preserved. DESCRIBE shows `deprecated` keyword.
+
+### 22.4 Duplicate without OR REPLACE
+
+```
+create published rest service MyModule.CustomerAPI (
+  Path: '/api/v1/dup',
+  Version: '1.0.0',
+  ServiceName: 'Dup'
+);
+create published rest service MyModule.CustomerAPI (
+  Path: '/api/v1/dup',
+  Version: '1.0.0',
+  ServiceName: 'Dup'
+);
+```
+
+**Expected:** Second CREATE fails with "already exists" error.
+
+> **BUG-017:** Currently duplicate creation is allowed for published REST services. Second CREATE succeeds and creates a duplicate entry instead of returning an error.
+
+### 22.5 Module auto-creation
+
+```
+create published rest service NewModule.TestAPI (
+  Path: '/api/v1/test',
+  Version: '1.0.0',
+  ServiceName: 'TestAPI'
+);
+```
+
+**Expected:** `NewModule` created automatically if it doesn't exist.
+
+### 22.6 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 23. CREATE OR REPLACE PUBLISHED REST SERVICE
+
+### 23.1 Upsert — new service
+
+```
+create or replace published rest service MyModule.UpsertAPI (
+  Path: '/api/v1/upsert',
+  Version: '1.0.0',
+  ServiceName: 'UpsertAPI'
+)
+  resource '/items' {
+    get microflow MyModule.GetItems;
+  };
+```
+
+**Expected:** Created. No error.
+
+### 23.2 Upsert — existing service
+
+```
+create or replace published rest service MyModule.UpsertAPI (
+  Path: '/api/v2/upsert',
+  Version: '2.0.0',
+  ServiceName: 'UpsertAPI'
+)
+  resource '/items' {
+    get microflow MyModule.GetItemsV2;
+    post microflow MyModule.CreateItem;
+  };
+```
+
+**Expected:** Replaced. ID reused. DESCRIBE shows new values.
+
+---
+
+## 24. ALTER PUBLISHED REST SERVICE
+
+### 24.1 Set property
+
+```
+alter published rest service MyModule.MyAPI set version = '2.0.0';
+```
+
+**Expected:** Only version changed. Resources unchanged.
+
+### 24.2 Add resource
+
+```
+alter published rest service MyModule.MyAPI
+  add resource '/new-resource' {
+    get microflow MyModule.GetNewResource;
+  };
+```
+
+**Expected:** New resource added. Existing resources unchanged.
+
+### 24.3 Drop resource
+
+```
+alter published rest service MyModule.MyAPI
+  drop resource '/old-resource';
+```
+
+**Expected:** Resource removed. Other resources unchanged.
+
+### 24.4 Alter non-existent service
+
+```
+alter published rest service MyModule.DoesNotExist set version = '1.0.0';
+```
+
+**Expected:** Clear error.
+
+---
+
+## 25. DROP PUBLISHED REST SERVICE
+
+### 25.1 Drop existing service
+
+```
+drop published rest service MyModule.CustomerAPI;
+```
+
+**Expected:** Removed. Not in `show published rest services`.
+
+### 25.2 Drop non-existent service
+
+```
+drop published rest service MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error.
+
+### 25.3 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 26. GRANT / REVOKE ACCESS ON PUBLISHED REST SERVICE
+
+### 26.1 Grant to single role
+
+```
+grant access on published rest service MyModule.MyAPI to MyModule.User;
+```
+
+**Expected:** Role granted.
+
+### 26.2 Grant to multiple roles
+
+```
+grant access on published rest service MyModule.MyAPI to MyModule.User, MyModule.Admin;
+```
+
+**Expected:** Both roles added.
+
+### 26.3 Revoke from role
+
+```
+revoke access on published rest service MyModule.MyAPI from MyModule.User;
+```
+
+**Expected:** Role removed.
+
+### 26.4 Grant on non-existent service
+
+**Expected:** Clear error.
+
+### 26.5 Grant with non-existent role
+
+**Expected:** Clear error.
+
+---
+
+## 27. SHOW REST CLIENTS
+
+> **Feature gate:** Mendix 10.1+. Test against Lato Enquiry (11.4.0) and Evora (10.24.15).
+
+### 27.1 List all REST clients
+
+```
+show rest clients;
+```
+
+**Expected:** All consumed REST services listed. Count matches Studio Pro.
+
+### 27.2 Filter by module
+
+```
+show rest clients in MyModule;
+```
+
+**Expected:** Only REST clients from `MyModule`.
+
+### 27.3 Empty module
+
+```
+show rest clients in ModuleWithNoREST;
+```
+
+**Expected:** Empty result, no error.
+
+### 27.4 Non-existent module
+
+```
+show rest clients in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 28. DESCRIBE REST CLIENT
+
+### 28.1 Describe existing client
+
+```
+describe rest client MyModule.MyRestClient;
+```
+
+**Expected:** Valid `create or modify rest client` MDL output. Includes BaseUrl, Authentication, operation blocks.
+
+### 28.2 Non-existent client
+
+```
+describe rest client MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+### 28.3 Operation detail
+
+Verify DESCRIBE output for each operation includes:
+
+| Property | Format |
+|----------|--------|
+| Method | `GET` / `POST` / `PUT` / `PATCH` / `DELETE` |
+| Path | String with `{param}` placeholders |
+| Parameters | Name + type list |
+| Query | Key-value pairs |
+| Headers | Key-value pairs |
+| Body | Type reference or inline |
+| Timeout | Integer (seconds) |
+| Response | Type reference |
+
+---
+
+## 29. CREATE REST CLIENT (manual)
+
+### 29.1 Full client with operations
+
+> **SKIP:** The `operation...end operation` syntax below is not yet implemented in the parser. See [#429](https://github.com/mendixlabs/mxcli/issues/429). Test case retained for future validation.
+
+```
+create rest client MyModule.ExternalAPI (
+  BaseUrl: 'https://api.example.com/v1',
+  Authentication: none
+)
+  operation GetUsers
+    method GET
+    path '/users'
+    timeout 30
+    response MyModule.UserListResponse
+  end operation
+  operation CreateUser
+    method POST
+    path '/users'
+    headers
+      'Content-Type' = 'application/json'
+    end headers
+    body MyModule.CreateUserRequest
+    timeout 60
+    response MyModule.UserResponse
+  end operation
+  operation GetUserById
+    method GET
+    path '/users/{userId}'
+    parameters
+      userId : String
+    end parameters
+    timeout 30
+    response MyModule.UserResponse
+  end operation;
+```
+
+**Expected:** Created. Listed in `show rest clients`. DESCRIBE matches input.
+
+### 29.2 With basic authentication
+
+```
+create rest client MyModule.AuthAPI (
+  BaseUrl: 'https://secure.example.com/api',
+  Authentication: basic
+)
+  operation Ping
+    method GET
+    path '/ping'
+    timeout 10
+  end operation;
+```
+
+**Expected:** Authentication set to basic. Roundtrips via DESCRIBE.
+
+### 29.3 With query parameters
+
+```
+create rest client MyModule.SearchAPI (
+  BaseUrl: 'https://api.example.com',
+  Authentication: none
+)
+  operation Search
+    method GET
+    path '/search'
+    query
+      'q' = '$SearchTerm',
+      'limit' = '10'
+    end query
+    timeout 30
+  end operation;
+```
+
+**Expected:** Query parameters preserved in DESCRIBE.
+
+### 29.4 Duplicate without OR MODIFY
+
+```
+create rest client MyModule.ExternalAPI (
+  BaseUrl: 'https://api.example.com'
+);
+create rest client MyModule.ExternalAPI (
+  BaseUrl: 'https://api.example.com'
+);
+```
+
+**Expected:** Second CREATE fails with "already exists" error.
+
+### 29.5 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 30. CREATE REST CLIENT FROM OPENAPI
+
+### 30.1 From local file
+
+```
+create rest client MyModule.PetStore
+  from openapi '/path/to/petstore.yaml';
+```
+
+**Expected:** Client created with operations derived from OpenAPI spec. All paths and methods mapped.
+
+### 30.2 From URL
+
+```
+create rest client MyModule.PetStoreURL
+  from openapi 'https://petstore3.swagger.io/api/v3/openapi.json';
+```
+
+**Expected:** Spec fetched and client created. Operations match spec paths.
+
+### 30.3 Invalid spec
+
+```
+create rest client MyModule.BadSpec
+  from openapi '/path/to/invalid.yaml';
+```
+
+**Expected:** Clear error about spec parsing failure.
+
+### 30.4 Non-existent file
+
+```
+create rest client MyModule.NoFile
+  from openapi '/nonexistent/spec.yaml';
+```
+
+**Expected:** Clear error about file not found.
+
+---
+
+## 31. CREATE OR MODIFY REST CLIENT
+
+### 31.1 Upsert — new client
+
+```
+create or modify rest client MyModule.UpsertREST (
+  BaseUrl: 'https://api.example.com',
+  Authentication: none
+);
+```
+
+**Expected:** Created. No error.
+
+### 31.2 Upsert — existing client
+
+```
+create or modify rest client MyModule.UpsertREST (
+  BaseUrl: 'https://api.example.com/v2',
+  Authentication: basic
+);
+```
+
+**Expected:** Updated. ID reused. DESCRIBE shows new values.
+
+---
+
+## 32. DROP REST CLIENT
+
+### 32.1 Drop existing client
+
+```
+drop rest client MyModule.ExternalAPI;
+```
+
+**Expected:** Removed. Not in `show rest clients`.
+
+### 32.2 Drop non-existent client
+
+```
+drop rest client MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error.
+
+### 32.3 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 33. DESCRIBE CONTRACT OPERATION FROM OPENAPI
+
+### 33.1 Preview from local file
+
+```
+describe contract operation from openapi '/path/to/petstore.yaml';
+```
+
+**Expected:** Lists all operations from the spec without creating anything. Shows method, path, parameters, request/response types.
+
+### 33.2 Preview from URL
+
+```
+describe contract operation from openapi 'https://petstore3.swagger.io/api/v3/openapi.json';
+```
+
+**Expected:** Same as §33.1 but fetched from URL.
+
+### 33.3 Invalid spec
+
+```
+describe contract operation from openapi '/path/to/invalid.yaml';
+```
+
+**Expected:** Clear error about spec parsing failure.
+
+---
+
+## 34. SHOW JSON STRUCTURES
+
+### 34.1 List all JSON structures
+
+```
+show json structures;
+```
+
+**Expected:** All JSON structures listed. Count matches Studio Pro.
+
+### 34.2 Filter by module
+
+```
+show json structures in MyModule;
+```
+
+**Expected:** Only JSON structures from `MyModule`.
+
+### 34.3 Empty module
+
+```
+show json structures in ModuleWithNoJSON;
+```
+
+**Expected:** Empty result, no error.
+
+### 34.4 Non-existent module
+
+```
+show json structures in NonExistentModule;
+```
+
+**Expected:** Empty result, no error. Consistent with other SHOW IN commands for empty modules.
+
+---
+
+## 35. DESCRIBE JSON STRUCTURE
+
+### 35.1 Describe existing structure
+
+```
+describe json structure MyModule.MyJsonStructure;
+```
+
+**Expected:** Valid `create or replace json structure` MDL output. Includes JSON snippet, folder, comment, custom name map.
+
+### 35.2 Non-existent structure
+
+```
+describe json structure MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error message.
+
+---
+
+## 36. CREATE JSON STRUCTURE
+
+### 36.1 With single-quoted snippet
+
+```
+create json structure MyModule.UserSchema
+  snippet '{"name": "string", "age": 0, "active": true}';
+```
+
+**Expected:** Created. Listed in `show json structures`. DESCRIBE matches input.
+
+### 36.2 With dollar-quoting
+
+```
+create json structure MyModule.ComplexSchema
+  $$
+  {
+    "users": [
+      {
+        "id": 0,
+        "name": "string",
+        "email": "string",
+        "address": {
+          "street": "string",
+          "city": "string",
+          "zip": "string"
+        }
+      }
+    ],
+    "total": 0,
+    "page": 0
+  }
+  $$;
+```
+
+**Expected:** Created. Complex nested structure preserved. DESCRIBE shows full JSON.
+
+> **Note:** Multiline `$$` quoting is not supported by the parser. Use single-line `$${"users":[...]}$$` or single-quoted JSON strings instead.
+
+### 36.3 With folder and comment
+
+```
+create json structure MyModule.DocumentedSchema
+  folder 'API/Schemas'
+  comment 'Schema for the user creation endpoint'
+  '{"username": "string", "password": "string"}';
+```
+
+**Expected:** Folder and comment preserved in DESCRIBE.
+
+### 36.4 With custom name map
+
+```
+create json structure MyModule.MappedSchema
+  '{"user-name": "string", "e-mail": "string"}'
+  custom name map
+    'user-name' as 'UserName',
+    'e-mail' as 'Email'
+  end custom name map;
+```
+
+**Expected:** Custom name map preserved. DESCRIBE shows mappings.
+
+### 36.5 Duplicate without OR REPLACE
+
+```
+create json structure MyModule.UserSchema '{"a": 1}';
+create json structure MyModule.UserSchema '{"a": 1}';
+```
+
+**Expected:** Second CREATE fails with "already exists" error.
+
+### 36.6 Module auto-creation
+
+```
+create json structure NewModule.TestSchema '{"test": true}';
+```
+
+**Expected:** `NewModule` created automatically if it doesn't exist.
+
+### 36.7 Write guard
+
+**Expected:** Error if no project open for writing.
+
+### 36.8 Invalid JSON snippet
+
+```
+create json structure MyModule.BadJSON '{invalid json}';
+```
+
+**Expected:** Clear error about JSON parsing failure.
+
+---
+
+## 37. CREATE OR REPLACE JSON STRUCTURE
+
+### 37.1 Upsert — new structure
+
+```
+create or replace json structure MyModule.UpsertSchema
+  '{"value": "string"}';
+```
+
+**Expected:** Created. No error.
+
+### 37.2 Upsert — existing structure
+
+```
+create or replace json structure MyModule.UpsertSchema
+  '{"value": "string", "count": 0}';
+```
+
+**Expected:** Replaced. DESCRIBE shows new schema.
+
+---
+
+## 38. DROP JSON STRUCTURE
+
+### 38.1 Drop existing structure
+
+```
+drop json structure MyModule.UserSchema;
+```
+
+**Expected:** Removed. Not in `show json structures`.
+
+### 38.2 Drop non-existent structure
+
+```
+drop json structure MyModule.DoesNotExist;
+```
+
+**Expected:** Clear error.
+
+### 38.3 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 39. ROUNDTRIP (BSON)
+
+### 39.1 OData Client roundtrip
+
+1. DESCRIBE odata client → capture MDL
+2. DROP odata client
+3. Execute captured MDL
+4. DESCRIBE again → capture
+5. Diff the two outputs
+
+**Expected:** Identical or cosmetic-only differences.
+
+### 39.2 OData Service roundtrip
+
+1. DESCRIBE odata service → capture MDL
+2. DROP odata service
+3. Execute captured MDL
+4. DESCRIBE again → capture
+5. Diff
+
+**Expected:** Identical or cosmetic-only differences.
+
+> **BUG-016:** OData service DESCRIBE is not fully roundtrippable. The `PUBLISH ENTITY` syntax in the output may not parse correctly when re-executed. Manual adjustment may be needed.
+
+1. DESCRIBE external entity → capture MDL
+2. Execute captured MDL via CREATE OR MODIFY
+3. DESCRIBE again → capture
+4. Diff
+
+**Expected:** Identical output.
+
+### 39.4 Published REST Service roundtrip
+
+1. DESCRIBE published rest service → capture MDL
+2. DROP published rest service
+3. Execute captured MDL
+4. DESCRIBE again → capture
+5. Diff
+
+**Expected:** Identical or cosmetic-only differences.
+
+### 39.5 REST Client roundtrip
+
+1. DESCRIBE rest client → capture MDL
+2. DROP rest client
+3. Execute captured MDL
+4. DESCRIBE again → capture
+5. Diff
+
+**Expected:** Identical or cosmetic-only differences.
+
+> **Note:** REST client body/response mappings are simplified on roundtrip — complex request body and response type definitions may lose detail. This is a known data loss issue during DESCRIBE→CREATE cycles.
+
+1. DESCRIBE json structure → capture MDL
+2. DROP json structure
+3. Execute captured MDL
+4. DESCRIBE again → capture
+5. Diff
+
+**Expected:** Identical output. JSON whitespace normalization acceptable.
+
+### 39.7 Bulk roundtrip
+
+Run §39.1–§39.6 on all instances across 3 test projects. Record pass/fail counts.
+
+---
+
+## 40. MULTI-STEP WORKFLOWS
+
+### 40.1 End-to-end REST integration
+
+1. CREATE json structure for request/response schemas
+2. CREATE rest client with operations referencing the JSON structures
+3. CREATE microflow calling the REST client operation
+4. DESCRIBE each artifact — verify cross-references intact
+
+### 40.2 OData publish-consume loop
+
+1. CREATE odata service publishing entity `MyModule.Product`
+2. CREATE odata client pointing to the service metadata URL
+3. CREATE external entity from the OData client
+4. DESCRIBE each — verify chain intact
+
+### 40.3 Scaffold module with all integration types
+
+1. CREATE odata client in `IntegrationModule`
+2. CREATE external entities from client
+3. CREATE published rest service exposing data
+4. CREATE json structure for API contract
+5. SHOW each type in `IntegrationModule` — verify all present
+6. DESCRIBE each — verify complete MDL output
+
+### 40.4 Iterative service evolution
+
+1. CREATE published rest service with 1 resource, 1 method
+2. ALTER to add second resource
+3. ALTER to add method to first resource
+4. ALTER to set new version
+5. After each step: DESCRIBE and verify cumulative changes
+
+### 40.5 Drop and recreate with different configuration
+
+1. CREATE rest client with 2 operations
+2. DROP
+3. CREATE same name with 3 different operations
+4. DESCRIBE — verify new configuration, no remnant of old operations
+
+---
+
+## 41. FAILURE MODES
+
+### 41.1 Not connected
+
+Attempt each write command without opening a project:
+
+| Command | Expected |
+|---------|----------|
+| `create odata client ...` | Error: not connected |
+| `create odata service ...` | Error: not connected |
+| `create external entity ...` | Error: not connected |
+| `create published rest service ...` | Error: not connected |
+| `create rest client ...` | Error: not connected |
+| `create json structure ...` | Error: not connected |
+
+### 41.2 Entity not found
+
+```
+create odata service MyModule.BadService (
+  Path: '/odata/v1/bad',
+  Version: '1.0.0',
+  ODataVersion: 4,
+  Namespace: 'com.example'
+)
+  publish entity MyModule.NonExistentEntity
+    expose Name end expose;
+```
+
+**Expected:** Error — entity not found.
+
+### 41.3 Duplicate without OR MODIFY/REPLACE
+
+Test for each type. See §3.4, §9.3, §22.4, §29.4, §36.5.
+
+### 41.4 Invalid metadata URL
+
+```
+create odata client MyModule.BadUrl (
+  MetadataUrl: 'not-a-url'
+);
+```
+
+**Expected:** Error about invalid URL format or connection failure.
+
+### 41.5 Unsupported driver version
+
+Open a pre-10.0 `.mpr` file. Attempt:
+
+```
+show published rest services;
+```
+
+**Expected:** Clear error about feature gate — Published REST requires Mendix 10.0+.
+
+### 41.6 Feature gate violation — REST client
+
+Open a pre-10.1 `.mpr` file. Attempt:
+
+```
+show rest clients;
+```
+
+**Expected:** Clear error about feature gate — REST Clients require Mendix 10.1+.
+
+### 41.7 Invalid JSON in structure
+
+```
+create json structure MyModule.Bad '{not json at all';
+```
+
+**Expected:** Clear error about JSON syntax.
+
+### 41.8 Non-existent microflow in REST service
+
+```
+create published rest service MyModule.BadRef (
+  Path: '/api/v1/bad',
+  Version: '1.0.0',
+  ServiceName: 'BadRef'
+)
+  resource '/items' {
+    get microflow MyModule.NonExistentMicroflow;
+  };
+```
+
+**Expected:** Error — microflow not found.
+
+### 41.9 Double DROP
+
+```
+drop rest client MyModule.X;
+drop rest client MyModule.X;
+```
+
+**Expected:** First succeeds, second gives "not found" error.
+
+### 41.10 Validation failure mid-batch
+
+```
+create json structure MyModule.Good1 '{"ok": true}';
+create json structure MyModule.Bad '{invalid}';
+create json structure MyModule.Good3 '{"ok": true}';
+```
+
+**Expected:** Good1 created, Bad rejected, Good3 NOT created — batch aborts on first error.
+
+> Batch mode (`mxcli exec`) is fail-fast. REPL mode continues on error per-line.
+
+### 41.11 Error message quality
+
+For each error scenario, verify the message includes:
+- **What** went wrong
+- **Which** object (qualified name)
+- **Actionable guidance** where applicable
+
+---
+
+## Test Project Coverage Matrix
+
+| Category | Enquiries (11.4.0) | Evora Factory (10.24.15) | Lato Inventory (11.2.0) |
+|---|---|---|---|
+| SHOW OData clients | Verify count | Verify count | Verify count |
+| SHOW OData services | Verify count | Verify count | Verify count |
+| SHOW external entities | Verify count | Verify count | Verify count |
+| SHOW published REST | Verify count | Verify count | Verify count |
+| SHOW REST clients | Verify count | Verify count | Verify count |
+| SHOW JSON structures | Verify count | Verify count | Verify count |
+| DESCRIBE (sample 5+ each) | All 6 types | All 6 types | All 6 types |
+| Roundtrip (sample 5+ each) | All 6 types | All 6 types | All 6 types |
+| CREATE + DROP cycle | All 6 types | All 6 types | All 6 types |
+| Feature gate (REST) | ✅ 10.0+ | ✅ 10.0+ | ✅ 10.0+ |
+| Feature gate (REST client) | ✅ 10.1+ | ✅ 10.1+ | ✅ 10.1+ |
+| Multi-step workflows (§40) | End-to-end | End-to-end | End-to-end |
+| Security (GRANT/REVOKE) | OData + REST | OData + REST | OData + REST |
+
+---
+
+## Automated Test Coverage
+
+| Area | Tests | Status |
+|---|---|---|
+| SHOW ODATA CLIENTS | None | **Gap** |
+| DESCRIBE ODATA CLIENT | None | **Gap** |
+| CREATE ODATA CLIENT | None | **Gap** |
+| DROP ODATA CLIENT | None | **Gap** |
+| SHOW ODATA SERVICES | None | **Gap** |
+| DESCRIBE ODATA SERVICE | None | **Gap** |
+| CREATE ODATA SERVICE | None | **Gap** |
+| DROP ODATA SERVICE | None | **Gap** |
+| GRANT/REVOKE ODATA SERVICE | None | **Gap** |
+| SHOW EXTERNAL ENTITIES | None | **Gap** |
+| DESCRIBE EXTERNAL ENTITY | None | **Gap** |
+| CREATE EXTERNAL ENTITY | None | **Gap** |
+| CREATE EXTERNAL ENTITIES (bulk) | None | **Gap** |
+| SHOW PUBLISHED REST SERVICES | None | **Gap** |
+| DESCRIBE PUBLISHED REST SERVICE | None | **Gap** |
+| CREATE PUBLISHED REST SERVICE | None | **Gap** |
+| DROP PUBLISHED REST SERVICE | None | **Gap** |
+| GRANT/REVOKE REST SERVICE | None | **Gap** |
+| SHOW REST CLIENTS | None | **Gap** |
+| DESCRIBE REST CLIENT | None | **Gap** |
+| CREATE REST CLIENT (manual) | None | **Gap** |
+| CREATE REST CLIENT (OpenAPI) | None | **Gap** |
+| DROP REST CLIENT | None | **Gap** |
+| DESCRIBE CONTRACT OPERATION | None | **Gap** |
+| SHOW JSON STRUCTURES | None | **Gap** |
+| DESCRIBE JSON STRUCTURE | None | **Gap** |
+| CREATE JSON STRUCTURE | None | **Gap** |
+| DROP JSON STRUCTURE | None | **Gap** |
+| Roundtrip (all 6 types) | None | **Gap** |
+| Multi-step workflows (§40) | None | **Manual only** |
+| Failure modes (§41) | None | **Manual only** |
+
+Manual testing priority:
+1. Roundtrip all instances across 3 projects (bulk DESCRIBE→DROP→CREATE→DESCRIBE)
+2. Feature gate enforcement (pre-10.0, pre-10.1 projects)
+3. Multi-step workflows (§40) — highest interaction bug risk
+4. Failure modes (§41) — especially §41.5, §41.6, §41.10
+5. GRANT/REVOKE on OData services and Published REST services
+
+---
+
+## Manual Test Report Template
+
+Copy and fill in after running manual tests.
+
+```markdown
+## Manual Testing
+
+**Date:** YYYY-MM-DD
+**Build:** `make build && make test && make lint-go` — PASS
+
+### Test Projects
+
+| App | Studio Pro | SHOW counts (clients/services/entities/REST/JSON) | DESCRIBE sample | Roundtrip |
+|-----|-----------|---------------------------------------------------|-----------------|-----------|
+| Lato Enquiry Management | 11.4.0 | ✅ _/_/_/_/_ | ✅ _n_ tested | ✅ _n_ passed |
+| Evora Factory Management | 10.24.15 | ✅ _/_/_/_/_ | ✅ _n_ tested | ✅ _n_ passed |
+| Lato Product Inventory | 11.2.0 | ✅ _/_/_/_/_ | ✅ _n_ tested | ✅ _n_ passed |
+
+### OData Client Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW ODATA CLIENTS | ✅/❌ | |
+| SHOW ODATA CLIENTS IN module | ✅/❌ | |
+| DESCRIBE ODATA CLIENT | ✅/❌ | |
+| CREATE ODATA CLIENT | ✅/❌ | |
+| CREATE OR MODIFY ODATA CLIENT | ✅/❌ | |
+| ALTER ODATA CLIENT | ✅/❌ | |
+| DROP ODATA CLIENT | ✅/❌ | |
+
+### OData Service Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW ODATA SERVICES | ✅/❌ | |
+| SHOW ODATA SERVICES IN module | ✅/❌ | |
+| DESCRIBE ODATA SERVICE | ✅/❌ | |
+| CREATE ODATA SERVICE | ✅/❌ | |
+| CREATE OR MODIFY ODATA SERVICE | ✅/❌ | |
+| ALTER ODATA SERVICE | ✅/❌ | |
+| DROP ODATA SERVICE | ✅/❌ | |
+| GRANT ACCESS ON ODATA SERVICE | ✅/❌ | |
+| REVOKE ACCESS ON ODATA SERVICE | ✅/❌ | |
+
+### External Entity Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW EXTERNAL ENTITIES | ✅/❌ | |
+| SHOW EXTERNAL ENTITIES IN module | ✅/❌ | |
+| SHOW EXTERNAL ACTIONS | ✅/❌ | |
+| DESCRIBE EXTERNAL ENTITY | ✅/❌ | |
+| CREATE EXTERNAL ENTITY | ✅/❌ | |
+| CREATE OR MODIFY EXTERNAL ENTITY | ✅/❌ | |
+| CREATE EXTERNAL ENTITIES (bulk) | ✅/❌ | |
+| CREATE OR MODIFY EXTERNAL ENTITIES (selective) | ✅/❌ | |
+
+### Published REST Service Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW PUBLISHED REST SERVICES | ✅/❌ | |
+| SHOW PUBLISHED REST SERVICES IN module | ✅/❌ | |
+| DESCRIBE PUBLISHED REST SERVICE | ✅/❌ | |
+| CREATE PUBLISHED REST SERVICE | ✅/❌ | |
+| CREATE OR REPLACE PUBLISHED REST SERVICE | ✅/❌ | |
+| ALTER PUBLISHED REST SERVICE SET | ✅/❌ | |
+| ALTER PUBLISHED REST SERVICE ADD RESOURCE | ✅/❌ | |
+| ALTER PUBLISHED REST SERVICE DROP RESOURCE | ✅/❌ | |
+| DROP PUBLISHED REST SERVICE | ✅/❌ | |
+| GRANT ACCESS ON PUBLISHED REST SERVICE | ✅/❌ | |
+| REVOKE ACCESS ON PUBLISHED REST SERVICE | ✅/❌ | |
+
+### REST Client Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW REST CLIENTS | ✅/❌ | |
+| SHOW REST CLIENTS IN module | ✅/❌ | |
+| DESCRIBE REST CLIENT | ✅/❌ | |
+| CREATE REST CLIENT (manual) | ✅/❌ | |
+| CREATE REST CLIENT FROM OPENAPI (file) | ✅/❌ | |
+| CREATE REST CLIENT FROM OPENAPI (URL) | ✅/❌ | |
+| CREATE OR MODIFY REST CLIENT | ✅/❌ | |
+| DROP REST CLIENT | ✅/❌ | |
+| DESCRIBE CONTRACT OPERATION FROM OPENAPI | ✅/❌ | |
+
+### JSON Structure Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW JSON STRUCTURES | ✅/❌ | |
+| SHOW JSON STRUCTURES IN module | ✅/❌ | |
+| DESCRIBE JSON STRUCTURE | ✅/❌ | |
+| CREATE JSON STRUCTURE (single-quote) | ✅/❌ | |
+| CREATE JSON STRUCTURE (dollar-quoting) | ✅/❌ | |
+| CREATE JSON STRUCTURE (with folder/comment) | ✅/❌ | |
+| CREATE JSON STRUCTURE (custom name map) | ✅/❌ | |
+| CREATE OR REPLACE JSON STRUCTURE | ✅/❌ | |
+| DROP JSON STRUCTURE | ✅/❌ | |
+
+### Roundtrip Results
+
+```
+OData Clients:   _n_ tested, _n_ passed, _n_ failed
+OData Services:  _n_ tested, _n_ passed, _n_ failed
+External Entities: _n_ tested, _n_ passed, _n_ failed
+Published REST:  _n_ tested, _n_ passed, _n_ failed
+REST Clients:    _n_ tested, _n_ passed, _n_ failed
+JSON Structures: _n_ tested, _n_ passed, _n_ failed
+```
+
+### Multi-Step Workflows (§40)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 40.1 End-to-end REST integration | ✅/❌ | |
+| 40.2 OData publish-consume loop | ✅/❌ | |
+| 40.3 Scaffold module | ✅/❌ | |
+| 40.4 Iterative service evolution | ✅/❌ | |
+| 40.5 Drop/recreate different config | ✅/❌ | |
+
+### Failure Modes (§41)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 41.1 Not connected (all 6 types) | ✅/❌ | |
+| 41.2 Entity not found | ✅/❌ | |
+| 41.4 Invalid metadata URL | ✅/❌ | |
+| 41.5 Feature gate (pre-10.0) | ✅/❌ | |
+| 41.6 Feature gate (pre-10.1) | ✅/❌ | |
+| 41.7 Invalid JSON | ✅/❌ | |
+| 41.8 Non-existent microflow ref | ✅/❌ | |
+| 41.10 Validation mid-batch | ✅/❌ | |
+
+### Issues Found
+
+1. (none / describe issues here)
+```
diff --git a/docs/15-testing/mapping-test-cases.md b/docs/15-testing/mapping-test-cases.md
new file mode 100644
index 00000000..8c8f7e09
--- /dev/null
+++ b/docs/15-testing/mapping-test-cases.md
@@ -0,0 +1,509 @@
+# Mapping & Data Transformer Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Import Mappings | Export Mappings | Data Transformers |
+|-----|-----------|-----------------|-----------------|-------------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+> Data Transformers require Mendix 11.9+ (feature gate: `integration/data_transformer`). Only the Lato apps (11.x) may contain them. Evora (10.24.15) must not.
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show import mappings;" > /tmp/show-im.mdl
+  mxcli exec /tmp/show-im.mdl -p "$mpr" 2>&1 | tail -1
+  echo "show export mappings;" > /tmp/show-em.mdl
+  mxcli exec /tmp/show-em.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+All commands in this document are **read-only** (SHOW and DESCRIBE). No write guard warnings apply.
+
+---
+
+## 1. SHOW IMPORT MAPPINGS
+
+### 1.1 List all import mappings
+```
+show import mappings;
+```
+**Expected:** Table with columns: Import Mapping, Name, Schema Source, Elements. Count matches Studio Pro.
+
+### 1.2 Filter by module
+```
+show import mappings in MyModule;
+```
+**Expected:** Only import mappings from `MyModule`.
+
+### 1.3 Empty module
+```
+show import mappings in ModuleWithNoMappings;
+```
+**Expected:** Empty result, no error.
+
+### 1.4 Non-existent module
+```
+show import mappings in NonExistentModule;
+```
+**Expected:** Error message.
+
+### 1.5 Column accuracy
+Pick 5+ import mappings. Verify Schema Source and Elements columns match Studio Pro.
+
+---
+
+## 2. DESCRIBE IMPORT MAPPING
+
+### 2.1 Simple import mapping
+```
+describe import mapping Module.SimpleMapping;
+```
+**Expected:** Valid MDL output in the form:
+```
+create import mapping Module.SimpleMapping with json structure Module.Schema {
+  create Module.Entity {
+    Attr = jsonField key,
+  }
+};
+```
+
+### 2.2 Element rendering — object root
+Verify the root element uses handling keyword and entity reference:
+```
+create Module.Entity {
+  ...
+}
+```
+Valid handling keywords: `create` (default), `find`, `find or create`.
+
+### 2.3 Element rendering — nested object
+Verify nested elements use association path and `jsonKey`:
+```
+create Assoc/Entity = jsonKey {
+  ...
+}
+```
+
+### 2.4 Element rendering — value mapping
+Verify leaf values render as:
+```
+Attr = jsonField key,
+```
+The `key` suffix marks the key attribute.
+
+### 2.5 Handling keyword — find
+```
+describe import mapping Module.FindMapping;
+```
+**Expected:** Root element uses `find Module.Entity { ... }`.
+
+### 2.6 Handling keyword — find or create
+```
+describe import mapping Module.FindOrCreateMapping;
+```
+**Expected:** Root element uses `find or create Module.Entity { ... }`.
+
+### 2.7 Handling keyword — create (default)
+```
+describe import mapping Module.CreateMapping;
+```
+**Expected:** Root element uses `create Module.Entity { ... }`.
+
+### 2.8 Multiple root elements
+Test import mapping with multiple top-level mapped entities. Verify all rendered.
+
+### 2.9 Deeply nested structure (3+ levels)
+Verify correct indentation and nesting for mappings with 3+ levels of nested objects.
+
+### 2.10 Non-existent import mapping
+```
+describe import mapping Module.DoesNotExist;
+```
+**Expected:** Clear error message.
+
+---
+
+## 3. SHOW EXPORT MAPPINGS
+
+### 3.1 List all export mappings
+```
+show export mappings;
+```
+**Expected:** Table with columns: Export Mapping, Name, Schema Source, Elements. Count matches Studio Pro.
+
+### 3.2 Filter by module
+```
+show export mappings in MyModule;
+```
+**Expected:** Only export mappings from `MyModule`.
+
+### 3.3 Empty module
+```
+show export mappings in ModuleWithNoMappings;
+```
+**Expected:** Empty result, no error.
+
+### 3.4 Non-existent module
+```
+show export mappings in NonExistentModule;
+```
+**Expected:** Error message.
+
+### 3.5 Column accuracy
+Pick 5+ export mappings. Verify Schema Source and Elements columns match Studio Pro.
+
+---
+
+## 4. DESCRIBE EXPORT MAPPING
+
+### 4.1 Simple export mapping
+```
+describe export mapping Module.SimpleExport;
+```
+**Expected:** Valid MDL output in the form:
+```
+create export mapping Module.SimpleExport with json structure Module.Schema null values <option> {
+  Entity {
+    jsonField = Attr,
+    Assoc/Entity as jsonKey {
+      ...
+    }
+  }
+};
+```
+
+### 4.2 Assignment direction
+Verify export mappings use reversed assignment compared to import: `jsonField = Attr` (not `Attr = jsonField`).
+
+### 4.3 Nested element — `as` keyword
+Verify nested elements use the `as` keyword:
+```
+Assoc/Entity as jsonKey {
+  ...
+}
+```
+
+### 4.4 No handling keyword
+Verify export mapping elements omit handling keywords (`create`, `find`, `find or create`). These apply only to import mappings.
+
+### 4.5 NullValueOption — default (LeaveOutElement)
+```
+describe export mapping Module.DefaultNullExport;
+```
+**Expected:** `null values` clause omitted when option is `LeaveOutElement` (the default).
+
+### 4.6 NullValueOption — non-default
+```
+describe export mapping Module.NullAsDefaultExport;
+```
+**Expected:** `null values` clause present, e.g. `null values send default`.
+
+### 4.7 Multiple root entities
+Test export mapping with multiple top-level entities. Verify all rendered.
+
+### 4.8 Deeply nested structure (3+ levels)
+Verify correct indentation and nesting.
+
+### 4.9 Non-existent export mapping
+```
+describe export mapping Module.DoesNotExist;
+```
+**Expected:** Clear error message.
+
+---
+
+## 5. SHOW DATA TRANSFORMERS
+
+### 5.1 List all data transformers
+```
+show data transformers;
+```
+**Expected:** Table with columns: Qualified Name, Module, Name, Source, Steps. Steps column shows arrow-joined technology names (e.g. `JavaScript → OQL → JavaScript`).
+
+### 5.2 Filter by module
+```
+show data transformers in MyModule;
+```
+**Expected:** Only data transformers from `MyModule`.
+
+### 5.3 Empty module
+```
+show data transformers in ModuleWithNoTransformers;
+```
+**Expected:** Empty result, no error.
+
+### 5.4 Non-existent module
+```
+show data transformers in NonExistentModule;
+```
+**Expected:** Error message.
+
+### 5.5 Steps column formatting
+Verify steps display as arrow-joined technology names (tech names from steps, not expressions).
+
+### 5.6 Feature gate — Mendix 10.x project
+```
+mxcli repl -p <evora-10.24.15.mpr>
+show data transformers;
+```
+**Expected:** Error indicating data transformers require Mendix 11.9+ (feature gate: `integration/data_transformer`).
+
+---
+
+## 6. DESCRIBE DATA TRANSFORMER
+
+### 6.1 Simple data transformer
+```
+describe data transformer Module.SimpleTransformer;
+```
+**Expected:** Valid MDL output in the form:
+```
+create data transformer Module.SimpleTransformer source <SourceType> '<sourceJSON>' {
+  <Technology> '<expression>';
+};
+```
+
+### 6.2 Multi-line expression — dollar quoting
+Verify multi-line expressions use dollar-quoting:
+```
+create data transformer Module.MultiLine source JSON '{}' {
+  JavaScript $$
+    const x = input;
+    return x;
+  $$;
+};
+```
+
+### 6.3 Single-line expression — regular quoting
+Verify single-line expressions use regular quotes:
+```
+create data transformer Module.SingleLine source JSON '{}' {
+  OQL 'SELECT * FROM Module.Entity';
+};
+```
+
+### 6.4 Multiple steps
+```
+describe data transformer Module.MultiStep;
+```
+**Expected:** Multiple technology/expression pairs in sequence:
+```
+create data transformer Module.MultiStep source JSON '{}' {
+  JavaScript 'transform(input)';
+  OQL 'SELECT * FROM Module.Entity';
+  JavaScript 'format(input)';
+};
+```
+
+### 6.5 Source type rendering
+Verify source type appears correctly (e.g. `source JSON`, `source OQL`, etc.).
+
+### 6.6 Non-existent data transformer
+```
+describe data transformer Module.DoesNotExist;
+```
+**Expected:** Clear error message.
+
+### 6.7 Feature gate — Mendix 10.x project
+```
+mxcli repl -p <evora-10.24.15.mpr>
+describe data transformer Module.SomeTransformer;
+```
+**Expected:** Error indicating data transformers require Mendix 11.9+ (feature gate: `integration/data_transformer`).
+
+---
+
+## 7. FAILURE MODES
+
+### 7.1 Not connected
+Run any SHOW or DESCRIBE command without opening a project.
+```
+show import mappings;
+```
+**Expected:** Error about not being connected to a project.
+
+### 7.2 Import mapping not found
+```
+describe import mapping Module.DoesNotExist;
+```
+**Expected:** Clear error: mapping not found.
+
+### 7.3 Export mapping not found
+```
+describe export mapping Module.DoesNotExist;
+```
+**Expected:** Clear error: mapping not found.
+
+### 7.4 Data transformer not found
+```
+describe data transformer Module.DoesNotExist;
+```
+**Expected:** Clear error: data transformer not found.
+
+### 7.5 Feature gate violation — data transformer on <11.9
+Run SHOW DATA TRANSFORMERS and DESCRIBE DATA TRANSFORMER on Evora (10.24.15).
+**Expected:** Both commands produce a clear error referencing the `integration/data_transformer` feature gate and Mendix 11.9+ requirement.
+
+### 7.6 Error message quality
+For each error scenario, verify the message includes:
+- **What** went wrong
+- **Which** entity (qualified name)
+- **Actionable guidance** where applicable
+
+Scenarios: not-found (DESCRIBE import/export/transformer), not-connected (all commands), feature gate violation (data transformer).
+
+---
+
+## Test Project Coverage Matrix
+
+| Category | Enquiries (11.4.0) | Evora Factory (10.24.15) | Lato Inventory (11.2.0) |
+|---|---|---|---|
+| SHOW IMPORT MAPPINGS count | Verify | Verify | Verify |
+| SHOW EXPORT MAPPINGS count | Verify | Verify | Verify |
+| SHOW DATA TRANSFORMERS | Verify (if 11.9+) | Feature gate error | Verify (if 11.9+) |
+| DESCRIBE IMPORT MAPPING (sample 5+) | Diverse schemas | Diverse schemas | Diverse schemas |
+| DESCRIBE EXPORT MAPPING (sample 5+) | Diverse schemas | Diverse schemas | Diverse schemas |
+| DESCRIBE DATA TRANSFORMER (sample) | If available | Feature gate error | If available |
+| Filter by module | All 3 types | All 3 types | All 3 types |
+| Nested structures (3+ levels) | Import + Export | Import + Export | Import + Export |
+| Handling keywords (import) | create/find/find or create | Same | Same |
+| NullValueOption (export) | Default + non-default | Same | Same |
+| Dollar-quoting (transformer) | Multi-line expressions | N/A (10.x) | Multi-line expressions |
+| Error scenarios | Not-found for each type | Feature gate + not-found | Not-found for each type |
+
+---
+
+## Automated Test Coverage
+
+| Area | Tests | Status |
+|---|---|---|
+| SHOW IMPORT MAPPINGS | None | **Gap** |
+| SHOW IMPORT MAPPINGS IN module | None | **Gap** |
+| DESCRIBE IMPORT MAPPING | None | **Gap** |
+| SHOW EXPORT MAPPINGS | None | **Gap** |
+| SHOW EXPORT MAPPINGS IN module | None | **Gap** |
+| DESCRIBE EXPORT MAPPING | None | **Gap** |
+| SHOW DATA TRANSFORMERS | None | **Gap** |
+| SHOW DATA TRANSFORMERS IN module | None | **Gap** |
+| DESCRIBE DATA TRANSFORMER | None | **Gap** |
+| Feature gate (data transformer) | None | **Gap** |
+| Error handling (not-found) | None | **Gap** |
+| Error handling (not-connected) | None | **Gap** |
+
+Manual testing priority:
+1. SHOW counts for import/export mappings across all 3 projects
+2. DESCRIBE accuracy against Studio Pro for import and export mappings
+3. Handling keywords (create/find/find or create) on import mappings
+4. NullValueOption rendering on export mappings
+5. Data transformer feature gate enforcement on Evora (10.x)
+6. Dollar-quoting for multi-line transformer expressions
+
+---
+
+## Manual Test Report Template
+
+Copy and fill in after running manual tests.
+
+```markdown
+## Manual Testing
+
+**Date:** YYYY-MM-DD
+**Build:** `make build && make test && make lint-go` — PASS
+
+### Test Projects
+
+| App | Studio Pro | Import Mappings | Export Mappings | Data Transformers |
+|-----|-----------|-----------------|-----------------|-------------------|
+| Lato Enquiry Management | 11.4.0 | ✅ _n_ | ✅ _n_ | ✅ _n_ / N/A |
+| Evora Factory Management | 10.24.15 | ✅ _n_ | ✅ _n_ | ✅ Feature gate |
+| Lato Product Inventory | 11.2.0 | ✅ _n_ | ✅ _n_ | ✅ _n_ / N/A |
+
+### Command Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW IMPORT MAPPINGS | ✅/❌ | |
+| SHOW IMPORT MAPPINGS IN module | ✅/❌ | |
+| DESCRIBE IMPORT MAPPING | ✅/❌ | |
+| SHOW EXPORT MAPPINGS | ✅/❌ | |
+| SHOW EXPORT MAPPINGS IN module | ✅/❌ | |
+| DESCRIBE EXPORT MAPPING | ✅/❌ | |
+| SHOW DATA TRANSFORMERS | ✅/❌ | |
+| SHOW DATA TRANSFORMERS IN module | ✅/❌ | |
+| DESCRIBE DATA TRANSFORMER | ✅/❌ | |
+
+### Import Mapping DESCRIBE Accuracy
+
+| Mapping | Schema Source | Handling Keyword | Nested Levels | Match Studio Pro |
+|---------|-------------|-----------------|---------------|-----------------|
+| Module.Name | JSON/XML | create/find/find or create | _n_ | ✅/❌ |
+| ... | | | | |
+
+### Export Mapping DESCRIBE Accuracy
+
+| Mapping | Schema Source | NullValueOption | Nested Levels | Match Studio Pro |
+|---------|-------------|----------------|---------------|-----------------|
+| Module.Name | JSON/XML | default/non-default | _n_ | ✅/❌ |
+| ... | | | | |
+
+### Data Transformer DESCRIBE Accuracy
+
+| Transformer | Source Type | Steps | Dollar-Quoting | Match Studio Pro |
+|-------------|-----------|-------|----------------|-----------------|
+| Module.Name | JSON/OQL/... | _n_ | Yes/No/N/A | ✅/❌ |
+| ... | | | | |
+
+### Failure Modes (§7)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 7.1 Not connected | ✅/❌ | |
+| 7.2 Import mapping not found | ✅/❌ | |
+| 7.3 Export mapping not found | ✅/❌ | |
+| 7.4 Data transformer not found | ✅/❌ | |
+| 7.5 Feature gate (10.x) | ✅/❌ | |
+| 7.6 Error message quality | ✅/❌ | |
+
+### Issues Found
+
+1. (none / describe issues here)
+```
diff --git a/docs/15-testing/microflow-test-cases.md b/docs/15-testing/microflow-test-cases.md
new file mode 100644
index 00000000..c9ffec67
--- /dev/null
+++ b/docs/15-testing/microflow-test-cases.md
@@ -0,0 +1,1155 @@
+# Microflow Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Microflows | Java Actions | JS Actions |
+|-----|-----------|------------|--------------|------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show microflows;" > /tmp/show-mf.mdl
+  mxcli exec /tmp/show-mf.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N microflows)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+> **IMPORTANT:** Tests in sections 3+ require `MyModule` to exist with prerequisite entities (`Order`, `Customer`, `Product`, `Item`, `WorkflowContext`) and associations. Create these before running CREATE MICROFLOW tests, or use the multi-step script in section 16.1 as a starting point.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Dropped microflows cannot be recovered.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW MICROFLOWS
+
+### 1.1 List all microflows
+
+```
+show microflows;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Excluded | Folder | Params | Actions | McCabe | Returns`. Summary `(N microflows)`.
+
+### 1.2 List microflows in a module
+
+```
+show microflows in Administration;
+```
+
+**Expected:** Only microflows from `Administration` module.
+
+### 1.3 Empty module
+
+```
+show microflows in NonExistentModule;
+```
+
+**Expected:** `Error: module not found: NonExistentModule`.
+
+### 1.4 Verify excluded microflows
+
+```
+show microflows;
+```
+
+**Expected:** Excluded microflows show `true` in `Excluded` column (non-excluded show `false`).
+
+---
+
+## 2. DESCRIBE MICROFLOW
+
+### 2.1 Simple microflow
+
+```
+describe microflow Administration.NewAccount;
+```
+
+**Expected:** Roundtrippable MDL:
+```
+create or modify microflow Administration.NewAccount (
+  $AccountName: String
+)
+begin
+  ...
+end;
+/
+```
+
+> **Note:** `returns Void` is implicit — `describe` omits it for Void microflows.
+
+### 2.2 Microflow with parameters and return type
+
+```
+describe microflow <Module.MfWithReturn>;
+```
+
+**Expected:** Shows `returns <Type> as $VarName` with the AS clause when return variable name differs from default.
+
+### 2.3 Microflow with security roles
+
+```
+describe microflow <Module.SecuredMf>;
+```
+
+**Expected:** Output ends with `grant execute on microflow Module.Name to Role1, Role2;` before `/`.
+
+### 2.4 Microflow with error handling
+
+```
+describe microflow <Module.MfWithErrorHandling>;
+```
+
+**Expected:** Activities show `on error continue`, `on error rollback`, or `on error { ... }` blocks.
+
+### 2.5 Microflow with annotations
+
+```
+describe microflow <Module.AnnotatedMf>;
+```
+
+**Expected:** Shows `@annotation 'text'`, `@position(x,y)`, `@caption 'text'`, `@color Color` on activities.
+
+### 2.6 Excluded microflow
+
+```
+describe microflow <Module.ExcludedMf>;
+```
+
+**Expected:** Output starts with `@excluded` before `create or modify microflow`.
+
+### 2.7 Microflow in folder
+
+```
+describe microflow <Module.FolderMf>;
+```
+
+**Expected:** Shows `folder 'path/to/folder'` after returns clause.
+
+### 2.8 Non-existent microflow
+
+```
+describe microflow Fake.Missing;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 3. CREATE MICROFLOW
+
+### 3.1 Minimal microflow (no-op)
+
+```
+create microflow MyModule.MF_DoNothing ()
+returns Void
+begin
+end;
+```
+
+**Expected:** Microflow created. `show microflows in MyModule` includes it.
+
+### 3.2 Microflow with parameters
+
+```
+create microflow MyModule.MF_Greet (
+  $Name: String,
+  $Count: Integer
+)
+returns String
+begin
+  return 'Hello ' + $Name;
+end;
+```
+
+**Expected:** Created with 2 parameters, returns String.
+
+### 3.3 Entity parameter (object)
+
+```
+create microflow MyModule.MF_ProcessOrder (
+  $Order: MyModule.Order
+)
+returns Void
+begin
+  commit $Order with events;
+end;
+```
+
+**Expected:** Parameter type is `MyModule.Order`. Activity uses `commit ... with events`.
+
+### 3.4 List parameter
+
+```
+create microflow MyModule.MF_CountItems (
+  $Items: List of MyModule.Item
+)
+returns Integer
+begin
+  declare $Count Integer = count($Items);
+  return $Count;
+end;
+```
+
+**Expected:** List parameter and count aggregate.
+
+### 3.5 Variable declaration and assignment
+
+```
+create microflow MyModule.MF_Variables ()
+returns String
+begin
+  declare $greeting String = 'Hello';
+  set $greeting = $greeting + ' World';
+  return $greeting;
+end;
+```
+
+**Expected:** Created. `describe` shows declare + set + return.
+
+### 3.6 If/else control flow
+
+```
+create microflow MyModule.MF_CheckAge (
+  $Age: Integer
+)
+returns String
+begin
+  if $Age >= 18 then
+    return 'Adult';
+  else
+    return 'Minor';
+  end if;
+end;
+```
+
+**Expected:** Created with if/else structure.
+
+### 3.7 Loop
+
+```
+create microflow MyModule.MF_SumPrices (
+  $Products: List of MyModule.Product
+)
+returns Decimal
+begin
+  declare $Total Decimal = 0;
+  loop $Item in $Products
+  begin
+    set $Total = $Total + $Item/Price;
+  end loop;
+  return $Total;
+end;
+```
+
+**Expected:** Loop over list with accumulator.
+
+### 3.8 Object create and change
+
+```
+create microflow MyModule.MF_CreateProduct (
+  $Name: String,
+  $Price: Decimal
+)
+returns MyModule.Product
+begin
+  $Product = create MyModule.Product (
+    Name = $Name,
+    Price = $Price,
+    IsActive = true
+  );
+  commit $Product;
+  return $Product;
+end;
+```
+
+**Expected:** Create object + commit + return.
+
+### 3.9 Retrieve by association
+
+```
+create microflow MyModule.MF_GetCustomer (
+  $Order: MyModule.Order
+)
+returns MyModule.Customer
+begin
+  retrieve $Customer from $Order/MyModule.Order_Customer;
+  return $Customer;
+end;
+```
+
+**Expected:** Association retrieve.
+
+### 3.10 Database retrieve (XPath)
+
+```
+create microflow MyModule.MF_FindActive ()
+returns List of MyModule.Product
+begin
+  retrieve $Products from MyModule.Product where [IsActive = true] sort by Name limit 10;
+  return $Products;
+end;
+```
+
+**Expected:** XPath retrieve with sort, limit.
+
+### 3.11 Call microflow
+
+```
+create microflow MyModule.MF_Orchestrate (
+  $Order: MyModule.Order
+)
+returns Void
+begin
+  call microflow MyModule.MF_ProcessOrder(Order = $Order);
+end;
+```
+
+**Expected:** Call action referencing another microflow.
+
+### 3.12 Call Java action
+
+```
+create microflow MyModule.MF_WithJava (
+  $Input: String
+)
+returns String
+begin
+  $Result = call java action MyModule.JA_Transform(Input = $Input);
+  return $Result;
+end;
+```
+
+**Expected:** Java action call (microflow-only — not available in nanoflows).
+
+### 3.13 Call JavaScript action
+
+```
+create microflow MyModule.MF_WithJS ()
+returns Void
+begin
+  call javascript action MyModule.JSA_ShowNotification('Done');
+end;
+```
+
+**Expected:** JavaScript action call.
+
+### 3.14 REST call
+
+```
+create microflow MyModule.MF_ApiCall ()
+returns String
+begin
+  $Response = rest call get 'https://api.example.com/data'
+    header 'Authorization' = 'Bearer token123'
+    timeout 30
+    returns string;
+  return $Response;
+end;
+```
+
+**Expected:** REST call activity (microflow-only).
+
+### 3.15 Show page
+
+```
+create microflow MyModule.MF_OpenDetail (
+  $Product: MyModule.Product
+)
+returns Void
+begin
+  show page MyModule.Product_Detail($Product = $Product);
+end;
+```
+
+**Expected:** Show page with object parameter.
+
+### 3.16 Show message
+
+```
+create microflow MyModule.MF_Notify ()
+returns Void
+begin
+  show message 'Operation completed successfully' type Info;
+end;
+```
+
+**Expected:** Show message activity.
+
+### 3.17 Log message
+
+```
+create microflow MyModule.MF_Logged ()
+returns Void
+begin
+  log info node 'MyModule' 'Processing started';
+end;
+```
+
+**Expected:** Log message with level and node.
+
+### 3.18 Error handling
+
+```
+create microflow MyModule.MF_SafeCall ()
+returns Boolean
+begin
+  call microflow MyModule.MF_Risky() on error continue;
+  return true;
+end;
+```
+
+**Expected:** Error handling annotation on individual activity.
+
+> **Note:** Error handling block syntax `on error continue begin...end` is NOT supported. Error handling is an annotation on individual activities, e.g. `call microflow M.F(P = $V) on error continue;`
+
+### 3.19 Import/Export mapping
+
+```
+create microflow MyModule.MF_ImportData (
+  $Json: String
+)
+returns MyModule.Data
+begin
+  $Result = import from mapping MyModule.DataMapping source $Json;
+  return $Result;
+end;
+```
+
+**Expected:** Import mapping activity (microflow-only).
+
+> **Note:** `source` is a reserved keyword. Avoid using `$Source` as a variable name or quote it. This is a known parser limitation.
+
+### 3.20 Workflow actions
+
+```
+create microflow MyModule.MF_StartWorkflow (
+  $Context: MyModule.WorkflowContext
+)
+returns Void
+begin
+  call workflow MyModule.ApprovalWorkflow(Context = $Context);
+end;
+```
+
+**Expected:** Workflow call activity (microflow-only).
+
+> **Note:** The entity `MyModule.WorkflowContext` must exist before running this test. Create it as a prerequisite or substitute with any existing entity in the test project.
+
+### 3.21 `create or modify` — existing microflow
+
+```
+create or modify microflow MyModule.MF_DoNothing ()
+returns Void
+begin
+  log info 'Modified';
+end;
+```
+
+**Expected:** Output says "Replaced microflow" (updates existing microflow body).
+
+### 3.22 `create or replace` — drop and recreate
+
+```
+create or replace microflow MyModule.MF_DoNothing ()
+returns Void
+begin
+  log info 'Replaced';
+end;
+```
+
+**Expected:** Drops and recreates (new ID but preserves security roles via remember/consume pattern).
+
+### 3.23 Duplicate (without modifier)
+
+```
+create microflow MyModule.MF_DoNothing ()
+returns Void
+begin
+end;
+```
+
+**Expected:** Error — microflow already exists.
+
+---
+
+## 4. DROP MICROFLOW
+
+### 4.1 Drop existing microflow
+
+```
+drop microflow MyModule.MF_DoNothing;
+```
+
+**Expected:** Microflow removed.
+
+### 4.2 Drop non-existent microflow
+
+```
+drop microflow MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 5. SHOW JAVA ACTIONS
+
+### 5.1 List all Java actions
+
+```
+show java actions;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Folder`.
+
+### 5.2 List Java actions in a module
+
+```
+show java actions in MyModule;
+```
+
+**Expected:** Only Java actions from specified module.
+
+---
+
+## 6. DESCRIBE JAVA ACTION
+
+### 6.1 Basic Java action
+
+```
+describe java action <Module.JavaAction>;
+```
+
+**Expected:**
+```
+create java action Module.Name(
+    ParamName: Type not null  -- description
+)
+returns Type
+exposed as 'Caption' in 'Category'
+as $$
+  // Java code from javasource/
+$$;
+```
+
+### 6.2 Java action with entity type parameter
+
+```
+describe java action <Module.GenericAction>;
+```
+
+**Expected:** Parameter shows `TypeParameter` for entity type selector (not `entity <T>` syntax).
+
+> **Note:** The input syntax for entity type parameters (§7.2 `entity T`) is currently broken.
+
+---
+
+## 7. CREATE JAVA ACTION
+
+### 7.1 Basic Java action
+
+```
+create java action MyModule.JA_Hash(
+  Input: String not null
+)
+returns String
+as $$
+  return DigestUtils.sha256Hex(Input);
+$$;
+```
+
+**Expected:** Java action created.
+
+### 7.2 Java action with entity type parameter
+
+```
+create java action MyModule.JA_Export(
+  Object: entity T
+)
+returns String
+as $$
+  return serialize(Object);
+$$;
+```
+
+**Expected:** Entity type parameter `T` created.
+
+### 7.3 Exposed Java action
+
+```
+create java action MyModule.JA_Public(
+  Value: Integer
+)
+returns Integer
+exposed as 'Double Value' in 'Math'
+as $$
+  return Value * 2;
+$$;
+```
+
+**Expected:** Java action exposed in microflow toolbox under specified category.
+
+---
+
+## 8. SHOW JAVASCRIPT ACTIONS
+
+### 8.1 List all JavaScript actions
+
+```
+show javascript actions;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Platform | Folder`.
+
+### 8.2 Platform values
+
+Verify Platform column shows `Web`, `Native`, or `All`.
+
+---
+
+## 9. DESCRIBE JAVASCRIPT ACTION
+
+### 9.1 Basic JavaScript action
+
+```
+describe javascript action <Module.JSAction>;
+```
+
+**Expected:**
+```
+create javascript action Module.Name<TypeParam>(
+    ParamName: Type not null  -- description
+)
+  PLATFORM Web
+  returns Type
+  exposed as 'Caption' in 'Category'
+as $$
+  // JavaScript code
+$$;
+```
+
+### 9.2 JavaScript action with type parameters
+
+Verify `<T>` syntax after action name for generic type parameters.
+
+> **Note:** CREATE JAVASCRIPT ACTION is not supported in MDL. JavaScript actions are authored externally in `.js` files under `javascriptsource/`. Only SHOW and DESCRIBE are available.
+
+---
+
+## 10. CALL MICROFLOW
+
+### 10.1 Call with arguments
+
+```
+create microflow MyModule.MF_Caller ()
+returns String
+begin
+  $Result = call microflow MyModule.MF_Greet(Name = 'World', Count = 1);
+  return $Result;
+end;
+```
+
+**Expected:** Arguments passed as named parameters.
+
+### 10.2 Call with entity argument
+
+```
+create microflow MyModule.MF_CallWithObj (
+  $Order: MyModule.Order
+)
+returns Void
+begin
+  call microflow MyModule.MF_ProcessOrder(Order = $Order);
+end;
+```
+
+**Expected:** Entity variable passed to microflow.
+
+### 10.3 Recursive call
+
+```
+create microflow MyModule.MF_Recursive (
+  $N: Integer
+)
+returns Integer
+begin
+  if $N <= 1 then
+    return 1;
+  else
+    $Prev = call microflow MyModule.MF_Recursive(N = $N - 1);
+    return $N * $Prev;
+  end if;
+end;
+```
+
+**Expected:** Self-referencing call accepted.
+
+---
+
+## 11. GRANT / REVOKE EXECUTE ON MICROFLOW
+
+### 11.1 Grant execute
+
+```
+grant execute on microflow MyModule.MF_ProcessOrder to MyModule.Manager, MyModule.Admin;
+```
+
+**Expected:** Roles granted. `describe` shows grant statement.
+
+### 11.2 Revoke execute
+
+```
+revoke execute on microflow MyModule.MF_ProcessOrder from MyModule.Manager;
+```
+
+**Expected:** Role removed. `describe` shows remaining grants.
+
+### 11.3 Grant to non-existent role
+
+```
+grant execute on microflow MyModule.MF_ProcessOrder to FakeRole;
+```
+
+**Expected:** Error — role not found.
+
+---
+
+## 12. SHOW ACCESS ON MICROFLOW
+
+### 12.1 Show access
+
+```
+show access on microflow MyModule.MF_ProcessOrder;
+```
+
+**Expected:** List of roles with execute permission.
+
+---
+
+## 13. RENAME MICROFLOW
+
+### 13.1 Rename microflow
+
+```
+rename microflow MyModule.MF_OldName to MF_NewName;
+```
+
+**Expected:** Microflow renamed. References updated.
+
+---
+
+## 14. MOVE MICROFLOW
+
+### 14.1 Move to different module
+
+```
+move microflow MyModule.MF_Moved to OtherModule;
+```
+
+**Expected:** Microflow relocated.
+
+### 14.2 Move to folder
+
+```
+move microflow MyModule.MF_Moved to folder 'SubFolder';
+```
+
+**Expected:** Microflow placed in folder.
+
+---
+
+## 15. ROUNDTRIP (BSON)
+
+### 15.1 Simple microflow roundtrip
+
+```
+create microflow RtTest.MF_Simple (
+  $Name: String
+)
+returns String
+begin
+  return 'Hello ' + $Name;
+end;
+```
+
+1. `describe microflow RtTest.MF_Simple`
+2. Drop: `drop microflow RtTest.MF_Simple`
+3. Execute described MDL
+4. `describe` again
+
+**Expected:** Output identical between step 1 and step 4.
+
+### 15.2 Complex microflow roundtrip
+
+Create a microflow with multiple activity types (if/else, loop, retrieve, create object, log). Verify roundtrip preserves all activities and their order.
+
+> **Known issue:** Negative position coordinates (`@position(-115, -20)`) snap to 0 on recreate. Caption annotation ordering may vary.
+
+---
+
+## 16. MULTI-STEP WORKFLOWS
+
+### 16.1 Create entity → microflow → grant
+
+```
+create persistent entity MyModule.Order (
+  Number: string(50) not null
+);
+
+create microflow MyModule.MF_CreateOrder (
+  $Number: String
+)
+returns MyModule.Order
+begin
+  $Order = create MyModule.Order (Number = $Number);
+  commit $Order;
+  return $Order;
+end;
+
+create module role MyModule.OrderClerk;
+grant execute on microflow MyModule.MF_CreateOrder to MyModule.OrderClerk;
+```
+
+**Expected:** All succeed. `describe microflow` shows grant.
+
+### 16.2 Chain microflow calls
+
+```
+create microflow MyModule.MF_Step1 () returns Integer
+begin return 1; end;
+
+create microflow MyModule.MF_Step2 () returns Integer
+begin
+  $V = call microflow MyModule.MF_Step1();
+  return $V + 1;
+end;
+```
+
+**Expected:** Both created. Callers/callees relationship established.
+
+---
+
+## 17. FAILURE MODES & ERROR RECOVERY
+
+### 17.1 Unknown activity type
+
+```
+create microflow MyModule.MF_Bad ()
+returns Void
+begin
+  unknownaction;
+end;
+```
+
+**Expected:** Parser error. No microflow created.
+
+### 17.2 Missing parameter type
+
+```
+create microflow MyModule.MF_Bad (
+  $X
+)
+returns Void
+begin
+end;
+```
+
+**Expected:** Error — parameter type required.
+
+### 17.3 Call non-existent microflow
+
+```
+create microflow MyModule.MF_BadCall ()
+returns Void
+begin
+  call microflow MyModule.MF_DoesNotExist();
+end;
+```
+
+**Expected:** **Known issue (BUG-008):** Microflow created without validation. Cross-reference validation not performed at create time.
+
+### 17.4 Return type mismatch
+
+```
+create microflow MyModule.MF_WrongReturn ()
+returns Integer
+begin
+  return 'not an integer';
+end;
+```
+
+**Expected:** **Known issue:** Return type mismatch not validated at create time.
+
+---
+
+## 18. SECURITY CASCADES
+
+### 18.1 Drop microflow with grants
+
+```
+drop microflow MyModule.MF_ProcessOrder;
+```
+
+**Expected:** Microflow and its access rules removed. `show access` no longer lists it.
+
+### 18.2 Grant on non-existent microflow
+
+```
+grant execute on microflow MyModule.Fake to Admin;
+```
+
+**Expected:** Error — microflow not found.
+
+---
+
+## 19. BOUNDARY & STRESS
+
+### 19.1 Microflow with many activities (50+)
+
+Create a microflow with 50+ sequential activities. Verify `describe` handles large bodies.
+
+### 19.2 Deeply nested control flow
+
+```
+create microflow MyModule.MF_Nested ()
+returns Void
+begin
+  if true then
+    if true then
+      if true then
+        log info 'Deep';
+      end if;
+    end if;
+  end if;
+end;
+```
+
+**Expected:** Created and described with correct indentation.
+
+### 19.3 Many parameters (20+)
+
+Create a microflow with 20 parameters. Verify `show` and `describe` display all.
+
+---
+
+## 20. DIAGRAM OUTPUT
+
+### 20.1 ELK diagram
+
+```
+describe microflow MyModule.MF_Complex --format elk;
+```
+
+**Expected:** JSON layout data with nodes and edges for each activity.
+
+> **Note:** ELK format flag not implemented in current build. Mark as SKIP until feature lands.
+
+### 20.2 Mermaid diagram
+
+```
+describe microflow MyModule.MF_Complex --format mermaid;
+```
+
+**Expected:** Mermaid flowchart syntax showing activity flow.
+
+> **Note:** Mermaid format flag not implemented in current build. Mark as SKIP until feature lands.
+
+---
+
+## Activity Coverage Table
+
+| Activity Type | Test Case | Section |
+|---------------|-----------|---------|
+| declare/set variable | 3.5 | CREATE |
+| if/else | 3.6 | CREATE |
+| loop | 3.7 | CREATE |
+| create object | 3.8 | CREATE |
+| commit (with events) | 3.3 | CREATE |
+| retrieve (association) | 3.9 | CREATE |
+| retrieve (XPath) | 3.10 | CREATE |
+| call microflow | 3.11, 10.x | CREATE, CALL |
+| call java action | 3.12 | CREATE |
+| call javascript action | 3.13 | CREATE |
+| rest call | 3.14 | CREATE |
+| show page | 3.15 | CREATE |
+| show message | 3.16 | CREATE |
+| log message | 3.17 | CREATE |
+| error handling | 3.18 | CREATE |
+| import mapping | 3.19 | CREATE |
+| workflow call | 3.20 | CREATE |
+| return | 3.2, 3.5–3.10 | CREATE |
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW MICROFLOWS | x | x | x |
+| DESCRIBE MICROFLOW | x | x | x |
+| CREATE MICROFLOW | x | | |
+| DROP MICROFLOW | x | | |
+| SHOW JAVA ACTIONS | x | x | x |
+| DESCRIBE JAVA ACTION | x | x | |
+| CREATE JAVA ACTION | x | | |
+| SHOW JS ACTIONS | x | x | x |
+| DESCRIBE JS ACTION | x | x | |
+| CALL MICROFLOW | x | | |
+| GRANT/REVOKE | x | | |
+| RENAME/MOVE | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW MICROFLOWS | Mock tests | |
+| 2. DESCRIBE MICROFLOW | Mock tests | Error handling, annotations |
+| 3. CREATE MICROFLOW | Mock tests | Complex activities |
+| 4. DROP MICROFLOW | Mock tests | |
+| 5–6. JAVA ACTIONS | Mock tests | |
+| 7. CREATE JAVA ACTION | Mock tests | Entity type params |
+| 8–9. JS ACTIONS | Mock tests | |
+| 10. CALL MICROFLOW | Mock tests | |
+| 11. GRANT/REVOKE | Mock tests | |
+| 12. SHOW ACCESS | Mock tests | |
+| 13–14. RENAME/MOVE | Mock tests | |
+| 15. Roundtrip | | Complex flows |
+| 16. Multi-step | | All manual |
+| 17. Failure modes | Partial | Type mismatch |
+| 18. Security cascades | | All manual |
+| 19. Boundary | | All manual |
+| 20. Diagram | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW MF | List all | | | | |
+| 1.2 | SHOW MF | Filter module | | | | |
+| 1.3 | SHOW MF | Empty module | | | | |
+| 1.4 | SHOW MF | Excluded flag | | | | |
+| 2.1 | DESCRIBE | Simple | | | | |
+| 2.2 | DESCRIBE | Params + return | | | | |
+| 2.3 | DESCRIBE | Security roles | | | | |
+| 2.4 | DESCRIBE | Error handling | | | | |
+| 2.5 | DESCRIBE | Annotations | | | | |
+| 2.6 | DESCRIBE | Excluded | | | | |
+| 2.7 | DESCRIBE | In folder | | | | |
+| 2.8 | DESCRIBE | Not found | | | | |
+| 3.1 | CREATE | Minimal | | | | |
+| 3.2 | CREATE | Parameters | | | | |
+| 3.3 | CREATE | Entity param | | | | |
+| 3.4 | CREATE | List param | | | | |
+| 3.5 | CREATE | Variables | | | | |
+| 3.6 | CREATE | If/else | | | | |
+| 3.7 | CREATE | Loop | | | | |
+| 3.8 | CREATE | Create object | | | | |
+| 3.9 | CREATE | Retrieve assoc | | | | |
+| 3.10 | CREATE | Retrieve XPath | | | | |
+| 3.11 | CREATE | Call microflow | | | | |
+| 3.12 | CREATE | Call Java | | | | |
+| 3.13 | CREATE | Call JavaScript | | | | |
+| 3.14 | CREATE | REST call | | | | |
+| 3.15 | CREATE | Show page | | | | |
+| 3.16 | CREATE | Show message | | | | |
+| 3.17 | CREATE | Log message | | | | |
+| 3.18 | CREATE | Error handling | | | | |
+| 3.19 | CREATE | Import mapping | | | | |
+| 3.20 | CREATE | Workflow call | | | | |
+| 3.21 | CREATE | create or modify | | | | |
+| 3.22 | CREATE | create or replace | | | | |
+| 3.23 | CREATE | Duplicate error | | | | |
+| 4.1 | DROP | Existing | | | | |
+| 4.2 | DROP | Non-existent | | | | |
+| 5.1 | JAVA SHOW | List all | | | | |
+| 5.2 | JAVA SHOW | Filter module | | | | |
+| 6.1 | JAVA DESC | Basic | | | | |
+| 6.2 | JAVA DESC | Entity type param | | | | |
+| 7.1 | JAVA CREATE | Basic | | | | |
+| 7.2 | JAVA CREATE | Entity type | | | | |
+| 7.3 | JAVA CREATE | Exposed | | | | |
+| 8.1 | JS SHOW | List all | | | | |
+| 8.2 | JS SHOW | Platform values | | | | |
+| 9.1 | JS DESC | Basic | | | | |
+| 9.2 | JS DESC | Type parameters | | | | |
+| 10.1 | CALL | With arguments | | | | |
+| 10.2 | CALL | Entity argument | | | | |
+| 10.3 | CALL | Recursive | | | | |
+| 11.1 | GRANT | Execute | | | | |
+| 11.2 | REVOKE | Execute | | | | |
+| 11.3 | GRANT | Non-existent role | | | | |
+| 12.1 | ACCESS | Show access | | | | |
+| 13.1 | RENAME | Rename microflow | | | | |
+| 14.1 | MOVE | To module | | | | |
+| 14.2 | MOVE | To folder | | | | |
+| 15.1 | ROUNDTRIP | Simple | | | | |
+| 15.2 | ROUNDTRIP | Complex | | | | |
+| 16.1 | MULTI-STEP | Entity + mf + grant | | | | |
+| 16.2 | MULTI-STEP | Chain calls | | | | |
+| 17.1 | FAILURE | Unknown activity | | | | |
+| 17.2 | FAILURE | Missing param type | | | | |
+| 17.3 | FAILURE | Call non-existent | | | | |
+| 17.4 | FAILURE | Return mismatch | | | | |
+| 18.1 | SECURITY | Drop with grants | | | | |
+| 18.2 | SECURITY | Grant on non-existent | | | | |
+| 19.1 | BOUNDARY | Many activities | | | | |
+| 19.2 | BOUNDARY | Deep nesting | | | | |
+| 19.3 | BOUNDARY | Many parameters | | | | |
+| 20.1 | DIAGRAM | ELK | | | | |
+| 20.2 | DIAGRAM | Mermaid | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/nanoflow-test-cases.md b/docs/15-testing/nanoflow-test-cases.md
index c7a0748e..41da82f0 100644
--- a/docs/15-testing/nanoflow-test-cases.md
+++ b/docs/15-testing/nanoflow-test-cases.md
@@ -1,7 +1,7 @@
 # Nanoflow Test Cases — Manual Testing
 
 **Updated:** 2026-04-28
-**PR:** [mendixlabs/mxcli#301](https://github.com/mendixlabs/mxcli/pull/301)
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
 
 ## Test Projects
 
@@ -339,7 +339,7 @@ create nanoflow MyModule.BadRef () begin
   call nanoflow NonExistent.Flow ();
 end;
 ```
-**Expected:** Error — target nanoflow not found.
+**Expected:** Nanoflow created (call target references not validated at CREATE time). This is a known design gap.
 
 ### 4.6 Non-existent page target
 ```
@@ -347,7 +347,7 @@ create nanoflow MyModule.BadPage () begin
   show page NonExistent.Page ();
 end;
 ```
-**Expected:** Error — target page not found.
+**Expected:** Nanoflow created (call target references not validated at CREATE time). This is a known design gap.
 
 ### 4.7 Non-existent microflow target
 ```
@@ -355,7 +355,7 @@ create nanoflow MyModule.BadMF () begin
   call microflow NonExistent.Flow ();
 end;
 ```
-**Expected:** Error — target microflow not found.
+**Expected:** Nanoflow created (call target references not validated at CREATE time). This is a known design gap.
 
 ---
 
@@ -544,7 +544,7 @@ rename nanoflow MyModule.OldName to NewName;
 Rename nanoflow called by another flow. Verify caller's reference updated.
 
 ### 9.3 Rename to existing name
-**Expected:** Error — name collision.
+**Expected:** ~~Error — name collision.~~ Rename collision detection is not implemented. The rename succeeds, resulting in duplicate names. **Known gap.**
 
 ---
 
diff --git a/docs/15-testing/navigation-settings-test-cases.md b/docs/15-testing/navigation-settings-test-cases.md
new file mode 100644
index 00000000..b59b440e
--- /dev/null
+++ b/docs/15-testing/navigation-settings-test-cases.md
@@ -0,0 +1,916 @@
+# Navigation & Settings Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Nav Profiles | Configurations | Languages |
+|-----|-----------|--------------|----------------|-----------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Navigation and settings changes modify the `.mpr` in place.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW NAVIGATION
+
+### 1.1 List all navigation profiles
+
+```
+show navigation;
+```
+
+**Expected:** Table with columns `Profile | Kind | HomePage | LoginPage | MenuItems | RoleHomes`. Kind shows navigation type with `(native)` suffix for native profiles. Summary `(N navigation profiles)`.
+
+### 1.2 Verify Kind column format
+
+Inspect each row in the output.
+
+**Expected:** Kind values like `Responsive`, `Tablet (native)`, `Phone (native)`. The `(native)` suffix appears only on native navigation profiles.
+
+---
+
+## 2. SHOW NAVIGATION MENU
+
+### 2.1 Menu tree for a profile
+
+```
+show navigation menu Responsive;
+```
+
+**Expected:** Tree output with indentation showing menu hierarchy. Each leaf shows target: page or microflow qualified name.
+
+### 2.2 Nested menu items
+
+```
+show navigation menu Responsive;
+```
+
+**Expected:** Nested items indented under parent menu groups. Format:
+
+```
+Administration
+  Account Overview → page Administration.AccountOverview
+  My Account → page Administration.MyAccount
+```
+
+### 2.3 Menu with microflow target
+
+If a menu item targets a microflow:
+
+**Expected:** Line shows `-> MF:Module.MicroflowName`.
+
+### 2.4 Non-existent profile
+
+```
+show navigation menu FakeProfile;
+```
+
+**Expected:** ~~Error — navigation profile not found.~~ Returns empty output with exit code 0 instead of an error. **Known inconsistency.**
+
+---
+
+## 3. SHOW NAVIGATION HOMES
+
+### 3.1 View home pages per profile
+
+```
+show navigation homes;
+```
+
+**Expected:** Per-profile output showing Default Home page and Role-Based Homes. Each role-based entry shows the role name and target page.
+
+### 3.2 Profile with no role-based homes
+
+If a profile has only a default home:
+
+**Expected:** Default Home listed. Role-Based Homes section empty or absent.
+
+---
+
+## 4. DESCRIBE NAVIGATION
+
+### 4.1 Describe a profile
+
+```
+describe navigation Responsive;
+```
+
+**Expected:** Full MDL output:
+
+```mdl
+create or replace navigation Responsive
+  home page Module.HomePage
+  login page Module.LoginPage
+  not found page Module.NotFoundPage
+  menu (
+    menu item 'Overview' page Module.Overview;
+    menu 'Admin' (
+      menu item 'Users' page Administration.AccountOverview;
+    );
+  );
+```
+
+### 4.2 Profile with microflow home
+
+If the home target is a microflow:
+
+**Expected:** MDL shows `home microflow Module.MicroflowName` instead of `home page`.
+
+### 4.3 Profile with role-based homes
+
+**Expected:** MDL includes `home page Module.Page for Role.Name` entries.
+
+### 4.4 Non-existent profile
+
+```
+describe navigation FakeProfile;
+```
+
+**Expected:** Error — navigation profile not found.
+
+---
+
+## 5. CREATE OR REPLACE NAVIGATION
+
+### 5.1 Replace home page
+
+```
+create or replace navigation Responsive
+  home page MyModule.NewHome;
+```
+
+**Expected:** Home page updated. Verify with `describe navigation Responsive`.
+
+### 5.2 Replace login page
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  login page MyModule.NewLogin;
+```
+
+**Expected:** Login page updated. Omitted clauses (menu, not found page) cleared.
+
+### 5.3 Full replacement semantics — omitted clauses clear
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home;
+```
+
+**Expected:** Login page, not found page, ~~and menu all~~ cleared. Verify with `describe navigation Responsive` — only `home page` present.
+
+> **Note:** Menu is **NOT** cleared when omitted from `CREATE OR REPLACE NAVIGATION`. Only login page and role-based homes are cleared. This is a known inconsistency.
+
+### 5.4 Replace menu block
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  menu (
+    menu item 'Dashboard' page MyModule.Dashboard;
+  );
+```
+
+**Expected:** Existing menu replaced entirely. Only `Dashboard` item remains.
+
+### 5.5 Nested menu items
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  menu (
+    menu 'Admin' (
+      menu item 'Users' page Administration.AccountOverview;
+      menu item 'Settings' page Administration.Settings;
+    );
+    menu item 'Home' page MyModule.Home;
+  );
+```
+
+**Expected:** Menu contains nested `Admin` group with two children and top-level `Home` item.
+
+### 5.6 Microflow menu target
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  menu (
+    menu item 'Run Report' microflow MyModule.MF_RunReport;
+  );
+```
+
+**Expected:** Menu item targets microflow. Verify with `describe navigation Responsive`.
+
+### 5.7 Role-based homes
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  home page MyModule.AdminHome for Administration.Administrator;
+```
+
+**Expected:** Default home and role-based home set. Verify with `show navigation homes`.
+
+### 5.8 Microflow home
+
+```
+create or replace navigation Responsive
+  home microflow MyModule.MF_Startup;
+```
+
+**Expected:** Home targets microflow. Verify with `describe navigation Responsive`.
+
+---
+
+## 6. SHOW SETTINGS
+
+### 6.1 View all settings
+
+```
+show settings;
+```
+
+**Expected:** Output organized in sections: Model Settings, Configuration, Language Settings, Workflow Settings.
+
+### 6.2 Not connected
+
+Run without an open project:
+
+**Expected:** Error — not connected to a project.
+
+---
+
+## 7. DESCRIBE SETTINGS
+
+### 7.1 Full MDL output
+
+```
+describe settings;
+```
+
+**Expected:** Full MDL for all settings sections. Includes model properties, configurations with constants, language settings, and workflow settings.
+
+---
+
+## 8. ALTER SETTINGS MODEL
+
+### 8.1 Set AfterStartupMicroflow
+
+```
+alter settings model AfterStartupMicroflow = 'MyModule.MF_OnStart';
+```
+
+**Expected:** Property updated. Verify with `show settings`.
+
+### 8.2 Set BeforeShutdownMicroflow
+
+```
+alter settings model BeforeShutdownMicroflow = 'MyModule.MF_OnShutdown';
+```
+
+**Expected:** Property updated.
+
+### 8.3 Set HealthCheckMicroflow
+
+```
+alter settings model HealthCheckMicroflow = 'MyModule.MF_HealthCheck';
+```
+
+**Expected:** Property updated.
+
+### 8.4 Set HashAlgorithm
+
+```
+alter settings model HashAlgorithm = 'BCrypt';
+```
+
+**Expected:** Property updated.
+
+### 8.5 Set BcryptCost
+
+```
+alter settings model BcryptCost = '12';
+```
+
+**Expected:** Property updated.
+
+### 8.6 Set JavaVersion
+
+```
+alter settings model JavaVersion = 'Java21';
+```
+
+**Expected:** Property updated.
+
+### 8.7 Set RoundingMode
+
+```
+alter settings model RoundingMode = 'HalfUp';
+```
+
+**Expected:** Property updated.
+
+### 8.8 Set AllowUserMultipleSessions
+
+```
+alter settings model AllowUserMultipleSessions = 'true';
+```
+
+**Expected:** Property updated.
+
+### 8.9 Set ScheduledEventTimeZoneCode
+
+```
+alter settings model ScheduledEventTimeZoneCode = 'Europe/Amsterdam';
+```
+
+**Expected:** Property updated.
+
+### 8.10 Unknown property
+
+```
+alter settings model FakeProperty = 'value';
+```
+
+**Expected:** Error — unknown property.
+
+---
+
+## 9. ALTER SETTINGS LANGUAGE
+
+### 9.1 Set DefaultLanguageCode
+
+```
+alter settings language DefaultLanguageCode = 'en_US';
+```
+
+**Expected:** Default language updated. Verify with `show settings`.
+
+### 9.2 Invalid language code
+
+```
+alter settings language DefaultLanguageCode = 'xx_XX';
+```
+
+**Expected:** ~~Error — invalid language code.~~ Invalid language codes are accepted without validation. **Known inconsistency.**
+
+---
+
+## 10. ALTER SETTINGS WORKFLOWS
+
+### 10.1 Set UserEntity
+
+```
+alter settings workflows UserEntity = 'Administration.Account';
+```
+
+**Expected:** Workflow user entity updated.
+
+### 10.2 Set DefaultTaskParallelism
+
+```
+alter settings workflows DefaultTaskParallelism = '5';
+```
+
+**Expected:** Property updated.
+
+### 10.3 Set WorkflowEngineParallelism
+
+```
+alter settings workflows WorkflowEngineParallelism = '10';
+```
+
+**Expected:** Property updated.
+
+---
+
+## 11. ALTER SETTINGS CONFIGURATION
+
+### 11.1 Set DatabaseType
+
+```
+alter settings configuration 'default' DatabaseType = 'PostgreSQL';
+```
+
+**Expected:** Property updated. Verify with `describe settings`.
+
+### 11.2 Set DatabaseUrl
+
+```
+alter settings configuration 'default' DatabaseUrl = 'jdbc:postgresql://localhost:5432/mydb';
+```
+
+**Expected:** Property updated.
+
+### 11.3 Set DatabaseName
+
+```
+alter settings configuration 'default' DatabaseName = 'mydb';
+```
+
+**Expected:** Property updated.
+
+### 11.4 Set DatabaseUserName
+
+```
+alter settings configuration 'default' DatabaseUserName = 'admin';
+```
+
+**Expected:** Property updated.
+
+### 11.5 Set DatabasePassword
+
+```
+alter settings configuration 'default' DatabasePassword = 'secret';
+```
+
+**Expected:** Property updated.
+
+### 11.6 Set HttpPortNumber
+
+```
+alter settings configuration 'default' HttpPortNumber = '8080';
+```
+
+**Expected:** Property updated.
+
+### 11.7 Set ServerPortNumber
+
+```
+alter settings configuration 'default' ServerPortNumber = '8090';
+```
+
+**Expected:** Property updated.
+
+### 11.8 Set ApplicationRootUrl
+
+```
+alter settings configuration 'default' ApplicationRootUrl = 'http://localhost:8080/';
+```
+
+**Expected:** Property updated.
+
+### 11.9 Non-existent configuration
+
+```
+alter settings configuration 'FakeConfig' DatabaseType = 'PostgreSQL';
+```
+
+**Expected:** Error — configuration not found.
+
+### 11.10 Unknown property
+
+```
+alter settings configuration 'default' FakeProperty = 'value';
+```
+
+**Expected:** Error — unknown property.
+
+---
+
+## 12. ALTER SETTINGS CONSTANT
+
+### 12.1 Set constant value in configuration
+
+```
+alter settings constant 'MyModule.MY_CONSTANT' value 'hello' in configuration 'default';
+```
+
+**Expected:** Constant value set. Verify with `describe settings`.
+
+### 12.2 Update existing constant value
+
+```
+alter settings constant 'MyModule.MY_CONSTANT' value 'updated' in configuration 'default';
+```
+
+**Expected:** Constant value updated.
+
+### 12.3 Drop constant from configuration
+
+```
+alter settings constant 'MyModule.MY_CONSTANT' drop in configuration 'default';
+```
+
+**Expected:** Constant removed from configuration.
+
+### 12.4 Non-existent constant
+
+```
+alter settings constant 'MyModule.FAKE_CONST' value 'x' in configuration 'default';
+```
+
+**Expected:** ~~Error — constant not found.~~ Non-existent constant names are accepted without validation (creates a phantom entry in the configuration). **Known inconsistency.**
+
+### 12.5 Non-existent configuration
+
+```
+alter settings constant 'MyModule.MY_CONSTANT' value 'x' in configuration 'FakeConfig';
+```
+
+**Expected:** Error — configuration not found.
+
+---
+
+## 13. CREATE CONFIGURATION
+
+### 13.1 Create basic configuration
+
+```
+create configuration 'staging';
+```
+
+**Expected:** Configuration created. Verify with `show settings`.
+
+### 13.2 Create configuration with properties
+
+```
+create configuration 'production'
+  DatabaseType = 'PostgreSQL',
+  HttpPortNumber = '8080',
+  ApplicationRootUrl = 'https://app.example.com/';
+```
+
+**Expected:** Configuration created with specified properties.
+
+### 13.3 Duplicate configuration
+
+```
+create configuration 'default';
+```
+
+**Expected:** Error — configuration already exists.
+
+---
+
+## 14. DROP CONFIGURATION
+
+### 14.1 Drop existing configuration
+
+```
+drop configuration 'staging';
+```
+
+**Expected:** Configuration removed. Verify with `show settings`.
+
+### 14.2 Drop non-existent configuration
+
+```
+drop configuration 'FakeConfig';
+```
+
+**Expected:** Error — configuration not found.
+
+---
+
+## 15. MULTI-STEP WORKFLOWS
+
+### 15.1 Full navigation setup
+
+```
+create or replace navigation Responsive
+  home page MyModule.Dashboard
+  login page MyModule.Login
+  menu (
+    menu item 'Dashboard' page MyModule.Dashboard;
+    menu 'Admin' (
+      menu item 'Users' page Administration.AccountOverview;
+    );
+  );
+```
+
+Verify:
+
+```
+show navigation;
+show navigation menu Responsive;
+show navigation homes;
+describe navigation Responsive;
+```
+
+**Expected:** All four commands reflect the created navigation state.
+
+### 15.2 Full settings workflow
+
+```
+create configuration 'staging';
+alter settings configuration 'staging' DatabaseType = 'PostgreSQL';
+alter settings configuration 'staging' DatabaseUrl = 'jdbc:postgresql://staging:5432/app';
+alter settings configuration 'staging' HttpPortNumber = '9090';
+alter settings constant 'MyModule.API_KEY' value 'staging-key' in configuration 'staging';
+describe settings;
+```
+
+**Expected:** `describe settings` output includes `staging` configuration with all set properties and the constant value.
+
+### 15.3 Replace navigation, verify omitted clauses cleared
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home
+  login page MyModule.Login
+  menu (
+    menu item 'A' page MyModule.PageA;
+    menu item 'B' page MyModule.PageB;
+  );
+```
+
+Then replace with minimal:
+
+```
+create or replace navigation Responsive
+  home page MyModule.Home;
+```
+
+```
+describe navigation Responsive;
+```
+
+**Expected:** Login page, ~~menu,~~ and not found page ~~all~~ absent from MDL output. Menu is **NOT** cleared when omitted (see §5.3 note).
+
+---
+
+## 16. FAILURE MODES & ERROR RECOVERY
+
+### 16.1 Not connected
+
+Run any navigation or settings command without an open project.
+
+**Expected:** Error — not connected to a project.
+
+### 16.2 Profile not found
+
+```
+show navigation menu NonExistent;
+```
+
+**Expected:** ~~Error — navigation profile not found.~~ Returns empty output with exit code 0 instead of an error. **Known inconsistency** (same as §2.4).
+
+### 16.3 Unknown model property
+
+```
+alter settings model BadProp = 'value';
+```
+
+**Expected:** Error — unknown property.
+
+### 16.4 Configuration not found
+
+```
+alter settings configuration 'NoSuch' DatabaseType = 'PostgreSQL';
+```
+
+**Expected:** Error — configuration not found.
+
+### 16.5 Constant not found
+
+```
+alter settings constant 'Fake.Const' value 'x' in configuration 'default';
+```
+
+**Expected:** Error — constant not found.
+
+---
+
+## 17. ROUNDTRIP
+
+### 17.1 Navigation profile roundtrip
+
+1. `describe navigation Responsive;` — save output
+2. Modify: `create or replace navigation Responsive ...` with a different home page
+3. `describe navigation Responsive;` — verify change
+4. Execute saved MDL from step 1
+5. `describe navigation Responsive;`
+
+**Expected:** Output at step 5 matches step 1 — original home page restored.
+
+### 17.2 Configuration roundtrip
+
+1. `create configuration 'RoundtripTest' DatabaseType = 'PostgreSQL';`
+2. `describe settings configuration 'RoundtripTest';` — save output
+3. `drop configuration 'RoundtripTest';`
+4. Execute saved output from step 2
+5. `describe settings configuration 'RoundtripTest';`
+
+**Expected:** Output at step 5 matches step 2.
+
+---
+
+## 18. BOUNDARY & STRESS
+
+### 18.1 Many configurations
+
+Create 20 configurations:
+
+```
+create configuration 'Config01' DatabaseType = 'PostgreSQL';
+create configuration 'Config02' DatabaseType = 'PostgreSQL';
+...
+create configuration 'Config20' DatabaseType = 'PostgreSQL';
+```
+
+**Expected:** All 20 created. `show settings configurations` lists all.
+
+### 18.2 Many constants in one configuration
+
+Set 50 constants in a single configuration:
+
+```
+alter settings constant 'MyModule.Const01' value 'v01' in configuration 'default';
+alter settings constant 'MyModule.Const02' value 'v02' in configuration 'default';
+...
+alter settings constant 'MyModule.Const50' value 'v50' in configuration 'default';
+```
+
+**Expected:** All 50 constants set. No overflow.
+
+### 18.3 Long constant value
+
+```
+alter settings constant 'MyModule.Description' value '<10000-character string>' in configuration 'default';
+```
+
+**Expected:** Value stored and retrievable.
+
+### 18.4 Navigation with many menu items
+
+Create a navigation profile with 20+ menu items, some nested 3 levels deep.
+
+**Expected:** `show navigation menu` and `describe navigation` handle all items.
+
+### 18.5 All navigation profiles at once
+
+Verify `show navigation` lists all profile types (Responsive, Tablet_web, Phone_web, Native_phone, Native_tablet) when all exist.
+
+**Expected:** All profiles listed.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW NAVIGATION | x | x | x |
+| SHOW NAVIGATION MENU | x | x | x |
+| SHOW NAVIGATION HOMES | x | x | x |
+| DESCRIBE NAVIGATION | x | x | x |
+| CREATE OR REPLACE NAV | x | | |
+| SHOW SETTINGS | x | x | x |
+| DESCRIBE SETTINGS | x | x | x |
+| ALTER SETTINGS MODEL | x | | |
+| ALTER SETTINGS LANGUAGE | x | | |
+| ALTER SETTINGS WORKFLOWS | x | | |
+| ALTER SETTINGS CONFIG | x | | |
+| ALTER SETTINGS CONSTANT | x | | |
+| CREATE CONFIGURATION | x | | |
+| DROP CONFIGURATION | x | | |
+| Multi-step workflows | x | | |
+| Failure modes | x | | |
+| Roundtrip | x | | |
+| Boundary & stress | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW NAVIGATION | Mock tests | Kind suffix format |
+| 2. SHOW NAVIGATION MENU | Mock tests | Deep nesting |
+| 3. SHOW NAVIGATION HOMES | Mock tests | |
+| 4. DESCRIBE NAVIGATION | Mock tests | Role-based homes MDL |
+| 5. CREATE OR REPLACE NAV | Mock tests | Omitted-clause clearing, nested menus |
+| 6. SHOW SETTINGS | Mock tests | |
+| 7. DESCRIBE SETTINGS | Mock tests | |
+| 8. ALTER SETTINGS MODEL | Mock tests | All 9 properties |
+| 9. ALTER SETTINGS LANGUAGE | Mock tests | Invalid code |
+| 10. ALTER SETTINGS WORKFLOWS | Mock tests | |
+| 11. ALTER SETTINGS CONFIG | Mock tests | All 8 properties |
+| 12. ALTER SETTINGS CONSTANT | Mock tests | Drop constant |
+| 13. CREATE CONFIGURATION | Mock tests | With properties |
+| 14. DROP CONFIGURATION | Mock tests | |
+| 15. Multi-step | | All manual |
+| 16. Failure modes | Partial | |
+| 17. Roundtrip | | All manual |
+| 18. Boundary & stress | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW NAV | List profiles | | | | |
+| 1.2 | SHOW NAV | Kind column format | | | | |
+| 2.1 | NAV MENU | Menu tree | | | | |
+| 2.2 | NAV MENU | Nested items | | | | |
+| 2.3 | NAV MENU | Microflow target | | | | |
+| 2.4 | NAV MENU | Profile not found | | | | |
+| 3.1 | NAV HOMES | Per-profile homes | | | | |
+| 3.2 | NAV HOMES | No role homes | | | | |
+| 4.1 | DESC NAV | Full MDL | | | | |
+| 4.2 | DESC NAV | Microflow home | | | | |
+| 4.3 | DESC NAV | Role-based homes | | | | |
+| 4.4 | DESC NAV | Not found | | | | |
+| 5.1 | ALTER NAV | Replace home | | | | |
+| 5.2 | ALTER NAV | Replace login | | | | |
+| 5.3 | ALTER NAV | Omitted clauses clear | | | | |
+| 5.4 | ALTER NAV | Replace menu | | | | |
+| 5.5 | ALTER NAV | Nested menus | | | | |
+| 5.6 | ALTER NAV | Microflow menu | | | | |
+| 5.7 | ALTER NAV | Role-based homes | | | | |
+| 5.8 | ALTER NAV | Microflow home | | | | |
+| 6.1 | SHOW SETTINGS | All sections | | | | |
+| 6.2 | SHOW SETTINGS | Not connected | | | | |
+| 7.1 | DESC SETTINGS | Full MDL | | | | |
+| 8.1 | MODEL | AfterStartup | | | | |
+| 8.2 | MODEL | BeforeShutdown | | | | |
+| 8.3 | MODEL | HealthCheck | | | | |
+| 8.4 | MODEL | HashAlgorithm | | | | |
+| 8.5 | MODEL | BcryptCost | | | | |
+| 8.6 | MODEL | JavaVersion | | | | |
+| 8.7 | MODEL | RoundingMode | | | | |
+| 8.8 | MODEL | MultiSessions | | | | |
+| 8.9 | MODEL | TimeZone | | | | |
+| 8.10 | MODEL | Unknown property | | | | |
+| 9.1 | LANGUAGE | DefaultLanguageCode | | | | |
+| 9.2 | LANGUAGE | Invalid code | | | | |
+| 10.1 | WORKFLOWS | UserEntity | | | | |
+| 10.2 | WORKFLOWS | TaskParallelism | | | | |
+| 10.3 | WORKFLOWS | EngineParallelism | | | | |
+| 11.1 | CONFIG | DatabaseType | | | | |
+| 11.2 | CONFIG | DatabaseUrl | | | | |
+| 11.3 | CONFIG | DatabaseName | | | | |
+| 11.4 | CONFIG | DatabaseUserName | | | | |
+| 11.5 | CONFIG | DatabasePassword | | | | |
+| 11.6 | CONFIG | HttpPortNumber | | | | |
+| 11.7 | CONFIG | ServerPortNumber | | | | |
+| 11.8 | CONFIG | ApplicationRootUrl | | | | |
+| 11.9 | CONFIG | Not found | | | | |
+| 11.10 | CONFIG | Unknown property | | | | |
+| 12.1 | CONSTANT | Set value | | | | |
+| 12.2 | CONSTANT | Update value | | | | |
+| 12.3 | CONSTANT | Drop | | | | |
+| 12.4 | CONSTANT | Const not found | | | | |
+| 12.5 | CONSTANT | Config not found | | | | |
+| 13.1 | CREATE CFG | Basic | | | | |
+| 13.2 | CREATE CFG | With properties | | | | |
+| 13.3 | CREATE CFG | Duplicate | | | | |
+| 14.1 | DROP CFG | Existing | | | | |
+| 14.2 | DROP CFG | Not found | | | | |
+| 15.1 | MULTI-STEP | Navigation setup | | | | |
+| 15.2 | MULTI-STEP | Settings workflow | | | | |
+| 15.3 | MULTI-STEP | Omitted clauses | | | | |
+| 16.1 | FAILURE | Not connected | | | | |
+| 16.2 | FAILURE | Profile not found | | | | |
+| 16.3 | FAILURE | Unknown property | | | | |
+| 16.4 | FAILURE | Config not found | | | | |
+| 16.5 | FAILURE | Constant not found | | | | |
+| 17.1 | ROUNDTRIP | Navigation profile | | | | |
+| 17.2 | ROUNDTRIP | Configuration | | | | |
+| 18.1 | BOUNDARY | Many configurations | | | | |
+| 18.2 | BOUNDARY | Many constants | | | | |
+| 18.3 | BOUNDARY | Long constant value | | | | |
+| 18.4 | BOUNDARY | Many menu items | | | | |
+| 18.5 | BOUNDARY | All nav profiles | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/organization-test-cases.md b/docs/15-testing/organization-test-cases.md
new file mode 100644
index 00000000..f4e3aadf
--- /dev/null
+++ b/docs/15-testing/organization-test-cases.md
@@ -0,0 +1,934 @@
+# Organization Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Modules | Marketplace Modules |
+|-----|-----------|---------|---------------------|
+| Lato Enquiry Management | 11.4.0 | 15+ | 5+ |
+| Evora - Factory Management | 10.24.15 | 20+ | 8+ |
+| Lato Product Inventory | 11.2.0 | 12+ | 4+ |
+
+Total: 3 projects with varying module counts and marketplace dependencies.
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show modules;" > /tmp/show-mod.mdl
+  mxcli exec /tmp/show-mod.mdl -p "$mpr" 2>&1 | head -5
+done
+```
+
+Expected: Module list with columns for each app. No errors.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations (CREATE, DROP, MOVE) modify the `.mpr` file **in place**.
+
+> **WARNING:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Dropped modules and their contents cannot be recovered — there is no undo, no git history,
+> and no Studio Pro autosave for `.mpr` files.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW MODULES
+
+### 1.1 List all modules
+
+```
+show modules;
+```
+
+**Expected:** Table with columns: Module, Source, Entities, Enums, Pages, Snippets, Microflows, Nanoflows, Workflows, Constants, JavaActions, PubREST, PubOData, ConOData, BizEvents, ExtDB. Rows sorted alphabetically by module name.
+
+### 1.2 Marketplace module source display
+
+```
+show modules;
+```
+
+**Expected:** Marketplace modules display `Marketplace vX.Y` in the Source column. App modules display `App` or similar.
+
+### 1.3 Column count accuracy
+
+Pick 3 modules. Cross-check entity count, microflow count, and page count against Studio Pro.
+
+**Expected:** All counts match Studio Pro.
+
+### 1.4 Zero-count modules
+
+Find a module with no nanoflows or no workflows.
+
+**Expected:** Zero displayed, not blank or null.
+
+### 1.5 Empty project
+
+Open a project with a single empty module.
+
+```
+show modules;
+```
+
+**Expected:** One row, all counts zero except module name.
+
+### 1.6 Large project
+
+Run on Evora project (20+ modules).
+
+**Expected:** All modules listed. No truncation. Alphabetical order maintained.
+
+---
+
+## 2. DESCRIBE MODULE
+
+### 2.1 Basic describe
+
+```
+describe module MyModule;
+```
+
+**Expected:** Output is valid MDL: `create module MyModule;`. No contents listed.
+
+### 2.2 Non-existent module
+
+```
+describe module NonExistentModule;
+```
+
+**Expected:** Clear error message.
+
+### 2.3 Marketplace module
+
+```
+describe module Atlas_Core;
+```
+
+**Expected:** Valid MDL output. Source metadata preserved.
+
+---
+
+## 3. DESCRIBE MODULE WITH ALL
+
+### 3.1 Full dump — dependency order
+
+```
+describe module MyModule with all;
+```
+
+**Expected:** Full MDL dump of module contents in dependency order:
+1. Enumerations
+2. Constants
+3. Entities (with attributes and validation rules)
+4. Associations
+5. Microflows
+6. Java actions
+7. Pages
+8. Snippets
+9. Layouts
+10. Database connections
+11. Business events
+12. OData services
+13. Agents
+
+### 3.2 Roundtrip — describe and recreate
+
+1. `describe module MyModule with all;` → capture MDL
+2. `drop module MyModule;`
+3. Execute captured MDL
+4. `describe module MyModule with all;` → capture again
+5. Diff the two outputs
+
+**Expected:** Identical or cosmetic-only differences.
+
+### 3.3 Empty module
+
+```
+create module EmptyTest;
+describe module EmptyTest with all;
+```
+
+**Expected:** Output contains `create module EmptyTest;` and nothing else.
+
+### 3.4 Module with all document types
+
+Find a module with entities, enums, microflows, nanoflows, pages, constants, and java actions. Run `describe module X with all;`.
+
+**Expected:** All document types present in output. Dependency order respected — enums before entities that reference them, entities before microflows that use them.
+
+### 3.5 Cross-module references in dump
+
+Module A references entities from Module B.
+
+**Expected:** References use qualified names (`ModuleB.EntityName`). No unresolved references in output.
+
+---
+
+## 4. CREATE MODULE
+
+### 4.1 Create new module
+
+```
+create module TestOrg;
+```
+
+**Expected:** Module created. Appears in `show modules;`.
+
+### 4.2 Idempotent create
+
+```
+create module TestOrg;
+create module TestOrg;
+```
+
+**Expected:** No error on second create. Module exists once.
+
+### 4.3 Create with special characters in name
+
+```
+create module My_Module_V2;
+```
+
+**Expected:** Created successfully with underscores and digits.
+
+### 4.4 Verify in show modules
+
+```
+create module BrandNew;
+show modules;
+```
+
+**Expected:** `BrandNew` appears with all counts at zero.
+
+### 4.5 Write guard
+
+Attempt CREATE without opening a project for writing.
+
+**Expected:** Error about not being connected.
+
+---
+
+## 5. DROP MODULE
+
+### 5.1 Drop empty module
+
+```
+create module DropTest;
+drop module DropTest;
+show modules;
+```
+
+**Expected:** Module removed. Not in `show modules`.
+
+### 5.2 Cascade delete — all contents removed
+
+1. Create module with entities, microflows, pages
+2. `drop module TestModule;`
+3. `show modules;` — module gone
+4. `show entities;` — no entities from dropped module
+5. `show microflows;` — no microflows from dropped module
+
+**Expected:** All contained documents deleted.
+
+### 5.3 Module role cleanup from user roles
+
+1. Create module with module role
+2. Grant module role to a user role
+3. `drop module TestModule;`
+4. Verify user role no longer references the dropped module role
+
+**Expected:** Module roles removed from all user role assignments.
+
+### 5.4 Themesource cleanup
+
+Drop a module that has themesource files.
+
+**Expected:** Corresponding `themesource/` directory contents cleaned up.
+
+### 5.5 Drop non-existent module
+
+```
+drop module NonExistentModule;
+```
+
+**Expected:** Clear error message.
+
+### 5.6 Drop marketplace module
+
+```
+drop module Atlas_Core;
+```
+
+**Expected:** Succeeds (or warns about marketplace status). All contents removed.
+
+### 5.7 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 6. DROP FOLDER
+
+### 6.1 Drop empty folder
+
+```
+drop folder 'TestFolder' in MyModule;
+```
+
+**Expected:** Folder removed. No error.
+
+### 6.2 Drop non-empty folder
+
+```
+drop folder 'FolderWithContents' in MyModule;
+```
+
+**Expected:** Error — folder must be empty.
+
+### 6.3 Drop nested folder
+
+```
+drop folder 'Parent/Child' in MyModule;
+```
+
+**Expected:** Only the `Child` folder removed. `Parent` remains.
+
+### 6.4 Drop non-existent folder
+
+```
+drop folder 'DoesNotExist' in MyModule;
+```
+
+**Expected:** Clear error message.
+
+### 6.5 Drop folder in non-existent module
+
+```
+drop folder 'SomeFolder' in NonExistent;
+```
+
+**Expected:** Error — module not found.
+
+### 6.6 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 7. MOVE FOLDER
+
+### 7.1 Move folder to another module
+
+```
+move folder MyModule.SubFolder to TargetModule;
+```
+
+**Expected:** Folder and all contents moved. References updated.
+
+### 7.2 Move folder to specific target path
+
+```
+move folder MyModule.SubFolder to folder 'NewParent/NewChild' in TargetModule;
+```
+
+**Expected:** Folder placed at target path. Target folders auto-created if needed.
+
+### 7.3 Move folder within same module
+
+```
+move folder MyModule.FolderA to folder 'Reorganized' in MyModule;
+```
+
+**Expected:** Folder relocated within same module.
+
+### 7.4 Move non-existent folder
+
+```
+move folder MyModule.NonExistent to TargetModule;
+```
+
+**Expected:** Clear error message.
+
+### 7.5 Move to non-existent module
+
+```
+move folder MyModule.SubFolder to NonExistent;
+```
+
+**Expected:** Error — target module not found.
+
+### 7.6 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 8. MOVE (Documents)
+
+### 8.1 Move page to another module
+
+```
+move page MyModule.MyPage to TargetModule;
+```
+
+**Expected:** Page moved. Qualified name becomes `TargetModule.MyPage`.
+
+### 8.2 Move page to folder in another module
+
+```
+move page MyModule.MyPage to folder 'Pages/Imported' in TargetModule;
+```
+
+**Expected:** Page placed in target folder. Folder auto-created if needed.
+
+### 8.3 Move microflow
+
+```
+move microflow MyModule.MyFlow to TargetModule;
+```
+
+**Expected:** Microflow moved. Cross-module callers updated.
+
+### 8.4 Move nanoflow
+
+```
+move nanoflow MyModule.MyNano to TargetModule;
+```
+
+**Expected:** Nanoflow moved. References updated.
+
+### 8.5 Move entity
+
+```
+move entity MyModule.MyEntity to TargetModule;
+```
+
+**Expected:** Entity moved. Association conversion handled — cross-module associations become cross-module references.
+
+### 8.6 Move enumeration
+
+```
+move enumeration MyModule.StatusEnum to TargetModule;
+```
+
+**Expected:** Enumeration moved. All attributes using this enum updated.
+
+### 8.7 Move snippet
+
+```
+move snippet MyModule.MySnippet to TargetModule;
+```
+
+**Expected:** Snippet moved. Pages referencing the snippet updated.
+
+### 8.8 Move constant
+
+```
+move constant MyModule.MyConstant to TargetModule;
+```
+
+**Expected:** Constant moved. Microflow expressions referencing the constant updated.
+
+### 8.9 Move database connection
+
+```
+move database connection MyModule.MyDBConn to TargetModule;
+```
+
+**Expected:** Database connection moved.
+
+### 8.10 Cross-module reference updates
+
+1. Create entity in ModuleA
+2. Create microflow in ModuleB that retrieves from ModuleA.Entity
+3. Move entity to ModuleC
+4. Describe microflow in ModuleB
+
+**Expected:** Microflow reference updated to `ModuleC.Entity`.
+
+### 8.11 Role remapping on move
+
+1. Create microflow in ModuleA with granted roles from ModuleA
+2. Move microflow to ModuleB
+
+**Expected:** Module role references remapped or warning issued about cross-module role references.
+
+### 8.12 Move to non-existent module
+
+```
+move page MyModule.MyPage to NonExistent;
+```
+
+**Expected:** Error — target module not found.
+
+### 8.13 Unsupported move type
+
+Attempt to move a document type not in the supported list.
+
+**Expected:** Clear error — unsupported move type.
+
+### 8.14 Write guard
+
+**Expected:** Error if no project open for writing.
+
+---
+
+## 9. SHOW STRUCTURE
+
+### 9.1 Default depth (module level)
+
+```
+show structure;
+```
+
+**Expected:** Tree listing of all modules. Requires catalog.
+
+### 9.2 Depth 1
+
+```
+show structure depth 1;
+```
+
+**Expected:** Modules only. No folder contents.
+
+### 9.3 Depth 2
+
+```
+show structure depth 2;
+```
+
+**Expected:** Modules and their top-level folders/documents.
+
+### 9.4 Depth 3
+
+```
+show structure depth 3;
+```
+
+**Expected:** Modules, folders, and nested subfolders with documents.
+
+### 9.5 Filter by module
+
+```
+show structure in MyModule;
+```
+
+**Expected:** Structure of single module only.
+
+### 9.6 ALL flag
+
+```
+show structure all;
+```
+
+**Expected:** Full tree with all depths expanded.
+
+> **Note:** `SHOW STRUCTURE ALL IN <Module>` is **not valid syntax** — `ALL` and `IN` cannot be combined. Valid forms: `SHOW STRUCTURE ALL` (all modules, full depth) or `SHOW STRUCTURE IN <Module>` (single module).
+
+### 9.7 Empty module structure
+
+```
+create module EmptyMod;
+show structure in EmptyMod;
+```
+
+**Expected:** Module listed with no children. No error.
+
+### 9.8 Catalog required
+
+Run `show structure;` without catalog loaded.
+
+**Expected:** Error or auto-build of catalog.
+
+### 9.9 Non-existent module filter
+
+```
+show structure in NonExistent;
+```
+
+**Expected:** Returns `(no modules found)` — no error raised, just an empty result.
+
+---
+
+## 10. MULTI-STEP WORKFLOWS
+
+### 10.1 Full module lifecycle
+
+```
+create module TestLifecycle;
+create entity TestLifecycle.Customer (Name : String, Email : String);
+create microflow TestLifecycle.GetCustomers () returns List of TestLifecycle.Customer
+begin
+  $Result = retrieve TestLifecycle.Customer;
+end;
+create nanoflow TestLifecycle.ShowCustomer (Input : TestLifecycle.Customer)
+begin
+  show page TestLifecycle.CustomerDetail (Input);
+end;
+show structure in TestLifecycle;
+show modules;
+```
+
+**Expected:** Module contains entity, microflow, nanoflow. Structure shows correct hierarchy. Module counts accurate.
+
+### 10.2 Move documents then verify references
+
+1. Create ModuleA with entity and microflow referencing entity
+2. Move entity to ModuleB
+3. Describe microflow in ModuleA — verify reference updated to ModuleB.Entity
+4. Show structure in ModuleA — entity gone
+5. Show structure in ModuleB — entity present
+
+**Expected:** All references intact after move.
+
+### 10.3 Drop module after moving contents out
+
+1. Create ModuleA with entities, microflows, pages
+2. Move all documents to ModuleB
+3. Drop ModuleA
+4. Verify ModuleB contains all moved documents
+5. Show modules — ModuleA gone
+
+**Expected:** Clean drop after contents moved out.
+
+### 10.4 Create → populate → describe with all → drop → recreate from describe
+
+1. Create module with 3 entities, 2 enums, 2 microflows, 1 constant
+2. `describe module TestMod with all;` → capture MDL
+3. `drop module TestMod;`
+4. Execute captured MDL
+5. `describe module TestMod with all;` → capture again
+6. Diff outputs
+
+**Expected:** Identical or cosmetic-only differences. Full roundtrip preserved.
+
+### 10.5 Folder organization workflow
+
+1. Create module with documents in root
+2. Create folder structure via document creation with `folder` clause
+3. Move documents into folders
+4. Show structure — verify hierarchy
+5. Move folder to another module
+6. Show structure — verify new location
+
+**Expected:** Folder hierarchy maintained through all operations.
+
+### 10.6 Cross-module reorganization
+
+1. Create 3 modules: Source, TargetA, TargetB
+2. Populate Source with entities, microflows, pages
+3. Move entities to TargetA
+4. Move microflows to TargetB
+5. Describe microflows in TargetB — verify entity references point to TargetA
+6. Drop Source (now empty)
+
+**Expected:** All cross-module references correct after reorganization.
+
+---
+
+## 11. FAILURE MODES & ERROR RECOVERY
+
+### 11.1 Not connected
+
+```
+create module Test;
+```
+
+**Expected:** Error — not connected to project.
+
+### 11.2 Module not found
+
+```
+describe module NonExistent;
+drop module NonExistent;
+show structure in NonExistent;
+```
+
+**Expected:** Clear error for each command. Includes module name in message.
+
+### 11.3 Folder not empty on drop
+
+```
+drop folder 'FolderWithDocs' in MyModule;
+```
+
+**Expected:** Error — folder is not empty. Lists or hints at contents.
+
+### 11.4 Unsupported move type
+
+Attempt to move a document type not in: PAGE, MICROFLOW, SNIPPET, NANOFLOW, ENTITY, ENUMERATION, CONSTANT, DATABASE CONNECTION.
+
+**Expected:** Parser error — not a friendly runtime error. Example: `MOVE LAYOUT MyModule.MyLayout TO Target;` produces a parse error because `LAYOUT` is not a recognized MOVE target.
+
+> **Note:** The parser rejects unsupported MOVE types before execution, so the error message is a generic parse error rather than a descriptive "unsupported document type" message.
+
+### 11.5 Move to self
+
+```
+move page MyModule.MyPage to MyModule;
+```
+
+**Expected:** Succeeds silently with a misleading success message (e.g., "moved page") even though source and target module are the same. No actual change occurs.
+
+> **Note:** The command does not detect same-module moves. It reports success without warning that the document was already in the target module.
+
+### 11.6 Drop module with cross-module references
+
+1. ModuleA.Entity referenced by ModuleB.Microflow
+2. `drop module ModuleA;`
+
+**Expected:** Module dropped. Dangling references in ModuleB handled (warning or graceful error on describe).
+
+### 11.7 Batch abort on error
+
+```
+create module Good1;
+drop module NonExistent;
+create module Good2;
+```
+
+**Expected:** `Good1` created, `NonExistent` fails, `Good2` NOT created — batch aborts on first error.
+
+> Batch mode (`mxcli exec`) is fail-fast. REPL mode continues on error per-line.
+
+### 11.8 Error message quality
+
+For each error scenario, verify the message includes:
+- **What** went wrong
+- **Which** module/folder/document (qualified name)
+- **Actionable guidance** where applicable
+
+Scenarios: not-found (DESCRIBE, DROP, MOVE, SHOW STRUCTURE IN), not-connected (CREATE, DROP, MOVE), folder not empty, unsupported move type.
+
+---
+
+## 12. FOLDER CREATION (implicit)
+
+### 12.1 Auto-create via document creation
+
+```
+create microflow MyModule.TestFlow () folder 'NewFolder/Nested' begin end;
+```
+
+**Expected:** Folders `NewFolder` and `NewFolder/Nested` auto-created. Microflow placed in `NewFolder/Nested`.
+
+### 12.2 Existing folder reuse
+
+```
+create microflow MyModule.Flow1 () folder 'Shared' begin end;
+create microflow MyModule.Flow2 () folder 'Shared' begin end;
+```
+
+**Expected:** Both microflows in same `Shared` folder. No duplicate folder.
+
+### 12.3 Deep nesting
+
+```
+create microflow MyModule.DeepFlow () folder 'A/B/C/D' begin end;
+show structure in MyModule;
+```
+
+**Expected:** Four-level folder hierarchy created. Structure shows correct nesting.
+
+### 12.4 SHOW STRUCTURE IN filters marketplace/system modules
+
+```
+show structure in Atlas_Core;
+```
+
+**Expected:** `SHOW STRUCTURE IN <Module>` filters out marketplace and system modules by default. To inspect these modules, use `SHOW STRUCTURE ALL` and locate the module in the full tree.
+
+---
+
+## Test Project Coverage Matrix
+
+| Category | Enquiries | Evora Factory | Lato Inventory |
+|---|---|---|---|
+| SHOW MODULES count | Verify total | Verify total | Verify total |
+| SHOW MODULES column accuracy (sample 3) | Cross-check Studio Pro | Cross-check Studio Pro | Cross-check Studio Pro |
+| Marketplace source display | Verify `Marketplace vX.Y` | Verify `Marketplace vX.Y` | Verify `Marketplace vX.Y` |
+| DESCRIBE MODULE (sample 3) | App + marketplace | App + marketplace | App + marketplace |
+| DESCRIBE MODULE WITH ALL (sample 2) | Roundtrip test | Roundtrip test | Roundtrip test |
+| CREATE MODULE | New module | New module | New module |
+| DROP MODULE cascade | Module with contents | Module with contents | Module with contents |
+| SHOW STRUCTURE depth 1/2/3 | All depths | All depths | All depths |
+| MOVE documents (sample 3 types) | Page, microflow, entity | Page, microflow, entity | Page, microflow, entity |
+| MOVE FOLDER | Folder with contents | Folder with contents | Folder with contents |
+| DROP FOLDER | Empty + non-empty | Empty + non-empty | Empty + non-empty |
+| Multi-step workflows (§10) | Full lifecycle | Full lifecycle | Full lifecycle |
+| Failure modes (§11) | Error scenarios | Error scenarios | Error scenarios |
+
+---
+
+## Automated Test Coverage
+
+| Area | Tests | Status |
+|---|---|---|
+| SHOW MODULES | Integration + mock | Covered |
+| DESCRIBE MODULE | Integration + mock | Covered |
+| DESCRIBE MODULE WITH ALL | Integration | Covered |
+| CREATE MODULE | Integration + mock | Covered |
+| DROP MODULE | Integration + mock | Covered |
+| DROP MODULE cascade | Integration | **Partial** |
+| DROP FOLDER | Mock | Covered |
+| MOVE FOLDER | Mock | Covered |
+| MOVE PAGE | Integration + mock | Covered |
+| MOVE MICROFLOW | Integration + mock | Covered |
+| MOVE NANOFLOW | Integration + mock | Covered |
+| MOVE ENTITY | Integration + mock | Covered |
+| MOVE ENUMERATION | Mock | Covered |
+| MOVE SNIPPET | Mock | Covered |
+| MOVE CONSTANT | Mock | Covered |
+| MOVE DATABASE CONNECTION | Mock | Covered |
+| SHOW STRUCTURE | Integration | Covered |
+| SHOW STRUCTURE depth levels | None | **Gap** |
+| Cross-module reference updates | Partial | **Mostly manual** |
+| Role remapping on move | None | **Manual only** |
+| Themesource cleanup on drop | None | **Manual only** |
+| Multi-step workflows (§10) | None | **Manual only** |
+| Failure modes (§11) | Partial | **Mostly manual** |
+| Folder auto-creation (§12) | Partial | **Mostly manual** |
+
+Manual testing priority:
+1. DROP MODULE cascade — verify all contents removed, roles cleaned, themesource deleted
+2. MOVE documents — cross-module reference updates for each supported type
+3. DESCRIBE MODULE WITH ALL roundtrip — full dump and recreate
+4. Multi-step workflows (§10) — highest interaction bug risk
+5. SHOW STRUCTURE depth levels — verify tree accuracy at each depth
+
+---
+
+## Manual Test Report Template
+
+Copy and fill in after running manual tests.
+
+```markdown
+## Manual Testing
+
+**Date:** YYYY-MM-DD
+**Build:** `make build && make test && make lint-go` — PASS
+
+### Test Projects
+
+| App | Studio Pro | Modules | SHOW count | DESCRIBE sample | WITH ALL roundtrip |
+|-----|-----------|---------|------------|-----------------|-------------------|
+| Lato Enquiry Management | 11.4.0 | _n_ | ✅ _n_ | ✅ _n_/_n_ | ✅ _n_/_n_ |
+| Evora Factory Management | 10.24.15 | _n_ | ✅ _n_ | ✅ _n_/_n_ | ✅ _n_/_n_ |
+| Lato Product Inventory | 11.2.0 | _n_ | ✅ _n_ | ✅ _n_/_n_ | ✅ _n_/_n_ |
+
+### Command Coverage
+
+| Command | Tested | Notes |
+|---------|--------|-------|
+| SHOW MODULES | ✅/❌ | |
+| DESCRIBE MODULE | ✅/❌ | |
+| DESCRIBE MODULE WITH ALL | ✅/❌ | |
+| CREATE MODULE | ✅/❌ | |
+| DROP MODULE | ✅/❌ | |
+| DROP MODULE cascade | ✅/❌ | |
+| DROP FOLDER | ✅/❌ | |
+| DROP FOLDER (non-empty) | ✅/❌ | |
+| MOVE FOLDER | ✅/❌ | |
+| MOVE PAGE | ✅/❌ | |
+| MOVE MICROFLOW | ✅/❌ | |
+| MOVE NANOFLOW | ✅/❌ | |
+| MOVE ENTITY | ✅/❌ | |
+| MOVE ENUMERATION | ✅/❌ | |
+| MOVE SNIPPET | ✅/❌ | |
+| MOVE CONSTANT | ✅/❌ | |
+| MOVE DATABASE CONNECTION | ✅/❌ | |
+| SHOW STRUCTURE | ✅/❌ | |
+| SHOW STRUCTURE DEPTH 1/2/3 | ✅/❌ | |
+| SHOW STRUCTURE IN module | ✅/❌ | |
+| SHOW STRUCTURE ALL | ✅/❌ | |
+
+### SHOW MODULES Column Accuracy
+
+| Module | Column | Studio Pro | mxcli | Match |
+|--------|--------|-----------|-------|-------|
+| _name_ | Entities | _n_ | _n_ | ✅/❌ |
+| _name_ | Microflows | _n_ | _n_ | ✅/❌ |
+| _name_ | Pages | _n_ | _n_ | ✅/❌ |
+
+### DESCRIBE MODULE WITH ALL Roundtrip
+
+```
+Total: _n_ modules tested
+Passed: _n_
+Failed: _n_ (list failures below)
+```
+
+### Move Document Results
+
+| Type | Source → Target | References Updated | Roles Remapped | Result |
+|------|----------------|-------------------|----------------|--------|
+| PAGE | _M.Name → M2_ | ✅/❌ | ✅/❌/N/A | ✅/❌ |
+| MICROFLOW | _M.Name → M2_ | ✅/❌ | ✅/❌/N/A | ✅/❌ |
+| ENTITY | _M.Name → M2_ | ✅/❌ | N/A | ✅/❌ |
+
+### Multi-Step Workflows (§10)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 10.1 Full module lifecycle | ✅/❌ | |
+| 10.2 Move then verify refs | ✅/❌ | |
+| 10.3 Drop after move-out | ✅/❌ | |
+| 10.4 Describe-drop-recreate roundtrip | ✅/❌ | |
+| 10.5 Folder organization | ✅/❌ | |
+| 10.6 Cross-module reorganization | ✅/❌ | |
+
+### Failure Modes (§11)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 11.1 Not connected | ✅/❌ | |
+| 11.2 Module not found | ✅/❌ | |
+| 11.3 Folder not empty | ✅/❌ | |
+| 11.4 Unsupported move type | ✅/❌ | |
+| 11.5 Move to self | ✅/❌ | |
+| 11.6 Drop with cross-module refs | ✅/❌ | |
+| 11.7 Batch abort | ✅/❌ | |
+
+### Issues Found
+
+1. (none / describe issues here)
+```
diff --git a/docs/15-testing/page-test-cases.md b/docs/15-testing/page-test-cases.md
new file mode 100644
index 00000000..75782acb
--- /dev/null
+++ b/docs/15-testing/page-test-cases.md
@@ -0,0 +1,1106 @@
+# Page, Snippet & Layout Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Pages | Snippets | Layouts |
+|-----|-----------|-------|----------|---------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show pages;" > /tmp/show-pages.mdl
+  mxcli exec /tmp/show-pages.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N pages)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Dropped pages/snippets cannot be recovered.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW PAGES
+
+### 1.1 List all pages
+
+```
+show pages;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Excluded | Folder | Title | URL | Params`. Summary `(N pages)`.
+
+### 1.2 List pages in a module
+
+```
+show pages in Administration;
+```
+
+**Expected:** Only pages from `Administration` module.
+
+### 1.3 Empty module
+
+```
+show pages in NonExistentModule;
+```
+
+**Expected:** Empty result or `(0 pages)`.
+
+---
+
+## 2. SHOW SNIPPETS
+
+### 2.1 List all snippets
+
+```
+show snippets;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Folder | Params`. Summary `(N snippets)`.
+
+### 2.2 List snippets in a module
+
+```
+show snippets in MyModule;
+```
+
+**Expected:** Only snippets from specified module.
+
+---
+
+## 3. SHOW LAYOUTS
+
+### 3.1 List all layouts
+
+```
+show layouts;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Name | Folder | Type`. Summary `(N layouts)`.
+
+### 3.2 List layouts in a module
+
+```
+show layouts in Atlas_Core;
+```
+
+**Expected:** Only layouts from specified module.
+
+---
+
+## 4. SHOW WIDGETS
+
+### 4.1 List all widgets
+
+```
+show widgets;
+```
+
+**Expected:** Table with columns: NAME, widget type, container, module.
+
+### 4.2 Filter by widget type
+
+```
+show widgets where WidgetType = 'Forms$DataView';
+```
+
+**Expected:** Only DataView widgets listed.
+
+### 4.3 Filter with LIKE
+
+```
+show widgets where Name LIKE '%button%';
+```
+
+**Expected:** Widgets with "button" in name.
+
+### 4.4 Filter by module
+
+```
+show widgets in MyModule;
+```
+
+**Expected:** Only widgets from specified module.
+
+---
+
+## 5. DESCRIBE PAGE
+
+### 5.1 Basic page
+
+```
+describe page Administration.Account_Overview;
+```
+
+**Expected:** Full MDL V3 output:
+```
+create or modify page Administration.Account_Overview (
+  Title: 'Account Overview',
+  Layout: Atlas_Core.Atlas_Default,
+  Url: 'account-overview'
+) {
+  -- widget tree
+}
+/
+```
+
+### 5.2 Page with parameters
+
+```
+describe page <Module.PageWithParams>;
+```
+
+**Expected:** `Params: { $ParamName: Module.Entity }` in header.
+
+### 5.3 Page with variables
+
+```
+describe page <Module.PageWithVars>;
+```
+
+**Expected:** `Variables: { $varName: Boolean = 'expression' }` in header.
+
+### 5.4 Page with folder
+
+```
+describe page <Module.PageInFolder>;
+```
+
+**Expected:** `Folder: 'path/to/folder'` in header.
+
+### 5.5 Page with security roles
+
+```
+describe page <Module.SecuredPage>;
+```
+
+**Expected:** Output ends with `grant view on page Module.Name to Role1, Role2;`.
+
+### 5.6 Non-existent page
+
+```
+describe page Fake.Missing;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 6. DESCRIBE SNIPPET
+
+### 6.1 Basic snippet
+
+```
+describe snippet <Module.SnippetName>;
+```
+
+**Expected:** `create or modify snippet Module.Name (Params: {...}) { widget tree }`.
+
+### 6.2 Snippet with parameters
+
+```
+describe snippet <Module.ParamSnippet>;
+```
+
+**Expected:** Parameters listed in header.
+
+---
+
+## 7. DESCRIBE LAYOUT
+
+### 7.1 Layout description
+
+```
+describe layout Atlas_Core.Atlas_Default;
+```
+
+**Expected:** Comment-only representation. Includes note that layouts cannot be created via MDL.
+
+---
+
+## 8. CREATE PAGE
+
+### 8.1 Minimal page
+
+```
+create page MyModule.SimplePage (
+  Title: 'Simple Page',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  dynamictext dtHello (Content: 'Hello World');
+}
+```
+
+**Expected:** Page created. `show pages in MyModule` includes it.
+
+### 8.2 Page with URL
+
+```
+create page MyModule.ProductDetail (
+  Title: 'Product Detail',
+  Layout: Atlas_Core.Atlas_Default,
+  Url: 'product/{Product/Name}',
+  Params: { $Product: MyModule.Product }
+) {
+  dataview dv1 (DataSource: $Product) {
+    textbox tbName (Attribute: Name);
+    textbox tbPrice (Attribute: Price);
+  }
+}
+```
+
+**Expected:** Page created with URL and parameter.
+
+### 8.3 Page with DataView
+
+```
+create page MyModule.EntityPage (
+  Title: 'Entity Page',
+  Layout: Atlas_Core.Atlas_Default,
+  Params: { $Item: MyModule.Item }
+) {
+  dataview main (DataSource: $Item) {
+    textbox tbName (Attribute: Name);
+    textarea tbDesc (Attribute: Description);
+    datepicker dpDate (Attribute: CreatedDate);
+    combobox ddStatus (Attribute: Status);
+    checkbox cbActive (Attribute: IsActive);
+  }
+}
+```
+
+**Expected:** Page with DataView containing input widgets bound to attributes.
+
+### 8.4 Page with DataGrid
+
+```
+create page MyModule.ListPage (
+  Title: 'Items',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  datagrid grid1 (DataSource: DATABASE MyModule.Item) {
+    column colName (Attribute: Name, Caption: 'Name');
+    column colPrice (Attribute: Price, Caption: 'Price', Alignment: right);
+  }
+}
+```
+
+**Expected:** Page with DataGrid2 and columns.
+
+### 8.5 Page with LayoutGrid (rows/columns)
+
+```
+create page MyModule.GridPage (
+  Title: 'Grid Layout',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  layoutgrid lg1 {
+    row r1 {
+      column c1 (Weight: 6) {
+        dynamictext dtLeft (Content: 'Left side');
+      }
+      column c2 (Weight: 6) {
+        dynamictext dtRight (Content: 'Right side');
+      }
+    }
+  }
+}
+```
+
+**Expected:** Page with responsive grid layout.
+
+### 8.6 Page with buttons and actions
+
+```
+create page MyModule.ActionPage (
+  Title: 'Actions',
+  Layout: Atlas_Core.Atlas_Default,
+  Params: { $Item: MyModule.Item }
+) {
+  dataview dv (DataSource: $Item) {
+    actionbutton btnSave (Caption: 'Save', Action: SAVE_CHANGES CLOSE_PAGE);
+    actionbutton btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES CLOSE_PAGE);
+    actionbutton btnDelete (Caption: 'Delete', Action: DELETE_OBJECT);
+    actionbutton btnOpen (Caption: 'Open', Action: SHOW_PAGE MyModule.DetailPage);
+    actionbutton btnRun (Caption: 'Run', Action: MICROFLOW MyModule.MF_Process);
+  }
+}
+```
+
+**Expected:** Buttons with different action types.
+
+### 8.7 Page with TabContainer
+
+```
+create page MyModule.TabbedPage (
+  Title: 'Tabs',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  tabcontainer tc1 {
+    tabpage tp1 (Caption: 'General') {
+      dynamictext dtGeneral (Content: 'General content');
+    }
+    tabpage tp2 (Caption: 'Details') {
+      dynamictext dtDetails (Content: 'Detail content');
+    }
+  }
+}
+```
+
+**Expected:** Tab container with two tab pages.
+
+### 8.8 Page with SnippetCall
+
+```
+create page MyModule.WithSnippet (
+  Title: 'With Snippet',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  snippetcall sc1 (Snippet: MyModule.HeaderSnippet)
+}
+```
+
+**Expected:** Snippet call widget referencing existing snippet.
+
+### 8.9 Page with conditional visibility
+
+```
+create page MyModule.ConditionalPage (
+  Title: 'Conditional',
+  Layout: Atlas_Core.Atlas_Default,
+  Variables: { $ShowExtra: Boolean = 'false' }
+) {
+  dynamictext dtAlways (Content: 'Always visible');
+  container cntExtra (VisibleIf: '$ShowExtra') {
+    dynamictext dtConditional (Content: 'Conditionally visible');
+  }
+}
+```
+
+**Expected:** Widget with conditional visibility expression.
+
+### 8.10 Page in folder
+
+```
+create page MyModule.FolderPage (
+  Title: 'In Folder',
+  Layout: Atlas_Core.Atlas_Default,
+  Folder: 'Admin/Reports'
+) {
+  dynamictext dtContent (Content: 'Content');
+}
+```
+
+**Expected:** Page placed in specified folder.
+
+### 8.11 `create or modify` — existing page
+
+```
+create or modify page MyModule.SimplePage (
+  Title: 'Updated Title',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  dynamictext dtUpdated (Content: 'Updated content');
+}
+```
+
+**Expected:** Updates existing page (preserves ID).
+
+### 8.12 `create or replace` — drop and recreate
+
+```
+create or replace page MyModule.SimplePage (
+  Title: 'Replaced',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  dynamictext dtNew (Content: 'New content');
+}
+```
+
+**Expected:** Drops and recreates (new ID).
+
+### 8.13 Duplicate page error
+
+```
+create page MyModule.SimplePage (
+  Title: 'Dup',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  dynamictext dtX (Content: 'X');
+}
+```
+
+**Expected:** Error — page already exists.
+
+---
+
+## 9. CREATE SNIPPET
+
+### 9.1 Minimal snippet
+
+```
+create snippet MyModule.SimpleSnippet {
+  dynamictext dtContent (Content: 'Snippet content');
+}
+```
+
+**Expected:** Snippet created.
+
+### 9.2 Snippet with parameters
+
+```
+create snippet MyModule.ItemCard (
+  Params: { $Item: MyModule.Item }
+) {
+  dataview dvItem (DataSource: $Item) {
+    textbox tbName (Attribute: Name);
+    textbox tbPrice (Attribute: Price);
+  }
+}
+```
+
+**Expected:** Snippet with entity parameter and DataView.
+
+### 9.3 Snippet in folder
+
+```
+create snippet MyModule.FolderSnippet (
+  Folder: 'Shared/Components'
+) {
+  dynamictext dtInFolder (Content: 'In folder');
+}
+```
+
+**Expected:** Snippet placed in folder.
+
+---
+
+## 10. DROP PAGE / DROP SNIPPET
+
+### 10.1 Drop existing page
+
+```
+drop page MyModule.SimplePage;
+```
+
+**Expected:** Page removed.
+
+### 10.2 Drop non-existent page
+
+```
+drop page MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+### 10.3 Drop existing snippet
+
+```
+drop snippet MyModule.SimpleSnippet;
+```
+
+**Expected:** Snippet removed.
+
+### 10.4 Drop non-existent snippet
+
+```
+drop snippet MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 11. ALTER PAGE
+
+### 11.1 SET widget property
+
+```
+alter page MyModule.EntityPage {
+  SET Placeholder = 'Enter name here' ON tbName;
+};
+```
+
+**Expected:** Widget property updated. `describe` shows new value.
+
+### 11.2 SET DataSource
+
+```
+alter page MyModule.ListPage {
+  SET DataSource = MICROFLOW MyModule.MF_GetItems ON grid1;
+};
+```
+
+**Expected:** DataGrid source changed to microflow.
+
+### 11.3 INSERT widget
+
+```
+alter page MyModule.EntityPage {
+  INSERT AFTER tbDesc {
+    actionbutton btnNew (Caption: 'Submit', Action: SAVE_CHANGES);
+  }
+};
+```
+
+**Expected:** Button added after tbDesc widget in DataView.
+
+### 11.4 INSERT widget at first position
+
+```
+alter page MyModule.EntityPage {
+  INSERT BEFORE tbName {
+    dynamictext dtTitle (Content: 'Edit Item');
+  }
+};
+```
+
+**Expected:** Dynamic text widget inserted before tbName.
+
+### 11.5 DROP widget
+
+```
+alter page MyModule.EntityPage {
+  DROP WIDGET tbDesc;
+};
+```
+
+**Expected:** TextArea widget removed from page.
+
+### 11.6 DROP multiple widgets
+
+```
+alter page MyModule.EntityPage {
+  DROP WIDGET dpDate, cbActive;
+};
+```
+
+**Expected:** Both widgets removed.
+
+### 11.7 REPLACE widget
+
+```
+alter page MyModule.EntityPage {
+  REPLACE ddStatus WITH {
+    radiobuttons rbStatus (Attribute: Status);
+  }
+};
+```
+
+**Expected:** ComboBox replaced with RadioButtons.
+
+### 11.8 ADD variable
+
+```
+alter page MyModule.ConditionalPage {
+  ADD VARIABLES $EditMode: Boolean = 'false';
+};
+```
+
+**Expected:** Variable added to page.
+
+### 11.9 DROP variable
+
+```
+alter page MyModule.ConditionalPage {
+  DROP VARIABLES $ShowExtra;
+};
+```
+
+**Expected:** Variable removed.
+
+### 11.10 SET layout
+
+```
+alter page MyModule.SimplePage {
+  SET LAYOUT = Atlas_Core.Atlas_TopBar;
+};
+```
+
+**Expected:** Page layout changed.
+
+### 11.11 SET column property
+
+```
+alter page MyModule.ListPage {
+  SET Caption = 'Full Name' ON colName;
+};
+```
+
+**Expected:** DataGrid column caption updated.
+
+---
+
+## 12. ALTER SNIPPET
+
+> **BUG-014:** ALTER SNIPPET is currently broken — the engine looks up a page
+> instead of a snippet. All tests in this section will fail until the bug is fixed.
+
+### 12.1 INSERT widget into snippet
+
+```
+alter snippet MyModule.ItemCard {
+  INSERT AFTER tbPrice {
+    actionbutton btnView (Caption: 'View', Action: SHOW_PAGE MyModule.Detail);
+  }
+};
+```
+
+**Expected:** Widget added to snippet. _(blocked by BUG-014)_
+
+### 12.2 DROP widget from snippet
+
+```
+alter snippet MyModule.ItemCard {
+  DROP WIDGET btnView;
+};
+```
+
+**Expected:** Widget removed from snippet. _(blocked by BUG-014)_
+
+---
+
+## 13. WIREFRAME OUTPUT
+
+> **Note:** The `--format wireframe` option is not implemented. These test cases
+> document the intended behavior for a future feature. All tests in this section
+> will fail with an unrecognized flag or no effect.
+
+### 13.1 Page wireframe (JSON)
+
+```
+describe page MyModule.EntityPage --format wireframe;
+```
+
+**Expected:** JSON output with structure:
+```json
+{
+  "format": "wireframe",
+  "type": "page",
+  "name": "MyModule.EntityPage",
+  "title": "...",
+  "layout": "...",
+  "parameters": [...],
+  "root": [...],
+  "mdlSource": "...",
+  "sourceMap": {...}
+}
+```
+
+### 13.2 Snippet wireframe
+
+```
+describe snippet MyModule.ItemCard --format wireframe;
+```
+
+**Expected:** JSON wireframe for snippet.
+
+### 13.3 Wireframe node structure
+
+Verify wireframe nodes contain: `id`, `widget`, `name`, `label`, `binding`, `action`, `datasource`, `children`.
+
+---
+
+## 14. UPDATE WIDGETS
+
+### 14.1 Update widget property
+
+```
+update widgets set 'Caption' = 'Save Changes' where Name = 'btnSave';
+```
+
+**Expected:** All matching widgets updated.
+
+### 14.2 Dry run
+
+```
+update widgets set 'Placeholder' = 'Enter...' where WidgetType = 'Forms$TextBox' dry run;
+```
+
+**Expected:** Shows what would change without modifying anything.
+
+---
+
+## 15. ROUNDTRIP (BSON)
+
+### 15.1 Page roundtrip
+
+1. Create a page with DataView, TextBox, Button
+2. `describe page MyModule.TestPage`
+3. Drop: `drop page MyModule.TestPage`
+4. Execute described MDL
+5. `describe` again
+
+**Expected:** Output identical between step 2 and step 5.
+
+### 15.2 Snippet roundtrip
+
+Same process for a snippet with parameters and widgets.
+
+---
+
+## 16. MULTI-STEP WORKFLOWS
+
+### 16.1 Entity → page → grant access
+
+```
+create persistent entity MyModule.Task (
+  Title: string(200) not null,
+  Done: boolean default false
+);
+
+create page MyModule.TaskList (
+  Title: 'Tasks',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  datagrid dgTasks (DataSource: DATABASE MyModule.Task) {
+    column colTitle (Attribute: Title, Caption: 'Task');
+    column colDone (Attribute: Done, Caption: 'Done');
+  }
+}
+
+create module role MyModule.User;
+grant view on page MyModule.TaskList to MyModule.User;
+```
+
+**Expected:** All succeed. `describe page` shows grant.
+
+### 16.2 Create snippet → use in page
+
+```
+create snippet MyModule.TaskRow (
+  Params: { $Task: MyModule.Task }
+) {
+  dataview dvTask (DataSource: $Task) {
+    textbox tbTitle (Attribute: Title);
+  }
+}
+
+create page MyModule.TaskPage (
+  Title: 'Tasks',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  snippetcall sc1 (Snippet: MyModule.TaskRow, Params: { $Task: $Task })
+}
+```
+
+**Expected:** Page references snippet.
+
+---
+
+## 17. FAILURE MODES & ERROR RECOVERY
+
+### 17.1 Unknown widget type
+
+```
+create page MyModule.Bad (
+  Title: 'Bad',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  unknownwidget;
+}
+```
+
+**Expected:** Error — unknown widget type.
+
+### 17.2 Non-existent layout
+
+```
+create page MyModule.Bad (
+  Title: 'Bad',
+  Layout: Fake.Layout
+) {
+  dynamictext dtX (Content: 'X');
+}
+```
+
+**Expected:** Warning about non-existent layout, but page is still created.
+
+### 17.3 ALTER on non-existent widget
+
+```
+alter page MyModule.EntityPage {
+  DROP WIDGET fakeWidget;
+};
+```
+
+**Expected:** Error — widget not found.
+
+### 17.4 Invalid DataSource
+
+```
+create page MyModule.Bad (
+  Title: 'Bad',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  datagrid dgBad (DataSource: DATABASE Fake.Entity) {
+    column colX (Attribute: X);
+  }
+}
+```
+
+**Expected:** Error — entity not found.
+
+---
+
+## 18. BOUNDARY & STRESS
+
+### 18.1 Page with many widgets (50+)
+
+Create a page with 50+ widgets nested in layout grid. Verify `describe` and wireframe handle it.
+
+### 18.2 Deeply nested widgets
+
+```
+create page MyModule.DeepNest (
+  Title: 'Deep',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  container {
+    container {
+      container {
+        container {
+          dynamictext dtDeep (Content: 'Deep content');
+        }
+      }
+    }
+  }
+}
+```
+
+**Expected:** Created and described with correct nesting.
+
+### 18.3 Page with all widget types
+
+Create a page using every supported widget type. Verify roundtrip.
+
+---
+
+## 19. SECURITY CASCADES
+
+### 19.1 GRANT VIEW ON PAGE
+
+```
+grant view on page MyModule.OrderOverview to MyModule.Admin, MyModule.User;
+```
+
+**Expected:** Page allowed roles updated. `describe page MyModule.OrderOverview` includes `grant view on page` in MDL output.
+
+### 19.2 REVOKE VIEW ON PAGE
+
+```
+revoke view on page MyModule.OrderOverview from MyModule.User;
+```
+
+**Expected:** User role removed. Admin role remains.
+
+### 19.3 Drop module role cascades to page
+
+1. `grant view on page MyModule.OrderOverview to MyModule.TempRole;`
+2. `drop module role MyModule.TempRole;`
+
+**Expected:** Step 2 output mentions removal from page allowed roles. `describe page MyModule.OrderOverview` no longer shows TempRole.
+
+### 19.4 Describe page shows grant MDL
+
+```
+describe page MyModule.OrderOverview;
+```
+
+**Expected:** Output ends with `grant view on page MyModule.OrderOverview to <roles>;` when roles are assigned.
+
+### 19.5 Grant on non-existent page
+
+```
+grant view on page MyModule.FakePage to MyModule.Admin;
+```
+
+**Expected:** Error — page not found.
+
+### 19.6 Grant non-existent role
+
+```
+grant view on page MyModule.OrderOverview to MyModule.FakeRole;
+```
+
+**Expected:** Error — module role not found.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW PAGES | x | x | x |
+| SHOW SNIPPETS | x | x | x |
+| SHOW LAYOUTS | x | x | x |
+| SHOW WIDGETS | x | x | |
+| DESCRIBE PAGE | x | x | x |
+| DESCRIBE SNIPPET | x | x | |
+| DESCRIBE LAYOUT | x | | |
+| CREATE PAGE | x | | |
+| CREATE SNIPPET | x | | |
+| ALTER PAGE | x | | |
+| ALTER SNIPPET | x | | |
+| DROP PAGE/SNIPPET | x | | |
+| WIREFRAME | x | x | |
+| UPDATE WIDGETS | x | | |
+| GRANT/REVOKE VIEW | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW PAGES | Mock tests | |
+| 2. SHOW SNIPPETS | Mock tests | |
+| 3. SHOW LAYOUTS | Mock tests | |
+| 4. SHOW WIDGETS | Mock tests | LIKE filter |
+| 5. DESCRIBE PAGE | Mock tests | Complex pages |
+| 6. DESCRIBE SNIPPET | Mock tests | |
+| 7. DESCRIBE LAYOUT | Mock tests | |
+| 8. CREATE PAGE | Mock tests | Complex widgets |
+| 9. CREATE SNIPPET | Mock tests | |
+| 10. DROP | Mock tests | |
+| 11. ALTER PAGE | Mock tests | Complex ops |
+| 12. ALTER SNIPPET | Mock tests | |
+| 13. WIREFRAME | Mock tests | JSON structure |
+| 14. UPDATE WIDGETS | Mock tests | Dry run |
+| 15. Roundtrip | | All manual |
+| 16. Multi-step | | All manual |
+| 17. Failure modes | Partial | |
+| 18. Boundary | | All manual |
+| 19. Security cascades | Mock tests | Role cascade |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW PAGES | List all | | | | |
+| 1.2 | SHOW PAGES | Filter module | | | | |
+| 1.3 | SHOW PAGES | Empty module | | | | |
+| 2.1 | SHOW SNIPPETS | List all | | | | |
+| 2.2 | SHOW SNIPPETS | Filter module | | | | |
+| 3.1 | SHOW LAYOUTS | List all | | | | |
+| 3.2 | SHOW LAYOUTS | Filter module | | | | |
+| 4.1 | SHOW WIDGETS | List all | | | | |
+| 4.2 | SHOW WIDGETS | Filter type | | | | |
+| 4.3 | SHOW WIDGETS | Filter LIKE | | | | |
+| 4.4 | SHOW WIDGETS | Filter module | | | | |
+| 5.1 | DESCRIBE PAGE | Basic | | | | |
+| 5.2 | DESCRIBE PAGE | With params | | | | |
+| 5.3 | DESCRIBE PAGE | With variables | | | | |
+| 5.4 | DESCRIBE PAGE | In folder | | | | |
+| 5.5 | DESCRIBE PAGE | Security roles | | | | |
+| 5.6 | DESCRIBE PAGE | Not found | | | | |
+| 6.1 | DESCRIBE SNIPPET | Basic | | | | |
+| 6.2 | DESCRIBE SNIPPET | With params | | | | |
+| 7.1 | DESCRIBE LAYOUT | Layout | | | | |
+| 8.1 | CREATE PAGE | Minimal | | | | |
+| 8.2 | CREATE PAGE | With URL + params | | | | |
+| 8.3 | CREATE PAGE | DataView | | | | |
+| 8.4 | CREATE PAGE | DataGrid | | | | |
+| 8.5 | CREATE PAGE | LayoutGrid | | | | |
+| 8.6 | CREATE PAGE | Buttons + actions | | | | |
+| 8.7 | CREATE PAGE | TabContainer | | | | |
+| 8.8 | CREATE PAGE | SnippetCall | | | | |
+| 8.9 | CREATE PAGE | Conditional visibility | | | | |
+| 8.10 | CREATE PAGE | In folder | | | | |
+| 8.11 | CREATE PAGE | create or modify | | | | |
+| 8.12 | CREATE PAGE | create or replace | | | | |
+| 8.13 | CREATE PAGE | Duplicate error | | | | |
+| 9.1 | CREATE SNIPPET | Minimal | | | | |
+| 9.2 | CREATE SNIPPET | With params | | | | |
+| 9.3 | CREATE SNIPPET | In folder | | | | |
+| 10.1 | DROP | Page | | | | |
+| 10.2 | DROP | Page not found | | | | |
+| 10.3 | DROP | Snippet | | | | |
+| 10.4 | DROP | Snippet not found | | | | |
+| 11.1 | ALTER PAGE | SET property | | | | |
+| 11.2 | ALTER PAGE | SET DataSource | | | | |
+| 11.3 | ALTER PAGE | INSERT last | | | | |
+| 11.4 | ALTER PAGE | INSERT first | | | | |
+| 11.5 | ALTER PAGE | DROP widget | | | | |
+| 11.6 | ALTER PAGE | DROP multiple | | | | |
+| 11.7 | ALTER PAGE | REPLACE widget | | | | |
+| 11.8 | ALTER PAGE | ADD variable | | | | |
+| 11.9 | ALTER PAGE | DROP variable | | | | |
+| 11.10 | ALTER PAGE | SET layout | | | | |
+| 11.11 | ALTER PAGE | SET column prop | | | | |
+| 12.1 | ALTER SNIPPET | INSERT | | | | |
+| 12.2 | ALTER SNIPPET | DROP | | | | |
+| 13.1 | WIREFRAME | Page JSON | | | | |
+| 13.2 | WIREFRAME | Snippet JSON | | | | |
+| 13.3 | WIREFRAME | Node structure | | | | |
+| 14.1 | UPDATE | Widget property | | | | |
+| 14.2 | UPDATE | Dry run | | | | |
+| 15.1 | ROUNDTRIP | Page | | | | |
+| 15.2 | ROUNDTRIP | Snippet | | | | |
+| 16.1 | MULTI-STEP | Entity + page + grant | | | | |
+| 16.2 | MULTI-STEP | Snippet + page | | | | |
+| 17.1 | FAILURE | Unknown widget | | | | |
+| 17.2 | FAILURE | Non-existent layout | | | | |
+| 17.3 | FAILURE | ALTER bad widget | | | | |
+| 17.4 | FAILURE | Invalid DataSource | | | | |
+| 18.1 | BOUNDARY | Many widgets | | | | |
+| 18.2 | BOUNDARY | Deep nesting | | | | |
+| 18.3 | BOUNDARY | All widget types | | | | |
+| 19.1 | SECURITY | Grant view | | | | |
+| 19.2 | SECURITY | Revoke view | | | | |
+| 19.3 | SECURITY | Drop role cascade | | | | |
+| 19.4 | SECURITY | Describe shows grant | | | | |
+| 19.5 | SECURITY | Grant bad page | | | | |
+| 19.6 | SECURITY | Grant bad role | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/security-test-cases.md b/docs/15-testing/security-test-cases.md
new file mode 100644
index 00000000..72f87cc3
--- /dev/null
+++ b/docs/15-testing/security-test-cases.md
@@ -0,0 +1,900 @@
+# Security Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Module Roles | User Roles | Demo Users |
+|-----|-----------|--------------|------------|------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Security changes (role creation, grant/revoke) modify the `.mpr` in place.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW PROJECT SECURITY
+
+### 1.1 View project security settings
+
+```
+show project security;
+```
+
+**Expected:** Displays SecurityLevel, CheckSecurity, StrictMode, DemoUsersEnabled, GuestAccess, UserRoles count, DemoUsers count, AdminUser, PasswordPolicy.
+
+---
+
+## 2. SHOW MODULE ROLES
+
+### 2.1 List all module roles
+
+```
+show module roles;
+```
+
+**Expected:** Table with columns `Qualified Name | Module | Role | Description`. Summary `(N module roles)`.
+
+### 2.2 List module roles in a module
+
+```
+show module roles in Administration;
+```
+
+**Expected:** Only roles from `Administration` module.
+
+---
+
+## 3. SHOW USER ROLES
+
+### 3.1 List all user roles
+
+```
+show user roles;
+```
+
+**Expected:** Table with columns `Name | Module Roles | Manage All | Check Security`. Summary `(N user roles)`.
+
+---
+
+## 4. SHOW DEMO USERS
+
+### 4.1 List demo users
+
+```
+show demo users;
+```
+
+**Expected:** Table with columns `User Name | User Roles`.
+
+### 4.2 Demo users disabled
+
+If demo users are disabled:
+
+**Expected:** Message "Demo users are disabled" with hint `alter project security demo users on;`.
+
+---
+
+## 5. SHOW ACCESS ON ENTITY
+
+### 5.1 Entity with access rules
+
+```
+show access on Administration.Account;
+```
+
+**Expected:** Per-rule output: rule number, roles, rights (create/read/write/delete), default member access, per-member overrides, XPath constraint.
+
+### 5.2 Entity without access rules
+
+```
+show access on MyModule.NewEntity;
+```
+
+**Expected:** Empty or "No access rules" message.
+
+### 5.3 Missing entity name
+
+```
+show access on;
+```
+
+**Expected:** Error — entity name required.
+
+### 5.4 Non-existent entity
+
+```
+show access on Fake.Entity;
+```
+
+**Expected:** Error — entity not found.
+
+---
+
+## 6. SHOW ACCESS ON MICROFLOW/PAGE/NANOFLOW
+
+### 6.1 Microflow access
+
+```
+show access on microflow Administration.ChangeMyPassword;
+```
+
+**Expected:** List of allowed module roles. Or "No module roles granted execute access".
+
+### 6.2 Page access
+
+```
+show access on page Administration.Account_Overview;
+```
+
+**Expected:** List of allowed module roles.
+
+### 6.3 Nanoflow access
+
+```
+show access on nanoflow <Module.NF>;
+```
+
+**Expected:** Same pattern as microflow.
+
+### 6.4 Workflow access (unsupported)
+
+```
+show access on workflow <Module.WF>;
+```
+
+**Expected:** Error — workflows do not have document-level AllowedModuleRoles.
+
+---
+
+## 7. SHOW SECURITY MATRIX
+
+### 7.1 Full security matrix
+
+```
+show security matrix;
+```
+
+**Expected:** Sections: Entity Access (role: CRWD), Microflow Access, Page Access, Workflow Access.
+
+### 7.2 Module-specific matrix
+
+```
+show security matrix in Administration;
+```
+
+**Expected:** Only security rules for `Administration` module.
+
+---
+
+## 8. DESCRIBE MODULE ROLE
+
+### 8.1 Describe existing role
+
+```
+describe module role Administration.Administrator;
+```
+
+**Expected:** DDL-like output `create module role ...` + which user roles include it.
+
+### 8.2 Non-existent role
+
+```
+describe module role Fake.Role;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 9. DESCRIBE USER ROLE
+
+### 9.1 Describe user role
+
+```
+describe user role 'Administrator';
+```
+
+> **Note:** The role name must be quoted. Unquoted names cause a parse error.
+
+**Expected:** `create user role Administrator (ModuleRoles) [manage all roles];` + description.
+
+---
+
+## 10. DESCRIBE DEMO USER
+
+### 10.1 Describe demo user
+
+```
+describe demo user 'admin';
+```
+
+**Expected:** `create demo user 'admin' password '***' [entity X] (Roles);`
+
+---
+
+## 11. CREATE MODULE ROLE
+
+### 11.1 Basic role creation
+
+```
+create module role MyModule.Viewer;
+```
+
+**Expected:** `Created module role: MyModule.Viewer`.
+
+### 11.2 Role with description
+
+```
+create module role MyModule.Admin description 'Full administrative access';
+```
+
+**Expected:** Role created with description.
+
+### 11.3 Duplicate role
+
+```
+create module role MyModule.Viewer;
+```
+
+**Expected:** Error — already exists.
+
+### 11.4 Case-insensitive collision
+
+```
+create module role MyModule.VIEWER;
+```
+
+**Expected:** Error — collision with existing `Viewer` (case-insensitive check).
+
+---
+
+## 12. DROP MODULE ROLE
+
+### 12.1 Drop role
+
+```
+drop module role MyModule.Viewer;
+```
+
+**Expected:** `Dropped module role: MyModule.Viewer`. Cascade removes role from entity access rules, microflow/page/OData allowed roles, and user roles.
+
+### 12.2 Drop role with cascading output
+
+Create role, grant access, then drop. Verify cascade messages: `Removed X from N ...`.
+
+### 12.3 Drop non-existent role
+
+```
+drop module role MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 13. CREATE USER ROLE
+
+### 13.1 Basic user role
+
+```
+create user role PowerUser (MyModule.Admin, Administration.Administrator);
+```
+
+**Expected:** `Created user role: PowerUser`.
+
+### 13.2 User role with manage all
+
+```
+create user role SuperAdmin (System.Administrator) manage all roles;
+```
+
+**Expected:** User role created with ManageAllRoles flag.
+
+### 13.3 `create or modify` — additive merge
+
+```
+create or modify user role PowerUser (MyModule.Viewer);
+```
+
+**Expected:** `Modified user role: PowerUser` — adds `MyModule.Viewer` to existing roles.
+
+### 13.4 Duplicate (without `or modify`)
+
+```
+create user role PowerUser (MyModule.Admin);
+```
+
+**Expected:** Error — already exists.
+
+---
+
+## 14. ALTER USER ROLE
+
+### 14.1 Add module roles
+
+```
+alter user role PowerUser add module roles (MyModule.Viewer);
+```
+
+**Expected:** Role added.
+
+### 14.2 Remove module roles
+
+```
+alter user role PowerUser remove module roles (MyModule.Viewer);
+```
+
+**Expected:** Role removed.
+
+### 14.3 Non-existent user role
+
+```
+alter user role FakeRole add module roles (MyModule.Admin);
+```
+
+**Expected:** Error — user role not found.
+
+---
+
+## 15. DROP USER ROLE
+
+### 15.1 Drop user role
+
+```
+drop user role PowerUser;
+```
+
+**Expected:** `Dropped user role: PowerUser`.
+
+### 15.2 Drop non-existent
+
+```
+drop user role FakeRole;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 16. GRANT ON ENTITY
+
+### 16.1 Full CRUD access
+
+```
+grant MyModule.Admin on MyModule.Customer (create, delete, read *, write *);
+```
+
+**Expected:** Access rule created with all rights.
+
+### 16.2 Read-only access
+
+```
+grant MyModule.Viewer on MyModule.Customer (read *);
+```
+
+**Expected:** Read-only rule (no create/delete/write).
+
+### 16.3 Selective member access
+
+```
+grant MyModule.User on MyModule.Customer (read (Name, Email), write (Email));
+```
+
+**Expected:** Only specified members accessible.
+
+### 16.4 With XPath constraint
+
+```
+grant MyModule.User on MyModule.Order (read *, write *) where '[Status = ''Open'']';
+```
+
+**Expected:** Rule with XPath constraint.
+
+### 16.5 Multiple roles
+
+```
+grant MyModule.User, MyModule.Admin on MyModule.Product (read *);
+```
+
+**Expected:** Both roles granted in same rule.
+
+---
+
+## 17. REVOKE ON ENTITY
+
+### 17.1 Full revoke
+
+```
+revoke MyModule.Viewer on MyModule.Customer;
+```
+
+**Expected:** Entire access rule removed.
+
+### 17.2 Partial revoke (rights)
+
+```
+revoke MyModule.User on MyModule.Customer (write (Email));
+```
+
+**Expected:** Write access on Email downgraded; other rights preserved.
+
+> Partial revoke (removing specific member access) works correctly as of v0.7.0.
+
+### 17.3 Revoke non-existent rule
+
+```
+revoke MyModule.Viewer on MyModule.UnrulledEntity;
+```
+
+**Expected:** "No access rules found matching".
+
+---
+
+## 18. GRANT/REVOKE EXECUTE ON MICROFLOW
+
+### 18.1 Grant execute
+
+```
+grant execute on microflow MyModule.MF_Create to MyModule.User, MyModule.Admin;
+```
+
+**Expected:** `Granted execute access on ...`.
+
+### 18.2 Idempotent grant
+
+```
+grant execute on microflow MyModule.MF_Create to MyModule.User;
+```
+
+**Expected:** "All specified roles already have execute access".
+
+### 18.3 Revoke execute
+
+```
+revoke execute on microflow MyModule.MF_Create from MyModule.User;
+```
+
+**Expected:** `Revoked execute access on ...`.
+
+### 18.4 Revoke non-granted role
+
+```
+revoke execute on microflow MyModule.MF_Create from MyModule.Viewer;
+```
+
+**Expected:** "None of the specified roles had execute access".
+
+---
+
+## 19. GRANT/REVOKE VIEW ON PAGE
+
+### 19.1 Grant view
+
+```
+grant view on page MyModule.Overview to MyModule.User;
+```
+
+**Expected:** `Granted view access on ...`.
+
+### 19.2 Revoke view
+
+```
+revoke view on page MyModule.Overview from MyModule.User;
+```
+
+**Expected:** `Revoked view access on ...`.
+
+---
+
+## 20. CREATE DEMO USER
+
+### 20.1 Basic demo user
+
+```
+create demo user 'testuser' password 'Test1234!!' (RegularUser);
+```
+
+**Expected:** Demo user created.
+
+### 20.2 `create or modify` — update password and roles
+
+```
+create or modify demo user 'testuser' password 'NewPass1234!!' (RegularUser, PowerUser);
+```
+
+**Expected:** Password updated, roles merged.
+
+### 20.3 Invalid password (policy violation)
+
+```
+create demo user 'weak' password '123' (RegularUser);
+```
+
+**Expected:** Error — password policy violation.
+
+> **Note:** Expected behavior depends on the project's password policy. If MinLength=1, weak passwords will be accepted without error.
+
+### 20.4 Demo users disabled
+
+If demo users are off, attempting to create:
+
+**Expected:** ~~Error or auto-enable suggestion.~~ **Actual:** Demo user is created successfully even when demo users are disabled — no error or warning is raised. The user silently exists but has no effect until demo users are enabled.
+
+---
+
+## 21. DROP DEMO USER
+
+### 21.1 Drop existing
+
+```
+drop demo user 'testuser';
+```
+
+**Expected:** Demo user removed.
+
+---
+
+## 22. ALTER PROJECT SECURITY
+
+### 22.1 Change security level
+
+```
+alter project security level Production;
+```
+
+**Expected:** Security level updated.
+
+### 22.2 Enable demo users
+
+```
+alter project security demo users on;
+```
+
+**Expected:** Demo users enabled.
+
+### 22.3 Disable demo users
+
+```
+alter project security demo users off;
+```
+
+**Expected:** Demo users disabled.
+
+---
+
+## 23. UPDATE SECURITY
+
+### 23.1 Reconcile all modules
+
+```
+update security;
+```
+
+**Expected:** Reconciles MemberAccesses on all entity access rules (fixes CE0066).
+
+### 23.2 Reconcile specific module
+
+```
+update security in MyModule;
+```
+
+**Expected:** Only MyModule access rules reconciled.
+
+---
+
+## 24. MULTI-STEP WORKFLOWS
+
+### 24.1 Full security setup
+
+```
+create module role MyModule.Admin description 'Admin role';
+create module role MyModule.User description 'Regular user';
+create user role Administrator (MyModule.Admin) manage all roles;
+create user role RegularUser (MyModule.User);
+create demo user 'admin' password 'Admin1234!!' (Administrator);
+create demo user 'user1' password 'User1234!!' (RegularUser);
+
+create persistent entity MyModule.Task (Title: string(200) not null);
+grant MyModule.Admin on MyModule.Task (create, delete, read *, write *);
+grant MyModule.User on MyModule.Task (read *, write (Title));
+
+create microflow MyModule.MF_CreateTask ($Title: String) returns Void
+begin
+  $T = create MyModule.Task (Title = $Title);
+  commit $T;
+end;
+grant execute on microflow MyModule.MF_CreateTask to MyModule.Admin;
+```
+
+**Expected:** Complete security setup. Matrix shows correct permissions.
+
+---
+
+## 25. FAILURE MODES & ERROR RECOVERY
+
+### 25.1 Grant on non-existent entity
+
+```
+grant MyModule.Admin on MyModule.Fake (read *);
+```
+
+**Expected:** Error — entity not found.
+
+### 25.2 Grant non-existent role
+
+```
+grant MyModule.FakeRole on MyModule.Customer (read *);
+```
+
+**Expected:** ~~Error — module role not found.~~ **BUG-013:** Non-existent role is silently accepted. Creates a phantom access rule referencing a role that does not exist. No validation error is raised. This should be fixed to reject unknown roles.
+
+### 25.3 Grant execute on non-existent microflow
+
+```
+grant execute on microflow MyModule.Fake to MyModule.Admin;
+```
+
+**Expected:** Error — microflow not found.
+
+---
+
+## 26. ROUNDTRIP
+
+### 26.1 Module role roundtrip
+
+1. `create module role SecTest.Auditor description 'Can view audit logs';`
+2. `describe module role SecTest.Auditor;` — save output
+3. `drop module role SecTest.Auditor;`
+4. Execute saved output from step 2
+5. `describe module role SecTest.Auditor;`
+
+**Expected:** Output at step 5 matches step 2.
+
+### 26.2 User role roundtrip
+
+1. `create user role Reviewer (SecTest.Viewer);`
+2. `describe user role Reviewer;` — save output
+3. `drop user role Reviewer;`
+4. Execute saved output from step 2
+5. `describe user role Reviewer;`
+
+**Expected:** Output at step 5 matches step 2.
+
+### 26.3 Demo user roundtrip
+
+1. `create demo user 'rt_admin' password 'Admin12345!!' (SuperAdmin);`
+2. `describe demo user 'rt_admin';` — save output
+3. `drop demo user 'rt_admin';`
+4. Execute saved output from step 2 (adjust password to meet policy)
+5. `describe demo user 'rt_admin';`
+
+**Expected:** Output at step 5 matches step 2 (password masked as `***`).
+
+---
+
+## 27. BOUNDARY & STRESS
+
+### 27.1 Many module roles
+
+Create 50 module roles:
+
+```
+create module role SecTest.Role01;
+create module role SecTest.Role02;
+...
+create module role SecTest.Role50;
+```
+
+**Expected:** All 50 created. `show module roles in SecTest` lists 50 roles.
+
+### 27.2 Many access rules on one entity
+
+Apply 20 different role grants to a single entity:
+
+```
+grant SecTest.Role01 on SecTest.Customer (read *);
+grant SecTest.Role02 on SecTest.Customer (read (Name));
+...
+grant SecTest.Role20 on SecTest.Customer (read *, write *);
+```
+
+**Expected:** All 20 rules stored. `show access on SecTest.Customer` lists all.
+
+### 27.3 Long XPath constraint
+
+```
+grant SecTest.User on SecTest.Order (read *, write *)
+  where '[Status = ''Open'' and (Priority = ''High'' or Priority = ''Medium'') and CreatedDate > ''[%BeginOfCurrentDay%]'' and AssignedTo = ''[%CurrentUser%]'']';
+```
+
+**Expected:** XPath stored and displayed correctly in `show access`.
+
+### 27.4 Drop role with cascading across many entities
+
+Create a role, grant on 10 entities, then drop:
+
+```
+drop module role SecTest.CascadeTest;
+```
+
+**Expected:** All 10 entity access rules cleaned up. Output shows removal counts.
+
+### 27.5 User role with many module roles
+
+```
+create user role MegaUser (SecTest.Role01, SecTest.Role02, ... SecTest.Role50);
+```
+
+**Expected:** User role created with all 50 module roles assigned.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW PROJECT SECURITY | x | x | x |
+| SHOW MODULE ROLES | x | x | x |
+| SHOW USER ROLES | x | x | x |
+| SHOW DEMO USERS | x | x | |
+| SHOW ACCESS | x | x | x |
+| SHOW SECURITY MATRIX | x | x | |
+| DESCRIBE ROLES | x | x | |
+| CREATE MODULE ROLE | x | | |
+| DROP MODULE ROLE | x | | |
+| CREATE USER ROLE | x | | |
+| ALTER USER ROLE | x | | |
+| DROP USER ROLE | x | | |
+| GRANT ON ENTITY | x | | |
+| REVOKE ON ENTITY | x | | |
+| GRANT/REVOKE EXECUTE | x | | |
+| GRANT/REVOKE VIEW | x | | |
+| CREATE DEMO USER | x | | |
+| DROP DEMO USER | x | | |
+| ALTER PROJECT SECURITY | x | | |
+| UPDATE SECURITY | x | | |
+| ROUNDTRIP | x | | |
+| BOUNDARY & STRESS | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1–7. SHOW commands | Mock tests | |
+| 8–10. DESCRIBE | Mock tests | |
+| 11. CREATE MODULE ROLE | Mock tests | Case collision |
+| 12. DROP MODULE ROLE | Mock tests | Cascade verification |
+| 13. CREATE USER ROLE | Mock tests | |
+| 14. ALTER USER ROLE | Mock tests | |
+| 15. DROP USER ROLE | Mock tests | |
+| 16. GRANT ON ENTITY | Mock tests | Selective members, XPath |
+| 17. REVOKE ON ENTITY | Mock tests | Partial revoke |
+| 18. GRANT/REVOKE EXECUTE | Mock tests | Idempotent |
+| 19. GRANT/REVOKE VIEW | Mock tests | |
+| 20–21. DEMO USERS | Mock tests | Password policy |
+| 22. ALTER PROJECT | Mock tests | |
+| 23. UPDATE SECURITY | Mock tests | |
+| 24. Multi-step | | All manual |
+| 25. Failure modes | Partial | |
+| 26. Roundtrip | | All manual |
+| 27. Boundary & stress | | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | PROJECT SEC | Show settings | | | | |
+| 2.1 | MODULE ROLES | List all | | | | |
+| 2.2 | MODULE ROLES | Filter module | | | | |
+| 3.1 | USER ROLES | List all | | | | |
+| 4.1 | DEMO USERS | List | | | | |
+| 4.2 | DEMO USERS | Disabled | | | | |
+| 5.1 | ACCESS ENTITY | With rules | | | | |
+| 5.2 | ACCESS ENTITY | No rules | | | | |
+| 5.3 | ACCESS ENTITY | Missing name | | | | |
+| 5.4 | ACCESS ENTITY | Not found | | | | |
+| 6.1 | ACCESS MF | Microflow | | | | |
+| 6.2 | ACCESS PAGE | Page | | | | |
+| 6.3 | ACCESS NF | Nanoflow | | | | |
+| 6.4 | ACCESS WF | Workflow (unsupported) | | | | |
+| 7.1 | MATRIX | Full | | | | |
+| 7.2 | MATRIX | Module filter | | | | |
+| 8.1 | DESC ROLE | Module role | | | | |
+| 8.2 | DESC ROLE | Not found | | | | |
+| 9.1 | DESC USER ROLE | Describe | | | | |
+| 10.1 | DESC DEMO | Describe | | | | |
+| 11.1 | CREATE ROLE | Basic | | | | |
+| 11.2 | CREATE ROLE | With description | | | | |
+| 11.3 | CREATE ROLE | Duplicate | | | | |
+| 11.4 | CREATE ROLE | Case collision | | | | |
+| 12.1 | DROP ROLE | Basic | | | | |
+| 12.2 | DROP ROLE | Cascade | | | | |
+| 12.3 | DROP ROLE | Not found | | | | |
+| 13.1 | CREATE USER | Basic | | | | |
+| 13.2 | CREATE USER | Manage all | | | | |
+| 13.3 | CREATE USER | Or modify | | | | |
+| 13.4 | CREATE USER | Duplicate | | | | |
+| 14.1 | ALTER USER | Add roles | | | | |
+| 14.2 | ALTER USER | Remove roles | | | | |
+| 14.3 | ALTER USER | Not found | | | | |
+| 15.1 | DROP USER | Basic | | | | |
+| 15.2 | DROP USER | Not found | | | | |
+| 16.1 | GRANT ENTITY | Full CRUD | | | | |
+| 16.2 | GRANT ENTITY | Read-only | | | | |
+| 16.3 | GRANT ENTITY | Selective members | | | | |
+| 16.4 | GRANT ENTITY | XPath | | | | |
+| 16.5 | GRANT ENTITY | Multiple roles | | | | |
+| 17.1 | REVOKE ENTITY | Full revoke | | | | |
+| 17.2 | REVOKE ENTITY | Partial | | | | |
+| 17.3 | REVOKE ENTITY | No match | | | | |
+| 18.1 | GRANT EXEC | Microflow | | | | |
+| 18.2 | GRANT EXEC | Idempotent | | | | |
+| 18.3 | REVOKE EXEC | Microflow | | | | |
+| 18.4 | REVOKE EXEC | Non-granted | | | | |
+| 19.1 | GRANT VIEW | Page | | | | |
+| 19.2 | REVOKE VIEW | Page | | | | |
+| 20.1 | DEMO USER | Create | | | | |
+| 20.2 | DEMO USER | Or modify | | | | |
+| 20.3 | DEMO USER | Bad password | | | | |
+| 20.4 | DEMO USER | Disabled | | | | |
+| 21.1 | DROP DEMO | Existing | | | | |
+| 22.1 | ALTER SEC | Level | | | | |
+| 22.2 | ALTER SEC | Demo on | | | | |
+| 22.3 | ALTER SEC | Demo off | | | | |
+| 23.1 | UPDATE SEC | All | | | | |
+| 23.2 | UPDATE SEC | Module | | | | |
+| 24.1 | MULTI-STEP | Full setup | | | | |
+| 25.1 | FAILURE | Bad entity | | | | |
+| 25.2 | FAILURE | Bad role | | | | |
+| 25.3 | FAILURE | Bad microflow | | | | |
+| 26.1 | ROUNDTRIP | Module role | | | | |
+| 26.2 | ROUNDTRIP | User role | | | | |
+| 26.3 | ROUNDTRIP | Demo user | | | | |
+| 27.1 | BOUNDARY | Many module roles | | | | |
+| 27.2 | BOUNDARY | Many access rules | | | | |
+| 27.3 | BOUNDARY | Long XPath | | | | |
+| 27.4 | BOUNDARY | Cascade drop | | | | |
+| 27.5 | BOUNDARY | User role many roles | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/session-test-cases.md b/docs/15-testing/session-test-cases.md
new file mode 100644
index 00000000..d56a8331
--- /dev/null
+++ b/docs/15-testing/session-test-cases.md
@@ -0,0 +1,534 @@
+# Session Management Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Modules |
+|-----|-----------|---------|
+| Lato Enquiry Management | 11.4.0 | — |
+| Evora - Factory Management | 10.24.15 | — |
+| Lato Product Inventory | 11.2.0 | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+---
+
+## 1. CONNECT LOCAL (OPEN PROJECT)
+
+### 1.1 Connect to a valid project
+
+```
+CONNECT LOCAL 'path/to/project.mpr';
+```
+
+**Expected:** `Connected to: /path/to/project.mpr (Mendix 10.x.y)`
+
+### 1.2 Connect replaces existing connection
+
+```
+CONNECT LOCAL 'first.mpr';
+CONNECT LOCAL 'second.mpr';
+```
+
+**Expected:** First connection disconnects silently. Second connection message shows `second.mpr`.
+
+### 1.3 Connect to non-existent file
+
+```
+CONNECT LOCAL 'does/not/exist.mpr';
+```
+
+**Expected:** Error message. No active connection.
+
+### 1.4 Connect with no backend factory
+
+Start REPL without a backend factory configured.
+
+```
+CONNECT LOCAL 'project.mpr';
+```
+
+**Expected:** Error indicating no backend factory available.
+
+---
+
+## 2. DISCONNECT (CLOSE PROJECT)
+
+### 2.1 Disconnect when connected
+
+```
+CONNECT LOCAL 'project.mpr';
+DISCONNECT;
+```
+
+**Expected:** `Disconnected from: /path/to/project.mpr`
+
+### 2.2 Disconnect when not connected
+
+```
+DISCONNECT;
+```
+
+**Expected:** `Not connected`
+
+---
+
+## 3. STATUS (SHOW STATUS)
+
+### 3.1 Status when connected
+
+```
+CONNECT LOCAL 'project.mpr';
+STATUS;
+```
+
+**Expected:** Output includes: Status, Project path, Mendix Version, MPR Format, Modules list.
+
+### 3.2 Status when not connected
+
+```
+STATUS;
+```
+
+**Expected:** `Status: Not connected`
+
+---
+
+## 4. SHOW VERSION
+
+### 4.1 Show version of connected project
+
+```
+CONNECT LOCAL 'project.mpr';
+SHOW VERSION;
+```
+
+**Expected:** Output includes: Mendix Version, Build Version, MPR Format, Schema Hash.
+
+---
+
+## 5. SET
+
+### 5.1 Set output format
+
+```
+SET format = json;
+```
+
+**Expected:** `Set format = json`
+
+### 5.2 Set default module
+
+```
+SET default module = MyModule;
+```
+
+**Expected:** `Set default module = MyModule`
+
+### 5.3 Set arbitrary key
+
+```
+SET custom_key = custom_value;
+```
+
+**Expected:** `Set custom_key = custom_value`
+
+---
+
+## 6. UPDATE / REFRESH
+
+### 6.1 Update reloads project
+
+```
+CONNECT LOCAL 'project.mpr';
+UPDATE;
+STATUS;
+```
+
+**Expected:** Disconnects and reconnects to the same MPR. STATUS shows the reloaded project.
+
+### 6.2 Update when not connected
+
+```
+UPDATE;
+```
+
+**Expected:** Error indicating not connected.
+
+---
+
+## 7. EXECUTE SCRIPT
+
+### 7.1 Execute a valid script
+
+```
+EXECUTE SCRIPT 'test-session.mdl';
+```
+
+Where `test-session.mdl` contains:
+
+```
+STATUS;
+SHOW VERSION;
+```
+
+**Expected:** Strips `/` separators, parses all statements, executes sequentially. Output from both commands.
+
+### 7.2 Script with EXIT stops only the script
+
+```
+EXECUTE SCRIPT 'early-exit.mdl';
+STATUS;
+```
+
+Where `early-exit.mdl` contains:
+
+```
+STATUS;
+EXIT;
+SHOW VERSION;
+```
+
+**Expected:** Script executes STATUS, hits EXIT, stops script. SHOW VERSION in script does not run. The REPL STATUS after the script runs normally.
+
+### 7.3 Script file not found
+
+```
+EXECUTE SCRIPT 'missing.mdl';
+```
+
+**Expected:** Error indicating file not found.
+
+### 7.4 Script with parse errors
+
+```
+EXECUTE SCRIPT 'bad-syntax.mdl';
+```
+
+**Expected:** Parse error message with location details.
+
+---
+
+## 8. HELP
+
+### 8.1 General help
+
+```
+HELP;
+```
+
+**Expected:** List of available commands.
+
+### 8.2 Help on specific topic
+
+```
+HELP CONNECT;
+```
+
+**Expected:** Usage details for CONNECT.
+
+---
+
+## 9. EXIT / QUIT
+
+### 9.1 Exit from REPL
+
+```
+EXIT;
+```
+
+**Expected:** REPL terminates.
+
+### 9.2 Quit from REPL
+
+```
+QUIT;
+```
+
+**Expected:** REPL terminates (alias for EXIT).
+
+---
+
+## 10. Multi-Step Workflow
+
+### 10.1 Full session lifecycle
+
+```
+CONNECT LOCAL 'project.mpr';
+STATUS;
+SET default module = MyFirstModule;
+SHOW VERSION;
+UPDATE;
+STATUS;
+DISCONNECT;
+```
+
+**Expected:** Each command succeeds in sequence. STATUS after UPDATE reflects reloaded project. DISCONNECT confirms path.
+
+### 10.2 Operations without connection
+
+```
+STATUS;
+SHOW VERSION;
+UPDATE;
+```
+
+**Expected:** Each command returns a "not connected" error.
+
+---
+
+## 11. FAILURE MODES
+
+### 11.1 Connect to corrupt MPR
+
+```
+CONNECT LOCAL 'corrupt-file.mpr';
+```
+
+**Expected:** Backend error describing parse/open failure.
+
+### 11.2 Execute script with runtime error
+
+Create `error-script.mdl`:
+```
+STATUS;
+SHOW ENTITIES;
+```
+
+Without connecting first:
+```
+EXECUTE SCRIPT 'error-script.mdl';
+```
+
+**Expected:** First statement outputs "Not connected". Script continues to next statement (fail-fast in script mode stops on first error).
+
+### 11.3 Double disconnect
+
+```
+CONNECT LOCAL 'project.mpr';
+DISCONNECT;
+DISCONNECT;
+```
+
+**Expected:** First DISCONNECT shows path. Second shows "Not connected".
+
+### 11.4 SHOW VERSION without connection
+
+```
+SHOW VERSION;
+```
+
+**Expected:** Error — not connected.
+
+### 11.5 SET with empty value
+
+```
+SET format = ;
+```
+
+**Expected:** Parse error or stored as empty string.
+
+### 11.6 EXECUTE SCRIPT with recursive include
+
+Create `recursive.mdl` containing:
+```
+EXECUTE SCRIPT 'recursive.mdl';
+```
+
+```
+EXECUTE SCRIPT 'recursive.mdl';
+```
+
+**Expected:** Stack overflow protection or max recursion depth error.
+
+### 11.7 Large script execution
+
+Create a script with 1000+ statements:
+
+```bash
+for i in $(seq 1 1000); do echo "STATUS;" >> big-script.mdl; done
+```
+
+```
+EXECUTE SCRIPT 'big-script.mdl';
+```
+
+**Expected:** All statements execute. No memory issues.
+
+### 11.8 Connect to directory instead of file
+
+```
+CONNECT LOCAL '/tmp/';
+```
+
+**Expected:** Error — not a valid MPR file.
+
+---
+
+## 12. BOUNDARY & STRESS
+
+### 12.1 Rapid connect/disconnect cycle
+
+```
+CONNECT LOCAL 'project.mpr';
+DISCONNECT;
+CONNECT LOCAL 'project.mpr';
+DISCONNECT;
+CONNECT LOCAL 'project.mpr';
+DISCONNECT;
+```
+
+Repeat 10 times.
+
+**Expected:** Each cycle succeeds. No connection leaks.
+
+### 12.2 Many SET operations
+
+```
+SET key1 = value1;
+SET key2 = value2;
+...
+SET key100 = value100;
+```
+
+**Expected:** All 100 settings stored. No map overflow.
+
+### 12.3 Very long setting value
+
+```
+SET description = <10000-character string>;
+```
+
+**Expected:** Value stored and retrievable.
+
+---
+
+## Test Project Coverage Matrix
+
+| # | Command | Scenario | Lato 11.4 | Evora 10.24 | Lato 11.2 |
+|---|---------|----------|-----------|-------------|-----------|
+| 1.1 | CONNECT LOCAL | Valid project | x | x | x |
+| 1.2 | CONNECT LOCAL | Replace existing | x | | |
+| 1.3 | CONNECT LOCAL | File not found | x | | |
+| 1.4 | CONNECT LOCAL | No backend factory | x | | |
+| 2.1 | DISCONNECT | When connected | x | x | x |
+| 2.2 | DISCONNECT | When not connected | x | | |
+| 3.1 | STATUS | When connected | x | x | x |
+| 3.2 | STATUS | When not connected | x | | |
+| 4.1 | SHOW VERSION | Connected | x | x | x |
+| 5.1 | SET | Output format | x | | |
+| 5.2 | SET | Default module | x | | |
+| 5.3 | SET | Arbitrary key | x | | |
+| 6.1 | UPDATE | Reload project | x | x | x |
+| 6.2 | UPDATE | Not connected | x | | |
+| 7.1 | EXECUTE SCRIPT | Valid script | x | | |
+| 7.2 | EXECUTE SCRIPT | EXIT in script | x | | |
+| 7.3 | EXECUTE SCRIPT | File not found | x | | |
+| 7.4 | EXECUTE SCRIPT | Parse errors | x | | |
+| 8.1 | HELP | General | x | | |
+| 8.2 | HELP | Specific topic | x | | |
+| 9.1 | EXIT | Terminate REPL | x | | |
+| 9.2 | QUIT | Terminate REPL | x | | |
+| 10.1 | MULTI-STEP | Full lifecycle | x | x | x |
+| 10.2 | MULTI-STEP | No connection | x | | |
+| 11.1 | FAILURE | Corrupt MPR | x | | |
+| 11.2 | FAILURE | Script runtime error | x | | |
+| 11.3 | FAILURE | Double disconnect | x | | |
+| 11.4 | FAILURE | Version no connection | x | | |
+| 11.5 | FAILURE | SET empty value | x | | |
+| 11.6 | FAILURE | Recursive script | x | | |
+| 11.7 | FAILURE | Large script | x | | |
+| 11.8 | FAILURE | Directory as MPR | x | | |
+| 12.1 | BOUNDARY | Rapid connect/disconnect | x | | |
+| 12.2 | BOUNDARY | Many SET ops | x | | |
+| 12.3 | BOUNDARY | Long value | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Area | Unit Tests | Integration Tests |
+|------|-----------|-------------------|
+| CONNECT LOCAL | Mock tests | Docker integration |
+| DISCONNECT | Mock tests | — |
+| STATUS | Mock tests | — |
+| SHOW VERSION | Mock tests | — |
+| SET | Mock tests | — |
+| UPDATE | Mock tests | — |
+| EXECUTE SCRIPT | Mock tests | — |
+| HELP | None | — |
+| EXIT / QUIT | Mock tests | — |
+| Failure modes | Partial | — |
+| Boundary | — | All manual |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**mxcli version:** `mxcli --version` → _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | CONNECT | Valid project | | | | |
+| 1.2 | CONNECT | Replace existing | | | | |
+| 1.3 | CONNECT | File not found | | | | |
+| 1.4 | CONNECT | No backend factory | | | | |
+| 2.1 | DISCONNECT | When connected | | | | |
+| 2.2 | DISCONNECT | Not connected | | | | |
+| 3.1 | STATUS | Connected | | | | |
+| 3.2 | STATUS | Not connected | | | | |
+| 4.1 | VERSION | Connected | | | | |
+| 5.1 | SET | Format | | | | |
+| 5.2 | SET | Default module | | | | |
+| 5.3 | SET | Arbitrary key | | | | |
+| 6.1 | UPDATE | Reload project | | | | |
+| 6.2 | UPDATE | Not connected | | | | |
+| 7.1 | SCRIPT | Valid script | | | | |
+| 7.2 | SCRIPT | EXIT in script | | | | |
+| 7.3 | SCRIPT | File not found | | | | |
+| 7.4 | SCRIPT | Parse errors | | | | |
+| 8.1 | HELP | General | | | | |
+| 8.2 | HELP | Specific topic | | | | |
+| 9.1 | EXIT | Terminate | | | | |
+| 9.2 | QUIT | Terminate | | | | |
+| 10.1 | MULTI-STEP | Full lifecycle | | | | |
+| 10.2 | MULTI-STEP | No connection | | | | |
+| 11.1 | FAILURE | Corrupt MPR | | | | |
+| 11.2 | FAILURE | Script runtime error | | | | |
+| 11.3 | FAILURE | Double disconnect | | | | |
+| 11.4 | FAILURE | Version no connection | | | | |
+| 11.5 | FAILURE | SET empty value | | | | |
+| 11.6 | FAILURE | Recursive script | | | | |
+| 11.7 | FAILURE | Large script | | | | |
+| 11.8 | FAILURE | Directory as MPR | | | | |
+| 12.1 | BOUNDARY | Rapid connect/disconnect | | | | |
+| 12.2 | BOUNDARY | Many SET ops | | | | |
+| 12.3 | BOUNDARY | Long value | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/sql-integration-test-cases.md b/docs/15-testing/sql-integration-test-cases.md
new file mode 100644
index 00000000..76ca7a18
--- /dev/null
+++ b/docs/15-testing/sql-integration-test-cases.md
@@ -0,0 +1,1238 @@
+# SQL Integration Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Entities |
+|-----|-----------|----------|
+| Lato Enquiry Management | 11.4.0 | — |
+| Evora - Factory Management | 10.24.15 | — |
+| Lato Product Inventory | 11.2.0 | — |
+
+> **SQL tests require external databases.** Provision PostgreSQL, MSSQL, and Oracle instances with test data before running. See §Setup below.
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Provision test databases
+
+Provision three databases with identical test schemas:
+
+| Driver | Container / Service | DSN example |
+|--------|-------------------|-------------|
+| postgres | `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:16` | `postgres://postgres:test@localhost:5432/testdb` |
+| sqlserver | `docker run -d -p 1433:1433 -e ACCEPT_EULA=Y -e SA_PASSWORD=Test1234! mcr.microsoft.com/mssql/server:2022-latest` | `sqlserver://sa:Test1234!@localhost:1433?database=testdb` |
+| oracle | `docker run -d -p 1521:1521 -e ORACLE_PASSWORD=test gvenzl/oracle-free:slim` | `oracle://system:test@localhost:1521/FREEPDB1` |
+
+Seed each database:
+
+```sql
+CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(100), email VARCHAR(200), active BOOLEAN, created_at TIMESTAMP);
+CREATE TABLE orders (id SERIAL PRIMARY KEY, user_id INTEGER REFERENCES users(id), total DECIMAL(10,2), status VARCHAR(50));
+CREATE TABLE products (id SERIAL PRIMARY KEY, name VARCHAR(200), price DECIMAL(10,2), category VARCHAR(100));
+CREATE VIEW active_users AS SELECT * FROM users WHERE active = true;
+INSERT INTO users (name, email, active, created_at) SELECT 'User ' || g, 'user' || g || '@test.com', true, NOW() FROM generate_series(1, 1000) g;
+INSERT INTO orders (user_id, total, status) SELECT (g % 1000) + 1, (random() * 1000)::decimal(10,2), CASE WHEN g % 3 = 0 THEN 'shipped' WHEN g % 3 = 1 THEN 'pending' ELSE 'cancelled' END FROM generate_series(1, 10000) g;
+INSERT INTO products (name, price, category) SELECT 'Product ' || g, (random() * 100)::decimal(10,2), CASE WHEN g % 4 = 0 THEN 'A' WHEN g % 4 = 1 THEN 'B' WHEN g % 4 = 2 THEN 'C' ELSE 'D' END FROM generate_series(1, 200) g;
+```
+
+> Adapt syntax for MSSQL and Oracle where `generate_series` is unavailable.
+
+### 3. Prepare connections.yaml
+
+Create `.mxcli/connections.yaml` in the test project directory:
+
+```yaml
+# List format
+connections:
+  - alias: mydb
+    driver: postgres
+    dsn: postgres://postgres:test@localhost:5432/testdb
+  - alias: mssqldb
+    driver: sqlserver
+    dsn: sqlserver://sa:Test1234!@localhost:1433?database=testdb
+  - alias: oradb
+    driver: oracle
+    dsn: oracle://system:test@localhost:1521/FREEPDB1
+```
+
+Also test map format:
+
+```yaml
+# Map format
+connections:
+  mydb:
+    driver: postgres
+    dsn: postgres://postgres:test@localhost:5432/testdb
+```
+
+### 4. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 5. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 6. Script-based testing
+
+```bash
+mxcli exec test-sql.mdl -p <mpr>
+```
+
+Write operations (CREATE DATABASE CONNECTION, GENERATE CONNECTOR EXEC, IMPORT FROM) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Changes from GENERATE CONNECTOR EXEC and IMPORT FROM cannot be easily undone.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SQL CONNECT
+
+### 1.1 Full form — postgres
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+```
+
+**Expected:** `Connected to postgres database as 'mydb'`
+
+### 1.2 Full form — sqlserver
+
+```
+SQL CONNECT sqlserver 'sqlserver://sa:Test1234!@localhost:1433?database=testdb' AS mssqldb
+```
+
+**Expected:** `Connected to sqlserver database as 'mssqldb'`
+
+### 1.3 Full form — oracle
+
+```
+SQL CONNECT oracle 'oracle://system:test@localhost:1521/FREEPDB1' AS oradb
+```
+
+**Expected:** `Connected to oracle database as 'oradb'`
+
+### 1.4 Driver aliases — postgresql
+
+```
+SQL CONNECT postgresql 'postgres://postgres:test@localhost:5432/testdb' AS pgdb
+```
+
+**Expected:** `Connected to postgres database as 'pgdb'`
+
+### 1.5 Driver aliases — pg
+
+```
+SQL CONNECT pg 'postgres://postgres:test@localhost:5432/testdb' AS pgdb2
+```
+
+**Expected:** `Connected to postgres database as 'pgdb2'`
+
+### 1.6 Driver aliases — mssql
+
+```
+SQL CONNECT mssql 'sqlserver://sa:Test1234!@localhost:1433?database=testdb' AS msdb2
+```
+
+**Expected:** `Connected to sqlserver database as 'msdb2'`
+
+### 1.7 Driver aliases — ora
+
+```
+SQL CONNECT ora 'oracle://system:test@localhost:1521/FREEPDB1' AS oradb2
+```
+
+**Expected:** `Connected to oracle database as 'oradb2'`
+
+### 1.8 Short form — from connections.yaml
+
+```
+SQL CONNECT mydb
+```
+
+**Expected:** `Connected to postgres database as 'mydb'` (resolved from `.mxcli/connections.yaml`).
+
+### 1.9 Auto-connect resolution — env var MXCLI_SQL_<ALIAS>_DSN
+
+```bash
+export MXCLI_SQL_ENVDB_DSN='postgres://postgres:test@localhost:5432/testdb'
+```
+
+```
+SQL CONNECT envdb
+```
+
+**Expected:** `Connected to postgres database as 'envdb'`
+
+### 1.10 Auto-connect resolution — env var MXCLI_SQL_<DRIVER>_DSN
+
+```bash
+export MXCLI_SQL_POSTGRES_DSN='postgres://postgres:test@localhost:5432/testdb'
+```
+
+```
+SQL CONNECT postgres_fallback
+```
+
+**Expected:** Resolves driver from env var. Connection succeeds.
+
+### 1.11 Auto-connect resolution priority
+
+Set all four sources (explicit DSN, alias env var, driver env var, connections.yaml) for the same alias. Connect with short form. Verify explicit DSN wins.
+
+### 1.12 Unsupported driver
+
+```
+SQL CONNECT mysql 'mysql://root:pass@localhost:3306/test' AS mysqldb
+```
+
+**Expected:** Error — unsupported driver `mysql`.
+
+### 1.13 Invalid DSN
+
+```
+SQL CONNECT postgres 'not-a-valid-dsn' AS baddb
+```
+
+**Expected:** Error — connection failed. Clear message with driver and DSN hint.
+
+### 1.14 Connection timeout
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@10.255.255.1:5432/testdb' AS timeoutdb
+```
+
+**Expected:** Error — connection timed out. Does not hang indefinitely.
+
+### 1.15 Duplicate alias
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+```
+
+**Expected:** Second connect fails or replaces. Verify behavior is consistent.
+
+### 1.16 connections.yaml — list format
+
+Use list format from §Setup. `SQL CONNECT mydb` resolves.
+
+### 1.17 connections.yaml — map format
+
+Use map format from §Setup. `SQL CONNECT mydb` resolves.
+
+### 1.18 Auto-connect not found
+
+```
+SQL CONNECT nonexistent_alias
+```
+
+**Expected:** Error — no connection config found for alias.
+
+---
+
+## 2. SQL DISCONNECT
+
+### 2.1 Disconnect active connection
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+SQL DISCONNECT mydb
+```
+
+**Expected:** `Disconnected 'mydb'`
+
+### 2.2 Disconnect non-existent alias
+
+```
+SQL DISCONNECT nonexistent
+```
+
+**Expected:** Error — no active connection with alias `nonexistent`.
+
+### 2.3 Disconnect then query
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+SQL DISCONNECT mydb
+SQL mydb SELECT 1
+```
+
+**Expected:** Error or auto-reconnect (if alias in config). Document actual behavior.
+
+### 2.4 Double disconnect
+
+```
+SQL DISCONNECT mydb
+SQL DISCONNECT mydb
+```
+
+**Expected:** First succeeds, second gives error.
+
+---
+
+## 3. SQL CONNECTIONS
+
+### 3.1 List active connections
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+SQL CONNECT sqlserver 'sqlserver://sa:Test1234!@localhost:1433?database=testdb' AS mssqldb
+SQL CONNECTIONS
+```
+
+**Expected:** Table with columns `Alias`, `Driver`. Two rows: `mydb | postgres`, `mssqldb | sqlserver`.
+
+### 3.2 No active connections
+
+```
+SQL CONNECTIONS
+```
+
+**Expected:** `No active sql connections`
+
+### 3.3 After disconnect
+
+```
+SQL CONNECT postgres 'postgres://postgres:test@localhost:5432/testdb' AS mydb
+SQL DISCONNECT mydb
+SQL CONNECTIONS
+```
+
+**Expected:** `No active sql connections`
+
+---
+
+## 4. SQL QUERY
+
+### 4.1 Simple SELECT
+
+```
+SQL mydb SELECT * FROM users LIMIT 10
+```
+
+**Expected:** Formatted table with columns from `users`. Footer: `(10 rows)`
+
+### 4.2 SELECT with WHERE
+
+```
+SQL mydb SELECT name, email FROM users WHERE active = true LIMIT 5
+```
+
+**Expected:** Two-column table. `(5 rows)`
+
+### 4.3 Aggregate query
+
+```
+SQL mydb SELECT COUNT(*) AS total FROM users
+```
+
+**Expected:** Single row, single column. `(1 rows)`
+
+### 4.4 Empty result
+
+```
+SQL mydb SELECT * FROM users WHERE name = 'nonexistent_user_xyz'
+```
+
+**Expected:** Column headers shown. `(0 rows)`
+
+### 4.5 Auto-connect on query
+
+Configure `mydb` in connections.yaml but do not explicitly connect. Run:
+
+```
+SQL mydb SELECT 1 AS test
+```
+
+**Expected:** Auto-connects using config, executes query. Output includes result.
+
+### 4.6 Auto-connect failure
+
+Remove `mydb` from connections.yaml and env vars. Run:
+
+```
+SQL mydb SELECT 1
+```
+
+**Expected:** Error — cannot auto-connect, no config found for alias.
+
+### 4.7 30-second timeout
+
+```
+SQL mydb SELECT pg_sleep(60)
+```
+
+**Expected:** Error — query timed out after 30 seconds.
+
+### 4.8 Syntax error in SQL
+
+```
+SQL mydb SELEC * FORM users
+```
+
+**Expected:** Error — SQL syntax error from database. Message includes SQL error detail.
+
+### 4.9 Non-existent table
+
+```
+SQL mydb SELECT * FROM nonexistent_table
+```
+
+**Expected:** Error — relation does not exist.
+
+### 4.10 Multi-line query result formatting
+
+```
+SQL mydb SELECT id, name, email, active, created_at FROM users LIMIT 20
+```
+
+**Expected:** Columns aligned. No truncation of values. Readable table format.
+
+---
+
+## 5. SQL SHOW TABLES / VIEWS / FUNCTIONS
+
+### 5.1 SHOW TABLES
+
+```
+SQL mydb SHOW TABLES
+```
+
+**Expected:** Table listing all tables. Footer: `(N tables)` where N matches actual count.
+
+### 5.2 SHOW VIEWS
+
+```
+SQL mydb SHOW VIEWS
+```
+
+**Expected:** Table listing all views. Footer: `(N views)`. Includes `active_users` from seed data.
+
+### 5.3 SHOW FUNCTIONS
+
+```
+SQL mydb SHOW FUNCTIONS
+```
+
+**Expected:** Table listing all functions. Footer: `(N functions)`.
+
+### 5.4 SHOW TABLES — empty database
+
+Connect to a database with no user tables.
+
+**Expected:** Empty result or system tables only. `(0 tables)` or similar.
+
+### 5.5 SHOW TABLES — MSSQL
+
+```
+SQL mssqldb SHOW TABLES
+```
+
+**Expected:** Same format as postgres. Driver-specific catalog queries handled internally.
+
+### 5.6 SHOW TABLES — Oracle
+
+```
+SQL oradb SHOW TABLES
+```
+
+**Expected:** Same format as postgres. Oracle catalog queries handled internally.
+
+---
+
+## 6. SQL DESCRIBE
+
+### 6.1 Describe table
+
+```
+SQL mydb DESCRIBE users
+```
+
+**Expected:** Column metadata table (column name, type, nullable, default, etc.). Footer: `(N columns)`.
+
+### 6.2 Describe view
+
+```
+SQL mydb DESCRIBE active_users
+```
+
+**Expected:** Column metadata for view columns. Same format as table describe.
+
+### 6.3 Non-existent table
+
+```
+SQL mydb DESCRIBE nonexistent_table
+```
+
+**Expected:** Error — table/view not found.
+
+### 6.4 Table with many columns
+
+Describe a table with 20+ columns. Verify all columns listed without truncation.
+
+### 6.5 Describe across drivers
+
+Run `SQL <alias> DESCRIBE users` for postgres, mssql, and oracle. Verify consistent output format.
+
+---
+
+## 7. SQL GENERATE CONNECTOR
+
+### 7.1 Dry run — all tables
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule
+```
+
+**Expected:** Prints MDL output. Footer: `-- Generated: N tables, 0 views`
+
+### 7.2 Dry run — specific tables
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (users, orders)
+```
+
+**Expected:** MDL for `users` and `orders` only. Footer: `-- Generated: 2 tables, 0 views`
+
+### 7.3 Dry run — tables and views
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (users) VIEWS (active_users)
+```
+
+**Expected:** MDL for `users` table and `active_users` view. Footer: `-- Generated: 1 tables, 1 views`
+
+### 7.4 Dry run — views only
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule VIEWS (active_users)
+```
+
+**Expected:** MDL for view. Footer: `-- Generated: 0 tables, 1 views`
+
+### 7.5 EXEC — create entities
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (users, orders) EXEC
+```
+
+**Expected:** Executes MDL in-process. Creates entities and constants in the Mendix project. Verify with `show entities in MyModule;`.
+
+### 7.6 EXEC — verify constants created
+
+After §7.5, verify database connection constants created in the module.
+
+### 7.7 120-second timeout
+
+Generate connector for a database with 100+ tables using EXEC.
+
+**Expected:** Completes within 120 seconds or times out with clear error.
+
+### 7.8 Skipped columns — unmappable types
+
+Create a table with a column type that has no Mendix equivalent (e.g., `JSONB`, `ARRAY`, `GEOMETRY`).
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (table_with_exotic_types)
+```
+
+**Expected:** Warning listing skipped columns with unmappable types. Generated MDL omits those columns.
+
+### 7.9 Non-existent table in TABLES clause
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (nonexistent)
+```
+
+**Expected:** Error or warning — table not found.
+
+### 7.10 Empty TABLES clause
+
+```
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES ()
+```
+
+**Expected:** Error — empty table list.
+
+### 7.11 EXEC without Mendix project
+
+Run GENERATE CONNECTOR EXEC without opening a Mendix project.
+
+**Expected:** Error — not connected to a Mendix project.
+
+---
+
+## 8. IMPORT FROM
+
+### 8.1 Simple import
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name, email FROM users LIMIT 100' INTO MyModule.User MAP (id AS Id, name AS Name, email AS Email)
+```
+
+**Expected:** Batch progress output. Summary: `Imported 100 rows into MyModule.User`.
+
+### 8.2 Import with BATCH size
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users' INTO MyModule.User MAP (id AS Id, name AS Name) BATCH 500
+```
+
+**Expected:** Processes in batches of 500. Progress output shows batch numbers.
+
+### 8.3 Import with LIMIT
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users' INTO MyModule.User MAP (id AS Id, name AS Name) LIMIT 50
+```
+
+**Expected:** Imports exactly 50 rows regardless of query result size.
+
+### 8.4 Import with LINK — raw object ID
+
+```
+IMPORT FROM mydb QUERY 'SELECT o.id, o.total, o.user_id FROM orders o LIMIT 100' INTO MyModule.Order MAP (id AS Id, total AS Total) LINK (user_id AS Order_User)
+```
+
+**Expected:** Link set using raw `user_id` value as object ID. Summary includes link statistics.
+
+### 8.5 Import with LINK ON — lookup
+
+```
+IMPORT FROM mydb QUERY 'SELECT o.id, o.total, o.user_id FROM orders o LIMIT 100' INTO MyModule.Order MAP (id AS Id, total AS Total) LINK (user_id AS Order_User ON UserId)
+```
+
+**Expected:** Lookup cache built for `UserId` attribute. Links resolved via lookup. Summary includes cache hit/miss statistics.
+
+### 8.6 Auto-connect to Mendix app DB
+
+Run IMPORT FROM. Verify `_mendix` connection auto-created for the app's database.
+
+### 8.7 Requires Mendix project
+
+Run IMPORT FROM without opening a Mendix project.
+
+**Expected:** Error — not connected to a Mendix project.
+
+### 8.8 ReferenceSet not supported
+
+```
+IMPORT FROM mydb QUERY 'SELECT ...' INTO MyModule.Entity MAP (...) LINK (col AS MyReferenceSet)
+```
+
+Where `MyReferenceSet` is a ReferenceSet association.
+
+**Expected:** Error — ReferenceSet not supported in IMPORT LINK.
+
+### 8.9 Default batch size
+
+Run IMPORT without BATCH clause.
+
+**Expected:** Default batch size is 1000.
+
+### 8.10 10-minute timeout
+
+```
+IMPORT FROM mydb QUERY 'SELECT * FROM large_table' INTO MyModule.Entity MAP (...) LIMIT 500000
+```
+
+**Expected:** Completes within 10 minutes or times out with clear error and partial import summary.
+
+### 8.11 Empty query result
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users WHERE 1=0' INTO MyModule.User MAP (id AS Id, name AS Name)
+```
+
+**Expected:** `Imported 0 rows into MyModule.User`. No error.
+
+### 8.12 Column mismatch in MAP
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users LIMIT 10' INTO MyModule.User MAP (id AS Id, nonexistent_col AS Name)
+```
+
+**Expected:** Error — column `nonexistent_col` not in query result.
+
+### 8.13 BATCH and LIMIT together
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users' INTO MyModule.User MAP (id AS Id, name AS Name) BATCH 100 LIMIT 250
+```
+
+**Expected:** 3 batches (100 + 100 + 50). Total: 250 rows.
+
+---
+
+## 9. CREATE DATABASE CONNECTION
+
+### 9.1 Minimal — PostgreSQL
+
+```
+CREATE DATABASE CONNECTION MyModule.MyPostgresDB
+  TYPE PostgreSQL
+  CONNECTION STRING @MyModule.PostgresDSN
+BEGIN
+END;
+```
+
+**Expected:** Database connection created. Verify with `SHOW DATABASE CONNECTIONS`.
+
+### 9.2 With literal connection string
+
+```
+CREATE DATABASE CONNECTION MyModule.MyDB
+  TYPE PostgreSQL
+  CONNECTION STRING 'postgres://user:pass@host:5432/db'
+BEGIN
+END;
+```
+
+**Expected:** Database connection created with literal DSN.
+
+### 9.3 With USERNAME and PASSWORD
+
+```
+CREATE DATABASE CONNECTION MyModule.MyDB
+  TYPE PostgreSQL
+  CONNECTION STRING @MyModule.PostgresDSN
+  USERNAME @MyModule.DBUser
+  PASSWORD @MyModule.DBPass
+BEGIN
+END;
+```
+
+**Expected:** Database connection created with separate credentials.
+
+### 9.4 With QUERY definitions
+
+```
+CREATE DATABASE CONNECTION MyModule.MyDB
+  TYPE PostgreSQL
+  CONNECTION STRING @MyModule.PostgresDSN
+BEGIN
+  QUERY GetUsers
+    SQL 'SELECT * FROM users WHERE active = {isActive}'
+    PARAMETER isActive : Boolean DEFAULT true
+    RETURNS MyModule.User
+    MAP (
+      name AS Name,
+      email AS Email
+    );
+  QUERY GetOrdersByStatus
+    SQL 'SELECT * FROM orders WHERE status = {status} AND total > {minTotal}'
+    PARAMETER status : String
+    PARAMETER minTotal : Decimal DEFAULT 0
+    RETURNS MyModule.Order
+    MAP (
+      total AS Total,
+      status AS Status
+    );
+END;
+```
+
+**Expected:** Database connection created with two queries. Parameters resolved. DESCRIBE shows full definition.
+
+### 9.5 QUERY parameter types
+
+Test each parameter type:
+
+| Type | Example |
+|------|---------|
+| String | `PARAMETER name : String` |
+| Integer | `PARAMETER count : Integer` |
+| Long | `PARAMETER bigId : Long` |
+| Decimal | `PARAMETER amount : Decimal` |
+| Boolean | `PARAMETER active : Boolean` |
+| DateTime | `PARAMETER since : DateTime` |
+| Date | `PARAMETER day : Date` |
+
+**Expected:** All types accepted and preserved in DESCRIBE.
+
+### 9.6 QUERY with NULL modifier
+
+```
+QUERY FindUser
+  SQL 'SELECT * FROM users WHERE name = {name}'
+  PARAMETER name : String NULL
+  RETURNS MyModule.User
+  MAP (name AS Name);
+```
+
+**Expected:** NULL modifier preserved. Parameter allows null values.
+
+### 9.7 QUERY with DEFAULT
+
+```
+QUERY ListUsers
+  SQL 'SELECT * FROM users WHERE active = {isActive}'
+  PARAMETER isActive : Boolean DEFAULT true
+  RETURNS MyModule.User
+  MAP (name AS Name);
+```
+
+**Expected:** Default value preserved in DESCRIBE.
+
+### 9.8 CREATE OR MODIFY — update existing
+
+```
+CREATE DATABASE CONNECTION MyModule.MyDB TYPE PostgreSQL CONNECTION STRING @MyModule.DSN BEGIN END;
+CREATE OR MODIFY DATABASE CONNECTION MyModule.MyDB TYPE PostgreSQL CONNECTION STRING @MyModule.DSN BEGIN
+  QUERY NewQuery SQL 'SELECT 1' RETURNS MyModule.Entity MAP (id AS Id);
+END;
+```
+
+**Expected:** Connection updated. DESCRIBE shows `NewQuery`.
+
+### 9.9 Database types — MSSQL
+
+```
+CREATE DATABASE CONNECTION MyModule.MssqlDB
+  TYPE MSSQL
+  CONNECTION STRING @MyModule.MssqlDSN
+BEGIN
+END;
+```
+
+**Expected:** Type `MSSQL` accepted and preserved.
+
+### 9.10 Database types — Oracle
+
+```
+CREATE DATABASE CONNECTION MyModule.OracleDB
+  TYPE Oracle
+  CONNECTION STRING @MyModule.OracleDSN
+BEGIN
+END;
+```
+
+**Expected:** Type `Oracle` accepted and preserved.
+
+### 9.11 Write guard
+
+Attempt CREATE DATABASE CONNECTION without opening a Mendix project.
+
+**Expected:** Error — not connected to a Mendix project.
+
+---
+
+## 10. SHOW DATABASE CONNECTIONS
+
+### 10.1 List all connections
+
+```
+SHOW DATABASE CONNECTIONS;
+```
+
+**Expected:** Table with columns: `Qualified Name`, `Module`, `Name`, `Folder`, `Type`, `Queries`.
+
+### 10.2 No connections
+
+Run on a project with no database connections.
+
+**Expected:** Empty table or message.
+
+### 10.3 Multiple connections
+
+Create 3 database connections across 2 modules. Verify all listed with correct metadata.
+
+---
+
+## 11. DESCRIBE DATABASE CONNECTION
+
+### 11.1 Simple connection
+
+```
+DESCRIBE DATABASE CONNECTION MyModule.MyDB;
+```
+
+**Expected:** Reproduces full MDL definition including TYPE, CONNECTION STRING, and all QUERY blocks.
+
+### 11.2 Connection with queries
+
+Create connection with 2+ queries (see §9.4). Run DESCRIBE. Verify all queries, parameters, return types, and MAP blocks present.
+
+### 11.3 Non-existent connection
+
+```
+DESCRIBE DATABASE CONNECTION MyModule.NonExistent;
+```
+
+**Expected:** Clear error — database connection not found.
+
+### 11.4 Roundtrip
+
+1. CREATE DATABASE CONNECTION with queries
+2. DESCRIBE → capture MDL
+3. DROP DATABASE CONNECTION
+4. Execute captured MDL
+5. DESCRIBE again → compare
+
+**Expected:** Identical or cosmetic-only differences.
+
+---
+
+## 12. MULTI-STEP WORKFLOWS
+
+### 12.1 Full SQL exploration workflow
+
+1. `SQL CONNECT postgres 'postgres://...' AS mydb`
+2. `SQL mydb SHOW TABLES`
+3. `SQL mydb DESCRIBE users`
+4. `SQL mydb SELECT * FROM users LIMIT 5`
+5. `SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (users, orders) EXEC`
+6. `show entities in MyModule;` — verify entities created
+7. `IMPORT FROM mydb QUERY 'SELECT id, name, email FROM users LIMIT 100' INTO MyModule.User MAP (id AS Id, name AS Name, email AS Email)`
+
+**Expected:** Each step succeeds. Entities visible after GENERATE CONNECTOR EXEC. Import populates data.
+
+### 12.2 Multi-driver workflow
+
+1. Connect postgres, mssql, and oracle simultaneously
+2. `SQL CONNECTIONS` — verify all three listed
+3. Run SHOW TABLES on each
+4. Run DESCRIBE on same table across all three
+5. Disconnect all three
+
+**Expected:** All drivers work in parallel. Output formats consistent across drivers.
+
+### 12.3 Generate then import
+
+1. `SQL mydb GENERATE CONNECTOR INTO TestModule TABLES (users, orders) EXEC`
+2. Verify entities created
+3. `IMPORT FROM mydb QUERY 'SELECT id, name FROM users LIMIT 50' INTO TestModule.User MAP (id AS Id, name AS Name)`
+4. `IMPORT FROM mydb QUERY 'SELECT id, user_id, total FROM orders LIMIT 100' INTO TestModule.Order MAP (id AS Id, total AS Total) LINK (user_id AS Order_User ON UserId)`
+
+**Expected:** Full pipeline works end-to-end. Links resolve correctly.
+
+### 12.4 Database connection with live queries
+
+1. CREATE DATABASE CONNECTION with parameterized queries
+2. DESCRIBE — verify definition
+3. SHOW DATABASE CONNECTIONS — verify listed
+4. Use generated entities in a nanoflow/microflow
+
+**Expected:** Full lifecycle from connection definition to usage.
+
+---
+
+## 13. FAILURE MODES & ERROR RECOVERY
+
+### 13.1 Unsupported driver
+
+```
+SQL CONNECT mysql 'mysql://root:pass@localhost:3306/db' AS mysqldb
+```
+
+**Expected:** Error — unsupported driver. Lists supported drivers.
+
+### 13.2 Connection timeout
+
+```
+SQL CONNECT postgres 'postgres://user:pass@10.255.255.1:5432/db' AS deadhost
+```
+
+**Expected:** Error — connection timed out. Does not block REPL.
+
+### 13.3 Auto-connect failure — no config
+
+```
+SQL unknown_alias SELECT 1
+```
+
+**Expected:** Error — no connection config found for `unknown_alias`.
+
+### 13.4 Invalid DSN format
+
+```
+SQL CONNECT postgres 'not://valid' AS baddsn
+```
+
+**Expected:** Error — invalid DSN.
+
+### 13.5 Feature gate — SQL without feature flag
+
+If SQL features require a feature gate/flag, test without it enabled.
+
+**Expected:** Clear error indicating the feature is not available.
+
+### 13.6 ReferenceSet in IMPORT LINK
+
+Attempt to LINK to a ReferenceSet association.
+
+**Expected:** Error — ReferenceSet not supported.
+
+### 13.7 Empty child table warning
+
+Run IMPORT FROM where the LINK target table has zero matching rows.
+
+**Expected:** Warning about empty lookup results. Import completes with zero links.
+
+### 13.8 Query after disconnect
+
+```
+SQL CONNECT postgres '...' AS mydb
+SQL DISCONNECT mydb
+SQL mydb SELECT 1
+```
+
+**Expected:** Error or auto-reconnect. Consistent behavior.
+
+### 13.9 GENERATE CONNECTOR — non-existent module target
+
+```
+SQL mydb GENERATE CONNECTOR INTO NonExistent.Sub.Module EXEC
+```
+
+**Expected:** Module auto-created or clear error.
+
+### 13.10 IMPORT FROM — entity not found
+
+```
+IMPORT FROM mydb QUERY 'SELECT 1 AS id' INTO NonExistent.Entity MAP (id AS Id)
+```
+
+**Expected:** Error — entity not found.
+
+---
+
+## 14. BOUNDARY & STRESS
+
+### 14.1 Large table — 100+ columns
+
+Create a test table with 100+ columns. Run:
+
+```
+SQL mydb DESCRIBE wide_table
+SQL mydb GENERATE CONNECTOR INTO MyModule TABLES (wide_table)
+```
+
+**Expected:** All columns listed in DESCRIBE. Generated MDL includes all mappable columns.
+
+### 14.2 IMPORT with 100K+ rows
+
+```
+IMPORT FROM mydb QUERY 'SELECT id, name FROM users' INTO MyModule.User MAP (id AS Id, name AS Name)
+```
+
+With 100K+ rows in users table.
+
+**Expected:** Completes within 10-minute timeout. Batch progress visible. Memory stable.
+
+### 14.3 Concurrent connections — 5+ databases
+
+Connect to 5 databases simultaneously. Run queries on each. Verify isolation — queries on one connection do not affect others.
+
+### 14.4 GENERATE CONNECTOR with 50+ tables
+
+```
+SQL mydb GENERATE CONNECTOR INTO BigModule
+```
+
+On a database with 50+ tables.
+
+**Expected:** All tables processed. MDL output complete. EXEC completes within 120 seconds.
+
+### 14.5 Large query result — 10K+ rows
+
+```
+SQL mydb SELECT * FROM orders
+```
+
+With 10K+ rows.
+
+**Expected:** All rows returned. No truncation. Performance reasonable.
+
+### 14.6 IMPORT with complex MAP and LINK
+
+```
+IMPORT FROM mydb QUERY 'SELECT o.id, o.total, o.status, o.user_id, u.name AS user_name FROM orders o JOIN users u ON o.user_id = u.id' INTO MyModule.Order MAP (id AS Id, total AS Total, status AS Status) LINK (user_id AS Order_User ON UserId) BATCH 200 LIMIT 5000
+```
+
+**Expected:** Join query works. MAP and LINK coexist. Batch + limit respected.
+
+### 14.7 Rapid connect/disconnect cycle
+
+```
+-- repeat 10 times:
+SQL CONNECT postgres '...' AS tempdb
+SQL DISCONNECT tempdb
+```
+
+**Expected:** No resource leak. `SQL CONNECTIONS` shows zero after all disconnects.
+
+### 14.8 Special characters in DSN
+
+```
+SQL CONNECT postgres 'postgres://user:p%40ss%23word@localhost:5432/test%20db' AS specialdb
+```
+
+**Expected:** URL-encoded characters handled correctly.
+
+---
+
+## Test Project Coverage Matrix
+
+| Category | Enquiries | Evora Factory | Lato Inventory |
+|---|---|---|---|
+| SQL CONNECT (3 drivers) | All 3 | All 3 | All 3 |
+| SQL SHOW TABLES/VIEWS | All 3 drivers | All 3 drivers | All 3 drivers |
+| SQL DESCRIBE | 5+ tables | 5+ tables | 5+ tables |
+| SQL QUERY (sample 10) | Various queries | Various queries | Various queries |
+| GENERATE CONNECTOR dry run | 2+ tables | 2+ tables | 2+ tables |
+| GENERATE CONNECTOR EXEC | 2 tables + verify | 2 tables + verify | 2 tables + verify |
+| IMPORT FROM | 3 imports with LINK | 3 imports with LINK | 3 imports with LINK |
+| CREATE DATABASE CONNECTION | 2 connections | 2 connections | 2 connections |
+| DESCRIBE DATABASE CONNECTION | Roundtrip | Roundtrip | Roundtrip |
+| Multi-step workflows (§12) | Full pipeline | Full pipeline | Full pipeline |
+| Failure modes (§13) | Per driver | Per driver | Per driver |
+| Boundary/Stress (§14) | Select cases | Select cases | Select cases |
+
+---
+
+## Automated Test Coverage
+
+| Area | Tests | Status |
+|---|---|---|
+| SQL CONNECT — all drivers | — | **Manual only** |
+| SQL CONNECT — auto-connect resolution | — | **Manual only** |
+| SQL DISCONNECT | — | **Manual only** |
+| SQL CONNECTIONS | — | **Manual only** |
+| SQL QUERY — basic | — | **Manual only** |
+| SQL QUERY — timeout | — | **Manual only** |
+| SQL SHOW TABLES/VIEWS/FUNCTIONS | — | **Manual only** |
+| SQL DESCRIBE | — | **Manual only** |
+| SQL GENERATE CONNECTOR — dry run | — | **Manual only** |
+| SQL GENERATE CONNECTOR — EXEC | — | **Manual only** |
+| IMPORT FROM — basic | — | **Manual only** |
+| IMPORT FROM — LINK/LINK ON | — | **Manual only** |
+| IMPORT FROM — BATCH/LIMIT | — | **Manual only** |
+| CREATE DATABASE CONNECTION | — | **Manual only** |
+| CREATE OR MODIFY DATABASE CONNECTION | — | **Manual only** |
+| SHOW DATABASE CONNECTIONS | — | **Manual only** |
+| DESCRIBE DATABASE CONNECTION | — | **Manual only** |
+| Roundtrip (DATABASE CONNECTION) | — | **Manual only** |
+| Multi-step workflows (§12) | — | **Manual only** |
+| Failure modes (§13) | — | **Manual only** |
+| Boundary/Stress (§14) | — | **Manual only** |
+
+Manual testing priority:
+1. SQL CONNECT across all 3 drivers — validates driver layer
+2. GENERATE CONNECTOR EXEC → verify entities — validates MDL generation pipeline
+3. IMPORT FROM with LINK ON — validates lookup cache and data pipeline
+4. Multi-step workflow §12.1 — highest integration risk
+5. Failure modes §13.1–§13.10 — error handling quality
+
+---
+
+## Manual Test Report Template
+
+Copy and fill in after running manual tests.
+
+```markdown
+## Manual Testing — SQL Integration
+
+**Date:** YYYY-MM-DD
+**Build:** `make build && make test && make lint-go` — PASS
+
+### Database Setup
+
+| Driver | Version | Container | Seeded |
+|--------|---------|-----------|--------|
+| PostgreSQL | 16 | docker | ✅/❌ |
+| MSSQL | 2022 | docker | ✅/❌ |
+| Oracle | 23 Free | docker | ✅/❌ |
+
+### Test Projects
+
+| App | Studio Pro | GENERATE CONNECTOR EXEC | IMPORT FROM |
+|-----|-----------|------------------------|-------------|
+| Lato Enquiry Management | 11.4.0 | ✅/❌ | ✅/❌ |
+| Evora Factory Management | 10.24.15 | ✅/❌ | ✅/❌ |
+| Lato Product Inventory | 11.2.0 | ✅/❌ | ✅/❌ |
+
+### Command Coverage
+
+| Command | postgres | sqlserver | oracle | Notes |
+|---------|----------|-----------|--------|-------|
+| SQL CONNECT (full form) | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL CONNECT (short form) | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL DISCONNECT | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL CONNECTIONS | ✅/❌ | — | — | |
+| SQL QUERY | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL SHOW TABLES | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL SHOW VIEWS | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL SHOW FUNCTIONS | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL DESCRIBE | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL GENERATE CONNECTOR | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SQL GENERATE CONNECTOR EXEC | ✅/❌ | ✅/❌ | ✅/❌ | |
+| IMPORT FROM | ✅/❌ | ✅/❌ | ✅/❌ | |
+| IMPORT FROM with LINK | ✅/❌ | ✅/❌ | ✅/❌ | |
+| IMPORT FROM with LINK ON | ✅/❌ | ✅/❌ | ✅/❌ | |
+| CREATE DATABASE CONNECTION | ✅/❌ | ✅/❌ | ✅/❌ | |
+| SHOW DATABASE CONNECTIONS | ✅/❌ | — | — | |
+| DESCRIBE DATABASE CONNECTION | ✅/❌ | — | — | |
+
+### Multi-Step Workflows (§12)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 12.1 Full SQL exploration | ✅/❌ | |
+| 12.2 Multi-driver | ✅/❌ | |
+| 12.3 Generate then import | ✅/❌ | |
+| 12.4 Database connection lifecycle | ✅/❌ | |
+
+### Failure Modes (§13)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 13.1 Unsupported driver | ✅/❌ | |
+| 13.2 Connection timeout | ✅/❌ | |
+| 13.3 Auto-connect failure | ✅/❌ | |
+| 13.4 Invalid DSN | ✅/❌ | |
+| 13.5 Feature gate | ✅/❌ | |
+| 13.6 ReferenceSet in LINK | ✅/❌ | |
+| 13.7 Empty child table | ✅/❌ | |
+| 13.8 Query after disconnect | ✅/❌ | |
+| 13.9 Non-existent module target | ✅/❌ | |
+| 13.10 Entity not found | ✅/❌ | |
+
+### Boundary & Stress (§14)
+
+| Scenario | Result | Notes |
+|----------|--------|-------|
+| 14.1 100+ columns | ✅/❌ | |
+| 14.2 100K+ row import | ✅/❌ | |
+| 14.3 5+ concurrent connections | ✅/❌ | |
+| 14.4 50+ table GENERATE | ✅/❌ | |
+| 14.5 10K+ row query | ✅/❌ | |
+| 14.7 Rapid connect/disconnect x10 | ✅/❌ | |
+
+### Issues Found
+
+1. (none / describe issues here)
+```
diff --git a/docs/15-testing/tooling-test-cases.md b/docs/15-testing/tooling-test-cases.md
new file mode 100644
index 00000000..65dd38c7
--- /dev/null
+++ b/docs/15-testing/tooling-test-cases.md
@@ -0,0 +1,1135 @@
+# Tooling Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Modules | Entities | Microflows |
+|-----|-----------|---------|----------|------------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show entities;" > /tmp/smoke.mdl
+  mxcli exec /tmp/smoke.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N entities)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+Write operations modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory.
+> Dropped documents cannot be recovered — there is no undo.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. RENAME
+
+### 1.1 Rename entity — dry run
+
+```
+RENAME ENTITY MyModule.OldEntity TO NewEntity DRY RUN;
+```
+
+**Expected:** Output starts with `Would rename`. Includes reference count. No changes written to `.mpr`.
+
+### 1.2 Rename entity — live
+
+```
+RENAME ENTITY MyModule.OldEntity TO NewEntity;
+```
+
+**Expected:** Output: `Renamed MyModule.OldEntity to MyModule.NewEntity`. Second line: `Updated N reference(s)`.
+
+### 1.3 Rename microflow
+
+```
+RENAME MICROFLOW MyModule.ACT_OldName TO ACT_NewName;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`. Verify with `show microflows in MyModule`.
+
+### 1.4 Rename nanoflow
+
+```
+RENAME NANOFLOW MyModule.NAF_OldName TO NAF_NewName;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`.
+
+### 1.5 Rename page
+
+```
+RENAME PAGE MyModule.OldPage TO NewPage;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`.
+
+### 1.6 Rename enumeration
+
+```
+RENAME ENUMERATION MyModule.OldEnum TO NewEnum;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`. Attributes using this enumeration updated.
+
+### 1.7 Rename association
+
+```
+RENAME ASSOCIATION MyModule.Old_Assoc TO New_Assoc;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`.
+
+### 1.8 Rename constant
+
+```
+RENAME CONSTANT MyModule.OLD_CONST TO NEW_CONST;
+```
+
+**Expected:** `Renamed` + `Updated N reference(s)`.
+
+### 1.9 Rename module
+
+```
+RENAME MODULE OldModule TO NewModule;
+```
+
+**Expected:** `Renamed` + reference count. All qualified names with `OldModule.` prefix updated to `NewModule.`.
+
+### 1.10 Rename module — prefix scan
+
+```
+RENAME MODULE Administration TO Admin DRY RUN;
+```
+
+**Expected:** `Would rename`. Reference count includes all documents, entities, microflows, pages, etc. that use `Administration.` prefix.
+
+### 1.11 Rename non-existent entity
+
+```
+RENAME ENTITY MyModule.DoesNotExist TO Something;
+```
+
+**Expected:** Error — entity not found.
+
+### 1.12 Rename unsupported type
+
+```
+RENAME SNIPPET MyModule.Old TO New;
+```
+
+**Expected:** Error — unsupported type for rename.
+
+### 1.13 Dry run produces no side effects
+
+1. Run `describe entity MyModule.Target`
+2. Run `RENAME ENTITY MyModule.Target TO Temp DRY RUN`
+3. Run `describe entity MyModule.Target`
+
+**Expected:** Output from step 1 and step 3 identical. Entity name unchanged.
+
+---
+
+## 2. DIFF (MDL Script)
+
+### 2.1 Basic diff — unified format
+
+Create a script `changes.mdl` that adds an entity:
+
+```
+CREATE PERSISTENT ENTITY MyModule.NewThing (
+  Name: string(200)
+);
+```
+
+```
+DIFF 'changes.mdl';
+```
+
+**Expected:** Unified diff output. Summary line: `1 new, 0 modified, 0 unchanged`.
+
+### 2.2 Diff — side format
+
+```
+SET format = side;
+DIFF 'changes.mdl';
+```
+
+**Expected:** Side-by-side diff output. Same summary counts.
+
+### 2.3 Diff — struct format
+
+```
+SET format = struct;
+DIFF 'changes.mdl';
+```
+
+**Expected:** Structural diff output showing entity tree. Same summary counts.
+
+### 2.4 Diff with modifications
+
+Create a script that modifies an existing entity (via `CREATE OR MODIFY`):
+
+```
+CREATE OR MODIFY PERSISTENT ENTITY MyModule.Existing (
+  Name: string(200),
+  NewAttr: integer
+);
+```
+
+```
+DIFF 'modify.mdl';
+```
+
+**Expected:** Shows `NewAttr` as added. Summary: `0 new, 1 modified, 0 unchanged`.
+
+### 2.5 Diff — CREATE ENTITY
+
+```
+DIFF 'create-entity.mdl';
+```
+
+**Expected:** New entity shown in diff output.
+
+### 2.6 Diff — VIEW ENTITY
+
+Diff a script containing a `CREATE VIEW ENTITY` statement.
+
+**Expected:** View entity and OQL source shown in diff.
+
+### 2.7 Diff — ENUMERATION
+
+Diff a script containing a `CREATE ENUMERATION` statement.
+
+**Expected:** Enumeration values shown in diff.
+
+### 2.8 Diff — ASSOCIATION
+
+Diff a script containing a `CREATE ASSOCIATION` statement.
+
+**Expected:** Association details shown in diff.
+
+### 2.9 Diff — MICROFLOW
+
+Diff a script containing microflow changes.
+
+**Expected:** Microflow actions shown in diff.
+
+### 2.10 Diff — NANOFLOW
+
+Diff a script containing nanoflow changes.
+
+**Expected:** Nanoflow actions shown in diff.
+
+### 2.11 Diff — mixed script
+
+Create a script with multiple CREATE and MODIFY statements across types.
+
+```
+DIFF 'mixed.mdl';
+```
+
+**Expected:** Summary: `N new, N modified, N unchanged`. Each change listed by type.
+
+### 2.12 Diff — non-existent script
+
+```
+DIFF 'missing.mdl';
+```
+
+**Expected:** Error — file not found.
+
+### 2.13 Diff — empty script
+
+```
+DIFF 'empty.mdl';
+```
+
+**Expected:** Summary: `0 new, 0 modified, 0 unchanged`.
+
+---
+
+## 3. DIFF LOCAL (Git-based)
+
+### 3.1 Diff local — HEAD
+
+```
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Shows changes in working tree vs last commit. Compares `.mxunit` files via git diff. Same format options as DIFF.
+
+### 3.2 Diff local — branch range
+
+```
+DIFF LOCAL 'main..feature';
+```
+
+**Expected:** Shows all model changes between `main` and `feature` branches.
+
+### 3.3 Diff local — unified format (default)
+
+```
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Unified diff output with `+`/`-` lines for changed model elements.
+
+### 3.4 Diff local — side format
+
+```
+SET format = side;
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Side-by-side format.
+
+### 3.5 Diff local — struct format
+
+```
+SET format = struct;
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Structural diff of model tree.
+
+### 3.6 Diff local — MPR v1 rejection
+
+Open a project with MPR v1 (pre-Mendix 10.18).
+
+```
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Error — DIFF LOCAL requires MPR v2 (Mendix 10.18+).
+
+### 3.7 Diff local — no changes
+
+```
+DIFF LOCAL 'HEAD';
+```
+
+Run on a clean working tree with no uncommitted changes.
+
+**Expected:** Summary: `0 new, 0 modified, 0 unchanged`.
+
+### 3.8 Diff local — invalid ref
+
+```
+DIFF LOCAL 'nonexistent-branch';
+```
+
+**Expected:** Error — git ref not found.
+
+---
+
+## 4. LINT
+
+### 4.1 Lint all modules
+
+```
+LINT;
+```
+
+**Expected:** Table of findings with columns: `Rule | Severity | Document | Message`. Summary: `N finding(s)`.
+
+### 4.2 Lint single module
+
+```
+LINT MyModule;
+```
+
+**Expected:** Only findings from `MyModule`.
+
+### 4.3 Lint — JSON format
+
+```
+LINT FORMAT json;
+```
+
+**Expected:** JSON array of finding objects with fields: `rule`, `severity`, `document`, `message`, `location`.
+
+### 4.4 Lint — SARIF format
+
+```
+LINT FORMAT sarif;
+```
+
+**Expected:** Valid SARIF v2.1.0 JSON. Contains `runs[0].results` with finding entries.
+
+### 4.5 Show lint rules
+
+```
+SHOW LINT RULES;
+```
+
+**Expected:** Table listing all built-in and custom rules with columns: `Rule | Severity | Description | Source`.
+
+### 4.6 Built-in rule — NamingConvention
+
+Create an entity or microflow with non-standard naming.
+
+**Expected:** `LINT` reports `NamingConvention` violation.
+
+### 4.7 Built-in rule — EmptyMicroflow
+
+Create a microflow with only start and end nodes.
+
+**Expected:** `LINT` reports `EmptyMicroflow` finding.
+
+### 4.8 Built-in rule — DomainModelSize
+
+Use a module with many entities.
+
+**Expected:** If threshold exceeded, `LINT` reports `DomainModelSize` warning.
+
+### 4.9 Built-in rule — ValidationFeedback
+
+Create an entity attribute with `not null` but no validation message.
+
+**Expected:** `LINT` reports `ValidationFeedback` finding.
+
+### 4.10 Built-in rule — ImageSource
+
+Use an image widget referencing a missing or oversized image.
+
+**Expected:** `LINT` reports `ImageSource` finding.
+
+### 4.11 Built-in rule — MissingTranslations
+
+Use a project with multiple languages and missing translation strings.
+
+**Expected:** `LINT` reports `MissingTranslations` finding.
+
+### 4.12 Custom Starlark rule
+
+Place a `.star` rule file in `.claude/lint-rules/`. Run `LINT`.
+
+**Expected:** Custom rule appears in `SHOW LINT RULES`. Findings from custom rule included in output.
+
+### 4.13 Config — excludeModules
+
+Create `.mdllint.yaml` with:
+
+```yaml
+excludeModules:
+  - Administration
+  - System
+```
+
+Run `LINT`.
+
+**Expected:** No findings from `Administration` or `System` modules.
+
+### 4.14 Lint — clean project
+
+Run on a project with no violations.
+
+**Expected:** `0 finding(s)`.
+
+---
+
+## 5. ELK DOMAIN MODEL
+
+> **Note:** ELK output is available via CLI only: `mxcli describe -p app.mpr --format elk entity Module.Entity`.
+> There is no REPL-level `ELK DOMAIN MODEL` command.
+
+### 5.1 Full module domain model (focused on entity)
+
+```bash
+mxcli describe -p app.mpr --format elk entity MyModule.Customer
+```
+
+**Expected:** JSON output with top-level keys: `entities`, `associations`, `generalizations`, `sourceMap`. Contains `MyModule.Customer` and its directly connected entities. Each entity has `id`, `name`, `category`, `attributes`.
+
+### 5.2 Entity categories
+
+Verify `category` field across entity types:
+
+| Category | Condition |
+|----------|-----------|
+| `persistent` | Normal persistent entity |
+| `nonpersistent` | Non-persistent entity |
+| `external` | External/OData entity |
+| `view` | View entity |
+
+### 5.3 System overview (module-level)
+
+```bash
+mxcli describe -p app.mpr --format elk systemoverview MyModule
+```
+
+**Expected:** JSON with `modules` array, each containing `id`, `name`, `entityCount`, `microflowCount`, `pageCount`.
+
+### 5.4 Focused view — view entity
+
+```bash
+mxcli describe -p app.mpr --format elk entity MyModule.ViewEntity
+```
+
+**Expected:** Delegates to OQL plan for view entities. Output includes source entities from OQL query.
+
+### 5.5 Associations in output
+
+**Expected:** Each association object contains `id`, `name`, `parent`, `child`, `type` (`Reference` / `ReferenceSet`).
+
+### 5.6 Generalizations in output
+
+**Expected:** Each generalization contains `child` and `parent` entity references.
+
+### 5.7 Source map
+
+**Expected:** `sourceMap` maps entity/association IDs to qualified names for client-side lookups.
+
+### 5.8 Empty module
+
+```bash
+mxcli describe -p app.mpr --format elk entity EmptyModule.SomeEntity
+```
+
+**Expected:** JSON with empty `entities`, `associations`, `generalizations` arrays (or error if no entity exists).
+
+### 5.9 Non-existent entity
+
+```bash
+mxcli describe -p app.mpr --format elk entity FakeModule.Fake
+```
+
+**Expected:** Error — entity/module not found.
+
+---
+
+## 6. ELK MICROFLOW
+
+> **Note:** ELK microflow output is available via CLI only: `mxcli describe -p app.mpr --format elk microflow Module.MF`.
+
+### 6.1 Basic microflow
+
+```bash
+mxcli describe -p app.mpr --format elk microflow MyModule.ACT_Simple
+```
+
+**Expected:** JSON with `nodes`, `edges`, `sourceMap`. Nodes include at least `start` and `end` types.
+
+### 6.2 Node types
+
+Verify node `type` values across different microflows:
+
+| Type | Meaning |
+|------|---------|
+| `start` | Start event |
+| `end` | End event |
+| `continue` | Continue event |
+| `break` | Break event |
+| `error` | Error handler |
+| `split` | Decision / exclusive split |
+| `merge` | Merge point |
+| `loop` | Loop activity (compound) |
+| `action` | Activity (action call, object operation, etc.) |
+
+### 6.3 Edge structure
+
+**Expected:** Each edge has `source`, `target`, optional `label` (for split conditions).
+
+### 6.4 Loop node — compound
+
+```bash
+mxcli describe -p app.mpr --format elk microflow MyModule.ACT_WithLoop
+```
+
+**Expected:** Loop node contains `children` (inner nodes) and `innerEdges`. Loop body rendered as sub-graph.
+
+### 6.5 Source map
+
+**Expected:** `sourceMap` maps node IDs to action names/descriptions.
+
+### 6.6 Non-existent microflow
+
+```bash
+mxcli describe -p app.mpr --format elk microflow MyModule.Fake
+```
+
+**Expected:** Error — microflow not found.
+
+---
+
+## 7. MERMAID
+
+> **Note:** Mermaid output is available via CLI only: `mxcli describe -p app.mpr --format mermaid <type> <name>`.
+
+### 7.1 Entity / domain model — erDiagram
+
+```bash
+mxcli describe -p app.mpr --format mermaid entity MyModule.Customer
+```
+
+**Expected:** Mermaid `erDiagram` syntax. Entities as blocks, associations as relationships. Metadata comments: `%% @colors`, `%% @nodeinfo`.
+
+### 7.2 Microflow — flowchart LR
+
+```bash
+mxcli describe -p app.mpr --format mermaid microflow MyModule.ACT_Process
+```
+
+**Expected:** Mermaid `flowchart LR` syntax. Start/end as rounded nodes, decisions as diamonds, actions as rectangles. Metadata comments present.
+
+### 7.3 Nanoflow — flowchart LR
+
+```bash
+mxcli describe -p app.mpr --format mermaid nanoflow MyModule.NAF_Validate
+```
+
+**Expected:** Same format as microflow. `flowchart LR` with nanoflow-specific nodes.
+
+### 7.4 Page — block-beta
+
+```bash
+mxcli describe -p app.mpr --format mermaid page MyModule.HomePage
+```
+
+**Expected:** Mermaid `block-beta` syntax representing page layout. Widgets as blocks.
+
+### 7.5 Metadata comments — @colors
+
+**Expected:** Output includes `%% @colors` comment with color assignments for entity categories or node types.
+
+### 7.6 Metadata comments — @nodeinfo
+
+**Expected:** Output includes `%% @nodeinfo` comment with node metadata (IDs, types).
+
+### 7.7 Non-existent document
+
+```bash
+mxcli describe -p app.mpr --format mermaid microflow MyModule.Fake
+```
+
+**Expected:** Error — document not found.
+
+---
+
+## 8. CONTRACT
+
+### 8.1 Show contract entities
+
+```
+SHOW CONTRACT ENTITIES FROM MyModule.MyService;
+```
+
+**Expected:** Table of published/consumed entities in the service contract.
+
+### 8.2 Show contract actions
+
+```
+SHOW CONTRACT ACTIONS FROM MyModule.MyService;
+```
+
+**Expected:** Table of published microflow actions.
+
+### 8.3 Show contract channels
+
+```
+SHOW CONTRACT CHANNELS FROM MyModule.MyService;
+```
+
+**Expected:** Table of message channels.
+
+### 8.4 Show contract messages
+
+```
+SHOW CONTRACT MESSAGES FROM MyModule.MyService;
+```
+
+**Expected:** Table of message definitions.
+
+### 8.5 Describe contract entity
+
+```
+DESCRIBE CONTRACT ENTITY MyModule.MyService.Customer;
+```
+
+**Expected:** Detailed entity description: attributes, types, key fields.
+
+### 8.6 Describe contract entity — MDL format
+
+```
+DESCRIBE CONTRACT ENTITY MyModule.MyService.Customer FORMAT mdl;
+```
+
+**Expected:** MDL-syntax output for the contract entity.
+
+### 8.7 Create external entities — all
+
+```
+CREATE EXTERNAL ENTITIES FROM MyModule.MyService;
+```
+
+**Expected:** External entities created in the service's module. `show entities` lists them as `External` type.
+
+### 8.8 Create external entities — into specific module
+
+```
+CREATE EXTERNAL ENTITIES FROM MyModule.MyService INTO TargetModule;
+```
+
+**Expected:** External entities created in `TargetModule` instead of default.
+
+### 8.9 Create external entities — selective
+
+```
+CREATE EXTERNAL ENTITIES FROM MyModule.MyService ENTITIES (Customer, Order);
+```
+
+**Expected:** Only `Customer` and `Order` external entities created.
+
+### 8.10 Non-existent service
+
+```
+SHOW CONTRACT ENTITIES FROM MyModule.Fake;
+```
+
+**Expected:** Error — service not found.
+
+---
+
+## 9. SHOW DESIGN PROPERTIES / DESCRIBE STYLING / ALTER STYLING
+
+### 9.1 Show all design properties
+
+```
+SHOW DESIGN PROPERTIES;
+```
+
+**Expected:** Table of available design properties with columns: `WidgetType | Property | Values`.
+
+### 9.2 Show design properties — filtered
+
+```
+SHOW DESIGN PROPERTIES FOR TextBox;
+```
+
+**Expected:** Only design properties applicable to `TextBox` widget.
+
+### 9.3 Describe styling on page
+
+```
+DESCRIBE STYLING ON PAGE MyModule.HomePage;
+```
+
+**Expected:** Lists all widgets on the page with their current `Class`, `Style`, and design property values.
+
+### 9.4 Describe styling on snippet
+
+```
+DESCRIBE STYLING ON SNIPPET MyModule.Header;
+```
+
+**Expected:** Same format, scoped to snippet.
+
+### 9.5 Describe styling — specific widget
+
+```
+DESCRIBE STYLING ON PAGE MyModule.HomePage WIDGET saveButton;
+```
+
+**Expected:** Styling for only the named widget.
+
+### 9.6 Alter styling — set class and style
+
+```
+ALTER STYLING ON PAGE MyModule.HomePage WIDGET saveButton SET Class='btn-primary mx-2', Style='color: red;';
+```
+
+**Expected:** Widget updated. `DESCRIBE STYLING` confirms new values.
+
+### 9.7 Alter styling — clear design properties
+
+```
+ALTER STYLING ON PAGE MyModule.HomePage WIDGET saveButton SET Class='btn-default' CLEAR DESIGN PROPERTIES;
+```
+
+**Expected:** Class set, all design properties cleared. `DESCRIBE STYLING` shows empty design properties.
+
+### 9.8 Alter styling on snippet
+
+```
+ALTER STYLING ON SNIPPET MyModule.Header WIDGET title SET Class='text-bold';
+```
+
+**Expected:** Snippet widget updated.
+
+### 9.9 Non-existent widget
+
+```
+ALTER STYLING ON PAGE MyModule.HomePage WIDGET nonexistent SET Class='x';
+```
+
+**Expected:** Error — widget not found.
+
+### 9.10 Non-existent page
+
+```
+DESCRIBE STYLING ON PAGE MyModule.Fake;
+```
+
+**Expected:** Error — page not found.
+
+---
+
+## 10. SHOW LANGUAGES
+
+### 10.1 Show languages — after catalog refresh
+
+```
+REFRESH CATALOG FULL;
+SHOW LANGUAGES;
+```
+
+**Expected:** Table with columns: `Language | Strings`. Lists all configured languages with translation string counts.
+
+### 10.2 Show languages — without catalog
+
+Start a fresh session without running `REFRESH CATALOG FULL`.
+
+```
+SHOW LANGUAGES;
+```
+
+**Expected:** Error — requires `REFRESH CATALOG FULL` first.
+
+---
+
+## 11. MULTI-STEP WORKFLOWS
+
+### 11.1 Create → Diff → Rename → Lint
+
+```mdl
+-- Step 1: Create entities
+CREATE PERSISTENT ENTITY MyModule.OldProduct (
+  Name: string(200),
+  Price: decimal
+);
+
+CREATE PERSISTENT ENTITY MyModule.Category (
+  Label: string(100)
+);
+
+CREATE ASSOCIATION MyModule.OldProduct_Category
+FROM MyModule.OldProduct TO MyModule.Category
+TYPE reference OWNER default;
+```
+
+Save as `setup.mdl`, then:
+
+```
+-- Step 2: Diff the script
+DIFF 'setup.mdl';
+```
+
+**Expected:** `3 new, 0 modified, 0 unchanged`.
+
+Execute the script, then:
+
+```
+-- Step 3: Rename
+RENAME ENTITY MyModule.OldProduct TO Product;
+```
+
+**Expected:** `Renamed`. References in association updated.
+
+```
+-- Step 4: Verify references
+DESCRIBE ASSOCIATION MyModule.OldProduct_Category;
+```
+
+**Expected:** Association now references `MyModule.Product` (or association also renamed).
+
+```
+-- Step 5: Lint
+LINT MyModule;
+```
+
+**Expected:** No naming violations for the renamed entity.
+
+### 11.2 Full tooling pipeline
+
+1. `mxcli describe --format elk entity MyModule.Customer` — capture baseline
+2. Create new entities via script
+3. `DIFF 'changes.mdl'` — preview changes
+4. Execute script
+5. `mxcli describe --format mermaid entity MyModule.Customer` — visualize updated model
+6. `LINT MyModule` — check for issues
+7. `RENAME ENTITY MyModule.Temp TO Final` — clean up names
+8. `mxcli describe --format elk entity MyModule.Customer` — verify final layout
+
+**Expected:** Each step succeeds. Final ELK output includes all new entities.
+
+---
+
+## 12. FAILURE MODES
+
+### 12.1 Not connected
+
+Run any tooling command without an open `.mpr`:
+
+```
+LINT;
+```
+
+**Expected:** Error — not connected to a project.
+
+### 12.2 Document not found
+
+```
+RENAME MICROFLOW MyModule.NonExistent TO Something;
+```
+
+**Expected:** Error — microflow not found.
+
+### 12.3 Unsupported type for rename
+
+```
+RENAME WORKFLOW MyModule.Old TO New;
+```
+
+**Expected:** Error — unsupported type. Lists supported types.
+
+### 12.4 MPR v1 for DIFF LOCAL
+
+Open an MPR v1 project:
+
+```
+DIFF LOCAL 'HEAD';
+```
+
+**Expected:** Error — MPR v2 required (Mendix 10.18+).
+
+### 12.5 No catalog for SHOW LANGUAGES
+
+```
+SHOW LANGUAGES;
+```
+
+**Expected:** Error — run `REFRESH CATALOG FULL` first.
+
+### 12.6 Invalid DIFF script path
+
+```
+DIFF '/nonexistent/path/script.mdl';
+```
+
+**Expected:** Error — file not found.
+
+### 12.7 LINT with invalid config
+
+Create a malformed `.mdllint.yaml`:
+
+```yaml
+excludeModules: "not-a-list"
+```
+
+**Expected:** Error or warning about invalid config format.
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| RENAME (all types) | x | x | |
+| RENAME DRY RUN | x | | |
+| RENAME MODULE | x | | |
+| DIFF (MDL Script) | x | x | |
+| DIFF LOCAL | x | | |
+| LINT | x | x | x |
+| LINT FORMAT json/sarif | x | | |
+| SHOW LINT RULES | x | | |
+| ELK entity (CLI --format elk) | x | x | x |
+| ELK microflow (CLI --format elk) | x | x | |
+| MERMAID entity (CLI --format mermaid) | x | x | x |
+| MERMAID microflow (CLI) | x | x | |
+| MERMAID nanoflow (CLI) | x | | |
+| MERMAID page (CLI) | x | x | |
+| CONTRACT (all) | x | | |
+| DESIGN PROPERTIES | x | x | |
+| SHOW LANGUAGES | x | | |
+
+Read operations tested on all applicable projects. Write operations on copies of one project.
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. RENAME | Mock tests | Module rename, prefix scan |
+| 2. DIFF (MDL Script) | Mock tests | Mixed scripts, format variants |
+| 3. DIFF LOCAL | | All manual (requires git + MPR v2) |
+| 4. LINT | Mock tests | Custom Starlark rules, SARIF |
+| 5. ELK DOMAIN MODEL | CLI only | All (--format elk on describe) |
+| 6. ELK MICROFLOW | CLI only | All (--format elk on describe) |
+| 7. MERMAID | CLI only | All (--format mermaid on describe) |
+| 8. CONTRACT | Mock tests | External entity creation |
+| 9. DESIGN PROPERTIES | | All manual |
+| 10. SHOW LANGUAGES | | All manual (requires catalog) |
+| 11. Multi-step | | All manual |
+| 12. Failure modes | Partial | MPR v1, missing catalog |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | RENAME | Entity dry run | | | | |
+| 1.2 | RENAME | Entity live | | | | |
+| 1.3 | RENAME | Microflow | | | | |
+| 1.4 | RENAME | Nanoflow | | | | |
+| 1.5 | RENAME | Page | | | | |
+| 1.6 | RENAME | Enumeration | | | | |
+| 1.7 | RENAME | Association | | | | |
+| 1.8 | RENAME | Constant | | | | |
+| 1.9 | RENAME | Module | | | | |
+| 1.10 | RENAME | Module prefix scan | | | | |
+| 1.11 | RENAME | Not found | | | | |
+| 1.12 | RENAME | Unsupported type | | | | |
+| 1.13 | RENAME | Dry run no side effects | | | | |
+| 2.1 | DIFF | Unified format | | | | |
+| 2.2 | DIFF | Side format | | | | |
+| 2.3 | DIFF | Struct format | | | | |
+| 2.4 | DIFF | Modifications | | | | |
+| 2.5 | DIFF | CREATE ENTITY | | | | |
+| 2.6 | DIFF | VIEW ENTITY | | | | |
+| 2.7 | DIFF | ENUMERATION | | | | |
+| 2.8 | DIFF | ASSOCIATION | | | | |
+| 2.9 | DIFF | MICROFLOW | | | | |
+| 2.10 | DIFF | NANOFLOW | | | | |
+| 2.11 | DIFF | Mixed script | | | | |
+| 2.12 | DIFF | Non-existent script | | | | |
+| 2.13 | DIFF | Empty script | | | | |
+| 3.1 | DIFF LOCAL | HEAD | | | | |
+| 3.2 | DIFF LOCAL | Branch range | | | | |
+| 3.3 | DIFF LOCAL | Unified format | | | | |
+| 3.4 | DIFF LOCAL | Side format | | | | |
+| 3.5 | DIFF LOCAL | Struct format | | | | |
+| 3.6 | DIFF LOCAL | MPR v1 rejection | | | | |
+| 3.7 | DIFF LOCAL | No changes | | | | |
+| 3.8 | DIFF LOCAL | Invalid ref | | | | |
+| 4.1 | LINT | All modules | | | | |
+| 4.2 | LINT | Single module | | | | |
+| 4.3 | LINT | JSON format | | | | |
+| 4.4 | LINT | SARIF format | | | | |
+| 4.5 | LINT | Show rules | | | | |
+| 4.6 | LINT | NamingConvention | | | | |
+| 4.7 | LINT | EmptyMicroflow | | | | |
+| 4.8 | LINT | DomainModelSize | | | | |
+| 4.9 | LINT | ValidationFeedback | | | | |
+| 4.10 | LINT | ImageSource | | | | |
+| 4.11 | LINT | MissingTranslations | | | | |
+| 4.12 | LINT | Custom Starlark rule | | | | |
+| 4.13 | LINT | excludeModules config | | | | |
+| 4.14 | LINT | Clean project | | | | |
+| 5.1 | ELK DOMAIN | Focused entity | | | | |
+| 5.2 | ELK DOMAIN | Entity categories | | | | |
+| 5.3 | ELK DOMAIN | System overview | | | | |
+| 5.4 | ELK DOMAIN | Focused view entity | | | | |
+| 5.5 | ELK DOMAIN | Associations | | | | |
+| 5.6 | ELK DOMAIN | Generalizations | | | | |
+| 5.7 | ELK DOMAIN | Source map | | | | |
+| 5.8 | ELK DOMAIN | Empty module | | | | |
+| 5.9 | ELK DOMAIN | Non-existent entity | | | | |
+| 6.1 | ELK MICROFLOW | Basic | | | | |
+| 6.2 | ELK MICROFLOW | Node types | | | | |
+| 6.3 | ELK MICROFLOW | Edge structure | | | | |
+| 6.4 | ELK MICROFLOW | Loop compound | | | | |
+| 6.5 | ELK MICROFLOW | Source map | | | | |
+| 6.6 | ELK MICROFLOW | Not found | | | | |
+| 7.1 | MERMAID | Entity erDiagram | | | | |
+| 7.2 | MERMAID | Microflow flowchart | | | | |
+| 7.3 | MERMAID | Nanoflow flowchart | | | | |
+| 7.4 | MERMAID | Page block-beta | | | | |
+| 7.5 | MERMAID | @colors metadata | | | | |
+| 7.6 | MERMAID | @nodeinfo metadata | | | | |
+| 7.7 | MERMAID | Not found | | | | |
+| 8.1 | CONTRACT | Show entities | | | | |
+| 8.2 | CONTRACT | Show actions | | | | |
+| 8.3 | CONTRACT | Show channels | | | | |
+| 8.4 | CONTRACT | Show messages | | | | |
+| 8.5 | CONTRACT | Describe entity | | | | |
+| 8.6 | CONTRACT | Describe FORMAT mdl | | | | |
+| 8.7 | CONTRACT | Create external — all | | | | |
+| 8.8 | CONTRACT | Create external — INTO | | | | |
+| 8.9 | CONTRACT | Create external — selective | | | | |
+| 8.10 | CONTRACT | Not found | | | | |
+| 9.1 | DESIGN PROPS | Show all | | | | |
+| 9.2 | DESIGN PROPS | Show filtered | | | | |
+| 9.3 | STYLING | Describe page | | | | |
+| 9.4 | STYLING | Describe snippet | | | | |
+| 9.5 | STYLING | Describe widget | | | | |
+| 9.6 | STYLING | Alter set class/style | | | | |
+| 9.7 | STYLING | Alter clear design props | | | | |
+| 9.8 | STYLING | Alter snippet widget | | | | |
+| 9.9 | STYLING | Widget not found | | | | |
+| 9.10 | STYLING | Page not found | | | | |
+| 10.1 | LANGUAGES | After catalog refresh | | | | |
+| 10.2 | LANGUAGES | Without catalog | | | | |
+| 11.1 | MULTI-STEP | Create → Diff → Rename → Lint | | | | |
+| 11.2 | MULTI-STEP | Full tooling pipeline | | | | |
+| 12.1 | FAILURE | Not connected | | | | |
+| 12.2 | FAILURE | Document not found | | | | |
+| 12.3 | FAILURE | Unsupported type | | | | |
+| 12.4 | FAILURE | MPR v1 for DIFF LOCAL | | | | |
+| 12.5 | FAILURE | No catalog for LANGUAGES | | | | |
+| 12.6 | FAILURE | Invalid DIFF path | | | | |
+| 12.7 | FAILURE | Invalid lint config | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped
diff --git a/docs/15-testing/workflow-test-cases.md b/docs/15-testing/workflow-test-cases.md
new file mode 100644
index 00000000..e27b8720
--- /dev/null
+++ b/docs/15-testing/workflow-test-cases.md
@@ -0,0 +1,1124 @@
+# Workflow Test Cases — Manual Testing
+
+**Updated:** 2026-04-29
+**PR:** [mendixlabs/mxcli#386](https://github.com/mendixlabs/mxcli/pull/386)
+
+## Test Projects
+
+Demo apps from [Mendix App Gallery](https://appgallery.mendixcloud.com/):
+
+| App | Studio Pro | Workflows | User Tasks | Decisions |
+|-----|-----------|-----------|------------|-----------|
+| Lato Enquiry Management | 11.4.0 | — | — | — |
+| Evora - Factory Management | 10.24.15 | — | — | — |
+| Lato Product Inventory | 11.2.0 | — | — | — |
+
+---
+
+## Setup
+
+### 1. Download test apps
+
+1. Go to [Mendix App Gallery](https://appgallery.mendixcloud.com/)
+2. Download each demo app listed above
+3. Open each `.mpk` in Studio Pro to extract the `.mpr` file
+
+### 2. Build mxcli
+
+```bash
+make build && make test && make lint-go
+```
+
+### 3. Smoke test
+
+```bash
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
+  echo "=== $(basename $(dirname $mpr)) ==="
+  echo "show workflows;" > /tmp/show-wf.mdl
+  mxcli exec /tmp/show-wf.mdl -p "$mpr" 2>&1 | tail -1
+done
+```
+
+Expected: count line `(N workflows)` for each project.
+
+### 4. Interactive testing
+
+```bash
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
+```
+
+### 5. Script-based testing
+
+```bash
+mxcli exec test-sequence.mdl -p <mpr>
+```
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder.
+> Dropped workflows cannot be recovered.
+>
+> ```bash
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
+
+---
+
+## 1. SHOW WORKFLOWS
+
+### 1.1 List all workflows
+
+```
+show workflows;
+```
+
+**Expected:** Table with columns `Qualified Name | Activities | User Tasks | Decisions | Parameter Entity`. Summary `(N workflows)`.
+
+### 1.2 Filter by module
+
+```
+show workflows in Administration;
+```
+
+**Expected:** Only workflows from `Administration` module.
+
+### 1.3 Empty module
+
+```
+show workflows in NonExistentModule;
+```
+
+**Expected:** Empty result or `(0 workflows)`.
+
+---
+
+## 2. DESCRIBE WORKFLOW
+
+### 2.1 Simple workflow
+
+```
+describe workflow MyModule.ApprovalWorkflow;
+```
+
+**Expected:** Full MDL output with header properties:
+
+```
+create or modify workflow MyModule.ApprovalWorkflow
+  parameter $WorkflowContext: MyModule.Request
+  display 'Approval Workflow'
+  description 'Handles approval requests'
+  export level Hidden
+  overview page MyModule.WorkflowOverview
+  due date '7d'
+begin
+  ...
+end workflow;
+/
+```
+
+### 2.2 User task activity
+
+```
+describe workflow <Module.WorkflowWithUserTask>;
+```
+
+**Expected:** Body contains user task with page, targeting, due date:
+
+```
+  user task ut1 'Review Request'
+    page MyModule.ReviewPage
+    description 'Review the submitted request'
+    targeting microflow MyModule.GetReviewers
+    due date '3d'
+  outcomes
+    'Approve' { }
+    'Reject' { }
+  end task;
+```
+
+### 2.3 Multi user task activity
+
+```
+describe workflow <Module.WorkflowWithMultiUserTask>;
+```
+
+**Expected:** `multi user task` keyword. Outcomes listed.
+
+### 2.4 Call microflow — without parameters
+
+```
+describe workflow <Module.WorkflowWithMfCall>;
+```
+
+**Expected:** Body contains:
+
+```
+  call microflow MyModule.ProcessRequest;
+```
+
+### 2.5 Call microflow — with parameters
+
+```
+describe workflow <Module.WorkflowWithParamMfCall>;
+```
+
+**Expected:** Body contains:
+
+```
+  call microflow MyModule.SendNotification($WorkflowContext);
+```
+
+### 2.6 Call workflow activity
+
+```
+describe workflow <Module.WorkflowWithSubWorkflow>;
+```
+
+**Expected:** Body contains `call workflow MyModule.SubWorkflow;`.
+
+### 2.7 Boolean decision
+
+```
+describe workflow <Module.WorkflowWithBoolDecision>;
+```
+
+**Expected:** Decision with `true`/`false` outcomes. Each outcome contains nested activities:
+
+```
+  decision 'Is Approved'
+    expression $WorkflowContext/IsApproved
+  outcomes
+    true {
+      call microflow MyModule.OnApproved;
+    }
+    false {
+      call microflow MyModule.OnRejected;
+    }
+  end decision;
+```
+
+### 2.8 Enum decision
+
+```
+describe workflow <Module.WorkflowWithEnumDecision>;
+```
+
+**Expected:** Decision outcomes match enum values:
+
+```
+  decision 'Check Status'
+    expression $WorkflowContext/Status
+  outcomes
+    'Draft'
+      ...
+    'Submitted'
+      ...
+    'Archived'
+      ...
+  end decision;
+```
+
+### 2.9 Parallel split
+
+```
+describe workflow <Module.WorkflowWithParallelSplit>;
+```
+
+**Expected:** Parallel split with named paths:
+
+```
+  parallel split
+  paths
+    path 'Finance Review'
+      user task ut1 'Finance Approval' ...
+    path 'Legal Review'
+      user task ut2 'Legal Approval' ...
+  end split;
+```
+
+### 2.10 Jump to activity
+
+```
+describe workflow <Module.WorkflowWithJump>;
+```
+
+**Expected:** `jump to 'ActivityCaption';` in body.
+
+### 2.11 Wait for timer
+
+```
+describe workflow <Module.WorkflowWithTimer>;
+```
+
+**Expected:** `wait for timer delay '2d';` or similar duration expression.
+
+### 2.12 Wait for notification
+
+```
+describe workflow <Module.WorkflowWithNotification>;
+```
+
+**Expected:** `wait for notification;` in body.
+
+### 2.13 Annotation
+
+```
+describe workflow <Module.AnnotatedWorkflow>;
+```
+
+**Expected:** `@annotation 'text'` on activities or at workflow level.
+
+### 2.14 Boundary event — interrupting timer
+
+```
+describe workflow <Module.WorkflowWithInterruptingTimer>;
+```
+
+**Expected:** Boundary event attached to a user task:
+
+```
+  user task ut1 'Review'
+    ...
+  outcomes
+    'Approve' {
+      ...
+    }
+  boundary events
+    interrupting timer delay '5d'
+      call microflow MyModule.OnTimeout;
+  end task;
+```
+
+### 2.15 Boundary event — non-interrupting timer
+
+```
+describe workflow <Module.WorkflowWithNonInterruptingTimer>;
+```
+
+**Expected:** `non-interrupting timer delay '3d'` in boundary events block.
+
+### 2.16 Outcome blocks with nested activities
+
+```
+describe workflow <Module.WorkflowWithNestedOutcomes>;
+```
+
+**Expected:** Each outcome contains one or more activities. Nesting preserved in indentation.
+
+### 2.17 Non-existent workflow
+
+```
+describe workflow Fake.Missing;
+```
+
+**Expected:** Error — not found.
+
+> **Note:** GRANT/REVOKE EXECUTE ON WORKFLOW is not supported. Mendix workflows do not have document-level `AllowedModuleRoles`. Workflow access is controlled via trigger microflows. The security-test-cases doc covers GRANT EXECUTE on microflows/nanoflows.
+
+---
+
+## 3. CREATE WORKFLOW
+
+### 3.1 Minimal workflow
+
+```
+create workflow MyModule.WF_Simple
+  parameter $WorkflowContext: MyModule.Request
+begin
+end workflow;
+```
+
+**Expected:** Created. `show workflows in MyModule` includes it. Implicit Start and End activities generated.
+
+### 3.2 Full syntax with all optional clauses
+
+```
+create workflow MyModule.WF_Full
+  parameter $WorkflowContext: MyModule.Request
+  display 'Full Workflow'
+  description 'A workflow with all optional clauses'
+  export level Hidden
+  overview page MyModule.OverviewPage
+  due date '14d'
+begin
+  user task ut1 'Review'
+    page MyModule.ReviewPage
+    description 'Initial review'
+    targeting microflow MyModule.GetReviewers
+    due date '3d'
+  outcomes
+    'Approve' {
+      call microflow MyModule.OnApproved;
+    }
+    'Reject' {
+      call microflow MyModule.OnRejected;
+    }
+  end task;
+end workflow;
+```
+
+**Expected:** All header properties and body activities preserved. `describe` output matches.
+
+> **BUG-015 (Critical):** CREATE WORKFLOW with a user task panics with nil pointer dereference at `visitor_workflow.go:420`. Blocked until fix lands.
+
+### 3.3 CREATE OR REPLACE variant
+
+```
+create or replace workflow MyModule.WF_Simple
+  parameter $WorkflowContext: MyModule.Request
+begin
+  user task ut1 'New Task'
+    page MyModule.TaskPage
+  outcomes
+    'Done' { }
+  end task;
+end workflow;
+```
+
+**Expected:** Drops and recreates. New body replaces old.
+
+### 3.4 Multiple activity types in body
+
+```
+create workflow MyModule.WF_Complex
+  parameter $WorkflowContext: MyModule.Request
+begin
+  call microflow MyModule.ValidateRequest;
+  decision 'Is Valid'
+    expression $WorkflowContext/IsValid
+  outcomes
+    true {
+      user task ut1 'Approve'
+        page MyModule.ApprovalPage
+        targeting xpath '[Module.Request_Approver = '[%CurrentUser%]']'
+        due date '5d'
+      outcomes
+        'Approved' {
+          call microflow MyModule.FinalizeApproval;
+        }
+        'Rejected' {
+          call microflow MyModule.NotifyRejection;
+        }
+      end task;
+    }
+    false {
+      call microflow MyModule.RejectInvalid;
+    }
+  end decision;
+end workflow;
+```
+
+**Expected:** Decision with nested user task and outcomes created.
+
+### 3.5 Parallel split in body
+
+```
+create workflow MyModule.WF_Parallel
+  parameter $WorkflowContext: MyModule.Request
+begin
+  parallel split
+  paths
+    path 'Manager Review'
+      user task ut1 'Manager Approval'
+        page MyModule.ManagerPage
+      outcomes
+        'Approve' { }
+        'Reject' { }
+      end task;
+    path 'Finance Review'
+      user task ut2 'Finance Approval'
+        page MyModule.FinancePage
+      outcomes
+        'Approve' { }
+        'Reject' { }
+      end task;
+  end split;
+end workflow;
+```
+
+**Expected:** Parallel split with two paths created. Each path contains a user task.
+
+### 3.6 Implicit Start/End auto-behavior
+
+```
+create workflow MyModule.WF_Implicit
+  parameter $WorkflowContext: MyModule.Request
+begin
+  call microflow MyModule.DoSomething;
+end workflow;
+```
+
+**Expected:** `describe` shows Start and End activities implicitly. No need to declare them.
+
+### 3.7 Parameter auto-binding
+
+```
+create workflow MyModule.WF_AutoBind
+  parameter $WorkflowContext: MyModule.Request
+begin
+  user task ut1 'Review'
+    page MyModule.ReviewPage
+  outcomes
+    'Done' { }
+  end task;
+end workflow;
+```
+
+**Expected:** Parameter entity `MyModule.Request` auto-binds as `$WorkflowContext`. Accessible in expressions and activity targeting.
+
+### 3.8 Duplicate name deduplication (CE0495)
+
+```
+create workflow MyModule.WF_DupNames
+  parameter $WorkflowContext: MyModule.Request
+begin
+  call microflow MyModule.Step1;
+  call microflow MyModule.Step1;
+end workflow;
+```
+
+**Expected:** Compiler event CE0495 — duplicate activity caption. Second activity receives deduplicated caption (e.g., `Step1 2`).
+
+### 3.9 Boolean decision skips Default outcome (CE6686)
+
+```
+create workflow MyModule.WF_BoolDecision
+  parameter $WorkflowContext: MyModule.Request
+begin
+  decision 'Check Flag'
+    expression $WorkflowContext/IsActive
+  outcomes
+    true {
+      call microflow MyModule.OnActive;
+    }
+    false {
+      call microflow MyModule.OnInactive;
+    }
+  end decision;
+end workflow;
+```
+
+**Expected:** No Default outcome generated for boolean decisions. Compiler event CE6686 suppressed.
+
+### 3.10 Duplicate workflow (without modifier)
+
+```
+create workflow MyModule.WF_Simple
+  parameter $WorkflowContext: MyModule.Request
+begin
+end workflow;
+```
+
+**Expected:** Error — workflow already exists.
+
+### 3.11 Boundary events in CREATE
+
+```
+create workflow MyModule.WF_WithBoundary
+  parameter $WorkflowContext: MyModule.Request
+begin
+  user task ut1 'Long Review'
+    page MyModule.ReviewPage
+    due date '7d'
+  outcomes
+    'Approve' { }
+    'Reject' { }
+  boundary events
+    interrupting timer delay '10d'
+      call microflow MyModule.EscalateTimeout;
+    non-interrupting timer delay '5d'
+      call microflow MyModule.SendReminder;
+  end task;
+end workflow;
+```
+
+**Expected:** Both boundary events created on the user task. `describe` shows both.
+
+---
+
+## 4. DROP WORKFLOW
+
+### 4.1 Drop existing workflow
+
+```
+drop workflow MyModule.WF_Simple;
+```
+
+**Expected:** Workflow removed. Not in `show workflows`.
+
+### 4.2 Drop non-existent workflow
+
+```
+drop workflow MyModule.Fake;
+```
+
+**Expected:** Error — not found.
+
+---
+
+## 5. ALTER WORKFLOW (Mendix 9.12+)
+
+> ALTER WORKFLOW requires Mendix 9.12+. Test against a project opened with Studio Pro 9.12 or later.
+
+### 5.1 SET display property
+
+```
+alter workflow MyModule.WF_Full
+  set display 'Updated Display Name';
+```
+
+**Expected:** `describe` shows new display name.
+
+### 5.2 SET description property
+
+```
+alter workflow MyModule.WF_Full
+  set description 'Updated description text';
+```
+
+**Expected:** `describe` shows new description.
+
+### 5.3 SET export level property
+
+```
+alter workflow MyModule.WF_Full
+  set export level Public;
+```
+
+**Expected:** `describe` shows `export level Public`.
+
+### 5.4 SET due date property
+
+```
+alter workflow MyModule.WF_Full
+  set due date '30d';
+```
+
+**Expected:** `describe` shows updated due date.
+
+### 5.5 SET overview page property
+
+```
+alter workflow MyModule.WF_Full
+  set overview page MyModule.NewOverviewPage;
+```
+
+**Expected:** `describe` shows new overview page.
+
+### 5.6 SET parameter property
+
+```
+alter workflow MyModule.WF_Full
+  set parameter $WorkflowContext: MyModule.NewParameterEntity;
+```
+
+**Expected:** `describe` shows updated parameter entity.
+
+### 5.7 SET ACTIVITY page
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'Review' page MyModule.NewReviewPage;
+```
+
+**Expected:** User task `Review` points to new page. `describe` confirms.
+
+### 5.8 SET ACTIVITY description
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'Review' description 'Updated task description';
+```
+
+**Expected:** `describe` shows new description on the activity.
+
+### 5.9 SET ACTIVITY targeting microflow
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'Review' targeting microflow MyModule.NewTargeting;
+```
+
+**Expected:** Targeting microflow updated.
+
+### 5.10 SET ACTIVITY targeting xpath
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'Review' targeting xpath '[Status = ''Active'']';
+```
+
+**Expected:** Targeting XPath updated.
+
+### 5.11 SET ACTIVITY due date
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'Review' due date '5d';
+```
+
+**Expected:** Activity due date updated.
+
+### 5.12 SET ACTIVITY with @N for disambiguation
+
+```
+alter workflow MyModule.WF_DupNames
+  set activity 'Step1' @2 description 'Second step';
+```
+
+**Expected:** Only the second `Step1` activity updated.
+
+### 5.13 INSERT AFTER activity
+
+```
+alter workflow MyModule.WF_Full
+  insert after 'Review'
+    call microflow MyModule.PostReviewAction;
+```
+
+**Expected:** New activity inserted after `Review`. `describe` shows correct ordering.
+
+### 5.14 INSERT AFTER with @N
+
+```
+alter workflow MyModule.WF_DupNames
+  insert after 'Step1' @1
+    call microflow MyModule.AfterFirstStep;
+```
+
+**Expected:** Activity inserted after the first `Step1` only.
+
+### 5.15 INSERT AFTER with full activity definition
+
+```
+alter workflow MyModule.WF_Full
+  insert after 'Review'
+    user task ut1 'Secondary Review'
+      page MyModule.SecondaryPage
+      due date '2d'
+    outcomes
+      'Approve' { }
+      'Reject' { }
+    end task;
+```
+
+**Expected:** Full user task definition inserted.
+
+### 5.16 DROP ACTIVITY
+
+```
+alter workflow MyModule.WF_Full
+  drop activity 'Secondary Review';
+```
+
+**Expected:** Activity removed. `describe` no longer shows it.
+
+### 5.17 DROP ACTIVITY with @N
+
+```
+alter workflow MyModule.WF_DupNames
+  drop activity 'Step1' @2;
+```
+
+**Expected:** Only the second `Step1` removed.
+
+### 5.18 REPLACE ACTIVITY
+
+```
+alter workflow MyModule.WF_Full
+  replace activity 'Review' with
+    user task ut1 'Enhanced Review'
+      page MyModule.EnhancedPage
+      targeting microflow MyModule.NewTargeting
+      due date '4d'
+    outcomes
+      'Approve' { }
+      'Reject' { }
+      'Escalate' { }
+    end task;
+```
+
+**Expected:** Old activity replaced. `describe` shows `Enhanced Review` with three outcomes.
+
+### 5.19 REPLACE ACTIVITY with @N
+
+```
+alter workflow MyModule.WF_DupNames
+  replace activity 'Step1' @1 with
+    call microflow MyModule.ReplacedStep;
+```
+
+**Expected:** Only the first `Step1` replaced.
+
+### 5.20 INSERT OUTCOME on user task
+
+```
+alter workflow MyModule.WF_Full
+  insert outcome 'Escalate' on 'Enhanced Review' { };
+```
+
+**Expected:** New outcome added. `describe` shows three outcomes.
+
+### 5.21 DROP OUTCOME on user task
+
+```
+alter workflow MyModule.WF_Full
+  drop outcome 'Escalate' on 'Enhanced Review';
+```
+
+**Expected:** Outcome removed. `describe` shows two outcomes.
+
+### 5.22 INSERT PATH on parallel split
+
+```
+alter workflow MyModule.WF_Parallel
+  insert path 'HR Review' on activity 'Multi-Approval'
+    user task ut1 'HR Approval'
+      page MyModule.HRPage
+    outcomes
+      'Approve' { }
+      'Reject' { }
+    end task;
+```
+
+**Expected:** Third path added to parallel split.
+
+### 5.23 DROP PATH on parallel split
+
+```
+alter workflow MyModule.WF_Parallel
+  drop path 'HR Review' on activity 'Multi-Approval';
+```
+
+**Expected:** Path removed. `describe` shows two paths.
+
+### 5.24 INSERT BRANCH on decision
+
+```
+alter workflow MyModule.WF_BoolDecision
+  insert branch 'Maybe' on activity 'Check Flag'
+    call microflow MyModule.OnMaybe;
+```
+
+**Expected:** New branch added to decision (applicable for enum decisions).
+
+### 5.25 DROP BRANCH on decision
+
+```
+alter workflow MyModule.WF_BoolDecision
+  drop branch 'Maybe' on activity 'Check Flag';
+```
+
+**Expected:** Branch removed.
+
+### 5.26 INSERT BOUNDARY EVENT
+
+```
+alter workflow MyModule.WF_Full
+  insert boundary event on activity 'Enhanced Review'
+    interrupting timer delay '7d'
+      call microflow MyModule.OnEscalation;
+```
+
+**Expected:** Boundary event added to user task.
+
+### 5.27 DROP BOUNDARY EVENT
+
+```
+alter workflow MyModule.WF_Full
+  drop boundary event interrupting timer on activity 'Enhanced Review';
+```
+
+**Expected:** Boundary event removed.
+
+### 5.28 INSERT non-interrupting BOUNDARY EVENT
+
+```
+alter workflow MyModule.WF_Full
+  insert boundary event on activity 'Enhanced Review'
+    non-interrupting timer delay '3d'
+      call microflow MyModule.SendReminder;
+```
+
+**Expected:** Non-interrupting timer added. `describe` shows both event types if interrupting timer remains.
+
+---
+
+## 6. ROUNDTRIP
+
+### 6.1 Simple roundtrip
+
+1. `describe workflow MyModule.WF_Full` → capture MDL
+2. `drop workflow MyModule.WF_Full`
+3. Execute captured MDL
+4. `describe workflow MyModule.WF_Full` → capture again
+
+**Expected:** Output identical between step 1 and step 4.
+
+> **Known issue:** Roundtrip loses activity captions — `-- Comment` style captions revert to the microflow name after DROP + re-CREATE.
+
+### 6.2 Complex roundtrip
+
+Create a workflow with: user tasks, decisions (boolean + enum), parallel split, boundary events, call microflow, call workflow. Run DESCRIBE → DROP → execute → DESCRIBE.
+
+**Expected:** All activity types, outcomes, paths, and boundary events preserved.
+
+---
+
+## 7. MULTI-STEP
+
+### 7.1 Create workflow with user tasks → ALTER to add decisions
+
+1. Create workflow with two user tasks
+2. `alter workflow ... insert after 'Task1'` a boolean decision
+3. `describe` → verify decision between Task1 and Task2
+
+### 7.2 ALTER to insert boundary events
+
+1. Start from §7.1 result
+2. `alter workflow ... insert boundary event on activity 'Task2'` with interrupting timer
+3. `describe` → verify boundary event on Task2
+
+### 7.3 Full multi-step → DESCRIBE → verify structure
+
+1. Start from §7.2 result
+2. `alter workflow ... insert path` on a new parallel split
+3. `alter workflow ... insert outcome` on a user task
+4. `describe` → verify complete structure matches all modifications
+
+---
+
+## 8. FAILURE MODES
+
+### 8.1 Not connected
+
+```
+describe workflow MyModule.WF_Full;
+```
+
+Run without opening a project.
+
+**Expected:** Error — not connected to a project.
+
+### 8.2 Workflow not found
+
+```
+describe workflow MyModule.DoesNotExist;
+```
+
+**Expected:** Error — workflow not found.
+
+### 8.3 Feature gate — ALTER on pre-9.12 project
+
+```
+alter workflow MyModule.WF_Full
+  set display 'New Name';
+```
+
+Run against a Mendix project older than 9.12.
+
+**Expected:** Error indicating ALTER WORKFLOW requires Mendix 9.12+.
+
+### 8.4 Activity caption not found
+
+```
+alter workflow MyModule.WF_Full
+  set activity 'NonExistentTask' page MyModule.SomePage;
+```
+
+**Expected:** Error — activity with caption `NonExistentTask` not found.
+
+### 8.5 Duplicate ambiguous caption without AT POSITION
+
+```
+alter workflow MyModule.WF_DupNames
+  set activity 'Step1' description 'Which one?';
+```
+
+**Expected:** Error — ambiguous caption. Use `@N` to disambiguate.
+
+### 8.6 Invalid @N index
+
+```
+alter workflow MyModule.WF_DupNames
+  set activity 'Step1' @99 description 'Out of range';
+```
+
+**Expected:** Error — position out of range.
+
+### 8.7 DROP last outcome on user task
+
+```
+alter workflow MyModule.WF_Full
+  drop outcome 'Approve' on activity 'Review';
+alter workflow MyModule.WF_Full
+  drop outcome 'Reject' on activity 'Review';
+```
+
+**Expected:** Error when dropping the last outcome — user task requires at least one.
+
+### 8.8 DROP last path on parallel split
+
+**Expected:** Error — parallel split requires at least two paths.
+
+### 8.9 INSERT AFTER non-existent activity
+
+```
+alter workflow MyModule.WF_Full
+  insert after 'GhostActivity'
+    call microflow MyModule.Something;
+```
+
+**Expected:** Error — activity not found.
+
+### 8.10 CREATE with non-existent parameter entity
+
+```
+create workflow MyModule.WF_BadParam
+  parameter $WorkflowContext: NonExistent.Entity
+begin
+end workflow;
+```
+
+**Expected:** Error — entity not found.
+
+> **Known issue:** Non-existent parameter entity is currently accepted without validation. No error is raised.
+
+---
+
+## Activity Coverage Table
+
+| Activity Type | Test Case | Section |
+|---------------|-----------|---------|
+| user task | 2.2, 3.2 | DESCRIBE, CREATE |
+| multi user task | 2.3 | DESCRIBE |
+| call microflow (no params) | 2.4 | DESCRIBE |
+| call microflow (with params) | 2.5 | DESCRIBE |
+| call workflow | 2.6 | DESCRIBE |
+| decision (boolean) | 2.7, 3.9 | DESCRIBE, CREATE |
+| decision (enum) | 2.8 | DESCRIBE |
+| parallel split | 2.9, 3.5 | DESCRIBE, CREATE |
+| jump to | 2.10 | DESCRIBE |
+| wait for timer | 2.11 | DESCRIBE |
+| wait for notification | 2.12 | DESCRIBE |
+| annotation | 2.13 | DESCRIBE |
+| boundary event (interrupting) | 2.14, 3.11 | DESCRIBE, CREATE |
+| boundary event (non-interrupting) | 2.15, 3.11 | DESCRIBE, CREATE |
+
+---
+
+## Test Project Coverage Matrix
+
+| Operation | Lato Enquiry | Evora Factory | Lato Product |
+|-----------|:---:|:---:|:---:|
+| SHOW WORKFLOWS | x | x | x |
+| DESCRIBE WORKFLOW | x | x | x |
+| CREATE WORKFLOW | x | | |
+| DROP WORKFLOW | x | | |
+| ALTER WORKFLOW | x | | |
+| Roundtrip | x | x | x |
+| Multi-step | x | | |
+
+---
+
+## Automated Test Coverage
+
+| Section | Automated | Manual-only |
+|---------|:---------:|:-----------:|
+| 1. SHOW WORKFLOWS | Mock tests | |
+| 2. DESCRIBE WORKFLOW | Mock tests | Boundary events, annotations |
+| 3. CREATE WORKFLOW | Mock tests | Complex bodies, auto-behaviors |
+| 4. DROP WORKFLOW | Mock tests | |
+| 5. ALTER WORKFLOW | | All manual |
+| 6. Roundtrip | | All manual |
+| 7. Multi-step | | All manual |
+| 8. Failure modes | Partial | Feature gate, ambiguous captions |
+
+---
+
+## Manual Test Report Template
+
+**Tester:** _______________
+**Date:** _______________
+**Project:** _______________
+
+| # | Section | Test | Pass | Fail | Skip | Notes |
+|---|---------|------|:----:|:----:|:----:|-------|
+| 1.1 | SHOW WF | List all | | | | |
+| 1.2 | SHOW WF | Filter module | | | | |
+| 1.3 | SHOW WF | Empty module | | | | |
+| 2.1 | DESCRIBE | Simple | | | | |
+| 2.2 | DESCRIBE | User task | | | | |
+| 2.3 | DESCRIBE | Multi user task | | | | |
+| 2.4 | DESCRIBE | Call mf (no params) | | | | |
+| 2.5 | DESCRIBE | Call mf (with params) | | | | |
+| 2.6 | DESCRIBE | Call workflow | | | | |
+| 2.7 | DESCRIBE | Boolean decision | | | | |
+| 2.8 | DESCRIBE | Enum decision | | | | |
+| 2.9 | DESCRIBE | Parallel split | | | | |
+| 2.10 | DESCRIBE | Jump to | | | | |
+| 2.11 | DESCRIBE | Wait for timer | | | | |
+| 2.12 | DESCRIBE | Wait for notification | | | | |
+| 2.13 | DESCRIBE | Annotation | | | | |
+| 2.14 | DESCRIBE | Boundary (interrupting) | | | | |
+| 2.15 | DESCRIBE | Boundary (non-interrupting) | | | | |
+| 2.16 | DESCRIBE | Nested outcomes | | | | |
+| 2.17 | DESCRIBE | Not found | | | | |
+| 3.1 | CREATE | Minimal | | | | |
+| 3.2 | CREATE | Full syntax | | | | |
+| 3.3 | CREATE | CREATE OR REPLACE | | | | |
+| 3.4 | CREATE | Multiple activity types | | | | |
+| 3.5 | CREATE | Parallel split | | | | |
+| 3.6 | CREATE | Implicit Start/End | | | | |
+| 3.7 | CREATE | Parameter auto-binding | | | | |
+| 3.8 | CREATE | Duplicate dedup (CE0495) | | | | |
+| 3.9 | CREATE | Bool decision skip Default (CE6686) | | | | |
+| 3.10 | CREATE | Duplicate error | | | | |
+| 3.11 | CREATE | Boundary events | | | | |
+| 4.1 | DROP | Existing | | | | |
+| 4.2 | DROP | Non-existent | | | | |
+| 5.1 | ALTER | SET display | | | | |
+| 5.2 | ALTER | SET description | | | | |
+| 5.3 | ALTER | SET export level | | | | |
+| 5.4 | ALTER | SET due date | | | | |
+| 5.5 | ALTER | SET overview page | | | | |
+| 5.6 | ALTER | SET parameter | | | | |
+| 5.7 | ALTER | SET ACTIVITY page | | | | |
+| 5.8 | ALTER | SET ACTIVITY description | | | | |
+| 5.9 | ALTER | SET ACTIVITY targeting_mf | | | | |
+| 5.10 | ALTER | SET ACTIVITY targeting xpath | | | | |
+| 5.11 | ALTER | SET ACTIVITY due date | | | | |
+| 5.12 | ALTER | SET ACTIVITY @N | | | | |
+| 5.13 | ALTER | INSERT AFTER | | | | |
+| 5.14 | ALTER | INSERT AFTER @N | | | | |
+| 5.15 | ALTER | INSERT full activity def | | | | |
+| 5.16 | ALTER | DROP ACTIVITY | | | | |
+| 5.17 | ALTER | DROP ACTIVITY @N | | | | |
+| 5.18 | ALTER | REPLACE ACTIVITY | | | | |
+| 5.19 | ALTER | REPLACE ACTIVITY @N | | | | |
+| 5.20 | ALTER | INSERT OUTCOME | | | | |
+| 5.21 | ALTER | DROP OUTCOME | | | | |
+| 5.22 | ALTER | INSERT PATH | | | | |
+| 5.23 | ALTER | DROP PATH | | | | |
+| 5.24 | ALTER | INSERT BRANCH | | | | |
+| 5.25 | ALTER | DROP BRANCH | | | | |
+| 5.26 | ALTER | INSERT BOUNDARY EVENT | | | | |
+| 5.27 | ALTER | DROP BOUNDARY EVENT | | | | |
+| 5.28 | ALTER | INSERT non-interrupting BE | | | | |
+| 6.1 | ROUNDTRIP | Simple | | | | |
+| 6.2 | ROUNDTRIP | Complex | | | | |
+| 7.1 | MULTI-STEP | Add decisions | | | | |
+| 7.2 | MULTI-STEP | Add boundary events | | | | |
+| 7.3 | MULTI-STEP | Full verify | | | | |
+| 8.1 | FAILURE | Not connected | | | | |
+| 8.2 | FAILURE | Workflow not found | | | | |
+| 8.3 | FAILURE | Feature gate (pre-9.12) | | | | |
+| 8.4 | FAILURE | Activity caption not found | | | | |
+| 8.5 | FAILURE | Ambiguous caption | | | | |
+| 8.6 | FAILURE | Invalid @N | | | | |
+| 8.7 | FAILURE | DROP last outcome | | | | |
+| 8.8 | FAILURE | DROP last path | | | | |
+| 8.9 | FAILURE | INSERT AFTER non-existent | | | | |
+| 8.10 | FAILURE | Bad parameter entity | | | | |
+
+**Summary:** ___ / ___ passed | ___ failed | ___ skipped