@plitzi/sdk-server 0.32.5 → 0.32.7

package/dist/modules/mcp/catalogs/builtinUtilities.js

@@ -0,0 +1,90 @@
+import { reconcileParams } from "./paramSpec.js";
+//#region src/modules/mcp/catalogs/builtinUtilities.ts
+var BUILTIN_UTILITIES = {
+	delayTime: {
+		title: "Delay Time",
+		strictParams: true,
+		params: { time: {
+			type: "number",
+			description: "Milliseconds to wait before the next step runs. The key is \"time\" (not \"delay\")."
+		} }
+	},
+	twigTemplate: {
+		title: "Twig Template",
+		strictParams: true,
+		params: {
+			returnMode: {
+				type: "select",
+				description: "How the rendered template is returned.",
+				default: "text",
+				options: [
+					"text",
+					"json",
+					"jsonObject"
+				]
+			},
+			template: {
+				type: "textarea",
+				description: "The Twig template string to render against the flow/global params."
+			}
+		}
+	},
+	webHook: {
+		title: "Webhook",
+		strictParams: true,
+		params: {
+			url: {
+				type: "text",
+				description: "The URL to call."
+			},
+			method: {
+				type: "select",
+				description: "HTTP method.",
+				default: "get",
+				options: [
+					"get",
+					"post",
+					"put",
+					"delete",
+					"patch",
+					"head"
+				]
+			},
+			body: {
+				type: "textarea",
+				description: "Request body."
+			},
+			authorizationToken: {
+				type: "text",
+				description: "Value sent as the Authorization header."
+			},
+			credentials: {
+				type: "select",
+				description: "fetch credentials mode.",
+				default: "same-origin",
+				options: [
+					"include",
+					"omit",
+					"same-origin"
+				]
+			}
+		}
+	}
+};
+/** The built-in utility for an action, or undefined when the action is not a known built-in utility. */
+var getUtility = (action) => Object.hasOwn(BUILTIN_UTILITIES, action) ? BUILTIN_UTILITIES[action] : void 0;
+/** Reconcile a `utility` action against the utility catalog: unknown keys dropped for a closed utility, then missing
+*  defaults filled. An unknown action yields unchanged params. */
+var applyUtility = (action, params) => {
+	const utility = getUtility(action);
+	if (!utility) return {
+		known: false,
+		params
+	};
+	return {
+		known: true,
+		params: reconcileParams(params, utility.params, utility.strictParams)
+	};
+};
+//#endregion
+export { BUILTIN_UTILITIES, applyUtility, getUtility };

package/dist/modules/mcp/{tools/operations/style → catalogs}/cssCatalog.js

@@ -1,5 +1,5 @@
 import styleConstants from "@plitzi/sdk-shared/style/styleConstants";
-//#region src/modules/mcp/tools/operations/style/cssCatalog.ts
+//#region src/modules/mcp/catalogs/cssCatalog.ts
 /** Every kebab-case CSS property Plitzi's style engine understands. Values written to a definition
 *  must use these exact keys — camelCase or unknown keys are rejected by the validator. */
 var cssProperties = Array.from(new Set(Object.values(styleConstants))).sort();
@@ -28,6 +28,79 @@ var splitTokens = (value) => {
 	if (current) tokens.push(current);
 	return tokens;
 };
+var COMPOUND_SHORTHANDS = {
+	flex: [
+		"flex-grow",
+		"flex-shrink",
+		"flex-basis"
+	],
+	"flex-flow": ["flex-direction", "flex-wrap"],
+	background: [
+		"background-color",
+		"background-image",
+		"background-position",
+		"background-size",
+		"background-repeat"
+	],
+	font: [
+		"font-family",
+		"font-size",
+		"font-weight",
+		"line-height"
+	],
+	transition: [
+		"transition-property",
+		"transition-duration",
+		"transition-timing-function",
+		"transition-delay"
+	],
+	animation: [
+		"animation-name",
+		"animation-duration",
+		"animation-timing-function",
+		"animation-delay",
+		"animation-iteration-count"
+	],
+	grid: [
+		"grid-template-columns",
+		"grid-template-rows",
+		"grid-template-areas"
+	],
+	"grid-template": [
+		"grid-template-columns",
+		"grid-template-rows",
+		"grid-template-areas"
+	],
+	"grid-area": [
+		"grid-row-start",
+		"grid-column-start",
+		"grid-row-end",
+		"grid-column-end"
+	],
+	"place-content": ["align-content", "justify-content"],
+	"place-items": ["align-items", "justify-items"],
+	"place-self": ["align-self", "justify-self"],
+	"list-style": [
+		"list-style-type",
+		"list-style-position",
+		"list-style-image"
+	],
+	"text-decoration": [
+		"text-decoration-line",
+		"text-decoration-color",
+		"text-decoration-style"
+	],
+	outline: [
+		"outline-width",
+		"outline-style",
+		"outline-color"
+	],
+	columns: ["column-width", "column-count"],
+	overflow: ["overflow-x", "overflow-y"]
+};
+/** The atomic longhands to write instead of a compound shorthand, or undefined when the key is not a compound
+*  shorthand. `flex` layout in particular is NOT `display` + `flex-direction` (those are their own properties). */
+var compoundLonghands = (key) => Object.hasOwn(COMPOUND_SHORTHANDS, key) ? COMPOUND_SHORTHANDS[key] : void 0;
 var SIDES = [
 	"top",
 	"right",
@@ -129,4 +202,4 @@ var expandShorthand = (css) => {
 	};
 };
 //#endregion
-export { cssProperties, expandShorthand, isCssProperty, suggestCssProperty };
+export { COMPOUND_SHORTHANDS, compoundLonghands, cssProperties, expandShorthand, isCssProperty, suggestCssProperty };

package/dist/modules/mcp/catalogs/observed.js

@@ -0,0 +1,90 @@
+import { BUILTIN_GLOBAL_CALLBACKS } from "./builtinCallbacks.js";
+import { BUILTIN_ELEMENT_CALLBACKS } from "./builtinElementCallbacks.js";
+import { BUILTIN_UTILITIES } from "./builtinUtilities.js";
+import { transformerCatalog } from "./builtinTransformers.js";
+//#region src/modules/mcp/catalogs/observed.ts
+var INTERACTION_NOTE = "Interaction actions observed on this space, grouped by node type. A flow is a trigger followed by ordered callbacks/utilities; write one with upsertInteractionFlow. Names not listed may still be valid plugin actions.";
+var GLOBAL_CALLBACKS_NOTE = "Built-in global callbacks always available in every space. A globalCallback is registered on its SOURCE MODULE, so its node `elementId` is the listed `source` (e.g. \"space\" for addNotification) — NOT the element that hosts the flow. Omit `elementId` and the MCP sets the right source and fills the param defaults for you. Use ONLY the params listed under each callback (with the exact spelling shown) — for addNotification the visible text goes in `content`; there is no title/message/type param. When strictParams is true, any other key is rejected.";
+var ELEMENT_CALLBACKS_NOTE = "Built-in `callback`-type actions every element registers on ITSELF. Unlike a globalCallback, an element callback runs against a real element, so its node `elementId` is that element (the flow host by default, or another element to act on) and its nodeType is \"callback\". `setState` here changes the element's own attribute/state (params category/key/value/revertOnFinish) — NOT the global state setState (which is a globalCallback on source \"state\" with params key/type/value). Set revertOnFinish:true for a TEMPORARY change (e.g. a \"loading…\" label): it is undone automatically when the flow finishes, so you do NOT add manual restore steps. A specific element type may register more callbacks beyond these defaults.";
+var UTILITIES_NOTE = "Built-in `utility`-type actions (no element/source module). Use nodeType \"utility\". Use the EXACT param names — e.g. delayTime waits `time` milliseconds (not `delay`).";
+var toParamInfo = (params) => Object.entries(params).map(([name, spec]) => ({
+	name,
+	type: spec.type,
+	description: spec.description,
+	...spec.default !== void 0 ? { default: spec.default } : {},
+	...spec.options ? { options: spec.options } : {},
+	...spec.when ? { conditional: true } : {}
+}));
+var builtinGlobalCallbacks = () => Object.entries(BUILTIN_GLOBAL_CALLBACKS).map(([action, { source, title, strictParams, params }]) => ({
+	action,
+	source,
+	title,
+	strictParams,
+	params: toParamInfo(params)
+}));
+var builtinElementCallbacks = () => Object.entries(BUILTIN_ELEMENT_CALLBACKS).map(([action, { title, strictParams, params }]) => ({
+	action,
+	title,
+	strictParams,
+	params: toParamInfo(params)
+}));
+var builtinUtilities = () => Object.entries(BUILTIN_UTILITIES).map(([action, { title, strictParams, params }]) => ({
+	action,
+	title,
+	strictParams,
+	params: toParamInfo(params)
+}));
+var DATA_SOURCE_NOTE = "Data-source paths and binding targets observed on this space. Bind a source to an element field with upsertBinding (category attributes|style|initialState). Paths not listed may still be valid. A binding may post-process its value through `transformers` (see below) and be gated by a `when` QueryBuilder guard.";
+var DATA_SOURCE_SCOPE_NOTE = "SCOPE: an element source named `<type>_<idRef>` (e.g. `apiContainer_products`, `list_food-list`) is provided by that element to its DESCENDANTS ONLY — the provider wraps its subtree in the source’s scope, so only elements INSIDE the provider can bind to it. Binding a sibling or unrelated element to it is schema-valid but broken at runtime (the source is not in scope), and validate/apply REJECT it as an error. To consume `apiContainer_x.data`, the bound element must live under that apiContainer. Module sources (no `<type>_<idRef>` head — e.g. state/space/navigation/auth/collection) are global and bindable anywhere.";
+var TRANSFORMERS_NOTE = "Built-in transformers that post-process a binding value before it reaches the field: `source → t₁ → t₂ → field`. Set them on a binding as `transformers: [{ action, params }]` (params are strings). The runtime resolves each by its `action` alone, so an UNKNOWN action is silently skipped (the value passes through unchanged) — use the exact action names below. Common formatting is `twigTemplate` (the value is the {{source}} token, not {{value}}).";
+var buildInteractionCatalog = (schema) => {
+	const actions = {};
+	const flows = /* @__PURE__ */ new Set();
+	for (const el of Object.values(schema.flat)) for (const node of Object.values(el.definition.interactions ?? {})) {
+		(actions[node.type] ??= /* @__PURE__ */ new Set()).add(node.action);
+		flows.add(node.flowId || node.id);
+	}
+	const grouped = {};
+	for (const [nodeType, set] of Object.entries(actions)) grouped[nodeType] = [...set].sort();
+	return {
+		note: INTERACTION_NOTE,
+		actions: grouped,
+		globalCallbacksNote: GLOBAL_CALLBACKS_NOTE,
+		globalCallbacks: builtinGlobalCallbacks(),
+		elementCallbacksNote: ELEMENT_CALLBACKS_NOTE,
+		elementCallbacks: builtinElementCallbacks(),
+		utilitiesNote: UTILITIES_NOTE,
+		utilities: builtinUtilities(),
+		flowCount: flows.size
+	};
+};
+var buildDataSourceCatalog = (schema) => {
+	const sources = /* @__PURE__ */ new Set();
+	const targets = {};
+	for (const el of Object.values(schema.flat)) for (const [category, list] of Object.entries(el.definition.bindings ?? {})) for (const binding of list) {
+		sources.add(binding.source);
+		(targets[category] ??= /* @__PURE__ */ new Set()).add(binding.to);
+	}
+	const groupedTargets = {};
+	for (const [category, set] of Object.entries(targets)) groupedTargets[category] = [...set].sort();
+	return {
+		note: DATA_SOURCE_NOTE,
+		scopeNote: DATA_SOURCE_SCOPE_NOTE,
+		sources: [...sources].sort(),
+		targets: groupedTargets,
+		transformersNote: TRANSFORMERS_NOTE,
+		transformers: transformerCatalog()
+	};
+};
+var observedInteractionActions = (schema) => {
+	const actions = /* @__PURE__ */ new Set();
+	for (const el of Object.values(schema.flat)) for (const node of Object.values(el.definition.interactions ?? {})) actions.add(node.action);
+	return actions;
+};
+var observedDataSources = (schema) => {
+	const sources = /* @__PURE__ */ new Set();
+	for (const el of Object.values(schema.flat)) for (const list of Object.values(el.definition.bindings ?? {})) for (const binding of list) sources.add(binding.source);
+	return sources;
+};
+//#endregion
+export { buildDataSourceCatalog, buildInteractionCatalog, observedDataSources, observedInteractionActions };

package/dist/modules/mcp/catalogs/paramSpec.js

@@ -0,0 +1,69 @@
+import { hasValidToken } from "@plitzi/sdk-shared/helpers/twigWrapper";
+//#region src/modules/mcp/catalogs/paramSpec.ts
+/** Declared params the agent supplied that end up HIDDEN because their own `when` guard is false against the
+*  effective params — they are silently ignored (e.g. a global setState `value` with no `type`, or an
+*  addNotification `autoDismissTimeout` with autoDismiss:false). Evaluated against the effective params so a param
+*  the default fills in (e.g. category:"attribute") does not false-report a value as hidden. */
+var hiddenParams = (provided, effective, spec) => {
+	const hidden = [];
+	for (const [key, param] of Object.entries(spec)) if (param.when && provided[key] !== void 0 && !param.when(effective)) hidden.push(key);
+	return hidden;
+};
+/** Declared params marked `required` that the agent did NOT supply, and whose `when` guard holds against the
+*  effective params (so they are actually in play). Evaluated against the effective params so a required param
+*  gated by a companion (e.g. setState `value`, shown only once `category` is set) is not reported when its guard
+*  is not met. */
+var missingRequiredParams = (provided, effective, spec) => {
+	const missing = [];
+	for (const [key, param] of Object.entries(spec)) if (param.required && provided[key] === void 0 && (!param.when || param.when(effective))) missing.push(key);
+	return missing;
+};
+var isNumeric = (value) => value.trim() !== "" && Number.isFinite(Number(value));
+var isBindingToken = (value) => typeof value === "string" && hasValidToken(value);
+var matchesType = (value, param) => {
+	switch (param.type) {
+		case "boolean": return typeof value === "boolean";
+		case "number": return typeof value === "number" || typeof value === "string" && isNumeric(value);
+		case "select": return typeof value === "string" && (!param.options || param.options.includes(value));
+		case "scalar": return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+		case "text":
+		case "textarea": return typeof value === "string";
+		default: return true;
+	}
+};
+/** Declared params the agent supplied whose value is the WRONG type for the catalog — the check that catches a
+*  malformed node the unknown/missing/hidden checks miss (a boolean stored as a string, a select value not in its
+*  options, a leftover `null`). Only params actually in play are checked: undefined values (the param is absent) and
+*  params hidden by their own `when` guard against the effective params are skipped, so this never fires on a param
+*  that is not really used. Callers gate this to CLOSED (strict) catalogs, whose types we own authoritatively. */
+var invalidParams = (provided, effective, spec) => {
+	const invalid = [];
+	for (const [key, param] of Object.entries(spec)) {
+		const value = provided[key];
+		if (value === void 0 || isBindingToken(value) || param.when && !param.when(effective)) continue;
+		if (!matchesType(value, param)) invalid.push({
+			key,
+			expected: param.type,
+			got: value === null ? "null" : typeof value,
+			...param.options ? { options: param.options } : {}
+		});
+	}
+	return invalid;
+};
+/** Reconcile supplied params to a catalog schema: drop unknown keys when the set is CLOSED (strict), then fill the
+*  builder's defaults for any declared param the agent omitted whose `when` guard holds. Mirrors what the builder
+*  stores, so the persisted node round-trips cleanly. */
+var reconcileParams = (params, spec, strict) => {
+	const next = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (strict && !(key in spec)) continue;
+		next[key] = value;
+	}
+	for (const [key, param] of Object.entries(spec)) {
+		if (param.default === void 0 || next[key] !== void 0 || param.when && !param.when(next)) continue;
+		next[key] = param.default;
+	}
+	return next;
+};
+//#endregion
+export { hiddenParams, invalidParams, missingRequiredParams, reconcileParams };

package/dist/modules/mcp/catalogs/registry.js

@@ -0,0 +1,89 @@
+import { BUILTIN_COMPONENTS } from "./builtinComponents.js";
+import { cssProperties } from "./cssCatalog.js";
+//#region src/modules/mcp/catalogs/registry.ts
+var enrichType = (typeName, info, catalog) => {
+	const entry = catalog?.[typeName];
+	if (entry) {
+		info.label = entry.label ?? info.label;
+		if (entry.description !== void 0) info.description = entry.description;
+		if (entry.category !== void 0) info.category = entry.category;
+		info.source = entry.custom ? "plugin" : "builtin";
+		if (entry.defaultStyle && Object.keys(entry.defaultStyle).length > 0) info.defaultStyle = entry.defaultStyle;
+		for (const attr of entry.attributes ?? []) info.props[attr] ??= {
+			valueTypes: [],
+			examples: []
+		};
+		for (const slot of entry.styleSelectors ?? []) if (!info.slots.includes(slot)) info.slots.push(slot);
+		return;
+	}
+	const builtin = BUILTIN_COMPONENTS[typeName];
+	if (builtin) {
+		info.label = builtin.label;
+		info.description = builtin.description;
+		info.category = builtin.category;
+		info.source = "builtin";
+	}
+};
+var EXAMPLE_MAX_LENGTH = 80;
+var isCompactExample = (value) => {
+	if (typeof value === "string") return value.length <= EXAMPLE_MAX_LENGTH;
+	return typeof value === "number" || typeof value === "boolean";
+};
+var NOTE = "Element types and their props/slots are observed from the elements that already exist in this space — they are ground truth, never inferred. Each type also carries a `label`, `description` (what it is FOR) and `category`, plus a `source`: \"builtin\" (a Plitzi element), \"plugin\" (a custom element added via a plugin), or \"unknown\" (observed but undescribed — label only). Use the description to pick the right type (e.g. apiContainer fetches backend data, link navigates between pages). Props list the attribute keys seen on each type with example values. Slots are the styleSelectors keys seen on each type (target them via element.style.slots). `defaultStyle` (when present) is the intrinsic base CSS of the type BEFORE any class is attached — the real starting point, so account for it and never assume `display: block` (e.g. `text` is `display: inline`; wrap or override it explicitly if you need block/flex layout). CSS in definitions must use the kebab-case keys in cssProperties. Reference schema variables in props via {{name}} and style variables in CSS via var(--name).";
+var buildTypeRegistry = (schema, catalog) => {
+	const types = {};
+	for (const el of Object.values(schema.flat)) {
+		const typeName = el.definition.type;
+		const info = types[typeName] ??= {
+			count: 0,
+			source: "unknown",
+			subTypes: [],
+			slots: [],
+			props: {}
+		};
+		info.count += 1;
+		if (!info.label && typeof el.definition.label === "string" && el.definition.label !== "") info.label = el.definition.label;
+		const subType = el.attributes.subType;
+		if (typeof subType === "string" && !info.subTypes.includes(subType)) info.subTypes.push(subType);
+		for (const slot of Object.keys(el.definition.styleSelectors)) if (!info.slots.includes(slot)) info.slots.push(slot);
+		for (const [key, value] of Object.entries(el.attributes)) {
+			if (key === "subType") continue;
+			const prop = info.props[key] ??= {
+				valueTypes: [],
+				examples: []
+			};
+			const valueType = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+			if (!prop.valueTypes.includes(valueType)) prop.valueTypes.push(valueType);
+			if (prop.examples.length < 3 && isCompactExample(value) && value !== "" && !prop.examples.includes(value)) prop.examples.push(value);
+		}
+	}
+	for (const typeName of Object.keys(catalog ?? {})) types[typeName] ??= {
+		count: 0,
+		source: "unknown",
+		subTypes: [],
+		slots: [],
+		props: {}
+	};
+	for (const [typeName, info] of Object.entries(types)) {
+		enrichType(typeName, info, catalog);
+		info.subTypes.sort();
+		info.slots.sort();
+	}
+	return {
+		note: NOTE,
+		cssProperties,
+		styleVariableCategories: [
+			"color",
+			"spacing",
+			"shadow",
+			"custom"
+		],
+		templateSyntax: {
+			schemaVariable: "{{name}}",
+			styleVariable: "var(--name)"
+		},
+		types
+	};
+};
+//#endregion
+export { buildTypeRegistry };

package/dist/modules/mcp/handler.js

@@ -16,32 +16,60 @@ var readMcpBody = (req) => new Promise((resolve, reject) => {
 	req.on("error", reject);
 });
 var serveMcp = async (raw, res, server) => {
+	res.setHeader("Access-Control-Allow-Origin", "*");
+	res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+	res.setHeader("Access-Control-Allow-Headers", "*");
+	res.setHeader("Access-Control-Max-Age", "86400");
+	if (raw.method === "OPTIONS") {
+		res.writeHead(204);
+		res.end();
+		return;
+	}
+	if (raw.url?.startsWith("/.well-known/")) {
+		res.writeHead(404);
+		res.end();
+		return;
+	}
+	if (raw.method !== "POST") {
+		res.writeHead(405, {
+			"Content-Type": "application/json",
+			Allow: "POST, OPTIONS"
+		});
+		res.end(JSON.stringify({
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message: "Method not allowed; this MCP endpoint accepts JSON-RPC over POST only."
+			},
+			id: null
+		}));
+		return;
+	}
 	const transport = new StreamableHTTPServerTransport({
 		sessionIdGenerator: void 0,
 		enableJsonResponse: true
 	});
 	await server.connect(transport);
 	try {
-		if (raw.method === "POST") {
-			let body = raw.body;
-			if (body === void 0) try {
-				body = await readMcpBody(raw);
-			} catch {
-				res.writeHead(400, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: "Invalid JSON body" }));
-				return;
-			}
-			await transport.handleRequest(raw, res, body);
-		} else await transport.handleRequest(raw, res);
+		let body = raw.body;
+		if (body === void 0) try {
+			body = await readMcpBody(raw);
+		} catch {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "Invalid JSON body" }));
+			return;
+		}
+		await transport.handleRequest(raw, res, body);
 	} finally {
 		await transport.close();
 	}
 };
-var handleMcp = (raw, res, req, adapters, preview, screenshot) => serveMcp(raw, res, createMcpServer({
+var handleMcp = (raw, res, req, adapters, preview, screenshot, logger) => serveMcp(raw, res, createMcpServer({
 	adapters,
 	getSpaceId: () => adapters.getSpaceId?.(req) ?? Promise.resolve(void 0),
 	preview,
-	screenshot
+	screenshot,
+	logger
 }));
 //#endregion
 export { createMcpServer, handleMcp, readMcpBody, serveMcp };

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

@@ -0,0 +1,104 @@
+import { BUILTIN_GLOBAL_CALLBACKS } from "../catalogs/builtinCallbacks.js";
+import { BUILTIN_ELEMENT_CALLBACKS } from "../catalogs/builtinElementCallbacks.js";
+import { BUILTIN_UTILITIES } from "../catalogs/builtinUtilities.js";
+//#region src/modules/mcp/helpers/agentPrompt.ts
+var EDITING_MODEL = [
+	"━━ PLITZI MCP — EDITING MODEL ━━",
+	"A Plitzi space is TWO schemas you edit together in one atomic plitzi_apply batch:",
+	"• Element schema — the tree of pages/elements (type, label, props, and which style classes each uses).",
+	"• Style schema — reusable definitions (CSS classes), design tokens (variables), theme.",
+	"To style an element: write a definition AND attach it via the element’s style.base in the same batch.",
+	"style.base is a LIST — an element can attach several classes (plus non-base slots); ALL of them apply together",
+	"(they cascade), so when a style looks wrong inspect EVERY attached class + its global/id styles, not just one.",
+	"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 (a provider source is `<type>_<idRef>.<field>` — a dot is not allowed in the",
+	"idRef, an underscore is). CSS is kebab-case; style vars are var(--name), schema",
+	"vars are {{name}}. Use patchElement/patchDefinition to change SOME props/CSS; the upsert variants replace them all.",
+	"Reads are cheap by design — list to navigate, read one item for detail; never fetch a whole tree you do not need."
+].join("\n");
+var TOOLS = [
+	"━━ MCP TOOLS ━━",
+	"• plitzi_search — find refs by label/type/attribute (include:\"detail\" also returns each hit’s 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_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 an element/page already in the schema (HTML / image).",
+	"Discover → browse resources. Find a ref → plitzi_search. Fetch known URIs → plitzi_read. Do not confuse them."
+].join("\n");
+var RESOURCES = [
+	"━━ MCP RESOURCES (read) ━━",
+	"Read plitzi://primer/{env} FIRST — a cold-start bundle: guide + types + css-properties + page/definition/variable",
+	"summaries in one call. Then, on demand:",
+	"• plitzi://guide — full usage reference.",
+	"• plitzi://types — element types observed in this space (props, slots, subTypes, label/description/category).",
+	"• plitzi://css-properties — valid kebab-case CSS property keys.",
+	"• plitzi://schema/{env}/pages , /{ref} — page summaries, then one page as a skeleton tree.",
+	"• plitzi://folders/{env} — page folders (the sidebar tree).",
+	"• plitzi://definitions/{env} , plitzi://style-variables/{env} — style classes and design tokens.",
+	"• plitzi://interactions/{env} — interaction actions + built-in globalCallbacks with their source + param schema.",
+	"• plitzi://data-sources/{env} — data-source paths and binding targets (vocabulary for upsertBinding).",
+	"• plitzi://settings/{env} — space-level settings."
+].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.",
+	"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",
+	"page as {{name}} in props AND as the binding source navigation.routeParams.name — so a dynamic detail page is a",
+	"\"posts/:postId\" page whose apiContainer query binds navigation.routeParams.postId."
+].join("\n");
+var paramList = (params) => {
+	const names = Object.keys(params);
+	return names.length > 0 ? names.join(", ") : "(no params)";
+};
+var globalCallbackLines = () => Object.entries(BUILTIN_GLOBAL_CALLBACKS).map(([action, { source, params }]) => `  • ${action} → source "${source}"; params: ${paramList(params)}`);
+var elementCallbackLines = () => Object.entries(BUILTIN_ELEMENT_CALLBACKS).map(([action, { params }]) => `  • ${action}; params: ${paramList(params)}`);
+var utilityLines = () => Object.entries(BUILTIN_UTILITIES).map(([action, { params }]) => `  • ${action}; params: ${paramList(params)}`);
+var INTERACTIONS = () => [
+	"━━ INTERACTIONS ━━",
+	"A flow is a trigger (onClick, onPageLoad…) followed by ordered callbacks/utilities; each step has an enabled",
+	"flag. Write one with upsertInteractionFlow (first node MUST be a trigger); change one step with",
+	"patchInteractionNode; remove a step (nodeId) or a whole flow (flowId) with deleteInteraction.",
+	"Disable ≠ delete: to turn a step off without removing it use patchInteractionNode { enabled: false }.",
+	"deleteInteraction is destructive — confirm with the user first.",
+	"Pick the RIGHT node type for an action: the wrong type resolves against nothing and the step silently no-ops.",
+	"Any param VALUE can be a data-binding token {{ source }} — e.g. addNotification content",
+	"\"{{ list_<idRef>.item.name }}\" shows the clicked row’s field; it resolves at runtime just like a prop binding.",
+	"",
+	"globalCallback (nodeType \"globalCallback\") — provided by a SOURCE MODULE, not the host element: OMIT elementId",
+	"and the MCP pins the right source and fills the builder’s param defaults. Use ONLY each callback’s declared",
+	"params (exact spelling) — for addNotification the text goes in `content` (NO title/message/type). Built-ins:",
+	...globalCallbackLines(),
+	"",
+	"callback (nodeType \"callback\") — a callback ON an element; elementId is that element (host by default). Every",
+	"element has a built-in `setState` that changes ITS OWN attribute/state (category/key/value/revertOnFinish). Set",
+	"revertOnFinish:true for a TEMPORARY change (e.g. a \"loading…\" label) so it auto-reverts at flow end — do NOT add",
+	"manual restore steps. This element setState has NO `type` param (that is the global state setState). Built-ins:",
+	...elementCallbackLines(),
+	"",
+	"utility (nodeType \"utility\") — no element/source. Use the EXACT param names (delayTime waits `time` ms, not",
+	"`delay`). Built-ins:",
+	...utilityLines(),
+	"The full param schema (types, options, defaults) for each is in plitzi://interactions/{env}."
+].join("\n");
+/** The MCP-owned guidance block a consumer concatenates into its system prompt. Covers what the MCP is
+*  authoritative about: its editing model, tools, resources and interaction vocabulary. It intentionally does NOT
+*  cover a consumer’s own tools (previews, design helpers) or product framing (modes, identity, security). */
+var buildAgentGuide = () => [
+	EDITING_MODEL,
+	"",
+	TOOLS,
+	"",
+	RESOURCES,
+	"",
+	NAVIGATION,
+	"",
+	INTERACTIONS()
+].join("\n");
+//#endregion
+export { buildAgentGuide };