docs: add DROP FOLDER documentation, examples, and help text

- Add docs-site reference page (drop-folder.md)
- Add MDL example file (18-folder-examples.mdl)
- Update quick reference, skills, help topics, and SUMMARY
- Update create-folder.md See Also links

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

Author: ako

.claude/skills/mendix/organize-project.md

@@ -202,9 +202,26 @@ MOVE ENTITY CRM.Customer TO CustomerModule;
 MOVE ENUMERATION CRM.OrderStatus TO SharedModule;
 ```
 
+## Deleting Folders
+
+Use `DROP FOLDER` to remove empty folders. The folder must not contain any documents or sub-folders.
+
+```sql
+-- Drop an empty folder
+DROP FOLDER 'OldPages' IN MyModule;
+
+-- Drop a nested folder (only the leaf is removed)
+DROP FOLDER 'Orders/Archive' IN MyModule;
+
+-- Move contents out first, then drop
+MOVE MICROFLOW MyModule.ACT_Process TO MyModule;
+DROP FOLDER 'Processing' IN MyModule;
+```
+
 ## Validation Checklist
 
 - [ ] Folder paths use `/` separator (not `\`)
 - [ ] FOLDER keyword placement is correct (before BEGIN for microflows, inside properties for pages)
 - [ ] Cross-module moves: checked impact with `SHOW IMPACT OF` first
 - [ ] Folder naming is consistent across modules
+- [ ] DROP FOLDER: verify folder is empty before dropping

cmd/mxcli/help_topics/move.txt

@@ -57,6 +57,18 @@ EXAMPLES
   SHOW IMPACT OF OldModule.CustomerPage;
   MOVE PAGE OldModule.CustomerPage TO NewModule;
 
+DROP FOLDER
+-----------
+
+Remove an empty folder from a module:
+  DROP FOLDER 'FolderPath' IN Module;
+  DROP FOLDER 'Parent/Child' IN Module;
+
+The folder must be empty (no documents or sub-folders).
+Move contents out first if needed:
+  MOVE MICROFLOW Module.Name TO Module;
+  DROP FOLDER 'OldFolder' IN Module;
+
 FOLDERS
 -------
 

docs-site/src/SUMMARY.md

@@ -260,6 +260,7 @@
 - [Organization Statements](reference/organization/README.md)
   - [CREATE MODULE](reference/organization/create-module.md)
   - [CREATE FOLDER](reference/organization/create-folder.md)
+  - [DROP FOLDER](reference/organization/drop-folder.md)
   - [MOVE](reference/organization/move.md)
 - [Session Statements](reference/session/README.md)
   - [SET](reference/session/set.md)

docs-site/src/reference/organization/README.md

@@ -6,4 +6,5 @@ Statements for organizing project structure: creating modules and folders, and m
 |-----------|-------------|
 | [CREATE MODULE](create-module.md) | Create a new module in the project |
 | [CREATE FOLDER](create-folder.md) | Create a folder within a module for organizing documents |
+| [DROP FOLDER](drop-folder.md) | Drop an empty folder from a module |
 | [MOVE](move.md) | Move a document to a different module or folder |

docs-site/src/reference/organization/create-folder.md

@@ -58,4 +58,4 @@ CREATE PAGE MyModule.Order_Edit
 
 ## See Also
 
-[CREATE MODULE](create-module.md), [MOVE](move.md)
+[CREATE MODULE](create-module.md), [DROP FOLDER](drop-folder.md), [MOVE](move.md)

docs-site/src/reference/organization/drop-folder.md

@@ -0,0 +1,56 @@
+# DROP FOLDER
+
+## Synopsis
+
+    DROP FOLDER 'folder_path' IN module_name;
+
+## Description
+
+Removes an empty folder from a module. The folder must contain no documents (pages, microflows, etc.) and no sub-folders. If the folder is not empty, the command returns an error indicating how many child units remain.
+
+Nested folder paths use the `/` separator. Only the leaf folder is deleted; parent folders are not affected.
+
+## Parameters
+
+**folder_path**
+: The path of the folder to delete. Use `/` for nested folders (e.g., `'Orders/Processing'`).
+
+**module_name**
+: The name of the module containing the folder.
+
+## Examples
+
+### Drop a simple folder
+
+```sql
+DROP FOLDER 'OldPages' IN MyModule;
+```
+
+### Drop a nested folder
+
+```sql
+DROP FOLDER 'Orders/Archive' IN MyModule;
+```
+
+### Move contents out first, then drop
+
+```sql
+-- Move all documents to module root
+MOVE MICROFLOW MyModule.ACT_Process TO MyModule;
+MOVE PAGE MyModule.ProcessDetail TO MyModule;
+
+-- Now the folder is empty and can be dropped
+DROP FOLDER 'Processing' IN MyModule;
+```
+
+## Error Conditions
+
+| Error | Cause |
+|-------|-------|
+| `folder is not empty: contains N child unit(s)` | The folder still has documents or sub-folders |
+| `folder not found: 'path' in Module` | No folder exists at the given path in the module |
+| `module not found: Module` | The specified module does not exist |
+
+## See Also
+
+[CREATE FOLDER](create-folder.md), [CREATE MODULE](create-module.md), [MOVE](move.md)

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -178,6 +178,7 @@ AUTHENTICATION Basic, Session
 |-----------|--------|-------|
 | Microflow folder | `FOLDER 'path'` (before BEGIN) | `CREATE MICROFLOW ... FOLDER 'ACT' BEGIN ... END;` |
 | Page folder | `Folder: 'path'` (in properties) | `CREATE PAGE ... (Folder: 'Pages/Detail') { ... }` |
+| Drop folder | `DROP FOLDER 'path' IN Module;` | Folder must be empty |
 | Move to folder | `MOVE PAGE\|MICROFLOW\|SNIPPET\|NANOFLOW\|ENUMERATION Module.Name TO FOLDER 'path';` | Folders created automatically |
 | Move to module root | `MOVE PAGE Module.Name TO Module;` | Removes from folder |
 | Move across modules | `MOVE PAGE Old.Name TO NewModule;` | **Breaks by-name references** — use `SHOW IMPACT OF` first |

mdl-examples/doctype-tests/18-folder-examples.mdl

@@ -0,0 +1,78 @@
+-- ############################################################################
+-- FOLDER EXAMPLES
+-- ############################################################################
+--
+-- This file demonstrates the MDL syntax for managing project folders:
+-- creating documents in folders, moving documents between folders,
+-- and dropping empty folders.
+--
+-- Folders are created implicitly when referenced in FOLDER clauses or
+-- MOVE statements. DROP FOLDER removes empty folders explicitly.
+--
+-- Prerequisites: Assumes a module 'FolderTest' exists.
+--
+-- ############################################################################
+
+create module FolderTest;
+
+-- MARK: - Create Documents in Folders
+
+/**
+ * Level 1.1: Create a microflow in a folder (auto-creates the folder)
+ */
+CREATE MICROFLOW FolderTest.ACT_Process()
+RETURNS Boolean
+FOLDER 'Processing'
+BEGIN
+  RETURN true;
+END;
+/
+
+/**
+ * Level 1.2: Create another microflow in a nested folder
+ */
+CREATE MICROFLOW FolderTest.ACT_Archive()
+RETURNS Boolean
+FOLDER 'Processing/Archive'
+BEGIN
+  RETURN true;
+END;
+/
+
+-- MARK: - Move Documents Between Folders
+
+/**
+ * Level 2.1: Move a microflow to a different folder (auto-creates target)
+ */
+MOVE MICROFLOW FolderTest.ACT_Process TO FOLDER 'Resources';
+/
+
+/**
+ * Level 2.2: Move a microflow to module root (out of folder)
+ */
+MOVE MICROFLOW FolderTest.ACT_Archive TO FolderTest;
+/
+
+-- MARK: - Drop Folders
+
+/**
+ * Level 3.1: Drop an empty nested folder
+ */
+DROP FOLDER 'Processing/Archive' IN FolderTest;
+/
+
+/**
+ * Level 3.2: Drop the now-empty parent folder
+ */
+DROP FOLDER 'Processing' IN FolderTest;
+/
+
+/**
+ * Level 3.3: Move contents out, then drop folder
+ */
+MOVE MICROFLOW FolderTest.ACT_Process TO FolderTest;
+DROP FOLDER 'Resources' IN FolderTest;
+/
+
+-- cleanup
+drop module FolderTest;