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

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/appSettings/theme.md

@@ -0,0 +1,58 @@
+# Theme · the app's named colors and fonts
+
+The app's design tokens: a set of **named colors** and **named fonts**, each with a light and optional dark variant. Pages don't hard-code hex values — they pick a theme entry in the Style tab, so re-theming the app is one file change.
+
+Selected in **App Settings → Themes** → [appSettings.md](appSettings.md).
+
+## Structure
+
+One theme file holds **several themes**; each theme has a light variant and an optional dark one; each variant carries colors and fonts.
+
+```
+theme file
+└─ themes[]
+   ├─ name
+   ├─ lightTheme
+   │  ├─ colors[]  { name, color, allowGradient }
+   │  └─ fonts[]   { fontClassName, configs }
+   └─ darkTheme?   (same shape)
+```
+
+A font's `configs` carry `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `fontColor`, `displayWeight` and `combinedFont`. Weights run `Thin - 100` … `Weight - 1000`.
+
+Alongside the file selection, App Settings stores which theme is the **default** — the one the app starts with.
+
+## How it reaches your pages
+
+Theme colors and fonts show up as **selectable options in the Style tab**; choosing one writes into the node's `S` object (a theme font lands as `combinedFont` / `ThemeFont`). There is no separate "theme" syntax in a page → [../styling.md](../styling.md).
+
+So the chain is: theme file → App Settings selection → Style tab options → `S` on your nodes.
+
+## Switching at runtime
+
+| Call | Does |
+|---|---|
+| `quick.Quick.theme.setTheme(name, isLight?)` | Switch to a theme by name; `isLight` picks the light or dark variant. |
+| `quick.Quick.theme.getThemeList()` | The available theme names. |
+| `quick.Quick.theme.addTheme(name)` | Add a theme at runtime. |
+| `quick.Quick.theme.removeTheme(name)` | Remove one. |
+
+Dark mode is a **variant of a theme**, not a separate theme — switch with the `isLight` flag rather than maintaining two theme entries.
+
+## Migration on older apps
+
+Apps built before themes became shareable files kept their theme inline in App Settings, with no theme file at all. Those apps get a **Theme Migration Required** prompt on the Themes tab and a **Migrate** button that lifts the inline theme into a real theme file.
+
+Until it is migrated the theme setting counts as unassigned — the tab is flagged and **Export and Publish are blocked**. You cannot migrate from the CLI; report it and let the user press Migrate in Studio.
+
+## Fonts
+
+Custom fonts are added as files and then become selectable in the Style tab's Text section. The documented formats are `.woff`, `.woff2` and `.ttf` (`.otf` is also handled by the platform's font pipeline).
+
+## Rules that prevent the common failures
+
+- Don't hard-code colors in `S` when the theme defines a named one — you break re-theming and dark mode.
+- Dark mode comes from the theme's dark variant; don't build a second theme to fake it.
+- A theme file that exists but is not selected in App Settings does nothing.
+- On an unmigrated app, fix the migration before anything else — every other theme change is moot until then.
+- Theme values surface **through the Style tab into `S`**; there is no page-level theme override syntax to author by hand.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/components.md

@@ -0,0 +1,105 @@
+# Components (how to use)
+
+Pick the `T` from [reference/component-catalog.md](../reference/component-catalog.md) / [reference/component-index.json](../reference/component-index.json). The catalog has the full list and per-component criticals; this file shows the build patterns you reach for most.
+
+## QLabel (text)
+```json
+{ "T": "QLabel", "P": { "ID": { "H": "lblTitle", "T": "prop" },
+    "text": { "H": "'Page Title'", "T": "prop" },
+    "class": { "H": "'text-h5 font-weight-bold primary--text'", "T": "class" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
+```
+
+## Button with label (VBtn + child QLabel)
+```json
+{ "T": "VBtn", "P": { "ID": { "H": "btnSave", "T": "prop" },
+    "color": { "H": "'primary'", "T": "prop" },
+    "depressed": { "H": "true", "T": "prop" } },
+  "E": { "click": { "H": "quick.MM.trigger('save');\r\n", "P": "mouseEvent:unknown | undefined", "HL": "TS" } },
+  "C": { "default": { "c": [
+    { "T": "QLabel", "P": { "ID": { "H": "lblSave", "T": "prop" },
+        "text": { "H": "'Kaydet'", "T": "prop" },
+        "class": { "H": "'white--text font-weight-bold'", "T": "class" } },
+      "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblSave" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "btnSave" } }
+```
+
+## Icon (note the PType)
+```json
+{ "T": "VIcon", "P": { "ID": { "H": "icEye", "T": "prop" },
+    "text": { "H": "'mdi-eye'", "T": "text" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icEye" } }
+```
+
+## DataTable (headers/items in props, scoped action slot)
+```json
+{ "T": "VDataTable", "P": { "ID": { "H": "tblItems", "T": "prop" },
+    "headers": { "H": "[{text='Name', value='name', sortable=true}, {text='Actions', value='actions', sortable=false, align='center'}]", "T": "prop" },
+    "items": { "H": "[]", "T": "prop" },
+    "itemsPerPage": { "H": "10", "T": "prop" } },
+  "E": { "click:row": { "H": "quick.store.set('selected', index);\r\n", "P": "index:any,row:any", "HL": "TS" } },
+  "C": { "item.actions": { "c": [ /* VBtn with item.<field> bindings */ ], "cType": "scopedSlot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "tblItems" } }
+```
+- `headers`/static `items` are QScript props with `=` keys. Dynamic rows: `components.tblItems.items = rows;` in a callback.
+- `click:row` → `index` is the row data object.
+
+## Dialog (open/close + non-persistent close)
+```json
+{ "T": "VDialog", "P": { "ID": { "H": "dlgDetail", "T": "prop" },
+    "width": { "H": "'700px'", "T": "prop" },
+    "persistent": { "H": "false", "T": "prop" },
+    "Render": { "H": "true", "T": "prop" }, "eager": { "H": "true", "T": "prop" } },
+  "E": { "click:outside": { "H": "components.dlgDetail.qValue=false;\r\n", "HL": "TS" } },
+  "C": { "default": { "c": [ /* VCard content */ ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "dlgDetail" } }
+```
+Open: `components.dlgDetail.qValue = true;`. Add `Render:true`+`eager:true` to touch inner components before opening.
+
+## Tabs (VTab + VTabItem sibling pairs)
+```json
+{ "T": "VTabs", "P": { "ID": { "H": "tabsMain", "T": "prop" } },
+  "E": {}, "C": { "default": { "c": [
+    { "T": "VTab", "P": { "ID": { "H": "tabGeneral", "T": "prop" } }, "E": {},
+      "C": { "default": { "c": [ /* QLabel 'General' */ ], "cType": "slot" } },
+      "O": { "cType": "slot" }, "_Editor": { "eID": "tabGeneral" } },
+    { "T": "VTabItem", "P": { "ID": { "H": "tabItemGeneral", "T": "prop" } }, "E": {},
+      "C": { "default": { "c": [ /* VContainer > VRow > VCol > content */ ], "cType": "slot" } },
+      "O": { "cType": "slot" }, "_Editor": { "eID": "tabItemGeneral" } }
+    /* , VTab 'Details', VTabItem 'Details', … */
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "tabsMain" } }
+```
+- `VTab` and `VTabItem` are **siblings** in `VTabs.C.default.c`, ordered as header/panel pairs: `VTab₁, VTabItem₁, VTab₂, VTabItem₂, …`. `VTabItem` is **never** a child of `VTab`.
+- Every `VTab` has exactly one `VTabItem` in the same group — same count, same order.
+- `VTab` holds only the visible label (a child `QLabel`). `VTabItem` holds that tab's page content.
+- Panel content: `VTabItem > VContainer > VRow > VCol > content`. Don't put content directly in `VTabItem`.
+- Put the `VTabItem`s directly in `VTabs`, paired with their `VTab`s.
+- The bundled examples show the pairing correctly but put a bare `VBtn` (or no `VCol`) in the panel — that's a minimal demo, not the content pattern.
+
+## Select / Autocomplete
+```json
+"items": { "H": "[{text='Istanbul', value=1}, {text='Ankara', value=2}]", "T": "prop" }
+```
+For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
+
+## Pagination
+`length`/`totalVisible` are string values; `input` handler starts with `quick.this.qValue = number;` (`"P":"number:number"`).
+
+## Block Component (embedding another qjson page)
+Place at `pJson` root level — **not** inside VContainer. Minimal node; no Ghost child, no `dynProps`.
+```json
+{ "T": "CustomComponent", "P": {
+    "ID": { "H": "blockMyPage", "T": "prop" },
+    "QJsonPath": { "H": "'<<qjson:path/to/page>>'", "T": "prop" } },
+  "E": {}, "C": {}, "O": {}, "_Editor": { "eID": "blockMyPage" } }
+```
+`QJsonPath` format: `'<<qjson:path>>'` — project-relative path without extension. Root-level page: `<<qjson:page-name>>`; nested: `<<qjson:folder/page-name>>`. Studio stores these internally as model IDs; in files you always write the path form — never a raw ID.
+
+**The embedded page must itself be a block component in Studio.** If it isn't one yet, it must be converted on the Studio side (via the workspace's tooling). This applies only to block-component embeds, not to service-caller embeds (below).
+
+## Messaging / service component / Ghost
+`Messaging` (`O.cType:"child"`) is the event hub. A project **service caller** `CustomComponent` (different from a block component — has `O:{cType:"child",dynProps:true}` and a `Ghost` child) embeds a service-proxy `.qjson` via `QJsonPath`. See [services.md](services.md) and [page-skeletons.md](page-skeletons.md).
+
+For any prop/event/slot not shown here, consult [reference/component-catalog.md](../reference/component-catalog.md); for Vuetify components, Vuetify 2 semantics apply.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/container-configuration.md

@@ -0,0 +1,157 @@
+# Container Configuration · calling the host from a page
+
+An app that runs inside a host — a shell, a native wrapper, a portal — can call functions the host exposes.
+Which functions exist is not discovered at runtime: the app **declares** them in a **Container
+Configuration**, and each declared entry becomes a method on `quick.container`.
+
+```ts
+const res = await (<any>quick.container).SomeHostFunction();
+```
+
+A Container Configuration is a **model**, not a setting file. It is created from **+ Add New → Application
+Configuration → Container Configuration**, stored as a `.container` file, and is **never selected in App
+Settings** — it takes effect on its own. Do not confuse it with the **Container Services File**, the JS
+module of low-level callbacks the runtime calls → [appSettings/container-services-file.md](appSettings/container-services-file.md).
+
+Each entry also carries a **mock**, which is what the function returns while the app runs in Studio. That
+is what lets a page that depends on host data render during development; the real host answers only once
+the app runs inside it.
+
+## One container file per app
+
+**One container file, and only one.** Look for the existing one before you create anything.
+
+Studio does not stop you from making a second — it merges the functions of *every* container model into one
+set, last one wins by `funcName`. So a second file does not raise an error, it silently shadows entries in
+the first. That is exactly why this is a rule.
+
+## Finding or creating it
+
+Before a page calls a host function, make sure the file exists and declares what the page calls:
+
+1. **Look for it:** any `*.container` file in the workspace outside `.ai-kit/`.
+2. **Found → use it.** Add any function the page needs that is missing. Do not create a second file, and do
+   not touch the mocks already in it. If it is readonly, run `studio startWorking <file>` first.
+3. **Not found → create it:**
+   1. Create `hostFunctions.container` at the workspace root containing only the frontmatter:
+
+      ```text
+      ---studio-metadata DO NOT EDIT---
+      id: new
+      settingKey: container
+      ---studio-metadata DO NOT EDIT---
+      ```
+
+   2. `studio push`. Studio creates the Container Configuration and writes its real `id` and a starter body
+      back into the file.
+   3. Replace the body — everything below the frontmatter — with your function declarations. Leave the
+      frontmatter as Studio wrote it.
+   4. `studio push` again.
+
+   If push rejects `settingKey: container`, stop and ask the user to create one in Studio (**+ Add New →
+   Application Configuration → Container Configuration**) and pull it, then continue from step 3.
+
+## What an entry looks like
+
+The body is a single `{ "functions": [ … ] }` array. Each entry:
+
+```json
+{
+    "funcName": "SomeHostFunction",
+    "parameters": [],
+    "returnValue": {
+        "objectContent": "{ isSuccess: boolean, retVal: { … } }",
+        "returnValueType": "object"
+    },
+    "mock": {
+        "mockBody": "{\"isSuccess\": true, \"retVal\": {}}",
+        "mockType": "static"
+    }
+}
+```
+
+- `funcName` is the method name the page calls. It must match exactly.
+- `returnValue.objectContent` is the return shape, written as a TypeScript type string. Studio parses it to
+  generate the mock, and understands object literals, `Array<T>` / `T[]` and the primitives —
+  **not union types and not optional (`?`) fields**. Either of those yields `null` or an "unknown type"
+  placeholder in the generated mock, so keep the shape plain and make every field concrete.
+- `mock.mockBody` is a **JSON string**, not an object — the quotes inside are escaped.
+- `mockType` is `"static"`.
+
+## Calling a function
+
+```ts
+async function loadFromHost() {
+    try {
+        const res = await (<any>quick.container).SomeHostFunction();
+        if (res?.isSuccess !== true) {
+            showError("Bilgiler alınamadı.");
+            return;
+        }
+        quick.store.set('$value', res.retVal.someField);
+    } catch (err) {
+        quick.EM.trace("SomeHostFunction failed: " + err);
+        showError("Servisle iletişim kurulamadı.");
+    }
+}
+
+function showError(message: string) {
+    components.errorLbl.text = message;
+    components.failDia.qValue = true;
+}
+
+loadFromHost();
+```
+
+- **Call through `(<any>quick.container)`.** `studio buildQjson` cannot see the container file and types
+  `quick.container` as `{}`, so a bare `quick.container.SomeHostFunction()` fails validation with
+  *Property 'SomeHostFunction' does not exist on type '{}'*. The cast changes only the type check — do not
+  "fix" it away. It also means validation will **not** catch a call to a function the file does not
+  declare: that surfaces only at runtime.
+- **A function a page calls must be declared in the container file.** Adding the call is not enough.
+- **Handle both failure shapes.** A call can reject, or resolve with `isSuccess !== true`. Handle both and
+  show the user an error rather than rendering empty fields.
+- **Several calls run one after another.** `await` each before starting the next. Firing them in parallel
+  (`Promise.all`, or several un-awaited calls) does not work.
+- **Fetch in `PostRender`** when the result populates the page, so the tree exists when the value arrives.
+- **Handlers are TypeScript.** Set `"HL":"TS"` on every one — the cast is TypeScript syntax.
+
+## The mocks belong to the user
+
+Each entry's `mock.mockBody` is what the function returns while the app runs in Studio. Any values a
+template or a starter body ships with are placeholders: the user changes them in Studio's Container
+Configuration editor to try other cases.
+
+- **Never reset a mock the user has changed.**
+- **Never put real customer data in a mock.**
+
+## `quick.Quick.host.trigger` is the deprecated predecessor
+
+The same calls used to be made by name through `host.trigger`, and most existing pages still look like this:
+
+```ts
+quick.Quick.host.trigger("SomeHostFunction", {}).then(response => {
+    if (response.isSuccess === true) {
+        let value = response.retVal["someField"];
+    }
+});
+```
+
+The payload shape is the same. Several calls on such a page are nested inside each other's `.then()`, for
+the same reason new code awaits them in sequence.
+
+- **Leave existing calls as they are** unless the user asks you to migrate the page.
+- **Anything you add is `quick.container`** — even on a page that otherwise uses `host.trigger`. Make sure
+  the function is declared in the container file.
+- **`host.trigger` calls do not respond in Studio at all.** Only `quick.container` calls answer, from the
+  mocks. A page built on `host.trigger` cannot be fully verified by rendering it locally — say so when you
+  report.
+
+## Rules
+
+- New code calls the host through `(<any>quick.container)`, never `quick.Quick.host.trigger`.
+- One container file per app. Look for it before creating one; never create a second.
+- A function a page calls must be declared in that file.
+- Don't overwrite mocks the user has edited, and don't put real customer data in a mock.
+- **Do not invent function names or payload fields.** The host defines them. If you need one that is not
+  declared, ask the user for the function's name, parameters, return fields and a mock body.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/dynamic-components.md

@@ -0,0 +1,169 @@
+# Dynamic Components (`createComponent`)
+
+Quick's **repeater** — the `v-for` / list-rendering equivalent. For any list, feed, menu, or set of repeated rows/cards built from an array, clone a **template** component once per record. There is no `{{var}}` interpolation and no array-valued prop: clones receive a `dataSource`, read inside the template as `data.*`.
+
+Use it whenever the same subtree repeats and its content changes at runtime — **even at a small fixed count**. The alternative (N hand-authored trees, then dozens of property assignments by id from a handler) is what this replaces.
+
+Working references: `examples/style/authorizationDashboard.qjson` (nested, with rebuild-on-change), `examples/style/dynamicComp.qjson`, `examples/style/placeQidDynamic.qjson`.
+
+## Where the build code may run — read this first
+
+**`components[...]` does not resolve inside a `Messaging` handler** — not in `PreRender`, not in `EndRender`. `createComponent` still returns a real component, so nothing throws and nothing appears in the console, but `placeQID` resolves to nothing and **no clone reaches the DOM**. It looks exactly like success.
+
+Seed data in `Messaging.PreRender`; put the **build loop in a real control's handler** (the button/tab that shows the list).
+
+```typescript
+// ❌ Messaging PreRender / EndRender  → returns OK, places nothing
+// ✅ VBtn click handler               → clones land in placeQID
+```
+
+To paint on first load, give the control that owns the list the same handler body and call it from there.
+
+## Model
+
+1. Park templates in a **container with `"Render": {"H": "false"}`**. Hiding the parent is enough — the templates inside need no `Render` prop of their own. The container may sit anywhere: nested inside the page's `VContainer` works, so a new page still satisfies the single-content-root rule (s-track S4).
+2. Bind template props to `data.<field>`.
+3. For each item call `quick.Quick.createComponent` with a unique `newCompQID` and the container to insert into (`placeQID`).
+
+```
+VContainer id=rowTemplateBox  Render=false   ← hidden container
+  VCard    id=rowTemplate                    ← template
+```
+
+`Render:false` only applies at **runtime / Preview mode**. In Studio's edit canvas the template still draws, with every `data.*` binding resolving to `null` — expected, not a bug.
+
+A template may instead live inline where it renders (a `VListItem` inside its own `VList`), but then it shows as a real row: only do that when a visible first row is wanted.
+
+## Create
+
+```
+quick.Quick.createComponent({
+  templateCompQID: string,   // required — id of the template to clone
+  newCompQID:      string,   // required — unique suffix for this clone
+  dataSource?:     any,      // read as data.* inside the template
+  place?:          'Before' | 'After' | 'Default',   // default 'Default' = end of page
+  placeQID?:       string,   // container to insert into; omit → relative to the template
+  childName?:      string    // names the child; documented as readable via data.newData (no example in this workspace)
+}): IComponent | undefined | null
+```
+
+`place` and `placeQID` are optional. `place` is the `ElementLocation` enum; a bare string works but cast `<any>'Before'` if TS complains.
+
+**It returns the created component.** Capturing that return value and looking the clone up later by id are both valid — capture it when you are setting the clone up right there, look it up when you reach the clone from somewhere else (see *Reaching a clone afterwards*).
+
+```typescript
+let index = 0;
+liste.forEach(function (r: any) {
+  quick.Quick.createComponent({
+    templateCompQID: 'rowTemplate',
+    newCompQID: 'r' + index,
+    placeQID: 'rowList',
+    place: <any>'Before',
+    dataSource: r
+  });
+  index = index + 1;
+});
+```
+
+## Clone ids
+
+The clone's root id is **`templateCompQID + '_' + newCompQID`** — `rowTemplate_r0` above.
+
+**Every descendant is suffixed the same way and keeps its own base id.** A child authored as `rowTemplateTitle` becomes **`rowTemplateTitle_r0`** — *not* `rowTemplate_r0_Title`. That is how you address one field of one row.
+
+## Template prop bindings
+
+In **props**, reference clone data directly as `data.<field>`:
+
+```json
+"text":  { "H": "data.title", "T": "prop" }
+"text":  { "H": "data.dev + ' · ' + data.code", "T": "prop" }
+"class": { "H": "data.sevCls", "T": "class" }
+"color": { "H": "data.bar", "T": "prop" }
+```
+
+Verified working per clone: `text`, `class`, `color`, a `VIcon`'s icon name (PType `text`), and string-concat expressions.
+
+In **events**, declare it first: `declare let data;` then use `data.field`.
+
+A purely structural template (a divider, a spacer) needs no `dataSource` — just clone it.
+
+**`S` styling cannot vary per clone.** `S` holds literal values with no expression support, so every clone inherits the template's `S` verbatim. Route per-row visual differences through the `class` or `color` prop, as above — and set the corresponding `S` param to `""`, since `S` renders as an inline style and would otherwise beat the prop. (The style validator flags these as `prop-to-S`; for data-bound values that warning is unavoidable.)
+
+## Reaching a clone afterwards
+
+Any of these work; pick by what you have in hand — from a control's handler, not from `Messaging`.
+
+```typescript
+components['rowTemplate_r0']                                       // by compound id
+quick.getComponent('rowTemplate_r0')                               // when unreachable by reference
+quick.Quick.findCreateComponentRelative(quick.this, 'rowTemplate') // from a child inside the clone
+quick.Quick.getComponentIdByInstance(instance)                     // instance → id
+```
+
+`findCreateComponentRelative(sourceComp, targetCompID)` takes the **template** id and a child instance — this is how a handler on a cloned control identifies *which* clone it fired from:
+
+```typescript
+// click handler on a button inside a cloned row — removes that row
+const component = quick.Quick.findCreateComponentRelative(quick.this, 'tmpCrsItemLatePayment');
+quick.Quick.deleteComponent(component);
+```
+
+## Re-rendering when the data changes
+
+There is no reactive rebind — nothing repaints when the source array changes. **Delete the clones and rebuild**, guarding on existence first:
+
+```typescript
+let i: number = 0;
+while (i < 20) {
+  let old: any = components['rowTemplate_r' + i];
+  if (old) { quick.Quick.deleteComponent(old); }
+  i = i + 1;
+}
+```
+
+Verified: switching data sets this way holds the clone count and total node count exactly steady across repeated switches — nothing accumulates.
+
+`deleteComponent` removes the component **and all its children** and breaks the parent connection — deleting a cloned container drops everything cloned into it.
+
+After mutating a component in place, `quick.Quick.updateComponent(instance)` refreshes it.
+
+## Nested creation (a cloned container holding cloned rows)
+
+Create the container clone first, then pass **its compound id** as the `placeQID` of the children:
+
+```typescript
+quick.Quick.createComponent({
+  templateCompQID: 'cardTable', newCompQID: 'newUserTable',
+  placeQID: 'newUserTableContainer', place: <any>'Before'
+});
+
+for (let i = 0; i < keys.length; i += 2) {
+  quick.Quick.createComponent({
+    templateCompQID: 'cardTableRow', newCompQID: 'newUserRow' + i,
+    dataSource: { col1: keys[i], col2: data[keys[i]], col3: keys[i+1] ?? '', col4: data[keys[i+1]] ?? '' },
+    placeQID: 'cardTable_newUserTable',        // ← the clone made above
+    place: <any>'Before'
+  });
+}
+```
+
+## Related APIs
+
+```typescript
+quick.Quick.setComponentsProperty(compId, propertyName, propertyValue); // sets a prop, cascading to children
+quick.Quick.setComponentClass(instance, ['cls1', 'cls2']);              // set classes via API
+```
+
+`quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? })` is **not** a general repeater — it adds a named child to a container that defines template children of its own (e.g. a `GoldenLayout` pane). For repeated rows/cards use `createComponent`.
+
+## Rules (each prevents a real failure)
+
+1. **Build from a control's handler, never from `Messaging`** — `components[...]` is empty there and clones silently go nowhere.
+2. **`newCompQID` must be unique.** A duplicate does not error — the existing component is **replaced and becomes permanently unreachable**. Suffix with the loop index.
+3. `placeQID` must be a real container with a `default` slot. A container whose only content is a `Ghost` placeholder is the normal target; a leaf `Ghost` itself is not.
+4. Templates go in a `Render:false` container unless you want the template visible. It need not be root-level.
+
+## When NOT to use this
+
+Tabular data → `VDataTable.items` (don't clone rows). Genuinely static chrome that never changes at runtime → author it directly. Everything else that repeats — cards, list rows, feed items, menu entries — clone it, whether the count is 5 or unknown.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/events-and-scripting.md

@@ -0,0 +1,79 @@
+# Events & Scripting (`E`)
+
+The `E` block holds behavior. Each event is `{ "H": code, "P"?: params, "HL"?: lang, "C"?, "I"?, "PE"?, "EV"?, "TO"? }`.
+
+```json
+"E": {
+  "click": {
+    "H": "quick.EM.trace('clicked');\r\n",
+    "P": "mouseEvent:unknown | undefined",
+    "HL": "TS"
+  },
+  "fetchData": {
+    "H": "let req = <any>{};\r\nreq.url='/api/items';\r\nreq.http='GET';\r\nreq.responseField='items';\r\nreq.onSuccess='onItems';\r\nquick.Request.async(req);\r\n",
+    "C": true, "HL": "TS"
+  }
+}
+```
+
+Event flags — runtime behavior (deep detail in [../reference/events-system.md](../reference/events-system.md)):
+- `C` = **custom**: triggered via `quick.MM.trigger`; the trigger payload is the dataSource (array→first element, object→whole), not name-mapped.
+- `I` = **immediate**: runs synchronously during render instead of being deferred to end-of-render.
+- `PE` = **property event**: injected into the component as a callback prop (chart `labelFormatter`/`tooltipLabel`).
+- `EV` = **externally visible**: exposed to a parent page as `quick.parent.events.<name>`.
+- `TO` = **post-render order**: deferred handlers run sorted by `TO` descending (higher fires first).
+- `HL` = handler language. **Event handlers must use `"HL": "TS"`.** `QS` is for properties/bindings (`P`), not the `E` block.
+
+> The whole events/scripting model (lifecycle internals, custom-event params, property/external events, the `quick.return` exception mechanism, compilation) is in **[../reference/events-system.md](../reference/events-system.md)**.
+
+## Language: events use TS; props may use QS
+**For every event handler (`E`/`D`), write `"HL": "TS"`.** Do not author event handlers as `QS`, `JS`, `FL`, or `GUI`.
+
+**Properties and bindings (`P`) may use `"HL": "QS"`**; QS is their default and is a good fit for short expressions. This property rule does not apply to event handlers.
+
+Line breaks in `H` are `\r\n`.
+
+## TypeScript handler rules (hard)
+1. **Never native `return`** — use `quick.return(value)` / `quick.return`.
+2. End statements with `;`. Close object literals with `};` before the next statement (a missing `;` after an object literal makes TS parse the next line as a call → "expression is not callable").
+3. **No browser globals**: `window`, `document`, `console`, `setTimeout`, `setInterval`. Use:
+   - `quick.EM.trace(...)` instead of `console.log`
+   - `quick.MM.delay('evt', { delayTime: 500 })` instead of `setTimeout`
+   - `quick.Quick.download(...)` instead of anchor downloads
+4. Reference framework APIs as `quick.X` (see [reference/quick-api.md](../reference/quick-api.md)).
+
+> In **QS properties/bindings**, drop `quick.`: write `store.get('x')`, `MM.trigger('evt')`, `Quick.go(...)`. The `quick.` prefix exists only in TS.
+
+> Note: some real files use `debugger;`/`setTimeout` in experimental editor pages. Don't copy those — prefer the Quick APIs for portable, compilable handlers.
+
+## Parameters (`P`) and declaring data
+- Framework/native event params → declare in `P`: `"P": "number:number"`, `"P": "index:any,row:any"`, `"P": "serviceResponse:any"`. Use the name directly in `H`.
+- Trigger-payload fields (passed via `quick.MM.trigger('evt', [{...}])`) are declared inside `H`.
+- Do **not** declare the same name both in `P` and inside `H` (duplicate identifier).
+
+## Page lifecycle (on `Messaging`)
+| Hook | When | Typical use |
+|------|------|-------------|
+| `PreRender` | before render (often `"I": true`) | init store, trigger first fetch |
+| `EndRender` | after render | access/set components |
+| `PostRender` | after prioritized events (`TO` orders them) | |
+| `Restored` | on navigating back | refresh |
+
+> ⚠️ **`PreRender` runs before components exist** — `components.*` is not accessible. Write to `store` in `PreRender` and read from it in prop expressions instead: `store.get('key')`. Use `EndRender` or a custom event if you need to set component props/values after render.
+
+Keep initialization in **one** hook to avoid duplicate fetches. Custom events live on `Messaging` with `"C": true`, called via `quick.MM.trigger`.
+
+## The `quick.*` API
+Everything you can call (network, store, alerts, navigation, validation, dynamic components, dates/money, crypto, …) is indexed in [reference/quick-api.md](../reference/quick-api.md) — scan its member index, then grep the exact signature, params and example for what you picked in [reference/quick-api.json](../reference/quick-api.json).
+
+```typescript
+components.myField.qValue = 'x';           // read/write component value
+quick.store.set('key', v); quick.store.get('key');   // page store ('#'=bag,'$'=global,'&'=shared)
+quick.MM.trigger('evt', [{ p: 1 }]);       // custom event
+quick.Quick.alert({ title:'T', text:'msg', category:'Info', actionButtons:[{name:'OK', type:'Confirm'}] });
+quick.Quick.go('<<qjson:UNIQUE-ID>>');     // navigate
+quick.return(value);                        // return from handler
+```
+
+## Service calls in one line of guidance
+Use `quick.Request.async({ url, http, data, responseField, onSuccess, onFail, blockRender })` and read the result in the `onSuccess` event as `response.<responseField>`. Full patterns (incl. project ServiceCaller convention) in [services.md](services.md).

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/knowledge/layout-and-slots-legacy.md

@@ -0,0 +1,15 @@
+# STOP — legacy pages cannot be edited in this workspace
+
+If the target page's root-level `opt.V` is **missing or `< 2.0`**, it is a legacy page. **Do not edit it.** Tell the user the page is legacy and cannot be authored from a mobile workspace, and make no changes.
+
+There is no way to author it correctly here: mobile does not apply the legacy `O.layout` css mechanism, so the page cannot be restyled through it, and `S` does not render on a `V < 2.0` page either. Both style systems are dead ends on that page. Converting it is a migration, not an edit — it needs a decision from the user, not a side effect of the task you were given.
+
+## This is not about stray legacy fragments
+
+A page with `opt.V >= 2.0` that merely *carries* some `O.layout` (`dOpt`/`class`) is **not** a legacy page. Studio's editor injects those fragments into some components on its own, and on mobile they have no effect at all. That page is an ordinary `S` page:
+
+- Author its design in `S`, as normal — go back to `s-track.md`.
+- Never read `O.layout` to work out how the page currently looks; it does not affect the rendering.
+- When you edit such a page, strip its `O.layout` (`dOpt`/`class`) so the page comes out clean.
+
+The test is **`opt.V`**, not whether legacy css is present.