docs: update documentation to reflect nanoflow implementation state

- Move JS action call and ELK layout from Future Work to Completed in proposal
- Fix stale action counts in proposal (25/32+ → actual ~16 case branches)
- Expand disallowed activities list in docs-site nanoflows.md (add DOWNLOAD FILE, REST, workflow, etc.)
- Add CALL JAVASCRIPT ACTION to docs-site calling examples
- Add CHANGELOG entries: LSP snippets, parser fixes, validation parity, DownloadFileStmt, flow cache, empty params
- Update feature matrix: nanoflow Tests column N → Y
- Document ValidateNanoflowBody/validateFlowBody and flow builder cache in parser architecture
- Add CALL JAVASCRIPT/JAVA ACTION and nanoflow restrictions to quick reference
- Update CLAUDE.md implementation status line

Author: retran

.claude/skills/mendix/write-nanoflows.md

@@ -19,7 +19,7 @@ Use this skill when:
 | **Java actions** | Supported | Not supported |
 | **JavaScript actions** | Not supported | Supported |
 | **File downloads** | Supported | Not supported |
-| **Error handling** | Full `ON ERROR` blocks | Limited |
+| **Error handling** | Full `ON ERROR` blocks | Per-action `ON ERROR` supported; `ErrorEvent` (raise error) forbidden |
 | **Offline** | Not available | Available |
 
 ## Nanoflow Structure
@@ -31,7 +31,7 @@ Use this skill when:
  * @param $Parameter1 Description
  * @returns Description of return value
  */
-CREATE [OR REPLACE] NANOFLOW Module.NAV_Name (
+CREATE [OR MODIFY] NANOFLOW Module.NAV_Name (
   $Parameter1: type
 )
 RETURNS ReturnType AS $Result
@@ -91,18 +91,19 @@ END IF;
 
 ## Disallowed Activities
 
-These will produce validation errors:
-- `RETRIEVE ... FROM Module.Entity WHERE ...` (database retrieval)
-- `COMMIT`
-- `DELETE`
-- `ROLLBACK`
-- `CALL JAVA ACTION`
-- `EXECUTE DATABASE QUERY`
-- `DOWNLOAD FILE`
-- REST calls (`CALL REST SERVICE`, `SEND REST REQUEST`)
-- Import/export mapping
-- JSON transformation
-- All workflow actions
+These will produce validation errors (12 case branches covering 22 action types in `nanoflow_validation.go`):
+- `ErrorEvent` / `RAISE ERROR` — not available in nanoflows
+- `CALL JAVA ACTION` — Java actions cannot run client-side
+- `EXECUTE DATABASE QUERY` — direct SQL requires server
+- `CALL EXTERNAL ACTION` — external actions are server-side
+- `SHOW HOME PAGE` — home page navigation is server-side
+- `CALL REST SERVICE` / `SEND REST REQUEST` — REST calls are server-side
+- `IMPORT FROM MAPPING` / `EXPORT TO MAPPING` — mapping operations are server-side
+- `TRANSFORM JSON` — JSON transformations are server-side
+- `DOWNLOAD FILE` — file downloads require server-side processing
+- All **workflow actions** (11 types: CallWorkflow, OpenWorkflow, SetTaskOutcome, OpenUserTask, etc.)
+
+**Note:** Object operations (CREATE, CHANGE, COMMIT, DELETE, RETRIEVE) ARE allowed in nanoflows — they operate in-memory on the client.
 
 ## Return Type Restrictions
 
@@ -127,20 +128,22 @@ MOVE NANOFLOW Sales.NAV_OpenCart TO FOLDER 'UI/Navigation';
 
 ## Common Mistakes
 
-1. **Using database operations** — Nanoflows cannot access the database directly. Use CALL MICROFLOW for server operations.
-2. **Using Java actions** — Use CALL JAVASCRIPT ACTION instead.
+1. **Using Java actions** — Use CALL JAVASCRIPT ACTION instead.
+2. **Using ErrorEvent** — Nanoflows cannot raise errors directly. Handle errors per-action with ON ERROR.
 3. **Expecting transactions** — Nanoflows have no rollback. Design for idempotency.
 4. **File operations** — DOWNLOAD FILE is server-only.
 5. **Binary return types** — Not supported in nanoflows.
-6. **Full error handling** — `ON ERROR { ... }` blocks are limited in nanoflows.
+6. **REST/external calls** — REST calls and external actions are server-only.
 
 ## Validation Checklist
 
-- [ ] No database operations (RETRIEVE with WHERE, COMMIT, DELETE, ROLLBACK)
+- [ ] No ErrorEvent / raise error
 - [ ] No Java action calls
-- [ ] No REST calls or external action calls
+- [ ] No REST calls, external action calls, or database queries
 - [ ] No file download operations
+- [ ] No import/export mapping or JSON transformation
 - [ ] No workflow actions
+- [ ] No show home page
 - [ ] No binary return type
 - [ ] Parameters and return types are nanoflow-compatible
 - [ ] JavaDoc documentation present

CHANGELOG.md

@@ -20,7 +20,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **Nanoflow bug fixes** — Module existence validation for SHOW NANOFLOWS/MICROFLOWS, numeric return literals no longer get spurious `$` prefix, empty nanoflow/microflow names rejected at create time, `NanoflowCallAction` error handling type resolved correctly, `not()` expression spacing preserved on roundtrip, JavaScript action call rendering in DESCRIBE output
 - **Nanoflow diff support** — `mxcli diff` now detects and displays nanoflow changes (previously silently skipped)
+- **Nanoflow validation parity** — `mxcli check` now runs full body validation on nanoflows (undeclared variables, missing returns, branch scoping) via shared `validateFlowBody` helper; `allNames()` includes nanoflows for forward-reference detection
+- **DownloadFileStmt denylist** — `DOWNLOAD FILE` added to nanoflow disallowed action list
 - **JavaScript action MDL syntax** — `call javascript action Module.ActionName(params)` now fully supported in CREATE NANOFLOW/MICROFLOW bodies: grammar, parser, builder, serializer, and roundtrip
+- **LSP snippet completions** — Added `CREATE NANOFLOW (with params)`, `CALL MICROFLOW`, `CALL NANOFLOW`, `CALL JAVASCRIPT ACTION`, `CALL JAVA ACTION` snippets
+- **Flow builder cache** — `lookupMicroflowReturnType` and `lookupNanoflowReturnType` now cache results with lazy-load bool flags, avoiding repeated `ListNanoflows`/`ListMicroflows` calls; nanoflow lookup uses `GetRawUnitByName` fast path
+- **Parser fixes** — Negative literals no longer greedily consumed by lexer (`-?` removed from `NUMBER_LITERAL`); XPath multi-predicate brackets correctly split and re-wrapped; multi-line string literals in change/create object expressions escaped; `ExclusiveSplit` (if/else) inside loop bodies now emits correct `end if;`
+- **Empty action params** — JS and Java action parameters with empty/nil values are omitted from DESCRIBE output instead of rendering as `...` or bare `= )`
 - **Association retrieve roundtrip fidelity** — `retrieve $X from $Y/Module.Association` syntax preserved on roundtrip (previously converted to `from Entity where Assoc = $Y`)
 - **DESCRIBE empty-then optimization** — If/else blocks with empty true branches are swapped and condition negated for readable output
 

CLAUDE.md

@@ -465,7 +465,7 @@ Full syntax tables for all MDL statements (microflows, pages, security, navigati
 - MPR v1/v2 reading and writing
 - Domain model (entities, attributes, associations)
 - ALTER ENTITY (add/rename/modify/drop attributes, indexes, documentation)
-- Microflows/Nanoflows with 60+ activity types
+- Microflows/Nanoflows with 60+ activity types, JavaScript action calls, nanoflow validation parity
 - Pages with 50+ widget types
 - ALTER PAGE/SNIPPET (SET, INSERT, DROP, REPLACE operations on widget trees)
 - Image widgets (IMAGE, STATICIMAGE, DYNAMICIMAGE) with Width/Height properties

docs-site/src/language/nanoflows.md

@@ -15,7 +15,7 @@ Nanoflows are client-side logic flows that execute in the user's browser or on m
 | **Close page** | Supported | Supported |
 | **Network** | Requires server round-trip | No network call (fast) |
 | **Offline** | Not available offline | Available offline |
-| **Error handling** | `ON ERROR` blocks | Limited error handling |
+| **Error handling** | `ON ERROR` blocks | Per-action `ON ERROR` (no `ErrorEvent`) |
 
 ## When to Use Which
 
@@ -36,7 +36,7 @@ Nanoflows are client-side logic flows that execute in the user's browser or on m
 ## CREATE NANOFLOW Syntax
 
 ```sql
-CREATE [OR REPLACE] NANOFLOW <Module.Name>
+CREATE [OR MODIFY] NANOFLOW <Module.Name>
   [FOLDER '<path>']
 BEGIN
   [<declarations>]
@@ -70,6 +70,9 @@ $Result = CALL NANOFLOW Sales.NAV_ValidateCart (Cart = $Cart);
 
 -- Call a microflow (triggers server round-trip)
 $ServerResult = CALL MICROFLOW Sales.ACT_SubmitOrder (Order = $Order);
+
+-- Call a JavaScript action
+$HasNetwork = CALL JAVASCRIPT ACTION NanoflowCommons.HasConnectivity();
 ```
 
 ### UI Activities
@@ -110,13 +113,18 @@ END IF;
 
 The following activities are server-only and cannot be used in nanoflows:
 
-- `RETRIEVE ... FROM Module.Entity WHERE ...` (database retrieval)
-- `COMMIT`
-- `DELETE`
-- `ROLLBACK`
-- `CALL JAVA ACTION`
-- `EXECUTE DATABASE QUERY`
-- `ON ERROR { ... }` (full error handler blocks)
+- `CALL JAVA ACTION` — Java actions cannot run client-side
+- `ErrorEvent` / `RAISE ERROR` — error events are not available in nanoflows
+- `DOWNLOAD FILE` — file downloads require server-side processing
+- `CALL REST SERVICE` / `SEND REST REQUEST` — REST calls are server-side
+- `IMPORT FROM MAPPING` / `EXPORT TO MAPPING` — mapping operations are server-side
+- `EXECUTE DATABASE QUERY` — direct SQL requires server
+- `TRANSFORM JSON` — JSON transformations are server-side
+- `SHOW HOME PAGE` — home page navigation is server-side
+- `CALL EXTERNAL ACTION` — external actions are server-side
+- All **workflow actions** (call/open workflow, set task outcome, user task, etc.)
+
+> **Note:** Per-action error handling (`on error continue`) IS supported in nanoflows. Only `ErrorEvent` (raise error as a standalone flow action) is forbidden. Note that `on error rollback` is syntactically valid but only rolls back in-memory changes — nanoflows have no database transactions.
 
 ## SHOW and DESCRIBE
 

docs/01-project/MDL_FEATURE_MATRIX.md

@@ -13,7 +13,7 @@ When adding a new MDL feature, use this matrix as a checklist to ensure complete
 | **Associations** | Y | Y | Y | N | Y | Y | 01 | Y | N | Y | Y | Y | Y | Y | Y | Y | N |
 | **Enumerations** | Y | Y | Y | Y | Y | Y | 01 | Y | Y | N | Y | Y | Y | N | Y | Y | Y |
 | **Microflows** | Y | Y | Y | Y | Y | N | 02 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **Nanoflows** | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y | Y | Y | P | N | N |
+| **Nanoflows** | Y | Y | Y | Y | Y | N | Y | Y | Y | Y | Y | Y | Y | Y | P | N | N |
 | **Pages** | Y | Y | Y | N | Y | Y | 03 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
 | **Snippets** | Y | Y | Y | N | Y | Y | 03 | Y | Y | Y | Y | Y | Y | N | Y | Y | Y |
 | **Layouts** | Y | Y | N | N | N | N | N | N | Y | Y | Y | N | Y | N | Y | N | N |
@@ -37,7 +37,7 @@ When adding a new MDL feature, use this matrix as a checklist to ensure complete
 | **Project Security** | Y | - | - | - | - | Y | 08 | Y | Y | Y | Y | Y | Y | N | N | Y | Y |
 | **Entity Access** | P | N | Y | P | Y | P | 08 | Y | N | Y | Y | Y | Y | N | N | Y | Y |
 | **Microflow Access** | Y | N | Y | P | Y | P | 08 | Y | N | Y | Y | Y | Y | N | N | Y | Y |
-| **Nanoflow Access** | Y | N | Y | P | Y | P | N | N | N | Y | Y | N | Y | N | N | N | N |
+| **Nanoflow Access** | Y | N | Y | P | Y | P | N | Y | N | Y | Y | Y | Y | N | N | N | N |
 | **Page Access** | Y | N | Y | P | Y | P | 08 | Y | N | Y | Y | Y | Y | N | N | Y | Y |
 
 ## Project Organization
@@ -124,7 +124,6 @@ These types are not covered in `help.go` output:
 
 ### Missing Skills
 
-- **Nanoflows** — Dedicated skill exists (`write-nanoflows.md`); also partially covered by microflow skill
 - **Layouts** — Read-only, no skill needed
 - **Constants** — No dedicated skill
 
@@ -134,7 +133,6 @@ These types are not covered in `help.go` output:
 
 ### Missing Examples
 
-- **Nanoflows** — No dedicated example file
 - **Layouts** — Read-only, no example needed
 - **Folders / MOVE** — No dedicated example file
 

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -207,6 +207,7 @@ authentication basic, session
 | Drop nanoflow | `drop nanoflow Module.Name;` | |
 | Create nanoflow | `create [or modify] nanoflow Module.Name (params) returns type [folder 'path'] begin ... end;` | Same body syntax as microflows |
 | Move nanoflow | `move nanoflow Module.Name to folder 'path';` | |
+| Nanoflow restrictions | N/A | No Java actions, ErrorEvent, REST calls, database queries, external actions, download file, workflow actions, import/export mappings, JSON transformation, show home page |
 
 ## Microflows - Supported Statements
 
@@ -225,6 +226,8 @@ authentication basic, session
 | Retrieve (Assoc) | `retrieve $list from $Parent/Module.AssocName;` | Retrieve by association |
 | Call microflow | `$Result = call microflow Module.Name (Param = $value);` | |
 | Call nanoflow | `$Result = call nanoflow Module.Name (Param = $value);` | |
+| Call JS action | `$Result = call javascript action Module.Name (Param = $value);` | JavaScript action (nanoflow/microflow) |
+| Call Java action | `$Result = call java action Module.Name (Param = $value);` | Java action (microflow only) |
 | Show page | `show page Module.PageName ($Param = $value);` | Also accepts `(Param: $value)` |
 | Close page | `close page;` | |
 | Download file | `download file $FileDocument [show in browser];` | Streams a `System.FileDocument` |

docs/03-development/MDL_PARSER_ARCHITECTURE.md

@@ -515,11 +515,11 @@ The `microflowValidator` struct walks the body and checks:
 4. **Variable scope** — Variables declared inside IF/ELSE branches or ON ERROR bodies cannot be referenced after the branch ends. The `checkBranchScoping()` method collects variables declared inside branches and checks if subsequent statements reference them.
 5. **Validation feedback** — VALIDATION FEEDBACK must have a non-empty message template (CE0091).
 
-This is separate from `ValidateMicroflowBody()` (in `cmd_microflows_builder.go`), which checks undeclared variable usage and runs during `--references` validation.
+This is separate from `ValidateMicroflowBody()` and `ValidateNanoflowBody()` (in `cmd_microflows_builder_validate.go`), which check undeclared variable usage and run during `--references` validation. Both delegate to the shared `validateFlowBody()` helper that accepts `[]ast.MicroflowParam` and `[]ast.MicroflowStatement`.
 
 ## Microflow Builder Architecture
 
-The microflow builder (`cmd_microflows_builder.go`) converts MDL microflow AST nodes into Mendix microflow objects. A key aspect is **variable type tracking**.
+The microflow builder (`cmd_microflows_builder.go`) converts MDL microflow AST nodes into Mendix microflow objects. A key aspect is **variable type tracking**. The `flowBuilder` also maintains `microflowsCache`/`nanoflowsCache` (with `Loaded` bool flags) for lazy-cached return type lookups, and `allNames()` includes nanoflows for forward-reference detection in multi-statement scripts.
 
 ### Variable Type Tracking (`varTypes`)
 

docs/05-mdl-specification/01-language-reference.md

@@ -629,7 +629,7 @@ Creates a microflow with activities, parameters, return type, and control flow.
 
 **Syntax:**
 ```sql
-create [or replace] microflow <qualified-name>
+create [or modify] microflow <qualified-name>
   [folder '<path>']
 begin
   [<statements>]
@@ -723,7 +723,7 @@ end;
 **Restrictions:**
 - No `ErrorEvent`, Java action calls, REST/web service calls, workflow actions, import/export mapping actions, or database queries
 - Return type cannot be `Binary`
-- Activities are the same as microflows minus server-side-only actions (see `PROPOSAL_nanoflow_support.md` for the full list of 20 disallowed action types)
+- Activities are the same as microflows minus server-side-only actions (see `PROPOSAL_nanoflow_support.md` for the full list of 22 disallowed action types)
 
 **Example:**
 ```sql
@@ -1538,6 +1538,7 @@ statement       = connect_stmt | disconnect_stmt | status_stmt
                 | create_entity_stmt | alter_entity_stmt | drop_entity_stmt
                 | create_assoc_stmt | drop_assoc_stmt
                 | create_microflow_stmt | drop_microflow_stmt
+                | create_nanoflow_stmt | drop_nanoflow_stmt
                 | create_page_stmt | alter_page_stmt | drop_page_stmt
                 | move_stmt
                 | security_stmt | grant_stmt | revoke_stmt

docs/11-proposals/PROPOSAL_nanoflow_support.md

@@ -31,9 +31,9 @@ Nanoflows execute client-side (browser or native app). In the Mendix metamodel,
 
 ### Action Restrictions
 
-**Allowed in nanoflows** (25 actions): ChangeVariable, AggregateList, CreateVariable, Rollback, Retrieve, Delete, CreateChange, Commit, Cast, Change, LogMessage, ListOperation, CreateList, ChangeList, MicroflowCall, ValidationFeedback, ShowPage, ShowMessage, CloseForm, **NanoflowCall**, **JavaScriptActionCall**, **Synchronize**, **CancelSynchronization**, **ClearFromClient**.
+**Allowed in nanoflows**: ChangeVariable, AggregateList, CreateVariable, Rollback, Retrieve, Delete, CreateChange, Commit, Cast, Change, LogMessage, ListOperation, CreateList, ChangeList, MicroflowCall, ValidationFeedback, ShowPage, ShowMessage, CloseForm, NanoflowCall, JavaScriptActionCall, Synchronize, CancelSynchronization, ClearFromClient, and others not explicitly denied.
 
-**Disallowed** (32+ actions): All Java actions, REST calls, workflow actions, import/export, external object ops, download file, push to client, show home page, email, document generation, metrics, ML model calls.
+**Disallowed** (enforced by `checkDisallowedNanoflowAction` in `nanoflow_validation.go`, 12 case branches covering 22 action types): RaiseError/ErrorEvent, JavaActionCall, RestCall, SendRestRequest, ImportFromMapping, ExportToMapping, CallExternalAction, DownloadFile, ShowHomePage, TransformJson, ExecuteDatabaseQuery, and 11 workflow action types (CallWorkflow, GetWorkflowData, GetWorkflows, GetWorkflowActivityRecords, WorkflowOperation, SetTaskOutcome, OpenUserTask, NotifyWorkflow, OpenWorkflow, LockWorkflow, UnlockWorkflow).
 
 ## Supported Commands
 
@@ -87,7 +87,7 @@ revokeNanoflowAccessStatement
 
 ## Validation Rules
 
-1. **Disallowed actions** — Type-switch rejects 21 microflow-only action types with descriptive error messages
+1. **Disallowed actions** — Type-switch rejects 12 case branches covering 22 microflow-only action types with descriptive error messages (11 workflow actions collapsed into multi-type case)
 2. **ErrorEvent forbidden** — `ErrorEvent is not allowed in nanoflows`
 3. **Binary return type rejected** — `Binary return type is not allowed in nanoflows`
 4. **Recursive validation** — Checks compound statements (IF/LOOP/WHILE bodies) and error handling blocks
@@ -118,11 +118,16 @@ revokeNanoflowAccessStatement
 | Feature | Priority | Notes |
 |---------|----------|-------|
 | Roundtrip tests with real `.mpr` baselines | P2 | CREATE → DESCRIBE → re-CREATE verification against App Gallery demos |
-| JavaScriptActionCall syntax | P2 | `call javascript action` in nanoflows |
 | SynchronizeAction | P3 | `synchronize` action for offline nanoflows |
-| ELK layout | P3 | Visual layout (low priority) |
 | Web/Native platform mixing check | P3 | CE6051 validation |
 
+### Completed (formerly Future Work)
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| JavaScriptActionCall syntax | Done | `call javascript action Module.ActionName(params)` fully supported in grammar, parser, builder, serializer, and roundtrip |
+| ELK layout | Done | `describe nanoflow --format elk` produces valid JSON layout |
+
 ## Testing
 
 Test plan: `docs/15-testing/nanoflow-test-cases.md` (19 sections, 100+ test cases covering all commands, validation, BSON round-trip, catalog, and edge cases).

docs/15-testing/nanoflow-test-cases.md

@@ -1,7 +1,7 @@
 # Nanoflow Test Cases — Manual Testing
 
 **Updated:** 2026-04-28
-**PR:** [retran/mxcli#10](https://github.com/retran/mxcli/pull/10)
+**PR:** [mendixlabs/mxcli#301](https://github.com/mendixlabs/mxcli/pull/301)
 
 ## Test Projects
 
@@ -269,7 +269,7 @@ create nanoflow NewModule.TestNano () begin end;
 
 ### 3.10 Folder placement
 ```
-create nanoflow MyModule.TestNano () in folder 'SubFolder/Nested' begin end;
+create nanoflow MyModule.TestNano () folder 'SubFolder/Nested' begin end;
 ```
 **Expected:** Nanoflow placed in correct folder.
 
@@ -295,22 +295,23 @@ Attempt CREATE without opening a project for writing.
 ### 4.1 Disallowed actions
 Each must be rejected with clear error:
 
-| # | Disallowed action |
-|---|-------------------|
-| 1 | ErrorEvent |
-| 2 | Java action call |
-| 3 | Database query |
-| 4 | REST call |
-| 5 | Web service call |
-| 6 | Import mapping |
-| 7 | Export mapping |
-| 8 | Generate document |
-| 9 | Show home page |
-| 10 | Download file |
-| 11 | External action |
-| 12 | Send external object |
-| 13 | Delete external object |
-| 14 | All workflow actions (9 types) |
+| # | Disallowed action | Notes |
+|---|-------------------|-------|
+| 1 | ErrorEvent | |
+| 2 | Java action call | |
+| 3 | Database query | |
+| 4 | REST call | |
+| 5 | Web service call | No MDL AST type — cannot be written in MDL |
+| 6 | Import mapping | |
+| 7 | Export mapping | |
+| 8 | Generate document | No MDL AST type — cannot be written in MDL |
+| 9 | Show home page | |
+| 10 | Download file | |
+| 11 | External action | |
+| 12 | Send external object | No MDL AST type — cannot be written in MDL |
+| 13 | Delete external object | No MDL AST type — cannot be written in MDL |
+| 14 | Transform JSON | |
+| 15 | All workflow actions (11 types) | |
 
 ### 4.2 Binary return type rejected
 ```