@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/modules/mcp/helpers/guide.js

@@ -0,0 +1,449 @@
+//#region src/modules/mcp/helpers/guide.ts
+var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is kebab-case and ATOMIC (shorthands like border/padding expanded; compound ones like flex/background/font rejected — use longhands); style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers).";
+var guideQuickstart = `# Plitzi AI MCP — quickstart
+This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
+
+A space is **two schemas you edit together in one atomic \`plitzi_apply\` batch**: the **element schema** (tree of
+pages/elements) and the **style schema** (definitions = CSS classes, tokens, theme). To style an element: write a
+**definition** and attach it via the element's \`style.base\` in the same batch.
+
+**Workflow:** (1) you already have this primer (guide + types + css + page/style summaries). (2) \`plitzi_search\`
+with \`include:"detail"\` to find elements — each hit carries its \`uri\`, \`stateVersion\` and full style, so no
+per-element read. (3) \`plitzi_apply\` with \`dryRun:true\` to preview. (4) \`plitzi_apply\` to persist, passing
+\`expectedResourceVersions\` (uri → the stateVersion you read) for every resource you change — omitting it lets a
+concurrent edit be lost. Use \`patchElement\`/\`patchDefinition\` to change only some props/CSS (upsert replaces all).
+
+**Refs & wiring:** a ref is the semantic \`idRef\` (letters, numbers, hyphens and underscores, **starting with a
+letter — no dots**) or the raw id. The idRef is the runtime wiring key: a provider's source is \`<type>_<idRef>\`, and
+interactions target by it. A dot would split that path; an **underscore is fine** — the first \`_\` separates the type
+from the idRef (element types have none), so \`list_food_item\` reads unambiguously as type \`list\`, idRef \`food_item\`.
+
+**Styling:** CSS keys are **kebab-case** (\`background-color\`); \`var(--token)\` for style vars, \`{{name}}\` for schema
+vars. Shorthands \`border\`/\`padding\`/\`margin\`/\`gap\` are expanded for you. Write **atomically — no compound
+shorthands** (\`flex\`, \`background\`, \`font\`, \`transition\`, \`grid\` are rejected/warned): use their longhands, and
+express flex layout as \`display: flex\` + \`flex-direction\`/\`align-items\`/… Mind a type's \`defaultStyle\` (\`text\`
+is \`display: inline\`). Global styles (\`button {…}\`) and id styles (\`#id\`) have their own ops.
+
+**Data bindings** (\`upsertBinding\`, category attributes|style|initialState): connect a \`source\` to a \`to\` field.
+A source \`<type>_<idRef>\` is scoped to the provider's **DESCENDANTS only** — bind inside the provider's subtree
+(module sources state/space/navigation/auth/collection are global). \`apiContainer.mockData\` is builder-only; set a
+real \`query\` for production. \`transformers: [{action, params}]\` post-process the value — use exact action names
+from \`plitzi://data-sources\`; \`twigTemplate\` formats it (the value is \`{{source}}\`, not \`{{value}}\`). \`when\` is
+a QueryBuilder RuleGroup gating the binding.
+
+**Interactions** (\`upsertInteractionFlow\`): a \`trigger\` node first, then callbacks/utilities **in order** (links
+computed for you). Node types: \`callback\` (an element's own callback — \`elementId\` is that element), \`globalCallback\`
+(a source module — omit \`elementId\`, the MCP sets it), \`utility\` (no element). Element \`setState\`
+(category/key/value/revertOnFinish) ≠ global \`setState\` (source \`state\`, key/type/value). To turn a step off use
+\`patchInteractionNode {enabled:false}\` — \`deleteInteraction\` removes it (destructive; confirm first). Any param
+**value** can be a binding token \`{{ source }}\` (e.g. notification \`content: "{{ list_<idRef>.item.name }}"\`).
+
+**Pages & navigation:** \`upsertPage\` — always set a **relative** \`slug\` (no leading \`/\`; the runtime and folder
+slugs prepend the path). A \`:name\` segment (\`"posts/:postId"\`) is a route param, readable as \`{{name}}\` and as the
+source \`navigation.routeParams.name\` → build dynamic pages this way. To move between pages **prefer the \`Link\`
+element** (a container: \`mode\` "page"/"internal"/"external") over a \`navigate\` interaction.
+
+**Touched resources must be malformation-free.** Editing an element/definition also checks its CURRENT stored content
+and BLOCKS the save on any \`Pre-existing malformation in <resource>\` error (a broken transformer, malformed node,
+invalid CSS) — even parts you did not touch. These are NOT from your change (the message says so); fix them in the
+SAME batch and re-apply (the check runs on the result, so the fix unblocks it). \`Pre-existing issue\` warnings advise
+but do not block.
+
+Read \`plitzi://guide\` before anything above is unclear.
+`;
+var guideText = `# Plitzi AI MCP — usage guide
+
+A Plitzi space is **two separate schemas** you edit together:
+- **Element schema** — the tree of pages and elements (their type, label, props, and which style classes they use).
+- **Style schema** — reusable **definitions** (CSS classes), design tokens (variables), theme.
+
+They are stored and persisted independently, but a single \`plitzi_apply\` batch may touch **both atomically**.
+To style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**
+it via the element's \`style.base\` (element schema). Example — "rename button X to PEPE and make it red":
+\`\`\`json
+{ "operations": [
+  { "type": "upsertDefinition", "ref": "btn-x", "desktop": { "color": "red" } },
+  { "type": "upsertElement", "pageRef": "home",
+    "element": { "ref": "X", "type": "button", "label": "PEPE", "style": { "base": ["btn-x"] } } }
+] }
+\`\`\`
+
+Reads are cheap by design — treat them like a filesystem: **list** to navigate, **read one item** for detail.
+Never download a whole tree you do not need.
+
+## Resources (read)
+- \`plitzi://primer/{env}\` — **cold-start bundle**: guide + types + css-properties + page/definition/variable
+  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only — open a
+  page skeleton or element for its tree/detail.
+- \`plitzi://guide\` — this guide.
+- \`plitzi://types\` — element types **observed in this space** (ground truth): props, slots, subTypes, plus each
+  type's \`label\`, \`description\` (what it is FOR) and \`category\`, and a \`source\` (\`builtin\` | \`plugin\` | \`unknown\`).
+  Read the descriptions to pick the right type — e.g. \`apiContainer\` fetches backend data into the frontend,
+  \`link\` navigates between pages, \`list\` repeats a template over a data array. \`plugin\` types are custom elements.
+- \`plitzi://css-properties\` — valid kebab-case CSS property keys.
+- \`plitzi://schema/{env}/pages\` — page **summaries** (ref, label, elementCount, folder). No element trees.
+- \`plitzi://folders/{env}\` — page **folders** (the sidebar tree): ref, name, slug, parentId. \`/{ref}\` for one.
+- \`plitzi://schema/{env}/pages/{ref}\` — one page as a **skeleton tree**: each node is \`ref/type/label\` **plus the
+  style classes it attaches** (\`base\`, and \`slots\` for non-base slots) — names only, no CSS. So you can map every
+  element to its class in a single page read, without opening each element just to learn which class it uses.
+- \`plitzi://schema/{env}/pages/{ref}/styles\` — **every style the page uses in one read**: the class definitions its
+  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.
+  Reach for this to recolor/restyle a whole page — it needs no shared class-name prefix and no per-element reads.
+- \`plitzi://schema/{env}/elements/{ref}\` — one element in **full detail** (props, style, parentRef, childRefs).
+  Its \`resolvedStyle\` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you
+  can see and edit its style without a separate definition read. Its \`globalStyles\` lists the **global element
+  selectors** that also affect it (the CSS equivalent of \`button { … }\`, keyed by the type they target) — every
+  element of that type inherits them. Edit a global only through the global-style tools (never per element). If the
+  element carries a DOM \`id\` that an id rule matches, its \`idStyle\` (\`#id\`) is inlined too.
+- \`plitzi://definitions/{env}\` — the **names** of every style definition.
+- \`plitzi://definitions/{env}/{ref}\` — one definition's CSS.
+- \`plitzi://global-styles/{env}\` — element **types** that have a site-wide global style. \`/{componentType}\` for one.
+- \`plitzi://id-styles/{env}\` — DOM **ids** that have an id rule (\`#id\`) targeting a single element. \`/{targetId}\` for one.
+- \`plitzi://style-variables/{env}\` — design tokens by category. \`/{category}\` for one.
+- \`plitzi://schema-variables/{env}\` — space-level values referenced in props as \`{{name}}\`.
+- \`plitzi://settings/{env}\` — space-level settings: the global \`customCss\` and the state/auth (user-provider) config.
+- \`plitzi://interactions/{env}\` — interaction **actions** observed in this space (grouped by node type): the
+  vocabulary for interaction flows.
+- \`plitzi://data-sources/{env}\` — data-source **paths** and binding targets observed in this space: the
+  vocabulary for data bindings.
+
+The style resources also answer under the \`plitzi://schema/{env}/…\` root as aliases — \`plitzi://schema/{env}/definitions/{ref}\`, \`plitzi://schema/{env}/style-variables/{category}\`, \`plitzi://schema/{env}/schema-variables\` — but prefer the ready-made \`uri\` from search / a write response over hand-building either form.
+
+Data resources return \`{ stateVersion, data }\`. Keep \`stateVersion\` for optimistic concurrency.
+
+**Reuse what you already know — don't re-scan an unchanged page.** A page read (\`plitzi://schema/{env}/pages/{ref}\`)
+returns a \`stateVersion\` that is an **aggregate of the whole page**: it changes if and only if some element on the
+page changed. Its skeleton \`tree\` also carries a \`stateVersion\` **per node**, identical to the one a direct element
+read or search hit returns for that element. So when you come back to a page you already inspected:
+1. Re-read just the page skeleton and compare its top-level \`stateVersion\` to the one you held. **Same → nothing
+   changed since your read; skip re-reading and re-searching the tree** and act on what you already know.
+2. If it differs, diff the per-node \`stateVersion\`s against the ones you cached and \`plitzi_read\` **only the nodes
+   that changed** — never re-search or re-read the whole tree.
+
+This is a **read-time** shortcut, not a safety guarantee. **Other agents/sub-agents may edit the same space
+concurrently**, so a version you cached can go stale between your read and your write. Never skip the write-time
+check below on the strength of a cached hash — the guarantee that no concurrent edit is lost comes only from
+\`expectedResourceVersions\` on \`plitzi_apply\`, which re-validates against the live data at write time.
+
+## Navigating (files analogy)
+Pages and containers are folders; elements are files. **Prefer \`plitzi_search\` (especially with \`include: "detail"\`)
+over reading elements one by one** — it jumps straight to elements by label/type/attribute and each hit already
+carries the element's \`uri\`, \`stateVersion\`, \`pageUri\`, \`parentRef\` and tree \`path\`, so you can edit it (with
+optimistic concurrency) **without a follow-up read**. \`include: "detail"\` additionally inlines each hit's props/style
+**and** its \`resolvedStyle\` (the CSS behind its classes) — so a search-then-edit is the efficient path and a manual
+element read is the exception. Search also matches **pages** by name/slug (returned under \`pages\`, each with its uri +
+stateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under \`definitions\`.
+When you do hold several refs to open (e.g. from a skeleton), read them together with \`plitzi_read\` rather than one at a time.
+
+## Tools (write)
+- \`plitzi_validate\` — check a batch, returns teachable errors/warnings. Writes nothing. Also reports **pre-existing
+  malformations** in any resource the batch touches (see below).
+- \`plitzi_apply\` — validate → apply → persist atomically. Rejects the whole batch on any error or conflict. Pass
+  \`dryRun: true\` to apply in memory only and get the same result back (changed versions + full element detail)
+  without persisting — inspect it, then re-run without \`dryRun\` to commit.
+- \`plitzi_search\` — find elements (and pages/definitions) across the space.
+- \`plitzi_read\` — read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the
+  ready-made uris from search / a write response; each result is \`{ uri, stateVersion, data }\` or a teachable error,
+  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.
+
+## Readers: resources vs plitzi_search vs plitzi_read (do not confuse them)
+Three ways to read, each for a different moment — pick by what you have in hand:
+- **MCP resources** (the \`plitzi://…\` catalog above) — the **browsable index**. List them to discover what exists, or
+  open one by URI when you are exploring. This is the passive catalog, not a tool.
+- **\`plitzi_search\`** — you know *what* you want but not its **ref/uri** ("the hero button"). Search finds it by
+  label/type/attribute and hands back the uri + stateVersion (and, with \`include:"detail"\`, the full element).
+- **\`plitzi_read\`** — you **already hold one or more uris** (from search or a write response) and want their
+  content in one batch. It is the tool form of opening resources, for when you have the addresses.
+Rule of thumb: **discover → resources**, **find a ref → plitzi_search**, **fetch known uris → plitzi_read**. Never
+hand-build a URI to guess your way to an element — search for it instead.
+
+Write tools return what **changed** (\`{ uri, stateVersion }\`) plus counts, and the **full detail of every element
+they created or updated** — each with its own \`uri\` and \`stateVersion\` (\`elements: [...]\`) so a follow-up edit of
+the same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only
+uri+stateVersion — re-read them if you need their new content. The operation shapes are in each tool's input
+schema (discriminated by \`type\`).
+
+## Addressing
+Refs are the semantic \`idRef\` (e.g. \`"hero-cta"\`) or the element's **raw id** — both resolve. Creating an element
+stores the \`ref\` you chose as its **idRef**.
+
+The idRef is not just an alias — it is the **wiring key the runtime uses**. A provider registers its data source as
+\`<type>_<idRef>\`, so a \`source\` you write against a ref resolves to that element at runtime with no id translation.
+Rules for a **new** ref (both are enforced; a violation fails the batch):
+- Charset \`[A-Za-z0-9_-]\`, **starting with a letter** (e.g. \`"products-api"\`, \`"food_item"\`). A \`.\` would split the
+  \`<type>_<idRef>.<field>\` source path and the interaction target lookup, so **no dots**. An **underscore is
+  allowed**: the FIRST \`_\` separates \`<type>\` from \`<idRef>\` and element types are camelCase with none, so
+  underscores inside the idRef are unambiguous (\`list_food_item\` → type \`list\`, idRef \`food_item\`).
+- **Unique across the space**; creating a ref that is taken is rejected (address the existing element instead).
+
+An idRef is **optional** on an element — one built in the builder may not have it. The consequence is specific: an
+element without an idRef **publishes no data source** and **holds no interactions**, because the runtime keys
+everything by idRef and the raw id is never a fallback. You do not have to fix this by hand: writing an
+interaction **mints an idRef for you** — the element that hosts the flow, and any element a node targets, is given
+a free \`<type>-<n>\` ref if it lacks one, and the flow is wired to it. A node target you write may be a raw id; it
+is normalised to that element's idRef. (To make an element a data-source **provider** to bind against, give it an
+idRef explicitly with \`patchElement\`, or create it with the \`ref\` you want — a created element stores its ref as
+its idRef.)
+
+**Renaming** an idRef moves the wiring key: every binding source and interaction target across the space that
+pointed at the old name is repointed with it, so the element stays wired. You do not have to rewrite them.
+
+## Styling (crosses both schemas)
+- **Mind the type's intrinsic default style.** A type renders with a base CSS *before* any class is attached — read
+  it from \`defaultStyle\` on the type in \`plitzi://types\` (the primer includes it). Do not assume \`display: block\`:
+  \`text\`, for one, defaults to \`display: inline\`, so margins/width/vertical padding behave differently. If you need
+  block/flex layout on such an element, set \`display\` explicitly in your definition rather than relying on a default.
+- **Images: preserve aspect ratio.** Setting only \`width\` and \`height\` (or forcing both) distorts an image. Change
+  one dimension and let the other be \`auto\`, or set \`aspect-ratio\` with \`object-fit: cover\`/\`contain\`, so the
+  image scales without stretching.
+- **Font size and line height move together.** When you change \`font-size\`, set \`line-height\` in the same edit
+  (prefer a unitless ratio like \`1.5\`, which tracks the font size). Changing one without the other leaves cramped or
+  loosely-spaced text — they are a joint change, not two separate ones.
+- A definition lives in the **style schema**; an element's \`style.base\` (element schema) is the link that applies
+  it. Styling an element = upsertDefinition + upsertElement with that ref in \`style.base\`, in one batch.
+- CSS keys are **kebab-case** (\`background-color\`). camelCase is rejected — read \`plitzi://css-properties\`.
+- Common **shorthands are accepted** and expanded for you: \`border\`, \`border-{side}\`, \`border-radius\`,
+  \`padding\`, \`margin\`, \`inset\`, \`gap\` (they persist as their longhand keys).
+- **Write CSS atomically — no multi-value compound shorthands.** Plitzi stores each property on its own so a
+  breakpoint/state/variant can override just that one, so \`flex\`, \`background\`, \`font\`, \`transition\`,
+  \`animation\`, \`grid\`, \`place-*\`, \`outline\`, \`columns\` are **rejected** (or warned) — use their longhands
+  instead: \`background\` → \`background-color\`/\`background-image\`/…, \`font\` → \`font-size\`/\`font-weight\`/
+  \`line-height\`, \`flex: 1\` → \`flex-grow\`/\`flex-shrink\`/\`flex-basis\`. **Flex layout is not a \`flex\` value**: set
+  \`display: flex\` **plus** \`flex-direction\`, \`align-items\`, \`justify-content\` as separate properties.
+- CSS is grouped by breakpoint: \`desktop\`, \`tablet\`, \`mobile\`.
+- Reference a style variable in CSS as \`var(--name)\`; a schema variable in a prop as \`{{name}}\`.
+- \`element.style.base\` is a **list** of definition refs; other slots go under \`element.style.slots\`.
+- **An element can attach SEVERAL classes at once, and they all apply.** \`style.base\` holds a list, and each
+  non-base slot holds its own — every attached definition contributes CSS, and they **cascade** (a later class, then a
+  global/id rule, overrides an earlier one on the same property). So when a style looks wrong, the culprit may be
+  ANY attached class, not the one you just edited: read the element's \`resolvedStyle\` (it inlines the CSS of every
+  class it attaches, keyed by ref) together with its \`globalStyles\`/\`idStyle\` and the type's \`defaultStyle\`, and
+  fix the class that actually sets the property — do not just pile another class on top.
+- **Three kinds of style live in the style schema — do not confuse them:**
+  - **Definitions** = reusable CSS **classes** (\`upsertDefinition\`/\`patchDefinition\`/\`deleteDefinition\`, keyed by a
+    class \`ref\`). Attach one to an element via \`style.base\` to style **that** element (and anything else that opts in).
+    This is the **default** way to style one element.
+  - **Global styles** = the CSS equivalent of a bare element selector like \`button { … }\`
+    (\`upsertGlobalStyle\`/\`patchGlobalStyle\`/\`deleteGlobalStyle\`, keyed by \`componentType\`). They style **every**
+    element of that type at once. Use these for site-wide intent — e.g. "all buttons rounded":
+    \`{ "type": "upsertGlobalStyle", "componentType": "button", "desktop": { "border-radius": "9999px" } }\`.
+  - **Id styles** = the CSS equivalent of an id selector like \`#hero { … }\`
+    (\`upsertIdStyle\`/\`patchIdStyle\`/\`deleteIdStyle\`, keyed by \`targetId\`). They style the **single** element whose
+    DOM \`id\` attribute equals \`targetId\` — so the element must carry that \`id\` (set it in its props). Prefer a
+    **definition** for one element; reach for an id style only when a specific, uniquely-identified node must be
+    targeted by id: \`{ "type": "upsertIdStyle", "targetId": "hero", "desktop": { "min-height": "100vh" } }\`.
+  - The three share one name space, so an op refuses a name held by another kind (guards against a typo silently
+    rewriting every element of a type, or converting a class into an id rule). If refused, you targeted the wrong
+    kind — switch tools or rename.
+
+## Style variants & element state
+A **variant** is a named CSS override on a definition (e.g. a button class with a \`primary\` variant). It takes two
+steps across the two schemas:
+- **Declare** the variant CSS on the class (style schema): \`upsertDefinition\`/\`patchDefinition\` with
+  \`variants: { "primary": { "desktop": { "background-color": "#111" } } }\` (per slot under \`slots.<slot>.variants\`).
+- **Apply** it to an element (element schema): \`initialState.styleVariant\` =
+  \`{ "<class-ref>": { "base": "primary" } }\` — a slot name instead of \`base\` targets that slot; an array applies
+  several. Set it via \`upsertElement\`/\`patchElement\`.
+An element read reports \`availableVariants\` (which variant each attached class offers) and the element's current
+\`initialState\`, so you can see a button **has** a \`primary\` variant and whether it uses it. If the user asks for a
+variant that does not exist yet, **create it (upsertDefinition variants) and apply it in the same batch**.
+- \`initialState.visibility\` (boolean) sets whether the element starts shown or hidden.
+
+## Data bindings
+Connect a data **source** to an element field. A binding is \`{ to, source, transformers?, when?, enabled? }\` grouped
+by **category**: \`attributes\` (a prop), \`style\` (a style value), \`initialState\` (an initial-state key).
+- \`upsertBinding\` adds one, or replaces the binding already feeding the same \`to\` (or \`id\`).
+- \`patchBinding\` edits an existing one (matched by \`to\`/\`id\`); \`deleteBinding\` removes it.
+Discover valid source paths **and the transformer catalog** in \`plitzi://data-sources/{env}\`. Example — feed an API
+list into a list element:
+\`{ "type": "upsertBinding", "pageRef": "home", "ref": "myList", "category": "attributes",
+  "binding": { "to": "items", "source": "apiContainer_x.data" } }\`.
+
+**Source scope — a source is visible to the provider's DESCENDANTS only.** An element source named
+\`<type>_<idRef>\` (e.g. \`apiContainer_products\`, \`list_food-list\`) is published by that element into the scope of
+its **subtree**, so **only elements INSIDE the provider can bind to it**. Binding a sibling or an unrelated element
+to it resolves to nothing at runtime. So to consume \`apiContainer_products.data\`, the bound element must live under
+that apiContainer; inside a \`list\`, the repeated \`listItem\` and its children read the per-row source
+(\`list_<idRef>.item.<field>\`). Module sources (no \`<type>_<idRef>\` head — \`state\`, \`space\`, \`navigation\`,
+\`auth\`, \`collection\`) are global and bindable anywhere. Binding an element to an element source outside its
+provider's subtree is schema-valid but **broken at runtime** (the source is not in scope), so
+\`plitzi_validate\`/\`plitzi_apply\` treat it as an **error and reject the batch** — move the element under the
+provider, or bind a source that is in scope.
+
+**mockData is builder-only.** An \`apiContainer\`'s \`mockData\` prop feeds sample data **while editing in the
+builder**; the published runtime fetches the real \`query\` instead. Never rely on mockData as the production source —
+set a real \`query\`/\`method\` so the binding has data at runtime.
+
+**\`transformers\` — post-process the value before it reaches the field** (\`source → t₁ → t₂ → field\`). An array of
+\`{ action, params }\`; the runtime runs them in order and resolves each by its \`action\` alone, so an **unknown
+action is silently skipped** and the raw value passes through. Use the **exact** action names from
+\`plitzi://data-sources\` (\`transformers\`). The most common is **\`twigTemplate\`** to format a value — the incoming
+value is the **\`{{source}}\`** token (NOT \`{{value}}\`); \`{{sourceTo}}\` is the field's previous value. Example —
+show a number with units:
+\`{ "type": "upsertBinding", "pageRef": "home", "ref": "food-item-time", "category": "attributes",
+  "binding": { "to": "content", "source": "list_food-list.item.cookTimeMinutes",
+    "transformers": [ { "action": "twigTemplate", "params": { "template": "{{source}} min de cocción" } } ] } }\`.
+Other transformers: \`dateConverter\` (format a date/timestamp), \`capitalize\`, \`stringToArray\` (split on a
+separator), \`arrayMap\` (remap the keys of each object in an array), \`staticValue\`. Transformer \`params\` values are
+strings. Each transformer also takes an optional \`enabled\` flag: set \`"enabled": false\` to keep it in the chain but
+skip it at runtime (defaults to true) — the value passes through untouched, and a disabled transformer is not
+validated.
+
+**\`when\` — gate the binding** with a QueryBuilder RuleGroup: the binding only applies when the guard passes against
+the data source. Shape: \`{ "combinator": "and", "rules": [ { "field": "<path>", "operator": "=", "value": "x" } ] }\`
+(operators: \`=\`, \`!=\`, \`<\`, \`>\`, \`contains\`, \`beginsWith\`, \`empty\`, \`in\`, \`between\`, …; nest RuleGroups for
+and/or). The guard is validated structurally. Example — only bind when a flag is set:
+\`"when": { "combinator": "and", "rules": [ { "field": "status", "operator": "=", "value": "published" } ] }\`.
+
+## Interactions
+An interaction **flow** is a **trigger** (an event like \`onClick\`, \`onPageLoad\`) followed by the callbacks/utilities
+it runs, in order. You pass the steps **in order** and the stored beforeNode/afterNode/flowId links are computed for
+you — never wire them by hand. Each step also has an \`enabled\` flag (see disable vs delete below).
+
+**Node types & \`elementId\`** — a step names which element (or module) provides the callback it runs. Picking the
+**wrong node type for an action** makes the runtime resolve it against nothing, so the step **silently does nothing**:
+- \`trigger\` — the event; belongs to the host element. \`elementId\` defaults to the host.
+- \`callback\` — a callback provided by a **specific element**. \`elementId\` is that element's ref (the flow host by
+  default, or another element to act on); give its ref or raw id and it is normalised to the idRef. Every element
+  registers a built-in **\`setState\`** callback that changes **its own attribute or state**: params
+  \`category\` (\`"attribute"\` — set a prop like \`content\`/\`disabled\` — or \`"state"\` — \`visibility\` or a style
+  selector), \`key\`, \`value\` (a **scalar** whose type follows the target attribute — a real boolean \`true\`/\`false\`
+  for a boolean attribute, a number for a numeric one, otherwise a string), and **\`revertOnFinish\`**. Set
+  \`revertOnFinish: true\` for a **temporary** change (a "loading…" label, disabling a button while it works): it is
+  **undone automatically when the flow finishes**, so you do **NOT** add manual restore steps at the end. This element
+  \`setState\` has **no** \`type\` param (that belongs to the global one below). An element type may also register its
+  own extra callbacks.
+- \`globalCallback\` — a callback provided by a **source module**, NOT by any element: \`addNotification\` (source
+  \`space\`), \`setState\`/\`clearState\` (\`state\`), \`navigate\` (\`navigation\`), \`authLogin\`/\`authLogout\`/
+  \`authRefreshDetails\` (\`auth\`), \`addCollectionRecord\`/\`updateCollectionRecord\`/\`removeCollectionRecord\`
+  (\`collection\`). Its \`elementId\` is the **source module id**, never the host element — a node that stored the host
+  idRef here would resolve to nothing at runtime. **Omit \`elementId\`**: the MCP sets the correct source and fills the
+  builder's **param defaults** (e.g. \`addNotification\` gets \`autoDismiss:true\`, \`autoDismissTimeout:5000\`,
+  \`placement:"top-right"\`, \`appeareance:"success"\`) for any params you leave out. Use **only** the params each
+  callback declares (exact spelling) — for \`addNotification\` the visible text goes in \`content\`; there is **no**
+  \`title\`/\`message\`/\`type\` param, and any unknown key is dropped. See the full param schema for each callback under
+  \`globalCallbacks\` in \`plitzi://interactions/{env}\`.
+- **Two \`setState\`s — do not mix them:** the **element** \`setState\` (nodeType \`callback\`, on an element,
+  category/key/value/revertOnFinish) changes THAT element's attribute/state and is what you want to change a button's
+  label or disabled flag. The **global** \`setState\` (nodeType \`globalCallback\`, source \`state\`, key/type/value)
+  writes \`runtime.state.<key>\`. They share a name but have different node types AND different params.
+- \`utility\` — a built-in utility action (no element/source module); nodeType \`utility\`. Use the **exact** param
+  names: \`delayTime\` waits \`time\` milliseconds (**not** \`delay\`), \`twigTemplate\` (\`returnMode\`, \`template\`),
+  \`webHook\` (\`url\`, \`method\`, …). See \`utilities\` in \`plitzi://interactions/{env}\`.
+
+**A param value can be a data binding.** Any interaction param may hold a \`{{ source }}\` token instead of a literal —
+it resolves at runtime exactly like a prop binding, using the same source grammar (\`<type>_<idRef>.<path>\`, or a
+module source like \`navigation\`/\`state\`). This is how a step reacts to *the data in context*: inside a \`listItem\`,
+a click on a row can show \`addNotification\` with \`content: "{{ list_<idRef>.item.name }}"\` — the clicked row's field.
+The value follows the source's type, so a token is valid even where a param expects a boolean/number. Copy/paste of an
+element repoints these tokens to the new idRefs automatically, along with the element's bindings.
+
+**Navigating between pages — prefer the \`Link\` element over an interaction.** For a plain "go to page X" the right
+tool is a \`link\` element (a container, see *Pages & folders*), not a \`navigate\` interaction step. Use the
+\`navigate\` globalCallback only when the navigation is one step of a larger flow (e.g. submit a form, then go).
+
+Tools:
+- \`upsertInteractionFlow\` — create or replace one flow. The FIRST node must be a \`trigger\`. Pass \`flowId\` (the
+  trigger's node id) to replace an existing flow. Example (elementId omitted — the MCP wires it to \`space\` and fills
+  the notification defaults):
+  \`{ "type": "upsertInteractionFlow", "pageRef": "home", "ref": "cta", "nodes": [
+    { "nodeType": "trigger", "action": "onClick", "title": "Click" },
+    { "nodeType": "globalCallback", "action": "addNotification", "title": "Notify",
+      "params": { "content": "Saved!" } } ] }\`.
+- \`patchInteractionNode\` — change one step in place (by \`nodeId\`); \`params\` merge onto the node.
+
+**Disable vs delete a step — do not confuse them (three different intents):**
+- **Disable / deactivate / turn off a step** (keep it in the flow, just stop it running): \`patchInteractionNode\`
+  with \`{ "enabled": false }\`. Re-enable with \`{ "enabled": true }\`. This is NOT a deletion — the step stays.
+- **Remove one step** from a flow: \`deleteInteraction\` with \`nodeId\` (its neighbors are re-linked).
+- **Remove the whole flow**: \`deleteInteraction\` with \`flowId\` (the trigger node id).
+
+So "deactivate the addNotification step" means \`patchInteractionNode { enabled: false }\` — never delete the step, and
+never delete the flow. \`deleteInteraction\` is **destructive and not undoable**: only use it when the user asked to
+*remove* something, and **confirm with the user before deleting** a step or a flow.
+
+Discover valid actions in \`plitzi://interactions/{env}\`: \`actions\` = observed, \`globalCallbacks\` /
+\`elementCallbacks\` / \`utilities\` = the built-in vocabularies with their full param schema, so you know the exact
+node type and valid params per action. An element read lists its flows as ordered nodes (each with its \`id\` and
+\`enabled\`), so a follow-up patch/delete needs no extra read.
+
+## Pages & folders
+- **Always set a \`slug\` when creating a page** (\`upsertPage\`) — it is the page's URL path and good practice for a
+  clean, stable route (e.g. \`"pricing"\` or \`"posts/:postId"\`). Omit it and the page ref is used as the slug,
+  and \`plitzi_validate\`/\`plitzi_apply\` warn so you remember to set a meaningful one.
+- **A page slug is RELATIVE — do NOT start it with \`/\`.** The runtime prepends the leading slash (and any folder
+  path) itself, so a leading slash doubles it. Write \`"pricing"\`, not \`"/pricing"\`. (upsertPage strips a leading
+  slash for you, but write it relative.)
+- **Dynamic pages — route params.** A slug segment written \`:name\` (e.g. \`"posts/:postId"\`) is a **route param**,
+  exactly like React Router. On that page it is readable **two ways**: as \`{{name}}\` inside a prop, and as the
+  data-binding source **\`navigation.routeParams.name\`** (the \`navigation\` module source, global — bindable
+  anywhere). So a blog is a \`"posts"\` list page plus a \`"posts/:postId"\` detail page whose \`apiContainer\` query
+  binds \`navigation.routeParams.postId\` to fetch that one post. (\`navigation.queryParams.<name>\` exposes \`?query=\`
+  string params the same way.)
+- **Navigate with the \`Link\` element, not an interaction.** \`link\` is a **container** — it wraps any children and
+  navigates on click, so it is the default way to move between pages. Its \`mode\`: \`"page"\` links to another space
+  page (set \`href\` to the target page, folder path resolved for you); \`"internal"\` takes a path inside the space and
+  resolves \`{{token}}\` templates in it, so a row's "view" link is \`mode:"internal", href:"posts/{{postId}}"\`;
+  \`"external"\` is a full URL. \`target\` is \`self\`/\`blank\`/\`parent\`/\`top\`. Reach for the \`navigate\` globalCallback
+  only when navigation must be **one step inside a larger interaction flow** (e.g. save, then go) — for a plain link,
+  use \`link\`.
+
+Pages can be grouped into **folders** (the sidebar tree). A folder is \`{ ref, name, slug, parentId? }\`; its \`ref\`
+**is its id** (there is no separate idRef), and that id is what a page and a nested folder reference.
+- **Folder slugs PREPEND to the page URL — this is how nested URLs are built.** The full path is each ancestor
+  folder's slug plus the page slug, joined by \`/\`: a page at slug \`"1-1-1"\` inside \`folder-1\` > \`folder-1-1\`
+  resolves to \`/folder-1/folder-1-1/1-1-1\`. So a folder slug is part of the route; keep folder slugs relative too.
+- Create/rename/move a folder with \`upsertFolder\` (the \`ref\` you pass on create becomes its id — pick a stable one
+  like \`"blog"\`). Nest it under another with \`parentId\` (a folder ref); \`parentId: null\` moves it back to the root.
+- Put a page in a folder with \`upsertPage\`'s \`folder\` (a folder ref). A page's \`folder\` is always either **empty
+  (root)** or an **existing folder id**: \`folder: null\` or \`folder: ""\` moves it to the root, and any other value
+  must resolve to a folder that already exists or is created earlier in the same batch — an unknown folder is
+  rejected, never stored.
+- \`deleteFolder\` removes a folder and **promotes its contents up one level** — its child folders and its pages move
+  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.
+- **Disable a page** with \`upsertPage\`'s \`enabled: false\`; \`enabled: true\` re-enables it (defaults to enabled, and
+  a page read reports its current \`enabled\`). Disabling only affects the **published SDK runtime** — the page stops
+  being routable/accessible to end users. It stays fully **editable here**: you can still read it and apply any op to
+  a disabled page. This does not delete it — \`deletePage\` does.
+
+## Settings
+Space-level configuration lives in \`plitzi://settings/{env}\` and is edited with a single **\`patchSettings\`** op
+(merge — only the fields you pass change):
+- \`customCss\` — **raw global CSS** injected for the whole space. Use it only for genuinely site-wide rules
+  (\`@keyframes\`, \`@font-face\`, resets). To style an element, write a **definition** and attach it — never customCss.
+- \`keepState\` / \`stateStorage\` — persist element state across reloads (\`localStorage\`/\`sessionStorage\`).
+- **User provider / auth**: \`userProvider\` (\`auth0\`|\`basic\`|\`custom\`|\`""\` to disable), \`auth0Domain\`,
+  \`auth0ClientId\`, \`tokenStorage\`, and the \`loginUrl\`/\`userUrl\`/\`refreshUrl\`/\`logoutUrl\` + \`detailsPath\`/
+  \`tokenPath\`/\`expirationTimePath\` mapping. Example — inject a keyframe globally:
+  \`{ "type": "patchSettings", "customCss": "@keyframes spin { to { transform: rotate(360deg); } }" }\`.
+
+## Semantics
+- **props are fully replaced** on \`upsertElement\`: send every prop you want to keep. To change only some props,
+  use **\`patchElement\`** — it merges \`props\`/\`style\` onto the existing element (listed keys change, \`null\` unsets
+  a key, everything else is preserved) and never creates. Combined with \`plitzi_search\` (which returns the ref +
+  stateVersion), a targeted edit is two calls with no read.
+- **definition CSS is fully replaced** on \`upsertDefinition\`: send every property you want to keep. To change only
+  some declarations, use **\`patchDefinition\`** — it merges CSS per breakpoint/state/variant/slot onto the existing
+  definition (listed keys change, \`null\` removes a property, everything else is preserved) and never creates.
+  Example — recolor one definition without resending it: \`{ "type": "patchDefinition", "ref": "btn-x",
+  "desktop": { "background-color": "#111" } }\`.
+- **Atomic batches**: if any operation fails, \`plitzi_apply\` persists nothing.
+- **Every resource you touch must be malformation-free — pre-existing errors block the save.** When your batch edits
+  an element (or a definition/global/id style), the validator also checks the resource's **current stored content**
+  for malformations — a broken transformer action, a malformed interaction node, invalid CSS — even in parts your
+  edit does not touch. Such a finding is reported as a \`Pre-existing malformation in <resource>: …\` **error**, and
+  \`plitzi_apply\` rejects the batch until it is fixed. These are **not caused by your change** (the message says so)
+  — do not be confused; fix them **in the same batch** and re-apply. Because the check runs on the resulting state,
+  including the fix in your batch is exactly what unblocks the save. (Advisory issues — an unobserved source/action
+  name that may still be a valid plugin, a binding target a plugin manifest does not list — come back as
+  \`Pre-existing issue …\` **warnings** and do not block.)
+- **Optimistic concurrency — read before you write, and prove your read is current.** Editing a resource means you
+  read it first, so you hold its \`stateVersion\`. **Always pass \`expectedResourceVersions\`** (URI → the stateVersion
+  you read) for every resource your batch changes. If another agent edited it in the meantime, the live version no
+  longer matches and apply is **rejected with a conflict** — nothing persists. Then re-read the reported resources
+  (their new content + version) and retry on top of the fresh state. This is exactly how a file editor forces a
+  re-read after a stale write: it is what keeps concurrent agents from silently overwriting each other's changes, so
+  never omit it "to save a call".
+`;
+//#endregion
+export { guideQuickstart, guideText, serverInstructions };

package/dist/modules/mcp/helpers/interactions.js

@@ -0,0 +1,123 @@
+import { applyBuiltinCallback } from "../catalogs/builtinCallbacks.js";
+import { applyElementCallback } from "../catalogs/builtinElementCallbacks.js";
+import { applyUtility } from "../catalogs/builtinUtilities.js";
+import { generateObjectId } from "./space.js";
+//#region src/modules/mcp/helpers/interactions.ts
+var BINDING_CATEGORIES = [
+	"attributes",
+	"style",
+	"initialState"
+];
+var NULLISH_ELEMENT_IDS = /* @__PURE__ */ new Set([
+	"undefined",
+	"null",
+	""
+]);
+var isNonEmptyObject = (value) => value !== void 0 && Object.keys(value).length > 0;
+var nodeToAI = (node) => {
+	const ai = {
+		id: node.id,
+		title: node.title,
+		nodeType: node.type,
+		action: node.action
+	};
+	if (isNonEmptyObject(node.params)) ai.params = node.params;
+	if (!node.enabled) ai.enabled = false;
+	if (node.when !== void 0) ai.when = node.when;
+	if (node.elementId && node.elementId !== node.id) ai.elementId = node.elementId;
+	if (isNonEmptyObject(node.preview)) ai.preview = node.preview;
+	return ai;
+};
+var orderFlow = (nodes) => {
+	const byId = new Map(nodes.map((n) => [n.id, n]));
+	const head = nodes.find((n) => !n.beforeNode || !byId.has(n.beforeNode)) ?? nodes[0];
+	const ordered = [];
+	const seen = /* @__PURE__ */ new Set();
+	let current = head;
+	while (current && !seen.has(current.id)) {
+		seen.add(current.id);
+		ordered.push(current);
+		current = current.afterNode ? byId.get(current.afterNode) : void 0;
+	}
+	for (const node of nodes) if (!seen.has(node.id)) ordered.push(node);
+	return ordered;
+};
+var flowsFromInteractions = (interactions) => {
+	if (!interactions || Object.keys(interactions).length === 0) return [];
+	const byFlow = /* @__PURE__ */ new Map();
+	for (const node of Object.values(interactions)) {
+		const key = node.flowId || node.id;
+		const list = byFlow.get(key);
+		if (list) list.push(node);
+		else byFlow.set(key, [node]);
+	}
+	const flows = [];
+	for (const [flowId, nodes] of byFlow) flows.push({
+		flowId,
+		nodes: orderFlow(nodes).map(nodeToAI)
+	});
+	return flows;
+};
+var newNodeId = () => `node_${generateObjectId()}`;
+/** Materialize an ordered list of nodes into the stored linked-node map for ONE flow: assign ids where missing,
+*  set flowId to the trigger id, and recompute beforeNode/afterNode from the order. `ownerId` is the default
+*  source element for callbacks that name none. */
+var materializeFlow = (nodes, ownerId) => {
+	const ids = nodes.map((node) => node.id || newNodeId());
+	const flowId = ids[0];
+	const record = {};
+	nodes.forEach((node, i) => {
+		let params = node.params ?? {};
+		const supplied = NULLISH_ELEMENT_IDS.has(node.elementId ?? "") ? void 0 : node.elementId;
+		let elementId = node.nodeType === "utility" ? null : supplied ?? ownerId;
+		if (node.nodeType === "globalCallback") {
+			const builtin = applyBuiltinCallback(node.action, params);
+			if (builtin.source) {
+				elementId = builtin.source;
+				params = builtin.params;
+			}
+		} else if (node.nodeType === "callback") params = applyElementCallback(node.action, params).params;
+		else if (node.nodeType === "utility") params = applyUtility(node.action, params).params;
+		const interaction = {
+			id: ids[i],
+			title: node.title,
+			type: node.nodeType,
+			action: node.action,
+			params,
+			preview: node.preview ?? {},
+			elementId,
+			beforeNode: i > 0 ? ids[i - 1] : "",
+			afterNode: i < ids.length - 1 ? ids[i + 1] : "",
+			flowId,
+			enabled: node.enabled ?? true
+		};
+		if (node.when !== void 0) interaction.when = node.when;
+		record[ids[i]] = interaction;
+	});
+	return {
+		flowId,
+		record
+	};
+};
+var bindingToAI = (binding) => {
+	const ai = {
+		id: binding.id,
+		to: binding.to,
+		source: binding.source
+	};
+	if (binding.transformers && binding.transformers.length > 0) ai.transformers = binding.transformers;
+	if (binding.when !== void 0) ai.when = binding.when;
+	if (binding.enabled === false) ai.enabled = false;
+	return ai;
+};
+var bindingsToAI = (bindings) => {
+	if (!bindings) return;
+	const result = {};
+	for (const category of BINDING_CATEGORIES) {
+		const list = bindings[category];
+		if (list && list.length > 0) result[category] = list.map(bindingToAI);
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
+//#endregion
+export { BINDING_CATEGORIES, NULLISH_ELEMENT_IDS, bindingToAI, bindingsToAI, flowsFromInteractions, materializeFlow, newNodeId };

package/dist/modules/mcp/helpers/log.js

@@ -0,0 +1,54 @@
+//#region src/modules/mcp/helpers/log.ts
+var MCP_DEBUG = process.env.MCP_DEBUG === "1";
+var summarize = (value, max = 300) => {
+	if (value === void 0) return;
+	let json;
+	try {
+		json = JSON.stringify(value);
+	} catch {
+		return "[unserializable]";
+	}
+	return json.length > max ? `${json.slice(0, max)}…` : json;
+};
+var errorText = (error) => error instanceof Error ? error.message : String(error);
+var consoleRender = (event) => {
+	const kind = event.kind === "tool" ? "tools/call" : "resources/read";
+	const detail = event.argsSummary ? ` ${event.argsSummary}` : "";
+	const status = event.ok ? "ok" : `ERROR ${event.error ?? ""}`;
+	console.log(`[mcp] ${kind} ${event.name}${detail} ${Math.round(event.durationMs)}ms ${status}`);
+};
+var noop = () => void 0;
+var inertLog = {
+	toolCall: noop,
+	resourceRead: noop
+};
+/** Build the request-log sink for one MCP server. Dispatches structured events to the consumer's `logger` when
+*  provided; otherwise renders to the console when MCP_DEBUG=1; otherwise a no-op. */
+var createMcpLog = (logger) => {
+	if (!logger && !MCP_DEBUG) return inertLog;
+	const emit = (event) => {
+		if (logger) logger(event);
+		else consoleRender(event);
+	};
+	return {
+		toolCall: (name, args, ms, error) => emit({
+			kind: "tool",
+			name,
+			durationMs: ms,
+			ok: !error,
+			...error ? { error: errorText(error) } : {},
+			...summarize(args) !== void 0 ? { argsSummary: summarize(args) } : {},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		}),
+		resourceRead: (uri, ms, error) => emit({
+			kind: "resource",
+			name: uri,
+			durationMs: ms,
+			ok: !error,
+			...error ? { error: errorText(error) } : {},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		})
+	};
+};
+//#endregion
+export { createMcpLog };