@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/component-list.md

@@ -0,0 +1,63 @@
+# Component List · the app's component prop catalog
+
+Declares, per component type, **which props exist**, their types, their allowed values and their editor defaults. It is what makes a component's props appear in the Studio property panel and gives them defaults.
+
+Selected in **App Settings → General → Component List** → [appSettings.md](appSettings.md).
+
+For the built-in components and their `S` params, use the kit's own reference — [../components.md](../components.md) and [../reference/component-styles.json](../../reference/component-styles.json). The Component List is the **app-level** catalog: where a project describes its domain components and any extra props.
+
+## Shape
+
+A JS/TS module holding a `componentOptions` object keyed by component type, exported under the name `plateauUIComponentOptions`:
+
+```javascript
+var componentOptions = {
+    QOtp: {
+        qValue:       { type: "Array<any>" },
+        length:       { type: Number,  editorDefaultValue: "4" },
+        type:         { type: String,  options: ["'number'", "'text'", "'password'"], editorDefaultValue: "'text'" },
+        preventPaste: { type: Boolean, editorDefaultValue: "true" },
+        width:        { type: String,  editorDefaultValue: "'147px'" },
+        readonly:     { type: Boolean }
+    }
+};
+
+if (typeof exports === 'object' && typeof module === 'object') {
+    module.exports = componentOptions;
+} else {
+    window["plateauUIComponentOptions"] = componentOptions;
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `type` | The prop's type — `String`, `Number`, `Boolean`, or a type name as a string (`"Array<any>"`). |
+| `options` | The allowed values, offered as a dropdown in the editor. |
+| `editorDefaultValue` | The value the editor pre-fills when the prop is added. |
+
+## Values use the prop-`H` quoting model
+
+`options` and `editorDefaultValue` are written the same way a prop's `H` is → [../properties.md](../properties.md):
+
+| Value | Write |
+|---|---|
+| string | single-quoted inside the string — `"'text'"`, `"'147px'"` |
+| number | bare — `"4"` |
+| boolean | bare — `"true"` |
+
+Writing `"text"` instead of `"'text'"` yields an identifier, not a string — the classic mistake here.
+
+## What it changes
+
+- **In the editor:** which props a component offers, their dropdowns, and their pre-filled defaults.
+- **At runtime:** it is handed to the renderer as the app's component settings.
+
+It describes props; it does not implement components. A component still has to exist for the app to render it — declaring props for an unknown type gives you editor entries that render nothing.
+
+## Rules that prevent the common failures
+
+- Quote values as you would in a prop `H` — strings single-quoted inside the string, numbers and booleans bare.
+- Don't duplicate the built-in registry here; consult [../reference/component-styles.json](../../reference/component-styles.json) for built-ins and keep this file for the app's own components.
+- `editorDefaultValue` only pre-fills the editor — it is not a runtime fallback. A page that never sets the prop does not get this value at runtime.
+- Adding a prop here does not create behaviour; the component must already support it.
+- Creating the file is not enough — it must be selected in App Settings → General → Component List.

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

@@ -0,0 +1,71 @@
+# Container Services File · the host integration layer
+
+A JS module of **callbacks the hosting container provides to the app**. When the app runs inside a shell — a superapp, a native wrapper, another portal — this file is how the runtime asks the host for things: the current user, the real URL for a call, the device scanner, logout.
+
+Selected in **App Settings → General → Container Services** → [appSettings.md](appSettings.md).
+
+## Shape
+
+A module exporting an object under the name `plateauUIContainerServices`. Every member is optional — implement only the hooks your host actually supports; the runtime falls back to its own behaviour for the rest.
+
+```javascript
+var containerServices = {
+    getURL: function (url, mode) {
+        // mode is "ui" or "service"; return the final URL
+        return environmentBase + url;
+    },
+    userContextCb: function () { return host.currentUser; },
+    logout: function () { host.signOut(); }
+};
+
+if (typeof exports === 'object' && typeof module === 'object') {
+    module.exports = containerServices;
+} else {
+    window["plateauUIContainerServices"] = containerServices;
+}
+```
+
+## The hooks
+
+| Hook | Purpose |
+|---|---|
+| `getURL(url, mode)` | Resolve the final URL for a call. `mode` is `"ui"` or `"service"`. The place to do environment-based domains and proxying. |
+| `hostTriggerCb(functionName, params, pageNameArray)` | Invoke a function on the host. This is what backs `quick.Quick.host.trigger` — deprecated in favour of Container Configuration and `quick.container`, but still needed by the pages that call it. |
+| `getPlateauIAM()` | The host's IAM object. |
+| `authenticatedCb()` | Whether the user is authenticated. |
+| `userContextCb()` / `customerContextCb()` | Current user / customer context. |
+| `getCurrentLanguageCb()` | The host's active language. |
+| `resourceCb(resource)` | Fetch a resource from the host. |
+| `getStoreDataCb(storeData)` | Read host-side stored data. |
+| `callMessageBox(messageType, messages, title)` | Show a host-native message box. |
+| `print` / `scan` / `ocr` / `biometric` | Device capabilities exposed by the host. |
+| `getContainerName()` | Identify the host. |
+| `logout()` | Log out through the host. |
+| `network` | Host-provided network layer. |
+| `extensions` | Named custom hooks — see below. |
+
+## `extensions` can take over engine behaviour
+
+`extensions` holds host-specific named hooks, and some of them **replace** what the engine would otherwise do. The clearest case: if `extensions.loadingCounter` exists, the engine hands loading state to it and **does not render the Loading Component at all** → [loading-component.md](loading-component.md).
+
+So when a selected Loading Component never appears in a hosted app, check this file before assuming the loading setting is wrong.
+
+## Not the same as Container Configuration
+
+Two different things share the word "container":
+
+| | |
+|---|---|
+| **Container Services File** *(this doc)* | A JS file of low-level host callbacks the **runtime** calls. Selected in App Settings → General. |
+| **Container Configuration** | A separate model — *not* a setting file — where you declare the host functions the app may call, with parameters, return types and mock data. Those become `quick.container.yourFunction()` in page code. Created from **+ Add New → Application Configuration → Container Configuration**, or from the CLI as a `.container` file. |
+
+If the task is "call a function on the host from a page", that is `quick.container.*` and Container Configuration — not this file.
+
+## Rules that prevent the common failures
+
+- Every hook is optional; implement only what the host supports rather than stubbing the whole interface.
+- `getURL` runs for both UI and service loads — branch on `mode` or you will rewrite URLs you didn't mean to.
+- Check `extensions` before debugging "the engine ignores my setting"; an extension may be taking that behaviour over.
+- Don't put page logic here — this file belongs to the host integration, not to any screen.
+- Keep it in step with its IntelliSense companion → [container-services-intellisense.md](container-services-intellisense.md).
+- Creating the file is not enough — it must be selected in App Settings → General → Container Services.

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

@@ -0,0 +1,42 @@
+# Container Services IntelliSense · editor type hints for the host layer
+
+A declarations file that tells the **Studio code editor** what the Container Services File exposes, so those calls autocomplete and type-check while you write handlers.
+
+Selected in **App Settings → General → Container Services Intellisense** → [appSettings.md](appSettings.md).
+
+## It is editor-only
+
+This is the one setting file that **never reaches the running app**. It is not written into the app's runtime settings and the engine has no notion of it — it exists purely to make authoring easier.
+
+What follows from that:
+
+- Changing it cannot fix, break, or alter any runtime behaviour. If a host call misbehaves at runtime, the bug is in the Container Services File → [container-services-file.md](container-services-file.md).
+- An app can run perfectly with this setting empty; you simply lose autocomplete.
+- It is not proof of anything. A member declared here may not exist in the services file at all.
+
+## Shape
+
+TypeScript declarations mirroring the surface the services file implements:
+
+```typescript
+interface IContainerServices {
+    getURL?(url: string, mode: "ui" | "service"): string | undefined;
+    userContextCb?(): IUserContext;
+    getContainerName?(): string;
+    logout?(): any;
+}
+```
+
+## Nothing keeps it in sync
+
+The two files are matched by convention only — no build step, no validation, and no warning when they disagree. Drift is silent and shows up as **autocomplete that lies**: a suggested member that does not exist, or a real member the editor never offers.
+
+When you change the Container Services File, update this one in the same pass.
+
+## Rules that prevent the common failures
+
+- Never diagnose a runtime problem from this file; it does not run. Read the services file.
+- Don't trust it as an inventory of what the host supports — verify against the services file.
+- Update both files together; nothing will tell you they have drifted.
+- An empty selection here is harmless, unlike the other General settings.
+- Creating the file is not enough — it must be selected in App Settings → General → Container Services Intellisense.

package/dist/studio-cli/kits/miniapp-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/miniapp-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/miniapp-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/miniapp-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/miniapp-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/miniapp-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.