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

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

@@ -0,0 +1,67 @@
+# persona — syntax
+
+Syntax rules for a `.persona` model: the hat a user wears at runtime. A persona is a named bundle of roles; a user record points at one, and at login every privilege carried by those roles becomes active. Changing who can do what is then a change to the persona, not to each user.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "TalepPersonalari", "type": "persona", "personas": [ … ] }
+```
+
+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
+{ "id": "<as pulled>",
+  "name": "TalepPersonalari",
+  "type": "persona",
+  "personas": [
+    { "id": "TalepSahibi",
+      "roles": [ "<<role:Access/TalepRolleri>>:hazirlayan" ],
+      "dashboard": [],
+      "description": "Talep açan son kullanıcı" },
+    { "id": "TalepYoneticisi",
+      "roles": [ "<<role:Access/TalepRolleri>>:onayci",
+                 "<<role:Access/TalepRolleri>>:raporlayan" ],
+      "dashboard": [],
+      "description": "Talepleri onaylayan ve raporlayan yönetici" }
+  ] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"persona"`. |
+| `personas` | yes | The persona items. |
+
+### A persona item
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The persona's name — what a user record points at. Unique across the **whole app**, not just this model. Same character rules as other access names: letters, digits, `_`, `-`, `@`, Turkish letters allowed. |
+| `roles` | yes | The roles this persona activates, as item references: `<<role:Owner/Path/Model>>:roleId`. **At least one** — the editor refuses to save a persona without a role, since a persona with no roles grants nothing at all. |
+| `dashboard` | yes | The dashboards this persona opens with. Author `[]`: the picker has no entries to offer at the moment, so every persona written today carries an empty list. |
+| `description` | no | Free text. It is how the next person tells two similar personas apart. |
+
+The reference runs one way: a persona names its roles, and a role never knows which personas use it. That is what lets the same role sit in several personas.
+
+## What blocks a save
+
+- A persona with an empty name.
+- A persona id repeated inside the model, or already used by another persona model in the app — the editor names the offending id.
+- A persona with no roles.
+
+## Easy to get wrong
+
+- **A persona id is permanent in practice.** Once saved, the editor locks it, because user records point at it by that string. New personas stay editable until the first save.
+- **Persona, role and lane are three different questions.** The persona says which roles a user has; a role says what those roles may do; a lane says which roles pick up a given task. A user reaches a task when their persona's roles appear in the task's lane, and may act on it when those same roles carry the action's privilege — every one of the three has to line up.
+- **One persona per user, several roles per persona.** A user who genuinely wears two hats gets a persona that carries both roles, not two personas.
+- **`roles` holds references, not names.** `"onayci"` on its own does not resolve — the entry has to name the role model too.

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

@@ -0,0 +1,69 @@
+# privilege — syntax
+
+Syntax rules for a `.privilege` model: the named permissions an app checks. A privilege is a label and nothing more — it holds no rule, no user and no target. Roles grant it, and actions, pages and processes ask for it; on its own it does nothing.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "TalepYetkileri", "type": "privilege", "privileges": [ … ] }
+```
+
+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. An app may hold several privilege models; they are folders for the same kind of thing, not scopes.
+
+## Model body
+
+```json
+{ "id": "<as pulled>",
+  "name": "TalepYetkileri",
+  "type": "privilege",
+  "privileges": [
+    { "id": "talep_onayla", "description": "Talebi onaylama yetkisi" },
+    { "id": "talep_reddet", "description": "Talebi reddetme yetkisi" },
+    { "id": "talep_goruntule", "description": "Talep detayını görüntüleme yetkisi" }
+  ] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"privilege"`. |
+| `privileges` | yes | The permission items. At least one — a model with an empty list grants nothing and means nothing. |
+
+### A privilege item
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The permission's name, and the only thing references address it by. Unique across the **whole app**, not just this model. Letters, digits, `_`, `-` and `@` only; Turkish letters are allowed, spaces and other punctuation are stripped, and a leading or trailing `_`/`-` is trimmed. `snake_case` is the convention: `talep_onayla`, `rapor_indir`. |
+| `description` | yes | Free text, and worth writing: it is what people see when they pick the privilege in the role, action and page pickers. May be `""`, which leaves them picking from bare ids. |
+
+Nothing else belongs on an item. There is no enabled flag, no parent, no target and no user list — a privilege is a name plus its explanation.
+
+## How it is referenced
+
+Other models point at one item, never at the whole model: `<<privilege:Owner/Path/ModelName>>:itemId`, the model's path inside `<<…>>` and the item's `id` after it. The suffix is matched literally and is never rewritten, which is what makes item ids load-bearing.
+
+Where those references sit:
+
+- a **role**'s privilege set — the one place a privilege is actually granted to somebody
+- an **action** item — the button the privilege guards on a user task
+- a **process**'s privilege list — who may start it
+- a **page**'s security list — who may open it
+
+## What blocks a save
+
+- An item id that repeats inside the model.
+- An item id already used by another privilege model in the app — ids are app-wide, and Studio names the offending id when it refuses.
+
+## Easy to get wrong
+
+- **An id is permanent in practice.** Once a privilege has been saved, the editor locks its id: every role, action and page that references it names it by that string, and a rename would break all of them silently. Newly added rows stay editable until the first save, so get the name right before saving rather than after.
+- **Missing means open, not closed.** A resource with no privilege on it is available to everyone. Leaving a privilege off an action or a page is not a safe default — it is the permissive one, and nothing warns you about it.
+- **The model is a container, not a boundary.** Splitting privileges across several models organises them for people; it does not scope them. Two models may not use the same item id, and a reference names the model it lives in, so moving an item between models rewrites every reference to it.
+- **Granting is somebody else's job.** Adding an item here gives no one anything. Until a role's privilege set names it, the privilege exists and is held by nobody — and a resource guarded by it is then reachable by nobody either.

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

@@ -0,0 +1,103 @@
+# role — syntax
+
+Syntax rules for a `.role` model: the permission packages a participant holds. A role gathers privileges and resource permissions under one name — *maker*, *checker*, *muhasebe* — so that the same combination can be given to many users without repeating it. Users are not named here; a role is a shape, and who fills it is decided outside the app.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "TalepRolleri", "type": "role", "roles": [ … ] }
+```
+
+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
+{ "id": "<as pulled>",
+  "name": "TalepRolleri",
+  "type": "role",
+  "roles": [
+    { "id": "temel",
+      "parents": [],
+      "rbacSet": [],
+      "privilegeSet": [ "<<privilege:Access/TalepYetkileri>>:talep_goruntule" ],
+      "description": "Herkesin sahip olduğu görüntüleme yetkisi" },
+
+    { "id": "hazirlayan",
+      "parents": [ "temel" ],
+      "rbacSet": [ { "refId": "<<workflow:Processes/TalepSureci>>",
+                     "refType": "workflow",
+                     "permissions": { "create": true, "read": true, "update": true, "delete": false } } ],
+      "privilegeSet": [ "<<privilege:Access/TalepYetkileri>>:talep_olustur" ],
+      "description": "Talebi oluşturan ve gönderen" },
+
+    { "id": "onayci",
+      "parents": [ "temel" ],
+      "rbacSet": [ { "refId": "<<workflow:Processes/TalepSureci>>",
+                     "refType": "workflow",
+                     "permissions": { "create": false, "read": true, "update": true, "delete": false } } ],
+      "privilegeSet": [ "<<privilege:Access/TalepYetkileri>>:talep_onayla",
+                        "<<privilege:Access/TalepYetkileri>>:talep_reddet" ],
+      "description": "Talebi onaylayan ya da reddeden" }
+  ] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"role"`. |
+| `roles` | yes | The role items. |
+
+### A role item
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The role's name, and what everything references it by. Unique across the **whole app**, not just this model. Same character rules as other access names: letters, digits, `_`, `-`, `@`, Turkish letters allowed. |
+| `parents` | yes | Roles this one inherits from, `[]` when none. Entries name a role by id when the parent sits in the **same** model, and by item reference — `<<role:Owner/Path/Model>>:roleId` — when it sits in another role model. |
+| `rbacSet` | yes | Resource permissions, `[]` when none. |
+| `privilegeSet` | yes | Privileges this role grants, `[]` when none. Entries are item references: `<<privilege:Owner/Path/Model>>:privilegeId`. |
+| `description` | no | Free text. Worth writing — it is how the next person tells two similar roles apart. |
+
+### An rbacSet entry
+
+```json
+{ "refId": "<<workflow:Processes/TalepSureci>>",
+  "refType": "workflow",
+  "permissions": { "create": true, "read": true, "update": false, "delete": false } }
+```
+
+| Field | Rule |
+|-------|------|
+| `refId` | The resource, as a model reference. |
+| `refType` | The resource's model type. Only `"workflow"` is offered today — a process is the one kind of resource this list guards. |
+| `permissions` | The four flags `create`, `read`, `update`, `delete`, each `true` or `false`. Create is what lets the role **start** the process. |
+
+Privileges and RBAC answer different questions: a privilege is a named permission other models ask for by name, while an RBAC entry says what this role may do to a specific process. A role usually needs both.
+
+## Inheritance
+
+`parents` is what keeps role sets small. A child role holds everything its parents hold and adds its own; it does not repeat the inherited entries, and repeating them is how the file starts drifting.
+
+When several roles share the same privileges, give the shared ones to a base role and let the others name it as a parent — as `temel` does above. When they share nothing, do not invent a base role for symmetry.
+
+## What blocks a save
+
+- A role with an empty name.
+- A role id that repeats inside the model, or one already used by another role model in the app — the editor names the offending role.
+- A privilege entry left unselected: pick one or remove the row.
+- An rbacSet entry naming a resource with none of the four permissions checked. Rows with no resource at all are dropped instead of blocking.
+
+## Easy to get wrong
+
+- **A role id is what everything else names.** Swimlanes, personas and other roles' `parents` all address it by that string, and the suffix in an item reference is never rewritten by a rename. Search the app for the id before changing one.
+- **The same job done twice is still one role.** A process with two consecutive approvals — first and second approver, maker and checker in one pool — needs one `onayci` role, not `birinci_onayci` and `ikinci_onayci`. "A different person must do it" is not a role distinction; it is enforced on the task itself. Split roles only when the work genuinely differs, as preparing differs from approving.
+- **A role with neither privileges nor parents grants nothing.** If the app has privileges at all, every role should reach some of them — directly through its own set, or through a parent chain that ends at one.
+- **`privilegeSet` holds references, not bare names.** `"talep_onayla"` on its own does not resolve; the entry has to name the privilege model too.
+- **Inheritance is by parent, not by copy.** Two roles carrying identical privilege lists work, but the next change updates one and forgets the other. Prefer the base role.

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

@@ -0,0 +1,65 @@
+# swimlane — syntax
+
+Syntax rules for a `.swimlane` model: the lanes a process assigns its user tasks to. A lane names roles, never people — when a task is sent to a lane, everyone whose roles match it sees the task in their pool and any one of them can pick it up. That is what lets staff change without the process changing.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "TalepKulvarlari", "type": "swimlane", "swimlanes": [ … ] }
+```
+
+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
+{ "id": "<as pulled>",
+  "name": "TalepKulvarlari",
+  "type": "swimlane",
+  "swimlanes": [
+    { "id": "Hazirlayan",
+      "roles": [ "<<role:Access/TalepRolleri>>:hazirlayan" ] },
+    { "id": "Onayci",
+      "roles": [ "<<role:Access/TalepRolleri>>:onayci",
+                 "<<role:Access/TalepRolleri>>:kidemliOnayci" ] }
+  ] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"swimlane"`. |
+| `swimlanes` | yes | The lanes. A model with an empty list gives a process nowhere to send its tasks. |
+
+### A lane
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The lane's name, and the only thing a task references it by. Unique across the **whole app**, not just this model. Same character rules as other access names: letters, digits, `_`, `-`, `@`, Turkish letters allowed. It is also what people see, so write it as a name rather than a code: `Onayci`, `MuhasebeEkibi`. |
+| `roles` | yes | The roles that may take the lane's tasks, as item references: `<<role:Owner/Path/Model>>:roleId`. Several roles in one lane means one shared pool. `[]` is legal and leaves the lane reachable by nobody. |
+
+Nothing else belongs on a lane. There are no users, no privileges and no task list here — a lane is a name and the roles behind it.
+
+## How a process uses it
+
+A user task assigns work either to a lane or to one named user. For a lane, the task carries `sendTo: "swimlane"` and the lane's item reference, `<<swimlane:Owner/Path/Model>>:laneId`. At login the engine compares the user's persona roles against each lane's role list; every lane that matches becomes visible to that user.
+
+## What blocks a save
+
+- A lane id repeated inside the model.
+- A lane id already used by another swimlane model in the app — the editor names the offending id.
+
+## Easy to get wrong
+
+- **A lane id is permanent in practice.** Once saved, the editor locks it: every user task that routes to the lane names it by that string, and the suffix in a reference is never rewritten. New rows stay editable until the first save.
+- **Lanes follow responsibilities, not steps.** Two consecutive approvals done by the same kind of person share one lane; a process does not get a `birinci_onay` and an `ikinci_onay` lane. When the rule is "a different person must handle the second one", that is enforced on the task itself, not by splitting the lane. Most processes end up with two to four lanes.
+- **An empty `roles` list is a silent dead end.** The lane saves, the task routes to it, and no one ever sees the work. Every lane needs at least one role reference before the process is usable.
+- **The lane knows roles, the roles know privileges.** Putting someone in a lane does not grant them anything; what they may do once they open the task comes from the privileges their roles carry.
+- **`roles` holds references, not names.** `"onayci"` on its own does not resolve — the entry has to name the role model too.

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

@@ -0,0 +1,90 @@
+# action — syntax
+
+Syntax rules for an `.action` model: the buttons a user task shows. An action ties a name to the workflow function that runs when the button is pressed, optionally to a form it opens, and optionally to the privileges a user must hold to press it. The same action is reused by every task that offers that button.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "TalepAksiyonlari", "type": "action", "actions": [ … ] }
+```
+
+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
+{ "id": "<as pulled>",
+  "name": "TalepAksiyonlari",
+  "type": "action",
+  "actions": [
+    { "id": "Onayla",
+      "description": "Talebi onaylar ve süreci ilerletir",
+      "privileges": [ "<<privilege:Access/TalepYetkileri>>:talep_onayla" ],
+      "designId": "<<qjson:Pages/OnayEkrani>>",
+      "function": {
+        "id": "<<flow:WorkflowCore/Functions/fn_Complete>>",
+        "mapping": {
+          "inParamMapping":  [ { "variable": { "type": "input",  "value": "taskId" },
+                                 "mapping":  { "type": "context", "value": "task.taskId" } } ],
+          "outParamMapping": [ { "variable": { "type": "output", "value": "result" },
+                                 "mapping":  { "type": "output", "value": "sessionResponse" } } ] } } },
+
+    { "id": "Reddet",
+      "description": "Talebi reddeder",
+      "privileges": [ "<<privilege:Access/TalepYetkileri>>:talep_reddet" ],
+      "function": { "id": "<<flow:WorkflowCore/Functions/fn_Complete>>",
+                    "mapping": { "inParamMapping": [ … ], "outParamMapping": [ … ] } } }
+  ] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"action"`. |
+| `actions` | yes | The action items. |
+
+### An action item
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The action's name — panel label **Name**. Unique across the **whole app**, not just this model. It is the id a task references and the string a decision compares against, so keep it short and specific: `Onayla`, `Reddet`, `IadeEt`, `Kaydet`. |
+| `function` | yes | The workflow function the button runs: `{ "id": "<<flow:Owner/Path/Name>>", "mapping": { … } }`. The function must already exist — the panel picks it from the app's functions and builds the mapping rows from its declared inputs and outputs. |
+| `privileges` | yes | Privileges required to press it, as item references: `<<privilege:Owner/Path/Model>>:privilegeId`. `[]` means anyone who reaches the task may press it. |
+| `description` | no | Free text, shown wherever Studio lists actions to pick from. |
+| `designId` | no | The form the action opens or updates: `<<qjson:Owner/Path/Page>>`. Omit it for a button that only runs its function. |
+
+Nothing else belongs on an item. A save-style button and a complete-style button differ only in the function they run, not in a field here.
+
+### The function mapping
+
+`mapping` follows the same shape every callee mapping does: one `inParamMapping` row per function input, one `outParamMapping` row per function output, each row naming the function's own parameter in `variable` and the value the action supplies in `mapping`. The caller side here is the task's runtime context, so input rows are usually `context` expressions; output rows commonly land in `sessionResponse`, the response the session carries back.
+
+Changing the function replaces the rows — a different function has a different contract — while re-opening an action whose function has gained a parameter adds the missing row and keeps what was already filled.
+
+## How it is referenced
+
+A user task names one item at a time: `<<action:Owner/Path/Model>>:actionId`, the model's path inside `<<…>>` and the item's `id` after it. The task decides the button's order and may override its caption; what the button *does* stays here.
+
+At runtime the process reports which button was pressed as the bare id — `"Onayla"` — so decisions compare against that, never against the full reference.
+
+## What blocks a save
+
+- An action with an empty **Name**.
+- An action with no **Function** — the function is not optional, since a button that runs nothing is not an action.
+- An action whose function mapping has an empty row: every input and output row must be filled.
+- An action id already used anywhere in the app, in this model or another one.
+
+## Easy to get wrong
+
+- **Ids are app-wide, so make them specific.** A second model in the app cannot introduce another `Onayla`. Where a clash is likely, qualify it — `TalepOnayla`, `MasrafOnayla` — rather than discovering the collision at save time.
+- **An id is what tasks and decisions name.** Renaming one breaks every task that offers the button and every decision that compares against it; the suffix in a reference is never rewritten for you.
+- **`privileges` is an AND.** A user must hold **all** of the listed privileges to press the button, not any one of them. Two alternative permissions mean two actions, or one privilege that both roles carry.
+- **The check runs before the function.** An unauthorized user cannot trigger the function even if the button is visible, so the privilege list is a real guard rather than a display hint. An empty list is the permissive case: everyone who can open the task can press it.
+- **`function` points at a function, not at a form.** The form is `designId`, and it is optional; a button that both opens a form and runs work carries both.

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

@@ -0,0 +1,37 @@
+# appSettings file syntax
+
+The exact shape of the `.appSettings` file — the app-wide configuration model. Exactly one per app, at the app root, named `App Settings.appSettings` (the space is part of the name — the runtime looks it up by the exact name `App Settings`; never rename it). Its `apiSecurity` block wires the app's auth model.
+
+## File wrapper
+
+Same studio-metadata header as every pulled model; edit only the JSON body.
+
+## Root object
+
+```json
+{
+  "general": {
+    "settings": "<<settings:WorkflowCore/Settings/DefaultSettings>>",
+    "alert": "<<alert:WorkflowCore/Settings/Alert>>",
+    "pipeline": "<<pipeline:WorkflowCore/Settings/Pipeline>>",
+    "containerServices": "<<containerServices:WorkflowCore/Settings/ContainerServices>>"
+  },
+  "globalLocalization": "<<globalLocalization:WorkflowCore/Settings/GlobalLocalization>>",
+  "apiSecurity": { "authModelId": "<<auth:apiAuth>>" }
+}
+```
+
+References here are plain strings using the settings-model kinds (`settings`, `alert`, `pipeline`, `containerServices`, `globalLocalization`, `auth`) — the kind matches the field name, the target is always the model's path.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `general` | object | Required. Wires the app's shared settings models, one `<<kind:…>>` reference per member — editor-managed — leave as pulled. Optional extra members exist in the schema (`siteTitle`, `startScreen`, `webLoading`, `mobileLoading`, `containerServIntelli`, `componentList`, `localProxy`, `loading` — strings; `useShadowDOM`, `renderCCOnEdit` — booleans); absent unless configured. |
+| `globalLocalization` | string? | `<<globalLocalization:…>>` reference to the app's localization model — editor-managed — leave as pulled. |
+| `apiSecurity` | object? | `{ "authModelId": "<<auth:…>>" }` — points at the app's `.auth` model. The one field you realistically author here. |
+| `oAuthSettings` | object? | IAM/OIDC client config (identity provider URL, realm, clientId, …) — editor-managed — leave as pulled. |
+| `themeSettings` / `integrationsSettings` | object? | Theme and integrations config — editor-managed — leave as pulled. |
+| `logging` | object? | `{ minEngineLogLevel?, yamlLogType?, logBulkSize? }`; levels `Debug Trace Warning Error`. |
+| `loading` | object? | `{ webLoading?, mobileLoading? }`. |
+| `tagValues` | object? | `{ "tagValues": [ { id, label, value, definitionSource } ] }` — editor-managed — leave as pulled. |
+
+Optional blocks are simply absent when unset — a body with only `general`, `globalLocalization` and `apiSecurity` is a complete, normal file.

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

@@ -0,0 +1,118 @@
+# auth — syntax
+
+Syntax rules for an `.auth` model: how callers of the app's API prove who they are. It decides whether the API is open or closed, which credentials are accepted, how long issued tokens live, and which workflow function turns the authenticated caller into a runtime user.
+
+The app points at the model from its settings (`apiSecurity.authModelId`), and an endpoint may name it from an auth middleware. One model describes one client.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{ "id": "…", "name": "apiAuth", "type": "auth", "authType": "oauth2", … }
+```
+
+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
+{ "id": "<as pulled>",
+  "name": "apiAuth",
+  "type": "auth",
+  "authType": "oauth2",
+  "typeOfClient": "confidential",
+  "grantTypes": [ "client_credentials" ],
+  "clientId": "portal-backend",
+  "clientSecret": "<generated>",
+  "accessTokenTtlSeconds": 3600,
+  "enableRefreshToken": true,
+  "refreshTokenTtlSeconds": 86400,
+  "userMappingFunction": {
+    "id": "<<flow:Auth/fn_ResolveUser>>",
+    "mapping": {
+      "inParamMapping":  [ { "variable": { "type": "input",  "value": "userId" },
+                             "mapping":  { "type": "string", "value": "" } } ],
+      "outParamMapping": [ { "variable": { "type": "output", "value": "response" },
+                             "mapping":  { "type": "output", "value": "response" } } ] } } }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | The model's own id. Studio fills it from the file's identity; author `""` in a new file and leave what a pulled one carries. |
+| `name` | yes | The model name, same as the file name. |
+| `type` | yes | Always `"auth"`. |
+| `authType` | yes | `"oauth2"`, `"basicAuth"` or `"noAuth"` — the shape's own name, and it must agree with the other two fields: `"oauth2"` with `client_credentials`, `"basicAuth"` with `password`, `"noAuth"` with a public client. A new model starts as `"oauth2"`. |
+| `typeOfClient` | yes | Panel field **Type of client**: `"confidential"` — the caller must authenticate — or `"public"`, which applies no authentication at all. |
+| `grantTypes` | yes | Panel field **Grant type**, an array holding exactly **one** entry: `"client_credentials"` for OAuth2, or `"password"` for basic authentication. The two are mutually exclusive. A public client has no grant: `[]`. |
+| `clientId` | with client credentials | Panel field **Client ID** — the caller's identifier. |
+| `clientSecret` | with client credentials | Panel field **Client secret**. Generated by the panel's **REGENERATE** button as random hex and shown masked. |
+| `basicAuth` | with basic authentication | `{ "username": "…", "password": "…" }` — the credentials the caller sends. |
+| `accessTokenTtlSeconds` | with client credentials | Panel field **Access token lifetime (s)**. Default `3600`. |
+| `enableRefreshToken` | with client credentials | Panel field **Refresh token**. `true` makes the token endpoint return a refresh token as well. |
+| `refreshTokenTtlSeconds` | with `enableRefreshToken` | Panel field **Refresh token lifetime (s)**. Default `86400`. Editable only while the refresh token is enabled. |
+| `userMappingFunction` | see below | `{ "id": "<<flow:Owner/Path/Name>>", "mapping": { … } }` — the function that turns the authenticated caller into a runtime user. |
+
+## The three shapes
+
+The panel shows only the fields that belong to the chosen combination, and a file is expected to carry only those:
+
+- **Public** — `authType: "noAuth"`, `typeOfClient: "public"`, `grantTypes: []`. No credentials, no token settings; every caller is let through.
+- **Basic authentication** — `authType: "basicAuth"`, `typeOfClient: "confidential"`, `grantTypes: ["password"]`, credentials in `basicAuth`. No tokens are issued, so the token fields do not apply.
+- **OAuth2 client credentials** — `authType: "oauth2"`, `typeOfClient: "confidential"`, `grantTypes: ["client_credentials"]`, `clientId` + `clientSecret`, and the token lifetimes. This is the shape a new model starts in.
+
+Switching the type of client to public clears the grant list; switching back restores a grant, defaulting to client credentials. Leaving stale fields from another shape behind is harmless but misleading — drop them.
+
+## The user mapping function
+
+Authentication proves *a caller*; a workflow needs *a user* — someone with a persona, roles and lanes. `userMappingFunction` bridges the two: the flow it names is handed the caller's identity and returns the runtime user the process then runs as.
+
+An app that contains workflows needs it: the engine calls it whenever it has to turn an id into a user, and a process reaching that point in an app without one aborts with "No user mapping function configured in the app's auth model".
+
+### The contract is fixed by names
+
+The function is not called the way a step calls a flow. The engine builds the call itself, matching **by member name**, so what matters is the function's own store:
+
+- **Input `userId`** — the identity to resolve. That is the only key the engine passes today; a declared input by any other name is simply not filled, and one named `userId` receives the value. What arrives in it is the **user id the request carried** (the caller's `user` header), or, when the engine is resolving somebody already known to the process, that person's id. It is never the client id or the basic-auth username: those authenticate the *client*, while this names the *person* the work belongs to. So the ids your function looks up are the app's user ids, not credentials.
+- **Output `response`** — the runtime user, and the **only** output that is read back. An output named anything else is ignored and the engine ends up with no user at all, which fails as if the function had returned nothing. This is the single easiest thing to get wrong here.
+
+The `mapping` block stored in the model is editor bookkeeping — the panel fills it in from the chosen function's contract, and the engine rebuilds its own mapping at call time rather than reading it. Keep what the panel wrote; do not hand-tune it to change behaviour, because it changes none.
+
+### What the returned user has to carry
+
+`response` is a plain object with the runtime user's fields:
+
+| Field | Rule |
+|-------|------|
+| `userId` | The identity, and what the engine compares against when a task is assigned to one person. |
+| `firstName` / `lastName` / `fullName` | Display names. `fullName` is what task lists and history entries show. |
+| `unit` | The user's organizational unit. |
+| `persona` | `{ "name", "roles": [ … ], "swimlanes": [ … ] }` — **the field that decides what the user can do**, and the two lists inside it have different shapes (below). An empty or missing persona means the user sees no lane's work and can complete nothing. |
+| `email` | Optional. |
+| `isSystemUser` | Optional; `true` for a caller that is a system rather than a person. |
+
+Inside the persona:
+
+- **`swimlanes` is a list of plain lane ids** — `["OnayHavuzu"]`, the same strings the swimlane model uses as its lane `id`s. A task's pool is matched against these directly, so a mismatch of one character means the work never shows up.
+- **`roles` is a list of objects**, not names: `{ "id": "<rol adı>", "rbacSet": [], "privilegeSet": [ { "id": "<<privilege:Owner/Path/Model>>:privilegeId" } ] }`. The privileges a user holds are gathered from these `privilegeSet` entries and compared **verbatim** against what an action or a task requires — which is why the entry carries the privilege's whole reference rather than its bare name. A role written as a plain string authenticates fine and grants nothing.
+
+A mapping function that returns only `userId` and a name authenticates fine and then stalls at the first user task, because there is no persona behind it. Where the users live — a dataType, an external directory, a fixed table — is the app's own business; producing this shape from them is the function's job.
+
+`response` itself is declared as an `any` output: it is a plain object the engine reads field by field, not a dataType instance.
+
+### Where the app finds it
+
+The engine reads the mapping function from **one** auth model: the one the app settings point at through `apiSecurity.authModelId`. An app may hold several auth models — one per caller — but only that one's mapping function is ever used, so it is the one that has to have it, and the others leave the field out entirely rather than carrying an empty or duplicated copy.
+
+## Easy to get wrong
+
+- **`grantTypes` holds one entry, not a set.** The panel offers a single choice; an array with both values is not a file Studio writes, and the first entry is what decides the shape.
+- **`"password"` means basic authentication here.** It is the grant name behind the panel's Basic Authentication choice, not a separate password flow — do not read it as OAuth2's password grant and add token settings to it.
+- **Public is not a mistake to fix.** `typeOfClient: "public"` is a deliberate "no authentication"; leave it alone rather than filling in credentials, and remember that everything reachable through that API is then open.
+- **Secrets are values, not placeholders — names are not secrets.** `clientSecret` and `basicAuth.password` are what the caller has to send, and they sit in the file in plain text: never invent one when editing an existing model, since regenerating it in Studio is what rotates it and a hand-written value silently breaks every caller. On a model you are creating, leave those two empty and say so — the person who owns the caller fills them in. `clientId` and `basicAuth.username` are different: they identify the caller rather than authenticate it, so write the name the integration will use.
+- **Fields that do not apply are left out, not zeroed.** With `enableRefreshToken: false` there is no `refreshTokenTtlSeconds`; on a basic-auth model there are no token fields at all; on a public one there are no credentials. The panel shows a default in a disabled box, which is display, not content.
+- **Nothing here grants anything.** Auth answers "who is calling"; what that user may do comes from their persona's roles and the privileges those carry.