@plitzi/sdk-server 0.30.19 → 0.31.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @plitzi/sdk-server
 
+## 0.31.1
+
+### Patch Changes
+
+- v0.31.1
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.31.1
+  - @plitzi/sdk-shared@0.31.1
+
+## 0.31.0
+
+### Minor Changes
+
+- v0.31.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.31.0
+  - @plitzi/sdk-shared@0.31.0
+
 ## 0.30.19
 
 ### Patch Changes

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/helpers/cache/TtlCache.js

@@ -1,6 +1,8 @@
 import { DEFAULT_TTL_MS } from "./defaults.js";
 //#region src/helpers/cache/TtlCache.ts
 var TtlCache = class {
+	ttlMs;
+	maxSize;
 	store = /* @__PURE__ */ new Map();
 	sweepTimer;
 	constructor(ttlMs = DEFAULT_TTL_MS.html, maxSize = 500, sweepIntervalMs = ttlMs) {

package/dist/index.js

@@ -1,3 +1,8 @@
+import { bindTools, getAllowedModes, isToolActive, resolveToolHandler, toolResponseErr, toolResponseOk, zodToJsonSchema } from "./modules/mcp/helpers.js";
+import { tools_exports } from "./modules/mcp/tools/index.js";
+import { createMcpServer } from "./modules/mcp/server.js";
+import AIEngine from "./modules/ai/AIEngine.js";
+import { handleMcp, readMcpBody } from "./modules/mcp/handler.js";
 import { createSSRServer } from "./core/createServer.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
-export { createJsonAdapters, createSSRServer };
+export { AIEngine, bindTools, createJsonAdapters, createMcpServer, createSSRServer, getAllowedModes, handleMcp, isToolActive, readMcpBody, resolveToolHandler, toolResponseErr, toolResponseOk, tools_exports as tools, zodToJsonSchema };

package/dist/modules/ai/AIEngine.js

@@ -0,0 +1,120 @@
+import { toolResponseErr } from "../mcp/helpers.js";
+//#region src/modules/ai/AIEngine.ts
+var AIEngine = class {
+	mode;
+	callbacks;
+	toolsAvailables = /* @__PURE__ */ new Map();
+	toolsAvailablesMap = /* @__PURE__ */ new Map();
+	ctx;
+	constructor(mode, callbacks, ctx) {
+		this.mode = mode;
+		this.callbacks = callbacks;
+		this.ctx = {
+			...ctx,
+			mode: mode || "plan"
+		};
+	}
+	readResource = (name, uri) => {
+		this.callbacks.onResourceRead?.(name, uri);
+	};
+	setToolsAvailables = (tools) => {
+		this.toolsAvailables = new Map(tools.map((t) => [t.name, t]));
+		this.toolsAvailablesMap = new Map(tools.map((t) => [t.name, t.definition.allowedModes]));
+	};
+	can = (name) => {
+		if (!this.mode || !this.toolsAvailablesMap.has(name)) return false;
+		const allowedModes = this.toolsAvailablesMap.get(name);
+		return !allowedModes || allowedModes.includes(this.mode);
+	};
+	before = async (name, args) => {
+		this.callbacks.onBeforeTool?.(name, args);
+		if (!this.toolsAvailables.has(name)) {
+			this.callbacks.onLog?.("error", `tool rejected: '${name}' has no definition — possible security violation`);
+			await this.after(name, args, toolResponseErr(`Tool '${name}' is not defined and cannot be executed`));
+			return false;
+		}
+		if (!this.can(name)) {
+			this.callbacks.onLog?.("info", `tool blocked: '${name}' is not permitted in ${this.mode} mode`);
+			await this.after(name, args, toolResponseErr(`Tool '${name}' is not permitted in ${this.mode} mode`));
+			return false;
+		}
+		return true;
+	};
+	after = (name, args, result) => {
+		let resultParsed;
+		if (result.data !== void 0) resultParsed = result.data;
+		else try {
+			resultParsed = JSON.parse(result.content[0]?.text ?? "");
+		} catch {}
+		if (result.isError) this.callbacks.onToolError?.({
+			name,
+			args,
+			result: resultParsed ?? { error: result.content[0]?.text ?? "Tool failed" }
+		});
+		else this.callbacks.onToolSuccess?.({
+			name,
+			args,
+			result: resultParsed
+		});
+		return Promise.resolve();
+	};
+	validateToolInput = (name, args) => {
+		const tool = this.toolsAvailables.get(name);
+		if (!tool || !tool.mcpDefinition.inputSchema) return {
+			success: true,
+			data: args
+		};
+		const parsed = tool.mcpDefinition.inputSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: parsed.error.message
+		};
+		return {
+			success: true,
+			data: parsed.data
+		};
+	};
+	validateToolOutput = (name, result) => {
+		const tool = this.toolsAvailables.get(name);
+		if (!tool || !tool.mcpDefinition.outputSchema || result.isError) return;
+		if (result.data === void 0) return;
+		const parsed = tool.mcpDefinition.outputSchema.safeParse(result.data);
+		if (!parsed.success) return parsed.error.message;
+	};
+	runPipeline = async (name, args, handler) => {
+		const parsedArgs = this.validateToolInput(name, args);
+		if (!parsedArgs.success) {
+			this.callbacks.onLog?.("error", `tool validation error: ${name} error=${parsedArgs.error}`);
+			const err = toolResponseErr(parsedArgs.error);
+			await this.after(name, args, err);
+			return err;
+		}
+		const t0 = Date.now();
+		const result = await handler(parsedArgs.data, this.ctx);
+		this.callbacks.onLog?.("debug", `tool done: ${name} ms=${Date.now() - t0} result=${JSON.stringify(result).slice(0, 200)}`);
+		const outputError = this.validateToolOutput(name, result);
+		if (outputError) this.callbacks.onLog?.("info", `tool output schema drift: ${name} — ${outputError}`);
+		const tool = this.toolsAvailables.get(name);
+		if (!result.isError && tool?.mcpDefinition.outputSchema && result.data !== void 0 && result.data !== null) result.structuredContent = typeof result.data === "object" && !Array.isArray(result.data) ? result.data : { data: result.data };
+		if (result.isError) this.callbacks.onLog?.("error", `tool failed: ${name} error=${result.content[0]?.text ?? "unknown"}`);
+		await this.after(name, args, result);
+		return result;
+	};
+	execute = (name, handlerFn) => async (args) => {
+		if (!await this.before(name, args)) return toolResponseErr(`Tool '${name}' execution was blocked`);
+		const handler = handlerFn ?? this.toolsAvailables.get(name)?.handler;
+		if (!handler) {
+			this.callbacks.onLog?.("error", `no handler registered for tool: ${name}`);
+			const err = toolResponseErr(`Tool '${name}' has no handler`);
+			await this.after(name, args, err);
+			return err;
+		}
+		this.callbacks.onLog?.("debug", `tool exec: ${name} args=${JSON.stringify(args).slice(0, 200)}`);
+		return this.runPipeline(name, args, handler);
+	};
+	executePrompt = (_name, handlerFn) => async (args) => {
+		return handlerFn(args, this.ctx);
+	};
+};
+//#endregion
+export { AIEngine as default };

package/dist/modules/mcp/handler.js

@@ -1,7 +1,8 @@
 import { createMcpServer } from "./server.js";
+import AIEngine from "../ai/AIEngine.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 //#region src/modules/mcp/handler.ts
-var readBody = (req) => new Promise((resolve, reject) => {
+var readMcpBody = (req) => new Promise((resolve, reject) => {
 	let raw = "";
 	req.on("data", (chunk) => {
 		raw += chunk.toString();
@@ -15,20 +16,38 @@ var readBody = (req) => new Promise((resolve, reject) => {
 	});
 	req.on("error", reject);
 });
-var handleMcp = async (req, res, config) => {
-	const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
-	await createMcpServer(config.adapters).connect(transport);
-	if (req.method === "POST") {
-		let body;
-		try {
-			body = await readBody(req);
-		} catch {
-			res.writeHead(400, { "Content-Type": "application/json" });
-			res.end(JSON.stringify({ error: "Invalid JSON body" }));
-			return;
-		}
-		await transport.handleRequest(req, res, body);
-	} else await transport.handleRequest(req, res);
+var handleMcp = async (req, res, config, server, transport, context) => {
+	if (!server) {
+		const ctx = context ?? {
+			userId: 0,
+			spaceId: 0,
+			environment: "main",
+			mode: "plan"
+		};
+		const engine = new AIEngine(ctx.mode, {}, ctx);
+		server = createMcpServer(config.adapters, engine, config.tools, config.prompts);
+	}
+	if (!transport) transport = new StreamableHTTPServerTransport({
+		sessionIdGenerator: void 0,
+		enableJsonResponse: true
+	});
+	await server.connect(transport);
+	try {
+		if (req.method === "POST") {
+			let body;
+			if (req.body !== void 0) body = req.body;
+			else try {
+				body = await readMcpBody(req);
+			} catch {
+				res.writeHead(400, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "Invalid JSON body" }));
+				return;
+			}
+			await transport.handleRequest(req, res, body);
+		} else await transport.handleRequest(req, res);
+	} finally {
+		await transport.close();
+	}
 };
 //#endregion
-export { handleMcp };
+export { handleMcp, readMcpBody };

package/dist/modules/mcp/helpers.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+//#region src/modules/mcp/helpers.ts
+var zodToJsonSchema = (schema) => {
+	if (schema instanceof z.ZodObject) {
+		const properties = {};
+		const required = [];
+		for (const [key, value] of Object.entries(schema.shape)) {
+			properties[key] = zodToJsonSchema(value);
+			if (value instanceof z.ZodString || value instanceof z.ZodNumber || value instanceof z.ZodBoolean) {
+				if (!value.isOptional()) required.push(key);
+			}
+		}
+		return {
+			type: "object",
+			properties,
+			required: required.length > 0 ? required : []
+		};
+	}
+	if (schema instanceof z.ZodString) return { type: "string" };
+	if (schema instanceof z.ZodNumber) return { type: "number" };
+	if (schema instanceof z.ZodBoolean) return { type: "boolean" };
+	if (schema instanceof z.ZodEnum) return {
+		type: "string",
+		enum: schema.options
+	};
+	if (schema instanceof z.ZodOptional) return zodToJsonSchema(schema._def.innerType);
+	if (schema instanceof z.ZodUnion) return { oneOf: schema.options.map((opt) => zodToJsonSchema(opt)) };
+	if (schema instanceof z.ZodArray) return {
+		type: "array",
+		items: zodToJsonSchema(schema.element)
+	};
+	if (schema instanceof z.ZodRecord) return {
+		type: "object",
+		additionalProperties: zodToJsonSchema(schema.valueType)
+	};
+	return {};
+};
+var getAllowedModes = (operationType) => {
+	return operationType === "write" ? ["build"] : ["plan", "build"];
+};
+var toolResponseOk = (data, agentMessage) => {
+	return {
+		content: [{
+			type: "text",
+			text: agentMessage ?? JSON.stringify(data ?? null, null, 2)
+		}],
+		data
+	};
+};
+var toolResponseErr = (error) => ({
+	content: [{
+		type: "text",
+		text: error instanceof Error ? error.message : error
+	}],
+	isError: true
+});
+var isToolActive = (tool, adapters) => Boolean(tool.handler || tool.adapterName && adapters[tool.adapterName]);
+var resolveToolHandler = (tool, adapters) => {
+	if (tool.handler) return tool.handler;
+	if (tool.adapterName) return adapterWrapper(tool.adapterName, adapters[tool.adapterName]);
+};
+var bindTools = (tools, adapters) => tools.filter((tool) => isToolActive(tool, adapters)).map((tool) => ({
+	...tool,
+	handler: resolveToolHandler(tool, adapters)
+}));
+var adapterWrapper = (adapterName, handler) => {
+	return async (args, ctx) => {
+		if (!handler) return toolResponseErr(`Adapter ${adapterName} not found`);
+		const result = await handler(args, ctx);
+		if ("error" in result) return toolResponseErr(result.error);
+		return toolResponseOk(result.data);
+	};
+};
+//#endregion
+export { bindTools, getAllowedModes, isToolActive, resolveToolHandler, toolResponseErr, toolResponseOk, zodToJsonSchema };

package/dist/modules/mcp/resources/glossary/binding.js

@@ -0,0 +1,73 @@
+//#region src/modules/mcp/resources/glossary/binding.ts
+var bindingResource = {
+	uri: "plitzi://docs/binding",
+	name: "Plitzi Docs: Binding",
+	description: "Data bindings in Plitzi — connections that dynamically drive element attributes, style, or state from data sources.",
+	mimeType: "text/markdown",
+	content: `# Binding
+
+A **Binding** connects a data source to an element property. At runtime, the bound value replaces the element's static attribute, style, or initial state. Bindings enable dynamic content — data from collections, variables, navigation params, or other elements can drive what is displayed or how it looks.
+
+## TypeScript Shape
+
+\`\`\`typescript
+type BindingCategory = 'attributes' | 'style' | 'initialState';
+
+type ElementBinding = {
+  id: string;
+  source: string;                   // Data source ID / reference
+  fromPath?: string;                // Path within the source data (e.g. 'user.name')
+  transformers?: BindingTransformer[];  // Optional value transforms
+  when?: RuleGroup;                 // Conditional activation rule
+  enabled?: boolean;
+  toPath: string;                   // Target attribute/style/state path to overwrite
+};
+
+type BindingTransformer = {
+  type: 'utility' | 'unknown';
+  action: string;                   // Transform function name
+  params: { valueType: string; value: string };
+};
+\`\`\`
+
+## Binding Categories
+
+Bindings are grouped by what they target inside an element:
+
+| Category | What it overwrites |
+|---|---|
+| \`attributes\` | Fields in \`element.attributes\` (e.g. \`text\`, \`src\`, \`href\`) |
+| \`style\` | Style-related data (e.g. active style variant) |
+| \`initialState\` | Initial runtime state values |
+
+## Key Properties
+
+- **\`source\`** — identifies the data source (a collection ID, a schema variable name, a navigation param key, etc.).
+- **\`fromPath\`** — dot-notation path into the source data to extract the bound value (e.g. \`'record.title'\`).
+- **\`toPath\`** — dot-notation path of the target property to set on the element (e.g. \`'text'\`, \`'src'\`).
+- **\`transformers\`** — optional chain of value transforms applied before writing to \`toPath\`.
+- **\`when\`** — a \`RuleGroup\` condition; the binding only applies when the condition evaluates to true.
+
+## Where Bindings Are Stored
+
+Bindings live inside \`element.definition.bindings\`:
+
+\`\`\`typescript
+element.definition.bindings = {
+  attributes: [
+    { id: '...', source: 'collection-posts', fromPath: 'title', toPath: 'text', ... }
+  ],
+  style: [...],
+  initialState: [...]
+}
+\`\`\`
+
+## Relationships
+
+- Bindings reference **Schema Variables** (source by variable name) or external data sources.
+- Bindings are part of **Element** definitions.
+- **Interactions** complement bindings by handling user-triggered events (click, change).
+`
+};
+//#endregion
+export { bindingResource };

package/dist/modules/mcp/resources/glossary/collection.js

@@ -0,0 +1,76 @@
+//#region src/modules/mcp/resources/glossary/collection.ts
+var collectionResource = {
+	uri: "plitzi://docs/collection",
+	name: "Plitzi Docs: Collection",
+	description: "A CMS-style data store in Plitzi — a typed set of records with configurable fields.",
+	mimeType: "text/markdown",
+	content: `# Collection
+
+A **Collection** is a CMS-style data store inside a Plitzi space. It has a defined field schema and holds typed records. Collections are used to manage dynamic content (blog posts, product listings, team members, etc.) that elements can bind to via data sources.
+
+## TypeScript Shape
+
+\`\`\`typescript
+type Collection = {
+  id: string;
+  name: string;              // Singular name (e.g. 'Post')
+  namePlural: string;        // Plural name (e.g. 'Posts')
+  description: string;
+  privacy: 'public' | 'private';
+  fields: Record<string, CollectionField>;   // Field schema keyed by field ID
+  records: CollectionRecord[];
+};
+
+type CollectionField = {
+  id: string;
+  name: string;              // Human-readable label
+  machineName: string;       // Programmatic key used in record values
+  type:
+    | 'text' | 'richText' | 'image' | 'multiImage'
+    | 'video' | 'link' | 'email' | 'phone'
+    | 'number' | 'date' | 'switch' | 'color'
+    | 'option' | 'file';
+  params: {
+    primary: boolean;        // Whether this is the display/title field
+    required: boolean;
+  };
+};
+
+type CollectionRecord = {
+  id: string;
+  values: Record<string, string | number | boolean>;  // Keyed by field machineName
+  status: 'draft' | 'published' | 'archived';
+  createdAt: number;
+  updatedAt: number;
+  publishedAt?: number;
+};
+\`\`\`
+
+## Key Properties
+
+- **\`fields\`** — the schema of the collection. Each field has a \`machineName\` which is the key used in \`record.values\`.
+- **\`CollectionField.type\`** — determines the data type and editor widget. Use \`richText\` for HTML content, \`image\` for single image uploads.
+- **\`CollectionField.params.primary\`** — marks the main display field (title/name). Used in lists and pickers.
+- **\`CollectionRecord.values\`** — the actual record data, keyed by \`field.machineName\`.
+- **\`CollectionRecord.status\`** — content lifecycle. Only \`published\` records are visible in production.
+
+## Relationships
+
+- Elements can bind to collection data via **Bindings** (data source type \`collection\`).
+- Collections belong to a **Space** and are available across all environments.
+
+## Common Operations
+
+- \`get_collections\` — list all collections in the space.
+- \`get_collection\` — get a collection with its field schema.
+- \`create_collection\` — define a new content type.
+- \`update_collection\` — rename or modify a collection.
+- \`delete_collection\` — remove collection and all records.
+- \`get_collection_records\` — fetch records (optionally filtered by status).
+- \`create_collection_record\` — add a new record.
+- \`update_collection_record\` — edit an existing record.
+- \`delete_collection_record\` — remove a record.
+`
+};
+//#endregion
+export { collectionResource };

package/dist/modules/mcp/resources/glossary/displayMode.js

@@ -0,0 +1,50 @@
+//#region src/modules/mcp/resources/glossary/displayMode.ts
+var displayModeResource = {
+	uri: "plitzi://docs/display-mode",
+	name: "Plitzi Docs: Display Mode",
+	description: "Responsive breakpoints in Plitzi — desktop, tablet, and mobile style layers.",
+	mimeType: "text/markdown",
+	content: `# Display Mode
+
+A **Display Mode** represents a responsive breakpoint in the Plitzi style system. Styles are defined per display mode, allowing different visual rules at each screen size.
+
+## Type
+
+\`\`\`typescript
+type DisplayMode = 'desktop' | 'tablet' | 'mobile';
+\`\`\`
+
+## Structure in Style
+
+The \`Style.platform\` object holds one style layer per display mode:
+
+\`\`\`typescript
+style.platform = {
+  desktop: Record<string, StyleItem>,   // Base styles (widest breakpoint)
+  tablet: Record<string, StyleItem>,    // Overrides for tablet-width screens
+  mobile: Record<string, StyleItem>     // Overrides for mobile-width screens
+};
+\`\`\`
+
+Each mode contains the same set of CSS selectors (keyed by selector string). A selector defined only in \`desktop\` inherits its rules at all sizes unless overridden in \`tablet\` or \`mobile\`.
+
+## Cascade Direction
+
+- **Desktop-first** (default, \`style.mode === 'desktop-first'\`): \`desktop\` is the base. \`tablet\` overrides at medium widths. \`mobile\` overrides at narrow widths.
+- **Mobile-first** (\`style.mode === 'mobile-first'\`): \`mobile\` is the base. \`tablet\` and \`desktop\` add styles as the viewport widens.
+
+## In MCP Operations
+
+MCP style tools that modify selectors accept a \`displayMode\` parameter:
+
+\`\`\`typescript
+createStyleSelector({ displayMode: 'mobile', selector: '.hero', ... })
+updateStyleSelector({ displayMode: 'tablet', selector: '.hero', ... })
+deleteStyleSelector({ displayMode: 'desktop', selector: '.hero' })
+\`\`\`
+
+Omitting \`displayMode\` typically defaults to \`desktop\`.
+`
+};
+//#endregion
+export { displayModeResource };

package/dist/modules/mcp/resources/glossary/element.js

@@ -0,0 +1,68 @@
+//#region src/modules/mcp/resources/glossary/element.ts
+var elementResource = {
+	uri: "plitzi://docs/element",
+	name: "Plitzi Docs: Element",
+	description: "A single UI component instance in a Plitzi page — the building block of every schema.",
+	mimeType: "text/markdown",
+	content: `# Element
+
+An \`Element\` is a single instance of a UI component in a Plitzi page. Every visual item — pages, containers, text blocks, forms, images — is an element. The entire page tree is stored as a flat dictionary of elements keyed by ID.
+
+## TypeScript Shape
+
+\`\`\`typescript
+type Element<TAttributes = Record<string, unknown>> = {
+  id: string;
+  attributes: TAttributes & { subType?: string };  // Component-specific configuration
+  definition: ElementDefinition;
+};
+
+type ElementDefinition = {
+  rootId: string;            // ID of the page/root element this belongs to
+  label: string;             // Human-readable name shown in the builder
+  type: string;              // Element type identifier (e.g. 'container', 'text', 'image')
+  parentId?: string;         // ID of the parent element (undefined = root)
+  items?: string[];          // Ordered array of child element IDs
+  styleSelectors: {
+    base: string;            // Always present — the primary CSS class
+    [key: string]: string;   // Additional sub-selectors (e.g. 'header', 'body', 'icon')
+  };
+  bindings?: Partial<Record<'attributes' | 'style' | 'initialState', ElementBinding[]>>;
+  interactions?: Record<string, ElementInteraction>;
+  initialState?: {
+    styleVariant?: Record<string, Record<string, string | string[]>>;
+    styleSelectors?: ElementDefinition['styleSelectors'];
+    visibility?: boolean;
+    [key: string]: unknown;
+  };
+  runtime?: 'server' | 'client' | 'shared';    // RSC render target
+  loadStrategy?: 'eager' | 'lazy' | 'visible'; // When to load/render
+};
+\`\`\`
+
+## Key Properties
+
+- **\`id\`** — unique identifier, used as the key in \`schema.flat\`.
+- **\`attributes\`** — component-specific data (text content, URLs, settings). Shape varies by plugin type. \`subType\` selects a variant within the same plugin.
+- **\`definition.type\`** — element type identifier that determines which component renders this element. Get valid values from \`get_builder_context\` (\`elementDefaults\` keys) or from the \`type\` field of existing elements in \`get_schema\`. This is NOT the plugin name from \`list_plugins\`.
+- **\`definition.parentId\`** — parent element ID. Elements without \`parentId\` are root elements (pages).
+- **\`definition.items\`** — ordered child IDs. Walk the tree by following \`items\` recursively.
+- **\`definition.styleSelectors\`** — maps named selector slots to actual CSS class strings from the \`Style\`. \`base\` is always present.
+- **\`definition.bindings\`** — data bindings that dynamically overwrite \`attributes\`, \`style\`, or \`initialState\` fields at runtime.
+- **\`definition.interactions\`** — event handlers (onClick, onChange, etc.) mapping to configured actions.
+- **\`definition.rootId\`** — always points to the page element this element belongs to.
+
+## Relationships
+
+- All elements live in \`schema.flat[id]\`.
+- Parent–child links: \`definition.parentId\` (up) and \`definition.items\` (down).
+- Style data for each element is found in \`style.platform[displayMode][styleSelector]\`.
+- **Segment** elements have their own \`schema.flat\` but follow the same structure.
+
+## Page Elements
+
+A page is an element whose type corresponds to a page plugin. Its ID appears in \`schema.pages\`. Pages are the top-level roots; they have no \`parentId\` and their \`rootId\` points to themselves.
+`
+};
+//#endregion
+export { elementResource };

package/dist/modules/mcp/resources/glossary/environment.js

@@ -0,0 +1,48 @@
+//#region src/modules/mcp/resources/glossary/environment.ts
+var environmentResource = {
+	uri: "plitzi://docs/environment",
+	name: "Plitzi Docs: Environment",
+	description: "Deployment environments in Plitzi — main (working copy), development, staging, and production.",
+	mimeType: "text/markdown",
+	content: `# Environment
+
+An **Environment** in Plitzi is a named version of a space's schema, style, and segments. Each environment can be published independently to its own domain.
+
+## Type
+
+\`\`\`typescript
+type Environment = 'production' | 'staging' | 'development' | 'main';
+\`\`\`
+
+## Environments
+
+| Environment | Purpose |
+|---|---|
+| \`main\` | The live editing/working copy. Always present. All builder changes apply here. |
+| \`development\` | Internal preview environment. Used for QA before staging. |
+| \`staging\` | Pre-production review. Shown to stakeholders before going live. |
+| \`production\` | The public-facing live site. Published from \`main\` when changes are ready. |
+
+## Key Behaviors
+
+- **All builder operations target \`main\`** unless explicitly scoped to another environment.
+- Publishing copies the \`main\` schema/style to the target environment (e.g. \`production\`).
+- Each environment can have a different domain and CDN deployment.
+- Segments are also versioned per environment.
+
+## In API and Tools
+
+Most MCP tools accept an \`environment\` parameter (defaults to \`main\`) that scopes the read/write operation:
+
+\`\`\`typescript
+// Example: get schema for the staging environment
+getSchema({ environment: 'staging' })
+\`\`\`
+
+## AI Context
+
+The \`AiContext.environment\` field tells the AI agent which environment the current session is operating in. This affects which schema/style data is read and which changes are applied.
+`
+};
+//#endregion
+export { environmentResource };