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

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/13-application.md

@@ -0,0 +1,164 @@
+# 13 · Application — what a Studio app is
+
+## What an Application is
+
+An **Application** (app) is the whole project a user builds in Studio. Everything you work on — UI pages, styles, services, entities, workflows, themes — lives **inside one application**.
+
+- An app belongs to an **organization** (and, within it, an organization group).
+- The app groups all of its content into **modules** (folders, some of them shareable) that hold the individual **files**: UI pages, style files, services, and so on.
+- Each app has its own name, description, logo, color, and a set of tags.
+
+```
+organization
+└─ application
+   ├─ App Settings          ← one settings screen per app (see appSettings/)
+   ├─ setting files         ← reusable config files selected in App Settings (see appSettings/)
+   ├─ modules (folders)
+   │  └─ files …
+   └─ files: UI pages, styles, services, entities, themes, …
+```
+
+## Creating an application
+
+Apps are created from the **application list** (the screen you see after choosing an organization, *before* entering the editor), not from inside the editor.
+
+1. On the application list, choose to add a new app.
+2. Fill in **Application Name** (required, 3–25 characters) and an optional **Description** (up to 100 characters), then confirm with **CREATE**.
+3. Studio opens the new app's editor. A fresh app is essentially empty — no pages yet, and an empty App Settings.
+
+Other ways an app can come into existence:
+- **From a template** — start from a pre-built app instead of a blank one.
+- **By uploading an existing app file** — bring an app that was exported/downloaded elsewhere into this organization (Studio checks for ID conflicts on import).
+
+> **Copy App is intentionally not covered here yet — to be added later.** (Duplicating an existing app, and the "Download Application File" → upload round-trip used to move an app between organizations.)
+
+## The editor layout
+
+Once inside an app, the screen has three regions: the **top bar**, the **left explorer**, and the **work area** (where an opened file's editor appears).
+
+## Top bar (left → right)
+
+| Element | What it does |
+|---|---|
+| **Plateau logo** | Returns to the application list / organization home. Warns first if you have unsaved changes. |
+| **App logo + name** | Shows the current app. Clicking the logo lets you change the app image. |
+| **Open tabs** | Each file you open becomes a tab here; a dot marks unsaved changes. |
+| **Connect CLI / Disconnect CLI** | Connects the editor to a local folder through the Studio CLI so you can pull/push files. A status dot shows the connection state (searching, selecting a folder, pulling, connected). See [cli-bridge.md](../../cli-kit/knowledge/cli-bridge.md). |
+| **AI assistant** | Opens the in-editor AI chat helper. |
+| **Preview** | Runs the app **temporarily** without deploying it — including on a real device by scanning a QR code, plus custom-preview options. Use it to try the app while building. |
+| **Export** | Gets the app's content **out of Studio**. Two modes: *Export Compiled App Package* (download a ready-to-run zip) and *Export Uncompiled App Models* (sync the source files to a local folder). "See Progress Details" shows past exports. |
+| **Publish** | **Deploys** the app to a live host so real users can reach it. Pick **Web** and/or **Mobile**, then publish. (More below.) |
+| **Account menu** | User and organization info, Documentation, Academy, (Back Office for admins), Logout. |
+
+**Preview vs Export vs Publish** are three different things: *Preview* runs it now and throws it away; *Export* hands you the files; *Publish* puts it live.
+
+## Export
+
+Export gets the app's content **out of Studio** (as opposed to Publish, which deploys it). It requires a **Premium** account. What you see depends on the app type: a **UI app** gets the two dropdown modes below (compiled / uncompiled); a **workflow / backend** app gets the module-picker export instead.
+
+**1. Export Compiled App Package**
+- Downloads a **compiled, ready-to-run** build of the app as a zip to your device.
+- Opens a **Choose Modules to Download** picker so you can pick which modules/items to include. Each item is exported at its **published version** (or *latest* when it has none), so the package is built from versioned content.
+- Before **DOWNLOAD** enables, Studio applies checks like the workflow export below: at least one item selected and **version-ready**, all dependencies present, and all setting files assigned in App Settings.
+- It warns when a newer version of an included module exists (the export uses the updated version) or when you're about to export an **unreleased** version.
+- Use it to hand someone a runnable build or to self-host the compiled app.
+
+**2. Export Uncompiled App Models**
+- Writes the app's **uncompiled source files** to a local folder — the raw pages, styles, services, and setting files, plus a generated app-settings file and a small export-info file naming the organization and app.
+- This is the source format the Studio CLI works with. The modern way to get it locally is the **Connect CLI** bridge and a pull (see [cli-bridge.md](../../cli-kit/knowledge/cli-bridge.md)); the classic way is running the sync command shown in the dropdown from your local app folder.
+- Before it runs, Studio checks that required **tag values** are filled and that App Settings has no missing selections, and warns you if any file references are broken.
+
+**3. Workflow / Backend Export**
+- For workflow / backend apps, Export opens a **Choose Modules to Download** picker instead of the two modes above. You select exactly which items (modules, pages, workflows, services, …) to include, and Studio produces the export as a background **job**.
+- Studio validates the selection before the **DOWNLOAD** button enables:
+  - At least one item is selected.
+  - Selected items are **version-ready** (ready to publish); at least one must be.
+  - The **root** UI page is included.
+  - If a workflow is included, its required execution items are also selected (e.g. *getUser*, *notify*, *TaskPreview*, *IPaaS_Endpoint*).
+  - All **dependencies** of the selected items are present in the selection.
+  - All **setting files** are assigned in App Settings — otherwise it links you to the Settings page to fix it first.
+- It warns when a newer version of an included module exists (the export uses the updated version), or when you're about to export an **unreleased** version.
+- Because it runs as a job, the finished export shows up under **See Progress Details**.
+
+**See Progress Details** lists past and running exports.
+
+> Compiled vs uncompiled: the **compiled package** runs as-is; the **uncompiled models** are the editable source you sync locally — e.g. to work on `.qjson` files with the CLI and this kit.
+
+## Publish
+
+The Publish menu deploys the current app:
+
+- **Web** — publishes the web build. Once published, the menu shows *when* and *by whom* it was last published and a link to the live web app.
+- **Mobile** — publishes to **StudioApps** (Plateau's mobile host). The menu shows a QR code to open the app on a phone, a copyable link, and App Store / Google Play links for the StudioApps container app.
+- After choosing platforms, **Publish Application** starts the deploy; **See Progress Details** tracks running/past publishes.
+- Publishing requires the app to have content and the organization to have deploy permission. An empty app cannot be published.
+- Depending on the organization, the Publish menu may instead offer **Create Package** — bundling a specific **App Version** (see below) for delivery rather than a direct deploy.
+
+## App Versions
+
+**App Versions** are named **snapshots** of the app's files, kept for versioning and rollback — independent of publishing.
+
+- Managed from the **App Versions** tab inside App Settings (see [appSettings](appSettings/appSettings.md)), and also reachable when creating a delivery package.
+- You can create a new version, list existing versions, delete one, or build a package from a chosen version.
+- A version captures the set of files as they were at that moment; it does **not** change the app's live deployment by itself.
+
+> Publish and App Versions are separate: *Publish* makes the app reachable by users; *App Versions* preserves a copy of the app's files at a point in time.
+
+## Explorer
+
+The left panel lists everything in the app as a tree and is where you create, open, and organize files.
+
+**App actions** (the "**⋯**" menu next to the app name):
+
+| Action | Meaning |
+|---|---|
+| Edit | Change the app's name/description. |
+| Download Application File | Save the whole app to a file (used to move/copy an app — *Copy App, covered later*). |
+| Delete | Remove the app. |
+| Change App Image | Set the app logo. |
+| Info | App details (counts, dates). |
+| Bulk Save and Version | Save all your checked-out work at once and create a version. |
+| Bulk Stop Working | Release all your checkouts at once. |
+
+**Toolbar icons** next to it: **Reload Cache** (refresh the tree), **Expand/Collapse All**, and collapse the panel.
+
+**Search area** — two tabs:
+- **Model Search** — search files by name or ID, with **filter chips** (All / UI / Asset / and more, scrollable) to narrow the tree to certain file types.
+- **Find in Models** — search (and replace) *inside* file contents across the app, with case / whole-word / regex options.
+
+**The tree** — modules and folders containing files. Each file shows a type icon; a **checkmark** next to a file means **you have it checked out** (you're the one working on it, so it's editable). Right-click / row actions let you open, check out, rename, move, and delete items.
+
+**"Try New A.I. Feature"** card — turns a design into a UI page via AI.
+
+**+ Add New** — the create menu (next section).
+
+**⚙ gear** (bottom of the panel) — opens **App Settings** ([appSettings](appSettings/appSettings.md)). This is the main entry point to the app-wide configuration.
+
+## The "Add New" menu
+
+**+ Add New** opens a grouped menu of everything you can create in the app. Which groups and items appear depends on the app's capabilities (a UI-only app won't show workflow/backend items).
+
+| Group | What you can create |
+|---|---|
+| **User Interface** | UI Page with AI, UI Page, Global Localization, Theme Group, CSS, Style File, Alert Component, Loading Component, Component List |
+| **Business Logic** | Workflow, Decision Table, Job Scheduler, SLA Definition |
+| **Data** | Data Type, Data Set, Constant |
+| **Services & Integration** | Backend Function, Workflow Function, REST Service, SOAP Service (from WSDL), Endpoint |
+| **Security & Access** | Persona, Role, Swimlane, Action, Privilege, Certificate |
+| **Application Configuration** | Settings File, Container Configuration, Pipeline, Local Proxy File, Container Services File, Container Services Intellisense |
+| **Project Organization** | Module, Folder |
+| **Import & Migration** | Import Module, Upload From Local |
+
+Note that several **User Interface** and **Application Configuration** items (Global Localization, Theme Group, Style File, Alert Component, Loading Component, Component List, Settings File, Pipeline, Local Proxy File, Container Services…) create **setting files** — the reusable config files an app points to from App Settings. See [appSettings](appSettings/appSettings.md).
+
+## App type: UI vs workflow
+
+An app is either a normal **UI app** or a **workflow app**. The difference mainly affects which page is treated as the app's **entry point** (start page), and which of the Add New groups above are available. Day-to-day page authoring is the same in both.
+
+## What to take from this
+
+- A qjson workspace is **one app**; its App Settings and setting files sit next to the pages.
+- **Preview** (try it now), **Export** (get the files), and **Publish** (deploy live) are three distinct actions.
+- **App Versions** are point-in-time snapshots, separate from publishing.
+- The **⚙ gear** in the explorer opens **App Settings**; **+ Add New** creates files — including the setting files App Settings points to.
+- To understand *how the app is configured* and the reusable *setting files* it points to, read [appSettings](appSettings/appSettings.md).

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

@@ -0,0 +1,91 @@
+# Alert Component · the app's alert UI
+
+One file per app that renders **every** `quick.Quick.alert(...)` call. Build it once and every alert in the app — confirmations, network errors, validation errors — gets your design instead of the framework default.
+
+Selected in **App Settings → General → Alert Component**. Until it is selected there it does nothing → [appSettings.md](appSettings.md).
+
+## With and without it
+
+| | |
+|---|---|
+| **Not selected** | The engine renders a built-in `VAlert`: dismissible, coloured border, and an icon chosen from `category` (`Info` → `mdi-information`, `Success` → `mdi-check-circle`, `Warning` → `mdi-alert-circle`, `Error` → `mdi-close-circle`). |
+| **Selected** | Your qjson is rendered instead, as a child page injected at the top of the app shell. The built-in alert is not used at all. |
+
+## Shape
+
+A normal `.qjson` file: a `Messaging` root plus whatever UI you want (typically a Dialog or a card). It is rendered as a **child page**, so it talks to the caller through `quick.parent`.
+
+## What it receives — `quick.parent.props`
+
+| Prop | Type | Meaning |
+|---|---|---|
+| `title` | string | Header text. |
+| `text` | string | Message body. |
+| `category` | `Warning` \| `Info` \| `Success` \| `Error` | Severity. |
+| `actionButtons` | array | `{ name?, type, clickEventName? }`; `type` is `Confirm` or `Cancel`. |
+| `error` | object | `{ errorMessage?, errorCode?, errorSource? }`; `errorSource` is `Page`, `Network` or `Validation`. |
+| `additionals` | object | `{ props?, events? }` — free-form extras from the caller. |
+
+Read them once the page is up, normally in `PostRender`:
+
+```typescript
+if (quick.parent.props) {
+    components.alertHeader.type = quick.parent.props.category;
+    components.alertHeaderText.text = quick.parent.props.title;
+    components.alertText.text = quick.parent.props.text;
+}
+```
+
+`error` is what tells the three cases apart — branch on `quick.parent.props.error?.errorSource` to lay out validation errors, network errors and plain confirmations differently.
+
+## What it calls back — `quick.parent.events`
+
+```typescript
+quick.parent.events.onConfirm();
+quick.parent.events.onCancel();
+```
+
+The engine wires these from `actionButtons` **by `type`**: the `Confirm` button's `clickEventName` becomes `onConfirm`, the `Cancel` button's becomes `onCancel`. Calling one fires that custom event **on the component that raised the alert**.
+
+Consequences worth knowing:
+
+- If the action button carried no `clickEventName`, calling the matching parent event does nothing. That is normal for an OK-only alert, not a bug.
+- These callbacks **do not dismiss the alert**. Closing is your job — hide your dialog or call `quick.Quick.closeAlert()`.
+
+## Closing
+
+- `quick.Quick.closeAlert()` — from anywhere; tears the alert page down.
+- Only **one** alert exists at a time: raising a new one removes the current one first.
+- **`additionals.props.timeout` does not auto-close a custom alert.** The engine's timeout auto-close only runs on the built-in fallback alert. With an Alert Component selected you receive `timeout` inside `quick.parent.props.additionals` and must honour it yourself — in `PostRender`:
+
+```typescript
+let timeout = quick.parent.props.additionals?.props?.timeout;
+if (timeout) {
+    setTimeout(() => { quick.Quick.closeAlert(); }, timeout);
+}
+```
+
+## How callers raise alerts
+
+```typescript
+quick.Quick.alert({
+    title: 'Onay',
+    text: 'Kayıt silinecektir, onaylıyor musunuz?',
+    category: 'Warning',
+    actionButtons: [
+        { name: 'Onayla', type: 'Confirm', clickEventName: 'onDeleteConfirmed' },
+        { name: 'İptal',  type: 'Cancel',  clickEventName: 'onDeleteCancelled' }
+    ]
+});
+```
+
+`onDeleteConfirmed` / `onDeleteCancelled` are custom events (`"C": true`) on the calling component — that is where the work goes, not in the alert file.
+
+## Rules that prevent the common failures
+
+- Render nothing until `quick.parent.props` exists; reading it too early gives you an empty alert.
+- Handle the `error` shape as well as `title`/`text` — network and validation alerts arrive with `error` set and often no `text`.
+- Don't expect `onConfirm`/`onCancel` to close the dialog; close it yourself.
+- Don't rely on `timeout` auto-closing — implement it from `additionals` when a custom alert is selected.
+- Keep business logic in the caller's `clickEventName` events; the alert file is presentation.
+- Creating the file is not enough — it must be selected in App Settings → General → Alert Component.

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

@@ -0,0 +1,204 @@
+# App Settings · overview
+
+Every app has **exactly one** App Settings — its app-wide configuration. It decides which theme, localization, alert, loading and pipeline files the running app uses. You will rarely edit it, but you must understand it: it determines whether the pages you author actually behave the way you expect.
+
+## Why you care
+
+- Localization keys in your pages resolve only if a **Global Localization** file is selected → [global-localization.md](global-localization.md).
+- Theme tokens and app-wide CSS come from the selected **Theme** and **Style File** → [theme.md](theme.md), [style-file.md](style-file.md).
+- Framework alerts render through the selected **Alert Component** → [alert-component.md](alert-component.md).
+- Every service call passes through the selected **Pipeline** → [pipeline.md](pipeline.md).
+- If a required selection is missing, **Export and Publish are blocked** — the app cannot ship no matter how correct your pages are.
+
+## It points at files, it does not contain them
+
+Most of App Settings is a **dropdown that selects a file**:
+
+1. The file is created — in Studio via **+ Add New** in the Explorer, or from the CLI (below).
+2. It is **selected** in the matching App Settings dropdown.
+3. Only then does the app use it.
+
+Creating the file is **not** enough. A setting file sitting in the workspace but not selected does nothing.
+
+The rest of App Settings is direct configuration (site title, Shadow DOM, oAuth, log levels, tags) stored in App Settings itself.
+
+## You can edit it yourself
+
+App Settings is pulled into the workspace like any other model, and it is pushable. So when you create a setting file, **wire it up yourself** — don't hand that back to the user as a manual step.
+
+| | |
+|---|---|
+| **Do** | Read it to see which setting files are active, and author your pages against them. |
+| **Do** | Edit it to select a file you just created, then push it with the rest of your work. |
+| **Don't** | Create a second App Settings. It is a singleton — one per app. |
+| **Don't** | Hand-write the keys Studio generates on export → [settings-file.md](settings-file.md). |
+
+In Studio it opens from the **⚙ gear** at the bottom of the Explorer panel; the user needs that only to review your change.
+
+## Creating a new setting file from the CLI
+
+A setting file is not just a `.qjson` with the right content — Studio also has to mark it `usageType: appSettings` with a `key` (`pipeline`, `alert`, …) so it shows up in the right App Settings dropdown at all. A plain file you create and push yourself does **not** get these — it lands as an ordinary page, invisible to App Settings.
+
+So creation goes through Studio's own setting-creation flow, triggered by frontmatter:
+
+1. Create the file **empty**, with frontmatter declaring `id: new` and `settingKey: <key>`:
+
+   ```
+   ---studio-metadata DO NOT EDIT---
+   id: new
+   settingKey: pipeline
+   ---studio-metadata DO NOT EDIT---
+   ```
+
+   `settingKey` is the value from the **Setting file** column below. Match the file's extension to what that setting expects (qjson/yaml/ts/css/…) — the per-file doc says which; if you get it wrong, push reports the exact extension required.
+
+2. **Push.** Studio creates the file through its own template — proper `key`, `usageType`, and starter content — and the CLI writes the real `id` plus that template body back into the file, replacing what you had.
+
+3. **Pull is not required** — the write-back happens automatically as part of the same push. Open the file, edit the template into what you need, and push again normally from then on.
+
+If the `settingKey` is unknown or unavailable for this organization, or the extension doesn't match, push fails with an error naming the problem — nothing is created.
+
+| Setting file | `settingKey` | Doc |
+|---|---|---|
+| Pipeline | `pipeline` | [pipeline.md](pipeline.md) |
+| Alert Component | `alert` | [alert-component.md](alert-component.md) |
+| Loading Component | `loading` | [loading-component.md](loading-component.md) |
+| Global Localization | `globalLocalization` | [global-localization.md](global-localization.md) |
+| Theme | `theme` | [theme.md](theme.md) |
+| Style File | `style` | [style-file.md](style-file.md) |
+| Settings File | `settings` | [settings-file.md](settings-file.md) |
+| Local Proxy File | `localProxy` | [local-proxy-file.md](local-proxy-file.md) |
+| Component List | `componentList` | [component-list.md](component-list.md) |
+| Container Services File | `containerServices` | [container-services-file.md](container-services-file.md) |
+| Container Services IntelliSense | `containerServIntelli` | [container-services-intellisense.md](container-services-intellisense.md) |
+
+This `id: new` + `settingKey` frontmatter is specific to setting files. An ordinary new page instead carries **no** frontmatter at all and still becomes a new model on push — see [sync.md](../../../cli-kit/knowledge/sync.md).
+
+## Editing App Settings itself from the CLI
+
+The local file is named after the model with an `.appSettings` extension (`App Settings.appSettings`) and carries the usual frontmatter `id`.
+
+Like any pulled model it arrives **readonly** unless it is checked out. If you cannot write to it, check it out first — don't `chmod` it → [cli-bridge.md](../../../cli-kit/knowledge/cli-bridge.md):
+
+```bash
+studio startWorking "App Settings.appSettings"
+```
+
+Its body is JSON:
+
+```json
+{
+  "general": {
+    "siteTitle": "Saha Servis",
+    "pipeline": "<<pipeline:settings/appPipeline>>",
+    "alert": "<<alert:settings/appAlert>>",
+    "loading": "<<loading:settings/appLoading>>",
+    "useShadowDOM": false
+  },
+  "globalLocalization": "<<globalLocalization:settings/common, settings/errors>>",
+  "themeSettings": { "themeModelId": "…", "defaultTheme": "corporate" },
+  "logging": {}, "tagValues": {}, "oAuthSettings": {}
+}
+```
+
+**Selections are reference tokens, and locally they hold file *paths*, not ids.** The bridge rewrites `<<type:id>>` → `<<type:diskPath>>` on pull and back on push, so you wire a setting by writing the target file's workspace path — no extension, forward slashes, prefixed with its module name when it lives in one.
+
+| Where | Key | Value |
+|---|---|---|
+| `general` | `pipeline`, `alert`, `loading`, `settings`, `localProxy`, `componentList`, `containerServices`, `containerServIntelli` | `<<key:path/to/file>>` |
+| `general` | `webLoading`, `mobileLoading` | `<<lottie:path/to/file>>` |
+| `general` | `siteTitle`, `useShadowDOM`, `renderCCOnEdit` | plain values |
+| root | `globalLocalization` | `<<globalLocalization:pathA, pathB>>` — **ordered, first wins** → [global-localization.md](global-localization.md) |
+| root | `themeSettings.themeModelId` | see below |
+
+> **`themeModelId` is the exception.** It is stored as a bare model id, not a `<<…>>` token, so the bridge does **not** convert it to a path — it stays an id locally. To select a theme, copy the target theme file's `id` from its frontmatter.
+
+A file only has a usable id/path once it has been **created through the flow above and pushed**. So the order is: create the setting file (`id: new` + `settingKey`) and push it first, then reference its now-real path in App Settings and push that.
+
+## Tabs
+
+| Group | Tab | What it holds |
+|---|---|---|
+| **Settings** | **General** | Site title, app image, and the selection of most setting files. |
+| | **App Versions** | Named snapshots of the app's files. Not part of the app's configuration. |
+| | **Localization** | Selects the **Global Localization** file(s) that give the app its languages. |
+| **User Interface** | **Themes** | Selects the app's **Theme**; older apps are migrated here. |
+| | **Loading** | Selects the **Loading Component** and the loading animations for web and mobile. |
+| **Connections** | **Tags** | Values for the app's tags. Must be filled before export. |
+| | **oAuth** | Identity-provider / login configuration. |
+| | **Integrations** | Third-party integrations — activate one for its token, or define custom ones. |
+| **Other** | **Log** | Log level, log type and bulk size. |
+
+A tab carries an **alert icon** when something in it is unassigned or points at a file that no longer exists.
+
+## Which tabs you actually see
+
+The tab list is not identical in every app:
+
+| What | When it is hidden |
+|---|---|
+| **App Versions** tab | Hidden unless the *App Version* feature is enabled for the organization (or its organization group). This is the **only tab** that is conditionally hidden — every other tab is always present. |
+
+Beyond that, the tabs are always there but their **content** depends on what the app can use:
+
+- A file dropdown lists only setting files **of its own kind that exist in this app**. None created → the dropdown is empty (just *Select*).
+- Which kinds can be created at all depends on the organization's enabled capabilities — the same flags that drive **+ Add New**. A UI-only app has no workflow/backend files to select; without the container capability there are no Container Configuration files.
+- An empty dropdown therefore means "none of that kind exists here" or "that capability is off" — not that something is broken.
+
+## The General tab
+
+| Field | Kind | Meaning |
+|---|---|---|
+| **Application name** | read-only | Edit with the pencil. |
+| **Site title** | text | Title shown in the browser tab. |
+| **Container Services** | file | → [container-services-file.md](container-services-file.md) |
+| **Container Services Intellisense** | file | → [container-services-intellisense.md](container-services-intellisense.md) |
+| **Component List** | file | → [component-list.md](component-list.md) |
+| **Show Block Components On Edit Mode** | Yes / No | Renders block components while editing. Editor-only; never reaches the running app. |
+| **Settings File** | file | → [settings-file.md](settings-file.md) |
+| **Alert Component** | file | → [alert-component.md](alert-component.md) |
+| **Local Proxy File** | file | → [local-proxy-file.md](local-proxy-file.md) |
+| **Pipeline** | file | → [pipeline.md](pipeline.md) |
+| **Use Shadow DOM** | Yes / No | Renders the app inside a Shadow DOM. |
+| **App Image** | image | The app logo. |
+
+## The setting files
+
+| Setting file | Selected in | Doc |
+|---|---|---|
+| Settings File | General | [settings-file.md](settings-file.md) |
+| Alert Component | General | [alert-component.md](alert-component.md) |
+| Local Proxy File | General | [local-proxy-file.md](local-proxy-file.md) |
+| Pipeline | General | [pipeline.md](pipeline.md) |
+| Container Services File | General | [container-services-file.md](container-services-file.md) |
+| Container Services IntelliSense | General | [container-services-intellisense.md](container-services-intellisense.md) |
+| Component List | General | [component-list.md](component-list.md) |
+| Loading Component | Loading | [loading-component.md](loading-component.md) |
+| Global Localization | Localization | [global-localization.md](global-localization.md) |
+| Theme | Themes | [theme.md](theme.md) |
+| Style File | *(applied automatically)* | [style-file.md](style-file.md) |
+
+## When a setting is broken
+
+A setting counts as **invalid** when it is empty, or points at a file that was deleted or is no longer a setting file of that kind.
+
+A kind is only **required** once the app contains at least one setting file of that kind. Creating the first Pipeline file is what makes an unassigned *Pipeline* a problem; an app that never had one is not nagged about it.
+
+Consequences — none of them cosmetic:
+
+- The tab shows an alert icon and the dropdown is highlighted.
+- Opening the app can raise a **Settings Selection Required** dialog.
+- **Export** and **Publish** refuse to run until every required setting file is assigned.
+- Apps on an old theme setup get **Theme Migration Required** on the Themes tab.
+
+Most of this you can fix yourself: point the setting at a valid file, or remove the key to clear it, then push. The exception is **theme migration**, which only the Migrate button in Studio performs — report that one and let the user run it.
+
+## Rules that prevent the common failures
+
+- Never author a second App Settings, and never assume one is in a state you did not read.
+- A new setting file needs `id: new` + `settingKey` frontmatter and a push — writing a plain file yourself creates an ordinary page, not a setting file.
+- A setting file has **no effect until it is selected here** — creating one and stopping is an unfinished job, not a handoff.
+- Push a new setting file **before** referencing it, so its path resolves to a real id.
+- Reference files by workspace **path** inside `<<…>>` tokens; `themeSettings.themeModelId` is the lone id-valued exception.
+- Don't diagnose an empty dropdown as breakage; check whether that kind of file exists in the app at all.
+- Before reporting the app ready to export, check that nothing is left unassigned.

package/dist/studio-cli/kits/ui-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/ui-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. |
+| `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** | An editor where you declare the host functions a miniapp may call, with parameters, return types and mock data. Those become `quick.container.yourFunction()` in page code. Created from **+ Add New → Container Configuration**. |
+
+If the task is "call a function on the superapp 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/ui-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.