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

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/reference/quick-api.md

@@ -0,0 +1,284 @@
+# Quick Runtime API (`quick.*`)
+
+> The API surface available inside event/prop handlers, extracted from the runtime's TypeScript interface definitions.
+>
+> **Two layers.** This file is the *readable* layer: the authoring rules below plus a complete index of every member (bottom of the file). [quick-api.json](quick-api.json) is the *detail* layer: full signature, params, returns and usage example per member — **grep the member you need there by its full path (e.g. `grep -n '"quick.Quick.region.setRegion"' quick-api.json`); never read it whole.** Workflow: scan the index here → grep the JSON for the one you picked → write the call.
+
+## Two scripting contexts
+
+Handlers run in one of two languages (`HL` field), and the available globals differ:
+
+| | `HL: "TS"` (TypeScript) | `HL: "QS"` (QScript) |
+|---|---|---|
+| Extra globals | `devex` | `Math`, `regex`, `typeOf`, `Date`, `Number`, `JSON`, `string`, `Object`, `js`, `Url` |
+| Default? | **event handlers: always author `TS`** (`"HL":"TS"`) | **properties/bindings: `QS`** — the omitted-`HL` runtime default |
+
+In **TS**, call framework APIs as `quick.X`. In **QScript** (all props, and QS handlers), the `quick.` prefix is **dropped**: `quick.store` → `store`, `quick.MM` → `MM`, `quick.Quick` → `Quick`. Props are always QScript regardless of `HL`. The index below lists the TS form; strip `quick.` when writing QScript.
+
+> **QScript semantics that differ from JS:** (1) `||` is boolean — `a || b` returns `true`/`false`, not the value of `a` or `b`. Don't write `store.get('x') || 'default'` expecting a fallback string; use `if(a){a}else{b}`. (2) Property access is null-safe by default — `a.b.c.d` won't throw even if `a` is undefined. So `|| ''` / `?? ''` guards are unnecessary and wrong in QScript props.
+
+> The QScript-only globals (`Math`, `Date`, `Number`, `JSON`, `string`, `regex`, `typeOf`, `Url`, `js`, `Object`) are wrappers, not the native objects — `Date.now()`, `Math.random(min,max)` and friends behave as the index describes. In TS handlers use native equivalents or `quick.*` instead.
+
+## Easy to get wrong
+
+- **`quick.store` prefixes are Page / Bag(`#`) / Global(`$`) / Shared(`&`)** — no prefix = Page context (cleared on navigation). None of them persist across sessions; for that use `quick.permanentStore`, **not** a store prefix.
+- **`quick.Quick.alert({...})` must always include `actionButtons`** — an alert without them cannot be dismissed.
+- **`quick.Quick.validate(compID, …)` takes the runtime ID (`P.ID.H`), not `_Editor.eID`.**
+- **There is no `phone` validation rule.** The full set is `required`, `minLength`, `maxLength`, `email`, `iban`, `IBANNumOnly`, `regex`, `tckn`, `vkn` (the last two are Turkish ID / tax-number validators). For phone input use the component's `format` mask plus `regex`.
+
+## Shapes the index can't show
+
+A few values are typed by interfaces the index doesn't expand:
+
+- **`IRequest`** (the object passed to `quick.Request.async` / `.download`): `url`, `http`, `data`, `responseField`, `onSuccess`, `onFail`, `blockRender`, `showSuccessMessage`, `showErrorMessage`, `args`, `headers`, `withCredentials`, `timeout`. **`http` is one of** `'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'MULTIPART' | 'POSTBLOB' | 'GETBLOB'`.
+- **`quick.permanentStore`** is **async, IndexedDB-backed** cross-session persistence (unlike `quick.store`, which is in-memory) — `await` its calls.
+- **`place`** in `quick.Quick.createComponent` is `ElementLocation`: `'Before' | 'After' | 'Default'`.
+
+## Golden rules for handler code
+
+1. **Never `return`** — use `quick.return(value)`.
+2. **Event handlers are always TypeScript — set `"HL": "TS"` on every handler.** (The omitted-`HL` default of `QS` applies to property/binding expressions, not `E` handlers.)
+3. In **props**, localization is bare `LR('key')`; in **events**, `quick.LR('key')`.
+4. Avoid browser globals in handlers: `quick.MM.delay` (not `setTimeout`), `quick.EM.trace` (not `console`), `quick.Quick.download` (not anchor downloads).
+5. Read a service response in the `onSuccess` event as `response.<responseField>`.
+6. Strip the `quick.` prefix in QScript (props + QS handlers); keep it in TS handlers.
+
+---
+
+## Complete member index
+
+Every member of the `quick.*` surface. Scan this to see what exists, then read the full
+signature, params and example for the one you need from [quick-api.json](quick-api.json) (grep the member name — never read that file whole).
+
+- **`quick.Request`**
+  - `quick.Request.async` — Sends a network request
+  - `quick.Request.download` — Downloads files and resources through network request
+- **`quick.MM`**
+  - `quick.MM.get` — Retrieves the custom event from the Page Component
+  - `quick.MM.trigger` — Triggers a custom event on the Page Component
+  - `quick.MM.delay` — Triggers a custom event on the Page Component with a delay
+  - `quick.MM.clearTimeout`
+- **`quick.EM`**
+  - `quick.EM.trace` — Writes a message to the browser console
+- `quick.LR` — Retrieves the language equivalent of the given key parameter with current language of the system
+- `quick.importLocalization` — Imports localization data for a specific language and adds it to Global Localization
+- `quick.go` — Triggers the go command in the shell with integrated WebSDK, routing to another page with the provided parameters
+- `quick.getComponent` — Retrieves the component instance by the given component id
+- `quick.setFormData`
+- `quick.getArrangedNestedData`
+- `quick.getFormData`
+- `quick.getArrangedFormData`
+- `quick.bind`
+- **`quick.Quick`**
+  - **`quick.Quick.dx`**
+    - `quick.Quick.dx.getDxCustomStore`
+  - **`quick.Quick.region`** — Provides methods for managing regions within the application
+    - `quick.Quick.region.setRegion` — Sets the current region
+    - `quick.Quick.region.getRegionList` — Retrieves the list of available regions
+    - `quick.Quick.region.getCurrentRegion` — Gets the name of the currently set region
+    - `quick.Quick.region.getFormattingDefinitionByCurrentRegion` — Retrieves the formatting definition based on the current region
+  - **`quick.Quick.theme`** — Provides methods for managing themes within the application
+    - `quick.Quick.theme.setTheme` — Sets the current theme
+    - `quick.Quick.theme.getThemeList` — Retrieves the list of available themes
+    - `quick.Quick.theme.addTheme` — Adds a new theme to the list of available themes
+    - `quick.Quick.theme.removeTheme` — Removes a theme from the list of available themes
+  - `quick.Quick.redirect` — Attempts to open a URL using the specified options for redirection
+  - `quick.Quick.performance`
+  - `quick.Quick.back`
+  - `quick.Quick.goHistory` — Navigates between opened pages using the specified step number in the navigation history
+  - `quick.Quick.go` — Triggers navigation to the specified page with optional configuration options
+  - `quick.Quick.goNative`
+  - `quick.Quick.copy` — Creates a deep copy of the provided object using a cloning technique
+  - `quick.Quick.setComponentsProperty` — Sets the specifed component properties with the given values
+  - `quick.Quick.download` — Initiates the download of a file using a base64-encoded string and specifying the file name
+  - `quick.Quick.shareData` — Initiates the share of a file using a base64-encoded string or by using a link and specifying the file name
+  - `quick.Quick.isObject` — Check if the given input is an object
+  - **`quick.Quick.validation`** — Collection of Quick Rule functions for input component validation
+    - `quick.Quick.validation.required` — Validates that a value is not empty
+    - `quick.Quick.validation.minLength` — Validates that a value has a minimum length
+    - `quick.Quick.validation.maxLength` — Validates that a value has a maximum length
+    - `quick.Quick.validation.email` — Validates that a value is a valid email address
+    - `quick.Quick.validation.iban` — Validates that a value is a valid IBAN
+    - `quick.Quick.validation.IBANNumOnly`
+    - `quick.Quick.validation.regex` — Validates that a value matches a specified regular expression
+    - `quick.Quick.validation.tckn` — Validates that a value is a valid Turkish Identification Number (TCKN)
+    - `quick.Quick.validation.vkn` — Validates that a value is a valid Tax Identification Number (VKN)
+  - `quick.Quick.validate` — Validates a component and all its child inputs
+  - `quick.Quick.validateAll` — Validates all registered inputs in the page
+  - `quick.Quick.resetValidation` — Only clears validations, it has no effect on other variables
+  - `quick.Quick.reset` — Ensures that the set values and validations of the components are cleared
+  - `quick.Quick.createComponent` — Creates a new component based on the provided template component and inserts it into the page at a specified location
+  - `quick.Quick.findCreateComponentRelative` — Finds the desired dynamic component created with a template by giving a child component inside that dynamically created component
+  - `quick.Quick.createChildren` — Creates a child component based on the provided template child name and inserts it into the specified parent component
+  - `quick.Quick.deleteComponent` — Deletes a component or DOM element from the page
+  - `quick.Quick.bind` — Declares legacy store dependencies for the provided fields *(deprecated)*
+  - `quick.Quick.setLanguage` — Sets the system language to given parameter if you add it beforehand in the localization file
+  - `quick.Quick.getLanguage` — Retrieves the currently set system language
+  - `quick.Quick.setPageTitle` — Sets the title of the current page
+  - `quick.Quick.copyToClipboard` — Allows copying a specified value to the clipboard
+  - `quick.Quick.initializePositioning` — Recalculates the positions of the input components drop-down menus
+  - `quick.Quick.cleanupPositioning` — Cleans up the effects of initializePositioning
+  - `quick.Quick.getPageTitle` — Retrieves the title of the current page
+  - `quick.Quick.getFavicon` — Retrieves the favicon of the current page
+  - `quick.Quick.updateComponent` — Updates a component using its instance
+  - `quick.Quick.exportToXlsx` — Exports data to multiple sheets in an Excel file
+  - `quick.Quick.xlsxToJson`
+  - `quick.Quick.toLongDate` — Takes the raw date value and converts it to a date format with month, day, year, hour and minute
+  - `quick.Quick.toShortDate` — Converts a raw date value to a short date format with month, day, and year
+  - `quick.Quick.toLongTime` — Converts a raw date value to a long time format with hour, minute, and second
+  - `quick.Quick.toShortTime` — Converts a raw date value to a short time format with hour and minute
+  - `quick.Quick.toDate` — Converts a string value to a Date object according to the given format type
+  - `quick.Quick.dateFromNow` — Calculates the time difference between a specified time and the present moment and returns a human-readable string
+  - **`quick.Quick.platform`**
+    - `quick.Quick.platform.isMobile` — Returns whether the platform is a mobile platform (Android or iOS)
+    - `quick.Quick.platform.isWeb` — Returns whether the platform is a web browser
+    - `quick.Quick.platform.getPlatformType` — Returns the current platform type
+    - `quick.Quick.platform.getDeviceId` — Returns the device ID that runs the application
+    - `quick.Quick.platform.getClientInfo`
+  - `quick.Quick.getCurrentPosition` — Retrieves the current geographical position of the device
+  - `quick.Quick.toMoney` — Converts a number or numeric string to a money-formatted string
+  - `quick.Quick.setComponentClass` — Sets the class properties of a component using the specified array of class names
+  - `quick.Quick.toDecimal` — Converts a formatted string to its raw decimal value
+  - `quick.Quick.toBigNumber`
+  - `quick.Quick.dm`
+  - `quick.Quick.getEditor`
+  - `quick.Quick.alert` — Displays an alert component with the specified configuration
+  - `quick.Quick.closeAlert`
+  - **`quick.Quick.host`**
+    - `quick.Quick.host.trigger` — ⚠️❗️**Use quick.container instead of quick.Quick.host.trigger.** **See Container Configuration documentation:** **https://docs.onplateau.com/UI-Screens/UI-Settings/container-configuration** *(deprecated)*
+  - `quick.Quick.isEditMode`
+  - `quick.Quick.getComponentIdByInstance` — Retrieves the ID of a component based on its instance
+  - **`quick.Quick.screen`** — Methods for interacting with the screen, including scrolling and bringing elements into view
+    - `quick.Quick.screen.YOffset` — Returns the vertical (up or down) scrolling offset of the screen or element
+    - `quick.Quick.screen.XOffset` — Returns the horizontal (left or right) scrolling offset of the screen or element
+    - `quick.Quick.screen.intoView` — Scrolls the webpage to bring a specific element into the visible area of the browser
+    - `quick.Quick.screen.scrollIntoView` — Alias for the intoView method
+    - `quick.Quick.screen.toTop` — Scrolls the document to the top of the page
+  - **`quick.Quick.environment`**
+    - `quick.Quick.environment.variable`
+  - `quick.Quick.yamlLogType`
+  - **`quick.Quick.loading`** — Methods for managing loading indicators, including showing and hiding the loading state
+    - `quick.Quick.loading.show` — Displays the loading indicator
+    - `quick.Quick.loading.hide` — Hides the loading indicator
+  - **`quick.Quick.network`**
+    - `quick.Quick.network.isConnected` — Determines the online/offline status of the network
+  - **`quick.Quick.render`**
+    - `quick.Quick.render.block` — Blocks rendering operations
+    - `quick.Quick.render.resume` — Resumes rendering operations
+  - **`quick.Quick.authentication`**
+    - `quick.Quick.authentication.getIamToken` — Retrieves IAM token
+  - **`quick.Quick.config`**
+    - `quick.Quick.config.get`
+- **`quick.containerServices`**
+  - `quick.containerServices.extensions`
+- **`quick.sso`**
+  - `quick.sso.start` — Initiates the single sign-on (SSO) process by starting the SSO request
+  - `quick.sso.validate` — Validates the user and completes the single sign-on (SSO) process
+- **`quick.store`**
+  - `quick.store.set` — Sets a value to the store
+  - `quick.store.get` — Gets a value from the store
+  - `quick.store.getAll` — Gets all values from the store
+  - `quick.store.delete` — Deletes a value from the store
+  - `quick.store.deleteAll` — Deletes all values from the store
+- **`quick.permanentStore`**
+  - `quick.permanentStore.set` — Sets a key-value pair object to the Permanent Store
+  - `quick.permanentStore.get` — Gets a key-value pair object from the Permanent Store
+  - `quick.permanentStore.delete` — Deletes a key-value pair object associated with the 'key' in the permanent store 
+  - `quick.permanentStore.getAll` — Gets all key-value pair objects from the permanent store
+  - `quick.permanentStore.createOrChangeStore` — Provide the permanent store name that application will use
+  - `quick.permanentStore.deleteStore` — Deletes the Permanent Store
+  - `quick.permanentStore.defaultStoreName`
+  - `quick.permanentStore.currentStoreName`
+- **`quick.cookie`**
+  - `quick.cookie.set` — Sets a cookie with the provided key and cookie value
+  - `quick.cookie.get` — Gets the value of the cookie associated with the provided key
+  - `quick.cookie.getAll` — Gets all cookies as key-value pairs
+  - `quick.cookie.delete` — Deletes the cookie associated with the provided key
+- **`quick.localStorage`**
+  - `quick.localStorage.set` — Sets a value in the local storage with the provided key
+  - `quick.localStorage.get` — Gets the value from the local storage associated with the provided key
+  - `quick.localStorage.clear` — Clears all values from the local storage
+  - `quick.localStorage.delete` — Deletes the value from the local storage associated with the provided key
+- **`quick.encryptedStorage`**
+  - `quick.encryptedStorage.set` — Only uses for Mobile Apps
+  - `quick.encryptedStorage.get` — Only uses for Mobile Apps
+  - `quick.encryptedStorage.clear` — Only uses for Mobile Apps
+  - `quick.encryptedStorage.delete` — Only uses for Mobile Apps
+- **`quick.Url`**
+  - `quick.Url.resolve`
+  - `quick.Url.getDeepLinkParams`
+  - `quick.Url.getUrl`
+- `quick.findControl`
+- `quick.this`
+- **`quick.parent`**
+  - `quick.parent.props` — Properties defined in Messaging P: ExternalProps
+  - `quick.parent.events` — Events defined in Messaging P: ExternalEvents
+- **`quick.process`**
+  - `quick.process.getMetadata` — Gets the metadata
+  - `quick.process.setMetadata` — Sets the metadata
+  - `quick.process.changeProcessMetadata` — Changes the process metadata
+- `quick.return` — Returns a value from the current event (stops execution and returns)
+- `quick.await`
+- **`quick.currentPage`**
+  - `quick.currentPage.isRenderCompleted` — Checks if the rendering process has been completed
+- **`quick.cryptography`**
+  - `quick.cryptography.hash` — Hashing transforms specific data into a hash value using a chosen hashing algorithm
+  - `quick.cryptography.encrypt` — Encrypts a specific data using the specified encryption algorithm
+  - `quick.cryptography.decrypt` — Decryption is the process of converting encrypted data back to its original, readable form
+- **`quick.encoding`**
+  - `quick.encoding.atob` — Transforms binary data into a text format to facilitate storage or transmission
+  - `quick.encoding.btoa` — Transforms Base64-encoded data back into its original binary form
+- `quick.integrations`
+- `quick.webScripts`
+- **`quick.workflowStore`**
+  - **`quick.workflowStore.context`**
+    - `quick.workflowStore.context.dataInstance`
+    - `quick.workflowStore.context.processInstance`
+  - **`quick.workflowStore.formContext`**
+    - `quick.workflowStore.formContext.task`
+    - `quick.workflowStore.formContext.form`
+    - `quick.workflowStore.formContext.swimlanes`
+- **`quick.workflow`**
+  - `quick.workflow.RunFunction`
+  - `quick.workflow.Commit`
+- `quick.RunBefunc` — !!! DON'T CHANGE
+- `quick.getConstant`
+- `quick.container`
+- **`quick.devex`** *[TypeScript handlers only]*
+  - `quick.devex.createArrayStore` — Creates an array store with the provided key and data for DevExtreme *[TypeScript handlers only]*
+  - `quick.devex.createCustomStore` — Creates a custom store with the provided loadUrl, key, and load options for DevExtreme *[TypeScript handlers only]*
+  - `quick.devex.createDataSource` — Creates a data source with the provided store for DevExtreme *[TypeScript handlers only]*
+  - `quick.devex.exportDxDataGrid` *[TypeScript handlers only]*
+- **`quick.Math`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Math.floor` — Rounds a number down to the nearest integer *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Math.random` — Generates a random number between the specified minimum (inclusive) and maximum (exclusive) values *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Math.findIndex` — Finds the index of an object in an array based on the specified key and search string *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Math.round` — Rounds a number to the specified number of decimal places *[QScript only (drop the `quick.` prefix when calling)]*
+- `quick.regex` *[QScript only (drop the `quick.` prefix when calling)]*
+- `quick.typeOf` *[QScript only (drop the `quick.` prefix when calling)]*
+- **`quick.Date`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.parse` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.now` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.time` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.compare` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.getTimezoneOffset` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.ISOString` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.differenceInDays` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Date.differenceInMonths` *[QScript only (drop the `quick.` prefix when calling)]*
+- **`quick.Number`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Number.parse` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Number.parseFloat` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.Number.mod` *[QScript only (drop the `quick.` prefix when calling)]*
+- **`quick.JSON`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.JSON.parse` *[QScript only (drop the `quick.` prefix when calling)]*
+- **`quick.string`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.string.space` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.string.replace` *[QScript only (drop the `quick.` prefix when calling)]*
+- `quick.Object` *[QScript only (drop the `quick.` prefix when calling)]*
+- **`quick.js`** *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.js.Object` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.js.String` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.js.Math` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.js.Date` *[QScript only (drop the `quick.` prefix when calling)]*
+  - `quick.js.Number` *[QScript only (drop the `quick.` prefix when calling)]*
+

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/reference/styling-system.md

@@ -0,0 +1,193 @@
+# Styling System (`S` / `SC` / `SA`)
+
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
+>
+> **This file is the `S` track** (`S` / `SC` / `SA` schema). Authoring how-to: [../knowledge/styling.md](../knowledge/styling.md). On a **legacy** page instead (where `S` does not render) → [layout-system.md](layout-system.md).
+
+## Why styling = the `S` object, not CSS
+
+Quick runs on **Web, Android, and iOS**. CSS only exists on Web (DOM). Mobile renders native views. So per-component styling is expressed as a **platform-neutral style object `S`** on the component node, which each platform applies natively:
+
+- **Web**: `S` → CSS rules with `@media` ranges + `[q_UID='…']` selectors (some components have specialized style handlers).
+- **Mobile** (`bridgets componentManager`): `S` → flattened to the single breakpoint range matching the device → promoted to top-level props → `col` converted to flex-basis %, `boxShadow` simplified → passed to the native bridge `nb_createComponent`.
+
+**Consequence:** a project Style File (CSS) styles Web only. To style **cross-platform**, you must use `S` (the Style tab). Author `S`, not CSS, for component visuals.
+
+## 1. Shape of `S`
+
+```ts
+// ICompJson.S : StyleValue
+type StyleValue = Record<string, string | boolean | undefined | Record<string,string>>;
+```
+
+In practice `S` is keyed by **resolution range**, each holding camelCase CSS-like params:
+
+```json
+"S": {
+  "xs-xl": { "backgroundColor": "#1976D2", "paddingLeft": "16px", "fontColor": "#ffffff" },
+  "md-xl": { "fontSize": "18px", "height": "48px" }
+}
+```
+
+- A range key is `"<from>-<to>"` over breakpoints `xs<sm<md<lg<xl`. Default full range `"xs-xl"`.
+- A narrower range (e.g. `"md-xl"`) overrides the base for those device widths (this is "Layout Multiplexing"). Empty string `""` = unset (use component default).
+- Breakpoint widths: `xs` 0, `sm` 600, `md` 960, `lg` 1264, `xl` ∞ (px).
+
+> Note: `S` ranges are inclusive spans over the breakpoints (`"xs-xl"`, `"md-xl"`, …), unlike the legacy `dOpt` keys which are **single** breakpoints.
+
+## 2. Per-component style definitions
+
+Each component declares which style fields it supports, grouped into the Style-tab sections: **LAYOUT**, **TEXT** (often `inheritedStyle:true`), **APPERANCE** (spelled that way in the data). Each group has typed editors (`type` from `COMPONENT_STYLE_TYPE`) that emit specific `param` keys with defaults. **The per-component flattened form of this data — every supported `S` param + default — is bundled in [component-styles.json](component-styles.json); that file is the single source to consult when authoring `S`.**
+
+> **A `default` in `component-styles.json` is only the Style-tab's pre-filled suggestion — it is NOT applied automatically.** Nothing merges these defaults at render; a param takes effect only when you write that `S` key on the node yourself. If you want a listed default value (e.g. `VBtn` `fontColor:#ffffff`), write it into `S` explicitly. (Same rule as [../knowledge/styling.md](../knowledge/styling.md) — the two docs agree on this.)
+
+### Editor types → params they emit (`COMPONENT_STYLE_TYPE`)
+| Editor `type` | Emits these `S` params |
+|---------------|------------------------|
+| `break-point-picker` | `break-point` (the Style-tab's range **selector**, e.g. `"xs-xl"` — it becomes the `S` range **key**, never a param **inside** a range. **Never write `"break-point"` into an `S` range** — it is not in `component-styles.json` and it has frozen the Web runtime.) |
+| `box-layout` | `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left` |
+| `inner-box-layout` | `innerMargin*`, `innerPadding*` (e.g. VTextField) |
+| `padding-input` | `inputPaddingTop/Right/Bottom/Left` |
+| `size` | `width`, `height`, `maxWidth`, `maxHeight`, `minWidth`, `minHeight`, `unlink`, `unlinkMax`, `unlinkMin`, `isSizeCollapsed` |
+| `grid-column` | `col` (1–12 string; `0`→hidden) |
+| `layout-chooser` / `content-direction` | `flexDirection` (`row`/`column`), `alignItems`, `justifyContent` |
+| `font-picker` | `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `combinedFont`, `ThemeFont` (+ `fontColor`) — and multi-part variants (`labelFontColor`, `prefixFontSize`, …) |
+| `color-picker` | one color param (e.g. `backgroundColor`, `fontColor`, `iconColor`); `allowGradient:true` enables gradients |
+| `box-shadow` | `boxShadow` (CSS shadow string) |
+| `border` | per side: `border{Top|Right|Bottom|Left}Style`, `…Width`, radius `border{TopLeft|TopRight|BottomLeft|BottomRight}Radius`, plus `defaultBorderColor`, `boxSizing`, `sides` |
+| `display` | `position`, `top`, `bottom`, `left`, `right`, `zIndex` |
+| `layout-input` / `basic-input` | a single numeric param (e.g. `lineHeight`) |
+| `display-text-align` | `textAlign` |
+| `display-text-decoration` | `textDecorationLine`, `textDecorationStyle`, `textDecorationColor` |
+
+### `IComponentDefinition` fields (per component)
+- the grouped style fields above (per component, in [component-styles.json](component-styles.json)).
+- `propMigrateList` — **old prop → style key** migration. E.g. `VBtn`/`VCard`: `color → backgroundColor`; `VTextField`: `color → labelDefaultFontColor`, `height → height`. (This is why setting a legacy `color` prop maps into `S`.)
+- `inheritedChildList` (→ node `SC`) — cascade a parent style to child sub-components (see §4). Bundled per component in [component-styles.json](component-styles.json) as the `inheritedChildList` key.
+- `propRemoveList` — deprecated props hidden by the editor (e.g. `VBtn`: `small`,`large`,`text`).
+- `parentListToBlockStyle` — under these parents the **Style tab UI** hides the child's own style editing (the parent's tab drives it). E.g. `QLabel` inside `VBtn`/`VChip`/`VTabs`/`VStepper`/…; `VBtn` inside `VBtnToggle`/`VSlideGroup`. **Authoring note:** the serialized page still carries the child's own `S` (the editor writes it — see the button label in [../examples/style/MMDelay.qjson](../examples/style/MMDelay.qjson)); per rule S3 you write the child's full-default `S` alongside the parent's `SC`.
+- `extendedDefaulStyleList` — extra defaults applied at render.
+
+## 3. Property taxonomy (the camelCase keys you put in `S`)
+
+**Spacing:** `marginTop|Right|Bottom|Left`, `paddingTop|Right|Bottom|Left` (+ `inner*`, `inputPadding*`).
+**Size:** `width`, `height`, `maxWidth`, `maxHeight`, `minWidth`, `minHeight`; flags `unlink`, `unlinkMax`, `unlinkMin`, `isSizeCollapsed` (units: px/%/em/rem).
+**Flex/grid:** `col` (1–12), `flexDirection` (`row`/`column`), `alignItems`, `justifyContent`.
+**Text:** `fontColor`, `fontFamily`, `fontSize`, `fontStyle` (`normal`/`italic`), `fontWeight` (`100`–`900`), `combinedFont` (auto `Family-Weight`, e.g. `Roboto-Regular`), `ThemeFont`, `lineHeight`, `textAlign`, `textDecorationLine|Style|Color`. Multi-part components prefix the part: `labelFontColor`, `prefixFontSize`, `PHFontColor` (placeholder), `inputFontColor`, `errorMessageFontColor`, …
+**Colors:** `backgroundColor` (gradient-capable), `fontColor`, `iconColor`; state variants `disabledBackgroundColor`, `hoverColor`, `activeBackgroundColor`, `selectedBackgroundColor`; icon variants `appendIconColor`, `prependInnerIconColor`, `*ActiveIconColor` (component-specific).
+**Border:** `border{Top|Right|Bottom|Left}Style` (`solid`/`dashed`/`dotted`), `…Width` (px), `border{TopLeft|TopRight|BottomLeft|BottomRight}Radius`, `defaultBorderColor`, `boxSizing`, `sides` (CSV `"Top,Right,Bottom,Left"`).
+**Shadow:** `boxShadow` (and `innerBoxShadow`, `hoverShadow`, … per component).
+**Position:** `position`, `top`, `bottom`, `left`, `right`, `zIndex`.
+
+Component-specific params exist (e.g. `VStepper`: `activeStepCircleColor`, `inactiveStepNumberFontColor`; `VTabs`: `tabsBarBackgroundColor`, `activeTabLabelFontColor`; `VDatePicker`: `dateItemSelectedBackgroundColor`). To discover the exact supported set + defaults for a component, read its block in [component-styles.json](component-styles.json) — that file is bundled with the kit and is the only source to use.
+
+### Representative editor-suggested defaults (illustrative only)
+
+> These are Style-tab pre-fill suggestions, **not** values applied automatically — write them into `S` explicitly if you want them. This table is illustrative; the authoritative per-component param list + defaults is [component-styles.json](component-styles.json). **Where this table and `component-styles.json` disagree, `component-styles.json` wins** — never set a param the component's JSON block doesn't list.
+
+| Component | Notable suggested defaults |
+|-----------|------------------|
+| `VBtn` | `backgroundColor:#1976D2`, `fontColor:#ffffff`, `paddingLeft/Right:16px`, border radius `4px`, border width `0px`, `textAlign:center` |
+| `QLabel` | `fontColor:#000000`, `fontFamily:Roboto`, `fontSize:16px`, `fontWeight:400`, `lineHeight:20px`, `textAlign:left` |
+| `VCard` | `backgroundColor:#ffffff`, elevation `boxShadow` set, radius `4px` |
+| `VCol` | `padding*:12px`, `flexDirection:column` |
+| `VContainer` | box-layout + size + position |
+| `VTextField` | five font groups (label/prefix/placeholder/input/errorMessage), inner border (`innerBorderBottomWidth:1px`, `innerDefaultBorderColor:#0000006b`), `activeBorderColor:#1976d2`, icon colors `#686868`/active `#1976d2` |
+
+## 4. Child-style inheritance: `SC` (`IStyleChild`)
+
+```ts
+type IStyleChild = { [styleParam: string]: { [childType: string]: string } };
+```
+Cascades a parent's style param to a typed child as a (possibly renamed) param. Driven by each component's `inheritedChildList` — **bundled per component in [component-styles.json](component-styles.json)** (the `inheritedChildList` key of the component's block, same `{ styleParam: { ChildType: childParam } }` shape; it is SC mapping data, **not** an `S` param). When authoring, copy that block into the node's `SC` as-is; components without one get no `SC`. Example — `VBtn` sets its text color and pushes it into its label/icon children:
+
+```json
+{ "T": "VBtn",
+  "S": { "xs-xl": { "fontColor": "#ffffff", "backgroundColor": "#1976D2", /* …full default set per rule S3… */ } },
+  "SC": {
+    "textAlign": { "QLabel": "textAlign" },
+    "textDecorationLine": { "QLabel": "textDecorationLine" },
+    "textDecorationStyle": { "QLabel": "textDecorationStyle" },
+    "textDecorationColor": { "QLabel": "textDecorationColor" },
+    "fontColor": { "VIcon": "iconColor", "QLabel": "fontColor" },
+    "fontStyle": { "QLabel": "fontStyle" },
+    "fontSize": { "QLabel": "fontSize" },
+    "fontFamily": { "QLabel": "fontFamily" },
+    "fontWeight": { "QLabel": "fontWeight" },
+    "combinedFont": { "QLabel": "combinedFont" },
+    "lineHeight": { "QLabel": "lineHeight" },
+    "ThemeFont": { "QLabel": "ThemeFont" },
+    "backgroundColor": { "VIcon": "backgroundColor" },
+    "disabledBackgroundColor": { "VIcon": "disabledBackgroundColor" }
+  },
+  "C": { "default": { "c": [ /* QLabel + VIcon inherit the above */ ], "cType": "slot" } } }
+```
+
+This is `VBtn`'s **complete** `inheritedChildList` — an `SC` is always the **whole** block copied from [component-styles.json](component-styles.json), never a hand-picked subset (the validator flags `incomplete-SC`).
+This is how a parent pushes its colors into the **text inside a button**, the **icon color**, etc. **It complements — does not replace — the child's own `S`:** per rule S3 the child label/icon also carries its own `S` with its full default set (values matched to the design, e.g. `fontColor:#ffffff` on a primary button's label), exactly as the editor serializes it. Keep both: child `S` + parent `SC`.
+
+## 5. Styled Components (`SA`)
+Reusable named styles created from the Style tab; the node references them via `SA: string[]`. Editing the styled component updates every consumer. Shareable across apps via modules. Normally produced by Studio, not hand-authored.
+
+## 6. Hand-authoring guidance
+- Put **everything** — visual styling (colors, fonts, borders, shadows, exact sizes) and layout (grid/flex/spacing) alike — in `S`, keyed by resolution range. Use `"xs-xl"` for "all sizes", add narrower ranges to override. Do not author `O.layout` (`dOpt`+`class`) here — that is the legacy mechanism, not used on `S`-system pages.
+- Not every component's style schema carries flex params: `VCol`'s `flexDirection`/`alignItems`/`justifyContent`/`col` are real, supported `S` params (check the `VCol` block in `component-styles.json`) and are what drive its rendered flex axis. A `VCol` left with no `S.flexDirection` defaults to a row axis, not the `column` shown as that param's editor-default suggestion — write it explicitly when you want children to stack. Components without those params (`VRow`/`VCard`/`VContainer`, …) generally don't need a direction override; if a design genuinely needs something their `S` schema can't express, the **Web-only, last-resort** fallback is the component's own `class` prop — there is **no** equivalent fallback on Mobile, so restructure with an `S`-capable component (typically a `VCol`) instead.
+- For a container's text/icon child (button label, etc.): give the child its own full-default `S` (values matched to the design) **and** add the parent's `SC` mapping (mirror the component's `inheritedChildList`).
+- **Emit every default (rule S3):** a placed component's `S` includes every param that carries a `default` in its [component-styles.json](component-styles.json) block — the default value, or your override. Params with no default are optional.
+- Values are camelCase keys with string values; sizes accept `px`/`%`/`em`/`rem`; `""` = unset.
+- For the exact supported params + defaults of a specific component, consult its block in [component-styles.json](component-styles.json) (bundled with the kit — never a source file outside this workspace).
+- Theme colors/fonts (Themes Settings) appear in the Style tab; prefer them for brand consistency — they're still values you put in `S`, not a separate mechanism.
+
+## 7. Containment rules (shared, editor-enforced)
+
+> Containment is enforced identically regardless of style era.
+
+| Rule | From |
+|------|------|
+| `VCol` must be a child of `VRow`; cannot be at page root | `VColExtension.acceptableParentComps={VRow}` + `restrictedComponents` + `layout.md` |
+| `VRow` accepts only `VCol` children | `VRowExtension.acceptableChildComps={VCol}` |
+| `VFooter` accepts only `VContainer` children | `VFooterExtension.acceptableChildComps={VContainer}` |
+
+Other components have no hard accept-list, but container components with item parts use fixed child generators (place `VTab`/`VTabItem` in `VTabs`, `VStepperStep`/`VStepperContent` in `VStepper`, etc.). Canonical page wrapper: `VContainer > VRow > VCol > content`. For a **newly-created page this `VContainer` content root is required**: wrap all UI content in a single top-level `VContainer`, with only `Messaging` and an optional service component as other top-level `pJson` siblings. This is a **new-page rule only** — do **not** retrofit a `VContainer` root onto an existing page unless the user explicitly asks. Machine-readable: [component-index.json](component-index.json) `containmentRules`.
+
+## 8. Breakpoint device ranges (shared)
+
+> `S` ranges (e.g. `"xs-xl"`, `"md-xl"`) are built from these same device boundaries.
+
+| Key | Device | Min px | Max px |
+|-----|--------|--------|--------|
+| `xs` | Mobile | 0 | 600 |
+| `sm` | Tablet | 600 | 960 |
+| `md` | Laptop | 960 | 1264 |
+| `lg` | Desktop | 1264 | 1904 |
+| `xl` | TV | 1904 | ∞ |
+
+## 9. `class` token → `S` equivalent (audit reference)
+
+> Full table: [mapping-S-vuetify-class.md](mapping-S-vuetify-class.md). This table is a **live dependency** of the class-prop audit rule (§6 above and the `S`-system final checklist at the end of [../knowledge/styling.md](../knowledge/styling.md)): before writing any `class` token as the Web-only last resort, check it here — if an `S` equivalent exists, write `S` and drop the token.
+
+**Has an `S` equivalent (don't leave in `class` if `S` is set):**
+
+| Class token | `S` equivalent |
+|---|---|
+| `pa-N` / `px-N` / `py-N` / `pt-N`/`pb-N`/`pl-N`/`pr-N` | `padding{Top,Right,Bottom,Left}` = `"Npx"` (Vuetify step `N` × 4px) |
+| `ma-N` / `mx-N` / `my-N` / `mt-N`/`mb-N`/`ml-N`/`mr-N` / `mx-auto` | `margin{Top,Right,Bottom,Left}` = `"Npx"` / `"auto"` |
+| `fill-height` | `height: "100%"` |
+| `d-flex` / `flex-row` / `flex-column` / `flex-row-reverse` / `flex-column-reverse` | `flexDirection: "row"/"column"/"row-reverse"/"column-reverse"` (`VCol`-only param) |
+| `justify-start/center/end/space-between/space-around` | `justifyContent` (`VCol`-only param) |
+| `align-start/center/end/baseline/stretch` | `alignItems` (`VCol`-only param) |
+| `text-h1`…`h6`, `text-subtitle-*`, `text-body-*`, `text-button`, `text-caption`, `text-overline` | `fontSize` + `fontWeight` + `lineHeight` |
+| `font-weight-*` | `fontWeight: "100"…"900"` |
+| `font-italic` | `fontStyle: "italic"` |
+| `text-left/center/right/justify` | `textAlign` |
+| `text-decoration-none/underline/line-through` | `textDecorationLine` |
+| `<color>--text` | `fontColor` |
+| `elevation-0`…`24` | `boxShadow` |
+| `rounded*` | `borderTopLeftRadius`+`borderTopRightRadius`+`borderBottomLeftRadius`+`borderBottomRightRadius` |
+| theme background color classes | `backgroundColor` |
+
+**No `S` equivalent** (informational — leave out of the conflict check): `text-uppercase/lowercase/capitalize`, `text-truncate`, `text-no-wrap`, `d-none/d-block/d-inline` (visibility), `flex-grow-*`/`flex-shrink-*`, `order-*`, `overflow-*`, responsive/breakpoint variants (`d-md-flex`, `pa-md-4` — `S` manages breakpoints separately via range keys).
+
+Full token-by-token table (Turkish) + the legacy-migration framing: [mapping-S-vuetify-class.md](mapping-S-vuetify-class.md).
+
+Practical how-to and copy-paste patterns: [../knowledge/styling.md](../knowledge/styling.md).

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/s-track.md

@@ -0,0 +1,30 @@
+# Quick qjson — `S` system track
+
+> **Style system: `S` (new).** Follow this guide when the target is an `S`-system page — a new page, or one whose root-level `opt.V >= 2.0`. If the page is legacy (`opt.V` missing or `< 2.0`), stop and use [legacy-track.md](legacy-track.md) instead. Shared workflow, shared docs, and shared rules are in the dispatcher [index.md](index.md); this guide adds the `S`-track doc set and the styling/layout rules.
+
+## The `S`-track doc set (open only these + the shared docs)
+- **Schema** → [reference/qjson-schema.md](reference/qjson-schema.md)
+- **Structure (start here)** → [knowledge/qjson-structure.md](knowledge/qjson-structure.md)
+- **Layout & slots** → [knowledge/layout-and-slots.md](knowledge/layout-and-slots.md)
+- **Styling how-to** → [knowledge/styling.md](knowledge/styling.md)
+- **Styling reference (`S`/`SC`/`SA` schema)** → [reference/styling-system.md](reference/styling-system.md)
+- **Component catalog** → [reference/component-catalog.md](reference/component-catalog.md)
+- **Page skeletons** → [knowledge/page-skeletons.md](knowledge/page-skeletons.md)
+- **Repeated rows/cards from data** → [knowledge/dynamic-components.md](knowledge/dynamic-components.md)
+- **Validation (final checklist)** → [knowledge/validation.md](knowledge/validation.md)
+- **Examples** → [examples/style/](examples/style/) only
+
+## Build & style
+1. **Build from a skeleton**, top-down (`Messaging` → optional service component → `VContainer` → rows/cols/cards → content). **A new page's `VContainer` content root is required** (rule S4 below), and **set the new page's `opt.V: 2.5`** (the current schema version — this is what makes it an `S`-system page). For large/visual pages, add **1–3 sections per edit** — never rewrite a whole page in one shot. Copy a skeleton from [knowledge/page-skeletons.md](knowledge/page-skeletons.md).
+2. **Style every component you add — set its `S` tag. Don't skip this.** `S` is the mechanism for *all* per-component design, layout included — size, spacing, grid column, flex direction/align/justify, colors, fonts, borders, shadows — keyed by resolution range (`"xs-xl"` = all sizes). For each node, set its `S` params from [reference/component-styles.json](reference/component-styles.json) — **including every param that carries a `default` in that component's block** (rule S3 below: write the default or your override, never omit it). If the component's block carries an `inheritedChildList`, copy it into the node's `SC` as-is (styles a child through its parent — `VBtn`/`VChip`/`VTabs` labels/icons) *in addition to* the child's own `S`, not instead of it. How-to: [knowledge/styling.md](knowledge/styling.md). **This is the single most-skipped step — a page returned without `S` is unstyled. Treat it as required.** Only when a component's `S` schema genuinely has no param for what you need: on **Web** you may set the `class` prop directly, as a last resort; on **Mobile** there is **no** `class` fallback — restructure with an `S`-capable component instead.
+   - **Token-by-token `class` justification (before writing any `class` prop):** list every CSS token you are about to write; check the `class → S` table in [reference/styling-system.md](reference/styling-system.md) §9 — if an `S` equivalent exists, write the `S` param and drop the token. Only tokens with confirmed no `S` equivalent belong in `class`. Never bulk-copy a class string. **Violation example:** `class: 'fill-height'` when `S.height:"100%"` is set — `fill-height` = `height:100%`, so drop the class token.
+   - **Big pages get a dedicated styling pass:** if the page has more than ~15 visual components, or is a dashboard/landing/hero recreating a visual design, don't style ad-hoc while building. Finish the structural pass first, then read [knowledge/styling.md](knowledge/styling.md) and run a focused styling pass over every node you flagged. Styling inline as you build is fine for small pages or single-component tweaks.
+3. **Validate** against [knowledge/validation.md](knowledge/validation.md) (shared core + `S` style checklist), then compile.
+
+## Non-negotiable `S`-track rules
+- **S1 — Don't author `O.layout`.** It's the legacy mechanism and does not belong on an `S` page. Size columns and any flex/grid/spacing intent via `S` instead: `S.col` for grid width, `S.flexDirection`/`alignItems`/`justifyContent` where the component's style block supports them (check [reference/component-styles.json](reference/component-styles.json)). **Do NOT use Vuetify's responsive column props** (`VCol.cols`/`.sm`/`.md`/`.lg`/`.xl`) — use `S.col` + resolution ranges (e.g. `"xs-sm": {"col":"12"}, "md-xl": {"col":"6"}`). Do NOT use `VRow.justify`/`VRow.align` props as style substitutes — if `S` can't express it on those components, that is the Web-only `class`-last-resort case.
+- **S2 — Prefer `S` over a Vuetify style-prop even when the prop is valid.** E.g. don't set `cols`/`sm`/`md`/`lg`/`xl` on `VCol` when `S.col` covers it; don't set `color` on `VBtn`/`VCard` when `S.backgroundColor` covers it; don't set the `elevation` prop when `S.boxShadow` covers it.
+- **S3 — Don't ship structure-only pages, and emit every default.** Every component you place gets an `S` object (range-keyed), and that `S` must include **ALL params that carry a `default` in the component's [reference/component-styles.json](reference/component-styles.json) block** — write the default value as-is, or your design's value where it differs. Never omit a default-valued param on the assumption it applies anyway (it does not — nothing merges defaults at render). For a component with a text/icon child (`VBtn`, `VChip`, `VTab`, …): the parent's own `S` still carries its full default set (fonts included), the child label/icon **also** carries its own `S` with its full default set (values matched to the design — e.g. white label text on a primary button), and the parent gets an **`SC`** — **copy the component's `inheritedChildList` block from [reference/component-styles.json](reference/component-styles.json) into `SC` as-is — the WHOLE block, never a hand-picked subset** (`VBtn`'s has 14 params, not just `fontColor`+`backgroundColor`; the validator reports `incomplete-SC`). Only components whose JSON block has an `inheritedChildList` get an `SC`; never invent mappings, never put `SC` on a component without one. Skipping `S` is the most common miss — it is not optional.
+- **S4 — New-page content root = `VContainer`.** A newly-created page must wrap all UI/visual content in a single top-level `VContainer`; the only non-`VContainer` top-level `pJson` siblings allowed are the non-visual `Messaging` event hub and an optional service component — `pJson: [Messaging, service?, VContainer{ … }]`. **New pages only:** when editing an existing page, keep its current root and do NOT insert a `VContainer` unless the user asks (real pages legitimately root on `VAppBar`, `VDataTable`, etc.).
+- **S5 — A multi-child `VCol` doesn't stack for free.** `VCol`'s flex direction defaults to row unless set — fix stacking with `"S": {"xs-xl": {"flexDirection": "column"}}` on that `VCol`. See the gotcha + copy-paste label/value pattern in [knowledge/layout-and-slots.md](knowledge/layout-and-slots.md).
+- **S6 — CSS Style Files are a Web-only true last resort** (project-level CSS, `@font-face`) — for cross-cutting rules neither `S` nor a component's `class` prop can express. Never rely on CSS for anything that must work on Mobile (no CSS there).

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/skills/quick-qjson/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: quick-qjson
+description: Create, edit, review, style, or validate Quick / Plateau Studio .qjson UI pages. Load this skill for ANY task that touches a file with the .qjson extension — building a new page, editing or fixing an existing one (even a one-line tweak or typo fix), styling/layout changes, events/scripting, services, localization, or validation. Also load it the moment you encounter a .qjson file mid-task, even if the request never mentions qjson. Covers the qjson schema, the quick.* scripting API, the component registry, and the styling/layout/events systems.
+---
+
+# Quick QJSON authoring
+
+The complete, source-grounded knowledge for **Quick / Plateau Studio `.qjson`** UI pages lives in the **`ui-kit/`** folder — locate it in your workspace (e.g. `.ai-kit/ui-kit/`) and treat it as authoritative over any prior assumptions about Quick.
+
+**Read `ui-kit/index.md` and follow it.** Its Step 0 routes you to the right style track (`S` vs legacy — never mixed on a page), its non-negotiable rules apply to every edit, and it maps which knowledge/reference docs to open for the task at hand. Don't load everything up front — open only your track's docs plus the shared ones it lists.

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

@@ -0,0 +1,70 @@
+# Plateau workflow app — agent guide (start here)
+
+You are an AI coding agent working on a **Plateau Studio workflow app**: a business process (`.workflow`) and the models that make it run — flows, actions, access models, data types, services, and the `.qjson` forms users see. These docs are the source of truth for the workflow domain. Follow this guide.
+
+## Where to look
+
+**Exact file syntax** — the field-by-field shape of the raw file, to open whenever you author or edit one. Each manual is complete on its own:
+
+| Extension | Manual | Notes |
+|-----------|--------|-------|
+| `.workflow` | [models/workflow/workflow-syntax.md](models/workflow/workflow-syntax.md) | The process itself: steps, connections, store, references. One file per step type under `models/workflow/steps/`. |
+| `.flow` | [models/flow/flow-syntax.md](models/flow/flow-syntax.md) | The function models: steps, connections, store, mappings. One file per step type under `models/flow/steps/`. |
+| `.dataType` | [dataType-syntax.md](../platform/models/dataType-syntax.md) | Business data shapes, including persisted entities and their queries. |
+| `.dataSet` | [dataSet-syntax.md](../platform/models/dataSet-syntax.md) | Closed lists of allowed values. |
+| `.constant` | [constant-syntax.md](../platform/models/constant-syntax.md) | One configuration value per environment. |
+| `.restService` | [rest-service-syntax.md](../platform/models/rest-service-syntax.md) | One external HTTP endpoint. |
+| `.soapServiceV2` | [soap-service-v2-syntax.md](../platform/models/soap-service-v2-syntax.md) | One SOAP operation, driven by a WSDL imported in Studio. The import is a user action — you edit the result, you do not create it. |
+| `.soapService` | [soap-service-syntax.md](../platform/models/soap-service-syntax.md) | The earlier SOAP model. Legacy: maintain existing ones, never create new. |
+| `.decisionTable` | [decision-table-syntax.md](models/decision-table-syntax.md) | Business rules as a table: condition columns, result columns, and the row order that decides. |
+| `.action` | [action-syntax.md](models/action-syntax.md) | The buttons a user task shows: the function each runs, its form, its privileges. |
+| `.privilege` | [access-manager/privilege-syntax.md](models/access-manager/privilege-syntax.md) | Named permissions — the labels everything else asks for. |
+| `.role` | [access-manager/role-syntax.md](models/access-manager/role-syntax.md) | Permission packages: privileges, process permissions, inheritance. |
+| `.swimlane` | [access-manager/swimlane-syntax.md](models/access-manager/swimlane-syntax.md) | The lanes a user task is assigned to, and the roles behind each. |
+| `.persona` | [access-manager/persona-syntax.md](models/access-manager/persona-syntax.md) | The roles a user carries at runtime. |
+| `.sla` | [sla-syntax.md](models/sla-syntax.md) | Time milestones and escalation for a process or a task. |
+| `.appSettings` | [app-settings-syntax.md](models/app-settings-syntax.md) | The app-level settings singleton. |
+| `.auth` | [auth-syntax.md](models/auth-syntax.md) | How callers of the app's API authenticate, and which function turns one into a runtime user. |
+
+Every model type a workflow app touches is covered above. If you meet a file whose type is not in the table, it has no manual and is not described anywhere else either: mirror a sibling model of the same type in the workspace and change as little as possible, and when there is no sibling to copy, stop and say so rather than inventing a shape — a guessed file is rejected by Studio or, worse, saves as a model whose items no reference can resolve.
+
+**Guides** — procedures that span models:
+
+- [models/workflow-ui-pages.md](models/workflow-ui-pages.md) — what a page gains in a workflow app: the master page and its blocks, process data and two-way binding, overrides, TaskPreview
+
+Expressions, mappings and the operators shared by several model types are documented inside the manual of the type that uses them; there is no separate shared-syntax file. There is no separate checklist file either: before finishing, go back over the manual's own **What blocks a save** and **Easy to get wrong** sections, and for a type whose manual has neither, over its field tables.
+
+## Every model file
+
+Everything in a Plateau Studio app is a **model**, and every model is one file in the workspace whose extension is its type. Whatever the type, these hold:
+
+- **The extension is the type.** The filename without it is the model's name, and the folder it sits in is the path other models reference it by.
+- **The metadata header is identity.** A pulled file starts with a `---studio-metadata DO NOT EDIT---` block; never edit, reorder or strip it. A file you create from scratch has none — write the body alone and Studio adds the header once the model reaches it.
+- **References are `<<type:target>>`**, where `target` is the referenced model's path without the file extension, **always counted from the workspace root** — never relative to the folder the referencing file sits in, and never shortened because the two models happen to be neighbours. A dataType at `common/Customer.dataType` is written `<<dataType:common/Customer>>`; one at `hr/leave/Request.dataType` is `<<dataType:hr/leave/Request>>` no matter where it is referenced from. Getting this wrong is quiet: the file stays valid JSON, push cannot match the path to a model, and the reference reaches Studio as unresolvable text — the target's name shows up as a raw string and pickers that should list it come up empty. Write the full form every time, pointing at a file that is really in the workspace. Some older files carry a raw model id instead — leave those alone, but never write a new one and never copy a reference out of another model, because those ids belong to the app they came from.
+- **The reference syntax is recognized anywhere in the body**, not only in the fields meant to hold one. Studio scans the whole text: a `<<type:…>>` written inside a description or any other free-text value is rewritten like a real reference and makes the model depend on a target it never uses. Name such a model in plain words instead — `common/inventory_api_key`, not `<<constant:common/inventory_api_key>>`.
+- **Bodies are JSON**, except for content models such as `.wsdl`, whose body is the raw file.
+
+Per-type rules — required keys, defaults, allowed expression types, what is generated and must be left alone — live in the manual for that type, and only there.
+
+## When a file in the workspace disagrees with the manual
+
+Both are evidence, about different things.
+
+- **On what the platform accepts** — field names, structures, which key a value lands under, the exact spelling of something generated — the files in the workspace win. They are what Studio produced and reads back, so a manual that contradicts them is out of date.
+- **On how to author** — which of two working forms to write, where a value belongs, what a field is for — the manual wins, especially where it states a consequence. A neighbouring file may simply be older, or written before the rule existed; that it runs is not evidence that it is the way to do it.
+
+Copying a pattern out of a sibling file is a good way to get the shape right and a poor way to choose an approach. When the two sources disagree, follow the split above, and say so in the report: which file, which rule, which way you went. Reproducing a questionable pattern silently is the one option that is always wrong.
+
+
+
+## This workspace: the studio CLI loop
+
+These models were pulled from Studio with the studio CLI and will be synced back. On top of the rules above:
+
+- **Validate before finishing.** Model files have no local compiler — walk this manual's validation checklist and fix every issue yourself. `.qjson` pages are the exception: they compile with `studio buildQjson <file-or-folder>`, per the qjson manual ([`../ui-kit/index.md`](../ui-kit/index.md)).
+- **Sync.** Once the checks pass and `.studio/server.json` exists (the CLI bridge is running), run `studio push` yourself — the models land in the user's open Studio session as unsaved work. Then ask the user to open each changed `.workflow`/`.flow` in its editor and save, so Studio regenerates the runtime body and reports anything the editor rejects. Round-trip rules, metadata headers, reference translation: [`../cli-kit/knowledge/sync.md`](../cli-kit/knowledge/sync.md).
+- **Locked files.** A pulled model may be readonly (`0444`) — checked out by someone else, or owned by an imported module. Run `studio startWorking <file>`; never `chmod`. Imported-module models never unlock — customize them through an override instead.
+- **Read the push output, don't just check that it succeeded.** An `[modelRefs] unresolved reference <<type:path>>` line means that reference reached Studio as plain text: the path is wrong, or the model it names was pushed after the file that references it. Push says success either way. Fix the path or the order and push again — details in [`../cli-kit/knowledge/sync.md`](../cli-kit/knowledge/sync.md).
+- **Report** the checklist result and the push result, including any unresolved-reference lines. If the bridge wasn't available, say so — never skip silently.
+
+Bridge setup and troubleshooting: [`../cli-kit/knowledge/cli-bridge.md`](../cli-kit/knowledge/cli-bridge.md).