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

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/decision-table-syntax.md

@@ -0,0 +1,115 @@
+# decisionTable — syntax
+
+Syntax rules for a `.decisionTable` model: business rules held as a table instead of as code. Each row is one rule — a set of conditions on the inputs and the outputs to produce when they hold. A flow's Decision Table step, or a decision step running in table mode, feeds the inputs and takes the outputs back.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "type": "decisionTable", "inputs": { … }, "outputs": { … }, "hitPolicy": "firstMatch", "rules": [ … ], "else": { "output": { … } } }
+```
+
+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**.
+
+The file's name is the model's name, and its folder is what other models reference it by.
+
+## Model body
+
+```json
+{ "type": "decisionTable",
+  "inputs":  { "creditScore": { "type": "number", "operator": ">=" },
+               "segment":     { "type": "string", "operator": "==" } },
+  "outputs": { "approved":   { "type": "boolean" },
+               "loanAmount": { "type": "number" } },
+  "hitPolicy": "firstMatch",
+  "rules": [
+    { "condition": { "creditScore": { "value": 700 }, "segment": { "value": "premium" } },
+      "output":    { "approved": true, "loanAmount": 100000 } },
+    { "condition": { "creditScore": { "value": 700 } },
+      "output":    { "approved": true, "loanAmount": 50000 } }
+  ],
+  "else": { "output": { "approved": false, "loanAmount": 0 } } }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `type` | yes | Always `"decisionTable"`. |
+| `inputs` | yes | The condition columns, keyed by variable name. At least one. |
+| `outputs` | yes | The result columns, keyed by variable name. At least one. |
+| `hitPolicy` | yes | `"firstMatch"`, `"collect"` or `"unique"` — what happens when more than one rule matches. |
+| `rules` | yes | The rows, in evaluation order. At least one. |
+| `else` | yes | `{ "output": { … } }` — the result when no rule matches. It has no condition side. |
+
+There is no `name`, no `description` and no store block: the model is the table and nothing else. Column names are variable names — letters, digits and underscore, no spaces, unique within the table.
+
+## Columns
+
+```json
+"inputs":  { "amount": { "type": "number", "operator": ">" } },
+"outputs": { "discount": { "type": "number" } }
+```
+
+| Field | Applies to | Rule |
+|-------|-----------|------|
+| `type` | both | `"number"`, `"string"` or `"boolean"`. Nothing else. |
+| `operator` | inputs only | The comparison every cell of that column uses. `"=="` for all three types; `">"`, `"<"`, `">="`, `"<="` for `number`. |
+
+An output column carries a `type` and nothing more — outputs are values, not comparisons.
+
+The operator belongs to the **column**, not to the cell: a rule's cell supplies only the value it is compared against, and the column decides how. A column that has to be compared two different ways is two columns.
+
+## Rules
+
+Each rule is `{ "condition": …, "output": … }`.
+
+`condition` is keyed by input name, and each entry is `{ "value": … }` written in the column's own type — a number as a number, a boolean as `true`/`false`, a string as a string. These are plain JSON values, not the `{ type, value }` expression objects other model types use.
+
+```json
+{ "condition": { "amount": { "value": 5000 }, "segment": { "value": "premium" } },
+  "output":    { "discount": 15 } }
+```
+
+- **A cell left out, or given an empty value, is not evaluated** — that criterion is simply skipped for that rule, which is how a rule tests some columns and ignores the rest. Every rule must test at least one column, though.
+- The conditions of one rule are combined with **and**: the rule matches when all of its non-empty cells hold. There is no "or" within a rule — write another rule for the alternative.
+- `output` must carry **every** output column, with a non-empty value. A rule that leaves one out is rejected on save.
+- Row order is evaluation order, and it is decided by the order of the array.
+
+### The else row
+
+```json
+"else": { "output": { "approved": false, "loanAmount": 0 } }
+```
+
+It is reached when no rule matched. It has outputs only — its condition side does not exist and the editor shows those cells disabled. Every output column must be filled here too, so a table always produces a complete result; there is no "no answer" outcome.
+
+## Hit policy
+
+| Value | Behaviour |
+|-------|-----------|
+| `firstMatch` | Evaluation stops at the first matching rule. Rules below it are never reached, so order carries the meaning: put the specific rules above the general ones. |
+| `unique` | Exactly one rule may match. A second match aborts the caller with a runtime error, which is what makes it the strict choice for rule sets that must not overlap. |
+| `collect` | Every matching rule contributes. |
+
+`collect` changes the shape of the result: each output comes back as a **list** of the values the matching rules produced, in row order, rather than as a single value. The other two return one value per output. A caller mapping a `collect` table's output into a store member declares that member as a list; one mapping a `firstMatch` or `unique` table declares it as the plain type.
+
+When nothing matches, the else row answers — and under `collect` it answers in the same list shape, as a **one-item list holding the else values**. A collecting table therefore never returns an empty list, because the else row cannot be left empty. Choose else values the caller can recognise as "nothing applied" (a code like `"NONE"`, a rate of `0`) and let the caller decide what to do with them; the empty-list behaviour some callers expect has to be produced on their side.
+
+## What blocks a save
+
+- No input columns, or no output columns.
+- No rules.
+- A rule whose condition cells are all empty.
+- A rule with an empty output cell, in any output column.
+- An empty output cell in the else row.
+- A column name that is not a valid variable name.
+
+## Easy to get wrong
+
+- **`!=` is offered but does not run.** The column dialog lists it for every type, and a table saved with it fails when a caller reaches that column: the engine has no such operator and aborts with an operator-not-found error. Express the negative case as a positive one — list the values that should match, or invert the rule and let the else row carry the rest.
+- **Editing a cell rewrites it.** A condition cell touched in the editor is written back as `{ "value": … }`, dropping anything else that was in it. Hand-authored extras on a cell survive only until someone opens that cell in Studio.
+- **The `else` row is not a rule.** It is not in `rules`, it has no conditions, and it fires only when the whole table missed. A "catch-all" written as a final rule with empty conditions is rejected instead: a rule with nothing to test does not save.
+- **Order matters under `firstMatch` and not at all under `collect`.** Moving a row changes the answer in the first case and changes only the order of the collected list in the second.
+- **Column names are the contract.** The caller maps against them by name, so renaming a column silently breaks the mapping that fed it — search the workflows and flows that use the table before renaming one.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/flow-syntax.md

@@ -0,0 +1,203 @@
+# flow — syntax
+
+Syntax rules for a `.flow` model: a Workflow Function — an autonomous, reusable function the engine runs start-to-end in one pass (scripts, service calls, DB access, decisions; no human steps). Studio editor: **Workflow Function Editor** (display name "Function"). Users know this model type as a **workflow function**.
+
+The file stores the **design-time model only**. Studio generates the runtime model automatically when the editor opens and saves the file — never author runtime shapes (`startSteps`, compiled step bodies) by hand.
+
+Per-step property reference: one file per box under [steps/](steps/). Known oddities: [quirks.md](quirks.md).
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"maxID":7,"steps":[…],"connections":[…],"store":{…},"description":"","executeType":"alive"}
+```
+
+The metadata header is identity — never edit or strip it. The body is **JSON**. There is no `name`/`_name` in the body (unlike `.workflow` and dataType/dataSet/constant bodies, which do carry them) — a flow's identity is the header `id` and its path.
+
+Pulled files additionally carry workflow-only fields (`swimlanes`, `sla`, `label`, `businessKeyGenerationFunction`, `fileUploadFunction`, `fileDownloadFunction`, `fileDeleteFunction`, `privileges`) that the editor writes back on every save — see [Workflow-only fields](#workflow-only-fields--opaque-ignore-them-entirely) for the rule.
+
+## Root fields
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `maxID` | yes | Single numeric counter shared by **steps and connections**. Every numeric `ID` in the file is below it; when adding a step or connection with a numeric id, use the current `maxID` value and increment it. |
+| `steps` | yes | Array of step envelopes (below). |
+| `connections` | yes | Array of connection objects (below). |
+| `store` | yes | The flow's variables — see [Store](#store). |
+| `description` | no | Free text, may be `""`. |
+| `executeType` | no | `"alive"` (immediate execution — the default; a missing value behaves as alive) or `"batch"` (the editor's **Scheduled Reliable Execution** checkbox: the flow is queued for delayed but guaranteed execution; its outputs never reach the caller). |
+| `uniqueKey` | with `"batch"` | Expression `{ type, value }` deduplicating queued runs. Exists only on batch flows — turning batch off removes it. in practice `"batch"` used **only by the Notify / NotifyLP flows** — author every other flow `"alive"` and don't reach for batch unless replicating that notification pattern. |
+
+### Workflow-only fields — opaque, ignore them entirely
+
+`swimlanes`, `sla`, `label`, `businessKeyGenerationFunction`, `fileUploadFunction`, `fileDownloadFunction`, `fileDeleteFunction`, `privileges` appear in pulled `.flow` files but belong to the workflow model — they leaked in because the editor's shared export writes them unconditionally, and nothing in a flow reads them. Treat them as opaque blobs:
+
+- **Absent → never add them.** The editor injects what it needs on its own save.
+- **Present → keep byte-for-byte.** Never edit, "correct", or normalize their values — whatever they contain, and however it differs from other files, it is not yours to change.
+- **Never read them** to derive behavior, and never mention them in a diff or review — they carry no meaning in a flow.
+
+## Steps
+
+```json
+{ "ID": "2", "sp": { "x": 492, "y": 263 }, "name": "code", "version": "0.8",
+  "props": { "label": "Script", "code": "…", "errors": [] } }
+```
+
+| Field | Rule |
+|-------|------|
+| `ID` | String, unique across steps. Numeric strings by default (drawn from `maxID`); steps that expose a "Step ID" field in the editor (`switch`, `subFlow`, `decisionTable`) may carry a descriptive id like `"convertCreateDate"`. Connections address steps by this id — renaming one means rewriting every connection that touches it. |
+| `sp` | Canvas position `{ x, y }` (numbers). Cosmetic to the engine, but the diagram is what a person opens — see [Layout](#layout). |
+| `name` | The step component, from the palette below. Nothing else is valid. |
+| `version` | Always `"0.8"`. |
+| `props` | Component-specific — see the step's own file. Every step has a `label` (the box caption). |
+
+### Layout
+
+Steps are drawn exactly where `sp` puts them, and the result is what a person opens. Aim for a diagram that fits on one screen and is read the way a paragraph is read: left to right, wrapping to the next line.
+
+**Spacing.** Neighbouring boxes on the same row sit **320 apart** on `x`; rows sit **200 apart** on `y`. Tighter than that and boxes touch, because a box is as wide as its contents — a `subFlow` renders the function it calls, service steps render the endpoint, and both are far wider than their caption. Start the first step around `{ "x": 200, "y": 200 }`.
+
+**Wrapping.** A row holds four or five boxes. When the chain is longer, take it back to the left `x` and continue one row down instead of extending the row — the same way text wraps. A flow that runs off to the right forces the reader to scroll to follow a single sequence, which is exactly what the diagram is supposed to spare them. Wrapping is for a straight chain; the box after a branch is not a wrap point.
+
+**Branching.** A `switch` fans its cases out to the **right** and downward: each case begins one column to the right of the switch — `switch.x + 320` — on a row of its own, and runs rightward from there. The column between the switch and its cases stays empty, which is what gives the fan room. Continue the wrapped chain only after the branches have ended or joined, and put the joining step to the right of the longest branch.
+
+Sending a branch back to the left `x` is the mistake worth naming, because the coordinates still look tidy afterwards. A connection is drawn between two ports and routes around nothing, so a target placed to the left of its source makes the line travel backwards through every box in between. Whenever a step's target sits at a smaller `x` than the step itself, the line will cross something; the only exception is the wrap of a straight chain, where the row above has already ended.
+
+**After an edit.** Inserting a step into an existing chain pushes everything after it along — including, if the row is now too long, onto the next row. Leaving the old coordinates in place is what produces overlapping boxes, and it is worth looking at the finished coordinates as a shape rather than trusting the arithmetic: rows of similar length, nothing overlapping, no lone box far from the rest.
+
+Nothing here breaks at runtime. It decides whether the next person can read the flow.
+
+### Step palette
+
+Core: [start](steps/start.md) · [end](steps/end.md) · [code](steps/code.md) (Script) · [switch](steps/switch.md) (Decision) · [subFlow](steps/subFlow.md) (Function) · [restServiceCall](steps/restServiceCall.md)
+
+Extended: [dbEntity](steps/dbEntity.md) · [decisionTable](steps/decisionTable.md) · [soapServiceCallV2](steps/soapServiceCallV2.md) · [counter](steps/counter.md) · [wait](steps/wait.md) · [s3FileUpload](steps/s3FileUpload.md) · [s3FileDownload](steps/s3FileDownload.md) · [s3FileDelete](steps/s3FileDelete.md) · [addActivity](steps/addActivity.md)
+
+Helpers: [set](steps/set.md) · [collection](steps/collection.md) — see the warning in `collection` before using anything but its `add` operation.
+
+Deprecated: [soapServiceCall](steps/soapServiceCall.md) — never author it in new flows.
+
+**Logic goes in `code` steps.** One `code` step with plain TypeScript beats a chain of [set](steps/set.md) / [counter](steps/counter.md) / [collection](steps/collection.md) helpers — reach for the helpers only when a flow already uses them.
+
+**There is no step that aborts a flow.** `end` finishes it normally and returns whatever the outputs hold. A flow that must stop because something went wrong throws instead, from the `code` step that noticed — `throw flow.createError({ … })`, with `type: "business"` for a rule the process defines and `type: "technical"` for a failure of the machinery. A genuine failure is reported by throwing, not by quietly reaching an `end` with half-filled outputs. That is about behaviour, not about wiring: the throwing step still gets its outgoing connection to an `end` like every other last box, because a path that stops mid-diagram is unreadable whether or not it was meant to fail there.
+
+## Connections
+
+```json
+{ "f": "0", "f_o": "_", "t": "2", "t_i": "_", "ID": "3" }
+```
+
+| Field | Rule |
+|-------|------|
+| `f` / `t` | Source / target step `ID`. |
+| `f_o` | Source **output port**. `"_"` for every single-output step; for a `switch` it is the **case name** (`"Else"`, `"High"`, …) and must match it character for character. |
+| `t_i` | Target input port — always `"_"`. |
+| `ID` | Unique, from the same `maxID` counter as steps. |
+
+### Graph rules
+
+- Exactly one `start`, at least one `end`; every step reachable from `start`.
+- **Every path ends at an `end` step.** Follow each branch to its last box and check that the box has an outgoing connection: a step whose output port leads nowhere leaves the diagram open, and the reader cannot tell an unfinished branch from a deliberate one. This holds even when the branch's last step always throws — throwing is how a flow reports failure, closing the path is how the diagram stays readable, and the two are separate obligations. Wire the `end` in anyway.
+- An output port may fan out into several connections — the branches run as parallel paths within the single engine pass. Join parallel branches with a [wait](steps/wait.md) step (it fires when **all** of its incoming connections have arrived).
+- A `switch` needs one outgoing connection per case, each with `f_o` set to that case's name; a case without a connection dead-ends the flow at runtime.
+
+## Store
+
+```json
+"store": {
+  "input":  { "key": { "name": "key", "type": "string", "desc": "", "list": false, "required": false,
+                        "default": { "type": "string", "value": "" } } },
+  "output": { "businessKey": { … } },
+  "vars":   { "counterValue": { "name": "counterValue", "type": "number", "desc": "", "list": false,
+                                 "required": false, "default": { "type": "number", "value": "0" } } },
+  "context": { "currentUser": { "type": "dataType", "objectID": "<<dataType:WorkflowCore/DataTypes/User>>",
+                                 "name": "currentUser", "desc": "user", "list": false, "required": true } },
+  "props": {}
+}
+```
+
+- `input` / `output` are the flow's **contract** — every caller (workflow Function step, another flow's subFlow, action binding, scheduler) maps against these names. Renaming one breaks every caller; grep for callers before touching a signature.
+- `vars` are private scratch variables. Declare intermediates here; keep `output` limited to what callers need. A flow that needs none writes `"vars": {}`; the key may also be missing entirely in older files, and neither form is worth changing.
+- `context` is where the engine-backed members sit. Its usual content is a single `currentUser` member — member name `user`, type `dataType`, `required: true`, no `default` — whose `objectID` is a reference to the app's User type in an app that has one and `""` in an app that does not. Write `"context": {}` on a new flow and Studio fills the member in for you; a flow that comes back from Studio carrying `currentUser` with an empty `objectID` is in its normal state, not a file to be corrected. Values come from the engine either way, so the declaration is what makes the member visible in the editor rather than what makes it available at runtime. Flows that receive process data may declare extra members (e.g. `dataInstance` as `any`).
+- `props` is editor-managed: `{}` and `{ "insert": ["vars", "input", "output"] }` both occur — keep whichever is there, author `{}` on new flows.
+
+### Variables
+
+Every store member is keyed by its name, and `name` inside repeats the key verbatim.
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `name` | yes | Same string as the map key. |
+| `desc` | yes | May be `""`. |
+| `type` | yes | `string \| number \| boolean \| datetime \| dataType \| dataSet \| any`. |
+| `list` | yes | `true` = array of that type. Written explicitly. |
+| `required` | yes | Written explicitly. Documentation for the caller, not a runtime check — see below. |
+| `default` | no | `{ "type": …, "value": "<string>" }`, value always a string. Only `string`, `number` and `boolean` have a literal form — `""`, `"0"`, `"false"`. Everything else, `datetime` and `any` as much as `dataType` and `dataSet`, has none and takes `{ "type": "string", "value": "" }`, which is the shape Studio leaves there. Pulled files often carry a mismatched `default.type` (see quirks); keep what you find. See below for where the field is worth writing at all. |
+| `objectID` | with `dataType`/`dataSet` | Model reference: `<<dataType:Owner/Path/Name>>` / `<<dataSet:Owner/Path/Name>>`. Required for reference types, forbidden otherwise. |
+
+Type-specific optional extras exist (`regex`, `template`, `format`, `digitLengths`, `tristate`) but the flow editor does not surface them — don't author them.
+
+What the engine actually enforces when a flow is called is the **mapping**, not `required`: every declared input must either appear in the caller's mapping or carry a `default`, and an input that has neither aborts the call with `input mapping error.'<name>' not found in given mapping.` Whatever the mapping yields is then passed through as it is — an empty string, an empty object and a missing value all arrive untouched, on a `required: true` input as much as on any other. So a flow that must reject empty input checks for it in its own `code` step and raises the error it wants; `required: true` only tells the caller the value matters.
+
+`required` and `default` are independent, not alternatives. Writing `required: true` with no `default` is the sharpest contract there is — a caller that forgets the parameter fails loudly instead of silently running on an empty value — while a `default` turns the parameter into an optional one whose omission is legal. Choose per parameter; neither field constrains the other.
+
+Where `default` earns its place is therefore the **inputs**, and only there. A `default` on an output or a local variable is inert unless its `type` matches the member's own — a `datetime` member with a `{ "type": "string", … }` default is initialised as if the field were absent — so nothing is lost by omitting it. Studio itself omits it: the store panel offers no default field, so inputs and outputs come out of the editor without one, and local variables carry it only because they are seeded with `{ "type": "string", "value": "" }` and rewritten to the matching literal when the type is `string`, `number` or `boolean`. Write a `default` when you mean "this input may be omitted"; leave the field out otherwise.
+
+## Expressions — `{ type, value }`
+
+Step props and mappings address flow data through expression objects:
+
+| `type` | Meaning | `value` |
+|--------|---------|---------|
+| `input`, `output`, `vars`, `context` | A store member. | Member name; dotted paths reach into dataType members (`"uploadedFile.created"`, `"processInstance.sla.slaDueGoal"`). |
+| `string`, `number`, `boolean` | Literal. | Always a **string** (`"false"`, `"0"`), converted at runtime. |
+| `constant` | A constant model's value. | `<<constant:Owner/Path/Name>>` reference. |
+| `literal` | A JS template literal evaluated at runtime with `flow` in scope. | E.g. `"Approved by ${flow.context.currentUser.fullName}"`. |
+| `notSet` | Explicitly empty. | `""`. |
+
+Write targets (where a step stores a result) are restricted to `output`, `vars`, `context`.
+
+Not every type is offered everywhere. `literal` belongs to step props — a label, a status text, a description that has to carry a value — and mapping rows do not take it: a caller feeding a callee's input picks a store reference, a plain literal or a constant. Each step's own file lists what its props accept.
+
+Model references are always **path references** — `<<type:Owner/Path/Name>>`, the target's path without the extension, counted from the workspace root and never shortened relative to the referencing file's own folder. Never author a guid inside `<<…>>` (guids in old pulls are legacy).
+
+## Mappings
+
+Referenced-model steps (`subFlow`, `restServiceCall`, `soapServiceCallV2`, `dbEntity`, `decisionTable`) carry a `mapping` binding the callee's contract to the caller's store:
+
+```json
+"mapping": {
+  "inParamMapping":  [ { "variable": { "type": "input",  "value": "timestamp" },
+                         "mapping":  { "type": "input",  "value": "uploadedFile.created" } } ],
+  "outParamMapping": [ { "variable": { "type": "output", "value": "convertedDate" },
+                         "mapping":  { "type": "vars",   "value": "createDate" } } ]
+}
+```
+
+- `variable` is the **callee's** parameter: always `{ "type": "input", "value": <callee input name> }` in `inParamMapping`, `{ "type": "output", "value": <callee output name> }` in `outParamMapping`.
+- `mapping` is the **caller's** side: for inputs a source (store reference, dotted path, or literal); for outputs a target (`output` / `vars` / `context`).
+- List **every** callee input and output, in the callee's declared order — the editor regenerates the rows from the callee's store. An intentionally unmapped input is `{ "type": "string", "value": "" }`; a discarded output is `{ "type": "output", "value": "" }`.
+- `restServiceCall` mappings additionally carry `"props": { "httpMethod": "GET" }`.
+
+## What blocks a save
+
+- A `code` step whose TypeScript does not compile (the editor writes the messages into the step's `errors` array and warns).
+- A `switch` case name that is empty, longer than 20 characters, or a duplicate.
+- A step `ID` rejected by the Step ID validator (empty or duplicate).
+
+Beyond that the editor is permissive — a structurally wrong file surfaces as a broken diagram or a runtime error, not a save error. Author to the shapes above.
+
+## Easy to get wrong
+
+- The runtime body is **generated** — author only the design body shown here.
+- `maxID` must stay above every numeric `ID` (steps *and* connections share it).
+- `f_o` on a switch connection is the case **name**, not the case key — renaming a case means updating its connection.
+- Store map keys and inner `name` fields must match; mappings must enumerate the full callee contract.
+- `list`, `required`, `desc` are always written out; `objectID` travels with `dataType`/`dataSet` types in both directions.
+- Literal expression values are strings, even for numbers and booleans.
+- The workflow-only root fields are opaque leftovers — never add, edit, or interpret them.
+- `sp` decides whether the diagram is readable ([Layout](#layout)): boxes 320 apart, rows 200 apart, and a long chain wrapped onto the next row rather than run off to the right.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/quirks.md

@@ -0,0 +1,35 @@
+# flow — quirks
+
+Oddities found while cross-checking pulled `.flow` models (temp/BRMCurrentAccTrxEzgi, 2026-08) against the editor step definitions (`flow/packs/flowComponents/editor`) and runtime sources. Some are fixable and will be fixed later; the rest stay here so agents authoring flows know about them. When a quirk contradicts [flow-syntax.md](flow-syntax.md), the syntax doc describes the intended shape and the quirk describes reality.
+
+## Runtime behavior traps
+
+
+- **`wait` is a join, not a timer.** It continues when all incoming connections have fired. Older docs described it as "pause for a duration/condition" — wrong.
+- **`switch` decisionTree `in`/`nin` operands are asymmetric.** `in`: left must be the array, right the value. `nin`: right must be the array, left the value. Authoring them mirrored silently yields `false`.
+- **`gt`/`gte`/`lt`/`lte` are number-only.** Non-numeric operands (including numeric strings) make the case `false` rather than erroring.
+- **`eq` is strict (`===`), `ne` is loose (`!=`).** `"5" eq 5` is false but `"5" ne 5` is also false.
+- **`code` steps have a hidden `waitTillNext` prop** (step completes on `flow.next()` / `flow.fail(err)`); it is real and used in production flows but easy to miss.
+
+## File-format inconsistencies (all shapes round-trip)
+
+- **Workflow-only root fields leak into `.flow` files** (`swimlanes`, `sla`, `label`, `businessKeyGenerationFunction`, `fileUploadFunction`, `fileDownloadFunction`, `fileDeleteFunction`, `privileges`).  Authoring rule: present → keep, absent → don't add. Fix candidate: split the export per funcType (the source already carries a TODO for exactly this split).
+- **Older pulls have extra/missing root keys**: some files carry `roles: {}` and lack `privileges`. Keep what's there; author the canonical root of flow-syntax.md for new flows.
+- **`store.props` is `{}` in pulled flows** although the editor's new-flow template writes `{ "insert": ["vars", "input", "output"] }`. Both accepted.
+- **`default.type` frequently disagrees with the variable type** (a `datetime` var with `default: { "type": "number", "value": "0" }`, a `dataType` var with `default: { "type": "string", "value": "" }`). The default is effectively unused decoration; keep the key present, don't try to "fix" existing ones.
+- **Code strings mix `\r\n` and `\n`** line endings across (and within) files. Both fine.
+
+## Editor / design-model gaps
+
+- **`errors` on `code` props is a stale cache** of the last compile — it is not revalidated until the editor reopens the step. An authored `[]` with broken code will only surface when Studio opens the model.
+- **Step IDs are only editable for `switch`, `subFlow`, `decisionTable`** (the steps with a "Step ID" field), yet any step's `ID` can be an arbitrary unique string in the file. `maxID` only tracks the numeric ones.
+- **`s3FileUpload`'s `policy` prop definition is malformed in the editor source** (`policy: { type: "free", version: "", statements: [] }` — the shape sits where `defaultValue` should be). The runtime honors `policy` fine; the editor just doesn't offer UI for it beyond what exists.
+- **`flow.getDataSet<T>` type arguments are cosmetic** — `T` names a TS interface that exists only in editor intellisense (e.g. `WFEKeys`); any identifier compiles.
+- **`switch` expression evaluation includes the Else case** ("1", empty `value`) in the loop — harmless, but it means an Else with a hand-authored non-empty `value` would actually be evaluated first and can hijack the branch. Keep Else's `value` at `""`.
+- **`set` items with an empty `variable.value`** trigger a bizarre runtime path (the value is wrapped in an object keyed by the assignee's value). Never author an item with an empty target.
+
+## Cross-model coupling
+
+- **`dbEntity.queryId` is a raw uuid** (the query's `id` inside the dataType's `persistency.queries`) while the entity itself is a path ref — deleting and recreating a query in the dataType breaks every dbEntity step pointing at it, with no editor warning.
+- **A flow's `input`/`output` names are its ABI.** Callers (workflow Function steps, subFlow steps, action bindings, schedulers) map by name with no referential integrity check — renaming a store member breaks callers silently at runtime.
+- **`restServiceCall.mapping.props.httpMethod` must be re-checked against the service model** — nothing validates that the method is still declared by the service after the service model changes.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/addActivity.md

@@ -0,0 +1,30 @@
+# addActivity (Add Activity)
+
+Writes one entry into the running process's activity history — the same list the History block on a task page shows. The entry is stamped with the acting user and the moment it was written, and is marked as coming from a flow rather than from a task action.
+
+Use it to record something the process did that no task action covers: a decision taken automatically, a document produced, an external system answered.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Add Activity"`. |
+| `descriptionCode` | yes | The entry's code — the stable identifier screens and reports match on. Expression, `string` or `literal`. |
+| `descriptionActivity` | yes | The text the entry shows. Expression, `string` or `literal`; a `literal` is the usual choice, since the sentence normally carries a value from the flow. |
+| `description` | yes | Editor-written, default `"Add Activity"`. Nothing reads it — leave it as generated. |
+
+```json
+{ "ID": "5", "sp": { "x": 520, "y": 200 }, "name": "addActivity", "version": "0.8",
+  "props": { "label": "Record approval",
+             "descriptionCode":     { "type": "string",  "value": "AUTO_APPROVED" },
+             "descriptionActivity": { "type": "literal", "value": "Talep ${flow.input.requestNumber} otomatik onaylandı." },
+             "description": "Add Activity" } }
+```
+
+## Where it works
+
+The step needs a running process instance to write to. Called from a flow that a process started, it records the entry against that instance. Called from a flow running outside a process, there is no history to write to and the step passes through without doing anything — it neither fails nor warns, so a flow that has to leave a trace in both situations logs with `flow.log` as well.
+
+The one case that does fail is a flow attached to a workflow whose process instance is not available at that moment; the step then aborts the flow rather than skipping the entry.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/code.md

@@ -0,0 +1,73 @@
+# code (Script)
+
+The workhorse: a TypeScript block executed by the engine. Panel label **Script**. Prefer one `code` step over chains of `set`/`counter`/`collection` helpers.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Script"`. `/` is stripped by the editor. |
+| `code` | yes | The TypeScript source, as one JSON string (`\n` or `\r\n` line breaks both occur). |
+| `errors` | yes | Compile diagnostics the editor wrote on last save. Author `[]`; a non-empty array means the code did not compile. |
+| `waitTillNext` | no | `true` = the step completes only when the code calls `flow.next()` (or `flow.fail(err)`) — for callback-style async work. Omit otherwise. |
+
+```json
+{ "ID": "2", "sp": { "x": 492, "y": 263 }, "name": "code", "version": "0.8",
+  "props": { "label": "Evaluate Business Key",
+             "code": "if (!flow.vars.counterValue) { throw flow.createError({ type: \"business\", category: \"error\", code: \"NO_KEY\", message: \"key missing\" }); }\nflow.output.businessKey = flow.input.key + '-' + flow.vars.counterValue;",
+             "errors": [] } }
+```
+
+## Code rules
+
+Plain top-level TypeScript. `await` works (the engine wraps execution in an async function). Never an IIFE, never a top-level `return`.
+
+The body is compiled as a function, not as a module, so there are no imports: no `import`, no `require`. A handful of names are taken away on purpose — `window`, `global` and `globalThis` resolve to an empty object, and `document`, `fetch`, `XMLHttpRequest`, `setInterval` and `navigator` are `undefined`. Log with `flow.log`, call services with service steps.
+
+Everything else the server runtime carries is still in scope, `Buffer`, `process`, `console` and `setTimeout` among them. They work, but they are the platform showing through rather than part of this API: reach for the `flow` object first, and where nothing there fits, keep the dependency small and obvious.
+
+Model reference tokens are legal inside the code string and resolve at compile time. The editor inserts them with a marker idiom — reuse it:
+
+```ts
+/*********  AUTO GENERATED LINE  *********/
+const getReportEnvironment = await flow.getConstant("<<constant:WorkflowCore/Constants/ReportEnvironment>>");
+/*********  AUTO GENERATED LINE  *********/
+```
+
+## The `flow` API
+
+| API | Notes |
+|-----|-------|
+| `flow.input.X` / `flow.output.Y` / `flow.vars.Z` | Declared store members. |
+| `flow.context.currentUser` | The acting user: `userId` (the identity to compare against), `firstName`, `lastName`, `fullName`, `unit`, `persona`, and optionally `email` and `isSystemUser`. |
+| `flow.log(…args)` | Engine logging (instead of `console`). |
+| `flow.getConstant("<<constant:…>>")` | Await; returns the constant's value. |
+| `flow.getDataSet<T>("<<dataSet:…>>")` | Await; returns the dataSet's values object. The `<T>` type argument is editor intellisense only — any name compiles. |
+| `flow.db.execute("<<dataType:…>>", "<queryName>", input, collectionName?)` | Await; runs a persistence query of the dataType by **name** (`"insertQuery"`, `"deleteQuery"`, or an authored query's name). `input` is `{ "<param>": { type, value } }` expression objects — e.g. `{ "object": { type: "vars", value: "item" } }` for inserts, `{ "_id": { type: "string", value: flow.input.x._id } }` for deletes. Read queries return the result rows. |
+| `flow.createError({ type, category, code, message })` | Builds a typed error — `throw flow.createError({ type: "business", category: "error", code: "…", message: "…" })`. Field values below. |
+| `flow.function.execute(functionId, inputs?)` | Await; call another flow programmatically (workflow context). Prefer a [subFlow](subFlow.md) step. |
+| `flow.accessmanager.getPersona(id)` | Await; access-model lookup. |
+| `flow.assignToUser(taskId, userId)` / `flow.assignToSwimlane(taskId, swimlane)` | Await; return `{ isSuccess }`. |
+| `flow.randomUUID()` | Fresh UUID. |
+| `flow.next()` / `flow.fail(err)` | Only meaningful with `waitTillNext: true`. |
+| `flow.context.type` | `"workflow"` when called from a process — guard task/file APIs with it. |
+| `flow.context.task.save()` / `.complete()` | Await; workflow context only — persist / persist-and-advance the current task. |
+| `flow.context.file.upload(…)` / `.delete(…)` | Await; workflow context only. |
+
+## Error fields
+
+`flow.createError` takes one object and returns an error to `throw`. Four fields are required and two of them are closed sets:
+
+| Field | Required | Values |
+|-------|----------|--------|
+| `type` | yes | `"business"` or `"technical"` — a rule the process defines versus a failure of the machinery. |
+| `category` | yes | `"error"` or `"warn"`. |
+| `code` | yes | Free string, the stable identifier callers and screens match on. |
+| `message` | yes | Free text shown to the user. |
+| `summary` | no | Short free text. |
+| `detail` | no | Long free text. |
+| `parameters` | no | `Record<string, string>` carried alongside the code. |
+
+Nothing else is read from the object.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/collection.md

@@ -0,0 +1,34 @@
+# collection (Collection)
+
+Operates on a list held in a store member — appending to it, emptying it, reordering it. Panel label **Collection**. The result is written back over the same member.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Collection"`. |
+| `collection` | yes | The list, and also the write target: `{ "type": "vars" \| "output", "value": <member name> }`. A member holding a single value is treated as a one-item list — including a member holding nothing yet, which becomes a list whose first entry is empty. An `output` member declared with `list: true` starts as an empty list and is safe to append to straight away; a local variable starts as nothing at all, so give it its empty list in an earlier step before the first append. |
+| `operation` | yes | `add`, `addFirst`, `remove`, `removeFirst`, `removeLast`, `clear`, `reverse`, `uniquify`. |
+| `params` | with some operations | The values the operation works on — expressions. `add` takes any number (a list argument is spread into the collection), `addFirst` and `remove` take exactly one, and the remaining five take none: omit the prop. |
+
+```json
+{ "ID": "4", "sp": { "x": 520, "y": 200 }, "name": "collection", "version": "0.8",
+  "props": { "label": "Collect error codes",
+             "collection": { "type": "vars", "value": "errorCodes" },
+             "operation": "add",
+             "params": [ { "type": "vars", "value": "currentCode" } ] } }
+```
+
+## Only `add` does what its name says
+
+The other seven operations do not survive the step: whatever they compute, execution continues through the remaining operations and the member is written back **empty**. `addFirst`, `remove`, `removeFirst`, `removeLast`, `clear`, `reverse` and `uniquify` therefore all end with an empty list, and `remove` keeps the matches rather than removing them on its way there.
+
+So this box is usable for appending and for nothing else. Anything that removes, reorders or de-duplicates belongs in a [code](code.md) step, where the list is an ordinary array:
+
+```ts
+flow.vars.errorCodes = flow.vars.errorCodes.filter(code => code !== flow.vars.currentCode);
+```
+
+The same goes for a flow you are editing: a `collection` step already sitting there with one of those operations is emptying its list on every run, whatever the label claims.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/counter.md

@@ -0,0 +1,23 @@
+# counter
+
+Persistent sequence numbers — the business-key building block. Each distinct `key` value names its own sequence; the step fetches the next number and stores it.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Counter"`. |
+| `reset` | yes | `"never" \| "daily" \| "monthly" \| "yearly"` — when the sequence restarts from 1. The restart happens on the first fetch after the boundary, compared against the previous fetch on the engine's own clock, and the number comes back bare: `1`, `2`, `17` — no padding, no year or prefix. Anything the business key needs around it is built in the following `code` step. |
+| `key` | yes | Names the sequence: `{ type: "string" \| "input" \| "context", value }`. The resolved string is the **only** thing identifying a sequence — counters live in one shared store keyed by it alone, with nothing scoping them to a flow or a model, so any two steps in the app whose keys resolve to the same string draw their numbers from the same pot. Pick a name specific enough that no other flow would land on it. |
+| `assignTo` | yes | Where the next number lands: `{ "type": "output" \| "vars", "value": <member name> }`. |
+
+```json
+{ "ID": "1", "sp": { "x": 508, "y": 447 }, "name": "counter", "version": "0.8",
+  "props": { "label": "Get Next Counter", "reset": "yearly",
+             "key":      { "type": "input", "value": "key" },
+             "assignTo": { "type": "vars",  "value": "counterValue" } } }
+```
+
+Typical use: counter → `code` step that formats the business key (prefix + year + `-` + counter) and guards against a missing value (see the `fn_BusinessKey` pattern — input `key`, output `businessKey`).

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/dbEntity.md

@@ -0,0 +1,52 @@
+# dbEntity (DB Entity)
+
+Runs a named persistence query of a **persisted** dataType model (`persistency.queries`). For queries inside a script, use `flow.db.execute` in a [code](code.md) step instead.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"DB Entity"`. |
+| `id` | yes | The entity: `<<dataType:Owner/Path/Name>>` — must be a dataType with `persistency`. |
+| `queryId` | yes | The **uuid** of the query inside the dataType's `persistency.queries` (`query.id`, not its name). Copy it from the dataType model. |
+| `mapping` | yes | Binds the query store's inputs/outputs — same shape as every mapping, no `props`. |
+
+```json
+{ "ID": "6", "sp": { "x": 506, "y": 142 }, "name": "dbEntity", "version": "0.8",
+  "props": { "label": "DB Entity",
+             "id": "<<dataType:WorkflowCore/Report/ReportEventDT>>",
+             "queryId": "310e8dd5-7e5e-1202-26d8-1b29eb73cbbc",
+             "mapping": {
+               "inParamMapping":  [ { "variable": { "type": "input", "value": "processInstanceId" },
+                                      "mapping":  { "type": "input", "value": "processInstanceId" } },
+                                    { "variable": { "type": "input", "value": "processed" },
+                                      "mapping":  { "type": "boolean", "value": "false" } },
+                                    { "variable": { "type": "input", "value": "type" },
+                                      "mapping":  { "type": "string", "value": "report" } } ],
+               "outParamMapping": [ { "variable": { "type": "output", "value": "response" },
+                                      "mapping":  { "type": "vars", "value": "existsQueueItem" } } ] } } }
+```
+
+Notes:
+
+- Input sources may be `input`/`context`/`vars` references and literals (`string`/`number`/`boolean`/`constant`) — literals are common for filter parameters. The generated `insertManyQuery` accepts only `input`/`context`/`vars` sources (its `objects` parameter is a list).
+- `queryId` is the one place a raw uuid is authored on purpose; changing the query in the dataType keeps the uuid, deleting and recreating it does not.
+- **Deleting or updating by a business key takes two steps.** The generated `deleteQuery` matches on `_id`, and `updateQuery` reads the `_id` inside the object it is given. A flow holding an order number rather than an `_id` runs a `SELECT` on that key first, checks that something came back, and passes the `_id` from the row it found. That lookup is an ordinary `SELECT` whose criteria take the key from one of its own query inputs, mapped in from the step like any other input — no custom query is involved, and a custom query would not help anyway, since those only read.
+
+## What `response` carries
+
+Every query type writes its result to the single output `response`, and what lands there depends on the query, not on how the query declares it — the declaration is `any` with `list: false` throughout, so it tells you nothing. Map `response` into a `vars` member and post-process in a [code](code.md) step; the member's own `type` and `list` are what the rest of the flow reads, so set them from this table:
+
+| Query type | `response` | Receiving member |
+|------------|-----------|------------------|
+| `SELECT`, `isMultipleResult: true` | The matching rows | `list: true` |
+| `SELECT`, `isMultipleResult: false` | The first matching row, or `null` when nothing matches | `list: false` |
+| `COUNT` | One row holding the total under `totalCount` | `list: true` — read `[0].totalCount` |
+| `CUSTOM` | The pipeline's rows | `list: true` |
+| `INSERT` | The new record's id | `list: false` |
+| `INSERT MANY` | The new records' ids, in input order | `list: true` |
+| `UPDATE`, `UPSERT`, `DELETE` | An empty object — success is the absence of an error | Map it only if you want the step to have an output at all |
+
+The step throws on any database failure, so a `code` step after it runs only on success. What it does not do is judge the result: an empty list, a `null` row and a `DELETE` that matched nothing are all ordinary outcomes, and the flow decides for itself whether they are acceptable.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/flow/steps/decisionTable.md

@@ -0,0 +1,27 @@
+# decisionTable (Decision Table)
+
+Evaluates a decision table model: feeds its inputs from the flow, writes its outputs back. No branching — for routing on table outputs use a [switch](switch.md) with `switchType: "decisionTable"`.
+
+Ports: `"_"` in, `"_"` out.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Decision Table"`. |
+| `type` | yes | Always `"referenced"`. |
+| `id` | yes | `<<decisionTable:Owner/Path/Name>>`. |
+| `mapping` | yes | One `inParamMapping` row per table input, one `outParamMapping` row per table output — [flow-syntax.md](../flow-syntax.md#mappings). |
+
+```json
+{ "ID": "4", "sp": { "x": 500, "y": 200 }, "name": "decisionTable", "version": "0.8",
+  "props": { "label": "Discount rules", "type": "referenced",
+             "id": "<<decisionTable:Owner/Tables/DiscountRules>>",
+             "mapping": {
+               "inParamMapping":  [ { "variable": { "type": "input",  "value": "amount" },
+                                      "mapping":  { "type": "vars",   "value": "amount" } } ],
+               "outParamMapping": [ { "variable": { "type": "output", "value": "discount" },
+                                      "mapping":  { "type": "output", "value": "discount" } } ] } } }
+```
+
+This step exposes a Step ID field in the editor, so descriptive step `ID`s are common here.