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

package/dist/quick/common/shrimp/src/Performance/PerfSingles.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerfSingles = void 0;
+const PerfManager_1 = require("./PerfManager");
+class PerfSingles {
+    static self;
+    static Register() {
+        PerfSingles.findSelf();
+    }
+    static Activate(name) {
+        const targetPerf = this.findSelf().findPerf(name);
+        targetPerf.Activate();
+    }
+    static Instance(name) {
+        return this.findSelf().findPerf(name);
+    }
+    static Reset() {
+        this.findSelf().perfSingles = {};
+    }
+    static findSelf() {
+        if (PerfSingles.self) {
+            return PerfSingles.self;
+        }
+        if (typeof window === "undefined") {
+            return PerfSingles.self = new PerfSingles();
+        }
+        return PerfSingles.self = window["perfQuickShrimp"] = window["perfQuickShrimp"] || new PerfSingles();
+    }
+    //Instance
+    perfSingles = {};
+    perfSingle;
+    findPerf(name) {
+        let targetPerf = name ? this.perfSingles[name] : this.perfSingle;
+        if (targetPerf) {
+            return targetPerf;
+        }
+        targetPerf = name ? this.perfSingles[name] = new PerfManager_1.PerfManager() : this.perfSingle = new PerfManager_1.PerfManager();
+        return targetPerf;
+    }
+    Activate(name) {
+        const targetPerf = this.findPerf(name);
+        targetPerf.Activate();
+    }
+}
+exports.PerfSingles = PerfSingles;
+PerfSingles.Register();
+//# sourceMappingURL=PerfSingles.js.map

package/dist/quick/common/shrimp/src/Performance/PerfSingles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerfSingles.js","sourceRoot":"","sources":["../../../../../../../quick/common/shrimp/src/Performance/PerfSingles.ts"],"names":[],"mappings":";;;AAAA,+CAA4C;AAE5C,MAAa,WAAW;IACZ,MAAM,CAAC,IAAI,CAAc;IAE1B,MAAM,CAAC,QAAQ;QAClB,WAAW,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAEM,MAAM,CAAC,QAAQ,CAAC,IAAa;QAChC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClD,UAAU,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAEM,MAAM,CAAC,QAAQ,CAAC,IAAa;QAChC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAEM,MAAM,CAAC,KAAK;QACf,IAAI,CAAC,QAAQ,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC;IACrC,CAAC;IAEO,MAAM,CAAC,QAAQ;QACnB,IAAI,WAAW,CAAC,IAAI,EAAE;YAAE,OAAO,WAAW,CAAC,IAAI,CAAC;SAAE;QAClD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YAAE,OAAO,WAAW,CAAC,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;SAAE;QACnF,OAAO,WAAW,CAAC,IAAI,GAAS,MAAO,CAAC,iBAAiB,CAAC,GAAS,MAAO,CAAC,iBAAiB,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;IACvH,CAAC;IAGD,UAAU;IACF,WAAW,GAAgC,EAAE,CAAC;IAC9C,UAAU,CAAe;IAEzB,QAAQ,CAAC,IAAa;QAC1B,IAAI,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;QACjE,IAAI,UAAU,EAAE;YAAE,OAAO,UAAU,CAAC;SAAE;QAEtC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,yBAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,yBAAW,EAAE,CAAC;QAEtG,OAAO,UAAU,CAAC;IACtB,CAAC;IACM,QAAQ,CAAC,IAAa;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvC,UAAU,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;CACJ;AA3CD,kCA2CC;AAED,WAAW,CAAC,QAAQ,EAAE,CAAC"}

package/dist/quick/common/shrimp/src/context/IContextItem.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IContextItem.js.map

package/dist/quick/common/shrimp/src/context/IContextItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContextItem.js","sourceRoot":"","sources":["../../../../../../../quick/common/shrimp/src/context/IContextItem.ts"],"names":[],"mappings":""}

package/dist/quick/common/shrimp/src/context/contextManager.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextManager = void 0;
+class ContextManager {
+    contextItems = {};
+    constructor() {
+    }
+    /**
+     * Register item to context
+     * @param item item to register
+     */
+    RegisterItem(item, options = { override: false }) {
+        let contextGroup = this.contextItems[item.contextName];
+        if (!contextGroup || options.override) {
+            contextGroup = [];
+            this.contextItems[item.contextName] = contextGroup;
+        }
+        contextGroup.push(item);
+    }
+    GetOrCreate(contextItemName, contextCreatorCb) {
+        let contextItem = this.GetItemSingle(contextItemName);
+        if (!contextItem) {
+            contextItem = contextCreatorCb();
+            this.RegisterItem(contextItem);
+        }
+        return contextItem;
+    }
+    /**
+     * Gets last Item. Use ! if it must exist.
+     */
+    GetItemSingle(contextItemName) {
+        const contextGroup = this.GetItemGroup(contextItemName);
+        if (!contextGroup) {
+            return undefined;
+        }
+        return contextGroup[contextGroup.length - 1]; //contextItem.name
+    }
+    GetItemGroup(contextItemName) {
+        return this.contextItems[contextItemName] || null;
+    }
+    ClearItemGroup(contextItemName) {
+        delete this.contextItems[contextItemName];
+    }
+    ClearItem(c) {
+        const itemGroup = this.GetItemGroup(c.contextName);
+        if (!itemGroup) {
+            return;
+        }
+        const itemIndex = itemGroup.indexOf(c);
+        itemGroup.splice(itemIndex, 1);
+    }
+    /**
+     * Shallow copy of self
+     * @param fields if specified, only puts those fields in the clone
+     */
+    Clone(fields) {
+        const contextCopy = new ContextManager();
+        const keys = fields ?? Object.keys(this.contextItems);
+        keys.forEach(contextKey => contextCopy.contextItems[contextKey] = this.contextItems[contextKey]?.map(item => item));
+        return contextCopy;
+    }
+    /**
+     * Get Contexts registered context item keys
+     */
+    GetKeys() {
+        return Object.keys(this.contextItems);
+    }
+}
+exports.ContextManager = ContextManager;
+//# sourceMappingURL=contextManager.js.map

package/dist/quick/common/shrimp/src/context/contextManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextManager.js","sourceRoot":"","sources":["../../../../../../../quick/common/shrimp/src/context/contextManager.ts"],"names":[],"mappings":";;;AAEA,MAAa,cAAc;IACf,YAAY,GAAoD,EAAE,CAAC;IAC3E;IAEA,CAAC;IAED;;;OAGG;IACI,YAAY,CAAC,IAAkB,EAAE,UAA+B,EAAC,QAAQ,EAAC,KAAK,EAAC;QACnF,IAAI,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE;YACnC,YAAY,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,YAAY,CAAC;SACtD;QAED,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAEM,WAAW,CAAuC,eAAuB,EAAE,gBAAuC;QACrH,IAAI,WAAW,GAAG,IAAI,CAAC,aAAa,CAAkB,eAAe,CAAC,CAAC;QACvE,IAAI,CAAC,WAAW,EAAC;YACb,WAAW,GAAG,gBAAgB,EAAE,CAAC;YACjC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;SAClC;QACD,OAAO,WAAW,CAAC;IACvB,CAAC;IACD;;OAEG;IACI,aAAa,CAAuC,eAAuB;QAC9E,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAkB,eAAe,CAAC,CAAC;QACzE,IAAI,CAAC,YAAY,EAAE;YACf,OAAO,SAAS,CAAC;SACpB;QACD,OAAO,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB;IACpE,CAAC;IAEM,YAAY,CAAuC,eAAuB;QAC7E,OAAQ,IAAI,CAAC,YAAY,CAAC,eAAe,CAA4B,IAAI,IAAI,CAAC;IAClF,CAAC;IAEM,cAAc,CAAC,eAAuB;QACzC,OAAO,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IAC9C,CAAC;IAEM,SAAS,CAAC,CAAe;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,EAAE;YACZ,OAAO;SACV;QACD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACvC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAsB;QAC/B,MAAM,WAAW,GAAG,IAAI,cAAc,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACpH,OAAO,WAAW,CAAC;IACvB,CAAC;IAED;;OAEG;IACI,OAAO;QACV,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;CACJ;AAzED,wCAyEC"}

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

@@ -0,0 +1,20 @@
+# UI app workspace — what's in this kit
+
+This workspace holds **Quick / Plateau Studio `.qjson`** 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 — style-track routing, the authoring rules, 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); its Step 0 routes you to the right style track and lists exactly which docs to open for the task.
+
+## 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/ui-app-kit/.ai-kit/ui-kit/examples/README.md

@@ -0,0 +1,12 @@
+# Examples — split by style system
+
+These reference pages are split into two folders by which **style system** they use. Pick the folder that matches the page you are working on (see the routing rule in [../index.md](../index.md) — read `opt.V` first).
+
+| Folder | Contains | Reference it when |
+| --- | --- | --- |
+| [`style/`](style/) | **S-system pages**: `opt.V >= 2.0` — design authored in the node's `S` object. | **Authoring a new page** or editing an **S-system** page (`opt.V >= 2.0`). This is the default. |
+| [`cssClass/`](cssClass/) | **Legacy pages**: `opt.V` missing or `< 2.0` — design via `O.layout` (`dOpt` + compiled `class`) / CSS utility classes. | **Only** when editing a **legacy** page (`opt.V` missing or `< 2.0`). |
+
+**Rule of thumb:** if you are building or styling in the `S` system, look **only** in [`style/`](style/) — do not copy patterns from [`cssClass/`](cssClass/), which contains the legacy mechanism you must not author on new/`S` pages.
+
+**Split axis:** the signal is the page's `opt.V`, kept consistent with whether the page actually uses the `S` Style System. A page with `opt.V >= 2.0` (authored with `S` style objects) is on the `S` system → `style/`; a page with `opt.V` missing or `< 2.0` (styled via `O.layout` + CSS classes) is legacy → `cssClass/`. The presence of an `S` object is the ground truth: **treat any page carrying an `S` object as S-system regardless of the folder it currently sits in** (a few partially-migrated pages still sit in `cssClass/`; 

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

@@ -0,0 +1,87 @@
+# Quick qjson — agent guide (start here)
+
+You are an AI coding agent working on **Quick / Plateau Studio `.qjson` files** — UI pages that live in Studio (the web IDE). These docs are the source of truth for Quick. Follow this guide.
+
+## Step 0 — determine the style system, then follow your track guide
+
+Quick has **two style systems**, and they are not interchangeable on a page. Decide which one the target page is on **before** you style, lay out, or validate — then follow that track's guide and doc set for the rest of the task.
+
+**Read the target's root-level `opt.V`:**
+
+| Condition | Track | Guide to follow |
+|-----------|-------|-----------------|
+| **Creating a new page** | **`S` (new)** — new pages are always created at the current `V` | [s-track.md](s-track.md) |
+| **`opt.V >= 2.0`** | **`S` (new)** — the `S` object renders; author design in `S` | [s-track.md](s-track.md) |
+| **`opt.V` missing OR `< 2.0`** | **legacy (`cssClass`)** — `S` does NOT render; author `O.layout` + CSS classes | [legacy-track.md](legacy-track.md) |
+
+There is no in-between: a page is either fully `S` or fully legacy. **Do not mix mechanisms** (never introduce `S` on a legacy page — it silently won't render; never author `O.layout` on an `S` page). **The presence of an `S` object is the ground truth for which system a page is on**, and `opt.V` should agree with it (`>= 2.0` ⇔ uses `S`). If the two disagree — `opt.V >= 2.0` but the nodes carry `O.layout`, or `opt.V` missing/`< 2.0` but the nodes carry an `S` object — the page is mid-migration or mis-tagged: go by whether an `S` object is actually present, and flag the mismatch to the user.
+
+Your track guide lists the exact doc set to use (schema, structure, layout, styling, catalog, skeletons, validation, examples) — **open only your track's docs plus the shared docs below.**
+
+## What a `.qjson` is (one paragraph)
+A JS module exporting `pjson = { ... }`. You author `pJson` (a tree of component nodes) and `lrids` (localization) — so an **AI-authored file carries only `{ pJson, lrids, opt }`**. The editor/compiler generates the compiled twins `cJson`/`clrids`; **omit them entirely from files you author** — never write them into a new file, and **strip them if present** when editing an existing file (Studio regenerates them on import). Each node is `{ T, P, E, C, O, _Editor }` plus styling fields — `S`/`SA`/`SC` on `S`-system pages, `O.layout` on legacy pages. Full schema: `S` → [reference/qjson-schema.md](reference/qjson-schema.md); legacy → [reference/qjson-schema-legacy.md](reference/qjson-schema-legacy.md).
+
+## Where to look — shared docs (both tracks)
+These carry no style-era content; use them regardless of track:
+- **Task-oriented how-to (shared topics)** → [knowledge/properties.md](knowledge/properties.md), [events-and-scripting.md](knowledge/events-and-scripting.md), [components.md](knowledge/components.md), [services.md](knowledge/services.md), [localization.md](knowledge/localization.md), [dynamic-components.md](knowledge/dynamic-components.md).
+- **Exact API of `quick.*`** (store, alert, request, navigation, validation, dates…) → [reference/quick-api.md](reference/quick-api.md) — the authoring rules **plus a complete index of every member**. Scan that index to see what exists, then grep the member's full signature/params/example in [reference/quick-api.json](reference/quick-api.json) (per-member blocks; never read it whole).
+- **Events deep dive** → [reference/events-system.md](reference/events-system.md).
+- **Which `T` exists + registry** → [reference/component-index.json](reference/component-index.json) (machine-readable; era-agnostic).
+- **Valid props/events for a component (so you don't invent them)** → [reference/component-contracts.json](reference/component-contracts.json) (per `T`: each prop's `pType` prop/class/text/attr, value `type`, allowed `options` (enum), `default`; and `events` as `{ name, params?: [{name,type}] }`).
+- **Valid Style-tab (`S`) params for a component** → [reference/component-styles.json](reference/component-styles.json) (per `T`: supported style param → value `type` + editor `default`). **Not every component has a block** — `componentsWithStyleBlocks` in [reference/component-index.json](reference/component-index.json) lists the ones that do (and `componentsWithSC` the ones that take an `SC`), so a grep returning nothing is an answer, not a failed lookup.
+
+> **Do NOT read these big files whole.** `component-contracts.json`, `component-styles.json` (keyed per `T`, one component block each) and `quick-api.json` (keyed per API member) are lookup tables, not documents. Reading either whole wastes context and the file tools cap at 2000 lines — so a whole-file read silently truncates and you'd miss most components without knowing. Instead, **for each component you place, grep its block and read only that slice**: `grep -n '"VIcon":' reference/component-contracts.json` → a line number → `Read` that offset for ~30–60 lines. Same for an API member: `grep -n '"setRegion"' reference/quick-api.json`. Batch the lookups a section needs before writing it.
+
+> **Why read these first (the core principle):** these dictionaries are *generation inputs*. Pick the prop/event/param/style from the contract **before** you write — then you never invent something the editor rejects. Never discover the valid set by trial and error against editor/compiler messages (a raw error says *what's wrong*, not *what's right*). Look it up up front.
+
+
+**Everything else — the schema, structure, layout, styling how-to, component catalog, page skeletons, validation checklist, and examples folder — is era-specific and listed in your track guide** ([s-track.md](s-track.md) / [legacy-track.md](legacy-track.md)).
+
+
+## Workflow for every task
+1. **Read the target + neighbors.** Open the `.qjson` you'll edit and 1–2 sibling pages in the same folder. These docs give you the *rules*; sibling pages give you *project conventions* (ID style, service URLs, `QJsonPath` of any service component, navigation `<<qjson:id>>` references). Mirror them.
+2. **Classify the work** — static layout / service / table / dialog-form / chart / navigation / localization / dynamic component (any repeated rows or cards built from data). Read the matching shared `knowledge/` file(s).
+3. **Determine the style system (Step 0) and open your track guide.** Everything about *how* you build the tree's design, style, lay out, and validate lives there — follow it.
+4. **Validate** before finishing: walk your track's `validation…` checklist and fix every issue. Touched multiple files → validate them all.
+5. **Report**: changed file(s), what changed (including styling), the validation result — say plainly what was and wasn't checked — and any project assumption you made.
+
+## Non-negotiable rules — shared (both tracks)
+These apply on every page regardless of era. (Style/layout-mechanism rules are in your track guide.)
+1. **Omit `cJson`/`clrids` entirely from AI-authored files.** Author `pJson`/`lrids` only; never write the compiled twins into a new file, and **strip them if present** when editing an existing one. Studio regenerates them on import.
+2. Every node: valid `T` (check the index), unique `P.ID.H`, unique `_Editor.eID`. (eID need not equal ID.) Don't invent props **or events** — use the props/events listed for that `T` in [reference/component-contracts.json](reference/component-contracts.json), with the PType it specifies and the event `params` it gives.
+3. Strings in prop `H` are single-quoted (`"'primary'"`); booleans/numbers/expressions are bare; QScript object literals use `=` (`{text='A', value=1}`).
+4. `QLabel.text` → PType `"prop"`. `VIcon` icon name → `text` with PType `"text"` — `H` is still a QScript string, so single-quote it: `"H": "'mdi-home'"` (never bare `"mdi-home"`).
+5. Events: never native `return` (use `quick.return`); close object literals with `};`; no browser globals (`window`/`document`/`console`/`setTimeout`) — use `quick.*`. **Event handlers are always TypeScript — set `"HL":"TS"` on every handler.** (Property/binding expressions are the ones that default to `QS`.)
+6. Props use bare `LR('key')`; events use `quick.LR('key')`.
+7. **Containment** (editor-enforced, era-agnostic): `VCol` only inside `VRow` (never at root); `VRow` holds only `VCol`; `VFooter` holds only `VContainer`; canonical wrapper `VContainer > VRow > VCol > content`.
+8. Charts: only `Bar`/`Line`/`Doughnut` (no `Pie`); no `visible` prop on charts.
+9. `quick.Quick.alert({...})` always includes `actionButtons`.
+10. `VBtn` label is a child `QLabel`/`VIcon`/`VImg`, not a text prop.
+11. **If you rename/move/delete a page that others reference**, update every referrer's `<<qjson:path>>` in the same change (references are path-based, so they go stale) — see [knowledge/validation.md](knowledge/validation.md#renaming--moving--deleting-a-referenced-page--update-the-referrers-yourself).
+12. **Never paste compiled (`╬…╩╩`) content** into a file — that is generated output (see rule 1).
+
+## Easy to get wrong
+These are the rules most often assumed backwards. Check them against what you were about to write.
+- **Props *can* contain `if/else` conditionals** — QScript returns the last evaluated value.
+- **`VIcon`'s icon name uses PType `"text"`**, not `"prop"` — and `H` is still a single-quoted QScript string: `"H": "'mdi-home'"`, never `"H": "mdi-home"`.
+- **`_Editor.eID` need not equal `P.ID.H`** (equal when auto-generated; differs after a rename).
+- **Property/binding expressions default to `QS`; event handlers are always `TS`** (`"HL":"TS"` on every handler). The default applies to properties only — handlers are TS-only.
+- **`quick.store` prefixes** are Page/Bag(`#`)/Global(`$`)/Shared(`&`) — for cross-session persistence use `quick.permanentStore`.
+- **`quick.Quick.validation`** has `required/minLength/maxLength/email/iban/regex/tckn/vkn` — there is no `phone` rule (use the input's `format` + `regex`).
+- **Per-component design lives in the Style tab, not only in CSS utility classes.** How it serializes depends on the page's era — see your track guide.
+
+## When unsure
+Don't invent props/events/slots/values. Check [reference/component-index.json](reference/component-index.json) and your track's component catalog; for Vuetify components Vuetify 2 semantics apply; otherwise find a real example in a sibling page or ask the user. If a `T` isn't in the index, it's probably wrong (or the index needs updating from a newer runtime).
+
+## This workspace: the studio CLI loop
+
+These pages were pulled from Studio with the studio CLI and will be synced back. On top of the steps above:
+
+- **Validate — always, before finishing.** `studio buildQjson <file-or-folder>` runs the official Quick compiler plus the structural and `S`-style checks. It **never edits the file**: read the errors, apply every fix yourself, re-run until clean. Details: [`../cli-kit/knowledge/buildqjson.md`](../cli-kit/knowledge/buildqjson.md).
+- **Sync.** Once validation is clean and `.studio/server.json` exists (the CLI bridge is running), run `studio push` yourself — the page lands in the user's open Studio session as unsaved work. Round-trip rules, frontmatter, `<<qjson:path>>` translation, `convertToBlock`: [`../cli-kit/knowledge/sync.md`](../cli-kit/knowledge/sync.md).
+- **Render-check.** Compiling clean does not prove the page runs clean. With the `playwright` MCP available, open `http://127.0.0.1:<port>/render` (port from `.studio/server.json`), fix what the render and console show, then `browser_close`: [`../cli-kit/knowledge/render-check.md`](../cli-kit/knowledge/render-check.md).
+- **Locked files.** A pulled page may be readonly (`0444`) — checked out by someone else in Studio. Run `studio startWorking <file>`; never `chmod`.
+- **Frontmatter.** Files may carry a `---studio-metadata---` header (model id, flags like `blockComponent`). Never edit or strip it, and never rename files — Studio matches them back by name/id. A new file gets its frontmatter written back by `studio push`.
+- **Report** the validation, push and render-check results. If the bridge or the browser wasn't available, say so — never skip silently.
+
+Bridge setup and troubleshooting: [`../cli-kit/knowledge/cli-bridge.md`](../cli-kit/knowledge/cli-bridge.md).