@plitzi/sdk-mcp 0.38.6 → 0.38.8

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

@@ -2,7 +2,7 @@ import { BUILTIN_TRANSFORMERS, GLOBAL_SOURCES, MOTION_ENTERS, MOTION_LOOPS } fro
 //#region src/modules/mcp/helpers/guide.ts
 var GLOBALS = GLOBAL_SOURCES.map((source) => `\`${source}\``).join(", ");
 var OTHER_TRANSFORMERS = Object.keys(BUILTIN_TRANSFORMERS).filter((action) => action !== "twigTemplate").map((action) => `\`${action}\``).join(", ");
-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 a quickstart of 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. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the 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 elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". 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). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_screenshot view:\"accessibility\" to check. Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
+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 a quickstart of 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. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the 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 elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". 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). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_look (its accessibility outline, the default view) to check. Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
 var widgetsOnlyInstructions = "Plitzi widget server (widgets-only connection). This connection carries NO Plitzi space: nothing can be read or edited in one, and the space tools are not offered here — do not look for them. What it does do is build self-contained UI widgets fully offline, with no backend, account or setup: call plitzi_render to SHOW the user a real rendered layout (card, hero, pricing table, checklist, form, gallery) instead of describing one. Read plitzi://render/guide first — the element/prop table, the style model and a worked example; plitzi://render/types lists every element type you can author (plitzi_read fetches both). To change a widget you already rendered, call plitzi_render again with patch:true and its renderId. If the user wants to edit their real Plitzi space from here, that is a reconnection they make: the integration must be re-authorized and granted a space (the consent screen lists theirs) — you cannot do it from this connection, and no retry will change it.";
 var guideQuickstart = `# Plitzi AI MCP — quickstart
 This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
@@ -51,8 +51,8 @@ a QueryBuilder RuleGroup gating the binding.
 as \`icon\` (\`iconPlacement\` before/after, its class on the \`icon\` slot) — never a \`text\` or \`fontAwesome\` child;
 a text child also ignores the box's colour and hover. Chrome on several pages is a **layout**; the nav item of the page being shown is marked by the
 \`current\` state of its class, not by a copy of the header per page. Sibling rows of data are one \`repeatElement\`; a
-block repeated with other words is a **component** (\`upsertComponent { fromRef }\`). \`plitzi_validate\` and
-\`plitzi_apply\` answer with **\`suggestions\`** for what the batch could have written shorter, each with the elements
+block repeated with other words is a **component** (\`upsertComponent { fromRef }\`). \`plitzi_apply\` (with or
+without \`dryRun\`) answers with **\`suggestions\`** for what the batch could have written shorter, each with the elements
 it saves — never blocking; take them unless the copies are about to diverge.
 
 **Interactions** (\`upsertInteractionFlow\`): a \`trigger\` node first, then callbacks/utilities **in order** (links
@@ -87,7 +87,7 @@ element or page — not \`visible\`. Read anywhere as \`{{ flags.x }}\`.
 **Accessible by default:** screen readers and browser agents (Claude in Chrome) read the accessibility tree, so every
 button/link needs words (an icon-only button a \`title\`), every field a \`label\` (\`hideLabel: true\` hides it), every
 image an \`alt\` or \`decorative: true\`; clicks go on a \`button\`/\`link\`, never a container; headings step down one
-level at a time. \`plitzi_screenshot view:"accessibility"\` shows the tree and what has no name.
+level at a time. \`plitzi_look\` shows the tree and what has no name.
 
 **Everything the space holds is public.** Its pages, variables, attributes, flow params and mock data ship to every
 visitor's browser, and a file on a public bucket of its CDN is served to anyone who has its address. A key, a token or
@@ -135,8 +135,8 @@ Never download a whole tree you do not need.
   \`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://explain/{name}\` — what a name means: an element type's attributes, triggers and callbacks; a step's
-  params; what a trigger hands its flow; a problem code's fix. \`plitzi://explain/steps\` (or elements, triggers,
-  codes, transformers) lists every one of a kind.
+  params and what it publishes; what a trigger hands its flow; a problem code's fix. \`plitzi://explain/steps\` (or
+  elements, triggers, codes, transformers) lists every one of a kind.
 - \`plitzi://schema/{env}/pages\` — page **summaries** (ref, label, elementCount, folder). No element trees.
 - \`plitzi://schema/{env}/layouts\` — the shared **layout shells** (header/sidebar/footer) and the pages rendered
   inside each. Read one like a page. See *Shared layouts* below.
@@ -217,25 +217,40 @@ stateVersion) and returns any **style definitions** whose name matches the query
 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
-- \`plitzi_validate\` — check a batch, returns teachable errors/warnings. Writes nothing. Also reports **pre-existing
-  malformations** in any resource the batch touches (see below), and \`suggestions\` (see *Suggestions*).
-- \`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. Its answer carries \`suggestions\` too.
+- \`plitzi_apply\` — validate → apply → persist atomically. Rejects the whole batch on any error or conflict, and
+  reports **pre-existing malformations** in any resource the batch touches (see below) and \`suggestions\` (see
+  *Suggestions*). Pass \`dryRun: true\` to check and apply in memory only — the same answer, nothing persisted — and
+  \`look\` (\`"html"\`, \`"image"\`, \`"accessibility"\` or \`"both"\`, with \`pageRef\` and \`viewport\`) to see the page
+  as the batch leaves it in the same call. Check and look with \`dryRun\`, then send the same operations without it.
+  \`effects\` is what the batch did, read off the space before and after it — every element, attribute, class and
+  setting it changed, one line each: read it, not your batch, for what is now so. \`Nothing changed\` and \`NOT saved\`
+  lead the warnings when they are so.
+- **By intention**, a few parameters and the element named by its ref alone — the page is found, the operations
+  written, the batch checked and saved as \`plitzi_apply\` saves it, and the answer its \`effects\`, whether it was
+  \`saved\`, and what was already so:
+  \`plitzi_set_attributes { ref, set, unset }\`, \`plitzi_set_classes { ref, add, remove }\` (the classes it wears and
+  you do not name stay), \`plitzi_bind_attribute { ref, to, source }\`, \`plitzi_place_component { component, ref, into,
+  props }\`, \`plitzi_add_page { ref, slug, layout }\`. One of them when it says the whole change; anything else is one
+  batch of \`plitzi_apply\`.
+- \`plitzi_describe_operation\` — one operation's schema by its \`type\` (every field, which are required); without a
+  type, every operation type there is. Ask for the one you are writing instead of guessing a field: a field an
+  operation does not have is refused naming the one meant (\`"prop" (did you mean "props"?)\`), and a type spelt with
+  other capitals is read as the catalog spells it and said in \`warnings\`. The same batch refused twice is not run a
+  third time (\`REPEATED_BATCH\`) — change what the errors name, or ask the person.
 - \`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.
-- \`plitzi_preview\` — render a page to HTML, optionally with unsaved \`operations\` applied, to check structure.
-- \`plitzi_screenshot\` — render a page to a PNG (desktop, mobile or \`both\`), optionally with unsaved \`operations\`:
-  the way to SEE overflow, misalignment and broken layout before you commit. \`view: "accessibility"\` reads the same
-  page as a screen reader and a browser agent (Claude in Chrome) do — its accessibility tree as an outline of roles and
-  names, with every control and picture that has no name listed in \`unnamed\` — as text, far cheaper than an image
-  (\`"both"\` returns both). Both need the SSR render service; where it is missing they answer \`PREVIEW_UNAVAILABLE\`.
+- \`plitzi_look { pageRef, view, viewport }\` — see a saved page. \`view\`: \`"accessibility"\` (default) reads it as a
+  screen reader and a browser agent (Claude in Chrome) do — an outline of roles and names, every control and picture
+  with no name listed in \`unnamed\`, as text and far cheaper than an image; \`"html"\` its markup; \`"image"\` a PNG,
+  the way to SEE overflow and misalignment (desktop, mobile or \`both\`); \`"both"\` image and outline. A change not
+  saved yet is seen with \`plitzi_apply\`'s \`dryRun\` and \`look\`, the same views. It needs the SSR render service
+  (\`PREVIEW_UNAVAILABLE\` without it); without a browser, an image or an outline falls back to the HTML, said.
 - \`plitzi_render\` — a different job: show the user a self-contained widget built offline. It never touches the space.
 
 ## Suggestions — the same page with fewer elements
-\`plitzi_validate\` and \`plitzi_apply\` answer with \`suggestions\`: lines like \`[content-attribute] … (saves 4
+\`plitzi_apply\` (with or without \`dryRun\`) answers with \`suggestions\`: lines like \`[content-attribute] … (saves 4
 elements)\`, each naming a shorter way to what the batch just wrote. Only what THIS batch opened up is said — what the
 space already had is not repeated on every batch — and none of them blocks anything: the page renders as written.
 - \`repeated-on-pages\` — the same block at the edge of several pages: put it in a **layout** once (a block only some
@@ -357,7 +372,11 @@ You do not have to rewrite them.
   \`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\`.
+- \`element.style.base\` is a **list** of definition refs; other slots go under \`element.style.slots\` — the slots
+  \`plitzi://explain/{type}\` lists, never custom CSS on the SDK's own class names. A \`markdown\` or a \`richText\`
+  has a slot per part of the document it writes (\`heading\`, \`heading2\`, \`paragraph\`, \`link\`, \`code\`,
+  \`codeBlockFrame\`…); a \`formControl\` its \`input\` box, the \`field\` inside it, \`label\`, \`requiredMark\`, \`error\`;
+  a \`pagination\` its \`previous\`, \`page\`, \`next\` (the page shown is the class's \`current\` state).
 - **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
@@ -403,6 +422,15 @@ hovered or in a variant (\`.card:hover .icon\`, a collapsed sidebar hiding its l
 keyed by a class the ancestor wears: \`ancestors: { "toolbar": { "desktop": { … } }, "card": { "states": { "hover":
 { "desktop": { … } } } }, "sidebar": { "variants": { "collapsed": … } } }\`.
 Any ancestor counts, not only the parent; the class's own states and variants win over these. Never customCss for it.
+\`">"\` keys the parent, whatever it wears — a component's part reacting to what it sits in.
+
+**Pseudo-elements and conditions** sit beside \`states\` in a definition and in each of its variants:
+\`pseudos: { "after": { "desktop": { "content": "\\"→\\"" }, "states": { "hover": { "desktop": { … } } } } }\`
+(\`before\`/\`after\` are drawn only with a quoted \`content\`; also \`selection\`, \`marker\`, \`placeholder\`,
+\`first-letter\`, \`first-line\`), and \`conditions: { "motion-reduce": { "desktop": { … } }, "container (max-width:
+30rem)": { … } }\` (the nearest ancestor whose class sets \`container-type\`). A patch keeps the ones it does not name;
+\`null\` removes one. A state beyond \`hover\`/\`focus-visible\`/\`current\`: \`expanded\` (an open trigger), \`first\`,
+\`last\`, \`odd\`, \`even\`.
 
 ## Variables, design tokens and fonts
 - **Schema variables** are space-wide values a prop reads as \`{{name}}\`: \`upsertVariable { name, variableType,
@@ -444,7 +472,7 @@ that apiContainer; inside a \`list\`, the repeated \`listItem\` and its children
 (\`list_<name>.item.<field>\`). The global sources — ${GLOBALS} — have no \`<type>_<name>\` head and are
 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
+\`plitzi_apply\` treats it as an **error and rejects 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
@@ -479,9 +507,11 @@ you — never wire them by hand. Each step also has an \`enabled\` flag (see dis
 
 **Each step reads the page as it is when it runs**: a \`when\` or a \`{{ state.x }}\` after a \`setState\` sees the new
 value, and one after a \`delay\` sees what changed meanwhile. To act on the value from BEFORE a write, put the reading
-step first. **A trigger fired again while its flow runs is ignored** (no double submit); set \`"whileRunning": "queue"\`
-on the trigger node for a stream of events that must each run in order (\`"parallel"\` runs them at once,
-\`"latest"\` stops the running flow — its server action or request too — for a search as you type).
+step first. A step's \`when\` asks an earlier step only for what it publishes (\`plitzi://explain/<action>\` lists it):
+a run's \`<step>.status\` (\`runServerAction\` only), a sign-in's \`<step>.ok\` — any other key is refused
+(\`condition-field-unpublished\`). **A trigger fired again while its flow runs is ignored** (no double submit); set
+\`"whileRunning": "queue"\` on the trigger node for a stream of events that must each run in order (\`"parallel"\` runs
+them at once, \`"latest"\` stops the running flow — its server action or request too — for a search as you type).
 **Keyboard shortcuts** are a trigger every element has: \`onKey\` with param \`keys\` — \`"f"\`, \`"shift+f"\`,
 \`"mod+k"\` (⌘ on a Mac, Ctrl elsewhere), \`"plus, ="\`, \`"escape"\`. Heard on the whole page while the element is
 mounted, ignored while someone types in a field; the flow reads the key pressed as \`{{ <trigger id>.key }}\`.
@@ -522,7 +552,8 @@ mounted, ignored while someone types in a field; the flow reads the key pressed
   nothing outside the element needs to know it is open; pick the state one when something else binds to it.
 - \`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}\`.
+  \`webHook\` (\`url\`, \`method\`, …), \`copyToClipboard\` (\`text\`). 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>_<name>.<path>\`, or a
@@ -727,8 +758,9 @@ any other (\`<namespace>.<action>\`), listed in \`plitzi://actions/{env}/tasks\`
   \`defineFunctions\` from \`@plitzi/sdk-server/functions\`. Files import each other by relative path — no package,
   no Node built-in.
 - **\`ctx\` is all a function reaches:** \`ctx.kv\` (the space's store), \`ctx.fetch(url, init)\` to the hosts
-  \`allow.hosts\` names (\`*.example.com\` for subdomains), \`ctx.publish/grant/revoke\` (channels), \`ctx.log\`,
-  \`ctx.user\` (who asked, never their session). A secret is NAMED, never read: \`ctx.fetch(url, { credential: "stripe",
+  \`allow.hosts\` names (\`*.example.com\` for subdomains), \`ctx.publish/grant/revoke\` (channels),
+  \`ctx.data("products.json")\` (one file of the space's data, parsed — never imported), \`ctx.log\`, \`ctx.user\` (who
+  asked, never their session). A secret is NAMED, never read: \`ctx.fetch(url, { credential: "stripe",
   headers: { authorization: "Bearer {{ credential.apiKey }}" } })\`.
 - **Stateless:** nothing a function keeps in memory outlives the call — a module-level cache or counter starts empty
   every time, on whichever instance runs it. What must last goes in \`ctx.kv\`. A call gets 100 ms of CPU and 10 s;
@@ -885,14 +917,14 @@ the component reads \`{{ props.item.name }}\`.
     "children": [ { "ref": "lamp-buy", "type": "button", "props": { "content": "Buy", "slot": "product-card-actions" } } ] } }
 \`\`\`
 A required prop left out, a prop the component does not declare, a value of the wrong kind or a child naming a slot
-the component does not have is reported by \`plitzi_validate\` — fix it before applying.
+the component does not have is reported by \`plitzi_apply\`'s \`dryRun\` — fix it before applying.
 
 ## Pages & folders
 - **A page behind a feature flag**: \`upsertPage { flag: "labs" }\` answers 404 while the flag is off (see **Feature
   flags**); \`flag: null\` removes it.
 - **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.
+  and \`plitzi_apply\` warns 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.)
@@ -917,7 +949,10 @@ the component does not have is reported by \`plitzi_validate\` — fix it before
 - **The link to the page being shown marks itself**: it carries \`aria-current="page"\`, and its class's \`current\`
   state says how it looks — \`{ "type": "patchDefinition", "ref": "nav-link", "states": { "current": { "desktop": {
   "color": "var(--primary)" } } } }\`. So a header written once in a layout lights the right item on every page; never
-  copy the header per page to style one item.
+  copy the header per page to style one item. A link for a section — a journal and its articles — takes
+  \`"current": "section"\` in its props: current on every page under its path too (\`aria-current="true"\`), the same
+  state dressing it. The same state dresses any chosen one of a set: a pressed toggle (\`aria-pressed\` — a theme
+  toggle's option slot) and a selected tab.
 - **A section of a page** is an element with an \`anchor\` (its \`id\` in the DOM: lowercase, digits, \`-\`; one per
   page, layouts included; not inside a list row or a component). A link lands on it with \`hash\`:
   \`{ "mode": "page", "href": "home", "hash": "plans" }\` goes to \`/#plans\` and scrolls there, from any page.
@@ -946,10 +981,12 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
 - \`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.
 - \`notifications\` — how the toasts an \`addNotification\` step shows look: colours (\`background\`, \`text\`,
-  \`success\`, \`danger\`, \`warning\`, \`info\`) and shape (\`radius\`, \`font\`, \`fontSize\`, \`border\`, \`shadow\`,
-  \`padding\`), any CSS value — a token follows the theme: \`{ "type": "patchSettings", "notifications": { "background":
-  "var(--card)", "border": "1px solid var(--border)" } }\`. Merged field by field, \`null\` removes one. It is stored as a
-  rule inside \`customCss\` but reads and changes apart from it: never write a \`.Toastify__toast\` rule yourself.
+  \`success\`, \`danger\`, \`warning\`, \`info\`), shape (\`radius\`, \`font\`, \`fontSize\`, \`fontWeight\`, \`lineHeight\`,
+  \`minHeight\`, \`border\`, \`shadow\`, \`padding\`) and the parts inside (\`iconSize\`, \`iconGap\`, \`closeColor\`,
+  \`closeOpacity\`, \`progressHeight\`), one CSS value each — a token follows the theme: \`{ "type": "patchSettings",
+  "notifications": { "background": "var(--card)", "iconSize": "18px" } }\`. Merged field by field, \`null\` removes one.
+  It is stored as rules inside \`customCss\` but reads and changes apart from it: never write a \`.Toastify__*\` rule
+  yourself.
 - \`keepState\` / \`stateStorage\` — keep the runtime state (\`state.<key>\`, what \`setState\` writes) across reloads,
   in \`localStorage\`/\`sessionStorage\`, filed under whoever is signed in. It is the space's setting — pages do not
   take one. \`transientState\` lists the top-level keys never kept (a filter, a demo, a panel left open); do not
@@ -957,10 +994,12 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
   \`paintedState\` lists the kept keys the FIRST PAINT shows (the tool a toolbar shows, a name in an avatar): they go
   in a cookie too, so the server draws with them instead of the page swapping them in after load. Small values only.
 - **User provider / auth**: \`userProvider\` — \`basic\` for any HTTP+JSON backend, the name of a provider registered
-  in the page, or \`""\` to disable auth — plus \`tokenStorage\`, the \`loginUrl\`/\`userUrl\`/\`refreshUrl\`/\`logoutUrl\`
+  in the page, or \`""\` for none — plus \`tokenStorage\`, the \`loginUrl\`/\`userUrl\`/\`refreshUrl\`/\`logoutUrl\`
   endpoints and the \`detailsPath\`/\`tokenPath\`/\`refreshTokenPath\`/\`expirationTimePath\` mapping that says where the
   values sit in their responses. \`sessionHintCookie\` is worth setting whenever the backend can: it names a readable
   cookie carrying only expiries, which is what lets a page answer "nobody is signed in" without a request.
+  A space served by a self-hosted \`createServer({ auth })\` declares none of these: that server tells its pages where
+  they sign in, and only what the space declares overrides it.
   On the Plitzi platform, \`userProvider: "server"\` signs visitors in with their Plitzi account on the space's own
   host: a \`link\` with \`mode: "external"\` to \`/auth/sign-in?return=/\` starts it, \`authLogout\` ends it.
 - \`visitorRoles\` — what each visitor role gives, \`{ "author": ["postPublish"] }\`: the permissions an action's
@@ -1034,7 +1073,7 @@ tree names nothing is invisible to both, however it looks. So build every page t
 The linter warns about these (\`control-without-name\`, \`image-without-alt\`, \`click-on-static-element\`,
 \`dropdown-without-control\`, \`heading-level-skipped\`, \`label-ignored\`, \`control-in-decorative\`) on every element
 you touch; fix them in the same batch. Then look:
-\`plitzi_screenshot\` with \`view: "accessibility"\` shows the page as those readers get it, and lists what has no name.
+\`plitzi_look\` shows the page as those readers get it, and lists what has no name.
 
 ## Semantics
 - **props are fully replaced** on \`upsertElement\`: send every prop you want to keep. To change only some props,

package/dist/modules/mcp/index.d.ts

@@ -1,6 +1,6 @@
 export { createMcpServer, handleMcp, serveMcp, readMcpBody } from './handler';
 export { readResource, resourceVersion, registerResources, buildTypeRegistry, cssProperties } from './resources';
-export { apply, validate, search, read, validateOperations, operation, tools } from './tools';
+export { apply, search, read, validateOperations, operation, tools } from './tools';
 export { computeVersion } from './helpers';
 export { createHttpPreviewClient } from './previewClient';
 export { createLocalScreenshotClient, resolveLocalBrowser } from './localScreenshotClient';
@@ -12,6 +12,6 @@ export type { LocalScreenshotClientConfig } from './localScreenshotClient';
 export type { HttpScreenshotClientConfig } from './screenshotClient';
 export type { AccessibilityNode, UnnamedControl } from './accessibilityOutline';
 export type { McpServerContext } from './server';
-export type { ApplyInput, WriteResponse, Persisters, SearchInput, ReadInput, ReadResponse, ValidateInput, Operation, ToolDef, ToolContext } from './tools';
+export type { ApplyInput, WriteResponse, Persisters, SearchInput, ReadInput, ReadResponse, Operation, ToolDef, ToolContext } from './tools';
 export type { Space } from './helpers';
 export type * from './types';

package/dist/modules/mcp/server.d.ts

@@ -11,11 +11,11 @@ import { SSRAdapters, ServerLogger, SSRGrant } from '@plitzi/sdk-shared';
 export interface McpServerContext {
     adapters: SSRAdapters;
     getGrant: () => Promise<SSRGrant | undefined>;
-    /** How the visual-preview tools (plitzi_preview / plitzi_screenshot) reach the renderer. Absent → those tools
-     *  report PREVIEW_UNAVAILABLE, so an MCP-only deployment without a renderer still runs every other tool. */
+    /** How a look (plitzi_look, plitzi_apply's `look`) reaches the renderer. Absent → it reports PREVIEW_UNAVAILABLE, so an
+     *  MCP-only deployment without a renderer still runs every other tool. */
     preview?: PreviewClient;
-    /** The dedicated browser service for plitzi_screenshot. Absent → the tool is not registered (only the HTML
-     *  plitzi_preview is offered). */
+    /** The dedicated browser service a look takes an image or an accessibility outline with. Absent → a look answers
+     *  the HTML, and says so. */
     screenshot?: ScreenshotClient;
     /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */

package/dist/modules/mcp/server.js

@@ -72,7 +72,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.6"
+		version: "0.38.8"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);
@@ -103,10 +103,15 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 		if (hasSpace) return async (args) => tool.execute(args, await toolContext(tool.name));
 		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
 	};
-	for (const tool of tools) {
-		if (tool.requires === "screenshot" && !screenshot) continue;
+	const listed = tools.flatMap((tool) => {
 		const behavior = behaviorOf(tool);
-		if (!behavior) continue;
+		return behavior ? [{
+			tool,
+			behavior
+		}] : [];
+	});
+	const operationsCarried = listed.some(({ tool }) => tool.carriesOperations);
+	for (const { tool, behavior } of listed) {
 		const run = async (args) => {
 			const start = performance.now();
 			try {
@@ -129,7 +134,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 		const config = {
 			title: tool.title,
 			description: tool.description,
-			inputSchema: tool.inputShape,
+			inputSchema: operationsCarried && tool.compactInputShape ? tool.compactInputShape : tool.inputShape,
 			annotations: { readOnlyHint: tool.access === "read" }
 		};
 		if (tool.ui) {

package/dist/modules/mcp/tests/cheapMistakes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/mcp/tests/helpers.d.ts

@@ -1,6 +1,6 @@
 import { Space } from '../helpers';
 import { Operation } from '../tools';
-import { Persisters } from '../types';
+import { Persisters, ValidationResult } from '../types';
 declare const buildSpace: () => Space;
 declare const capturing: (space: Space) => {
     persisters: Persisters;
@@ -10,4 +10,11 @@ declare const spaceWithRoute: () => Space;
 declare const varOp: (pageRef: string, type: string, value: string) => Operation;
 declare const scopeSpace: () => Space;
 declare const malformedSpace: () => Space;
-export { buildSpace, capturing, spaceWithRoute, varOp, scopeSpace, malformedSpace };
+/**
+ * What `plitzi_apply`'s dryRun answers of a batch, as one result to assert on: the same `draftBatch` it runs before
+ * anything is saved, so a refusal here is the one an agent meets.
+ */
+declare const checkBatch: (input: {
+    operations: Operation[];
+}, space: Space) => ValidationResult;
+export { buildSpace, capturing, checkBatch, spaceWithRoute, varOp, scopeSpace, malformedSpace };

package/dist/modules/mcp/tests/intents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/mcp/tests/look.test.d.ts

@@ -0,0 +1 @@
+export {};