From 5d6f9ebcf577289121f07a5399dd9825eb8a2c34 Mon Sep 17 00:00:00 2001
From: Martin Galik <matogalik@gmail.com>
Date: Wed, 16 Sep 2026 16:48:24 +0200
Subject: [PATCH] updated fmscript skills

---
 .../references/fmscript-0.90.md               | 155 +++++++++++++-----
 1 file changed, 114 insertions(+), 41 deletions(-)

diff --git a/skills/filemaker-fmscript/references/fmscript-0.90.md b/skills/filemaker-fmscript/references/fmscript-0.90.md
index 31458b1..1971eb4 100644
--- a/skills/filemaker-fmscript/references/fmscript-0.90.md
+++ b/skills/filemaker-fmscript/references/fmscript-0.90.md
@@ -1,63 +1,136 @@
 # `.fmscript` 0.90 grammar reference
 
-Source: <https://fmscript.org/spec.html>
+Source: [https://fmscript.org/spec.html](https://fmscript.org/spec.html)
 
-This is a concise working reference to the public 0.90 grammar overview. The
-published page is not yet the complete script-step catalogue. When a particular
-step or parameter variant is uncertain, use a known-good FileMaker/ai2fm export
-or validate it with ai2fm; do not infer syntax from another step.
+This is a concise working reference to the public 0.90 grammar overview. The published page is not yet the complete script-step catalog. When a particular step or parameter variant is uncertain, use the authoritative catalog in `../examples/`, a known-good FileMaker/ai2fm export, or validation with ai2fm; do not infer syntax from another step.
 
-## Core grammar
+## Bracket Rule
 
-- Give a parameterized script step exactly one bracket group containing all of
-  its parameters.
-- Do not add brackets to a step with no parameters.
-- Separate main arguments inside the brackets with a semicolon followed by a
-  space. Do not use a comma as the main argument separator.
-- Use `# ` for a FileMaker comment step.
-- Continue the same multiline comment step with `#>`.
-- Use `// ` before a script step to represent a disabled step.
-- Preserve `//` and `/* */` comments that occur inside FileMaker calculations.
-- Qualify field references with their table occurrence, for example
-  `Customers::Name`. Do not emit a bare `::Name` reference.
-- Prefix a local variable with one `$` and a global variable with exactly `$$`.
-- Keep simple steps on one line.
-- Preserve multiline calculations and determine their boundary using the known
-  step name, balanced brackets, and continuation structure.
+Every script step that has parameters is followed by exactly one bracket group containing all parameters. Steps with no parameters have no bracket group.
 
-## Representative forms
+Valid:
 
 ```text
+Set Variable [ $x ; Value: "Hello" ]
 Show All Records
-Set Field [ Customers::Name ; "Ada" ]
-Set Variable [ $name ; Value: Customers::Name ]
-Perform Script [ Specified:From list; "Normalize Customer"; Parameter: $name ]
 ```
 
+Invalid:
+
 ```text
-# Prepare the payload
-Set Variable [ $payload ; Value: JSONSetElement (
-  "{}" ;
-  [ "id" ; Customers::ID ; JSONString ]
-) ]
+Set Variable $x = "Hello"
 ```
 
-The exact parameter labels and internal punctuation belong to the individual
-FileMaker step definition. Verify them rather than generalizing from these
-representative forms.
+## Semicolon Rule
+
+Main arguments inside brackets are separated by semicolon plus space. A comma is not a main argument separator.
+
+Valid:
+
+```text
+Set Field [ Customers::Name ; "Ada" ]
+```
+
+Invalid:
+
+```text
+Set Field [ Customers::Name , "Ada" ]
+```
+
+## Comment Rule
+
+Dedicated script comments use `# `. Disabled script steps use `// `. Multi-line comment steps continue with `#>`. Inside FileMaker calculation bodies, inline `//` and `/* */` comments are valid and must be preserved.
+
+```text
+# Explain the next operation
+# Long comment title
+#> continuation paragraph that remains part of the same comment step
+// Perform Script [ Specified:From list; "Legacy Step" ]
+Set Variable [ $x ; Value: Let ( [
+  a = 1 ; // inline calculation comment
+  b = 2  /* block calculation comment */
+] ; a + b ) ]
+```
+
+## Field Reference Rule
+
+Field references include both table occurrence and field name. Bare `::FieldName` references are invalid.
+
+Valid:
+
+```text
+Set Field [ Customers::FirstName ; "Ada" ]
+```
+
+Invalid:
+
+```text
+Set Field [ ::FirstName ; "Ada" ]
+```
+
+## Variable Rule
+
+Local variables start with one `$`. Global variables start with exactly two `$$`.
+
+Valid:
+
+```text
+Set Variable [ $counter ; Value: 1 ]
+Set Variable [ $$APP_MODE ; Value: "review" ]
+```
+
+Invalid:
+
+```text
+Set Variable [ counter ; Value: 1 ]
+```
+
+## Step Boundary Rule
+
+Simple script steps are compact, but 0.90 preserves multi-line calculation bodies and multi-line comment steps. Boundaries are determined by known step names, balanced brackets, and continuation tokens, not by blindly flattening every real-world step.
+
+```text
+Perform Script [ Specified:From list; "Parse Result"; Parameter: Get ( ActiveLayoutObjectName ) ]
+Perform Script [ Specified:From list; "Parse JSON"; Parameter: JSONSetElement (
+  "{}" ;
+  [ "id" ; Customers::ID ; JSONString ] ;
+  [ "name" ; Customers::Name ; JSONString ]
+) ]
+# Summary
+#> This paragraph continues the same FileMaker comment step.
+```
+
+## Representative syntax.
+
+The formal catalog covers the complete FileMaker step index. These examples show the public grammar style for common patterns, including 0.90 multi-line preservation.
+
+`common-patterns.fmscript` — valid
+
+```text
+Go to Layout [ "Customers" (Customers) ]
+New Record/Request
+Set Field [ Customers::FirstName ; "Ada" ]
+Set Field [ Customers::LastName ; "Lovelace" ]
+Commit Records/Requests [ With dialog: Off ]
+Perform Script [ Specified:From list; "Normalize Customer"; Parameter: JSONSetElement (
+  "{}" ;
+  [ "id" ; Customers::CustomerID ; JSONString ] ;
+  [ "fullName" ; Customers::FirstName & " " & Customers::LastName ; JSONString ]
+) ]
+If [ Get ( LastError ) = 0 ]
+  Show Custom Dialog [ "Saved"; "Customer created." ]
+End If
+```
 
 ## Review checklist
 
 - Use an exact, supported FileMaker step name.
-- Give each parameterized step one balanced outer bracket group.
+- Give each parameterized step one balanced outer bracket group and give parameterless steps no bracket group.
 - Keep calculation parentheses and internal brackets balanced.
-- Use semicolons for main arguments.
+- Use semicolon plus space for main arguments.
 - Fully qualify every field reference.
 - Use `$` and `$$` variables correctly.
-- Close every structured block with the complete matching FileMaker closing
-  step.
-- Preserve comment steps, disabled steps, and calculation comments correctly.
-- Preserve multiline calculation boundaries.
+- Close every structured block with the complete matching FileMaker closing step.
+- Preserve comment steps, disabled steps, calculation comments, and multiline calculation boundaries.
 - Apply the project's formatting, naming, path, and output-only requirements.
-- Validate uncertain or version-specific syntax through ai2fm or a known-good
-  export before describing the script as round-trip ready.
+- Validate uncertain or version-specific syntax through ai2fm or a known-good export before describing the script as round-trip ready.