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

package/dist/studio-cli/src/.ai-kit/knowledge/10-validation-and-sync-legacy.md

@@ -1,69 +0,0 @@
-# 10 · Validation & Studio Sync — legacy `cssClass` system
-
-> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
->
-> **This file is the `legacy` track.** Shared-core checks + sync-back rules are identical across tracks; only the style checklist (§B) differs. On a new page / `opt.V >= 2.0` instead → [10-validation-and-sync.md](10-validation-and-sync.md).
-
-The intended loop: **Studio → download `.qjson` folder → AI edits locally → self-check & fix in a loop → sync back to Studio.** This replaces the manual *paste-into-editor → copy-error → ask-AI → paste-back* round-trip: the AI checks its own output and fixes errors before you ever see it.
-
-## One command: `studio buildQjson` (the fix-loop)
-
-```bash
-studio buildQjson path/to/page.qjson
-```
-Runs **the official Quick compiler** (bundled with studio-cli) on the file or folder: compiles `pJson → cJson` exactly like the editor and reports **QScript/TypeScript syntax & type errors** in your handlers. (See [tools/README.md](../tools/README.md).)
-
-The loop: **run → if there are errors, read them, fix the file, re-run → deliver when it compiles clean.**
-
-## Pre-sync checklist
-
-### A) Shared core — every page
-- [ ] Module shape: three authored keys present (`pJson`, `lrids`, `opt`); ends with `};` + `export default pjson`.
-- [ ] `cJson`/`clrids` **absent** — omitted from new files, stripped from any downloaded file you edited (Studio regenerates the compiled twins on import).
-- [ ] Every node: `T` valid; `P.ID.H` present + unique; `_Editor.eID` present + unique (equal to ID when new; may differ after a Studio rename — not required to match); **`C` present** (use `{}` for leaves — omitting `C` is a validator error).
-- [ ] Props: strings single-quoted in `H`; QScript object literals use `=`; `QLabel.text`=`prop`, `VIcon.text`=`text`.
-- [ ] Events: no native `return` (use `quick.return`); object literals closed with `};`; no browser globals; custom events have `C:true`; `P` matches payload.
-- [ ] Localization: `lrids` per language; keys exist in all languages; `LR` in props / `quick.LR` in events.
-- [ ] Containment: `VCol` only inside `VRow`; `VRow` holds only `VCol`; item components inside their container.
-- [ ] Charts: only `Bar`/`Line`/`Doughnut`; no `visible` on the chart.
-- [ ] Alerts include `actionButtons`.
-- [ ] `studio buildQjson <file>` compiles clean (no errors).
-
-### B) Legacy style checklist
-- [ ] **No `S` introduced** — it won't render on `V < 2`; design stays in `O.layout` / CSS classes, matching how the page already does it.
-- [ ] `O.layout.dOpt` ↔ `O.layout.class` in sync — recompile `class` per the algorithm in [../reference/layout-system.md](../reference/layout-system.md) after any `dOpt` change (`xs` as-is; `sm/md/lg/xl` infixed).
-- [ ] `class` prop used freely for design (typography/color/spacing/elevation) is expected here — it is the legacy styling mechanism, Web-only, and is NOT audited against `S`.
-
-## `<<qjson:path>>` — ID↔path translation
-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
-
-**What this means when authoring locally:**
-- Always write `'<<qjson:path>>'` — never a raw model ID.
-- The path is relative to the project root, without the `.qjson` extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:forms/login>>` for a nested one).
-- If you see a UUID-style `<<qjson:...>>` in a pulled file, that means pull did not find the target page locally — do not copy that ID format into new authoring.
-
-### Renaming / moving / deleting a referenced page — update the referrers yourself
-Locally the link between two pages is the **path/name** inside `<<qjson:path>>`; in Studio it is a stable model id. So on the Studio side a rename/move needs no extra work (the id never changes) — but **locally every file that referenced the old path goes stale** and `studio push` can no longer resolve it (`replacePathsWithIds` fails → broken link). When **you** (the agent) rename, move, or delete a `.qjson`, you must fix the referrers in the same change:
-
-1. **Find referrers first.** Grep the whole project for the target's current path *before* you touch it:
-   `grep -rln "<<qjson:sari-buton>>" .` (use the exact path the referrers use — root-level is just the name, nested is `folder/name`, module-owned is `ModuleName/.../name`, no `.qjson`).
-2. **Rename / move** → replace `<<qjson:oldPath>>` with `<<qjson:newPath>>` in every referrer. Keep the target file's frontmatter `id` unchanged so Studio still matches it.
-3. **Delete** → the reference target no longer exists; do not leave a dangling `<<qjson:path>>`. Remove or repoint the component instance that used it in each referrer (e.g. the `CustomComponent` whose `QJsonPath` pointed there), then validate.
-4. **Compile every file you edited** (`studio buildQjson`) — referrers included, not just the renamed page.
-
-> If the **user** renames/moves a file manually (outside the agent), `studio push` is expected to repair referrers automatically; this section is the agent's responsibility for agent-initiated changes.
-
-
-## 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** (see next).
-- Omit `cJson`/`clrids` so Studio recompiles cleanly on import — it regenerates the compiled twins whether they're absent or empty. Strip them from any downloaded file you edit; never paste compiled (`╬…╩╩`) content by hand.
-- For multi-file edits, validate the whole folder before syncing.
-
-## 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 [11-cli-bridge.md](11-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.

package/dist/studio-cli/src/.ai-kit/knowledge/10-validation-and-sync.md

@@ -1,78 +0,0 @@
-# 10 · Validation & Studio Sync — `S` system
-
-> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
->
-> **This file is the `S` track.** Shared-core checks + sync-back rules are identical across tracks; only the style checklist (§B) differs. On a **legacy** page instead → [10-validation-and-sync-legacy.md](10-validation-and-sync-legacy.md).
-
-The intended loop: **Studio → download `.qjson` folder → AI edits locally → self-check & fix in a loop → sync back to Studio.** This replaces the manual *paste-into-editor → copy-error → ask-AI → paste-back* round-trip: the AI checks its own output and fixes errors before you ever see it.
-
-## One command: `studio buildQjson` (the fix-loop)
-
-```bash
-studio buildQjson path/to/page.qjson
-```
-Runs **the official Quick compiler** (bundled with studio-cli) on the file or folder: compiles `pJson → cJson` exactly like the editor and reports **QScript/TypeScript syntax & type errors** in your handlers, then the structural and `S`-style validations. (See [tools/README.md](../tools/README.md).)
-
-**The tool never edits the qjson — it only reports. Every fix is yours to apply**, then re-run until clean. The style validation reports `S`/`SC` gaps as **errors**, each naming the exact params so you know precisely what to write:
-
-- **`missing-S` / `incomplete-S`** — the node's `S` lacks default-valued params from the component's [`component-styles.json`](../reference/component-styles.json) block. Fix: add each listed param to the `"xs-xl"` range with its default value from that block (or your design's override) — rule S3. (`VCol.flexDirection` is exempt: its editor default `column` does not match the runtime-unset `row` behavior — write it deliberately when you want stacking, per rule S5.)
-- **`missing-SC` / `incomplete-SC` / `wrong-SC-target` / `unknown-SC*`** — the node's `SC` does not match the component's `inheritedChildList` in `component-styles.json`. Fix: copy that block into `SC` **as-is** (the whole block, never a subset); remove `SC` entirely from components whose block has no `inheritedChildList`.
-- **`unknown-S-param`** — the param doesn't exist for this component; rename per the suggestion or remove it (the compiler silently drops it).
-
-The loop: **run → read the errors → apply the fixes yourself from `component-styles.json` → re-run → deliver when it's clean.**
-
-## Pre-sync checklist
-
-### A) Shared core — every page, both style systems
-- [ ] Module shape: three authored keys present (`pJson`, `lrids`, `opt`); ends with `};` + `export default pjson`.
-- [ ] `cJson`/`clrids` **absent** — omitted from new files, stripped from any downloaded file you edited (Studio regenerates the compiled twins on import).
-- [ ] Every node: `T` valid; `P.ID.H` present + unique; `_Editor.eID` present + unique (equal to ID when new; may differ after a Studio rename — not required to match); **`C` present** (use `{}` for leaves — omitting `C` is a validator error).
-- [ ] Props: strings single-quoted in `H`; QScript object literals use `=`; `QLabel.text`=`prop`, `VIcon.text`=`text`.
-- [ ] Events: no native `return` (use `quick.return`); object literals closed with `};`; no browser globals; custom events have `C:true`; `P` matches payload.
-- [ ] Localization: `lrids` per language; keys exist in all languages; `LR` in props / `quick.LR` in events.
-- [ ] Containment: `VCol` only inside `VRow`; `VRow` holds only `VCol`; item components inside their container.
-- [ ] Charts: only `Bar`/`Line`/`Doughnut`; no `visible` on the chart.
-- [ ] Alerts include `actionButtons`.
-- [ ] `studio buildQjson <file>` compiles clean (no errors).
-
-### B) `S`-system style checklist
-
-- [ ] Every visually-intentful node has an `S` object (range-keyed); child text/icons via the parent's `SC`. No structure-only nodes.
-- [ ] **No `O.layout`** (`dOpt`/`class`) on any node — grid width, flex direction/align/justify, and spacing all live in `S`.
-- [ ] **Class-prop audit:** if any `class` prop is present, verify each token individually against the `class → S` table in [../reference/styling-system.md](../reference/styling-system.md) §9 (full table: [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md)). Tokens that have an `S` equivalent must NOT appear in `class` (e.g. `fill-height` when `S.height:"100%"` is set, `pt-2` when `S.paddingTop:"8px"` is set, `flex-column` when `S.flexDirection:"column"` is set). `class` here is a Web-only last resort, only for tokens with confirmed no `S` equivalent — and has no Mobile effect.
-- [ ] Vuetify style-affecting props not used where `S` has an equivalent (`VCol.cols/sm/md/lg/xl` → `S.col`; `VBtn/VCard.color` → `S.backgroundColor`; `elevation` prop → `S.boxShadow`).
-
-## `<<qjson:path>>` — ID↔path translation
-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
-
-**What this means when authoring locally:**
-- Always write `'<<qjson:path>>'` — never a raw model ID.
-- The path is relative to the project root, without the `.qjson` extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:forms/login>>` for a nested one).
-- If you see a UUID-style `<<qjson:...>>` in a pulled file, that means pull did not find the target page locally — do not copy that ID format into new authoring.
-
-### Renaming / moving / deleting a referenced page — update the referrers yourself
-Locally the link between two pages is the **path/name** inside `<<qjson:path>>`; in Studio it is a stable model id. So on the Studio side a rename/move needs no extra work (the id never changes) — but **locally every file that referenced the old path goes stale** and `studio push` can no longer resolve it (`replacePathsWithIds` fails → broken link). When **you** (the agent) rename, move, or delete a `.qjson`, you must fix the referrers in the same change:
-
-1. **Find referrers first.** Grep the whole project for the target's current path *before* you touch it:
-   `grep -rln "<<qjson:sari-buton>>" .` (use the exact path the referrers use — root-level is just the name, nested is `folder/name`, module-owned is `ModuleName/.../name`, no `.qjson`).
-2. **Rename / move** → replace `<<qjson:oldPath>>` with `<<qjson:newPath>>` in every referrer. Keep the target file's frontmatter `id` unchanged so Studio still matches it.
-3. **Delete** → the reference target no longer exists; do not leave a dangling `<<qjson:path>>`. Remove or repoint the component instance that used it in each referrer (e.g. the `CustomComponent` whose `QJsonPath` pointed there), then validate.
-4. **Compile every file you edited** (`studio buildQjson`) — referrers included, not just the renamed page.
-
-> If the **user** renames/moves a file manually (outside the agent), `studio push` is expected to repair referrers automatically; this section is the agent's responsibility for agent-initiated changes.
-
-## 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** (see next).
-- Omit `cJson`/`clrids` so Studio recompiles cleanly on import — it regenerates the compiled twins whether they're absent or empty. Strip them from any downloaded file you edit; never paste compiled (`╬…╩╩`) content by hand.
-- For multi-file edits, validate the whole folder before syncing.
-
-## 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 [11-cli-bridge.md](11-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.

package/dist/studio-cli/src/.ai-kit/knowledge/11-cli-bridge.md

@@ -1,97 +0,0 @@
-# 11 · 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/src/.ai-kit/knowledge/12-render-check.md

@@ -1,48 +0,0 @@
-# 12 · 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-sync checklist](10-validation-and-sync.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/src/.ai-kit/reference/component-catalog-legacy.md

@@ -1,120 +0,0 @@
-# Component Catalog — Authoritative `T` Names & Contracts (legacy `cssClass` system)
-
-> **Style system: legacy (`cssClass`).** For legacy pages only — root-level `opt.V` missing or `< 2.0`, where `S` does not render. Component identity (`T` names, props, events) is the same in both eras; only the `VContainer`/`VRow`/`VCol` styling note below is legacy-specific. On a new page, or one with `opt.V >= 2.0`? Use [component-catalog.md](component-catalog.md) instead.
->
-> Source of truth: the Quick runtime component registry (`packages/websdk/src/components/providers/VuetifyComponents.ts`, `LocalComponents.ts`, `ChartComponents.ts`, `common/shrimp/constants/knownComps.ts`). The machine-readable list lives in [component-index.json](component-index.json). Vuetify components follow Vuetify 2 prop/event/slot semantics unless noted.
-
-## 1. Lifecycle / system (non-visual or embedding)
-
-| `T` | Role |
-|-----|------|
-| `Messaging` | Page event hub. Holds lifecycle hooks (`PreRender`, `EndRender`, `PostRender`, `Restored`) and custom events. Prop `masterPath`; can declare `ExternalProps`/`ExternalEvents`. `O.cType: "child"`. |
-| `CustomComponent` | Embeds another `.qjson` via prop `QJsonPath`; cascades `readonly`/`disabled` to children. `O: { cType:"child", dynProps:true }`. |
-| `RenderingComponent` | Root embedder for a qjson view (props `QJsonPath`, `readonly`, `disabled`). |
-| `Ghost` | Empty placeholder div; used as a structural child / insertion anchor. |
-
-## 2. Charts (Chart.js) — only three exist
-
-| `T` | Notes |
-|-----|-------|
-| `Bar` | vertical/horizontal bars (`indexAxis: 'x'|'y'`) |
-| `Line` | has `fill`, `tension`, point styling |
-| `Doughnut` | `cutoutPercentage: 0` renders a **pie** shape |
-
-> **There is no `Pie` runtime component.** The chart library registers exactly `{ Doughnut, Bar, Line }`. `QPieChart` is a mobile-only placeholder. Use `Doughnut` for pie charts.
-
-Chart prop vocabulary: `labels` (array of axis/segment labels), `data` (number array), `label` (singular dataset name), `backgroundColor`/`borderColor` (array or string), `borderWidth`, `width`/`height`, axis (`xDisplay`/`yDisplay`), legend (`legendDisplay`/`legendPosition`), data labels (`labelDisplay`, ...). Charts have **no `visible` prop** — wrap in a `VCol` and toggle that. Runtime updates: mutate `components.<id>.data` then `(<any>components.<id>).update()`.
-
-## 3. Quick-native components
-
-`QLabel`, `Ghost`, `VContainer`, `VCol`, `VRow` (layout wrappers — note these three layout names are V-prefixed but implemented by Quick), `QFrame`, `QPhoneInput`, `QOtp`, `QMenu`, `QAnimation`, `QVideo`, `QMap`, `QRichText`, `QRichContent`, `QImgZoom`, `QLightBox`, `QDocumentViewer`, `QReCaptcha`, `QTableCell`, `QTutorial`, `QAppointmentCalendar`, `GroupBox`, `InfiniteScroll`, `LiveConnection`, `Tooltip`, `CustomAvatarComp`, `VInlineDatepicker`, `VInlineTimePicker`, `VPdfFileViewer`, `VSubElement`, `GoldenLayout`.
-
-## 4. Vuetify components (V-prefixed)
-
-See [component-index.json](component-index.json) `vuetify` array for the full list (80+). Common: `VBtn`, `VCard`, `VTextField`, `VTextarea`, `VSelect`, `VCombobox`, `VAutocomplete`, `VCheckbox`, `VSwitch`, `VRadio`/`VRadioGroup`, `VSlider`/`VRangeSlider`, `VDataTable`, `VDataIterator`, `VDialog`, `VIcon`, `VImg`, `VChip`, `VAlert`, `VSnackbar`, `VTabs`/`VTab`/`VTabItem`, `VStepper*`, `VExpansionPanel*`, `VPagination`, `VBreadcrumbs`, `VDivider`, `VAvatar`, `VBadge`, `VProgressCircular`/`VProgressLinear`, `VCarousel`/`VCarouselItem`, `VSkeletonLoader`, `VNavigationDrawer`, `VAppBar`, `VToolbar`, `VFooter`, `VSheet`, `VList*`, `VMenu`, `VTooltip`, `VDatePicker`/`VTimePicker`, `VFileInput`, `VRating`, `VSparkline`, `VTreeview`, `VForm`.
-
-## 5. Special Quick props injected on every component
-
-These are handled by the rendering layer, not plain Vuetify props:
-
-| Prop | `T` | Meaning |
-|------|-----|---------|
-| `ID` | `prop` | required unique runtime id; reference as `components.<ID>`. `_Editor.eID` is a separate unique editor id (equal to ID when auto-generated, may differ after rename — not required to match) |
-| `visible` | `prop` | show/hide (injected getter/setter; simple equality expressions allowed) |
-| `Render` | `prop` | if falsey, the component is not rendered at all (`Render:true` + `eager:true` to pre-build dialog contents) |
-| `qValue` | `prop` | Quick value binding; normalized to Vuetify's `value` at render. Use for inputs and to open/close dialogs (`components.dlg.qValue=true`). |
-| `class` | `class` | CSS classes (`T:"class"`) |
-
-> Some Vuetify components map `value` to an internal name (`VTextField`/`VExpansionPanels` → `internalValue`; `VSwitch`/`VCheckbox` → `inputValue`). Setting `qValue` handles this for you — prefer `qValue`.
-
-## 6. Per-component criticals (verified against runtime + real files)
-
-### `QLabel` — text is a PROP
-```json
-{ "T": "QLabel", "P": {
-    "ID": { "H": "lblTitle", "T": "prop" },
-    "text": { "H": "'Page Title'", "T": "prop" } },
-  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
-```
-`text` uses `T: "prop"`. `HL` defaults to `QS`, so localized/expression text works directly: `"H": "LR('title')"`. Do **not** use `T: "text"` for QLabel.
-
-### `VIcon` — icon name is `text` with PType `"text"` ⚠️
-```json
-{ "T": "VIcon", "P": {
-    "ID": { "H": "icHome", "T": "prop" },
-    "text": { "H": "'mdi-home'", "T": "text" } },
-  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icHome" } }
-```
-The icon name goes in `text` with **`T: "text"`** (verified in real files, e.g. `VDataTableIconExample.qjson`). PType `text` renders as slot content, which Vuetify reads as the icon. (This corrects older docs that said `T:"prop"`.)
-
-### `VBtn`
-- No text prop — put a child `QLabel`/`VIcon`/`VImg` in the `default` slot.
-- Flat style: `depressed:true`, `elevation:0`.
-
-### `VCard`
-- Flat style: `elevation:0`. Slots: `default` (+ Vuetify `title`/`subtitle`/`actions`).
-
-### `VContainer` / `VRow` / `VCol`
-- Layout wrappers (Quick-implemented) — the grid is `VContainer > VRow > VCol`. Structural props: `VContainer` has `fluid`, `noGutters`, `eager`. `VCol` carries its own `layout-chooser` (nested flex). See [../knowledge/03-layout-and-slots-legacy.md](../knowledge/03-layout-and-slots-legacy.md).
-- **Column width:** `c:col-N` (1–12) in the `VCol`'s `O.layout.dOpt` + the matching `col-N` in the compiled `O.layout.class` (deterministic; `P.cols` alone is not) — see [layout-system.md](layout-system.md).
-- **Do NOT rely on `P.cols` alone** — it is unreliable across editor/runtime. Use `c:col-N` in `dOpt` with the synced class.
-- Flex direction/align/justify come from `dOpt` tokens (`fd:`/`a:`/`j:`) on the node, mirrored into the compiled `class`.
-
-### `VTextField` / inputs
-- `dense:true`, `outlined:true`, usually `hideDetails:true`.
-- Masking via `format` (`T:"attr"`): e.g. `number`, `email`, `iban`, `turkishMobilePhone`, `creditcard`, `regex`, `alphaNumeric`, ... Validation via `rules` (QScript array of `quick.Quick.validation.*`).
-
-### `VSelect` / `VCombobox` / `VAutocomplete`
-- `items` is QScript: `[{text='A', value=1}]` (use `=`). For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
-
-### `VDataTable`
-- `headers` and static `items` are **props** (QScript `=` literals); dynamic rows assigned in a callback (`components.tbl.items = rows;`).
-- Custom cells: scoped slot keyed `item.<columnValue>`, `cType:"scopedSlot"`; `item` is available in child bindings.
-- `click:row` params: `"P": "index:any,row:any"` — `index` is the row data.
-- `itemsPerPage` commonly `10`.
-
-### `VDialog`
-- Open/close: `components.<id>.qValue = true/false`.
-- Add `Render:true` + `eager:true` to access inner components before opening.
-- Non-persistent dialogs: handle `click:outside` to set `qValue=false`.
-
-### `VPagination`
-- `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
-
-### `VChip`
-- `color`: for per-row variation use static colors + sibling toggling with `visible` (so rows aren't blocked on conditional color expressions). Allowed: `default|primary|secondary|accent|success|error|info|warning`.
-
-## 7. Valid props, events & style params per component
-The exhaustive, authoritative per-component contract is in [component-contracts.json](component-contracts.json). For each prop it gives:
-- `pType` — `prop` / `class` / `text` / `attr` (the qjson kind)
-- `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
-- `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
-- `default` — the editor default
-
-And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Generated by merging the editor PIM (`ComponentPims.ts` → prop existence + PType + event names), `componentList.js` (`componentOptions` → value type + options + default), and `eventParamDict.ts` (per-event params). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.
-
-**Style params** live in [component-styles.json](component-styles.json) — per `T`, the Style-tab (`S`) params the component supports, each with value `type` and editor `default`. Read it before writing `S` so you only set supported params (generation guidance; not hard-validated, since the editor expands composite border/shadow/font widgets into extra sub-params).
-
-## 8. Editor names vs runtime names
-
-The web editor may present friendlier names (e.g. "Text/Label" for `QLabel`, "Button" for `VBtn`). When **authoring the `T` field**, always use the runtime name from [component-index.json](component-index.json). When unsure whether a `T` is valid, check that file.

package/dist/studio-cli/src/.ai-kit/reference/component-catalog.md

@@ -1,135 +0,0 @@
-# Component Catalog — Authoritative `T` Names & Contracts (`S` system)
-
-> **Style system: `S` (new).** For `S`-system pages only — a new page, or one whose root-level `opt.V >= 2.0`. Component identity (`T` names, props, events) is the same in both eras; only the `VContainer`/`VRow`/`VCol` styling note below is `S`-specific. Editing a **legacy** page (`opt.V` missing or `< 2.0`)? Use [component-catalog-legacy.md](component-catalog-legacy.md) instead.
->
-> Source of truth: the Quick runtime component registry (`packages/websdk/src/components/providers/VuetifyComponents.ts`, `LocalComponents.ts`, `ChartComponents.ts`, `common/shrimp/constants/knownComps.ts`). The machine-readable list lives in [component-index.json](component-index.json). Vuetify components follow Vuetify 2 prop/event/slot semantics unless noted.
-
-## 1. Lifecycle / system (non-visual or embedding)
-
-| `T` | Role |
-|-----|------|
-| `Messaging` | Page event hub. Holds lifecycle hooks (`PreRender`, `EndRender`, `PostRender`, `Restored`) and custom events. Prop `masterPath`; can declare `ExternalProps`/`ExternalEvents`. `O.cType: "child"`. |
-| `CustomComponent` | Embeds another `.qjson` via prop `QJsonPath`; cascades `readonly`/`disabled` to children. Two distinct usages — see § 6 below. |
-| `RenderingComponent` | Root embedder for a qjson view (props `QJsonPath`, `readonly`, `disabled`). |
-| `Ghost` | Empty placeholder div; used as a structural child / insertion anchor. |
-
-## 2. Charts (Chart.js) — only three exist
-
-| `T` | Notes |
-|-----|-------|
-| `Bar` | vertical/horizontal bars (`indexAxis: 'x'|'y'`) |
-| `Line` | has `fill`, `tension`, point styling |
-| `Doughnut` | `cutoutPercentage: 0` renders a **pie** shape |
-
-> **There is no `Pie` runtime component.** The chart library registers exactly `{ Doughnut, Bar, Line }`. `QPieChart` is a mobile-only placeholder. Use `Doughnut` for pie charts.
-
-Chart prop vocabulary: `labels` (array of axis/segment labels), `data` (number array), `label` (singular dataset name), `backgroundColor`/`borderColor` (array or string), `borderWidth`, `width`/`height`, axis (`xDisplay`/`yDisplay`), legend (`legendDisplay`/`legendPosition`), data labels (`labelDisplay`, ...). Charts have **no `visible` prop** — wrap in a `VCol` and toggle that. Runtime updates: mutate `components.<id>.data` then `(<any>components.<id>).update()`.
-
-## 3. Quick-native components
-
-`QLabel`, `Ghost`, `VContainer`, `VCol`, `VRow` (layout wrappers — note these three layout names are V-prefixed but implemented by Quick), `QFrame`, `QPhoneInput`, `QOtp`, `QMenu`, `QAnimation`, `QVideo`, `QMap`, `QRichText`, `QRichContent`, `QImgZoom`, `QLightBox`, `QDocumentViewer`, `QReCaptcha`, `QTableCell`, `QTutorial`, `QAppointmentCalendar`, `GroupBox`, `InfiniteScroll`, `LiveConnection`, `Tooltip`, `CustomAvatarComp`, `VInlineDatepicker`, `VInlineTimePicker`, `VPdfFileViewer`, `VSubElement`, `GoldenLayout`.
-
-## 4. Vuetify components (V-prefixed)
-
-See [component-index.json](component-index.json) `vuetify` array for the full list (80+). Common: `VBtn`, `VCard`, `VTextField`, `VTextarea`, `VSelect`, `VCombobox`, `VAutocomplete`, `VCheckbox`, `VSwitch`, `VRadio`/`VRadioGroup`, `VSlider`/`VRangeSlider`, `VDataTable`, `VDataIterator`, `VDialog`, `VIcon`, `VImg`, `VChip`, `VAlert`, `VSnackbar`, `VTabs`/`VTab`/`VTabItem`, `VStepper*`, `VExpansionPanel*`, `VPagination`, `VBreadcrumbs`, `VDivider`, `VAvatar`, `VBadge`, `VProgressCircular`/`VProgressLinear`, `VCarousel`/`VCarouselItem`, `VSkeletonLoader`, `VNavigationDrawer`, `VAppBar`, `VToolbar`, `VFooter`, `VSheet`, `VList*`, `VMenu`, `VTooltip`, `VDatePicker`/`VTimePicker`, `VFileInput`, `VRating`, `VSparkline`, `VTreeview`, `VForm`.
-
-## 5. Special Quick props injected on every component
-
-These are handled by the rendering layer, not plain Vuetify props:
-
-| Prop | `T` | Meaning |
-|------|-----|---------|
-| `ID` | `prop` | required unique runtime id; reference as `components.<ID>`. `_Editor.eID` is a separate unique editor id (equal to ID when auto-generated, may differ after rename — not required to match) |
-| `visible` | `prop` | show/hide (injected getter/setter; simple equality expressions allowed) |
-| `Render` | `prop` | if falsey, the component is not rendered at all (`Render:true` + `eager:true` to pre-build dialog contents) |
-| `qValue` | `prop` | Quick value binding; normalized to Vuetify's `value` at render. Use for inputs and to open/close dialogs (`components.dlg.qValue=true`). |
-| `class` | `class` | CSS classes (`T:"class"`) |
-
-> Some Vuetify components map `value` to an internal name (`VTextField`/`VExpansionPanels` → `internalValue`; `VSwitch`/`VCheckbox` → `inputValue`). Setting `qValue` handles this for you — prefer `qValue`.
-
-## 6. Per-component criticals (verified against runtime + real files)
-
-### `CustomComponent` — two distinct usages
-
-**A. Block Component (UI embedding)** — the standard way to embed another page as a UI block. Placed at `pJson` root level (not inside VContainer). Minimal node — no Ghost, no `dynProps`.
-```json
-{ "T": "CustomComponent", "P": {
-    "ID": { "H": "blockMyPage", "T": "prop" },
-    "QJsonPath": { "H": "'<<qjson:path/to/page>>'", "T": "prop" } },
-  "E": {}, "C": {}, "O": {}, "_Editor": { "eID": "blockMyPage" } }
-```
-The embedded page must itself be a block component in Studio: if its frontmatter lacks `blockComponent: true`, run `studio convertToBlock <embedded-file>` (details: [knowledge/05-components.md](../knowledge/05-components.md#block-component-embedding-another-qjson-page)). Does not apply to usage B.
-
-**B. Service Caller (project-specific proxy)** — only if the project provides a dedicated service-caller qjson. Has event handlers, a `Ghost` child, and `O: { cType:"child", dynProps:true }`. See [06-services.md](../knowledge/06-services.md) Pattern B.
-
-**`QJsonPath` format:** always `'<<qjson:path>>'` where `path` is the page's project-relative path without extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:folder/page-name>>` for a nested one). Studio stores model IDs internally; `studio pull` converts ID→path and `studio push` converts path→ID automatically — never write a raw model ID here.
-
-### `QLabel` — text is a PROP
-```json
-{ "T": "QLabel", "P": {
-    "ID": { "H": "lblTitle", "T": "prop" },
-    "text": { "H": "'Page Title'", "T": "prop" } },
-  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
-```
-`text` uses `T: "prop"`. `HL` defaults to `QS`, so localized/expression text works directly: `"H": "LR('title')"`. Do **not** use `T: "text"` for QLabel.
-
-### `VIcon` — icon name is `text` with PType `"text"` ⚠️
-```json
-{ "T": "VIcon", "P": {
-    "ID": { "H": "icHome", "T": "prop" },
-    "text": { "H": "'mdi-home'", "T": "text" } },
-  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icHome" } }
-```
-The icon name goes in `text` with **`T: "text"`** (verified in real files, e.g. `VDataTableIconExample.qjson`). PType `text` renders as slot content, which Vuetify reads as the icon. (This corrects older docs that said `T:"prop"`.)
-
-### `VBtn`
-- No text prop — put a child `QLabel`/`VIcon`/`VImg` in the `default` slot.
-- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation`/`depressed` props).
-
-### `VCard`
-- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation` prop). Slots: `default` (+ Vuetify `title`/`subtitle`/`actions`).
-
-### `VContainer` / `VRow` / `VCol`
-- Layout wrappers (Quick-implemented) — the grid is `VContainer > VRow > VCol`. Structural props: `VContainer` has `fluid`, `eager`. `VCol` is the one component whose flex axis (`flexDirection`/`alignItems`/`justifyContent`) is controllable as a real style param — see [../knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md).
-- **Column width:** `S.col` on the `VCol` (1–12, range-keyed, e.g. `"xs-xl": {"col":"3"}`) — see [styling-system.md](styling-system.md).
-- **Do NOT use Vuetify responsive column props** (`VCol.cols`/`.sm`/`.md`/`.lg`/`.xl`): they set width via the Vuetify prop system, which `S` does not read. Use `S.col` + resolution ranges.
-- **Do NOT use `VRow.justify`/`VRow.align` props** as design intent — `VRow` exposes no `justifyContent`/`alignItems` `S` param; put alignment on a `VCol` (which supports those params), or fall back to the Web-only `class` last resort.
-
-### `VTextField` / inputs
-- `dense:true`, `outlined:true`, usually `hideDetails:true`.
-- Masking via `format` (`T:"attr"`): e.g. `number`, `email`, `iban`, `turkishMobilePhone`, `creditcard`, `regex`, `alphaNumeric`, ... Validation via `rules` (QScript array of `quick.Quick.validation.*`).
-
-### `VSelect` / `VCombobox` / `VAutocomplete`
-- `items` is QScript: `[{text='A', value=1}]` (use `=`). For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
-
-### `VDataTable`
-- `headers` and static `items` are **props** (QScript `=` literals); dynamic rows assigned in a callback (`components.tbl.items = rows;`).
-- Custom cells: scoped slot keyed `item.<columnValue>`, `cType:"scopedSlot"`; `item` is available in child bindings.
-- `click:row` params: `"P": "index:any,row:any"` — `index` is the row data.
-- `itemsPerPage` commonly `10`.
-
-### `VDialog`
-- Open/close: `components.<id>.qValue = true/false`.
-- Add `Render:true` + `eager:true` to access inner components before opening.
-- Non-persistent dialogs: handle `click:outside` to set `qValue=false`.
-
-### `VPagination`
-- `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
-
-### `VChip`
-- `color`: for per-row variation use static colors + sibling toggling with `visible` (so rows aren't blocked on conditional color expressions). Allowed: `default|primary|secondary|accent|success|error|info|warning`.
-
-## 7. Valid props, events & style params per component
-The exhaustive, authoritative per-component contract is in [component-contracts.json](component-contracts.json). For each prop it gives:
-- `pType` — `prop` / `class` / `text` / `attr` (the qjson kind)
-- `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
-- `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
-- `default` — the editor default
-
-And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Generated by merging the editor PIM (`ComponentPims.ts` → prop existence + PType + event names), `componentList.js` (`componentOptions` → value type + options + default), and `eventParamDict.ts` (per-event params). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.
-
-**Style params** live in [component-styles.json](component-styles.json) — per `T`, the Style-tab (`S`) params the component supports, each with value `type` and editor `default`. Read it before writing `S` so you only set supported params (generation guidance; not hard-validated, since the editor expands composite border/shadow/font widgets into extra sub-params).
-
-## 8. Editor names vs runtime names
-
-The web editor may present friendlier names (e.g. "Text/Label" for `QLabel`, "Button" for `VBtn`). When **authoring the `T` field**, always use the runtime name from [component-index.json](component-index.json). When unsure whether a `T` is valid, check that file.