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

package/dist/common/helpers/aiKitResolver.js

@@ -1,12 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveKitName = exports.getKitName = exports.getAppType = void 0;
+exports.resolveKitName = exports.getKitName = exports.getAppType = exports.MOBILE_MODULE_NAME = void 0;
 const appFlagsHelper_1 = require("./appFlagsHelper");
+// An app that imports this module is a mobile app.
+exports.MOBILE_MODULE_NAME = "MiniAppCore";
 const KIT_BY_APP_TYPE = {
     ui: "ui-app-kit",
     workflow: "wf-app-kit",
+    mobile: "mobile-app-kit",
 };
-function getAppType(flags) {
+// Mobile is checked first: a mobile app also has qjson models and would otherwise read as ui.
+function getAppType(flags, moduleNames) {
+    if (moduleNames.has(exports.MOBILE_MODULE_NAME))
+        return "mobile";
     if (flags.ui)
         return "ui";
     if (flags.workflow)
@@ -18,10 +24,10 @@ function getKitName(kind) {
     return KIT_BY_APP_TYPE[kind];
 }
 exports.getKitName = getKitName;
-// Single source of the "model types → which kit" decision (studio-cli pull + agenticStudio);
+// Single source of the "model types + modules → which kit" decision (studio-cli pull + agenticStudio);
 // hard-errors when the app type maps to no kit.
-function resolveKitName(modelTypes) {
-    const appType = getAppType((0, appFlagsHelper_1.deriveAppFlags)(modelTypes));
+function resolveKitName(modelTypes, moduleNames = new Set()) {
+    const appType = getAppType((0, appFlagsHelper_1.deriveAppFlags)(modelTypes), moduleNames);
     const kitName = getKitName(appType);
     if (!kitName)
         throw new Error(`no kit for app type "${appType}"`);

package/dist/common/helpers/aiKitResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"aiKitResolver.js","sourceRoot":"","sources":["../../../../common/helpers/aiKitResolver.ts"],"names":[],"mappings":";;;AACA,qDAAkD;AAOlD,MAAM,eAAe,GAAsC;IACvD,EAAE,EAAE,YAAY;IAChB,QAAQ,EAAE,YAAY;CACzB,CAAC;AAEF,SAAgB,UAAU,CAAC,KAAgB;IACvC,IAAI,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAC;IACtC,OAAO,iBAAiB,CAAC;AAC7B,CAAC;AAJD,gCAIC;AAED,SAAgB,UAAU,CAAC,IAAa;IACpC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAFD,gCAEC;AAED,6FAA6F;AAC7F,gDAAgD;AAChD,SAAgB,cAAc,CAAC,UAA+B;IAC1D,MAAM,OAAO,GAAG,UAAU,CAAC,IAAA,+BAAc,EAAC,UAAU,CAAC,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,GAAG,CAAC,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC;AALD,wCAKC"}
+{"version":3,"file":"aiKitResolver.js","sourceRoot":"","sources":["../../../../common/helpers/aiKitResolver.ts"],"names":[],"mappings":";;;AACA,qDAAkD;AAOlD,mDAAmD;AACtC,QAAA,kBAAkB,GAAG,aAAa,CAAC;AAEhD,MAAM,eAAe,GAAsC;IACvD,EAAE,EAAE,YAAY;IAChB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,gBAAgB;CAC3B,CAAC;AAEF,8FAA8F;AAC9F,SAAgB,UAAU,CAAC,KAAgB,EAAE,WAAgC;IACzE,IAAI,WAAW,CAAC,GAAG,CAAC,0BAAkB,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzD,IAAI,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAC;IACtC,OAAO,iBAAiB,CAAC;AAC7B,CAAC;AALD,gCAKC;AAED,SAAgB,UAAU,CAAC,IAAa;IACpC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAFD,gCAEC;AAED,uGAAuG;AACvG,gDAAgD;AAChD,SAAgB,cAAc,CAAC,UAA+B,EAAE,cAAmC,IAAI,GAAG,EAAE;IACxG,MAAM,OAAO,GAAG,UAAU,CAAC,IAAA,+BAAc,EAAC,UAAU,CAAC,EAAE,WAAW,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,GAAG,CAAC,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC;AALD,wCAKC"}

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/cli-kit/knowledge/buildqjson.md

@@ -0,0 +1,35 @@
+# `studio buildQjson` — the validate command
+
+```bash
+studio buildQjson <file.qjson | folder>
+```
+
+Replaces the manual *paste-into-Studio → copy-the-error → paste-to-AI → paste-back* round-trip with a **local check the agent runs itself**: author → validate → read errors → fix → repeat, until clean. Requires **no bridge**; `studio` must be on your PATH (the normal global install). Exit code `0` = clean, non-zero = errors.
+
+**It never edits the qjson — it only reports.** Every fix is yours to apply, then re-run.
+
+## The three sections of its output
+
+Run in order on the same file(s) — read all three:
+
+1. **Compiler** — the official Quick compiler bundled with studio-cli, the same one the editor runs. Compiles `pJson → cJson` and reports QScript/TypeScript syntax & type errors in your handlers.
+2. **Structural validation** — the editor-domain checks the compiler doesn't do: unknown component `T`, duplicate `ID`/`eID`, bad `PType`/`HL`, `dOpt`↔`class` drift, containment.
+3. **Style validation** — the S-first check below.
+
+## Section 3: the S-first style check
+
+The compiler checks *script* correctness but **silently ignores unknown styling** — a wrong `S` param (e.g. `fontColor` on a `VIcon`, which wants `iconColor`) or a Vuetify prop that should be `S` (`color` on a `VBtn`) compiles "clean" yet renders nothing. This section closes that gap deterministically, straight from `component-contracts.json` + `component-styles.json`. It activates **only on S-track pages** (`opt.V >= 2.0`, or a page carrying an `S` object); legacy pages are reported as `skipped`.
+
+Per node it flags, with a suggested fix:
+
+- **`prop-to-S`** — a styling prop with an `S` equivalent (`color`→`backgroundColor`, `elevation`→`boxShadow`, `VCol` `cols/sm/md/lg`→`col`, `block`→`width:100%`).
+- **`class-token-to-S` / `class-token-misuse`** — a `class` token that has an `S` target the component supports (move it), or a grid class on the wrong component (`col-12` on a `VBtn` → `width:100%`).
+- **`css-prop-in-S`** — a prop the contract marks `cssProp: "true"` (a legacy CSS prop like `height`, `rounded`, `outlined`, `dense`): usable on a legacy page, **not** on the S track. Remove it and set the equivalent `S` param. (Components with no `component-styles.json` block are exempt — they have no `S` alternative.)
+- **`unknown-prop`**, **`style-conflict`** (same style in both `S` and `class`), **`legacy-layout`** (`O.layout`/`dOpt` still present on an S page).
+- **`missing-S` / `incomplete-S` / `missing-SC` / `incomplete-SC` / `unknown-S-param`** — how to fix each is in the ui-kit's validation doc: [`../../ui-kit/knowledge/validation.md`](../../ui-kit/knowledge/validation.md).
+
+Rule order matches the S-first policy: **contract prop → `S` equivalent → Vuetify class only as a last resort.** There is no separate command — every `buildQjson` run includes this section.
+
+## Reference data
+
+The structural and style checks read two reference files — [`../../ui-kit/reference/component-contracts.json`](../../ui-kit/reference/component-contracts.json) (per-component props/events/PType) and [`component-styles.json`](../../ui-kit/reference/component-styles.json) (per-component `S` params) — extracted from authoritative Quick runtime sources (`ComponentPims.ts`, `componentList.js`, `styleDefinitions.ts`). Treat them as read-only ground truth in a workspace.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/cli-kit/knowledge/cli-bridge.md

@@ -0,0 +1,97 @@
+# Studio CLI Bridge — Connection & Commands
+
+## Architecture
+
+```
+Studio (browser)  ←→  studio connect (local WS server)  ←→  file system
+                            ↑
+             studio pull / push / startWorking
+             (read port from .studio/server.json in the same workspace)
+```
+
+- `studio connect` starts a local WebSocket server (first free port in 7345–7350).
+- `pull`, `push`, `startWorking` are short-lived processes; they find the running `connect` process via `.studio/server.json` and communicate over HTTP.
+
+## `.studio/` folder
+
+| File | Written by | Read by | Contents |
+|---|---|---|---|
+| `server.json` | `studio connect` (after hello handshake) | `pull`, `push`, `startWorking` | `{ port, pid, startedAt, appId }` |
+| `state.json` | `pull` and `push` | `push` | `{ modelId: bodyHash }` |
+
+If `server.json` is absent, `pull`/`push`/`startWorking` exit with "no studio server in this workspace".
+
+## Starting the bridge — two ways
+
+### 1. Manual (`studio connect`)
+
+```bash
+cd /path/to/workspace
+studio connect   # keep this terminal open
+```
+
+Then, in the Studio browser UI, click the **Connect** button. Studio scans ports 7345–7350 and completes the handshake. Once connected, `server.json` is written and `pull`/`push`/`startWorking` become available.
+
+> Both steps are required: running `studio connect` alone is not enough — the browser must connect to it via the Connect button.
+
+### 2. Protocol handler (`studio://`) — if `studio protocol install` was run
+
+After a one-time install, the Connect button in Studio can start the bridge automatically — no manual terminal command needed:
+
+- If Studio finds no running server, it triggers `studio://connect?dir=pick`.
+- The OS hands this URL to the registered handler, which spawns `studio connect --dir pick`.
+- The CLI opens a native OS folder picker; the user selects the workspace and the bridge starts.
+- Studio UI asks for confirmation, then completes the connection.
+
+Install once:
+```bash
+studio protocol install    # macOS: ~/Library/Application Support/StudioCLI/StudioProtocol.app
+                           # Windows: HKCU\Software\Classes\studio registry key
+studio protocol uninstall  # to remove
+```
+
+## Readonly files and `startWorking`
+
+Studio decides readonly status per model during pull:
+- Checked out by **me** → `0644` (writable)
+- **Not checked out** (free) or checked out by **someone else** → `0444` (readonly)
+- In a **versioned / imported module** → always `0444`
+
+`studio push` skips readonly files and reports them:
+```
+! skipped: MyPage.qjson — read-only (use startWorking to check out)
+```
+
+To edit a readonly file:
+1. In the Studio browser UI, check out (take ownership of) the model.
+2. Run `studio startWorking <file>` — the CLI sends the checkout request to Studio and makes the file writable.
+
+```bash
+studio startWorking MyPage.qjson
+```
+
+> Do **not** `chmod` the file manually — without a Studio checkout record the push would create a conflict.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `no studio server in this workspace` | `server.json` missing — bridge not running | Run `studio connect`, then click Connect in Studio UI; or just click Connect if protocol is installed |
+| `studio server not reachable` | `server.json` exists but process is dead | Delete `server.json`, restart `studio connect` |
+| Connect button does nothing, no folder picker | Protocol not installed | Run `studio protocol install` |
+| `handshake failed` | Server claimed by a different app | Stop the other `connect`; run `studio connect` in the correct workspace |
+| Push sends 0 files | All files are readonly or unchanged | Use `studio startWorking` to check out |
+| `checkout failed — file may be locked` | Checked out by another user | Ask that user to release the checkout in Studio UI |
+
+## Command reference
+
+```bash
+studio connect                      # Start bridge (keep terminal open); then click Connect in Studio UI
+studio protocol install             # Register studio:// URL handler with the OS (one-time)
+studio pull                         # Pull all models from the open Studio app to local files
+studio startWorking <file>          # Check out a file in Studio + make it locally writable
+studio push                         # Push changed writable files back to Studio
+studio buildQjson <file|dir>        # Compile + validate qjson (no bridge needed)
+```
+
+Run `studio --help` for all commands, or `studio <command> --help` for a specific one (e.g. `studio buildQjson --help`).

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/cli-kit/knowledge/render-check.md

@@ -0,0 +1,48 @@
+# Render check (Playwright MCP)
+
+`studio buildQjson` is **static** — it compiles and structurally validates, but never *runs* the page, so it can't see **runtime / console errors** (a handler that throws on init, a bad binding, a service call that blows up at render). To catch those, render the page in a real Studio editor tab and look at it.
+
+You have a browser for this: the **Playwright MCP** server (`playwright`). You do **not** log in and you do **not** deal with any token — the CLI opens an authenticated Studio editor for you, and that tab keeps itself in sync with your pushes.
+
+## Push first — the editor renders the *cloud* model
+
+The test tab shows the real Studio app editor. A page you just authored locally reaches it through `studio push`: push creates brand-new models in the cloud app (writing their id back into the file's frontmatter) and mirrors every pushed body straight into the test tab. So the order is **build → push → check**:
+
+1. `studio buildQjson <file>` is clean.
+2. `studio push` — your model now exists in the app, and the test tab receives its body automatically (the pushed page is opened in the editor for you).
+3. Check it.
+
+## The loop
+
+1. **Open the render URL** with `browser_navigate`:
+   ```
+   http://127.0.0.1:<port>/render
+   ```
+   `<port>` is the `port` field of `.studio/server.json` in the workspace (usually `7345`). The CLI redirects the browser into the **authenticated** Studio editor for the right org + app — you never log in and never handle credentials. The tab also connects to the CLI as a **test client** automatically. Wait for the editor to load.
+2. **Find your page open in the editor.** Pushed pages are opened automatically; if you need another model, click its name in the file explorer on the left.
+3. **Check for errors** in three places:
+   - the **rendered UI** itself — `browser_take_screenshot`; does it draw, or is it blank / broken / misaligned?
+   - the **browser console** — `browser_console_messages`; collect every `error` (and relevant `warning`),
+   - the **editor's own error panel / markers**, if it surfaces any.
+4. **Fix & re-push:** map each error back to the offending node/handler in your `.qjson`, fix it locally, run `studio buildQjson`, then `studio push`. The test tab updates itself — no reload needed.
+5. **Repeat** until the UI renders correctly and the console is clean.
+6. **Close the browser** with `browser_close`. The Playwright MCP keeps a real browser process alive between tool calls — it does not shut down on its own — so this is a required, explicit final action, not something to get to eventually. Close it whether the check passed or you are stopping early; the only time there is nothing to close is when you never opened the browser at all.
+
+Interact only *inside* the editor page (clicking, typing into the rendered preview is fine). Do **not** navigate the tab elsewhere, do **not** click Save / check-in / create anything in that tab — it is a viewer; your changes become permanent only when the user reviews and saves in their own Studio session.
+
+## What to look for in the console
+
+- `TypeError` / `undefined is not a function` → a handler calling something that isn't there (wrong `quick.*` API, missing service, bad binding).
+- Errors naming a component id → that node's props/events are wrong.
+- Errors thrown on render/init → lifecycle (`onInit`/`mounted`) handler problems.
+
+Ignore unrelated framework/network noise; focus on errors that name your components, handlers, or values.
+
+## When it isn't available
+
+- If `http://127.0.0.1:<port>/render` refuses the connection, the bridge isn't running — the user needs `studio connect`. Skip the render check and rely on `buildQjson`; note that runtime wasn't verified.
+- If it returns **503** ("no authenticated Studio session"), the user's Studio tab isn't connected — ask them to open Studio and connect the CLI, then retry.
+- If the test tab starts failing with auth errors mid-session (token expired), `browser_navigate` to the render URL again — it re-enters with a fresh session and replays your pushes.
+- If the `playwright` MCP server isn't in your harness at all, skip the render check and rely on `buildQjson` + the [pre-delivery checklist](../../ui-kit/knowledge/validation.md). Nothing was opened, so there is nothing to close.
+
+Whenever you *did* open the browser — even if the check couldn't be finished (connection refused after navigating, a 503, an expired session you gave up on) — still call `browser_close` before you finish. A launched browser left open outlives the task.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/cli-kit/knowledge/sync.md

@@ -0,0 +1,50 @@
+# Studio sync — pull, push, and the sync-back rules
+
+This doc is the CLI half of the loop: **Studio → `studio pull` (or manual download) → AI edits locally → validate → `studio push` back into Studio.** It replaces the manual *paste-into-editor → copy-error → ask-AI → paste-back* round-trip.
+
+Authoring and validation themselves are host-independent — they live in the ui-kit ([../../ui-kit/knowledge/validation.md](../../ui-kit/knowledge/validation.md) / [validation-legacy.md](../../ui-kit/knowledge/validation-legacy.md)). This file covers the round-trip: pull/push, the frontmatter, and the sync-back rules. The validate command itself is [buildqjson.md](buildqjson.md).
+
+## `<<qjson:path>>` — ID↔path translation on pull/push
+
+Studio stores inter-page references (e.g. `CustomComponent.QJsonPath`) as internal model IDs: `<<qjson:bqrs7zi8-uq1r-2oh9-3ujg-yrl0mqulnxui>>`. The CLI translates these automatically:
+- **`studio pull`** → converts every model ID to a human-readable project-relative path: `<<qjson:folder/page-name>>`
+- **`studio push`** → converts paths back to model IDs before uploading (`replacePathsWithIds`)
+
+If push cannot resolve a path (a referrer went stale after a rename/move/delete), the link breaks. The agent-side procedure for keeping referrers consistent is in the ui-kit validation doc; the CLI-side facts:
+- Keep the target file's frontmatter `id` unchanged across renames — Studio matches the model by id.
+- If the **user** renames/moves a file manually (outside the agent), `studio push` is expected to repair referrers automatically; the agent-side procedure applies to agent-initiated changes.
+
+### Unresolved references are warnings, and they matter
+
+A path push cannot match is not an error. Push logs one line per occurrence —
+
+```
+[modelRefs] unresolved reference <<role:Access/Roles>> — new/moved model?
+```
+
+— leaves the text as it stands and uploads the model anyway. The push reports success, so nothing stops you.
+
+**Read those lines before calling the work done.** In Studio the reference is now unresolvable text: the target's name shows as a raw `<<type:path>>` string wherever it should have been resolved, and pickers that list the target come up empty — a swimlane's role column, a persona's role list, an action's privilege column. Two mistakes produce it:
+
+- **The path is not the one the workspace has.** Paths are counted from the workspace root, never relative to the referencing file's own folder, and never shortened because the two models are neighbours. A model in `hr/Access/` referencing its neighbour still writes `<<role:hr/Access/Roles>>`.
+- **The target did not exist yet when the referrer was pushed.** A model created in the same run has no id until its own push lands, so push the referenced models first and the referencing ones after — privileges before roles, roles before swimlanes and personas, functions before the actions that call them.
+
+Both are fixed the same way: correct or create the target, then push the referrer again.
+
+## Sync-back rules
+- Keep the **filename and any embedded page id stable** — Studio matches files back by name/id. Don't rename downloaded files.
+- Don't introduce new top-level keys or strip existing ones — **except `cJson`/`clrids`, which you always remove** (Studio regenerates the compiled twins on import; never paste compiled `╬…╩╩` content by hand).
+- For multi-file edits, validate the whole folder before syncing.
+- A file pulled from Studio may be **readonly** (`0444`) if it is locked/checked-out by someone else in Studio. To edit it locally, run `studio startWorking <file>` — do not `chmod` it manually.
+
+## Studio CLI commands
+
+`studio buildQjson` requires no bridge. All other commands require a running bridge (`studio connect`). For connection setup, readonly files, protocol handler, and troubleshooting see [cli-bridge.md](cli-bridge.md).
+
+**New files (no frontmatter):** if you create a `.qjson` from scratch with no `---studio-metadata---` header, `studio push` will create it as a new model in Studio and write the frontmatter back.
+
+**Pages embedded as block components:** a page you added into another page as a block component (not a service-caller embed) must also be converted in Studio: run `studio convertToBlock <embedded-file>` unless its frontmatter already has `blockComponent: true`. For a page newly created locally, run it **after** `studio push` — the model must exist in Studio first (push leaves new models checked out). For an existing page that isn't checked out, run `studio startWorking <file>` first.
+
+## After push: render-check
+
+Pushing places the page in the user's open Studio session as unsaved work. Compiling clean does not prove the page runs clean — when the CLI bridge and the Playwright MCP are available, open the rendered page and check the console: [render-check.md](render-check.md).

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

@@ -0,0 +1,23 @@
+# MiniApp app workspace — what's in this kit
+
+This workspace holds a **Plateau Studio MiniApp**: Quick `.qjson` mobile pages that run inside a SuperApp shell. These docs are the manuals for that content.
+
+## The manuals
+
+| Folder | Read it for |
+|--------|-------------|
+| [`ui-kit/`](ui-kit/index.md) | the qjson manual — the authoring rules, the `S` styling system, the component and `quick.*` references, validation. Its MiniApp section carries the host rules, and it ends with this workspace's CLI loop |
+| [`miniapp-kit/`](miniapp-kit/index.md) | what the SuperApp host adds — the required appbar and exit action, host functions and consents, the platform payment component, analytics and logging |
+| [`cli-kit/knowledge/`](cli-kit/knowledge/) | the studio CLI depth behind that loop — the bridge, round-trip rules, `buildQjson`, render checks |
+
+Skills are installed for page work: **quick-qjson** for authoring, **figma-to-qjson** for rebuilding a page from a Figma design.
+
+## Where to start
+
+Start at [`ui-kit/index.md`](ui-kit/index.md). It routes you to the docs the task needs, and its **MiniApp** section states the constraints that apply to every page here — an appbar with a host-exit button, and host-owned capabilities you integrate with rather than rebuild. Read that section before authoring; the detail behind it is in [`miniapp-kit/`](miniapp-kit/index.md).
+
+**Author every page in `S`.** Mobile does not apply the legacy `O.layout` css mechanism, so any legacy fragments you find in a qjson have no effect on how it renders — ignore them, and strip them when you edit that page. A page whose `opt.V` is missing or `< 2.0` is a legacy page and **cannot be edited from this workspace** — stop and tell the user.
+
+## Not covered yet
+
+App-level authoring — turning "build me a loyalty miniapp" into a page set (page list, navigation map, shared services and conventions, then page-by-page authoring against it) — is not written yet. Until it is, this is a **page-authoring** workspace: one page at a time, validated and synced.

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

@@ -0,0 +1,39 @@
+# MiniApp concepts
+
+A MiniApp is a mobile application that runs inside a SuperApp-owned environment. It uses the normal mobile QJSON authoring model, while the host adds mandatory UI, navigation and platform-service contracts.
+
+## Ownership boundary
+
+The MiniApp owns its business screens, page content, data access and feature-specific interaction logic. The SuperApp owns the surrounding experience and exposes capabilities the MiniApp consumes.
+
+Host-owned:
+
+- the application bar's exit action, and the act of leaving the MiniApp
+- the payment experience — card selection and the secure payment call
+- the signed-in user's details (identity, contact, customer numbers)
+- device capabilities reached through the host, such as opening the map application
+
+**Do not duplicate a host-owned capability with ordinary page components.** Integrate through the documented platform component or host function instead. A hand-built card form or a hand-built "return to app" that only navigates within the MiniApp are both wrong even when they look right.
+
+## What the project provides
+
+Four things live in the project rather than in these docs, and you read them from the workspace:
+
+- **The container file** (`*.container`, one per app) — declares the host functions the MiniApp calls through `quick.container`, and the mock each one returns in Studio. If the workspace has none, you create it from the kit's template. Finding and creating it: [../../.ai-kit/ui-kit/knowledge/container-configuration.md](../../.ai-kit/ui-kit/knowledge/container-configuration.md). Which functions the SuperApp exposes: [guides/host-functions.md](guides/host-functions.md).
+- **The `IsbankComponents` module** at the project root — holds the platform components, including the payment component. Its `<<qjson:…>>` references are per-project; copy them from the module or a sibling page, never from an example.
+- **The pipeline file** — where a `logHandler` event goes if the MiniApp forwards its logs. See [guides/analytics-and-logging.md](guides/analytics-and-logging.md).
+- **Constants** — secure central storage for API keys, tokens and similar secrets. Never hard-code one into a page.
+
+## Host calls in development
+
+A `quick.container` call answers in Studio with the mock declared for that function in the app's container file, so a page that depends on host data renders with those values during development. The real shell answers only once the MiniApp runs inside it. Build against the documented payload shapes, and say plainly in your report what was checked only against mocks.
+
+`quick.Quick.host.trigger` calls — on older pages and inside the payment component — do not respond in Studio at all, so a page that depends on one cannot be fully verified by rendering it locally.
+
+## Relationship to the mobile manual
+
+The mobile and QJSON manuals remain the source of truth for page structure, valid components, properties, events, styling and validation. This domain adds only the MiniApp-specific requirements. The only general rules this domain changes are listed under *Corrections to the ui-kit manual* in [index.md](index.md); everywhere else the manuals win.
+
+## Contracts, not assumptions
+
+Component names, properties, events, payloads and lifecycle behaviour come from this domain's `reference/` files. If a required detail is absent, **stop and ask for it** rather than inferring behaviour from a standalone mobile or browser application.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/miniapp-kit/examples/README.md

@@ -0,0 +1,18 @@
+# MiniApp examples
+
+Complete MiniApp pages pulled from real apps, all on the `S` style system (`opt.V: 2.5`). Copy their **structure** — node nesting, `S` params, event shapes, how the host calls are wired — not their IDs, image data, service URLs or `<<qjson:…>>` references, which belong to the project they came from.
+
+**One exception: the host-app image.** The `VImg#returnToHostApp` inside every appbar's exit button is a platform asset, not project image data — it must be copied as-is on every page. Take it from [../reference/host-app-image.json](../reference/host-app-image.json); see [../guides/miniapp-page-structure.md](../guides/miniapp-page-structure.md#the-exit-buttons-image-is-fixed).
+
+| File | Shows |
+|---|---|
+| [miniapp-page-example-with-appbar-and-footer.qjson](miniapp-page-example-with-appbar-and-footer.qjson) | **The page shell to start from** — `Messaging` + `VAppBar` + `VContainer` + `VFooter` at the top level of `pJson`, with back and exit wired. The exit calls `(<any>quick.container).stopMiniApp()`, so the app's container file must declare it. |
+| [miniapp-appbar.qjson](miniapp-appbar.qjson) | An appbar with the same three-column layout, here nested inside the content `VContainer`. Renders, but prefer the top-level placement above for a new page. |
+| [miniapp-footer.qjson](miniapp-footer.qjson) | A `VFooter` skeleton. Structure only — it has no event handlers. |
+| [consent-check-using-container-methods.qjson](consent-check-using-container-methods.qjson) | **Host functions on a new page** — `GetIdentity` → `GetMailAddress` → `GetPhoneNumber` through `(<any>quick.container)`, awaited in sequence on a button click, each result stored, with `isSuccess` checks and a failure dialog on either failure shape. The app's container file must declare all three. |
+| [consent-check-using-hosttrigger.qjson](consent-check-using-hosttrigger.qjson) | **Legacy** — the same three calls through the deprecated `quick.Quick.host.trigger`, chained as *nested* `.then()` calls on a button click. For reading and maintaining older pages; don't copy it for new code. |
+| [miniapp-payment-page-paymentComp-usage.qjson](miniapp-payment-page-paymentComp-usage.qjson) | **The platform payment component** — placed as a `CustomComponent`, `miniappId` set, all five callbacks wired, `doPayment` called from a button, results shown in a dialog. Its `QJsonPath` and `miniappId` are that project's values; use your own. |
+| [dataroid.qjson](dataroid.qjson) | Dataroid analytics on an appbar page — `track` calls fired before the exit action. |
+| [consentHostMethods.container](consentHostMethods.container) | **A real container file**, pulled from a live app — frontmatter with `settingKey: container`, then six declared functions with the user's own mocks. What the file you are looking for actually looks like; the full template is [../reference/host-functions.container](../reference/host-functions.container). |
+
+**Provenance:** exported from live MiniApp projects, so they carry `_Editor` blocks and real component ids. They have not all been re-validated against the current schema — if an example and the guides disagree, follow the guides and flag the example.