@stechquick/studio-cli 4.2.0-0 → 4.2.0-1

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/constant-syntax.md

@@ -0,0 +1,70 @@
+# constant — syntax
+
+Syntax rules for a `.constant` model: **one** configuration value carried in a per-environment variant table — a base URL, an endpoint, a mode flag. Studio editor: **Constant Editor** (a single read-only-keyed table, one row per environment).
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"id":"…","name":"payment_endpoint","desc":"","_name":"payment_endpoint","type":"constant","constants":{…}}
+```
+
+The metadata header is identity — never edit or strip it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "name": "payment_endpoint", "desc": "", "_name": "payment_endpoint",
+  "type": "constant",
+  "constants": {
+    "int":         { "constantType": "string", "value": "https://api-int.example.com" },
+    "uat":         { "constantType": "string", "value": "https://api-uat.example.com" },
+    "prod":        { "constantType": "env",    "value": "PAYMENT_API_URL" },
+    "pre-prod":    { "constantType": "string", "value": "https://api-preprod.example.com" },
+    "livepreview": { "constantType": "string", "value": "https://api-int.example.com" } } }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id — as pulled. `""` on a model that has never reached Studio; Studio fills it. Never invent one. |
+| `name` | yes | Identical to the filename without the extension. Studio overwrites it with the model's name every time the editor opens the file — rename the model, don't edit this field. |
+| `desc` | yes | May be `""`, but the key is present. Note the spelling: `desc`, not `description`. |
+| `_name` | yes | Derived from `name`: lowercased, with separator runs collapsed and the following letter capitalized (`_` and `:` survive as-is). Studio recomputes it on every open — never hand-set a different value. |
+| `type` | yes | Always the literal `"constant"`. |
+| `constants` | yes | The environment table, keyed by environment name. |
+
+A constant body is exactly these six keys — no `attributes`, no `options`, no nesting.
+
+## constants — the environment table
+
+```json
+"int": { "constantType": "string", "value": "https://api-int.example.com" }
+```
+
+| Field | Rule |
+|-------|------|
+| key | An environment name. The default set is `int`, `uat`, `prod`, `pre-prod`, `livepreview`; an organization can configure a different list, so match the keys already present in the workspace's other constants rather than assuming. |
+| `constantType` | `"string"` (literal value) or `"env"` (read at runtime from a Docker environment variable). Nothing else. |
+| `value` | Always a JSON **string**, in both forms. For `string` it is the literal; for `env` it is the *name* of the environment variable, not its content. Numbers and booleans are written as quoted strings. |
+
+**Every environment gets an entry**, and the key set is not author-editable: the editor renders one fixed row per configured environment with no add or delete. A missing environment means that deployment has no value; an extra key is not an environment and will never be read.
+
+**One model holds one logical value.** `constants` is not a place for several settings — two values means two constant models. There is no per-environment name, description or type beyond the two fields above.
+
+ Environments may mix forms freely — a literal in `int` and an env var in `prod` is the normal pattern.
+
+## References
+
+A constant is referenced as `<<constant:…>>`, where the reference body is the target's path without the extension in a pulled workspace. It is consumed by `constant`-typed expressions (`{ "type": "constant", "value": "<<constant:…>>" }`), by service host/endpoint fields, by `constant`-typed dataType attributes (which carry the reference in their `ID` field), and by flow code that resolves the constant by reference and gets back a plain string. The environment is chosen at runtime — nothing in the reference names one.
+
+## Easy to get wrong
+
+- The field is `desc`, not `description`.
+- `_name` is derived from `name` — the two never disagree, and neither is edited by hand.
+- Under `constantType: "env"`, `value` is the variable's *name*; putting the actual value there ships the wrong string.
+- Every configured environment needs a row, including `livepreview`.
+- `value` is always a quoted string, never a bare number or boolean.
+- One constant model = one value; adding a second key under `constants` does not create a second setting.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/dataSet-syntax.md

@@ -0,0 +1,68 @@
+# dataSet — syntax
+
+Syntax rules for a `.dataSet` model: a closed list of allowed values — status values, categories, header names, any fixed option set consumed by pickers, expressions and flow code. Studio editor: **Data Set Editor**.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"id":"…","name":"Priorities","description":"","type":"set","options":["low","normal","high"]}
+```
+
+The metadata header is identity — never edit or strip it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "name": "Priorities", "description": "", "type": "set",
+  "options": ["low", "normal", "high"] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id — as pulled. `""` on a model that has never reached Studio; Studio fills it. Never invent one. |
+| `name` | yes | Identical to the filename without the extension. Studio overwrites it with the model's name every time the editor opens the file — rename the model, don't edit this field. |
+| `description` | yes | May be `""`, but the key is present. Note the spelling: `description`, not `desc`. |
+| `type` | yes | Always the literal `"set"`. |
+| `options` | yes | The values, as a JSON array of strings. |
+
+There is no `desc`, no `attributes`, no `summary` — a dataSet body is exactly these five keys.
+
+## options
+
+A JSON array of plain strings, written in display order; the editor preserves that order.
+
+```json
+"options": ["Pending-InProgress", "Pending-Approval", "Resolved-Completed"]
+```
+
+The values are a **set**: duplicates collapse silently on the next save, so two identical entries become one without warning. An empty string is an allowed value — the editor adds a new row as `""` and nothing rejects it, so an unfinished row survives into the file. The list never goes empty: the last remaining row cannot be deleted.
+
+## Changing an option
+
+An option's text is its identity. Everything that consumes the set stores and compares that exact string, and nothing is rewritten when the text changes — so renaming an option is not an edit inside this file, it is a change that runs through the workspace, and this file is only its first step. Removing one has the same reach: the value keeps living in the places that still name it.
+
+Before changing or dropping a value, find every use of the old text and update them in the same pass. It sits in a handful of predictable places:
+
+- **Query criteria on persisted dataTypes** — a rule that compares a field against the value, in both the authored rule set and the compiled filter, which have to stay in step.
+- **Expressions and conditions** that test the value, and code that compares against it by name.
+- **Pages** bound to the field, where the value may be written into a fixed option or a display label.
+
+If the search comes back empty the change is local. If it does not, those files are updated together with this one, and the change is reported as touching all of them. Adding a value reaches nothing and is always safe.
+
+## References
+
+A dataSet is referenced as `<<dataSet:…>>`, where the reference body is the target's path without the extension in a pulled workspace. It is consumed by dataType attributes typed `dataSet` (which carry the reference in `objectID`), by `dataSet`-typed expressions in mappings and conditions, and by flow code that loads the set by reference.
+
+One dataSet is bound by name rather than by reference: a set named `ProcessStatus` supplies a workflow's custom process statuses. Never rename it.
+
+## Easy to get wrong
+
+- The field is `description`, not `desc`.
+- `options` is a JSON array of strings — never an object, and never a nested `{ value: … }` wrapper.
+- `type` is the form of the model, always `"set"` — it says nothing about the datatype of the values, which are always strings.
+- Duplicate options are dropped, not reported.
+- Renaming or removing an option reaches every place that names the old text — search the workspace for it and update those files in the same change. Adding reaches nothing.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/dataType-syntax.md

@@ -0,0 +1,275 @@
+# dataType — syntax
+
+Syntax rules for a `.dataType` model: the shape of a business object — a workflow's process data, a service request/response body, a nested sub-object, or a persisted entity. Studio editor: **Data Type Editor** (tabs: Attribute, Summary, and Entity when persistence is on).
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"id":"…","type":"dataType","name":"ExpenseRequest","_name":"expenserequest","desc":"","attributes":{…},"summary":[],"keyColumn":"","labels":[]}
+```
+
+The metadata header is identity — never edit or strip it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "type": "dataType",
+  "name": "ExpenseRequest", "_name": "expenserequest", "desc": "Expense request process data",
+  "attributes": { "<key>": { …attribute } },
+  "summary": [],
+  "keyColumn": "",
+  "labels": [],
+  "persistency": { "collectionName": "…", "queries": [ …query ] } }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id — as pulled. On a model that has never reached Studio it may be `""`; Studio fills it. Never invent one. |
+| `type` | yes | Always the literal `"dataType"`. |
+| `name` | yes | Display name, UpperCamel, identical to the filename without the extension. Studio overwrites it with the model's name every time the editor opens the file — renaming happens by renaming the model, not by editing this field. |
+| `_name` | as pulled | Lowercased `name`, present in pulled models. Keep it consistent with `name`; never introduce a different value. |
+| `desc` | yes | May be `""`, but the key is always present. |
+| `attributes` | yes | Object keyed by attribute name. `{}` is valid (empty shape). |
+| `summary` | yes | Array, may be `[]`. |
+| `keyColumn` | no | String, always `""` — the editor does not expose it. |
+| `labels` | no | Array, always `[]` — the editor does not expose it. |
+| `persistency` | no | Only on persisted entities. Omit the key entirely otherwise — never `null` or `{}`. |
+
+Attribute order in the JSON is the display order in the editor, and the same holds for `summary` and for a query's `sort`. These are ordered structures; preserve the order you found.
+
+## Attributes
+
+```json
+"amount": { "name": "amount", "desc": "Amount", "type": "number",
+            "list": false, "required": false }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `name` | yes | Repeats the map key verbatim. Studio re-keys the whole map by `name` on save, so a key that differs from `name` silently moves the attribute. |
+| `desc` | yes | Human label shown in the editor and in generated forms. May be `""`. |
+| `type` | yes | From the whitelist below. |
+| `list` | yes | `true` = array of that type. Always written out, never omitted to mean `false`. |
+| `required` | yes | Always written out, and always `false` on an attribute you add — see below. |
+
+### required
+
+The Data Type Editor has no Required column: an attribute is created `false` there and the flag can never be seen or changed from that editor again. A `true` written into the file therefore survives every round-trip while being invisible and unreachable in Studio.
+
+So `required` is not where mandatory data is expressed. Write `false` on every attribute you add, and leave whatever an existing attribute already carries exactly as it is. A field that must be filled is enforced where it is used — on the form that collects it, or in the mapping of the model that consumes it — not by a flag the editor cannot show.
+
+### Naming
+
+Attribute names are short lowerCamel identifiers. The editor strips every character outside `A-Z a-z 0-9 _ - [ ] " ' . : $` and drops a leading digit, so a name written with spaces or other punctuation will not survive a round-trip. Two further hard rules: a name may not be empty, and two attributes may not share the same name.
+
+`_id` is reserved, and which way it goes depends on `persistency`:
+
+- **No `persistency`** — an attribute named `_id` is rejected outright and blocks the save.
+- **With `persistency`** — the record key lives there, as `{ "name": "_id", "desc": "_id", "type": "string", "list": false, "required": false }`. Studio adds it at the moment persistence is switched on inside the editor, but it does not go back and add it to a persistency block that arrived in the file, so writing that block means writing this attribute with it. The generated delete query takes `_id` as its input, so a persisted dataType without the attribute is inconsistent with its own queries. Never rename or retype it, and remove it only together with the whole `persistency` block.
+
+### Renaming or retyping an existing attribute
+
+The attribute's name is its address: everything that uses this dataType reaches the field through that name, and nothing rewrites those places when the name changes. So a rename is not an edit of one line — it is a change that runs through the workspace, and the model file is only its first step. Retyping reaches just as far, since the readers of the old type break while the name still resolves.
+
+Before changing the name, find every use of the old one and change them in the same pass. They sit in a handful of predictable places:
+
+- **Inside this model** — `summary` paths that name the attribute, and, on a persisted dataType, the query parts that address fields by name: `sort[].field`, `fields[].attribute`, the rules in `filterRuleSet` and the compiled `filter`.
+- **In parent models** — a dataType that references this one reaches through it with a dot path, so its `summary` may end at the renamed field.
+- **In the models that carry the data** — mappings and expressions addressing the field by dot path, and any code that reads or writes it by name.
+- **In the pages bound to it** — form fields bound to the old path.
+
+If the search comes back empty the rename is local and harmless. If it does not, the file where the name is used is updated together with this one, and the change is reported as touching all of them.
+
+### Type whitelist
+
+| `type` | Extra fields | Notes |
+|--------|--------------|-------|
+| `string` | `template?`, `regex?` | |
+| `number` | `template?`, `format?`, `digitLengths?: [int, frac]` | |
+| `boolean` | `tristate?` | |
+| `datetime` | `template?`, `format?` | |
+| `dataType` | `objectID` **required** | Reference to another dataType model. |
+| `dataSet` | `objectID` **required** | Reference to a dataSet model. |
+| `any` | — | Untyped payloads, file/blob content. |
+
+Nothing else is a valid attribute type — `object`, `data`, `date`, `int`, `text`, `enum` are all wrong. (`constant` exists in the underlying variable format but the Data Type Editor does not offer it.) When an attribute's type changes away from a reference type, `objectID` is dropped — a leftover `objectID` on a primitive is invalid, and so is `type: "dataType"` or `type: "dataSet"` without one.
+
+### References and nesting
+
+A structured sub-object is its own dataType model; the parent attribute points at it. A nested shape is never inlined.
+
+```json
+"customer": { "name": "customer", "desc": "Customer", "type": "dataType", "list": false,
+              "required": false, "objectID": "<<dataType:common/Customer>>" }
+```
+
+`objectID` is `<<dataType:…>>` / `<<dataSet:…>>`; the reference body is the target's path in the workspace without the file extension, and it must name a model that is really there — never copy a reference out of another model, because a raw model id belongs to the app it came from and resolves to nothing here. A dataType cannot reference itself: the editor excludes the current model from the picker, so no attribute may point back at its own model.
+
+`list: true` is the only way to express an array — there is no `Type[]` notation — and it applies to primitives and references alike.
+
+## summary
+
+```json
+"summary": [ { "attribute": "customer.name", "header": "Customer", "display": true } ]
+```
+
+Preview columns for task lists and notifications. `attribute` is a dot-path over the flattened shape — nested dataType attributes are reachable (`customer.name`), and the path must name an attribute that actually exists. `header` is the column title, `display` toggles the column on (new entries default to `true`). Neither `attribute` nor `header` may be empty: an entry with either blank blocks the save. 
+
+## persistency
+
+Present only on a persisted dataType. In Studio the whole block appears at once when persistence is switched on; written into the file it has to be assembled by hand, together with the `_id` attribute that belongs to it.
+
+```json
+"persistency": { "collectionName": "<Name>_<ownerId>", "queries": [ … ] }
+```
+
+`collectionName` is `<model name>_<owner id>` and is not editable afterwards. The owner id is the app's own id, which the workspace records for you: `.studio/server.json` carries it as `appId`, and every persisted model in the app repeats that same value after the underscore. Read it there — never invent one, and never leave a placeholder standing in for it. Removing the block removes persistence entirely, along with `_id` and every query in it.
+
+Five queries belong to the block and are neither editable nor removable in Studio: `insertQuery`, `insertManyQuery`, `updateQuery`, `deleteQuery`, `upsertQuery`. Only `SELECT`, `COUNT` and `CUSTOM` queries are author-added.
+
+### The five fixed queries
+
+They share one shape. `insertQuery` in full:
+
+```json
+{ "id": "<uuid>", "source": "database", "name": "insertQuery",
+  "filter": {}, "filterRuleSet": { "combinator": "and", "rules": [] },
+  "type": "INSERT",
+  "store": { "context": {},
+             "input":  { "object": { "name": "object", "desc": "", "type": "any", "list": false, "required": false,
+                                     "default": { "type": "string", "value": "" } } },
+             "output": { "response": { "name": "response", "desc": "Response", "type": "any",
+                                       "list": false, "required": false } },
+             "props":  { "insert": ["input"] } },
+  "fields": [] }
+```
+
+The other four are the same object with only these differences:
+
+| `name` | `type` | `store.input` | `store.output` |
+|--------|--------|---------------|----------------|
+| `insertManyQuery` | `INSERT MANY` | `objects` — as `object` above but `list: true` | as above |
+| `updateQuery` | `UPDATE` | `object`, identical to above | `{}` |
+| `deleteQuery` | `DELETE` | `_id` — same fields, `type: "string"` | `{}` |
+| `upsertQuery` | `UPSERT` | `object` as above, plus `filter`: `type: "string"`, `required: true` | `{}` |
+
+What each of the five expects at call time is worth spelling out, because two of them are easy to misread:
+
+- `deleteQuery` matches on `_id` and nothing else. A caller holding a business key — an order number, a dealer code — has to find the record first (a `SELECT` on that key) and pass the `_id` it found. There is no delete-by-criteria query.
+- `upsertQuery`'s `filter` is the **name of the attribute** to match on, e.g. `"dealerCode"` — not a criteria object and not JSON. The engine matches the stored record on that one attribute, taking the value from the `object` being written, then updates it or inserts it. Passing anything else there matches nothing, so every call inserts a new record instead of updating.
+- `updateQuery` requires an `_id` inside `object`; the rest of the object's fields are what gets written. Only those fields are touched — a field the object omits keeps the value it has in storage — so passing the whole record back after changing a few of its fields and passing only the changed fields both work.
+
+Nothing else belongs on these five. `customQuery`, `isMultipleResult`, `sort`, `limit` and `skip` are keys of author-added queries only; adding them here makes the block differ from what Studio maintains.
+
+### filter
+
+A query's `filter` is compiled from its `filterRuleSet`, in Mongo form:
+
+```json
+"filterRuleSet": { "combinator": "and",
+                   "rules": [ { "field": "status", "operator": "!=", "value": "Closed" } ] },
+"filter": { "$and": [ { "status": { "$ne": "Closed" } } ] }
+```
+
+`filterRuleSet` is the authored side and `filter` mirrors it, so the two always express the same condition. The compiled value is rewritten on the first save in Studio.
+
+A rule is `{ "field", "operator", "value" }`. `field` is a top-level attribute name. `operator` comes from this list and nothing else:
+
+| Operator | Meaning |
+|----------|---------|
+| `=` `!=` | equal, not equal |
+| `<` `>` `<=` `>=` | numeric and date comparisons |
+| `contains` `beginsWith` `endsWith` | substring tests |
+| `doesNotContain` `doesNotBeginWith` `doesNotEndWith` | their negations |
+| `null` `notNull` | field absent / present — `value` stays `""` |
+| `in` `notIn` | membership; `value` is a list |
+| `between` `notBetween` | range; `value` carries the two bounds |
+
+Rules sit in a group with `combinator` `"and"` or `"or"`, and a group may hold nested groups of the same shape. An empty criteria block is `{ "combinator": "and", "rules": [] }` with `filter` as `{}`.
+
+**A rule's `value` may be a parameter instead of a fixed value.** Write it as an expression object `{ "type": …, "value": … }` — normally `{ "type": "input", "value": "<query input name>" }`, naming an input declared in the query's own `store.input` — in both `filterRuleSet` and the compiled `filter`:
+
+```json
+"store": { "input": { "productCode": { "name": "productCode", "desc": "", "type": "string",
+                                       "list": false, "required": true } }, … }
+"filterRuleSet": { "combinator": "and",
+                   "rules": [ { "field": "productCode", "operator": "=",
+                                "value": { "type": "input", "value": "productCode" } } ] },
+"filter": { "$and": [ { "productCode": { "$eq": { "type": "input", "value": "productCode" } } } ] }
+```
+
+The value the caller maps into that input is substituted before the query runs, wherever it sits — including inside an `in` / `notIn` list and inside a `contains` pattern. This is how an ordinary `SELECT`, `COUNT` or `DELETE`-preparing lookup takes its search key; a `CUSTOM` query is not needed for parameters, and reaching for one to get them costs you the criteria editor for nothing.
+
+The same slot takes the other expression types too, and one of them earns its place: `{ "type": "context", "value": "currentUser.userId" }` filters rows by the person the process is running for. Permission models say what someone may do, never which rows they may see — when the requirement is "everyone sees only their own records", it is answered here, in the criteria of the query that fetches them. Context values need a running process behind the query, so a query written this way is one that flows called from a workflow use.
+
+### Author-added queries
+
+```json
+{ "id": "<uuid>", "name": "getByStatus", "source": "database", "type": "SELECT",
+  "filter": { }, "filterRuleSet": { "combinator": "and", "rules": [] },
+  "fields": [ { "type": "project", "output": "total", "attribute": "amount", "operator": "" } ],
+  "customQuery": "", "isMultipleResult": true,
+  "limit": { "type": "input", "value": "pageSize" }, "skip": { "type": "input", "value": "offset" },
+  "sort": [ { "type": "asc", "field": "createDate" } ],
+  "store": { "context": {}, "input": { }, "output": { "response": { "name": "response", "desc": "Response", "type": "any", "list": false, "required": false } },
+             "props": { "insert": ["input"] } } }
+```
+
+| Field | Rule |
+|-------|------|
+| `id` | UUID, assigned once. Keep it — it is how an edit finds the query to replace. |
+| `name` | Required, non-empty, same character rules as attribute names, unique in the model. It is what a flow's DB Entity step references. |
+| `source` | Always `"database"`. |
+| `type` | `INSERT \| INSERT MANY \| UPDATE \| DELETE \| SELECT \| COUNT \| UPSERT \| CUSTOM`. Note the space in `INSERT MANY`. Changing the type resets `filter`, `filterRuleSet`, `fields`, `customQuery`, `limit`, `skip`, `sort` and `isMultipleResult`. |
+| `store` | The query's signature: `input` is what the caller maps in, `output` what it maps back. Attributes inside follow the same syntax as the model's own. `props.insert` stays as generated. |
+| `filterRuleSet` | The authored criteria — `{ combinator: "and" \| "or", rules: [] }`, groups nested. Empty is `{ "combinator": "and", "rules": [] }`. |
+| `filter` | **Derived**: the Mongo form the editor compiles from `filterRuleSet` on save. Never hand-edit it, and never let the two disagree. |
+| `fields` | Aggregations, `{ type, output, attribute, operator? }`. `type` follows `operator`: `"group"` when an operator is set, `"project"` when it is empty. Operators are `sum`/`avg` (number or any) and `min`/`max` (number, string, datetime, boolean, any). `[]` when unused. |
+| `isMultipleResult` | `SELECT` only — the flag exists in the editor for no other type, and switching a query to `COUNT` or `CUSTOM` sets it back to `false`. `true` returns a list. A `COUNT` returns one row regardless of what this says, so leaving `true` on one is a value Studio would never write. |
+| `limit`, `skip` | `SELECT` with `isMultipleResult: true` only. Expressions of type `input` whose `value` is the name of a declared query input — dropping that input drops the limit. Omitted otherwise. |
+| `sort` | `SELECT` only. Ordered `{ "type": "asc" \| "desc", "field" }` entries. |
+| `customQuery` | `CUSTOM` only, and required there — one expression that evaluates to an aggregation pipeline, written as described below. `""` for every other type. |
+
+`filterRuleSet` rules, `fields[].attribute` and `sort[].field` all address **top-level attribute names only** — no dot-paths into nested dataTypes. With a `group` aggregation present, only aggregation `output` names are sortable.
+
+### `customQuery`
+
+A `CUSTOM` query is an aggregation pipeline the query builder could not express — a `$group` the `fields` list cannot reach, a `$lookup`, a staged filter. What you write is **one expression that produces the pipeline array**, not a script that runs it:
+
+```json
+"customQuery": "[ { \"$match\": { \"dealerCode\": store.inputs.dealerCode, \"createDate\": { \"$gte\": new Date(Date.now() - 30*24*60*60*1000) } } }, { \"$group\": { \"_id\": \"$dealerCode\", \"totalAmount\": { \"$sum\": \"$amount\" } } }, { \"$sort\": { \"totalAmount\": -1 } }, { \"$limit\": 5 } ]"
+```
+
+The rules that follow from that:
+
+- **It must evaluate to an array.** Anything else — an object, a number, a series of statements — fails the query with `Custom query must evaluate to an aggregation pipeline array.` A string that parses as a JSON array is accepted too.
+- **`store.inputs.<name>` is the only way parameters get in.** Before evaluation, each occurrence is replaced with the JSON form of the value the caller mapped into that query input, so it may sit anywhere a value belongs, including inside `$in` arrays and `$regex` strings. The input must be declared in the query's `store.input` like any other.
+- **There is no collection object, no database handle and no `await`.** The engine runs the pipeline against the model's own collection itself.
+- **Nothing is assigned to `store.outputs`.** Whatever the pipeline returns becomes the query's `response` output, always as a list of rows.
+- **It reads.** A pipeline cannot delete or update records — those go through `deleteQuery`, `updateQuery` and `upsertQuery`.
+- `filter`, `filterRuleSet`, `fields`, `sort`, `limit` and `skip` are ignored on a `CUSTOM` query; express all of it in the pipeline.
+
+The expression is evaluated as ordinary JavaScript, so `new Date(...)` and arithmetic work inside it — but keep it to building the pipeline. Anything that needs real logic belongs in the flow's `code` step, before or after the query.
+
+## What blocks a save
+
+- An attribute with an empty `name`.
+- Two attributes with the same `name`.
+- An `_id` attribute on a dataType without persistence.
+- A summary entry with an empty `attribute` or an empty `header`.
+- A query with an empty `name`, or a `CUSTOM` query with no `customQuery`.
+
+## Easy to get wrong
+
+- The map key and `name` must be the same string — Studio re-keys by `name`.
+- `list` and `required` are written explicitly, including when `false`.
+- A new attribute is always `required: false`, however mandatory the data is — the editor cannot show that flag, so it is not the place to record it.
+- Reference types and `objectID` always travel together, in both directions.
+- `persistency` is omitted, not emptied, on a non-persisted type; `keyColumn` stays `""` and `labels` stays `[]` on every type.
+- `filter` is compiled from `filterRuleSet`; editing it by hand desynchronizes the query.
+- Renaming or retyping an existing attribute reaches every mapping, expression, summary path and form binding on the old name — search the workspace for it and update those files in the same change.
+- A persisted dataType carries an `_id` attribute; a `persistency` block written without it does not get one later.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/rest-service-syntax.md

@@ -0,0 +1,190 @@
+# restService — syntax
+
+Syntax rules for a `.restService` model: one external HTTP endpoint — its base URL, method, request URL/headers/body, and the extraction of the response into store variables. Use this doc when writing a new `.restService` file or editing an existing one.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "type": "restService", "name": "GetUser", … }
+```
+
+The metadata header is identity — never edit or strip it. A file you create from scratch has no header; write the JSON body alone and Studio adds the header once the model reaches it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "type": "restService",
+  "name": "GetUser", "_name": "getuser", "desc": "",
+  "hostKey": { "type": "constant", "value": "<<constant:services/UserApiConfig>>" },
+  "contentType": "application/json",
+  "httpMethod": ["GET"],
+  "requestHeader": {},
+  "requestUrl": [ … ],
+  "requestBody": [],
+  "responseHeader": {},
+  "responseBody": [ … ],
+  "responseStatus": { "type": "output", "value": "" },
+  "mock": [],
+  "store": { "context": { … }, "input": { … }, "output": { … } },
+  "cacheRefreshPeriodInMs": 30000,
+  "cacheValidityDurationInMs": 60000,
+  "timeout": 0 }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id. Keep the pulled value; write `""` in a file you create — Studio fills it. Never invent one. |
+| `type` | yes | The literal `"restService"`. |
+| `name` | yes | Identical to the filename without the extension. Studio overwrites it with the model's name on every open, so renaming means renaming the file/model, not this field. |
+| `_name` | yes | Derived from `name`: lowercased, with separator runs collapsed and the following letter capitalized (`_` and `:` survive as-is). Write it consistent with `name`; Studio recomputes it anyway. |
+| `desc` | yes | May be `""`, but the key is present. |
+| `hostKey` | yes | The base URL, as an expression object (see below). |
+| `contentType` | no | `"application/json"` or `"application/x-www-form-urlencoded"`. Missing or empty counts as `application/json`. |
+| `httpMethod` | yes | Array of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. Several may be listed and the caller picks one; write the single method the endpoint serves unless the endpoint really serves more. `[]` leaves the service uncallable. |
+| `requestHeader` | yes | Object keyed by header name; `{}` when none. |
+| `requestUrl` | yes | Array of PATH segments and QUERY params; `[]` when the base URL is the whole URL. |
+| `requestBody` | yes | Array of body entries; `[]` for GET and DELETE. |
+| `responseHeader` | yes | Object keyed by header name; `{}` unless a header must be captured. |
+| `responseBody` | yes | Array of extraction entries. |
+| `responseStatus` | yes | Always exactly `{ "type": "output", "value": "" }`. |
+| `mock` | yes | Array of mock responses; `[]` when none. |
+| `store` | yes | `{ context, input, output }` — the service's own variables. |
+| `cacheRefreshPeriodInMs` | no | Milliseconds — see cache rules below. Omit when the response is not cached. |
+| `cacheValidityDurationInMs` | no | Milliseconds. Meaningless without a refresh period above zero. |
+| `timeout` | no | Request timeout in **milliseconds**, written as a plain number — this field takes no expression, so a value kept in a constant cannot be bound here. Omitted or `0` means the built-in default of 120000. |
+| `cachePeriod` | no | Legacy field found in older files. Leave it where it appears; never add it to a file you write. |
+
+Every key marked required is written even when empty — an absent `requestHeader` or `mock` is not equivalent to `{}` / `[]` for authoring purposes.
+
+## Expression objects
+
+Every dynamic value in the request and response sections is an object `{ "type": …, "value": … }`. The allowed `type` depends on the section:
+
+| Section | Allowed `type` |
+|---------|----------------|
+| `hostKey` | `string \| literal \| input \| constant` |
+| `requestUrl` (PATH `value`, QUERY `key` and `value`), `requestHeader` values, `requestBody` values | `string \| boolean \| input \| output \| context \| literal` |
+| `responseHeader` values, `responseBody` values | `output \| context` |
+
+- With `string` the `value` is the literal text.
+- With `input`, `output` or `context` the `value` is the name of a member of that store section. Declare the member in `store` first; a name that is not declared there resolves to nothing at runtime.
+- With `constant` the `value` is a `<<constant:…>>` reference — the reference body is the target constant's path in the workspace, without the file extension. Point it at a constant that is really there; never copy a reference out of another model, because a raw model id belongs to the app it came from and resolves to nothing here.
+
+`type` and `value` must always agree: when you change a `type`, rewrite its `value` too. A value carried over from the previous type is dead text.
+
+## requestUrl
+
+One array holds both kinds of entry, told apart by `type`:
+
+```json
+[ { "type": "PATH",  "value": { "type": "string", "value": "users" },  "required": true },
+  { "type": "PATH",  "value": { "type": "input",  "value": "userId" }, "required": true },
+  { "type": "QUERY", "key":   { "type": "string", "value": "level" },
+                     "value": { "type": "input",  "value": "level" },  "required": true } ]
+```
+
+- `PATH` entries are joined with `/` and appended to the host, in the order they appear among the PATH entries. `QUERY` entries follow as `?key=value&…`, in the order they appear among the QUERY entries. Order across the two kinds carries no meaning, so grouping all PATHs before all QUERYs is the clearest form to write.
+- `key` belongs to `QUERY` entries only and is required there; a `PATH` entry never has one.
+- `required` is written on every entry; `true` is the normal value.
+- Path segments and query key/value text may use only letters, digits and `_ - [ ] " ' . : $`, and may not start with a digit — anything else is stripped when the model round-trips through Studio.
+
+## requestHeader / responseHeader
+
+Objects keyed by the header name, each value an expression object:
+
+```json
+"requestHeader": { "Authorization": { "type": "input",   "value": "authToken" },
+                   "X-Corr-Id":     { "type": "context", "value": "currentUser.userId" } }
+```
+
+Header names are free text, but they are object keys: never write two entries with the same name (the second wins) or an entry with an empty name. Header *values* follow the character rule above.
+
+## requestBody / responseBody
+
+Both are arrays of `{ "bodyKey": …, "value": … }`.
+
+**Request** — builds the JSON body: each `bodyKey` becomes a top-level property of the payload.
+
+```json
+[ { "bodyKey": "eventType", "value": { "type": "input", "value": "eventType" } },
+  { "bodyKey": "payload",   "value": { "type": "input", "value": "payload" } } ]
+```
+
+**Response** — extracts from the JSON response into store members. `bodyKey: ""` maps the whole body; a non-empty key extracts that top-level property.
+
+```json
+[ { "bodyKey": "", "value": { "type": "output", "value": "response" } } ]
+```
+
+`bodyKey` is free text and unrestricted; the expression `value` follows the character rule above. The usual response shape is a single entry with `bodyKey: ""` writing into an output typed with the payload's dataType.
+
+## store
+
+Three sections — `context`, `input`, `output`. There is no `vars` section here. Each member is keyed by its own name:
+
+```json
+{ "context": { "currentUser": { "name": "user", "desc": "user", "type": "dataType",
+                                "objectID": "<<dataType:WorkflowCore/DataTypes/User>>",
+                                "list": false, "required": true } },
+  "input":   { "userId": { "name": "userId", "desc": "", "type": "string", "list": false, "required": true,
+                           "default": { "type": "string", "value": "" } } },
+  "output":  { "responseStatus": { "name": "responseStatus", "desc": "Response Status", "type": "number",
+                                   "list": false, "required": false,
+                                   "default": { "type": "number", "value": "0" } },
+               "response":       { "name": "response", "desc": "", "type": "dataType",
+                                   "objectID": "<<dataType:DataTypes/UserResponse>>",
+                                   "list": false, "required": false,
+                                   "default": { "type": "string", "value": "" } } } }
+```
+
+| Field | Rule |
+|-------|------|
+| `name` | Repeats the map key. |
+| `desc` | Free text, may be `""`. |
+| `type` | `string \| number \| datetime \| boolean \| dataType \| dataSet \| constant \| any`. |
+| `objectID` | Required with `dataType` and `dataSet`, and only there — a `<<dataType:…>>` / `<<dataSet:…>>` reference. |
+| `list` | `true` = array of that type. |
+| `required` | Enforced on the caller's mapping. |
+| `default` | Optional initial value, an expression object such as `{ "type": "string", "value": "" }`. |
+
+- Add members to `input` and `output` only; `context` is not extended.
+- `input` needs one member per dynamic URL, header or body value — these are the names those sections bind by, so write the store member and the binding together.
+- `output` carries `responseStatus` (number), and `responseHeader` / `responseBody` (any) as generated. A service that extracts a payload adds a member for it, typed with the payload's dataType, or `string`/`any` when the payload has no structure.
+- `context` holds at most one member, `currentUser`, and it is the section's only legal member:
+
+```json
+"context": { "currentUser": { "name": "user", "desc": "user", "type": "dataType",
+                              "objectID": "", "list": false, "required": true } }
+```
+
+  Declare it when the service binds a `context` expression — a header or body value reading `currentUser.userId` and the like. A service that never touches the acting user is complete with `"context": {}`, and stays that way: Studio does not add the member to a file that lacks it, so an empty section is not a mistake waiting to be corrected. What Studio does do is keep an existing one pointed at the right model — it matches the member name against a dataType of the same name on every open. So keep the member name `user` and leave `objectID` as you find it, empty in a new file and a dataType reference in a pulled one; an empty value fills itself and a filled one must not be repointed by hand.
+
+## Cache and timeout
+
+`cacheRefreshPeriodInMs` and `cacheValidityDurationInMs` are **milliseconds** in the file even though the editor shows seconds, so write multiples of 1000. A validity duration only counts alongside a refresh period above zero. The cache applies to GET services only, and its key is the request URL alone — two calls differing only in headers or body share a cache entry. `timeout` is independent of the cache and also in milliseconds, but unlike `hostKey` it is a bare number: no expression, no constant reference. Leaving it out is the same as `0`, which the runtime reads as 120000.
+
+## mock
+
+One entry per mocked request:
+
+```json
+[ { "reqExp": "/mock/test", "responseHeaders": {}, "responseBody": {}, "responseStatus": 200 } ]
+```
+
+`reqExp` is the request-matching expression; `responseHeaders`, `responseBody` and `responseStatus` are the canned response and the only parts a mock may set. Write `[]` when the service has no mocks.
+
+## Easy to get wrong
+
+- `name` and `_name` both follow the model's name — never diverge them, never rename through them.
+- `type` and `value` of an expression object must agree; a leftover value from another type is dead text.
+- Response-side expressions accept only `output` and `context` — `input` or `string` there never lands.
+- `key` exists on QUERY entries only; a PATH entry with a `key` is malformed.
+- PATH order matters only against other PATHs, and QUERY order only against other QUERYs.
+- Header maps are objects: duplicate or empty names silently lose data.
+- Cache values are milliseconds even though the editor shows seconds.
+- `objectID` and the `dataType`/`dataSet` member types always travel together, in both directions.
+- Every `input`/`output`/`context` binding must name a member that exists in `store`.