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

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

@@ -0,0 +1,153 @@
+# Quick qjson — agent guide (start here)
+
+You are an AI coding agent working on **Quick / Plateau Studio `.qjson` files** — UI pages that live in Studio (the web IDE). These docs are the source of truth for Quick. Follow this guide.
+
+## Step 0 — determine the style system, then follow your track guide
+
+Quick has **two style systems**, and they are not interchangeable on a page. Decide which one the target page is on **before** you style, lay out, or validate — then follow that track's guide and doc set for the rest of the task.
+
+**Read the target's root-level `opt.V`:**
+
+| Condition | Track | Guide to follow |
+|-----------|-------|-----------------|
+| **Creating a new page** | **`S` (new)** — new pages are always created at the current `V` | [s-track.md](s-track.md) |
+| **`opt.V >= 2.0`** | **`S` (new)** — the `S` object renders; author design in `S` | [s-track.md](s-track.md) |
+| **`opt.V` missing OR `< 2.0`** | **legacy (`cssClass`)** — `S` does NOT render; author `O.layout` + CSS classes | [legacy-track.md](legacy-track.md) |
+
+There is no in-between: a page is either fully `S` or fully legacy. **Do not mix mechanisms** (never introduce `S` on a legacy page — it silently won't render; never author `O.layout` on an `S` page). **The presence of an `S` object is the ground truth for which system a page is on**, and `opt.V` should agree with it (`>= 2.0` ⇔ uses `S`). If the two disagree — `opt.V >= 2.0` but the nodes carry `O.layout`, or `opt.V` missing/`< 2.0` but the nodes carry an `S` object — the page is mid-migration or mis-tagged: go by whether an `S` object is actually present, and flag the mismatch to the user.
+
+> **On Mobile, two things above work differently.** Mobile does not parse or apply `O.layout`, so legacy css declarations simply **have no effect** there — the page still renders, it is just not styled by them, and Studio's editor injects some of these fragments on its own.
+>
+> - **`opt.V >= 2.0` with leftover `O.layout` is normal on Mobile — do NOT flag it as a mismatch.** It is an ordinary `S` page. Never read `O.layout` to work out how it currently looks, author its design in `S`, and **strip its `O.layout` (`dOpt`/`class`) when you edit it**, so the page comes out clean.
+> - **`opt.V` missing or `< 2.0` on Mobile: stop.** That page is legacy and **cannot be edited from a mobile workspace** — neither style system can author it there. Tell the user and make no changes. 
+
+Your track guide lists the exact doc set to use (schema, structure, layout, styling, catalog, skeletons, validation, examples) — **open only your track's docs plus the shared docs below.**
+
+## What a `.qjson` is (one paragraph)
+A JS module exporting `pjson = { ... }`. You author `pJson` (a tree of component nodes) and `lrids` (localization) — so an **AI-authored file carries only `{ pJson, lrids, opt }`**. The editor/compiler generates the compiled twins `cJson`/`clrids`; **omit them entirely from files you author** — never write them into a new file, and **strip them if present** when editing an existing file (Studio regenerates them on import). Each node is `{ T, P, E, C, O, _Editor }` plus styling fields — `S`/`SA`/`SC` on `S`-system pages, `O.layout` on legacy pages. Full schema: `S` → [reference/qjson-schema.md](reference/qjson-schema.md); legacy → [reference/qjson-schema-legacy.md](reference/qjson-schema-legacy.md).
+
+## Where to look — shared docs (both tracks)
+These carry no style-era content; use them regardless of track:
+- **Task-oriented how-to (shared topics)** → [knowledge/properties.md](knowledge/properties.md), [events-and-scripting.md](knowledge/events-and-scripting.md), [components.md](knowledge/components.md), [services.md](knowledge/services.md), [localization.md](knowledge/localization.md), [dynamic-components.md](knowledge/dynamic-components.md).
+- **Exact API of `quick.*`** (store, alert, request, navigation, validation, dates…) → [reference/quick-api.md](reference/quick-api.md) — the authoring rules **plus a complete index of every member**. Scan that index to see what exists, then grep the member's full signature/params/example in [reference/quick-api.json](reference/quick-api.json) (per-member blocks; never read it whole).
+- **Events deep dive** → [reference/events-system.md](reference/events-system.md).
+- **Which `T` exists + registry** → [reference/component-index.json](reference/component-index.json) (machine-readable; era-agnostic).
+- **Valid props/events for a component (so you don't invent them)** → [reference/component-contracts.json](reference/component-contracts.json) (per `T`: each prop's `pType` prop/class/text/attr, value `type`, allowed `options` (enum), `default`; and `events` as `{ name, params?: [{name,type}] }`).
+- **Valid Style-tab (`S`) params for a component** → [reference/component-styles.json](reference/component-styles.json) (per `T`: supported style param → value `type` + editor `default`). **Not every component has a block** — `componentsWithStyleBlocks` in [reference/component-index.json](reference/component-index.json) lists the ones that do (and `componentsWithSC` the ones that take an `SC`), so a grep returning nothing is an answer, not a failed lookup.
+
+> **Do NOT read these big files whole.** `component-contracts.json`, `component-styles.json` (keyed per `T`, one component block each) and `quick-api.json` (keyed per API member) are lookup tables, not documents. Reading either whole wastes context and the file tools cap at 2000 lines — so a whole-file read silently truncates and you'd miss most components without knowing. Instead, **for each component you place, grep its block and read only that slice**: `grep -n '"VIcon":' reference/component-contracts.json` → a line number → `Read` that offset for ~30–60 lines. Same for an API member: `grep -n '"setRegion"' reference/quick-api.json`. Batch the lookups a section needs before writing it.
+
+> **Why read these first (the core principle):** these dictionaries are *generation inputs*. Pick the prop/event/param/style from the contract **before** you write — then you never invent something the editor rejects. Never discover the valid set by trial and error against editor/compiler messages (a raw error says *what's wrong*, not *what's right*). Look it up up front.
+
+
+**Everything else — the schema, structure, layout, styling how-to, component catalog, page skeletons, validation checklist, and examples folder — is era-specific and listed in your track guide** ([s-track.md](s-track.md) / [legacy-track.md](legacy-track.md)).
+
+
+## Workflow for every task
+1. **Read the target + neighbors.** Open the `.qjson` you'll edit and 1–2 sibling pages in the same folder. These docs give you the *rules*; sibling pages give you *project conventions* (ID style, service URLs, `QJsonPath` of any service component, navigation `<<qjson:id>>` references). Mirror them.
+2. **Classify the work** — static layout / service / table / dialog-form / chart / navigation / localization / dynamic component (any repeated rows or cards built from data). Read the matching shared `knowledge/` file(s).
+3. **Determine the style system (Step 0) and open your track guide.** Everything about *how* you build the tree's design, style, lay out, and validate lives there — follow it.
+4. **Validate** before finishing: walk your track's `validation…` checklist and fix every issue. Touched multiple files → validate them all.
+5. **Report**: changed file(s), what changed (including styling), the validation result — say plainly what was and wasn't checked — and any project assumption you made.
+
+## Non-negotiable rules — shared (both tracks)
+These apply on every page regardless of era. (Style/layout-mechanism rules are in your track guide.)
+1. **Omit `cJson`/`clrids` entirely from AI-authored files.** Author `pJson`/`lrids` only; never write the compiled twins into a new file, and **strip them if present** when editing an existing one. Studio regenerates them on import.
+2. Every node: valid `T` (check the index), unique `P.ID.H`, unique `_Editor.eID`. (eID need not equal ID.) Don't invent props **or events** — use the props/events listed for that `T` in [reference/component-contracts.json](reference/component-contracts.json), with the PType it specifies and the event `params` it gives.
+3. Strings in prop `H` are single-quoted (`"'primary'"`); booleans/numbers/expressions are bare; QScript object literals use `=` (`{text='A', value=1}`).
+4. `QLabel.text` → PType `"prop"`. `VIcon` icon name → `text` with PType `"text"` — `H` is still a QScript string, so single-quote it: `"H": "'mdi-home'"` (never bare `"mdi-home"`).
+5. Events: never native `return` (use `quick.return`); close object literals with `};`; no browser globals (`window`/`document`/`console`/`setTimeout`) — use `quick.*`. **Event handlers are always TypeScript — set `"HL":"TS"` on every handler.** (Property/binding expressions are the ones that default to `QS`.)
+6. Props use bare `LR('key')`; events use `quick.LR('key')`.
+7. **Containment** (editor-enforced, era-agnostic): `VCol` only inside `VRow` (never at root); `VRow` holds only `VCol`; `VFooter` holds only `VContainer`; canonical wrapper `VContainer > VRow > VCol > content`.
+8. Charts: only `Bar`/`Line`/`Doughnut` (no `Pie`); no `visible` prop on charts.
+9. `quick.Quick.alert({...})` always includes `actionButtons`.
+10. `VBtn` label is a child `QLabel`/`VIcon`/`VImg`, not a text prop.
+11. **If you rename/move/delete a page that others reference**, update every referrer's `<<qjson:path>>` in the same change (references are path-based, so they go stale) — see [knowledge/validation.md](knowledge/validation.md#renaming--moving--deleting-a-referenced-page--update-the-referrers-yourself).
+12. **Never paste compiled (`╬…╩╩`) content** into a file — that is generated output (see rule 1).
+
+## Easy to get wrong
+These are the rules most often assumed backwards. Check them against what you were about to write.
+- **Props *can* contain `if/else` conditionals** — QScript returns the last evaluated value.
+- **`VIcon`'s icon name uses PType `"text"`**, not `"prop"` — and `H` is still a single-quoted QScript string: `"H": "'mdi-home'"`, never `"H": "mdi-home"`.
+- **`_Editor.eID` need not equal `P.ID.H`** (equal when auto-generated; differs after a rename).
+- **Property/binding expressions default to `QS`; event handlers are always `TS`** (`"HL":"TS"` on every handler). The default applies to properties only — handlers are TS-only.
+- **`quick.store` prefixes** are Page/Bag(`#`)/Global(`$`)/Shared(`&`) — for cross-session persistence use `quick.permanentStore`.
+- **`quick.Quick.validation`** has `required/minLength/maxLength/email/iban/regex/tckn/vkn` — there is no `phone` rule (use the input's `format` + `regex`).
+- **Per-component design lives in the Style tab, not only in CSS utility classes.** How it serializes depends on the page's era — see your track guide.
+
+## When unsure
+Don't invent props/events/slots/values. Check [reference/component-index.json](reference/component-index.json) and your track's component catalog; for Vuetify components Vuetify 2 semantics apply; otherwise find a real example in a sibling page or ask the user. If a `T` isn't in the index, it's probably wrong (or the index needs updating from a newer runtime).
+
+## Calling the host from a page
+
+If this app runs inside a host — a shell, a native wrapper, a portal — it can call functions the host
+exposes, through `quick.container`. Those functions are not discovered at runtime: the app declares them in
+a **Container Configuration** (a `.container` file), one per app, each entry carrying a mock that answers
+while the app runs in Studio.
+
+Two rules catch most of the mistakes:
+
+- **A function a page calls must be declared in the container file**, and `buildQjson` cannot check that —
+  an undeclared call fails only at runtime.
+- **Call through a cast: `(<any>quick.container).<funcName>()`.** `quick.container` is typed `{}`, so a bare
+  call fails validation.
+
+The full capability — finding or creating the file, the entry shape, mocks, and the deprecated
+`quick.Quick.host.trigger` it replaces → [knowledge/container-configuration.md](knowledge/container-configuration.md).
+
+Not to be confused with the **Container Services File**, a different feature that shares the word
+→ [knowledge/appSettings/container-services-file.md](knowledge/appSettings/container-services-file.md).
+
+## MiniApp — host rules for every page
+
+The pages in this workspace are a **MiniApp**: they run inside a SuperApp shell that owns the surrounding experience. Everything in the ui-kit manual ([../../.ai-kit/ui-kit/index.md](../../.ai-kit/ui-kit/index.md)) still applies; these are the additional constraints the host imposes. Read this before authoring or editing any page here.
+
+### Non-negotiable — every page
+
+1. **Every page has a top-level `VAppBar`** carrying a back control (`quick.Quick.back()`) and an exit control that returns the user to the host app (`(<any>quick.container).stopMiniApp()`) and **shows the standard host-app image** — the `VImg` from [reference/host-app-image.json](reference/host-app-image.json), copied as-is, never a `VIcon` or another image. A page without one compiles, validates and pushes clean, and is still wrong. → [guides/miniapp-page-structure.md](guides/miniapp-page-structure.md)
+2. **Never rebuild a host-owned experience.** Payments go through the platform's payment component — no hand-built card pickers or card-number inputs. User details (name, TCKN, e-mail, phone, customer numbers) come from the host through `quick.container`, not from your own forms or services. → [guides/platform-payments.md](guides/platform-payments.md), [guides/host-functions.md](guides/host-functions.md)
+3. **Back and exit are different actions.** `quick.Quick.back()` moves within the MiniApp; `stopMiniApp` leaves it. Never substitute one for the other. → [guides/navigation-and-lifecycle.md](guides/navigation-and-lifecycle.md)
+4. **Secrets go in the project's constants**, never hard-coded into a page.
+5. **A `logHandler` in the pipeline file blocks the production build.** If you add one, say so. → [guides/analytics-and-logging.md](guides/analytics-and-logging.md)
+6. **The app has one container file** (`*.container`) declaring every host function its pages call, with a mock for each. Find it before adding a host call — the appbar's exit is one — and if the workspace has none, create it from the kit's template. Never create a second. → [../../.ai-kit/ui-kit/knowledge/container-configuration.md](../../.ai-kit/ui-kit/knowledge/container-configuration.md) for finding and creating it, [guides/host-functions.md](guides/host-functions.md) for which functions the SuperApp exposes
+
+### Corrections to the ui-kit manual
+
+These are the only ui-kit rules a MiniApp changes; each replaces the rule it names.
+
+- **Rule S4 is narrowed.** On a MiniApp page, `VAppBar` — and `VFooter` when used — are allowed and expected as top-level `pJson` siblings of the content `VContainer`, alongside `Messaging`.
+- **Call `quick.container` through a cast: `(<any>quick.container).<funcName>()`.** [quick-api.json](../../.ai-kit/ui-kit/reference/quick-api.json) rightly marks `quick.Quick.host.trigger` deprecated in favour of `quick.container`, but it types `quick.container` as `{}`, so `buildQjson` rejects a bare `quick.container.<funcName>()`. `host.trigger` remains only on older pages and inside the payment component — leave those calls alone unless asked to migrate.
+- **`quick.integrations` is missing from this workspace's API table.** Analytics still works: `quick.integrations.Dataroid.track(name, payload)`. A grep returning nothing is not an answer for it.
+- **The platform payment component is not a registry `T`.** It will not appear in [component-index.json](../../.ai-kit/ui-kit/reference/component-index.json) or [component-contracts.json](../../.ai-kit/ui-kit/reference/component-contracts.json), and that absence does **not** mean it doesn't exist — it is an embedded page reached through a `QJsonPath`.
+
+### Where the detail is
+
+| Read | For |
+|---|---|
+| [concepts.md](concepts.md) | what the host owns vs. what you own; what the project provides; how host calls behave in development |
+| [guides/miniapp-page-structure.md](guides/miniapp-page-structure.md) | the page shell and the appbar |
+| [guides/navigation-and-lifecycle.md](guides/navigation-and-lifecycle.md) | moving within the MiniApp vs. leaving it |
+| [../../.ai-kit/ui-kit/knowledge/container-configuration.md](../../.ai-kit/ui-kit/knowledge/container-configuration.md) | the container file itself — finding or creating it, the entry shape, mocks, the `(<any>…)` cast, and the deprecated `host.trigger` |
+| [guides/host-functions.md](guides/host-functions.md) | which functions the SuperApp exposes, what each returns, and the consent call patterns |
+| [guides/platform-payments.md](guides/platform-payments.md) | wiring the platform payment component |
+| [guides/analytics-and-logging.md](guides/analytics-and-logging.md) | Dataroid events, log forwarding, secrets |
+| [reference/host-functions.json](reference/host-functions.json) | each host function's purpose and rules — grep by `funcName` |
+| [reference/host-functions.container](reference/host-functions.container) | the template for the app's container file — every host function with its default mock |
+| [reference/platform-components.json](reference/platform-components.json) | the payment component's props, methods and callbacks |
+| [reference/host-app-image.json](reference/host-app-image.json) | the fixed host-app image `VImg` that goes inside the appbar's exit button |
+| [examples/](examples/) | complete MiniApp pages to copy structure from |
+
+**When a detail you need is not in these files, ask.** Do not infer host behaviour from how a standalone mobile or browser app would do it.
+
+## This workspace: the studio CLI loop
+
+These pages were pulled from Studio with the studio CLI and will be synced back. On top of the steps above:
+
+- **Validate — always, before finishing.** `studio buildQjson <file-or-folder>` runs the official Quick compiler plus the structural and `S`-style checks. It **never edits the file**: read the errors, apply every fix yourself, re-run until clean. Details: [`../cli-kit/knowledge/buildqjson.md`](../cli-kit/knowledge/buildqjson.md).
+- **Sync.** Once validation is clean and `.studio/server.json` exists (the CLI bridge is running), run `studio push` yourself — the page lands in the user's open Studio session as unsaved work. Round-trip rules, frontmatter, `<<qjson:path>>` translation, `convertToBlock`: [`../cli-kit/knowledge/sync.md`](../cli-kit/knowledge/sync.md).
+- **Render-check.** Compiling clean does not prove the page runs clean. With the `playwright` MCP available, open `http://127.0.0.1:<port>/render` (port from `.studio/server.json`), fix what the render and console show, then `browser_close`: [`../cli-kit/knowledge/render-check.md`](../cli-kit/knowledge/render-check.md).
+- **Locked files.** A pulled page may be readonly (`0444`) — checked out by someone else in Studio. Run `studio startWorking <file>`; never `chmod`.
+- **Frontmatter.** Files may carry a `---studio-metadata---` header (model id, flags like `blockComponent`). Never edit or strip it, and never rename files — Studio matches them back by name/id. A new file gets its frontmatter written back by `studio push`.
+- **Report** the validation, push and render-check results. If the bridge or the browser wasn't available, say so — never skip silently.
+
+Bridge setup and troubleshooting: [`../cli-kit/knowledge/cli-bridge.md`](../cli-kit/knowledge/cli-bridge.md).

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