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

package/dist/studio-cli/kits/miniapp-app-kit/.claude/skills/figma-to-qjson/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: figma-to-qjson
+description: Reconstruct a Quick / Plateau Studio .qjson page from a Figma design (a Figma selection URL). If the design isn't fetched yet, run the `studio figmaPull` command to populate a local .figma/ folder (node.json, file.json, render.json, imagefills.json, assets/*.svg), then turn that raw Figma node tree into a real qjson page. Use whenever the task is to convert a Figma frame/selection into a qjson page. Covers fetching via the `studio figmaPull` command, the Figma→qjson mapping rules, the geometry/style extraction recipe, the rect+text control-clustering heuristic, and asset handling. Delegates all qjson-authoring detail to the quick-qjson skill + the ui-kit package.
+---
+
+# Figma → QJSON reconstruction
+
+This skill turns a Figma design into a **Quick `.qjson` page**. The raw Figma responses live in a local **`.figma/`** folder; you produce that folder by **running the `studio figmaPull` command** (which wraps `figmaPull(url, token)`). This skill never calls the Figma API directly — it runs the command, then reads what the command wrote.
+
+It owns only the **translation knowledge** (Figma node tree → qjson components). For everything about *authoring* qjson (schema, props, styling, validation, project conventions) it defers to the **`quick-qjson`** skill and the **`ui-kit/`** folder in your workspace (e.g. `.ai-kit/ui-kit/index.md`) — read those; do not re-derive them here.
+
+## Get the design first (run `studio figmaPull`)
+Before the translation workflow below, you need the raw Figma responses in `.figma/`. Get them by running the **`studio figmaPull` command** (the CLI that wraps `figmaPull(url, token)` — it extracts `fileKey` + `node-id` from the URL itself):
+
+- If `.figma/` is already present and current for the design you want → just read `.figma/manifest.json` and continue.
+- Otherwise **run the command yourself** (don't wait for the user to pre-fetch). The URL and token are **positional arguments**, in that order; `-d, --dir <dir>` optionally picks the workspace whose `.figma/` receives the output (defaults to the current directory):
+  ```
+    studio figmaPull "<figma-url>" "<token>"
+  ```
+- **Parameters — resolve, don't block:**
+  - **URL**: take the Figma *selection* link from the user's message / context; if it isn't there, **ask the user** (AskUserQuestion: "paste the Figma 'Copy link to selection'"). Don't guess it.
+  - **Token**: a Figma personal access token, passed as the **second positional argument**. The command has no env/config fallback, so you must supply it explicitly; ask the user once if you don't have it, never hardcode.
+- The command writes `.figma/node.json`, `file.json`, `render.json`, `imagefills.json`, `manifest.json` (+ `assets/*.svg`). **Read `manifest.json` first** — if its `node` endpoint failed (403 token / 404 file·node), surface that error and stop; don't proceed on a bad fetch.
+
+Inputs you'll then use, as needed:
+- `.figma/node.json` — the target frame's full node tree (primary input).
+- `.figma/file.json` — whole-file tree (styles, components — fallback/context).
+- `.figma/render.json` — `{images:{<nodeId>: <svg-url>}}` for vector/icon render.
+- `.figma/imagefills.json` — `imageRef → URL` map for IMAGE fills.
+- `.figma/assets/*.svg` — downloaded SVGs (if the command saved them).
+
+## Workflow (the same process a human reviewer would follow)
+
+### 0. Load + triage
+Read `node.json`, grab the fetched frame, and get a shape-of-the-page read: node-type counts, max depth, **auto-layout usage**, and all TEXT content. This decides the page kind (login / form / list / landing…) and whether it maps cleanly.
+
+```python
+import json, collections
+doc = next(iter(json.load(open('.figma/node.json'))['nodes'].values()))['document']
+types, lm, texts = collections.Counter(), collections.Counter(), []
+def walk(n):
+    types[n['type']] += 1
+    if n['type'] == 'FRAME': lm[n.get('layoutMode','NONE')] += 1
+    if n['type'] == 'TEXT':  texts.append(n.get('characters','')[:40])
+    for c in n.get('children', []): walk(c)
+walk(doc)
+print('types', dict(types)); print('layoutMode', dict(lm)); print('texts', texts)
+```
+> Many frames with `layoutMode` HORIZONTAL/VERTICAL → the layout maps cleanly to `VRow`/`VCol`. Many `NONE` (absolute) → you must reconstruct structure from geometry (step 2–3).
+
+### 1. Extract per-node geometry + style
+For each visible node, pull **frame-relative** `x,y,w,h`, fill hex, font size/weight/color, and `cornerRadius`. This table is what tells you "what each thing is".
+
+```python
+root = doc['absoluteBoundingBox']; rx, ry = root['x'], root['y']
+def hexfill(n):
+    for f in (n.get('fills') or []):
+        if f.get('type') == 'SOLID':
+            c = f['color']; return '#%02x%02x%02x' % (int(c['r']*255), int(c['g']*255), int(c['b']*255))
+    return None
+def walk(n, d=0):
+    bb = n.get('absoluteBoundingBox') or {}
+    x = (bb.get('x',0)-rx) if 'x' in bb else None; y = (bb.get('y',0)-ry) if 'y' in bb else None
+    st = n.get('style', {})
+    print('  '*d, n['type'], n.get('name'),
+          f"({x},{y}) {bb.get('width')}x{bb.get('height')}" if x is not None else '',
+          '|', repr(n.get('characters','')[:30]) if n['type']=='TEXT' else '',
+          'fz', st.get('fontSize'), 'fw', st.get('fontWeight'),
+          'fill', hexfill(n), 'r', n.get('cornerRadius'))
+    for c in n.get('children', []): walk(c, d+1)
+walk(doc)
+```
+
+### 2. Detect the *real* visible background
+The frame's own `fills` may just be the **artboard** color, not what the user sees. Look for a **full-bleed shape** (a RECTANGLE/VECTOR roughly the frame's size, drawn first/behind) — its fill is the real page background. (Tell-tale: dark text only makes sense on a light background.) Use that for `Messaging.pageBackgroundColor` and container backgrounds.
+
+### 3. Cluster loose elements into controls
+Figma often keeps a button's **background rect** and its **label text** as *separate siblings*. Infer a single control when a TEXT's center lies **within a RECTANGLE's bounds** (and they're adjacent in z-order). One rect + one text inside it = one button or one input — not two components.
+
+### 4. Map each control → qjson (the rules)
+
+| Figma pattern | → qjson | Decisive signal |
+|---|---|---|
+| auto-layout FRAME, `VERTICAL` / `HORIZONTAL` | stacked `VRow`s / a `VRow` of `VCol`s | `layoutMode` |
+| plain TEXT | `QLabel` (`text` PType `prop`) | — |
+| TEXT whose chars are PUA glyphs (U+F0000+) | `VIcon` (icon name, PType `text`) | codepoint → `mdi-*` name |
+| large bold TEXT near top | title `QLabel` | fontSize/weight |
+| rounded rect (high `cornerRadius`) + **centered, light** text inside | **filled** `VBtn` → child `QLabel`; rect fill → `S.backgroundColor` | rect has a solid fill |
+| rounded rect, `fill=none` + stroke, text inside | `VBtn` `outlined` | no fill, has stroke |
+| white/light rounded rect + **gray** text inside | `VTextField` (the gray text → `placeholder`) | inner text is a muted color |
+| field whose name/label is "şifre"/"password"/"pin" | + `type='password'` | text content |
+| small, right-aligned text link | `VBtn` `text` (link) → `QLabel` | alignment + size |
+| custom VECTOR group (logo/illustration) | `VImg` from an asset (see step 5) | type VECTOR/GROUP, not a glyph |
+| IMAGE fill (`imageRef`) | `VImg`, URL from `imagefills.json` | fill type IMAGE |
+
+Pick real props/events/styles from **`ui-kit/reference/component-contracts.json`** and **`component-styles.json`** — never invent. Convert px → the kit's responsive grid (`col`, `S` blocks); do **not** reproduce absolute pixel coordinates.
+
+### 5. Assets (vectors / logos)
+A deployed Quick app can't read local SVGs or Figma's expiring S3 URLs. So:
+- If there is an asset pipeline / CDN, upload `.figma/assets/<id>.svg` and reference it via `VImg`.
+- Otherwise insert a **`VIcon` placeholder** in the right spot and **flag in the report** that the real logo must be exported (`render.json` URL → `.figma/assets/`) and uploaded as a Studio asset. Don't silently drop it.
+
+### 6. Author the qjson
+Hand off to **`quick-qjson`**: build top-down `Messaging → VContainer > VRow > VCol > content`, mirror a sibling page in the workspace for ID style and `S`-block shape, author `pJson`/`lrids` only (omit `cJson`/`clrids` entirely — never write them, strip if present). Wire obvious behavior (e.g. a login button → a `Messaging` event that reads `components.<id>.qValue` and `quick.Quick.alert(...)`).
+
+### 7. Validate + report
+`studio buildQjson <file>` — fix every error. Then report: the new file, the **mapping decisions** (what each Figma element became), any **assumptions** (background, clustering, responsive sizing), **assets needing manual upload**, and the validation result.
+
+## Gotchas (these trip up naive conversions)
+- **Artboard ≠ background.** Use the full-bleed shape's fill, not `frame.fills`.
+- **Separate rect + text = one control.** Cluster by spatial containment before mapping.
+- **PUA-glyph TEXT is an icon**, not a label → `VIcon` (map the codepoint to an `mdi-*` name).
+- **Gray inner text in a white field = placeholder**, not a value.
+- **Absolute (`NONE`) layout** still becomes semantic `VRow/VCol`; reconstruct order/grouping from `y` then `x`. Never emit pixel coordinates.
+- **Big visual pages**: don't convert in one shot — 1–3 sections per edit (per the quick-qjson rules).
+```

package/dist/studio-cli/kits/miniapp-app-kit/.claude/skills/quick-qjson/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: quick-qjson
+description: Create, edit, review, style, or validate Quick / Plateau Studio .qjson UI pages. Load this skill for ANY task that touches a file with the .qjson extension — building a new page, editing or fixing an existing one (even a one-line tweak or typo fix), styling/layout changes, events/scripting, services, localization, or validation. Also load it the moment you encounter a .qjson file mid-task, even if the request never mentions qjson. Covers the qjson schema, the quick.* scripting API, the component registry, and the styling/layout/events systems.
+---
+
+# Quick QJSON authoring
+
+The complete, source-grounded knowledge for **Quick / Plateau Studio `.qjson`** UI pages lives in the **`ui-kit/`** folder — locate it in your workspace (e.g. `.ai-kit/ui-kit/`) and treat it as authoritative over any prior assumptions about Quick.
+
+**Read `ui-kit/index.md` and follow it.** Its Step 0 routes you to the right style track (`S` vs legacy — never mixed on a page), its non-negotiable rules apply to every edit, and it maps which knowledge/reference docs to open for the task at hand. Don't load everything up front — open only your track's docs plus the shared ones it lists.

package/dist/studio-cli/kits/miniapp-app-kit/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--ignore-https-errors"]
+    }
+  }
+}

package/dist/studio-cli/kits/miniapp-app-kit/.opencode/opencode.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "../.ai-kit/ui-kit/index.md"
+  ],
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "@playwright/mcp@latest"
+      ],
+      "enabled": true
+    }
+  },
+  "permission": {
+    "playwright*": "allow"
+  }
+}

package/dist/studio-cli/kits/miniapp-app-kit/.opencode/skills/figma-to-qjson/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: figma-to-qjson
+description: Reconstruct a Quick / Plateau Studio .qjson page from a Figma design (a Figma selection URL). If the design isn't fetched yet, run the `studio figmaPull` command to populate a local .figma/ folder (node.json, file.json, render.json, imagefills.json, assets/*.svg), then turn that raw Figma node tree into a real qjson page. Use whenever the task is to convert a Figma frame/selection into a qjson page. Covers fetching via the `studio figmaPull` command, the Figma→qjson mapping rules, the geometry/style extraction recipe, the rect+text control-clustering heuristic, and asset handling. Delegates all qjson-authoring detail to the quick-qjson skill + the ui-kit package.
+---
+
+# Figma → QJSON reconstruction
+
+This skill turns a Figma design into a **Quick `.qjson` page**. The raw Figma responses live in a local **`.figma/`** folder; you produce that folder by **running the `studio figmaPull` command** (which wraps `figmaPull(url, token)`). This skill never calls the Figma API directly — it runs the command, then reads what the command wrote.
+
+It owns only the **translation knowledge** (Figma node tree → qjson components). For everything about *authoring* qjson (schema, props, styling, validation, project conventions) it defers to the **`quick-qjson`** skill and the **`ui-kit/`** folder in your workspace (e.g. `.ai-kit/ui-kit/index.md`) — read those; do not re-derive them here.
+
+## Get the design first (run `studio figmaPull`)
+Before the translation workflow below, you need the raw Figma responses in `.figma/`. Get them by running the **`studio figmaPull` command** (the CLI that wraps `figmaPull(url, token)` — it extracts `fileKey` + `node-id` from the URL itself):
+
+- If `.figma/` is already present and current for the design you want → just read `.figma/manifest.json` and continue.
+- Otherwise **run the command yourself** (don't wait for the user to pre-fetch). The URL and token are **positional arguments**, in that order; `-d, --dir <dir>` optionally picks the workspace whose `.figma/` receives the output (defaults to the current directory):
+  ```
+    studio figmaPull "<figma-url>" "<token>"
+  ```
+- **Parameters — resolve, don't block:**
+  - **URL**: take the Figma *selection* link from the user's message / context; if it isn't there, **ask the user** (AskUserQuestion: "paste the Figma 'Copy link to selection'"). Don't guess it.
+  - **Token**: a Figma personal access token, passed as the **second positional argument**. The command has no env/config fallback, so you must supply it explicitly; ask the user once if you don't have it, never hardcode.
+- The command writes `.figma/node.json`, `file.json`, `render.json`, `imagefills.json`, `manifest.json` (+ `assets/*.svg`). **Read `manifest.json` first** — if its `node` endpoint failed (403 token / 404 file·node), surface that error and stop; don't proceed on a bad fetch.
+
+Inputs you'll then use, as needed:
+- `.figma/node.json` — the target frame's full node tree (primary input).
+- `.figma/file.json` — whole-file tree (styles, components — fallback/context).
+- `.figma/render.json` — `{images:{<nodeId>: <svg-url>}}` for vector/icon render.
+- `.figma/imagefills.json` — `imageRef → URL` map for IMAGE fills.
+- `.figma/assets/*.svg` — downloaded SVGs (if the command saved them).
+
+## Workflow (the same process a human reviewer would follow)
+
+### 0. Load + triage
+Read `node.json`, grab the fetched frame, and get a shape-of-the-page read: node-type counts, max depth, **auto-layout usage**, and all TEXT content. This decides the page kind (login / form / list / landing…) and whether it maps cleanly.
+
+```python
+import json, collections
+doc = next(iter(json.load(open('.figma/node.json'))['nodes'].values()))['document']
+types, lm, texts = collections.Counter(), collections.Counter(), []
+def walk(n):
+    types[n['type']] += 1
+    if n['type'] == 'FRAME': lm[n.get('layoutMode','NONE')] += 1
+    if n['type'] == 'TEXT':  texts.append(n.get('characters','')[:40])
+    for c in n.get('children', []): walk(c)
+walk(doc)
+print('types', dict(types)); print('layoutMode', dict(lm)); print('texts', texts)
+```
+> Many frames with `layoutMode` HORIZONTAL/VERTICAL → the layout maps cleanly to `VRow`/`VCol`. Many `NONE` (absolute) → you must reconstruct structure from geometry (step 2–3).
+
+### 1. Extract per-node geometry + style
+For each visible node, pull **frame-relative** `x,y,w,h`, fill hex, font size/weight/color, and `cornerRadius`. This table is what tells you "what each thing is".
+
+```python
+root = doc['absoluteBoundingBox']; rx, ry = root['x'], root['y']
+def hexfill(n):
+    for f in (n.get('fills') or []):
+        if f.get('type') == 'SOLID':
+            c = f['color']; return '#%02x%02x%02x' % (int(c['r']*255), int(c['g']*255), int(c['b']*255))
+    return None
+def walk(n, d=0):
+    bb = n.get('absoluteBoundingBox') or {}
+    x = (bb.get('x',0)-rx) if 'x' in bb else None; y = (bb.get('y',0)-ry) if 'y' in bb else None
+    st = n.get('style', {})
+    print('  '*d, n['type'], n.get('name'),
+          f"({x},{y}) {bb.get('width')}x{bb.get('height')}" if x is not None else '',
+          '|', repr(n.get('characters','')[:30]) if n['type']=='TEXT' else '',
+          'fz', st.get('fontSize'), 'fw', st.get('fontWeight'),
+          'fill', hexfill(n), 'r', n.get('cornerRadius'))
+    for c in n.get('children', []): walk(c, d+1)
+walk(doc)
+```
+
+### 2. Detect the *real* visible background
+The frame's own `fills` may just be the **artboard** color, not what the user sees. Look for a **full-bleed shape** (a RECTANGLE/VECTOR roughly the frame's size, drawn first/behind) — its fill is the real page background. (Tell-tale: dark text only makes sense on a light background.) Use that for `Messaging.pageBackgroundColor` and container backgrounds.
+
+### 3. Cluster loose elements into controls
+Figma often keeps a button's **background rect** and its **label text** as *separate siblings*. Infer a single control when a TEXT's center lies **within a RECTANGLE's bounds** (and they're adjacent in z-order). One rect + one text inside it = one button or one input — not two components.
+
+### 4. Map each control → qjson (the rules)
+
+| Figma pattern | → qjson | Decisive signal |
+|---|---|---|
+| auto-layout FRAME, `VERTICAL` / `HORIZONTAL` | stacked `VRow`s / a `VRow` of `VCol`s | `layoutMode` |
+| plain TEXT | `QLabel` (`text` PType `prop`) | — |
+| TEXT whose chars are PUA glyphs (U+F0000+) | `VIcon` (icon name, PType `text`) | codepoint → `mdi-*` name |
+| large bold TEXT near top | title `QLabel` | fontSize/weight |
+| rounded rect (high `cornerRadius`) + **centered, light** text inside | **filled** `VBtn` → child `QLabel`; rect fill → `S.backgroundColor` | rect has a solid fill |
+| rounded rect, `fill=none` + stroke, text inside | `VBtn` `outlined` | no fill, has stroke |
+| white/light rounded rect + **gray** text inside | `VTextField` (the gray text → `placeholder`) | inner text is a muted color |
+| field whose name/label is "şifre"/"password"/"pin" | + `type='password'` | text content |
+| small, right-aligned text link | `VBtn` `text` (link) → `QLabel` | alignment + size |
+| custom VECTOR group (logo/illustration) | `VImg` from an asset (see step 5) | type VECTOR/GROUP, not a glyph |
+| IMAGE fill (`imageRef`) | `VImg`, URL from `imagefills.json` | fill type IMAGE |
+
+Pick real props/events/styles from **`ui-kit/reference/component-contracts.json`** and **`component-styles.json`** — never invent. Convert px → the kit's responsive grid (`col`, `S` blocks); do **not** reproduce absolute pixel coordinates.
+
+### 5. Assets (vectors / logos)
+A deployed Quick app can't read local SVGs or Figma's expiring S3 URLs. So:
+- If there is an asset pipeline / CDN, upload `.figma/assets/<id>.svg` and reference it via `VImg`.
+- Otherwise insert a **`VIcon` placeholder** in the right spot and **flag in the report** that the real logo must be exported (`render.json` URL → `.figma/assets/`) and uploaded as a Studio asset. Don't silently drop it.
+
+### 6. Author the qjson
+Hand off to **`quick-qjson`**: build top-down `Messaging → VContainer > VRow > VCol > content`, mirror a sibling page in the workspace for ID style and `S`-block shape, author `pJson`/`lrids` only (omit `cJson`/`clrids` entirely — never write them, strip if present). Wire obvious behavior (e.g. a login button → a `Messaging` event that reads `components.<id>.qValue` and `quick.Quick.alert(...)`).
+
+### 7. Validate + report
+`studio buildQjson <file>` — fix every error. Then report: the new file, the **mapping decisions** (what each Figma element became), any **assumptions** (background, clustering, responsive sizing), **assets needing manual upload**, and the validation result.
+
+## Gotchas (these trip up naive conversions)
+- **Artboard ≠ background.** Use the full-bleed shape's fill, not `frame.fills`.
+- **Separate rect + text = one control.** Cluster by spatial containment before mapping.
+- **PUA-glyph TEXT is an icon**, not a label → `VIcon` (map the codepoint to an `mdi-*` name).
+- **Gray inner text in a white field = placeholder**, not a value.
+- **Absolute (`NONE`) layout** still becomes semantic `VRow/VCol`; reconstruct order/grouping from `y` then `x`. Never emit pixel coordinates.
+- **Big visual pages**: don't convert in one shot — 1–3 sections per edit (per the quick-qjson rules).
+```

package/dist/studio-cli/kits/miniapp-app-kit/.opencode/skills/quick-qjson/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: quick-qjson
+description: Create, edit, review, style, or validate Quick / Plateau Studio .qjson UI pages. Load this skill for ANY task that touches a file with the .qjson extension — building a new page, editing or fixing an existing one (even a one-line tweak or typo fix), styling/layout changes, events/scripting, services, localization, or validation. Also load it the moment you encounter a .qjson file mid-task, even if the request never mentions qjson. Covers the qjson schema, the quick.* scripting API, the component registry, and the styling/layout/events systems.
+---
+
+# Quick QJSON authoring
+
+The complete, source-grounded knowledge for **Quick / Plateau Studio `.qjson`** UI pages lives in the **`ui-kit/`** folder — locate it in your workspace (e.g. `.ai-kit/ui-kit/`) and treat it as authoritative over any prior assumptions about Quick.
+
+**Read `ui-kit/index.md` and follow it.** Its Step 0 routes you to the right style track (`S` vs legacy — never mixed on a page), its non-negotiable rules apply to every edit, and it maps which knowledge/reference docs to open for the task at hand. Don't load everything up front — open only your track's docs plus the shared ones it lists.

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

@@ -0,0 +1,24 @@
+# AGENTS.md — MiniApp workspace
+
+This workspace holds a **Plateau Studio MiniApp**: Quick `.qjson` mobile pages that run inside a SuperApp shell. The shell owns the surrounding experience, so pages here carry host obligations an ordinary mobile page does not.
+
+## Capabilities
+
+- **Any work on a `.qjson` file** — new page, edit, styling, events, validation → [`.ai-kit/ui-kit/index.md`](.ai-kit/ui-kit/index.md), the manual · or load the **quick-qjson** skill
+- **MiniApp host rules** — appbar, exit, consents, platform payments, analytics → [`.ai-kit/miniapp-kit/index.md`](.ai-kit/miniapp-kit/index.md)
+
+## Two rules that apply to every page
+
+- **Every page has a `VAppBar`** carrying a back action and a button that returns the user to the host app. A page without one is incomplete even though it compiles.
+- **Never rebuild a host-owned experience.** Payments go through the platform's payment component; host functions (user details, exit) go through `quick.container`, declared in the app's one `.container` file. If you are about to build one from ordinary components, stop and read the MiniApp manual.
+
+## Working with the studio CLI
+
+These pages were pulled from Studio and will be synced back.
+
+- **Building a page from a Figma design** → load the **figma-to-qjson** skill
+- **CLI depth** — sync/frontmatter, the bridge, render-check, `buildQjson` internals → [`.ai-kit/cli-kit/knowledge/`](.ai-kit/cli-kit/knowledge/)
+
+**Commands:** `studio buildQjson <file-or-folder>` (validate — always, before finishing) · `studio push` (sync, needs the bridge) · render-check via the `playwright` MCP · `studio startWorking <file>` (unlock a readonly page) · `studio convertToBlock <file>` (mark an embedded page as a block component).
+
+Report what you changed, the validation result, and the push/render-check result — if the bridge or browser wasn't available, say so rather than skipping silently.

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

@@ -0,0 +1,24 @@
+# CLAUDE.md — MiniApp workspace
+
+This workspace holds a **Plateau Studio MiniApp**: Quick `.qjson` mobile pages that run inside a SuperApp shell. The shell owns the surrounding experience, so pages here carry host obligations an ordinary mobile page does not.
+
+## Capabilities
+
+- **Any work on a `.qjson` file** — new page, edit, styling, events, validation → [`.ai-kit/ui-kit/index.md`](.ai-kit/ui-kit/index.md), the manual · or load the **quick-qjson** skill
+- **MiniApp host rules** — appbar, exit, consents, platform payments, analytics → [`.ai-kit/miniapp-kit/index.md`](.ai-kit/miniapp-kit/index.md)
+
+## Two rules that apply to every page
+
+- **Every page has a `VAppBar`** carrying a back action and a button that returns the user to the host app. A page without one is incomplete even though it compiles.
+- **Never rebuild a host-owned experience.** Payments go through the platform's payment component; host functions (user details, exit) go through `quick.container`, declared in the app's one `.container` file. If you are about to build one from ordinary components, stop and read the MiniApp manual.
+
+## Working with the studio CLI
+
+These pages were pulled from Studio and will be synced back.
+
+- **Building a page from a Figma design** → load the **figma-to-qjson** skill
+- **CLI depth** — sync/frontmatter, the bridge, render-check, `buildQjson` internals → [`.ai-kit/cli-kit/knowledge/`](.ai-kit/cli-kit/knowledge/)
+
+**Commands:** `studio buildQjson <file-or-folder>` (validate — always, before finishing) · `studio push` (sync, needs the bridge) · render-check via the `playwright` MCP · `studio startWorking <file>` (unlock a readonly page) · `studio convertToBlock <file>` (mark an embedded page as a block component).
+
+Report what you changed, the validation result, and the push/render-check result — if the bridge or browser wasn't available, say so rather than skipping silently.

package/dist/studio-cli/kits/mobile-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/mobile-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/mobile-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/mobile-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/mobile-app-kit/.ai-kit/index.md

@@ -0,0 +1,22 @@
+# Mobile app workspace — what's in this kit
+
+This workspace holds **Quick / Plateau Studio `.qjson`** mobile UI pages. 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. Ends with this workspace's CLI loop |
+| [`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 both: **quick-qjson** for page authoring, **figma-to-qjson** for rebuilding a page from a Figma design. Loading a skill and following the manual is equivalent — both land you in the same docs.
+
+## Where to start
+
+Start at [`ui-kit/index.md`](ui-kit/index.md); it lists exactly which docs to open for the task.
+
+**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 to-do app" 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/mobile-app-kit/.ai-kit/ui-kit/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Reference pages pulled from real apps, all on the **`S` style system** (`opt.V >= 2.0`, design authored in each node's `S` object).
+
+| Folder | Contains | Reference it when |
+| --- | --- | --- |
+| [`style/`](style/) | S-system pages — the only style system mobile supports. | Any page you author or edit here. |
+
+There is no `cssClass/` folder: mobile does not apply the legacy `O.layout` + CSS-class mechanism, so authoring in it here would have no effect. If a page you are working on carries leftover `O.layout`, ignore it — it does not affect how the page renders — and style in `S`.
+
+Copy the **structure** from these pages — node nesting, `S` params, event shapes, `_Editor` blocks — not their IDs, service URLs or `<<qjson:…>>` references, which belong to the project they came from.