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

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

@@ -0,0 +1,30 @@
+# subWorkflow (Workflow)
+
+Starts another workflow as a child process and waits for it. There is no flow-side counterpart: only a process can start a process.
+
+Ports: `"_"` in, `"_"` out. The outgoing connection is followed when the child process finishes; until then this process pauses at the step and resumes where it left off, so the wait costs nothing while it lasts.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"Workflow"`. |
+| `workflowId` | yes | The child: `<<workflow:Owner/Path/Name>>`. The prop is named `workflowId`, not `id` — unlike every other referencing step. |
+| `mapping` | yes | The child's contract: one `inParamMapping` row per declared input, one `outParamMapping` row per declared output. `{ "inParamMapping": [], "outParamMapping": [] }` is what a step starts with, and it is filled in when a workflow is chosen. |
+
+```json
+{ "ID": "altSurec", "sp": { "x": 840, "y": 200 }, "name": "subWorkflow", "version": "0.8",
+  "props": { "label": "Tedarikçi Onayı",
+             "workflowId": "<<workflow:Processes/TedarikciOnayi>>",
+             "mapping": {
+               "inParamMapping":  [ { "variable": { "type": "input",  "value": "talepNo" },
+                                      "mapping":  { "type": "input",  "value": "talepNo" } } ],
+               "outParamMapping": [ { "variable": { "type": "output", "value": "sonuc" },
+                                      "mapping":  { "type": "output", "value": "onaySonucu" } } ] } } }
+```
+
+Notes:
+
+- Caller-side sources are the parent workflow's `input`, `output` and `context` members and literals; output targets are `output` and `context`. There is no `vars` bucket in a workflow.
+- Enumerate the child's whole contract, the same rule every mapping follows. Choosing a different workflow in the panel replaces the rows rather than merging them, since the two contracts have nothing to do with each other.
+- The child is a process in its own right: it has its own instance, its own tasks and its own status, and it appears in the process list separately. Use it when the work has a life of its own; use a [subFlow](subFlow.md) when it is a computation the parent needs done.

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

@@ -0,0 +1,7 @@
+# switch (Decision)
+
+The same component the flow editor offers, registered in the workflow palette unchanged. Its props, its three variants and its case rules are in [the flow step's file](../../flow/steps/switch.md) — read them there; nothing about the authored shape differs here.
+
+What differs is only where it can run: a workflow `switch` needs the process engine, so the step exists to route a **process**, not a standalone function. Everything else — the `"1"` key always being Else, one outgoing connection per case, the connection's `f_o` matching the case name character for character — carries over as written.
+
+Conditions read the workflow's own store: `input`, `output` and `context`, the last being where the process instance, the business data and the last action sit. A decision on which button the user pressed compares `context.action.actionId` against the bare item id (`"Complete"`), never against the full action reference.

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

@@ -0,0 +1,71 @@
+# User Task
+
+The step that stops the process and waits for a person. Its `name` in the model file is `humantask` — the panel calls it **User Task**, and that is the name used from here on. It names the screen the user sees, the buttons they can press, who the work goes to, and what the process is called while it sits there. There is no flow-side counterpart.
+
+Ports: `"_"` in, `"_"` out — the outgoing connection is followed once the task is completed. Which action the user pressed is read afterwards from `context.action.actionId`, usually by a `switch`.
+
+## Props
+
+| Prop | Required | Rule |
+|------|----------|------|
+| `label` | yes | Box caption, default `"User Task"`. This is the task name users see in their lists. |
+| `procesStatus` | yes | The status the **process** carries while this task is open. Chosen from the app's **ProcessStatus** dataSet entries, or `"Others"` to compose one. `""` leaves the process's status untouched. Note the single `s`. |
+| `procesStatusLiteral` | yes | `""` unless `procesStatus` is `"Others"`, in which case it carries the status text, evaluated as a template. |
+| `taskStatus` | yes | Editor-written, `""`. The panel offers no field for it — leave it as generated. |
+| `priority` | yes | Task priority, default `10`. The panel offers no field for it either; it is dropped from the step the moment an SLA model is attached, since the SLA then drives priority. |
+| `form` | yes | The screen: `{ "id": { "type": …, "value": … }, "readonly": false }`. |
+| `actions` | yes | The buttons, as a numbered map — see below. `{}` means a task with no actions, which nothing can complete. |
+| `sendTo` | yes | `"swimlane"` (default) or `"user"` — which of the two assignment props applies. |
+| `swimlane` | with `sendTo: "swimlane"` | `{ "type": "swimlane" \| "context" \| "constant", "value": … }`. With `"swimlane"` the value is a lane reference; the other two resolve the lane at runtime. |
+| `user` | with `sendTo: "user"` | `{ "type": "context" \| "constant" \| "literal", "value": … }` — the user id the task goes to. Switching assignment back to a lane removes this prop. |
+| `sla` | yes | `{ "selectedSlaModelId": … }`, plus a `mapping` once a model is chosen. `{ "selectedSlaModelId": "" }` means no SLA. |
+| `stepIdToShow` | yes | Repeats the step's own `ID`. The panel's **Step ID** field writes both, so workflow tasks carry descriptive ids like `"onayBekliyor"` rather than numbers — keep the two in agreement. |
+
+```json
+{ "ID": "onayBekliyor", "sp": { "x": 520, "y": 200 }, "name": "humantask", "version": "0.8",
+  "props": { "label": "Onay Bekliyor",
+             "procesStatus": "InProgress-Approval", "procesStatusLiteral": "", "taskStatus": "",
+             "priority": 10,
+             "form": { "id": { "type": "string", "value": "<<qjson:Pages/OnayEkrani>>" }, "readonly": false },
+             "actions": { "0": { "actionId": "<<action:Actions/TaskActions>>:Approve", "label": "Onayla" },
+                          "1": { "actionId": "<<action:Actions/TaskActions>>:Reject", "label": "Reddet",
+                                 "visibilityRule": "flow.context.dataInstance.tutar > 1000" } },
+             "sendTo": "swimlane",
+             "swimlane": { "type": "swimlane", "value": "<<swimlane:Access/Swimlanes>>:Yonetici" },
+             "sla": { "selectedSlaModelId": "<<sla:SLAs/OnaySLA>>" },
+             "stepIdToShow": "onayBekliyor" } }
+```
+
+## The form
+
+`form.id` names the screen. Its `type` decides how:
+
+- `"string"` — a page reference, `<<qjson:Path/PageName>>`. This is the normal case.
+- `"literal"` — a template evaluated at runtime, for a task that shows different screens depending on the data. Changing the source between the two clears the value; they are not interchangeable.
+
+`readonly: true` opens the screen without letting the user change anything — a review step rather than a data-entry one.
+
+## The actions
+
+`actions` is a map keyed by position — `"0"`, `"1"`, `"2"` — and the order is what the buttons appear in. Each entry:
+
+| Field | Rule |
+|-------|------|
+| `actionId` | Required. `<<action:Model>>:ItemId` — the container reference plus the item's id. At runtime `context.action.actionId` carries the bare id (`"Approve"`), so that is what decisions compare against. |
+| `label` | The button caption. Omitted, the action's own label is used. |
+| `visibilityRule` | A condition deciding whether the button is shown at all. |
+| `uniqueKeys` | Free labels that stop one person from acting twice in the same process. When a user completes this action, the engine remembers the keys it carried; if a **later** task offers an action sharing any of those keys, that same user is refused it — with a business error, not a hidden filter. Two-level approvals where the second approver must be someone else are exactly this: give both approval actions a shared key such as `["onay"]`. Leave it out when repeat action by the same person is fine. |
+
+A task whose `actions` is empty is a dead end: nothing can complete it and the process waits there forever.
+
+## Assignment
+
+Exactly one of the two applies, and `sendTo` says which. Assigning to a **lane** is the usual choice — the task goes to whoever holds that role, and the lane may be named directly, taken from process data, or read from a constant. Assigning to a **user** puts it in one person's queue, addressed by user id; that is for tasks the process routes to a specific person it knows, such as the originator.
+
+**There is no unassigned task.** Whichever mode you pick, the value has to resolve at runtime or the process fails right there: an empty user expression aborts with a target-user-not-found error, and an empty lane value aborts with "Swimlane expression resolved to empty value" — a lane naming a lane that no swimlane model actually holds fails the same way. So a process whose app has no access models yet cannot park a task with `"swimlane": { "type": "swimlane", "value": "" }` and sort it out later; route it to a user expression the engine can resolve — `processInstance.initiatorUser.userId` is the one that always exists — until the lane exists.
+
+The lane reference is also the one place where the authored form and the runtime form differ. Author the ordinary item reference, `<<swimlane:Owner/Path/Model>>:laneId`; the editor's own picker writes a longer form that additionally carries the app, and a file that already holds that form is correct — leave it as you find it.
+
+## SLA
+
+Attaching an SLA model gives the task its goal, deadline and critical milestones and takes over its priority. The `mapping` alongside the model reference feeds the SLA's own inputs from the workflow's store, in the same form every mapping uses. Leave `{ "selectedSlaModelId": "" }` on tasks that are not timed.

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

@@ -0,0 +1,218 @@
+# workflow — syntax
+
+Syntax rules for a `.workflow` model: a **business process** — a long-running graph of human tasks, decisions and function calls that the workflow engine drives across users. One `.workflow` is one process definition; every start creates a **process instance** that lives, with its own data, tasks, SLA clocks and history, until it reaches an `end` step. Studio editor: **Workflow Editor** (display name "Workflow").
+
+Contrast `.flow` ([../flow/flow-syntax.md](../flow/flow-syntax.md)): a flow is an autonomous function the engine runs start-to-end in one pass; a workflow *waits* — on people, actions and SLAs — and calls flows for its logic.
+
+The file stores the **design-time model only** (body key `workflow-design`). Studio regenerates the runtime body (`workflow-runtime`: `startSteps`, step records keyed `{N,V,P,I,O}`, no connections array) from it on every save — never author runtime shapes by hand.
+
+This file covers the model's overall structure and its reference system. Step `props` are component-specific and documented per step, one file per box — this manual deliberately does not describe them.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: /
+---studio-metadata DO NOT EDIT---
+{
+ "maxID":16,"name":"ExampleWorkflow","_name":"exampleworkflow",
+ "steps":[…],
+ "connections":[…],
+ "swimlanes":{},
+ "store":{…},
+ "sla":{…},
+ "label":{…},
+ "description":"",
+ "businessKeyGenerationFunction":{…},
+ "fileUploadFunction":{…},
+ "fileDownloadFunction":{…},
+ "fileDeleteFunction":{…},
+ "privileges":[…],
+ "executeType":"alive"
+ }
+```
+
+- The metadata header is identity — never edit, reorder or strip it. A file you create from scratch has none; Studio adds it when the model reaches it.
+- The body is **JSON** (tab-indented on pull).
+- Unlike a `.flow`, the body carries `name` and `_name` — but Studio overwrites both on every open (`name` ← the model's name in the tree, `_name` ← camelized `name`), so keep `name` identical to the file name and put no meaning in either.
+
+## 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 value and increment it. |
+| `name` / `_name` | yes | Model name and its camelized form. Regenerated from the file name on every open — keep `name` equal to the file name. |
+| `steps` | yes | Array of step envelopes (below). |
+| `connections` | yes | Array of connection objects (below). |
+| `swimlanes` | no | **Legacy** leave as it is |
+| `store` | yes | The process's variables and context — see [Store](#store). |
+| `sla` | yes | Process-level SLA: `{ "selectedSlaModelId": "<<sla:…>>", "mapping": { "inParamMapping": […], "outParamMapping": [] } }`. Applied once at start: it stamps the instance's goal/deadline/critical due dates and priority, and schedules escalation for the whole instance. Only `inParamMapping` is ever read — leave `outParamMapping` empty. Unset = `{ "selectedSlaModelId": "" }`. (Human-task steps carry their own per-task `sla` of the same shape.) |
+| `label` | yes | `{ "type": "string", "value": "<process name>" }` — the human-facing **process name** shown on process-instance lists and worklists (the editor's PROCESS NAME field). Empty value → Studio resets it to the model name. Trimmed on save. |
+| `description` | no | Free text, may be `""`. Not consumed at runtime. |
+| `businessKeyGenerationFunction` | yes | Referenced flow that produces the instance's **business key** (the domain-level unique id, distinct from the technical `processInstanceId`) — see [Process-level functions](#process-level-functions). With an empty `id`, the caller of process start must supply the business key instead; a start without any business key fails. |
+| `fileUploadFunction` / `fileDownloadFunction` / `fileDeleteFunction` | no | **Legacy** leave as it is |
+| `privileges` | no | Array of `"<<privilege:Model>>:PrivilegeId"` item references gating **who may start** the process. **AND semantics** — the starting user must hold every listed privilege. Empty or absent = everyone may start. (Per-action and per-form privileges live on the action model and the qjson page, not here.) |
+| `executeType` | yes | Always `"alive"`. Workflows cannot be batch — the engine starts them in must-be-alive mode and a hand-edited `"batch"` throws at start. |
+
+Never author: `roles` (legacy root map — fresh saves don't emit it), `uniqueKey` (batch-only; a workflow is never batch, so it never appears).
+
+## References
+
+Everything a workflow touches — flows, screens, SLAs, data types, actions, swimlanes, privileges — it touches through the `<<…>>` reference syntax.
+
+### The grammar
+
+- **Model reference:** `<<type:target>>` — `type` is the target's model type (= its file extension), `target` is its **path from the workspace root**: `[module/]folder…/name`, forward slashes, **no extension**. Never relative to the referencing file's own folder: a model in `hr/Access/` referencing its neighbour still writes the whole path, `<<role:hr/Access/Roles>>`, not `<<role:Access/Roles>>`. `<<flow:WorkflowCore/Functions/BusinessKeyGenerator>>` points at `BusinessKeyGenerator.flow` under the `WorkflowCore` module; `<<qjson:Pages/BilgiGirisEkrani>>` at an app-local page.
+- **Item reference:** `<<type:Model>>:ItemId` — addresses one named item **inside** a container model. Only the access/action container types support it: `action`, `swimlane`, `privilege` (and `role`, `persona`). The suffix after `>>` is the item's `id` in the container's list; it is never rewritten (only the part inside `<<…>>` is).
+- The path form is the authored, on-disk form. Inside a live Studio app the same slot holds the model's id; pull/push convert between the two. **Never author an id inside `<<…>>`** — ids in old pulls are legacy, leave them alone, and never copy a reference out of another app's model.
+- **A reference works only in the fields defined to take one** (the table below) — written anywhere else it does nothing. Studio's dependency scan cannot tell the difference, though: it stringifies the whole body and regex-scans it for `<<type:…>>`, so a ref-shaped string inside a label or description creates a phantom dependency on a model nothing uses (and is rewritten on pull/push like a real reference). In free text, name models in plain words.
+
+### What a workflow references, and where
+
+| Reference | Written at | Target |
+|-----------|-----------|--------|
+| `<<flow:…>>` | subFlow step `props.id`; root `businessKeyGenerationFunction.id` and the three file function `id`s | A `.flow` workflow function. |
+| `<<workflow:…>>` | subWorkflow step `props.workflowId` | Another `.workflow` started as a child process. |
+| `<<qjson:…>>` | human-task `props.form.id` | The screen the task shows. |
+| `<<sla:…>>` | root `sla.selectedSlaModelId`; human-task `props.sla.selectedSlaModelId` | An `.sla` model (goal/deadline/critical milestones + escalation). |
+| `<<dataType:…>>` | `store` variable `objectID`s | A `.dataType` — including `context.dataInstance`'s business data shape and the engine-backed `ProcessInstance`/`User` types. |
+| `<<dataSet:…>>` | `store` variable `objectID` for `dataSet`-typed variables | A `.dataSet` closed value list. |
+| `<<constant:…>>` | expression values with `"type": "constant"` | A `.constant`. |
+| `<<action:Model>>:Id` | human-task `props.actions[n].actionId` | One action item (`id`, e.g. `Complete`) in a `.action` model's `actions` array. |
+| `<<swimlane:Model>>:Id` | human-task `props.swimlane.value` | One lane (`id`, which is also its display name) in a `.swimlane` model's `swimlanes` array. |
+| `<<privilege:Model>>:Id` | root `privileges[]` | One privilege item (`id`) in a `.privilege` model's `privileges` array. |
+
+Two things that trip people up:
+
+- **The item suffix is an id, not a ref.** At runtime `context.action.actionId` carries the bare item id — decision steps compare it against `"Complete"`, never against the full `<<action:…>>:Complete` string.
+- **Item ids are load-bearing.** App-local container models (`.action`, `.swimlane`, `.privilege`, `.role`, `.persona`) are editable files like any other — check out, edit, push. Ones owned by an **imported module** follow the module rules instead: read-only, never edited from here. And renaming or removing an item inside a container silently breaks every `<<…>>:ItemId` suffix that names it: rename cascades rewrite only the `<<…>>` part of a reference, never the suffix. Search the workspace for the item id before changing one.
+
+## Steps
+
+```json
+{ "ID": "2", "sp": { "x": 387, "y": 276.4 }, "name": "humantask", "version": "0.8", "props": { "label": "Bilgi Girişi", … } }
+```
+
+| Field | Rule |
+|-------|------|
+| `ID` | String, unique across steps. Numeric strings drawn from `maxID`. Connections address steps by this id — renaming one means rewriting every connection that touches it. |
+| `sp` | Canvas position `{ x, y }` (numbers, floats fine). Cosmetic only; lay steps out so the diagram reads top-to-bottom or left-to-right. |
+| `name` | The step component: [start](steps/start.md) · [end](steps/end.md) · [humantask](steps/usertask.md) (User Task) · [switch](steps/switch.md) (Decision) · [subFlow](steps/subFlow.md) (Function) · [subWorkflow](steps/subWorkflow.md). Nothing else is valid in a workflow. |
+| `version` | Always `"0.8"`. |
+| `props` | Component-specific — see the step's own file. Every step has a `label` (the box caption). |
+
+Graph rules: exactly one `start`, at least one `end`, every step reachable from `start`.
+
+## Connections
+
+```json
+{ "f": "2", "f_o": "_", "t": "4", "t_i": "_", "ID": "8" }
+```
+
+| 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** (`"Default"`, `"İptal Edilmedi Kontrolü"`, …) and must match it character for character — renaming a case means rewiring its connection. |
+| `t_i` | Target input port — always `"_"`. |
+| `ID` | Unique, from the same `maxID` counter as steps. |
+
+A connection whose endpoints don't both exist is silently dropped on save. A `switch` needs one outgoing connection per case; a case without one dead-ends the process.
+
+## Store
+
+The workflow store has three buckets plus editor props — **no `vars`** (that bucket belongs to flows):
+
+```json
+"store": {
+  "input":  {},
+  "output": {},
+  "context": {
+    "dataInstance":    { "name": "dataInstance", "desc": "dataInstance", "type": "dataType", "objectID": "<<dataType:DataTypes/EntityDataType>>" },
+    "processInstance": { "type": "dataType", "objectID": "", "name": "processInstance", "desc": "Process Instance", "list": false, "required": true },
+    "currentUser":     { "type": "dataType", "objectID": "", "name": "currentUser", "desc": "user", "list": false, "required": true },
+    "action":          { "actionId": "" }
+  },
+  "props": { "insert": [ "context.dataInstance", "input", "output" ] }
+}
+```
+
+### The reserved context
+
+Every workflow gets these four `context` members — Studio seeds them from its template and merges the file's values over it on load:
+
+- **`dataInstance`** — the process's **business data record**; the one context entry the developer chooses. Point `objectID` at the app's dataType for this process. Its members are what forms bind and flows read/write (`context.dataInstance.…`). Written without `list`/`required`.
+- **`processInstance`** — engine-backed instance metadata (`businessKey`, `initiatorUser`, `status`, `tasks`, `sla`, …), `"list": false, "required": true`. **Author `objectID` as `""`.** Studio seeds the member empty and resolves it itself: a valid existing reference is kept, otherwise it binds the app's dataType **named** `ProcessInstance` — in an app built on the WorkflowCore module, the one that module ships. An app without such a dataType simply keeps the empty value, and that is a finished file, not an unfinished one. Never write a path here to a model the workspace does not contain: the reference resolves to nothing and Studio's dependency scan starts reporting a model that was never there.
+- **`currentUser`** — the engine-backed acting user, `"list": false, "required": true`. Same rule, resolved by the name `User`: author `""` and leave what a pulled file already carries alone.
+- **`action`** — exactly `{ "actionId": "" }`, always. It is a placeholder slot, not a variable: at runtime it carries the last action taken (so decisions read `context.action.actionId`), and Studio rewrites it back to `{ "actionId": "" }` on every save. Never put anything else in it.
+
+The shapes these members carry at runtime are engine-fixed; the WorkflowCore dataTypes their `objectID`s point at are only the design-time mirror of them.
+
+### `input` / `output` / `props`
+
+- `input` and `output` are extra process-level variables (the start payload contract and process outputs). Most workflows leave both `{}` — the business data lives in `dataInstance`.
+- Variable shape is the same as in a flow: key = `name`, plus `desc`, `type` (`string | number | boolean | datetime | dataType | dataSet | any` — no `constant` in a workflow), explicit `list` and `required`, `objectID` required with `dataType`/`dataSet` and forbidden otherwise, optional `default` `{ "type", "value" }` with a string value.
+- `props` is editor-managed and rebuilt from the template on every load — author exactly `{ "insert": [ "context.dataInstance", "input", "output" ] }`.
+
+## Expressions — `{ type, value }`
+
+Step props and mappings address process data through the same expression objects flows use. In a workflow the useful `type`s are:
+
+| `type` | Meaning | `value` |
+|--------|---------|---------|
+| `context`, `input`, `output` | A store member. | Member name; dotted paths reach into dataTypes (`"processInstance.initiatorUser.userId"`, `"dataInstance.customer.customerNumber"`). No `vars` in a workflow. |
+| `string`, `number`, `boolean` | Literal. | Always a **string** (`"false"`, `"0"`), converted at runtime. |
+| `constant` | A constant model's value. | `<<constant:…>>` reference. |
+| `literal` | A JS template literal evaluated at runtime with `flow` in scope. | E.g. `"Approved by ${flow.context.currentUser.fullName}"`. |
+| `swimlane` | A swimlane item reference. | `<<swimlane:Model>>:LaneId`. |
+| `notSet` | Explicitly empty. | `""`. |
+
+Write targets (where a result is stored) are `context` and `output`.
+
+## Mappings
+
+The root functions, the SLAs and the referenced-model steps all bind a callee's contract to this workflow's store through the same `mapping` shape:
+
+```json
+"businessKeyGenerationFunction": {
+  "id": "<<flow:WorkflowCore/Functions/BusinessKeyGenerator>>",
+  "type": "referenced",
+  "mapping": {
+    "inParamMapping":  [ { "variable": { "type": "input",  "value": "key" },
+                           "mapping":  { "type": "string", "value": "BY" } } ],
+    "outParamMapping": [ { "variable": { "type": "output", "value": "businessKey" },
+                           "mapping":  { "type": "context", "value": "processInstance.businessKey" } } ]
+  }
+}
+```
+
+- `variable` is the **callee's** parameter — `{ "type": "input", "value": <callee input> }` in `inParamMapping`, `{ "type": "output", "value": <callee output> }` in `outParamMapping`.
+- `mapping` is **this workflow's** side: a source expression for inputs, a `context`/`output` target for outputs.
+- `type` on the wrapper is always `"referenced"` — the only legal value; the four root functions always reference a deployed flow by `<<flow:…>>`.
+
+### Process-level functions
+
+- `businessKeyGenerationFunction` runs once, at instance start, before anything is persisted. Its `outParamMapping` **must** map an output to `{ "type": "context", "value": "processInstance.businessKey" }` — the engine rejects the start otherwise — and the produced key must be non-empty.
+- **At that moment the business data is still empty.** `context.dataInstance` exists but holds nothing: the first user task has not run, so nothing the user will type is available yet. Feeding the generator from `dataInstance.…` therefore yields empty values, and the key comes out short of what you expected — a fault that shows up only at runtime. Build the key from what exists at start: the acting user, a counter, a constant, a value the starter passed in. A label that has to include data entered later is a different thing from the key, and belongs on the record rather than in it.
+- The three file functions receive/return the file object for the process's attachment endpoints. When unused, keep the empty skeleton exactly as the editor writes it: `{ "id": "", "type": "referenced", "mapping": { "inParamMapping": [], "outParamMapping": [] } }`.
+
+## What blocks a save
+
+- A step id that is empty or duplicated (human tasks are validated on their `stepIdToShow` prop, every other step on its `ID`).
+- A human-task action whose `actionId` does not start with `<<action:`.
+- A step carrying compile errors in its `props.errors`.
+
+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 the counter).
+- `executeType` is always `"alive"` — a workflow hand-edited to `"batch"` fails at start.
+- `store.context.action` is exactly `{ "actionId": "" }` — anything else is rewritten away on save.
+- `store.props.insert` is fixed at `["context.dataInstance", "input", "output"]`; a hand-written variant is overwritten on load.
+- Root `swimlanes` is a legacy `{}` — real routing is the human-task step's `swimlane` prop, with an item reference, not this map.
+- The business-key mapping must target `context.processInstance.businessKey`, and the referenced flow must not be batch.
+- `privileges` is AND, and it gates **starting** only — task actions and forms have their own privilege lists elsewhere.
+- References are paths (`<<type:Owner/Path/Name>>`); in an item reference the `:ItemId` after `>>` is the item's bare `id` inside the container model — never a path, never rewritten. And the dependency scan picks up ref-shaped text anywhere in the body, so never write `<<…>>` outside a field that takes one.
+- `f_o` on a switch connection is the case **name**, not the case key.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/workflow-kit/models/workflow-ui-pages.md

@@ -0,0 +1,199 @@
+# Pages in a workflow app
+
+A `.qjson` page in a workflow app is an ordinary Quick page, plus a set of bindings that only exist because a process is running behind it: the task it belongs to, the shell it renders inside, the process data it reads and writes, and the privileges that decide who may open it. This guide covers those bindings. Everything about qjson itself — components, styling, events, the `quick.*` API — is in the qjson manual and is not repeated here.
+
+## Attaching a page to a task
+
+A page becomes a task's form from the workflow side: select the user task, and pick the page in its **Form** field. One task, one page.
+
+The page itself then declares three things, on its page component's settings:
+
+| Setting | What it does | What may be picked |
+|---------|--------------|--------------------|
+| **MasterPage** | The shell the page renders inside. | Any page in the app that contains a `RenderingComponent`, is a full page rather than a block component, and is not this page itself. |
+| **Store** | The process data the page binds to. | The dataTypes that some workflow in the app already uses as its data instance — nothing else appears in the list. |
+| **Security** | Who may open the page. | Items from the app's privilege model. A user holding a listed privilege is authorized on this page. |
+
+The Store choice is what makes `quick.workflowStore.context.dataInstance` resolve to a real shape, so pick the dataType the process actually carries, not a lookalike.
+
+### Where the three settings sit in the file
+
+Two of them are props on the page's **first component** — the messaging component whose `ID` is `PageComp` — and the third sits at the root of the page object, beside the component list:
+
+```json
+{ "T": "Messaging",
+  "P": { "ID": { "H": "PageComp", "T": "prop" },
+         "masterPath": { "H": "'<<qjson:pages/MasterPage>>'", "T": "prop", "HL": "QS" },
+         "store": { "H": { "context": { "dataInstance": { "name": "dataInstance", "desc": "dataInstance",
+                                                          "type": "dataType",
+                                                          "objectID": "<<dataType:common/ExpenseData>>" } } },
+                    "T": "prop", "HL": "QS" } } }
+```
+
+```json
+"security": { "privileges": [ "<<privilege:AccessManagement/Privileges>>:CompletePrivilege",
+                              "<<privilege:AccessManagement/Privileges>>:CancelPrivilege" ] }
+```
+
+| Setting | Where | Shape |
+|---------|-------|-------|
+| MasterPage | `masterPath` prop on `PageComp` | A `<<qjson:…>>` reference, quoted inside the expression string. A master page has no `masterPath` of its own. |
+| Store | `store` prop on `PageComp` | The `H` here is an **object**, not an expression string: one `context.dataInstance` member carrying the dataType reference in `objectID`. |
+| Security | `security.privileges` at the page root, next to the component list | Privilege **item** references — the model reference followed by the item id outside the brackets. Absent or empty means no privilege check on the page. |
+
+A page that has none of these three is a plain Quick page: no shell, no process data, no privilege gate.
+
+## The master page
+
+The master page is the frame every task form of a process appears in: it holds a `RenderingComponent`, and the task's own page is rendered inside it. **Every page used by one process must select the same master page** — the shell is not switched per task.
+
+Its contents are shared across processes: the block components inside it come from a module, so they are the same building blocks everywhere. When one process needs a different behaviour, the block is overridden in that app instead of being edited in place.
+
+The blocks a master page usually carries:
+
+| Block | Role |
+|-------|------|
+| `ActionBar` | The task's actions, rendered as buttons. |
+| `AppBar` | Process name, status, business key, and the return button. |
+| `ProcessDetails` | Process facts — target, urgency, last editor, customer information. |
+| `Summary` | A read-only recap of what was entered. Almost every process overrides this one to match its own form. |
+| `Notes` | Adding, editing, deleting and listing notes on the process. |
+| `Attachments` | Uploading, deleting and downloading process files. |
+| `History` | Everything that has happened on the process. |
+| `Return` | Sending the process back to its previous owner instead of approving. |
+| `AssignToUser` | Handing the process to another user. |
+
+**None of these blocks is technically required.** A task page renders without any of them, and every need they cover could be met some other way — a process could draw its own action buttons, keep its own note panel, or do without a shell at all. What this set buys is that the behaviour is already built, already tested and identical in every process, with the differences pushed into overrides. So treat it as the shape to start from rather than a constraint: replacing a block is a real option, but it means rebuilding behaviour that already works everywhere else, and it costs the process the shared fixes that arrive with the module. The one page that genuinely cannot be skipped is `TaskPreview`, for the reasons at the end of this guide.
+
+### How a block reaches the process
+
+None of these blocks is wired to the task page directly. They read the process out of the two global-store keys themselves, derive what they need from it — process id, process instance id, business key, task id, plus the app id kept under `$appId` — and call the form manager with that. When a call comes back, the returned context is written straight back into `$context_…`, which is what makes every other block on the screen see the new state.
+
+They coordinate with the master page and with each other through two channels: `$`-prefixed store keys that act as signals (`$getFormActions`, `$sendFormAction`, `$pendingAction`, `$applyActionResponse`, `$updateHistory`, `$updateNotes`, `$updatePages`, `$closeAlert`, `$showAlert`), and their own events and inputs, declared as props on the block's own `PageComp`:
+
+```json
+"externalEvents": { "H": "[{name='goPage', params=['pageId']},{name='cancel', params=[]}]",
+                    "T": "prop", "HL": "QS" },
+"externalProps": { "H": "…", "T": "prop", "HL": "QS" }
+```
+
+`externalEvents` is the list of events the block raises for whoever hosts it — the block fires them with `quick.parent.events.<name>(…)`. `externalProps` is the matching direction: what the host may pass in. Both are a public contract, so editing a block means keeping both sides of it: renaming a signal key or an event silently detaches the block from the shell, with nothing failing loudly.
+
+A block is marked as one in its metadata header, not in the body:
+
+```
+---studio-metadata DO NOT EDIT---
+id: …
+ownerName: WorkflowCore
+blockComponent: true
+---studio-metadata DO NOT EDIT---
+```
+
+That line is also what keeps the page out of the MasterPage picker, so never add or remove it to change how a page renders.
+
+### ActionBar
+
+Renders the current task's actions as buttons, in the order the task carries them. It picks the actions up from the form context rather than from any model of its own, so a button appears exactly when the task grants that action to this user; readonly tasks end up with no buttons at all. Pressing one hands the chosen action to the shell through the pending/send action keys, waits for the result, and writes the returned context back. It also exposes `validateRendering`, which is how the shell makes the task page validate itself before an action is allowed to go through.
+
+### AppBar
+
+The strip above the form: process name, current status and business key, plus the return button. It talks to the form manager's action endpoints (`/action/trigger`, `/action/complete`) using the same ids the ActionBar derives, and raises `goPage` and `reject` for the shell to act on. Because it shows identity rather than data, this is the block a project usually leaves alone.
+
+### ProcessDetails
+
+A read-only card of process facts — target date, urgency, last editor, customer information and the like. It is built almost entirely from bindings against the context, with no scripting behind it, which makes it the cheapest block to override: change which fields the card shows and nothing else moves.
+
+### Summary
+
+A read-only recap of what the user entered. It ships **empty** — a container with a placeholder and nothing in it — because there is no way to know in advance what a process collects. Practically every process overrides it and rebuilds the recap from its own data instance fields. An empty Summary on screen is not a bug; it is a block nobody has overridden yet.
+
+### Notes
+
+The process's note list, with adding, editing and deleting. Deletion goes through a flow rather than a direct call, and after a change the block commits the process and raises the notes and history signals so the rest of the screen refreshes. Notes belong to the process instance, not to the task, so they stay visible across steps.
+
+### Attachments
+
+Upload, download and delete for process files. All three go through flows called with `quick.workflow.RunFunction`, and the list itself is read from `quick.workflowStore.context.processInstance.files`. It raises `updateFiles` after every change. When a process needs its own document rules — allowed types, mandatory documents — this is the block that gets overridden.
+
+### History
+
+Everything that has happened on the process, as a paged data table: who did what, on which step, when. It refreshes when the `$updateHistory` signal fires, which is how the note and action blocks make their own effects show up here. Content comes from the activity records of the process instance, so there is nothing process-specific to configure.
+
+### Return
+
+Sending the process back to its previous owner instead of approving it. The block is a reason list plus a free-text note, validated before it is submitted, and it then travels the same action path as any other outcome. The heading and the reason list are customizable through the return label and type keys, so a process can reword the dialog without overriding the block.
+
+### AssignToUser
+
+Handing the current task to another user: pick a user, confirm, and the block writes the new assignment back into the context. It exposes events for the dialog value and for disabling itself, so the shell can hide the option on steps where reassignment is not allowed.
+
+## What the page does not do
+
+Anything that moves or records the process is an **action** of the task, not a control on the page. That covers both kinds: the ones that advance the work — approve, reject, submit — and the ones that do not, like saving a draft so the user can come back later. The task declares which of them this user may use, and the shell's `ActionBar` turns that list into buttons. So a page never draws its own approve, reject or save button.
+
+The temptation is real, because the API a page has in its hands is enough to do it anyway: a click handler can write the context back and call `quick.workflow.Commit()`, which posts the data instance to the task's commit endpoint, and the screen will look right. What that path loses is everything the action carries — the privilege check on the action, the activity record that puts the save into the process history, and the task's own say in whether saving is allowed at this step. The engine ends up with the data but no trace of who did what.
+
+So when a page seems to need a button of this kind, the change belongs on the action side: an action item bound to the save or complete flow, granted to the task. The page stays a form.
+
+## Overrides
+
+Models inside a versioned module cannot be edited in the app that imports them. An override is an app-owned copy that leaves the module's original intact, and at runtime the overridden version is what executes. This is the normal way to adapt a shared block — `Summary` above being the usual case — so treat a block that looks app-specific as an override rather than as a module edit gone wrong.
+
+## Reading and writing process data
+
+Inside a page's handlers the process is reachable through two namespaces:
+
+- `quick.workflowStore.context` — `dataInstance` (the process data) and `processInstance` (the process itself).
+- `quick.workflowStore.formContext` — `task` (the task being displayed), `form` (form id, readonly flag, the actions, and on the preview page the task list), and `swimlanes`.
+
+The readonly flag lives on `form` and only there. The task object carries `taskId`, `taskLabel`, `taskName`, `taskDefinitionKey`, `status`, `statusDescription`, `userId`, `userName`, `currentUnit`, `swimlane`, `taskStart`, `taskEnd`, `sla`, `priority` and `actions` — no readonly of its own, so `formContext.task.readonly` is always empty and any condition resting on it is dead code.
+
+Both live in the global store under fixed keys:
+
+```
+$context_a236711b-aa1b-4b42-b336-3bb486ca07cd
+$formContext_a236711b-aa1b-4b42-b336-3bb486ca07cd
+```
+
+Assigning to `quick.workflowStore.context.…` in a handler changes a local copy only. For the change to survive into the rest of the process it has to go back into the global store:
+
+```js
+quick.workflowStore.context.dataInstance.originatorScript = value;
+quick.store.set('$context_a236711b-aa1b-4b42-b336-3bb486ca07cd', quick.workflowStore.context);
+```
+
+## Two-way binding
+
+Writing `bind(...)` in a component's value field (`value` or `qValue`) ties the component and the store together in both directions: the component follows the store, and what the user types goes back into the store. It is two-way **only** there — in any other field `bind(...)` is a plain read.
+
+A plain read is still a live one, and that is the point: `bind(...)` belongs in any prop that should follow the store, not just in value fields. Gating a field on the task being readonly is one binding and no code:
+
+```
+readonly = bind(quick.workflowStore.formContext.form.readonly)
+```
+
+The same goes for `disabled`, `visible` and any other prop. Reading the flag in a handler, parking it in a store key and binding the prop to that key is a longer road to a worse result — the handler runs once, so the prop stops following the store.
+
+What it takes is a store path. An ordinary page store is bound as `store.<storeName>.…`; the two workflow namespaces are accepted by name and resolved to the keys above, so binding the process context needs no key of its own.
+
+In a workflow app the binding target can be the process context directly:
+
+```
+bind(quick.workflowStore.context.dataInstance.originatorScript)
+```
+
+A field bound this way needs no manual write-back: the value lands in the context as the user edits, and the `quick.store.set` above becomes unnecessary. Form context fields can be bound the same way.
+
+## TaskPreview
+
+`TaskPreview` is the page shown when a process is opened without landing on a task form. It renders inside the master page's `RenderingComponent`, so it needs a master page selected like any other page.
+
+It lists the process's open work: one row per task, with a **Start** button that is enabled only where the user is authorized — pressing it continues the process from that task. Steps that have not produced a task yet, or that failed, appear as rows too; they carry no usable Start button, and their status column says whether the step is still running or what error it hit.
+
+Which of the two opens — the preview or the form — is decided by `skipToForm`:
+
+- **Not sent** (the process was opened from a search screen, for example) → the preview.
+- **Sent** (arriving on a task from the inbox) → straight to the task form.
+- **Sent, but** the process is already finished, or the user has no single task they are allowed to open → the preview anyway.
+
+The page is mandatory in every process and its name must be exactly `TaskPreview` — the engine resolves it by name, and deploy and export fail without it.