@stechquick/studio-cli 4.1.2-0 → 4.2.0-0-BETA-release-4.2.0-2026.9.9.8.51

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/reference/component-styles.json

@@ -6977,6 +6977,152 @@
       "borderLeftWidth": {},
       "defaultBorderColor": {},
       "sides": {}
+    },
+    "VSnackbar": {
+      "marginTop": {},
+      "marginRight": {},
+      "marginBottom": {},
+      "marginLeft": {},
+      "paddingTop": {},
+      "paddingRight": {},
+      "paddingBottom": {},
+      "paddingLeft": {},
+      "width": {},
+      "height": {},
+      "maxWidth": {},
+      "maxHeight": {},
+      "minWidth": {},
+      "minHeight": {},
+      "unlink": {
+        "default": "false"
+      },
+      "unlinkMax": {
+        "default": "false"
+      },
+      "unlinkMin": {
+        "default": "false"
+      },
+      "isSizeCollapsed": {
+        "default": "false"
+      },
+      "backgroundColor": {
+        "default": "#323232"
+      },
+      "boxShadow": {},
+      "boxSizing": {},
+      "borderTopStyle": {},
+      "borderRightStyle": {},
+      "borderBottomStyle": {},
+      "borderLeftStyle": {},
+      "borderTopLeftRadius": {},
+      "borderTopRightRadius": {},
+      "borderBottomLeftRadius": {},
+      "borderBottomRightRadius": {},
+      "borderTopWidth": {},
+      "borderRightWidth": {},
+      "borderBottomWidth": {},
+      "borderLeftWidth": {},
+      "defaultBorderColor": {},
+      "sides": {}
+    },
+    "VBreadcrumbs": {
+      "marginLeft": {},
+      "marginRight": {},
+      "marginBottom": {},
+      "marginTop": {},
+      "paddingTop": {},
+      "paddingBottom": {},
+      "paddingLeft": {},
+      "paddingRight": {},
+      "width": {},
+      "height": {},
+      "maxWidth": {},
+      "maxHeight": {},
+      "minWidth": {},
+      "minHeight": {},
+      "unlink": {
+        "default": "false"
+      },
+      "unlinkMax": {
+        "default": "false"
+      },
+      "unlinkMin": {
+        "default": "false"
+      },
+      "isSizeCollapsed": {
+        "default": "false"
+      },
+      "defaultItemFontColor": {
+        "default": "rgba(0,0,0,.87)"
+      },
+      "defaultItemFontFamily": {
+        "default": "Roboto"
+      },
+      "defaultItemFontSize": {
+        "default": "14px"
+      },
+      "defaultItemFontStyle": {
+        "default": "normal"
+      },
+      "defaultItemFontWeight": {
+        "default": "400"
+      },
+      "defaultItemCombinedFont": {
+        "default": "Roboto-Regular"
+      },
+      "defaultItemThemeFont": {
+        "default": "Custom"
+      },
+      "defaultItemLineHeight": {
+        "default": "20px"
+      },
+      "disabledItemFontColor": {
+        "default": "rgba(0,0,0,.38)"
+      },
+      "disabledItemFontFamily": {
+        "default": "Roboto"
+      },
+      "disabledItemFontSize": {
+        "default": "14px"
+      },
+      "disabledItemFontStyle": {
+        "default": "normal"
+      },
+      "disabledItemFontWeight": {
+        "default": "400"
+      },
+      "disabledItemCombinedFont": {
+        "default": "Roboto-Regular"
+      },
+      "disabledItemThemeFont": {
+        "default": "Custom"
+      },
+      "disabledItemLineHeight": {
+        "default": "20px"
+      },
+      "dividerFontSize": {
+        "default": "14px"
+      },
+      "backgroundColor": {},
+      "dividerColor": {
+        "default": "rgba(0,0,0,.38)"
+      },
+      "boxShadow": {},
+      "boxSizing": {},
+      "borderTopStyle": {},
+      "borderRightStyle": {},
+      "borderBottomStyle": {},
+      "borderLeftStyle": {},
+      "borderTopLeftRadius": {},
+      "borderTopRightRadius": {},
+      "borderBottomLeftRadius": {},
+      "borderBottomRightRadius": {},
+      "borderTopWidth": {},
+      "borderRightWidth": {},
+      "borderBottomWidth": {},
+      "borderLeftWidth": {},
+      "defaultBorderColor": {},
+      "sides": {}
     }
   }
-}
+}

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/s-track.md

@@ -10,6 +10,7 @@
 - **Styling reference (`S`/`SC`/`SA` schema)** → [reference/styling-system.md](reference/styling-system.md)
 - **Component catalog** → [reference/component-catalog.md](reference/component-catalog.md)
 - **Page skeletons** → [knowledge/page-skeletons.md](knowledge/page-skeletons.md)
+- **Repeated rows/cards from data** → [knowledge/dynamic-components.md](knowledge/dynamic-components.md)
 - **Validation (final checklist)** → [knowledge/validation.md](knowledge/validation.md)
 - **Examples** → [examples/style/](examples/style/) only
 

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/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/ui-app-kit/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(studio *)",
+      "mcp__playwright__*"
+    ]
+  }
+}

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

@@ -7,7 +7,7 @@ description: Reconstruct a Quick / Plateau Studio .qjson page from a Figma desig
 
 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** package ([`index.md`](../../../ui-kit/index.md)) — read those; do not re-derive them here.
+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):

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

@@ -7,7 +7,7 @@ description: Reconstruct a Quick / Plateau Studio .qjson page from a Figma desig
 
 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** package ([`index.md`](../../../ui-kit/index.md)) — read those; do not re-derive them here.
+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):

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

@@ -0,0 +1,22 @@
+# Workflow app workspace — what's in this kit
+
+This workspace holds a **Plateau Studio workflow app**: the business process and every model that runs it, plus the UI pages its tasks open. The file extension is the model type. These docs are the manuals for that content.
+
+## The manuals
+
+| Folder | Read it for |
+|--------|-------------|
+| [`workflow-kit/`](workflow-kit/index.md) | the process domain and the map of everything else — concepts, one doc per model type, the rules every model file shares, the cross-model guides and real examples |
+| [`models/`](workflow-kit/index.md#exact-file-syntax) | one syntax manual per shared model type (`.dataType`, `.dataSet`, `.constant`, services, `.sla`) — the field-by-field shape of the raw file; routed from the workflow-kit index |
+| [`ui-kit/`](ui-kit/index.md) | authoring the `.qjson` pages user tasks open: schema, components, styling, events, the `quick.*` API, validation |
+| [`cli-kit/knowledge/`](cli-kit/knowledge/) | the studio CLI depth behind the sync loop — the bridge, round-trip rules, render checks |
+
+Skills are installed for the two big domains: **plateau-workflow** for workflow models, **quick-qjson** (and **figma-to-qjson**) for pages. Loading a skill and following its manual is equivalent — both land you in the same docs.
+
+## Where to start
+
+Start at [`workflow-kit/index.md`](workflow-kit/index.md) for anything about the process or its models; it routes to the rest. For a page, start at [`ui-kit/index.md`](ui-kit/index.md). Each manual ends with this workspace's CLI loop — validate, sync, report.
+
+## Not covered yet
+
+Workflow model files are not compiled locally. There is no separate checklist file: before finishing, go back over the **What blocks a save** and **Easy to get wrong** sections of the manual for each type you touched, and for a type whose manual has neither, over its field tables. Entity designer (`.entityDesigner`) models have no doc — mirror an existing model in the workspace when you touch one.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/constant-syntax.md

@@ -0,0 +1,70 @@
+# constant — syntax
+
+Syntax rules for a `.constant` model: **one** configuration value carried in a per-environment variant table — a base URL, an endpoint, a mode flag. Studio editor: **Constant Editor** (a single read-only-keyed table, one row per environment).
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"id":"…","name":"payment_endpoint","desc":"","_name":"payment_endpoint","type":"constant","constants":{…}}
+```
+
+The metadata header is identity — never edit or strip it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "name": "payment_endpoint", "desc": "", "_name": "payment_endpoint",
+  "type": "constant",
+  "constants": {
+    "int":         { "constantType": "string", "value": "https://api-int.example.com" },
+    "uat":         { "constantType": "string", "value": "https://api-uat.example.com" },
+    "prod":        { "constantType": "env",    "value": "PAYMENT_API_URL" },
+    "pre-prod":    { "constantType": "string", "value": "https://api-preprod.example.com" },
+    "livepreview": { "constantType": "string", "value": "https://api-int.example.com" } } }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id — as pulled. `""` on a model that has never reached Studio; Studio fills it. Never invent one. |
+| `name` | yes | Identical to the filename without the extension. Studio overwrites it with the model's name every time the editor opens the file — rename the model, don't edit this field. |
+| `desc` | yes | May be `""`, but the key is present. Note the spelling: `desc`, not `description`. |
+| `_name` | yes | Derived from `name`: lowercased, with separator runs collapsed and the following letter capitalized (`_` and `:` survive as-is). Studio recomputes it on every open — never hand-set a different value. |
+| `type` | yes | Always the literal `"constant"`. |
+| `constants` | yes | The environment table, keyed by environment name. |
+
+A constant body is exactly these six keys — no `attributes`, no `options`, no nesting.
+
+## constants — the environment table
+
+```json
+"int": { "constantType": "string", "value": "https://api-int.example.com" }
+```
+
+| Field | Rule |
+|-------|------|
+| key | An environment name. The default set is `int`, `uat`, `prod`, `pre-prod`, `livepreview`; an organization can configure a different list, so match the keys already present in the workspace's other constants rather than assuming. |
+| `constantType` | `"string"` (literal value) or `"env"` (read at runtime from a Docker environment variable). Nothing else. |
+| `value` | Always a JSON **string**, in both forms. For `string` it is the literal; for `env` it is the *name* of the environment variable, not its content. Numbers and booleans are written as quoted strings. |
+
+**Every environment gets an entry**, and the key set is not author-editable: the editor renders one fixed row per configured environment with no add or delete. A missing environment means that deployment has no value; an extra key is not an environment and will never be read.
+
+**One model holds one logical value.** `constants` is not a place for several settings — two values means two constant models. There is no per-environment name, description or type beyond the two fields above.
+
+ Environments may mix forms freely — a literal in `int` and an env var in `prod` is the normal pattern.
+
+## References
+
+A constant is referenced as `<<constant:…>>`, where the reference body is the target's path without the extension in a pulled workspace. It is consumed by `constant`-typed expressions (`{ "type": "constant", "value": "<<constant:…>>" }`), by service host/endpoint fields, by `constant`-typed dataType attributes (which carry the reference in their `ID` field), and by flow code that resolves the constant by reference and gets back a plain string. The environment is chosen at runtime — nothing in the reference names one.
+
+## Easy to get wrong
+
+- The field is `desc`, not `description`.
+- `_name` is derived from `name` — the two never disagree, and neither is edited by hand.
+- Under `constantType: "env"`, `value` is the variable's *name*; putting the actual value there ships the wrong string.
+- Every configured environment needs a row, including `livepreview`.
+- `value` is always a quoted string, never a bare number or boolean.
+- One constant model = one value; adding a second key under `constants` does not create a second setting.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/platform/models/dataSet-syntax.md

@@ -0,0 +1,68 @@
+# dataSet — syntax
+
+Syntax rules for a `.dataSet` model: a closed list of allowed values — status values, categories, header names, any fixed option set consumed by pickers, expressions and flow code. Studio editor: **Data Set Editor**.
+
+## File layout
+
+```
+---studio-metadata DO NOT EDIT---
+id: <model id>
+ownerName: <owner>
+---studio-metadata DO NOT EDIT---
+{"id":"…","name":"Priorities","description":"","type":"set","options":["low","normal","high"]}
+```
+
+The metadata header is identity — never edit or strip it. The model body is **JSON**.
+
+## Model body
+
+```json
+{ "id": "<as pulled>", "name": "Priorities", "description": "", "type": "set",
+  "options": ["low", "normal", "high"] }
+```
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `id` | yes | Model id — as pulled. `""` on a model that has never reached Studio; Studio fills it. Never invent one. |
+| `name` | yes | Identical to the filename without the extension. Studio overwrites it with the model's name every time the editor opens the file — rename the model, don't edit this field. |
+| `description` | yes | May be `""`, but the key is present. Note the spelling: `description`, not `desc`. |
+| `type` | yes | Always the literal `"set"`. |
+| `options` | yes | The values, as a JSON array of strings. |
+
+There is no `desc`, no `attributes`, no `summary` — a dataSet body is exactly these five keys.
+
+## options
+
+A JSON array of plain strings, written in display order; the editor preserves that order.
+
+```json
+"options": ["Pending-InProgress", "Pending-Approval", "Resolved-Completed"]
+```
+
+The values are a **set**: duplicates collapse silently on the next save, so two identical entries become one without warning. An empty string is an allowed value — the editor adds a new row as `""` and nothing rejects it, so an unfinished row survives into the file. The list never goes empty: the last remaining row cannot be deleted.
+
+## Changing an option
+
+An option's text is its identity. Everything that consumes the set stores and compares that exact string, and nothing is rewritten when the text changes — so renaming an option is not an edit inside this file, it is a change that runs through the workspace, and this file is only its first step. Removing one has the same reach: the value keeps living in the places that still name it.
+
+Before changing or dropping a value, find every use of the old text and update them in the same pass. It sits in a handful of predictable places:
+
+- **Query criteria on persisted dataTypes** — a rule that compares a field against the value, in both the authored rule set and the compiled filter, which have to stay in step.
+- **Expressions and conditions** that test the value, and code that compares against it by name.
+- **Pages** bound to the field, where the value may be written into a fixed option or a display label.
+
+If the search comes back empty the change is local. If it does not, those files are updated together with this one, and the change is reported as touching all of them. Adding a value reaches nothing and is always safe.
+
+## References
+
+A dataSet is referenced as `<<dataSet:…>>`, where the reference body is the target's path without the extension in a pulled workspace. It is consumed by dataType attributes typed `dataSet` (which carry the reference in `objectID`), by `dataSet`-typed expressions in mappings and conditions, and by flow code that loads the set by reference.
+
+One dataSet is bound by name rather than by reference: a set named `ProcessStatus` supplies a workflow's custom process statuses. Never rename it.
+
+## Easy to get wrong
+
+- The field is `description`, not `desc`.
+- `options` is a JSON array of strings — never an object, and never a nested `{ value: … }` wrapper.
+- `type` is the form of the model, always `"set"` — it says nothing about the datatype of the values, which are always strings.
+- Duplicate options are dropped, not reported.
+- Renaming or removing an option reaches every place that names the old text — search the workspace for it and update those files in the same change. Adding reaches nothing.