@stechquick/studio-cli 4.0.3-2

package/dist/studio-cli/src/.ai-kit/knowledge/04-styling.md

@@ -0,0 +1,177 @@
+# 04 · Styling — the `S` (Style) system
+
+> ⚠️ **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? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+>
+> **This file is the `S` track.** `S` does not render on a legacy page — on a **legacy** page instead → [04-styling-legacy.md](04-styling-legacy.md). Reference examples from [../examples/style/](../examples/style/) only.
+
+> The earlier community docs treated styling as "CSS utility classes only" — that is just one mechanism, and **CSS works on Web only**. For the exhaustive schema (every `S` param, editor types, defaults, `SC` inheritance, cross-platform application) see **[../reference/styling-system.md](../reference/styling-system.md)**; the per-component supported `S` params + defaults are in **[../reference/component-styles.json](../reference/component-styles.json)** — the only source to consult when authoring `S`.
+
+> **Why not CSS:** Quick renders on Web, Android, and iOS. CSS exists only on Web. The Style tab serializes into the node's platform-neutral **`S`** object, which each platform applies natively (Web → CSS `@media`+`[q_UID]`; Mobile → flattened to the device's breakpoint range, `col`→flex-basis, via the native bridge). So for cross-platform styling you must use `S`, not a CSS Style File.
+
+## The styling mechanisms — in strict priority order
+
+1. **`S` (Style System)** — per-component design: size, spacing, grid column, flex direction/align/justify, colors, fonts, borders, shadows. This is now the mechanism for *everything* the Style tab does — layout included. Try this first, always.
+2. **`class` prop, Web only, last resort** — if a component's `S` schema (check [../reference/component-styles.json](../reference/component-styles.json)) genuinely has no param for what you need, on **Web** you may set the component's own `class` prop directly. This is a fallback for the rare gap, not a parallel mechanism — don't reach for it before confirming `S` can't do it.
+3. **Style File (CSS), Web only, true last resort** — project-level CSS (`body .v-application …`) and `@font-face`. Only for cross-cutting rules neither `S` nor a component's `class` prop can express (e.g. a pseudo-selector, a project-wide rule, custom fonts).
+
+**`O.layout` (`dOpt`/`class`) is not part of this system** — it is the pre-`S` legacy mechanism. Never author it on an `S`-system page; everything it used to carry (grid width, flex direction, align, justify, spacing) is a `S` param here.
+
+**There is no Mobile fallback past `S`.** `class`/CSS are Web-only (CSS doesn't exist on native; the `class` prop has no native-bridge equivalent either). If a design needs something `S` can't express and the page targets Mobile, restructure with an `S`-capable component instead of reaching for `class`/CSS — there's nothing for the Mobile renderer to apply it from.
+
+Theme colors and fonts defined in **Themes Settings** appear as selectable options inside the Style tab (i.e. as values you put in `S`, not separately).
+
+## A) Style tab → the `S` object
+
+The Style tab writes a node-level **`S`** object keyed by **resolution range**, each holding CSS-like camelCase properties. Example from a real file:
+
+```json
+"S": {
+  "xs-xl": {
+    "marginTop": "", "marginRight": "", "marginBottom": "", "marginLeft": "",
+    "paddingTop": "12px", "paddingRight": "12px", "paddingBottom": "12px", "paddingLeft": "12px",
+    "width": "", "height": "",
+    "fontColor": "#000000", "fontFamily": "Roboto", "fontSize": "16px",
+    "fontStyle": "normal", "fontWeight": "400", "lineHeight": "20px", "textAlign": "left",
+    "backgroundColor": "#FFFFFF", "color": "", "iconColor": "",
+    "boxShadow": "", "boxSizing": "",
+    "borderColor": "", "borderWidth": "", "borderTopStyle": "", "borderRightStyle": ""
+  }
+}
+```
+
+The Style tab is organized into boxes that map to these `S` keys:
+
+| Style-tab box | `S` properties it writes |
+|---------------|--------------------------|
+| **Size** | `width`, `height` (px / % / em / rem) |
+| **Text** | `fontColor`, `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `lineHeight`, `textAlign` (+ `combinedFont`/`ThemeFont` when a theme/custom font is chosen) |
+| **Appearance** | `backgroundColor`, `color`, `iconColor` (color picker: hex / RGB / HSL); `border*` (`borderColor`, `borderWidth`, `border<side>Style`, `borderRadius`, `boxSizing`); `boxShadow` |
+| **Layout box** | grid column, direction, align, justify, margin, padding — written as `S` params: `col`, `flexDirection`, `alignItems`, `justifyContent`, `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left`. Which of these a given component actually supports varies — check that `T`'s block in [../reference/component-styles.json](../reference/component-styles.json) (e.g. only `VCol` carries `flexDirection`/`alignItems`/`justifyContent`/`col`; most containers carry the margin/padding set). |
+
+Notes for authoring `S` by hand:
+- Keys are **resolution ranges**, default full-range `"xs-xl"`. A narrower range (e.g. `"xs-sm"`, `"md-xl"`) targets specific devices — this is "Layout Multiplexing" (see responsive table below). Empty string `""` means "unset" (the Style-tab checkbox unchecked).
+- Sizes accept `px`, `%`, `em`, `rem`.
+- `S` is read by the runtime directly; you usually let the Style tab generate it, but you may hand-write it.
+
+## B) The Layout box → `S` (grid column, direction, align, justify, spacing)
+
+On an `S`-system page, layout is **not** a separate mechanism — the Layout box (Grid Column, Direction, Align, Justify, Box margin/padding) writes into **`S`** like every other Style-tab box: `col` (grid width, 1–12, `VCol`-specific), `flexDirection`/`alignItems`/`justifyContent` (`VCol`-specific), `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left` (most containers). Check the component's block in [../reference/component-styles.json](../reference/component-styles.json) for which of these it actually supports before assuming a param exists.
+
+```json
+"S": { "xs-xl": { "flexDirection": "column", "justifyContent": "center", "paddingTop": "16px", "paddingBottom": "16px", "col": "6" } }
+```
+
+> The pre-`S` `O.layout` (`dOpt` + compiled `class`) mechanism for the same intents belongs to the legacy era — never author it on an `S`-system page.
+
+### Responsive breakpoints (authoritative pixel ranges)
+| Key | Device | Range |
+|-----|--------|-------|
+| `xs` | Mobile | 0–600px |
+| `sm` | Tablet | 600–960px |
+| `md` | Laptop | 960–1264px |
+| `lg` | Desktop | 1264–1904px |
+| `xl` | TV | 1904px+ |
+
+`S` is keyed by **ranges** built from these breakpoints (`"xs-xl"`, `"md-xl"`, …). Grid-Column (1–12) lives on `VCol`; Direction → `flexDirection: "row"/"column"`; Justify (start/center/end/space-between/space-around) → `justifyContent` (main axis); Align (start/center/end/stretch/baseline) → `alignItems` (cross axis).
+
+## B2) Styling a child from its parent — `SC` (child-style inheritance)
+
+Some visuals are set on the **parent** and pushed into a typed child — e.g. a button's **label text color** and **icon color**. The node's `SC` maps a parent style param to a child component type's param. **Fill it from data, not from memory: copy the component's `inheritedChildList` block in [../reference/component-styles.json](../reference/component-styles.json) into `SC` as-is** (same shape: `{ styleParam: { ChildType: childParam } }`). Components without an `inheritedChildList` in their JSON block get **no** `SC` — the engine ignores it there.
+
+```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" } } }
+```
+
+**`SC` complements the child's own `S` — it does not replace it.** Per rule S3 ([AGENT_GUIDE-s.md](../AGENT_GUIDE-s.md)) the child label/icon inside a `VBtn`/`VChip`/`VTabs` **also** carries its own `S` with its full default set from `component-styles.json`, values matched to the design (e.g. a white-text button label writes `fontColor:#ffffff` — not the generic QLabel default `#000000`). This is what the editor itself produces (see the button label in [../examples/style/MMDelay.qjson](../examples/style/MMDelay.qjson)). Keep the parent's `SC` mapping alongside it.
+
+Also: legacy props migrate into `S` per each component's `propMigrateList` — e.g. `VBtn`/`VCard` `color` → `backgroundColor`, `VTextField` `color` → `labelDefaultFontColor`. Prefer setting `S` directly.
+
+## C) Styled Components (`SA`) — reusable named styles
+Create from the Style tab ("Create or Select a Styled Component"), name it, and it becomes reusable across pages; applied components reference it via the node's **`SA`** array. Editing the styled component updates every component using it. Move it into a shared module to reuse across applications. When hand-authoring you normally don't invent `SA` entries — apply them in Studio.
+
+## D) Style File (project CSS) — the older / cross-cutting path
+A project-level CSS file. Because the UI is Vuetify, prefix selectors with `body .v-application`:
+```css
+body .v-application .v-text-field { background: lightgrey; }
+```
+Fonts via `@font-face` with Studio asset references:
+```css
+@font-face { font-family: MyFont; src: url("<<ttf:font-id>>"); }
+```
+For locally-exported projects, custom fonts need the `@font-face` rule added to the CSS file (Google Fonts can be blocked with `blockFontRequest: true` in `settings.yaml`). This, and any other Style File use, is Web-only and a last resort — prefer `S` for per-component styling, full stop.
+
+## Practical guidance for an AI authoring qjson
+
+**The flow, every time you design a screen or place a component:**
+
+1. **Try `S` first.** Look up the component's block in [../reference/component-styles.json](../reference/component-styles.json) and set every param the design needs there — size, spacing, grid `col`, `flexDirection`/`alignItems`/`justifyContent` (where supported), colors, fonts, borders, shadows. This covers the large majority of designs.
+2. **If `S` genuinely has no param for it:**
+   - **Before writing any `class` token:** list every token you intend to use and check [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md) for an `S` equivalent. Only tokens with confirmed no `S` equivalent belong in `class`. Never bulk-copy a class string. If `S` and `class` already express the same thing (e.g. `S.height:"100%"` + `class:'fill-height'`), remove the class token — `S` is authoritative.
+   - **Web:** you may set the component's own `class` prop with the surviving tokens — but only as a last resort, with no other option.
+   - **Mobile:** there is **no** `class` alternative. Don't set `class` expecting it to do anything on Mobile — restructure with an `S`-capable component (most commonly wrap in/use a `VCol`, which uniquely supports the flex axis in `S`) instead.
+3. **Style File (CSS)** is the true last resort, Web-only, for cross-cutting rules neither `S` nor a `class` prop can express (pseudo-selectors, project-wide rules, `@font-face`). Confirm with the user before reaching for it on a single component — it usually means a missing `S` param, not a real gap.
+
+- **`O.layout` belongs to the legacy era — never write it on an `S`-system page.** If you are tempted to write `O: { "cType": "slot", "layout": { "dOpt": ... } }`, stop — that is the legacy mechanism, valid only on `V<2` pages. Use `S` here. Reference examples only from [../examples/style/](../examples/style/) — a `O.layout` block means the example came from the legacy set; do not copy it into an `S` page.
+
+- **Vuetify style-affecting props are NOT an alternative to `S`.** Even when a prop appears in `component-contracts.json`, if `S` has an equivalent param, use `S`. Common violations to avoid:
+
+  | Vuetify prop (don't use for style) | Use this instead |
+  | --- | --- |
+  | `VCol.cols` / `VCol.sm` / `VCol.md` / `VCol.lg` / `VCol.xl` | `S.col: "N"` + resolution ranges |
+  | `VRow.justify` / `VRow.align` | Web-only `class` last resort (no S equivalent on VRow) |
+  | `VBtn.color` / `VCard.color` | `S.backgroundColor` |
+  | `VTextField.color` | `S.labelDefaultFontColor` |
+  | `maxWidth` / `minWidth` / `maxHeight` as props | `S.maxWidth` / `S.minWidth` / `S.maxHeight` |
+  | `elevation` prop | `S.boxShadow` |
+
+- **Never leave a component you placed with no `S` at all, and emit every default** — see [AGENT_GUIDE-s.md](../AGENT_GUIDE-s.md) rule S3. A `default` value listed in `component-styles.json` for a param is only the Style-tab's pre-filled suggestion — it is not silently applied unless you write that `S` key yourself. Therefore a placed component's `S` must include **every param that carries a `default` in its `component-styles.json` block** (the default value, or your design's override). Params whose JSON entry has no default (empty `{}`) are optional — set them only when the design needs them.
+- **A multi-child `VCol` does not stack for free.** `VCol` is itself a flex container, but its flex-direction is **not** column unless you set it — left unset it lays children out as a row, so two components dropped straight into a `VCol` render side-by-side instead of stacked (true in both eras — see [03-layout-and-slots.md](03-layout-and-slots.md)). The fix here is `S.flexDirection: "column"` on that `VCol` — a real, supported `S` param (`componentStyleList`'s `layout-chooser`/`content-direction` group; see the `VCol` block in [../reference/component-styles.json](../reference/component-styles.json)).
+
+  Canonical **stacked label + value field** (label on top, value/input below):
+
+  ```json
+  { "T": "VCol", "P": { "ID": { "H": "colField", "T": "prop" } },
+    "E": {},
+    "C": { "default": { "c": [
+      { "T": "QLabel", "P": { "ID": { "H": "lblFieldLabel", "T": "prop" }, "text": { "H": "'Field Label'", "T": "prop" } },
+        "E": {}, "C": {}, "O": { "cType": "slot" },
+        "S": { "xs-xl": { "fontColor": "#9AA0A6", "fontSize": "14px", "fontWeight": "400" } },
+        "_Editor": { "eID": "lblFieldLabel" } },
+      { "T": "QLabel", "P": { "ID": { "H": "lblFieldValue", "T": "prop" }, "text": { "H": "'Value'", "T": "prop" } },
+        "E": {}, "C": {}, "O": { "cType": "slot" },
+        "S": { "xs-xl": { "fontColor": "#1B2A4A", "fontSize": "18px", "fontWeight": "700" } },
+        "_Editor": { "eID": "lblFieldValue" } }
+    ], "cType": "slot" } },
+    "O": { "cType": "slot" },
+    "S": { "xs-xl": { "flexDirection": "column", "col": "12" } },
+    "_Editor": { "eID": "colField" } }
+  ```
+
+  `S.flexDirection: "column"` guarantees the stack; `S.col: "12"` controls the width — both live in `S`, nothing here goes through `O.layout`.
+- **Equal-height cards in a row:** `VCard` has no flex `S` params, so on **Web only** this is one of the rare legitimate uses of the `class` last resort — add `d-flex` to the `VCol`'s `class` and `flex-grow-1 d-flex flex-column` to the card's `class` (the `VRow`'s default `alignItems:stretch` already gives the `VCol` full height). There's no Mobile equivalent — accept the card's natural height there, or restructure with an `S`-capable wrapper (`VCol`) doing the stretching instead.
+- When matching a mockup/Figma, encode colors/borders/shadows/spacing/grid/direction all in `S`, and confirm ambiguous choices.
+
+## Common theme utility classes (via `class` prop — Web-only last resort)
+These exist and work on Web, but most have an `S` equivalent that also works on Mobile — always check [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md) first and prefer the `S` param (e.g. `fontSize`+`fontWeight` over `text-h5`, `fontColor` over `primary--text`, `borderRadius`/`backgroundColor` over `rounded-lg`/`transparent`, `paddingTop` over `pt-N`, `height:"100%"` over `fill-height`). Only reach for these classes when you specifically need a Web-only effect or are confirmed to not need Mobile parity. Typography: `text-h5`, `text-h6`, `text-body-1`, `text-body-2`, `text-caption` + `font-weight-bold|medium|regular`. Color: `primary`/`primary--text`, `secondary`/`secondary--text`, `success--text`, `error--text`, `white`/`white--text`, `secondary lighten-4`. Card: `rounded-lg`, `transparent` (for a flat card use `S.boxShadow:"none"`, **not** the `elevation` prop — the `elevation` prop is legacy-only). Icons: name in `VIcon.text` (PType `text`).
+
+## Pre-sync checklist
+
+The full pre-sync checklist (shared core + the `S`-system style checks — `S` on every visual node, no `O.layout`, the `class`-prop audit) is in [10-validation-and-sync.md](10-validation-and-sync.md). Run it before syncing.

package/dist/studio-cli/src/.ai-kit/knowledge/05-components.md

@@ -0,0 +1,97 @@
+# 05 · 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.
+
+## Select / Combobox / 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"`).
+
+## Charts (Bar / Line / Doughnut only)
+```json
+{ "T": "Bar", "P": { "ID": { "H": "barChart", "T": "prop" },
+    "labels": { "H": "['Jan','Feb','Mar']", "T": "prop" },
+    "data": { "H": "[12,19,3]", "T": "prop" },
+    "label": { "H": "'Sales'", "T": "prop" },
+    "backgroundColor": { "H": "['rgba(54,162,235,0.4)']", "T": "prop" },
+    "width": { "H": "'32vw'", "T": "prop" }, "height": { "H": "'40vh'", "T": "prop" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "barChart" } }
+```
+- `labels`=array, `label`=string. No `visible` prop (wrap in a `VCol`).
+- Runtime update: mutate `components.barChart.data` then `(<any>components.barChart).update()`. Use `Doughnut` + `cutoutPercentage:0` for a pie.
+
+## 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 pull` converts Studio model IDs to this path format; `studio push` converts back — never write a raw ID.
+
+**The embedded page must itself be a block component in Studio.** When you add a page into another page as a block component, check the embedded page's frontmatter: if it lacks `blockComponent: true`, run `studio convertToBlock <embedded-file>`. The file must be checked out (`studio startWorking <file>` if it isn't; pages newly created by `studio push` come back already checked out). For a brand-new page this runs only **after** `studio push` — the model must exist in Studio first. 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 [06-services.md](06-services.md) and [09-page-skeletons.md](09-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/src/.ai-kit/knowledge/06-services.md

@@ -0,0 +1,68 @@
+# 06 · Services (REST)
+
+Two patterns. **Check existing project pages first** and follow whichever the project uses.
+
+## Pattern A — `quick.Request.async` (framework-native, default)
+Call from any event; success/fail route to custom events on the same component (usually `Messaging`).
+
+```typescript
+let req = <any>{};
+req.url = '/api/products/list';
+req.http = 'GET';                 // GET|POST|PUT|DELETE|PATCH|MULTIPART|POSTBLOB|GETBLOB
+req.data = null;                  // body for POST/PUT
+req.blockRender = false;
+req.responseField = 'productList';
+req.onSuccess = 'onProductsSuccess';
+req.onFail = 'onProductsFail';
+quick.Request.async(req);
+```
+
+Read the result in the success event as `response.<responseField>`:
+```json
+"onProductsSuccess": {
+  "H": "if (response.productList != null) {\r\n  let resData = response.productList;\r\n  components.tblProducts.items = resData.resultList;\r\n}\r\n",
+  "C": true, "HL": "TS"
+}
+"onProductsFail": {
+  "H": "quick.Quick.alert({ title:'Hata', text:'İstek başarısız', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n",
+  "C": true, "HL": "TS"
+}
+```
+
+`IRequest` fields: `url`, `http`, `data`, `responseField`, `onSuccess`, `onFail`, `blockRender`, `showSuccessMessage`, `showErrorMessage`, `headers`, `withCredentials`, `timeout`, `args`. Inline `await` form also works:
+```typescript
+const respo = await quick.Request.async(req);
+let result = (<any>respo).data;
+```
+
+## Pattern B — project ServiceCaller `CustomComponent`
+Some projects centralize calls in a reusable `CustomComponent` (a service proxy) with `onLoad` / `onServiceSuccessCallBack` / `onServiceFailCallBack`. Use it **only if the project already provides one** (copy its `QJsonPath` from an existing page).
+
+```json
+{ "T": "CustomComponent", "P": {
+    "ID": { "H": "serviceCallerComp", "T": "prop" },
+    "QJsonPath": { "H": "'<<qjson:path/to/ServiceCallerCustomComponent>>'", "T": "prop" } },
+  "E": {
+    "onLoad": { "H": "quick.store.set('page', 0);\r\nquick.MM.trigger('getProducts', [{ page: 0 }]);\r\n", "HL": "TS" },
+    "onServiceSuccessCallBack": { "H": "/* capture → null → process */", "C": true, "P": "serviceResponse:any", "HL": "TS" },
+    "onServiceFailCallBack": { "H": "/* alert with actionButtons */", "C": true, "P": "serviceResponse:any", "HL": "TS" }
+  },
+  "C": { "default": { "c": [ { "T": "Ghost", "P": { "ID": { "H": "ghostComp", "T": "prop" } }, "E": {}, "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "ghostComp" } } ], "cType": "child" } },
+  "O": { "cType": "child", "dynProps": true }, "_Editor": { "eID": "serviceCallerComp" } }
+```
+Each call is a custom event on `Messaging` that builds a `requestObj` and calls `(<any>components.serviceCallerComp).serviceCall(requestObj)`. In the success callback, **capture → null → process**:
+```typescript
+if (serviceResponse.getProducts != null) {
+  let resData = serviceResponse.getProducts;  // capture
+  serviceResponse.getProducts = null;         // null immediately
+  components.tblProducts.items = resData.resultList; // process
+}
+```
+
+## Rules that prevent the common failures
+- Close the request object literal with `};` before the next call (missing `;` → "not callable").
+- Triggered custom events need `"C": true`; declare `P` to match the trigger payload.
+- `responseField` / event names must match exactly across trigger, request, and callback.
+- Fail alerts must include `actionButtons`.
+- Initialize in **one** place (service `onLoad` or `Messaging.PreRender`).
+- Don't assign `VDataTable.headers`/static `items` in callbacks — those are component props; assign only dynamic rows.

package/dist/studio-cli/src/.ai-kit/knowledge/07-localization.md

@@ -0,0 +1,40 @@
+# 07 · Localization (`lrids`, `LR`)
+
+## `lrids` structure — by language code, values single-quoted
+```json
+"lrids": {
+  "tr-TR": { "save": "'Kaydet'", "userName": "'Kullanıcı Adı:'" },
+  "en-US": { "save": "'Save'",   "userName": "'User Name:'" }
+}
+```
+- Group by language code (`tr-TR`, `en-US`, …).
+- Every value is a single-quoted string (same quoting model as prop `H`).
+- Every key used by `LR`/`quick.LR` must exist in **all** required languages.
+- **Omit `clrids` entirely** — the compiler generates it on import (compiled values look like `╬'Kaydet'╩╩`). Never author `clrids`, and strip it from any downloaded file you edit.
+
+## Context rule: `LR` in props, `quick.LR` in events
+| Context | Use |
+|---------|-----|
+| Props (`P.H`, QScript) | bare `LR('key')` |
+| Events (`E.H`, TS) | `quick.LR('key')` |
+
+Props:
+```json
+"text": { "H": "LR('save')", "T": "prop" }
+```
+Events:
+```typescript
+quick.Quick.alert({ text: quick.LR('genericError'), category:'Error', actionButtons:[{name: quick.LR('ok'), type:'Confirm'}] });
+```
+`quick.LR(key, dataSource?)` returns the localized string. Never call `quick.LR` inside a prop.
+
+## Static vs localized text
+Static = a quoted literal (`"H": "'Kaydet'"`); localized = wrap the key (`"H": "LR('save')"`). Apostrophe inside a QScript string is doubled: `'Premium''u'`.
+
+## Workflow
+1. Pick a stable key.
+2. Add it under every language block in `lrids`.
+3. Reference with `LR('key')` (props) / `quick.LR('key')` (events).
+4. Verify no language is missing the key before delivery.
+
+There is also a runtime `quick.importLocalization(langCode, {...})` and global localization qjsons in some projects — but for a single page, `lrids` is what you author.

package/dist/studio-cli/src/.ai-kit/knowledge/08-dynamic-components.md

@@ -0,0 +1,49 @@
+# 08 · Dynamic Components (`createComponent`)
+
+For repeated UI generated from data, clone a **template** component. There is no `{{var}}` interpolation — clones receive a `dataSource` accessed as `data.*`.
+
+## Model
+1. Keep a template as a **root-level** `pJson` element, hidden until cloned.
+2. Bind template props to `data.<field>`.
+3. For each item, call `quick.Quick.createComponent` with a unique `newCompQID`, inserting into a real container (`placeQID`).
+
+## Create (TypeScript)
+```typescript
+quick.Quick.createComponent({
+  templateCompQID: 'rowTemplate',
+  newCompQID: 'row' + index,
+  placeQID: 'rowList',
+  place: ElementLocation.Default,   // or <any>'Before' / <any>'After'
+  dataSource: response.data         // accessed as data.* in the template
+});
+```
+Real files also build `dataSource` from a service response and loop (`forEach`) creating one clone per item. `place` is the `ElementLocation` enum (`Before`/`After`/`Default`); a bare string works but cast `<any>'After'` if TS complains.
+
+## Template prop bindings
+In **props**, reference clone data directly as `data.<field>`:
+```json
+"text": { "H": "data.title", "T": "prop" }
+"class": { "H": "if(data.statusColor==1){'red lighten-5'}else{'blue lighten-5'}", "T": "class" }
+```
+In **events**, declare it first: `declare let data;` then use `data.field`.
+The template's `visible` should guard against the pre-clone state:
+```json
+"visible": { "H": "if(data!=undefined){data.visible}else{false}", "T": "prop" }
+```
+Pass `visible:true` per clone so clones show while the template stays hidden.
+
+## Rules (each prevents a real failure)
+1. `templateCompQID` must be a **pJson root-level** component id (not a nested child).
+2. `placeQID` must be a real container with a `default` slot (not a leaf `Ghost`).
+3. `newCompQID` must be unique per clone (effective id becomes `templateCompQID + '_' + newCompQID`).
+4. Guard template `visible` with the `if(data!=undefined){...}else{false}` pattern.
+
+## Related APIs
+```typescript
+quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? });
+let c = quick.Quick.findCreateComponentRelative(quick.this, 'rowTemplate');
+quick.Quick.deleteComponent(quick.getComponent('rowTemplate_row0'));
+```
+
+## When NOT to use this
+Tabular data → use `VDataTable.items` (don't clone rows). A few fixed cards → author them statically. Use `createComponent` for unknown-count, card/row-shaped repeated UI.

package/dist/studio-cli/src/.ai-kit/knowledge/09-page-skeletons-legacy.md

@@ -0,0 +1,83 @@
+# 09 · Page Skeletons — legacy `cssClass` system
+
+> ⚠️ **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? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+>
+> **This file is the `legacy` track.** These are **structure references for editing/extending an existing legacy page**, not "start from scratch" templates — keep the page's current root, don't retrofit a `VContainer`, and design via `O.layout` (`dOpt`/`class`) + CSS classes. Starting a genuinely new page instead → [09-page-skeletons.md](09-page-skeletons.md).
+
+## Reference shape — framework-native (no service component)
+A legacy page typically has this shape (`Messaging` + a layout root). Match it when adding sections; do not add a `VContainer` root to a page that already roots elsewhere.
+
+```javascript
+let pjson = {
+  "pJson": [
+    {
+      "T": "Messaging",
+      "P": { "ID": { "H": "msg", "T": "prop" } },
+      "E": {
+        "PreRender": { "H": "quick.MM.trigger('fetchData');\r\n", "I": true, "HL": "TS" },
+        "fetchData": { "H": "let req=<any>{};\r\nreq.url='/api/data';\r\nreq.http='GET';\r\nreq.data=null;\r\nreq.blockRender=false;\r\nreq.responseField='data';\r\nreq.onSuccess='onData';\r\nreq.onFail='onFail';\r\nquick.Request.async(req);\r\n", "C": true, "HL": "TS" },
+        "onData": { "H": "let resData = response.data;\r\n/* process resData */\r\n", "C": true, "HL": "TS" },
+        "onFail": { "H": "quick.Quick.alert({ title:'Hata', text:'Bir hata oluştu.', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n", "C": true, "HL": "TS" }
+      },
+      "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "msg" }
+    },
+    {
+      "T": "VContainer",
+      "P": { "ID": { "H": "pageContainer", "T": "prop" },
+             "class": { "H": "'container container--fluid'", "T": "class" } },
+      "E": {},
+      "C": { "default": { "c": [ /* PAGE CONTENT */ ], "cType": "slot" } },
+      "O": { "cType": "child" }, "_Editor": { "eID": "pageContainer" }
+    }
+  ],
+  "lrids": {}, "opt": {}
+};
+export default pjson
+```
+
+## Reference shape — with project ServiceCaller (only if the project provides one)
+Same as above, plus a `CustomComponent` after `Messaging` (see [06-services.md](06-services.md) Pattern B), with init in its `onLoad`.
+
+## Centered content scaffold (drop into PAGE CONTENT)
+Legacy form — layout via `O.layout` (`dOpt` + synced `class`), visuals via CSS utility classes on the `class` prop:
+
+```json
+{ "T": "VRow", "P": { "ID": { "H": "rowMain", "T": "prop" } }, "E": {},
+  "C": { "default": { "c": [
+    { "T": "VCol", "P": { "ID": { "H": "colMain", "T": "prop" } }, "E": {},
+      "C": { "default": { "c": [
+        { "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" },
+            "elevation": { "H": "0", "T": "prop" },
+            "class": { "H": "'white pa-4 rounded-lg'", "T": "class" } },
+          "E": {}, "C": { "default": { "c": [
+            { "T": "QLabel", "P": { "ID": { "H": "lblPageTitle", "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": "lblPageTitle" } }
+          ], "cType": "slot" } },
+          "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+      ], "cType": "slot" } },
+      "O": { "cType": "slot", "layout": { "dOpt": { "xs": ["d:d-flex","j:justify-center"] }, "class": "d-flex justify-center" } },
+      "_Editor": { "eID": "colMain" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "rowMain" } }
+```
+
+## Styling — `O.layout` + CSS classes (do NOT author `S`)
+On a legacy page, design lives in two places, not in `S` (which won't render on `V < 2`):
+
+- **`O.layout`** (`dOpt` + compiled `class`) — grid width (`c:col-N`), flex direction/align/justify (`fd:`/`a:`/`j:`), spacing (`sp:`). Keep `dOpt` and `class` in sync.
+- **The `class` prop** — CSS utility classes for typography (`text-h5`, `font-weight-bold`), color (`primary--text`, `white`), elevation (`elevation-2`), rounding (`rounded-lg`).
+
+```json
+{ "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" },
+    "elevation": { "H": "2", "T": "prop" },
+    "class": { "H": "'white pa-4 rounded-lg'", "T": "class" } },
+  "E": {}, "C": { "default": { "c": [ /* … */ ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+```
+
+Full how-to: [04-styling-legacy.md](04-styling-legacy.md); the `dOpt` grammar + `dOpt → class` compilation rule: [../reference/layout-system.md](../reference/layout-system.md). **Do not introduce `S` on a legacy page — it silently won't render.**
+
+## Large-page policy (incremental)
+Don't rewrite a whole page in one shot. Add **1–3 sections per edit**, validate, and report progress. Reuse examples from [../examples/cssClass/](../examples/cssClass/) (the legacy set — e.g. `CardTitle.qjson`, `Profile_Card.qjson`) and neighboring project pages rather than re-deriving structures.

package/dist/studio-cli/src/.ai-kit/knowledge/09-page-skeletons.md

@@ -0,0 +1,87 @@
+# 09 · Page Skeletons — `S` system
+
+> ⚠️ **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? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+>
+> **This file is the `S` track** (starting a brand-new page). A new page's `opt.V` is always the current version — **author it as `opt.V: 2.5`** (this marks the page as `S`-system; the skeleton below already sets it). Adding a section to an **existing legacy page** instead → [09-page-skeletons-legacy.md](09-page-skeletons-legacy.md).
+
+Start every new page from one of these. Structure: `Messaging` (event hub) → optional service `CustomComponent` (only if the project uses one) → `VContainer` (layout root). For a **new page the `VContainer` content root is required** (not merely canonical): wrap all UI content in a single top-level `VContainer`, with `Messaging` and the optional service component as the only other top-level `pJson` siblings. This is a **new-page rule only** — when editing an existing page, keep its current root and do **not** add a `VContainer` unless the user asks.
+
+## Skeleton — framework-native (no service component)
+```javascript
+let pjson = {
+  "pJson": [
+    {
+      "T": "Messaging",
+      "P": { "ID": { "H": "msg", "T": "prop" } },
+      "E": {
+        "PreRender": { "H": "quick.MM.trigger('fetchData');\r\n", "I": true, "HL": "TS" },
+        "fetchData": { "H": "let req=<any>{};\r\nreq.url='/api/data';\r\nreq.http='GET';\r\nreq.data=null;\r\nreq.blockRender=false;\r\nreq.responseField='data';\r\nreq.onSuccess='onData';\r\nreq.onFail='onFail';\r\nquick.Request.async(req);\r\n", "C": true, "HL": "TS" },
+        "onData": { "H": "let resData = response.data;\r\n/* process resData */\r\n", "C": true, "HL": "TS" },
+        "onFail": { "H": "quick.Quick.alert({ title:'Hata', text:'Bir hata oluştu.', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n", "C": true, "HL": "TS" }
+      },
+      "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "msg" }
+    },
+    {
+      "T": "VContainer",
+      "P": { "ID": { "H": "pageContainer", "T": "prop" },
+             "class": { "H": "'container container--fluid'", "T": "class" } },
+      "E": {},
+      "C": { "default": { "c": [ /* PAGE CONTENT */ ], "cType": "slot" } },
+      "O": { "cType": "child" }, "_Editor": { "eID": "pageContainer" }
+    }
+  ],
+  "lrids": {}, "opt": { "V": 2.5 }
+};
+export default pjson
+```
+
+## Skeleton — with project ServiceCaller (only if the project provides one)
+Same as above, plus a `CustomComponent` after `Messaging` (see [06-services.md](06-services.md) Pattern B), with init in its `onLoad`.
+
+## Centered content scaffold (drop into PAGE CONTENT)
+```json
+{ "T": "VRow", "P": { "ID": { "H": "rowMain", "T": "prop" } }, "E": {},
+  "C": { "default": { "c": [
+    { "T": "VCol", "P": { "ID": { "H": "colMain", "T": "prop" } }, "E": {},
+      "C": { "default": { "c": [
+        { "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" } },
+          "S": { "xs-xl": { "backgroundColor": "#ffffff", "boxShadow": "none", "paddingTop": "16px", "paddingRight": "16px", "paddingBottom": "16px", "paddingLeft": "16px", "borderTopLeftRadius": "8px", "borderTopRightRadius": "8px", "borderBottomLeftRadius": "8px", "borderBottomRightRadius": "8px" } },
+          "E": {}, "C": { "default": { "c": [
+            { "T": "QLabel", "P": { "ID": { "H": "lblPageTitle", "T": "prop" },
+                "text": { "H": "'Page Title'", "T": "prop" } },
+              "S": { "xs-xl": { "fontSize": "24px", "fontWeight": "700", "fontColor": "#1976D2" } },
+              "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblPageTitle" } }
+          ], "cType": "slot" } },
+          "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+      ], "cType": "slot" } },
+      "O": { "cType": "slot" },
+      "S": { "xs-xl": { "justifyContent": "center" } },
+      "_Editor": { "eID": "colMain" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "rowMain" } }
+```
+
+## Styling — every component carries an `S` (don't skip it)
+The skeletons above are intentionally minimal: **structure + `class` only**. They are *not* a finished page. A real page also sets each component's visual design in its top-level **`S`** object — the cross-platform Style tag the editor serializes (sibling to `T`/`P`/`E`/`C`/`O`/`_Editor`). After you drop in a section, give its components their `S`:
+
+```json
+{ "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" } },
+  "S": { "xs-xl": {
+      "backgroundColor": "#ffffff",
+      "borderTopLeftRadius": "8px", "borderTopRightRadius": "8px",
+      "borderBottomLeftRadius": "8px", "borderBottomRightRadius": "8px",
+      "paddingTop": "16px", "paddingRight": "16px", "paddingBottom": "16px", "paddingLeft": "16px",
+      "boxShadow": "0 2px 8px rgba(0,0,0,0.08)" } },
+  "E": {}, "C": { "default": { "c": [ /* … */ ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+```
+
+- `S` is **range-keyed** (`"xs-xl"` = all sizes; narrower ranges like `"md-xl"` override for larger screens). Values are strings; `""` = unset.
+- Pull the supported param names + editor defaults for each `T` from [../reference/component-styles.json](../reference/component-styles.json) — don't invent params.
+- Style a child's text/icon (e.g. a `VBtn` label color) through the **parent's `SC`**, not the child's own `S`.
+- **Everything goes in `S`** — layout (flex/grid/spacing/direction, where the component's `componentStyleList` supports it) and visuals (color/font/border/shadow/exact size) alike. `O.layout` (`dOpt`+`class`) is legacy; don't author it. Reach for the component's `class` prop only as a Web-only last resort when `S` truly has no param for it — never on Mobile.
+
+Full how-to: [04-styling.md](04-styling.md). **A page delivered with no `S` is unstyled — the styling pass is part of authoring, not an optional extra.**
+
+## Large-page policy (incremental)
+Don't rewrite a whole page in one shot. Write the skeleton + scaffold, then add **1–3 sections per edit**, validate, and report progress. Reuse examples from [../examples/style/](../examples/style/) (the `S`-system set) and neighboring project pages rather than re-deriving structures.