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

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/appSettings/global-localization.md

@@ -0,0 +1,78 @@
+# Global Localization · app-wide translations
+
+Translation keys shared by **every page** in the app. Page-level `lrids` live inside the page that uses them; global localization is the layer beneath, so a key defined once is available everywhere.
+
+Selected in **App Settings → Localization** (not General) → [appSettings.md](appSettings.md).
+
+For how keys are written and referenced — `lrids` structure, `LR` in props vs `quick.LR` in events — see [../localization.md](../localization.md). This doc covers only the app-wide layer.
+
+## Shape
+
+A `.qjson` file carrying `lrids` and no UI. Same structure as a page's `lrids`:
+
+```json
+"lrids": {
+  "tr-TR": { "save": "'Kaydet'", "cancel": "'İptal'" },
+  "en-US": { "save": "'Save'",   "cancel": "'Cancel'" }
+}
+```
+
+As always, author `lrids` only — never `clrids`.
+
+## Several files, in order
+
+The Localization tab is an **ordered list**, not a single dropdown:
+
+- Add a row, pick a file in it, and drag rows to reorder.
+- A file already picked disappears from the other rows' options — each file can appear once.
+- Remove a row to release its file back into the options.
+
+Splitting translations across files (per module, per domain, a shared base) is the normal pattern.
+
+## Merge rule: first wins
+
+Studio merges the selected files **top to bottom into one** before the app runs. A key already defined by an earlier file is **not** overridden by a later one.
+
+So the order is the precedence order: **put the file that should win first**. Adding an "overrides" file at the bottom of the list does nothing — move it to the top.
+
+## Language at runtime
+
+| Call | Does |
+|---|---|
+| `quick.Quick.getLanguage()` | Current language code. Default is `tr-TR`. |
+| `quick.Quick.setLanguage(code)` | Switches the app's language. |
+| `quick.LR(key)` | Resolves a key in events. |
+| `LR(key)` | Resolves a key in props (QScript). |
+
+`tr-TR` and `en-US` exist by default; further languages are added from the editor's **Localization → Add Language**, where each language declares its text direction (LTR / RTL).
+
+## Parametric keys
+
+Placeholders use `{}` in the text and are filled through the second argument:
+
+```typescript
+let userInfo = quick.LR('UserName', { firstName: 'Ahmet', lastName: 'Yıldız' });
+
+const person = { name: "Ahmet", surname: "Bulut" };
+let info = quick.LR('userInfo', { person });
+```
+
+## Translations from a service
+
+Localization can also arrive at runtime from a backend, imported into the same lookup:
+
+```typescript
+quick.importLocalization(langCode, resourceList, { overrite: true });
+```
+
+The usual place for this is the pipeline's `PreRender`, so it happens once at startup → [pipeline.md](pipeline.md).
+
+> The option is spelled **`overrite`**, not `overwrite`. Spelling it correctly silently disables the override.
+
+## Rules that prevent the common failures
+
+- Every key must exist in **all** supported languages; a missing key falls back to the raw key at runtime.
+- Order the files by precedence — first wins, and a later file cannot override an earlier one.
+- Don't duplicate a key across global and page `lrids` expecting the page to win; keep each key in one place.
+- Creating the file is not enough — it must be selected in App Settings → Localization. If the app has global localization files but none selected, the tab is flagged and **Export and Publish are blocked**.
+- Author `lrids`; never write `clrids`.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/appSettings/loading-component.md

@@ -0,0 +1,61 @@
+# Loading Component · the app's loading screen
+
+The screen the app shows while blocking work is in flight. Build it once and every blocking request in the app covers itself with your design instead of nothing.
+
+Selected in **App Settings → Loading** → [appSettings.md](appSettings.md).
+
+## The Loading tab holds three things
+
+| Field | What it is |
+|---|---|
+| **Web Lottie** | A Lottie animation file used for loading on web. **Add New** imports one. |
+| **Loading Component** | The `.qjson` loading screen itself — the subject of this doc. |
+| **Mobile Lottie** | The Lottie animation used for loading on mobile. |
+
+The two Lottie rows only appear if the organization has the Lottie capability. On mobile, the selected mobile Lottie is what ships as the loading animation.
+
+## When it shows
+
+The engine keeps a **counter of in-flight blocking operations**:
+
+- Counter goes to **1** → your loading qjson is rendered as a child page into the app root.
+- Counter drops to **0 or less** → the loading screen is cleared.
+
+A service call joins that counter by asking for it — `blockRender: true` on the request → [../services.md](../services.md). A request without `blockRender` runs invisibly and never raises the loading screen.
+
+Only one loading screen exists at a time, no matter how many requests overlap; it stays up until the **last** one finishes.
+
+## Driving it yourself
+
+Blocking requests raise the loading screen on their own, but you can also control it directly:
+
+```typescript
+quick.Quick.loading.show();
+quick.Quick.loading.hide();
+```
+
+Use this for slow work the network layer cannot see — a heavy computation, or a multi-step flow you want covered from start to finish.
+
+**`show()` and `hide()` are not symmetric.** `show()` adds one to the in-flight counter; `hide()` sets the counter straight to **zero**. A single `hide()` therefore tears the loading screen down for *everything* currently pending, including blocking requests you did not start.
+
+- Don't treat `hide()` as the inverse of `show()` — it is a reset, not a decrement.
+- Never call `hide()` from shared code (a pipeline handler, a reusable component) while page requests may still be running.
+- For ordinary service calls, let `blockRender` manage the counter; reach for manual control only when nothing else will raise it.
+
+## It receives nothing
+
+Unlike the Alert Component, the loading screen is rendered with **no props and no events**. It cannot know what is loading, which page asked, or how long it will take, and it has no way to call back.
+
+So: build it as a self-contained animation. Do not design it around a message passed in from the caller — there is no such message. If a screen needs a contextual "Saving…" text, that belongs on the page, not here.
+
+## Shape
+
+A normal `.qjson`: a `Messaging` root plus the visual — typically a full-screen overlay with a spinner or a Lottie animation. No parent communication, no action buttons.
+
+## Rules that prevent the common failures
+
+- Don't read `quick.parent.props` here; nothing is passed. It will be empty.
+- Don't put logic that must run per request in the loading component — it is mounted and cleared by a counter, not once per call.
+- Requests only trigger it with `blockRender: true`; if the loading screen "never appears", check that first.
+- Keep it cheap to render: it mounts on every blocking call.
+- Creating the file is not enough — it must be selected in App Settings → Loading.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/appSettings/local-proxy-file.md

@@ -0,0 +1,62 @@
+# Local Proxy File · dev-time request redirection
+
+A redirect table for **development**. It intercepts outgoing calls whose URL matches a pattern and sends them somewhere else — a service running on localhost, a different environment, or another micro-UI. It lets you point a page at real endpoints without editing the page.
+
+Selected in **App Settings → General → Local Proxy File** → [appSettings.md](appSettings.md).
+
+## It needs a switch in the Settings File
+
+The proxy is inert until the app is told to use it:
+
+```yaml
+useLocalProxyOnClient: true
+```
+
+That line goes in the **Settings File**, not here → [settings-file.md](settings-file.md). Studio's Live Preview turns it on by itself, so a mapping that works in preview but not elsewhere usually means this flag is missing.
+
+## Format
+
+YAML, one `pattern: target` pair per line. `##` starts a comment.
+
+```yaml
+## Service redirection (local)
+service/campaign-delete/: http://localhost:3002/campaignManagament-sym/campaign-delete
+
+## Service redirection (remote)
+service/campaign-create/: https://apigateway.myPlatform.onplateau.com/campaignManagament-sym/campaign-create/
+
+## API redirection
+/api/users: https://reqres.in/api/users
+
+## MicroUI redirection (URL)
+/microUI/processmanager: http://URL
+
+## MicroUI redirection (file system)
+/microUI/authorization: ../../authorization/authorizationUI
+
+## Symphony qjson redirection
+/moneytransfer/qjsonfunc: http://localhost:3001/moneytransfer/qjsonfunc
+```
+
+The key is a fragment of the outgoing URL; a request whose URL matches it is redirected to the target. Targets can be a local server, a remote environment, or — for micro-UIs — a path on disk.
+
+## What it is for
+
+| Redirect | Typical use |
+|---|---|
+| Service calls | Point a service at a locally running backend instead of the deployed one. |
+| API paths | Swap an endpoint for a mock or a public test API. |
+| Micro-UI | Load another UI from a URL or straight from the file system. |
+| qjson functions | Serve page functions from a local server. |
+
+## Development only
+
+This is a local-development mechanism. It is not a routing layer for a published app — do not design runtime behaviour around it, and do not assume a mapping here will exist for real users.
+
+## Rules that prevent the common failures
+
+- Without `useLocalProxyOnClient: true` in the Settings File the file does nothing — check that before debugging mappings.
+- When a call reaches the wrong host during preview, look here first; the page is usually innocent.
+- Keep environment-specific hosts in this file, not hard-coded in pages, so the pages stay portable.
+- Don't rely on it in published apps — it is a development tool.
+- Creating the file is not enough — it must be selected in App Settings → General → Local Proxy File.

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

@@ -0,0 +1,139 @@
+# Pipeline · app-wide request/response hooks
+
+One file per app that intercepts **every** service call and a few global lifecycle points. Use it for cross-cutting concerns — auth headers, tracing, global error handling, network-status reactions — instead of repeating that logic on every page.
+
+Selected in **App Settings → General → Pipeline**. Until it is selected there it does nothing, no matter how correct the file is → [appSettings.md](appSettings.md).
+
+## Shape
+
+A pipeline is a normal `.qjson` file whose `pJson` is a **single `Messaging` component**. All pipeline behavior lives in that component's `E` block — there is no UI.
+
+```json
+"pJson": [
+  { "T": "Messaging",
+    "P": { "ID": { "H": "pipelineComp", "T": "prop" } },
+    "E": {
+      "onBeforeRequest": { "H": "...", "C": true, "EV": true, "HL": "TS" }
+    },
+    "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "pipelineComp" } }
+]
+```
+
+## Every pipeline event needs `"EV": true`
+
+The engine calls these handlers **from outside the page**, so each one must be marked externally visible:
+
+```json
+{ "H": "…", "C": true, "EV": true, "HL": "TS" }
+```
+
+- `"EV": true` — **required**. This is the *External Visible* checkbox in the Studio editor. Only externally-visible events are registered as callable pipeline methods; when the engine fires an event it does not find, it just returns nothing. So a missing `EV` fails **silently** — no error, the pipeline simply never runs.
+- `"C": true` — custom event.
+- `"HL": "TS"` — pipeline handlers are TypeScript, not QScript.
+
+## Events
+
+| Event | Parameter | Fires |
+|---|---|---|
+| `onBeforeRequest` | `requestObject: IRequest` | Before every outgoing request. Add/update/delete headers, body, timeout. |
+| `onAfterResponse` | `response: INetworkResponse` | After every **successful** response. |
+| `onAfterErrorResponse` | `response: INetworkResponse` | After every **failed** response. |
+| `onPostRender` | — | After each page render in the app. |
+| `logHandler` | `messages: IMessage` | For every log written (page `quick.EM.trace` and engine logs). |
+| `onNetworkStatusChange` | `isNetworkConnected: boolean` | When connectivity changes (online/offline). |
+| `applicationEnd` | — | When the app shuts down: the browser unloads the page, or a host embedding the app closes/destroys it. Use it for teardown — flush logs, clear stored state, notify a host. |
+
+`applicationEnd` is **not** in the starter template and not in most sample pipelines — add it yourself when you need shutdown behavior. It is a real engine event, not a custom one.
+
+The parameter is not declared in `P`; declare it at the top of the handler:
+
+```typescript
+declare var requestObject: IRequest;
+```
+
+## Parameter shapes
+
+`requestObject` is the same `IRequest` used by `quick.Request.async` → [../services.md](../services.md). Commonly touched: `url`, `headers`, `data`, `timeout`.
+
+`response` (`INetworkResponse`): `data`, `headers`, `status`, `statusText`.
+
+`messages` (`IMessage`): `message`, `type` (`Debug` | `MobilDebug` | `Trace` | `Warning` | `Error`), `time`, `caller`.
+
+## Custom pipeline events
+
+The built-in list is not closed. A host embedding the app can trigger **any** pipeline event by name, passing its own arguments — so a pipeline can expose app-specific hooks the host calls at will. Such an event is defined exactly like the built-in ones (`"C": true`, `"EV": true`) and reads its arguments with `declare var`.
+
+Only names the pipeline actually exposes do anything; triggering an unknown name is a no-op.
+
+## Typical handlers
+
+```typescript
+// onBeforeRequest
+declare var requestObject: IRequest;
+
+requestObject.headers["pipelineKey"] = "pipelineValue";
+
+let token = quick.store.get("#authToken");
+requestObject.headers["Authorization"] = token;
+
+if (requestObject.url.indexOf("employees") > -1) {
+    requestObject.headers["pipelineKey2"] = "pipelineValue2";
+}
+
+requestObject.timeout = 20000;
+delete requestObject.headers["unwanted"];
+```
+
+```typescript
+// onAfterErrorResponse
+declare var response: INetworkResponse;
+
+quick.EM.trace(response.status);
+quick.EM.trace(response.statusText);
+response.data["handled"] = true;
+```
+
+```typescript
+// logHandler
+declare var messages: IMessage;
+
+let messageMsg = messages.message;
+let messageType = messages.type;
+let messageCaller = messages.caller;
+```
+
+```typescript
+// applicationEnd — no parameter; runs once as the app shuts down
+quick.EM.trace("application is closing");
+quick.store.set("#session", null);
+```
+
+## It can hold ordinary events too
+
+The `Messaging` component is a normal component, so you may add regular events beside the pipeline hooks — most usefully `PreRender` (`"I": true`) to bootstrap the app once, with its own custom callbacks:
+
+```typescript
+// PreRender — load localization bundles at startup
+let request1: IRequest = {
+    url: '/api/localization/bundles',
+    http: 'get',
+    data: { locale: 'tr' },
+    responseField: 'data',
+    onSuccess: 'localizationOnSuccess',
+    onFail: 'localizationOnFail',
+    blockRender: true,
+};
+quick.Request.async(request1);
+```
+
+Those callbacks are ordinary custom events (`"C": true`) and do **not** need `EV`.
+
+## Rules that prevent the common failures
+
+- **Missing `"EV": true` is the number-one pipeline bug** — the handler never runs and nothing reports it. Check it on every pipeline event.
+- Use `"HL": "TS"`; these handlers are TypeScript.
+- Declare the parameter with `declare var …` — it is not passed via `P`.
+- `onBeforeRequest` runs for **every** request; guard URL-specific logic with a check on `requestObject.url` or you will corrupt unrelated calls.
+- Mutate the given object (`requestObject` / `response`) in place; don't reassign it.
+- Creating the file is not enough — it must be selected in App Settings → General → Pipeline.
+- One pipeline per app. Don't scatter global request logic across pages when a pipeline exists.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/appSettings/settings-file.md

@@ -0,0 +1,66 @@
+# Settings File · app-level runtime knobs
+
+A YAML file of runtime settings the engine reads at startup — service URL prefixes, regional settings, back-button behaviour, and the switch that turns the local proxy on.
+
+Selected in **App Settings → General → Settings File** → [appSettings.md](appSettings.md).
+
+## The one thing to understand: authored vs generated
+
+When the app is exported or published, Studio produces a **single settings document**: your Settings File content **plus** a block of keys it generates from the App Settings selections. The generated block is appended after yours, so on a duplicate key **the generated value wins**.
+
+So there are two disjoint sets of keys, and mixing them up is the classic failure here.
+
+### Generated by Studio — never author these
+
+These come from your App Settings selections and the app's contents:
+
+| Key | Comes from |
+|---|---|
+| `rootqjson` | The app's start page. |
+| `alertqjson` | App Settings → Alert Component → [alert-component.md](alert-component.md) |
+| `loadingqjson`, `loadingfile` | App Settings → Loading → [loading-component.md](loading-component.md) |
+| `pipelineqjson` | App Settings → Pipeline → [pipeline.md](pipeline.md) |
+| `globalLocalizationqjson` | App Settings → Localization → [global-localization.md](global-localization.md) |
+| `csspath` | Every CSS file in the app → [style-file.md](style-file.md) |
+| `fontPath` | Uploaded font files. |
+| `containerServicesPath`, `componentListPath` | The matching General selections. |
+| `localproxy` | App Settings → Local Proxy File → [local-proxy-file.md](local-proxy-file.md) |
+| `title` | General → **Site title**. |
+| `iamV2` | The oAuth tab. |
+| `appSettings`, `fileMap`, `certificate` | The app's own configuration and file index. |
+
+Writing any of these by hand is at best ignored and at worst confusing — change the corresponding App Settings selection instead.
+
+### Authored here
+
+The runtime knobs App Settings has no field for:
+
+| Key | Meaning |
+|---|---|
+| `useLocalProxyOnClient` | Turns the Local Proxy File on. Required for it to do anything → [local-proxy-file.md](local-proxy-file.md) |
+| `serviceURL` | Prefix prepended to service call URLs. |
+| `selectedServiceUrl` | Which configured service URL is active. |
+| `defaultServiceHeader` | Headers added to every service call by default. |
+| `qjsonURLPrefix` | Prefix for fetching page files. |
+| `regionalDefinition` | Regional/locale settings. |
+| `disableBackManagement` | Turns off the engine's browser-back handling. |
+| `blockFontRequest` | Suppresses the automatic font request. |
+| `serviceWorkerPath` | Where the service worker is served from. |
+| `backendInf` | Backend info, including container name and IAM flags. |
+
+```yaml
+useLocalProxyOnClient: true
+serviceURL: https://apigateway.example.onplateau.com
+disableBackManagement: false
+```
+
+## Where it overlaps with the pipeline
+
+`defaultServiceHeader` sets headers statically for every call; the pipeline's `onBeforeRequest` sets them dynamically per call. Use the Settings File for constants and the pipeline for anything conditional → [pipeline.md](pipeline.md).
+
+## Rules that prevent the common failures
+
+- Never hand-write a generated key (`title`, `alertqjson`, `pipelineqjson`, `csspath`, …) — set it through App Settings; the generated value overrides yours anyway.
+- `useLocalProxyOnClient: true` lives **here**, not in the Local Proxy File. A proxy that "does nothing" is usually this line missing.
+- Put per-request logic in the pipeline, not in `defaultServiceHeader`.
+- Creating the file is not enough — it must be selected in App Settings → General → Settings File.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/appSettings/style-file.md

@@ -0,0 +1,58 @@
+# Style File · app-wide CSS
+
+Project-level CSS applied across the whole app. Created from **+ Add New → Style File**.
+
+> ⚠️ **CSS is Web-only and the last resort.** Quick renders on Web, Android and iOS; CSS exists only on Web. Style a component with its `S` object first, then its `class` prop, and only then reach for a Style File — the full priority order is in [../styling.md](../styling.md). Anything you put here simply does not exist on mobile.
+
+Legitimate uses: pseudo-selectors, project-wide rules, and `@font-face` — things neither `S` nor `class` can express.
+
+## It is not selected — it is collected
+
+Unlike every other setting file, a Style File has **no dropdown in App Settings**. Every CSS file in the app is gathered and applied automatically (a file overridden by a module override is skipped).
+
+Consequences:
+
+- Creating a Style File is enough to make it live. There is nothing to "assign", and nothing to forget to assign.
+- You cannot disable one from App Settings — to stop its rules applying, change or delete the file.
+- Rules from several files all land in the same place, so ordinary CSS specificity decides conflicts.
+
+## Multiple style files are an enterprise feature
+
+By default an app has a single Style File. Support for several CSS files is enabled per organization; once enabled, a **CSS** entry appears in **+ Add New** alongside *Style File*. If that entry is missing, the organization does not have the feature — that is not a bug.
+
+## Scoping: prefix every rule with `body .v-application`
+
+The runtime renders inside Vuetify, so a bare selector will not win. Every rule must be scoped:
+
+```css
+body .v-application .v-text-field { background: lightgrey; }
+```
+
+A rule without the `body .v-application` prefix is the single most common reason a Style File "does nothing".
+
+## Fonts and `@font-face`
+
+Font files are uploaded into the app (**+ Add New → Upload From Local**, or under a module) and referenced by their font token in `url(...)`:
+
+```css
+@font-face {
+  font-family: DXIcons;
+  src: local("DevExtreme Generic Icons"), url("<<woff2:icmn8uep-j6k3-ke30-kkam-nj2hwwav>>") format("woff2");
+}
+```
+
+Accepted formats: `.woff`, `.woff2`, `.ttf`.
+
+The `<<woff2:…>>` token is resolved to a real path when the app is exported or published. In an exported local project you may have to write the `@font-face` rule yourself with the correct font id.
+
+## Style File vs Theme
+
+They are not alternatives. A **Theme** defines named colors and fonts that pages consume through the Style tab and `S`, and it works on every platform → [theme.md](theme.md). A Style File is raw Web CSS. Put design tokens in the theme; keep the Style File for what CSS alone can do.
+
+## Rules that prevent the common failures
+
+- Confirm `S` genuinely cannot do it before writing CSS — see [../styling.md](../styling.md).
+- Never rely on a Style File for anything the app needs on mobile; it will not be there.
+- Prefix every selector with `body .v-application`.
+- Don't hard-code colors here that the theme already names.
+- Don't look for a Style File dropdown in App Settings — there isn't one; the file applies as soon as it exists.

package/dist/studio-cli/kits/ui-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/ui-app-kit/.ai-kit/ui-kit/knowledge/components.md

@@ -0,0 +1,97 @@
+# 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 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.