@plitzi/sdk-mcp 0.37.9 → 0.37.10

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

@@ -20,7 +20,8 @@ var TOOLS = [
 	"• plitzi_search — find elements by label/type/attribute; a hit carries the NAME every op takes (include:\"detail\"",
 	"  also returns its style + versions).",
 	"• plitzi_read — batch-read one or more resource URIs you already hold (from search or a write response).",
-	"• plitzi_validate — check a batch of operations without executing; returns teachable errors and warnings.",
+	"• plitzi_validate — check a batch of operations without executing; returns teachable errors and warnings, and",
+	"  suggestions: a shorter way to the same page (a layout, a component, the content of a link) — never blocking.",
 	"• plitzi_apply — persist a batch of operations. Pass dryRun to preview the full diff without writing, and",
 	"  expectedResourceVersions to guard against concurrent edits (apply and search hand back the versions you need).",
 	"• plitzi_preview / plitzi_screenshot — render a page (HTML / PNG), with unsaved operations applied if you pass them.",
@@ -57,10 +58,11 @@ var ACCESSIBILITY = [
 ].join("\n");
 var NAVIGATION = [
 	"━━ NAVIGATION & DYNAMIC PAGES ━━",
-	"To move between pages, PREFER the Link element over an interaction — it is a CONTAINER that wraps any children and",
-	"navigates on click. mode \"page\" links to another space page (href = the target page); mode \"internal\" takes a",
-	"path inside the space and resolves {{token}} templates in it (e.g. posts/{{postId}}); mode \"external\" is a full",
-	"URL. Reach for the navigate globalCallback only when navigation must be one step inside a larger flow.",
+	"To move between pages, PREFER the Link element over an interaction — its words are its `content`, and it can wrap",
+	"any children too. The link to the page being shown is styled by its class's `current` state. mode \"page\" links",
+	"to another space page (href = the target page); mode \"internal\" takes a path inside the space and resolves",
+	"{{token}} templates in it (e.g. posts/{{postId}}); mode \"external\" is a full URL. Reach for the navigate",
+	"globalCallback only when navigation must be one step inside a larger flow.",
 	"A page slug is RELATIVE — never start it with \"/\" (the runtime prepends it). Folder slugs PREPEND to the page",
 	"slug, so a page at slug \"post\" inside folders \"blog\" > \"2024\" resolves to /blog/2024/post.",
 	"A slug segment \":name\" (e.g. \"posts/:postId\") declares a ROUTE PARAM, react-router style. It is readable on that",

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

@@ -36,6 +36,10 @@ vars. **Write plain CSS** — shorthands (\`border\`, \`padding\`, \`margin\`, \
 still \`display: flex\` + \`flex-direction\`/\`align-items\`/…, not a \`flex\` value. Mind a type's \`defaultStyle\`
 (\`text\` is \`display: inline\`). Global styles (\`button {…}\`) and id styles (\`#id\`) have their own ops.
 
+**Motion:** animate only \`opacity\` and \`transform\` — they stay smooth while the page loads; an animated blur,
+shadow, size, \`top\`/\`left\` or \`background-position\` stutters on every visitor's machine. Good practices in
+\`plitzi://guide\` (Motion).
+
 **Data bindings** (\`upsertBinding\`, category attributes|style|initialState): connect a \`source\` to a \`to\` field.
 A source \`<type>_<name>\` is scoped to the provider's **DESCENDANTS only** — bind inside the provider's subtree
 (the global sources ${GLOBALS} are bindable anywhere). \`apiContainer.mockData\` is builder-only; set a
@@ -43,6 +47,14 @@ real \`query\` for production. \`transformers: [{action, params}]\` post-process
 from \`plitzi://data-sources\`; \`twigTemplate\` formats it (the value is \`{{source}}\`, not \`{{value}}\`). \`when\` is
 a QueryBuilder RuleGroup gating the binding.
 
+**Fewer elements, same page:** a \`link\` or \`button\` says its words itself — \`content\`, with an icon beside them
+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
+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
 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\`
@@ -65,7 +77,11 @@ flow — list page, detail page, paging, writes — in \`plitzi://guide\`.
 **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.
+element** (\`mode\` "page"/"internal"/"external"; its words are its \`content\`, and it can wrap any children too) over
+a \`navigate\` interaction.
+
+**Feature flags:** what a person switches on (a beta, a rollout) is \`upsertFlag\` plus \`flag: "x"\` / \`"!x"\` on the
+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
@@ -76,7 +92,8 @@ level at a time. \`plitzi_screenshot view:"accessibility"\` shows the tree and w
 the save on any \`Pre-existing malformation in element …\` error (a broken transformer, a malformed step, an attribute
 it never reads) — 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. A broken tree your batch leaves ANYWHERE (an element orphaned by a delete) blocks it too.
+but do not block. A broken tree your batch leaves ANYWHERE (an element orphaned by a delete) blocks it too. Each
+problem leads with its \`[code]\`, and its hint says what to write instead.
 
 Read \`plitzi://guide\` before anything above is unclear.
 `;
@@ -110,6 +127,9 @@ Never download a whole tree you do not need.
   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://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.
 - \`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.
@@ -135,6 +155,7 @@ Never download a whole tree you do not need.
 - \`plitzi://style-variables/{env}\` — design tokens by category. \`/{category}\` for one.
 - \`plitzi://fonts/{env}\` — the font **families the space loads**, with their source and fallback. \`/{family}\` for one.
 - \`plitzi://schema-variables/{env}\` — space-level values referenced in props as \`{{name}}\`.
+- \`plitzi://flags/{env}\` — the space's **feature flags**, each a default and its rules (see **Feature flags**).
 - \`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.
@@ -188,10 +209,10 @@ When you do hold several refs to open (e.g. from a skeleton), read them together
 
 ## 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).
+  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.
+  without persisting — inspect it, then re-run without \`dryRun\` to commit. Its answer carries \`suggestions\` too.
 - \`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,
@@ -204,6 +225,25 @@ When you do hold several refs to open (e.g. from a skeleton), read them together
   (\`"both"\` returns both). Both need the SSR render service; where it is missing they answer \`PREVIEW_UNAVAILABLE\`.
 - \`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
+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
+  pages of a layout carry is a **component** instead). Copies differing only in one link's class are the nav item of the
+  page being shown: the \`current\` state marks it (see *Pages & folders*).
+- \`repeated-shape\` — one structure written again with other words: a **component** with props
+  (\`upsertComponent { fromRef }\` turns one copy into it), or, for sibling rows of data, one \`repeatElement\`/\`list\`.
+  A few cards a person rewords by hand can stay cards.
+- \`content-attribute\` — a \`button\` or \`link\` whose children are only a \`text\` and/or a \`fontAwesome\`: its words
+  are its own \`content\` and the icon its \`icon\`. What the text's class adds (\`white-space: nowrap\`) moves to the
+  box's class — never the class itself; the icon's class goes in the \`icon\` slot.
+- \`custom-css-class\`, \`custom-css-sdk-default\`, \`custom-css-notifications\` — \`customCss\` that a class's
+  \`states\`/\`ancestors\`, the SDK (reduced motion, the theme toggle's icons) or the space's notification look says.
+- \`heavy-animation\` — keyframes that animate a size, a position, a blur, a shadow, or a colour in a loop: they stutter
+  while the page loads. Lighter, not shorter — see **Motion — good practices**.
+\`plitzi://explain/<code>\` explains each. Take one unless the copies are about to diverge.
+
 ## 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
@@ -255,6 +295,12 @@ You do not have to rewrite them.
 - \`deleteElement { pageRef, ref }\` removes an element **and everything under it**. A binding or an interaction
   elsewhere that named one of them is left pointing at nothing, and the save reports it — delete them in the same
   batch. Destructive: confirm first.
+- \`flag\` on \`upsertElement\` / \`patchElement\` gates an element on a feature flag (\`"newCheckout"\` or
+  \`"!newCheckout"\`) — not a visibility: gated off it is not rendered at all. See **Feature flags**.
+- **A compound element is written with its parts**, as \`children\` of the same \`upsertElement\`: a \`carousel\` holds a
+  \`carouselTrack\` (the slides go in it), a \`tabContainer\` a \`tabContainerHeader\` and a \`tabContainerBody\`, a
+  \`dropdown\` a \`dropdownPopup\`. Without its part it shows nothing (\`part-missing\`); a part anywhere else breaks the
+  page (\`outside-ancestor\`).
 
 ## Styling (crosses both schemas)
 - **Mind the type's intrinsic default style.** A type renders with a base CSS *before* any class is attached — read
@@ -681,6 +727,30 @@ element binds \`grant\` to it. Without one the topic is refused however well its
 \`expected\` = only if nothing is there yet), ordered lists with \`list.put\` / \`list.range\`, and put
 \`flow.rateLimit\` first in any public action that writes.
 
+## Feature flags
+A flag turns a part of the space on or off without anyone editing it: a feature still being built, a version for
+beta users, the old checkout kept until the new one ships. **Not a visibility** — visibility hides an element that is
+still rendered; a flag decides whether it exists at all.
+
+- **Declare** with \`upsertFlag { name, description?, value, rules? }\`. \`value\` is its answer when no rule matches;
+  \`rules\` are \`[{ when, value }]\` read top to bottom, the first match deciding. A rule's \`when\` is a rule group over
+  \`environment\` (\`main\`, \`development\`, \`staging\`, \`production\`), \`hostname\`, \`routeParams.<name>\`,
+  \`queryParams.<name>\` and the visitor: \`user.authenticated\`, \`user.email\`, \`user.username\`, \`user.roles\` (with
+  \`contains\`). A group with no rules is skipped, never read as "always". \`deleteFlag { name }\` removes one.
+- **Gate** an element with \`flag\` on \`upsertElement\` / \`patchElement\`: \`"newCheckout"\` exists only while the flag is
+  on, \`"!newCheckout"\` only while it is off — put both side by side for a rollout. On \`upsertPage\` a gated-off page
+  answers 404. \`null\` on a patch removes the gate. Gated off, it is not rendered and its server data is not
+  resolved — but the space's document, gated elements included, still reaches the browser: a flag is not a secret.
+- **Read** it anywhere a source is read: \`{{ flags.newCheckout }}\` in a binding, a \`when\` of a flow step, a computed
+  value — and in a server action's steps, where it is resolved on the server.
+
+A gate or a read naming a flag the space does not declare is an error (\`flag-undeclared\`, \`flag-unknown\`): an
+undeclared flag is off. A declared flag nothing reads is a warning (\`flag-unused\`) — remove it once the feature
+ships. The draft applies flags at once. Flags are not part of a snapshot: each environment has one set, shared by every
+snapshot it serves — publishing a snapshot sends the draft's with it (and the snapshot keeps a copy, as a fallback), the
+builder's *Publish flags* sends only them, and a rollback keeps them. Above the space, the server rendering it, the SDK embedding it and a tester with the dev tools
+may each override a flag; you only ever write the space's own.
+
 ## Shared layouts — the chrome a page does NOT contain
 A page's tree is usually **not the whole page**. The header, the sidebar and the footer normally live in a **layout
 container**: a shell several pages are rendered inside, so the navigation is authored once instead of once per page.
@@ -714,6 +784,9 @@ vocabulary:
 - \`deleteLayout\` removes a shell and everything in it, and is **refused while any page still renders inside it**
   (the refusal names them). Destructive: what it deletes is on every page that uses it, so confirm first.
 
+**Only some pages?** A block that only some of a layout's pages carry (a newsletter band on two of ten) is not
+chrome: make it a **component** and place it on those pages.
+
 **Where does this element belong?** If the user asks for something "on every page" — a nav item, a banner, a footer
 link, an upgrade prompt in the sidebar — it belongs in the LAYOUT, not in the page you happen to have open. Check
 the page's \`layout\` first; if the element you are looking for is not in the page's own tree, it is in the shell.
@@ -724,6 +797,10 @@ any page as an **instance**. It is part of the space, so it is published, versio
 not inside any page: it is a root of its own, like a layout, and **editing it changes every instance** — say so
 before you touch one.
 
+It is not a **snippet**. The builder's *Save as snippet* keeps a copy of a block as a file people drop onto pages, and
+each drop is the page's own from then on. No operation here writes one: when someone wants a block that stays the same
+everywhere, that is a component.
+
 It is **closed**. Inside, a binding or a template reads **\`props\`** — what each instance hands in — and the globals
 (\`state\`, \`auth\`, \`navigation\`, \`theme\`, \`variables\`, \`computed\`), never the page an instance sits on. A
 component that needs a list row's record gets it as a prop: the INSTANCE binds it (\`item: "{{ list_rows.item }}"\`),
@@ -760,6 +837,8 @@ A required prop left out, a prop the component does not declare, a value of the
 the component does not have is reported by \`plitzi_validate\` — 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.
@@ -779,6 +858,18 @@ the component does not have is reported by \`plitzi_validate\` — fix it before
   \`"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\`.
+- **A link's words are its \`content\`, and an icon beside them its \`icon\`** — \`{ "type": "link", "props": { "mode":
+  "page", "href": "pricing", "content": "Pricing", "icon": "fa-solid fa-arrow-right", "iconPlacement": "after" } }\`
+  (a \`button\` takes the same two). The icon's class goes in the element's \`icon\` slot (\`style.slots.icon\`). With
+  children too, \`contentPlacement\` puts the words \`before\` or \`after\` them. A \`text\` or \`fontAwesome\` inside is
+  one element more, and a text keeps a colour of its own instead of the link's (and its hover).
+- **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.
+- **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.
 
 Pages can be grouped into **folders** (the sidebar tree). A folder is \`{ ref, name, slug, parentId? }\`; its \`ref\`
 **is its id**, and that id is what a page and a nested folder reference.
@@ -803,6 +894,11 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
 (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.
+- \`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.
 - \`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
@@ -818,12 +914,33 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
   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
   \`access: { mode: "role" }\` and a page's \`can()\` ask for. A visitor holds ONLY the permissions of their roles here,
-  never their account's. Who holds a role is given by email in the builder's Visitors panel — never in settings.
+  never their account's. Who holds a role is given by email in the builder's Settings → Visitors — never in the
+  space's \`settings\`.
 - \`channels\` — the realtime channels, by topic pattern (see **Realtime channels**). Merged pattern by pattern;
   \`null\` removes one.
   Example — inject a keyframe globally:
   \`{ "type": "patchSettings", "customCss": "@keyframes spin { to { transform: rotate(360deg); } }" }\`.
 
+## Motion — good practices
+Keyframes go in \`customCss\` (\`patchSettings\`), a definition names them (\`animation\`). Only \`opacity\` and
+\`transform\` (\`translate\`, \`scale\`, \`rotate\`) animate off the main thread: they stay smooth while the page
+hydrates and on a slow phone. Anything else repaints or lays the page out again on every frame, and freezes while the
+page's scripts run.
+- Slide, grow, fade with \`transform\` and \`opacity\` — never \`left\`, \`top\`, \`width\`, \`height\` or
+  \`margin\`. Something travelling across a box is \`transform: translate(%)\` on an element as large as the box.
+- No animated blur: no \`filter: blur()\` in an entrance or a loop, no \`backdrop-filter\` over moving content. A soft
+  shape is a \`radial-gradient\` fading to transparent.
+- Fake the expensive ones: a growing shadow is a second shadow on a pseudo-element whose \`opacity\` changes; a
+  pulsing glow is a static gradient whose \`opacity\` or \`scale\` changes.
+- Decoration that must animate something else (a custom property, \`background-position\`) starts paused and runs
+  once the page is hydrated: \`.glow { animation: glow 8s linear infinite paused; } [data-hydrated] .glow {
+  animation-play-state: running; }\` in \`customCss\`.
+- Entrances: \`opacity\` + a small \`translateY\`, under ~600ms, staggered by tens of ms.
+- One slow ambient loop per screen at most — not one per card: \`infinite\` runs on every visitor's battery.
+- Name what transitions (\`transition: transform 200ms, opacity 200ms\`), never \`all\`; \`will-change\` only on the
+  few elements about to move.
+- Reduced motion is the SDK's: it cuts every animation to an instant for whoever asks — never write that reset.
+
 ## Accessibility — pages people, screen readers and browser agents can all use
 A page is read three ways: seen, heard through a screen reader, and worked by a **browser agent** (Claude in Chrome)
 — which finds the controls it can press in the same **accessibility tree** a screen reader walks. A control that

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

@@ -13,6 +13,7 @@ export declare const elementUri: (env: Env, ref: string) => string;
 export declare const componentsUri: (env: Env) => string;
 export declare const schemaVarsUri: (env: Env) => string;
 export declare const settingsUri: (env: Env) => string;
+export declare const flagsUri: (env: Env) => string;
 export declare const interactionsUri: (env: Env) => string;
 export declare const dataSourcesUri: (env: Env) => string;
 /** Worked manifests + the template vocabulary. Space-independent, hence no env — and a distinct root, so a

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

@@ -13,6 +13,7 @@ var elementUri = (env, ref) => `plitzi://schema/${env}/elements/${ref}`;
 var componentsUri = (env) => `plitzi://schema/${env}/components`;
 var schemaVarsUri = (env) => `plitzi://schema-variables/${env}`;
 var settingsUri = (env) => `plitzi://settings/${env}`;
+var flagsUri = (env) => `plitzi://flags/${env}`;
 var interactionsUri = (env) => `plitzi://interactions/${env}`;
 var dataSourcesUri = (env) => `plitzi://data-sources/${env}`;
 /** Worked manifests + the template vocabulary. Space-independent, hence no env — and a distinct root, so a
@@ -61,4 +62,4 @@ var itemTemplates = (env) => [
 *  family and extracts its ref in one step, without repeating the prefix string for both the startsWith and slice. */
 var afterPrefix = (uri, prefix) => uri.startsWith(prefix) ? uri.slice(prefix.length) : void 0;
 //#endregion
-export { actionTasksUri, actionUri, actionsUri, afterPrefix, aliasedRoots, changesUri, componentsUri, connectorPresetsUri, connectorUri, connectorsUri, cssPropertiesUri, dataSourcesUri, defUri, defsUri, elementUri, folderUri, foldersUri, fontUri, fontsUri, functionFileUri, functionsUri, globalUri, globalsUri, guideUri, idUri, idsUri, interactionsUri, itemTemplates, layoutsUri, pageUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarUri, styleVarsUri, typesUri };
+export { actionTasksUri, actionUri, actionsUri, afterPrefix, aliasedRoots, changesUri, componentsUri, connectorPresetsUri, connectorUri, connectorsUri, cssPropertiesUri, dataSourcesUri, defUri, defsUri, elementUri, flagsUri, folderUri, foldersUri, fontUri, fontsUri, functionFileUri, functionsUri, globalUri, globalsUri, guideUri, idUri, idsUri, interactionsUri, itemTemplates, layoutsUri, pageUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarUri, styleVarsUri, typesUri };

package/dist/modules/mcp/resources/explain.d.ts

@@ -0,0 +1,19 @@
+import { ExplainKind, Explanation } from '@plitzi/sdk-authoring';
+/** `plitzi://explain/{name}`: what a name means when authoring, or every name of a kind (`plitzi://explain/steps`). */
+export declare const EXPLAIN_URI_TEMPLATE = "plitzi://explain/{name}";
+/**
+ * The read behind the resource: a kind's plural lists it; any other name is explained, each meaning it has, as data
+ * and as the text the CLI prints. A name that is nothing says what there is to ask about instead.
+ */
+export type ExplainRead = {
+    list: ExplainKind;
+    names: {
+        name: string;
+        summary: string;
+    }[];
+} | {
+    name: string;
+    explanations: Explanation[];
+    text: string;
+};
+export declare const explainResource: (uri: string) => ExplainRead;

package/dist/modules/mcp/resources/explain.js

@@ -0,0 +1,22 @@
+import { EXPLAIN_KINDS, explain, explainKindOf, explainList, explanationText } from "@plitzi/sdk-authoring";
+//#region src/modules/mcp/resources/explain.ts
+/** `plitzi://explain/{name}`: what a name means when authoring, or every name of a kind (`plitzi://explain/steps`). */
+var EXPLAIN_URI_TEMPLATE = "plitzi://explain/{name}";
+var PREFIX = "plitzi://explain/";
+var explainResource = (uri) => {
+	const name = decodeURIComponent(uri.startsWith(PREFIX) ? uri.slice(17) : uri);
+	const kind = explainKindOf(name);
+	if (kind) return {
+		list: kind,
+		names: explainList(kind)
+	};
+	const explanations = explain(name);
+	if (explanations.length === 0) throw new Error(`"${name}" is no element, step, trigger, code or transformer. List what there is: ${Object.values(EXPLAIN_KINDS).map((plural) => `${PREFIX}${plural}`).join(", ")}.`);
+	return {
+		name,
+		explanations,
+		text: explanations.map(explanationText).join("\n\n")
+	};
+};
+//#endregion
+export { EXPLAIN_URI_TEMPLATE, explainResource };

package/dist/modules/mcp/resources/explain.test.d.ts

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

package/dist/modules/mcp/resources/primer.js

@@ -2,7 +2,7 @@ import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/obs
 import { buildTypeRegistry } from "../catalogs/registry.js";
 import { cssProperties, cssShorthands } from "../catalogs/index.js";
 import { componentSummariesToAI } from "../helpers/components.js";
-import { componentsUri, connectorsUri, dataSourcesUri, defsUri, foldersUri, fontsUri, interactionsUri, layoutsUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarsUri, typesUri } from "../helpers/uris.js";
+import { componentsUri, connectorsUri, dataSourcesUri, defsUri, flagsUri, foldersUri, fontsUri, interactionsUri, layoutsUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarsUri, typesUri } from "../helpers/uris.js";
 import { guideQuickstart } from "../helpers/guide.js";
 import { envelope } from "./envelope.js";
 import { connectorSummaries } from "./connectors.js";
@@ -104,6 +104,11 @@ var readPrimerResource = (space, env, uri) => {
 			value: schemaVariablesToAI(space.schema, false),
 			read: schemaVarsUri(env)
 		},
+		{
+			key: "flags",
+			value: Object.keys(space.schema.flags ?? {}),
+			read: flagsUri(env)
+		},
 		{
 			key: "styleVariables",
 			value: styleVariablesToAI(space.style),

package/dist/modules/mcp/resources/register.js

@@ -5,6 +5,7 @@ import { envelope, jsonContents } from "./envelope.js";
 import { resourceErrorMessage } from "./canonical.js";
 import { registerRenderResources } from "./renderGuide.js";
 import { readResource } from "./router.js";
+import { EXPLAIN_URI_TEMPLATE, explainResource } from "./explain.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 //#region src/modules/mcp/resources/register.ts
 /** A page an agent can read in one go: each change carries whole elements before and after. */
@@ -49,6 +50,10 @@ var registerResources = (server, getSpace, env, log, hasSpace, readChanges) => {
 		properties: cssProperties,
 		shorthands: cssShorthands
 	}))));
+	server.registerResource("Explain", new ResourceTemplate(EXPLAIN_URI_TEMPLATE, { list: void 0 }), {
+		description: "What a name means when authoring: an element (container), a step (navigate), a trigger (onScroll), a problem code (class-and-css) or a transformer — or every one of a kind: elements, steps, triggers, codes, transformers",
+		mimeType: "application/json"
+	}, (uri) => emitStatic(uri.href, () => jsonContents(uri.href, envelope(explainResource(uri.href)))));
 	registerRenderResources(server, log);
 	if (!hasSpace) return;
 	const fixed = [
@@ -107,6 +112,11 @@ var registerResources = (server, getSpace, env, log, hasSpace, readChanges) => {
 			`plitzi://schema-variables/${env}`,
 			"Space-level values referenced via {{name}}"
 		],
+		[
+			"Feature flags",
+			`plitzi://flags/${env}`,
+			"The feature flags the space declares, each a default and its rules: read as {{ flags.<name> }}, named by the `flag` of an element or a page"
+		],
 		[
 			"Settings",
 			`plitzi://settings/${env}`,

package/dist/modules/mcp/resources/schema.js

@@ -1,7 +1,7 @@
 import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/observed.js";
 import { componentSummariesToAI, componentView, findComponentByRef } from "../helpers/components.js";
 import { findElementByRef, findRootByRef } from "../helpers/space.js";
-import { afterPrefix, componentsUri, dataSourcesUri, elementUri, folderUri, foldersUri, interactionsUri, layoutsUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../helpers/uris.js";
+import { afterPrefix, componentsUri, dataSourcesUri, elementUri, flagsUri, folderUri, foldersUri, interactionsUri, layoutsUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../helpers/uris.js";
 import { envelope } from "./envelope.js";
 import { elementView, folderRefToAI, foldersToAI, layoutSummariesToAI, pageSkeletonToAI, pageStylesToAI, pageSummariesToAI, schemaVariablesToAI, settingsToAI } from "../tools/operations/schema/translator.js";
 import { treeOf } from "@plitzi/sdk-schema/helpers/components";
@@ -42,6 +42,7 @@ var readSchemaResource = (space, env, uri) => {
 		};
 	}
 	if (uri === schemaVarsUri(env)) return envelope(schemaVariablesToAI(space.schema));
+	if (uri === flagsUri(env)) return envelope(space.schema.flags ?? {});
 	if (uri === settingsUri(env)) return envelope(settingsToAI(space.schema));
 	if (uri === interactionsUri(env)) return envelope(buildInteractionCatalog(space.schema));
 	if (uri === dataSourcesUri(env)) return envelope(buildDataSourceCatalog(space.schema));

package/dist/modules/mcp/server.js

@@ -69,7 +69,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.37.9"
+		version: "0.37.10"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);

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

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

package/dist/modules/mcp/tools/apply/dispatch.js

@@ -17,6 +17,8 @@ import { deleteElement } from "../operations/schema/elements/deleteElement.js";
 import { moveElement } from "../operations/schema/elements/moveElement.js";
 import { patchElement } from "../operations/schema/elements/patchElement.js";
 import { upsertElement } from "../operations/schema/elements/upsertElement.js";
+import { deleteFlag } from "../operations/schema/flags/deleteFlag.js";
+import { upsertFlag } from "../operations/schema/flags/upsertFlag.js";
 import { deleteFolder } from "../operations/schema/folders/deleteFolder.js";
 import { upsertFolder } from "../operations/schema/folders/upsertFolder.js";
 import { deleteInteraction } from "../operations/schema/interactions/deleteInteraction.js";
@@ -78,6 +80,8 @@ var executeOp = (space, env, op) => {
 		case "deleteFolder": return deleteFolder(space, env, op);
 		case "upsertVariable": return upsertVariable(space, env, op);
 		case "deleteVariable": return deleteVariable(space, env, op);
+		case "upsertFlag": return upsertFlag(space, env, op);
+		case "deleteFlag": return deleteFlag(space, env, op);
 		case "upsertBinding": return upsertBinding(space, env, op);
 		case "patchBinding": return patchBinding(space, env, op);
 		case "deleteBinding": return deleteBinding(space, env, op);

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

@@ -54,6 +54,8 @@ export declare const applyShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -78,6 +80,7 @@ export declare const applyShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -122,6 +125,18 @@ export declare const applyShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -225,6 +240,7 @@ export declare const applyShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";

package/dist/modules/mcp/tools/apply/index.js

@@ -53,7 +53,7 @@ var apply = async (input, space, persisters) => {
 		errors: result.errors,
 		warnings: noWarnings(result.warnings)
 	};
-	const { draft, outcome, warnings } = result;
+	const { draft, outcome, warnings, suggestions } = result;
 	if (input.dryRun) return {
 		applied: false,
 		dryRun: true,
@@ -64,7 +64,8 @@ var apply = async (input, space, persisters) => {
 		},
 		changed: changedResources(draft, env, outcome.staleResources),
 		elements: resolvedElements(draft, env, outcome.elementRefs),
-		warnings: noWarnings(warnings)
+		warnings: noWarnings(warnings),
+		suggestions: noWarnings(suggestions)
 	};
 	let persisted = true;
 	if (outcome.changedFunctions && draft.functions) {
@@ -118,7 +119,8 @@ var apply = async (input, space, persisters) => {
 		},
 		changed: changedResources(draft, env, outcome.staleResources),
 		elements: resolvedElements(draft, env, outcome.elementRefs),
-		warnings: noWarnings(warnings)
+		warnings: noWarnings(warnings),
+		suggestions: noWarnings(suggestions)
 	};
 };
 var applyTool = defineTool({